@kafitra/lynx-async-storage 0.1.0

package/README.md

@@ -0,0 +1,282 @@
+# @kafitra/lynx-async-storage
+
+Async key-value storage for the [Lynx](https://lynxjs.org) runtime — mirrors the React Native `AsyncStorage` API.
+
+## Features
+
+- **Drop-in API** – same method signatures as React Native `AsyncStorage`
+- **Pure JS** – no native Android/iOS modules, no `prebuild` step
+- **Thin async wrapper** – microtask-scheduled Promises over the synchronous Lynx runtime storage
+- **JSON merge** – shallow object merge via `mergeItem` / `multiMerge`
+- **Pluggable backend** – swap the storage adapter at runtime or in tests
+- **Tree-shakeable** – `"sideEffects": false`, ESM + CJS dual output
+- **Strict TypeScript** – full type safety, no implicit `any`
+
+---
+
+## Installation
+
+```bash
+pnpm add @kafitra/lynx-async-storage
+# or
+npm install @kafitra/lynx-async-storage
+```
+
+---
+
+## Quick Start
+
+```ts
+import AsyncStorage from "@kafitra/lynx-async-storage";
+
+// Store a value
+await AsyncStorage.setItem("token", "abc123");
+
+// Retrieve a value (null if absent)
+const token = await AsyncStorage.getItem("token");
+console.log(token); // 'abc123'
+
+// Remove a value
+await AsyncStorage.removeItem("token");
+
+// Clear everything
+await AsyncStorage.clear();
+```
+
+---
+
+## API Reference
+
+### Single-key methods
+
+| Method       | Signature                                       | Description                                |
+| ------------ | ----------------------------------------------- | ------------------------------------------ |
+| `getItem`    | `(key: string) => Promise<string \| null>`      | Returns the value, or `null` if absent     |
+| `setItem`    | `(key: string, value: string) => Promise<void>` | Stores a value                             |
+| `removeItem` | `(key: string) => Promise<void>`                | Removes a single key                       |
+| `clear`      | `() => Promise<void>`                           | Removes **all** keys                       |
+| `getAllKeys` | `() => Promise<string[]>`                       | Returns all keys, sorted lexicographically |
+
+### Batch methods
+
+| Method        | Signature                                                 | Description                               |
+| ------------- | --------------------------------------------------------- | ----------------------------------------- |
+| `multiGet`    | `(keys: string[]) => Promise<[string, string \| null][]>` | Fetches multiple keys; order is preserved |
+| `multiSet`    | `(pairs: [string, string][]) => Promise<void>`            | Stores multiple pairs atomically          |
+| `multiRemove` | `(keys: string[]) => Promise<void>`                       | Removes multiple keys                     |
+
+### Merge methods
+
+| Method       | Signature                                       | Description                                        |
+| ------------ | ----------------------------------------------- | -------------------------------------------------- |
+| `mergeItem`  | `(key: string, value: string) => Promise<void>` | Shallow-merges a JSON object into the stored value |
+| `multiMerge` | `(pairs: [string, string][]) => Promise<void>`  | Applies `mergeItem` for each pair                  |
+
+---
+
+## Usage Examples
+
+### Storing structured data
+
+```ts
+import AsyncStorage from "@kafitra/lynx-async-storage";
+
+const user = { id: 1, name: "Alice", role: "admin" };
+await AsyncStorage.setItem("user", JSON.stringify(user));
+
+const raw = await AsyncStorage.getItem("user");
+const parsed = raw ? JSON.parse(raw) : null;
+```
+
+### Batch read / write
+
+```ts
+await AsyncStorage.multiSet([
+  ["firstName", "Alice"],
+  ["lastName", "Smith"],
+  ["city", "Oslo"],
+]);
+
+const results = await AsyncStorage.multiGet(["firstName", "city"]);
+// [['firstName', 'Alice'], ['city', 'Oslo']]
+```
+
+### JSON merge
+
+```ts
+// Initial state
+await AsyncStorage.setItem(
+  "prefs",
+  JSON.stringify({ theme: "light", lang: "en" }),
+);
+
+// Partial update – only theme changes; lang is preserved
+await AsyncStorage.mergeItem("prefs", JSON.stringify({ theme: "dark" }));
+
+const prefs = JSON.parse((await AsyncStorage.getItem("prefs")) ?? "{}");
+// { theme: 'dark', lang: 'en' }
+```
+
+### List all stored keys
+
+```ts
+await AsyncStorage.multiSet([
+  ["b", "2"],
+  ["a", "1"],
+  ["c", "3"],
+]);
+const keys = await AsyncStorage.getAllKeys();
+// ['a', 'b', 'c']  ← always sorted
+```
+
+---
+
+## Custom / Test Backend
+
+Inject any object that satisfies `StorageBackend` for testing or custom adapters:
+
+```ts
+import { AsyncStorage, MemoryBackend } from "@kafitra/lynx-async-storage";
+
+const storage = new AsyncStorage(new MemoryBackend());
+
+// Or swap the singleton's backend:
+import instance from "@kafitra/lynx-async-storage";
+import { MemoryBackend } from "@kafitra/lynx-async-storage";
+
+instance.useBackend(new MemoryBackend());
+```
+
+Implement `StorageBackend` yourself:
+
+```ts
+import type { StorageBackend } from "@kafitra/lynx-async-storage";
+
+class MyCustomBackend implements StorageBackend {
+  getItem(key: string): string | null {
+    /* … */
+  }
+  setItem(key: string, value: string): void {
+    /* … */
+  }
+  removeItem(key: string): void {
+    /* … */
+  }
+  clear(): void {
+    /* … */
+  }
+  getAllKeys(): string[] {
+    /* … */
+  }
+}
+```
+
+---
+
+## Error Handling
+
+All methods return Promises. Errors are always delivered via rejection – no method throws synchronously.
+
+```ts
+import {
+  InvalidKeyError,
+  InvalidValueError,
+  InvalidJsonError,
+} from "@kafitra/lynx-async-storage";
+
+try {
+  await AsyncStorage.setItem("key", "value");
+} catch (err) {
+  if (err instanceof InvalidKeyError) {
+    /* bad key type */
+  }
+  if (err instanceof InvalidValueError) {
+    /* bad value type */
+  }
+  if (err instanceof InvalidJsonError) {
+    /* merge JSON error */
+  }
+}
+```
+
+### Error types
+
+| Class               | Code                                | Cause                        |
+| ------------------- | ----------------------------------- | ---------------------------- |
+| `InvalidKeyError`   | `ERR_ASYNC_STORAGE_INVALID_KEY`     | Key is not a `string`        |
+| `InvalidValueError` | `ERR_ASYNC_STORAGE_INVALID_VALUE`   | Value is not a `string`      |
+| `InvalidJsonError`  | `ERR_ASYNC_STORAGE_INVALID_JSON`    | Non-JSON-object during merge |
+| `BackendError`      | `ERR_ASYNC_STORAGE_BACKEND_FAILURE` | Underlying storage threw     |
+
+---
+
+## Runtime Backend Detection
+
+At startup `createDefaultBackend()` probes the runtime in priority order:
+
+```
+1. NativeModules.LynxStorage available?  → NativeStorageBackend  (disk, persists across restarts)
+2. globalThis.localStorage available?    → LocalStorageBackend   (browser / WebView)
+3. fallback                              → MemoryBackend         (in-memory, lost on reload)
+```
+
+For disk-persistent storage in a Lynx app, install [`@kafitra/lynx-storage`](https://www.npmjs.com/package/@kafitra/lynx-storage) alongside:
+
+```bash
+pnpm add @kafitra/lynx-storage @kafitra/lynx-async-storage
+```
+
+No extra configuration needed — `NativeModules.LynxStorage` is auto-detected at runtime.
+
+---
+
+## Design Decisions
+
+### Why microtask scheduling?
+
+`Promise.resolve().then(work)` schedules `work` on the microtask queue. This
+guarantees the public API is always async – callers can safely `await` without
+relying on synchronous completion, even when the backend is synchronous.
+
+### Why shallow merge?
+
+React Native AsyncStorage specifies a shallow merge for `mergeItem`. Deep merge
+would require a third-party library and introduces ambiguity around array
+handling. Consumers who need deep merge can read-modify-write using `getItem` /
+`setItem`.
+
+### Why sorted `getAllKeys`?
+
+Sorted output is deterministic and consistent across calls regardless of the
+order in which keys were inserted – essential for reproducible application
+behaviour.
+
+### Why fail-fast validation in batch methods?
+
+Batch operations (`multiSet`, `multiGet`, etc.) validate **all** inputs before
+any backend write begins. This provides best-effort atomicity: either all writes
+happen or none do, minimising partial-state corruption.
+
+---
+
+## Development
+
+```bash
+# Install dependencies
+pnpm install
+
+# Build (ESM + CJS + types)
+pnpm build
+
+# Run tests
+pnpm test
+
+# Run tests with coverage
+pnpm test:coverage
+```
+
+---
+
+## License
+
+MIT © Kafitra

package/dist/index.cjs

@@ -0,0 +1,348 @@
+'use strict';
+
+Object.defineProperty(exports, '__esModule', { value: true });
+
+// src/errors.ts
+var ErrorCodes = {
+  INVALID_KEY: "ERR_ASYNC_STORAGE_INVALID_KEY",
+  INVALID_VALUE: "ERR_ASYNC_STORAGE_INVALID_VALUE",
+  INVALID_JSON: "ERR_ASYNC_STORAGE_INVALID_JSON",
+  BACKEND_FAILURE: "ERR_ASYNC_STORAGE_BACKEND_FAILURE"
+};
+var AsyncStorageError = class extends Error {
+  constructor(code, message, cause) {
+    super(message);
+    this.name = "AsyncStorageError";
+    this.code = code;
+    if (cause !== void 0) this.cause = cause;
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+};
+var InvalidKeyError = class extends AsyncStorageError {
+  constructor(key) {
+    super(
+      ErrorCodes.INVALID_KEY,
+      `AsyncStorage key must be a string, got: ${typeof key}`
+    );
+    this.name = "InvalidKeyError";
+  }
+};
+var InvalidValueError = class extends AsyncStorageError {
+  constructor(value) {
+    super(
+      ErrorCodes.INVALID_VALUE,
+      `AsyncStorage value must be a string, got: ${typeof value}`
+    );
+    this.name = "InvalidValueError";
+  }
+};
+var InvalidJsonError = class extends AsyncStorageError {
+  constructor(context, cause) {
+    super(
+      ErrorCodes.INVALID_JSON,
+      `AsyncStorage mergeItem: ${context} value is not valid JSON`,
+      cause
+    );
+    this.name = "InvalidJsonError";
+  }
+};
+var BackendError = class extends AsyncStorageError {
+  constructor(operation, cause) {
+    super(
+      ErrorCodes.BACKEND_FAILURE,
+      `AsyncStorage backend error during "${operation}"`,
+      cause
+    );
+    this.name = "BackendError";
+  }
+};
+
+// src/storageBackend.ts
+var MemoryBackend = class {
+  constructor() {
+    this.store = /* @__PURE__ */ new Map();
+  }
+  getItem(key) {
+    return this.store.has(key) ? this.store.get(key) : null;
+  }
+  setItem(key, value) {
+    this.store.set(key, value);
+  }
+  removeItem(key) {
+    this.store.delete(key);
+  }
+  clear() {
+    this.store.clear();
+  }
+  getAllKeys() {
+    return Array.from(this.store.keys());
+  }
+};
+var NativeStorageBackend = class {
+  constructor(native) {
+    this.native = native;
+  }
+  getItem(key) {
+    try {
+      return this.native.getString(key);
+    } catch (err) {
+      throw new BackendError("getItem", err);
+    }
+  }
+  setItem(key, value) {
+    try {
+      this.native.setString(key, value);
+    } catch (err) {
+      throw new BackendError("setItem", err);
+    }
+  }
+  removeItem(key) {
+    try {
+      this.native.remove(key);
+    } catch (err) {
+      throw new BackendError("removeItem", err);
+    }
+  }
+  clear() {
+    try {
+      this.native.clear();
+    } catch (err) {
+      throw new BackendError("clear", err);
+    }
+  }
+  getAllKeys() {
+    try {
+      const raw = this.native.getAllKeys();
+      return JSON.parse(raw);
+    } catch (err) {
+      throw new BackendError("getAllKeys", err);
+    }
+  }
+};
+var LocalStorageBackend = class {
+  constructor(ls) {
+    this.ls = ls;
+  }
+  getItem(key) {
+    try {
+      return this.ls.getItem(key);
+    } catch (err) {
+      throw new BackendError("getItem", err);
+    }
+  }
+  setItem(key, value) {
+    try {
+      this.ls.setItem(key, value);
+    } catch (err) {
+      throw new BackendError("setItem", err);
+    }
+  }
+  removeItem(key) {
+    try {
+      this.ls.removeItem(key);
+    } catch (err) {
+      throw new BackendError("removeItem", err);
+    }
+  }
+  clear() {
+    try {
+      this.ls.clear();
+    } catch (err) {
+      throw new BackendError("clear", err);
+    }
+  }
+  getAllKeys() {
+    try {
+      const keys = [];
+      for (let i = 0; i < this.ls.length; i++) {
+        const k = this.ls.key(i);
+        if (k !== null) keys.push(k);
+      }
+      return keys;
+    } catch (err) {
+      throw new BackendError("getAllKeys", err);
+    }
+  }
+};
+function isNativeStorageAvailable(candidate) {
+  if (candidate === null || candidate === void 0 || typeof candidate !== "object") {
+    return false;
+  }
+  const obj = candidate;
+  return typeof obj["getString"] === "function" && typeof obj["setString"] === "function" && typeof obj["remove"] === "function" && typeof obj["clear"] === "function" && typeof obj["getAllKeys"] === "function";
+}
+function isStorageAvailable(candidate) {
+  if (candidate === null || candidate === void 0 || typeof candidate !== "object") {
+    return false;
+  }
+  const obj = candidate;
+  return typeof obj["getItem"] === "function" && typeof obj["setItem"] === "function" && typeof obj["removeItem"] === "function" && typeof obj["clear"] === "function" && typeof obj["key"] === "function" && typeof obj["length"] === "number";
+}
+function createDefaultBackend() {
+  const g = globalThis;
+  try {
+    const nm = (
+      // eslint-disable-next-line no-undef
+      typeof NativeModules !== "undefined" ? NativeModules : g["NativeModules"]
+    );
+    if (nm && isNativeStorageAvailable(nm.LynxStorage)) {
+      return new NativeStorageBackend(nm.LynxStorage);
+    }
+  } catch {
+  }
+  if (isStorageAvailable(g["localStorage"])) {
+    return new LocalStorageBackend(g["localStorage"]);
+  }
+  return new MemoryBackend();
+}
+
+// src/AsyncStorage.ts
+function assertKey(key) {
+  if (typeof key !== "string") {
+    throw new InvalidKeyError(key);
+  }
+}
+function assertValue(value) {
+  if (typeof value !== "string") {
+    throw new InvalidValueError(value);
+  }
+}
+function shallowMergeJson(existingRaw, incomingRaw) {
+  const baseString = existingRaw ?? "{}";
+  let base;
+  let patch;
+  try {
+    base = JSON.parse(baseString);
+  } catch (err) {
+    throw new InvalidJsonError("existing", err);
+  }
+  try {
+    patch = JSON.parse(incomingRaw);
+  } catch (err) {
+    throw new InvalidJsonError("incoming", err);
+  }
+  if (base === null || typeof base !== "object" || Array.isArray(base)) {
+    throw new InvalidJsonError("existing");
+  }
+  if (patch === null || typeof patch !== "object" || Array.isArray(patch)) {
+    throw new InvalidJsonError("incoming");
+  }
+  const merged = {
+    ...base,
+    ...patch
+  };
+  return JSON.stringify(merged);
+}
+var AsyncStorage = class {
+  constructor(backend) {
+    this.backend = backend ?? createDefaultBackend();
+  }
+  // ── Backend injection ────────────────────────────────────────────────────
+  useBackend(backend) {
+    this.backend = backend;
+  }
+  // ── Single-key API ───────────────────────────────────────────────────────
+  getItem(key) {
+    return Promise.resolve().then(() => {
+      assertKey(key);
+      return this.backend.getItem(key);
+    });
+  }
+  setItem(key, value) {
+    return Promise.resolve().then(() => {
+      assertKey(key);
+      assertValue(value);
+      this.backend.setItem(key, value);
+    });
+  }
+  removeItem(key) {
+    return Promise.resolve().then(() => {
+      assertKey(key);
+      this.backend.removeItem(key);
+    });
+  }
+  clear() {
+    return Promise.resolve().then(() => {
+      this.backend.clear();
+    });
+  }
+  getAllKeys() {
+    return Promise.resolve().then(() => {
+      return this.backend.getAllKeys().slice().sort();
+    });
+  }
+  // ── Batch API ────────────────────────────────────────────────────────────
+  multiGet(keys) {
+    return Promise.resolve().then(() => {
+      for (const key of keys) {
+        assertKey(key);
+      }
+      return keys.map(
+        (key) => [key, this.backend.getItem(key)]
+      );
+    });
+  }
+  multiSet(keyValuePairs) {
+    return Promise.resolve().then(() => {
+      for (const [key, value] of keyValuePairs) {
+        assertKey(key);
+        assertValue(value);
+      }
+      for (const [key, value] of keyValuePairs) {
+        this.backend.setItem(key, value);
+      }
+    });
+  }
+  multiRemove(keys) {
+    return Promise.resolve().then(() => {
+      for (const key of keys) {
+        assertKey(key);
+      }
+      for (const key of keys) {
+        this.backend.removeItem(key);
+      }
+    });
+  }
+  // ── Merge API ────────────────────────────────────────────────────────────
+  mergeItem(key, value) {
+    return Promise.resolve().then(() => {
+      assertKey(key);
+      assertValue(value);
+      const existing = this.backend.getItem(key);
+      const merged = shallowMergeJson(existing, value);
+      this.backend.setItem(key, merged);
+    });
+  }
+  multiMerge(keyValuePairs) {
+    return Promise.resolve().then(() => {
+      for (const [key, value] of keyValuePairs) {
+        assertKey(key);
+        assertValue(value);
+      }
+      for (const [key, value] of keyValuePairs) {
+        const existing = this.backend.getItem(key);
+        const merged = shallowMergeJson(existing, value);
+        this.backend.setItem(key, merged);
+      }
+    });
+  }
+};
+
+// src/index.ts
+var instance = new AsyncStorage();
+var index_default = instance;
+
+exports.AsyncStorage = AsyncStorage;
+exports.AsyncStorageError = AsyncStorageError;
+exports.BackendError = BackendError;
+exports.ErrorCodes = ErrorCodes;
+exports.InvalidJsonError = InvalidJsonError;
+exports.InvalidKeyError = InvalidKeyError;
+exports.InvalidValueError = InvalidValueError;
+exports.LocalStorageBackend = LocalStorageBackend;
+exports.MemoryBackend = MemoryBackend;
+exports.NativeStorageBackend = NativeStorageBackend;
+exports.createDefaultBackend = createDefaultBackend;
+exports.default = index_default;
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/errors.ts","../src/storageBackend.ts","../src/AsyncStorage.ts","../src/index.ts"],"names":[],"mappings":"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","file":"index.cjs","sourcesContent":["/**\r\n * @kafitra/lynx-async-storage\r\n *\r\n * Typed error classes used across the module.\r\n * All errors extend the built-in Error so they are instanceof-compatible.\r\n */\r\n\r\n// ─── Error codes ──────────────────────────────────────────────────────────────\r\n\r\nexport const ErrorCodes = {\r\n  INVALID_KEY: \"ERR_ASYNC_STORAGE_INVALID_KEY\",\r\n  INVALID_VALUE: \"ERR_ASYNC_STORAGE_INVALID_VALUE\",\r\n  INVALID_JSON: \"ERR_ASYNC_STORAGE_INVALID_JSON\",\r\n  BACKEND_FAILURE: \"ERR_ASYNC_STORAGE_BACKEND_FAILURE\",\r\n} as const;\r\n\r\nexport type ErrorCode = (typeof ErrorCodes)[keyof typeof ErrorCodes];\r\n\r\n// ─── Base error ───────────────────────────────────────────────────────────────\r\n\r\nexport class AsyncStorageError extends Error {\r\n  public readonly code: ErrorCode;\r\n  public readonly cause?: unknown;\r\n\r\n  constructor(code: ErrorCode, message: string, cause?: unknown) {\r\n    super(message);\r\n    this.name = \"AsyncStorageError\";\r\n    this.code = code;\r\n    if (cause !== undefined) this.cause = cause;\r\n\r\n    // Maintain proper prototype chain for instanceof checks in transpiled code.\r\n    Object.setPrototypeOf(this, new.target.prototype);\r\n  }\r\n}\r\n\r\n// ─── Specific error subtypes ──────────────────────────────────────────────────\r\n\r\n/** Thrown when a key is not a non-empty string. */\r\nexport class InvalidKeyError extends AsyncStorageError {\r\n  constructor(key: unknown) {\r\n    super(\r\n      ErrorCodes.INVALID_KEY,\r\n      `AsyncStorage key must be a string, got: ${typeof key}`,\r\n    );\r\n    this.name = \"InvalidKeyError\";\r\n  }\r\n}\r\n\r\n/** Thrown when a value is not a string. */\r\nexport class InvalidValueError extends AsyncStorageError {\r\n  constructor(value: unknown) {\r\n    super(\r\n      ErrorCodes.INVALID_VALUE,\r\n      `AsyncStorage value must be a string, got: ${typeof value}`,\r\n    );\r\n    this.name = \"InvalidValueError\";\r\n  }\r\n}\r\n\r\n/** Thrown when JSON parsing fails during a merge operation. */\r\nexport class InvalidJsonError extends AsyncStorageError {\r\n  constructor(context: \"existing\" | \"incoming\", cause?: unknown) {\r\n    super(\r\n      ErrorCodes.INVALID_JSON,\r\n      `AsyncStorage mergeItem: ${context} value is not valid JSON`,\r\n      cause,\r\n    );\r\n    this.name = \"InvalidJsonError\";\r\n  }\r\n}\r\n\r\n/** Thrown when the underlying storage backend raises an exception. */\r\nexport class BackendError extends AsyncStorageError {\r\n  constructor(operation: string, cause?: unknown) {\r\n    super(\r\n      ErrorCodes.BACKEND_FAILURE,\r\n      `AsyncStorage backend error during \"${operation}\"`,\r\n      cause,\r\n    );\r\n    this.name = \"BackendError\";\r\n  }\r\n}\r\n","/**\r\n * @kafitra/lynx-async-storage\r\n *\r\n * StorageBackend implementations.\r\n *\r\n * Resolution order (createDefaultBackend):\r\n *  1. NativeStorageBackend  — NativeModules.LynxStorage (disk-backed, persists across restarts)\r\n *  2. LocalStorageBackend   — globalThis.localStorage   (browser / some WebView runtimes)\r\n *  3. MemoryBackend         — in-memory Map fallback     (tests / unknown environments)\r\n *\r\n * Swap the backend at any time via AsyncStorage.useBackend().\r\n */\r\n\r\nimport type { StorageBackend } from \"./types\";\r\nimport { BackendError } from \"./errors\";\r\n\r\n// ─── Lynx NativeModules shape (minimal) ──────────────────────────────────────\r\n\r\ninterface LynxNativeStorage {\r\n  getString(key: string): string | null;\r\n  setString(key: string, value: string): void;\r\n  remove(key: string): void;\r\n  clear(): void;\r\n  /** Returns a JSON array string, e.g. '[\"a\",\"b\"]' */\r\n  getAllKeys(): string;\r\n}\r\n\r\ninterface LynxNativeModules {\r\n  LynxStorage?: LynxNativeStorage;\r\n}\r\n\r\n/**\r\n * Lynx injects NativeModules as a top-level global (not via globalThis).\r\n * We declare it here so TypeScript is happy; the typeof guard prevents\r\n * ReferenceError in environments where it doesn't exist (tests, browser).\r\n */\r\ndeclare const NativeModules: LynxNativeModules | undefined;\r\n\r\n// ─── In-memory backend ────────────────────────────────────────────────────────\r\n\r\n/**\r\n * Simple Map-backed store.\r\n *\r\n * Used as the built-in fallback when no runtime storage is detected, and as a\r\n * convenient injectable backend for unit tests.\r\n */\r\nexport class MemoryBackend implements StorageBackend {\r\n  private readonly store = new Map<string, string>();\r\n\r\n  getItem(key: string): string | null {\r\n    return this.store.has(key) ? (this.store.get(key) as string) : null;\r\n  }\r\n\r\n  setItem(key: string, value: string): void {\r\n    this.store.set(key, value);\r\n  }\r\n\r\n  removeItem(key: string): void {\r\n    this.store.delete(key);\r\n  }\r\n\r\n  clear(): void {\r\n    this.store.clear();\r\n  }\r\n\r\n  getAllKeys(): string[] {\r\n    return Array.from(this.store.keys());\r\n  }\r\n}\r\n\r\n// ─── Lynx NativeModules backend ───────────────────────────────────────────────\r\n\r\n/**\r\n * Wraps the `NativeModules.LynxStorage` Lynx native module.\r\n *\r\n * This backend provides **disk-persistent** storage that survives app restarts,\r\n * backed by Android SharedPreferences and iOS NSUserDefaults.\r\n *\r\n * Requires `@kafitra/lynx-storage` to be installed and registered in the\r\n * host Android/iOS app:\r\n *\r\n *   Android: LynxEnv.inst().registerModule(\"LynxStorage\", LynxStorageModule.class)\r\n *   iOS:     [globalConfig registerModule:LynxStorageModule.class]\r\n */\r\nexport class NativeStorageBackend implements StorageBackend {\r\n  constructor(private readonly native: LynxNativeStorage) {}\r\n\r\n  getItem(key: string): string | null {\r\n    try {\r\n      return this.native.getString(key);\r\n    } catch (err) {\r\n      throw new BackendError(\"getItem\", err);\r\n    }\r\n  }\r\n\r\n  setItem(key: string, value: string): void {\r\n    try {\r\n      this.native.setString(key, value);\r\n    } catch (err) {\r\n      throw new BackendError(\"setItem\", err);\r\n    }\r\n  }\r\n\r\n  removeItem(key: string): void {\r\n    try {\r\n      this.native.remove(key);\r\n    } catch (err) {\r\n      throw new BackendError(\"removeItem\", err);\r\n    }\r\n  }\r\n\r\n  clear(): void {\r\n    try {\r\n      this.native.clear();\r\n    } catch (err) {\r\n      throw new BackendError(\"clear\", err);\r\n    }\r\n  }\r\n\r\n  getAllKeys(): string[] {\r\n    try {\r\n      const raw = this.native.getAllKeys();\r\n      return JSON.parse(raw) as string[];\r\n    } catch (err) {\r\n      throw new BackendError(\"getAllKeys\", err);\r\n    }\r\n  }\r\n}\r\n\r\n// ─── localStorage-compatible backend ─────────────────────────────────────────\r\n\r\n/**\r\n * Wraps any object that matches the Web Storage / Lynx localStorage API.\r\n */\r\nexport class LocalStorageBackend implements StorageBackend {\r\n  constructor(private readonly ls: Storage) {}\r\n\r\n  getItem(key: string): string | null {\r\n    try {\r\n      return this.ls.getItem(key);\r\n    } catch (err) {\r\n      throw new BackendError(\"getItem\", err);\r\n    }\r\n  }\r\n\r\n  setItem(key: string, value: string): void {\r\n    try {\r\n      this.ls.setItem(key, value);\r\n    } catch (err) {\r\n      throw new BackendError(\"setItem\", err);\r\n    }\r\n  }\r\n\r\n  removeItem(key: string): void {\r\n    try {\r\n      this.ls.removeItem(key);\r\n    } catch (err) {\r\n      throw new BackendError(\"removeItem\", err);\r\n    }\r\n  }\r\n\r\n  clear(): void {\r\n    try {\r\n      this.ls.clear();\r\n    } catch (err) {\r\n      throw new BackendError(\"clear\", err);\r\n    }\r\n  }\r\n\r\n  getAllKeys(): string[] {\r\n    try {\r\n      const keys: string[] = [];\r\n      for (let i = 0; i < this.ls.length; i++) {\r\n        const k = this.ls.key(i);\r\n        if (k !== null) keys.push(k);\r\n      }\r\n      return keys;\r\n    } catch (err) {\r\n      throw new BackendError(\"getAllKeys\", err);\r\n    }\r\n  }\r\n}\r\n\r\n// ─── Runtime detection ────────────────────────────────────────────────────────\r\n\r\nfunction isNativeStorageAvailable(\r\n  candidate: unknown,\r\n): candidate is LynxNativeStorage {\r\n  if (\r\n    candidate === null ||\r\n    candidate === undefined ||\r\n    typeof candidate !== \"object\"\r\n  ) {\r\n    return false;\r\n  }\r\n  const obj = candidate as Record<string, unknown>;\r\n  return (\r\n    typeof obj[\"getString\"] === \"function\" &&\r\n    typeof obj[\"setString\"] === \"function\" &&\r\n    typeof obj[\"remove\"] === \"function\" &&\r\n    typeof obj[\"clear\"] === \"function\" &&\r\n    typeof obj[\"getAllKeys\"] === \"function\"\r\n  );\r\n}\r\n\r\nfunction isStorageAvailable(candidate: unknown): candidate is Storage {\r\n  if (\r\n    candidate === null ||\r\n    candidate === undefined ||\r\n    typeof candidate !== \"object\"\r\n  ) {\r\n    return false;\r\n  }\r\n\r\n  const obj = candidate as Record<string, unknown>;\r\n\r\n  return (\r\n    typeof obj[\"getItem\"] === \"function\" &&\r\n    typeof obj[\"setItem\"] === \"function\" &&\r\n    typeof obj[\"removeItem\"] === \"function\" &&\r\n    typeof obj[\"clear\"] === \"function\" &&\r\n    typeof obj[\"key\"] === \"function\" &&\r\n    typeof obj[\"length\"] === \"number\"\r\n  );\r\n}\r\n\r\n/**\r\n * Creates and returns the best available backend for the current runtime.\r\n *\r\n * Resolution order:\r\n *  1. NativeModules.LynxStorage  (Lynx runtime with @kafitra/lynx-storage linked)\r\n *  2. globalThis.localStorage    (browser / jsdom)\r\n *  3. MemoryBackend              (fallback)\r\n */\r\nexport function createDefaultBackend(): StorageBackend {\r\n  const g = globalThis as Record<string, unknown>;\r\n\r\n  // 1. Prefer the Lynx native module — disk-persistent across app restarts\r\n  // NativeModules is injected as a top-level global by the Lynx runtime,\r\n  // so we check both the declared global and globalThis as a fallback.\r\n  try {\r\n    const nm: LynxNativeModules | undefined =\r\n      // eslint-disable-next-line no-undef\r\n      typeof NativeModules !== \"undefined\"\r\n        ? NativeModules\r\n        : (g[\"NativeModules\"] as LynxNativeModules | undefined);\r\n    if (nm && isNativeStorageAvailable(nm.LynxStorage)) {\r\n      return new NativeStorageBackend(nm.LynxStorage);\r\n    }\r\n  } catch {\r\n    // NativeModules not available in this runtime\r\n  }\r\n\r\n  // 2. Fall back to localStorage (browser / WebView runtimes)\r\n  if (isStorageAvailable(g[\"localStorage\"])) {\r\n    return new LocalStorageBackend(g[\"localStorage\"] as Storage);\r\n  }\r\n\r\n  // 3. In-memory fallback — data lost on reload, but never crashes\r\n  return new MemoryBackend();\r\n}\r\n","/**\r\n * @kafitra/lynx-async-storage\r\n *\r\n * Core AsyncStorage implementation.\r\n *\r\n * Design notes\r\n * ────────────\r\n * • Every public method wraps its synchronous backend call inside a microtask\r\n *   (Promise.resolve().then(...)) so callers always receive a Promise, even when\r\n *   the underlying operation completes instantaneously.\r\n *\r\n * • Validation (key/value type checks) is performed *inside* the microtask so\r\n *   that no method ever throws synchronously.\r\n *\r\n * • mergeItem implements a shallow JSON Object merge as specified: parse both\r\n *   values, spread-merge, stringify, and persist.\r\n *\r\n * • getAllKeys returns keys sorted lexicographically for deterministic output.\r\n *\r\n * • multiGet preserves the order of the input `keys` array.\r\n */\r\n\r\nimport type {\r\n  AsyncStorageInterface,\r\n  KeyValuePair,\r\n  KeyValueResult,\r\n  StorageBackend,\r\n} from \"./types\";\r\nimport { InvalidKeyError, InvalidValueError, InvalidJsonError } from \"./errors\";\r\nimport { createDefaultBackend } from \"./storageBackend\";\r\n\r\n// ─── Validation helpers ───────────────────────────────────────────────────────\r\n\r\nfunction assertKey(key: unknown): asserts key is string {\r\n  if (typeof key !== \"string\") {\r\n    throw new InvalidKeyError(key);\r\n  }\r\n}\r\n\r\nfunction assertValue(value: unknown): asserts value is string {\r\n  if (typeof value !== \"string\") {\r\n    throw new InvalidValueError(value);\r\n  }\r\n}\r\n\r\n// ─── Merge helper ─────────────────────────────────────────────────────────────\r\n\r\n/**\r\n * Performs a shallow merge of two JSON-encoded object strings.\r\n *\r\n * @param existingRaw  Current value stored (may be null).\r\n * @param incomingRaw  New value to merge in.\r\n * @returns            JSON-stringified merged result.\r\n * @throws             InvalidJsonError if either value is not a JSON object.\r\n */\r\nfunction shallowMergeJson(\r\n  existingRaw: string | null,\r\n  incomingRaw: string,\r\n): string {\r\n  // Treat null as an empty object – consistent with RN behaviour.\r\n  const baseString = existingRaw ?? \"{}\";\r\n\r\n  let base: unknown;\r\n  let patch: unknown;\r\n\r\n  try {\r\n    base = JSON.parse(baseString);\r\n  } catch (err) {\r\n    throw new InvalidJsonError(\"existing\", err);\r\n  }\r\n\r\n  try {\r\n    patch = JSON.parse(incomingRaw);\r\n  } catch (err) {\r\n    throw new InvalidJsonError(\"incoming\", err);\r\n  }\r\n\r\n  if (base === null || typeof base !== \"object\" || Array.isArray(base)) {\r\n    throw new InvalidJsonError(\"existing\");\r\n  }\r\n\r\n  if (patch === null || typeof patch !== \"object\" || Array.isArray(patch)) {\r\n    throw new InvalidJsonError(\"incoming\");\r\n  }\r\n\r\n  const merged = {\r\n    ...(base as Record<string, unknown>),\r\n    ...(patch as Record<string, unknown>),\r\n  };\r\n\r\n  return JSON.stringify(merged);\r\n}\r\n\r\n// ─── AsyncStorage class ───────────────────────────────────────────────────────\r\n\r\nexport class AsyncStorage implements AsyncStorageInterface {\r\n  private backend: StorageBackend;\r\n\r\n  constructor(backend?: StorageBackend) {\r\n    this.backend = backend ?? createDefaultBackend();\r\n  }\r\n\r\n  // ── Backend injection ────────────────────────────────────────────────────\r\n  useBackend(backend: StorageBackend): void {\r\n    this.backend = backend;\r\n  }\r\n\r\n  // ── Single-key API ───────────────────────────────────────────────────────\r\n\r\n  getItem(key: string): Promise<string | null> {\r\n    return Promise.resolve().then(() => {\r\n      assertKey(key);\r\n      return this.backend.getItem(key);\r\n    });\r\n  }\r\n\r\n  setItem(key: string, value: string): Promise<void> {\r\n    return Promise.resolve().then(() => {\r\n      assertKey(key);\r\n      assertValue(value);\r\n      this.backend.setItem(key, value);\r\n    });\r\n  }\r\n\r\n  removeItem(key: string): Promise<void> {\r\n    return Promise.resolve().then(() => {\r\n      assertKey(key);\r\n      this.backend.removeItem(key);\r\n    });\r\n  }\r\n\r\n  clear(): Promise<void> {\r\n    return Promise.resolve().then(() => {\r\n      this.backend.clear();\r\n    });\r\n  }\r\n\r\n  getAllKeys(): Promise<string[]> {\r\n    return Promise.resolve().then(() => {\r\n      return this.backend.getAllKeys().slice().sort();\r\n    });\r\n  }\r\n\r\n  // ── Batch API ────────────────────────────────────────────────────────────\r\n\r\n  multiGet(keys: readonly string[]): Promise<KeyValueResult[]> {\r\n    return Promise.resolve().then(() => {\r\n      // Validate every key before touching the backend (fail-fast, all-or-nothing).\r\n      for (const key of keys) {\r\n        assertKey(key);\r\n      }\r\n\r\n      return keys.map(\r\n        (key): KeyValueResult => [key, this.backend.getItem(key)],\r\n      );\r\n    });\r\n  }\r\n\r\n  multiSet(keyValuePairs: readonly KeyValuePair[]): Promise<void> {\r\n    return Promise.resolve().then(() => {\r\n      // Validate all pairs first (best-effort atomic: validate then write).\r\n      for (const [key, value] of keyValuePairs) {\r\n        assertKey(key);\r\n        assertValue(value);\r\n      }\r\n\r\n      for (const [key, value] of keyValuePairs) {\r\n        this.backend.setItem(key, value);\r\n      }\r\n    });\r\n  }\r\n\r\n  multiRemove(keys: readonly string[]): Promise<void> {\r\n    return Promise.resolve().then(() => {\r\n      for (const key of keys) {\r\n        assertKey(key);\r\n      }\r\n\r\n      for (const key of keys) {\r\n        this.backend.removeItem(key);\r\n      }\r\n    });\r\n  }\r\n\r\n  // ── Merge API ────────────────────────────────────────────────────────────\r\n\r\n  mergeItem(key: string, value: string): Promise<void> {\r\n    return Promise.resolve().then(() => {\r\n      assertKey(key);\r\n      assertValue(value);\r\n\r\n      const existing = this.backend.getItem(key);\r\n      const merged = shallowMergeJson(existing, value);\r\n      this.backend.setItem(key, merged);\r\n    });\r\n  }\r\n\r\n  multiMerge(keyValuePairs: readonly KeyValuePair[]): Promise<void> {\r\n    return Promise.resolve().then(() => {\r\n      // Validate inputs before any writes.\r\n      for (const [key, value] of keyValuePairs) {\r\n        assertKey(key);\r\n        assertValue(value);\r\n      }\r\n\r\n      for (const [key, value] of keyValuePairs) {\r\n        const existing = this.backend.getItem(key);\r\n        const merged = shallowMergeJson(existing, value);\r\n        this.backend.setItem(key, merged);\r\n      }\r\n    });\r\n  }\r\n}\r\n","/**\r\n * @kafitra/lynx-async-storage\r\n *\r\n * Public barrel export.\r\n *\r\n * Default export: shared singleton (mirrors React Native AsyncStorage usage).\r\n * Named exports: class and types for consumers who need custom instances.\r\n */\r\n\r\nexport { AsyncStorage } from \"./AsyncStorage\";\r\nexport {\r\n  MemoryBackend,\r\n  LocalStorageBackend,\r\n  NativeStorageBackend,\r\n  createDefaultBackend,\r\n} from \"./storageBackend\";\r\nexport {\r\n  AsyncStorageError,\r\n  InvalidKeyError,\r\n  InvalidValueError,\r\n  InvalidJsonError,\r\n  BackendError,\r\n  ErrorCodes,\r\n} from \"./errors\";\r\nexport type {\r\n  AsyncStorageInterface,\r\n  StorageBackend,\r\n  KeyValuePair,\r\n  KeyValueResult,\r\n} from \"./types\";\r\n\r\nimport { AsyncStorage } from \"./AsyncStorage\";\r\n\r\n/**\r\n * Shared singleton instance – drop-in replacement for React Native AsyncStorage.\r\n *\r\n * @example\r\n * ```ts\r\n * import AsyncStorage from '@kafitra/lynx-async-storage';\r\n *\r\n * await AsyncStorage.setItem('token', 'abc123');\r\n * const token = await AsyncStorage.getItem('token'); // 'abc123'\r\n * ```\r\n */\r\nconst instance = new AsyncStorage();\r\nexport default instance;\r\n"]}