@tanstack/query-db-collection 0.0.2 → 0.0.4

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Kyle Mathews
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/cjs/index.cjs

@@ -0,0 +1,5 @@
+"use strict";
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const query = require("./query.cjs");
+exports.queryCollectionOptions = query.queryCollectionOptions;
+//# sourceMappingURL=index.cjs.map

package/dist/cjs/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.cjs","sources":[],"sourcesContent":[],"names":[],"mappings":";;;;"}

package/dist/cjs/index.d.cts

@@ -0,0 +1 @@
+export { queryCollectionOptions, type QueryCollectionConfig, type QueryCollectionUtils, } from './query.cjs';

package/dist/cjs/query.cjs

@@ -0,0 +1,147 @@
+"use strict";
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const queryCore = require("@tanstack/query-core");
+function queryCollectionOptions(config) {
+  const {
+    queryKey,
+    queryFn,
+    queryClient,
+    enabled,
+    refetchInterval,
+    retry,
+    retryDelay,
+    staleTime,
+    getKey,
+    onInsert,
+    onUpdate,
+    onDelete,
+    ...baseCollectionConfig
+  } = config;
+  if (!queryKey) {
+    throw new Error(`[QueryCollection] queryKey must be provided.`);
+  }
+  if (!queryFn) {
+    throw new Error(`[QueryCollection] queryFn must be provided.`);
+  }
+  if (!queryClient) {
+    throw new Error(`[QueryCollection] queryClient must be provided.`);
+  }
+  if (!getKey) {
+    throw new Error(`[QueryCollection] getKey must be provided.`);
+  }
+  const internalSync = (params) => {
+    const { begin, write, commit, collection } = params;
+    const observerOptions = {
+      queryKey,
+      queryFn,
+      enabled,
+      refetchInterval,
+      retry,
+      retryDelay,
+      staleTime,
+      structuralSharing: true,
+      notifyOnChangeProps: `all`
+    };
+    const localObserver = new queryCore.QueryObserver(queryClient, observerOptions);
+    const actualUnsubscribeFn = localObserver.subscribe((result) => {
+      if (result.isSuccess) {
+        const newItemsArray = result.data;
+        if (!Array.isArray(newItemsArray) || newItemsArray.some((item) => typeof item !== `object`)) {
+          console.error(
+            `[QueryCollection] queryFn did not return an array of objects. Skipping update.`,
+            newItemsArray
+          );
+          return;
+        }
+        const currentSyncedItems = new Map(collection.syncedData);
+        const newItemsMap = /* @__PURE__ */ new Map();
+        newItemsArray.forEach((item) => {
+          const key = getKey(item);
+          newItemsMap.set(key, item);
+        });
+        begin();
+        const shallowEqual = (obj1, obj2) => {
+          const keys1 = Object.keys(obj1);
+          const keys2 = Object.keys(obj2);
+          if (keys1.length !== keys2.length) return false;
+          return keys1.every((key) => {
+            if (typeof obj1[key] === `function`) return true;
+            if (typeof obj1[key] === `object` && obj1[key] !== null) {
+              return obj1[key] === obj2[key];
+            }
+            return obj1[key] === obj2[key];
+          });
+        };
+        currentSyncedItems.forEach((oldItem, key) => {
+          const newItem = newItemsMap.get(key);
+          if (!newItem) {
+            write({ type: `delete`, value: oldItem });
+          } else if (!shallowEqual(
+            oldItem,
+            newItem
+          )) {
+            write({ type: `update`, value: newItem });
+          }
+        });
+        newItemsMap.forEach((newItem, key) => {
+          if (!currentSyncedItems.has(key)) {
+            write({ type: `insert`, value: newItem });
+          }
+        });
+        commit();
+      } else if (result.isError) {
+        console.error(
+          `[QueryCollection] Error observing query ${String(queryKey)}:`,
+          result.error
+        );
+      }
+    });
+    return async () => {
+      actualUnsubscribeFn();
+      await queryClient.cancelQueries({ queryKey });
+      queryClient.removeQueries({ queryKey });
+    };
+  };
+  const refetch = async () => {
+    return queryClient.refetchQueries({
+      queryKey
+    });
+  };
+  const wrappedOnInsert = onInsert ? async (params) => {
+    const handlerResult = await onInsert(params) ?? {};
+    const shouldRefetch = handlerResult.refetch !== false;
+    if (shouldRefetch) {
+      await refetch();
+    }
+    return handlerResult;
+  } : void 0;
+  const wrappedOnUpdate = onUpdate ? async (params) => {
+    const handlerResult = await onUpdate(params) ?? {};
+    const shouldRefetch = handlerResult.refetch !== false;
+    if (shouldRefetch) {
+      await refetch();
+    }
+    return handlerResult;
+  } : void 0;
+  const wrappedOnDelete = onDelete ? async (params) => {
+    const handlerResult = await onDelete(params) ?? {};
+    const shouldRefetch = handlerResult.refetch !== false;
+    if (shouldRefetch) {
+      await refetch();
+    }
+    return handlerResult;
+  } : void 0;
+  return {
+    ...baseCollectionConfig,
+    getKey,
+    sync: { sync: internalSync },
+    onInsert: wrappedOnInsert,
+    onUpdate: wrappedOnUpdate,
+    onDelete: wrappedOnDelete,
+    utils: {
+      refetch
+    }
+  };
+}
+exports.queryCollectionOptions = queryCollectionOptions;
+//# sourceMappingURL=query.cjs.map

package/dist/cjs/query.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"query.cjs","sources":["../../src/query.ts"],"sourcesContent":["import { QueryObserver } from \"@tanstack/query-core\"\nimport type {\n  QueryClient,\n  QueryFunctionContext,\n  QueryKey,\n  QueryObserverOptions,\n} from \"@tanstack/query-core\"\nimport type {\n  CollectionConfig,\n  DeleteMutationFn,\n  DeleteMutationFnParams,\n  InsertMutationFn,\n  InsertMutationFnParams,\n  SyncConfig,\n  UpdateMutationFn,\n  UpdateMutationFnParams,\n  UtilsRecord,\n} from \"@tanstack/db\"\n\nexport interface QueryCollectionConfig<\n  TItem extends object,\n  TError = unknown,\n  TQueryKey extends QueryKey = QueryKey,\n> {\n  queryKey: TQueryKey\n  queryFn: (context: QueryFunctionContext<TQueryKey>) => Promise<Array<TItem>>\n  queryClient: QueryClient\n\n  // Query-specific options\n  enabled?: boolean\n  refetchInterval?: QueryObserverOptions<\n    Array<TItem>,\n    TError,\n    Array<TItem>,\n    Array<TItem>,\n    TQueryKey\n  >[`refetchInterval`]\n  retry?: QueryObserverOptions<\n    Array<TItem>,\n    TError,\n    Array<TItem>,\n    Array<TItem>,\n    TQueryKey\n  >[`retry`]\n  retryDelay?: QueryObserverOptions<\n    Array<TItem>,\n    TError,\n    Array<TItem>,\n    Array<TItem>,\n    TQueryKey\n  >[`retryDelay`]\n  staleTime?: QueryObserverOptions<\n    Array<TItem>,\n    TError,\n    Array<TItem>,\n    Array<TItem>,\n    TQueryKey\n  >[`staleTime`]\n\n  // Standard Collection configuration properties\n  id?: string\n  getKey: CollectionConfig<TItem>[`getKey`]\n  schema?: CollectionConfig<TItem>[`schema`]\n  sync?: CollectionConfig<TItem>[`sync`]\n  startSync?: CollectionConfig<TItem>[`startSync`]\n\n  // Direct persistence handlers\n  /**\n   * Optional asynchronous handler function called before an insert operation\n   * @param params Object containing transaction and collection information\n   * @returns Promise resolving to void or { refetch?: boolean } to control refetching\n   * @example\n   * // Basic query collection insert handler\n   * onInsert: async ({ transaction }) => {\n   *   const newItem = transaction.mutations[0].modified\n   *   await api.createTodo(newItem)\n   *   // Automatically refetches query after insert\n   * }\n   *\n   * @example\n   * // Insert handler with refetch control\n   * onInsert: async ({ transaction }) => {\n   *   const newItem = transaction.mutations[0].modified\n   *   await api.createTodo(newItem)\n   *   return { refetch: false } // Skip automatic refetch\n   * }\n   *\n   * @example\n   * // Insert handler with multiple items\n   * onInsert: async ({ transaction }) => {\n   *   const items = transaction.mutations.map(m => m.modified)\n   *   await api.createTodos(items)\n   *   // Will refetch query to get updated data\n   * }\n   *\n   * @example\n   * // Insert handler with error handling\n   * onInsert: async ({ transaction }) => {\n   *   try {\n   *     const newItem = transaction.mutations[0].modified\n   *     await api.createTodo(newItem)\n   *   } catch (error) {\n   *     console.error('Insert failed:', error)\n   *     throw error // Transaction will rollback optimistic changes\n   *   }\n   * }\n   */\n  onInsert?: InsertMutationFn<TItem>\n\n  /**\n   * Optional asynchronous handler function called before an update operation\n   * @param params Object containing transaction and collection information\n   * @returns Promise resolving to void or { refetch?: boolean } to control refetching\n   * @example\n   * // Basic query collection update handler\n   * onUpdate: async ({ transaction }) => {\n   *   const mutation = transaction.mutations[0]\n   *   await api.updateTodo(mutation.original.id, mutation.changes)\n   *   // Automatically refetches query after update\n   * }\n   *\n   * @example\n   * // Update handler with multiple items\n   * onUpdate: async ({ transaction }) => {\n   *   const updates = transaction.mutations.map(m => ({\n   *     id: m.key,\n   *     changes: m.changes\n   *   }))\n   *   await api.updateTodos(updates)\n   *   // Will refetch query to get updated data\n   * }\n   *\n   * @example\n   * // Update handler with manual refetch\n   * onUpdate: async ({ transaction, collection }) => {\n   *   const mutation = transaction.mutations[0]\n   *   await api.updateTodo(mutation.original.id, mutation.changes)\n   *\n   *   // Manually trigger refetch\n   *   await collection.utils.refetch()\n   *\n   *   return { refetch: false } // Skip automatic refetch\n   * }\n   *\n   * @example\n   * // Update handler with related collection refetch\n   * onUpdate: async ({ transaction, collection }) => {\n   *   const mutation = transaction.mutations[0]\n   *   await api.updateTodo(mutation.original.id, mutation.changes)\n   *\n   *   // Refetch related collections when this item changes\n   *   await Promise.all([\n   *     collection.utils.refetch(), // Refetch this collection\n   *     usersCollection.utils.refetch(), // Refetch users\n   *     tagsCollection.utils.refetch() // Refetch tags\n   *   ])\n   *\n   *   return { refetch: false } // Skip automatic refetch since we handled it manually\n   * }\n   */\n  onUpdate?: UpdateMutationFn<TItem>\n\n  /**\n   * Optional asynchronous handler function called before a delete operation\n   * @param params Object containing transaction and collection information\n   * @returns Promise resolving to void or { refetch?: boolean } to control refetching\n   * @example\n   * // Basic query collection delete handler\n   * onDelete: async ({ transaction }) => {\n   *   const mutation = transaction.mutations[0]\n   *   await api.deleteTodo(mutation.original.id)\n   *   // Automatically refetches query after delete\n   * }\n   *\n   * @example\n   * // Delete handler with refetch control\n   * onDelete: async ({ transaction }) => {\n   *   const mutation = transaction.mutations[0]\n   *   await api.deleteTodo(mutation.original.id)\n   *   return { refetch: false } // Skip automatic refetch\n   * }\n   *\n   * @example\n   * // Delete handler with multiple items\n   * onDelete: async ({ transaction }) => {\n   *   const keysToDelete = transaction.mutations.map(m => m.key)\n   *   await api.deleteTodos(keysToDelete)\n   *   // Will refetch query to get updated data\n   * }\n   *\n   * @example\n   * // Delete handler with related collection refetch\n   * onDelete: async ({ transaction, collection }) => {\n   *   const mutation = transaction.mutations[0]\n   *   await api.deleteTodo(mutation.original.id)\n   *\n   *   // Refetch related collections when this item is deleted\n   *   await Promise.all([\n   *     collection.utils.refetch(), // Refetch this collection\n   *     usersCollection.utils.refetch(), // Refetch users\n   *     projectsCollection.utils.refetch() // Refetch projects\n   *   ])\n   *\n   *   return { refetch: false } // Skip automatic refetch since we handled it manually\n   * }\n   */\n  onDelete?: DeleteMutationFn<TItem>\n  // TODO type returning { refetch: boolean }\n}\n\n/**\n * Type for the refetch utility function\n */\nexport type RefetchFn = () => Promise<void>\n\n/**\n * Query collection utilities type\n */\nexport interface QueryCollectionUtils extends UtilsRecord {\n  refetch: RefetchFn\n}\n\n/**\n * Creates query collection options for use with a standard Collection\n *\n * @param config - Configuration options for the Query collection\n * @returns Collection options with utilities\n */\nexport function queryCollectionOptions<\n  TItem extends object,\n  TError = unknown,\n  TQueryKey extends QueryKey = QueryKey,\n>(\n  config: QueryCollectionConfig<TItem, TError, TQueryKey>\n): CollectionConfig<TItem> & { utils: QueryCollectionUtils } {\n  const {\n    queryKey,\n    queryFn,\n    queryClient,\n    enabled,\n    refetchInterval,\n    retry,\n    retryDelay,\n    staleTime,\n    getKey,\n    onInsert,\n    onUpdate,\n    onDelete,\n    ...baseCollectionConfig\n  } = config\n\n  // Validate required parameters\n\n  // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition\n  if (!queryKey) {\n    throw new Error(`[QueryCollection] queryKey must be provided.`)\n  }\n  // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition\n  if (!queryFn) {\n    throw new Error(`[QueryCollection] queryFn must be provided.`)\n  }\n\n  // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition\n  if (!queryClient) {\n    throw new Error(`[QueryCollection] queryClient must be provided.`)\n  }\n\n  if (!getKey) {\n    throw new Error(`[QueryCollection] getKey must be provided.`)\n  }\n\n  const internalSync: SyncConfig<TItem>[`sync`] = (params) => {\n    const { begin, write, commit, collection } = params\n\n    const observerOptions: QueryObserverOptions<\n      Array<TItem>,\n      TError,\n      Array<TItem>,\n      Array<TItem>,\n      TQueryKey\n    > = {\n      queryKey: queryKey,\n      queryFn: queryFn,\n      enabled: enabled,\n      refetchInterval: refetchInterval,\n      retry: retry,\n      retryDelay: retryDelay,\n      staleTime: staleTime,\n      structuralSharing: true,\n      notifyOnChangeProps: `all`,\n    }\n\n    const localObserver = new QueryObserver<\n      Array<TItem>,\n      TError,\n      Array<TItem>,\n      Array<TItem>,\n      TQueryKey\n    >(queryClient, observerOptions)\n\n    const actualUnsubscribeFn = localObserver.subscribe((result) => {\n      if (result.isSuccess) {\n        const newItemsArray = result.data\n\n        if (\n          !Array.isArray(newItemsArray) ||\n          newItemsArray.some((item) => typeof item !== `object`)\n        ) {\n          console.error(\n            `[QueryCollection] queryFn did not return an array of objects. Skipping update.`,\n            newItemsArray\n          )\n          return\n        }\n\n        const currentSyncedItems = new Map(collection.syncedData)\n        const newItemsMap = new Map<string | number, TItem>()\n        newItemsArray.forEach((item) => {\n          const key = getKey(item)\n          newItemsMap.set(key, item)\n        })\n\n        begin()\n\n        // Helper function for shallow equality check of objects\n        const shallowEqual = (\n          obj1: Record<string, any>,\n          obj2: Record<string, any>\n        ): boolean => {\n          // Get all keys from both objects\n          const keys1 = Object.keys(obj1)\n          const keys2 = Object.keys(obj2)\n\n          // If number of keys is different, objects are not equal\n          if (keys1.length !== keys2.length) return false\n\n          // Check if all keys in obj1 have the same values in obj2\n          return keys1.every((key) => {\n            // Skip comparing functions and complex objects deeply\n            if (typeof obj1[key] === `function`) return true\n            if (typeof obj1[key] === `object` && obj1[key] !== null) {\n              // For nested objects, just compare references\n              // A more robust solution might do recursive shallow comparison\n              // or let users provide a custom equality function\n              return obj1[key] === obj2[key]\n            }\n            return obj1[key] === obj2[key]\n          })\n        }\n\n        currentSyncedItems.forEach((oldItem, key) => {\n          const newItem = newItemsMap.get(key)\n          if (!newItem) {\n            write({ type: `delete`, value: oldItem })\n          } else if (\n            !shallowEqual(\n              oldItem as Record<string, any>,\n              newItem as Record<string, any>\n            )\n          ) {\n            // Only update if there are actual differences in the properties\n            write({ type: `update`, value: newItem })\n          }\n        })\n\n        newItemsMap.forEach((newItem, key) => {\n          if (!currentSyncedItems.has(key)) {\n            write({ type: `insert`, value: newItem })\n          }\n        })\n\n        commit()\n      } else if (result.isError) {\n        console.error(\n          `[QueryCollection] Error observing query ${String(queryKey)}:`,\n          result.error\n        )\n      }\n    })\n\n    return async () => {\n      actualUnsubscribeFn()\n      await queryClient.cancelQueries({ queryKey })\n      queryClient.removeQueries({ queryKey })\n    }\n  }\n\n  /**\n   * Refetch the query data\n   * @returns Promise that resolves when the refetch is complete\n   */\n  const refetch: RefetchFn = async (): Promise<void> => {\n    return queryClient.refetchQueries({\n      queryKey: queryKey,\n    })\n  }\n\n  // Create wrapper handlers for direct persistence operations that handle refetching\n  const wrappedOnInsert = onInsert\n    ? async (params: InsertMutationFnParams<TItem>) => {\n        const handlerResult = (await onInsert(params)) ?? {}\n        const shouldRefetch =\n          (handlerResult as { refetch?: boolean }).refetch !== false\n\n        if (shouldRefetch) {\n          await refetch()\n        }\n\n        return handlerResult\n      }\n    : undefined\n\n  const wrappedOnUpdate = onUpdate\n    ? async (params: UpdateMutationFnParams<TItem>) => {\n        const handlerResult = (await onUpdate(params)) ?? {}\n        const shouldRefetch =\n          (handlerResult as { refetch?: boolean }).refetch !== false\n\n        if (shouldRefetch) {\n          await refetch()\n        }\n\n        return handlerResult\n      }\n    : undefined\n\n  const wrappedOnDelete = onDelete\n    ? async (params: DeleteMutationFnParams<TItem>) => {\n        const handlerResult = (await onDelete(params)) ?? {}\n        const shouldRefetch =\n          (handlerResult as { refetch?: boolean }).refetch !== false\n\n        if (shouldRefetch) {\n          await refetch()\n        }\n\n        return handlerResult\n      }\n    : undefined\n\n  return {\n    ...baseCollectionConfig,\n    getKey,\n    sync: { sync: internalSync },\n    onInsert: wrappedOnInsert,\n    onUpdate: wrappedOnUpdate,\n    onDelete: wrappedOnDelete,\n    utils: {\n      refetch,\n    },\n  }\n}\n"],"names":["QueryObserver"],"mappings":"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"}

package/dist/cjs/query.d.cts

@@ -0,0 +1,174 @@
+import { QueryClient, QueryFunctionContext, QueryKey, QueryObserverOptions } from '@tanstack/query-core';
+import { CollectionConfig, DeleteMutationFn, InsertMutationFn, UpdateMutationFn, UtilsRecord } from '@tanstack/db';
+export interface QueryCollectionConfig<TItem extends object, TError = unknown, TQueryKey extends QueryKey = QueryKey> {
+    queryKey: TQueryKey;
+    queryFn: (context: QueryFunctionContext<TQueryKey>) => Promise<Array<TItem>>;
+    queryClient: QueryClient;
+    enabled?: boolean;
+    refetchInterval?: QueryObserverOptions<Array<TItem>, TError, Array<TItem>, Array<TItem>, TQueryKey>[`refetchInterval`];
+    retry?: QueryObserverOptions<Array<TItem>, TError, Array<TItem>, Array<TItem>, TQueryKey>[`retry`];
+    retryDelay?: QueryObserverOptions<Array<TItem>, TError, Array<TItem>, Array<TItem>, TQueryKey>[`retryDelay`];
+    staleTime?: QueryObserverOptions<Array<TItem>, TError, Array<TItem>, Array<TItem>, TQueryKey>[`staleTime`];
+    id?: string;
+    getKey: CollectionConfig<TItem>[`getKey`];
+    schema?: CollectionConfig<TItem>[`schema`];
+    sync?: CollectionConfig<TItem>[`sync`];
+    startSync?: CollectionConfig<TItem>[`startSync`];
+    /**
+     * Optional asynchronous handler function called before an insert operation
+     * @param params Object containing transaction and collection information
+     * @returns Promise resolving to void or { refetch?: boolean } to control refetching
+     * @example
+     * // Basic query collection insert handler
+     * onInsert: async ({ transaction }) => {
+     *   const newItem = transaction.mutations[0].modified
+     *   await api.createTodo(newItem)
+     *   // Automatically refetches query after insert
+     * }
+     *
+     * @example
+     * // Insert handler with refetch control
+     * onInsert: async ({ transaction }) => {
+     *   const newItem = transaction.mutations[0].modified
+     *   await api.createTodo(newItem)
+     *   return { refetch: false } // Skip automatic refetch
+     * }
+     *
+     * @example
+     * // Insert handler with multiple items
+     * onInsert: async ({ transaction }) => {
+     *   const items = transaction.mutations.map(m => m.modified)
+     *   await api.createTodos(items)
+     *   // Will refetch query to get updated data
+     * }
+     *
+     * @example
+     * // Insert handler with error handling
+     * onInsert: async ({ transaction }) => {
+     *   try {
+     *     const newItem = transaction.mutations[0].modified
+     *     await api.createTodo(newItem)
+     *   } catch (error) {
+     *     console.error('Insert failed:', error)
+     *     throw error // Transaction will rollback optimistic changes
+     *   }
+     * }
+     */
+    onInsert?: InsertMutationFn<TItem>;
+    /**
+     * Optional asynchronous handler function called before an update operation
+     * @param params Object containing transaction and collection information
+     * @returns Promise resolving to void or { refetch?: boolean } to control refetching
+     * @example
+     * // Basic query collection update handler
+     * onUpdate: async ({ transaction }) => {
+     *   const mutation = transaction.mutations[0]
+     *   await api.updateTodo(mutation.original.id, mutation.changes)
+     *   // Automatically refetches query after update
+     * }
+     *
+     * @example
+     * // Update handler with multiple items
+     * onUpdate: async ({ transaction }) => {
+     *   const updates = transaction.mutations.map(m => ({
+     *     id: m.key,
+     *     changes: m.changes
+     *   }))
+     *   await api.updateTodos(updates)
+     *   // Will refetch query to get updated data
+     * }
+     *
+     * @example
+     * // Update handler with manual refetch
+     * onUpdate: async ({ transaction, collection }) => {
+     *   const mutation = transaction.mutations[0]
+     *   await api.updateTodo(mutation.original.id, mutation.changes)
+     *
+     *   // Manually trigger refetch
+     *   await collection.utils.refetch()
+     *
+     *   return { refetch: false } // Skip automatic refetch
+     * }
+     *
+     * @example
+     * // Update handler with related collection refetch
+     * onUpdate: async ({ transaction, collection }) => {
+     *   const mutation = transaction.mutations[0]
+     *   await api.updateTodo(mutation.original.id, mutation.changes)
+     *
+     *   // Refetch related collections when this item changes
+     *   await Promise.all([
+     *     collection.utils.refetch(), // Refetch this collection
+     *     usersCollection.utils.refetch(), // Refetch users
+     *     tagsCollection.utils.refetch() // Refetch tags
+     *   ])
+     *
+     *   return { refetch: false } // Skip automatic refetch since we handled it manually
+     * }
+     */
+    onUpdate?: UpdateMutationFn<TItem>;
+    /**
+     * Optional asynchronous handler function called before a delete operation
+     * @param params Object containing transaction and collection information
+     * @returns Promise resolving to void or { refetch?: boolean } to control refetching
+     * @example
+     * // Basic query collection delete handler
+     * onDelete: async ({ transaction }) => {
+     *   const mutation = transaction.mutations[0]
+     *   await api.deleteTodo(mutation.original.id)
+     *   // Automatically refetches query after delete
+     * }
+     *
+     * @example
+     * // Delete handler with refetch control
+     * onDelete: async ({ transaction }) => {
+     *   const mutation = transaction.mutations[0]
+     *   await api.deleteTodo(mutation.original.id)
+     *   return { refetch: false } // Skip automatic refetch
+     * }
+     *
+     * @example
+     * // Delete handler with multiple items
+     * onDelete: async ({ transaction }) => {
+     *   const keysToDelete = transaction.mutations.map(m => m.key)
+     *   await api.deleteTodos(keysToDelete)
+     *   // Will refetch query to get updated data
+     * }
+     *
+     * @example
+     * // Delete handler with related collection refetch
+     * onDelete: async ({ transaction, collection }) => {
+     *   const mutation = transaction.mutations[0]
+     *   await api.deleteTodo(mutation.original.id)
+     *
+     *   // Refetch related collections when this item is deleted
+     *   await Promise.all([
+     *     collection.utils.refetch(), // Refetch this collection
+     *     usersCollection.utils.refetch(), // Refetch users
+     *     projectsCollection.utils.refetch() // Refetch projects
+     *   ])
+     *
+     *   return { refetch: false } // Skip automatic refetch since we handled it manually
+     * }
+     */
+    onDelete?: DeleteMutationFn<TItem>;
+}
+/**
+ * Type for the refetch utility function
+ */
+export type RefetchFn = () => Promise<void>;
+/**
+ * Query collection utilities type
+ */
+export interface QueryCollectionUtils extends UtilsRecord {
+    refetch: RefetchFn;
+}
+/**
+ * Creates query collection options for use with a standard Collection
+ *
+ * @param config - Configuration options for the Query collection
+ * @returns Collection options with utilities
+ */
+export declare function queryCollectionOptions<TItem extends object, TError = unknown, TQueryKey extends QueryKey = QueryKey>(config: QueryCollectionConfig<TItem, TError, TQueryKey>): CollectionConfig<TItem> & {
+    utils: QueryCollectionUtils;
+};

package/dist/esm/index.d.ts

@@ -0,0 +1 @@
+export { queryCollectionOptions, type QueryCollectionConfig, type QueryCollectionUtils, } from './query.js';

package/dist/esm/index.js

@@ -0,0 +1,5 @@
+import { queryCollectionOptions } from "./query.js";
+export {
+  queryCollectionOptions
+};
+//# sourceMappingURL=index.js.map

package/dist/esm/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sources":[],"sourcesContent":[],"names":[],"mappings":";"}

package/dist/esm/query.d.ts

@@ -0,0 +1,174 @@
+import { QueryClient, QueryFunctionContext, QueryKey, QueryObserverOptions } from '@tanstack/query-core';
+import { CollectionConfig, DeleteMutationFn, InsertMutationFn, UpdateMutationFn, UtilsRecord } from '@tanstack/db';
+export interface QueryCollectionConfig<TItem extends object, TError = unknown, TQueryKey extends QueryKey = QueryKey> {
+    queryKey: TQueryKey;
+    queryFn: (context: QueryFunctionContext<TQueryKey>) => Promise<Array<TItem>>;
+    queryClient: QueryClient;
+    enabled?: boolean;
+    refetchInterval?: QueryObserverOptions<Array<TItem>, TError, Array<TItem>, Array<TItem>, TQueryKey>[`refetchInterval`];
+    retry?: QueryObserverOptions<Array<TItem>, TError, Array<TItem>, Array<TItem>, TQueryKey>[`retry`];
+    retryDelay?: QueryObserverOptions<Array<TItem>, TError, Array<TItem>, Array<TItem>, TQueryKey>[`retryDelay`];
+    staleTime?: QueryObserverOptions<Array<TItem>, TError, Array<TItem>, Array<TItem>, TQueryKey>[`staleTime`];
+    id?: string;
+    getKey: CollectionConfig<TItem>[`getKey`];
+    schema?: CollectionConfig<TItem>[`schema`];
+    sync?: CollectionConfig<TItem>[`sync`];
+    startSync?: CollectionConfig<TItem>[`startSync`];
+    /**
+     * Optional asynchronous handler function called before an insert operation
+     * @param params Object containing transaction and collection information
+     * @returns Promise resolving to void or { refetch?: boolean } to control refetching
+     * @example
+     * // Basic query collection insert handler
+     * onInsert: async ({ transaction }) => {
+     *   const newItem = transaction.mutations[0].modified
+     *   await api.createTodo(newItem)
+     *   // Automatically refetches query after insert
+     * }
+     *
+     * @example
+     * // Insert handler with refetch control
+     * onInsert: async ({ transaction }) => {
+     *   const newItem = transaction.mutations[0].modified
+     *   await api.createTodo(newItem)
+     *   return { refetch: false } // Skip automatic refetch
+     * }
+     *
+     * @example
+     * // Insert handler with multiple items
+     * onInsert: async ({ transaction }) => {
+     *   const items = transaction.mutations.map(m => m.modified)
+     *   await api.createTodos(items)
+     *   // Will refetch query to get updated data
+     * }
+     *
+     * @example
+     * // Insert handler with error handling
+     * onInsert: async ({ transaction }) => {
+     *   try {
+     *     const newItem = transaction.mutations[0].modified
+     *     await api.createTodo(newItem)
+     *   } catch (error) {
+     *     console.error('Insert failed:', error)
+     *     throw error // Transaction will rollback optimistic changes
+     *   }
+     * }
+     */
+    onInsert?: InsertMutationFn<TItem>;
+    /**
+     * Optional asynchronous handler function called before an update operation
+     * @param params Object containing transaction and collection information
+     * @returns Promise resolving to void or { refetch?: boolean } to control refetching
+     * @example
+     * // Basic query collection update handler
+     * onUpdate: async ({ transaction }) => {
+     *   const mutation = transaction.mutations[0]
+     *   await api.updateTodo(mutation.original.id, mutation.changes)
+     *   // Automatically refetches query after update
+     * }
+     *
+     * @example
+     * // Update handler with multiple items
+     * onUpdate: async ({ transaction }) => {
+     *   const updates = transaction.mutations.map(m => ({
+     *     id: m.key,
+     *     changes: m.changes
+     *   }))
+     *   await api.updateTodos(updates)
+     *   // Will refetch query to get updated data
+     * }
+     *
+     * @example
+     * // Update handler with manual refetch
+     * onUpdate: async ({ transaction, collection }) => {
+     *   const mutation = transaction.mutations[0]
+     *   await api.updateTodo(mutation.original.id, mutation.changes)
+     *
+     *   // Manually trigger refetch
+     *   await collection.utils.refetch()
+     *
+     *   return { refetch: false } // Skip automatic refetch
+     * }
+     *
+     * @example
+     * // Update handler with related collection refetch
+     * onUpdate: async ({ transaction, collection }) => {
+     *   const mutation = transaction.mutations[0]
+     *   await api.updateTodo(mutation.original.id, mutation.changes)
+     *
+     *   // Refetch related collections when this item changes
+     *   await Promise.all([
+     *     collection.utils.refetch(), // Refetch this collection
+     *     usersCollection.utils.refetch(), // Refetch users
+     *     tagsCollection.utils.refetch() // Refetch tags
+     *   ])
+     *
+     *   return { refetch: false } // Skip automatic refetch since we handled it manually
+     * }
+     */
+    onUpdate?: UpdateMutationFn<TItem>;
+    /**
+     * Optional asynchronous handler function called before a delete operation
+     * @param params Object containing transaction and collection information
+     * @returns Promise resolving to void or { refetch?: boolean } to control refetching
+     * @example
+     * // Basic query collection delete handler
+     * onDelete: async ({ transaction }) => {
+     *   const mutation = transaction.mutations[0]
+     *   await api.deleteTodo(mutation.original.id)
+     *   // Automatically refetches query after delete
+     * }
+     *
+     * @example
+     * // Delete handler with refetch control
+     * onDelete: async ({ transaction }) => {
+     *   const mutation = transaction.mutations[0]
+     *   await api.deleteTodo(mutation.original.id)
+     *   return { refetch: false } // Skip automatic refetch
+     * }
+     *
+     * @example
+     * // Delete handler with multiple items
+     * onDelete: async ({ transaction }) => {
+     *   const keysToDelete = transaction.mutations.map(m => m.key)
+     *   await api.deleteTodos(keysToDelete)
+     *   // Will refetch query to get updated data
+     * }
+     *
+     * @example
+     * // Delete handler with related collection refetch
+     * onDelete: async ({ transaction, collection }) => {
+     *   const mutation = transaction.mutations[0]
+     *   await api.deleteTodo(mutation.original.id)
+     *
+     *   // Refetch related collections when this item is deleted
+     *   await Promise.all([
+     *     collection.utils.refetch(), // Refetch this collection
+     *     usersCollection.utils.refetch(), // Refetch users
+     *     projectsCollection.utils.refetch() // Refetch projects
+     *   ])
+     *
+     *   return { refetch: false } // Skip automatic refetch since we handled it manually
+     * }
+     */
+    onDelete?: DeleteMutationFn<TItem>;
+}
+/**
+ * Type for the refetch utility function
+ */
+export type RefetchFn = () => Promise<void>;
+/**
+ * Query collection utilities type
+ */
+export interface QueryCollectionUtils extends UtilsRecord {
+    refetch: RefetchFn;
+}
+/**
+ * Creates query collection options for use with a standard Collection
+ *
+ * @param config - Configuration options for the Query collection
+ * @returns Collection options with utilities
+ */
+export declare function queryCollectionOptions<TItem extends object, TError = unknown, TQueryKey extends QueryKey = QueryKey>(config: QueryCollectionConfig<TItem, TError, TQueryKey>): CollectionConfig<TItem> & {
+    utils: QueryCollectionUtils;
+};

package/dist/esm/query.js

@@ -0,0 +1,147 @@
+import { QueryObserver } from "@tanstack/query-core";
+function queryCollectionOptions(config) {
+  const {
+    queryKey,
+    queryFn,
+    queryClient,
+    enabled,
+    refetchInterval,
+    retry,
+    retryDelay,
+    staleTime,
+    getKey,
+    onInsert,
+    onUpdate,
+    onDelete,
+    ...baseCollectionConfig
+  } = config;
+  if (!queryKey) {
+    throw new Error(`[QueryCollection] queryKey must be provided.`);
+  }
+  if (!queryFn) {
+    throw new Error(`[QueryCollection] queryFn must be provided.`);
+  }
+  if (!queryClient) {
+    throw new Error(`[QueryCollection] queryClient must be provided.`);
+  }
+  if (!getKey) {
+    throw new Error(`[QueryCollection] getKey must be provided.`);
+  }
+  const internalSync = (params) => {
+    const { begin, write, commit, collection } = params;
+    const observerOptions = {
+      queryKey,
+      queryFn,
+      enabled,
+      refetchInterval,
+      retry,
+      retryDelay,
+      staleTime,
+      structuralSharing: true,
+      notifyOnChangeProps: `all`
+    };
+    const localObserver = new QueryObserver(queryClient, observerOptions);
+    const actualUnsubscribeFn = localObserver.subscribe((result) => {
+      if (result.isSuccess) {
+        const newItemsArray = result.data;
+        if (!Array.isArray(newItemsArray) || newItemsArray.some((item) => typeof item !== `object`)) {
+          console.error(
+            `[QueryCollection] queryFn did not return an array of objects. Skipping update.`,
+            newItemsArray
+          );
+          return;
+        }
+        const currentSyncedItems = new Map(collection.syncedData);
+        const newItemsMap = /* @__PURE__ */ new Map();
+        newItemsArray.forEach((item) => {
+          const key = getKey(item);
+          newItemsMap.set(key, item);
+        });
+        begin();
+        const shallowEqual = (obj1, obj2) => {
+          const keys1 = Object.keys(obj1);
+          const keys2 = Object.keys(obj2);
+          if (keys1.length !== keys2.length) return false;
+          return keys1.every((key) => {
+            if (typeof obj1[key] === `function`) return true;
+            if (typeof obj1[key] === `object` && obj1[key] !== null) {
+              return obj1[key] === obj2[key];
+            }
+            return obj1[key] === obj2[key];
+          });
+        };
+        currentSyncedItems.forEach((oldItem, key) => {
+          const newItem = newItemsMap.get(key);
+          if (!newItem) {
+            write({ type: `delete`, value: oldItem });
+          } else if (!shallowEqual(
+            oldItem,
+            newItem
+          )) {
+            write({ type: `update`, value: newItem });
+          }
+        });
+        newItemsMap.forEach((newItem, key) => {
+          if (!currentSyncedItems.has(key)) {
+            write({ type: `insert`, value: newItem });
+          }
+        });
+        commit();
+      } else if (result.isError) {
+        console.error(
+          `[QueryCollection] Error observing query ${String(queryKey)}:`,
+          result.error
+        );
+      }
+    });
+    return async () => {
+      actualUnsubscribeFn();
+      await queryClient.cancelQueries({ queryKey });
+      queryClient.removeQueries({ queryKey });
+    };
+  };
+  const refetch = async () => {
+    return queryClient.refetchQueries({
+      queryKey
+    });
+  };
+  const wrappedOnInsert = onInsert ? async (params) => {
+    const handlerResult = await onInsert(params) ?? {};
+    const shouldRefetch = handlerResult.refetch !== false;
+    if (shouldRefetch) {
+      await refetch();
+    }
+    return handlerResult;
+  } : void 0;
+  const wrappedOnUpdate = onUpdate ? async (params) => {
+    const handlerResult = await onUpdate(params) ?? {};
+    const shouldRefetch = handlerResult.refetch !== false;
+    if (shouldRefetch) {
+      await refetch();
+    }
+    return handlerResult;
+  } : void 0;
+  const wrappedOnDelete = onDelete ? async (params) => {
+    const handlerResult = await onDelete(params) ?? {};
+    const shouldRefetch = handlerResult.refetch !== false;
+    if (shouldRefetch) {
+      await refetch();
+    }
+    return handlerResult;
+  } : void 0;
+  return {
+    ...baseCollectionConfig,
+    getKey,
+    sync: { sync: internalSync },
+    onInsert: wrappedOnInsert,
+    onUpdate: wrappedOnUpdate,
+    onDelete: wrappedOnDelete,
+    utils: {
+      refetch
+    }
+  };
+}
+export {
+  queryCollectionOptions
+};
+//# sourceMappingURL=query.js.map

package/dist/esm/query.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"query.js","sources":["../../src/query.ts"],"sourcesContent":["import { QueryObserver } from \"@tanstack/query-core\"\nimport type {\n  QueryClient,\n  QueryFunctionContext,\n  QueryKey,\n  QueryObserverOptions,\n} from \"@tanstack/query-core\"\nimport type {\n  CollectionConfig,\n  DeleteMutationFn,\n  DeleteMutationFnParams,\n  InsertMutationFn,\n  InsertMutationFnParams,\n  SyncConfig,\n  UpdateMutationFn,\n  UpdateMutationFnParams,\n  UtilsRecord,\n} from \"@tanstack/db\"\n\nexport interface QueryCollectionConfig<\n  TItem extends object,\n  TError = unknown,\n  TQueryKey extends QueryKey = QueryKey,\n> {\n  queryKey: TQueryKey\n  queryFn: (context: QueryFunctionContext<TQueryKey>) => Promise<Array<TItem>>\n  queryClient: QueryClient\n\n  // Query-specific options\n  enabled?: boolean\n  refetchInterval?: QueryObserverOptions<\n    Array<TItem>,\n    TError,\n    Array<TItem>,\n    Array<TItem>,\n    TQueryKey\n  >[`refetchInterval`]\n  retry?: QueryObserverOptions<\n    Array<TItem>,\n    TError,\n    Array<TItem>,\n    Array<TItem>,\n    TQueryKey\n  >[`retry`]\n  retryDelay?: QueryObserverOptions<\n    Array<TItem>,\n    TError,\n    Array<TItem>,\n    Array<TItem>,\n    TQueryKey\n  >[`retryDelay`]\n  staleTime?: QueryObserverOptions<\n    Array<TItem>,\n    TError,\n    Array<TItem>,\n    Array<TItem>,\n    TQueryKey\n  >[`staleTime`]\n\n  // Standard Collection configuration properties\n  id?: string\n  getKey: CollectionConfig<TItem>[`getKey`]\n  schema?: CollectionConfig<TItem>[`schema`]\n  sync?: CollectionConfig<TItem>[`sync`]\n  startSync?: CollectionConfig<TItem>[`startSync`]\n\n  // Direct persistence handlers\n  /**\n   * Optional asynchronous handler function called before an insert operation\n   * @param params Object containing transaction and collection information\n   * @returns Promise resolving to void or { refetch?: boolean } to control refetching\n   * @example\n   * // Basic query collection insert handler\n   * onInsert: async ({ transaction }) => {\n   *   const newItem = transaction.mutations[0].modified\n   *   await api.createTodo(newItem)\n   *   // Automatically refetches query after insert\n   * }\n   *\n   * @example\n   * // Insert handler with refetch control\n   * onInsert: async ({ transaction }) => {\n   *   const newItem = transaction.mutations[0].modified\n   *   await api.createTodo(newItem)\n   *   return { refetch: false } // Skip automatic refetch\n   * }\n   *\n   * @example\n   * // Insert handler with multiple items\n   * onInsert: async ({ transaction }) => {\n   *   const items = transaction.mutations.map(m => m.modified)\n   *   await api.createTodos(items)\n   *   // Will refetch query to get updated data\n   * }\n   *\n   * @example\n   * // Insert handler with error handling\n   * onInsert: async ({ transaction }) => {\n   *   try {\n   *     const newItem = transaction.mutations[0].modified\n   *     await api.createTodo(newItem)\n   *   } catch (error) {\n   *     console.error('Insert failed:', error)\n   *     throw error // Transaction will rollback optimistic changes\n   *   }\n   * }\n   */\n  onInsert?: InsertMutationFn<TItem>\n\n  /**\n   * Optional asynchronous handler function called before an update operation\n   * @param params Object containing transaction and collection information\n   * @returns Promise resolving to void or { refetch?: boolean } to control refetching\n   * @example\n   * // Basic query collection update handler\n   * onUpdate: async ({ transaction }) => {\n   *   const mutation = transaction.mutations[0]\n   *   await api.updateTodo(mutation.original.id, mutation.changes)\n   *   // Automatically refetches query after update\n   * }\n   *\n   * @example\n   * // Update handler with multiple items\n   * onUpdate: async ({ transaction }) => {\n   *   const updates = transaction.mutations.map(m => ({\n   *     id: m.key,\n   *     changes: m.changes\n   *   }))\n   *   await api.updateTodos(updates)\n   *   // Will refetch query to get updated data\n   * }\n   *\n   * @example\n   * // Update handler with manual refetch\n   * onUpdate: async ({ transaction, collection }) => {\n   *   const mutation = transaction.mutations[0]\n   *   await api.updateTodo(mutation.original.id, mutation.changes)\n   *\n   *   // Manually trigger refetch\n   *   await collection.utils.refetch()\n   *\n   *   return { refetch: false } // Skip automatic refetch\n   * }\n   *\n   * @example\n   * // Update handler with related collection refetch\n   * onUpdate: async ({ transaction, collection }) => {\n   *   const mutation = transaction.mutations[0]\n   *   await api.updateTodo(mutation.original.id, mutation.changes)\n   *\n   *   // Refetch related collections when this item changes\n   *   await Promise.all([\n   *     collection.utils.refetch(), // Refetch this collection\n   *     usersCollection.utils.refetch(), // Refetch users\n   *     tagsCollection.utils.refetch() // Refetch tags\n   *   ])\n   *\n   *   return { refetch: false } // Skip automatic refetch since we handled it manually\n   * }\n   */\n  onUpdate?: UpdateMutationFn<TItem>\n\n  /**\n   * Optional asynchronous handler function called before a delete operation\n   * @param params Object containing transaction and collection information\n   * @returns Promise resolving to void or { refetch?: boolean } to control refetching\n   * @example\n   * // Basic query collection delete handler\n   * onDelete: async ({ transaction }) => {\n   *   const mutation = transaction.mutations[0]\n   *   await api.deleteTodo(mutation.original.id)\n   *   // Automatically refetches query after delete\n   * }\n   *\n   * @example\n   * // Delete handler with refetch control\n   * onDelete: async ({ transaction }) => {\n   *   const mutation = transaction.mutations[0]\n   *   await api.deleteTodo(mutation.original.id)\n   *   return { refetch: false } // Skip automatic refetch\n   * }\n   *\n   * @example\n   * // Delete handler with multiple items\n   * onDelete: async ({ transaction }) => {\n   *   const keysToDelete = transaction.mutations.map(m => m.key)\n   *   await api.deleteTodos(keysToDelete)\n   *   // Will refetch query to get updated data\n   * }\n   *\n   * @example\n   * // Delete handler with related collection refetch\n   * onDelete: async ({ transaction, collection }) => {\n   *   const mutation = transaction.mutations[0]\n   *   await api.deleteTodo(mutation.original.id)\n   *\n   *   // Refetch related collections when this item is deleted\n   *   await Promise.all([\n   *     collection.utils.refetch(), // Refetch this collection\n   *     usersCollection.utils.refetch(), // Refetch users\n   *     projectsCollection.utils.refetch() // Refetch projects\n   *   ])\n   *\n   *   return { refetch: false } // Skip automatic refetch since we handled it manually\n   * }\n   */\n  onDelete?: DeleteMutationFn<TItem>\n  // TODO type returning { refetch: boolean }\n}\n\n/**\n * Type for the refetch utility function\n */\nexport type RefetchFn = () => Promise<void>\n\n/**\n * Query collection utilities type\n */\nexport interface QueryCollectionUtils extends UtilsRecord {\n  refetch: RefetchFn\n}\n\n/**\n * Creates query collection options for use with a standard Collection\n *\n * @param config - Configuration options for the Query collection\n * @returns Collection options with utilities\n */\nexport function queryCollectionOptions<\n  TItem extends object,\n  TError = unknown,\n  TQueryKey extends QueryKey = QueryKey,\n>(\n  config: QueryCollectionConfig<TItem, TError, TQueryKey>\n): CollectionConfig<TItem> & { utils: QueryCollectionUtils } {\n  const {\n    queryKey,\n    queryFn,\n    queryClient,\n    enabled,\n    refetchInterval,\n    retry,\n    retryDelay,\n    staleTime,\n    getKey,\n    onInsert,\n    onUpdate,\n    onDelete,\n    ...baseCollectionConfig\n  } = config\n\n  // Validate required parameters\n\n  // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition\n  if (!queryKey) {\n    throw new Error(`[QueryCollection] queryKey must be provided.`)\n  }\n  // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition\n  if (!queryFn) {\n    throw new Error(`[QueryCollection] queryFn must be provided.`)\n  }\n\n  // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition\n  if (!queryClient) {\n    throw new Error(`[QueryCollection] queryClient must be provided.`)\n  }\n\n  if (!getKey) {\n    throw new Error(`[QueryCollection] getKey must be provided.`)\n  }\n\n  const internalSync: SyncConfig<TItem>[`sync`] = (params) => {\n    const { begin, write, commit, collection } = params\n\n    const observerOptions: QueryObserverOptions<\n      Array<TItem>,\n      TError,\n      Array<TItem>,\n      Array<TItem>,\n      TQueryKey\n    > = {\n      queryKey: queryKey,\n      queryFn: queryFn,\n      enabled: enabled,\n      refetchInterval: refetchInterval,\n      retry: retry,\n      retryDelay: retryDelay,\n      staleTime: staleTime,\n      structuralSharing: true,\n      notifyOnChangeProps: `all`,\n    }\n\n    const localObserver = new QueryObserver<\n      Array<TItem>,\n      TError,\n      Array<TItem>,\n      Array<TItem>,\n      TQueryKey\n    >(queryClient, observerOptions)\n\n    const actualUnsubscribeFn = localObserver.subscribe((result) => {\n      if (result.isSuccess) {\n        const newItemsArray = result.data\n\n        if (\n          !Array.isArray(newItemsArray) ||\n          newItemsArray.some((item) => typeof item !== `object`)\n        ) {\n          console.error(\n            `[QueryCollection] queryFn did not return an array of objects. Skipping update.`,\n            newItemsArray\n          )\n          return\n        }\n\n        const currentSyncedItems = new Map(collection.syncedData)\n        const newItemsMap = new Map<string | number, TItem>()\n        newItemsArray.forEach((item) => {\n          const key = getKey(item)\n          newItemsMap.set(key, item)\n        })\n\n        begin()\n\n        // Helper function for shallow equality check of objects\n        const shallowEqual = (\n          obj1: Record<string, any>,\n          obj2: Record<string, any>\n        ): boolean => {\n          // Get all keys from both objects\n          const keys1 = Object.keys(obj1)\n          const keys2 = Object.keys(obj2)\n\n          // If number of keys is different, objects are not equal\n          if (keys1.length !== keys2.length) return false\n\n          // Check if all keys in obj1 have the same values in obj2\n          return keys1.every((key) => {\n            // Skip comparing functions and complex objects deeply\n            if (typeof obj1[key] === `function`) return true\n            if (typeof obj1[key] === `object` && obj1[key] !== null) {\n              // For nested objects, just compare references\n              // A more robust solution might do recursive shallow comparison\n              // or let users provide a custom equality function\n              return obj1[key] === obj2[key]\n            }\n            return obj1[key] === obj2[key]\n          })\n        }\n\n        currentSyncedItems.forEach((oldItem, key) => {\n          const newItem = newItemsMap.get(key)\n          if (!newItem) {\n            write({ type: `delete`, value: oldItem })\n          } else if (\n            !shallowEqual(\n              oldItem as Record<string, any>,\n              newItem as Record<string, any>\n            )\n          ) {\n            // Only update if there are actual differences in the properties\n            write({ type: `update`, value: newItem })\n          }\n        })\n\n        newItemsMap.forEach((newItem, key) => {\n          if (!currentSyncedItems.has(key)) {\n            write({ type: `insert`, value: newItem })\n          }\n        })\n\n        commit()\n      } else if (result.isError) {\n        console.error(\n          `[QueryCollection] Error observing query ${String(queryKey)}:`,\n          result.error\n        )\n      }\n    })\n\n    return async () => {\n      actualUnsubscribeFn()\n      await queryClient.cancelQueries({ queryKey })\n      queryClient.removeQueries({ queryKey })\n    }\n  }\n\n  /**\n   * Refetch the query data\n   * @returns Promise that resolves when the refetch is complete\n   */\n  const refetch: RefetchFn = async (): Promise<void> => {\n    return queryClient.refetchQueries({\n      queryKey: queryKey,\n    })\n  }\n\n  // Create wrapper handlers for direct persistence operations that handle refetching\n  const wrappedOnInsert = onInsert\n    ? async (params: InsertMutationFnParams<TItem>) => {\n        const handlerResult = (await onInsert(params)) ?? {}\n        const shouldRefetch =\n          (handlerResult as { refetch?: boolean }).refetch !== false\n\n        if (shouldRefetch) {\n          await refetch()\n        }\n\n        return handlerResult\n      }\n    : undefined\n\n  const wrappedOnUpdate = onUpdate\n    ? async (params: UpdateMutationFnParams<TItem>) => {\n        const handlerResult = (await onUpdate(params)) ?? {}\n        const shouldRefetch =\n          (handlerResult as { refetch?: boolean }).refetch !== false\n\n        if (shouldRefetch) {\n          await refetch()\n        }\n\n        return handlerResult\n      }\n    : undefined\n\n  const wrappedOnDelete = onDelete\n    ? async (params: DeleteMutationFnParams<TItem>) => {\n        const handlerResult = (await onDelete(params)) ?? {}\n        const shouldRefetch =\n          (handlerResult as { refetch?: boolean }).refetch !== false\n\n        if (shouldRefetch) {\n          await refetch()\n        }\n\n        return handlerResult\n      }\n    : undefined\n\n  return {\n    ...baseCollectionConfig,\n    getKey,\n    sync: { sync: internalSync },\n    onInsert: wrappedOnInsert,\n    onUpdate: wrappedOnUpdate,\n    onDelete: wrappedOnDelete,\n    utils: {\n      refetch,\n    },\n  }\n}\n"],"names":[],"mappings":"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"}

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "@tanstack/query-db-collection",
   "description": "TanStack Query collection for TanStack DB",
-  "version": "0.0.2",
+  "version": "0.0.4",
   "dependencies": {
-    "@tanstack/db": "workspace:*",
-    "@tanstack/query-core": "^5.75.7"
+    "@tanstack/query-core": "^5.75.7",
+    "@tanstack/db": "0.0.22"
   },
   "devDependencies": {
     "@vitest/coverage-istanbul": "^3.0.9"
@@ -28,7 +28,6 @@
   ],
   "main": "dist/cjs/index.cjs",
   "module": "dist/esm/index.js",
-  "packageManager": "pnpm@10.6.3",
   "peerDependencies": {
     "typescript": ">=4.7"
   },
@@ -46,14 +45,13 @@
     "optimistic",
     "typescript"
   ],
+  "sideEffects": false,
+  "type": "module",
+  "types": "dist/esm/index.d.ts",
   "scripts": {
     "build": "vite build",
     "dev": "vite build --watch",
     "lint": "eslint . --fix",
     "test": "npx vitest --run"
-  },
-  "sideEffects": false,
-  "type": "module",
-  "types": "dist/esm/index.d.ts"
-}
-
+  }
+}

package/src/query.ts

@@ -265,7 +265,6 @@ export function queryCollectionOptions<
     throw new Error(`[QueryCollection] queryClient must be provided.`)
   }
 
-  // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
   if (!getKey) {
     throw new Error(`[QueryCollection] getKey must be provided.`)
   }