ObjectStorage
Upload files, stream downloads, read metadata, and list objects.
ObjectStorage stores files and binary data, with metadata, range reads, streaming downloads, and paginated listings.
Create and associate the resource first; see resources and associations in the module overview.
import { ObjectStorage } from 'lexmount:storage';
const storage = await ObjectStorage.open('uploads');ObjectStorage.storages()
Function: lists object storage resources associated with this instance.
Parameters: none.
Return value: Promise<{ id: string; name: string }[]>.
ObjectStorage.open(name)
Function: opens an existing associated resource by name.
Parameters: required name: string; see resource naming.
Return value: Promise<Readonly<NamedObjectStorage>>, with read-only name: string and the methods below. Handles bind to resource IDs; recreating a name does not retarget an old handle.
storage.put(key, body, options?)
Function: uploads an object, replacing existing content at the same key.
| Parameter | Type | Required | Description |
|---|---|---|---|
key | string | Yes | Relative object path |
body | BodyInit / null | Yes | A Fetch body, including a string, bytes, Blob, FormData, or byte stream; null is empty |
options.httpMetadata | HttpMetadata | No | HTTP metadata; fields below |
options.customMetadata | Record<string, string> | No | ASCII header-safe custom metadata; names are stored in lowercase |
Return value: Promise<StorageObject> containing object metadata; PUT results omit uploaded.
The entire body is buffered in memory before a single PUT, with a 64 MiB limit. Passing a stream does not make the upload streaming. Exceeding the limit throws RangeError.
storage.get(key, options?)
Function: reads object metadata and a streaming body.
Parameters: required key: string; optional options?: { range?: ObjectRange } selects a byte range:
| range | Description |
|---|---|
{ offset, length } | Read length bytes starting at offset |
{ offset } | Read from offset to the end |
{ length } | Read length bytes starting at 0 |
{ suffix } | Read the final suffix bytes; cannot combine with offset / length |
Offset is a nonnegative safe integer; length and suffix are positive safe integers.
Return value: Promise<StorageObjectBody | null>; null if absent. The object includes metadata, body, and the body methods below. For a range response, size is the returned body length and contentRange describes the range.
storage.head(key)
Function: reads metadata without downloading the body.
Parameters: required key: string.
Return value: Promise<StorageObject | null>; null if absent.
storage.delete(keyOrKeys)
Function: deletes objects within a resource, without deleting the resource itself.
Parameters: required keyOrKeys: string | string[]; arrays accept at most 1000 keys.
Return value: Promise<void>. Missing keys succeed. Batch deletion is not atomic and can partially complete before failure.
storage.list(options?)
Function: lists objects with prefix filtering, delimiter grouping, and pagination.
| Parameter | Type | Default and description |
|---|---|---|
options.prefix | string | Empty string; filter by this prefix |
options.cursor | string | Optional previous cursor; keep prefix and delimiter unchanged |
options.delimiter | string | Optional prefix-grouping delimiter, such as / |
options.limit | number | 1000; integer 1–1000 |
Return value: Promise<ObjectPage>:
| Field | Type | Description |
|---|---|---|
objects | StorageObject[] | Object metadata; listings omit HTTP and custom metadata, so use head for full metadata |
delimitedPrefixes | string[] | Prefixes grouped by delimiter |
truncated | boolean | Whether more pages exist |
cursor | string / null | Next cursor; null on the last page |
StorageObject, StorageObjectBody, and HttpMetadata
| Metadata field | Type | Description |
|---|---|---|
key | string | Object key |
size | number | Bytes; returned body size for range reads |
etag | string | Entity tag |
httpEtag | string | Entity tag suitable for HTTP headers |
uploaded | Optional Date | Service-reported modification time; not provided by PUT |
httpMetadata | HttpMetadata | HTTP metadata below |
customMetadata | Record<string, string> | Custom metadata |
contentRange | Optional string | Content-Range for range responses |
Every HttpMetadata field is an optional string:
| Field | Response header |
|---|---|
contentType | Content-Type |
contentLanguage | Content-Language |
contentDisposition | Content-Disposition |
contentEncoding | Content-Encoding |
cacheControl | Cache-Control |
object.writeHttpMetadata(headers) writes HTTP metadata into its required Headers argument and returns void, without consuming the body.
A get result's StorageObjectBody additionally exposes read-only body: ReadableStream<Uint8Array> and bodyUsed: boolean, plus no-argument text(): Promise<string>, json<T>(): Promise<T>, arrayBuffer(): Promise<ArrayBuffer>, and blob(): Promise<Blob>. A body can be consumed once; cancel it if unused. Do not read text and then forward the same stream.
Keys must be relative paths, without standalone . / .. segments or control characters. The complete path including the platform resource prefix is limited to 1024 UTF-8 bytes. See the object storage example for uploads, downloads, and HTTP forwarding.
See StorageError for shared error handling and storage.d.ts for declarations.