@tanstack/react-db 0.1.4 → 0.1.5

package/dist/cjs/useLiveQuery.cjs

@@ -4,7 +4,9 @@ const react = require("react");
 const db = require("@tanstack/db");
 function useLiveQuery(configOrQueryOrCollection, deps = []) {
   const isCollection = configOrQueryOrCollection && typeof configOrQueryOrCollection === `object` && typeof configOrQueryOrCollection.subscribeChanges === `function` && typeof configOrQueryOrCollection.startSyncImmediate === `function` && typeof configOrQueryOrCollection.id === `string`;
-  const collectionRef = react.useRef(null);
+  const collectionRef = react.useRef(
+    null
+  );
   const depsRef = react.useRef(null);
   const configRef = react.useRef(null);
   const needsNewCollection = !collectionRef.current || isCollection && configRef.current !== configOrQueryOrCollection || !isCollection && (depsRef.current === null || depsRef.current.length !== deps.length || depsRef.current.some((dep, i) => dep !== deps[i]));
@@ -55,16 +57,10 @@ function useLiveQuery(configOrQueryOrCollection, deps = []) {
     getSnapshotRef.current = () => {
       const currentVersion = versionRef.current;
       const currentCollection = collectionRef.current;
-      if (!snapshotRef.current || snapshotRef.current._version !== currentVersion) {
+      if (!snapshotRef.current || snapshotRef.current.version !== currentVersion || snapshotRef.current.collection !== currentCollection) {
         snapshotRef.current = {
-          get state() {
-            return new Map(currentCollection.entries());
-          },
-          get data() {
-            return Array.from(currentCollection.values());
-          },
           collection: currentCollection,
-          _version: currentVersion
+          version: currentVersion
         };
       }
       return snapshotRef.current;
@@ -74,17 +70,36 @@ function useLiveQuery(configOrQueryOrCollection, deps = []) {
     subscribeRef.current,
     getSnapshotRef.current
   );
-  return {
-    state: snapshot.state,
-    data: snapshot.data,
-    collection: snapshot.collection,
-    status: snapshot.collection.status,
-    isLoading: snapshot.collection.status === `loading` || snapshot.collection.status === `initialCommit`,
-    isReady: snapshot.collection.status === `ready`,
-    isIdle: snapshot.collection.status === `idle`,
-    isError: snapshot.collection.status === `error`,
-    isCleanedUp: snapshot.collection.status === `cleaned-up`
-  };
+  const returnedSnapshotRef = react.useRef(null);
+  const returnedRef = react.useRef(null);
+  if (!returnedSnapshotRef.current || returnedSnapshotRef.current.version !== snapshot.version || returnedSnapshotRef.current.collection !== snapshot.collection) {
+    const entries = Array.from(snapshot.collection.entries());
+    let stateCache = null;
+    let dataCache = null;
+    returnedRef.current = {
+      get state() {
+        if (!stateCache) {
+          stateCache = new Map(entries);
+        }
+        return stateCache;
+      },
+      get data() {
+        if (!dataCache) {
+          dataCache = entries.map(([, value]) => value);
+        }
+        return dataCache;
+      },
+      collection: snapshot.collection,
+      status: snapshot.collection.status,
+      isLoading: snapshot.collection.status === `loading` || snapshot.collection.status === `initialCommit`,
+      isReady: snapshot.collection.status === `ready`,
+      isIdle: snapshot.collection.status === `idle`,
+      isError: snapshot.collection.status === `error`,
+      isCleanedUp: snapshot.collection.status === `cleaned-up`
+    };
+    returnedSnapshotRef.current = snapshot;
+  }
+  return returnedRef.current;
 }
 exports.useLiveQuery = useLiveQuery;
 //# sourceMappingURL=useLiveQuery.cjs.map

package/dist/cjs/useLiveQuery.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"useLiveQuery.cjs","sources":["../../src/useLiveQuery.ts"],"sourcesContent":["import { useRef, useSyncExternalStore } from \"react\"\nimport { createLiveQueryCollection } from \"@tanstack/db\"\nimport type {\n  Collection,\n  CollectionStatus,\n  Context,\n  GetResult,\n  InitialQueryBuilder,\n  LiveQueryCollectionConfig,\n  QueryBuilder,\n} from \"@tanstack/db\"\n\n/**\n * Create a live query using a query function\n * @param queryFn - Query function that defines what data to fetch\n * @param deps - Array of dependencies that trigger query re-execution when changed\n * @returns Object with reactive data, state, and status information\n * @example\n * // Basic query with object syntax\n * const { data, isLoading } = useLiveQuery((q) =>\n *   q.from({ todos: todosCollection })\n *    .where(({ todos }) => eq(todos.completed, false))\n *    .select(({ todos }) => ({ id: todos.id, text: todos.text }))\n * )\n *\n * @example\n * // With dependencies that trigger re-execution\n * const { data, state } = useLiveQuery(\n *   (q) => q.from({ todos: todosCollection })\n *          .where(({ todos }) => gt(todos.priority, minPriority)),\n *   [minPriority] // Re-run when minPriority changes\n * )\n *\n * @example\n * // Join pattern\n * const { data } = useLiveQuery((q) =>\n *   q.from({ issues: issueCollection })\n *    .join({ persons: personCollection }, ({ issues, persons }) =>\n *      eq(issues.userId, persons.id)\n *    )\n *    .select(({ issues, persons }) => ({\n *      id: issues.id,\n *      title: issues.title,\n *      userName: persons.name\n *    }))\n * )\n *\n * @example\n * // Handle loading and error states\n * const { data, isLoading, isError, status } = useLiveQuery((q) =>\n *   q.from({ todos: todoCollection })\n * )\n *\n * if (isLoading) return <div>Loading...</div>\n * if (isError) return <div>Error: {status}</div>\n *\n * return (\n *   <ul>\n *     {data.map(todo => <li key={todo.id}>{todo.text}</li>)}\n *   </ul>\n * )\n */\n// Overload 1: Accept just the query function\nexport function useLiveQuery<TContext extends Context>(\n  queryFn: (q: InitialQueryBuilder) => QueryBuilder<TContext>,\n  deps?: Array<unknown>\n): {\n  state: Map<string | number, GetResult<TContext>>\n  data: Array<GetResult<TContext>>\n  collection: Collection<GetResult<TContext>, string | number, {}>\n  status: CollectionStatus\n  isLoading: boolean\n  isReady: boolean\n  isIdle: boolean\n  isError: boolean\n  isCleanedUp: boolean\n}\n\n/**\n * Create a live query using configuration object\n * @param config - Configuration object with query and options\n * @param deps - Array of dependencies that trigger query re-execution when changed\n * @returns Object with reactive data, state, and status information\n * @example\n * // Basic config object usage\n * const { data, status } = useLiveQuery({\n *   query: (q) => q.from({ todos: todosCollection }),\n *   gcTime: 60000\n * })\n *\n * @example\n * // With query builder and options\n * const queryBuilder = new Query()\n *   .from({ persons: collection })\n *   .where(({ persons }) => gt(persons.age, 30))\n *   .select(({ persons }) => ({ id: persons.id, name: persons.name }))\n *\n * const { data, isReady } = useLiveQuery({ query: queryBuilder })\n *\n * @example\n * // Handle all states uniformly\n * const { data, isLoading, isReady, isError } = useLiveQuery({\n *   query: (q) => q.from({ items: itemCollection })\n * })\n *\n * if (isLoading) return <div>Loading...</div>\n * if (isError) return <div>Something went wrong</div>\n * if (!isReady) return <div>Preparing...</div>\n *\n * return <div>{data.length} items loaded</div>\n */\n// Overload 2: Accept config object\nexport function useLiveQuery<TContext extends Context>(\n  config: LiveQueryCollectionConfig<TContext>,\n  deps?: Array<unknown>\n): {\n  state: Map<string | number, GetResult<TContext>>\n  data: Array<GetResult<TContext>>\n  collection: Collection<GetResult<TContext>, string | number, {}>\n  status: CollectionStatus\n  isLoading: boolean\n  isReady: boolean\n  isIdle: boolean\n  isError: boolean\n  isCleanedUp: boolean\n}\n\n/**\n * Subscribe to an existing live query collection\n * @param liveQueryCollection - Pre-created live query collection to subscribe to\n * @returns Object with reactive data, state, and status information\n * @example\n * // Using pre-created live query collection\n * const myLiveQuery = createLiveQueryCollection((q) =>\n *   q.from({ todos: todosCollection }).where(({ todos }) => eq(todos.active, true))\n * )\n * const { data, collection } = useLiveQuery(myLiveQuery)\n *\n * @example\n * // Access collection methods directly\n * const { data, collection, isReady } = useLiveQuery(existingCollection)\n *\n * // Use collection for mutations\n * const handleToggle = (id) => {\n *   collection.update(id, draft => { draft.completed = !draft.completed })\n * }\n *\n * @example\n * // Handle states consistently\n * const { data, isLoading, isError } = useLiveQuery(sharedCollection)\n *\n * if (isLoading) return <div>Loading...</div>\n * if (isError) return <div>Error loading data</div>\n *\n * return <div>{data.map(item => <Item key={item.id} {...item} />)}</div>\n */\n// Overload 3: Accept pre-created live query collection\nexport function useLiveQuery<\n  TResult extends object,\n  TKey extends string | number,\n  TUtils extends Record<string, any>,\n>(\n  liveQueryCollection: Collection<TResult, TKey, TUtils>\n): {\n  state: Map<TKey, TResult>\n  data: Array<TResult>\n  collection: Collection<TResult, TKey, TUtils>\n  status: CollectionStatus\n  isLoading: boolean\n  isReady: boolean\n  isIdle: boolean\n  isError: boolean\n  isCleanedUp: boolean\n}\n\n// Implementation - use function overloads to infer the actual collection type\nexport function useLiveQuery(\n  configOrQueryOrCollection: any,\n  deps: Array<unknown> = []\n) {\n  // Check if it's already a collection by checking for specific collection methods\n  const isCollection =\n    configOrQueryOrCollection &&\n    typeof configOrQueryOrCollection === `object` &&\n    typeof configOrQueryOrCollection.subscribeChanges === `function` &&\n    typeof configOrQueryOrCollection.startSyncImmediate === `function` &&\n    typeof configOrQueryOrCollection.id === `string`\n\n  // Use refs to cache collection and track dependencies\n  const collectionRef = useRef<any>(null)\n  const depsRef = useRef<Array<unknown> | null>(null)\n  const configRef = useRef<any>(null)\n\n  // Check if we need to create/recreate the collection\n  const needsNewCollection =\n    !collectionRef.current ||\n    (isCollection && configRef.current !== configOrQueryOrCollection) ||\n    (!isCollection &&\n      (depsRef.current === null ||\n        depsRef.current.length !== deps.length ||\n        depsRef.current.some((dep, i) => dep !== deps[i])))\n\n  if (needsNewCollection) {\n    if (isCollection) {\n      // It's already a collection, ensure sync is started for React hooks\n      configOrQueryOrCollection.startSyncImmediate()\n      collectionRef.current = configOrQueryOrCollection\n      configRef.current = configOrQueryOrCollection\n    } else {\n      // Original logic for creating collections\n      // Ensure we always start sync for React hooks\n      if (typeof configOrQueryOrCollection === `function`) {\n        collectionRef.current = createLiveQueryCollection({\n          query: configOrQueryOrCollection,\n          startSync: true,\n          gcTime: 0, // Live queries created by useLiveQuery are cleaned up immediately\n        })\n      } else {\n        collectionRef.current = createLiveQueryCollection({\n          startSync: true,\n          gcTime: 0, // Live queries created by useLiveQuery are cleaned up immediately\n          ...configOrQueryOrCollection,\n        })\n      }\n      depsRef.current = [...deps]\n    }\n  }\n\n  // Use refs to track version and memoized snapshot\n  const versionRef = useRef(0)\n  const snapshotRef = useRef<{\n    state: Map<any, any>\n    data: Array<any>\n    collection: Collection<any, any, any>\n    _version: number\n  } | null>(null)\n\n  // Reset refs when collection changes\n  if (needsNewCollection) {\n    versionRef.current = 0\n    snapshotRef.current = null\n  }\n\n  // Create stable subscribe function using ref\n  const subscribeRef = useRef<\n    ((onStoreChange: () => void) => () => void) | null\n  >(null)\n  if (!subscribeRef.current || needsNewCollection) {\n    subscribeRef.current = (onStoreChange: () => void) => {\n      const unsubscribe = collectionRef.current!.subscribeChanges(() => {\n        versionRef.current += 1\n        onStoreChange()\n      })\n      return () => {\n        unsubscribe()\n      }\n    }\n  }\n\n  // Create stable getSnapshot function using ref\n  const getSnapshotRef = useRef<\n    | (() => {\n        state: Map<any, any>\n        data: Array<any>\n        collection: Collection<any, any, any>\n      })\n    | null\n  >(null)\n  if (!getSnapshotRef.current || needsNewCollection) {\n    getSnapshotRef.current = () => {\n      const currentVersion = versionRef.current\n      const currentCollection = collectionRef.current!\n\n      // If we don't have a snapshot or the version changed, create a new one\n      if (\n        !snapshotRef.current ||\n        snapshotRef.current._version !== currentVersion\n      ) {\n        snapshotRef.current = {\n          get state() {\n            return new Map(currentCollection.entries())\n          },\n          get data() {\n            return Array.from(currentCollection.values())\n          },\n          collection: currentCollection,\n          _version: currentVersion,\n        }\n      }\n\n      return snapshotRef.current\n    }\n  }\n\n  // Use useSyncExternalStore to subscribe to collection changes\n  const snapshot = useSyncExternalStore(\n    subscribeRef.current,\n    getSnapshotRef.current\n  )\n\n  return {\n    state: snapshot.state,\n    data: snapshot.data,\n    collection: snapshot.collection,\n    status: snapshot.collection.status,\n    isLoading:\n      snapshot.collection.status === `loading` ||\n      snapshot.collection.status === `initialCommit`,\n    isReady: snapshot.collection.status === `ready`,\n    isIdle: snapshot.collection.status === `idle`,\n    isError: snapshot.collection.status === `error`,\n    isCleanedUp: snapshot.collection.status === `cleaned-up`,\n  }\n}\n"],"names":["useRef","createLiveQueryCollection","useSyncExternalStore"],"mappings":";;;;AAgLO,SAAS,aACd,2BACA,OAAuB,IACvB;AAEA,QAAM,eACJ,6BACA,OAAO,8BAA8B,YACrC,OAAO,0BAA0B,qBAAqB,cACtD,OAAO,0BAA0B,uBAAuB,cACxD,OAAO,0BAA0B,OAAO;AAG1C,QAAM,gBAAgBA,MAAAA,OAAY,IAAI;AACtC,QAAM,UAAUA,MAAAA,OAA8B,IAAI;AAClD,QAAM,YAAYA,MAAAA,OAAY,IAAI;AAGlC,QAAM,qBACJ,CAAC,cAAc,WACd,gBAAgB,UAAU,YAAY,6BACtC,CAAC,iBACC,QAAQ,YAAY,QACnB,QAAQ,QAAQ,WAAW,KAAK,UAChC,QAAQ,QAAQ,KAAK,CAAC,KAAK,MAAM,QAAQ,KAAK,CAAC,CAAC;AAEtD,MAAI,oBAAoB;AACtB,QAAI,cAAc;AAEhB,gCAA0B,mBAAA;AAC1B,oBAAc,UAAU;AACxB,gBAAU,UAAU;AAAA,IACtB,OAAO;AAGL,UAAI,OAAO,8BAA8B,YAAY;AACnD,sBAAc,UAAUC,6BAA0B;AAAA,UAChD,OAAO;AAAA,UACP,WAAW;AAAA,UACX,QAAQ;AAAA;AAAA,QAAA,CACT;AAAA,MACH,OAAO;AACL,sBAAc,UAAUA,6BAA0B;AAAA,UAChD,WAAW;AAAA,UACX,QAAQ;AAAA;AAAA,UACR,GAAG;AAAA,QAAA,CACJ;AAAA,MACH;AACA,cAAQ,UAAU,CAAC,GAAG,IAAI;AAAA,IAC5B;AAAA,EACF;AAGA,QAAM,aAAaD,MAAAA,OAAO,CAAC;AAC3B,QAAM,cAAcA,MAAAA,OAKV,IAAI;AAGd,MAAI,oBAAoB;AACtB,eAAW,UAAU;AACrB,gBAAY,UAAU;AAAA,EACxB;AAGA,QAAM,eAAeA,MAAAA,OAEnB,IAAI;AACN,MAAI,CAAC,aAAa,WAAW,oBAAoB;AAC/C,iBAAa,UAAU,CAAC,kBAA8B;AACpD,YAAM,cAAc,cAAc,QAAS,iBAAiB,MAAM;AAChE,mBAAW,WAAW;AACtB,sBAAA;AAAA,MACF,CAAC;AACD,aAAO,MAAM;AACX,oBAAA;AAAA,MACF;AAAA,IACF;AAAA,EACF;AAGA,QAAM,iBAAiBA,MAAAA,OAOrB,IAAI;AACN,MAAI,CAAC,eAAe,WAAW,oBAAoB;AACjD,mBAAe,UAAU,MAAM;AAC7B,YAAM,iBAAiB,WAAW;AAClC,YAAM,oBAAoB,cAAc;AAGxC,UACE,CAAC,YAAY,WACb,YAAY,QAAQ,aAAa,gBACjC;AACA,oBAAY,UAAU;AAAA,UACpB,IAAI,QAAQ;AACV,mBAAO,IAAI,IAAI,kBAAkB,SAAS;AAAA,UAC5C;AAAA,UACA,IAAI,OAAO;AACT,mBAAO,MAAM,KAAK,kBAAkB,OAAA,CAAQ;AAAA,UAC9C;AAAA,UACA,YAAY;AAAA,UACZ,UAAU;AAAA,QAAA;AAAA,MAEd;AAEA,aAAO,YAAY;AAAA,IACrB;AAAA,EACF;AAGA,QAAM,WAAWE,MAAAA;AAAAA,IACf,aAAa;AAAA,IACb,eAAe;AAAA,EAAA;AAGjB,SAAO;AAAA,IACL,OAAO,SAAS;AAAA,IAChB,MAAM,SAAS;AAAA,IACf,YAAY,SAAS;AAAA,IACrB,QAAQ,SAAS,WAAW;AAAA,IAC5B,WACE,SAAS,WAAW,WAAW,aAC/B,SAAS,WAAW,WAAW;AAAA,IACjC,SAAS,SAAS,WAAW,WAAW;AAAA,IACxC,QAAQ,SAAS,WAAW,WAAW;AAAA,IACvC,SAAS,SAAS,WAAW,WAAW;AAAA,IACxC,aAAa,SAAS,WAAW,WAAW;AAAA,EAAA;AAEhD;;"}
+{"version":3,"file":"useLiveQuery.cjs","sources":["../../src/useLiveQuery.ts"],"sourcesContent":["import { useRef, useSyncExternalStore } from \"react\"\nimport { createLiveQueryCollection } from \"@tanstack/db\"\nimport type {\n  Collection,\n  CollectionStatus,\n  Context,\n  GetResult,\n  InitialQueryBuilder,\n  LiveQueryCollectionConfig,\n  QueryBuilder,\n} from \"@tanstack/db\"\n\n/**\n * Create a live query using a query function\n * @param queryFn - Query function that defines what data to fetch\n * @param deps - Array of dependencies that trigger query re-execution when changed\n * @returns Object with reactive data, state, and status information\n * @example\n * // Basic query with object syntax\n * const { data, isLoading } = useLiveQuery((q) =>\n *   q.from({ todos: todosCollection })\n *    .where(({ todos }) => eq(todos.completed, false))\n *    .select(({ todos }) => ({ id: todos.id, text: todos.text }))\n * )\n *\n * @example\n * // With dependencies that trigger re-execution\n * const { data, state } = useLiveQuery(\n *   (q) => q.from({ todos: todosCollection })\n *          .where(({ todos }) => gt(todos.priority, minPriority)),\n *   [minPriority] // Re-run when minPriority changes\n * )\n *\n * @example\n * // Join pattern\n * const { data } = useLiveQuery((q) =>\n *   q.from({ issues: issueCollection })\n *    .join({ persons: personCollection }, ({ issues, persons }) =>\n *      eq(issues.userId, persons.id)\n *    )\n *    .select(({ issues, persons }) => ({\n *      id: issues.id,\n *      title: issues.title,\n *      userName: persons.name\n *    }))\n * )\n *\n * @example\n * // Handle loading and error states\n * const { data, isLoading, isError, status } = useLiveQuery((q) =>\n *   q.from({ todos: todoCollection })\n * )\n *\n * if (isLoading) return <div>Loading...</div>\n * if (isError) return <div>Error: {status}</div>\n *\n * return (\n *   <ul>\n *     {data.map(todo => <li key={todo.id}>{todo.text}</li>)}\n *   </ul>\n * )\n */\n// Overload 1: Accept just the query function\nexport function useLiveQuery<TContext extends Context>(\n  queryFn: (q: InitialQueryBuilder) => QueryBuilder<TContext>,\n  deps?: Array<unknown>\n): {\n  state: Map<string | number, GetResult<TContext>>\n  data: Array<GetResult<TContext>>\n  collection: Collection<GetResult<TContext>, string | number, {}>\n  status: CollectionStatus\n  isLoading: boolean\n  isReady: boolean\n  isIdle: boolean\n  isError: boolean\n  isCleanedUp: boolean\n}\n\n/**\n * Create a live query using configuration object\n * @param config - Configuration object with query and options\n * @param deps - Array of dependencies that trigger query re-execution when changed\n * @returns Object with reactive data, state, and status information\n * @example\n * // Basic config object usage\n * const { data, status } = useLiveQuery({\n *   query: (q) => q.from({ todos: todosCollection }),\n *   gcTime: 60000\n * })\n *\n * @example\n * // With query builder and options\n * const queryBuilder = new Query()\n *   .from({ persons: collection })\n *   .where(({ persons }) => gt(persons.age, 30))\n *   .select(({ persons }) => ({ id: persons.id, name: persons.name }))\n *\n * const { data, isReady } = useLiveQuery({ query: queryBuilder })\n *\n * @example\n * // Handle all states uniformly\n * const { data, isLoading, isReady, isError } = useLiveQuery({\n *   query: (q) => q.from({ items: itemCollection })\n * })\n *\n * if (isLoading) return <div>Loading...</div>\n * if (isError) return <div>Something went wrong</div>\n * if (!isReady) return <div>Preparing...</div>\n *\n * return <div>{data.length} items loaded</div>\n */\n// Overload 2: Accept config object\nexport function useLiveQuery<TContext extends Context>(\n  config: LiveQueryCollectionConfig<TContext>,\n  deps?: Array<unknown>\n): {\n  state: Map<string | number, GetResult<TContext>>\n  data: Array<GetResult<TContext>>\n  collection: Collection<GetResult<TContext>, string | number, {}>\n  status: CollectionStatus\n  isLoading: boolean\n  isReady: boolean\n  isIdle: boolean\n  isError: boolean\n  isCleanedUp: boolean\n}\n\n/**\n * Subscribe to an existing live query collection\n * @param liveQueryCollection - Pre-created live query collection to subscribe to\n * @returns Object with reactive data, state, and status information\n * @example\n * // Using pre-created live query collection\n * const myLiveQuery = createLiveQueryCollection((q) =>\n *   q.from({ todos: todosCollection }).where(({ todos }) => eq(todos.active, true))\n * )\n * const { data, collection } = useLiveQuery(myLiveQuery)\n *\n * @example\n * // Access collection methods directly\n * const { data, collection, isReady } = useLiveQuery(existingCollection)\n *\n * // Use collection for mutations\n * const handleToggle = (id) => {\n *   collection.update(id, draft => { draft.completed = !draft.completed })\n * }\n *\n * @example\n * // Handle states consistently\n * const { data, isLoading, isError } = useLiveQuery(sharedCollection)\n *\n * if (isLoading) return <div>Loading...</div>\n * if (isError) return <div>Error loading data</div>\n *\n * return <div>{data.map(item => <Item key={item.id} {...item} />)}</div>\n */\n// Overload 3: Accept pre-created live query collection\nexport function useLiveQuery<\n  TResult extends object,\n  TKey extends string | number,\n  TUtils extends Record<string, any>,\n>(\n  liveQueryCollection: Collection<TResult, TKey, TUtils>\n): {\n  state: Map<TKey, TResult>\n  data: Array<TResult>\n  collection: Collection<TResult, TKey, TUtils>\n  status: CollectionStatus\n  isLoading: boolean\n  isReady: boolean\n  isIdle: boolean\n  isError: boolean\n  isCleanedUp: boolean\n}\n\n// Implementation - use function overloads to infer the actual collection type\nexport function useLiveQuery(\n  configOrQueryOrCollection: any,\n  deps: Array<unknown> = []\n) {\n  // Check if it's already a collection by checking for specific collection methods\n  const isCollection =\n    configOrQueryOrCollection &&\n    typeof configOrQueryOrCollection === `object` &&\n    typeof configOrQueryOrCollection.subscribeChanges === `function` &&\n    typeof configOrQueryOrCollection.startSyncImmediate === `function` &&\n    typeof configOrQueryOrCollection.id === `string`\n\n  // Use refs to cache collection and track dependencies\n  const collectionRef = useRef<Collection<object, string | number, {}> | null>(\n    null\n  )\n  const depsRef = useRef<Array<unknown> | null>(null)\n  const configRef = useRef<unknown>(null)\n\n  // Check if we need to create/recreate the collection\n  const needsNewCollection =\n    !collectionRef.current ||\n    (isCollection && configRef.current !== configOrQueryOrCollection) ||\n    (!isCollection &&\n      (depsRef.current === null ||\n        depsRef.current.length !== deps.length ||\n        depsRef.current.some((dep, i) => dep !== deps[i])))\n\n  if (needsNewCollection) {\n    if (isCollection) {\n      // It's already a collection, ensure sync is started for React hooks\n      configOrQueryOrCollection.startSyncImmediate()\n      collectionRef.current = configOrQueryOrCollection\n      configRef.current = configOrQueryOrCollection\n    } else {\n      // Original logic for creating collections\n      // Ensure we always start sync for React hooks\n      if (typeof configOrQueryOrCollection === `function`) {\n        collectionRef.current = createLiveQueryCollection({\n          query: configOrQueryOrCollection,\n          startSync: true,\n          gcTime: 0, // Live queries created by useLiveQuery are cleaned up immediately\n        }) as unknown as Collection<object, string | number, {}>\n      } else {\n        collectionRef.current = createLiveQueryCollection({\n          startSync: true,\n          gcTime: 0, // Live queries created by useLiveQuery are cleaned up immediately\n          ...configOrQueryOrCollection,\n        }) as unknown as Collection<object, string | number, {}>\n      }\n      depsRef.current = [...deps]\n    }\n  }\n\n  // Use refs to track version and memoized snapshot\n  const versionRef = useRef(0)\n  const snapshotRef = useRef<{\n    collection: Collection<object, string | number, {}>\n    version: number\n  } | null>(null)\n\n  // Reset refs when collection changes\n  if (needsNewCollection) {\n    versionRef.current = 0\n    snapshotRef.current = null\n  }\n\n  // Create stable subscribe function using ref\n  const subscribeRef = useRef<\n    ((onStoreChange: () => void) => () => void) | null\n  >(null)\n  if (!subscribeRef.current || needsNewCollection) {\n    subscribeRef.current = (onStoreChange: () => void) => {\n      const unsubscribe = collectionRef.current!.subscribeChanges(() => {\n        // Bump version on any change; getSnapshot will rebuild next time\n        versionRef.current += 1\n        onStoreChange()\n      })\n      return () => {\n        unsubscribe()\n      }\n    }\n  }\n\n  // Create stable getSnapshot function using ref\n  const getSnapshotRef = useRef<\n    | (() => {\n        collection: Collection<object, string | number, {}>\n        version: number\n      })\n    | null\n  >(null)\n  if (!getSnapshotRef.current || needsNewCollection) {\n    getSnapshotRef.current = () => {\n      const currentVersion = versionRef.current\n      const currentCollection = collectionRef.current!\n\n      // Recreate snapshot object only if version/collection changed\n      if (\n        !snapshotRef.current ||\n        snapshotRef.current.version !== currentVersion ||\n        snapshotRef.current.collection !== currentCollection\n      ) {\n        snapshotRef.current = {\n          collection: currentCollection,\n          version: currentVersion,\n        }\n      }\n\n      return snapshotRef.current\n    }\n  }\n\n  // Use useSyncExternalStore to subscribe to collection changes\n  const snapshot = useSyncExternalStore(\n    subscribeRef.current,\n    getSnapshotRef.current\n  )\n\n  // Track last snapshot (from useSyncExternalStore) and the returned value separately\n  const returnedSnapshotRef = useRef<{\n    collection: Collection<object, string | number, {}>\n    version: number\n  } | null>(null)\n  // Keep implementation return loose to satisfy overload signatures\n  const returnedRef = useRef<any>(null)\n\n  // Rebuild returned object only when the snapshot changes (version or collection identity)\n  if (\n    !returnedSnapshotRef.current ||\n    returnedSnapshotRef.current.version !== snapshot.version ||\n    returnedSnapshotRef.current.collection !== snapshot.collection\n  ) {\n    // Capture a stable view of entries for this snapshot to avoid tearing\n    const entries = Array.from(snapshot.collection.entries())\n    let stateCache: Map<string | number, unknown> | null = null\n    let dataCache: Array<unknown> | null = null\n\n    returnedRef.current = {\n      get state() {\n        if (!stateCache) {\n          stateCache = new Map(entries)\n        }\n        return stateCache\n      },\n      get data() {\n        if (!dataCache) {\n          dataCache = entries.map(([, value]) => value)\n        }\n        return dataCache\n      },\n      collection: snapshot.collection,\n      status: snapshot.collection.status,\n      isLoading:\n        snapshot.collection.status === `loading` ||\n        snapshot.collection.status === `initialCommit`,\n      isReady: snapshot.collection.status === `ready`,\n      isIdle: snapshot.collection.status === `idle`,\n      isError: snapshot.collection.status === `error`,\n      isCleanedUp: snapshot.collection.status === `cleaned-up`,\n    }\n\n    // Remember the snapshot that produced this returned value\n    returnedSnapshotRef.current = snapshot\n  }\n\n  return returnedRef.current!\n}\n"],"names":["useRef","createLiveQueryCollection","useSyncExternalStore"],"mappings":"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"}

package/dist/esm/useLiveQuery.js

@@ -2,7 +2,9 @@ import { useRef, useSyncExternalStore } from "react";
 import { createLiveQueryCollection } from "@tanstack/db";
 function useLiveQuery(configOrQueryOrCollection, deps = []) {
   const isCollection = configOrQueryOrCollection && typeof configOrQueryOrCollection === `object` && typeof configOrQueryOrCollection.subscribeChanges === `function` && typeof configOrQueryOrCollection.startSyncImmediate === `function` && typeof configOrQueryOrCollection.id === `string`;
-  const collectionRef = useRef(null);
+  const collectionRef = useRef(
+    null
+  );
   const depsRef = useRef(null);
   const configRef = useRef(null);
   const needsNewCollection = !collectionRef.current || isCollection && configRef.current !== configOrQueryOrCollection || !isCollection && (depsRef.current === null || depsRef.current.length !== deps.length || depsRef.current.some((dep, i) => dep !== deps[i]));
@@ -53,16 +55,10 @@ function useLiveQuery(configOrQueryOrCollection, deps = []) {
     getSnapshotRef.current = () => {
       const currentVersion = versionRef.current;
       const currentCollection = collectionRef.current;
-      if (!snapshotRef.current || snapshotRef.current._version !== currentVersion) {
+      if (!snapshotRef.current || snapshotRef.current.version !== currentVersion || snapshotRef.current.collection !== currentCollection) {
         snapshotRef.current = {
-          get state() {
-            return new Map(currentCollection.entries());
-          },
-          get data() {
-            return Array.from(currentCollection.values());
-          },
           collection: currentCollection,
-          _version: currentVersion
+          version: currentVersion
         };
       }
       return snapshotRef.current;
@@ -72,17 +68,36 @@ function useLiveQuery(configOrQueryOrCollection, deps = []) {
     subscribeRef.current,
     getSnapshotRef.current
   );
-  return {
-    state: snapshot.state,
-    data: snapshot.data,
-    collection: snapshot.collection,
-    status: snapshot.collection.status,
-    isLoading: snapshot.collection.status === `loading` || snapshot.collection.status === `initialCommit`,
-    isReady: snapshot.collection.status === `ready`,
-    isIdle: snapshot.collection.status === `idle`,
-    isError: snapshot.collection.status === `error`,
-    isCleanedUp: snapshot.collection.status === `cleaned-up`
-  };
+  const returnedSnapshotRef = useRef(null);
+  const returnedRef = useRef(null);
+  if (!returnedSnapshotRef.current || returnedSnapshotRef.current.version !== snapshot.version || returnedSnapshotRef.current.collection !== snapshot.collection) {
+    const entries = Array.from(snapshot.collection.entries());
+    let stateCache = null;
+    let dataCache = null;
+    returnedRef.current = {
+      get state() {
+        if (!stateCache) {
+          stateCache = new Map(entries);
+        }
+        return stateCache;
+      },
+      get data() {
+        if (!dataCache) {
+          dataCache = entries.map(([, value]) => value);
+        }
+        return dataCache;
+      },
+      collection: snapshot.collection,
+      status: snapshot.collection.status,
+      isLoading: snapshot.collection.status === `loading` || snapshot.collection.status === `initialCommit`,
+      isReady: snapshot.collection.status === `ready`,
+      isIdle: snapshot.collection.status === `idle`,
+      isError: snapshot.collection.status === `error`,
+      isCleanedUp: snapshot.collection.status === `cleaned-up`
+    };
+    returnedSnapshotRef.current = snapshot;
+  }
+  return returnedRef.current;
 }
 export {
   useLiveQuery

package/dist/esm/useLiveQuery.js.map

@@ -1 +1 @@
-{"version":3,"file":"useLiveQuery.js","sources":["../../src/useLiveQuery.ts"],"sourcesContent":["import { useRef, useSyncExternalStore } from \"react\"\nimport { createLiveQueryCollection } from \"@tanstack/db\"\nimport type {\n  Collection,\n  CollectionStatus,\n  Context,\n  GetResult,\n  InitialQueryBuilder,\n  LiveQueryCollectionConfig,\n  QueryBuilder,\n} from \"@tanstack/db\"\n\n/**\n * Create a live query using a query function\n * @param queryFn - Query function that defines what data to fetch\n * @param deps - Array of dependencies that trigger query re-execution when changed\n * @returns Object with reactive data, state, and status information\n * @example\n * // Basic query with object syntax\n * const { data, isLoading } = useLiveQuery((q) =>\n *   q.from({ todos: todosCollection })\n *    .where(({ todos }) => eq(todos.completed, false))\n *    .select(({ todos }) => ({ id: todos.id, text: todos.text }))\n * )\n *\n * @example\n * // With dependencies that trigger re-execution\n * const { data, state } = useLiveQuery(\n *   (q) => q.from({ todos: todosCollection })\n *          .where(({ todos }) => gt(todos.priority, minPriority)),\n *   [minPriority] // Re-run when minPriority changes\n * )\n *\n * @example\n * // Join pattern\n * const { data } = useLiveQuery((q) =>\n *   q.from({ issues: issueCollection })\n *    .join({ persons: personCollection }, ({ issues, persons }) =>\n *      eq(issues.userId, persons.id)\n *    )\n *    .select(({ issues, persons }) => ({\n *      id: issues.id,\n *      title: issues.title,\n *      userName: persons.name\n *    }))\n * )\n *\n * @example\n * // Handle loading and error states\n * const { data, isLoading, isError, status } = useLiveQuery((q) =>\n *   q.from({ todos: todoCollection })\n * )\n *\n * if (isLoading) return <div>Loading...</div>\n * if (isError) return <div>Error: {status}</div>\n *\n * return (\n *   <ul>\n *     {data.map(todo => <li key={todo.id}>{todo.text}</li>)}\n *   </ul>\n * )\n */\n// Overload 1: Accept just the query function\nexport function useLiveQuery<TContext extends Context>(\n  queryFn: (q: InitialQueryBuilder) => QueryBuilder<TContext>,\n  deps?: Array<unknown>\n): {\n  state: Map<string | number, GetResult<TContext>>\n  data: Array<GetResult<TContext>>\n  collection: Collection<GetResult<TContext>, string | number, {}>\n  status: CollectionStatus\n  isLoading: boolean\n  isReady: boolean\n  isIdle: boolean\n  isError: boolean\n  isCleanedUp: boolean\n}\n\n/**\n * Create a live query using configuration object\n * @param config - Configuration object with query and options\n * @param deps - Array of dependencies that trigger query re-execution when changed\n * @returns Object with reactive data, state, and status information\n * @example\n * // Basic config object usage\n * const { data, status } = useLiveQuery({\n *   query: (q) => q.from({ todos: todosCollection }),\n *   gcTime: 60000\n * })\n *\n * @example\n * // With query builder and options\n * const queryBuilder = new Query()\n *   .from({ persons: collection })\n *   .where(({ persons }) => gt(persons.age, 30))\n *   .select(({ persons }) => ({ id: persons.id, name: persons.name }))\n *\n * const { data, isReady } = useLiveQuery({ query: queryBuilder })\n *\n * @example\n * // Handle all states uniformly\n * const { data, isLoading, isReady, isError } = useLiveQuery({\n *   query: (q) => q.from({ items: itemCollection })\n * })\n *\n * if (isLoading) return <div>Loading...</div>\n * if (isError) return <div>Something went wrong</div>\n * if (!isReady) return <div>Preparing...</div>\n *\n * return <div>{data.length} items loaded</div>\n */\n// Overload 2: Accept config object\nexport function useLiveQuery<TContext extends Context>(\n  config: LiveQueryCollectionConfig<TContext>,\n  deps?: Array<unknown>\n): {\n  state: Map<string | number, GetResult<TContext>>\n  data: Array<GetResult<TContext>>\n  collection: Collection<GetResult<TContext>, string | number, {}>\n  status: CollectionStatus\n  isLoading: boolean\n  isReady: boolean\n  isIdle: boolean\n  isError: boolean\n  isCleanedUp: boolean\n}\n\n/**\n * Subscribe to an existing live query collection\n * @param liveQueryCollection - Pre-created live query collection to subscribe to\n * @returns Object with reactive data, state, and status information\n * @example\n * // Using pre-created live query collection\n * const myLiveQuery = createLiveQueryCollection((q) =>\n *   q.from({ todos: todosCollection }).where(({ todos }) => eq(todos.active, true))\n * )\n * const { data, collection } = useLiveQuery(myLiveQuery)\n *\n * @example\n * // Access collection methods directly\n * const { data, collection, isReady } = useLiveQuery(existingCollection)\n *\n * // Use collection for mutations\n * const handleToggle = (id) => {\n *   collection.update(id, draft => { draft.completed = !draft.completed })\n * }\n *\n * @example\n * // Handle states consistently\n * const { data, isLoading, isError } = useLiveQuery(sharedCollection)\n *\n * if (isLoading) return <div>Loading...</div>\n * if (isError) return <div>Error loading data</div>\n *\n * return <div>{data.map(item => <Item key={item.id} {...item} />)}</div>\n */\n// Overload 3: Accept pre-created live query collection\nexport function useLiveQuery<\n  TResult extends object,\n  TKey extends string | number,\n  TUtils extends Record<string, any>,\n>(\n  liveQueryCollection: Collection<TResult, TKey, TUtils>\n): {\n  state: Map<TKey, TResult>\n  data: Array<TResult>\n  collection: Collection<TResult, TKey, TUtils>\n  status: CollectionStatus\n  isLoading: boolean\n  isReady: boolean\n  isIdle: boolean\n  isError: boolean\n  isCleanedUp: boolean\n}\n\n// Implementation - use function overloads to infer the actual collection type\nexport function useLiveQuery(\n  configOrQueryOrCollection: any,\n  deps: Array<unknown> = []\n) {\n  // Check if it's already a collection by checking for specific collection methods\n  const isCollection =\n    configOrQueryOrCollection &&\n    typeof configOrQueryOrCollection === `object` &&\n    typeof configOrQueryOrCollection.subscribeChanges === `function` &&\n    typeof configOrQueryOrCollection.startSyncImmediate === `function` &&\n    typeof configOrQueryOrCollection.id === `string`\n\n  // Use refs to cache collection and track dependencies\n  const collectionRef = useRef<any>(null)\n  const depsRef = useRef<Array<unknown> | null>(null)\n  const configRef = useRef<any>(null)\n\n  // Check if we need to create/recreate the collection\n  const needsNewCollection =\n    !collectionRef.current ||\n    (isCollection && configRef.current !== configOrQueryOrCollection) ||\n    (!isCollection &&\n      (depsRef.current === null ||\n        depsRef.current.length !== deps.length ||\n        depsRef.current.some((dep, i) => dep !== deps[i])))\n\n  if (needsNewCollection) {\n    if (isCollection) {\n      // It's already a collection, ensure sync is started for React hooks\n      configOrQueryOrCollection.startSyncImmediate()\n      collectionRef.current = configOrQueryOrCollection\n      configRef.current = configOrQueryOrCollection\n    } else {\n      // Original logic for creating collections\n      // Ensure we always start sync for React hooks\n      if (typeof configOrQueryOrCollection === `function`) {\n        collectionRef.current = createLiveQueryCollection({\n          query: configOrQueryOrCollection,\n          startSync: true,\n          gcTime: 0, // Live queries created by useLiveQuery are cleaned up immediately\n        })\n      } else {\n        collectionRef.current = createLiveQueryCollection({\n          startSync: true,\n          gcTime: 0, // Live queries created by useLiveQuery are cleaned up immediately\n          ...configOrQueryOrCollection,\n        })\n      }\n      depsRef.current = [...deps]\n    }\n  }\n\n  // Use refs to track version and memoized snapshot\n  const versionRef = useRef(0)\n  const snapshotRef = useRef<{\n    state: Map<any, any>\n    data: Array<any>\n    collection: Collection<any, any, any>\n    _version: number\n  } | null>(null)\n\n  // Reset refs when collection changes\n  if (needsNewCollection) {\n    versionRef.current = 0\n    snapshotRef.current = null\n  }\n\n  // Create stable subscribe function using ref\n  const subscribeRef = useRef<\n    ((onStoreChange: () => void) => () => void) | null\n  >(null)\n  if (!subscribeRef.current || needsNewCollection) {\n    subscribeRef.current = (onStoreChange: () => void) => {\n      const unsubscribe = collectionRef.current!.subscribeChanges(() => {\n        versionRef.current += 1\n        onStoreChange()\n      })\n      return () => {\n        unsubscribe()\n      }\n    }\n  }\n\n  // Create stable getSnapshot function using ref\n  const getSnapshotRef = useRef<\n    | (() => {\n        state: Map<any, any>\n        data: Array<any>\n        collection: Collection<any, any, any>\n      })\n    | null\n  >(null)\n  if (!getSnapshotRef.current || needsNewCollection) {\n    getSnapshotRef.current = () => {\n      const currentVersion = versionRef.current\n      const currentCollection = collectionRef.current!\n\n      // If we don't have a snapshot or the version changed, create a new one\n      if (\n        !snapshotRef.current ||\n        snapshotRef.current._version !== currentVersion\n      ) {\n        snapshotRef.current = {\n          get state() {\n            return new Map(currentCollection.entries())\n          },\n          get data() {\n            return Array.from(currentCollection.values())\n          },\n          collection: currentCollection,\n          _version: currentVersion,\n        }\n      }\n\n      return snapshotRef.current\n    }\n  }\n\n  // Use useSyncExternalStore to subscribe to collection changes\n  const snapshot = useSyncExternalStore(\n    subscribeRef.current,\n    getSnapshotRef.current\n  )\n\n  return {\n    state: snapshot.state,\n    data: snapshot.data,\n    collection: snapshot.collection,\n    status: snapshot.collection.status,\n    isLoading:\n      snapshot.collection.status === `loading` ||\n      snapshot.collection.status === `initialCommit`,\n    isReady: snapshot.collection.status === `ready`,\n    isIdle: snapshot.collection.status === `idle`,\n    isError: snapshot.collection.status === `error`,\n    isCleanedUp: snapshot.collection.status === `cleaned-up`,\n  }\n}\n"],"names":[],"mappings":";;AAgLO,SAAS,aACd,2BACA,OAAuB,IACvB;AAEA,QAAM,eACJ,6BACA,OAAO,8BAA8B,YACrC,OAAO,0BAA0B,qBAAqB,cACtD,OAAO,0BAA0B,uBAAuB,cACxD,OAAO,0BAA0B,OAAO;AAG1C,QAAM,gBAAgB,OAAY,IAAI;AACtC,QAAM,UAAU,OAA8B,IAAI;AAClD,QAAM,YAAY,OAAY,IAAI;AAGlC,QAAM,qBACJ,CAAC,cAAc,WACd,gBAAgB,UAAU,YAAY,6BACtC,CAAC,iBACC,QAAQ,YAAY,QACnB,QAAQ,QAAQ,WAAW,KAAK,UAChC,QAAQ,QAAQ,KAAK,CAAC,KAAK,MAAM,QAAQ,KAAK,CAAC,CAAC;AAEtD,MAAI,oBAAoB;AACtB,QAAI,cAAc;AAEhB,gCAA0B,mBAAA;AAC1B,oBAAc,UAAU;AACxB,gBAAU,UAAU;AAAA,IACtB,OAAO;AAGL,UAAI,OAAO,8BAA8B,YAAY;AACnD,sBAAc,UAAU,0BAA0B;AAAA,UAChD,OAAO;AAAA,UACP,WAAW;AAAA,UACX,QAAQ;AAAA;AAAA,QAAA,CACT;AAAA,MACH,OAAO;AACL,sBAAc,UAAU,0BAA0B;AAAA,UAChD,WAAW;AAAA,UACX,QAAQ;AAAA;AAAA,UACR,GAAG;AAAA,QAAA,CACJ;AAAA,MACH;AACA,cAAQ,UAAU,CAAC,GAAG,IAAI;AAAA,IAC5B;AAAA,EACF;AAGA,QAAM,aAAa,OAAO,CAAC;AAC3B,QAAM,cAAc,OAKV,IAAI;AAGd,MAAI,oBAAoB;AACtB,eAAW,UAAU;AACrB,gBAAY,UAAU;AAAA,EACxB;AAGA,QAAM,eAAe,OAEnB,IAAI;AACN,MAAI,CAAC,aAAa,WAAW,oBAAoB;AAC/C,iBAAa,UAAU,CAAC,kBAA8B;AACpD,YAAM,cAAc,cAAc,QAAS,iBAAiB,MAAM;AAChE,mBAAW,WAAW;AACtB,sBAAA;AAAA,MACF,CAAC;AACD,aAAO,MAAM;AACX,oBAAA;AAAA,MACF;AAAA,IACF;AAAA,EACF;AAGA,QAAM,iBAAiB,OAOrB,IAAI;AACN,MAAI,CAAC,eAAe,WAAW,oBAAoB;AACjD,mBAAe,UAAU,MAAM;AAC7B,YAAM,iBAAiB,WAAW;AAClC,YAAM,oBAAoB,cAAc;AAGxC,UACE,CAAC,YAAY,WACb,YAAY,QAAQ,aAAa,gBACjC;AACA,oBAAY,UAAU;AAAA,UACpB,IAAI,QAAQ;AACV,mBAAO,IAAI,IAAI,kBAAkB,SAAS;AAAA,UAC5C;AAAA,UACA,IAAI,OAAO;AACT,mBAAO,MAAM,KAAK,kBAAkB,OAAA,CAAQ;AAAA,UAC9C;AAAA,UACA,YAAY;AAAA,UACZ,UAAU;AAAA,QAAA;AAAA,MAEd;AAEA,aAAO,YAAY;AAAA,IACrB;AAAA,EACF;AAGA,QAAM,WAAW;AAAA,IACf,aAAa;AAAA,IACb,eAAe;AAAA,EAAA;AAGjB,SAAO;AAAA,IACL,OAAO,SAAS;AAAA,IAChB,MAAM,SAAS;AAAA,IACf,YAAY,SAAS;AAAA,IACrB,QAAQ,SAAS,WAAW;AAAA,IAC5B,WACE,SAAS,WAAW,WAAW,aAC/B,SAAS,WAAW,WAAW;AAAA,IACjC,SAAS,SAAS,WAAW,WAAW;AAAA,IACxC,QAAQ,SAAS,WAAW,WAAW;AAAA,IACvC,SAAS,SAAS,WAAW,WAAW;AAAA,IACxC,aAAa,SAAS,WAAW,WAAW;AAAA,EAAA;AAEhD;"}
+{"version":3,"file":"useLiveQuery.js","sources":["../../src/useLiveQuery.ts"],"sourcesContent":["import { useRef, useSyncExternalStore } from \"react\"\nimport { createLiveQueryCollection } from \"@tanstack/db\"\nimport type {\n  Collection,\n  CollectionStatus,\n  Context,\n  GetResult,\n  InitialQueryBuilder,\n  LiveQueryCollectionConfig,\n  QueryBuilder,\n} from \"@tanstack/db\"\n\n/**\n * Create a live query using a query function\n * @param queryFn - Query function that defines what data to fetch\n * @param deps - Array of dependencies that trigger query re-execution when changed\n * @returns Object with reactive data, state, and status information\n * @example\n * // Basic query with object syntax\n * const { data, isLoading } = useLiveQuery((q) =>\n *   q.from({ todos: todosCollection })\n *    .where(({ todos }) => eq(todos.completed, false))\n *    .select(({ todos }) => ({ id: todos.id, text: todos.text }))\n * )\n *\n * @example\n * // With dependencies that trigger re-execution\n * const { data, state } = useLiveQuery(\n *   (q) => q.from({ todos: todosCollection })\n *          .where(({ todos }) => gt(todos.priority, minPriority)),\n *   [minPriority] // Re-run when minPriority changes\n * )\n *\n * @example\n * // Join pattern\n * const { data } = useLiveQuery((q) =>\n *   q.from({ issues: issueCollection })\n *    .join({ persons: personCollection }, ({ issues, persons }) =>\n *      eq(issues.userId, persons.id)\n *    )\n *    .select(({ issues, persons }) => ({\n *      id: issues.id,\n *      title: issues.title,\n *      userName: persons.name\n *    }))\n * )\n *\n * @example\n * // Handle loading and error states\n * const { data, isLoading, isError, status } = useLiveQuery((q) =>\n *   q.from({ todos: todoCollection })\n * )\n *\n * if (isLoading) return <div>Loading...</div>\n * if (isError) return <div>Error: {status}</div>\n *\n * return (\n *   <ul>\n *     {data.map(todo => <li key={todo.id}>{todo.text}</li>)}\n *   </ul>\n * )\n */\n// Overload 1: Accept just the query function\nexport function useLiveQuery<TContext extends Context>(\n  queryFn: (q: InitialQueryBuilder) => QueryBuilder<TContext>,\n  deps?: Array<unknown>\n): {\n  state: Map<string | number, GetResult<TContext>>\n  data: Array<GetResult<TContext>>\n  collection: Collection<GetResult<TContext>, string | number, {}>\n  status: CollectionStatus\n  isLoading: boolean\n  isReady: boolean\n  isIdle: boolean\n  isError: boolean\n  isCleanedUp: boolean\n}\n\n/**\n * Create a live query using configuration object\n * @param config - Configuration object with query and options\n * @param deps - Array of dependencies that trigger query re-execution when changed\n * @returns Object with reactive data, state, and status information\n * @example\n * // Basic config object usage\n * const { data, status } = useLiveQuery({\n *   query: (q) => q.from({ todos: todosCollection }),\n *   gcTime: 60000\n * })\n *\n * @example\n * // With query builder and options\n * const queryBuilder = new Query()\n *   .from({ persons: collection })\n *   .where(({ persons }) => gt(persons.age, 30))\n *   .select(({ persons }) => ({ id: persons.id, name: persons.name }))\n *\n * const { data, isReady } = useLiveQuery({ query: queryBuilder })\n *\n * @example\n * // Handle all states uniformly\n * const { data, isLoading, isReady, isError } = useLiveQuery({\n *   query: (q) => q.from({ items: itemCollection })\n * })\n *\n * if (isLoading) return <div>Loading...</div>\n * if (isError) return <div>Something went wrong</div>\n * if (!isReady) return <div>Preparing...</div>\n *\n * return <div>{data.length} items loaded</div>\n */\n// Overload 2: Accept config object\nexport function useLiveQuery<TContext extends Context>(\n  config: LiveQueryCollectionConfig<TContext>,\n  deps?: Array<unknown>\n): {\n  state: Map<string | number, GetResult<TContext>>\n  data: Array<GetResult<TContext>>\n  collection: Collection<GetResult<TContext>, string | number, {}>\n  status: CollectionStatus\n  isLoading: boolean\n  isReady: boolean\n  isIdle: boolean\n  isError: boolean\n  isCleanedUp: boolean\n}\n\n/**\n * Subscribe to an existing live query collection\n * @param liveQueryCollection - Pre-created live query collection to subscribe to\n * @returns Object with reactive data, state, and status information\n * @example\n * // Using pre-created live query collection\n * const myLiveQuery = createLiveQueryCollection((q) =>\n *   q.from({ todos: todosCollection }).where(({ todos }) => eq(todos.active, true))\n * )\n * const { data, collection } = useLiveQuery(myLiveQuery)\n *\n * @example\n * // Access collection methods directly\n * const { data, collection, isReady } = useLiveQuery(existingCollection)\n *\n * // Use collection for mutations\n * const handleToggle = (id) => {\n *   collection.update(id, draft => { draft.completed = !draft.completed })\n * }\n *\n * @example\n * // Handle states consistently\n * const { data, isLoading, isError } = useLiveQuery(sharedCollection)\n *\n * if (isLoading) return <div>Loading...</div>\n * if (isError) return <div>Error loading data</div>\n *\n * return <div>{data.map(item => <Item key={item.id} {...item} />)}</div>\n */\n// Overload 3: Accept pre-created live query collection\nexport function useLiveQuery<\n  TResult extends object,\n  TKey extends string | number,\n  TUtils extends Record<string, any>,\n>(\n  liveQueryCollection: Collection<TResult, TKey, TUtils>\n): {\n  state: Map<TKey, TResult>\n  data: Array<TResult>\n  collection: Collection<TResult, TKey, TUtils>\n  status: CollectionStatus\n  isLoading: boolean\n  isReady: boolean\n  isIdle: boolean\n  isError: boolean\n  isCleanedUp: boolean\n}\n\n// Implementation - use function overloads to infer the actual collection type\nexport function useLiveQuery(\n  configOrQueryOrCollection: any,\n  deps: Array<unknown> = []\n) {\n  // Check if it's already a collection by checking for specific collection methods\n  const isCollection =\n    configOrQueryOrCollection &&\n    typeof configOrQueryOrCollection === `object` &&\n    typeof configOrQueryOrCollection.subscribeChanges === `function` &&\n    typeof configOrQueryOrCollection.startSyncImmediate === `function` &&\n    typeof configOrQueryOrCollection.id === `string`\n\n  // Use refs to cache collection and track dependencies\n  const collectionRef = useRef<Collection<object, string | number, {}> | null>(\n    null\n  )\n  const depsRef = useRef<Array<unknown> | null>(null)\n  const configRef = useRef<unknown>(null)\n\n  // Check if we need to create/recreate the collection\n  const needsNewCollection =\n    !collectionRef.current ||\n    (isCollection && configRef.current !== configOrQueryOrCollection) ||\n    (!isCollection &&\n      (depsRef.current === null ||\n        depsRef.current.length !== deps.length ||\n        depsRef.current.some((dep, i) => dep !== deps[i])))\n\n  if (needsNewCollection) {\n    if (isCollection) {\n      // It's already a collection, ensure sync is started for React hooks\n      configOrQueryOrCollection.startSyncImmediate()\n      collectionRef.current = configOrQueryOrCollection\n      configRef.current = configOrQueryOrCollection\n    } else {\n      // Original logic for creating collections\n      // Ensure we always start sync for React hooks\n      if (typeof configOrQueryOrCollection === `function`) {\n        collectionRef.current = createLiveQueryCollection({\n          query: configOrQueryOrCollection,\n          startSync: true,\n          gcTime: 0, // Live queries created by useLiveQuery are cleaned up immediately\n        }) as unknown as Collection<object, string | number, {}>\n      } else {\n        collectionRef.current = createLiveQueryCollection({\n          startSync: true,\n          gcTime: 0, // Live queries created by useLiveQuery are cleaned up immediately\n          ...configOrQueryOrCollection,\n        }) as unknown as Collection<object, string | number, {}>\n      }\n      depsRef.current = [...deps]\n    }\n  }\n\n  // Use refs to track version and memoized snapshot\n  const versionRef = useRef(0)\n  const snapshotRef = useRef<{\n    collection: Collection<object, string | number, {}>\n    version: number\n  } | null>(null)\n\n  // Reset refs when collection changes\n  if (needsNewCollection) {\n    versionRef.current = 0\n    snapshotRef.current = null\n  }\n\n  // Create stable subscribe function using ref\n  const subscribeRef = useRef<\n    ((onStoreChange: () => void) => () => void) | null\n  >(null)\n  if (!subscribeRef.current || needsNewCollection) {\n    subscribeRef.current = (onStoreChange: () => void) => {\n      const unsubscribe = collectionRef.current!.subscribeChanges(() => {\n        // Bump version on any change; getSnapshot will rebuild next time\n        versionRef.current += 1\n        onStoreChange()\n      })\n      return () => {\n        unsubscribe()\n      }\n    }\n  }\n\n  // Create stable getSnapshot function using ref\n  const getSnapshotRef = useRef<\n    | (() => {\n        collection: Collection<object, string | number, {}>\n        version: number\n      })\n    | null\n  >(null)\n  if (!getSnapshotRef.current || needsNewCollection) {\n    getSnapshotRef.current = () => {\n      const currentVersion = versionRef.current\n      const currentCollection = collectionRef.current!\n\n      // Recreate snapshot object only if version/collection changed\n      if (\n        !snapshotRef.current ||\n        snapshotRef.current.version !== currentVersion ||\n        snapshotRef.current.collection !== currentCollection\n      ) {\n        snapshotRef.current = {\n          collection: currentCollection,\n          version: currentVersion,\n        }\n      }\n\n      return snapshotRef.current\n    }\n  }\n\n  // Use useSyncExternalStore to subscribe to collection changes\n  const snapshot = useSyncExternalStore(\n    subscribeRef.current,\n    getSnapshotRef.current\n  )\n\n  // Track last snapshot (from useSyncExternalStore) and the returned value separately\n  const returnedSnapshotRef = useRef<{\n    collection: Collection<object, string | number, {}>\n    version: number\n  } | null>(null)\n  // Keep implementation return loose to satisfy overload signatures\n  const returnedRef = useRef<any>(null)\n\n  // Rebuild returned object only when the snapshot changes (version or collection identity)\n  if (\n    !returnedSnapshotRef.current ||\n    returnedSnapshotRef.current.version !== snapshot.version ||\n    returnedSnapshotRef.current.collection !== snapshot.collection\n  ) {\n    // Capture a stable view of entries for this snapshot to avoid tearing\n    const entries = Array.from(snapshot.collection.entries())\n    let stateCache: Map<string | number, unknown> | null = null\n    let dataCache: Array<unknown> | null = null\n\n    returnedRef.current = {\n      get state() {\n        if (!stateCache) {\n          stateCache = new Map(entries)\n        }\n        return stateCache\n      },\n      get data() {\n        if (!dataCache) {\n          dataCache = entries.map(([, value]) => value)\n        }\n        return dataCache\n      },\n      collection: snapshot.collection,\n      status: snapshot.collection.status,\n      isLoading:\n        snapshot.collection.status === `loading` ||\n        snapshot.collection.status === `initialCommit`,\n      isReady: snapshot.collection.status === `ready`,\n      isIdle: snapshot.collection.status === `idle`,\n      isError: snapshot.collection.status === `error`,\n      isCleanedUp: snapshot.collection.status === `cleaned-up`,\n    }\n\n    // Remember the snapshot that produced this returned value\n    returnedSnapshotRef.current = snapshot\n  }\n\n  return returnedRef.current!\n}\n"],"names":[],"mappings":"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"}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@tanstack/react-db",
   "description": "React integration for @tanstack/db",
-  "version": "0.1.4",
+  "version": "0.1.5",
   "author": "Kyle Mathews",
   "license": "MIT",
   "repository": {
@@ -17,7 +17,7 @@
   ],
   "dependencies": {
     "use-sync-external-store": "^1.2.0",
-    "@tanstack/db": "0.1.4"
+    "@tanstack/db": "0.1.5"
   },
   "devDependencies": {
     "@electric-sql/client": "1.0.0",

package/src/useLiveQuery.ts

@@ -187,9 +187,11 @@ export function useLiveQuery(
     typeof configOrQueryOrCollection.id === `string`
 
   // Use refs to cache collection and track dependencies
-  const collectionRef = useRef<any>(null)
+  const collectionRef = useRef<Collection<object, string | number, {}> | null>(
+    null
+  )
   const depsRef = useRef<Array<unknown> | null>(null)
-  const configRef = useRef<any>(null)
+  const configRef = useRef<unknown>(null)
 
   // Check if we need to create/recreate the collection
   const needsNewCollection =
@@ -214,13 +216,13 @@ export function useLiveQuery(
           query: configOrQueryOrCollection,
           startSync: true,
           gcTime: 0, // Live queries created by useLiveQuery are cleaned up immediately
-        })
+        }) as unknown as Collection<object, string | number, {}>
       } else {
         collectionRef.current = createLiveQueryCollection({
           startSync: true,
           gcTime: 0, // Live queries created by useLiveQuery are cleaned up immediately
           ...configOrQueryOrCollection,
-        })
+        }) as unknown as Collection<object, string | number, {}>
       }
       depsRef.current = [...deps]
     }
@@ -229,10 +231,8 @@ export function useLiveQuery(
   // Use refs to track version and memoized snapshot
   const versionRef = useRef(0)
   const snapshotRef = useRef<{
-    state: Map<any, any>
-    data: Array<any>
-    collection: Collection<any, any, any>
-    _version: number
+    collection: Collection<object, string | number, {}>
+    version: number
   } | null>(null)
 
   // Reset refs when collection changes
@@ -248,6 +248,7 @@ export function useLiveQuery(
   if (!subscribeRef.current || needsNewCollection) {
     subscribeRef.current = (onStoreChange: () => void) => {
       const unsubscribe = collectionRef.current!.subscribeChanges(() => {
+        // Bump version on any change; getSnapshot will rebuild next time
         versionRef.current += 1
         onStoreChange()
       })
@@ -260,9 +261,8 @@ export function useLiveQuery(
   // Create stable getSnapshot function using ref
   const getSnapshotRef = useRef<
     | (() => {
-        state: Map<any, any>
-        data: Array<any>
-        collection: Collection<any, any, any>
+        collection: Collection<object, string | number, {}>
+        version: number
       })
     | null
   >(null)
@@ -271,20 +271,15 @@ export function useLiveQuery(
       const currentVersion = versionRef.current
       const currentCollection = collectionRef.current!
 
-      // If we don't have a snapshot or the version changed, create a new one
+      // Recreate snapshot object only if version/collection changed
       if (
         !snapshotRef.current ||
-        snapshotRef.current._version !== currentVersion
+        snapshotRef.current.version !== currentVersion ||
+        snapshotRef.current.collection !== currentCollection
       ) {
         snapshotRef.current = {
-          get state() {
-            return new Map(currentCollection.entries())
-          },
-          get data() {
-            return Array.from(currentCollection.values())
-          },
           collection: currentCollection,
-          _version: currentVersion,
+          version: currentVersion,
         }
       }
 
@@ -298,17 +293,52 @@ export function useLiveQuery(
     getSnapshotRef.current
   )
 
-  return {
-    state: snapshot.state,
-    data: snapshot.data,
-    collection: snapshot.collection,
-    status: snapshot.collection.status,
-    isLoading:
-      snapshot.collection.status === `loading` ||
-      snapshot.collection.status === `initialCommit`,
-    isReady: snapshot.collection.status === `ready`,
-    isIdle: snapshot.collection.status === `idle`,
-    isError: snapshot.collection.status === `error`,
-    isCleanedUp: snapshot.collection.status === `cleaned-up`,
+  // Track last snapshot (from useSyncExternalStore) and the returned value separately
+  const returnedSnapshotRef = useRef<{
+    collection: Collection<object, string | number, {}>
+    version: number
+  } | null>(null)
+  // Keep implementation return loose to satisfy overload signatures
+  const returnedRef = useRef<any>(null)
+
+  // Rebuild returned object only when the snapshot changes (version or collection identity)
+  if (
+    !returnedSnapshotRef.current ||
+    returnedSnapshotRef.current.version !== snapshot.version ||
+    returnedSnapshotRef.current.collection !== snapshot.collection
+  ) {
+    // Capture a stable view of entries for this snapshot to avoid tearing
+    const entries = Array.from(snapshot.collection.entries())
+    let stateCache: Map<string | number, unknown> | null = null
+    let dataCache: Array<unknown> | null = null
+
+    returnedRef.current = {
+      get state() {
+        if (!stateCache) {
+          stateCache = new Map(entries)
+        }
+        return stateCache
+      },
+      get data() {
+        if (!dataCache) {
+          dataCache = entries.map(([, value]) => value)
+        }
+        return dataCache
+      },
+      collection: snapshot.collection,
+      status: snapshot.collection.status,
+      isLoading:
+        snapshot.collection.status === `loading` ||
+        snapshot.collection.status === `initialCommit`,
+      isReady: snapshot.collection.status === `ready`,
+      isIdle: snapshot.collection.status === `idle`,
+      isError: snapshot.collection.status === `error`,
+      isCleanedUp: snapshot.collection.status === `cleaned-up`,
+    }
+
+    // Remember the snapshot that produced this returned value
+    returnedSnapshotRef.current = snapshot
   }
+
+  return returnedRef.current!
 }