@okint-digital/okint-rn-storage 0.6.0

package/package.json

@@ -0,0 +1,74 @@
+{
+  "name": "@okint-digital/okint-rn-storage",
+  "version": "0.6.0",
+  "description": "Vanilla, pluggable React Native storage — one API over swappable backends: hardware Keystore/Keychain (secure), AES-encrypted blobs (encrypted), SQLite, SharedPreferences/UserDefaults (async), a synchronous fast store, or in-memory.",
+  "keywords": [
+    "react-native",
+    "storage",
+    "keystore",
+    "keychain",
+    "secure-storage",
+    "encrypted-storage",
+    "async-storage",
+    "mmkv-alternative",
+    "okint"
+  ],
+  "license": "MIT",
+  "author": "Okint Digital",
+  "homepage": "https://github.com/okint-digital/okint-rn-storage#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/okint-digital/okint-rn-storage.git"
+  },
+  "bugs": {
+    "url": "https://github.com/okint-digital/okint-rn-storage/issues"
+  },
+  "main": "lib/index.js",
+  "types": "lib/index.d.ts",
+  "react-native": "src/index.ts",
+  "source": "src/index.ts",
+  "files": [
+    "src",
+    "lib",
+    "android",
+    "ios",
+    "cpp",
+    "okint-rn-storage.podspec",
+    "react-native.config.js",
+    "README.md",
+    "LICENSE",
+    "!**/__tests__",
+    "!**/*.spec.ts"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "jest",
+    "lint": "eslint src",
+    "prepack": "npm run build"
+  },
+  "peerDependencies": {
+    "react": "*",
+    "react-native": "*"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.18.0",
+    "@types/jest": "^29.5.14",
+    "@types/node": "^22.10.0",
+    "@types/react": "^19.0.0",
+    "eslint": "^9.18.0",
+    "globals": "^15.14.0",
+    "jest": "^29.7.0",
+    "react": "^19.1.0",
+    "react-native": "^0.81.0",
+    "ts-jest": "^29.2.5",
+    "typescript": "^5.7.3",
+    "typescript-eslint": "^8.20.0"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/react-native.config.js

@@ -0,0 +1,15 @@
+// Autolinking descriptor for consuming apps.
+module.exports = {
+  dependency: {
+    platforms: {
+      android: {
+        sourceDir: 'android',
+        packageImportPath: 'import com.okint.rnstorage.OkintRnStoragePackage;',
+        packageInstance: 'new OkintRnStoragePackage()',
+      },
+      ios: {
+        podspecPath: __dirname + '/okint-rn-storage.podspec',
+      },
+    },
+  },
+};

package/src/backends/memory.ts

@@ -0,0 +1,35 @@
+import type { BackendKind, StorageBackend } from '../types';
+
+/**
+ * Pure-JS, in-process backend. Zero native dependencies. Data lives only for the
+ * lifetime of the instance — ideal for tests, ephemeral caches, and as a safe
+ * default before the native module is available.
+ */
+export class MemoryBackend implements StorageBackend {
+  readonly kind: BackendKind;
+  private readonly store = new Map<string, string>();
+
+  constructor(kind: BackendKind = 'memory') {
+    this.kind = kind;
+  }
+
+  async getString(key: string): Promise<string | null> {
+    return this.store.has(key) ? (this.store.get(key) as string) : null;
+  }
+
+  async setString(key: string, value: string): Promise<void> {
+    this.store.set(key, value);
+  }
+
+  async remove(key: string): Promise<void> {
+    this.store.delete(key);
+  }
+
+  async clear(): Promise<void> {
+    this.store.clear();
+  }
+
+  async keys(): Promise<string[]> {
+    return [...this.store.keys()];
+  }
+}

package/src/backends/native-backend.ts

@@ -0,0 +1,69 @@
+import type { NativeOkintStorage, NativeStoreKind, StorageBackend } from '../types';
+import { OkintStorageError } from '../errors';
+
+/**
+ * Backend that delegates to the native module. One class drives all four
+ * native-backed stores, selected by `kind`, which is forwarded to native as the
+ * `store` discriminator:
+ *   - `secure`    → hardware Keystore / Keychain
+ *   - `async`     → SharedPreferences / UserDefaults (plaintext)
+ *   - `encrypted` → AES-encrypted blobs, key in Keystore/Keychain (large values)
+ *   - `sqlite`    → SQLite-backed key/value
+ *
+ * The native module is injected (not imported here) so this file stays free of
+ * `react-native` and is unit-testable under plain Node with a fake bridge.
+ */
+export class NativeBackend implements StorageBackend {
+  constructor(
+    private readonly native: NativeOkintStorage,
+    private readonly service: string,
+    readonly kind: NativeStoreKind,
+  ) {}
+
+  async getString(key: string): Promise<string | null> {
+    try {
+      const v = await this.native.getItem(this.service, key, this.kind);
+      return v ?? null;
+    } catch (e) {
+      throw wrap(e, `get "${key}"`);
+    }
+  }
+
+  async setString(key: string, value: string): Promise<void> {
+    try {
+      await this.native.setItem(this.service, key, value, this.kind);
+    } catch (e) {
+      throw wrap(e, `set "${key}"`);
+    }
+  }
+
+  async remove(key: string): Promise<void> {
+    try {
+      await this.native.removeItem(this.service, key, this.kind);
+    } catch (e) {
+      throw wrap(e, `remove "${key}"`);
+    }
+  }
+
+  async clear(): Promise<void> {
+    try {
+      await this.native.clear(this.service, this.kind);
+    } catch (e) {
+      throw wrap(e, 'clear');
+    }
+  }
+
+  async keys(): Promise<string[]> {
+    try {
+      const ks = await this.native.getAllKeys(this.service, this.kind);
+      return ks ?? [];
+    } catch (e) {
+      throw wrap(e, 'keys');
+    }
+  }
+}
+
+function wrap(cause: unknown, op: string): OkintStorageError {
+  const msg = cause instanceof Error ? cause.message : String(cause);
+  return new OkintStorageError('NATIVE_ERROR', `Native storage failed during ${op}: ${msg}`, cause);
+}

package/src/errors.ts

@@ -0,0 +1,26 @@
+export type OkintStorageErrorCode =
+  | 'NATIVE_MODULE_MISSING'
+  | 'BACKEND_NOT_IMPLEMENTED'
+  | 'UNKNOWN_BACKEND'
+  | 'PARSE_ERROR'
+  | 'INVALID_VALUE'
+  | 'INVALID_NAMESPACE'
+  | 'INVALID_KEY'
+  | 'NATIVE_ERROR';
+
+/**
+ * Single error type for the whole package. Carries a stable `code` so callers
+ * can branch without string-matching messages.
+ */
+export class OkintStorageError extends Error {
+  readonly code: OkintStorageErrorCode;
+
+  constructor(code: OkintStorageErrorCode, message: string, cause?: unknown) {
+    // `cause` is carried by the native Error.cause (ES2022) — we don't redeclare it.
+    super(message, cause !== undefined ? { cause } : undefined);
+    this.name = 'OkintStorageError';
+    this.code = code;
+    // Restore prototype chain (TS targeting ES5/ES2015 class-extends-builtin caveat).
+    Object.setPrototypeOf(this, OkintStorageError.prototype);
+  }
+}

package/src/facade.ts

@@ -0,0 +1,118 @@
+import type { BackendKind, OkintStorage, StorageBackend } from './types';
+import {
+  assertKey,
+  assertStringValue,
+  fromJson,
+  numberToString,
+  stringToBoolean,
+  stringToNumber,
+  toJson,
+} from './validate';
+
+/**
+ * Wraps a low-level StorageBackend with ergonomic, typed accessors. All values
+ * are persisted as strings; the facade handles JSON / number / boolean
+ * (de)serialization, key validation, and typed errors.
+ *
+ * Every method is async and REJECTS (never throws synchronously) on validation
+ * errors, so callers can rely on a single error channel (.catch / try-await).
+ */
+export class StorageFacade implements OkintStorage {
+  constructor(private readonly impl: StorageBackend) {}
+
+  get backend(): BackendKind {
+    return this.impl.kind;
+  }
+
+  async getString(key: string): Promise<string | null> {
+    assertKey(key);
+    return this.impl.getString(key);
+  }
+
+  async setString(key: string, value: string): Promise<void> {
+    assertKey(key);
+    assertStringValue(value);
+    return this.impl.setString(key, value);
+  }
+
+  async getItem<T>(key: string): Promise<T | null> {
+    assertKey(key);
+    const raw = await this.impl.getString(key);
+    return raw == null ? null : fromJson<T>(key, raw);
+  }
+
+  async setItem<T>(key: string, value: T): Promise<void> {
+    assertKey(key);
+    return this.impl.setString(key, toJson(key, value));
+  }
+
+  async getNumber(key: string): Promise<number | null> {
+    assertKey(key);
+    const raw = await this.impl.getString(key);
+    return raw == null ? null : stringToNumber(raw);
+  }
+
+  async setNumber(key: string, value: number): Promise<void> {
+    assertKey(key);
+    return this.impl.setString(key, numberToString(key, value));
+  }
+
+  async getBoolean(key: string): Promise<boolean | null> {
+    assertKey(key);
+    const raw = await this.impl.getString(key);
+    return raw == null ? null : stringToBoolean(raw);
+  }
+
+  async setBoolean(key: string, value: boolean): Promise<void> {
+    assertKey(key);
+    return this.impl.setString(key, value ? 'true' : 'false');
+  }
+
+  async has(key: string): Promise<boolean> {
+    assertKey(key);
+    return (await this.impl.getString(key)) !== null;
+  }
+
+  async remove(key: string): Promise<void> {
+    assertKey(key);
+    return this.impl.remove(key);
+  }
+
+  clear(): Promise<void> {
+    return this.impl.clear();
+  }
+
+  keys(): Promise<string[]> {
+    return this.impl.keys();
+  }
+
+  async multiGet(keys: string[]): Promise<Record<string, string | null>> {
+    const out: Record<string, string | null> = {};
+    await Promise.all(
+      keys.map(async (k) => {
+        assertKey(k);
+        out[k] = await this.impl.getString(k);
+      }),
+    );
+    return out;
+  }
+
+  async multiSet(entries: Record<string, string>): Promise<void> {
+    await Promise.all(
+      Object.entries(entries).map(([k, v]) => {
+        assertKey(k);
+        assertStringValue(v);
+        return this.impl.setString(k, v);
+      }),
+    );
+  }
+
+  async multiRemove(keys: string[]): Promise<void> {
+    await Promise.all(
+      keys.map((k) => {
+        assertKey(k);
+        return this.impl.remove(k);
+      }),
+    );
+  }
+}

package/src/index.ts

@@ -0,0 +1,194 @@
+import type {
+  OkintStorage,
+  OkintStorageOptions,
+  StorageBackend,
+  BackendKind,
+  OkintSyncStorage,
+  OkintSyncStorageOptions,
+  SyncPersistence,
+} from './types';
+import { StorageFacade } from './facade';
+import { MemoryBackend } from './backends/memory';
+import { NativeBackend } from './backends/native-backend';
+import { OkintSyncStore } from './sync/sync-store';
+import { JSISyncStore } from './sync/jsi-store';
+import { MemorySyncPersistence, BackendSyncPersistence } from './sync/persistence';
+import { getNativeModule } from './native/bridge';
+import { getJSIStore } from './native/jsi';
+import { OkintStorageError } from './errors';
+import { normalizeNamespace } from './validate';
+
+const DEFAULT_NAMESPACE = 'okint';
+
+/**
+ * Create a storage instance bound to a backend + namespace.
+ *
+ * @example
+ *   const secure = createStorage({ backend: 'secure', namespace: 'auth' });
+ *   await secure.setString('refreshToken', token);   // hardware-encrypted
+ *
+ *   const cache = createStorage({ backend: 'memory' });
+ *   await cache.setItem('campaigns', list);
+ */
+export function createStorage(options: OkintStorageOptions): OkintStorage {
+  const namespace = normalizeNamespace(options.namespace, DEFAULT_NAMESPACE);
+  return new StorageFacade(resolveBackend(options.backend, namespace));
+}
+
+function resolveBackend(kind: BackendKind, namespace: string): StorageBackend {
+  switch (kind) {
+    case 'memory':
+      return new MemoryBackend('memory');
+    case 'secure':
+    case 'async':
+    case 'encrypted':
+    case 'sqlite':
+      return new NativeBackend(getNativeModule(), namespace, kind);
+    default:
+      throw new OkintStorageError('UNKNOWN_BACKEND', `Unknown storage backend "${String(kind)}".`);
+  }
+}
+
+/**
+ * Create a SYNCHRONOUS storage instance. Resolves once the snapshot is loaded;
+ * thereafter all get/set are synchronous. This is the MMKV-style store — use it
+ * for state persistence/rehydration, feature flags, and hot-path UI state.
+ *
+ * @example
+ *   const fast = await createSyncStorage({ backend: 'fast', namespace: 'app' });
+ *   fast.setBoolean('onboarded', true);          // sync write (persists in bg)
+ *   const onboarded = fast.getBoolean('onboarded'); // sync read
+ *   await fast.flush();                           // ensure durability (e.g. on background)
+ */
+// Sync stores are interned per (backend, namespace): two callers asking for the
+// same fast store get the SAME instance, so their in-memory snapshots can't
+// diverge and silently overwrite each other. The cached promise is evicted on
+// load failure so a later call can retry.
+const syncRegistry = new Map<string, Promise<OkintSyncStorage>>();
+
+export function createSyncStorage(options: OkintSyncStorageOptions): Promise<OkintSyncStorage> {
+  // Promise-returning factory → surface validation as a rejection, not a sync throw.
+  let namespace: string;
+  try {
+    namespace = normalizeNamespace(options.namespace, DEFAULT_NAMESPACE);
+  } catch (e) {
+    return Promise.reject(e);
+  }
+  const registryKey = `${options.backend}:${namespace}`;
+
+  const existing = syncRegistry.get(registryKey);
+  if (existing) return existing;
+
+  const built = buildSyncStore(options.backend, namespace);
+  syncRegistry.set(registryKey, built);
+  built.catch(() => syncRegistry.delete(registryKey));
+  return built;
+}
+
+// Synchronous, zero-load sync stores: hydrated in one blocking native call at
+// construction, then pure in-JS reads (maximum read performance). Interned per
+// (backend, namespace) like the async variant.
+const syncRegistrySync = new Map<string, OkintSyncStorage>();
+
+/**
+ * Create a synchronous storage instance WITHOUT an async load step. Hydrates the
+ * snapshot in a single blocking native bulk-read, then all get/set are
+ * synchronous in-JS-memory ops (writes persist in the background). Use this when
+ * you need state available immediately at startup (e.g. before first render).
+ *
+ * @example
+ *   const fast = createSyncStorageSync({ backend: 'fast', namespace: 'app' });
+ *   const onboarded = fast.getBoolean('onboarded'); // sync, zero-load
+ */
+export function createSyncStorageSync(options: OkintSyncStorageOptions): OkintSyncStorage {
+  const namespace = normalizeNamespace(options.namespace, DEFAULT_NAMESPACE);
+  const registryKey = `${options.backend}:${namespace}`;
+  const existing = syncRegistrySync.get(registryKey);
+  if (existing) return existing;
+
+  let store: OkintSyncStore;
+  switch (options.backend) {
+    case 'memory':
+      store = new OkintSyncStore('memory', new MemorySyncPersistence());
+      store.loadSync({});
+      break;
+    case 'fast': {
+      const native = getNativeModule();
+      const entries = native.getEntriesSync(namespace, 'async');
+      store = new OkintSyncStore('fast', new BackendSyncPersistence(new NativeBackend(native, namespace, 'async')));
+      store.loadSync(entries);
+      break;
+    }
+    default:
+      throw new OkintStorageError('UNKNOWN_BACKEND', `Unknown sync backend "${String(options.backend)}".`);
+  }
+  syncRegistrySync.set(registryKey, store);
+  return store;
+}
+
+// JSI stores are interned per namespace (one HostObject per logical store).
+const jsiRegistry = new Map<string, OkintSyncStorage>();
+
+/**
+ * Create a synchronous store backed by the C++/JSI engine — get/set go straight
+ * into C++ with no bridge serialization and no snapshot (maximum performance,
+ * zero JS memory overhead). Installs the native engine on first use; throws if
+ * the JSI runtime is unreachable (e.g. remote JS debugging) — fall back to
+ * `createSyncStorageSync` there.
+ *
+ * @example
+ *   const kv = createJSIStorage({ namespace: 'app' });
+ *   kv.setString('theme', 'dark');           // sync, in C++
+ *   const theme = kv.getString('theme');     // sync, in C++
+ */
+export function createJSIStorage(options: { namespace?: string } = {}): OkintSyncStorage {
+  const namespace = normalizeNamespace(options.namespace, DEFAULT_NAMESPACE);
+  const existing = jsiRegistry.get(namespace);
+  if (existing) return existing;
+  const store = new JSISyncStore(getJSIStore(getNativeModule(), namespace));
+  jsiRegistry.set(namespace, store);
+  return store;
+}
+
+async function buildSyncStore(
+  backend: OkintSyncStorageOptions['backend'],
+  namespace: string,
+): Promise<OkintSyncStorage> {
+  let persistence: SyncPersistence;
+  switch (backend) {
+    case 'memory':
+      persistence = new MemorySyncPersistence();
+      break;
+    case 'fast':
+      persistence = new BackendSyncPersistence(
+        new NativeBackend(getNativeModule(), namespace, 'async'),
+      );
+      break;
+    default:
+      throw new OkintStorageError('UNKNOWN_BACKEND', `Unknown sync backend "${String(backend)}".`);
+  }
+  const store = new OkintSyncStore(backend, persistence);
+  await store.load();
+  return store;
+}
+
+export { StorageFacade } from './facade';
+export { MemoryBackend } from './backends/memory';
+export { NativeBackend } from './backends/native-backend';
+export { OkintSyncStore } from './sync/sync-store';
+export { JSISyncStore } from './sync/jsi-store';
+export { MemorySyncPersistence, BackendSyncPersistence } from './sync/persistence';
+export { OkintStorageError } from './errors';
+export type { OkintStorageErrorCode } from './errors';
+export type {
+  OkintStorage,
+  OkintStorageOptions,
+  StorageBackend,
+  BackendKind,
+  NativeOkintStorage,
+  JSIStore,
+  OkintSyncStorage,
+  OkintSyncStorageOptions,
+  SyncBackendKind,
+  SyncPersistence,
+} from './types';

package/src/native/bridge.ts

@@ -0,0 +1,28 @@
+import { NativeModules } from 'react-native';
+import type { NativeOkintStorage } from '../types';
+import { OkintStorageError } from '../errors';
+
+/**
+ * Resolves the native module. This is the ONLY file that imports `react-native`,
+ * so the rest of the package (facade, backends, types) stays runtime-agnostic
+ * and unit-testable under Node.
+ *
+ * Uses the classic NativeModules registry (works on both the legacy and the New
+ * Architecture via the interop layer). If the module isn't present — e.g. the
+ * app wasn't rebuilt after install — we throw a clear, actionable error rather
+ * than failing deep in a call.
+ */
+export function getNativeModule(): NativeOkintStorage {
+  const mod = (NativeModules as Record<string, unknown>)['OkintRnStorage'] as
+    | NativeOkintStorage
+    | undefined;
+
+  if (!mod) {
+    throw new OkintStorageError(
+      'NATIVE_MODULE_MISSING',
+      "okint-rn-storage native module not found. Rebuild the app after install " +
+        "(pod install on iOS / gradle sync on Android), or use backend: 'memory'.",
+    );
+  }
+  return mod;
+}

package/src/native/jsi.ts

@@ -0,0 +1,37 @@
+import type { JSIStore, NativeOkintStorage } from '../types';
+import { OkintStorageError } from '../errors';
+
+const GLOBAL_FACTORY = '__okintCreateJSI';
+
+function factory(): ((namespace: string) => JSIStore) | undefined {
+  const g = globalThis as Record<string, unknown>;
+  const f = g[GLOBAL_FACTORY];
+  return typeof f === 'function' ? (f as (namespace: string) => JSIStore) : undefined;
+}
+
+let installed = false;
+
+/**
+ * Resolve a JSI HostObject store for `namespace`, installing the native C++
+ * engine on first use. Throws a clear error if the JSI runtime is unreachable
+ * (e.g. remote JS debugging) — callers should fall back to `createSyncStorageSync`.
+ */
+export function getJSIStore(native: NativeOkintStorage, namespace: string): JSIStore {
+  if (!installed && factory() === undefined) {
+    try {
+      native.installJSI();
+    } catch {
+      // fall through to the missing-engine error below
+    }
+  }
+  const create = factory();
+  if (create === undefined) {
+    throw new OkintStorageError(
+      'NATIVE_MODULE_MISSING',
+      'okint JSI engine is unavailable (remote JS debugging or unsupported runtime). ' +
+        'Use createSyncStorageSync for synchronous access instead.',
+    );
+  }
+  installed = true;
+  return create(namespace);
+}