@tanstack/react-db 0.1.10 → 0.1.11

package/dist/cjs/useLiveQuery.cjs

@@ -47,6 +47,10 @@ function useLiveQuery(configOrQueryOrCollection, deps = []) {
         versionRef.current += 1;
         onStoreChange();
       });
+      if (collectionRef.current.status === `ready`) {
+        versionRef.current += 1;
+        onStoreChange();
+      }
       return () => {
         unsubscribe();
       };

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<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":";;;;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;AAAAA,IACpB;AAAA,EAAA;AAEF,QAAM,UAAUA,MAAAA,OAA8B,IAAI;AAClD,QAAM,YAAYA,MAAAA,OAAgB,IAAI;AAGtC,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,OAGV,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;AAEhE,mBAAW,WAAW;AACtB,sBAAA;AAAA,MACF,CAAC;AACD,aAAO,MAAM;AACX,oBAAA;AAAA,MACF;AAAA,IACF;AAAA,EACF;AAGA,QAAM,iBAAiBA,MAAAA,OAMrB,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,YAAY,kBAChC,YAAY,QAAQ,eAAe,mBACnC;AACA,oBAAY,UAAU;AAAA,UACpB,YAAY;AAAA,UACZ,SAAS;AAAA,QAAA;AAAA,MAEb;AAEA,aAAO,YAAY;AAAA,IACrB;AAAA,EACF;AAGA,QAAM,WAAWE,MAAAA;AAAAA,IACf,aAAa;AAAA,IACb,eAAe;AAAA,EAAA;AAIjB,QAAM,sBAAsBF,MAAAA,OAGlB,IAAI;AAEd,QAAM,cAAcA,MAAAA,OAAY,IAAI;AAGpC,MACE,CAAC,oBAAoB,WACrB,oBAAoB,QAAQ,YAAY,SAAS,WACjD,oBAAoB,QAAQ,eAAe,SAAS,YACpD;AAEA,UAAM,UAAU,MAAM,KAAK,SAAS,WAAW,SAAS;AACxD,QAAI,aAAmD;AACvD,QAAI,YAAmC;AAEvC,gBAAY,UAAU;AAAA,MACpB,IAAI,QAAQ;AACV,YAAI,CAAC,YAAY;AACf,uBAAa,IAAI,IAAI,OAAO;AAAA,QAC9B;AACA,eAAO;AAAA,MACT;AAAA,MACA,IAAI,OAAO;AACT,YAAI,CAAC,WAAW;AACd,sBAAY,QAAQ,IAAI,CAAC,CAAA,EAAG,KAAK,MAAM,KAAK;AAAA,QAC9C;AACA,eAAO;AAAA,MACT;AAAA,MACA,YAAY,SAAS;AAAA,MACrB,QAAQ,SAAS,WAAW;AAAA,MAC5B,WACE,SAAS,WAAW,WAAW,aAC/B,SAAS,WAAW,WAAW;AAAA,MACjC,SAAS,SAAS,WAAW,WAAW;AAAA,MACxC,QAAQ,SAAS,WAAW,WAAW;AAAA,MACvC,SAAS,SAAS,WAAW,WAAW;AAAA,MACxC,aAAa,SAAS,WAAW,WAAW;AAAA,IAAA;AAI9C,wBAAoB,UAAU;AAAA,EAChC;AAEA,SAAO,YAAY;AACrB;;"}
+{"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      // Collection may be ready and will not receive initial `subscribeChanges()`\n      if (collectionRef.current!.status === `ready`) {\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":";;;;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;AAAAA,IACpB;AAAA,EAAA;AAEF,QAAM,UAAUA,MAAAA,OAA8B,IAAI;AAClD,QAAM,YAAYA,MAAAA,OAAgB,IAAI;AAGtC,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,OAGV,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;AAEhE,mBAAW,WAAW;AACtB,sBAAA;AAAA,MACF,CAAC;AAED,UAAI,cAAc,QAAS,WAAW,SAAS;AAC7C,mBAAW,WAAW;AACtB,sBAAA;AAAA,MACF;AACA,aAAO,MAAM;AACX,oBAAA;AAAA,MACF;AAAA,IACF;AAAA,EACF;AAGA,QAAM,iBAAiBA,MAAAA,OAMrB,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,YAAY,kBAChC,YAAY,QAAQ,eAAe,mBACnC;AACA,oBAAY,UAAU;AAAA,UACpB,YAAY;AAAA,UACZ,SAAS;AAAA,QAAA;AAAA,MAEb;AAEA,aAAO,YAAY;AAAA,IACrB;AAAA,EACF;AAGA,QAAM,WAAWE,MAAAA;AAAAA,IACf,aAAa;AAAA,IACb,eAAe;AAAA,EAAA;AAIjB,QAAM,sBAAsBF,MAAAA,OAGlB,IAAI;AAEd,QAAM,cAAcA,MAAAA,OAAY,IAAI;AAGpC,MACE,CAAC,oBAAoB,WACrB,oBAAoB,QAAQ,YAAY,SAAS,WACjD,oBAAoB,QAAQ,eAAe,SAAS,YACpD;AAEA,UAAM,UAAU,MAAM,KAAK,SAAS,WAAW,SAAS;AACxD,QAAI,aAAmD;AACvD,QAAI,YAAmC;AAEvC,gBAAY,UAAU;AAAA,MACpB,IAAI,QAAQ;AACV,YAAI,CAAC,YAAY;AACf,uBAAa,IAAI,IAAI,OAAO;AAAA,QAC9B;AACA,eAAO;AAAA,MACT;AAAA,MACA,IAAI,OAAO;AACT,YAAI,CAAC,WAAW;AACd,sBAAY,QAAQ,IAAI,CAAC,CAAA,EAAG,KAAK,MAAM,KAAK;AAAA,QAC9C;AACA,eAAO;AAAA,MACT;AAAA,MACA,YAAY,SAAS;AAAA,MACrB,QAAQ,SAAS,WAAW;AAAA,MAC5B,WACE,SAAS,WAAW,WAAW,aAC/B,SAAS,WAAW,WAAW;AAAA,MACjC,SAAS,SAAS,WAAW,WAAW;AAAA,MACxC,QAAQ,SAAS,WAAW,WAAW;AAAA,MACvC,SAAS,SAAS,WAAW,WAAW;AAAA,MACxC,aAAa,SAAS,WAAW,WAAW;AAAA,IAAA;AAI9C,wBAAoB,UAAU;AAAA,EAChC;AAEA,SAAO,YAAY;AACrB;;"}

package/dist/esm/useLiveQuery.js

@@ -45,6 +45,10 @@ function useLiveQuery(configOrQueryOrCollection, deps = []) {
         versionRef.current += 1;
         onStoreChange();
       });
+      if (collectionRef.current.status === `ready`) {
+        versionRef.current += 1;
+        onStoreChange();
+      }
       return () => {
         unsubscribe();
       };

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<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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"}
+{"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      // Collection may be ready and will not receive initial `subscribeChanges()`\n      if (collectionRef.current!.status === `ready`) {\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":";;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;AAAA,IACpB;AAAA,EAAA;AAEF,QAAM,UAAU,OAA8B,IAAI;AAClD,QAAM,YAAY,OAAgB,IAAI;AAGtC,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,OAGV,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;AAEhE,mBAAW,WAAW;AACtB,sBAAA;AAAA,MACF,CAAC;AAED,UAAI,cAAc,QAAS,WAAW,SAAS;AAC7C,mBAAW,WAAW;AACtB,sBAAA;AAAA,MACF;AACA,aAAO,MAAM;AACX,oBAAA;AAAA,MACF;AAAA,IACF;AAAA,EACF;AAGA,QAAM,iBAAiB,OAMrB,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,YAAY,kBAChC,YAAY,QAAQ,eAAe,mBACnC;AACA,oBAAY,UAAU;AAAA,UACpB,YAAY;AAAA,UACZ,SAAS;AAAA,QAAA;AAAA,MAEb;AAEA,aAAO,YAAY;AAAA,IACrB;AAAA,EACF;AAGA,QAAM,WAAW;AAAA,IACf,aAAa;AAAA,IACb,eAAe;AAAA,EAAA;AAIjB,QAAM,sBAAsB,OAGlB,IAAI;AAEd,QAAM,cAAc,OAAY,IAAI;AAGpC,MACE,CAAC,oBAAoB,WACrB,oBAAoB,QAAQ,YAAY,SAAS,WACjD,oBAAoB,QAAQ,eAAe,SAAS,YACpD;AAEA,UAAM,UAAU,MAAM,KAAK,SAAS,WAAW,SAAS;AACxD,QAAI,aAAmD;AACvD,QAAI,YAAmC;AAEvC,gBAAY,UAAU;AAAA,MACpB,IAAI,QAAQ;AACV,YAAI,CAAC,YAAY;AACf,uBAAa,IAAI,IAAI,OAAO;AAAA,QAC9B;AACA,eAAO;AAAA,MACT;AAAA,MACA,IAAI,OAAO;AACT,YAAI,CAAC,WAAW;AACd,sBAAY,QAAQ,IAAI,CAAC,CAAA,EAAG,KAAK,MAAM,KAAK;AAAA,QAC9C;AACA,eAAO;AAAA,MACT;AAAA,MACA,YAAY,SAAS;AAAA,MACrB,QAAQ,SAAS,WAAW;AAAA,MAC5B,WACE,SAAS,WAAW,WAAW,aAC/B,SAAS,WAAW,WAAW;AAAA,MACjC,SAAS,SAAS,WAAW,WAAW;AAAA,MACxC,QAAQ,SAAS,WAAW,WAAW;AAAA,MACvC,SAAS,SAAS,WAAW,WAAW;AAAA,MACxC,aAAa,SAAS,WAAW,WAAW;AAAA,IAAA;AAI9C,wBAAoB,UAAU;AAAA,EAChC;AAEA,SAAO,YAAY;AACrB;"}

package/package.json

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

package/src/useLiveQuery.ts

@@ -252,6 +252,11 @@ export function useLiveQuery(
         versionRef.current += 1
         onStoreChange()
       })
+      // Collection may be ready and will not receive initial `subscribeChanges()`
+      if (collectionRef.current!.status === `ready`) {
+        versionRef.current += 1
+        onStoreChange()
+      }
       return () => {
         unsubscribe()
       }