@tanstack/react-db 0.0.16 → 0.0.18

package/dist/cjs/useLiveQuery.cjs

@@ -77,7 +77,13 @@ function useLiveQuery(configOrQueryOrCollection, deps = []) {
   return {
     state: snapshot.state,
     data: snapshot.data,
-    collection: snapshot.collection
+    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`
   };
 }
 exports.useLiveQuery = useLiveQuery;

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  Context,\n  GetResult,\n  InitialQueryBuilder,\n  LiveQueryCollectionConfig,\n  QueryBuilder,\n} from \"@tanstack/db\"\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}\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}\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}\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  }\n}\n"],"names":["useRef","createLiveQueryCollection","useSyncExternalStore"],"mappings":";;;;AA6CO,SAAS,aACd,2BACA,OAAuB,IACvB;AAEA,QAAM,eACJ,6BACA,OAAO,8BAA8B,YACrC,OAAO,0BAA0B,qBAAqB,cACtD,OAAO,0BAA0B,uBAAuB,cACxD,OAAO,0BAA0B,OAAO;AAGpC,QAAA,gBAAgBA,aAAY,IAAI;AAChC,QAAA,UAAUA,aAA8B,IAAI;AAC5C,QAAA,YAAYA,aAAY,IAAI;AAG5B,QAAA,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,mBAAmB;AAC7C,oBAAc,UAAU;AACxB,gBAAU,UAAU;AAAA,IAAA,OACf;AAGD,UAAA,OAAO,8BAA8B,YAAY;AACnD,sBAAc,UAAUC,6BAA0B;AAAA,UAChD,OAAO;AAAA,UACP,WAAW;AAAA,UACX,QAAQ;AAAA;AAAA,QAAA,CACT;AAAA,MAAA,OACI;AACL,sBAAc,UAAUA,6BAA0B;AAAA,UAChD,WAAW;AAAA,UACX,QAAQ;AAAA;AAAA,UACR,GAAG;AAAA,QAAA,CACJ;AAAA,MAAA;AAEK,cAAA,UAAU,CAAC,GAAG,IAAI;AAAA,IAAA;AAAA,EAC5B;AAII,QAAA,aAAaD,aAAO,CAAC;AACrB,QAAA,cAAcA,aAKV,IAAI;AAGd,MAAI,oBAAoB;AACtB,eAAW,UAAU;AACrB,gBAAY,UAAU;AAAA,EAAA;AAIlB,QAAA,eAAeA,aAEnB,IAAI;AACF,MAAA,CAAC,aAAa,WAAW,oBAAoB;AAClC,iBAAA,UAAU,CAAC,kBAA8B;AACpD,YAAM,cAAc,cAAc,QAAS,iBAAiB,MAAM;AAChE,mBAAW,WAAW;AACR,sBAAA;AAAA,MAAA,CACf;AACD,aAAO,MAAM;AACC,oBAAA;AAAA,MACd;AAAA,IACF;AAAA,EAAA;AAII,QAAA,iBAAiBA,aAOrB,IAAI;AACF,MAAA,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,QACZ;AAAA,MAAA;AAGF,aAAO,YAAY;AAAA,IACrB;AAAA,EAAA;AAIF,QAAM,WAAWE,MAAA;AAAA,IACf,aAAa;AAAA,IACb,eAAe;AAAA,EACjB;AAEO,SAAA;AAAA,IACL,OAAO,SAAS;AAAA,IAChB,MAAM,SAAS;AAAA,IACf,YAAY,SAAS;AAAA,EACvB;AACF;;"}
+{"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;;"}

package/dist/cjs/useLiveQuery.d.cts

@@ -1,16 +1,146 @@
-import { Collection, Context, GetResult, InitialQueryBuilder, LiveQueryCollectionConfig, QueryBuilder } from '@tanstack/db';
+import { Collection, CollectionStatus, Context, GetResult, InitialQueryBuilder, LiveQueryCollectionConfig, QueryBuilder } from '@tanstack/db';
+/**
+ * Create a live query using a query function
+ * @param queryFn - Query function that defines what data to fetch
+ * @param deps - Array of dependencies that trigger query re-execution when changed
+ * @returns Object with reactive data, state, and status information
+ * @example
+ * // Basic query with object syntax
+ * const { data, isLoading } = useLiveQuery((q) =>
+ *   q.from({ todos: todosCollection })
+ *    .where(({ todos }) => eq(todos.completed, false))
+ *    .select(({ todos }) => ({ id: todos.id, text: todos.text }))
+ * )
+ *
+ * @example
+ * // With dependencies that trigger re-execution
+ * const { data, state } = useLiveQuery(
+ *   (q) => q.from({ todos: todosCollection })
+ *          .where(({ todos }) => gt(todos.priority, minPriority)),
+ *   [minPriority] // Re-run when minPriority changes
+ * )
+ *
+ * @example
+ * // Join pattern
+ * const { data } = useLiveQuery((q) =>
+ *   q.from({ issues: issueCollection })
+ *    .join({ persons: personCollection }, ({ issues, persons }) =>
+ *      eq(issues.userId, persons.id)
+ *    )
+ *    .select(({ issues, persons }) => ({
+ *      id: issues.id,
+ *      title: issues.title,
+ *      userName: persons.name
+ *    }))
+ * )
+ *
+ * @example
+ * // Handle loading and error states
+ * const { data, isLoading, isError, status } = useLiveQuery((q) =>
+ *   q.from({ todos: todoCollection })
+ * )
+ *
+ * if (isLoading) return <div>Loading...</div>
+ * if (isError) return <div>Error: {status}</div>
+ *
+ * return (
+ *   <ul>
+ *     {data.map(todo => <li key={todo.id}>{todo.text}</li>)}
+ *   </ul>
+ * )
+ */
 export declare function useLiveQuery<TContext extends Context>(queryFn: (q: InitialQueryBuilder) => QueryBuilder<TContext>, deps?: Array<unknown>): {
     state: Map<string | number, GetResult<TContext>>;
     data: Array<GetResult<TContext>>;
     collection: Collection<GetResult<TContext>, string | number, {}>;
+    status: CollectionStatus;
+    isLoading: boolean;
+    isReady: boolean;
+    isIdle: boolean;
+    isError: boolean;
+    isCleanedUp: boolean;
 };
+/**
+ * Create a live query using configuration object
+ * @param config - Configuration object with query and options
+ * @param deps - Array of dependencies that trigger query re-execution when changed
+ * @returns Object with reactive data, state, and status information
+ * @example
+ * // Basic config object usage
+ * const { data, status } = useLiveQuery({
+ *   query: (q) => q.from({ todos: todosCollection }),
+ *   gcTime: 60000
+ * })
+ *
+ * @example
+ * // With query builder and options
+ * const queryBuilder = new Query()
+ *   .from({ persons: collection })
+ *   .where(({ persons }) => gt(persons.age, 30))
+ *   .select(({ persons }) => ({ id: persons.id, name: persons.name }))
+ *
+ * const { data, isReady } = useLiveQuery({ query: queryBuilder })
+ *
+ * @example
+ * // Handle all states uniformly
+ * const { data, isLoading, isReady, isError } = useLiveQuery({
+ *   query: (q) => q.from({ items: itemCollection })
+ * })
+ *
+ * if (isLoading) return <div>Loading...</div>
+ * if (isError) return <div>Something went wrong</div>
+ * if (!isReady) return <div>Preparing...</div>
+ *
+ * return <div>{data.length} items loaded</div>
+ */
 export declare function useLiveQuery<TContext extends Context>(config: LiveQueryCollectionConfig<TContext>, deps?: Array<unknown>): {
     state: Map<string | number, GetResult<TContext>>;
     data: Array<GetResult<TContext>>;
     collection: Collection<GetResult<TContext>, string | number, {}>;
+    status: CollectionStatus;
+    isLoading: boolean;
+    isReady: boolean;
+    isIdle: boolean;
+    isError: boolean;
+    isCleanedUp: boolean;
 };
+/**
+ * Subscribe to an existing live query collection
+ * @param liveQueryCollection - Pre-created live query collection to subscribe to
+ * @returns Object with reactive data, state, and status information
+ * @example
+ * // Using pre-created live query collection
+ * const myLiveQuery = createLiveQueryCollection((q) =>
+ *   q.from({ todos: todosCollection }).where(({ todos }) => eq(todos.active, true))
+ * )
+ * const { data, collection } = useLiveQuery(myLiveQuery)
+ *
+ * @example
+ * // Access collection methods directly
+ * const { data, collection, isReady } = useLiveQuery(existingCollection)
+ *
+ * // Use collection for mutations
+ * const handleToggle = (id) => {
+ *   collection.update(id, draft => { draft.completed = !draft.completed })
+ * }
+ *
+ * @example
+ * // Handle states consistently
+ * const { data, isLoading, isError } = useLiveQuery(sharedCollection)
+ *
+ * if (isLoading) return <div>Loading...</div>
+ * if (isError) return <div>Error loading data</div>
+ *
+ * return <div>{data.map(item => <Item key={item.id} {...item} />)}</div>
+ */
 export declare function useLiveQuery<TResult extends object, TKey extends string | number, TUtils extends Record<string, any>>(liveQueryCollection: Collection<TResult, TKey, TUtils>): {
     state: Map<TKey, TResult>;
     data: Array<TResult>;
     collection: Collection<TResult, TKey, TUtils>;
+    status: CollectionStatus;
+    isLoading: boolean;
+    isReady: boolean;
+    isIdle: boolean;
+    isError: boolean;
+    isCleanedUp: boolean;
 };

package/dist/esm/useLiveQuery.d.ts

@@ -1,16 +1,146 @@
-import { Collection, Context, GetResult, InitialQueryBuilder, LiveQueryCollectionConfig, QueryBuilder } from '@tanstack/db';
+import { Collection, CollectionStatus, Context, GetResult, InitialQueryBuilder, LiveQueryCollectionConfig, QueryBuilder } from '@tanstack/db';
+/**
+ * Create a live query using a query function
+ * @param queryFn - Query function that defines what data to fetch
+ * @param deps - Array of dependencies that trigger query re-execution when changed
+ * @returns Object with reactive data, state, and status information
+ * @example
+ * // Basic query with object syntax
+ * const { data, isLoading } = useLiveQuery((q) =>
+ *   q.from({ todos: todosCollection })
+ *    .where(({ todos }) => eq(todos.completed, false))
+ *    .select(({ todos }) => ({ id: todos.id, text: todos.text }))
+ * )
+ *
+ * @example
+ * // With dependencies that trigger re-execution
+ * const { data, state } = useLiveQuery(
+ *   (q) => q.from({ todos: todosCollection })
+ *          .where(({ todos }) => gt(todos.priority, minPriority)),
+ *   [minPriority] // Re-run when minPriority changes
+ * )
+ *
+ * @example
+ * // Join pattern
+ * const { data } = useLiveQuery((q) =>
+ *   q.from({ issues: issueCollection })
+ *    .join({ persons: personCollection }, ({ issues, persons }) =>
+ *      eq(issues.userId, persons.id)
+ *    )
+ *    .select(({ issues, persons }) => ({
+ *      id: issues.id,
+ *      title: issues.title,
+ *      userName: persons.name
+ *    }))
+ * )
+ *
+ * @example
+ * // Handle loading and error states
+ * const { data, isLoading, isError, status } = useLiveQuery((q) =>
+ *   q.from({ todos: todoCollection })
+ * )
+ *
+ * if (isLoading) return <div>Loading...</div>
+ * if (isError) return <div>Error: {status}</div>
+ *
+ * return (
+ *   <ul>
+ *     {data.map(todo => <li key={todo.id}>{todo.text}</li>)}
+ *   </ul>
+ * )
+ */
 export declare function useLiveQuery<TContext extends Context>(queryFn: (q: InitialQueryBuilder) => QueryBuilder<TContext>, deps?: Array<unknown>): {
     state: Map<string | number, GetResult<TContext>>;
     data: Array<GetResult<TContext>>;
     collection: Collection<GetResult<TContext>, string | number, {}>;
+    status: CollectionStatus;
+    isLoading: boolean;
+    isReady: boolean;
+    isIdle: boolean;
+    isError: boolean;
+    isCleanedUp: boolean;
 };
+/**
+ * Create a live query using configuration object
+ * @param config - Configuration object with query and options
+ * @param deps - Array of dependencies that trigger query re-execution when changed
+ * @returns Object with reactive data, state, and status information
+ * @example
+ * // Basic config object usage
+ * const { data, status } = useLiveQuery({
+ *   query: (q) => q.from({ todos: todosCollection }),
+ *   gcTime: 60000
+ * })
+ *
+ * @example
+ * // With query builder and options
+ * const queryBuilder = new Query()
+ *   .from({ persons: collection })
+ *   .where(({ persons }) => gt(persons.age, 30))
+ *   .select(({ persons }) => ({ id: persons.id, name: persons.name }))
+ *
+ * const { data, isReady } = useLiveQuery({ query: queryBuilder })
+ *
+ * @example
+ * // Handle all states uniformly
+ * const { data, isLoading, isReady, isError } = useLiveQuery({
+ *   query: (q) => q.from({ items: itemCollection })
+ * })
+ *
+ * if (isLoading) return <div>Loading...</div>
+ * if (isError) return <div>Something went wrong</div>
+ * if (!isReady) return <div>Preparing...</div>
+ *
+ * return <div>{data.length} items loaded</div>
+ */
 export declare function useLiveQuery<TContext extends Context>(config: LiveQueryCollectionConfig<TContext>, deps?: Array<unknown>): {
     state: Map<string | number, GetResult<TContext>>;
     data: Array<GetResult<TContext>>;
     collection: Collection<GetResult<TContext>, string | number, {}>;
+    status: CollectionStatus;
+    isLoading: boolean;
+    isReady: boolean;
+    isIdle: boolean;
+    isError: boolean;
+    isCleanedUp: boolean;
 };
+/**
+ * Subscribe to an existing live query collection
+ * @param liveQueryCollection - Pre-created live query collection to subscribe to
+ * @returns Object with reactive data, state, and status information
+ * @example
+ * // Using pre-created live query collection
+ * const myLiveQuery = createLiveQueryCollection((q) =>
+ *   q.from({ todos: todosCollection }).where(({ todos }) => eq(todos.active, true))
+ * )
+ * const { data, collection } = useLiveQuery(myLiveQuery)
+ *
+ * @example
+ * // Access collection methods directly
+ * const { data, collection, isReady } = useLiveQuery(existingCollection)
+ *
+ * // Use collection for mutations
+ * const handleToggle = (id) => {
+ *   collection.update(id, draft => { draft.completed = !draft.completed })
+ * }
+ *
+ * @example
+ * // Handle states consistently
+ * const { data, isLoading, isError } = useLiveQuery(sharedCollection)
+ *
+ * if (isLoading) return <div>Loading...</div>
+ * if (isError) return <div>Error loading data</div>
+ *
+ * return <div>{data.map(item => <Item key={item.id} {...item} />)}</div>
+ */
 export declare function useLiveQuery<TResult extends object, TKey extends string | number, TUtils extends Record<string, any>>(liveQueryCollection: Collection<TResult, TKey, TUtils>): {
     state: Map<TKey, TResult>;
     data: Array<TResult>;
     collection: Collection<TResult, TKey, TUtils>;
+    status: CollectionStatus;
+    isLoading: boolean;
+    isReady: boolean;
+    isIdle: boolean;
+    isError: boolean;
+    isCleanedUp: boolean;
 };

package/dist/esm/useLiveQuery.js

@@ -75,7 +75,13 @@ function useLiveQuery(configOrQueryOrCollection, deps = []) {
   return {
     state: snapshot.state,
     data: snapshot.data,
-    collection: snapshot.collection
+    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`
   };
 }
 export {

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  Context,\n  GetResult,\n  InitialQueryBuilder,\n  LiveQueryCollectionConfig,\n  QueryBuilder,\n} from \"@tanstack/db\"\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}\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}\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}\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  }\n}\n"],"names":[],"mappings":";;AA6CO,SAAS,aACd,2BACA,OAAuB,IACvB;AAEA,QAAM,eACJ,6BACA,OAAO,8BAA8B,YACrC,OAAO,0BAA0B,qBAAqB,cACtD,OAAO,0BAA0B,uBAAuB,cACxD,OAAO,0BAA0B,OAAO;AAGpC,QAAA,gBAAgB,OAAY,IAAI;AAChC,QAAA,UAAU,OAA8B,IAAI;AAC5C,QAAA,YAAY,OAAY,IAAI;AAG5B,QAAA,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,mBAAmB;AAC7C,oBAAc,UAAU;AACxB,gBAAU,UAAU;AAAA,IAAA,OACf;AAGD,UAAA,OAAO,8BAA8B,YAAY;AACnD,sBAAc,UAAU,0BAA0B;AAAA,UAChD,OAAO;AAAA,UACP,WAAW;AAAA,UACX,QAAQ;AAAA;AAAA,QAAA,CACT;AAAA,MAAA,OACI;AACL,sBAAc,UAAU,0BAA0B;AAAA,UAChD,WAAW;AAAA,UACX,QAAQ;AAAA;AAAA,UACR,GAAG;AAAA,QAAA,CACJ;AAAA,MAAA;AAEK,cAAA,UAAU,CAAC,GAAG,IAAI;AAAA,IAAA;AAAA,EAC5B;AAII,QAAA,aAAa,OAAO,CAAC;AACrB,QAAA,cAAc,OAKV,IAAI;AAGd,MAAI,oBAAoB;AACtB,eAAW,UAAU;AACrB,gBAAY,UAAU;AAAA,EAAA;AAIlB,QAAA,eAAe,OAEnB,IAAI;AACF,MAAA,CAAC,aAAa,WAAW,oBAAoB;AAClC,iBAAA,UAAU,CAAC,kBAA8B;AACpD,YAAM,cAAc,cAAc,QAAS,iBAAiB,MAAM;AAChE,mBAAW,WAAW;AACR,sBAAA;AAAA,MAAA,CACf;AACD,aAAO,MAAM;AACC,oBAAA;AAAA,MACd;AAAA,IACF;AAAA,EAAA;AAII,QAAA,iBAAiB,OAOrB,IAAI;AACF,MAAA,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,QACZ;AAAA,MAAA;AAGF,aAAO,YAAY;AAAA,IACrB;AAAA,EAAA;AAIF,QAAM,WAAW;AAAA,IACf,aAAa;AAAA,IACb,eAAe;AAAA,EACjB;AAEO,SAAA;AAAA,IACL,OAAO,SAAS;AAAA,IAChB,MAAM,SAAS;AAAA,IACf,YAAY,SAAS;AAAA,EACvB;AACF;"}
+{"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;"}

package/package.json

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

package/src/useLiveQuery.ts

@@ -2,6 +2,7 @@ import { useRef, useSyncExternalStore } from "react"
 import { createLiveQueryCollection } from "@tanstack/db"
 import type {
   Collection,
+  CollectionStatus,
   Context,
   GetResult,
   InitialQueryBuilder,
@@ -9,6 +10,56 @@ import type {
   QueryBuilder,
 } from "@tanstack/db"
 
+/**
+ * Create a live query using a query function
+ * @param queryFn - Query function that defines what data to fetch
+ * @param deps - Array of dependencies that trigger query re-execution when changed
+ * @returns Object with reactive data, state, and status information
+ * @example
+ * // Basic query with object syntax
+ * const { data, isLoading } = useLiveQuery((q) =>
+ *   q.from({ todos: todosCollection })
+ *    .where(({ todos }) => eq(todos.completed, false))
+ *    .select(({ todos }) => ({ id: todos.id, text: todos.text }))
+ * )
+ *
+ * @example
+ * // With dependencies that trigger re-execution
+ * const { data, state } = useLiveQuery(
+ *   (q) => q.from({ todos: todosCollection })
+ *          .where(({ todos }) => gt(todos.priority, minPriority)),
+ *   [minPriority] // Re-run when minPriority changes
+ * )
+ *
+ * @example
+ * // Join pattern
+ * const { data } = useLiveQuery((q) =>
+ *   q.from({ issues: issueCollection })
+ *    .join({ persons: personCollection }, ({ issues, persons }) =>
+ *      eq(issues.userId, persons.id)
+ *    )
+ *    .select(({ issues, persons }) => ({
+ *      id: issues.id,
+ *      title: issues.title,
+ *      userName: persons.name
+ *    }))
+ * )
+ *
+ * @example
+ * // Handle loading and error states
+ * const { data, isLoading, isError, status } = useLiveQuery((q) =>
+ *   q.from({ todos: todoCollection })
+ * )
+ *
+ * if (isLoading) return <div>Loading...</div>
+ * if (isError) return <div>Error: {status}</div>
+ *
+ * return (
+ *   <ul>
+ *     {data.map(todo => <li key={todo.id}>{todo.text}</li>)}
+ *   </ul>
+ * )
+ */
 // Overload 1: Accept just the query function
 export function useLiveQuery<TContext extends Context>(
   queryFn: (q: InitialQueryBuilder) => QueryBuilder<TContext>,
@@ -17,8 +68,47 @@ export function useLiveQuery<TContext extends Context>(
   state: Map<string | number, GetResult<TContext>>
   data: Array<GetResult<TContext>>
   collection: Collection<GetResult<TContext>, string | number, {}>
+  status: CollectionStatus
+  isLoading: boolean
+  isReady: boolean
+  isIdle: boolean
+  isError: boolean
+  isCleanedUp: boolean
 }
 
+/**
+ * Create a live query using configuration object
+ * @param config - Configuration object with query and options
+ * @param deps - Array of dependencies that trigger query re-execution when changed
+ * @returns Object with reactive data, state, and status information
+ * @example
+ * // Basic config object usage
+ * const { data, status } = useLiveQuery({
+ *   query: (q) => q.from({ todos: todosCollection }),
+ *   gcTime: 60000
+ * })
+ *
+ * @example
+ * // With query builder and options
+ * const queryBuilder = new Query()
+ *   .from({ persons: collection })
+ *   .where(({ persons }) => gt(persons.age, 30))
+ *   .select(({ persons }) => ({ id: persons.id, name: persons.name }))
+ *
+ * const { data, isReady } = useLiveQuery({ query: queryBuilder })
+ *
+ * @example
+ * // Handle all states uniformly
+ * const { data, isLoading, isReady, isError } = useLiveQuery({
+ *   query: (q) => q.from({ items: itemCollection })
+ * })
+ *
+ * if (isLoading) return <div>Loading...</div>
+ * if (isError) return <div>Something went wrong</div>
+ * if (!isReady) return <div>Preparing...</div>
+ *
+ * return <div>{data.length} items loaded</div>
+ */
 // Overload 2: Accept config object
 export function useLiveQuery<TContext extends Context>(
   config: LiveQueryCollectionConfig<TContext>,
@@ -27,8 +117,43 @@ export function useLiveQuery<TContext extends Context>(
   state: Map<string | number, GetResult<TContext>>
   data: Array<GetResult<TContext>>
   collection: Collection<GetResult<TContext>, string | number, {}>
+  status: CollectionStatus
+  isLoading: boolean
+  isReady: boolean
+  isIdle: boolean
+  isError: boolean
+  isCleanedUp: boolean
 }
 
+/**
+ * Subscribe to an existing live query collection
+ * @param liveQueryCollection - Pre-created live query collection to subscribe to
+ * @returns Object with reactive data, state, and status information
+ * @example
+ * // Using pre-created live query collection
+ * const myLiveQuery = createLiveQueryCollection((q) =>
+ *   q.from({ todos: todosCollection }).where(({ todos }) => eq(todos.active, true))
+ * )
+ * const { data, collection } = useLiveQuery(myLiveQuery)
+ *
+ * @example
+ * // Access collection methods directly
+ * const { data, collection, isReady } = useLiveQuery(existingCollection)
+ *
+ * // Use collection for mutations
+ * const handleToggle = (id) => {
+ *   collection.update(id, draft => { draft.completed = !draft.completed })
+ * }
+ *
+ * @example
+ * // Handle states consistently
+ * const { data, isLoading, isError } = useLiveQuery(sharedCollection)
+ *
+ * if (isLoading) return <div>Loading...</div>
+ * if (isError) return <div>Error loading data</div>
+ *
+ * return <div>{data.map(item => <Item key={item.id} {...item} />)}</div>
+ */
 // Overload 3: Accept pre-created live query collection
 export function useLiveQuery<
   TResult extends object,
@@ -40,6 +165,12 @@ export function useLiveQuery<
   state: Map<TKey, TResult>
   data: Array<TResult>
   collection: Collection<TResult, TKey, TUtils>
+  status: CollectionStatus
+  isLoading: boolean
+  isReady: boolean
+  isIdle: boolean
+  isError: boolean
+  isCleanedUp: boolean
 }
 
 // Implementation - use function overloads to infer the actual collection type
@@ -171,5 +302,13 @@ export function useLiveQuery(
     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`,
   }
 }