@flighthq/storage 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export * from './storage';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,WAAW,CAAC"}

package/dist/index.js

@@ -0,0 +1,2 @@
+export * from './storage';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,WAAW,CAAC"}

package/dist/storage.d.ts

@@ -0,0 +1,41 @@
+import type { StorageBackend, StorageMigration, StorageNamespace, StorageQuota, StorageSignals } from '@flighthq/types';
+export declare function clearStorage(): boolean;
+export declare function clearStorageNamespace(namespace: Readonly<StorageNamespace>): boolean;
+export declare function createStorageNamespace(prefix: string): StorageNamespace;
+export declare function createWebStorageBackend(): StorageBackend;
+export declare function disableStorageSignals(): void;
+export declare function enableStorageSignals(): StorageSignals;
+export declare function getNamespacedStorageByteSize(namespace: Readonly<StorageNamespace>): number;
+export declare function getNamespacedStorageEntries(namespace: Readonly<StorageNamespace>): readonly (readonly [string, string])[];
+export declare function getNamespacedStorageItem(namespace: Readonly<StorageNamespace>, key: string): string | null;
+export declare function getNamespacedStorageKeys(namespace: Readonly<StorageNamespace>): string[];
+export declare function getStorageBackend(): StorageBackend;
+export declare function getStorageBoolean(key: string): boolean | null;
+export declare function getStorageBooleanOr(key: string, fallback: boolean): boolean;
+export declare function getStorageByteSize(): number;
+export declare function getStorageEntries(): readonly (readonly [string, string])[];
+export declare function getStorageItem(key: string): string | null;
+export declare function getStorageItemCount(): number;
+export declare function getStorageItemOr(key: string, fallback: string): string;
+export declare function getStorageItems(keys: readonly string[]): readonly (string | null)[];
+export declare function getStorageJSON<T>(key: string): T | null;
+export declare function getStorageJSONOr<T>(key: string, fallback: T): T;
+export declare function getStorageKeys(): string[];
+export declare function getStorageNumber(key: string): number | null;
+export declare function getStorageNumberOr(key: string, fallback: number): number;
+export declare function getStorageQuotaEstimate(): Promise<StorageQuota | null>;
+export declare function getStorageSignals(): StorageSignals | null;
+export declare function hasNamespacedStorageItem(namespace: Readonly<StorageNamespace>, key: string): boolean;
+export declare function hasStorageItem(key: string): boolean;
+export declare function migrateStorage(namespace: Readonly<StorageNamespace> | null, migrations: readonly Readonly<StorageMigration>[]): number;
+export declare function removeNamespacedStorageItem(namespace: Readonly<StorageNamespace>, key: string): boolean;
+export declare function removeStorageItem(key: string): boolean;
+export declare function removeStorageItems(keys: readonly string[]): boolean;
+export declare function setNamespacedStorageItem(namespace: Readonly<StorageNamespace>, key: string, value: string): boolean;
+export declare function setStorageBackend(backend: StorageBackend | null): void;
+export declare function setStorageBoolean(key: string, value: boolean): boolean;
+export declare function setStorageItem(key: string, value: string): boolean;
+export declare function setStorageItems(record: Readonly<Record<string, string>>): boolean;
+export declare function setStorageJSON<T>(key: string, value: T): boolean;
+export declare function setStorageNumber(key: string, value: number): boolean;
+//# sourceMappingURL=storage.d.ts.map

package/dist/storage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"storage.d.ts","sourceRoot":"","sources":["../src/storage.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EACV,cAAc,EAEd,gBAAgB,EAChB,gBAAgB,EAChB,YAAY,EACZ,cAAc,EACf,MAAM,iBAAiB,CAAC;AAGzB,wBAAgB,YAAY,IAAI,OAAO,CAMtC;AAGD,wBAAgB,qBAAqB,CAAC,SAAS,EAAE,QAAQ,CAAC,gBAAgB,CAAC,GAAG,OAAO,CASpF;AAID,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,MAAM,GAAG,gBAAgB,CAEvE;AAKD,wBAAgB,uBAAuB,IAAI,cAAc,CAgExD;AAID,wBAAgB,qBAAqB,IAAI,IAAI,CAW5C;AAKD,wBAAgB,oBAAoB,IAAI,cAAc,CAWrD;AAGD,wBAAgB,4BAA4B,CAAC,SAAS,EAAE,QAAQ,CAAC,gBAAgB,CAAC,GAAG,MAAM,CAa1F;AAID,wBAAgB,2BAA2B,CACzC,SAAS,EAAE,QAAQ,CAAC,gBAAgB,CAAC,GACpC,SAAS,CAAC,SAAS,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,EAAE,CAYxC;AAGD,wBAAgB,wBAAwB,CAAC,SAAS,EAAE,QAAQ,CAAC,gBAAgB,CAAC,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAE1G;AAGD,wBAAgB,wBAAwB,CAAC,SAAS,EAAE,QAAQ,CAAC,gBAAgB,CAAC,GAAG,MAAM,EAAE,CAOxF;AAGD,wBAAgB,iBAAiB,IAAI,cAAc,CAGlD;AAID,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,GAAG,IAAI,CAM7D;AAGD,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,OAAO,GAAG,OAAO,CAE3E;AAID,wBAAgB,kBAAkB,IAAI,MAAM,CAa3C;AAID,wBAAgB,iBAAiB,IAAI,SAAS,CAAC,SAAS,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,EAAE,CAS1E;AAGD,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAEzD;AAGD,wBAAgB,mBAAmB,IAAI,MAAM,CAE5C;AAGD,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAEtE;AAID,wBAAgB,eAAe,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,CAAC,MAAM,GAAG,IAAI,CAAC,EAAE,CAOnF;AAID,wBAAgB,cAAc,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,GAAG,CAAC,GAAG,IAAI,CAQvD;AAGD,wBAAgB,gBAAgB,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC,GAAG,CAAC,CAQ/D;AAGD,wBAAgB,cAAc,IAAI,MAAM,EAAE,CAEzC;AAID,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAK3D;AAGD,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAExE;AAKD,wBAAsB,uBAAuB,IAAI,OAAO,CAAC,YAAY,GAAG,IAAI,CAAC,CAe5E;AAGD,wBAAgB,iBAAiB,IAAI,cAAc,GAAG,IAAI,CAEzD;AAGD,wBAAgB,wBAAwB,CAAC,SAAS,EAAE,QAAQ,CAAC,gBAAgB,CAAC,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAEpG;AAGD,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAEnD;AAMD,wBAAgB,cAAc,CAC5B,SAAS,EAAE,QAAQ,CAAC,gBAAgB,CAAC,GAAG,IAAI,EAC5C,UAAU,EAAE,SAAS,QAAQ,CAAC,gBAAgB,CAAC,EAAE,GAChD,MAAM,CAuBR;AAGD,wBAAgB,2BAA2B,CAAC,SAAS,EAAE,QAAQ,CAAC,gBAAgB,CAAC,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAEvG;AAGD,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAOtD;AAGD,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAOnE;AAGD,wBAAgB,wBAAwB,CAAC,SAAS,EAAE,QAAQ,CAAC,gBAAgB,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAEnH;AAGD,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,cAAc,GAAG,IAAI,GAAG,IAAI,CActE;AAGD,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,OAAO,CAEtE;AAGD,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAOlE;AAGD,wBAAgB,eAAe,CAAC,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,GAAG,OAAO,CAOjF;AAID,wBAAgB,cAAc,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,GAAG,OAAO,CAQhE;AAGD,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAEpE"}

package/dist/storage.js

@@ -0,0 +1,470 @@
+import { clearSignal, createSignal, emitSignal } from '@flighthq/signals';
+// Removes every key. Returns false when the host denies access. Sentinel, not throw.
+export function clearStorage() {
+    const result = getStorageBackend().clear();
+    if (_signalsActive && result) {
+        _emitStorageChange({ key: null, oldValue: null, newValue: null });
+    }
+    return result;
+}
+// Removes all keys under the namespace without touching other keys. Returns false on denial.
+export function clearStorageNamespace(namespace) {
+    const prefix = namespace.prefix + '.';
+    const backend = getStorageBackend();
+    let success = true;
+    for (const key of backend.keys()) {
+        if (!key.startsWith(prefix))
+            continue;
+        if (!backend.removeItem(key))
+            success = false;
+    }
+    return success;
+}
+// Creates a prefix-scoped view into the keyspace. Keys under the namespace are stored as
+// `prefix + '.' + key` and never collide with the global keyspace or other namespaces.
+export function createStorageNamespace(prefix) {
+    return { prefix };
+}
+// Builds the default web backend over window.localStorage. Every call is guarded with try/catch:
+// localStorage access can throw in private mode or when storage is disabled. Writes return false and
+// reads return null / [] on failure rather than throwing — storage is an expected-failure surface.
+export function createWebStorageBackend() {
+    return {
+        getItem(key) {
+            const ls = getWebStorage();
+            if (ls === null)
+                return null;
+            try {
+                return ls.getItem(key);
+            }
+            catch {
+                return null;
+            }
+        },
+        setItem(key, value) {
+            const ls = getWebStorage();
+            if (ls === null)
+                return false;
+            try {
+                ls.setItem(key, value);
+                return true;
+            }
+            catch {
+                return false;
+            }
+        },
+        removeItem(key) {
+            const ls = getWebStorage();
+            if (ls === null)
+                return false;
+            try {
+                ls.removeItem(key);
+                return true;
+            }
+            catch {
+                return false;
+            }
+        },
+        clear() {
+            const ls = getWebStorage();
+            if (ls === null)
+                return false;
+            try {
+                ls.clear();
+                return true;
+            }
+            catch {
+                return false;
+            }
+        },
+        keys() {
+            const ls = getWebStorage();
+            if (ls === null)
+                return [];
+            try {
+                const out = [];
+                for (let i = 0; i < ls.length; i += 1) {
+                    const key = ls.key(i);
+                    if (key !== null)
+                        out.push(key);
+                }
+                return out;
+            }
+            catch {
+                return [];
+            }
+        },
+        subscribeChanges(listener) {
+            if (typeof window === 'undefined')
+                return () => { };
+            const handler = (event) => {
+                listener({ key: event.key, oldValue: event.oldValue, newValue: event.newValue });
+            };
+            window.addEventListener('storage', handler);
+            return () => window.removeEventListener('storage', handler);
+        },
+    };
+}
+// Stops the storage change-notification group. Removes the DOM storage listener and disconnects
+// all listeners. Pair with enableStorageSignals.
+export function disableStorageSignals() {
+    if (!_signalsActive)
+        return;
+    _signalsActive = false;
+    if (_crossTabUnsubscribe !== null) {
+        _crossTabUnsubscribe();
+        _crossTabUnsubscribe = null;
+    }
+    if (_signals !== null) {
+        clearSignal(_signals.onChange);
+        _signals = null;
+    }
+}
+// Starts the storage change-notification group, wiring cross-tab DOM storage events and enabling
+// same-tab emission for write operations. Idempotent: calling again while already enabled returns
+// the existing signals object. Pair with disableStorageSignals.
+export function enableStorageSignals() {
+    if (_signalsActive && _signals !== null)
+        return _signals;
+    _signals = { onChange: createSignal() };
+    _signalsActive = true;
+    const backend = getStorageBackend();
+    if (backend.subscribeChanges !== undefined) {
+        _crossTabUnsubscribe = backend.subscribeChanges((change) => {
+            _emitStorageChange(change);
+        });
+    }
+    return _signals;
+}
+// Returns the estimated UTF-16 byte cost of all keys under the namespace. Returns -1 on denial.
+export function getNamespacedStorageByteSize(namespace) {
+    const prefix = namespace.prefix + '.';
+    const backend = getStorageBackend();
+    const keys = backend.keys();
+    if (keys.length === 0)
+        return 0;
+    let total = 0;
+    for (const rawKey of keys) {
+        if (!rawKey.startsWith(prefix))
+            continue;
+        const value = backend.getItem(rawKey);
+        if (value === null)
+            continue;
+        total += (rawKey.length + value.length) * 2;
+    }
+    return total;
+}
+// Returns all key/value pairs under the given namespace prefix. Keys returned are unprefixed.
+// Returns [] on denial.
+export function getNamespacedStorageEntries(namespace) {
+    const prefix = namespace.prefix + '.';
+    const backend = getStorageBackend();
+    const keys = backend.keys();
+    const out = [];
+    for (const rawKey of keys) {
+        if (!rawKey.startsWith(prefix))
+            continue;
+        const key = rawKey.slice(prefix.length);
+        const value = backend.getItem(rawKey);
+        if (value !== null)
+            out.push([key, value]);
+    }
+    return out;
+}
+// Reads a value from the namespace. Returns null on absent key or access denial.
+export function getNamespacedStorageItem(namespace, key) {
+    return getStorageBackend().getItem(_namespacedKey(namespace, key));
+}
+// Returns every key stored under the namespace (unprefixed). Returns [] on denial.
+export function getNamespacedStorageKeys(namespace) {
+    const prefix = namespace.prefix + '.';
+    const out = [];
+    for (const rawKey of getStorageBackend().keys()) {
+        if (rawKey.startsWith(prefix))
+            out.push(rawKey.slice(prefix.length));
+    }
+    return out;
+}
+// The active storage backend, or a lazily-created web default. There is always a backend.
+export function getStorageBackend() {
+    if (_backend === null)
+        _backend = createWebStorageBackend();
+    return _backend;
+}
+// Reads the stored value as a stored boolean ('true'/'false'). Returns null on absent key,
+// access denial, or unrecognized value.
+export function getStorageBoolean(key) {
+    const raw = getStorageBackend().getItem(key);
+    if (raw === null)
+        return null;
+    if (raw === 'true')
+        return true;
+    if (raw === 'false')
+        return false;
+    return null;
+}
+// Returns the stored boolean, or `fallback` on absent key, access denial, or unrecognized value.
+export function getStorageBooleanOr(key, fallback) {
+    return getStorageBoolean(key) ?? fallback;
+}
+// Returns the estimated UTF-16 byte cost of the entire store. Delegates to the backend's
+// byteSize() when available; otherwise enumerates entries. Returns -1 on denial.
+export function getStorageByteSize() {
+    const backend = getStorageBackend();
+    if (backend.byteSize !== undefined)
+        return backend.byteSize();
+    const keys = backend.keys();
+    if (keys.length === 0)
+        return 0;
+    let total = 0;
+    for (const key of keys) {
+        const value = backend.getItem(key);
+        if (value === null)
+            continue;
+        // localStorage stores strings as UTF-16: each code unit is 2 bytes.
+        total += (key.length + value.length) * 2;
+    }
+    return total;
+}
+// Returns all key/value pairs in one pass. Skips keys whose value is null (concurrent removal).
+// Returns [] on denial.
+export function getStorageEntries() {
+    const backend = getStorageBackend();
+    const keys = backend.keys();
+    const out = [];
+    for (const key of keys) {
+        const value = backend.getItem(key);
+        if (value !== null)
+            out.push([key, value]);
+    }
+    return out;
+}
+// Reads a stored value, or null when the key is absent or access is denied.
+export function getStorageItem(key) {
+    return getStorageBackend().getItem(key);
+}
+// Returns the number of stored keys. Returns 0 on denial.
+export function getStorageItemCount() {
+    return getStorageBackend().keys().length;
+}
+// Returns the stored value, or `fallback` when the key is absent or access is denied.
+export function getStorageItemOr(key, fallback) {
+    return getStorageBackend().getItem(key) ?? fallback;
+}
+// Reads multiple keys in one call. Returns a parallel-indexed array with null for absent/denied
+// keys. Returns [] when keys is empty.
+export function getStorageItems(keys) {
+    const backend = getStorageBackend();
+    const out = new Array(keys.length);
+    for (let i = 0; i < keys.length; i += 1) {
+        out[i] = backend.getItem(keys[i]);
+    }
+    return out;
+}
+// Reads and JSON.parses a stored value. Returns null on absent key, parse failure, or access
+// denial — corrupt stored data is an expected-failure surface; do not throw.
+export function getStorageJSON(key) {
+    const raw = getStorageBackend().getItem(key);
+    if (raw === null)
+        return null;
+    try {
+        return JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+}
+// Returns the parsed stored value, or `fallback` on absent key, parse failure, or access denial.
+export function getStorageJSONOr(key, fallback) {
+    const raw = getStorageBackend().getItem(key);
+    if (raw === null)
+        return fallback;
+    try {
+        return JSON.parse(raw);
+    }
+    catch {
+        return fallback;
+    }
+}
+// Returns every stored key, or [] when access is denied.
+export function getStorageKeys() {
+    return getStorageBackend().keys();
+}
+// Reads the stored value as a number. Returns null on absent key, access denial, or parse failure
+// (NaN is treated as parse failure).
+export function getStorageNumber(key) {
+    const raw = getStorageBackend().getItem(key);
+    if (raw === null)
+        return null;
+    const n = Number(raw);
+    return Number.isNaN(n) ? null : n;
+}
+// Returns the stored number, or `fallback` on absent key, access denial, or parse failure.
+export function getStorageNumberOr(key, fallback) {
+    return getStorageNumber(key) ?? fallback;
+}
+// Returns the estimated storage quota from the web backend (navigator.storage.estimate), or null
+// when unavailable. This is async on the browser; the result is best-effort and may be stale.
+// Returns null when the API is absent or returns a denial.
+export async function getStorageQuotaEstimate() {
+    if (typeof navigator === 'undefined')
+        return null;
+    const storage = navigator.storage;
+    if (storage?.estimate === undefined)
+        return null;
+    try {
+        const estimate = await storage.estimate();
+        const used = typeof estimate.usage === 'number' ? estimate.usage : -1;
+        const available = typeof estimate.quota === 'number' && estimate.quota >= 0 ? estimate.quota - (used >= 0 ? used : 0) : -1;
+        return { used, available };
+    }
+    catch {
+        return null;
+    }
+}
+// Returns the active StorageSignals, or null when signals have not been enabled.
+export function getStorageSignals() {
+    return _signals;
+}
+// Returns true when the key exists in the namespace.
+export function hasNamespacedStorageItem(namespace, key) {
+    return getStorageBackend().getItem(_namespacedKey(namespace, key)) !== null;
+}
+// Returns true when the key exists in the store.
+export function hasStorageItem(key) {
+    return getStorageBackend().getItem(key) !== null;
+}
+// Applies a sequence of versioned migrations to the given namespace (or global keyspace when null).
+// Migrations are run in ascending version order, starting from the stored version + 1. Stores the
+// resulting version under the reserved key `__flight_storage_version` (namespaced or global).
+// Returns the new version number, or -1 on failure.
+export function migrateStorage(namespace, migrations) {
+    const versionKey = '__flight_storage_version';
+    const raw = namespace !== null ? getNamespacedStorageItem(namespace, versionKey) : getStorageItem(versionKey);
+    const currentVersion = raw !== null ? parseInt(raw, 10) : 0;
+    const sorted = [...migrations].sort((a, b) => a.version - b.version);
+    let newVersion = currentVersion;
+    for (const migration of sorted) {
+        if (migration.version <= currentVersion)
+            continue;
+        try {
+            migration.migrate(namespace?.prefix ?? null);
+        }
+        catch {
+            return -1;
+        }
+        newVersion = migration.version;
+    }
+    if (newVersion !== currentVersion) {
+        const stored = namespace !== null
+            ? setNamespacedStorageItem(namespace, versionKey, String(newVersion))
+            : setStorageItem(versionKey, String(newVersion));
+        if (!stored)
+            return -1;
+    }
+    return newVersion;
+}
+// Removes a key from the namespace. Returns false on denial.
+export function removeNamespacedStorageItem(namespace, key) {
+    return getStorageBackend().removeItem(_namespacedKey(namespace, key));
+}
+// Removes one key. Returns false when the host denies access.
+export function removeStorageItem(key) {
+    const oldValue = _signalsActive ? getStorageBackend().getItem(key) : null;
+    const result = getStorageBackend().removeItem(key);
+    if (_signalsActive && result) {
+        _emitStorageChange({ key, oldValue, newValue: null });
+    }
+    return result;
+}
+// Removes multiple keys. Returns false if any removal fails; partial removals are possible.
+export function removeStorageItems(keys) {
+    const backend = getStorageBackend();
+    let success = true;
+    for (const key of keys) {
+        if (!backend.removeItem(key))
+            success = false;
+    }
+    return success;
+}
+// Writes a namespaced value. Returns false on denial/quota.
+export function setNamespacedStorageItem(namespace, key, value) {
+    return getStorageBackend().setItem(_namespacedKey(namespace, key), value);
+}
+// Installs a native host storage backend; pass null to fall back to the web default.
+export function setStorageBackend(backend) {
+    if (_signalsActive && _crossTabUnsubscribe !== null) {
+        _crossTabUnsubscribe();
+        _crossTabUnsubscribe = null;
+    }
+    _backend = backend;
+    if (_signalsActive) {
+        const b = getStorageBackend();
+        if (b.subscribeChanges !== undefined) {
+            _crossTabUnsubscribe = b.subscribeChanges((change) => {
+                _emitStorageChange(change);
+            });
+        }
+    }
+}
+// Writes a boolean as 'true' or 'false'. Returns false on denial/quota.
+export function setStorageBoolean(key, value) {
+    return setStorageItem(key, value ? 'true' : 'false');
+}
+// Writes a value. Returns false when the host denies access (private mode, quota exceeded).
+export function setStorageItem(key, value) {
+    const oldValue = _signalsActive ? getStorageBackend().getItem(key) : null;
+    const result = getStorageBackend().setItem(key, value);
+    if (_signalsActive && result) {
+        _emitStorageChange({ key, oldValue, newValue: value });
+    }
+    return result;
+}
+// Writes multiple key/value pairs. Returns false if any write fails; partial writes are possible.
+export function setStorageItems(record) {
+    const backend = getStorageBackend();
+    let success = true;
+    for (const key of Object.keys(record)) {
+        if (!backend.setItem(key, record[key]))
+            success = false;
+    }
+    return success;
+}
+// JSON.stringifies and stores a value. Returns false on denial/quota or if stringify fails
+// (cyclic value). Corrupt data is an expected-failure surface; do not throw.
+export function setStorageJSON(key, value) {
+    let raw;
+    try {
+        raw = JSON.stringify(value);
+    }
+    catch {
+        return false;
+    }
+    return setStorageItem(key, raw);
+}
+// Writes a number. Returns false on denial/quota.
+export function setStorageNumber(key, value) {
+    return setStorageItem(key, String(value));
+}
+let _backend = null;
+let _signals = null;
+let _signalsActive = false;
+let _crossTabUnsubscribe = null;
+function _emitStorageChange(change) {
+    if (_signals !== null)
+        emitSignal(_signals.onChange, change);
+}
+function _namespacedKey(namespace, key) {
+    return namespace.prefix + '.' + key;
+}
+function getWebStorage() {
+    if (typeof window === 'undefined')
+        return null;
+    try {
+        return window.localStorage ?? null;
+    }
+    catch {
+        return null;
+    }
+}
+//# sourceMappingURL=storage.js.map

package/dist/storage.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"storage.js","sourceRoot":"","sources":["../src/storage.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@flighthq/storage",
+  "version": "0.1.0",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src/**/*.test.ts",
+    "!dist/**/*.test.js",
+    "!dist/**/*.test.d.ts",
+    "!dist/**/*.test.js.map",
+    "!dist/**/*.test.d.ts.map"
+  ],
+  "scripts": {
+    "build": "tsc -b",
+    "clean": "tsc -b --clean",
+    "test": "vitest run --config vitest.config.ts",
+    "test:watch": "vitest --watch --config vitest.config.ts",
+    "prepack": "npm run clean && npm run clean:dist && npm run build",
+    "clean:dist": "tsx ../../scripts/clean-package-dist.ts"
+  },
+  "dependencies": {
+    "@flighthq/signals": "0.1.0",
+    "@flighthq/types": "0.1.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.3.0"
+  },
+  "description": "Synchronous key/value persistence over a swappable web/native backend (localStorage by default)",
+  "sideEffects": false
+}

package/src/storage.test.ts

@@ -0,0 +1,761 @@
+import type { StorageBackend, StorageNamespace } from '@flighthq/types';
+
+import {
+  clearStorage,
+  clearStorageNamespace,
+  createStorageNamespace,
+  createWebStorageBackend,
+  disableStorageSignals,
+  enableStorageSignals,
+  getNamespacedStorageByteSize,
+  getNamespacedStorageEntries,
+  getNamespacedStorageItem,
+  getNamespacedStorageKeys,
+  getStorageBackend,
+  getStorageBoolean,
+  getStorageBooleanOr,
+  getStorageByteSize,
+  getStorageEntries,
+  getStorageItem,
+  getStorageItemCount,
+  getStorageItemOr,
+  getStorageItems,
+  getStorageJSON,
+  getStorageJSONOr,
+  getStorageKeys,
+  getStorageNumber,
+  getStorageNumberOr,
+  getStorageQuotaEstimate,
+  getStorageSignals,
+  hasNamespacedStorageItem,
+  hasStorageItem,
+  migrateStorage,
+  removeNamespacedStorageItem,
+  removeStorageItem,
+  removeStorageItems,
+  setNamespacedStorageItem,
+  setStorageBackend,
+  setStorageBoolean,
+  setStorageItem,
+  setStorageItems,
+  setStorageJSON,
+  setStorageNumber,
+} from './storage';
+
+function fakeBackend(): StorageBackend {
+  const map = new Map<string, string>();
+  return {
+    getItem(key) {
+      return map.has(key) ? (map.get(key) as string) : null;
+    },
+    setItem(key, value) {
+      map.set(key, value);
+      return true;
+    },
+    removeItem(key) {
+      map.delete(key);
+      return true;
+    },
+    clear() {
+      map.clear();
+      return true;
+    },
+    keys() {
+      return [...map.keys()];
+    },
+  };
+}
+
+function deniedBackend(): StorageBackend {
+  return {
+    getItem() {
+      return null;
+    },
+    setItem() {
+      return false;
+    },
+    removeItem() {
+      return false;
+    },
+    clear() {
+      return false;
+    },
+    keys() {
+      return [];
+    },
+  };
+}
+
+afterEach(() => {
+  disableStorageSignals();
+  setStorageBackend(null);
+});
+
+describe('clearStorage', () => {
+  it('clears via the active backend', () => {
+    setStorageBackend(fakeBackend());
+    setStorageItem('a', '1');
+    expect(clearStorage()).toBe(true);
+    expect(getStorageKeys()).toEqual([]);
+  });
+
+  it('returns false when denied', () => {
+    setStorageBackend(deniedBackend());
+    expect(clearStorage()).toBe(false);
+  });
+});
+
+describe('clearStorageNamespace', () => {
+  it('removes only keys under the prefix', () => {
+    setStorageBackend(fakeBackend());
+    const ns = createStorageNamespace('ns');
+    setNamespacedStorageItem(ns, 'a', '1');
+    setNamespacedStorageItem(ns, 'b', '2');
+    setStorageItem('global', 'g');
+    expect(clearStorageNamespace(ns)).toBe(true);
+    expect(getNamespacedStorageKeys(ns)).toEqual([]);
+    expect(getStorageItem('global')).toBe('g');
+  });
+
+  it('drives the namespace byte-size and key-set to empty after cleanup', () => {
+    setStorageBackend(fakeBackend());
+    const ns = createStorageNamespace('ns');
+    setNamespacedStorageItem(ns, 'a', '1');
+    setNamespacedStorageItem(ns, 'b', '2');
+    expect(getNamespacedStorageByteSize(ns)).toBeGreaterThan(0);
+    expect(clearStorageNamespace(ns)).toBe(true);
+    expect(getNamespacedStorageKeys(ns)).toEqual([]);
+    expect(getNamespacedStorageByteSize(ns)).toBe(0);
+  });
+});
+
+describe('createStorageNamespace', () => {
+  it('creates a namespace with the given prefix', () => {
+    const ns = createStorageNamespace('app');
+    expect(ns.prefix).toBe('app');
+  });
+});
+
+describe('createWebStorageBackend', () => {
+  it('returns a backend whose reads yield sentinels without throwing', () => {
+    const backend = createWebStorageBackend();
+    expect(() => backend.getItem('missing')).not.toThrow();
+    expect(Array.isArray(backend.keys())).toBe(true);
+    expect(typeof backend.setItem('k', 'v')).toBe('boolean');
+  });
+});
+
+describe('disableStorageSignals', () => {
+  it('is a no-op when signals are not enabled', () => {
+    expect(() => disableStorageSignals()).not.toThrow();
+  });
+
+  it('stops emitting after disable', () => {
+    setStorageBackend(fakeBackend());
+    enableStorageSignals();
+    disableStorageSignals();
+    expect(getStorageSignals()).toBeNull();
+    // write should not throw after disable
+    setStorageItem('x', 'y');
+  });
+});
+
+describe('enableStorageSignals', () => {
+  it('returns a StorageSignals object', () => {
+    const sigs = enableStorageSignals();
+    expect(sigs).not.toBeNull();
+    expect(sigs.onChange).toBeDefined();
+  });
+
+  it('is idempotent — returns the same object', () => {
+    const a = enableStorageSignals();
+    const b = enableStorageSignals();
+    expect(a).toBe(b);
+  });
+
+  it('emits onChange when setStorageItem is called', () => {
+    setStorageBackend(fakeBackend());
+    const sigs = enableStorageSignals();
+    const changes: Array<{ key: string | null; oldValue: string | null; newValue: string | null }> = [];
+    sigs.onChange.emit = (change) => changes.push({ ...change });
+    setStorageItem('hello', 'world');
+    expect(changes).toHaveLength(1);
+    expect(changes[0].key).toBe('hello');
+    expect(changes[0].newValue).toBe('world');
+  });
+
+  it('emits onChange when clearStorage is called', () => {
+    setStorageBackend(fakeBackend());
+    const sigs = enableStorageSignals();
+    const changes: Array<{ key: string | null }> = [];
+    sigs.onChange.emit = (change) => changes.push({ key: change.key });
+    clearStorage();
+    expect(changes).toHaveLength(1);
+    expect(changes[0].key).toBeNull();
+  });
+
+  it('emits onChange when removeStorageItem is called', () => {
+    setStorageBackend(fakeBackend());
+    setStorageItem('a', '1');
+    const sigs = enableStorageSignals();
+    const changes: Array<{ key: string | null; newValue: string | null }> = [];
+    sigs.onChange.emit = (change) => changes.push({ key: change.key, newValue: change.newValue });
+    removeStorageItem('a');
+    expect(changes).toHaveLength(1);
+    expect(changes[0].key).toBe('a');
+    expect(changes[0].newValue).toBeNull();
+  });
+});
+
+describe('getNamespacedStorageByteSize', () => {
+  it('counts only namespaced keys', () => {
+    setStorageBackend(fakeBackend());
+    const ns = createStorageNamespace('ns');
+    setNamespacedStorageItem(ns, 'x', 'y');
+    setStorageItem('global', 'g');
+    const size = getNamespacedStorageByteSize(ns);
+    expect(size).toBeGreaterThan(0);
+  });
+
+  it('returns 0 for empty namespace', () => {
+    setStorageBackend(fakeBackend());
+    const ns = createStorageNamespace('empty');
+    expect(getNamespacedStorageByteSize(ns)).toBe(0);
+  });
+});
+
+describe('getNamespacedStorageEntries', () => {
+  it('returns unprefixed key/value pairs', () => {
+    setStorageBackend(fakeBackend());
+    const ns = createStorageNamespace('ns');
+    setNamespacedStorageItem(ns, 'a', '1');
+    setNamespacedStorageItem(ns, 'b', '2');
+    setStorageItem('ns.x', 'outside'); // Actually prefix-matching — valid entry
+    const entries = getNamespacedStorageEntries(ns);
+    const keys = entries.map((e) => e[0]).sort();
+    expect(keys).toContain('a');
+    expect(keys).toContain('b');
+  });
+
+  it('does not include global keys', () => {
+    setStorageBackend(fakeBackend());
+    const ns = createStorageNamespace('app');
+    setStorageItem('global', 'g');
+    setNamespacedStorageItem(ns, 'local', 'v');
+    const entries = getNamespacedStorageEntries(ns);
+    expect(entries.every((e) => e[0] !== 'global')).toBe(true);
+  });
+});
+
+describe('getNamespacedStorageItem', () => {
+  it('returns null when absent', () => {
+    setStorageBackend(fakeBackend());
+    const ns = createStorageNamespace('ns');
+    expect(getNamespacedStorageItem(ns, 'missing')).toBeNull();
+  });
+
+  it('round-trips through the backend', () => {
+    setStorageBackend(fakeBackend());
+    const ns = createStorageNamespace('ns');
+    setNamespacedStorageItem(ns, 'key', 'val');
+    expect(getNamespacedStorageItem(ns, 'key')).toBe('val');
+  });
+});
+
+describe('getNamespacedStorageKeys', () => {
+  it('returns unprefixed keys', () => {
+    setStorageBackend(fakeBackend());
+    const ns = createStorageNamespace('app');
+    setNamespacedStorageItem(ns, 'x', '1');
+    setNamespacedStorageItem(ns, 'y', '2');
+    setStorageItem('global', 'g');
+    const keys = getNamespacedStorageKeys(ns).sort();
+    expect(keys).toEqual(['x', 'y']);
+  });
+});
+
+describe('getStorageBackend', () => {
+  it('falls back to a web backend', () => {
+    expect(getStorageBackend()).not.toBeNull();
+  });
+
+  it('returns the registered backend', () => {
+    const backend = fakeBackend();
+    setStorageBackend(backend);
+    expect(getStorageBackend()).toBe(backend);
+  });
+});
+
+describe('getStorageBoolean', () => {
+  it('returns true for stored "true"', () => {
+    setStorageBackend(fakeBackend());
+    setStorageItem('flag', 'true');
+    expect(getStorageBoolean('flag')).toBe(true);
+  });
+
+  it('returns false for stored "false"', () => {
+    setStorageBackend(fakeBackend());
+    setStorageItem('flag', 'false');
+    expect(getStorageBoolean('flag')).toBe(false);
+  });
+
+  it('returns null for absent key', () => {
+    setStorageBackend(fakeBackend());
+    expect(getStorageBoolean('missing')).toBeNull();
+  });
+
+  it('returns null for unrecognized value', () => {
+    setStorageBackend(fakeBackend());
+    setStorageItem('flag', '1');
+    expect(getStorageBoolean('flag')).toBeNull();
+  });
+});
+
+describe('getStorageBooleanOr', () => {
+  it('returns fallback on absent key', () => {
+    setStorageBackend(fakeBackend());
+    expect(getStorageBooleanOr('missing', true)).toBe(true);
+  });
+
+  it('returns stored value when present', () => {
+    setStorageBackend(fakeBackend());
+    setStorageItem('flag', 'false');
+    expect(getStorageBooleanOr('flag', true)).toBe(false);
+  });
+});
+
+describe('getStorageByteSize', () => {
+  it('returns 0 for an empty store', () => {
+    setStorageBackend(fakeBackend());
+    expect(getStorageByteSize()).toBe(0);
+  });
+
+  it('returns a positive size after writing', () => {
+    setStorageBackend(fakeBackend());
+    setStorageItem('key', 'value');
+    expect(getStorageByteSize()).toBeGreaterThan(0);
+  });
+
+  it('delegates to backend.byteSize when present', () => {
+    const backend = fakeBackend();
+    backend.byteSize = () => 42;
+    setStorageBackend(backend);
+    expect(getStorageByteSize()).toBe(42);
+  });
+});
+
+describe('getStorageEntries', () => {
+  it('returns all key/value pairs', () => {
+    setStorageBackend(fakeBackend());
+    setStorageItem('a', '1');
+    setStorageItem('b', '2');
+    const entries = getStorageEntries();
+    const sorted = [...entries].sort((a, b) => a[0].localeCompare(b[0]));
+    expect(sorted).toEqual([
+      ['a', '1'],
+      ['b', '2'],
+    ]);
+  });
+
+  it('returns [] for a denied backend', () => {
+    setStorageBackend(deniedBackend());
+    expect(getStorageEntries()).toEqual([]);
+  });
+
+  it('returns [] for an empty store', () => {
+    setStorageBackend(fakeBackend());
+    expect(getStorageEntries()).toEqual([]);
+  });
+});
+
+describe('getStorageItem', () => {
+  it('returns null for an absent key', () => {
+    setStorageBackend(fakeBackend());
+    expect(getStorageItem('missing')).toBeNull();
+  });
+
+  it('round-trips through the backend', () => {
+    setStorageBackend(fakeBackend());
+    setStorageItem('greeting', 'hi');
+    expect(getStorageItem('greeting')).toBe('hi');
+  });
+});
+
+describe('getStorageItemCount', () => {
+  it('returns 0 for an empty store', () => {
+    setStorageBackend(fakeBackend());
+    expect(getStorageItemCount()).toBe(0);
+  });
+
+  it('counts stored keys', () => {
+    setStorageBackend(fakeBackend());
+    setStorageItem('a', '1');
+    setStorageItem('b', '2');
+    expect(getStorageItemCount()).toBe(2);
+  });
+
+  it('returns 0 when denied', () => {
+    setStorageBackend(deniedBackend());
+    expect(getStorageItemCount()).toBe(0);
+  });
+});
+
+describe('getStorageItemOr', () => {
+  it('returns the stored value', () => {
+    setStorageBackend(fakeBackend());
+    setStorageItem('k', 'v');
+    expect(getStorageItemOr('k', 'default')).toBe('v');
+  });
+
+  it('returns the fallback on absent key', () => {
+    setStorageBackend(fakeBackend());
+    expect(getStorageItemOr('missing', 'fallback')).toBe('fallback');
+  });
+});
+
+describe('getStorageItems', () => {
+  it('returns parallel-indexed values', () => {
+    setStorageBackend(fakeBackend());
+    setStorageItem('a', '1');
+    setStorageItem('b', '2');
+    const results = getStorageItems(['a', 'missing', 'b']);
+    expect(results).toEqual(['1', null, '2']);
+  });
+
+  it('returns [] for empty keys array', () => {
+    setStorageBackend(fakeBackend());
+    expect(getStorageItems([])).toEqual([]);
+  });
+});
+
+describe('getStorageJSON', () => {
+  it('parses a valid JSON string', () => {
+    setStorageBackend(fakeBackend());
+    setStorageItem('obj', '{"x":1}');
+    expect(getStorageJSON<{ x: number }>('obj')).toEqual({ x: 1 });
+  });
+
+  it('returns null on absent key', () => {
+    setStorageBackend(fakeBackend());
+    expect(getStorageJSON('missing')).toBeNull();
+  });
+
+  it('returns null on corrupt stored data (parse failure)', () => {
+    setStorageBackend(fakeBackend());
+    setStorageItem('bad', 'not-json{');
+    expect(getStorageJSON('bad')).toBeNull();
+  });
+
+  it('round-trips through setStorageJSON', () => {
+    setStorageBackend(fakeBackend());
+    setStorageJSON('data', { hello: 'world' });
+    expect(getStorageJSON<{ hello: string }>('data')).toEqual({ hello: 'world' });
+  });
+});
+
+describe('getStorageJSONOr', () => {
+  it('returns fallback on absent key', () => {
+    setStorageBackend(fakeBackend());
+    expect(getStorageJSONOr('missing', 42)).toBe(42);
+  });
+
+  it('returns fallback on parse failure', () => {
+    setStorageBackend(fakeBackend());
+    setStorageItem('bad', '{corrupt');
+    expect(getStorageJSONOr('bad', 'default')).toBe('default');
+  });
+
+  it('returns the parsed value when present', () => {
+    setStorageBackend(fakeBackend());
+    setStorageJSON('n', 99);
+    expect(getStorageJSONOr('n', 0)).toBe(99);
+  });
+});
+
+describe('getStorageKeys', () => {
+  it('lists stored keys', () => {
+    setStorageBackend(fakeBackend());
+    setStorageItem('a', '1');
+    setStorageItem('b', '2');
+    expect(getStorageKeys().sort()).toEqual(['a', 'b']);
+  });
+});
+
+describe('getStorageNumber', () => {
+  it('returns a stored number', () => {
+    setStorageBackend(fakeBackend());
+    setStorageItem('n', '42');
+    expect(getStorageNumber('n')).toBe(42);
+  });
+
+  it('returns null for absent key', () => {
+    setStorageBackend(fakeBackend());
+    expect(getStorageNumber('missing')).toBeNull();
+  });
+
+  it('returns null for non-numeric value', () => {
+    setStorageBackend(fakeBackend());
+    setStorageItem('bad', 'nope');
+    expect(getStorageNumber('bad')).toBeNull();
+  });
+});
+
+describe('getStorageNumberOr', () => {
+  it('returns fallback on absent key', () => {
+    setStorageBackend(fakeBackend());
+    expect(getStorageNumberOr('missing', -1)).toBe(-1);
+  });
+
+  it('returns stored value when present', () => {
+    setStorageBackend(fakeBackend());
+    setStorageItem('n', '7');
+    expect(getStorageNumberOr('n', 0)).toBe(7);
+  });
+});
+
+describe('getStorageQuotaEstimate', () => {
+  it('returns null when navigator.storage is absent', async () => {
+    const result = await getStorageQuotaEstimate();
+    // In jsdom, navigator.storage.estimate may or may not be available — just assert no throw.
+    expect(result === null || typeof result === 'object').toBe(true);
+  });
+});
+
+describe('getStorageSignals', () => {
+  it('returns null before enableStorageSignals', () => {
+    expect(getStorageSignals()).toBeNull();
+  });
+
+  it('returns the signals after enableStorageSignals', () => {
+    const sigs = enableStorageSignals();
+    expect(getStorageSignals()).toBe(sigs);
+  });
+});
+
+describe('hasNamespacedStorageItem', () => {
+  it('returns false when absent', () => {
+    setStorageBackend(fakeBackend());
+    const ns = createStorageNamespace('ns');
+    expect(hasNamespacedStorageItem(ns, 'missing')).toBe(false);
+  });
+
+  it('returns true when present', () => {
+    setStorageBackend(fakeBackend());
+    const ns = createStorageNamespace('ns');
+    setNamespacedStorageItem(ns, 'key', 'val');
+    expect(hasNamespacedStorageItem(ns, 'key')).toBe(true);
+  });
+});
+
+describe('hasStorageItem', () => {
+  it('returns false for absent key', () => {
+    setStorageBackend(fakeBackend());
+    expect(hasStorageItem('missing')).toBe(false);
+  });
+
+  it('returns true for a stored key', () => {
+    setStorageBackend(fakeBackend());
+    setStorageItem('present', 'value');
+    expect(hasStorageItem('present')).toBe(true);
+  });
+
+  it('returns false when denied', () => {
+    setStorageBackend(deniedBackend());
+    expect(hasStorageItem('any')).toBe(false);
+  });
+});
+
+describe('migrateStorage', () => {
+  it('runs migrations in version order', () => {
+    setStorageBackend(fakeBackend());
+    const calls: number[] = [];
+    const migrations = [
+      {
+        version: 2,
+        migrate: () => {
+          calls.push(2);
+        },
+      },
+      {
+        version: 1,
+        migrate: () => {
+          calls.push(1);
+        },
+      },
+    ];
+    const result = migrateStorage(null, migrations);
+    expect(result).toBe(2);
+    expect(calls).toEqual([1, 2]);
+  });
+
+  it('skips migrations at or below current version', () => {
+    setStorageBackend(fakeBackend());
+    setStorageItem('__flight_storage_version', '2');
+    const calls: number[] = [];
+    const migrations = [
+      {
+        version: 1,
+        migrate: () => {
+          calls.push(1);
+        },
+      },
+      {
+        version: 2,
+        migrate: () => {
+          calls.push(2);
+        },
+      },
+      {
+        version: 3,
+        migrate: () => {
+          calls.push(3);
+        },
+      },
+    ];
+    const result = migrateStorage(null, migrations);
+    expect(result).toBe(3);
+    expect(calls).toEqual([3]);
+  });
+
+  it('works with a namespace', () => {
+    setStorageBackend(fakeBackend());
+    const ns = createStorageNamespace('app');
+    const calls: number[] = [];
+    const migrations = [
+      {
+        version: 1,
+        migrate: () => {
+          calls.push(1);
+        },
+      },
+    ];
+    const result = migrateStorage(ns, migrations);
+    expect(result).toBe(1);
+    expect(calls).toEqual([1]);
+    expect(getNamespacedStorageItem(ns, '__flight_storage_version')).toBe('1');
+  });
+
+  it('returns -1 when a migration throws', () => {
+    setStorageBackend(fakeBackend());
+    const migrations = [
+      {
+        version: 1,
+        migrate: () => {
+          throw new Error('fail');
+        },
+      },
+    ];
+    expect(migrateStorage(null, migrations)).toBe(-1);
+  });
+});
+
+describe('removeNamespacedStorageItem', () => {
+  it('removes a namespaced key', () => {
+    setStorageBackend(fakeBackend());
+    const ns = createStorageNamespace('ns');
+    setNamespacedStorageItem(ns, 'key', 'val');
+    expect(removeNamespacedStorageItem(ns, 'key')).toBe(true);
+    expect(getNamespacedStorageItem(ns, 'key')).toBeNull();
+  });
+});
+
+describe('removeStorageItem', () => {
+  it('removes via the active backend', () => {
+    setStorageBackend(fakeBackend());
+    setStorageItem('a', '1');
+    expect(removeStorageItem('a')).toBe(true);
+    expect(getStorageItem('a')).toBeNull();
+  });
+});
+
+describe('removeStorageItems', () => {
+  it('removes multiple keys', () => {
+    setStorageBackend(fakeBackend());
+    setStorageItem('a', '1');
+    setStorageItem('b', '2');
+    expect(removeStorageItems(['a', 'b'])).toBe(true);
+    expect(getStorageItem('a')).toBeNull();
+    expect(getStorageItem('b')).toBeNull();
+  });
+
+  it('returns false when any removal fails', () => {
+    setStorageBackend(deniedBackend());
+    expect(removeStorageItems(['x'])).toBe(false);
+  });
+});
+
+describe('setNamespacedStorageItem', () => {
+  it('stores under the prefixed key', () => {
+    setStorageBackend(fakeBackend());
+    const ns = createStorageNamespace('app');
+    setNamespacedStorageItem(ns, 'setting', '42');
+    expect(getStorageItem('app.setting')).toBe('42');
+  });
+});
+
+describe('setStorageBackend', () => {
+  it('clears back to the web fallback when passed null', () => {
+    setStorageBackend(fakeBackend());
+    setStorageBackend(null);
+    expect(getStorageBackend()).not.toBeNull();
+  });
+});
+
+describe('setStorageBoolean', () => {
+  it('writes "true" for true', () => {
+    setStorageBackend(fakeBackend());
+    setStorageBoolean('flag', true);
+    expect(getStorageItem('flag')).toBe('true');
+  });
+
+  it('writes "false" for false', () => {
+    setStorageBackend(fakeBackend());
+    setStorageBoolean('flag', false);
+    expect(getStorageItem('flag')).toBe('false');
+  });
+});
+
+describe('setStorageItem', () => {
+  it('writes via the active backend', () => {
+    setStorageBackend(fakeBackend());
+    expect(setStorageItem('x', 'y')).toBe(true);
+    expect(getStorageItem('x')).toBe('y');
+  });
+});
+
+describe('setStorageItems', () => {
+  it('writes all key/value pairs', () => {
+    setStorageBackend(fakeBackend());
+    expect(setStorageItems({ a: '1', b: '2' })).toBe(true);
+    expect(getStorageItem('a')).toBe('1');
+    expect(getStorageItem('b')).toBe('2');
+  });
+
+  it('returns false when any write fails', () => {
+    setStorageBackend(deniedBackend());
+    expect(setStorageItems({ a: '1' })).toBe(false);
+  });
+});
+
+describe('setStorageJSON', () => {
+  it('stores a stringified value', () => {
+    setStorageBackend(fakeBackend());
+    expect(setStorageJSON('obj', { n: 1 })).toBe(true);
+    expect(getStorageItem('obj')).toBe('{"n":1}');
+  });
+
+  it('returns false for cyclic values', () => {
+    setStorageBackend(fakeBackend());
+    const cyclic: Record<string, unknown> = {};
+    cyclic.self = cyclic;
+    expect(setStorageJSON('bad', cyclic)).toBe(false);
+  });
+});
+
+describe('setStorageNumber', () => {
+  it('stores the number as a string', () => {
+    setStorageBackend(fakeBackend());
+    setStorageNumber('n', 3.14);
+    expect(getStorageItem('n')).toBe('3.14');
+  });
+});