Storage API

Factory options, typed reads, writes, expiration, subscriptions, and Storage-compatible methods.

createStorage(options?: CreateStorageOptions): UltraStorage

Creates a new storage instance. All options are optional.

Also available from ultrastorage/core where serializer is required and devalue is not bundled. See Custom serializer.

Returns a UltraStorage instance, that has the same interface as Storage, with additional APIs.

UltraStorage instance

A UltraStorage instance with the following methods:

storage.subscribe(key, listener)

Observe one key and receive set, remove, or expire events. Returns an idempotent unsubscribe function. See the subscription guide for the event types, timing, errors, and cross-tab behavior.

storage.getItem<T = unknown>(key: string): T | null

Retrieves and deserializes a value. Returns null if the key is missing or expired. If the entry is expired, getItem() removes it from storage.

storage.getItem<T>(key: string, options: { schema: StandardSchema }): T | null

Retrieves and deserializes a value. Returns null if the key is missing, expired, or fails schema validation.

If the entry is expired, getItem() removes it from storage.

Options:

storage.setItem<T = unknown>(key: string, value: T, options?: StorageOptions): void

Serializes and stores a value. Options:

ttl and expiresAt cannot be used together.

storage.getOrInit<T>(key: string, factory: () => T, options?: StorageOptions): T

Returns the existing value for key, or calls factory() to create, store, and return a new value.

Options:

ttl and expiresAt cannot be used together.

getOrInit() is useful for migrating from an existing localStorage (but non-ultrastorage) key. To do that, specify a factory function that reads from the existing localStorage key.

const theme = storage.getOrInit('theme', () => localStorage.getItem('theme'));

storage.updateItem<T = unknown>(key: string, updater: (value: T | null) => T, options?: StorageOptions): T

Calls updater(currentValue) where currentValue is the existing value (or null), stores the result, and returns it.

Options:

ttl and expiresAt cannot be used together.

storage.removeItem(key: string): void

Removes a single key from the current namespace.

storage.has(key: string): boolean

Returns true if the key exists and is not expired. Expired entries are treated as missing and are not removed by has().

storage.key(index: number): string | null

Returns the key at the given zero-based index among non-expired entries, or null if the index is out of bounds. Expired entries are skipped but not removed.

storage.clear(): void

Removes all entries written by ultrastorage in the current namespace.

Entries outside the namespace and values not written by ultrastorage are left untouched.

storage.clearExpired(): void

Removes only expired entries in the current namespace.

storage.length: number

The number of non-expired entries in the current namespace.

Expired entries are excluded from the count but not removed unless read via getItem() or swept with clearExpired().

createMemoryStorage(): Storage

Returns an in-memory Storage implementation. Useful for tests or server-side usage.