Browser-tier AbstractStorage adapter backed by the synchronous Storage API (globalThis.localStorage). Provides namespaced, origin-scoped key-value storage with full AbstractStorage conformance, AbortSignal threading, Zod-validated options, structured LocalStorageError boundary, lazy TTL eviction, an injectable StorageLike adapter for testing, and a complete OpenTelemetry surface.

Documentation tree

envelope — (no submodules)
- envelope — (no submodules)
in-memory-storage — (no submodules)
- in-memory-storage — (no submodules)
key-sanitizer — (no submodules)
- key-sanitizer — (no submodules)
local-storage — (no submodules) - local-storage.ops — localStorage is a flat string…
- local-storage.errors — Maps every error thrown by the underlying Storage adapter to the typed LocalStorageError surface. Browsers raise in…
- local-storage — (no submodules) - local-storage.ops — localStorage is a flat string…
- local-storage.ops — localStorage is a flat string keyspace shared across the entire origin. @suaveplan/storage-browser-localstorage par…
- local-storage.partial — localStorage is an inherently whole-value API — there is no native partial read or partial write. `LocalStorageStorag…
- local-storage.slot — The slot module owns the pure functional helpers LocalStorageStorage needs but does not benefit from keeping inside t…
local-storage-adapter — (no submodules)
- local-storage-adapter — (no submodules)
otel — (no submodules)
- otel — (no submodules)
registry — (no submodules)
- registry — (no submodules)
error-codes — Single source of truth for every error code the @suaveplan/storage-browser-localstorage package can throw. The regist…

envelope — (no submodules)- in-memory-storage — (no submodules) - in-memory-storage — (no submodules)- key-sanitizer — (no submodules) - key-sanitizer — (no submodules)- local-storage — (no submodules) - local-storage.errors — Maps every error thrown by the underlying Storage adapter to the typed LocalStorageError surface. Browsers raise in…
local-storage — (no submodules) - local-storage.ops — localStorage is a flat string keyspace shared across the entire origin. @suaveplan/storage-browser-localstorage par…
local-storage.partial — localStorage is an inherently whole-value API — there is no native partial read or partial write. `LocalStorageStorag…
local-storage.slot — The slot module owns the pure functional helpers LocalStorageStorage needs but does not benefit from keeping inside t…
local-storage-adapter — (no submodules) - local-storage-adapter — (no submodules)- otel — (no submodules) - otel — (no submodules)- registry — (no submodules) - registry — (no submodules)- error-codes — Single source of truth for every error code the @suaveplan/storage-browser-localstorage package can throw. The regist…

Install

bun add @suaveplan/storage-browser-localstorage

Quick start

import {
    createLocalStorageStorage,
    isLocalStorageAvailable,
} from "@suaveplan/storage-browser-localstorage";

if (!isLocalStorageAvailable()) {
    throw new Error("This browser blocks localStorage (private mode?)");
}
const storage = createLocalStorageStorage({ namespace: "myapp" });
await storage.set("user/42", new TextEncoder().encode("hello"));
const back = await storage.get("user/42");

Factory integration

import { registerLocalStorageProvider } from "@suaveplan/storage-browser-localstorage/registry";
import { createStorage } from "@suaveplan/storage/factory";

registerLocalStorageProvider();
const storage = createStorage({
    type: "localstorage",
    config: { namespace: "myapp" },
});

The package does NOT self-register at module-evaluation time — call registerLocalStorageProvider() explicitly so sideEffects: false bundlers can tree-shake the factory path when not used.

Capabilities

Capability	Value	Notes
`partialReads`	`false`	`getPartial` is implemented via the `AbstractStorage` reference helper (load + slice).
`partialWrites`	`false`	`setPartial` is implemented via the `AbstractStorage` reference helper (load + splice + write).
`nativeStreams`	`false`	`createReadStream` / `createWriteStream` use the `AbstractStorage` default buffered implementations.
`atomicWrites`	`true`	A single `setItem` is atomic at the DOM API level.
`contentAddressable`	`false`	Keys are caller-supplied strings.

Modules

src/error-codes.ts — LOCAL_STORAGE_CODES registry + LocalStorageError.
src/key-sanitizer/key-sanitizer.ts — strict key boundary.
src/envelope/envelope.ts — base64 + JSON wire format.
src/local-storage-adapter/local-storage-adapter.ts — defaultLocalStorage() + isLocalStorageAvailable().
src/local-storage/local-storage.ts — the LocalStorageStorage class.
src/local-storage/local-storage.errors.ts — DOMException mapping.
src/local-storage/local-storage.ops.ts — namespacing + pagination helpers.
src/local-storage/local-storage.partial.ts — argument validation.
src/local-storage/local-storage.slot.ts — option resolution + envelope IO.
src/otel/otel.ts — OpenTelemetry instrument set.
src/registry/registry.ts — registerLocalStorageProvider().
src/in-memory-storage/in-memory-storage.ts — real-implementation test double, exposed under ./in-memory-storage for downstream test packages.
src/types/storage-like.types.ts — structural DOM Storage surface.
src/types/local-storage-storage.types.ts — option boundary.

License

MIT.