@tanstack/react-db 0.1.20 → 0.1.21

package/dist/cjs/useLiveQuery.cjs

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 const react = require("react");
 const db = require("@tanstack/db");
+const DEFAULT_GC_TIME_MS = 1;
 function useLiveQuery(configOrQueryOrCollection, deps = []) {
   const isCollection = configOrQueryOrCollection && typeof configOrQueryOrCollection === `object` && typeof configOrQueryOrCollection.subscribeChanges === `function` && typeof configOrQueryOrCollection.startSyncImmediate === `function` && typeof configOrQueryOrCollection.id === `string`;
   const collectionRef = react.useRef(
@@ -9,6 +10,8 @@ function useLiveQuery(configOrQueryOrCollection, deps = []) {
   );
   const depsRef = react.useRef(null);
   const configRef = react.useRef(null);
+  const versionRef = react.useRef(0);
+  const snapshotRef = react.useRef(null);
   const needsNewCollection = !collectionRef.current || isCollection && configRef.current !== configOrQueryOrCollection || !isCollection && (depsRef.current === null || depsRef.current.length !== deps.length || depsRef.current.some((dep, i) => dep !== deps[i]));
   if (needsNewCollection) {
     if (isCollection) {
@@ -17,25 +20,41 @@ function useLiveQuery(configOrQueryOrCollection, deps = []) {
       configRef.current = configOrQueryOrCollection;
     } else {
       if (typeof configOrQueryOrCollection === `function`) {
-        collectionRef.current = db.createLiveQueryCollection({
-          query: configOrQueryOrCollection,
-          startSync: true,
-          gcTime: 0
-          // Live queries created by useLiveQuery are cleaned up immediately
-        });
+        const queryBuilder = new db.BaseQueryBuilder();
+        const result = configOrQueryOrCollection(queryBuilder);
+        if (result === void 0 || result === null) {
+          collectionRef.current = null;
+        } else if (result instanceof db.CollectionImpl) {
+          result.startSyncImmediate();
+          collectionRef.current = result;
+        } else if (result instanceof db.BaseQueryBuilder) {
+          collectionRef.current = db.createLiveQueryCollection({
+            query: configOrQueryOrCollection,
+            startSync: true,
+            gcTime: DEFAULT_GC_TIME_MS
+          });
+        } else if (result && typeof result === `object`) {
+          collectionRef.current = db.createLiveQueryCollection({
+            startSync: true,
+            gcTime: DEFAULT_GC_TIME_MS,
+            ...result
+          });
+        } else {
+          throw new Error(
+            `useLiveQuery callback must return a QueryBuilder, LiveQueryCollectionConfig, Collection, undefined, or null. Got: ${typeof result}`
+          );
+        }
+        depsRef.current = [...deps];
       } else {
         collectionRef.current = db.createLiveQueryCollection({
           startSync: true,
-          gcTime: 0,
-          // Live queries created by useLiveQuery are cleaned up immediately
+          gcTime: DEFAULT_GC_TIME_MS,
           ...configOrQueryOrCollection
         });
+        depsRef.current = [...deps];
       }
-      depsRef.current = [...deps];
     }
   }
-  const versionRef = react.useRef(0);
-  const snapshotRef = react.useRef(null);
   if (needsNewCollection) {
     versionRef.current = 0;
     snapshotRef.current = null;
@@ -43,6 +62,10 @@ function useLiveQuery(configOrQueryOrCollection, deps = []) {
   const subscribeRef = react.useRef(null);
   if (!subscribeRef.current || needsNewCollection) {
     subscribeRef.current = (onStoreChange) => {
+      if (!collectionRef.current) {
+        return () => {
+        };
+      }
       const unsubscribe = collectionRef.current.subscribeChanges(() => {
         versionRef.current += 1;
         onStoreChange();
@@ -77,30 +100,46 @@ function useLiveQuery(configOrQueryOrCollection, deps = []) {
   const returnedSnapshotRef = react.useRef(null);
   const returnedRef = react.useRef(null);
   if (!returnedSnapshotRef.current || returnedSnapshotRef.current.version !== snapshot.version || returnedSnapshotRef.current.collection !== snapshot.collection) {
-    const entries = Array.from(snapshot.collection.entries());
-    let stateCache = null;
-    let dataCache = null;
-    returnedRef.current = {
-      get state() {
-        if (!stateCache) {
-          stateCache = new Map(entries);
-        }
-        return stateCache;
-      },
-      get data() {
-        if (!dataCache) {
-          dataCache = entries.map(([, value]) => value);
-        }
-        return dataCache;
-      },
-      collection: snapshot.collection,
-      status: snapshot.collection.status,
-      isLoading: snapshot.collection.status === `loading` || snapshot.collection.status === `initialCommit`,
-      isReady: snapshot.collection.status === `ready`,
-      isIdle: snapshot.collection.status === `idle`,
-      isError: snapshot.collection.status === `error`,
-      isCleanedUp: snapshot.collection.status === `cleaned-up`
-    };
+    if (!snapshot.collection) {
+      returnedRef.current = {
+        state: void 0,
+        data: void 0,
+        collection: void 0,
+        status: `disabled`,
+        isLoading: false,
+        isReady: false,
+        isIdle: false,
+        isError: false,
+        isCleanedUp: false,
+        isEnabled: false
+      };
+    } else {
+      const entries = Array.from(snapshot.collection.entries());
+      let stateCache = null;
+      let dataCache = null;
+      returnedRef.current = {
+        get state() {
+          if (!stateCache) {
+            stateCache = new Map(entries);
+          }
+          return stateCache;
+        },
+        get data() {
+          if (!dataCache) {
+            dataCache = entries.map(([, value]) => value);
+          }
+          return dataCache;
+        },
+        collection: snapshot.collection,
+        status: snapshot.collection.status,
+        isLoading: snapshot.collection.status === `loading` || snapshot.collection.status === `initialCommit`,
+        isReady: snapshot.collection.status === `ready`,
+        isIdle: snapshot.collection.status === `idle`,
+        isError: snapshot.collection.status === `error`,
+        isCleanedUp: snapshot.collection.status === `cleaned-up`,
+        isEnabled: true
+      };
+    }
     returnedSnapshotRef.current = snapshot;
   }
   return returnedRef.current;

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      // 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":"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"}
+{"version":3,"file":"useLiveQuery.cjs","sources":["../../src/useLiveQuery.ts"],"sourcesContent":["import { useRef, useSyncExternalStore } from \"react\"\nimport {\n  BaseQueryBuilder,\n  CollectionImpl,\n  createLiveQueryCollection,\n} from \"@tanstack/db\"\nimport type {\n  Collection,\n  CollectionStatus,\n  Context,\n  GetResult,\n  InitialQueryBuilder,\n  LiveQueryCollectionConfig,\n  QueryBuilder,\n} from \"@tanstack/db\"\n\nconst DEFAULT_GC_TIME_MS = 1 // Live queries created by useLiveQuery are cleaned up immediately (0 disables GC)\n\nexport type UseLiveQueryStatus = CollectionStatus | `disabled`\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 query function that always returns QueryBuilder\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 // Can't be disabled if always returns QueryBuilder\n  isLoading: boolean\n  isReady: boolean\n  isIdle: boolean\n  isError: boolean\n  isCleanedUp: boolean\n  isEnabled: true // Always true if always returns QueryBuilder\n}\n\n// Overload 2: Accept query function that can return undefined/null\nexport function useLiveQuery<TContext extends Context>(\n  queryFn: (\n    q: InitialQueryBuilder\n  ) => QueryBuilder<TContext> | undefined | null,\n  deps?: Array<unknown>\n): {\n  state: Map<string | number, GetResult<TContext>> | undefined\n  data: Array<GetResult<TContext>> | undefined\n  collection: Collection<GetResult<TContext>, string | number, {}> | undefined\n  status: UseLiveQueryStatus\n  isLoading: boolean\n  isReady: boolean\n  isIdle: boolean\n  isError: boolean\n  isCleanedUp: boolean\n  isEnabled: boolean\n}\n\n// Overload 3: Accept query function that can return LiveQueryCollectionConfig\nexport function useLiveQuery<TContext extends Context>(\n  queryFn: (\n    q: InitialQueryBuilder\n  ) => LiveQueryCollectionConfig<TContext> | undefined | null,\n  deps?: Array<unknown>\n): {\n  state: Map<string | number, GetResult<TContext>> | undefined\n  data: Array<GetResult<TContext>> | undefined\n  collection: Collection<GetResult<TContext>, string | number, {}> | undefined\n  status: UseLiveQueryStatus\n  isLoading: boolean\n  isReady: boolean\n  isIdle: boolean\n  isError: boolean\n  isCleanedUp: boolean\n  isEnabled: boolean\n}\n\n// Overload 4: Accept query function that can return Collection\nexport function useLiveQuery<\n  TResult extends object,\n  TKey extends string | number,\n  TUtils extends Record<string, any>,\n>(\n  queryFn: (\n    q: InitialQueryBuilder\n  ) => Collection<TResult, TKey, TUtils> | undefined | null,\n  deps?: Array<unknown>\n): {\n  state: Map<TKey, TResult> | undefined\n  data: Array<TResult> | undefined\n  collection: Collection<TResult, TKey, TUtils> | undefined\n  status: UseLiveQueryStatus\n  isLoading: boolean\n  isReady: boolean\n  isIdle: boolean\n  isError: boolean\n  isCleanedUp: boolean\n  isEnabled: boolean\n}\n\n// Overload 5: Accept query function that can return all types\nexport function useLiveQuery<\n  TContext extends Context,\n  TResult extends object,\n  TKey extends string | number,\n  TUtils extends Record<string, any>,\n>(\n  queryFn: (\n    q: InitialQueryBuilder\n  ) =>\n    | QueryBuilder<TContext>\n    | LiveQueryCollectionConfig<TContext>\n    | Collection<TResult, TKey, TUtils>\n    | undefined\n    | null,\n  deps?: Array<unknown>\n): {\n  state:\n    | Map<string | number, GetResult<TContext>>\n    | Map<TKey, TResult>\n    | undefined\n  data: Array<GetResult<TContext>> | Array<TResult> | undefined\n  collection:\n    | Collection<GetResult<TContext>, string | number, {}>\n    | Collection<TResult, TKey, TUtils>\n    | undefined\n  status: UseLiveQueryStatus\n  isLoading: boolean\n  isReady: boolean\n  isIdle: boolean\n  isError: boolean\n  isCleanedUp: boolean\n  isEnabled: 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 6: 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 // Can't be disabled for config objects\n  isLoading: boolean\n  isReady: boolean\n  isIdle: boolean\n  isError: boolean\n  isCleanedUp: boolean\n  isEnabled: true // Always true for config objects\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 7: 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 // Can't be disabled for pre-created live query collections\n  isLoading: boolean\n  isReady: boolean\n  isIdle: boolean\n  isError: boolean\n  isCleanedUp: boolean\n  isEnabled: true // Always true for pre-created live query collections\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  // Use refs to track version and memoized snapshot\n  const versionRef = useRef(0)\n  const snapshotRef = useRef<{\n    collection: Collection<object, string | number, {}> | null\n    version: number\n  } | null>(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      // Handle different callback return types\n      if (typeof configOrQueryOrCollection === `function`) {\n        // Call the function with a query builder to see what it returns\n        const queryBuilder = new BaseQueryBuilder() as InitialQueryBuilder\n        const result = configOrQueryOrCollection(queryBuilder)\n\n        if (result === undefined || result === null) {\n          // Callback returned undefined/null - disabled query\n          collectionRef.current = null\n        } else if (result instanceof CollectionImpl) {\n          // Callback returned a Collection instance - use it directly\n          result.startSyncImmediate()\n          collectionRef.current = result\n        } else if (result instanceof BaseQueryBuilder) {\n          // Callback returned QueryBuilder - create live query collection using the original callback\n          // (not the result, since the result might be from a different query builder instance)\n          collectionRef.current = createLiveQueryCollection({\n            query: configOrQueryOrCollection,\n            startSync: true,\n            gcTime: DEFAULT_GC_TIME_MS,\n          })\n        } else if (result && typeof result === `object`) {\n          // Assume it's a LiveQueryCollectionConfig\n          collectionRef.current = createLiveQueryCollection({\n            startSync: true,\n            gcTime: DEFAULT_GC_TIME_MS,\n            ...result,\n          })\n        } else {\n          // Unexpected return type\n          throw new Error(\n            `useLiveQuery callback must return a QueryBuilder, LiveQueryCollectionConfig, Collection, undefined, or null. Got: ${typeof result}`\n          )\n        }\n        depsRef.current = [...deps]\n      } else {\n        // Original logic for config objects\n        collectionRef.current = createLiveQueryCollection({\n          startSync: true,\n          gcTime: DEFAULT_GC_TIME_MS,\n          ...configOrQueryOrCollection,\n        })\n        depsRef.current = [...deps]\n      }\n    }\n  }\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      // If no collection, return a no-op unsubscribe function\n      if (!collectionRef.current) {\n        return () => {}\n      }\n\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, {}> | null\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, {}> | null\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    // Handle null collection case (when callback returns undefined/null)\n    if (!snapshot.collection) {\n      returnedRef.current = {\n        state: undefined,\n        data: undefined,\n        collection: undefined,\n        status: `disabled`,\n        isLoading: false,\n        isReady: false,\n        isIdle: false,\n        isError: false,\n        isCleanedUp: false,\n        isEnabled: false,\n      }\n    } else {\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        isEnabled: true,\n      }\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","BaseQueryBuilder","CollectionImpl","createLiveQueryCollection","useSyncExternalStore"],"mappings":";;;;AAgBA,MAAM,qBAAqB;AA2QpB,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,aAAaA,MAAAA,OAAO,CAAC;AAC3B,QAAM,cAAcA,MAAAA,OAGV,IAAI;AAGd,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;AAEL,UAAI,OAAO,8BAA8B,YAAY;AAEnD,cAAM,eAAe,IAAIC,oBAAA;AACzB,cAAM,SAAS,0BAA0B,YAAY;AAErD,YAAI,WAAW,UAAa,WAAW,MAAM;AAE3C,wBAAc,UAAU;AAAA,QAC1B,WAAW,kBAAkBC,mBAAgB;AAE3C,iBAAO,mBAAA;AACP,wBAAc,UAAU;AAAA,QAC1B,WAAW,kBAAkBD,qBAAkB;AAG7C,wBAAc,UAAUE,6BAA0B;AAAA,YAChD,OAAO;AAAA,YACP,WAAW;AAAA,YACX,QAAQ;AAAA,UAAA,CACT;AAAA,QACH,WAAW,UAAU,OAAO,WAAW,UAAU;AAE/C,wBAAc,UAAUA,6BAA0B;AAAA,YAChD,WAAW;AAAA,YACX,QAAQ;AAAA,YACR,GAAG;AAAA,UAAA,CACJ;AAAA,QACH,OAAO;AAEL,gBAAM,IAAI;AAAA,YACR,qHAAqH,OAAO,MAAM;AAAA,UAAA;AAAA,QAEtI;AACA,gBAAQ,UAAU,CAAC,GAAG,IAAI;AAAA,MAC5B,OAAO;AAEL,sBAAc,UAAUA,6BAA0B;AAAA,UAChD,WAAW;AAAA,UACX,QAAQ;AAAA,UACR,GAAG;AAAA,QAAA,CACJ;AACD,gBAAQ,UAAU,CAAC,GAAG,IAAI;AAAA,MAC5B;AAAA,IACF;AAAA,EACF;AAGA,MAAI,oBAAoB;AACtB,eAAW,UAAU;AACrB,gBAAY,UAAU;AAAA,EACxB;AAGA,QAAM,eAAeH,MAAAA,OAEnB,IAAI;AACN,MAAI,CAAC,aAAa,WAAW,oBAAoB;AAC/C,iBAAa,UAAU,CAAC,kBAA8B;AAEpD,UAAI,CAAC,cAAc,SAAS;AAC1B,eAAO,MAAM;AAAA,QAAC;AAAA,MAChB;AAEA,YAAM,cAAc,cAAc,QAAQ,iBAAiB,MAAM;AAE/D,mBAAW,WAAW;AACtB,sBAAA;AAAA,MACF,CAAC;AAED,UAAI,cAAc,QAAQ,WAAW,SAAS;AAC5C,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,WAAWI,MAAAA;AAAAA,IACf,aAAa;AAAA,IACb,eAAe;AAAA,EAAA;AAIjB,QAAM,sBAAsBJ,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,QAAI,CAAC,SAAS,YAAY;AACxB,kBAAY,UAAU;AAAA,QACpB,OAAO;AAAA,QACP,MAAM;AAAA,QACN,YAAY;AAAA,QACZ,QAAQ;AAAA,QACR,WAAW;AAAA,QACX,SAAS;AAAA,QACT,QAAQ;AAAA,QACR,SAAS;AAAA,QACT,aAAa;AAAA,QACb,WAAW;AAAA,MAAA;AAAA,IAEf,OAAO;AAEL,YAAM,UAAU,MAAM,KAAK,SAAS,WAAW,SAAS;AACxD,UAAI,aAAmD;AACvD,UAAI,YAAmC;AAEvC,kBAAY,UAAU;AAAA,QACpB,IAAI,QAAQ;AACV,cAAI,CAAC,YAAY;AACf,yBAAa,IAAI,IAAI,OAAO;AAAA,UAC9B;AACA,iBAAO;AAAA,QACT;AAAA,QACA,IAAI,OAAO;AACT,cAAI,CAAC,WAAW;AACd,wBAAY,QAAQ,IAAI,CAAC,CAAA,EAAG,KAAK,MAAM,KAAK;AAAA,UAC9C;AACA,iBAAO;AAAA,QACT;AAAA,QACA,YAAY,SAAS;AAAA,QACrB,QAAQ,SAAS,WAAW;AAAA,QAC5B,WACE,SAAS,WAAW,WAAW,aAC/B,SAAS,WAAW,WAAW;AAAA,QACjC,SAAS,SAAS,WAAW,WAAW;AAAA,QACxC,QAAQ,SAAS,WAAW,WAAW;AAAA,QACvC,SAAS,SAAS,WAAW,WAAW;AAAA,QACxC,aAAa,SAAS,WAAW,WAAW;AAAA,QAC5C,WAAW;AAAA,MAAA;AAAA,IAEf;AAGA,wBAAoB,UAAU;AAAA,EAChC;AAEA,SAAO,YAAY;AACrB;;"}

package/dist/cjs/useLiveQuery.d.cts

@@ -1,4 +1,5 @@
 import { Collection, CollectionStatus, Context, GetResult, InitialQueryBuilder, LiveQueryCollectionConfig, QueryBuilder } from '@tanstack/db';
+export type UseLiveQueryStatus = CollectionStatus | `disabled`;
 /**
  * Create a live query using a query function
  * @param queryFn - Query function that defines what data to fetch
@@ -59,6 +60,55 @@ export declare function useLiveQuery<TContext extends Context>(queryFn: (q: Init
     isIdle: boolean;
     isError: boolean;
     isCleanedUp: boolean;
+    isEnabled: true;
+};
+export declare function useLiveQuery<TContext extends Context>(queryFn: (q: InitialQueryBuilder) => QueryBuilder<TContext> | undefined | null, deps?: Array<unknown>): {
+    state: Map<string | number, GetResult<TContext>> | undefined;
+    data: Array<GetResult<TContext>> | undefined;
+    collection: Collection<GetResult<TContext>, string | number, {}> | undefined;
+    status: UseLiveQueryStatus;
+    isLoading: boolean;
+    isReady: boolean;
+    isIdle: boolean;
+    isError: boolean;
+    isCleanedUp: boolean;
+    isEnabled: boolean;
+};
+export declare function useLiveQuery<TContext extends Context>(queryFn: (q: InitialQueryBuilder) => LiveQueryCollectionConfig<TContext> | undefined | null, deps?: Array<unknown>): {
+    state: Map<string | number, GetResult<TContext>> | undefined;
+    data: Array<GetResult<TContext>> | undefined;
+    collection: Collection<GetResult<TContext>, string | number, {}> | undefined;
+    status: UseLiveQueryStatus;
+    isLoading: boolean;
+    isReady: boolean;
+    isIdle: boolean;
+    isError: boolean;
+    isCleanedUp: boolean;
+    isEnabled: boolean;
+};
+export declare function useLiveQuery<TResult extends object, TKey extends string | number, TUtils extends Record<string, any>>(queryFn: (q: InitialQueryBuilder) => Collection<TResult, TKey, TUtils> | undefined | null, deps?: Array<unknown>): {
+    state: Map<TKey, TResult> | undefined;
+    data: Array<TResult> | undefined;
+    collection: Collection<TResult, TKey, TUtils> | undefined;
+    status: UseLiveQueryStatus;
+    isLoading: boolean;
+    isReady: boolean;
+    isIdle: boolean;
+    isError: boolean;
+    isCleanedUp: boolean;
+    isEnabled: boolean;
+};
+export declare function useLiveQuery<TContext extends Context, TResult extends object, TKey extends string | number, TUtils extends Record<string, any>>(queryFn: (q: InitialQueryBuilder) => QueryBuilder<TContext> | LiveQueryCollectionConfig<TContext> | Collection<TResult, TKey, TUtils> | undefined | null, deps?: Array<unknown>): {
+    state: Map<string | number, GetResult<TContext>> | Map<TKey, TResult> | undefined;
+    data: Array<GetResult<TContext>> | Array<TResult> | undefined;
+    collection: Collection<GetResult<TContext>, string | number, {}> | Collection<TResult, TKey, TUtils> | undefined;
+    status: UseLiveQueryStatus;
+    isLoading: boolean;
+    isReady: boolean;
+    isIdle: boolean;
+    isError: boolean;
+    isCleanedUp: boolean;
+    isEnabled: boolean;
 };
 /**
  * Create a live query using configuration object
@@ -103,6 +153,7 @@ export declare function useLiveQuery<TContext extends Context>(config: LiveQuery
     isIdle: boolean;
     isError: boolean;
     isCleanedUp: boolean;
+    isEnabled: true;
 };
 /**
  * Subscribe to an existing live query collection
@@ -143,4 +194,5 @@ export declare function useLiveQuery<TResult extends object, TKey extends string
     isIdle: boolean;
     isError: boolean;
     isCleanedUp: boolean;
+    isEnabled: true;
 };

package/dist/esm/useLiveQuery.d.ts

@@ -1,4 +1,5 @@
 import { Collection, CollectionStatus, Context, GetResult, InitialQueryBuilder, LiveQueryCollectionConfig, QueryBuilder } from '@tanstack/db';
+export type UseLiveQueryStatus = CollectionStatus | `disabled`;
 /**
  * Create a live query using a query function
  * @param queryFn - Query function that defines what data to fetch
@@ -59,6 +60,55 @@ export declare function useLiveQuery<TContext extends Context>(queryFn: (q: Init
     isIdle: boolean;
     isError: boolean;
     isCleanedUp: boolean;
+    isEnabled: true;
+};
+export declare function useLiveQuery<TContext extends Context>(queryFn: (q: InitialQueryBuilder) => QueryBuilder<TContext> | undefined | null, deps?: Array<unknown>): {
+    state: Map<string | number, GetResult<TContext>> | undefined;
+    data: Array<GetResult<TContext>> | undefined;
+    collection: Collection<GetResult<TContext>, string | number, {}> | undefined;
+    status: UseLiveQueryStatus;
+    isLoading: boolean;
+    isReady: boolean;
+    isIdle: boolean;
+    isError: boolean;
+    isCleanedUp: boolean;
+    isEnabled: boolean;
+};
+export declare function useLiveQuery<TContext extends Context>(queryFn: (q: InitialQueryBuilder) => LiveQueryCollectionConfig<TContext> | undefined | null, deps?: Array<unknown>): {
+    state: Map<string | number, GetResult<TContext>> | undefined;
+    data: Array<GetResult<TContext>> | undefined;
+    collection: Collection<GetResult<TContext>, string | number, {}> | undefined;
+    status: UseLiveQueryStatus;
+    isLoading: boolean;
+    isReady: boolean;
+    isIdle: boolean;
+    isError: boolean;
+    isCleanedUp: boolean;
+    isEnabled: boolean;
+};
+export declare function useLiveQuery<TResult extends object, TKey extends string | number, TUtils extends Record<string, any>>(queryFn: (q: InitialQueryBuilder) => Collection<TResult, TKey, TUtils> | undefined | null, deps?: Array<unknown>): {
+    state: Map<TKey, TResult> | undefined;
+    data: Array<TResult> | undefined;
+    collection: Collection<TResult, TKey, TUtils> | undefined;
+    status: UseLiveQueryStatus;
+    isLoading: boolean;
+    isReady: boolean;
+    isIdle: boolean;
+    isError: boolean;
+    isCleanedUp: boolean;
+    isEnabled: boolean;
+};
+export declare function useLiveQuery<TContext extends Context, TResult extends object, TKey extends string | number, TUtils extends Record<string, any>>(queryFn: (q: InitialQueryBuilder) => QueryBuilder<TContext> | LiveQueryCollectionConfig<TContext> | Collection<TResult, TKey, TUtils> | undefined | null, deps?: Array<unknown>): {
+    state: Map<string | number, GetResult<TContext>> | Map<TKey, TResult> | undefined;
+    data: Array<GetResult<TContext>> | Array<TResult> | undefined;
+    collection: Collection<GetResult<TContext>, string | number, {}> | Collection<TResult, TKey, TUtils> | undefined;
+    status: UseLiveQueryStatus;
+    isLoading: boolean;
+    isReady: boolean;
+    isIdle: boolean;
+    isError: boolean;
+    isCleanedUp: boolean;
+    isEnabled: boolean;
 };
 /**
  * Create a live query using configuration object
@@ -103,6 +153,7 @@ export declare function useLiveQuery<TContext extends Context>(config: LiveQuery
     isIdle: boolean;
     isError: boolean;
     isCleanedUp: boolean;
+    isEnabled: true;
 };
 /**
  * Subscribe to an existing live query collection
@@ -143,4 +194,5 @@ export declare function useLiveQuery<TResult extends object, TKey extends string
     isIdle: boolean;
     isError: boolean;
     isCleanedUp: boolean;
+    isEnabled: true;
 };

package/dist/esm/useLiveQuery.js

@@ -1,5 +1,6 @@
 import { useRef, useSyncExternalStore } from "react";
-import { createLiveQueryCollection } from "@tanstack/db";
+import { BaseQueryBuilder, CollectionImpl, createLiveQueryCollection } from "@tanstack/db";
+const DEFAULT_GC_TIME_MS = 1;
 function useLiveQuery(configOrQueryOrCollection, deps = []) {
   const isCollection = configOrQueryOrCollection && typeof configOrQueryOrCollection === `object` && typeof configOrQueryOrCollection.subscribeChanges === `function` && typeof configOrQueryOrCollection.startSyncImmediate === `function` && typeof configOrQueryOrCollection.id === `string`;
   const collectionRef = useRef(
@@ -7,6 +8,8 @@ function useLiveQuery(configOrQueryOrCollection, deps = []) {
   );
   const depsRef = useRef(null);
   const configRef = useRef(null);
+  const versionRef = useRef(0);
+  const snapshotRef = useRef(null);
   const needsNewCollection = !collectionRef.current || isCollection && configRef.current !== configOrQueryOrCollection || !isCollection && (depsRef.current === null || depsRef.current.length !== deps.length || depsRef.current.some((dep, i) => dep !== deps[i]));
   if (needsNewCollection) {
     if (isCollection) {
@@ -15,25 +18,41 @@ function useLiveQuery(configOrQueryOrCollection, deps = []) {
       configRef.current = configOrQueryOrCollection;
     } else {
       if (typeof configOrQueryOrCollection === `function`) {
-        collectionRef.current = createLiveQueryCollection({
-          query: configOrQueryOrCollection,
-          startSync: true,
-          gcTime: 0
-          // Live queries created by useLiveQuery are cleaned up immediately
-        });
+        const queryBuilder = new BaseQueryBuilder();
+        const result = configOrQueryOrCollection(queryBuilder);
+        if (result === void 0 || result === null) {
+          collectionRef.current = null;
+        } else if (result instanceof CollectionImpl) {
+          result.startSyncImmediate();
+          collectionRef.current = result;
+        } else if (result instanceof BaseQueryBuilder) {
+          collectionRef.current = createLiveQueryCollection({
+            query: configOrQueryOrCollection,
+            startSync: true,
+            gcTime: DEFAULT_GC_TIME_MS
+          });
+        } else if (result && typeof result === `object`) {
+          collectionRef.current = createLiveQueryCollection({
+            startSync: true,
+            gcTime: DEFAULT_GC_TIME_MS,
+            ...result
+          });
+        } else {
+          throw new Error(
+            `useLiveQuery callback must return a QueryBuilder, LiveQueryCollectionConfig, Collection, undefined, or null. Got: ${typeof result}`
+          );
+        }
+        depsRef.current = [...deps];
       } else {
         collectionRef.current = createLiveQueryCollection({
           startSync: true,
-          gcTime: 0,
-          // Live queries created by useLiveQuery are cleaned up immediately
+          gcTime: DEFAULT_GC_TIME_MS,
           ...configOrQueryOrCollection
         });
+        depsRef.current = [...deps];
       }
-      depsRef.current = [...deps];
     }
   }
-  const versionRef = useRef(0);
-  const snapshotRef = useRef(null);
   if (needsNewCollection) {
     versionRef.current = 0;
     snapshotRef.current = null;
@@ -41,6 +60,10 @@ function useLiveQuery(configOrQueryOrCollection, deps = []) {
   const subscribeRef = useRef(null);
   if (!subscribeRef.current || needsNewCollection) {
     subscribeRef.current = (onStoreChange) => {
+      if (!collectionRef.current) {
+        return () => {
+        };
+      }
       const unsubscribe = collectionRef.current.subscribeChanges(() => {
         versionRef.current += 1;
         onStoreChange();
@@ -75,30 +98,46 @@ function useLiveQuery(configOrQueryOrCollection, deps = []) {
   const returnedSnapshotRef = useRef(null);
   const returnedRef = useRef(null);
   if (!returnedSnapshotRef.current || returnedSnapshotRef.current.version !== snapshot.version || returnedSnapshotRef.current.collection !== snapshot.collection) {
-    const entries = Array.from(snapshot.collection.entries());
-    let stateCache = null;
-    let dataCache = null;
-    returnedRef.current = {
-      get state() {
-        if (!stateCache) {
-          stateCache = new Map(entries);
-        }
-        return stateCache;
-      },
-      get data() {
-        if (!dataCache) {
-          dataCache = entries.map(([, value]) => value);
-        }
-        return dataCache;
-      },
-      collection: snapshot.collection,
-      status: snapshot.collection.status,
-      isLoading: snapshot.collection.status === `loading` || snapshot.collection.status === `initialCommit`,
-      isReady: snapshot.collection.status === `ready`,
-      isIdle: snapshot.collection.status === `idle`,
-      isError: snapshot.collection.status === `error`,
-      isCleanedUp: snapshot.collection.status === `cleaned-up`
-    };
+    if (!snapshot.collection) {
+      returnedRef.current = {
+        state: void 0,
+        data: void 0,
+        collection: void 0,
+        status: `disabled`,
+        isLoading: false,
+        isReady: false,
+        isIdle: false,
+        isError: false,
+        isCleanedUp: false,
+        isEnabled: false
+      };
+    } else {
+      const entries = Array.from(snapshot.collection.entries());
+      let stateCache = null;
+      let dataCache = null;
+      returnedRef.current = {
+        get state() {
+          if (!stateCache) {
+            stateCache = new Map(entries);
+          }
+          return stateCache;
+        },
+        get data() {
+          if (!dataCache) {
+            dataCache = entries.map(([, value]) => value);
+          }
+          return dataCache;
+        },
+        collection: snapshot.collection,
+        status: snapshot.collection.status,
+        isLoading: snapshot.collection.status === `loading` || snapshot.collection.status === `initialCommit`,
+        isReady: snapshot.collection.status === `ready`,
+        isIdle: snapshot.collection.status === `idle`,
+        isError: snapshot.collection.status === `error`,
+        isCleanedUp: snapshot.collection.status === `cleaned-up`,
+        isEnabled: true
+      };
+    }
     returnedSnapshotRef.current = snapshot;
   }
   return returnedRef.current;

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      // 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":"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"}
+{"version":3,"file":"useLiveQuery.js","sources":["../../src/useLiveQuery.ts"],"sourcesContent":["import { useRef, useSyncExternalStore } from \"react\"\nimport {\n  BaseQueryBuilder,\n  CollectionImpl,\n  createLiveQueryCollection,\n} from \"@tanstack/db\"\nimport type {\n  Collection,\n  CollectionStatus,\n  Context,\n  GetResult,\n  InitialQueryBuilder,\n  LiveQueryCollectionConfig,\n  QueryBuilder,\n} from \"@tanstack/db\"\n\nconst DEFAULT_GC_TIME_MS = 1 // Live queries created by useLiveQuery are cleaned up immediately (0 disables GC)\n\nexport type UseLiveQueryStatus = CollectionStatus | `disabled`\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 query function that always returns QueryBuilder\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 // Can't be disabled if always returns QueryBuilder\n  isLoading: boolean\n  isReady: boolean\n  isIdle: boolean\n  isError: boolean\n  isCleanedUp: boolean\n  isEnabled: true // Always true if always returns QueryBuilder\n}\n\n// Overload 2: Accept query function that can return undefined/null\nexport function useLiveQuery<TContext extends Context>(\n  queryFn: (\n    q: InitialQueryBuilder\n  ) => QueryBuilder<TContext> | undefined | null,\n  deps?: Array<unknown>\n): {\n  state: Map<string | number, GetResult<TContext>> | undefined\n  data: Array<GetResult<TContext>> | undefined\n  collection: Collection<GetResult<TContext>, string | number, {}> | undefined\n  status: UseLiveQueryStatus\n  isLoading: boolean\n  isReady: boolean\n  isIdle: boolean\n  isError: boolean\n  isCleanedUp: boolean\n  isEnabled: boolean\n}\n\n// Overload 3: Accept query function that can return LiveQueryCollectionConfig\nexport function useLiveQuery<TContext extends Context>(\n  queryFn: (\n    q: InitialQueryBuilder\n  ) => LiveQueryCollectionConfig<TContext> | undefined | null,\n  deps?: Array<unknown>\n): {\n  state: Map<string | number, GetResult<TContext>> | undefined\n  data: Array<GetResult<TContext>> | undefined\n  collection: Collection<GetResult<TContext>, string | number, {}> | undefined\n  status: UseLiveQueryStatus\n  isLoading: boolean\n  isReady: boolean\n  isIdle: boolean\n  isError: boolean\n  isCleanedUp: boolean\n  isEnabled: boolean\n}\n\n// Overload 4: Accept query function that can return Collection\nexport function useLiveQuery<\n  TResult extends object,\n  TKey extends string | number,\n  TUtils extends Record<string, any>,\n>(\n  queryFn: (\n    q: InitialQueryBuilder\n  ) => Collection<TResult, TKey, TUtils> | undefined | null,\n  deps?: Array<unknown>\n): {\n  state: Map<TKey, TResult> | undefined\n  data: Array<TResult> | undefined\n  collection: Collection<TResult, TKey, TUtils> | undefined\n  status: UseLiveQueryStatus\n  isLoading: boolean\n  isReady: boolean\n  isIdle: boolean\n  isError: boolean\n  isCleanedUp: boolean\n  isEnabled: boolean\n}\n\n// Overload 5: Accept query function that can return all types\nexport function useLiveQuery<\n  TContext extends Context,\n  TResult extends object,\n  TKey extends string | number,\n  TUtils extends Record<string, any>,\n>(\n  queryFn: (\n    q: InitialQueryBuilder\n  ) =>\n    | QueryBuilder<TContext>\n    | LiveQueryCollectionConfig<TContext>\n    | Collection<TResult, TKey, TUtils>\n    | undefined\n    | null,\n  deps?: Array<unknown>\n): {\n  state:\n    | Map<string | number, GetResult<TContext>>\n    | Map<TKey, TResult>\n    | undefined\n  data: Array<GetResult<TContext>> | Array<TResult> | undefined\n  collection:\n    | Collection<GetResult<TContext>, string | number, {}>\n    | Collection<TResult, TKey, TUtils>\n    | undefined\n  status: UseLiveQueryStatus\n  isLoading: boolean\n  isReady: boolean\n  isIdle: boolean\n  isError: boolean\n  isCleanedUp: boolean\n  isEnabled: 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 6: 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 // Can't be disabled for config objects\n  isLoading: boolean\n  isReady: boolean\n  isIdle: boolean\n  isError: boolean\n  isCleanedUp: boolean\n  isEnabled: true // Always true for config objects\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 7: 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 // Can't be disabled for pre-created live query collections\n  isLoading: boolean\n  isReady: boolean\n  isIdle: boolean\n  isError: boolean\n  isCleanedUp: boolean\n  isEnabled: true // Always true for pre-created live query collections\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  // Use refs to track version and memoized snapshot\n  const versionRef = useRef(0)\n  const snapshotRef = useRef<{\n    collection: Collection<object, string | number, {}> | null\n    version: number\n  } | null>(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      // Handle different callback return types\n      if (typeof configOrQueryOrCollection === `function`) {\n        // Call the function with a query builder to see what it returns\n        const queryBuilder = new BaseQueryBuilder() as InitialQueryBuilder\n        const result = configOrQueryOrCollection(queryBuilder)\n\n        if (result === undefined || result === null) {\n          // Callback returned undefined/null - disabled query\n          collectionRef.current = null\n        } else if (result instanceof CollectionImpl) {\n          // Callback returned a Collection instance - use it directly\n          result.startSyncImmediate()\n          collectionRef.current = result\n        } else if (result instanceof BaseQueryBuilder) {\n          // Callback returned QueryBuilder - create live query collection using the original callback\n          // (not the result, since the result might be from a different query builder instance)\n          collectionRef.current = createLiveQueryCollection({\n            query: configOrQueryOrCollection,\n            startSync: true,\n            gcTime: DEFAULT_GC_TIME_MS,\n          })\n        } else if (result && typeof result === `object`) {\n          // Assume it's a LiveQueryCollectionConfig\n          collectionRef.current = createLiveQueryCollection({\n            startSync: true,\n            gcTime: DEFAULT_GC_TIME_MS,\n            ...result,\n          })\n        } else {\n          // Unexpected return type\n          throw new Error(\n            `useLiveQuery callback must return a QueryBuilder, LiveQueryCollectionConfig, Collection, undefined, or null. Got: ${typeof result}`\n          )\n        }\n        depsRef.current = [...deps]\n      } else {\n        // Original logic for config objects\n        collectionRef.current = createLiveQueryCollection({\n          startSync: true,\n          gcTime: DEFAULT_GC_TIME_MS,\n          ...configOrQueryOrCollection,\n        })\n        depsRef.current = [...deps]\n      }\n    }\n  }\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      // If no collection, return a no-op unsubscribe function\n      if (!collectionRef.current) {\n        return () => {}\n      }\n\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, {}> | null\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, {}> | null\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    // Handle null collection case (when callback returns undefined/null)\n    if (!snapshot.collection) {\n      returnedRef.current = {\n        state: undefined,\n        data: undefined,\n        collection: undefined,\n        status: `disabled`,\n        isLoading: false,\n        isReady: false,\n        isIdle: false,\n        isError: false,\n        isCleanedUp: false,\n        isEnabled: false,\n      }\n    } else {\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        isEnabled: true,\n      }\n    }\n\n    // Remember the snapshot that produced this returned value\n    returnedSnapshotRef.current = snapshot\n  }\n\n  return returnedRef.current!\n}\n"],"names":[],"mappings":"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"}

package/package.json

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

package/src/useLiveQuery.ts

@@ -1,5 +1,9 @@
 import { useRef, useSyncExternalStore } from "react"
-import { createLiveQueryCollection } from "@tanstack/db"
+import {
+  BaseQueryBuilder,
+  CollectionImpl,
+  createLiveQueryCollection,
+} from "@tanstack/db"
 import type {
   Collection,
   CollectionStatus,
@@ -10,6 +14,10 @@ import type {
   QueryBuilder,
 } from "@tanstack/db"
 
+const DEFAULT_GC_TIME_MS = 1 // Live queries created by useLiveQuery are cleaned up immediately (0 disables GC)
+
+export type UseLiveQueryStatus = CollectionStatus | `disabled`
+
 /**
  * Create a live query using a query function
  * @param queryFn - Query function that defines what data to fetch
@@ -60,7 +68,7 @@ import type {
  *   </ul>
  * )
  */
-// Overload 1: Accept just the query function
+// Overload 1: Accept query function that always returns QueryBuilder
 export function useLiveQuery<TContext extends Context>(
   queryFn: (q: InitialQueryBuilder) => QueryBuilder<TContext>,
   deps?: Array<unknown>
@@ -68,12 +76,109 @@ export function useLiveQuery<TContext extends Context>(
   state: Map<string | number, GetResult<TContext>>
   data: Array<GetResult<TContext>>
   collection: Collection<GetResult<TContext>, string | number, {}>
-  status: CollectionStatus
+  status: CollectionStatus // Can't be disabled if always returns QueryBuilder
+  isLoading: boolean
+  isReady: boolean
+  isIdle: boolean
+  isError: boolean
+  isCleanedUp: boolean
+  isEnabled: true // Always true if always returns QueryBuilder
+}
+
+// Overload 2: Accept query function that can return undefined/null
+export function useLiveQuery<TContext extends Context>(
+  queryFn: (
+    q: InitialQueryBuilder
+  ) => QueryBuilder<TContext> | undefined | null,
+  deps?: Array<unknown>
+): {
+  state: Map<string | number, GetResult<TContext>> | undefined
+  data: Array<GetResult<TContext>> | undefined
+  collection: Collection<GetResult<TContext>, string | number, {}> | undefined
+  status: UseLiveQueryStatus
+  isLoading: boolean
+  isReady: boolean
+  isIdle: boolean
+  isError: boolean
+  isCleanedUp: boolean
+  isEnabled: boolean
+}
+
+// Overload 3: Accept query function that can return LiveQueryCollectionConfig
+export function useLiveQuery<TContext extends Context>(
+  queryFn: (
+    q: InitialQueryBuilder
+  ) => LiveQueryCollectionConfig<TContext> | undefined | null,
+  deps?: Array<unknown>
+): {
+  state: Map<string | number, GetResult<TContext>> | undefined
+  data: Array<GetResult<TContext>> | undefined
+  collection: Collection<GetResult<TContext>, string | number, {}> | undefined
+  status: UseLiveQueryStatus
+  isLoading: boolean
+  isReady: boolean
+  isIdle: boolean
+  isError: boolean
+  isCleanedUp: boolean
+  isEnabled: boolean
+}
+
+// Overload 4: Accept query function that can return Collection
+export function useLiveQuery<
+  TResult extends object,
+  TKey extends string | number,
+  TUtils extends Record<string, any>,
+>(
+  queryFn: (
+    q: InitialQueryBuilder
+  ) => Collection<TResult, TKey, TUtils> | undefined | null,
+  deps?: Array<unknown>
+): {
+  state: Map<TKey, TResult> | undefined
+  data: Array<TResult> | undefined
+  collection: Collection<TResult, TKey, TUtils> | undefined
+  status: UseLiveQueryStatus
   isLoading: boolean
   isReady: boolean
   isIdle: boolean
   isError: boolean
   isCleanedUp: boolean
+  isEnabled: boolean
+}
+
+// Overload 5: Accept query function that can return all types
+export function useLiveQuery<
+  TContext extends Context,
+  TResult extends object,
+  TKey extends string | number,
+  TUtils extends Record<string, any>,
+>(
+  queryFn: (
+    q: InitialQueryBuilder
+  ) =>
+    | QueryBuilder<TContext>
+    | LiveQueryCollectionConfig<TContext>
+    | Collection<TResult, TKey, TUtils>
+    | undefined
+    | null,
+  deps?: Array<unknown>
+): {
+  state:
+    | Map<string | number, GetResult<TContext>>
+    | Map<TKey, TResult>
+    | undefined
+  data: Array<GetResult<TContext>> | Array<TResult> | undefined
+  collection:
+    | Collection<GetResult<TContext>, string | number, {}>
+    | Collection<TResult, TKey, TUtils>
+    | undefined
+  status: UseLiveQueryStatus
+  isLoading: boolean
+  isReady: boolean
+  isIdle: boolean
+  isError: boolean
+  isCleanedUp: boolean
+  isEnabled: boolean
 }
 
 /**
@@ -109,7 +214,7 @@ export function useLiveQuery<TContext extends Context>(
  *
  * return <div>{data.length} items loaded</div>
  */
-// Overload 2: Accept config object
+// Overload 6: Accept config object
 export function useLiveQuery<TContext extends Context>(
   config: LiveQueryCollectionConfig<TContext>,
   deps?: Array<unknown>
@@ -117,12 +222,13 @@ export function useLiveQuery<TContext extends Context>(
   state: Map<string | number, GetResult<TContext>>
   data: Array<GetResult<TContext>>
   collection: Collection<GetResult<TContext>, string | number, {}>
-  status: CollectionStatus
+  status: CollectionStatus // Can't be disabled for config objects
   isLoading: boolean
   isReady: boolean
   isIdle: boolean
   isError: boolean
   isCleanedUp: boolean
+  isEnabled: true // Always true for config objects
 }
 
 /**
@@ -154,7 +260,7 @@ export function useLiveQuery<TContext extends Context>(
  *
  * return <div>{data.map(item => <Item key={item.id} {...item} />)}</div>
  */
-// Overload 3: Accept pre-created live query collection
+// Overload 7: Accept pre-created live query collection
 export function useLiveQuery<
   TResult extends object,
   TKey extends string | number,
@@ -165,12 +271,13 @@ export function useLiveQuery<
   state: Map<TKey, TResult>
   data: Array<TResult>
   collection: Collection<TResult, TKey, TUtils>
-  status: CollectionStatus
+  status: CollectionStatus // Can't be disabled for pre-created live query collections
   isLoading: boolean
   isReady: boolean
   isIdle: boolean
   isError: boolean
   isCleanedUp: boolean
+  isEnabled: true // Always true for pre-created live query collections
 }
 
 // Implementation - use function overloads to infer the actual collection type
@@ -193,6 +300,13 @@ export function useLiveQuery(
   const depsRef = useRef<Array<unknown> | null>(null)
   const configRef = useRef<unknown>(null)
 
+  // Use refs to track version and memoized snapshot
+  const versionRef = useRef(0)
+  const snapshotRef = useRef<{
+    collection: Collection<object, string | number, {}> | null
+    version: number
+  } | null>(null)
+
   // Check if we need to create/recreate the collection
   const needsNewCollection =
     !collectionRef.current ||
@@ -209,32 +323,53 @@ export function useLiveQuery(
       collectionRef.current = configOrQueryOrCollection
       configRef.current = configOrQueryOrCollection
     } else {
-      // Original logic for creating collections
-      // Ensure we always start sync for React hooks
+      // Handle different callback return types
       if (typeof configOrQueryOrCollection === `function`) {
-        collectionRef.current = createLiveQueryCollection({
-          query: configOrQueryOrCollection,
-          startSync: true,
-          gcTime: 0, // Live queries created by useLiveQuery are cleaned up immediately
-        }) as unknown as Collection<object, string | number, {}>
+        // Call the function with a query builder to see what it returns
+        const queryBuilder = new BaseQueryBuilder() as InitialQueryBuilder
+        const result = configOrQueryOrCollection(queryBuilder)
+
+        if (result === undefined || result === null) {
+          // Callback returned undefined/null - disabled query
+          collectionRef.current = null
+        } else if (result instanceof CollectionImpl) {
+          // Callback returned a Collection instance - use it directly
+          result.startSyncImmediate()
+          collectionRef.current = result
+        } else if (result instanceof BaseQueryBuilder) {
+          // Callback returned QueryBuilder - create live query collection using the original callback
+          // (not the result, since the result might be from a different query builder instance)
+          collectionRef.current = createLiveQueryCollection({
+            query: configOrQueryOrCollection,
+            startSync: true,
+            gcTime: DEFAULT_GC_TIME_MS,
+          })
+        } else if (result && typeof result === `object`) {
+          // Assume it's a LiveQueryCollectionConfig
+          collectionRef.current = createLiveQueryCollection({
+            startSync: true,
+            gcTime: DEFAULT_GC_TIME_MS,
+            ...result,
+          })
+        } else {
+          // Unexpected return type
+          throw new Error(
+            `useLiveQuery callback must return a QueryBuilder, LiveQueryCollectionConfig, Collection, undefined, or null. Got: ${typeof result}`
+          )
+        }
+        depsRef.current = [...deps]
       } else {
+        // Original logic for config objects
         collectionRef.current = createLiveQueryCollection({
           startSync: true,
-          gcTime: 0, // Live queries created by useLiveQuery are cleaned up immediately
+          gcTime: DEFAULT_GC_TIME_MS,
           ...configOrQueryOrCollection,
-        }) as unknown as Collection<object, string | number, {}>
+        })
+        depsRef.current = [...deps]
       }
-      depsRef.current = [...deps]
     }
   }
 
-  // Use refs to track version and memoized snapshot
-  const versionRef = useRef(0)
-  const snapshotRef = useRef<{
-    collection: Collection<object, string | number, {}>
-    version: number
-  } | null>(null)
-
   // Reset refs when collection changes
   if (needsNewCollection) {
     versionRef.current = 0
@@ -247,13 +382,18 @@ export function useLiveQuery(
   >(null)
   if (!subscribeRef.current || needsNewCollection) {
     subscribeRef.current = (onStoreChange: () => void) => {
-      const unsubscribe = collectionRef.current!.subscribeChanges(() => {
+      // If no collection, return a no-op unsubscribe function
+      if (!collectionRef.current) {
+        return () => {}
+      }
+
+      const unsubscribe = collectionRef.current.subscribeChanges(() => {
         // Bump version on any change; getSnapshot will rebuild next time
         versionRef.current += 1
         onStoreChange()
       })
       // Collection may be ready and will not receive initial `subscribeChanges()`
-      if (collectionRef.current!.status === `ready`) {
+      if (collectionRef.current.status === `ready`) {
         versionRef.current += 1
         onStoreChange()
       }
@@ -266,7 +406,7 @@ export function useLiveQuery(
   // Create stable getSnapshot function using ref
   const getSnapshotRef = useRef<
     | (() => {
-        collection: Collection<object, string | number, {}>
+        collection: Collection<object, string | number, {}> | null
         version: number
       })
     | null
@@ -274,7 +414,7 @@ export function useLiveQuery(
   if (!getSnapshotRef.current || needsNewCollection) {
     getSnapshotRef.current = () => {
       const currentVersion = versionRef.current
-      const currentCollection = collectionRef.current!
+      const currentCollection = collectionRef.current
 
       // Recreate snapshot object only if version/collection changed
       if (
@@ -300,7 +440,7 @@ export function useLiveQuery(
 
   // Track last snapshot (from useSyncExternalStore) and the returned value separately
   const returnedSnapshotRef = useRef<{
-    collection: Collection<object, string | number, {}>
+    collection: Collection<object, string | number, {}> | null
     version: number
   } | null>(null)
   // Keep implementation return loose to satisfy overload signatures
@@ -312,33 +452,50 @@ export function useLiveQuery(
     returnedSnapshotRef.current.version !== snapshot.version ||
     returnedSnapshotRef.current.collection !== snapshot.collection
   ) {
-    // Capture a stable view of entries for this snapshot to avoid tearing
-    const entries = Array.from(snapshot.collection.entries())
-    let stateCache: Map<string | number, unknown> | null = null
-    let dataCache: Array<unknown> | null = null
+    // Handle null collection case (when callback returns undefined/null)
+    if (!snapshot.collection) {
+      returnedRef.current = {
+        state: undefined,
+        data: undefined,
+        collection: undefined,
+        status: `disabled`,
+        isLoading: false,
+        isReady: false,
+        isIdle: false,
+        isError: false,
+        isCleanedUp: false,
+        isEnabled: false,
+      }
+    } else {
+      // Capture a stable view of entries for this snapshot to avoid tearing
+      const entries = Array.from(snapshot.collection.entries())
+      let stateCache: Map<string | number, unknown> | null = null
+      let dataCache: Array<unknown> | null = null
 
-    returnedRef.current = {
-      get state() {
-        if (!stateCache) {
-          stateCache = new Map(entries)
-        }
-        return stateCache
-      },
-      get data() {
-        if (!dataCache) {
-          dataCache = entries.map(([, value]) => value)
-        }
-        return dataCache
-      },
-      collection: snapshot.collection,
-      status: snapshot.collection.status,
-      isLoading:
-        snapshot.collection.status === `loading` ||
-        snapshot.collection.status === `initialCommit`,
-      isReady: snapshot.collection.status === `ready`,
-      isIdle: snapshot.collection.status === `idle`,
-      isError: snapshot.collection.status === `error`,
-      isCleanedUp: snapshot.collection.status === `cleaned-up`,
+      returnedRef.current = {
+        get state() {
+          if (!stateCache) {
+            stateCache = new Map(entries)
+          }
+          return stateCache
+        },
+        get data() {
+          if (!dataCache) {
+            dataCache = entries.map(([, value]) => value)
+          }
+          return dataCache
+        },
+        collection: snapshot.collection,
+        status: snapshot.collection.status,
+        isLoading:
+          snapshot.collection.status === `loading` ||
+          snapshot.collection.status === `initialCommit`,
+        isReady: snapshot.collection.status === `ready`,
+        isIdle: snapshot.collection.status === `idle`,
+        isError: snapshot.collection.status === `error`,
+        isCleanedUp: snapshot.collection.status === `cleaned-up`,
+        isEnabled: true,
+      }
     }
 
     // Remember the snapshot that produced this returned value