react-native-nitro-storage 0.7.0 → 0.9.0

package/src/core/durability.ts

@@ -0,0 +1,170 @@
+import { runMicrotask } from "../shared";
+import { StorageScope, type AccessControl } from "../Storage.types";
+import type { PendingDiskWrite, PendingSecureWrite } from "../shared";
+
+export type DurabilityBackend = {
+  setBatch(keys: string[], values: string[], scope: number): void;
+  removeBatch(keys: string[], scope: number): void;
+  setSecureAccessControl(level: AccessControl): void;
+};
+
+export type DurabilityCoordinator = {
+  setDiskWritesAsync(enabled: boolean): void;
+  isDiskWritesAsync(): boolean;
+  hasPendingDiskWrite(key: string): boolean;
+  hasPendingSecureWrite(key: string): boolean;
+  readPendingDiskWrite(key: string): string | undefined;
+  readPendingSecureWrite(key: string): string | undefined;
+  clearPendingDiskWrite(key: string): void;
+  clearPendingSecureWrite(key: string): void;
+  clearAllPendingDiskWrites(): void;
+  clearAllPendingSecureWrites(): void;
+  scheduleDiskWrite(key: string, value: string | undefined): void;
+  scheduleSecureWrite(
+    key: string,
+    value: string | undefined,
+    accessControl?: AccessControl,
+  ): void;
+  flushDiskWrites(): void;
+  flushSecureWrites(): void;
+};
+
+export function createDurabilityCoordinator(options: {
+  backend: DurabilityBackend;
+  resolveSecureDefaultAccessControl(): AccessControl;
+}): DurabilityCoordinator {
+  const pendingDiskWrites = new Map<string, PendingDiskWrite>();
+  let diskFlushScheduled = false;
+  let diskWritesAsync = false;
+  const pendingSecureWrites = new Map<string, PendingSecureWrite>();
+  let secureFlushScheduled = false;
+
+  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);
+    });
+
+    if (keysToSet.length > 0) {
+      options.backend.setBatch(keysToSet, valuesToSet, StorageScope.Disk);
+    }
+    if (keysToRemove.length > 0) {
+      options.backend.removeBatch(keysToRemove, StorageScope.Disk);
+    }
+  }
+
+  function flushSecureWrites(): void {
+    secureFlushScheduled = false;
+
+    if (pendingSecureWrites.size === 0) {
+      return;
+    }
+
+    const writes = Array.from(pendingSecureWrites.values());
+    pendingSecureWrites.clear();
+
+    const groupedSetWrites = new Map<
+      AccessControl,
+      { keys: string[]; values: string[] }
+    >();
+    const keysToRemove: string[] = [];
+
+    writes.forEach(({ key, value, accessControl }) => {
+      if (value === undefined) {
+        keysToRemove.push(key);
+      } else {
+        const resolvedAccessControl =
+          accessControl ?? options.resolveSecureDefaultAccessControl();
+        const existingGroup = groupedSetWrites.get(resolvedAccessControl);
+        const group = existingGroup ?? { keys: [], values: [] };
+        group.keys.push(key);
+        group.values.push(value);
+        if (!existingGroup) {
+          groupedSetWrites.set(resolvedAccessControl, group);
+        }
+      }
+    });
+
+    groupedSetWrites.forEach((group, accessControl) => {
+      options.backend.setSecureAccessControl(accessControl);
+      options.backend.setBatch(group.keys, group.values, StorageScope.Secure);
+    });
+    if (keysToRemove.length > 0) {
+      options.backend.removeBatch(keysToRemove, StorageScope.Secure);
+    }
+  }
+
+  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,
+    accessControl?: AccessControl,
+  ): void {
+    const pendingWrite: PendingSecureWrite = { key, value };
+    if (accessControl !== undefined) {
+      pendingWrite.accessControl = accessControl;
+    }
+    pendingSecureWrites.set(key, pendingWrite);
+    if (secureFlushScheduled) {
+      return;
+    }
+    secureFlushScheduled = true;
+    runMicrotask(flushSecureWrites);
+  }
+
+  return {
+    setDiskWritesAsync(enabled) {
+      diskWritesAsync = enabled;
+      if (!enabled) {
+        flushDiskWrites();
+      }
+    },
+    isDiskWritesAsync: () => diskWritesAsync,
+    hasPendingDiskWrite: (key) => pendingDiskWrites.has(key),
+    hasPendingSecureWrite: (key) => pendingSecureWrites.has(key),
+    readPendingDiskWrite: (key) => pendingDiskWrites.get(key)?.value,
+    readPendingSecureWrite: (key) => pendingSecureWrites.get(key)?.value,
+    clearPendingDiskWrite: (key) => {
+      pendingDiskWrites.delete(key);
+    },
+    clearPendingSecureWrite: (key) => {
+      pendingSecureWrites.delete(key);
+    },
+    clearAllPendingDiskWrites: () => {
+      pendingDiskWrites.clear();
+    },
+    clearAllPendingSecureWrites: () => {
+      pendingSecureWrites.clear();
+    },
+    scheduleDiskWrite,
+    scheduleSecureWrite,
+    flushDiskWrites,
+    flushSecureWrites,
+  };
+}

package/src/core/metrics.ts

@@ -0,0 +1,133 @@
+import { now } from "../shared";
+import type { StorageMetricSummary, StorageMetricsObserver } from "../shared";
+import type { StorageScope } from "../Storage.types";
+
+export type MetricsRegistry = {
+  setObserver(observer?: StorageMetricsObserver): void;
+  record(
+    operation: string,
+    scope: StorageScope,
+    durationMs: number,
+    keysCount?: number,
+  ): void;
+  measure<T>(
+    operation: string,
+    scope: StorageScope,
+    fn: () => T,
+    keysCount?: number,
+  ): T;
+  getSnapshot(): Record<string, StorageMetricSummary>;
+  getScopedSnapshot(): Record<string, StorageMetricSummary>;
+  reset(): void;
+};
+
+export function createMetricsRegistry(): MetricsRegistry {
+  let observer: StorageMetricsObserver | undefined;
+  const counters = new Map<
+    string,
+    { count: number; totalDurationMs: number; maxDurationMs: number }
+  >();
+
+  function record(
+    operation: string,
+    scope: StorageScope,
+    durationMs: number,
+    keysCount = 1,
+  ): void {
+    const counterKey = `${operation}:${scope}`;
+    const existing = counters.get(counterKey);
+    if (!existing) {
+      counters.set(counterKey, {
+        count: 1,
+        totalDurationMs: durationMs,
+        maxDurationMs: durationMs,
+      });
+    } else {
+      existing.count += 1;
+      existing.totalDurationMs += durationMs;
+      existing.maxDurationMs = Math.max(existing.maxDurationMs, durationMs);
+    }
+
+    observer?.({
+      operation,
+      scope,
+      durationMs,
+      keysCount,
+    });
+  }
+
+  function measure<T>(
+    operation: string,
+    scope: StorageScope,
+    fn: () => T,
+    keysCount = 1,
+  ): T {
+    if (!observer) {
+      return fn();
+    }
+    const start = now();
+    try {
+      return fn();
+    } finally {
+      record(operation, scope, now() - start, keysCount);
+    }
+  }
+
+  function toSummary(value: {
+    count: number;
+    totalDurationMs: number;
+    maxDurationMs: number;
+  }): StorageMetricSummary {
+    return {
+      count: value.count,
+      totalDurationMs: value.totalDurationMs,
+      avgDurationMs:
+        value.count === 0 ? 0 : value.totalDurationMs / value.count,
+      maxDurationMs: value.maxDurationMs,
+    };
+  }
+
+  return {
+    setObserver(next) {
+      observer = next;
+    },
+    record,
+    measure,
+    getSnapshot(): Record<string, StorageMetricSummary> {
+      const aggregated = new Map<
+        string,
+        { count: number; totalDurationMs: number; maxDurationMs: number }
+      >();
+      counters.forEach((value, key) => {
+        const separator = key.lastIndexOf(":");
+        const operation = separator === -1 ? key : key.slice(0, separator);
+        const existing = aggregated.get(operation);
+        if (!existing) {
+          aggregated.set(operation, { ...value });
+          return;
+        }
+        existing.count += value.count;
+        existing.totalDurationMs += value.totalDurationMs;
+        existing.maxDurationMs = Math.max(
+          existing.maxDurationMs,
+          value.maxDurationMs,
+        );
+      });
+      const snapshot: Record<string, StorageMetricSummary> = {};
+      aggregated.forEach((value, operation) => {
+        snapshot[operation] = toSummary(value);
+      });
+      return snapshot;
+    },
+    getScopedSnapshot(): Record<string, StorageMetricSummary> {
+      const snapshot: Record<string, StorageMetricSummary> = {};
+      counters.forEach((value, key) => {
+        snapshot[key] = toSummary(value);
+      });
+      return snapshot;
+    },
+    reset() {
+      counters.clear();
+    },
+  };
+}

package/src/index.ts

@@ -1,27 +1,30 @@
+import { Platform } from "react-native";
+import { NitroModules } from "react-native-nitro-modules";
+import { resolveNativeWriteBuffering } from "./capabilities";
+import { decodeNativeBatchValue, unescapeCollidingRawValue } from "./internal";
 import {
   assertAccessControlLevel,
   notifyAllListeners,
   notifyKeyListeners,
   type NonMemoryScope,
 } from "./shared";
-import { NitroModules } from "react-native-nitro-modules";
-import type { Storage } from "./Storage.nitro";
-import { StorageScope, AccessControl } from "./Storage.types";
-import { decodeNativeBatchValue } from "./internal";
-import type {
-  WebDiskStorageBackend,
-  WebSecureStorageBackend,
-} from "./web-storage-backend";
-import type {
-  SecurityCapabilities,
-  StorageCapabilities,
-} from "./storage-runtime";
 import {
   createStorageCore,
   type StorageCoreAdapter,
   type StorageCoreBackend,
   type StorageCoreInternals,
 } from "./storage-core";
+import type {
+  SecurityCapabilities,
+  StorageCapabilities,
+} from "./storage-runtime";
+import type { Storage } from "./Storage.nitro";
+import type { AccessControl } from "./Storage.types";
+import { StorageScope } from "./Storage.types";
+import type {
+  WebDiskStorageBackend,
+  WebSecureStorageBackend,
+} from "./web-storage-backend";
 export type {
   ExpirationConfig,
   Migration,
@@ -76,6 +79,7 @@ export type {
   StorageKeyRef,
   TransactionContext,
 } from "./storage-core";
+export type { PlatformScope, PlatformStorage } from "./storage-platform";
 
 let _storageModule: Storage | null = null;
 
@@ -90,44 +94,60 @@ const nativeSecureBackend = "platform-secure-storage";
 
 const nativeBackend: StorageCoreBackend = {
   get: (key, scope) => getStorageModule().get(key, scope),
-  set: (key, value, scope) => getStorageModule().set(key, value, scope),
-  remove: (key, scope) => getStorageModule().remove(key, scope),
-  clear: (scope) => getStorageModule().clear(scope),
+  set: (key, value, scope) => {
+    getStorageModule().set(key, value, scope);
+  },
+  remove: (key, scope) => {
+    getStorageModule().remove(key, scope);
+  },
+  clear: (scope) => {
+    getStorageModule().clear(scope);
+  },
   has: (key, scope) => getStorageModule().has(key, scope),
   getAllKeys: (scope) => getStorageModule().getAllKeys(scope) ?? [],
   getKeysByPrefix: (prefix, scope) =>
     getStorageModule().getKeysByPrefix(prefix, scope) ?? [],
   size: (scope) => getStorageModule().size(scope),
-  setBatch: (keys, values, scope) =>
-    getStorageModule().setBatch(keys, values, scope),
+  setBatch: (keys, values, scope) => {
+    getStorageModule().setBatch(keys, values, scope);
+  },
   getBatch: (keys, scope) =>
     (getStorageModule().getBatch(keys, scope) ?? []).map((value) =>
       decodeNativeBatchValue(value),
     ),
-  removeBatch: (keys, scope) => getStorageModule().removeBatch(keys, scope),
-  removeByPrefix: (prefix, scope) =>
-    getStorageModule().removeByPrefix(prefix, scope),
-  setSecureAccessControl: (level) =>
-    getStorageModule().setSecureAccessControl(level),
+  removeBatch: (keys, scope) => {
+    getStorageModule().removeBatch(keys, scope);
+  },
+  removeByPrefix: (prefix, scope) => {
+    getStorageModule().removeByPrefix(prefix, scope);
+  },
+  setSecureAccessControl: (level) => {
+    getStorageModule().setSecureAccessControl(level);
+  },
   getSecureBiometric: (key) => getStorageModule().getSecureBiometric(key),
-  setSecureBiometricWithLevel: (key, value, level) =>
-    getStorageModule().setSecureBiometricWithLevel(key, value, level),
-  deleteSecureBiometric: (key) => getStorageModule().deleteSecureBiometric(key),
+  setSecureBiometricWithLevel: (key, value, level) => {
+    getStorageModule().setSecureBiometricWithLevel(key, value, level);
+  },
+  deleteSecureBiometric: (key) => {
+    getStorageModule().deleteSecureBiometric(key);
+  },
   hasSecureBiometric: (key) => getStorageModule().hasSecureBiometric(key),
-  clearSecureBiometric: () => getStorageModule().clearSecureBiometric(),
+  clearSecureBiometric: () => {
+    getStorageModule().clearSecureBiometric();
+  },
 };
 
 function buildNativeAdapter(
   internals: StorageCoreInternals,
 ): StorageCoreAdapter {
   const scopedUnsubscribers = new Map<NonMemoryScope, () => void>();
-  const suppressedNativeEvents = new Map<NonMemoryScope, Map<string, number>>([
-    [StorageScope.Disk, new Map()],
-    [StorageScope.Secure, new Map()],
-  ]);
+  const suppressedNativeEvents: Record<NonMemoryScope, Map<string, number>> = {
+    [StorageScope.Disk]: new Map(),
+    [StorageScope.Secure]: new Map(),
+  };
 
   function suppressNativeEvent(scope: NonMemoryScope, key: string): void {
-    const suppressedEvents = suppressedNativeEvents.get(scope)!;
+    const suppressedEvents = suppressedNativeEvents[scope];
     suppressedEvents.set(key, (suppressedEvents.get(key) ?? 0) + 1);
   }
 
@@ -135,7 +155,7 @@ function buildNativeAdapter(
     scope: NonMemoryScope,
     key: string,
   ): boolean {
-    const suppressedEvents = suppressedNativeEvents.get(scope)!;
+    const suppressedEvents = suppressedNativeEvents[scope];
     const count = suppressedEvents.get(key);
     if (count === undefined) {
       return false;
@@ -185,8 +205,10 @@ function buildNativeAdapter(
       internals.emitKeyChange(
         scope,
         key,
-        oldValue,
-        value,
+        oldValue === undefined
+          ? undefined
+          : unescapeCollidingRawValue(oldValue),
+        value === undefined ? undefined : unescapeCollidingRawValue(value),
         "external",
         "native",
       );
@@ -220,7 +242,6 @@ function buildNativeAdapter(
     backend: nativeBackend,
     changeSource: "native",
     applyAccessControlOnSecureRawWrite: true,
-    flushDiskWritesOnImport: false,
     ensureScopeSubscription: ensureNativeScopeSubscription,
     maybeCleanupScopeSubscription: maybeCleanupNativeScopeSubscription,
     onWillEmitChanges: (scope, keys, operation, source) => {
@@ -230,7 +251,9 @@ function buildNativeAdapter(
         scope !== StorageScope.Memory &&
         scopedUnsubscribers.has(scope)
       ) {
-        keys.forEach((key) => suppressNativeEvent(scope, key));
+        keys.forEach((key) => {
+          suppressNativeEvent(scope, key);
+        });
       }
     },
     getSecureMetadataProfile: () => ({
@@ -244,6 +267,8 @@ function buildNativeAdapter(
 const core = createStorageCore(buildNativeAdapter);
 const { internals } = core;
 
+let secureWritesBuffered = false;
+
 export const storage = {
   ...core.storage,
   setAccessControl: (level: AccessControl) => {
@@ -262,6 +287,7 @@ export const storage = {
       "storage:setSecureWritesAsync",
       StorageScope.Secure,
       () => {
+        secureWritesBuffered = enabled;
         getStorageModule().setSecureWritesAsync(enabled);
       },
     );
@@ -281,10 +307,10 @@ export const storage = {
       disk: "platform-preferences",
       secure: nativeSecureBackend,
     },
-    writeBuffering: {
-      disk: true,
-      secure: true,
-    },
+    writeBuffering: resolveNativeWriteBuffering(
+      Platform.OS === "android" ? "android" : "ios",
+      secureWritesBuffered,
+    ),
     errorClassification: true,
   }),
   getSecurityCapabilities: (): SecurityCapabilities => ({