@okint-digital/okint-rn-storage 0.6.0

package/src/sync/jsi-store.ts

@@ -0,0 +1,98 @@
+import type { JSIStore, OkintSyncStorage, SyncBackendKind } from '../types';
+import {
+  assertKey,
+  assertStringValue,
+  fromJson,
+  numberToString,
+  stringToBoolean,
+  stringToNumber,
+  toJson,
+} from '../validate';
+
+/**
+ * OkintSyncStorage backed by the C++/JSI HostObject. Reads and writes go
+ * straight into C++ with no bridge serialization and no snapshot — the
+ * maximum-performance synchronous path. Writes are persisted synchronously by
+ * the native engine, so `flush()` is a no-op.
+ */
+export class JSISyncStore implements OkintSyncStorage {
+  readonly backend: SyncBackendKind = 'fast';
+
+  constructor(private readonly store: JSIStore) {}
+
+  getString(key: string): string | null {
+    assertKey(key);
+    return this.store.getString(key);
+  }
+
+  setString(key: string, value: string): void {
+    assertKey(key);
+    assertStringValue(value);
+    this.store.setString(key, value);
+  }
+
+  getItem<T>(key: string): T | null {
+    const raw = this.getString(key);
+    return raw == null ? null : fromJson<T>(key, raw);
+  }
+
+  setItem<T>(key: string, value: T): void {
+    assertKey(key);
+    this.store.setString(key, toJson(key, value));
+  }
+
+  getNumber(key: string): number | null {
+    const raw = this.getString(key);
+    return raw == null ? null : stringToNumber(raw);
+  }
+
+  setNumber(key: string, value: number): void {
+    assertKey(key);
+    this.store.setString(key, numberToString(key, value));
+  }
+
+  getBoolean(key: string): boolean | null {
+    const raw = this.getString(key);
+    return raw == null ? null : stringToBoolean(raw);
+  }
+
+  setBoolean(key: string, value: boolean): void {
+    this.setString(key, value ? 'true' : 'false');
+  }
+
+  has(key: string): boolean {
+    assertKey(key);
+    return this.store.contains(key);
+  }
+
+  remove(key: string): void {
+    assertKey(key);
+    this.store.remove(key);
+  }
+
+  clear(): void {
+    this.store.clear();
+  }
+
+  keys(): string[] {
+    return this.store.getAllKeys();
+  }
+
+  multiGet(keys: string[]): Record<string, string | null> {
+    const out: Record<string, string | null> = {};
+    for (const k of keys) out[k] = this.getString(k);
+    return out;
+  }
+
+  multiSet(entries: Record<string, string>): void {
+    for (const [k, v] of Object.entries(entries)) this.setString(k, v);
+  }
+
+  multiRemove(keys: string[]): void {
+    for (const k of keys) this.remove(k);
+  }
+
+  async flush(): Promise<void> {
+    // The JSI engine persists synchronously on each write — nothing to flush.
+  }
+}

package/src/sync/persistence.ts

@@ -0,0 +1,47 @@
+import type { StorageBackend, SyncPersistence } from '../types';
+
+/** No-op persistence for the ephemeral `memory` sync store. */
+export class MemorySyncPersistence implements SyncPersistence {
+  async loadAll(): Promise<Record<string, string>> {
+    return {};
+  }
+  async persist(): Promise<void> {
+    /* nothing to persist */
+  }
+  async clearAll(): Promise<void> {
+    /* nothing to clear */
+  }
+}
+
+/**
+ * Persists a sync store to any async StorageBackend (e.g. the native plain
+ * store). Pure TS — takes the backend by injection, so it's testable in Node
+ * with a MemoryBackend standing in for native.
+ */
+export class BackendSyncPersistence implements SyncPersistence {
+  constructor(private readonly backend: StorageBackend) {}
+
+  async loadAll(): Promise<Record<string, string>> {
+    const keys = await this.backend.keys();
+    const out: Record<string, string> = {};
+    await Promise.all(
+      keys.map(async (k) => {
+        const v = await this.backend.getString(k);
+        if (v !== null) out[k] = v;
+      }),
+    );
+    return out;
+  }
+
+  async persist(key: string, value: string | null): Promise<void> {
+    if (value === null) {
+      await this.backend.remove(key);
+    } else {
+      await this.backend.setString(key, value);
+    }
+  }
+
+  async clearAll(): Promise<void> {
+    await this.backend.clear();
+  }
+}

package/src/sync/sync-store.ts

@@ -0,0 +1,186 @@
+import type { OkintSyncStorage, SyncBackendKind, SyncPersistence } from '../types';
+import { OkintStorageError } from '../errors';
+import {
+  assertKey,
+  assertStringValue,
+  fromJson,
+  numberToString,
+  stringToBoolean,
+  stringToNumber,
+  toJson,
+} from '../validate';
+
+/**
+ * Synchronous storage over an in-memory snapshot. After `load()`, every accessor
+ * is synchronous; writes update the map immediately and are persisted to the
+ * backing `SyncPersistence` in the background.
+ *
+ * Persistence is **coalesced**: a burst of writes collapses to the latest value
+ * per key and is drained once per microtask (bounded by the number of distinct
+ * dirty keys, not the number of writes). `flush()` awaits durability and
+ * surfaces any background failure.
+ */
+export class OkintSyncStore implements OkintSyncStorage {
+  readonly backend: SyncBackendKind;
+  private map = new Map<string, string>();
+  private loaded = false;
+
+  // Coalescing state.
+  private pending = new Map<string, string | null>(); // value === null → delete
+  private pendingClear = false;
+  private drainScheduled = false;
+  private chain: Promise<void> = Promise.resolve();
+  private persistErrors: unknown[] = [];
+
+  constructor(
+    backend: SyncBackendKind,
+    private readonly persistence: SyncPersistence,
+  ) {
+    this.backend = backend;
+  }
+
+  /** Load the snapshot. Idempotent — the factory calls it once; extra calls no-op. */
+  async load(): Promise<void> {
+    if (this.loaded) return;
+    const all = await this.persistence.loadAll();
+    this.map = new Map(Object.entries(all));
+    this.loaded = true;
+  }
+
+  /**
+   * Synchronous hydration (the zero-load path). Used by `createSyncStorageSync`
+   * after one blocking native bulk-read. Idempotent like `load()`.
+   */
+  loadSync(entries: Record<string, string>): void {
+    if (this.loaded) return;
+    this.map = new Map(Object.entries(entries));
+    this.loaded = true;
+  }
+
+  getString(key: string): string | null {
+    assertKey(key);
+    const v = this.map.get(key);
+    return v === undefined ? null : v;
+  }
+
+  setString(key: string, value: string): void {
+    assertKey(key);
+    assertStringValue(value);
+    this.map.set(key, value);
+    this.queueWrite(key, value);
+  }
+
+  getItem<T>(key: string): T | null {
+    const raw = this.getString(key);
+    return raw == null ? null : fromJson<T>(key, raw);
+  }
+
+  setItem<T>(key: string, value: T): void {
+    assertKey(key);
+    const json = toJson(key, value);
+    this.map.set(key, json);
+    this.queueWrite(key, json);
+  }
+
+  getNumber(key: string): number | null {
+    const raw = this.getString(key);
+    return raw == null ? null : stringToNumber(raw);
+  }
+
+  setNumber(key: string, value: number): void {
+    assertKey(key);
+    const s = numberToString(key, value);
+    this.map.set(key, s);
+    this.queueWrite(key, s);
+  }
+
+  getBoolean(key: string): boolean | null {
+    const raw = this.getString(key);
+    return raw == null ? null : stringToBoolean(raw);
+  }
+
+  setBoolean(key: string, value: boolean): void {
+    this.setString(key, value ? 'true' : 'false');
+  }
+
+  has(key: string): boolean {
+    assertKey(key);
+    return this.map.has(key);
+  }
+
+  remove(key: string): void {
+    assertKey(key);
+    this.map.delete(key);
+    this.queueWrite(key, null);
+  }
+
+  clear(): void {
+    this.map.clear();
+    this.pending.clear(); // superseded by the clear
+    this.pendingClear = true;
+    this.schedule();
+  }
+
+  keys(): string[] {
+    return [...this.map.keys()];
+  }
+
+  multiGet(keys: string[]): Record<string, string | null> {
+    const out: Record<string, string | null> = {};
+    for (const k of keys) out[k] = this.getString(k);
+    return out;
+  }
+
+  multiSet(entries: Record<string, string>): void {
+    for (const [k, v] of Object.entries(entries)) this.setString(k, v);
+  }
+
+  multiRemove(keys: string[]): void {
+    for (const k of keys) this.remove(k);
+  }
+
+  async flush(): Promise<void> {
+    if ((this.pending.size > 0 || this.pendingClear) && !this.drainScheduled) {
+      this.schedule();
+    }
+    await this.chain;
+    if (this.persistErrors.length > 0) {
+      const first = this.persistErrors[0];
+      const count = this.persistErrors.length;
+      this.persistErrors = [];
+      throw new OkintStorageError(
+        'NATIVE_ERROR',
+        `${count} background persist operation(s) failed.`,
+        first,
+      );
+    }
+  }
+
+  private queueWrite(key: string, value: string | null): void {
+    this.pending.set(key, value);
+    this.schedule();
+  }
+
+  private schedule(): void {
+    if (this.drainScheduled) return;
+    this.drainScheduled = true;
+    this.chain = this.chain.then(() => this.drain());
+  }
+
+  private async drain(): Promise<void> {
+    this.drainScheduled = false;
+    const doClear = this.pendingClear;
+    this.pendingClear = false;
+    const writes = this.pending;
+    this.pending = new Map();
+
+    try {
+      if (doClear) await this.persistence.clearAll();
+      for (const [key, value] of writes) {
+        await this.persistence.persist(key, value);
+      }
+    } catch (e) {
+      this.persistErrors.push(e);
+    }
+  }
+}

package/src/types.ts

@@ -0,0 +1,174 @@
+/**
+ * okint-rn-storage — public types.
+ *
+ * One async API, several swappable backends. Pick the backend per the data's
+ * needs: secrets → `secure` (hardware Keystore / Keychain); large hardware-
+ * encrypted blobs → `encrypted`; structured/large data → `sqlite`; plain data →
+ * `async`; ephemeral → `memory`.
+ */
+
+export type BackendKind = 'memory' | 'secure' | 'async' | 'encrypted' | 'sqlite';
+
+/** The native-backed stores (everything except the pure-JS `memory`). */
+export type NativeStoreKind = 'secure' | 'async' | 'encrypted' | 'sqlite';
+
+export interface OkintStorageOptions {
+  /** Which storage backend to use. */
+  backend: BackendKind;
+  /**
+   * Logical store name. Partitions data so two stores never collide. Maps to:
+   *   - secure  → Keychain service (iOS) / EncryptedSharedPreferences file (Android)
+   *   - async   → UserDefaults suite (iOS) / SharedPreferences file (Android)
+   *   - memory  → a private in-process Map
+   * Defaults to `'okint'`.
+   */
+  namespace?: string;
+}
+
+/**
+ * Low-level backend contract. Everything is async (the secure/native backends
+ * cross the bridge). Keys reaching a backend are already partitioned by
+ * namespace at construction, so backends store keys verbatim.
+ */
+export interface StorageBackend {
+  readonly kind: BackendKind;
+  getString(key: string): Promise<string | null>;
+  setString(key: string, value: string): Promise<void>;
+  remove(key: string): Promise<void>;
+  clear(): Promise<void>;
+  keys(): Promise<string[]>;
+}
+
+/**
+ * The storage instance returned by `createStorage`. Adds ergonomic typed
+ * accessors (JSON / number / boolean) on top of the raw string backend.
+ */
+export interface OkintStorage {
+  /** The backend kind backing this instance. */
+  readonly backend: BackendKind;
+
+  getString(key: string): Promise<string | null>;
+  setString(key: string, value: string): Promise<void>;
+
+  /** JSON-parsed read. Throws OkintStorageError('PARSE_ERROR') on malformed data. */
+  getItem<T>(key: string): Promise<T | null>;
+  /** JSON-stringified write. */
+  setItem<T>(key: string, value: T): Promise<void>;
+
+  getNumber(key: string): Promise<number | null>;
+  setNumber(key: string, value: number): Promise<void>;
+
+  getBoolean(key: string): Promise<boolean | null>;
+  setBoolean(key: string, value: boolean): Promise<void>;
+
+  has(key: string): Promise<boolean>;
+  remove(key: string): Promise<void>;
+  clear(): Promise<void>;
+  keys(): Promise<string[]>;
+
+  /** Batched string reads/writes/removes. */
+  multiGet(keys: string[]): Promise<Record<string, string | null>>;
+  multiSet(entries: Record<string, string>): Promise<void>;
+  multiRemove(keys: string[]): Promise<void>;
+}
+
+// ──────────────────────────────────────────────────────────────────────────
+// Synchronous stores (the MMKV-style use case)
+//
+// React Native's bridge is async, so true zero-latency sync needs JSI. Instead
+// of reinventing MMKV's C++, the `fast` store loads a snapshot once (async),
+// then serves get/set SYNCHRONOUSLY from memory while persisting writes in the
+// background. Covers the dominant sync need — persist/rehydrate, flags, cached
+// UI state — with no native risk. `memory` is ephemeral sync (no persistence).
+// ──────────────────────────────────────────────────────────────────────────
+
+export type SyncBackendKind = 'memory' | 'fast';
+
+export interface OkintSyncStorageOptions {
+  backend: SyncBackendKind;
+  /** Partitions the store (see OkintStorageOptions.namespace). Defaults to 'okint'. */
+  namespace?: string;
+}
+
+/**
+ * A synchronous storage instance. Obtained via `await createSyncStorage(...)`,
+ * which resolves only after the initial snapshot has loaded — so every method
+ * below is safe to call synchronously thereafter.
+ */
+export interface OkintSyncStorage {
+  readonly backend: SyncBackendKind;
+
+  getString(key: string): string | null;
+  setString(key: string, value: string): void;
+
+  getItem<T>(key: string): T | null;
+  setItem<T>(key: string, value: T): void;
+
+  getNumber(key: string): number | null;
+  setNumber(key: string, value: number): void;
+
+  getBoolean(key: string): boolean | null;
+  setBoolean(key: string, value: boolean): void;
+
+  has(key: string): boolean;
+  remove(key: string): void;
+  clear(): void;
+  keys(): string[];
+
+  /** Batched (synchronous) reads/writes/removes. */
+  multiGet(keys: string[]): Record<string, string | null>;
+  multiSet(entries: Record<string, string>): void;
+  multiRemove(keys: string[]): void;
+
+  /**
+   * Await pending background writes (the `fast` store persists asynchronously).
+   * Call on app background / before exit for guaranteed durability. Rejects if a
+   * background persist failed.
+   */
+  flush(): Promise<void>;
+}
+
+/** Persistence sink for sync stores. Snapshot load + per-key write-through. */
+export interface SyncPersistence {
+  loadAll(): Promise<Record<string, string>>;
+  /** value === null → delete the key. */
+  persist(key: string, value: string | null): Promise<void>;
+  clearAll(): Promise<void>;
+}
+
+/**
+ * Shape of the native module (Android/iOS). The JS layer talks to this; tests
+ * inject a fake implementation. `store` selects which native store to target.
+ */
+export interface NativeOkintStorage {
+  setItem(service: string, key: string, value: string, store: NativeStoreKind): Promise<void>;
+  getItem(service: string, key: string, store: NativeStoreKind): Promise<string | null>;
+  removeItem(service: string, key: string, store: NativeStoreKind): Promise<void>;
+  clear(service: string, store: NativeStoreKind): Promise<void>;
+  getAllKeys(service: string, store: NativeStoreKind): Promise<string[]>;
+  /**
+   * Synchronous bulk read (blocking bridge call) used by the zero-load sync
+   * store: it hydrates the in-memory snapshot in one shot at construction, so
+   * subsequent reads are pure in-JS Map lookups (no per-call bridge crossing).
+   */
+  getEntriesSync(service: string, store: NativeStoreKind): Record<string, string>;
+  /**
+   * Install the C++/JSI fast-path engine into the JS runtime (exposes
+   * `global.__okintCreateJSI`). Returns false if the runtime isn't reachable
+   * (e.g. remote JS debugging). Blocking-synchronous.
+   */
+  installJSI(): boolean;
+}
+
+/**
+ * The C++ JSI HostObject returned by `global.__okintCreateJSI(namespace)`.
+ * Every method is synchronous and crosses no bridge — the fastest path.
+ */
+export interface JSIStore {
+  getString(key: string): string | null;
+  setString(key: string, value: string): void;
+  remove(key: string): void;
+  clear(): void;
+  contains(key: string): boolean;
+  getAllKeys(): string[];
+}

package/src/validate.ts

@@ -0,0 +1,102 @@
+import { OkintStorageError } from './errors';
+
+/**
+ * Namespace becomes an Android SharedPreferences FILE NAME and an iOS Keychain
+ * service / UserDefaults suite. It must therefore be filename-safe — no path
+ * separators, `..`, NUL, or other characters that could traverse or collide.
+ * Restrict to a conservative charset.
+ */
+const NAMESPACE_RE = /^[A-Za-z0-9._-]{1,200}$/;
+
+const MAX_KEY_LENGTH = 1024;
+
+/** Validate + default the namespace. Throws on anything unsafe. */
+export function normalizeNamespace(ns: string | undefined, fallback: string): string {
+  const value = (typeof ns === 'string' ? ns.trim() : '') || fallback;
+  if (!NAMESPACE_RE.test(value)) {
+    throw new OkintStorageError(
+      'INVALID_NAMESPACE',
+      `Invalid namespace "${String(ns)}". Use only letters, digits, "." "-" "_" (1-200 chars).`,
+    );
+  }
+  return value;
+}
+
+/**
+ * Validate a key. Keys are stored verbatim (not used as filenames), so the rules
+ * are looser than namespaces — but must be a non-empty string free of control
+ * characters (NUL etc.), within a sane length.
+ */
+export function assertKey(key: string): void {
+  if (typeof key !== 'string' || key.length === 0) {
+    throw new OkintStorageError('INVALID_KEY', 'Key must be a non-empty string.');
+  }
+  if (key.length > MAX_KEY_LENGTH) {
+    throw new OkintStorageError('INVALID_KEY', `Key exceeds the ${MAX_KEY_LENGTH}-character limit.`);
+  }
+  for (let i = 0; i < key.length; i++) {
+    if (key.charCodeAt(i) < 0x20) {
+      throw new OkintStorageError('INVALID_KEY', 'Key must not contain control characters.');
+    }
+  }
+}
+
+/** Serialize a value to JSON, surfacing non-serializable inputs as a typed error. */
+export function toJson(key: string, value: unknown): string {
+  let json: string | undefined;
+  try {
+    json = JSON.stringify(value);
+  } catch (e) {
+    throw new OkintStorageError(
+      'INVALID_VALUE',
+      `Value for "${key}" is not JSON-serializable (circular reference or BigInt).`,
+      e,
+    );
+  }
+  if (json === undefined) {
+    throw new OkintStorageError(
+      'INVALID_VALUE',
+      `Value for "${key}" is not JSON-serializable (undefined, function, or symbol).`,
+    );
+  }
+  return json;
+}
+
+/** Parse JSON, surfacing malformed data as a typed error. */
+export function fromJson<T>(key: string, raw: string): T {
+  try {
+    return JSON.parse(raw) as T;
+  } catch (e) {
+    throw new OkintStorageError('PARSE_ERROR', `Stored value for "${key}" is not valid JSON.`, e);
+  }
+}
+
+/** Serialize a number, rejecting NaN/+-Infinity (which don't round-trip). */
+export function numberToString(key: string, value: number): string {
+  if (typeof value !== 'number' || !Number.isFinite(value)) {
+    throw new OkintStorageError(
+      'INVALID_VALUE',
+      `setNumber requires a finite number for "${key}" (got ${String(value)}). ` +
+        `For integers above 2^53 use setString to avoid precision loss.`,
+    );
+  }
+  return String(value);
+}
+
+/** Parse a stored number; non-numeric -> null. */
+export function stringToNumber(raw: string): number | null {
+  const n = Number(raw);
+  return Number.isFinite(n) ? n : null;
+}
+
+/** Strict boolean parse: only canonical 'true'/'false' map; anything else -> null. */
+export function stringToBoolean(raw: string): boolean | null {
+  return raw === 'true' ? true : raw === 'false' ? false : null;
+}
+
+/** Assert a raw value is a string (for setString / multiSet). */
+export function assertStringValue(value: unknown): asserts value is string {
+  if (typeof value !== 'string') {
+    throw new OkintStorageError('INVALID_VALUE', 'Value must be a string.');
+  }
+}