API Reference

get

Retrieves an object by path.

const result = await storage.get(path, options?)   // { meta, data: Uint8Array }
const text = await storage.getText(path)            // string
const json = await storage.getJson<T>(path)         // parsed JSON

let result = storage.get(&path.into()).await?;
let bytes = result.bytes().await?;

Parameter	Type	Required	Description
`path`	`string`	Yes	Object path (key). Max 1,024 bytes.
`options.rangeStart`	`number`	No	Start byte offset for partial read.
`options.rangeEnd`	`number`	No	End byte offset for partial read.
`options.ifMatch`	`string`	No	Only return if ETag matches.
`options.ifNoneMatch`	`string`	No	Only return if ETag does not match.
`options.ifModifiedSince`	`Date`	No	Only return if modified after this time.
`options.ifUnmodifiedSince`	`Date`	No	Only return if not modified after this time.

Returns: StorageGetResult — { meta: StorageObjectMeta, data: Uint8Array }

Errors:

Object not found — throws with a not-found error.
STORAGE_OPERATION_FAILED — backend error (retryable).

getText

Retrieves an object as a UTF-8 string.

const text = await storage.getText(path: string, options?: StorageGetOptions): Promise<string>

Same parameters as get. Returns the object data decoded as UTF-8.

getJson

Retrieves an object and parses it as JSON.

const data = await storage.getJson<T>(path: string, options?: StorageGetOptions): Promise<T>

Same parameters as get. Returns the parsed JSON value.

put

Stores an object. Overwrites if the path already exists.

await storage.put(path, data, options?)
// data: Uint8Array | string | object (auto-serialized as JSON)

storage.put(&path.into(), payload).await?;

Parameter	Type	Required	Description
`path`	`string`	Yes	Object path (key). Max 1,024 bytes.
`data`	`Uint8Array \| string \| object`	Yes	Object data. Objects are JSON-serialized.
`options.contentType`	`string`	No	MIME type.
`options.metadata`	`Record<string, string>`	No	Custom metadata key-value pairs.
`options.ifNotExists`	`boolean`	No	Only store if the path doesn't already exist.

putMultipart

Stores a large object using streaming multipart upload.

await storage.putMultipart(
  path: string,
  chunks: AsyncIterable<Uint8Array>,
  options?: StoragePutOptions
): Promise<void>

Use this for files larger than a few MB. Data is streamed in chunks without buffering the entire object in memory.

delete

Deletes an object. Deleting a non-existent object is a no-op.

await storage.delete(path: string): Promise<void>

async fn delete(&self, location: &Path) -> Result<()>

list

Lists objects under a prefix. Returns an async iterator.

for await (const obj of storage.list(prefix?: string, options?: { offset?: string })) {
  // obj: StorageObjectMeta
}

fn list(&self, prefix: Option<&Path>) -> BoxStream<'_, Result<ObjectMeta>>

Parameter	Type	Required	Description
`prefix`	`string`	No	Only return objects whose path starts with this prefix.
`options.offset`	`string`	No	Start listing after this path (for pagination).

Yields: StorageObjectMeta — { location, lastModified, size, etag, version }

listWithDelimiter

Lists objects and common prefixes under a prefix, using / as a delimiter. Useful for directory-style browsing.

const result = await storage.listWithDelimiter(prefix?: string): Promise<StorageListResult>

Returns: StorageListResult — { commonPrefixes: string[], objects: StorageObjectMeta[] }

head

Returns object metadata without downloading the object body.

const meta = await storage.head(path: string): Promise<StorageObjectMeta>

async fn head(&self, location: &Path) -> Result<ObjectMeta>

Returns: StorageObjectMeta — { location, lastModified, size, etag, version }

Errors: Throws if the object does not exist.

exists

Checks if an object exists.

const found = await storage.exists(path: string): Promise<boolean>

copy

Copies an object from one path to another within the same storage resource.

await storage.copy(from: string, to: string): Promise<void>

rename

Moves an object from one path to another. Equivalent to copy + delete.

await storage.rename(from: string, to: string): Promise<void>

copyIfNotExists / renameIfNotExists

Same as copy / rename, but only if the destination path does not already exist.

await storage.copyIfNotExists(from: string, to: string): Promise<void>
await storage.renameIfNotExists(from: string, to: string): Promise<void>

signedUrl

Generates a time-limited signed URL for direct client access.

const result = await storage.signedUrl(path: string, options: SignedUrlOptions): Promise<SignedUrlResult>

Parameter	Type	Required	Description
`path`	`string`	Yes	Object path.
`options.operation`	`"get" \| "put" \| "delete"`	Yes	The HTTP operation the URL authorizes.
`options.expiresInSeconds`	`number`	No	URL lifetime. Default: 3600 (1 hour).
`options.contentType`	`string`	No	Required content type for `put` URLs.

Returns: SignedUrlResult — { url: string, expiresAt?: Date }

getBaseDir / getUrl

Utility methods for advanced use cases.

const baseDir = await storage.getBaseDir(): Promise<string>
const url = await storage.getUrl(): Promise<string>

getBaseDir() returns the configured base directory path. getUrl() returns the underlying storage URL (e.g., s3://bucket-name or file:///path/to/dir).

Types

StorageObjectMeta

interface StorageObjectMeta {
  location: string        // Full path of the object
  lastModified?: Date     // Last modified timestamp
  size: number            // Object size in bytes
  etag?: string           // Entity tag
  version?: string        // Object version (if versioning enabled)
}

StorageGetResult

interface StorageGetResult {
  meta: StorageObjectMeta
  data: Uint8Array
}

StorageListResult

interface StorageListResult {
  commonPrefixes: string[]      // Directory-like prefixes
  objects: StorageObjectMeta[]  // Objects at this level
}

SignedUrlResult

interface SignedUrlResult {
  url: string           // The signed URL
  expiresAt?: Date      // When the URL expires
}

API Reference

On this page