@okint-digital/okint-rn-storage 0.6.0

package/ios/OkintRnStorageJSI.mm

@@ -0,0 +1,24 @@
+#import <Foundation/Foundation.h>
+#import <React/RCTBridge.h>
+#import <React/RCTBridge+Private.h>
+#import <jsi/jsi.h>
+
+#import "OkintJSI.h"
+
+/**
+ * Installs the okint C++/JSI engine into the bridge's JS runtime. Isolated in an
+ * Obj-C++ (.mm) file so the main Obj-C module stays free of C++.
+ */
+BOOL OkintInstallJSIForBridge(RCTBridge *bridge) {
+  RCTCxxBridge *cxxBridge = (RCTCxxBridge *)bridge;
+  if (cxxBridge == nil || ![cxxBridge respondsToSelector:@selector(runtime)]) {
+    return NO;
+  }
+  void *runtimePtr = cxxBridge.runtime;
+  if (runtimePtr == NULL) {
+    return NO;
+  }
+  NSString *dir = NSSearchPathForDirectoriesInDomains(NSLibraryDirectory, NSUserDomainMask, YES).firstObject;
+  okint::install(*reinterpret_cast<facebook::jsi::Runtime *>(runtimePtr), std::string([dir UTF8String]));
+  return YES;
+}

package/lib/backends/memory.d.ts

@@ -0,0 +1,16 @@
+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 declare class MemoryBackend implements StorageBackend {
+    readonly kind: BackendKind;
+    private readonly store;
+    constructor(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[]>;
+}

package/lib/backends/memory.js

@@ -0,0 +1,31 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MemoryBackend = void 0;
+/**
+ * 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.
+ */
+class MemoryBackend {
+    kind;
+    store = new Map();
+    constructor(kind = 'memory') {
+        this.kind = kind;
+    }
+    async getString(key) {
+        return this.store.has(key) ? this.store.get(key) : null;
+    }
+    async setString(key, value) {
+        this.store.set(key, value);
+    }
+    async remove(key) {
+        this.store.delete(key);
+    }
+    async clear() {
+        this.store.clear();
+    }
+    async keys() {
+        return [...this.store.keys()];
+    }
+}
+exports.MemoryBackend = MemoryBackend;

package/lib/backends/native-backend.d.ts

@@ -0,0 +1,24 @@
+import type { NativeOkintStorage, NativeStoreKind, StorageBackend } from '../types';
+/**
+ * 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 declare class NativeBackend implements StorageBackend {
+    private readonly native;
+    private readonly service;
+    readonly kind: NativeStoreKind;
+    constructor(native: NativeOkintStorage, service: string, kind: NativeStoreKind);
+    getString(key: string): Promise<string | null>;
+    setString(key: string, value: string): Promise<void>;
+    remove(key: string): Promise<void>;
+    clear(): Promise<void>;
+    keys(): Promise<string[]>;
+}

package/lib/backends/native-backend.js

@@ -0,0 +1,73 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NativeBackend = void 0;
+const errors_1 = require("../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.
+ */
+class NativeBackend {
+    native;
+    service;
+    kind;
+    constructor(native, service, kind) {
+        this.native = native;
+        this.service = service;
+        this.kind = kind;
+    }
+    async getString(key) {
+        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, value) {
+        try {
+            await this.native.setItem(this.service, key, value, this.kind);
+        }
+        catch (e) {
+            throw wrap(e, `set "${key}"`);
+        }
+    }
+    async remove(key) {
+        try {
+            await this.native.removeItem(this.service, key, this.kind);
+        }
+        catch (e) {
+            throw wrap(e, `remove "${key}"`);
+        }
+    }
+    async clear() {
+        try {
+            await this.native.clear(this.service, this.kind);
+        }
+        catch (e) {
+            throw wrap(e, 'clear');
+        }
+    }
+    async keys() {
+        try {
+            const ks = await this.native.getAllKeys(this.service, this.kind);
+            return ks ?? [];
+        }
+        catch (e) {
+            throw wrap(e, 'keys');
+        }
+    }
+}
+exports.NativeBackend = NativeBackend;
+function wrap(cause, op) {
+    const msg = cause instanceof Error ? cause.message : String(cause);
+    return new errors_1.OkintStorageError('NATIVE_ERROR', `Native storage failed during ${op}: ${msg}`, cause);
+}

package/lib/errors.d.ts

@@ -0,0 +1,9 @@
+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 declare class OkintStorageError extends Error {
+    readonly code: OkintStorageErrorCode;
+    constructor(code: OkintStorageErrorCode, message: string, cause?: unknown);
+}

package/lib/errors.js

@@ -0,0 +1,19 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OkintStorageError = void 0;
+/**
+ * Single error type for the whole package. Carries a stable `code` so callers
+ * can branch without string-matching messages.
+ */
+class OkintStorageError extends Error {
+    code;
+    constructor(code, message, cause) {
+        // `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);
+    }
+}
+exports.OkintStorageError = OkintStorageError;

package/lib/facade.d.ts

@@ -0,0 +1,29 @@
+import type { BackendKind, OkintStorage, StorageBackend } from './types';
+/**
+ * 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 declare class StorageFacade implements OkintStorage {
+    private readonly impl;
+    constructor(impl: StorageBackend);
+    get backend(): BackendKind;
+    getString(key: string): Promise<string | null>;
+    setString(key: string, value: string): Promise<void>;
+    getItem<T>(key: string): Promise<T | null>;
+    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[]>;
+    multiGet(keys: string[]): Promise<Record<string, string | null>>;
+    multiSet(entries: Record<string, string>): Promise<void>;
+    multiRemove(keys: string[]): Promise<void>;
+}

package/lib/facade.js

@@ -0,0 +1,93 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.StorageFacade = void 0;
+const validate_1 = require("./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).
+ */
+class StorageFacade {
+    impl;
+    constructor(impl) {
+        this.impl = impl;
+    }
+    get backend() {
+        return this.impl.kind;
+    }
+    async getString(key) {
+        (0, validate_1.assertKey)(key);
+        return this.impl.getString(key);
+    }
+    async setString(key, value) {
+        (0, validate_1.assertKey)(key);
+        (0, validate_1.assertStringValue)(value);
+        return this.impl.setString(key, value);
+    }
+    async getItem(key) {
+        (0, validate_1.assertKey)(key);
+        const raw = await this.impl.getString(key);
+        return raw == null ? null : (0, validate_1.fromJson)(key, raw);
+    }
+    async setItem(key, value) {
+        (0, validate_1.assertKey)(key);
+        return this.impl.setString(key, (0, validate_1.toJson)(key, value));
+    }
+    async getNumber(key) {
+        (0, validate_1.assertKey)(key);
+        const raw = await this.impl.getString(key);
+        return raw == null ? null : (0, validate_1.stringToNumber)(raw);
+    }
+    async setNumber(key, value) {
+        (0, validate_1.assertKey)(key);
+        return this.impl.setString(key, (0, validate_1.numberToString)(key, value));
+    }
+    async getBoolean(key) {
+        (0, validate_1.assertKey)(key);
+        const raw = await this.impl.getString(key);
+        return raw == null ? null : (0, validate_1.stringToBoolean)(raw);
+    }
+    async setBoolean(key, value) {
+        (0, validate_1.assertKey)(key);
+        return this.impl.setString(key, value ? 'true' : 'false');
+    }
+    async has(key) {
+        (0, validate_1.assertKey)(key);
+        return (await this.impl.getString(key)) !== null;
+    }
+    async remove(key) {
+        (0, validate_1.assertKey)(key);
+        return this.impl.remove(key);
+    }
+    clear() {
+        return this.impl.clear();
+    }
+    keys() {
+        return this.impl.keys();
+    }
+    async multiGet(keys) {
+        const out = {};
+        await Promise.all(keys.map(async (k) => {
+            (0, validate_1.assertKey)(k);
+            out[k] = await this.impl.getString(k);
+        }));
+        return out;
+    }
+    async multiSet(entries) {
+        await Promise.all(Object.entries(entries).map(([k, v]) => {
+            (0, validate_1.assertKey)(k);
+            (0, validate_1.assertStringValue)(v);
+            return this.impl.setString(k, v);
+        }));
+    }
+    async multiRemove(keys) {
+        await Promise.all(keys.map((k) => {
+            (0, validate_1.assertKey)(k);
+            return this.impl.remove(k);
+        }));
+    }
+}
+exports.StorageFacade = StorageFacade;

package/lib/index.d.ts

@@ -0,0 +1,48 @@
+import type { OkintStorage, OkintStorageOptions, OkintSyncStorage, OkintSyncStorageOptions } from './types';
+/**
+ * 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 declare function createStorage(options: OkintStorageOptions): OkintStorage;
+export declare function createSyncStorage(options: OkintSyncStorageOptions): Promise<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 declare function createSyncStorageSync(options: OkintSyncStorageOptions): 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 declare function createJSIStorage(options?: {
+    namespace?: string;
+}): OkintSyncStorage;
+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/lib/index.js

@@ -0,0 +1,172 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OkintStorageError = exports.BackendSyncPersistence = exports.MemorySyncPersistence = exports.JSISyncStore = exports.OkintSyncStore = exports.NativeBackend = exports.MemoryBackend = exports.StorageFacade = void 0;
+exports.createStorage = createStorage;
+exports.createSyncStorage = createSyncStorage;
+exports.createSyncStorageSync = createSyncStorageSync;
+exports.createJSIStorage = createJSIStorage;
+const facade_1 = require("./facade");
+const memory_1 = require("./backends/memory");
+const native_backend_1 = require("./backends/native-backend");
+const sync_store_1 = require("./sync/sync-store");
+const jsi_store_1 = require("./sync/jsi-store");
+const persistence_1 = require("./sync/persistence");
+const bridge_1 = require("./native/bridge");
+const jsi_1 = require("./native/jsi");
+const errors_1 = require("./errors");
+const validate_1 = require("./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);
+ */
+function createStorage(options) {
+    const namespace = (0, validate_1.normalizeNamespace)(options.namespace, DEFAULT_NAMESPACE);
+    return new facade_1.StorageFacade(resolveBackend(options.backend, namespace));
+}
+function resolveBackend(kind, namespace) {
+    switch (kind) {
+        case 'memory':
+            return new memory_1.MemoryBackend('memory');
+        case 'secure':
+        case 'async':
+        case 'encrypted':
+        case 'sqlite':
+            return new native_backend_1.NativeBackend((0, bridge_1.getNativeModule)(), namespace, kind);
+        default:
+            throw new errors_1.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();
+function createSyncStorage(options) {
+    // Promise-returning factory → surface validation as a rejection, not a sync throw.
+    let namespace;
+    try {
+        namespace = (0, validate_1.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();
+/**
+ * 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
+ */
+function createSyncStorageSync(options) {
+    const namespace = (0, validate_1.normalizeNamespace)(options.namespace, DEFAULT_NAMESPACE);
+    const registryKey = `${options.backend}:${namespace}`;
+    const existing = syncRegistrySync.get(registryKey);
+    if (existing)
+        return existing;
+    let store;
+    switch (options.backend) {
+        case 'memory':
+            store = new sync_store_1.OkintSyncStore('memory', new persistence_1.MemorySyncPersistence());
+            store.loadSync({});
+            break;
+        case 'fast': {
+            const native = (0, bridge_1.getNativeModule)();
+            const entries = native.getEntriesSync(namespace, 'async');
+            store = new sync_store_1.OkintSyncStore('fast', new persistence_1.BackendSyncPersistence(new native_backend_1.NativeBackend(native, namespace, 'async')));
+            store.loadSync(entries);
+            break;
+        }
+        default:
+            throw new errors_1.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();
+/**
+ * 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++
+ */
+function createJSIStorage(options = {}) {
+    const namespace = (0, validate_1.normalizeNamespace)(options.namespace, DEFAULT_NAMESPACE);
+    const existing = jsiRegistry.get(namespace);
+    if (existing)
+        return existing;
+    const store = new jsi_store_1.JSISyncStore((0, jsi_1.getJSIStore)((0, bridge_1.getNativeModule)(), namespace));
+    jsiRegistry.set(namespace, store);
+    return store;
+}
+async function buildSyncStore(backend, namespace) {
+    let persistence;
+    switch (backend) {
+        case 'memory':
+            persistence = new persistence_1.MemorySyncPersistence();
+            break;
+        case 'fast':
+            persistence = new persistence_1.BackendSyncPersistence(new native_backend_1.NativeBackend((0, bridge_1.getNativeModule)(), namespace, 'async'));
+            break;
+        default:
+            throw new errors_1.OkintStorageError('UNKNOWN_BACKEND', `Unknown sync backend "${String(backend)}".`);
+    }
+    const store = new sync_store_1.OkintSyncStore(backend, persistence);
+    await store.load();
+    return store;
+}
+var facade_2 = require("./facade");
+Object.defineProperty(exports, "StorageFacade", { enumerable: true, get: function () { return facade_2.StorageFacade; } });
+var memory_2 = require("./backends/memory");
+Object.defineProperty(exports, "MemoryBackend", { enumerable: true, get: function () { return memory_2.MemoryBackend; } });
+var native_backend_2 = require("./backends/native-backend");
+Object.defineProperty(exports, "NativeBackend", { enumerable: true, get: function () { return native_backend_2.NativeBackend; } });
+var sync_store_2 = require("./sync/sync-store");
+Object.defineProperty(exports, "OkintSyncStore", { enumerable: true, get: function () { return sync_store_2.OkintSyncStore; } });
+var jsi_store_2 = require("./sync/jsi-store");
+Object.defineProperty(exports, "JSISyncStore", { enumerable: true, get: function () { return jsi_store_2.JSISyncStore; } });
+var persistence_2 = require("./sync/persistence");
+Object.defineProperty(exports, "MemorySyncPersistence", { enumerable: true, get: function () { return persistence_2.MemorySyncPersistence; } });
+Object.defineProperty(exports, "BackendSyncPersistence", { enumerable: true, get: function () { return persistence_2.BackendSyncPersistence; } });
+var errors_2 = require("./errors");
+Object.defineProperty(exports, "OkintStorageError", { enumerable: true, get: function () { return errors_2.OkintStorageError; } });

package/lib/native/bridge.d.ts

@@ -0,0 +1,12 @@
+import type { NativeOkintStorage } from '../types';
+/**
+ * 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 declare function getNativeModule(): NativeOkintStorage;

package/lib/native/bridge.js

@@ -0,0 +1,23 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getNativeModule = getNativeModule;
+const react_native_1 = require("react-native");
+const errors_1 = require("../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.
+ */
+function getNativeModule() {
+    const mod = react_native_1.NativeModules['OkintRnStorage'];
+    if (!mod) {
+        throw new errors_1.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/lib/native/jsi.d.ts

@@ -0,0 +1,7 @@
+import type { JSIStore, NativeOkintStorage } from '../types';
+/**
+ * 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 declare function getJSIStore(native: NativeOkintStorage, namespace: string): JSIStore;

package/lib/native/jsi.js

@@ -0,0 +1,33 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getJSIStore = getJSIStore;
+const errors_1 = require("../errors");
+const GLOBAL_FACTORY = '__okintCreateJSI';
+function factory() {
+    const g = globalThis;
+    const f = g[GLOBAL_FACTORY];
+    return typeof f === 'function' ? f : 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`.
+ */
+function getJSIStore(native, namespace) {
+    if (!installed && factory() === undefined) {
+        try {
+            native.installJSI();
+        }
+        catch {
+            // fall through to the missing-engine error below
+        }
+    }
+    const create = factory();
+    if (create === undefined) {
+        throw new errors_1.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);
+}

package/lib/sync/jsi-store.d.ts

@@ -0,0 +1,28 @@
+import type { JSIStore, OkintSyncStorage, SyncBackendKind } from '../types';
+/**
+ * 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 declare class JSISyncStore implements OkintSyncStorage {
+    private readonly store;
+    readonly backend: SyncBackendKind;
+    constructor(store: JSIStore);
+    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[];
+    multiGet(keys: string[]): Record<string, string | null>;
+    multiSet(entries: Record<string, string>): void;
+    multiRemove(keys: string[]): void;
+    flush(): Promise<void>;
+}