react-native-nitro-storage 0.4.5 → 0.5.0

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,217 @@
+# 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. |
+| `serialize(value)`             | Serialize a value with the item encoder.                    |
+| `deserialize(value)`           | Deserialize a raw string with the item decoder.             |
+
+## 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:`.                               |
+| `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.                                             |
+| `import(data, scope)`              | Bulk import raw strings.                                      |
+
+Raw string APIs bypass item serialization and validation. Prefer `StorageItem<T>` unless you are migrating, importing, or writing a custom integration.
+
+## 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`
+- `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,186 @@
+# 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.
+
+## Batch Removes
+
+```ts
+import { removeBatch, StorageScope } from "react-native-nitro-storage";
+
+removeBatch([themeItem, localeItem], StorageScope.Disk);
+```
+
+## Raw Import
+
+`storage.import(data, scope)` writes raw strings. It does not serialize values.
+
+```ts
+import { storage, StorageScope } from "react-native-nitro-storage";
+
+storage.import(
+  {
+    "flags:newOnboarding": "true",
+    "flags:paywall": "control",
+  },
+  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.
+
+## 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).

package/docs/react-hooks.md

@@ -0,0 +1,113 @@
+# React Hooks
+
+Nitro Storage hooks connect a `StorageItem<T>` to React with `useSyncExternalStore`. No provider is needed, and the same item can also be used outside React.
+
+Keep storage items at module scope. Creating items during render creates new subscriptions and breaks cache reuse.
+
+## useStorage
+
+Use `useStorage(item)` when a component both reads and writes the full value.
+
+```tsx
+import {
+  createStorageItem,
+  StorageScope,
+  useStorage,
+} from "react-native-nitro-storage";
+
+const themeItem = createStorageItem({
+  key: "theme",
+  scope: StorageScope.Disk,
+  defaultValue: "system",
+});
+
+export function ThemeToggle() {
+  const [theme, setTheme] = useStorage(themeItem);
+
+  return (
+    <Button
+      title={theme}
+      onPress={() => setTheme(theme === "dark" ? "light" : "dark")}
+    />
+  );
+}
+```
+
+Updater functions read the current stored value first:
+
+```ts
+const countItem = createStorageItem({
+  key: "count",
+  scope: StorageScope.Memory,
+  defaultValue: 0,
+});
+
+const [, setCount] = useStorage(countItem);
+setCount((current) => current + 1);
+```
+
+Direct `set(value)` writes do not read the current value first.
+
+## useStorageSelector
+
+Use `useStorageSelector(item, selector, isEqual?)` when the stored value is larger than what the component renders.
+
+```tsx
+type Profile = {
+  name: string;
+  email: string;
+  plan: "free" | "pro";
+};
+
+const profileItem = createStorageItem<Profile>({
+  key: "profile",
+  scope: StorageScope.Disk,
+  defaultValue: { name: "", email: "", plan: "free" },
+});
+
+export function PlanBadge() {
+  const [plan] = useStorageSelector(profileItem, (profile) => profile.plan);
+  return <Text>{plan}</Text>;
+}
+```
+
+Pass a custom equality function when the selector returns an object:
+
+```ts
+const [contact] = useStorageSelector(
+  profileItem,
+  (profile) => ({ name: profile.name, email: profile.email }),
+  (prev, next) => prev.name === next.name && prev.email === next.email,
+);
+```
+
+## useSetStorage
+
+Use `useSetStorage(item)` for controls that write without rendering from the value.
+
+```tsx
+const dismissItem = createStorageItem({
+  key: "welcomeDismissed",
+  scope: StorageScope.Disk,
+  defaultValue: false,
+});
+
+export function DismissWelcomeButton() {
+  const setDismissed = useSetStorage(dismissItem);
+  return <Button title="Dismiss" onPress={() => setDismissed(true)} />;
+}
+```
+
+## Subscribe Outside React
+
+Every item has a low-level subscription API:
+
+```ts
+const unsubscribe = themeItem.subscribe(() => {
+  analytics.track("theme_changed", { theme: themeItem.get() });
+});
+
+unsubscribe();
+```
+
+Subscriptions fire after item writes and after TTL expiry is detected during a read.