react-native-nitro-storage 0.4.4 → 0.5.0

package/src/index.ts

@@ -14,10 +14,34 @@ import {
   prefixKey,
   isNamespaced,
 } from "./internal";
+import type {
+  WebDiskStorageBackend,
+  WebSecureStorageBackend,
+} from "./web-storage-backend";
+import {
+  getStorageErrorCode,
+  isLockedStorageErrorCode,
+  type SecureStorageMetadata,
+  type SecurityCapabilities,
+  type StorageCapabilities,
+  type StorageErrorCode,
+} from "./storage-runtime";
 
 export { StorageScope, AccessControl, BiometricLevel } from "./Storage.types";
 export type { Storage } from "./Storage.nitro";
 export { migrateFromMMKV } from "./migration";
+export {
+  getStorageErrorCode,
+  type SecureStorageMetadata,
+  type SecurityCapabilities,
+  type StorageCapabilities,
+  type StorageErrorCode,
+} from "./storage-runtime";
+export type {
+  WebStorageBackend,
+  WebStorageChangeEvent,
+  WebStorageScope,
+} from "./web-storage-backend";
 
 export type Validator<T> = (value: unknown) => value is T;
 export type ExpirationConfig = {
@@ -41,14 +65,6 @@ export type StorageMetricSummary = {
   avgDurationMs: number;
   maxDurationMs: number;
 };
-export type WebSecureStorageBackend = {
-  getItem: (key: string) => string | null;
-  setItem: (key: string, value: string) => void;
-  removeItem: (key: string) => void;
-  clear: () => void;
-  getAllKeys: () => string[];
-};
-
 export type MigrationContext = {
   scope: StorageScope;
   getRaw: (key: string) => string | undefined;
@@ -95,6 +111,10 @@ function typedKeys<K extends string, V>(record: Record<K, V>): K[] {
   return Object.keys(record) as K[];
 }
 type NonMemoryScope = StorageScope.Disk | StorageScope.Secure;
+type PendingDiskWrite = {
+  key: string;
+  value: string | undefined;
+};
 type PendingSecureWrite = {
   key: string;
   value: string | undefined;
@@ -108,6 +128,10 @@ const runMicrotask =
     : (task: () => void) => {
         Promise.resolve().then(task);
       };
+const now =
+  typeof performance !== "undefined" && typeof performance.now === "function"
+    ? () => performance.now()
+    : () => Date.now();
 
 let _storageModule: Storage | null = null;
 
@@ -131,6 +155,9 @@ const scopedRawCache = new Map<NonMemoryScope, Map<string, string | undefined>>(
     [StorageScope.Secure, new Map()],
   ],
 );
+const pendingDiskWrites = new Map<string, PendingDiskWrite>();
+let diskFlushScheduled = false;
+let diskWritesAsync = false;
 const pendingSecureWrites = new Map<string, PendingSecureWrite>();
 let secureFlushScheduled = false;
 let secureDefaultAccessControl: AccessControl = AccessControl.WhenUnlocked;
@@ -139,6 +166,7 @@ const metricsCounters = new Map<
   string,
   { count: number; totalDurationMs: number; maxDurationMs: number }
 >();
+const nativeSecureBackend = "platform-secure-storage";
 
 function recordMetric(
   operation: string,
@@ -176,11 +204,11 @@ function measureOperation<T>(
   if (!metricsObserver) {
     return fn();
   }
-  const start = Date.now();
+  const start = now();
   try {
     return fn();
   } finally {
-    recordMetric(operation, scope, Date.now() - start, keysCount);
+    recordMetric(operation, scope, now() - start, keysCount);
   }
 }
 
@@ -262,14 +290,59 @@ function readPendingSecureWrite(key: string): string | undefined {
   return pendingSecureWrites.get(key)?.value;
 }
 
+function readPendingDiskWrite(key: string): string | undefined {
+  return pendingDiskWrites.get(key)?.value;
+}
+
+function hasPendingDiskWrite(key: string): boolean {
+  return pendingDiskWrites.has(key);
+}
+
 function hasPendingSecureWrite(key: string): boolean {
   return pendingSecureWrites.has(key);
 }
 
+function clearPendingDiskWrite(key: string): void {
+  pendingDiskWrites.delete(key);
+}
+
 function clearPendingSecureWrite(key: string): void {
   pendingSecureWrites.delete(key);
 }
 
+function flushDiskWrites(): void {
+  diskFlushScheduled = false;
+
+  if (pendingDiskWrites.size === 0) {
+    return;
+  }
+
+  const writes = Array.from(pendingDiskWrites.values());
+  pendingDiskWrites.clear();
+
+  const keysToSet: string[] = [];
+  const valuesToSet: string[] = [];
+  const keysToRemove: string[] = [];
+
+  writes.forEach(({ key, value }) => {
+    if (value === undefined) {
+      keysToRemove.push(key);
+      return;
+    }
+
+    keysToSet.push(key);
+    valuesToSet.push(value);
+  });
+
+  const storageModule = getStorageModule();
+  if (keysToSet.length > 0) {
+    storageModule.setBatch(keysToSet, valuesToSet, StorageScope.Disk);
+  }
+  if (keysToRemove.length > 0) {
+    storageModule.removeBatch(keysToRemove, StorageScope.Disk);
+  }
+}
+
 function flushSecureWrites(): void {
   secureFlushScheduled = false;
 
@@ -311,6 +384,15 @@ function flushSecureWrites(): void {
   }
 }
 
+function scheduleDiskWrite(key: string, value: string | undefined): void {
+  pendingDiskWrites.set(key, { key, value });
+  if (diskFlushScheduled) {
+    return;
+  }
+  diskFlushScheduled = true;
+  runMicrotask(flushDiskWrites);
+}
+
 function scheduleSecureWrite(
   key: string,
   value: string | undefined,
@@ -334,6 +416,14 @@ function ensureNativeScopeSubscription(scope: NonMemoryScope): void {
   }
 
   const unsubscribe = getStorageModule().addOnChange(scope, (key, value) => {
+    if (scope === StorageScope.Disk) {
+      if (key === "") {
+        pendingDiskWrites.clear();
+      } else {
+        clearPendingDiskWrite(key);
+      }
+    }
+
     if (scope === StorageScope.Secure) {
       if (key === "") {
         pendingSecureWrites.clear();
@@ -376,6 +466,10 @@ function getRawValue(key: string, scope: StorageScope): string | undefined {
     return typeof value === "string" ? value : undefined;
   }
 
+  if (scope === StorageScope.Disk && hasPendingDiskWrite(key)) {
+    return readPendingDiskWrite(key);
+  }
+
   if (scope === StorageScope.Secure && hasPendingSecureWrite(key)) {
     return readPendingSecureWrite(key);
   }
@@ -391,6 +485,17 @@ function setRawValue(key: string, value: string, scope: StorageScope): void {
     return;
   }
 
+  if (scope === StorageScope.Disk) {
+    cacheRawValue(scope, key, value);
+    if (diskWritesAsync) {
+      scheduleDiskWrite(key, value);
+      return;
+    }
+
+    flushDiskWrites();
+    clearPendingDiskWrite(key);
+  }
+
   if (scope === StorageScope.Secure) {
     flushSecureWrites();
     clearPendingSecureWrite(key);
@@ -409,6 +514,17 @@ function removeRawValue(key: string, scope: StorageScope): void {
     return;
   }
 
+  if (scope === StorageScope.Disk) {
+    cacheRawValue(scope, key, undefined);
+    if (diskWritesAsync) {
+      scheduleDiskWrite(key, undefined);
+      return;
+    }
+
+    flushDiskWrites();
+    clearPendingDiskWrite(key);
+  }
+
   if (scope === StorageScope.Secure) {
     flushSecureWrites();
     clearPendingSecureWrite(key);
@@ -441,6 +557,11 @@ export const storage = {
         return;
       }
 
+      if (scope === StorageScope.Disk) {
+        flushDiskWrites();
+        pendingDiskWrites.clear();
+      }
+
       if (scope === StorageScope.Secure) {
         flushSecureWrites();
         pendingSecureWrites.clear();
@@ -476,6 +597,9 @@ export const storage = {
       }
 
       const keyPrefix = prefixKey(namespace, "");
+      if (scope === StorageScope.Disk) {
+        flushDiskWrites();
+      }
       if (scope === StorageScope.Secure) {
         flushSecureWrites();
       }
@@ -500,6 +624,12 @@ export const storage = {
       if (scope === StorageScope.Memory) {
         return memoryStore.has(key);
       }
+      if (scope === StorageScope.Disk) {
+        flushDiskWrites();
+      }
+      if (scope === StorageScope.Secure) {
+        flushSecureWrites();
+      }
       return getStorageModule().has(key, scope);
     });
   },
@@ -509,6 +639,12 @@ export const storage = {
       if (scope === StorageScope.Memory) {
         return Array.from(memoryStore.keys());
       }
+      if (scope === StorageScope.Disk) {
+        flushDiskWrites();
+      }
+      if (scope === StorageScope.Secure) {
+        flushSecureWrites();
+      }
       return getStorageModule().getAllKeys(scope);
     });
   },
@@ -520,6 +656,12 @@ export const storage = {
           key.startsWith(prefix),
         );
       }
+      if (scope === StorageScope.Disk) {
+        flushDiskWrites();
+      }
+      if (scope === StorageScope.Secure) {
+        flushSecureWrites();
+      }
       return getStorageModule().getKeysByPrefix(prefix, scope);
     });
   },
@@ -544,6 +686,12 @@ export const storage = {
         return result;
       }
 
+      if (scope === StorageScope.Disk) {
+        flushDiskWrites();
+      }
+      if (scope === StorageScope.Secure) {
+        flushSecureWrites();
+      }
       const values = getStorageModule().getBatch(keys, scope);
       keys.forEach((key, idx) => {
         const value = decodeNativeBatchValue(values[idx]);
@@ -564,6 +712,12 @@ export const storage = {
         });
         return result;
       }
+      if (scope === StorageScope.Disk) {
+        flushDiskWrites();
+      }
+      if (scope === StorageScope.Secure) {
+        flushSecureWrites();
+      }
       const keys = getStorageModule().getAllKeys(scope);
       if (keys.length === 0) return result;
       const values = getStorageModule().getBatch(keys, scope);
@@ -580,6 +734,12 @@ export const storage = {
       if (scope === StorageScope.Memory) {
         return memoryStore.size;
       }
+      if (scope === StorageScope.Disk) {
+        flushDiskWrites();
+      }
+      if (scope === StorageScope.Secure) {
+        flushSecureWrites();
+      }
       return getStorageModule().size(scope);
     });
   },
@@ -598,6 +758,19 @@ export const storage = {
       },
     );
   },
+  setDiskWritesAsync: (enabled: boolean) => {
+    measureOperation("storage:setDiskWritesAsync", StorageScope.Disk, () => {
+      diskWritesAsync = enabled;
+      if (!enabled) {
+        flushDiskWrites();
+      }
+    });
+  },
+  flushDiskWrites: () => {
+    measureOperation("storage:flushDiskWrites", StorageScope.Disk, () => {
+      flushDiskWrites();
+    });
+  },
   flushSecureWrites: () => {
     measureOperation("storage:flushSecureWrites", StorageScope.Secure, () => {
       flushSecureWrites();
@@ -631,6 +804,79 @@ export const storage = {
   resetMetrics: () => {
     metricsCounters.clear();
   },
+  getCapabilities: (): StorageCapabilities => ({
+    platform: "native",
+    backend: {
+      disk: "platform-preferences",
+      secure: nativeSecureBackend,
+    },
+    writeBuffering: {
+      disk: true,
+      secure: true,
+    },
+    errorClassification: true,
+  }),
+  getSecurityCapabilities: (): SecurityCapabilities => ({
+    platform: "native",
+    secureStorage: {
+      backend: nativeSecureBackend,
+      encrypted: "available",
+      accessControl: "unknown",
+      keychainAccessGroup: "unknown",
+      hardwareBacked: "unknown",
+    },
+    biometric: {
+      storage: "unknown",
+      prompt: "unknown",
+      biometryOnly: "unknown",
+      biometryOrPasscode: "unknown",
+    },
+    metadata: {
+      perKey: true,
+      listsWithoutValues: true,
+      persistsTimestamps: false,
+    },
+  }),
+  getSecureMetadata: (key: string): SecureStorageMetadata => {
+    return measureOperation(
+      "storage:getSecureMetadata",
+      StorageScope.Secure,
+      () => {
+        flushSecureWrites();
+        const storageModule = getStorageModule();
+        const biometricProtected = storageModule.hasSecureBiometric(key);
+        const exists =
+          biometricProtected || storageModule.has(key, StorageScope.Secure);
+        let kind: SecureStorageMetadata["kind"] = "missing";
+        if (exists) {
+          kind = biometricProtected ? "biometric" : "secure";
+        }
+
+        return {
+          key,
+          exists,
+          kind,
+          backend: nativeSecureBackend,
+          encrypted: "available",
+          hardwareBacked: "unknown",
+          biometricProtected,
+          valueExposed: false,
+        };
+      },
+    );
+  },
+  getAllSecureMetadata: (): SecureStorageMetadata[] => {
+    return measureOperation(
+      "storage:getAllSecureMetadata",
+      StorageScope.Secure,
+      () => {
+        flushSecureWrites();
+        return getStorageModule()
+          .getAllKeys(StorageScope.Secure)
+          .map((key) => storage.getSecureMetadata(key));
+      },
+    );
+  },
   getString: (key: string, scope: StorageScope): string | undefined => {
     return measureOperation("storage:getString", scope, () => {
       return getRawValue(key, scope);
@@ -689,6 +935,20 @@ export function getWebSecureStorageBackend():
   return undefined;
 }
 
+export function setWebDiskStorageBackend(
+  _backend?: WebDiskStorageBackend,
+): void {
+  // Native platforms do not use web disk backends.
+}
+
+export function getWebDiskStorageBackend(): WebDiskStorageBackend | undefined {
+  return undefined;
+}
+
+export async function flushWebStorageBackends(): Promise<void> {
+  // Native platforms do not use web storage backends.
+}
+
 export interface StorageItemConfig<T> {
   key: string;
   scope: StorageScope;
@@ -700,6 +960,7 @@ export interface StorageItemConfig<T> {
   expiration?: ExpirationConfig;
   onExpired?: (key: string) => void;
   readCache?: boolean;
+  coalesceDiskWrites?: boolean;
   coalesceSecureWrites?: boolean;
   namespace?: string;
   biometric?: boolean;
@@ -784,6 +1045,8 @@ export function createStorageItem<T = undefined>(
   const memoryExpiration =
     expiration && isMemory ? new Map<string, number>() : null;
   const readCache = !isMemory && config.readCache === true;
+  const coalesceDiskWrites =
+    config.scope === StorageScope.Disk && config.coalesceDiskWrites === true;
   const coalesceSecureWrites =
     config.scope === StorageScope.Secure &&
     config.coalesceSecureWrites === true &&
@@ -852,6 +1115,13 @@ export function createStorageItem<T = undefined>(
       return memoryStore.get(storageKey);
     }
 
+    if (nonMemoryScope === StorageScope.Disk) {
+      const pending = pendingDiskWrites.get(storageKey);
+      if (pending !== undefined) {
+        return pending.value;
+      }
+    }
+
     if (nonMemoryScope === StorageScope.Secure && !isBiometric) {
       const pending = pendingSecureWrites.get(storageKey);
       if (pending !== undefined) {
@@ -888,6 +1158,15 @@ export function createStorageItem<T = undefined>(
 
     cacheRawValue(nonMemoryScope!, storageKey, rawValue);
 
+    if (nonMemoryScope === StorageScope.Disk) {
+      if (coalesceDiskWrites || diskWritesAsync) {
+        scheduleDiskWrite(storageKey, rawValue);
+        return;
+      }
+
+      clearPendingDiskWrite(storageKey);
+    }
+
     if (coalesceSecureWrites) {
       scheduleSecureWrite(
         storageKey,
@@ -915,6 +1194,15 @@ export function createStorageItem<T = undefined>(
 
     cacheRawValue(nonMemoryScope!, storageKey, undefined);
 
+    if (nonMemoryScope === StorageScope.Disk) {
+      if (coalesceDiskWrites || diskWritesAsync) {
+        scheduleDiskWrite(storageKey, undefined);
+        return;
+      }
+
+      clearPendingDiskWrite(storageKey);
+    }
+
     if (coalesceSecureWrites) {
       scheduleSecureWrite(
         storageKey,
@@ -1125,6 +1413,18 @@ export function createStorageItem<T = undefined>(
     measureOperation("item:has", config.scope, () => {
       if (isMemory) return memoryStore.has(storageKey);
       if (isBiometric) return getStorageModule().hasSecureBiometric(storageKey);
+      if (nonMemoryScope === StorageScope.Disk) {
+        const pending = pendingDiskWrites.get(storageKey);
+        if (pending !== undefined) {
+          return pending.value !== undefined;
+        }
+      }
+      if (nonMemoryScope === StorageScope.Secure) {
+        const pending = pendingSecureWrites.get(storageKey);
+        if (pending !== undefined) {
+          return pending.value !== undefined;
+        }
+      }
       return getStorageModule().has(storageKey, config.scope);
     });
 
@@ -1224,6 +1524,14 @@ export function getBatch(
       const keyIndexes: number[] = [];
 
       items.forEach((item, index) => {
+        if (scope === StorageScope.Disk) {
+          const pending = pendingDiskWrites.get(item.key);
+          if (pending !== undefined) {
+            rawValues[index] = pending.value;
+            return;
+          }
+        }
+
         if (scope === StorageScope.Secure) {
           const pending = pendingSecureWrites.get(item.key);
           if (pending !== undefined) {
@@ -1353,6 +1661,8 @@ export function setBatch<T>(
         return;
       }
 
+      flushDiskWrites();
+
       const useRawBatchPath = items.every(({ item }) =>
         canUseRawBatchPath(asInternal(item)),
       );
@@ -1387,6 +1697,9 @@ export function removeBatch(
       }
 
       const keys = items.map((item) => item.key);
+      if (scope === StorageScope.Disk) {
+        flushDiskWrites();
+      }
       if (scope === StorageScope.Secure) {
         flushSecureWrites();
       }
@@ -1450,6 +1763,9 @@ export function runTransaction<T>(
 ): T {
   return measureOperation("transaction:run", scope, () => {
     assertValidScope(scope);
+    if (scope === StorageScope.Disk) {
+      flushDiskWrites();
+    }
     if (scope === StorageScope.Secure) {
       flushSecureWrites();
     }
@@ -1525,6 +1841,9 @@ export function runTransaction<T>(
           }
         });
 
+        if (scope === StorageScope.Disk) {
+          flushDiskWrites();
+        }
         if (scope === StorageScope.Secure) {
           flushSecureWrites();
         }
@@ -1555,16 +1874,7 @@ export type SecureAuthStorageConfig<K extends string = string> = Record<
 >;
 
 export function isKeychainLockedError(err: unknown): boolean {
-  if (!(err instanceof Error)) return false;
-  const msg = err.message;
-  return (
-    msg.includes("errSecInteractionNotAllowed") ||
-    msg.includes("UserNotAuthenticatedException") ||
-    msg.includes("KeyStoreException") ||
-    msg.includes("KeyPermanentlyInvalidatedException") ||
-    msg.includes("InvalidKeyException") ||
-    msg.includes("android.security.keystore")
-  );
+  return isLockedStorageErrorCode(getStorageErrorCode(err));
 }
 
 export function createSecureAuthStorage<K extends string>(