react-native-nitro-storage 0.10.3 → 0.11.0

package/src/index.ts

@@ -4,6 +4,7 @@ import {
   DEFAULT_SECURE_WRITES_ASYNC,
   resolveNativeWriteBuffering,
 } from "./capabilities";
+import { createIndexedDBBackend as createIndexedDBBackendFromSubpath } from "./indexeddb-backend";
 import { unescapeCollidingRawValue } from "./internal";
 import {
   assertAccessControlLevel,
@@ -86,6 +87,11 @@ export type {
   StorageKeyRef,
   TransactionContext,
 } from "./storage-core";
+export {
+  describeWebBackendCapabilities,
+  isIndexedDBWebBackend,
+  type WebBackendCapabilities,
+} from "./web-backend-contract";
 export type { PlatformScope, PlatformStorage } from "./storage-platform";
 
 let _storageModule: Storage | null = null;
@@ -200,6 +206,10 @@ function buildNativeAdapter(
         return;
       }
 
+      if (consumeSuppressedNativeEvent(scope, key)) {
+        notifyKeyListeners(internals.getScopedListeners(scope), key);
+        return;
+      }
       const oldValue =
         scope === StorageScope.Secure
           ? undefined
@@ -210,9 +220,6 @@ function buildNativeAdapter(
         internals.cacheRawValue(scope, key, value);
       }
       notifyKeyListeners(internals.getScopedListeners(scope), key);
-      if (consumeSuppressedNativeEvent(scope, key)) {
-        return;
-      }
       internals.emitKeyChange(
         scope,
         key,
@@ -315,7 +322,7 @@ export const storage = {
   getCapabilities: (): StorageCapabilities => ({
     platform: "native",
     backend: {
-      disk: "platform-preferences",
+      disk: "sqlite",
       secure: nativeSecureBackend,
     },
     writeBuffering: resolveNativeWriteBuffering(
@@ -392,4 +399,11 @@ export {
   useStorageSelector,
   useStorageValue,
 } from "./storage-hooks";
-export { createIndexedDBBackend } from "./indexeddb-backend";
+
+/**
+ * @deprecated Import `createIndexedDBBackend` from
+ * `react-native-nitro-storage/indexeddb-backend` instead. The root export
+ * will be removed in a future minor release.
+ */
+export const createIndexedDBBackend: typeof createIndexedDBBackendFromSubpath =
+  createIndexedDBBackendFromSubpath;

package/src/index.web.ts

@@ -1,4 +1,5 @@
 import { resolveWebWriteBuffering } from "./capabilities";
+import { createIndexedDBBackend as createIndexedDBBackendFromSubpath } from "./indexeddb-backend";
 import { unescapeCollidingRawValue } from "./internal";
 import {
   assertAccessControlLevel,
@@ -111,20 +112,26 @@ function getInternals(): StorageCoreInternals {
   return internals;
 }
 
+const DEFAULT_DISK_BACKEND_NAME = "localStorage:disk";
+const DEFAULT_SECURE_BACKEND_NAME = "localStorage:secure";
+
+function isSecureWebStorageKey(key: string): boolean {
+  return (
+    key.startsWith(SECURE_WEB_PREFIX) || key.startsWith(BIOMETRIC_WEB_PREFIX)
+  );
+}
+
 function createDefaultDiskBackend(): WebDiskStorageBackend {
   return createLocalStorageWebBackend({
-    name: "localStorage:disk",
-    includeKey: (key) =>
-      !key.startsWith(SECURE_WEB_PREFIX) &&
-      !key.startsWith(BIOMETRIC_WEB_PREFIX),
+    name: DEFAULT_DISK_BACKEND_NAME,
+    includeKey: (key) => !isSecureWebStorageKey(key),
   });
 }
 
 function createDefaultSecureBackend(): WebSecureStorageBackend {
   return createLocalStorageWebBackend({
-    name: "localStorage:secure",
-    includeKey: (key) =>
-      key.startsWith(SECURE_WEB_PREFIX) || key.startsWith(BIOMETRIC_WEB_PREFIX),
+    name: DEFAULT_SECURE_BACKEND_NAME,
+    includeKey: isSecureWebStorageKey,
   });
 }
 
@@ -227,7 +234,9 @@ function replaceWebScopeKeyIndex(
   keyIndex.clear();
   for (const key of keys) {
     if (scope === StorageScope.Disk) {
-      keyIndex.add(key);
+      if (!isSecureWebStorageKey(key)) {
+        keyIndex.add(key);
+      }
       continue;
     }
 
@@ -432,23 +441,41 @@ function applyExternalChangeEvent(
   );
 }
 
+function usesDefaultLocalStorageBackend(scope: NonMemoryScope): boolean {
+  return (
+    getWebBackend(scope)?.name ===
+    (scope === StorageScope.Disk
+      ? DEFAULT_DISK_BACKEND_NAME
+      : DEFAULT_SECURE_BACKEND_NAME)
+  );
+}
+
 function handleWebStorageEvent(event: StorageEvent): void {
+  if (
+    typeof globalThis.localStorage === "undefined" ||
+    event.storageArea !== globalThis.localStorage
+  ) {
+    return;
+  }
+
   const key = event.key;
   if (key === null) {
-    applyExternalChangeEvent(StorageScope.Disk, null, null);
-    applyExternalChangeEvent(StorageScope.Secure, null, null);
+    if (usesDefaultLocalStorageBackend(StorageScope.Disk)) {
+      applyExternalChangeEvent(StorageScope.Disk, null, null);
+    }
+    if (usesDefaultLocalStorageBackend(StorageScope.Secure)) {
+      applyExternalChangeEvent(StorageScope.Secure, null, null);
+    }
     return;
   }
 
-  if (
-    key.startsWith(SECURE_WEB_PREFIX) ||
-    key.startsWith(BIOMETRIC_WEB_PREFIX)
-  ) {
-    applyExternalChangeEvent(StorageScope.Secure, key, event.newValue);
+  const scope = isSecureWebStorageKey(key)
+    ? StorageScope.Secure
+    : StorageScope.Disk;
+  if (!usesDefaultLocalStorageBackend(scope)) {
     return;
   }
-
-  applyExternalChangeEvent(StorageScope.Disk, key, event.newValue);
+  applyExternalChangeEvent(scope, key, event.newValue);
 }
 
 function subscribeToBackendChanges(scope: NonMemoryScope): void {
@@ -462,6 +489,22 @@ function subscribeToBackendChanges(scope: NonMemoryScope): void {
   }
 
   const unsubscribe = backend.subscribe((event: WebStorageChangeEvent) => {
+    if (webDiskStorageBackend !== webSecureStorageBackend) {
+      applyExternalChangeEvent(scope, event.key, event.newValue);
+      return;
+    }
+    if (event.key === null) {
+      getInternals().clearScopeRawCache(scope);
+      reconcileWebScopeKeyIndex(scope);
+      notifyAllListeners(getInternals().getScopedListeners(scope));
+      return;
+    }
+    const eventScope = isSecureWebStorageKey(event.key)
+      ? StorageScope.Secure
+      : StorageScope.Disk;
+    if (eventScope !== scope) {
+      return;
+    }
     applyExternalChangeEvent(scope, event.key, event.newValue);
   });
   externalSyncUnsubscribers.set(scope, unsubscribe);
@@ -581,7 +624,24 @@ const WebStorage: Storage = {
     }
     try {
       withWebBackendOperation(scope, "clear", (backend) => {
-        backend.clear();
+        if (webDiskStorageBackend !== webSecureStorageBackend) {
+          backend.clear();
+          return;
+        }
+        const ownedKeys = backend
+          .getAllKeys()
+          .filter((key) =>
+            scope === StorageScope.Secure
+              ? isSecureWebStorageKey(key)
+              : !isSecureWebStorageKey(key),
+          );
+        if (backend.removeMany) {
+          backend.removeMany(ownedKeys);
+          return;
+        }
+        ownedKeys.forEach((key) => {
+          backend.removeItem(key);
+        });
       });
     } catch (error) {
       throwAfterWebMutationFailure(scope, "clear", error);
@@ -1135,4 +1195,11 @@ export {
   useStorageSelector,
   useStorageValue,
 } from "./storage-hooks";
-export { createIndexedDBBackend } from "./indexeddb-backend";
+
+/**
+ * @deprecated Import `createIndexedDBBackend` from
+ * `react-native-nitro-storage/indexeddb-backend` instead. The root export
+ * will be removed in a future minor release.
+ */
+export const createIndexedDBBackend: typeof createIndexedDBBackendFromSubpath =
+  createIndexedDBBackendFromSubpath;

package/src/indexeddb-backend.ts

@@ -111,42 +111,24 @@ export async function createIndexedDBBackend(
     options.onError?.(normalized);
   }
 
-  function handleLifecycleFlush(): void {
-    if (closed || pendingWrites.size === 0) {
-      return;
-    }
-    void Promise.all(Array.from(pendingWrites)).catch(() => {
-      // Errors are surfaced through flush() and onError; the page may be
-      // hidden, so the flush result is intentionally not awaited here.
-    });
-  }
+  let hydrated = false;
+  const queuedChannelEvents: WebStorageChangeEvent[] = [];
 
-  function installLifecycleFlush(): () => void {
-    if (typeof globalThis === "undefined" || !globalThis.addEventListener) {
-      return () => {};
+  function applyChannelEvent(data: WebStorageChangeEvent): void {
+    if (data.key === null) {
+      cache.clear();
+    } else if (data.newValue === null) {
+      cache.delete(data.key);
+    } else {
+      cache.set(data.key, data.newValue);
     }
 
-    const onPageHide = () => {
-      handleLifecycleFlush();
-    };
-    const onVisibilityChange = () => {
-      if (
-        typeof document !== "undefined" &&
-        document.visibilityState === "hidden"
-      ) {
-        handleLifecycleFlush();
-      }
-    };
-    globalThis.addEventListener("pagehide", onPageHide);
-    globalThis.addEventListener("visibilitychange", onVisibilityChange);
-    return () => {
-      globalThis.removeEventListener("pagehide", onPageHide);
-      globalThis.removeEventListener("visibilitychange", onVisibilityChange);
-    };
+    emitExternal({
+      key: data.key,
+      newValue: data.newValue,
+    });
   }
 
-  const removeLifecycleFlush = installLifecycleFlush();
-
   channel?.addEventListener("message", (event: MessageEvent) => {
     if (closed) {
       return;
@@ -158,18 +140,12 @@ export async function createIndexedDBBackend(
       return;
     }
 
-    if (data.key === null) {
-      cache.clear();
-    } else if (data.newValue === null) {
-      cache.delete(data.key);
-    } else {
-      cache.set(data.key, data.newValue);
+    if (!hydrated) {
+      queuedChannelEvents.push({ key: data.key, newValue: data.newValue });
+      return;
     }
 
-    emitExternal({
-      key: data.key,
-      newValue: data.newValue,
-    });
+    applyChannelEvent(data);
   });
 
   function publish(event: WebStorageChangeEvent): void {
@@ -204,6 +180,9 @@ export async function createIndexedDBBackend(
     };
   });
 
+  hydrated = true;
+  queuedChannelEvents.splice(0).forEach(applyChannelEvent);
+
   function trackWrite(tx: IDBTransaction, keys: string[] | null): void {
     const pending = new Promise<void>((resolve) => {
       tx.oncomplete = () => {
@@ -381,7 +360,6 @@ export async function createIndexedDBBackend(
         return;
       }
       closed = true;
-      removeLifecycleFlush();
       subscribers.clear();
       channel?.close();
       db.close();

package/src/internal.ts

@@ -72,6 +72,14 @@ export function assertValidScope(scope: StorageScope): void {
   }
 }
 
+export function assertValidStorageKey(key: string): void {
+  if (typeof key !== "string" || key.length === 0) {
+    throw new Error(
+      "[nitro-error:invalid_key] NitroStorage: storage keys must be non-empty strings.",
+    );
+  }
+}
+
 export type ScopedBatchItem = {
   key: string;
   scope: StorageScope;

package/src/storage-core.ts

@@ -7,6 +7,7 @@ import {
   assertBatchScope,
   assertValidScope,
   toVersionToken,
+  assertValidStorageKey,
   prefixKey,
   isNamespaced,
   escapeCollidingRawValue,
@@ -57,7 +58,7 @@ import {
   type StorageKeyChangeEvent,
 } from "./storage-events";
 import type { StorageSetter } from "./storage-hooks";
-import type { SecureStorageMetadata } from "./storage-runtime";
+import { isStorageError, type SecureStorageMetadata } from "./storage-runtime";
 import { StorageScope, AccessControl, BiometricLevel } from "./Storage.types";
 
 export type TransactionContext = {
@@ -342,6 +343,20 @@ export function createStorageCore(
   let eventObserverRedactSecureValues = true;
   const storageEvents = new StorageEventRegistry();
   const metrics = createMetricsRegistry();
+
+  function setOwnDataProperty(
+    target: object,
+    key: string,
+    value: unknown,
+  ): void {
+    Object.defineProperty(target, key, {
+      configurable: true,
+      enumerable: true,
+      value,
+      writable: true,
+    });
+  }
+
   const durability = createDurabilityCoordinator({
     backend: {
       setBatch: (keys, values, scope) => {
@@ -493,6 +508,26 @@ export function createStorageCore(
     return scope !== StorageScope.Secure || !eventObserverRedactSecureValues;
   }
 
+  function readPreviousEventValue(
+    scope: StorageScope,
+    key: string,
+    representation: StorageRawCacheRepresentation = "plain",
+  ): string | undefined {
+    if (!shouldReadPreviousEventValues(scope)) {
+      return undefined;
+    }
+    return getEventRawValueForRepresentation(scope, key, representation);
+  }
+
+  function toMemoryStoredValue(value: unknown): unknown {
+    return typeof value === "string" ? escapeCollidingRawValue(value) : value;
+  }
+
+  function deleteMemoryKey(key: string): void {
+    memoryStore.delete(key);
+    memoryExpirationDeadlines.delete(key);
+  }
+
   function eventForGlobalObserver(
     event: StorageChangeEvent,
   ): StorageChangeEvent {
@@ -693,6 +728,7 @@ export function createStorageCore(
 
   function setRawValue(key: string, value: string, scope: StorageScope): void {
     assertValidScope(scope);
+    assertValidStorageKey(key);
     const storedValue = escapeCollidingRawValue(value);
     const oldValue =
       scope === StorageScope.Memory ? getEventRawValue(scope, key) : undefined;
@@ -731,9 +767,10 @@ export function createStorageCore(
 
   function removeRawValue(key: string, scope: StorageScope): void {
     assertValidScope(scope);
-    const oldValue = getEventRawValue(scope, key);
+    assertValidStorageKey(key);
+    const oldValue = readPreviousEventValue(scope, key);
     if (scope === StorageScope.Memory) {
-      memoryStore.delete(key);
+      deleteMemoryKey(key);
       notifyKeyListeners(memoryListeners, key);
       emitKeyChange(scope, key, oldValue, undefined, "remove", "memory");
       return;
@@ -837,7 +874,7 @@ export function createStorageCore(
         const previousValues = shouldReadPreviousEventValues(scope)
           ? removeKeys.map((key) => getEventRawValue(scope, key))
           : [];
-        removeKeys.forEach((key) => memoryStore.delete(key));
+        removeKeys.forEach(deleteMemoryKey);
         removeKeys.forEach((key) => {
           notifyKeyListeners(memoryListeners, key);
         });
@@ -1290,9 +1327,11 @@ export function createStorageCore(
       return measureOperation("storage:getKeysByPrefix", scope, () => {
         assertValidScope(scope);
         if (scope === StorageScope.Memory) {
-          return Array.from(memoryStore.keys()).filter((key) =>
-            key.startsWith(prefix),
-          );
+          const keys: string[] = [];
+          for (const key of memoryStore.keys()) {
+            if (key.startsWith(prefix)) keys.push(key);
+          }
+          return keys;
         }
         if (scope === StorageScope.Disk) {
           flushDiskWrites();
@@ -1318,7 +1357,7 @@ export function createStorageCore(
           keys.forEach((key) => {
             const value = memoryStore.get(key);
             if (typeof value === "string") {
-              result[key] = value;
+              setOwnDataProperty(result, key, unescapeCollidingRawValue(value));
             }
           });
           return result;
@@ -1334,7 +1373,7 @@ export function createStorageCore(
         keys.forEach((key, idx) => {
           const value = values[idx];
           if (value !== undefined) {
-            result[key] = unescapeCollidingRawValue(value);
+            setOwnDataProperty(result, key, unescapeCollidingRawValue(value));
           }
         });
         return result;
@@ -1345,11 +1384,11 @@ export function createStorageCore(
         assertValidScope(scope);
         const result: Record<string, string> = {};
         if (scope === StorageScope.Memory) {
-          for (const key of memoryStore.keys()) {
-            const value = memoryStore.get(key);
-            if (typeof value === "string")
-              result[key] = unescapeCollidingRawValue(value);
-          }
+          memoryStore.forEach((value, key) => {
+            if (typeof value === "string") {
+              setOwnDataProperty(result, key, unescapeCollidingRawValue(value));
+            }
+          });
           return result;
         }
         if (scope === StorageScope.Disk) {
@@ -1363,7 +1402,9 @@ export function createStorageCore(
         const values = adapter.backend.getBatch(keys, scope);
         keys.forEach((key, idx) => {
           const val = values[idx];
-          if (val !== undefined) result[key] = unescapeCollidingRawValue(val);
+          if (val !== undefined) {
+            setOwnDataProperty(result, key, unescapeCollidingRawValue(val));
+          }
         });
         return result;
       });
@@ -1503,14 +1544,18 @@ export function createStorageCore(
         scope,
         () => {
           assertValidScope(scope);
+          keys.forEach(assertValidStorageKey);
           if (keys.length === 0) return;
           const values = keys.map((k) => data[k] as string);
           const storedValues = values.map(escapeCollidingRawValue);
+          const readPrevious =
+            scope === StorageScope.Memory ||
+            shouldReadPreviousEventValues(scope);
           const changes = keys.map((key, index) =>
             createKeyChange(
               scope,
               key,
-              getEventRawValue(scope, key),
+              readPrevious ? getEventRawValue(scope, key) : undefined,
               values[index],
               "import",
               scope === StorageScope.Memory ? "memory" : adapter.changeSource,
@@ -1553,6 +1598,7 @@ export function createStorageCore(
   function createStorageItem<T = undefined>(
     config: StorageItemConfig<T>,
   ): StorageItem<T> {
+    assertValidStorageKey(config.key);
     const storageKey = prefixKey(config.namespace, config.key);
     const serialize = config.serialize ?? defaultSerialize;
     const deserialize = config.deserialize ?? defaultDeserialize;
@@ -1732,7 +1778,7 @@ export function createStorageCore(
         const raw = readBackendRaw(() =>
           adapter.backend.getSecureBiometric(storageKey),
         );
-        if (readCache) {
+        if (readCache || fallbackToCacheOnReadError) {
           cacheRawValue(
             resolveNonMemoryScope(),
             storageKey,
@@ -1746,7 +1792,9 @@ export function createStorageCore(
       const raw = readBackendRaw(() =>
         adapter.backend.get(storageKey, config.scope),
       );
-      cacheRawValue(resolveNonMemoryScope(), storageKey, raw);
+      if (readCache || fallbackToCacheOnReadError) {
+        cacheRawValue(resolveNonMemoryScope(), storageKey, raw);
+      }
       return raw;
     };
 
@@ -1757,7 +1805,10 @@ export function createStorageCore(
         return read();
       } catch (error) {
         onReadError?.(error);
-        if (fallbackToCacheOnReadError) {
+        if (
+          fallbackToCacheOnReadError &&
+          isStorageError(error, "keychain_locked")
+        ) {
           const scope = resolveNonMemoryScope();
           const cached = readCachedRawValue(
             scope,
@@ -2407,13 +2458,11 @@ export function createStorageCore(
     const removeStoredRaw = (
       operation: StorageChangeOperation = "remove",
     ): void => {
-      const oldValue = isBiometric
-        ? getEventRawValueForRepresentation(
-            config.scope,
-            storageKey,
-            "biometric",
-          )
-        : getEventRawValue(config.scope, storageKey);
+      const oldValue = readPreviousEventValue(
+        config.scope,
+        storageKey,
+        isBiometric ? "biometric" : "plain",
+      );
       if (isBiometric) {
         invalidateRawCache(StorageScope.Secure, storageKey);
         scheduleRenameSourceCleanup();
@@ -2494,9 +2543,7 @@ export function createStorageCore(
         } else {
           memoryExpirationDeadlines.delete(storageKey);
         }
-        const storedValue =
-          typeof value === "string" ? escapeCollidingRawValue(value) : value;
-        memoryStore.set(storageKey, storedValue);
+        memoryStore.set(storageKey, toMemoryStoredValue(value));
         notifyKeyListeners(memoryListeners, storageKey);
         emitKeyChange(
           config.scope,
@@ -3000,7 +3047,7 @@ export function createStorageCore(
 
           // Atomic write: update all values in memoryStore, invalidate caches, then batch-notify
           items.forEach(({ item, value }) => {
-            memoryStore.set(item.key, value);
+            memoryStore.set(item.key, toMemoryStoredValue(value));
             asInternal(
               item as StorageItem<unknown>,
             )._invalidateParsedCacheOnly();
@@ -3455,9 +3502,13 @@ export function createStorageCore(
         const rollbackSource =
           scope === StorageScope.Memory ? "memory" : adapter.changeSource;
         const rollbackErrors: { label: string; error: unknown }[] = [];
+        const readRollbackEvents = shouldReadPreviousEventValues(scope);
         const readRollbackEventValue = (
           entry: TransactionRollbackEntry,
         ): string | undefined => {
+          if (!readRollbackEvents) {
+            return undefined;
+          }
           try {
             return getEventRawValueForRepresentation(
               scope,
@@ -3746,7 +3797,7 @@ export function createStorageCore(
     const initial: Record<string, true> = {};
     if (defaultValue) {
       for (const id of defaultValue) {
-        initial[id] = true;
+        setOwnDataProperty(initial, id, true);
       }
     }
 
@@ -3763,7 +3814,7 @@ export function createStorageCore(
         return;
       }
       const next = { ...current };
-      next[id] = true;
+      setOwnDataProperty(next, id, true);
       item.set(next);
     };
 
@@ -3789,7 +3840,7 @@ export function createStorageCore(
     const getTyped = (): Partial<Record<TMember, true>> => {
       const typed: Partial<Record<TMember, true>> = {};
       for (const id of Object.keys(item.get())) {
-        typed[id as TMember] = true;
+        setOwnDataProperty(typed, id, true);
       }
       return typed;
     };

package/src/storage-runtime.ts

@@ -5,7 +5,8 @@ export type StorageErrorCode =
   | "storage_corruption"
   | "storage_compensation_failed"
   | "biometric_unavailable"
-  | "unsupported";
+  | "unsupported"
+  | "invalid_key";
 
 export type StorageCapabilities = {
   platform: "native" | "web";
@@ -65,6 +66,7 @@ const STORAGE_ERROR_CODES = new Set<StorageErrorCode>([
   "storage_compensation_failed",
   "biometric_unavailable",
   "unsupported",
+  "invalid_key",
 ]);
 
 export function getStorageErrorCode(