@tanstack/solid-db 0.1.53 → 0.1.55

package/dist/esm/useLiveQuery.d.ts

@@ -67,6 +67,17 @@ export declare function useLiveQuery<TContext extends Context>(queryFn: (q: Init
     isError: Accessor<boolean>;
     isCleanedUp: Accessor<boolean>;
 };
+export declare function useLiveQuery<TContext extends Context>(queryFn: (q: InitialQueryBuilder) => QueryBuilder<TContext> | undefined | null): {
+    state: ReactiveMap<string | number, GetResult<TContext>>;
+    data: Array<GetResult<TContext>>;
+    collection: Accessor<Collection<GetResult<TContext>, string | number, {}> | null>;
+    status: Accessor<CollectionStatus | `disabled`>;
+    isLoading: Accessor<boolean>;
+    isReady: Accessor<boolean>;
+    isIdle: Accessor<boolean>;
+    isError: Accessor<boolean>;
+    isCleanedUp: Accessor<boolean>;
+};
 /**
  * Create a live query using configuration object
  * @param config - Configuration object with query and options

package/dist/esm/useLiveQuery.js

@@ -1,17 +1,25 @@
 import { createMemo, createSignal, createComputed, batch, createResource, onCleanup } from "solid-js";
 import { ReactiveMap } from "@solid-primitives/map";
-import { createLiveQueryCollection, CollectionImpl } from "@tanstack/db";
+import { BaseQueryBuilder, createLiveQueryCollection, CollectionImpl } from "@tanstack/db";
 import { createStore, reconcile } from "solid-js/store";
 function useLiveQuery(configOrQueryOrCollection) {
   const collection = createMemo(
     () => {
       if (configOrQueryOrCollection.length === 1) {
+        const queryBuilder = new BaseQueryBuilder();
+        const result = configOrQueryOrCollection(queryBuilder);
+        if (result === void 0 || result === null) {
+          return null;
+        }
         return createLiveQueryCollection({
           query: configOrQueryOrCollection,
           startSync: true
         });
       }
       const innerCollection = configOrQueryOrCollection();
+      if (innerCollection === void 0 || innerCollection === null) {
+        return null;
+      }
       if (innerCollection instanceof CollectionImpl) {
         innerCollection.startSyncImmediate();
         return innerCollection;
@@ -28,9 +36,12 @@ function useLiveQuery(configOrQueryOrCollection) {
   const [data, setData] = createStore([], {
     name: `TanstackDBData`
   });
-  const [status, setStatus] = createSignal(collection().status, {
-    name: `TanstackDBStatus`
-  });
+  const [status, setStatus] = createSignal(
+    collection() ? collection().status : `disabled`,
+    {
+      name: `TanstackDBStatus`
+    }
+  );
   const syncDataFromCollection = (currentCollection) => {
     setData(
       (prev) => reconcile(Array.from(currentCollection.values()))(prev).filter(Boolean)
@@ -40,6 +51,16 @@ function useLiveQuery(configOrQueryOrCollection) {
   createComputed(
     () => {
       const currentCollection = collection();
+      if (!currentCollection) {
+        setStatus(`disabled`);
+        state.clear();
+        setData([]);
+        if (currentUnsubscribe) {
+          currentUnsubscribe();
+          currentUnsubscribe = null;
+        }
+        return;
+      }
       setStatus(currentCollection.status);
       state.clear();
       for (const [key, value] of currentCollection.entries()) {
@@ -87,7 +108,7 @@ function useLiveQuery(configOrQueryOrCollection) {
     collection,
     status,
     isLoading: () => status() === `loading`,
-    isReady: () => status() === `ready`,
+    isReady: () => status() === `ready` || status() === `disabled`,
     isIdle: () => status() === `idle`,
     isError: () => status() === `error`,
     isCleanedUp: () => status() === `cleaned-up`

package/dist/esm/useLiveQuery.js.map

@@ -1 +1 @@
-{"version":3,"file":"useLiveQuery.js","sources":["../../src/useLiveQuery.ts"],"sourcesContent":["import {\n  batch,\n  createComputed,\n  createMemo,\n  createResource,\n  createSignal,\n  onCleanup,\n} from \"solid-js\"\nimport { ReactiveMap } from \"@solid-primitives/map\"\nimport { CollectionImpl, createLiveQueryCollection } from \"@tanstack/db\"\nimport { createStore, reconcile } from \"solid-js/store\"\nimport type { Accessor } from \"solid-js\"\nimport type {\n  ChangeMessage,\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 * @returns Object with reactive data, state, and status information\n * @example\n * // Basic query with object syntax\n * const todosQuery = 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 todosQuery = useLiveQuery(\n *   (q) => q.from({ todos: todosCollection })\n *          .where(({ todos }) => gt(todos.priority, minPriority())),\n * )\n *\n * @example\n * // Join pattern\n * const personIssues = 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 todosQuery = useLiveQuery((q) =>\n *   q.from({ todos: todoCollection })\n * )\n *\n * return (\n *   <Switch>\n *     <Match when={todosQuery.isLoading()}>\n *       <div>Loading...</div>\n *     </Match>\n *     <Match when={todosQuery.isError()}>\n *       <div>Error: {todosQuery.status()}</div>\n *     </Match>\n *     <Match when={todosQuery.isReady()}>\n *       <For each={todosQuery.data()}>\n *         {(todo) => <li key={todo.id}>{todo.text}</li>}\n *       </For>\n *     </Match>\n *   </Switch>\n * )\n */\n// Overload 1: Accept just the query function\nexport function useLiveQuery<TContext extends Context>(\n  queryFn: (q: InitialQueryBuilder) => QueryBuilder<TContext>\n): {\n  state: ReactiveMap<string | number, GetResult<TContext>>\n  data: Array<GetResult<TContext>>\n  collection: Accessor<Collection<GetResult<TContext>, string | number, {}>>\n  status: Accessor<CollectionStatus>\n  isLoading: Accessor<boolean>\n  isReady: Accessor<boolean>\n  isIdle: Accessor<boolean>\n  isError: Accessor<boolean>\n  isCleanedUp: Accessor<boolean>\n}\n\n/**\n * Create a live query using configuration object\n * @param config - Configuration object with query and options\n * @returns Object with reactive data, state, and status information\n * @example\n * // Basic config object usage\n * const todosQuery = 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 personsQuery = useLiveQuery(() => ({ query: queryBuilder }))\n *\n * @example\n * // Handle all states uniformly\n * const itemsQuery = useLiveQuery(() => ({\n *   query: (q) => q.from({ items: itemCollection })\n * }))\n *\n * return (\n *   <Switch fallback={<div>{itemsQuery.data.length} items loaded</div>}>\n *     <Match when={itemsQuery.isLoading()}>\n *       <div>Loading...</div>\n *     </Match>\n *     <Match when={itemsQuery.isError()}>\n *       <div>Something went wrong</div>\n *     </Match>\n *     <Match when={!itemsQuery.isReady()}>\n *       <div>Preparing...</div>\n *     </Match>\n *   </Switch>\n * )\n */\n// Overload 2: Accept config object\nexport function useLiveQuery<TContext extends Context>(\n  config: Accessor<LiveQueryCollectionConfig<TContext>>\n): {\n  state: ReactiveMap<string | number, GetResult<TContext>>\n  data: Array<GetResult<TContext>>\n  collection: Accessor<Collection<GetResult<TContext>, string | number, {}>>\n  status: Accessor<CollectionStatus>\n  isLoading: Accessor<boolean>\n  isReady: Accessor<boolean>\n  isIdle: Accessor<boolean>\n  isError: Accessor<boolean>\n  isCleanedUp: Accessor<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 todosQuery = useLiveQuery(() => myLiveQuery)\n *\n * @example\n * // Access collection methods directly\n * const existingQuery = useLiveQuery(() => existingCollection)\n *\n * // Use collection for mutations\n * const handleToggle = (id) => {\n *   existingQuery.collection().update(id, draft => { draft.completed = !draft.completed })\n * }\n *\n * @example\n * // Handle states consistently\n * const sharedQuery = useLiveQuery(() => sharedCollection)\n *\n * return (\n *  <Switch fallback={<div><For each={sharedQuery.data()}>{(item) => <Item key={item.id} {...item} />}</For></div>}>\n *    <Match when={sharedQuery.isLoading()}>\n *      <div>Loading...</div>\n *    </Match>\n *    <Match when={sharedQuery.isError()}>\n *      <div>Error loading data</div>\n *    </Match>\n *  </Switch>\n * )\n */\n// Overload 3: Accept pre-created live query collection\nexport function useLiveQuery<\n  TResult extends object,\n  TKey extends string | number,\n  TUtils extends Record<string, any>,\n>(\n  liveQueryCollection: Accessor<Collection<TResult, TKey, TUtils>>\n): {\n  state: ReactiveMap<TKey, TResult>\n  data: Array<TResult>\n  collection: Accessor<Collection<TResult, TKey, TUtils>>\n  status: Accessor<CollectionStatus>\n  isLoading: Accessor<boolean>\n  isReady: Accessor<boolean>\n  isIdle: Accessor<boolean>\n  isError: Accessor<boolean>\n  isCleanedUp: Accessor<boolean>\n}\n\n// Implementation - use function overloads to infer the actual collection type\nexport function useLiveQuery(\n  configOrQueryOrCollection: (queryFn?: any) => any\n) {\n  const collection = createMemo(\n    () => {\n      if (configOrQueryOrCollection.length === 1) {\n        return createLiveQueryCollection({\n          query: configOrQueryOrCollection,\n          startSync: true,\n        })\n      }\n\n      const innerCollection = configOrQueryOrCollection()\n      if (innerCollection instanceof CollectionImpl) {\n        innerCollection.startSyncImmediate()\n        return innerCollection as Collection\n      }\n\n      return createLiveQueryCollection({\n        ...innerCollection,\n        startSync: true,\n      })\n    },\n    undefined,\n    { name: `TanstackDBCollectionMemo` }\n  )\n\n  // Reactive state that gets updated granularly through change events\n  const state = new ReactiveMap<string | number, any>()\n\n  // Reactive data array that maintains sorted order\n  const [data, setData] = createStore<Array<any>>([], {\n    name: `TanstackDBData`,\n  })\n\n  // Track collection status reactively\n  const [status, setStatus] = createSignal(collection().status, {\n    name: `TanstackDBStatus`,\n  })\n\n  // Helper to sync data array from collection in correct order\n  const syncDataFromCollection = (\n    currentCollection: Collection<any, any, any>\n  ) => {\n    setData((prev) =>\n      reconcile(Array.from(currentCollection.values()))(prev).filter(Boolean)\n    )\n  }\n\n  // Track current unsubscribe function\n  let currentUnsubscribe: (() => void) | null = null\n\n  createComputed(\n    () => {\n      const currentCollection = collection()\n\n      // Update status ref whenever the effect runs\n      setStatus(currentCollection.status)\n\n      // Initialize state with current collection data\n      state.clear()\n      for (const [key, value] of currentCollection.entries()) {\n        state.set(key, value)\n      }\n\n      // Subscribe to collection changes with granular updates\n      const subscription = currentCollection.subscribeChanges(\n        (changes: Array<ChangeMessage<any>>) => {\n          // Apply each change individually to the reactive state\n          batch(() => {\n            for (const change of changes) {\n              switch (change.type) {\n                case `insert`:\n                case `update`:\n                  state.set(change.key, change.value)\n                  break\n                case `delete`:\n                  state.delete(change.key)\n                  break\n              }\n            }\n          })\n\n          // Update the data array to maintain sorted order\n          syncDataFromCollection(currentCollection)\n\n          // Update status ref on every change\n          setStatus(currentCollection.status)\n        },\n        {\n          includeInitialState: true,\n        }\n      )\n\n      currentUnsubscribe = subscription.unsubscribe.bind(subscription)\n\n      // Preload collection data if not already started\n      if (currentCollection.status === `idle`) {\n        createResource(() => currentCollection.preload())\n      }\n\n      // Cleanup when computed is invalidated\n      onCleanup(() => {\n        if (currentUnsubscribe) {\n          currentUnsubscribe()\n          currentUnsubscribe = null\n        }\n      })\n    },\n    undefined,\n    { name: `TanstackDBSyncComputed` }\n  )\n\n  return {\n    state,\n    data,\n    collection,\n    status,\n    isLoading: () => status() === `loading`,\n    isReady: () => status() === `ready`,\n    isIdle: () => status() === `idle`,\n    isError: () => status() === `error`,\n    isCleanedUp: () => status() === `cleaned-up`,\n  }\n}\n"],"names":[],"mappings":";;;;AA2MO,SAAS,aACd,2BACA;AACA,QAAM,aAAa;AAAA,IACjB,MAAM;AACJ,UAAI,0BAA0B,WAAW,GAAG;AAC1C,eAAO,0BAA0B;AAAA,UAC/B,OAAO;AAAA,UACP,WAAW;AAAA,QAAA,CACZ;AAAA,MACH;AAEA,YAAM,kBAAkB,0BAAA;AACxB,UAAI,2BAA2B,gBAAgB;AAC7C,wBAAgB,mBAAA;AAChB,eAAO;AAAA,MACT;AAEA,aAAO,0BAA0B;AAAA,QAC/B,GAAG;AAAA,QACH,WAAW;AAAA,MAAA,CACZ;AAAA,IACH;AAAA,IACA;AAAA,IACA,EAAE,MAAM,2BAAA;AAAA,EAA2B;AAIrC,QAAM,QAAQ,IAAI,YAAA;AAGlB,QAAM,CAAC,MAAM,OAAO,IAAI,YAAwB,CAAA,GAAI;AAAA,IAClD,MAAM;AAAA,EAAA,CACP;AAGD,QAAM,CAAC,QAAQ,SAAS,IAAI,aAAa,WAAA,EAAa,QAAQ;AAAA,IAC5D,MAAM;AAAA,EAAA,CACP;AAGD,QAAM,yBAAyB,CAC7B,sBACG;AACH;AAAA,MAAQ,CAAC,SACP,UAAU,MAAM,KAAK,kBAAkB,OAAA,CAAQ,CAAC,EAAE,IAAI,EAAE,OAAO,OAAO;AAAA,IAAA;AAAA,EAE1E;AAGA,MAAI,qBAA0C;AAE9C;AAAA,IACE,MAAM;AACJ,YAAM,oBAAoB,WAAA;AAG1B,gBAAU,kBAAkB,MAAM;AAGlC,YAAM,MAAA;AACN,iBAAW,CAAC,KAAK,KAAK,KAAK,kBAAkB,WAAW;AACtD,cAAM,IAAI,KAAK,KAAK;AAAA,MACtB;AAGA,YAAM,eAAe,kBAAkB;AAAA,QACrC,CAAC,YAAuC;AAEtC,gBAAM,MAAM;AACV,uBAAW,UAAU,SAAS;AAC5B,sBAAQ,OAAO,MAAA;AAAA,gBACb,KAAK;AAAA,gBACL,KAAK;AACH,wBAAM,IAAI,OAAO,KAAK,OAAO,KAAK;AAClC;AAAA,gBACF,KAAK;AACH,wBAAM,OAAO,OAAO,GAAG;AACvB;AAAA,cAAA;AAAA,YAEN;AAAA,UACF,CAAC;AAGD,iCAAuB,iBAAiB;AAGxC,oBAAU,kBAAkB,MAAM;AAAA,QACpC;AAAA,QACA;AAAA,UACE,qBAAqB;AAAA,QAAA;AAAA,MACvB;AAGF,2BAAqB,aAAa,YAAY,KAAK,YAAY;AAG/D,UAAI,kBAAkB,WAAW,QAAQ;AACvC,uBAAe,MAAM,kBAAkB,SAAS;AAAA,MAClD;AAGA,gBAAU,MAAM;AACd,YAAI,oBAAoB;AACtB,6BAAA;AACA,+BAAqB;AAAA,QACvB;AAAA,MACF,CAAC;AAAA,IACH;AAAA,IACA;AAAA,IACA,EAAE,MAAM,yBAAA;AAAA,EAAyB;AAGnC,SAAO;AAAA,IACL;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA,WAAW,MAAM,aAAa;AAAA,IAC9B,SAAS,MAAM,aAAa;AAAA,IAC5B,QAAQ,MAAM,aAAa;AAAA,IAC3B,SAAS,MAAM,aAAa;AAAA,IAC5B,aAAa,MAAM,OAAA,MAAa;AAAA,EAAA;AAEpC;"}
+{"version":3,"file":"useLiveQuery.js","sources":["../../src/useLiveQuery.ts"],"sourcesContent":["import {\n  batch,\n  createComputed,\n  createMemo,\n  createResource,\n  createSignal,\n  onCleanup,\n} from 'solid-js'\nimport { ReactiveMap } from '@solid-primitives/map'\nimport {\n  BaseQueryBuilder,\n  CollectionImpl,\n  createLiveQueryCollection,\n} from '@tanstack/db'\nimport { createStore, reconcile } from 'solid-js/store'\nimport type { Accessor } from 'solid-js'\nimport type {\n  ChangeMessage,\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 * @returns Object with reactive data, state, and status information\n * @example\n * // Basic query with object syntax\n * const todosQuery = 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 todosQuery = useLiveQuery(\n *   (q) => q.from({ todos: todosCollection })\n *          .where(({ todos }) => gt(todos.priority, minPriority())),\n * )\n *\n * @example\n * // Join pattern\n * const personIssues = 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 todosQuery = useLiveQuery((q) =>\n *   q.from({ todos: todoCollection })\n * )\n *\n * return (\n *   <Switch>\n *     <Match when={todosQuery.isLoading()}>\n *       <div>Loading...</div>\n *     </Match>\n *     <Match when={todosQuery.isError()}>\n *       <div>Error: {todosQuery.status()}</div>\n *     </Match>\n *     <Match when={todosQuery.isReady()}>\n *       <For each={todosQuery.data()}>\n *         {(todo) => <li key={todo.id}>{todo.text}</li>}\n *       </For>\n *     </Match>\n *   </Switch>\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): {\n  state: ReactiveMap<string | number, GetResult<TContext>>\n  data: Array<GetResult<TContext>>\n  collection: Accessor<Collection<GetResult<TContext>, string | number, {}>>\n  status: Accessor<CollectionStatus>\n  isLoading: Accessor<boolean>\n  isReady: Accessor<boolean>\n  isIdle: Accessor<boolean>\n  isError: Accessor<boolean>\n  isCleanedUp: Accessor<boolean>\n}\n\n// Overload 1b: 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): {\n  state: ReactiveMap<string | number, GetResult<TContext>>\n  data: Array<GetResult<TContext>>\n  collection: Accessor<Collection<\n    GetResult<TContext>,\n    string | number,\n    {}\n  > | null>\n  status: Accessor<CollectionStatus | `disabled`>\n  isLoading: Accessor<boolean>\n  isReady: Accessor<boolean>\n  isIdle: Accessor<boolean>\n  isError: Accessor<boolean>\n  isCleanedUp: Accessor<boolean>\n}\n\n/**\n * Create a live query using configuration object\n * @param config - Configuration object with query and options\n * @returns Object with reactive data, state, and status information\n * @example\n * // Basic config object usage\n * const todosQuery = 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 personsQuery = useLiveQuery(() => ({ query: queryBuilder }))\n *\n * @example\n * // Handle all states uniformly\n * const itemsQuery = useLiveQuery(() => ({\n *   query: (q) => q.from({ items: itemCollection })\n * }))\n *\n * return (\n *   <Switch fallback={<div>{itemsQuery.data.length} items loaded</div>}>\n *     <Match when={itemsQuery.isLoading()}>\n *       <div>Loading...</div>\n *     </Match>\n *     <Match when={itemsQuery.isError()}>\n *       <div>Something went wrong</div>\n *     </Match>\n *     <Match when={!itemsQuery.isReady()}>\n *       <div>Preparing...</div>\n *     </Match>\n *   </Switch>\n * )\n */\n// Overload 2: Accept config object\nexport function useLiveQuery<TContext extends Context>(\n  config: Accessor<LiveQueryCollectionConfig<TContext>>,\n): {\n  state: ReactiveMap<string | number, GetResult<TContext>>\n  data: Array<GetResult<TContext>>\n  collection: Accessor<Collection<GetResult<TContext>, string | number, {}>>\n  status: Accessor<CollectionStatus>\n  isLoading: Accessor<boolean>\n  isReady: Accessor<boolean>\n  isIdle: Accessor<boolean>\n  isError: Accessor<boolean>\n  isCleanedUp: Accessor<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 todosQuery = useLiveQuery(() => myLiveQuery)\n *\n * @example\n * // Access collection methods directly\n * const existingQuery = useLiveQuery(() => existingCollection)\n *\n * // Use collection for mutations\n * const handleToggle = (id) => {\n *   existingQuery.collection().update(id, draft => { draft.completed = !draft.completed })\n * }\n *\n * @example\n * // Handle states consistently\n * const sharedQuery = useLiveQuery(() => sharedCollection)\n *\n * return (\n *  <Switch fallback={<div><For each={sharedQuery.data()}>{(item) => <Item key={item.id} {...item} />}</For></div>}>\n *    <Match when={sharedQuery.isLoading()}>\n *      <div>Loading...</div>\n *    </Match>\n *    <Match when={sharedQuery.isError()}>\n *      <div>Error loading data</div>\n *    </Match>\n *  </Switch>\n * )\n */\n// Overload 3: Accept pre-created live query collection\nexport function useLiveQuery<\n  TResult extends object,\n  TKey extends string | number,\n  TUtils extends Record<string, any>,\n>(\n  liveQueryCollection: Accessor<Collection<TResult, TKey, TUtils>>,\n): {\n  state: ReactiveMap<TKey, TResult>\n  data: Array<TResult>\n  collection: Accessor<Collection<TResult, TKey, TUtils>>\n  status: Accessor<CollectionStatus>\n  isLoading: Accessor<boolean>\n  isReady: Accessor<boolean>\n  isIdle: Accessor<boolean>\n  isError: Accessor<boolean>\n  isCleanedUp: Accessor<boolean>\n}\n\n// Implementation - use function overloads to infer the actual collection type\nexport function useLiveQuery(\n  configOrQueryOrCollection: (queryFn?: any) => any,\n) {\n  const collection = createMemo(\n    () => {\n      if (configOrQueryOrCollection.length === 1) {\n        // This is a query function - check if it returns null/undefined\n        const queryBuilder = new BaseQueryBuilder() as InitialQueryBuilder\n        const result = configOrQueryOrCollection(queryBuilder)\n\n        if (result === undefined || result === null) {\n          // Disabled query - return null\n          return null\n        }\n\n        return createLiveQueryCollection({\n          query: configOrQueryOrCollection,\n          startSync: true,\n        })\n      }\n\n      const innerCollection = configOrQueryOrCollection()\n\n      if (innerCollection === undefined || innerCollection === null) {\n        // Disabled query - return null\n        return null\n      }\n\n      if (innerCollection instanceof CollectionImpl) {\n        innerCollection.startSyncImmediate()\n        return innerCollection as Collection\n      }\n\n      return createLiveQueryCollection({\n        ...innerCollection,\n        startSync: true,\n      })\n    },\n    undefined,\n    { name: `TanstackDBCollectionMemo` },\n  )\n\n  // Reactive state that gets updated granularly through change events\n  const state = new ReactiveMap<string | number, any>()\n\n  // Reactive data array that maintains sorted order\n  const [data, setData] = createStore<Array<any>>([], {\n    name: `TanstackDBData`,\n  })\n\n  // Track collection status reactively\n  const [status, setStatus] = createSignal(\n    collection() ? collection()!.status : (`disabled` as const),\n    {\n      name: `TanstackDBStatus`,\n    },\n  )\n\n  // Helper to sync data array from collection in correct order\n  const syncDataFromCollection = (\n    currentCollection: Collection<any, any, any>,\n  ) => {\n    setData((prev) =>\n      reconcile(Array.from(currentCollection.values()))(prev).filter(Boolean),\n    )\n  }\n\n  // Track current unsubscribe function\n  let currentUnsubscribe: (() => void) | null = null\n\n  createComputed(\n    () => {\n      const currentCollection = collection()\n\n      // Handle null collection (disabled query)\n      if (!currentCollection) {\n        setStatus(`disabled` as const)\n        state.clear()\n        setData([])\n        if (currentUnsubscribe) {\n          currentUnsubscribe()\n          currentUnsubscribe = null\n        }\n        return\n      }\n\n      // Update status ref whenever the effect runs\n      setStatus(currentCollection.status)\n\n      // Initialize state with current collection data\n      state.clear()\n      for (const [key, value] of currentCollection.entries()) {\n        state.set(key, value)\n      }\n\n      // Subscribe to collection changes with granular updates\n      const subscription = currentCollection.subscribeChanges(\n        (changes: Array<ChangeMessage<any>>) => {\n          // Apply each change individually to the reactive state\n          batch(() => {\n            for (const change of changes) {\n              switch (change.type) {\n                case `insert`:\n                case `update`:\n                  state.set(change.key, change.value)\n                  break\n                case `delete`:\n                  state.delete(change.key)\n                  break\n              }\n            }\n          })\n\n          // Update the data array to maintain sorted order\n          syncDataFromCollection(currentCollection)\n\n          // Update status ref on every change\n          setStatus(currentCollection.status)\n        },\n        {\n          includeInitialState: true,\n        },\n      )\n\n      currentUnsubscribe = subscription.unsubscribe.bind(subscription)\n\n      // Preload collection data if not already started\n      if (currentCollection.status === `idle`) {\n        createResource(() => currentCollection.preload())\n      }\n\n      // Cleanup when computed is invalidated\n      onCleanup(() => {\n        if (currentUnsubscribe) {\n          currentUnsubscribe()\n          currentUnsubscribe = null\n        }\n      })\n    },\n    undefined,\n    { name: `TanstackDBSyncComputed` },\n  )\n\n  return {\n    state,\n    data,\n    collection,\n    status,\n    isLoading: () => status() === `loading`,\n    isReady: () => status() === `ready` || status() === `disabled`,\n    isIdle: () => status() === `idle`,\n    isError: () => status() === `error`,\n    isCleanedUp: () => status() === `cleaned-up`,\n  }\n}\n"],"names":[],"mappings":"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"}

package/package.json

@@ -1,12 +1,12 @@
 {
   "name": "@tanstack/solid-db",
+  "version": "0.1.55",
   "description": "Solid integration for @tanstack/db",
-  "version": "0.1.53",
   "author": "Kyle Mathews",
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "https://github.com/TanStack/db.git",
+    "url": "git+https://github.com/TanStack/db.git",
     "directory": "packages/solid-db"
   },
   "homepage": "https://tanstack.com/db",
@@ -15,19 +15,10 @@
     "solid",
     "typescript"
   ],
-  "dependencies": {
-    "@solid-primitives/map": "^0.7.2",
-    "@tanstack/db": "0.5.10"
-  },
-  "devDependencies": {
-    "@electric-sql/client": "1.2.0",
-    "@solidjs/testing-library": "^0.8.10",
-    "@vitest/coverage-istanbul": "^3.2.4",
-    "jsdom": "^27.2.0",
-    "solid-js": "^1.9.10",
-    "vite-plugin-solid": "^2.11.10",
-    "vitest": "^3.2.4"
-  },
+  "type": "module",
+  "main": "dist/esm/index.js",
+  "module": "dist/esm/index.js",
+  "types": "dist/esm/index.d.ts",
   "exports": {
     ".": {
       "import": {
@@ -37,18 +28,27 @@
     },
     "./package.json": "./package.json"
   },
+  "sideEffects": false,
   "files": [
     "dist",
     "src"
   ],
-  "main": "dist/cjs/index.cjs",
-  "module": "dist/esm/index.js",
+  "dependencies": {
+    "@solid-primitives/map": "^0.7.2",
+    "@tanstack/db": "0.5.12"
+  },
   "peerDependencies": {
     "solid-js": ">=1.9.0"
   },
-  "sideEffects": false,
-  "type": "module",
-  "types": "dist/esm/index.d.ts",
+  "devDependencies": {
+    "@electric-sql/client": "1.2.0",
+    "@solidjs/testing-library": "^0.8.10",
+    "@vitest/coverage-istanbul": "^3.2.4",
+    "jsdom": "^27.2.0",
+    "solid-js": "^1.9.10",
+    "vite-plugin-solid": "^2.11.10",
+    "vitest": "^3.2.4"
+  },
   "scripts": {
     "build": "vite build",
     "dev": "vite build --watch",

package/src/index.ts

@@ -1,9 +1,9 @@
 // Re-export all public APIs
-export * from "./useLiveQuery"
+export * from './useLiveQuery'
 
 // Re-export everything from @tanstack/db
-export * from "@tanstack/db"
+export * from '@tanstack/db'
 
 // Re-export some stuff explicitly to ensure the type & value is exported
-export type { Collection } from "@tanstack/db"
-export { createTransaction } from "@tanstack/db"
+export type { Collection } from '@tanstack/db'
+export { createTransaction } from '@tanstack/db'

package/src/useLiveQuery.ts

@@ -5,11 +5,15 @@ import {
   createResource,
   createSignal,
   onCleanup,
-} from "solid-js"
-import { ReactiveMap } from "@solid-primitives/map"
-import { CollectionImpl, createLiveQueryCollection } from "@tanstack/db"
-import { createStore, reconcile } from "solid-js/store"
-import type { Accessor } from "solid-js"
+} from 'solid-js'
+import { ReactiveMap } from '@solid-primitives/map'
+import {
+  BaseQueryBuilder,
+  CollectionImpl,
+  createLiveQueryCollection,
+} from '@tanstack/db'
+import { createStore, reconcile } from 'solid-js/store'
+import type { Accessor } from 'solid-js'
 import type {
   ChangeMessage,
   Collection,
@@ -19,7 +23,7 @@ import type {
   InitialQueryBuilder,
   LiveQueryCollectionConfig,
   QueryBuilder,
-} from "@tanstack/db"
+} from '@tanstack/db'
 
 /**
  * Create a live query using a query function
@@ -76,9 +80,9 @@ import type {
  *   </Switch>
  * )
  */
-// 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>
+  queryFn: (q: InitialQueryBuilder) => QueryBuilder<TContext>,
 ): {
   state: ReactiveMap<string | number, GetResult<TContext>>
   data: Array<GetResult<TContext>>
@@ -91,6 +95,27 @@ export function useLiveQuery<TContext extends Context>(
   isCleanedUp: Accessor<boolean>
 }
 
+// Overload 1b: Accept query function that can return undefined/null
+export function useLiveQuery<TContext extends Context>(
+  queryFn: (
+    q: InitialQueryBuilder,
+  ) => QueryBuilder<TContext> | undefined | null,
+): {
+  state: ReactiveMap<string | number, GetResult<TContext>>
+  data: Array<GetResult<TContext>>
+  collection: Accessor<Collection<
+    GetResult<TContext>,
+    string | number,
+    {}
+  > | null>
+  status: Accessor<CollectionStatus | `disabled`>
+  isLoading: Accessor<boolean>
+  isReady: Accessor<boolean>
+  isIdle: Accessor<boolean>
+  isError: Accessor<boolean>
+  isCleanedUp: Accessor<boolean>
+}
+
 /**
  * Create a live query using configuration object
  * @param config - Configuration object with query and options
@@ -133,7 +158,7 @@ export function useLiveQuery<TContext extends Context>(
  */
 // Overload 2: Accept config object
 export function useLiveQuery<TContext extends Context>(
-  config: Accessor<LiveQueryCollectionConfig<TContext>>
+  config: Accessor<LiveQueryCollectionConfig<TContext>>,
 ): {
   state: ReactiveMap<string | number, GetResult<TContext>>
   data: Array<GetResult<TContext>>
@@ -187,7 +212,7 @@ export function useLiveQuery<
   TKey extends string | number,
   TUtils extends Record<string, any>,
 >(
-  liveQueryCollection: Accessor<Collection<TResult, TKey, TUtils>>
+  liveQueryCollection: Accessor<Collection<TResult, TKey, TUtils>>,
 ): {
   state: ReactiveMap<TKey, TResult>
   data: Array<TResult>
@@ -202,11 +227,20 @@ export function useLiveQuery<
 
 // Implementation - use function overloads to infer the actual collection type
 export function useLiveQuery(
-  configOrQueryOrCollection: (queryFn?: any) => any
+  configOrQueryOrCollection: (queryFn?: any) => any,
 ) {
   const collection = createMemo(
     () => {
       if (configOrQueryOrCollection.length === 1) {
+        // This is a query function - check if it returns null/undefined
+        const queryBuilder = new BaseQueryBuilder() as InitialQueryBuilder
+        const result = configOrQueryOrCollection(queryBuilder)
+
+        if (result === undefined || result === null) {
+          // Disabled query - return null
+          return null
+        }
+
         return createLiveQueryCollection({
           query: configOrQueryOrCollection,
           startSync: true,
@@ -214,6 +248,12 @@ export function useLiveQuery(
       }
 
       const innerCollection = configOrQueryOrCollection()
+
+      if (innerCollection === undefined || innerCollection === null) {
+        // Disabled query - return null
+        return null
+      }
+
       if (innerCollection instanceof CollectionImpl) {
         innerCollection.startSyncImmediate()
         return innerCollection as Collection
@@ -225,7 +265,7 @@ export function useLiveQuery(
       })
     },
     undefined,
-    { name: `TanstackDBCollectionMemo` }
+    { name: `TanstackDBCollectionMemo` },
   )
 
   // Reactive state that gets updated granularly through change events
@@ -237,16 +277,19 @@ export function useLiveQuery(
   })
 
   // Track collection status reactively
-  const [status, setStatus] = createSignal(collection().status, {
-    name: `TanstackDBStatus`,
-  })
+  const [status, setStatus] = createSignal(
+    collection() ? collection()!.status : (`disabled` as const),
+    {
+      name: `TanstackDBStatus`,
+    },
+  )
 
   // Helper to sync data array from collection in correct order
   const syncDataFromCollection = (
-    currentCollection: Collection<any, any, any>
+    currentCollection: Collection<any, any, any>,
   ) => {
     setData((prev) =>
-      reconcile(Array.from(currentCollection.values()))(prev).filter(Boolean)
+      reconcile(Array.from(currentCollection.values()))(prev).filter(Boolean),
     )
   }
 
@@ -257,6 +300,18 @@ export function useLiveQuery(
     () => {
       const currentCollection = collection()
 
+      // Handle null collection (disabled query)
+      if (!currentCollection) {
+        setStatus(`disabled` as const)
+        state.clear()
+        setData([])
+        if (currentUnsubscribe) {
+          currentUnsubscribe()
+          currentUnsubscribe = null
+        }
+        return
+      }
+
       // Update status ref whenever the effect runs
       setStatus(currentCollection.status)
 
@@ -292,7 +347,7 @@ export function useLiveQuery(
         },
         {
           includeInitialState: true,
-        }
+        },
       )
 
       currentUnsubscribe = subscription.unsubscribe.bind(subscription)
@@ -311,7 +366,7 @@ export function useLiveQuery(
       })
     },
     undefined,
-    { name: `TanstackDBSyncComputed` }
+    { name: `TanstackDBSyncComputed` },
   )
 
   return {
@@ -320,7 +375,7 @@ export function useLiveQuery(
     collection,
     status,
     isLoading: () => status() === `loading`,
-    isReady: () => status() === `ready`,
+    isReady: () => status() === `ready` || status() === `disabled`,
     isIdle: () => status() === `idle`,
     isError: () => status() === `error`,
     isCleanedUp: () => status() === `cleaned-up`,