react-native-nitro-storage 0.4.5 → 0.5.1

package/SECURITY.md

@@ -0,0 +1,26 @@
+# Security Policy
+
+## Supported Versions
+
+Security fixes are shipped for the latest published `0.x` release line.
+
+| Version | Supported |
+| ------- | --------- |
+| `0.5.x` | Yes       |
+| `<0.5`  | No        |
+
+## Reporting a Vulnerability
+
+Report security issues through GitHub Security Advisories with:
+
+- affected package version
+- platform and OS version
+- React Native and `react-native-nitro-modules` versions
+- reproduction steps
+- whether the issue affects Memory, Disk, Secure, biometric storage, web backends, or packaging
+
+Do not publish proof-of-concept exploit details until a fix is available.
+
+## Storage Boundary
+
+Native Secure scope delegates encryption to platform storage APIs: iOS Keychain and Android Jetpack Security `EncryptedSharedPreferences`. Web Secure scope is API-compatible but defaults to namespaced `localStorage`; use a custom web secure backend when browser-side storage must meet a stricter threat model.

package/docs/api-reference.md

@@ -0,0 +1,281 @@
+# API Reference
+
+This page lists the public API surface. For copy-ready workflows, see [recipes.md](recipes.md).
+
+## createStorageItem
+
+```ts
+const item = createStorageItem<T>({
+  key: "theme",
+  scope: StorageScope.Disk,
+  defaultValue: "system",
+});
+```
+
+`StorageItemConfig<T>`:
+
+| Field                  | Type                             | Purpose                                                          |
+| ---------------------- | -------------------------------- | ---------------------------------------------------------------- |
+| `key`                  | `string`                         | Storage key. Combined with `namespace` when provided.            |
+| `scope`                | `StorageScope`                   | Memory, Disk, or Secure.                                         |
+| `defaultValue`         | `T`                              | Value returned when no stored value exists.                      |
+| `serialize`            | `(value: T) => string`           | Custom string encoder. Defaults to primitive/JSON serialization. |
+| `deserialize`          | `(value: string) => T`           | Custom string decoder.                                           |
+| `validate`             | `(value: unknown) => value is T` | Runtime guard for stored data.                                   |
+| `onValidationError`    | `(invalidValue: unknown) => T`   | Replacement value when validation fails.                         |
+| `expiration`           | `{ ttlMs: number }`              | Time-to-live for the value.                                      |
+| `onExpired`            | `(key: string) => void`          | Called when a read detects TTL expiry.                           |
+| `readCache`            | `boolean`                        | Cache parsed values in memory.                                   |
+| `coalesceDiskWrites`   | `boolean`                        | Buffer Disk writes until the next flush.                         |
+| `coalesceSecureWrites` | `boolean`                        | Buffer Secure writes until the next flush.                       |
+| `namespace`            | `string`                         | Prefix keys as `namespace:key`.                                  |
+| `biometric`            | `boolean`                        | Store through biometric secure storage.                          |
+| `biometricLevel`       | `BiometricLevel`                 | Require biometric/passcode or biometric-only access.             |
+| `accessControl`        | `AccessControl`                  | Platform secure accessibility setting.                           |
+
+`StorageItem<T>`:
+
+| Method                         | Purpose                                                     |
+| ------------------------------ | ----------------------------------------------------------- |
+| `get()`                        | Return the typed value or the default value.                |
+| `getWithVersion()`             | Return `{ value, version }` for optimistic writes.          |
+| `set(value)`                   | Store a value. Accepts direct values or updater functions.  |
+| `setIfVersion(version, value)` | Store only when the current version still matches.          |
+| `delete()`                     | Remove the key.                                             |
+| `has()`                        | Check whether the key exists.                               |
+| `subscribe(callback)`          | Subscribe to item changes. Returns an unsubscribe function. |
+| `subscribeSelector(...)`       | Subscribe to a selected value with an equality check.       |
+| `serialize(value)`             | Serialize a value with the item encoder.                    |
+| `deserialize(value)`           | Deserialize a raw string with the item decoder.             |
+
+```ts
+const unsubscribe = profileItem.subscribeSelector(
+  (profile) => profile.name,
+  (name, previousName) => {
+    console.log("Profile name changed", { name, previousName });
+  },
+  { fireImmediately: true },
+);
+```
+
+## React Hooks
+
+```ts
+const [value, setValue] = useStorage(item);
+const [selected, setItem] = useStorageSelector(item, selector, isEqual);
+const setOnly = useSetStorage(item);
+```
+
+See [react-hooks.md](react-hooks.md).
+
+## storage
+
+`storage` exposes raw and cross-item utilities:
+
+| Method                                           | Purpose                                                       |
+| ------------------------------------------------ | ------------------------------------------------------------- |
+| `clear(scope)`                                   | Clear one scope.                                              |
+| `clearAll()`                                     | Clear Memory, Disk, and Secure scopes.                        |
+| `clearNamespace(namespace, scope)`               | Remove keys under `namespace:`.                               |
+| `subscribe(scope, listener)`                     | Subscribe to raw scope-level change events.                   |
+| `subscribeKey(scope, key, listener)`             | Subscribe to raw events for one key.                          |
+| `subscribePrefix(scope, prefix, listener)`       | Subscribe to raw events for matching key prefixes.            |
+| `subscribeNamespace(namespace, scope, listener)` | Subscribe to raw events for `namespace:` keys.                |
+| `setEventObserver(observer)`                     | Receive all change events for devtools or logging.            |
+| `clearBiometric()`                               | Clear biometric Secure entries.                               |
+| `has(key, scope)`                                | Check for a raw key.                                          |
+| `getAllKeys(scope)`                              | List raw keys.                                                |
+| `getKeysByPrefix(prefix, scope)`                 | List raw keys with a prefix.                                  |
+| `getByPrefix(prefix, scope)`                     | Read raw string values by prefix.                             |
+| `getAll(scope)`                                  | Read all raw string values in a scope.                        |
+| `size(scope)`                                    | Return approximate scope entry count.                         |
+| `setAccessControl(accessControl)`                | Set the default Secure access control level.                  |
+| `setSecureWritesAsync(enabled)`                  | Toggle Android secure writes between sync and async modes.    |
+| `setDiskWritesAsync(enabled)`                    | Toggle coalesced Disk write behavior.                         |
+| `flushDiskWrites()`                              | Flush pending Disk writes.                                    |
+| `flushSecureWrites()`                            | Flush pending Secure writes.                                  |
+| `setKeychainAccessGroup(group)`                  | Configure iOS Keychain access group.                          |
+| `setMetricsObserver(observer)`                   | Receive operation timing events.                              |
+| `getMetricsSnapshot()`                           | Read aggregated metrics.                                      |
+| `resetMetrics()`                                 | Clear metrics counters.                                       |
+| `getCapabilities()`                              | Read runtime storage capabilities.                            |
+| `getSecurityCapabilities()`                      | Read secure backend capability metadata.                      |
+| `getSecureMetadata(key)`                         | Read secure metadata for one key without returning its value. |
+| `getAllSecureMetadata()`                         | Read secure metadata for all secure keys without values.      |
+| `getString(key, scope)`                          | Read a raw string.                                            |
+| `setString(key, value, scope)`                   | Write a raw string.                                           |
+| `deleteString(key, scope)`                       | Remove a raw key.                                             |
+| `export(scope)`                                  | Snapshot raw strings from one scope.                          |
+| `import(data, scope)`                            | Bulk import raw strings.                                      |
+
+Raw string APIs bypass item serialization and validation. Prefer `StorageItem<T>` unless you are migrating, exporting/importing, or writing a custom integration.
+
+```ts
+const diskSnapshot = storage.export(StorageScope.Disk);
+storage.import(diskSnapshot, StorageScope.Disk);
+```
+
+Secure exports contain raw secret values. Do not log `storage.export(StorageScope.Secure)` output or attach it to diagnostics, analytics, crash reports, or support bundles.
+
+## Event Subscriptions
+
+Use raw subscriptions when integrating Nitro Storage with state managers, sync engines, debug tooling, or non-React code.
+
+```ts
+const unsubscribe = storage.subscribeNamespace(
+  "auth",
+  StorageScope.Secure,
+  (event) => {
+    if (event.type === "batch") {
+      console.log(
+        "Auth keys changed",
+        event.changes.map((change) => change.key),
+      );
+      return;
+    }
+
+    console.log("Auth key changed", event.key, event.operation);
+  },
+);
+```
+
+For whole-app debug tooling, install one observer:
+
+```ts
+storage.setEventObserver((event) => {
+  if (event.scope !== StorageScope.Secure) {
+    console.log(event);
+  }
+});
+```
+
+Local batch APIs emit one `type: "batch"` envelope to scope and prefix/namespace listeners. Key subscribers receive the matching per-key change so direct key integrations do not need to unpack batch envelopes. Secure events can include raw secret values; do not log Secure event payloads in production.
+
+## Batch Operations
+
+```ts
+const values = getBatch([themeItem, localeItem], StorageScope.Disk);
+
+setBatch(
+  [
+    { item: themeItem, value: "dark" },
+    { item: localeItem, value: "en-US" },
+  ],
+  StorageScope.Disk,
+);
+
+removeBatch([themeItem, localeItem], StorageScope.Disk);
+```
+
+See [batch-transactions-migrations.md](batch-transactions-migrations.md).
+
+## Transactions
+
+```ts
+runTransaction(StorageScope.Disk, (tx) => {
+  const current = tx.getItem(balanceItem);
+  tx.setItem(balanceItem, current + 10);
+});
+```
+
+If the callback throws, previously changed keys in that transaction are rolled back synchronously.
+
+## Migrations
+
+```ts
+registerMigration(2, (ctx) => {
+  const oldTheme = ctx.getRaw("theme");
+  if (oldTheme === "black") {
+    ctx.setRaw("theme", "dark");
+  }
+});
+
+migrateToLatest(StorageScope.Disk);
+```
+
+Migration versions are tracked per scope.
+
+## Secure Auth Storage
+
+```ts
+const auth = createSecureAuthStorage({
+  accessToken: { ttlMs: 15 * 60 * 1000 },
+  refreshToken: { accessControl: AccessControl.AfterFirstUnlockThisDeviceOnly },
+});
+
+auth.accessToken.set("token");
+```
+
+The returned object is a typed record of secure string `StorageItem`s.
+
+## Web Backend APIs
+
+```ts
+setWebDiskStorageBackend(backend);
+getWebDiskStorageBackend();
+setWebSecureStorageBackend(backend);
+getWebSecureStorageBackend();
+await flushWebStorageBackends();
+```
+
+See [web-backends.md](web-backends.md).
+
+## Enums
+
+```ts
+enum StorageScope {
+  Memory = 0,
+  Disk = 1,
+  Secure = 2,
+}
+
+enum BiometricLevel {
+  None = 0,
+  BiometryOrPasscode = 1,
+  BiometryOnly = 2,
+}
+```
+
+`AccessControl` values:
+
+- `WhenUnlocked`
+- `AfterFirstUnlock`
+- `WhenPasscodeSetThisDeviceOnly`
+- `WhenUnlockedThisDeviceOnly`
+- `AfterFirstUnlockThisDeviceOnly`
+
+## Exported Types
+
+Common public types:
+
+- `Storage`
+- `Validator<T>`
+- `ExpirationConfig`
+- `StorageItem<T>`
+- `StorageItemConfig<T>`
+- `StorageBatchSetItem<T>`
+- `StorageVersion`
+- `VersionedValue<T>`
+- `StorageMetricsEvent`
+- `StorageMetricsObserver`
+- `StorageMetricSummary`
+- `StorageChangeEvent`
+- `StorageKeyChangeEvent`
+- `StorageBatchChangeEvent`
+- `StorageChangeOperation`
+- `StorageChangeSource`
+- `StorageEventListener`
+- `MigrationContext`
+- `Migration`
+- `TransactionContext`
+- `SecureAuthStorageConfig<K>`
+- `SecurityCapabilities`
+- `SecureStorageMetadata`
+- `StorageErrorCode`
+- `WebStorageBackend`
+- `WebDiskStorageBackend`
+- `WebSecureStorageBackend`
+- `WebStorageChangeEvent`
+- `WebStorageScope`
+
+The IndexedDB subpath exports `createIndexedDBBackend()` and `IndexedDBBackendOptions`.

package/docs/batch-transactions-migrations.md

@@ -0,0 +1,200 @@
+# Batch, Transactions, and Migrations
+
+Use these APIs when a workflow touches several keys or needs a controlled upgrade path.
+
+## Batch Reads
+
+```ts
+import {
+  createStorageItem,
+  getBatch,
+  StorageScope,
+} from "react-native-nitro-storage";
+
+const themeItem = createStorageItem({
+  key: "theme",
+  scope: StorageScope.Disk,
+  defaultValue: "system",
+});
+
+const localeItem = createStorageItem({
+  key: "locale",
+  scope: StorageScope.Disk,
+  defaultValue: "en-US",
+});
+
+const [theme, locale] = getBatch([themeItem, localeItem], StorageScope.Disk);
+```
+
+All items in a batch must use the same scope.
+
+## Batch Writes
+
+```ts
+import { setBatch, StorageScope } from "react-native-nitro-storage";
+
+setBatch(
+  [
+    { item: themeItem, value: "dark" },
+    { item: localeItem, value: "pt-BR" },
+  ],
+  StorageScope.Disk,
+);
+```
+
+Memory-scope batch writes are two-phase: all values are written first, then listeners are notified. Items with validation or TTL fall back to per-item writes so those rules still run.
+
+Scope and prefix subscriptions receive one batch event for raw batch writes and removes:
+
+```ts
+const unsubscribe = storage.subscribePrefix(
+  StorageScope.Disk,
+  "settings:",
+  (event) => {
+    if (event.type === "batch") {
+      event.changes.forEach((change) => {
+        console.log(change.key, change.operation);
+      });
+    }
+  },
+);
+```
+
+## Batch Removes
+
+```ts
+import { removeBatch, StorageScope } from "react-native-nitro-storage";
+
+removeBatch([themeItem, localeItem], StorageScope.Disk);
+```
+
+## Raw Import and Export
+
+`storage.export(scope)` returns raw strings, and `storage.import(data, scope)` writes raw strings. These APIs do not serialize values.
+
+```ts
+import { storage, StorageScope } from "react-native-nitro-storage";
+
+const snapshot = storage.export(StorageScope.Disk);
+
+storage.import(snapshot, StorageScope.Disk);
+```
+
+For Memory scope, import is atomic: all keys are written before listeners fire. For Disk and Secure, import delegates to native or web batch paths.
+
+Secure exports contain raw secret values. Do not log them or include them in diagnostics, analytics, crash reports, or support bundles.
+
+## Transactions
+
+Use `runTransaction(scope, callback)` when several raw or item writes should roll back together if the callback throws.
+
+```ts
+import { runTransaction, StorageScope } from "react-native-nitro-storage";
+
+const fromBalanceItem = createStorageItem({
+  key: "account:from",
+  scope: StorageScope.Disk,
+  defaultValue: 100,
+});
+
+const toBalanceItem = createStorageItem({
+  key: "account:to",
+  scope: StorageScope.Disk,
+  defaultValue: 0,
+});
+
+runTransaction(StorageScope.Disk, (tx) => {
+  const from = tx.getItem(fromBalanceItem);
+
+  if (from < 25) {
+    throw new Error("Insufficient balance");
+  }
+
+  tx.setItem(fromBalanceItem, from - 25);
+  tx.setItem(toBalanceItem, tx.getItem(toBalanceItem) + 25);
+});
+```
+
+Transaction context methods:
+
+- `getRaw(key)`
+- `setRaw(key, value)`
+- `removeRaw(key)`
+- `getItem(item)`
+- `setItem(item, value)`
+- `removeItem(item)`
+
+If the callback throws, Nitro Storage restores the keys it changed during that transaction.
+
+## Migrations
+
+Register migrations with monotonically increasing versions, then migrate a scope to the latest known version.
+
+```ts
+import {
+  migrateToLatest,
+  registerMigration,
+  StorageScope,
+} from "react-native-nitro-storage";
+
+registerMigration(1, (ctx) => {
+  const oldValue = ctx.getRaw("theme");
+  if (oldValue === "black") {
+    ctx.setRaw("theme", "dark");
+  }
+});
+
+registerMigration(2, (ctx) => {
+  const token = ctx.getRaw("token");
+  if (token) {
+    ctx.setRaw("auth:accessToken", token);
+    ctx.removeRaw("token");
+  }
+});
+
+migrateToLatest(StorageScope.Disk);
+```
+
+Migration context methods work with raw strings. Use item serializers manually when migrating structured data.
+
+```ts
+registerMigration(3, (ctx) => {
+  const raw = ctx.getRaw("settings");
+  if (!raw) {
+    return;
+  }
+
+  const settings = JSON.parse(raw) as { mode?: string };
+  ctx.setRaw(
+    "settings",
+    JSON.stringify({
+      ...settings,
+      theme: settings.mode ?? "system",
+    }),
+  );
+});
+```
+
+## Prefix Queries and Cleanup
+
+```ts
+const keys = storage.getKeysByPrefix("tenant:42:", StorageScope.Disk);
+const values = storage.getByPrefix("tenant:42:", StorageScope.Disk);
+
+storage.clearNamespace("tenant:42", StorageScope.Disk);
+```
+
+Use namespaces for multi-account or tenant-specific state so cleanup is predictable.
+
+## Optimistic Versioned Writes
+
+```ts
+const current = themeItem.getWithVersion();
+
+const didWrite = themeItem.setIfVersion(
+  current.version,
+  current.value === "dark" ? "light" : "dark",
+);
+```
+
+`setIfVersion()` returns `false` if another write changed the item after `getWithVersion()`.

package/docs/benchmarks.md

@@ -0,0 +1,37 @@
+# Benchmarks
+
+Benchmarks are release checks, not product promises. Use them to catch regressions on the local machine and CI image used by this repo.
+
+Run:
+
+```sh
+bun run benchmark -- --filter=react-native-nitro-storage
+```
+
+The benchmark script checks representative synchronous read/write paths and fails when results drift beyond the configured threshold.
+
+## Interpreting Results
+
+- Compare results on the same machine and Node/Bun version.
+- Treat large deltas as a prompt to inspect recent storage-runtime, serialization, native bridge, or cache changes.
+- Do not compare web backend numbers against native secure storage numbers; they measure different systems.
+- Secure storage performance depends on platform state, device lock state, biometric prompts, and Keystore/Keychain behavior.
+
+## Release Checklist
+
+Before publishing:
+
+```sh
+bun run lint -- --filter=react-native-nitro-storage
+bun run format:check -- --filter=react-native-nitro-storage
+bun run typecheck -- --filter=react-native-nitro-storage
+bun run test:types -- --filter=react-native-nitro-storage
+bun run test -- --filter=react-native-nitro-storage
+bun run test:cpp -- --filter=react-native-nitro-storage
+bun run build -- --filter=react-native-nitro-storage
+bun run benchmark -- --filter=react-native-nitro-storage
+bun run --cwd packages/react-native-nitro-storage check:pack
+npm publish --dry-run
+```
+
+Keep the dry-publish output in the release notes when validating a version locally.

package/docs/mmkv-migration.md

@@ -0,0 +1,80 @@
+# MMKV Migration
+
+Use `migrateFromMMKV(mmkv, item, deleteAfterMigration?)` when an app already stores values with `react-native-mmkv` and you want to move one key at a time into Nitro Storage.
+
+The helper reads in this order:
+
+1. `mmkv.getString(key)`
+2. `mmkv.getNumber(key)`
+3. `mmkv.getBoolean(key)`
+
+It writes through `item.set()`, so custom serialization, validation, TTL behavior, and listeners remain active.
+
+## Basic Migration
+
+```ts
+import {
+  createStorageItem,
+  migrateFromMMKV,
+  StorageScope,
+} from "react-native-nitro-storage";
+import { MMKV } from "react-native-mmkv";
+
+const mmkv = new MMKV();
+
+const usernameItem = createStorageItem({
+  key: "username",
+  scope: StorageScope.Disk,
+  defaultValue: "",
+});
+
+const migrated = migrateFromMMKV(mmkv, usernameItem, true);
+```
+
+`migrated` is `true` when a value was found and written. The third argument deletes the MMKV key after a successful write.
+
+## Type Conversion
+
+MMKV numbers and booleans are converted through the target item's serializer.
+
+```ts
+const launchCountItem = createStorageItem({
+  key: "launchCount",
+  scope: StorageScope.Disk,
+  defaultValue: 0,
+});
+
+migrateFromMMKV(mmkv, launchCountItem, true);
+```
+
+## Custom Serialized Values
+
+```ts
+type Settings = {
+  compactMode: boolean;
+};
+
+const settingsItem = createStorageItem<Settings>({
+  key: "settings",
+  scope: StorageScope.Disk,
+  defaultValue: { compactMode: false },
+  serialize: JSON.stringify,
+  deserialize: JSON.parse,
+  validate: (value): value is Settings =>
+    typeof value === "object" &&
+    value !== null &&
+    "compactMode" in value &&
+    typeof value.compactMode === "boolean",
+});
+
+migrateFromMMKV(mmkv, settingsItem, true);
+```
+
+## Migration Strategy
+
+- Migrate stable keys first: preferences, feature flags, and local settings.
+- Keep secure credentials in Secure scope instead of moving them to Disk scope.
+- Run migration once during startup, before components read the target item.
+- Delete the MMKV key only after you have shipped and observed the migration path.
+
+For larger data-shape upgrades, use the versioned migration APIs in [batch-transactions-migrations.md](batch-transactions-migrations.md).