react-native-nitro-storage 0.7.0 → 0.8.0

package/src/indexeddb-backend.ts

@@ -19,7 +19,11 @@ export type IndexedDBBackendOptions = {
 function openDB(dbName: string, storeName: string): Promise<IDBDatabase> {
   return new Promise((resolve, reject) => {
     if (typeof indexedDB === "undefined") {
-      reject(new Error("IndexedDB is not available in this environment."));
+      reject(
+        new Error(
+          "[nitro-error:unsupported] IndexedDB is not available in this environment.",
+        ),
+      );
       return;
     }
 
@@ -32,9 +36,12 @@ function openDB(dbName: string, storeName: string): Promise<IDBDatabase> {
       }
     };
 
-    request.onsuccess = () => resolve(request.result);
-    request.onerror = () =>
+    request.onsuccess = () => {
+      resolve(request.result);
+    };
+    request.onerror = () => {
       reject(request.error ?? new Error("Failed to open IndexedDB database."));
+    };
   });
 }
 
@@ -72,7 +79,7 @@ export async function createIndexedDBBackend(
   const db = await openDB(dbName, storeName);
   const cache = new Map<string, string>();
   const pendingWrites = new Set<Promise<void>>();
-  const pendingErrors: Error[] = [];
+  const pendingErrors: { keys: string[] | null; error: Error }[] = [];
   const subscribers = new Set<(event: WebStorageChangeEvent) => void>();
   let closed = false;
   const sourceId = `nitro-storage-${Math.random().toString(36).slice(2)}`;
@@ -95,15 +102,51 @@ export async function createIndexedDBBackend(
     });
   }
 
-  function handleAsyncError(error: unknown): void {
+  function handleAsyncError(keys: string[] | null, error: unknown): void {
     const normalized =
       error instanceof Error
         ? error
         : new Error(String(error ?? "Unknown IndexedDB error"));
-    pendingErrors.push(normalized);
+    pendingErrors.push({ keys, error: normalized });
     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.
+    });
+  }
+
+  function installLifecycleFlush(): () => void {
+    if (typeof globalThis === "undefined" || !globalThis.addEventListener) {
+      return () => {};
+    }
+
+    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);
+    };
+  }
+
+  const removeLifecycleFlush = installLifecycleFlush();
+
   channel?.addEventListener("message", (event: MessageEvent) => {
     if (closed) {
       return;
@@ -153,22 +196,29 @@ export async function createIndexedDBBackend(
       }
     };
 
-    tx.oncomplete = () => resolve();
-    tx.onerror = () =>
+    tx.oncomplete = () => {
+      resolve();
+    };
+    tx.onerror = () => {
       reject(tx.error ?? new Error("Failed to load IndexedDB entries."));
+    };
   });
 
-  function trackWrite(tx: IDBTransaction): void {
+  function trackWrite(tx: IDBTransaction, keys: string[] | null): void {
     const pending = new Promise<void>((resolve) => {
-      tx.oncomplete = () => resolve();
+      tx.oncomplete = () => {
+        resolve();
+      };
       tx.onerror = () => {
         handleAsyncError(
+          keys,
           tx.error ?? new Error("Failed to persist IndexedDB transaction."),
         );
         resolve();
       };
       tx.onabort = () => {
         handleAsyncError(
+          keys,
           tx.error ?? new Error("IndexedDB transaction was aborted."),
         );
         resolve();
@@ -186,9 +236,10 @@ export async function createIndexedDBBackend(
     try {
       const tx = db.transaction(storeName, "readwrite");
       tx.objectStore(storeName).put(value, key);
-      trackWrite(tx);
+      trackWrite(tx, [key]);
     } catch {
       handleAsyncError(
+        [key],
         new Error(`Failed to queue IndexedDB write for "${key}".`),
       );
     }
@@ -198,9 +249,10 @@ export async function createIndexedDBBackend(
     try {
       const tx = db.transaction(storeName, "readwrite");
       tx.objectStore(storeName).delete(key);
-      trackWrite(tx);
+      trackWrite(tx, [key]);
     } catch {
       handleAsyncError(
+        [key],
         new Error(`Failed to queue IndexedDB delete for "${key}".`),
       );
     }
@@ -210,9 +262,9 @@ export async function createIndexedDBBackend(
     try {
       const tx = db.transaction(storeName, "readwrite");
       tx.objectStore(storeName).clear();
-      trackWrite(tx);
+      trackWrite(tx, null);
     } catch {
-      handleAsyncError(new Error("Failed to queue IndexedDB clear."));
+      handleAsyncError(null, new Error("Failed to queue IndexedDB clear."));
     }
   }
 
@@ -254,8 +306,10 @@ export async function createIndexedDBBackend(
     },
     setMany(entries): void {
       assertOpen();
+      const keys: string[] = [];
       entries.forEach(([key, value]) => {
         cache.set(key, value);
+        keys.push(key);
       });
       try {
         const tx = db.transaction(storeName, "readwrite");
@@ -264,9 +318,12 @@ export async function createIndexedDBBackend(
           store.put(value, key);
           publish({ key, newValue: value });
         });
-        trackWrite(tx);
+        trackWrite(tx, keys);
       } catch {
-        handleAsyncError(new Error("Failed to queue IndexedDB batch write."));
+        handleAsyncError(
+          null,
+          new Error("Failed to queue IndexedDB batch write."),
+        );
       }
     },
     removeMany(keys: string[]): void {
@@ -281,9 +338,12 @@ export async function createIndexedDBBackend(
           store.delete(key);
           publish({ key, newValue: null });
         });
-        trackWrite(tx);
+        trackWrite(tx, keys);
       } catch {
-        handleAsyncError(new Error("Failed to queue IndexedDB batch delete."));
+        handleAsyncError(
+          null,
+          new Error("Failed to queue IndexedDB batch delete."),
+        );
       }
     },
     size(): number {
@@ -303,14 +363,25 @@ export async function createIndexedDBBackend(
         return;
       }
 
-      const [error] = pendingErrors.splice(0);
-      throw error;
+      const failures = pendingErrors.splice(0);
+      const failedKeys = failures
+        .flatMap(({ keys }) => keys ?? [])
+        .filter((key, index, all) => all.indexOf(key) === index);
+      const keyDetail =
+        failedKeys.length > 0
+          ? ` Affected keys: ${failedKeys.join(", ")}.`
+          : "";
+      const [first] = failures;
+      throw new Error(
+        `NitroStorage: IndexedDB persistence failed for ${failures.length} write(s).${keyDetail} ${first?.error.message ?? ""}`,
+      );
     },
     close(): void {
       if (closed) {
         return;
       }
       closed = true;
+      removeLifecycleFlush();
       subscribers.clear();
       channel?.close();
       db.close();

package/src/internal.ts

@@ -16,6 +16,36 @@ const PRIM_NAN = "__nitro_storage_primitive__:n:NaN";
 const NAMESPACE_SEPARATOR = ":";
 const VERSION_TOKEN_PREFIX = "__nitro_storage_version__:";
 
+export const ESCAPE_PREFIX = "__nitro_storage_escaped__:";
+
+const RESERVED_RAW_TOKENS = new Set<string>([
+  PRIM_NULL,
+  PRIM_UNDEFINED,
+  PRIM_TRUE,
+  PRIM_FALSE,
+  PRIM_INFINITY,
+  PRIM_NEG_INFINITY,
+  PRIM_NAN,
+  NATIVE_BATCH_MISSING_SENTINEL,
+]);
+
+export function escapeCollidingRawValue(value: string): string {
+  if (
+    RESERVED_RAW_TOKENS.has(value) ||
+    value.startsWith(PRIMITIVE_FAST_PATH_PREFIX) ||
+    value.startsWith(ESCAPE_PREFIX)
+  ) {
+    return `${ESCAPE_PREFIX}${value}`;
+  }
+  return value;
+}
+
+export function unescapeCollidingRawValue(value: string): string {
+  return value.startsWith(ESCAPE_PREFIX)
+    ? value.slice(ESCAPE_PREFIX.length)
+    : value;
+}
+
 export type StoredEnvelope = {
   __nitroStorageEnvelope: true;
   expiresAt: number;
@@ -71,7 +101,7 @@ export function assertBatchScope(
 export function decodeNativeBatchValue(
   value: string | undefined,
 ): string | undefined {
-  if (value === NATIVE_BATCH_MISSING_SENTINEL) {
+  if (value === undefined || value === NATIVE_BATCH_MISSING_SENTINEL) {
     return undefined;
   }
 
@@ -93,8 +123,17 @@ export function serializeWithPrimitiveFastPath<T>(value: T): string {
   }
 
   switch (typeof value) {
-    case "string":
-      return PRIM_STRING_PREFIX + (value as string);
+    case "string": {
+      const stringValue = value as string;
+      if (
+        stringValue === NATIVE_BATCH_MISSING_SENTINEL ||
+        stringValue.startsWith(PRIMITIVE_FAST_PATH_PREFIX) ||
+        stringValue.startsWith(ESCAPE_PREFIX)
+      ) {
+        return `${PRIM_STRING_PREFIX}${ESCAPE_PREFIX}${stringValue}`;
+      }
+      return PRIM_STRING_PREFIX + stringValue;
+    }
     case "number":
       if (Number.isFinite(value)) {
         return PRIM_NUMBER_PREFIX + String(value);
@@ -134,6 +173,10 @@ const CHAR_B = 98; // 'b'
 const CHAR_N = 110; // 'n'
 
 export function deserializeWithPrimitiveFastPath<T>(value: string): T {
+  if (value.startsWith(ESCAPE_PREFIX)) {
+    return value.slice(ESCAPE_PREFIX.length) as T;
+  }
+
   if (value.startsWith(PRIMITIVE_FAST_PATH_PREFIX)) {
     const prefixLen = PRIMITIVE_FAST_PATH_PREFIX.length;
     const tagChar = value.charCodeAt(prefixLen);
@@ -149,7 +192,10 @@ export function deserializeWithPrimitiveFastPath<T>(value: string): T {
     const payload = value.slice(prefixLen + 2);
 
     if (tagChar === CHAR_S) {
-      return payload as T;
+      const unescapedPayload = payload.startsWith(ESCAPE_PREFIX)
+        ? payload.slice(ESCAPE_PREFIX.length)
+        : payload;
+      return unescapedPayload as T;
     }
     if (tagChar === CHAR_B) {
       return (payload === "1") as T;

package/src/shared.ts

@@ -1,17 +1,18 @@
-import { StorageScope, AccessControl, BiometricLevel } from "./Storage.types";
 import {
   serializeWithPrimitiveFastPath,
   deserializeWithPrimitiveFastPath,
 } from "./internal";
-import {
-  getStorageErrorCode,
-  isLockedStorageErrorCode,
-} from "./storage-runtime";
 import type {
   StorageChangeOperation,
   StorageChangeSource,
   StorageKeyChangeEvent,
 } from "./storage-events";
+import {
+  getStorageErrorCode,
+  isLockedStorageErrorCode,
+} from "./storage-runtime";
+import { StorageScope } from "./Storage.types";
+import type { AccessControl, BiometricLevel } from "./Storage.types";
 
 export type Validator<T> = (value: unknown) => value is T;
 
@@ -144,7 +145,7 @@ export const runMicrotask =
   typeof queueMicrotask === "function"
     ? queueMicrotask
     : (task: () => void) => {
-        Promise.resolve().then(task);
+        void Promise.resolve().then(task);
       };
 
 export const now =