KVStorage
Persist string values with expiration and prefix pagination.
KVStorage provides persistent string key/value data with expiration and prefix pagination, suitable for configuration, cached values, and JSON text.
Create and associate the resource first; see resources and associations in the module overview.
import { KVStorage } from 'lexmount:storage';
const kv = await KVStorage.open('cache');KVStorage.storages()
Function: lists KV resources associated with this instance.
Parameters: none.
Return value: Promise<{ id: string; name: string }[]>.
KVStorage.open(name)
Function: opens an existing associated KV resource by name.
Parameters: required name: string; see resource naming.
Return value: Promise<Readonly<NamedKVStorage>>, with read-only name: string and the methods below. Handles bind to the selected resource ID.
kv.put(key, value, options?)
Function: stores a string, replacing the old value and expiration settings for that key.
| Parameter | Type | Required | Description |
|---|---|---|---|
key | string | Yes | Nonempty valid Unicode without NUL; at most 1024 UTF-8 bytes |
value | string | Yes | May be empty; valid Unicode without NUL; at most 1 MiB UTF-8 text |
options.expirationTtl | number | No | Positive safe-integer seconds, measured with the storage server's clock |
options.expiration | number | No | Future Unix timestamp in seconds; a safe integer |
The expiration options are mutually exclusive. Omit both to retain indefinitely and clear any previous TTL. Every put replaces expiration settings.
Return value: Promise<void>, resolving after commit. Values are strings. Automatic non-string conversion follows String(value), without automatic JSON serialization. Use JSON.stringify() for JSON.
kv.get(key)
Function: reads an unexpired value.
Parameters: required key: string, following put's rules.
Return value: Promise<string | null>; null for missing or expired values. Empty strings are valid results. Parse JSON yourself and distinguish an empty string from absence.
kv.delete(key)
Function: deletes one key, without deleting the KV resource.
Parameters: required key: string, following put's rules.
Return value: Promise<void>; missing keys also succeed.
kv.list(options?)
Function: lists unexpired keys in UTF-8 byte order with pagination.
| Parameter | Type | Default and description |
|---|---|---|
options.prefix | string | Empty string; a literal prefix, with % and _ treated literally |
options.cursor | string | Optional cursor from the same resource and prefix |
options.limit | number | 1000; integer 1–1000 |
Return value: Promise<KVPage>, containing keys: { name: string; expiration?: number }[], truncated: boolean, and cursor: string | null. Expiration, when present, is a Unix timestamp in seconds. The last cursor is null.
Get and list immediately hide expired records. Concurrent changes mean pagination is not a snapshot. Operations commit independently; there are no multi-key transactions or compare-and-swap. See the KV example.
See StorageError for shared error handling and storage.d.ts for declarations.