Overview

lexmount:storage provides structured databases, file storage, and string key/value storage. Data outlives a JavaScript execution, and instances associated with the same resource can share committed data.

• IndexedDB: Structured records, indexes, cursors, and transactions.
• ObjectStorage: Files, binary objects, metadata, and streaming downloads.
• KVStorage: String key/value data, expiration, and prefix listings.

import { IndexedDB, ObjectStorage, KVStorage } from 'lexmount:storage';

console.log(await IndexedDB.databases());
const uploads = await ObjectStorage.open('uploads');
const cache = await KVStorage.open('cache');
await cache.put('ready', 'true');

Resources and associations

Create resources in Storage, then associate them in a stopped instance's Storage tab; see the quickstart. Code can only list or open associated resources. open() never creates resources.

Resources belong to a project and can serve multiple instances; an instance can use multiple resources. Names are unique within a project and storage type, preserved as supplied, and limited to 1024 UTF-8 bytes. Whitespace-only names, NUL, and invalid Unicode are rejected. Backends are platform configuration. Do not supply database connections or object storage credentials; application variables cannot select or override the backend.

Association changes require the instance to be fully stopped, cleaned up, and free of pending operations. Each atomic association batch accepts at most 100 resources. Stopping, rerunning, deleting an instance, or removing an association preserves resources and data. Instance deletion only removes its associations. Remove all associations before deleting a resource. Failed object-resource deletion may already have removed some files; a resource pending deletion cannot be accessed or reassociated, and deleting again continues cleanup.

StorageError

Object and KV storage failures reject with the exported StorageError extends Error. It has read-only code: string, status: number, and requestId: string, plus an error description in message. Status 0 means no HTTP status is available; requestId is empty when unavailable.

The constructor is new StorageError(message, options?): message is a string; optional options contains code?: string (default StorageUnavailable), status?: number (default 0), and requestId?: string (default empty string). It returns a StorageError object. Applications usually just catch errors produced by storage operations.

Invalid arguments can also throw TypeError or RangeError. IndexedDB uses request errors, transaction abortion, and DOMException; see requests and events.

See storage.d.ts. Its base IndexedDB types come from the WebWorker standard library; the runtime restrictions documented for each storage API still apply.