@kafitra/lynx-async-storage 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,226 @@
+/**
+ * @kafitra/lynx-async-storage
+ *
+ * Public type definitions.
+ */
+/** A key-value pair used for multi-set and multi-merge operations. */
+type KeyValuePair = [key: string, value: string];
+/** A key-result pair returned by multi-get. Value is null when the key is absent. */
+type KeyValueResult = [key: string, value: string | null];
+/**
+ * Synchronous low-level storage contract.
+ *
+ * Implementations wrap the underlying platform storage (e.g., Lynx runtime
+ * key-value store, localStorage-compatible API) and expose a uniform surface.
+ * All methods are intentionally synchronous; async scheduling is handled by
+ * the AsyncStorage layer above.
+ */
+interface StorageBackend {
+    /** Returns the stored string, or null when the key is absent. */
+    getItem(key: string): string | null;
+    /** Stores a string value. */
+    setItem(key: string, value: string): void;
+    /** Removes a single key. */
+    removeItem(key: string): void;
+    /** Removes every key managed by this backend. */
+    clear(): void;
+    /** Returns every currently stored key in an unspecified order. */
+    getAllKeys(): string[];
+}
+/**
+ * Full async API surface – mirrors React Native AsyncStorage.
+ */
+interface AsyncStorageInterface {
+    getItem(key: string): Promise<string | null>;
+    setItem(key: string, value: string): Promise<void>;
+    removeItem(key: string): Promise<void>;
+    clear(): Promise<void>;
+    getAllKeys(): Promise<string[]>;
+    multiGet(keys: readonly string[]): Promise<KeyValueResult[]>;
+    multiSet(keyValuePairs: readonly KeyValuePair[]): Promise<void>;
+    multiRemove(keys: readonly string[]): Promise<void>;
+    mergeItem(key: string, value: string): Promise<void>;
+    multiMerge(keyValuePairs: readonly KeyValuePair[]): Promise<void>;
+    /**
+     * Swaps the current backend for a new one.
+     * Useful for testing or runtime adapter injection.
+     */
+    useBackend(backend: StorageBackend): void;
+}
+
+/**
+ * @kafitra/lynx-async-storage
+ *
+ * Core AsyncStorage implementation.
+ *
+ * Design notes
+ * ────────────
+ * • Every public method wraps its synchronous backend call inside a microtask
+ *   (Promise.resolve().then(...)) so callers always receive a Promise, even when
+ *   the underlying operation completes instantaneously.
+ *
+ * • Validation (key/value type checks) is performed *inside* the microtask so
+ *   that no method ever throws synchronously.
+ *
+ * • mergeItem implements a shallow JSON Object merge as specified: parse both
+ *   values, spread-merge, stringify, and persist.
+ *
+ * • getAllKeys returns keys sorted lexicographically for deterministic output.
+ *
+ * • multiGet preserves the order of the input `keys` array.
+ */
+
+declare class AsyncStorage implements AsyncStorageInterface {
+    private backend;
+    constructor(backend?: StorageBackend);
+    useBackend(backend: StorageBackend): void;
+    getItem(key: string): Promise<string | null>;
+    setItem(key: string, value: string): Promise<void>;
+    removeItem(key: string): Promise<void>;
+    clear(): Promise<void>;
+    getAllKeys(): Promise<string[]>;
+    multiGet(keys: readonly string[]): Promise<KeyValueResult[]>;
+    multiSet(keyValuePairs: readonly KeyValuePair[]): Promise<void>;
+    multiRemove(keys: readonly string[]): Promise<void>;
+    mergeItem(key: string, value: string): Promise<void>;
+    multiMerge(keyValuePairs: readonly KeyValuePair[]): Promise<void>;
+}
+
+/**
+ * @kafitra/lynx-async-storage
+ *
+ * StorageBackend implementations.
+ *
+ * Resolution order (createDefaultBackend):
+ *  1. NativeStorageBackend  — NativeModules.LynxStorage (disk-backed, persists across restarts)
+ *  2. LocalStorageBackend   — globalThis.localStorage   (browser / some WebView runtimes)
+ *  3. MemoryBackend         — in-memory Map fallback     (tests / unknown environments)
+ *
+ * Swap the backend at any time via AsyncStorage.useBackend().
+ */
+
+interface LynxNativeStorage {
+    getString(key: string): string | null;
+    setString(key: string, value: string): void;
+    remove(key: string): void;
+    clear(): void;
+    /** Returns a JSON array string, e.g. '["a","b"]' */
+    getAllKeys(): string;
+}
+/**
+ * Simple Map-backed store.
+ *
+ * Used as the built-in fallback when no runtime storage is detected, and as a
+ * convenient injectable backend for unit tests.
+ */
+declare class MemoryBackend implements StorageBackend {
+    private readonly store;
+    getItem(key: string): string | null;
+    setItem(key: string, value: string): void;
+    removeItem(key: string): void;
+    clear(): void;
+    getAllKeys(): string[];
+}
+/**
+ * Wraps the `NativeModules.LynxStorage` Lynx native module.
+ *
+ * This backend provides **disk-persistent** storage that survives app restarts,
+ * backed by Android SharedPreferences and iOS NSUserDefaults.
+ *
+ * Requires `@kafitra/lynx-storage` to be installed and registered in the
+ * host Android/iOS app:
+ *
+ *   Android: LynxEnv.inst().registerModule("LynxStorage", LynxStorageModule.class)
+ *   iOS:     [globalConfig registerModule:LynxStorageModule.class]
+ */
+declare class NativeStorageBackend implements StorageBackend {
+    private readonly native;
+    constructor(native: LynxNativeStorage);
+    getItem(key: string): string | null;
+    setItem(key: string, value: string): void;
+    removeItem(key: string): void;
+    clear(): void;
+    getAllKeys(): string[];
+}
+/**
+ * Wraps any object that matches the Web Storage / Lynx localStorage API.
+ */
+declare class LocalStorageBackend implements StorageBackend {
+    private readonly ls;
+    constructor(ls: Storage);
+    getItem(key: string): string | null;
+    setItem(key: string, value: string): void;
+    removeItem(key: string): void;
+    clear(): void;
+    getAllKeys(): string[];
+}
+/**
+ * Creates and returns the best available backend for the current runtime.
+ *
+ * Resolution order:
+ *  1. NativeModules.LynxStorage  (Lynx runtime with @kafitra/lynx-storage linked)
+ *  2. globalThis.localStorage    (browser / jsdom)
+ *  3. MemoryBackend              (fallback)
+ */
+declare function createDefaultBackend(): StorageBackend;
+
+/**
+ * @kafitra/lynx-async-storage
+ *
+ * Typed error classes used across the module.
+ * All errors extend the built-in Error so they are instanceof-compatible.
+ */
+declare const ErrorCodes: {
+    readonly INVALID_KEY: "ERR_ASYNC_STORAGE_INVALID_KEY";
+    readonly INVALID_VALUE: "ERR_ASYNC_STORAGE_INVALID_VALUE";
+    readonly INVALID_JSON: "ERR_ASYNC_STORAGE_INVALID_JSON";
+    readonly BACKEND_FAILURE: "ERR_ASYNC_STORAGE_BACKEND_FAILURE";
+};
+type ErrorCode = (typeof ErrorCodes)[keyof typeof ErrorCodes];
+declare class AsyncStorageError extends Error {
+    readonly code: ErrorCode;
+    readonly cause?: unknown;
+    constructor(code: ErrorCode, message: string, cause?: unknown);
+}
+/** Thrown when a key is not a non-empty string. */
+declare class InvalidKeyError extends AsyncStorageError {
+    constructor(key: unknown);
+}
+/** Thrown when a value is not a string. */
+declare class InvalidValueError extends AsyncStorageError {
+    constructor(value: unknown);
+}
+/** Thrown when JSON parsing fails during a merge operation. */
+declare class InvalidJsonError extends AsyncStorageError {
+    constructor(context: "existing" | "incoming", cause?: unknown);
+}
+/** Thrown when the underlying storage backend raises an exception. */
+declare class BackendError extends AsyncStorageError {
+    constructor(operation: string, cause?: unknown);
+}
+
+/**
+ * @kafitra/lynx-async-storage
+ *
+ * Public barrel export.
+ *
+ * Default export: shared singleton (mirrors React Native AsyncStorage usage).
+ * Named exports: class and types for consumers who need custom instances.
+ */
+
+/**
+ * Shared singleton instance – drop-in replacement for React Native AsyncStorage.
+ *
+ * @example
+ * ```ts
+ * import AsyncStorage from '@kafitra/lynx-async-storage';
+ *
+ * await AsyncStorage.setItem('token', 'abc123');
+ * const token = await AsyncStorage.getItem('token'); // 'abc123'
+ * ```
+ */
+declare const instance: AsyncStorage;
+
+// @ts-ignore
+export = instance;
+export { AsyncStorage, AsyncStorageError, type AsyncStorageInterface, BackendError, ErrorCodes, InvalidJsonError, InvalidKeyError, InvalidValueError, type KeyValuePair, type KeyValueResult, LocalStorageBackend, MemoryBackend, NativeStorageBackend, type StorageBackend, createDefaultBackend };

package/dist/index.d.ts

@@ -0,0 +1,224 @@
+/**
+ * @kafitra/lynx-async-storage
+ *
+ * Public type definitions.
+ */
+/** A key-value pair used for multi-set and multi-merge operations. */
+type KeyValuePair = [key: string, value: string];
+/** A key-result pair returned by multi-get. Value is null when the key is absent. */
+type KeyValueResult = [key: string, value: string | null];
+/**
+ * Synchronous low-level storage contract.
+ *
+ * Implementations wrap the underlying platform storage (e.g., Lynx runtime
+ * key-value store, localStorage-compatible API) and expose a uniform surface.
+ * All methods are intentionally synchronous; async scheduling is handled by
+ * the AsyncStorage layer above.
+ */
+interface StorageBackend {
+    /** Returns the stored string, or null when the key is absent. */
+    getItem(key: string): string | null;
+    /** Stores a string value. */
+    setItem(key: string, value: string): void;
+    /** Removes a single key. */
+    removeItem(key: string): void;
+    /** Removes every key managed by this backend. */
+    clear(): void;
+    /** Returns every currently stored key in an unspecified order. */
+    getAllKeys(): string[];
+}
+/**
+ * Full async API surface – mirrors React Native AsyncStorage.
+ */
+interface AsyncStorageInterface {
+    getItem(key: string): Promise<string | null>;
+    setItem(key: string, value: string): Promise<void>;
+    removeItem(key: string): Promise<void>;
+    clear(): Promise<void>;
+    getAllKeys(): Promise<string[]>;
+    multiGet(keys: readonly string[]): Promise<KeyValueResult[]>;
+    multiSet(keyValuePairs: readonly KeyValuePair[]): Promise<void>;
+    multiRemove(keys: readonly string[]): Promise<void>;
+    mergeItem(key: string, value: string): Promise<void>;
+    multiMerge(keyValuePairs: readonly KeyValuePair[]): Promise<void>;
+    /**
+     * Swaps the current backend for a new one.
+     * Useful for testing or runtime adapter injection.
+     */
+    useBackend(backend: StorageBackend): void;
+}
+
+/**
+ * @kafitra/lynx-async-storage
+ *
+ * Core AsyncStorage implementation.
+ *
+ * Design notes
+ * ────────────
+ * • Every public method wraps its synchronous backend call inside a microtask
+ *   (Promise.resolve().then(...)) so callers always receive a Promise, even when
+ *   the underlying operation completes instantaneously.
+ *
+ * • Validation (key/value type checks) is performed *inside* the microtask so
+ *   that no method ever throws synchronously.
+ *
+ * • mergeItem implements a shallow JSON Object merge as specified: parse both
+ *   values, spread-merge, stringify, and persist.
+ *
+ * • getAllKeys returns keys sorted lexicographically for deterministic output.
+ *
+ * • multiGet preserves the order of the input `keys` array.
+ */
+
+declare class AsyncStorage implements AsyncStorageInterface {
+    private backend;
+    constructor(backend?: StorageBackend);
+    useBackend(backend: StorageBackend): void;
+    getItem(key: string): Promise<string | null>;
+    setItem(key: string, value: string): Promise<void>;
+    removeItem(key: string): Promise<void>;
+    clear(): Promise<void>;
+    getAllKeys(): Promise<string[]>;
+    multiGet(keys: readonly string[]): Promise<KeyValueResult[]>;
+    multiSet(keyValuePairs: readonly KeyValuePair[]): Promise<void>;
+    multiRemove(keys: readonly string[]): Promise<void>;
+    mergeItem(key: string, value: string): Promise<void>;
+    multiMerge(keyValuePairs: readonly KeyValuePair[]): Promise<void>;
+}
+
+/**
+ * @kafitra/lynx-async-storage
+ *
+ * StorageBackend implementations.
+ *
+ * Resolution order (createDefaultBackend):
+ *  1. NativeStorageBackend  — NativeModules.LynxStorage (disk-backed, persists across restarts)
+ *  2. LocalStorageBackend   — globalThis.localStorage   (browser / some WebView runtimes)
+ *  3. MemoryBackend         — in-memory Map fallback     (tests / unknown environments)
+ *
+ * Swap the backend at any time via AsyncStorage.useBackend().
+ */
+
+interface LynxNativeStorage {
+    getString(key: string): string | null;
+    setString(key: string, value: string): void;
+    remove(key: string): void;
+    clear(): void;
+    /** Returns a JSON array string, e.g. '["a","b"]' */
+    getAllKeys(): string;
+}
+/**
+ * Simple Map-backed store.
+ *
+ * Used as the built-in fallback when no runtime storage is detected, and as a
+ * convenient injectable backend for unit tests.
+ */
+declare class MemoryBackend implements StorageBackend {
+    private readonly store;
+    getItem(key: string): string | null;
+    setItem(key: string, value: string): void;
+    removeItem(key: string): void;
+    clear(): void;
+    getAllKeys(): string[];
+}
+/**
+ * Wraps the `NativeModules.LynxStorage` Lynx native module.
+ *
+ * This backend provides **disk-persistent** storage that survives app restarts,
+ * backed by Android SharedPreferences and iOS NSUserDefaults.
+ *
+ * Requires `@kafitra/lynx-storage` to be installed and registered in the
+ * host Android/iOS app:
+ *
+ *   Android: LynxEnv.inst().registerModule("LynxStorage", LynxStorageModule.class)
+ *   iOS:     [globalConfig registerModule:LynxStorageModule.class]
+ */
+declare class NativeStorageBackend implements StorageBackend {
+    private readonly native;
+    constructor(native: LynxNativeStorage);
+    getItem(key: string): string | null;
+    setItem(key: string, value: string): void;
+    removeItem(key: string): void;
+    clear(): void;
+    getAllKeys(): string[];
+}
+/**
+ * Wraps any object that matches the Web Storage / Lynx localStorage API.
+ */
+declare class LocalStorageBackend implements StorageBackend {
+    private readonly ls;
+    constructor(ls: Storage);
+    getItem(key: string): string | null;
+    setItem(key: string, value: string): void;
+    removeItem(key: string): void;
+    clear(): void;
+    getAllKeys(): string[];
+}
+/**
+ * Creates and returns the best available backend for the current runtime.
+ *
+ * Resolution order:
+ *  1. NativeModules.LynxStorage  (Lynx runtime with @kafitra/lynx-storage linked)
+ *  2. globalThis.localStorage    (browser / jsdom)
+ *  3. MemoryBackend              (fallback)
+ */
+declare function createDefaultBackend(): StorageBackend;
+
+/**
+ * @kafitra/lynx-async-storage
+ *
+ * Typed error classes used across the module.
+ * All errors extend the built-in Error so they are instanceof-compatible.
+ */
+declare const ErrorCodes: {
+    readonly INVALID_KEY: "ERR_ASYNC_STORAGE_INVALID_KEY";
+    readonly INVALID_VALUE: "ERR_ASYNC_STORAGE_INVALID_VALUE";
+    readonly INVALID_JSON: "ERR_ASYNC_STORAGE_INVALID_JSON";
+    readonly BACKEND_FAILURE: "ERR_ASYNC_STORAGE_BACKEND_FAILURE";
+};
+type ErrorCode = (typeof ErrorCodes)[keyof typeof ErrorCodes];
+declare class AsyncStorageError extends Error {
+    readonly code: ErrorCode;
+    readonly cause?: unknown;
+    constructor(code: ErrorCode, message: string, cause?: unknown);
+}
+/** Thrown when a key is not a non-empty string. */
+declare class InvalidKeyError extends AsyncStorageError {
+    constructor(key: unknown);
+}
+/** Thrown when a value is not a string. */
+declare class InvalidValueError extends AsyncStorageError {
+    constructor(value: unknown);
+}
+/** Thrown when JSON parsing fails during a merge operation. */
+declare class InvalidJsonError extends AsyncStorageError {
+    constructor(context: "existing" | "incoming", cause?: unknown);
+}
+/** Thrown when the underlying storage backend raises an exception. */
+declare class BackendError extends AsyncStorageError {
+    constructor(operation: string, cause?: unknown);
+}
+
+/**
+ * @kafitra/lynx-async-storage
+ *
+ * Public barrel export.
+ *
+ * Default export: shared singleton (mirrors React Native AsyncStorage usage).
+ * Named exports: class and types for consumers who need custom instances.
+ */
+
+/**
+ * Shared singleton instance – drop-in replacement for React Native AsyncStorage.
+ *
+ * @example
+ * ```ts
+ * import AsyncStorage from '@kafitra/lynx-async-storage';
+ *
+ * await AsyncStorage.setItem('token', 'abc123');
+ * const token = await AsyncStorage.getItem('token'); // 'abc123'
+ * ```
+ */
+declare const instance: AsyncStorage;
+
+export { AsyncStorage, AsyncStorageError, type AsyncStorageInterface, BackendError, ErrorCodes, InvalidJsonError, InvalidKeyError, InvalidValueError, type KeyValuePair, type KeyValueResult, LocalStorageBackend, MemoryBackend, NativeStorageBackend, type StorageBackend, createDefaultBackend, instance as default };