@tanstack/query-db-collection 0.0.9 → 0.0.12

package/dist/cjs/errors.cjs

@@ -0,0 +1,39 @@
+"use strict";
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const db = require("@tanstack/db");
+class QueryCollectionError extends db.TanStackDBError {
+  constructor(message) {
+    super(message);
+    this.name = `QueryCollectionError`;
+  }
+}
+class QueryKeyRequiredError extends QueryCollectionError {
+  constructor() {
+    super(`[QueryCollection] queryKey must be provided.`);
+    this.name = `QueryKeyRequiredError`;
+  }
+}
+class QueryFnRequiredError extends QueryCollectionError {
+  constructor() {
+    super(`[QueryCollection] queryFn must be provided.`);
+    this.name = `QueryFnRequiredError`;
+  }
+}
+class QueryClientRequiredError extends QueryCollectionError {
+  constructor() {
+    super(`[QueryCollection] queryClient must be provided.`);
+    this.name = `QueryClientRequiredError`;
+  }
+}
+class GetKeyRequiredError extends QueryCollectionError {
+  constructor() {
+    super(`[QueryCollection] getKey must be provided.`);
+    this.name = `GetKeyRequiredError`;
+  }
+}
+exports.GetKeyRequiredError = GetKeyRequiredError;
+exports.QueryClientRequiredError = QueryClientRequiredError;
+exports.QueryCollectionError = QueryCollectionError;
+exports.QueryFnRequiredError = QueryFnRequiredError;
+exports.QueryKeyRequiredError = QueryKeyRequiredError;
+//# sourceMappingURL=errors.cjs.map

package/dist/cjs/errors.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.cjs","sources":["../../src/errors.ts"],"sourcesContent":["import { TanStackDBError } from \"@tanstack/db\"\n\n// Query Collection Errors\nexport class QueryCollectionError extends TanStackDBError {\n  constructor(message: string) {\n    super(message)\n    this.name = `QueryCollectionError`\n  }\n}\n\nexport class QueryKeyRequiredError extends QueryCollectionError {\n  constructor() {\n    super(`[QueryCollection] queryKey must be provided.`)\n    this.name = `QueryKeyRequiredError`\n  }\n}\n\nexport class QueryFnRequiredError extends QueryCollectionError {\n  constructor() {\n    super(`[QueryCollection] queryFn must be provided.`)\n    this.name = `QueryFnRequiredError`\n  }\n}\n\nexport class QueryClientRequiredError extends QueryCollectionError {\n  constructor() {\n    super(`[QueryCollection] queryClient must be provided.`)\n    this.name = `QueryClientRequiredError`\n  }\n}\n\nexport class GetKeyRequiredError extends QueryCollectionError {\n  constructor() {\n    super(`[QueryCollection] getKey must be provided.`)\n    this.name = `GetKeyRequiredError`\n  }\n}\n"],"names":["TanStackDBError"],"mappings":";;;AAGO,MAAM,6BAA6BA,GAAAA,gBAAgB;AAAA,EACxD,YAAY,SAAiB;AAC3B,UAAM,OAAO;AACb,SAAK,OAAO;AAAA,EACd;AACF;AAEO,MAAM,8BAA8B,qBAAqB;AAAA,EAC9D,cAAc;AACZ,UAAM,8CAA8C;AACpD,SAAK,OAAO;AAAA,EACd;AACF;AAEO,MAAM,6BAA6B,qBAAqB;AAAA,EAC7D,cAAc;AACZ,UAAM,6CAA6C;AACnD,SAAK,OAAO;AAAA,EACd;AACF;AAEO,MAAM,iCAAiC,qBAAqB;AAAA,EACjE,cAAc;AACZ,UAAM,iDAAiD;AACvD,SAAK,OAAO;AAAA,EACd;AACF;AAEO,MAAM,4BAA4B,qBAAqB;AAAA,EAC5D,cAAc;AACZ,UAAM,4CAA4C;AAClD,SAAK,OAAO;AAAA,EACd;AACF;;;;;;"}

package/dist/cjs/errors.d.cts

@@ -0,0 +1,16 @@
+import { TanStackDBError } from '@tanstack/db';
+export declare class QueryCollectionError extends TanStackDBError {
+    constructor(message: string);
+}
+export declare class QueryKeyRequiredError extends QueryCollectionError {
+    constructor();
+}
+export declare class QueryFnRequiredError extends QueryCollectionError {
+    constructor();
+}
+export declare class QueryClientRequiredError extends QueryCollectionError {
+    constructor();
+}
+export declare class GetKeyRequiredError extends QueryCollectionError {
+    constructor();
+}

package/dist/cjs/index.cjs

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

package/dist/cjs/index.cjs.map

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

package/dist/cjs/index.d.cts

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

package/dist/cjs/query.cjs

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 const queryCore = require("@tanstack/query-core");
+const errors = require("./errors.cjs");
 function queryCollectionOptions(config) {
   const {
     queryKey,
@@ -18,16 +19,16 @@ function queryCollectionOptions(config) {
     ...baseCollectionConfig
   } = config;
   if (!queryKey) {
-    throw new Error(`[QueryCollection] queryKey must be provided.`);
+    throw new errors.QueryKeyRequiredError();
   }
   if (!queryFn) {
-    throw new Error(`[QueryCollection] queryFn must be provided.`);
+    throw new errors.QueryFnRequiredError();
   }
   if (!queryClient) {
-    throw new Error(`[QueryCollection] queryClient must be provided.`);
+    throw new errors.QueryClientRequiredError();
   }
   if (!getKey) {
-    throw new Error(`[QueryCollection] getKey must be provided.`);
+    throw new errors.GetKeyRequiredError();
   }
   const internalSync = (params) => {
     const { begin, write, commit, markReady, collection } = params;

package/dist/cjs/query.cjs.map

@@ -1 +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, markReady, 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\n        // Mark collection as ready after first successful query result\n        markReady()\n      } else if (result.isError) {\n        console.error(\n          `[QueryCollection] Error observing query ${String(queryKey)}:`,\n          result.error\n        )\n\n        // Mark collection as ready even on error to avoid blocking apps\n        markReady()\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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"}
+{"version":3,"file":"query.cjs","sources":["../../src/query.ts"],"sourcesContent":["import { QueryObserver } from \"@tanstack/query-core\"\nimport {\n  GetKeyRequiredError,\n  QueryClientRequiredError,\n  QueryFnRequiredError,\n  QueryKeyRequiredError,\n} from \"./errors\"\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 QueryKeyRequiredError()\n  }\n  // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition\n  if (!queryFn) {\n    throw new QueryFnRequiredError()\n  }\n\n  // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition\n  if (!queryClient) {\n    throw new QueryClientRequiredError()\n  }\n\n  if (!getKey) {\n    throw new GetKeyRequiredError()\n  }\n\n  const internalSync: SyncConfig<TItem>[`sync`] = (params) => {\n    const { begin, write, commit, markReady, 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\n        // Mark collection as ready after first successful query result\n        markReady()\n      } else if (result.isError) {\n        console.error(\n          `[QueryCollection] Error observing query ${String(queryKey)}:`,\n          result.error\n        )\n\n        // Mark collection as ready even on error to avoid blocking apps\n        markReady()\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":["QueryKeyRequiredError","QueryFnRequiredError","QueryClientRequiredError","GetKeyRequiredError","QueryObserver"],"mappings":"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"}

package/dist/esm/errors.d.ts

@@ -0,0 +1,16 @@
+import { TanStackDBError } from '@tanstack/db';
+export declare class QueryCollectionError extends TanStackDBError {
+    constructor(message: string);
+}
+export declare class QueryKeyRequiredError extends QueryCollectionError {
+    constructor();
+}
+export declare class QueryFnRequiredError extends QueryCollectionError {
+    constructor();
+}
+export declare class QueryClientRequiredError extends QueryCollectionError {
+    constructor();
+}
+export declare class GetKeyRequiredError extends QueryCollectionError {
+    constructor();
+}

package/dist/esm/errors.js

@@ -0,0 +1,39 @@
+import { TanStackDBError } from "@tanstack/db";
+class QueryCollectionError extends TanStackDBError {
+  constructor(message) {
+    super(message);
+    this.name = `QueryCollectionError`;
+  }
+}
+class QueryKeyRequiredError extends QueryCollectionError {
+  constructor() {
+    super(`[QueryCollection] queryKey must be provided.`);
+    this.name = `QueryKeyRequiredError`;
+  }
+}
+class QueryFnRequiredError extends QueryCollectionError {
+  constructor() {
+    super(`[QueryCollection] queryFn must be provided.`);
+    this.name = `QueryFnRequiredError`;
+  }
+}
+class QueryClientRequiredError extends QueryCollectionError {
+  constructor() {
+    super(`[QueryCollection] queryClient must be provided.`);
+    this.name = `QueryClientRequiredError`;
+  }
+}
+class GetKeyRequiredError extends QueryCollectionError {
+  constructor() {
+    super(`[QueryCollection] getKey must be provided.`);
+    this.name = `GetKeyRequiredError`;
+  }
+}
+export {
+  GetKeyRequiredError,
+  QueryClientRequiredError,
+  QueryCollectionError,
+  QueryFnRequiredError,
+  QueryKeyRequiredError
+};
+//# sourceMappingURL=errors.js.map

package/dist/esm/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sources":["../../src/errors.ts"],"sourcesContent":["import { TanStackDBError } from \"@tanstack/db\"\n\n// Query Collection Errors\nexport class QueryCollectionError extends TanStackDBError {\n  constructor(message: string) {\n    super(message)\n    this.name = `QueryCollectionError`\n  }\n}\n\nexport class QueryKeyRequiredError extends QueryCollectionError {\n  constructor() {\n    super(`[QueryCollection] queryKey must be provided.`)\n    this.name = `QueryKeyRequiredError`\n  }\n}\n\nexport class QueryFnRequiredError extends QueryCollectionError {\n  constructor() {\n    super(`[QueryCollection] queryFn must be provided.`)\n    this.name = `QueryFnRequiredError`\n  }\n}\n\nexport class QueryClientRequiredError extends QueryCollectionError {\n  constructor() {\n    super(`[QueryCollection] queryClient must be provided.`)\n    this.name = `QueryClientRequiredError`\n  }\n}\n\nexport class GetKeyRequiredError extends QueryCollectionError {\n  constructor() {\n    super(`[QueryCollection] getKey must be provided.`)\n    this.name = `GetKeyRequiredError`\n  }\n}\n"],"names":[],"mappings":";AAGO,MAAM,6BAA6B,gBAAgB;AAAA,EACxD,YAAY,SAAiB;AAC3B,UAAM,OAAO;AACb,SAAK,OAAO;AAAA,EACd;AACF;AAEO,MAAM,8BAA8B,qBAAqB;AAAA,EAC9D,cAAc;AACZ,UAAM,8CAA8C;AACpD,SAAK,OAAO;AAAA,EACd;AACF;AAEO,MAAM,6BAA6B,qBAAqB;AAAA,EAC7D,cAAc;AACZ,UAAM,6CAA6C;AACnD,SAAK,OAAO;AAAA,EACd;AACF;AAEO,MAAM,iCAAiC,qBAAqB;AAAA,EACjE,cAAc;AACZ,UAAM,iDAAiD;AACvD,SAAK,OAAO;AAAA,EACd;AACF;AAEO,MAAM,4BAA4B,qBAAqB;AAAA,EAC5D,cAAc;AACZ,UAAM,4CAA4C;AAClD,SAAK,OAAO;AAAA,EACd;AACF;"}

package/dist/esm/index.d.ts

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

package/dist/esm/index.js

@@ -1,5 +1,11 @@
 import { queryCollectionOptions } from "./query.js";
+import { GetKeyRequiredError, QueryClientRequiredError, QueryCollectionError, QueryFnRequiredError, QueryKeyRequiredError } from "./errors.js";
 export {
+  GetKeyRequiredError,
+  QueryClientRequiredError,
+  QueryCollectionError,
+  QueryFnRequiredError,
+  QueryKeyRequiredError,
   queryCollectionOptions
 };
 //# sourceMappingURL=index.js.map

package/dist/esm/index.js.map

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

package/dist/esm/query.js

@@ -1,4 +1,5 @@
 import { QueryObserver } from "@tanstack/query-core";
+import { QueryKeyRequiredError, QueryFnRequiredError, QueryClientRequiredError, GetKeyRequiredError } from "./errors.js";
 function queryCollectionOptions(config) {
   const {
     queryKey,
@@ -16,16 +17,16 @@ function queryCollectionOptions(config) {
     ...baseCollectionConfig
   } = config;
   if (!queryKey) {
-    throw new Error(`[QueryCollection] queryKey must be provided.`);
+    throw new QueryKeyRequiredError();
   }
   if (!queryFn) {
-    throw new Error(`[QueryCollection] queryFn must be provided.`);
+    throw new QueryFnRequiredError();
   }
   if (!queryClient) {
-    throw new Error(`[QueryCollection] queryClient must be provided.`);
+    throw new QueryClientRequiredError();
   }
   if (!getKey) {
-    throw new Error(`[QueryCollection] getKey must be provided.`);
+    throw new GetKeyRequiredError();
   }
   const internalSync = (params) => {
     const { begin, write, commit, markReady, collection } = params;

package/dist/esm/query.js.map

@@ -1 +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, markReady, 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\n        // Mark collection as ready after first successful query result\n        markReady()\n      } else if (result.isError) {\n        console.error(\n          `[QueryCollection] Error observing query ${String(queryKey)}:`,\n          result.error\n        )\n\n        // Mark collection as ready even on error to avoid blocking apps\n        markReady()\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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"}
+{"version":3,"file":"query.js","sources":["../../src/query.ts"],"sourcesContent":["import { QueryObserver } from \"@tanstack/query-core\"\nimport {\n  GetKeyRequiredError,\n  QueryClientRequiredError,\n  QueryFnRequiredError,\n  QueryKeyRequiredError,\n} from \"./errors\"\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 QueryKeyRequiredError()\n  }\n  // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition\n  if (!queryFn) {\n    throw new QueryFnRequiredError()\n  }\n\n  // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition\n  if (!queryClient) {\n    throw new QueryClientRequiredError()\n  }\n\n  if (!getKey) {\n    throw new GetKeyRequiredError()\n  }\n\n  const internalSync: SyncConfig<TItem>[`sync`] = (params) => {\n    const { begin, write, commit, markReady, 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\n        // Mark collection as ready after first successful query result\n        markReady()\n      } else if (result.isError) {\n        console.error(\n          `[QueryCollection] Error observing query ${String(queryKey)}:`,\n          result.error\n        )\n\n        // Mark collection as ready even on error to avoid blocking apps\n        markReady()\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.9",
+  "version": "0.0.12",
   "dependencies": {
     "@tanstack/query-core": "^5.75.7",
-    "@tanstack/db": "0.0.27"
+    "@tanstack/db": "0.0.30"
   },
   "devDependencies": {
     "@vitest/coverage-istanbul": "^3.0.9"

package/src/errors.ts

@@ -0,0 +1,37 @@
+import { TanStackDBError } from "@tanstack/db"
+
+// Query Collection Errors
+export class QueryCollectionError extends TanStackDBError {
+  constructor(message: string) {
+    super(message)
+    this.name = `QueryCollectionError`
+  }
+}
+
+export class QueryKeyRequiredError extends QueryCollectionError {
+  constructor() {
+    super(`[QueryCollection] queryKey must be provided.`)
+    this.name = `QueryKeyRequiredError`
+  }
+}
+
+export class QueryFnRequiredError extends QueryCollectionError {
+  constructor() {
+    super(`[QueryCollection] queryFn must be provided.`)
+    this.name = `QueryFnRequiredError`
+  }
+}
+
+export class QueryClientRequiredError extends QueryCollectionError {
+  constructor() {
+    super(`[QueryCollection] queryClient must be provided.`)
+    this.name = `QueryClientRequiredError`
+  }
+}
+
+export class GetKeyRequiredError extends QueryCollectionError {
+  constructor() {
+    super(`[QueryCollection] getKey must be provided.`)
+    this.name = `GetKeyRequiredError`
+  }
+}

package/src/index.ts

@@ -3,3 +3,5 @@ export {
   type QueryCollectionConfig,
   type QueryCollectionUtils,
 } from "./query"
+
+export * from "./errors"

package/src/query.ts

@@ -1,4 +1,10 @@
 import { QueryObserver } from "@tanstack/query-core"
+import {
+  GetKeyRequiredError,
+  QueryClientRequiredError,
+  QueryFnRequiredError,
+  QueryKeyRequiredError,
+} from "./errors"
 import type {
   QueryClient,
   QueryFunctionContext,
@@ -253,20 +259,20 @@ export function queryCollectionOptions<
 
   // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
   if (!queryKey) {
-    throw new Error(`[QueryCollection] queryKey must be provided.`)
+    throw new QueryKeyRequiredError()
   }
   // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
   if (!queryFn) {
-    throw new Error(`[QueryCollection] queryFn must be provided.`)
+    throw new QueryFnRequiredError()
   }
 
   // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
   if (!queryClient) {
-    throw new Error(`[QueryCollection] queryClient must be provided.`)
+    throw new QueryClientRequiredError()
   }
 
   if (!getKey) {
-    throw new Error(`[QueryCollection] getKey must be provided.`)
+    throw new GetKeyRequiredError()
   }
 
   const internalSync: SyncConfig<TItem>[`sync`] = (params) => {