Storage
Defined in: src/storage/storage.ts:64
A backend for storing and retrieving raw bytes under string keys.
The interface is deliberately minimal — four operations over opaque Uint8Array
values. Implementations must treat keys as opaque path-like strings (segments
separated by /) and must round-trip the bytes they are given unchanged.
The ListQuery type parameter controls what list accepts. It defaults to
string (a key prefix), which every backend supports. Implementations may
widen it to accept a richer query object (e.g. a DynamoDB partition/sort-key
filter) while still accepting a plain string for SDK-internal callers.
Implement this to add a custom backend; the SDK ships InMemoryStorage, LocalFileStorage, and S3Storage.
Type Parameters
Section titled “Type Parameters”| Type Parameter | Default type |
|---|---|
ListQuery | string |
Methods
Section titled “Methods”write()
Section titled “write()”write(key, data): Promise<void>;Defined in: src/storage/storage.ts:72
Stores data under key, overwriting any existing value.
Parameters
Section titled “Parameters”| Parameter | Type | Description |
|---|---|---|
key | string | Opaque, /-separated key identifying the value |
data | Uint8Array | Raw bytes to persist |
Returns
Section titled “Returns”Promise<void>
Throws
Section titled “Throws”StorageError if the write fails
read()
Section titled “read()”read(key): Promise<Uint8Array<ArrayBufferLike>>;Defined in: src/storage/storage.ts:81
Retrieves the bytes previously stored under key.
Parameters
Section titled “Parameters”| Parameter | Type | Description |
|---|---|---|
key | string | The key to read |
Returns
Section titled “Returns”Promise<Uint8Array<ArrayBufferLike>>
The stored bytes, or null if no value exists for key
Throws
Section titled “Throws”StorageError if the read fails for a reason other than a missing key
delete()
Section titled “delete()”delete(key): Promise<void>;Defined in: src/storage/storage.ts:89
Deletes the value stored under key. A no-op if the key does not exist.
Parameters
Section titled “Parameters”| Parameter | Type | Description |
|---|---|---|
key | string | The key to delete |
Returns
Section titled “Returns”Promise<void>
Throws
Section titled “Throws”StorageError if the delete fails
list()
Section titled “list()”list(query): Promise<string[]>;Defined in: src/storage/storage.ts:105
Lists keys matching the given query.
When ListQuery is string (the default), this is a prefix match — returns
full keys (not the suffix after the prefix), sorted lexicographically. An empty
string lists every key.
Implementations may accept richer query objects (e.g. partition + sort-key filters) while still supporting a plain string prefix for SDK-internal callers.
Parameters
Section titled “Parameters”| Parameter | Type | Description |
|---|---|---|
query | ListQuery | A string prefix or backend-specific query object |
Returns
Section titled “Returns”Promise<string[]>
The matching keys, sorted ascending
Throws
Section titled “Throws”StorageError if the listing fails
namespace()?
Section titled “namespace()?”optional namespace(prefix): Storage;Defined in: src/storage/storage.ts:116
Returns a view of this storage with all keys prefixed by prefix.
The original storage is not mutated.
Optional — shipped backends implement this, custom backends may omit it.
Parameters
Section titled “Parameters”| Parameter | Type | Description |
|---|---|---|
prefix | string | Prefix to prepend to all keys |
Returns
Section titled “Returns”Storage
A Storage view scoped to the given prefix