react-smart-query 1.0.0

package/dist/types-XXiTKLnh.d.ts

@@ -0,0 +1,134 @@
+/**
+ * src/types.ts
+ *
+ * Single source of truth for all shared public types.
+ * No implementation logic — pure TypeScript interfaces and type aliases.
+ */
+/**
+ * Minimum shape required for list items.
+ * The actual id field name is configured via `getItemId` — this type
+ * only enforces that items are plain objects.
+ */
+type AnyItem = Record<string, unknown>;
+/**
+ * Extracts the id of an item. Configurable so APIs using `_id`, `uuid`,
+ * numeric ids, or composite keys all work without data transformation.
+ *
+ * @example
+ *   getItemId: (item) => item.id          // "id: string"
+ *   getItemId: (item) => String(item._id) // MongoDB ObjectId
+ *   getItemId: (item) => String(item.id)  // numeric id
+ */
+type GetItemId<T extends AnyItem> = (item: T) => string;
+/**
+ * Comparator for sort order. Same contract as Array.sort comparator.
+ * Return negative if a < b, positive if a > b, 0 if equal.
+ */
+type SortComparator<T extends AnyItem> = (a: T, b: T) => number;
+/**
+ * Extracts a version sticker (timestamp or counter) from an item.
+ * Used to prevent stale updates from overwriting fresher data.
+ */
+type GetItemVersion<T extends AnyItem> = (item: T) => number | string;
+interface CacheEntry<T> {
+    readonly version: number;
+    readonly data: T;
+    readonly cachedAt: number;
+    readonly lastAccessedAt: number;
+}
+interface NormalizedList<T extends AnyItem> {
+    byId: Record<string, T>;
+    allIds: string[];
+}
+type PaginationMode = "normalized" | "pages";
+interface UnifiedNormalizedInfiniteData<T extends AnyItem> {
+    data: NormalizedList<T>;
+    meta: {
+        nextCursor: unknown | null;
+        pageParams: unknown[];
+        lastFetchedAt?: number;
+    };
+}
+/** Legacy support - will be used internally or for migration if needed */
+interface InfinitePagedData<T extends AnyItem> {
+    pages: NormalizedList<T>[];
+    pageParams: unknown[];
+    nextCursor: unknown | null;
+}
+type ObservabilityEvent = {
+    type: "cache_hit";
+    queryKey: readonly unknown[];
+    cachedAt: number;
+} | {
+    type: "cache_miss";
+    queryKey: readonly unknown[];
+} | {
+    type: "cache_write";
+    queryKey: readonly unknown[];
+    dataSize: number;
+} | {
+    type: "fetch_start";
+    queryKey: readonly unknown[];
+} | {
+    type: "fetch_success";
+    queryKey: readonly unknown[];
+    durationMs: number;
+} | {
+    type: "fetch_error";
+    queryKey: readonly unknown[];
+    error: unknown;
+} | {
+    type: "queue_enqueue";
+    mutationId: string;
+    mutationType: string;
+} | {
+    type: "queue_success";
+    mutationId: string;
+} | {
+    type: "queue_failure";
+    mutationId: string;
+    retryCount: number;
+} | {
+    type: "queue_drained";
+} | {
+    type: "sync_conflict";
+    queryKey: readonly unknown[];
+    localVersion: unknown;
+    serverVersion: unknown;
+} | {
+    type: "storage_quota_exceeded";
+    key: string;
+};
+type ObserverFn = (event: ObservabilityEvent) => void;
+type MutationType = "ADD_ITEM" | "UPDATE_ITEM" | "REMOVE_ITEM" | "CUSTOM";
+interface QueuedMutation<TPayload = unknown> {
+    id: string;
+    type: MutationType | string;
+    /** Logical entity key for coalescing — e.g. "expense:exp_123" */
+    entityKey?: string;
+    queryKey: readonly unknown[];
+    payload: TPayload;
+    enqueuedAt: number;
+    retryCount: number;
+    maxRetries: number;
+    nextRetryAt: number;
+}
+interface SmartQueryError {
+    /** Original error from the API / network */
+    cause: unknown;
+    /** Human-readable message */
+    message: string;
+    /** Whether this error is retryable */
+    retryable: boolean;
+    /** HTTP status code if available */
+    statusCode?: number;
+}
+interface AsyncStorage {
+    get(key: string): Promise<string | undefined>;
+    set(key: string, value: string): Promise<void>;
+    delete(key: string): Promise<void>;
+    clearAll(): Promise<void>;
+    keys(): Promise<string[]>;
+}
+
+export type { AsyncStorage as A, CacheEntry as C, GetItemId as G, InfinitePagedData as I, MutationType as M, NormalizedList as N, ObserverFn as O, PaginationMode as P, QueuedMutation as Q, SortComparator as S, UnifiedNormalizedInfiniteData as U, AnyItem as a, GetItemVersion as b, SmartQueryError as c, ObservabilityEvent as d };

package/dist/utils/debug.d.mts

@@ -0,0 +1,2 @@
+
+export {  }

package/dist/utils/debug.d.ts

@@ -0,0 +1,2 @@
+
+export {  }

package/dist/utils/debug.js

@@ -0,0 +1,208 @@
+'use strict';
+
+var reactNative = require('react-native');
+
+var __require = /* @__PURE__ */ ((x) => typeof require !== "undefined" ? require : typeof Proxy !== "undefined" ? new Proxy(x, {
+  get: (a, b) => (typeof require !== "undefined" ? require : a)[b]
+}) : x)(function(x) {
+  if (typeof require !== "undefined") return require.apply(this, arguments);
+  throw Error('Dynamic require of "' + x + '" is not supported');
+});
+function createMemoryStorage() {
+  const store = /* @__PURE__ */ new Map();
+  return {
+    get: (key) => Promise.resolve(store.get(key)),
+    set: (key, value) => {
+      store.set(key, value);
+      return Promise.resolve();
+    },
+    delete: (key) => {
+      store.delete(key);
+      return Promise.resolve();
+    },
+    clearAll: () => {
+      store.clear();
+      return Promise.resolve();
+    },
+    keys: () => Promise.resolve(Array.from(store.keys()))
+  };
+}
+function createNativeStorage() {
+  const MMKV = __require("react-native-mmkv").MMKV;
+  const mmkv = new MMKV({ id: "react-smart-query-v2" });
+  return {
+    get: (key) => Promise.resolve(mmkv.getString(key) ?? void 0),
+    set: (key, value) => Promise.resolve(void mmkv.set(key, value)),
+    delete: (key) => Promise.resolve(void mmkv.delete(key)),
+    clearAll: () => Promise.resolve(void mmkv.clearAll()),
+    keys: () => Promise.resolve(mmkv.getAllKeys())
+  };
+}
+var IDB_NAME = "SmartQueryV2";
+var IDB_STORE = "entries";
+var IDB_VERSION = 1;
+function isIDBAvailable() {
+  return typeof globalThis !== "undefined" && typeof globalThis.indexedDB !== "undefined";
+}
+function openIDB() {
+  return new Promise((resolve, reject) => {
+    const req = indexedDB.open(IDB_NAME, IDB_VERSION);
+    req.onupgradeneeded = (e) => {
+      const db = e.target.result;
+      if (!db.objectStoreNames.contains(IDB_STORE)) {
+        db.createObjectStore(IDB_STORE);
+      }
+    };
+    req.onsuccess = (e) => resolve(e.target.result);
+    req.onerror = () => reject(req.error);
+    req.onblocked = () => reject(new Error("IDB blocked by another tab"));
+  });
+}
+var _idb = null;
+var getIDB = () => {
+  _idb ??= openIDB();
+  return _idb;
+};
+function idbWrap(req) {
+  return new Promise((res, rej) => {
+    req.onsuccess = () => res(req.result);
+    req.onerror = () => rej(req.error);
+  });
+}
+function createWebStorage() {
+  if (!isIDBAvailable()) return createMemoryStorage();
+  return {
+    async get(key) {
+      const db = await getIDB();
+      return idbWrap(
+        db.transaction(IDB_STORE, "readonly").objectStore(IDB_STORE).get(key)
+      );
+    },
+    async set(key, value) {
+      const db = await getIDB();
+      await idbWrap(
+        db.transaction(IDB_STORE, "readwrite").objectStore(IDB_STORE).put(value, key)
+      );
+    },
+    async delete(key) {
+      const db = await getIDB();
+      await idbWrap(
+        db.transaction(IDB_STORE, "readwrite").objectStore(IDB_STORE).delete(key)
+      );
+    },
+    async clearAll() {
+      const db = await getIDB();
+      await idbWrap(
+        db.transaction(IDB_STORE, "readwrite").objectStore(IDB_STORE).clear()
+      );
+    },
+    async keys() {
+      const db = await getIDB();
+      const result = await idbWrap(
+        db.transaction(IDB_STORE, "readonly").objectStore(IDB_STORE).getAllKeys()
+      );
+      return result.map(String);
+    }
+  };
+}
+var storage = reactNative.Platform.OS === "web" ? createWebStorage() : createNativeStorage();
+function getStorage() {
+  return storage;
+}
+
+// src/services/observer.service.ts
+var observers = /* @__PURE__ */ new Set();
+function emit(event) {
+  if (observers.size === 0) return;
+  for (const fn of observers) {
+    try {
+      fn(event);
+    } catch {
+    }
+  }
+}
+
+// src/services/cache.service.ts
+var CURRENT_CACHE_VERSION = 2;
+function cacheKeyFor(queryKey) {
+  return `sq2:${JSON.stringify(queryKey)}`;
+}
+async function readCache(key, queryKey) {
+  try {
+    const storage2 = getStorage();
+    const raw = await storage2.get(key);
+    if (!raw) {
+      if (queryKey) emit({ type: "cache_miss", queryKey });
+      return null;
+    }
+    const entry = JSON.parse(raw);
+    if (entry.version !== CURRENT_CACHE_VERSION) {
+      void storage2.delete(key);
+      if (queryKey) emit({ type: "cache_miss", queryKey });
+      return null;
+    }
+    void storage2.set(
+      key,
+      JSON.stringify({ ...entry, lastAccessedAt: Date.now() })
+    );
+    if (queryKey) emit({ type: "cache_hit", queryKey, cachedAt: entry.cachedAt });
+    return entry;
+  } catch {
+    return null;
+  }
+}
+
+// src/services/queue.service.ts
+var QUEUE_KEY = "sq2:mutation_queue";
+async function loadQueue() {
+  try {
+    const raw = await getStorage().get(QUEUE_KEY);
+    if (!raw) return [];
+    return JSON.parse(raw);
+  } catch {
+    return [];
+  }
+}
+var getQueue = loadQueue;
+var getQueueLength = async () => (await loadQueue()).length;
+
+// src/services/requestLock.service.ts
+var inFlight = /* @__PURE__ */ new Map();
+var inFlightCount = () => inFlight.size;
+var inFlightKeys = () => Array.from(inFlight.keys());
+
+// src/utils/debug.ts
+if (__DEV__) {
+  const debug = {
+    async inspectCache(queryKey) {
+      return readCache(cacheKeyFor(queryKey), queryKey);
+    },
+    async listCacheKeys() {
+      const keys = await getStorage().keys();
+      return keys.filter((k) => k.startsWith("sq2:"));
+    },
+    async clearCache() {
+      await getStorage().clearAll();
+      console.log("[SmartQuery] Cache cleared");
+    },
+    getQueue,
+    getQueueLength,
+    inFlightKeys,
+    inFlightCount,
+    async snapshot() {
+      const [keys, queue] = await Promise.all([
+        debug.listCacheKeys(),
+        debug.getQueue()
+      ]);
+      console.group("[SmartQuery] Debug Snapshot");
+      console.log("Cache entries:", keys.length, keys);
+      console.log("Queued mutations:", queue.length, queue);
+      console.log("In-flight requests:", inFlightKeys());
+      console.groupEnd();
+    }
+  };
+  globalThis.smartQueryDebug = debug;
+  console.log("[SmartQuery] Debug tools ready \u2192 smartQueryDebug.snapshot()");
+}
+//# sourceMappingURL=debug.js.map
+//# sourceMappingURL=debug.js.map

package/dist/utils/debug.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/services/storage.adapter.ts","../../src/services/observer.service.ts","../../src/services/cache.service.ts","../../src/services/queue.service.ts","../../src/services/requestLock.service.ts","../../src/utils/debug.ts"],"names":["Platform","storage"],"mappings":";;;;;;;;;;AAqBA,SAAS,mBAAA,GAAoC;AAC3C,EAAA,MAAM,KAAA,uBAAY,GAAA,EAAoB;AACtC,EAAA,OAAO;AAAA,IACL,GAAA,EAAK,CAAC,GAAA,KAAQ,OAAA,CAAQ,QAAQ,KAAA,CAAM,GAAA,CAAI,GAAG,CAAC,CAAA;AAAA,IAC5C,GAAA,EAAK,CAAC,GAAA,EAAK,KAAA,KAAU;AAAE,MAAA,KAAA,CAAM,GAAA,CAAI,KAAK,KAAK,CAAA;AAAG,MAAA,OAAO,QAAQ,OAAA,EAAQ;AAAA,IAAG,CAAA;AAAA,IACxE,MAAA,EAAQ,CAAC,GAAA,KAAQ;AAAE,MAAA,KAAA,CAAM,OAAO,GAAG,CAAA;AAAG,MAAA,OAAO,QAAQ,OAAA,EAAQ;AAAA,IAAG,CAAA;AAAA,IAChE,UAAU,MAAM;AAAE,MAAA,KAAA,CAAM,KAAA,EAAM;AAAG,MAAA,OAAO,QAAQ,OAAA,EAAQ;AAAA,IAAG,CAAA;AAAA,IAC3D,IAAA,EAAM,MAAM,OAAA,CAAQ,OAAA,CAAQ,MAAM,IAAA,CAAK,KAAA,CAAM,IAAA,EAAM,CAAC;AAAA,GACtD;AACF;AAIA,SAAS,mBAAA,GAAoC;AAC3C,EAAA,MAAM,IAAA,GAAO,SAAA,CAAQ,mBAAmB,CAAA,CAAE,IAAA;AAC1C,EAAA,MAAM,OAAO,IAAI,IAAA,CAAK,EAAE,EAAA,EAAI,wBAAwB,CAAA;AACpD,EAAA,OAAO;AAAA,IACL,GAAA,EAAK,CAAC,GAAA,KAAQ,OAAA,CAAQ,QAAQ,IAAA,CAAK,SAAA,CAAU,GAAG,CAAA,IAAK,MAAS,CAAA;AAAA,IAC9D,GAAA,EAAK,CAAC,GAAA,EAAK,KAAA,KAAU,OAAA,CAAQ,OAAA,CAAQ,KAAK,IAAA,CAAK,GAAA,CAAI,GAAA,EAAK,KAAK,CAAC,CAAA;AAAA,IAC9D,MAAA,EAAQ,CAAC,GAAA,KAAQ,OAAA,CAAQ,QAAQ,KAAK,IAAA,CAAK,MAAA,CAAO,GAAG,CAAC,CAAA;AAAA,IACtD,UAAU,MAAM,OAAA,CAAQ,QAAQ,KAAK,IAAA,CAAK,UAAU,CAAA;AAAA,IACpD,MAAM,MAAM,OAAA,CAAQ,OAAA,CAAQ,IAAA,CAAK,YAAY;AAAA,GAC/C;AACF;AAIA,IAAM,QAAA,GAAW,cAAA;AACjB,IAAM,SAAA,GAAY,SAAA;AAClB,IAAM,WAAA,GAAc,CAAA;AAEpB,SAAS,cAAA,GAA0B;AACjC,EAAA,OAAO,OAAO,UAAA,KAAe,WAAA,IAC3B,OAAQ,WAAkD,SAAA,KAAc,WAAA;AAC5E;AAEA,SAAS,OAAA,GAAgC;AACvC,EAAA,OAAO,IAAI,OAAA,CAAQ,CAAC,OAAA,EAAS,MAAA,KAAW;AACtC,IAAA,MAAM,GAAA,GAAM,SAAA,CAAU,IAAA,CAAK,QAAA,EAAU,WAAW,CAAA;AAChD,IAAA,GAAA,CAAI,eAAA,GAAkB,CAAC,CAAA,KAAM;AAC3B,MAAA,MAAM,EAAA,GAAM,EAAE,MAAA,CAA4B,MAAA;AAC1C,MAAA,IAAI,CAAC,EAAA,CAAG,gBAAA,CAAiB,QAAA,CAAS,SAAS,CAAA,EAAG;AAC5C,QAAA,EAAA,CAAG,kBAAkB,SAAS,CAAA;AAAA,MAChC;AAAA,IACF,CAAA;AACA,IAAA,GAAA,CAAI,YAAY,CAAC,CAAA,KAAM,OAAA,CAAS,CAAA,CAAE,OAA4B,MAAM,CAAA;AACpE,IAAA,GAAA,CAAI,OAAA,GAAU,MAAM,MAAA,CAAO,GAAA,CAAI,KAAK,CAAA;AACpC,IAAA,GAAA,CAAI,YAAY,MAAM,MAAA,CAAO,IAAI,KAAA,CAAM,4BAA4B,CAAC,CAAA;AAAA,EACtE,CAAC,CAAA;AACH;AAEA,IAAI,IAAA,GAAoC,IAAA;AACxC,IAAM,SAAS,MAAM;AAAE,EAAA,IAAA,KAAS,OAAA,EAAQ;AAAG,EAAA,OAAO,IAAA;AAAM,CAAA;AAExD,SAAS,QAAW,GAAA,EAAgC;AAClD,EAAA,OAAO,IAAI,OAAA,CAAQ,CAAC,GAAA,EAAK,GAAA,KAAQ;AAC/B,IAAA,GAAA,CAAI,SAAA,GAAY,MAAM,GAAA,CAAI,GAAA,CAAI,MAAM,CAAA;AACpC,IAAA,GAAA,CAAI,OAAA,GAAU,MAAM,GAAA,CAAI,GAAA,CAAI,KAAK,CAAA;AAAA,EACnC,CAAC,CAAA;AACH;AAEA,SAAS,gBAAA,GAAiC;AAExC,EAAA,IAAI,CAAC,cAAA,EAAe,EAAG,OAAO,mBAAA,EAAoB;AAElD,EAAA,OAAO;AAAA,IACL,MAAM,IAAI,GAAA,EAAK;AACb,MAAA,MAAM,EAAA,GAAK,MAAM,MAAA,EAAO;AACxB,MAAA,OAAO,OAAA;AAAA,QACL,EAAA,CAAG,YAAY,SAAA,EAAW,UAAU,EAAE,WAAA,CAAY,SAAS,CAAA,CAAE,GAAA,CAAI,GAAG;AAAA,OACtE;AAAA,IACF,CAAA;AAAA,IACA,MAAM,GAAA,CAAI,GAAA,EAAK,KAAA,EAAO;AACpB,MAAA,MAAM,EAAA,GAAK,MAAM,MAAA,EAAO;AACxB,MAAA,MAAM,OAAA;AAAA,QACJ,EAAA,CAAG,WAAA,CAAY,SAAA,EAAW,WAAW,CAAA,CAAE,YAAY,SAAS,CAAA,CAAE,GAAA,CAAI,KAAA,EAAO,GAAG;AAAA,OAC9E;AAAA,IACF,CAAA;AAAA,IACA,MAAM,OAAO,GAAA,EAAK;AAChB,MAAA,MAAM,EAAA,GAAK,MAAM,MAAA,EAAO;AACxB,MAAA,MAAM,OAAA;AAAA,QACJ,EAAA,CAAG,YAAY,SAAA,EAAW,WAAW,EAAE,WAAA,CAAY,SAAS,CAAA,CAAE,MAAA,CAAO,GAAG;AAAA,OAC1E;AAAA,IACF,CAAA;AAAA,IACA,MAAM,QAAA,GAAW;AACf,MAAA,MAAM,EAAA,GAAK,MAAM,MAAA,EAAO;AACxB,MAAA,MAAM,OAAA;AAAA,QACJ,EAAA,CAAG,YAAY,SAAA,EAAW,WAAW,EAAE,WAAA,CAAY,SAAS,EAAE,KAAA;AAAM,OACtE;AAAA,IACF,CAAA;AAAA,IACA,MAAM,IAAA,GAAO;AACX,MAAA,MAAM,EAAA,GAAK,MAAM,MAAA,EAAO;AACxB,MAAA,MAAM,SAAS,MAAM,OAAA;AAAA,QACnB,EAAA,CAAG,YAAY,SAAA,EAAW,UAAU,EAAE,WAAA,CAAY,SAAS,EAAE,UAAA;AAAW,OAC1E;AACA,MAAA,OAAO,MAAA,CAAO,IAAI,MAAM,CAAA;AAAA,IAC1B;AAAA,GACF;AACF;AAIO,IAAM,UACXA,oBAAA,CAAS,EAAA,KAAO,KAAA,GAAQ,gBAAA,KAAqB,mBAAA,EAAoB;AAK5D,SAAS,UAAA,GAA2B;AACzC,EAAA,OAA2B,OAAA;AAC7B;;;ACtGA,IAAM,SAAA,uBAAgB,GAAA,EAAgB;AA8B/B,SAAS,KAAK,KAAA,EAAiC;AACpD,EAAA,IAAI,SAAA,CAAU,SAAS,CAAA,EAAG;AAC1B,EAAA,KAAA,MAAW,MAAM,SAAA,EAAW;AAC1B,IAAA,IAAI;AAAE,MAAA,EAAA,CAAG,KAAK,CAAA;AAAA,IAAG,CAAA,CAAA,MAAQ;AAAA,IAA8C;AAAA,EACzE;AACF;;;ACzCO,IAAM,qBAAA,GAAwB,CAAA;AAc9B,SAAS,YAAY,QAAA,EAAsC;AAChE,EAAA,OAAO,CAAA,IAAA,EAAO,IAAA,CAAK,SAAA,CAAU,QAAQ,CAAC,CAAA,CAAA;AACxC;AAIA,eAAsB,SAAA,CACpB,KACA,QAAA,EAC+B;AAC/B,EAAA,IAAI;AACF,IAAA,MAAMC,WAAU,UAAA,EAAW;AAC3B,IAAA,MAAM,GAAA,GAAM,MAAMA,QAAAA,CAAQ,GAAA,CAAI,GAAG,CAAA;AAEjC,IAAA,IAAI,CAAC,GAAA,EAAK;AACR,MAAA,IAAI,UAAU,IAAA,CAAK,EAAE,IAAA,EAAM,YAAA,EAAc,UAAU,CAAA;AACnD,MAAA,OAAO,IAAA;AAAA,IACT;AAEA,IAAA,MAAM,KAAA,GAAQ,IAAA,CAAK,KAAA,CAAM,GAAG,CAAA;AAE5B,IAAA,IAAI,KAAA,CAAM,YAAY,qBAAA,EAAuB;AAC3C,MAAA,KAAKA,QAAAA,CAAQ,OAAO,GAAG,CAAA;AACvB,MAAA,IAAI,UAAU,IAAA,CAAK,EAAE,IAAA,EAAM,YAAA,EAAc,UAAU,CAAA;AACnD,MAAA,OAAO,IAAA;AAAA,IACT;AAGA,IAAA,KAAKA,QAAAA,CAAQ,GAAA;AAAA,MACX,GAAA;AAAA,MACA,IAAA,CAAK,UAAU,EAAE,GAAG,OAAO,cAAA,EAAgB,IAAA,CAAK,GAAA,EAAI,EAAG;AAAA,KACzD;AAEA,IAAA,IAAI,QAAA,OAAe,EAAE,IAAA,EAAM,aAAa,QAAA,EAAU,QAAA,EAAU,KAAA,CAAM,QAAA,EAAU,CAAA;AAC5E,IAAA,OAAO,KAAA;AAAA,EACT,CAAA,CAAA,MAAQ;AACN,IAAA,OAAO,IAAA;AAAA,EACT;AACF;;;ACrDA,IAAM,SAAA,GAAY,oBAAA;AAyFlB,eAAe,SAAA,GAAuC;AACpD,EAAA,IAAI;AACF,IAAA,MAAM,GAAA,GAAM,MAAM,UAAA,EAAW,CAAE,IAAI,SAAS,CAAA;AAC5C,IAAA,IAAI,CAAC,GAAA,EAAK,OAAO,EAAC;AAClB,IAAA,OAAO,IAAA,CAAK,MAAM,GAAG,CAAA;AAAA,EACvB,CAAA,CAAA,MAAQ;AAAE,IAAA,OAAO,EAAC;AAAA,EAAG;AACvB;AAyHO,IAAM,QAAA,GAAW,SAAA;AACjB,IAAM,cAAA,GAAiB,YAAA,CAC3B,MAAM,SAAA,EAAU,EAAG,MAAA;;;ACzOtB,IAAM,QAAA,uBAAe,GAAA,EAA8B;AAW5C,IAAM,aAAA,GAAgB,MAAc,QAAA,CAAS,IAAA;AAC7C,IAAM,eAAe,MAAgB,KAAA,CAAM,IAAA,CAAK,QAAA,CAAS,MAAM,CAAA;;;ACCtE,IAAI,OAAA,EAAS;AACX,EAAA,MAAM,KAAA,GAAQ;AAAA,IACZ,MAAM,aAAa,QAAA,EAA8B;AAC/C,MAAA,OAAO,SAAA,CAAU,WAAA,CAAY,QAAQ,CAAA,EAAG,QAAQ,CAAA;AAAA,IAClD,CAAA;AAAA,IACA,MAAM,aAAA,GAAgB;AACpB,MAAA,MAAM,IAAA,GAAO,MAAM,UAAA,EAAW,CAAE,IAAA,EAAK;AACrC,MAAA,OAAO,KAAK,MAAA,CAAO,CAAC,MAAM,CAAA,CAAE,UAAA,CAAW,MAAM,CAAC,CAAA;AAAA,IAChD,CAAA;AAAA,IACA,MAAM,UAAA,GAAa;AACjB,MAAA,MAAM,UAAA,GAAa,QAAA,EAAS;AAC5B,MAAA,OAAA,CAAQ,IAAI,4BAA4B,CAAA;AAAA,IAC1C,CAAA;AAAA,IACA,QAAA;AAAA,IACA,cAAA;AAAA,IACA,YAAA;AAAA,IACA,aAAA;AAAA,IACA,MAAM,QAAA,GAAW;AACf,MAAA,MAAM,CAAC,IAAA,EAAM,KAAK,CAAA,GAAI,MAAM,QAAQ,GAAA,CAAI;AAAA,QACtC,MAAM,aAAA,EAAc;AAAA,QACpB,MAAM,QAAA;AAAS,OAChB,CAAA;AACD,MAAA,OAAA,CAAQ,MAAM,6BAA6B,CAAA;AAC3C,MAAA,OAAA,CAAQ,GAAA,CAAI,gBAAA,EAAkB,IAAA,CAAK,MAAA,EAAQ,IAAI,CAAA;AAC/C,MAAA,OAAA,CAAQ,GAAA,CAAI,mBAAA,EAAqB,KAAA,CAAM,MAAA,EAAQ,KAAK,CAAA;AACpD,MAAA,OAAA,CAAQ,GAAA,CAAI,qBAAA,EAAuB,YAAA,EAAc,CAAA;AACjD,MAAA,OAAA,CAAQ,QAAA,EAAS;AAAA,IACnB;AAAA,GACF;AAEA,EAAC,WAAuC,eAAA,GAAkB,KAAA;AAC1D,EAAA,OAAA,CAAQ,IAAI,kEAA6D,CAAA;AAC3E","file":"debug.js","sourcesContent":["/**\n * src/services/storage.adapter.ts\n *\n * Platform-aware storage with SSR safety.\n *\n *   iOS / Android  →  react-native-mmkv\n *   Web (browser)  →  IndexedDB\n *   SSR / Node.js  →  in-memory Map (safe no-op, hydrates on client)\n *\n * The SSR guard prevents \"indexedDB is not defined\" crashes in\n * Next.js / Expo Router SSR builds. Data written during SSR is discarded;\n * the client hydrates from real IDB on first mount.\n */\n\nimport { Platform } from \"react-native\";\nimport type { AsyncStorage } from \"../types\";\n\nexport type { AsyncStorage };\n\n// ─── SSR / Node.js in-memory adapter ─────────────────────────────────────────\n\nfunction createMemoryStorage(): AsyncStorage {\n  const store = new Map<string, string>();\n  return {\n    get: (key) => Promise.resolve(store.get(key)),\n    set: (key, value) => { store.set(key, value); return Promise.resolve(); },\n    delete: (key) => { store.delete(key); return Promise.resolve(); },\n    clearAll: () => { store.clear(); return Promise.resolve(); },\n    keys: () => Promise.resolve(Array.from(store.keys())),\n  };\n}\n\n// ─── Native adapter (iOS + Android) ──────────────────────────────────────────\n\nfunction createNativeStorage(): AsyncStorage {\n  const MMKV = require(\"react-native-mmkv\").MMKV;\n  const mmkv = new MMKV({ id: \"react-smart-query-v2\" });\n  return {\n    get: (key) => Promise.resolve(mmkv.getString(key) ?? undefined),\n    set: (key, value) => Promise.resolve(void mmkv.set(key, value)),\n    delete: (key) => Promise.resolve(void mmkv.delete(key)),\n    clearAll: () => Promise.resolve(void mmkv.clearAll()),\n    keys: () => Promise.resolve(mmkv.getAllKeys()),\n  };\n}\n\n// ─── Web adapter (IndexedDB) with SSR guard ───────────────────────────────────\n\nconst IDB_NAME = \"SmartQueryV2\";\nconst IDB_STORE = \"entries\";\nconst IDB_VERSION = 1;\n\nfunction isIDBAvailable(): boolean {\n  return typeof globalThis !== \"undefined\" &&\n    typeof (globalThis as unknown as Record<string, unknown>).indexedDB !== \"undefined\";\n}\n\nfunction openIDB(): Promise<IDBDatabase> {\n  return new Promise((resolve, reject) => {\n    const req = indexedDB.open(IDB_NAME, IDB_VERSION);\n    req.onupgradeneeded = (e) => {\n      const db = (e.target as IDBOpenDBRequest).result;\n      if (!db.objectStoreNames.contains(IDB_STORE)) {\n        db.createObjectStore(IDB_STORE);\n      }\n    };\n    req.onsuccess = (e) => resolve((e.target as IDBOpenDBRequest).result);\n    req.onerror = () => reject(req.error);\n    req.onblocked = () => reject(new Error(\"IDB blocked by another tab\"));\n  });\n}\n\nlet _idb: Promise<IDBDatabase> | null = null;\nconst getIDB = () => { _idb ??= openIDB(); return _idb; };\n\nfunction idbWrap<T>(req: IDBRequest<T>): Promise<T> {\n  return new Promise((res, rej) => {\n    req.onsuccess = () => res(req.result);\n    req.onerror = () => rej(req.error);\n  });\n}\n\nfunction createWebStorage(): AsyncStorage {\n  // SSR guard — return memory storage when IDB is unavailable\n  if (!isIDBAvailable()) return createMemoryStorage();\n\n  return {\n    async get(key) {\n      const db = await getIDB();\n      return idbWrap<string | undefined>(\n        db.transaction(IDB_STORE, \"readonly\").objectStore(IDB_STORE).get(key)\n      );\n    },\n    async set(key, value) {\n      const db = await getIDB();\n      await idbWrap(\n        db.transaction(IDB_STORE, \"readwrite\").objectStore(IDB_STORE).put(value, key)\n      );\n    },\n    async delete(key) {\n      const db = await getIDB();\n      await idbWrap(\n        db.transaction(IDB_STORE, \"readwrite\").objectStore(IDB_STORE).delete(key)\n      );\n    },\n    async clearAll() {\n      const db = await getIDB();\n      await idbWrap(\n        db.transaction(IDB_STORE, \"readwrite\").objectStore(IDB_STORE).clear()\n      );\n    },\n    async keys() {\n      const db = await getIDB();\n      const result = await idbWrap<IDBValidKey[]>(\n        db.transaction(IDB_STORE, \"readonly\").objectStore(IDB_STORE).getAllKeys()\n      );\n      return result.map(String);\n    },\n  };\n}\n\n// ─── Singleton ────────────────────────────────────────────────────────────────\n\nexport const storage: AsyncStorage =\n  Platform.OS === \"web\" ? createWebStorage() : createNativeStorage();\n\n/** Exposed for test utilities to inject a custom adapter */\nlet _overrideStorage: AsyncStorage | null = null;\n\nexport function getStorage(): AsyncStorage {\n  return _overrideStorage ?? storage;\n}\n\n/** @internal — used by SmartQueryTestProvider only */\nexport function _setStorageOverride(s: AsyncStorage | null): void {\n  _overrideStorage = s;\n}\n","/**\n * src/services/observer.service.ts\n *\n * Pluggable observability — emit structured events to any analytics backend.\n *\n * Zero coupling: the library emits; you decide where it goes.\n * Attach observers at app startup; they receive every internal event.\n *\n * @example\n *   // Sentry breadcrumbs\n *   addObserver((event) => {\n *     if (event.type === \"fetch_error\") {\n *       Sentry.addBreadcrumb({ message: event.type, data: event });\n *     }\n *   });\n *\n * @example\n *   // Datadog / Mixpanel\n *   addObserver((event) => {\n *     analytics.track(event.type, event);\n *   });\n *\n * @example\n *   // Simple console logger in dev\n *   if (__DEV__) addObserver(console.log);\n */\n\nimport type { ObservabilityEvent, ObserverFn } from \"../types\";\n\nconst observers = new Set<ObserverFn>();\n\n/**\n * Register an observer. Returns an unsubscribe function.\n *\n * @example\n *   const unsub = addObserver(myLogger);\n *   // Later:\n *   unsub();\n */\nexport function addObserver(fn: ObserverFn): () => void {\n  observers.add(fn);\n  return () => observers.delete(fn);\n}\n\n/** Remove a specific observer */\nexport function removeObserver(fn: ObserverFn): void {\n  observers.delete(fn);\n}\n\n/** Remove all observers */\nexport function clearObservers(): void {\n  observers.clear();\n}\n\n/**\n * @internal — emit an event to all registered observers.\n * Called by cache.service, queue.service, and useSmartQuery.\n * Never throws — observer errors are swallowed to protect the data path.\n */\nexport function emit(event: ObservabilityEvent): void {\n  if (observers.size === 0) return; // fast path — no observers registered\n  for (const fn of observers) {\n    try { fn(event); } catch { /* observer error must not crash the app */ }\n  }\n}\n","/**\n * src/services/cache.service.ts\n *\n * Versioned, LRU-aware cache layer.\n *\n * Features:\n *   • Schema versioning — auto-invalidates stale entries on version bump\n *   • lastAccessedAt tracking — enables LRU eviction\n *   • Configurable max entries per prefix — prevents unbounded growth\n *   • Partial hydration — read a subset of a NormalizedList by ids\n *   • Observability events on hit / miss / write / quota exceeded\n */\n\nimport { getStorage } from \"./storage.adapter\";\nimport { emit } from \"./observer.service\";\nimport type { CacheEntry, NormalizedList, AnyItem } from \"../types\";\n\n// ─── Versioning ───────────────────────────────────────────────────────────────\n\n/**\n * Bump when CacheEntry shape or NormalizedList schema changes in a\n * breaking way. Any stored entry with a lower version is silently discarded.\n */\nexport const CURRENT_CACHE_VERSION = 2;\n\n// ─── LRU config ───────────────────────────────────────────────────────────────\n\nconst DEFAULT_MAX_ENTRIES = 200;\nlet _maxEntries = DEFAULT_MAX_ENTRIES;\n\n/** Override the global max entries limit (call before any reads/writes) */\nexport function setMaxCacheEntries(n: number): void {\n  _maxEntries = n;\n}\n\n// ─── Key derivation ───────────────────────────────────────────────────────────\n\nexport function cacheKeyFor(queryKey: readonly unknown[]): string {\n  return `sq2:${JSON.stringify(queryKey)}`;\n}\n\n// ─── Read ─────────────────────────────────────────────────────────────────────\n\nexport async function readCache<T>(\n  key: string,\n  queryKey?: readonly unknown[]\n): Promise<CacheEntry<T> | null> {\n  try {\n    const storage = getStorage();\n    const raw = await storage.get(key);\n\n    if (!raw) {\n      if (queryKey) emit({ type: \"cache_miss\", queryKey });\n      return null;\n    }\n\n    const entry = JSON.parse(raw) as CacheEntry<T>;\n\n    if (entry.version !== CURRENT_CACHE_VERSION) {\n      void storage.delete(key);\n      if (queryKey) emit({ type: \"cache_miss\", queryKey });\n      return null;\n    }\n\n    // Touch lastAccessedAt for LRU — fire-and-forget, non-blocking\n    void storage.set(\n      key,\n      JSON.stringify({ ...entry, lastAccessedAt: Date.now() })\n    );\n\n    if (queryKey) emit({ type: \"cache_hit\", queryKey, cachedAt: entry.cachedAt });\n    return entry;\n  } catch {\n    return null;\n  }\n}\n\n// ─── Write ────────────────────────────────────────────────────────────────────\n\nexport async function writeCache<T>(\n  key: string,\n  data: T,\n  queryKey?: readonly unknown[]\n): Promise<void> {\n  try {\n    const storage = getStorage();\n    const now = Date.now();\n    const entry: CacheEntry<T> = {\n      version: CURRENT_CACHE_VERSION,\n      data,\n      cachedAt: now,\n      lastAccessedAt: now,\n    };\n\n    const serialized = JSON.stringify(entry);\n\n    try {\n      await storage.set(key, serialized);\n      if (queryKey) {\n        emit({ type: \"cache_write\", queryKey, dataSize: serialized.length });\n      }\n    } catch (quotaErr) {\n      emit({ type: \"storage_quota_exceeded\", key });\n      // Attempt LRU eviction then retry once\n      await evictLRUEntries();\n      await storage.set(key, serialized);\n    }\n\n    // Async LRU check — doesn't block the write\n    void checkAndEvict();\n  } catch {\n    // Fail silently — a cache write failure must never crash the app\n  }\n}\n\n// ─── Delete ───────────────────────────────────────────────────────────────────\n\nexport async function deleteCache(key: string): Promise<void> {\n  try {\n    await getStorage().delete(key);\n  } catch {}\n}\n\n// ─── LRU eviction ─────────────────────────────────────────────────────────────\n\ninterface LRUMeta {\n  key: string;\n  lastAccessedAt: number;\n}\n\nasync function checkAndEvict(): Promise<void> {\n  const storage = getStorage();\n  const allKeys = await storage.keys();\n  const sqKeys = allKeys.filter((k) => k.startsWith(\"sq2:\"));\n\n  if (sqKeys.length <= _maxEntries) return;\n\n  await evictLRUEntries(sqKeys);\n}\n\nasync function evictLRUEntries(sqKeys?: string[]): Promise<void> {\n  const storage = getStorage();\n  const keys = sqKeys ?? (await storage.keys()).filter((k) => k.startsWith(\"sq2:\"));\n\n  // Read lastAccessedAt for each entry — lightweight parse\n  const metas: LRUMeta[] = [];\n  await Promise.all(\n    keys.map(async (key) => {\n      try {\n        const raw = await storage.get(key);\n        if (!raw) return;\n        const parsed = JSON.parse(raw) as Partial<CacheEntry<unknown>>;\n        metas.push({ key, lastAccessedAt: parsed.lastAccessedAt ?? 0 });\n      } catch {}\n    })\n  );\n\n  // Sort oldest-first and evict the bottom 20%\n  metas.sort((a, b) => a.lastAccessedAt - b.lastAccessedAt);\n  const evictCount = Math.max(1, Math.floor(metas.length * 0.2));\n  const toEvict = metas.slice(0, evictCount);\n\n  await Promise.all(toEvict.map(({ key }) => storage.delete(key)));\n}\n\n// ─── Partial hydration ────────────────────────────────────────────────────────\n\n/**\n * Read a subset of a NormalizedList cache entry by item ids.\n *\n * Use for pagination, lazy loading, or detail views that only need\n * a handful of items from a large cached list.\n *\n * @returns null if the cache entry doesn't exist.\n *          Empty array if none of the requested ids are cached.\n *\n * @example\n *   const items = await getPartialCache<Expense>(\n *     cacheKeyFor([\"expenses\", tripId]),\n *     [\"exp_1\", \"exp_2\"]\n *   );\n */\nexport async function getPartialCache<T extends AnyItem>(\n  key: string,\n  ids: string[]\n): Promise<T[] | null> {\n  const entry = await readCache<NormalizedList<T>>(key);\n  if (!entry) return null;\n\n  const { byId } = entry.data;\n  const result: T[] = [];\n  for (const id of ids) {\n    if (id in byId) result.push(byId[id]);\n  }\n  return result;\n}\n\n// ─── TTL check ────────────────────────────────────────────────────────────────\n\nexport function isCacheStale(entry: CacheEntry<unknown>, ttlMs: number): boolean {\n  return Date.now() - entry.cachedAt > ttlMs;\n}\n","/**\n * src/services/queue.service.ts\n *\n * Offline Mutation Queue — persist-first, retry-on-reconnect, with coalescing.\n *\n * Key design decisions:\n *   • Sequential FIFO processing preserves causal ordering\n *   • Coalescing: two mutations with the same entityKey are merged before send\n *     (prevents stale optimistic updates from racing each other)\n *   • Exponential backoff with full jitter — no thundering herd on reconnect\n *   • Observability events on enqueue / success / failure / drain\n *   • clearQueue() on logout prevents cross-user mutation leakage\n */\n\nimport { getStorage } from \"./storage.adapter\";\nimport { emit } from \"./observer.service\";\nimport type { QueuedMutation, MutationType } from \"../types\";\n\nexport type { QueuedMutation, MutationType };\n\n// ─── Constants ────────────────────────────────────────────────────────────────\n\nconst QUEUE_KEY = \"sq2:mutation_queue\";\nconst DEFAULT_MAX_RETRIES = 5;\nconst BACKOFF_BASE_MS = 1_000;\nconst BACKOFF_MAX_MS = 120_000;\n\n// ─── Executor registry ────────────────────────────────────────────────────────\n\ntype Executor<P = unknown> = (mutation: QueuedMutation<P>) => Promise<void>;\nconst executors = new Map<string, Executor>();\n\n/**\n * Register an executor for a mutation type.\n * Must be called at app startup before mutations are enqueued.\n *\n * @example\n *   registerExecutor(\"ADD_ITEM\", async (m) => {\n *     await api.post(\"/expenses\", m.payload);\n *   });\n */\nexport function registerExecutor<TPayload>(\n  type: string,\n  fn: Executor<TPayload>\n): void {\n  executors.set(type, fn as Executor);\n}\n\n// ─── Queue coalescing ─────────────────────────────────────────────────────────\n\n/**\n * Coalesce mutations with the same entityKey.\n *\n * Rules (applied in order for each entityKey group):\n *   • REMOVE_ITEM after any other mutation → keep only REMOVE_ITEM\n *   • Multiple UPDATE_ITEM → keep only the latest (highest enqueuedAt)\n *   • Multiple ADD_ITEM → keep only the latest (shouldn't normally happen)\n *   • ADD_ITEM then UPDATE_ITEM → merge into a single ADD_ITEM with latest payload\n *\n * Mutations without an entityKey are never coalesced.\n */\nfunction coalesceQueue(queue: QueuedMutation[]): QueuedMutation[] {\n  // Separate coalesable (have entityKey) from non-coalesable\n  const byEntityKey = new Map<string, QueuedMutation[]>();\n  const standalone: QueuedMutation[] = [];\n\n  for (const m of queue) {\n    if (!m.entityKey) { standalone.push(m); continue; }\n    const group = byEntityKey.get(m.entityKey) ?? [];\n    group.push(m);\n    byEntityKey.set(m.entityKey, group);\n  }\n\n  const coalesced: QueuedMutation[] = [];\n\n  for (const group of byEntityKey.values()) {\n    // Sort by enqueuedAt ascending within each group\n    group.sort((a, b) => a.enqueuedAt - b.enqueuedAt);\n\n    const hasRemove = group.some((m) => m.type === \"REMOVE_ITEM\");\n    if (hasRemove) {\n      // Keep only the last REMOVE_ITEM — all preceding mutations are superseded\n      const removeOp = [...group].reverse().find((m) => m.type === \"REMOVE_ITEM\")!;\n      coalesced.push(removeOp);\n      continue;\n    }\n\n    const addOp = group.find((m) => m.type === \"ADD_ITEM\");\n    const updateOps = group.filter((m) => m.type === \"UPDATE_ITEM\");\n\n    if (addOp && updateOps.length > 0) {\n      // ADD + UPDATE(s) → single ADD with the latest payload\n      const latestUpdate = updateOps[updateOps.length - 1];\n      coalesced.push({ ...addOp, payload: latestUpdate.payload });\n    } else if (addOp) {\n      coalesced.push(addOp);\n    } else if (updateOps.length > 0) {\n      // Multiple UPDATEs → keep latest\n      coalesced.push(updateOps[updateOps.length - 1]);\n    } else {\n      // CUSTOM or mixed — keep all\n      coalesced.push(...group);\n    }\n  }\n\n  // Restore original ordering by enqueuedAt\n  return [...standalone, ...coalesced].sort((a, b) => a.enqueuedAt - b.enqueuedAt);\n}\n\n// ─── Persistence ──────────────────────────────────────────────────────────────\n\nasync function loadQueue(): Promise<QueuedMutation[]> {\n  try {\n    const raw = await getStorage().get(QUEUE_KEY);\n    if (!raw) return [];\n    return JSON.parse(raw) as QueuedMutation[];\n  } catch { return []; }\n}\n\nasync function saveQueue(queue: QueuedMutation[]): Promise<void> {\n  try {\n    await getStorage().set(QUEUE_KEY, JSON.stringify(queue));\n  } catch {}\n}\n\n// ─── Backoff ──────────────────────────────────────────────────────────────────\n\nfunction backoffMs(retryCount: number): number {\n  const exp = Math.min(BACKOFF_BASE_MS * 2 ** retryCount, BACKOFF_MAX_MS);\n  return Math.random() * exp; // full jitter\n}\n\n// ─── Processing ───────────────────────────────────────────────────────────────\n\nlet isProcessing = false;\n\n/**\n * Process all pending mutations in FIFO order.\n * Coalesces before sending to minimize network calls.\n * Safe to call concurrently — guarded by isProcessing flag.\n */\nexport async function processQueue(): Promise<void> {\n  if (isProcessing) return;\n  isProcessing = true;\n\n  try {\n    const raw = await loadQueue();\n    if (raw.length === 0) return;\n\n    const queue = coalesceQueue(raw);\n    const now = Date.now();\n    const remaining: QueuedMutation[] = [];\n\n    for (const mutation of queue) {\n      if (mutation.nextRetryAt > now) { remaining.push(mutation); continue; }\n\n      const executor = executors.get(mutation.type);\n      if (!executor) {\n        if (__DEV__) {\n          console.warn(`[SmartQuery] No executor for \"${mutation.type}\"`);\n        }\n        remaining.push(mutation);\n        continue;\n      }\n\n      try {\n        await executor(mutation);\n        emit({ type: \"queue_success\", mutationId: mutation.id });\n      } catch (err) {\n        const nextRetry = mutation.retryCount + 1;\n        emit({ type: \"queue_failure\", mutationId: mutation.id, retryCount: nextRetry });\n\n        if (nextRetry >= mutation.maxRetries) {\n          if (__DEV__) {\n            console.error(\n              `[SmartQuery] Mutation ${mutation.id} dropped after ${mutation.maxRetries} retries`,\n              err\n            );\n          }\n        } else {\n          remaining.push({\n            ...mutation,\n            retryCount: nextRetry,\n            nextRetryAt: now + backoffMs(nextRetry),\n          });\n        }\n      }\n    }\n\n    await saveQueue(remaining);\n    if (remaining.length === 0) emit({ type: \"queue_drained\" });\n  } finally {\n    isProcessing = false;\n  }\n}\n\n// ─── Public API ───────────────────────────────────────────────────────────────\n\n/**\n * Add a mutation to the persistent queue.\n *\n * @param entityKey  Optional logical key for coalescing (e.g. \"expense:exp_123\").\n *                   Mutations with the same entityKey are merged before sending.\n */\nexport async function enqueueMutation<TPayload>(options: {\n  type: MutationType | string;\n  queryKey: readonly unknown[];\n  payload: TPayload;\n  entityKey?: string;\n  maxRetries?: number;\n}): Promise<void> {\n  const queue = await loadQueue();\n  const mutation: QueuedMutation<TPayload> = {\n    id: `mut_${Date.now()}_${Math.random().toString(36).slice(2, 8)}`,\n    type: options.type as MutationType,\n    entityKey: options.entityKey,\n    queryKey: options.queryKey,\n    payload: options.payload,\n    enqueuedAt: Date.now(),\n    retryCount: 0,\n    maxRetries: options.maxRetries ?? DEFAULT_MAX_RETRIES,\n    nextRetryAt: 0,\n  };\n  queue.push(mutation as QueuedMutation);\n  await saveQueue(queue);\n  emit({ type: \"queue_enqueue\", mutationId: mutation.id, mutationType: mutation.type });\n}\n\n/** Process queue on app startup */\nexport async function initQueue(): Promise<void> {\n  await processQueue();\n}\n\n/** Clear all pending mutations — call on logout */\nexport async function clearQueue(): Promise<void> {\n  await saveQueue([]);\n}\n\nexport const getQueue = loadQueue;\nexport const getQueueLength = async (): Promise<number> =>\n  (await loadQueue()).length;\n","/**\n * src/services/requestLock.service.ts\n *\n * In-flight request deduplication.\n * Concurrent calls with the same key share one Promise — only one fetch fires.\n */\n\nconst inFlight = new Map<string, Promise<unknown>>();\n\nexport function fetchWithLock<T>(key: string, fn: () => Promise<T>): Promise<T> {\n  const existing = inFlight.get(key);\n  if (existing) return existing as Promise<T>;\n\n  const promise = fn().finally(() => inFlight.delete(key));\n  inFlight.set(key, promise);\n  return promise;\n}\n\nexport const inFlightCount = (): number => inFlight.size;\nexport const inFlightKeys = (): string[] => Array.from(inFlight.keys());\n","/**\n * src/utils/debug.ts\n *\n * Developer debug tools — zero production overhead.\n * Attach to globalThis only when __DEV__ is true.\n *\n * Import once as a side effect:\n *   import \"react-smart-query/debug\"; // in App.tsx\n *\n * Then use in debugger / console:\n *   await smartQueryDebug.snapshot()\n *   await smartQueryDebug.inspectCache([\"expenses\", \"trip_1\"])\n *   smartQueryDebug.inFlightKeys()\n */\n\nimport { cacheKeyFor, readCache } from \"../services/cache.service\";\nimport { getStorage } from \"../services/storage.adapter\";\nimport { getQueue, getQueueLength } from \"../services/queue.service\";\nimport { inFlightCount, inFlightKeys } from \"../services/requestLock.service\";\n\nif (__DEV__) {\n  const debug = {\n    async inspectCache(queryKey: readonly unknown[]) {\n      return readCache(cacheKeyFor(queryKey), queryKey);\n    },\n    async listCacheKeys() {\n      const keys = await getStorage().keys();\n      return keys.filter((k) => k.startsWith(\"sq2:\"));\n    },\n    async clearCache() {\n      await getStorage().clearAll();\n      console.log(\"[SmartQuery] Cache cleared\");\n    },\n    getQueue,\n    getQueueLength,\n    inFlightKeys,\n    inFlightCount,\n    async snapshot() {\n      const [keys, queue] = await Promise.all([\n        debug.listCacheKeys(),\n        debug.getQueue(),\n      ]);\n      console.group(\"[SmartQuery] Debug Snapshot\");\n      console.log(\"Cache entries:\", keys.length, keys);\n      console.log(\"Queued mutations:\", queue.length, queue);\n      console.log(\"In-flight requests:\", inFlightKeys());\n      console.groupEnd();\n    },\n  };\n\n  (globalThis as Record<string, unknown>).smartQueryDebug = debug;\n  console.log(\"[SmartQuery] Debug tools ready → smartQueryDebug.snapshot()\");\n}\n\nexport {};\n"]}

package/dist/utils/debug.mjs

@@ -0,0 +1,40 @@
+import { init_requestLock_service, inFlightCount, inFlightKeys, getQueueLength, getQueue } from '../chunk-KLJQATIV.mjs';
+import { readCache, cacheKeyFor } from '../chunk-KSLDOL27.mjs';
+import { getStorage } from '../chunk-QRCVY7UR.mjs';
+
+// src/utils/debug.ts
+init_requestLock_service();
+if (__DEV__) {
+  const debug = {
+    async inspectCache(queryKey) {
+      return readCache(cacheKeyFor(queryKey), queryKey);
+    },
+    async listCacheKeys() {
+      const keys = await getStorage().keys();
+      return keys.filter((k) => k.startsWith("sq2:"));
+    },
+    async clearCache() {
+      await getStorage().clearAll();
+      console.log("[SmartQuery] Cache cleared");
+    },
+    getQueue,
+    getQueueLength,
+    inFlightKeys,
+    inFlightCount,
+    async snapshot() {
+      const [keys, queue] = await Promise.all([
+        debug.listCacheKeys(),
+        debug.getQueue()
+      ]);
+      console.group("[SmartQuery] Debug Snapshot");
+      console.log("Cache entries:", keys.length, keys);
+      console.log("Queued mutations:", queue.length, queue);
+      console.log("In-flight requests:", inFlightKeys());
+      console.groupEnd();
+    }
+  };
+  globalThis.smartQueryDebug = debug;
+  console.log("[SmartQuery] Debug tools ready \u2192 smartQueryDebug.snapshot()");
+}
+//# sourceMappingURL=debug.mjs.map
+//# sourceMappingURL=debug.mjs.map

package/dist/utils/debug.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/utils/debug.ts"],"names":[],"mappings":";;;;;AAkBA,wBAAA,EAAA;AAEA,IAAI,OAAA,EAAS;AACX,EAAA,MAAM,KAAA,GAAQ;AAAA,IACZ,MAAM,aAAa,QAAA,EAA8B;AAC/C,MAAA,OAAO,SAAA,CAAU,WAAA,CAAY,QAAQ,CAAA,EAAG,QAAQ,CAAA;AAAA,IAClD,CAAA;AAAA,IACA,MAAM,aAAA,GAAgB;AACpB,MAAA,MAAM,IAAA,GAAO,MAAM,UAAA,EAAW,CAAE,IAAA,EAAK;AACrC,MAAA,OAAO,KAAK,MAAA,CAAO,CAAC,MAAM,CAAA,CAAE,UAAA,CAAW,MAAM,CAAC,CAAA;AAAA,IAChD,CAAA;AAAA,IACA,MAAM,UAAA,GAAa;AACjB,MAAA,MAAM,UAAA,GAAa,QAAA,EAAS;AAC5B,MAAA,OAAA,CAAQ,IAAI,4BAA4B,CAAA;AAAA,IAC1C,CAAA;AAAA,IACA,QAAA;AAAA,IACA,cAAA;AAAA,IACA,YAAA;AAAA,IACA,aAAA;AAAA,IACA,MAAM,QAAA,GAAW;AACf,MAAA,MAAM,CAAC,IAAA,EAAM,KAAK,CAAA,GAAI,MAAM,QAAQ,GAAA,CAAI;AAAA,QACtC,MAAM,aAAA,EAAc;AAAA,QACpB,MAAM,QAAA;AAAS,OAChB,CAAA;AACD,MAAA,OAAA,CAAQ,MAAM,6BAA6B,CAAA;AAC3C,MAAA,OAAA,CAAQ,GAAA,CAAI,gBAAA,EAAkB,IAAA,CAAK,MAAA,EAAQ,IAAI,CAAA;AAC/C,MAAA,OAAA,CAAQ,GAAA,CAAI,mBAAA,EAAqB,KAAA,CAAM,MAAA,EAAQ,KAAK,CAAA;AACpD,MAAA,OAAA,CAAQ,GAAA,CAAI,qBAAA,EAAuB,YAAA,EAAc,CAAA;AACjD,MAAA,OAAA,CAAQ,QAAA,EAAS;AAAA,IACnB;AAAA,GACF;AAEA,EAAC,WAAuC,eAAA,GAAkB,KAAA;AAC1D,EAAA,OAAA,CAAQ,IAAI,kEAA6D,CAAA;AAC3E","file":"debug.mjs","sourcesContent":["/**\n * src/utils/debug.ts\n *\n * Developer debug tools — zero production overhead.\n * Attach to globalThis only when __DEV__ is true.\n *\n * Import once as a side effect:\n *   import \"react-smart-query/debug\"; // in App.tsx\n *\n * Then use in debugger / console:\n *   await smartQueryDebug.snapshot()\n *   await smartQueryDebug.inspectCache([\"expenses\", \"trip_1\"])\n *   smartQueryDebug.inFlightKeys()\n */\n\nimport { cacheKeyFor, readCache } from \"../services/cache.service\";\nimport { getStorage } from \"../services/storage.adapter\";\nimport { getQueue, getQueueLength } from \"../services/queue.service\";\nimport { inFlightCount, inFlightKeys } from \"../services/requestLock.service\";\n\nif (__DEV__) {\n  const debug = {\n    async inspectCache(queryKey: readonly unknown[]) {\n      return readCache(cacheKeyFor(queryKey), queryKey);\n    },\n    async listCacheKeys() {\n      const keys = await getStorage().keys();\n      return keys.filter((k) => k.startsWith(\"sq2:\"));\n    },\n    async clearCache() {\n      await getStorage().clearAll();\n      console.log(\"[SmartQuery] Cache cleared\");\n    },\n    getQueue,\n    getQueueLength,\n    inFlightKeys,\n    inFlightCount,\n    async snapshot() {\n      const [keys, queue] = await Promise.all([\n        debug.listCacheKeys(),\n        debug.getQueue(),\n      ]);\n      console.group(\"[SmartQuery] Debug Snapshot\");\n      console.log(\"Cache entries:\", keys.length, keys);\n      console.log(\"Queued mutations:\", queue.length, queue);\n      console.log(\"In-flight requests:\", inFlightKeys());\n      console.groupEnd();\n    },\n  };\n\n  (globalThis as Record<string, unknown>).smartQueryDebug = debug;\n  console.log(\"[SmartQuery] Debug tools ready → smartQueryDebug.snapshot()\");\n}\n\nexport {};\n"]}

package/docs/API_REFERENCE.md

@@ -0,0 +1,149 @@
+# React Smart Query Documentation
+
+Welcome to the detailed documentation for `react-smart-query`. This library provides a robust, offline-first, normalized data orchestration layer tailored for React Native and Web applications, built on top of TanStack Query.
+
+## Table of Contents
+
+1. [Core Concepts](#core-concepts)
+2. [Hooks API](#hooks-api)
+   - [`useSmartQuery`](#usesmartquery)
+   - [`useInfiniteSmartQuery`](#useinfinitesmartquery)
+   - [`useSmartMutation`](#usesmartmutation)
+   - [`useSmartQuerySelector`](#usesmartqueryselector)
+3. [Factory API](#factory-api)
+   - [`createTypedQuery`](#createtypedquery)
+4. [Advanced Features](#advanced-features)
+   - [Offline Queue](#offline-queue)
+   - [Normalization & Cache](#normalization--cache)
+   - [Debugging](#debugging)
+
+---
+
+## Core Concepts
+
+### Normalization
+Instead of keeping duplicate instances of data items in memory across different query responses (especially in paginated lists), `react-smart-query` stores data in a normalized cache (`byId` map and `allIds` array). This ensures that updates to an item in one place immediately reflect everywhere that item is rendered.
+
+### Offline-First Architecture
+Mutations made while the device is offline are pushed to a persistent queue. When the device regains connectivity, the queue is processed automatically, ensuring no data loss.
+
+### Deterministic Sorting
+For infinite lists, `react-smart-query` maintains a strictly ordered aggregate list (`allIds`). When new items are added, they are inserted using binary search (O(log n)), guaranteeing perfectly sorted lists without "flickering".
+
+---
+
+## Hooks API
+
+### `useSmartQuery`
+A drop-in enhancement for TanStack's `useQuery`. It seamlessly reads from and writes to the normalized store.
+
+**Example Usage:**
+```tsx
+import { useSmartQuery } from 'react-smart-query';
+
+const { data, isLoading, error } = useSmartQuery({
+  queryKey: ['userProfile', userId],
+  queryFn: () => fetchUserProfile(userId),
+});
+```
+
+### `useInfiniteSmartQuery`
+The flagship hook for handling paginated data. It abstracts away the complexity of infinite scrolling, normalization, and sorting.
+
+**Key Props:**
+- `queryKey`: Unique identifier for the query.
+- `queryFn`: Function to fetch a page of data.
+- `getNextCursor`: Function to extract the next page token from a response.
+- `getItemId`: Function extracting a unique ID from an item.
+- `sortComparator`: Function sorting items in the list.
+
+**Example Usage:**
+```tsx
+import { useInfiniteSmartQuery } from 'react-smart-query';
+
+const { data, addItem, removeItem, fetchNextPage } = useInfiniteSmartQuery({
+  queryKey: ['feed'],
+  queryFn: ({ pageParam }) => fetchFeed(pageParam),
+  getNextCursor: (res) => res.nextCursor,
+  select: (res) => res.items,
+  getItemId: (item) => item.id,
+  sortComparator: (a, b) => b.timestamp - a.timestamp,
+});
+
+// Mutating the list
+const onPostCreated = (newPost) => addItem(newPost);
+const onPostDeleted = (postId) => removeItem(postId);
+```
+
+### `useSmartMutation`
+Handles creating, updating, or deleting items. It integrates with the offline queue and provides optimistic UI updates.
+
+**Example Usage:**
+```tsx
+import { useSmartMutation } from 'react-smart-query';
+
+const mutate = useSmartMutation({
+  mutationFn: (newExpense) => api.post('/expenses', newExpense),
+  onMutate: (newExpense) => {
+    // Optimistically update UI
+  },
+});
+```
+
+### `useSmartQuerySelector`
+Allows fine-grained subscriptions to a slice of the cached data, preventing unnecessary re-renders.
+
+**Example Usage:**
+```tsx
+import { useSmartQuerySelector } from 'react-smart-query';
+
+const specificItem = useSmartQuerySelector(['expenses'], (data) => data.find(i => i.id === '123'));
+```
+
+---
+
+## Factory API
+
+### `createTypedQuery`
+Provides a way to create strongly-typed query configurations that can be reused across your application, ensuring type safety and consistency.
+
+**Example Usage:**
+```tsx
+import { createTypedQuery } from 'react-smart-query';
+
+export const userQuery = createTypedQuery({
+  queryKeyBase: ['users'],
+  queryFn: (id: string) => fetchUser(id),
+});
+
+// In component:
+const { data } = useSmartQuery(userQuery.buildConfig('user-123'));
+```
+
+---
+
+## Advanced Features
+
+### Offline Queue
+The library automatically handles queuing mutations when offline.
+To interact with it manually (rarely needed):
+```tsx
+import { getQueue, clearQueue, processQueue } from 'react-smart-query';
+```
+
+### Normalization & Cache
+While hooks handle normalization automatically, you can interact with the raw cache:
+```tsx
+import { readCache, writeCache, clearAllSmartCache } from 'react-smart-query';
+```
+
+### Debugging
+For development, you can enable verbose logging and snapshot tools.
+```tsx
+// In your App entry point (DEV ONLY)
+import "react-smart-query/debug";
+
+// Access the debugger window or call globally (if attached)
+import { smartQueryDebug } from 'react-smart-query';
+smartQueryDebug.snapshot();
+```

package/docs/GUIDELINES.md

@@ -0,0 +1,23 @@
+# Best Practices & Guidelines
+
+To get the most out of `react-smart-query`, follow these architectural guidelines.
+
+## 1. Always provide an ID and a Sort Comparator
+When using `useInfiniteSmartQuery`, `getItemId` and `sortComparator` are critical. Even if your API returns items in perfect order, the sort comparator is how `react-smart-query` knows where to insert *optimistic or newly added offline items*.
+
+```typescript
+// Good
+sortComparator: (a, b) => new Date(b.createdAt).getTime() - new Date(a.createdAt).getTime()
+```
+
+## 2. Leverage Background Fetch Guards
+`react-smart-query` protects local mutations. If you add an item locally, and a subsequent background refetch (from `react-query`) does *not* contain that item, it won't be deleted if it was created locally within the guard window (default 5 minutes).
+
+## 3. Keep Cache Keys Consistent
+Use strongly typed cache keys or leverage `createTypedQuery` to ensure your keys match exactly across your application. Normalization ties items to keys; a typo in a key implies an entirely separate data store.
+
+## 4. Handle Offline Sync Gracefully
+The queue processes mutations automatically when the device comes online. Ensure your `mutationFn` in `useSmartMutation` is robust enough to handle data that might be slightly stale.
+
+## 5. Don't Store Enormous Lists Indefinitely
+The library automatically applies a soft trim when lists exceed a certain threshold to prevent memory bloat, but avoid querying 10,000 items in a single non-paginated `useSmartQuery`.