ObjectStorage
上传文件、流式下载、读取元数据并分页列出对象。
ObjectStorage 用于保存文件和二进制数据，支持对象元数据、范围读取、流式下载和分页列表。
先创建并关联资源；关联与共享规则见模块概览。
import { ObjectStorage } from 'lexmount:storage';
const storage = await ObjectStorage.open('uploads');ObjectStorage.storages()
功能： 列出当前实例已关联的对象存储资源。
参数： 无。
返回值： Promise<{ id: string; name: string }[]>。
ObjectStorage.open(name)
功能： 按名称打开已有且已关联的资源。
参数： name: string 必填，名称规则见资源与关联。
返回值： Promise<Readonly<NamedObjectStorage>>，含只读 name: string 及下列方法。句柄绑定资源 ID，同名重建不会把旧句柄指向新资源。
storage.put(key, body, options?)
功能： 上传对象，覆盖同一 key 的已有内容。
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
key | string | 是 | 相对对象路径 |
body | BodyInit / null | 是 | Fetch 正文类型，包括字符串、二进制、Blob、FormData 或字节流；null 表示空正文 |
options.httpMetadata | HttpMetadata | 否 | HTTP 元数据，字段见下表 |
options.customMetadata | Record<string, string> | 否 | 符合 ASCII 请求头要求的自定义元数据，名称按小写保存 |
返回值： Promise<StorageObject>，为对象元数据；上传响应不含 uploaded。
上传会先把完整正文收集到内存，再发送一次 PUT，最多 64 MiB，传入流也不会变为流式上传。超出大小上限抛出 RangeError。
storage.get(key, options?)
功能： 读取对象元数据和可流式消费的正文。
参数： key: string 必填；options?: { range?: ObjectRange } 可选择字节范围：
| range | 说明 |
|---|---|
{ offset, length } | 从 offset 开始读取 length 字节 |
{ offset } | 从 offset 读到结束 |
{ length } | 从 0 开始读取 length 字节 |
{ suffix } | 读取末尾 suffix 字节，不能与 offset / length 同用 |
Offset 为非负安全整数，length 和 suffix 为正安全整数。
返回值： Promise<StorageObjectBody | null>；对象不存在时为 null。返回对象包含下面的元数据、body 及正文读取方法。范围响应的 size 为实际返回正文长度，contentRange 描述该范围。
storage.head(key)
功能： 仅读取元数据，不下载正文。
参数： key: string 必填。
返回值： Promise<StorageObject | null>；对象不存在时为 null。
storage.delete(keyOrKeys)
功能： 删除一个或多个对象，不删除资源本身。
参数： 必填 keyOrKeys: string | string[]，数组最多 1000 项。
返回值： Promise<void>。删除不存在的 key 成功；批量删除非原子，失败前可能已删除部分对象。
storage.list(options?)
功能： 按前缀或目录分隔符分页列出对象。
| 参数 | 类型 | 默认值与说明 |
|---|---|---|
options.prefix | string | 空字符串；仅列出此前缀的对象 |
options.cursor | string | 可选，使用上页 cursor，并保持相同 prefix 和 delimiter |
options.delimiter | string | 可选，按分隔符聚合前缀，例如 / |
options.limit | number | 1000；1～1000 的整数 |
返回值： Promise<ObjectPage>：
| 字段 | 类型 | 说明 |
|---|---|---|
objects | StorageObject[] | 对象元数据；列表不附带 HTTP 或自定义元数据，用 head 获取完整元数据 |
delimitedPrefixes | string[] | 按 delimiter 聚合的前缀 |
truncated | boolean | 是否还有后续页 |
cursor | string / null | 下一页游标，最后一页为 null |
StorageObject、StorageObjectBody 与 HttpMetadata
| 元数据字段 | 类型 | 说明 |
|---|---|---|
key | string | 对象 key |
size | number | 字节大小，范围读取时为返回正文大小 |
etag | string | 实体标签 |
httpEtag | string | 可用于 HTTP 头的实体标签 |
uploaded | Date，可选 | 服务提供的修改时间；PUT 返回值不提供 |
httpMetadata | HttpMetadata | 下表中的 HTTP 元数据 |
customMetadata | Record<string, string> | 自定义元数据 |
contentRange | string，可选 | 范围响应的 Content-Range |
HttpMetadata 的所有字段均为可选字符串：
| 字段 | 对应响应头 |
|---|---|
contentType | Content-Type |
contentLanguage | Content-Language |
contentDisposition | Content-Disposition |
contentEncoding | Content-Encoding |
cacheControl | Cache-Control |
object.writeHttpMetadata(headers) 将 HTTP 元数据写入必填的 Headers 对象，返回 void，不消费正文。
Get 返回的 StorageObjectBody 还提供只读 body: ReadableStream<Uint8Array>、bodyUsed: boolean，以及无参数的 text(): Promise<string>、json<T>(): Promise<T>、arrayBuffer(): Promise<ArrayBuffer>、blob(): Promise<Blob>。正文只能消费一次，不读取时应取消 body；不能先调用 text 再转发同一个流。
Key 不得含独立的 . / .. 路径段或控制字符，必须为相对路径；加上平台资源前缀后的完整路径最多 1024 UTF-8 字节。文件上传、下载和 HTTP 转发的组合见对象存储示例。
错误处理见 StorageError，声明见 storage.d.ts。