@tanstack/query-db-collection 0.2.36 → 0.2.37

package/dist/cjs/query.cjs

@@ -36,6 +36,7 @@ function queryCollectionOptions(config) {
   let lastError;
   let errorCount = 0;
   let lastErrorUpdatedAt = 0;
+  let queryObserver;
   const internalSync = (params) => {
     const { begin, write, commit, markReady, collection } = params;
     const observerOptions = {
@@ -52,6 +53,7 @@ function queryCollectionOptions(config) {
       ...staleTime !== void 0 && { staleTime }
     };
     const localObserver = new queryCore.QueryObserver(queryClient, observerOptions);
+    queryObserver = localObserver;
     let isSubscribed = false;
     let actualUnsubscribeFn = null;
     const handleQueryResult = (result) => {
@@ -146,15 +148,13 @@ function queryCollectionOptions(config) {
       queryClient.removeQueries({ queryKey });
     };
   };
-  const refetch = (opts) => {
-    return queryClient.refetchQueries(
-      {
-        queryKey
-      },
-      {
-        throwOnError: opts?.throwOnError
-      }
-    );
+  const refetch = async (opts) => {
+    if (!queryObserver) {
+      return;
+    }
+    return queryObserver.refetch({
+      throwOnError: opts?.throwOnError
+    });
   };
   let writeContext = null;
   const enhancedInternalSync = (params) => {
@@ -210,11 +210,11 @@ function queryCollectionOptions(config) {
       lastError: () => lastError,
       isError: () => !!lastError,
       errorCount: () => errorCount,
-      clearError: () => {
+      clearError: async () => {
         lastError = void 0;
         errorCount = 0;
         lastErrorUpdatedAt = 0;
-        return refetch({ throwOnError: true });
+        await refetch({ throwOnError: true });
       }
     }
   };

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 {\n  GetKeyRequiredError,\n  QueryClientRequiredError,\n  QueryFnRequiredError,\n  QueryKeyRequiredError,\n} from \"./errors\"\nimport { createWriteUtils } from \"./manual-sync\"\nimport type {\n  QueryClient,\n  QueryFunctionContext,\n  QueryKey,\n  QueryObserverOptions,\n} from \"@tanstack/query-core\"\nimport type {\n  BaseCollectionConfig,\n  ChangeMessage,\n  CollectionConfig,\n  DeleteMutationFnParams,\n  InsertMutationFnParams,\n  SyncConfig,\n  UpdateMutationFnParams,\n  UtilsRecord,\n} from \"@tanstack/db\"\nimport type { StandardSchemaV1 } from \"@standard-schema/spec\"\n\n// Re-export for external use\nexport type { SyncOperation } from \"./manual-sync\"\n\n// Schema output type inference helper (matches electric.ts pattern)\ntype InferSchemaOutput<T> = T extends StandardSchemaV1\n  ? StandardSchemaV1.InferOutput<T> extends object\n    ? StandardSchemaV1.InferOutput<T>\n    : Record<string, unknown>\n  : Record<string, unknown>\n\n// Schema input type inference helper (matches electric.ts pattern)\ntype InferSchemaInput<T> = T extends StandardSchemaV1\n  ? StandardSchemaV1.InferInput<T> extends object\n    ? StandardSchemaV1.InferInput<T>\n    : Record<string, unknown>\n  : Record<string, unknown>\n\n/**\n * Configuration options for creating a Query Collection\n * @template T - The explicit type of items stored in the collection\n * @template TQueryFn - The queryFn type\n * @template TError - The type of errors that can occur during queries\n * @template TQueryKey - The type of the query key\n * @template TKey - The type of the item keys\n * @template TSchema - The schema type for validation\n */\nexport interface QueryCollectionConfig<\n  T extends object = object,\n  TQueryFn extends (context: QueryFunctionContext<any>) => Promise<any> = (\n    context: QueryFunctionContext<any>\n  ) => Promise<any>,\n  TError = unknown,\n  TQueryKey extends QueryKey = QueryKey,\n  TKey extends string | number = string | number,\n  TSchema extends StandardSchemaV1 = never,\n  TQueryData = Awaited<ReturnType<TQueryFn>>,\n> extends BaseCollectionConfig<T, TKey, TSchema> {\n  /** The query key used by TanStack Query to identify this query */\n  queryKey: TQueryKey\n  /** Function that fetches data from the server. Must return the complete collection state */\n  queryFn: TQueryFn extends (\n    context: QueryFunctionContext<TQueryKey>\n  ) => Promise<Array<any>>\n    ? (context: QueryFunctionContext<TQueryKey>) => Promise<Array<T>>\n    : TQueryFn\n  /* Function that extracts array items from wrapped API responses (e.g metadata, pagination)  */\n  select?: (data: TQueryData) => Array<T>\n  /** The TanStack Query client instance */\n  queryClient: QueryClient\n\n  // Query-specific options\n  /** Whether the query should automatically run (default: true) */\n  enabled?: boolean\n  refetchInterval?: QueryObserverOptions<\n    Array<T>,\n    TError,\n    Array<T>,\n    Array<T>,\n    TQueryKey\n  >[`refetchInterval`]\n  retry?: QueryObserverOptions<\n    Array<T>,\n    TError,\n    Array<T>,\n    Array<T>,\n    TQueryKey\n  >[`retry`]\n  retryDelay?: QueryObserverOptions<\n    Array<T>,\n    TError,\n    Array<T>,\n    Array<T>,\n    TQueryKey\n  >[`retryDelay`]\n  staleTime?: QueryObserverOptions<\n    Array<T>,\n    TError,\n    Array<T>,\n    Array<T>,\n    TQueryKey\n  >[`staleTime`]\n\n  /**\n   * Metadata to pass to the query.\n   * Available in queryFn via context.meta\n   *\n   * @example\n   * // Using meta for error context\n   * queryFn: async (context) => {\n   *   try {\n   *     return await api.getTodos(userId)\n   *   } catch (error) {\n   *     // Use meta for better error messages\n   *     throw new Error(\n   *       context.meta?.errorMessage || 'Failed to load todos'\n   *     )\n   *   }\n   * },\n   * meta: {\n   *   errorMessage: `Failed to load todos for user ${userId}`\n   * }\n   */\n  meta?: Record<string, unknown>\n}\n\n/**\n * Type for the refetch utility function\n */\nexport type RefetchFn = (opts?: { throwOnError?: boolean }) => Promise<void>\n\n/**\n * Utility methods available on Query Collections for direct writes and manual operations.\n * Direct writes bypass the normal query/mutation flow and write directly to the synced data store.\n * @template TItem - The type of items stored in the collection\n * @template TKey - The type of the item keys\n * @template TInsertInput - The type accepted for insert operations\n * @template TError - The type of errors that can occur during queries\n */\nexport interface QueryCollectionUtils<\n  TItem extends object = Record<string, unknown>,\n  TKey extends string | number = string | number,\n  TInsertInput extends object = TItem,\n  TError = unknown,\n> extends UtilsRecord {\n  /** Manually trigger a refetch of the query */\n  refetch: RefetchFn\n  /** Insert one or more items directly into the synced data store without triggering a query refetch or optimistic update */\n  writeInsert: (data: TInsertInput | Array<TInsertInput>) => void\n  /** Update one or more items directly in the synced data store without triggering a query refetch or optimistic update */\n  writeUpdate: (updates: Partial<TItem> | Array<Partial<TItem>>) => void\n  /** Delete one or more items directly from the synced data store without triggering a query refetch or optimistic update */\n  writeDelete: (keys: TKey | Array<TKey>) => void\n  /** Insert or update one or more items directly in the synced data store without triggering a query refetch or optimistic update */\n  writeUpsert: (data: Partial<TItem> | Array<Partial<TItem>>) => void\n  /** Execute multiple write operations as a single atomic batch to the synced data store */\n  writeBatch: (callback: () => void) => void\n  /** Get the last error encountered by the query (if any); reset on success */\n  lastError: () => TError | undefined\n  /** Check if the collection is in an error state */\n  isError: () => boolean\n  /**\n   * Get the number of consecutive sync failures.\n   * Incremented only when query fails completely (not per retry attempt); reset on success.\n   */\n  errorCount: () => number\n  /**\n   * Clear the error state and trigger a refetch of the query\n   * @returns Promise that resolves when the refetch completes successfully\n   * @throws Error if the refetch fails\n   */\n  clearError: () => Promise<void>\n}\n\n/**\n * Creates query collection options for use with a standard Collection.\n * This integrates TanStack Query with TanStack DB for automatic synchronization.\n *\n * Supports automatic type inference following the priority order:\n * 1. Schema inference (highest priority)\n * 2. QueryFn return type inference (second priority)\n *\n * @template T - Type of the schema if a schema is provided otherwise it is the type of the values returned by the queryFn\n * @template TError - The type of errors that can occur during queries\n * @template TQueryKey - The type of the query key\n * @template TKey - The type of the item keys\n * @param config - Configuration options for the Query collection\n * @returns Collection options with utilities for direct writes and manual operations\n *\n * @example\n * // Type inferred from queryFn return type (NEW!)\n * const todosCollection = createCollection(\n *   queryCollectionOptions({\n *     queryKey: ['todos'],\n *     queryFn: async () => {\n *       const response = await fetch('/api/todos')\n *       return response.json() as Todo[] // Type automatically inferred!\n *     },\n *     queryClient,\n *     getKey: (item) => item.id, // item is typed as Todo\n *   })\n * )\n *\n * @example\n * // Explicit type\n * const todosCollection = createCollection<Todo>(\n *   queryCollectionOptions({\n *     queryKey: ['todos'],\n *     queryFn: async () => fetch('/api/todos').then(r => r.json()),\n *     queryClient,\n *     getKey: (item) => item.id,\n *   })\n * )\n *\n * @example\n * // Schema inference\n * const todosCollection = createCollection(\n *   queryCollectionOptions({\n *     queryKey: ['todos'],\n *     queryFn: async () => fetch('/api/todos').then(r => r.json()),\n *     queryClient,\n *     schema: todoSchema, // Type inferred from schema\n *     getKey: (item) => item.id,\n *   })\n * )\n *\n * @example\n * // With persistence handlers\n * const todosCollection = createCollection(\n *   queryCollectionOptions({\n *     queryKey: ['todos'],\n *     queryFn: fetchTodos,\n *     queryClient,\n *     getKey: (item) => item.id,\n *     onInsert: async ({ transaction }) => {\n *       await api.createTodos(transaction.mutations.map(m => m.modified))\n *     },\n *     onUpdate: async ({ transaction }) => {\n *       await api.updateTodos(transaction.mutations)\n *     },\n *     onDelete: async ({ transaction }) => {\n *       await api.deleteTodos(transaction.mutations.map(m => m.key))\n *     }\n *   })\n * )\n *\n * @example\n * // The select option extracts the items array from a response with metadata\n * const todosCollection = createCollection(\n *   queryCollectionOptions({\n *     queryKey: ['todos'],\n *     queryFn: async () => fetch('/api/todos').then(r => r.json()),\n *     select: (data) => data.items, // Extract the array of items\n *     queryClient,\n *     schema: todoSchema,\n *     getKey: (item) => item.id,\n *   })\n * )\n */\n// Overload for when schema is provided and select present\nexport function queryCollectionOptions<\n  T extends StandardSchemaV1,\n  TQueryFn extends (context: QueryFunctionContext<any>) => Promise<any>,\n  TError = unknown,\n  TQueryKey extends QueryKey = QueryKey,\n  TKey extends string | number = string | number,\n  TQueryData = Awaited<ReturnType<TQueryFn>>,\n>(\n  config: QueryCollectionConfig<\n    InferSchemaOutput<T>,\n    TQueryFn,\n    TError,\n    TQueryKey,\n    TKey,\n    T\n  > & {\n    schema: T\n    select: (data: TQueryData) => Array<InferSchemaInput<T>>\n  }\n): CollectionConfig<InferSchemaOutput<T>, TKey, T> & {\n  schema: T\n  utils: QueryCollectionUtils<\n    InferSchemaOutput<T>,\n    TKey,\n    InferSchemaInput<T>,\n    TError\n  >\n}\n\n// Overload for when no schema is provided and select present\nexport function queryCollectionOptions<\n  T extends object,\n  TQueryFn extends (context: QueryFunctionContext<any>) => Promise<any> = (\n    context: QueryFunctionContext<any>\n  ) => Promise<any>,\n  TError = unknown,\n  TQueryKey extends QueryKey = QueryKey,\n  TKey extends string | number = string | number,\n  TQueryData = Awaited<ReturnType<TQueryFn>>,\n>(\n  config: QueryCollectionConfig<\n    T,\n    TQueryFn,\n    TError,\n    TQueryKey,\n    TKey,\n    never,\n    TQueryData\n  > & {\n    schema?: never // prohibit schema\n    select: (data: TQueryData) => Array<T>\n  }\n): CollectionConfig<T, TKey> & {\n  schema?: never // no schema in the result\n  utils: QueryCollectionUtils<T, TKey, T, TError>\n}\n\n// Overload for when schema is provided\nexport function queryCollectionOptions<\n  T extends StandardSchemaV1,\n  TError = unknown,\n  TQueryKey extends QueryKey = QueryKey,\n  TKey extends string | number = string | number,\n>(\n  config: QueryCollectionConfig<\n    InferSchemaOutput<T>,\n    (\n      context: QueryFunctionContext<any>\n    ) => Promise<Array<InferSchemaOutput<T>>>,\n    TError,\n    TQueryKey,\n    TKey,\n    T\n  > & {\n    schema: T\n  }\n): CollectionConfig<InferSchemaOutput<T>, TKey, T> & {\n  schema: T\n  utils: QueryCollectionUtils<\n    InferSchemaOutput<T>,\n    TKey,\n    InferSchemaInput<T>,\n    TError\n  >\n}\n\n// Overload for when no schema is provided\nexport function queryCollectionOptions<\n  T extends object,\n  TError = unknown,\n  TQueryKey extends QueryKey = QueryKey,\n  TKey extends string | number = string | number,\n>(\n  config: QueryCollectionConfig<\n    T,\n    (context: QueryFunctionContext<any>) => Promise<Array<T>>,\n    TError,\n    TQueryKey,\n    TKey\n  > & {\n    schema?: never // prohibit schema\n  }\n): CollectionConfig<T, TKey> & {\n  schema?: never // no schema in the result\n  utils: QueryCollectionUtils<T, TKey, T, TError>\n}\n\nexport function queryCollectionOptions(\n  config: QueryCollectionConfig<Record<string, unknown>>\n): CollectionConfig & {\n  utils: QueryCollectionUtils\n} {\n  const {\n    queryKey,\n    queryFn,\n    select,\n    queryClient,\n    enabled,\n    refetchInterval,\n    retry,\n    retryDelay,\n    staleTime,\n    getKey,\n    onInsert,\n    onUpdate,\n    onDelete,\n    meta,\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  // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition\n  if (!getKey) {\n    throw new GetKeyRequiredError()\n  }\n\n  /** The last error encountered by the query */\n  let lastError: any\n  /** The number of consecutive sync failures */\n  let errorCount = 0\n  /** The timestamp for when the query most recently returned the status as \"error\" */\n  let lastErrorUpdatedAt = 0\n\n  const internalSync: SyncConfig<any>[`sync`] = (params) => {\n    const { begin, write, commit, markReady, collection } = params\n\n    const observerOptions: QueryObserverOptions<\n      Array<any>,\n      any,\n      Array<any>,\n      Array<any>,\n      any\n    > = {\n      queryKey: queryKey,\n      queryFn: queryFn,\n      structuralSharing: true,\n      notifyOnChangeProps: `all`,\n      // Only include options that are explicitly defined to allow QueryClient defaultOptions to be used\n      ...(meta !== undefined && { meta }),\n      ...(enabled !== undefined && { enabled }),\n      ...(refetchInterval !== undefined && { refetchInterval }),\n      ...(retry !== undefined && { retry }),\n      ...(retryDelay !== undefined && { retryDelay }),\n      ...(staleTime !== undefined && { staleTime }),\n    }\n\n    const localObserver = new QueryObserver<\n      Array<any>,\n      any,\n      Array<any>,\n      Array<any>,\n      any\n    >(queryClient, observerOptions)\n\n    let isSubscribed = false\n    let actualUnsubscribeFn: (() => void) | null = null\n\n    type UpdateHandler = Parameters<typeof localObserver.subscribe>[0]\n    const handleQueryResult: UpdateHandler = (result) => {\n      if (result.isSuccess) {\n        // Clear error state\n        lastError = undefined\n        errorCount = 0\n\n        const rawData = result.data\n        const newItemsArray = select ? select(rawData) : rawData\n\n        if (\n          !Array.isArray(newItemsArray) ||\n          newItemsArray.some((item) => typeof item !== `object`)\n        ) {\n          const errorMessage = select\n            ? `@tanstack/query-db-collection: select() must return an array of objects. Got: ${typeof newItemsArray} for queryKey ${JSON.stringify(queryKey)}`\n            : `@tanstack/query-db-collection: queryFn must return an array of objects. Got: ${typeof newItemsArray} for queryKey ${JSON.stringify(queryKey)}`\n\n          console.error(errorMessage)\n          return\n        }\n\n        const currentSyncedItems: Map<string | number, any> = new Map(\n          collection._state.syncedData.entries()\n        )\n        const newItemsMap = new Map<string | number, any>()\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            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        if (result.errorUpdatedAt !== lastErrorUpdatedAt) {\n          lastError = result.error\n          errorCount++\n          lastErrorUpdatedAt = result.errorUpdatedAt\n        }\n\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    const subscribeToQuery = () => {\n      if (!isSubscribed) {\n        actualUnsubscribeFn = localObserver.subscribe(handleQueryResult)\n        isSubscribed = true\n      }\n    }\n\n    const unsubscribeFromQuery = () => {\n      if (isSubscribed && actualUnsubscribeFn) {\n        actualUnsubscribeFn()\n        actualUnsubscribeFn = null\n        isSubscribed = false\n      }\n    }\n\n    // Always subscribe when sync starts (this could be from preload(), startSync config, or first subscriber)\n    // We'll dynamically unsubscribe/resubscribe based on subscriber count to maintain staleTime behavior\n    subscribeToQuery()\n\n    // Set up event listener for subscriber changes\n    const unsubscribeFromCollectionEvents = collection.on(\n      `subscribers:change`,\n      ({ subscriberCount }) => {\n        if (subscriberCount > 0) {\n          subscribeToQuery()\n        } else if (subscriberCount === 0) {\n          unsubscribeFromQuery()\n        }\n      }\n    )\n\n    // Ensure we process any existing query data (QueryObserver doesn't invoke its callback automatically with initial\n    // state)\n    handleQueryResult(localObserver.getCurrentResult())\n\n    return async () => {\n      unsubscribeFromCollectionEvents()\n      unsubscribeFromQuery()\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 = (opts) => {\n    return queryClient.refetchQueries(\n      {\n        queryKey: queryKey,\n      },\n      {\n        throwOnError: opts?.throwOnError,\n      }\n    )\n  }\n\n  // Create write context for manual write operations\n  let writeContext: {\n    collection: any\n    queryClient: QueryClient\n    queryKey: Array<unknown>\n    getKey: (item: any) => string | number\n    begin: () => void\n    write: (message: Omit<ChangeMessage<any>, `key`>) => void\n    commit: () => void\n  } | null = null\n\n  // Enhanced internalSync that captures write functions for manual use\n  const enhancedInternalSync: SyncConfig<any>[`sync`] = (params) => {\n    const { begin, write, commit, collection } = params\n\n    // Store references for manual write operations\n    writeContext = {\n      collection,\n      queryClient,\n      queryKey: queryKey as unknown as Array<unknown>,\n      getKey: getKey as (item: any) => string | number,\n      begin,\n      write,\n      commit,\n    }\n\n    // Call the original internalSync logic\n    return internalSync(params)\n  }\n\n  // Create write utils using the manual-sync module\n  const writeUtils = createWriteUtils<any, string | number, any>(\n    () => writeContext\n  )\n\n  // Create wrapper handlers for direct persistence operations that handle refetching\n  const wrappedOnInsert = onInsert\n    ? async (params: InsertMutationFnParams<any>) => {\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<any>) => {\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<any>) => {\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: enhancedInternalSync },\n    onInsert: wrappedOnInsert,\n    onUpdate: wrappedOnUpdate,\n    onDelete: wrappedOnDelete,\n    utils: {\n      refetch,\n      ...writeUtils,\n      lastError: () => lastError,\n      isError: () => !!lastError,\n      errorCount: () => errorCount,\n      clearError: () => {\n        lastError = undefined\n        errorCount = 0\n        lastErrorUpdatedAt = 0\n        return refetch({ throwOnError: true })\n      },\n    },\n  }\n}\n"],"names":["QueryKeyRequiredError","QueryFnRequiredError","QueryClientRequiredError","GetKeyRequiredError","QueryObserver","createWriteUtils"],"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 { createWriteUtils } from \"./manual-sync\"\nimport type {\n  QueryClient,\n  QueryFunctionContext,\n  QueryKey,\n  QueryObserverOptions,\n  QueryObserverResult,\n} from \"@tanstack/query-core\"\nimport type {\n  BaseCollectionConfig,\n  ChangeMessage,\n  CollectionConfig,\n  DeleteMutationFnParams,\n  InsertMutationFnParams,\n  SyncConfig,\n  UpdateMutationFnParams,\n  UtilsRecord,\n} from \"@tanstack/db\"\nimport type { StandardSchemaV1 } from \"@standard-schema/spec\"\n\n// Re-export for external use\nexport type { SyncOperation } from \"./manual-sync\"\n\n// Schema output type inference helper (matches electric.ts pattern)\ntype InferSchemaOutput<T> = T extends StandardSchemaV1\n  ? StandardSchemaV1.InferOutput<T> extends object\n    ? StandardSchemaV1.InferOutput<T>\n    : Record<string, unknown>\n  : Record<string, unknown>\n\n// Schema input type inference helper (matches electric.ts pattern)\ntype InferSchemaInput<T> = T extends StandardSchemaV1\n  ? StandardSchemaV1.InferInput<T> extends object\n    ? StandardSchemaV1.InferInput<T>\n    : Record<string, unknown>\n  : Record<string, unknown>\n\n/**\n * Configuration options for creating a Query Collection\n * @template T - The explicit type of items stored in the collection\n * @template TQueryFn - The queryFn type\n * @template TError - The type of errors that can occur during queries\n * @template TQueryKey - The type of the query key\n * @template TKey - The type of the item keys\n * @template TSchema - The schema type for validation\n */\nexport interface QueryCollectionConfig<\n  T extends object = object,\n  TQueryFn extends (context: QueryFunctionContext<any>) => Promise<any> = (\n    context: QueryFunctionContext<any>\n  ) => Promise<any>,\n  TError = unknown,\n  TQueryKey extends QueryKey = QueryKey,\n  TKey extends string | number = string | number,\n  TSchema extends StandardSchemaV1 = never,\n  TQueryData = Awaited<ReturnType<TQueryFn>>,\n> extends BaseCollectionConfig<T, TKey, TSchema> {\n  /** The query key used by TanStack Query to identify this query */\n  queryKey: TQueryKey\n  /** Function that fetches data from the server. Must return the complete collection state */\n  queryFn: TQueryFn extends (\n    context: QueryFunctionContext<TQueryKey>\n  ) => Promise<Array<any>>\n    ? (context: QueryFunctionContext<TQueryKey>) => Promise<Array<T>>\n    : TQueryFn\n  /* Function that extracts array items from wrapped API responses (e.g metadata, pagination)  */\n  select?: (data: TQueryData) => Array<T>\n  /** The TanStack Query client instance */\n  queryClient: QueryClient\n\n  // Query-specific options\n  /** Whether the query should automatically run (default: true) */\n  enabled?: boolean\n  refetchInterval?: QueryObserverOptions<\n    Array<T>,\n    TError,\n    Array<T>,\n    Array<T>,\n    TQueryKey\n  >[`refetchInterval`]\n  retry?: QueryObserverOptions<\n    Array<T>,\n    TError,\n    Array<T>,\n    Array<T>,\n    TQueryKey\n  >[`retry`]\n  retryDelay?: QueryObserverOptions<\n    Array<T>,\n    TError,\n    Array<T>,\n    Array<T>,\n    TQueryKey\n  >[`retryDelay`]\n  staleTime?: QueryObserverOptions<\n    Array<T>,\n    TError,\n    Array<T>,\n    Array<T>,\n    TQueryKey\n  >[`staleTime`]\n\n  /**\n   * Metadata to pass to the query.\n   * Available in queryFn via context.meta\n   *\n   * @example\n   * // Using meta for error context\n   * queryFn: async (context) => {\n   *   try {\n   *     return await api.getTodos(userId)\n   *   } catch (error) {\n   *     // Use meta for better error messages\n   *     throw new Error(\n   *       context.meta?.errorMessage || 'Failed to load todos'\n   *     )\n   *   }\n   * },\n   * meta: {\n   *   errorMessage: `Failed to load todos for user ${userId}`\n   * }\n   */\n  meta?: Record<string, unknown>\n}\n\n/**\n * Type for the refetch utility function\n * Returns the QueryObserverResult from TanStack Query\n */\nexport type RefetchFn = (opts?: {\n  throwOnError?: boolean\n}) => Promise<QueryObserverResult<any, any> | void>\n\n/**\n * Utility methods available on Query Collections for direct writes and manual operations.\n * Direct writes bypass the normal query/mutation flow and write directly to the synced data store.\n * @template TItem - The type of items stored in the collection\n * @template TKey - The type of the item keys\n * @template TInsertInput - The type accepted for insert operations\n * @template TError - The type of errors that can occur during queries\n */\nexport interface QueryCollectionUtils<\n  TItem extends object = Record<string, unknown>,\n  TKey extends string | number = string | number,\n  TInsertInput extends object = TItem,\n  TError = unknown,\n> extends UtilsRecord {\n  /** Manually trigger a refetch of the query */\n  refetch: RefetchFn\n  /** Insert one or more items directly into the synced data store without triggering a query refetch or optimistic update */\n  writeInsert: (data: TInsertInput | Array<TInsertInput>) => void\n  /** Update one or more items directly in the synced data store without triggering a query refetch or optimistic update */\n  writeUpdate: (updates: Partial<TItem> | Array<Partial<TItem>>) => void\n  /** Delete one or more items directly from the synced data store without triggering a query refetch or optimistic update */\n  writeDelete: (keys: TKey | Array<TKey>) => void\n  /** Insert or update one or more items directly in the synced data store without triggering a query refetch or optimistic update */\n  writeUpsert: (data: Partial<TItem> | Array<Partial<TItem>>) => void\n  /** Execute multiple write operations as a single atomic batch to the synced data store */\n  writeBatch: (callback: () => void) => void\n  /** Get the last error encountered by the query (if any); reset on success */\n  lastError: () => TError | undefined\n  /** Check if the collection is in an error state */\n  isError: () => boolean\n  /**\n   * Get the number of consecutive sync failures.\n   * Incremented only when query fails completely (not per retry attempt); reset on success.\n   */\n  errorCount: () => number\n  /**\n   * Clear the error state and trigger a refetch of the query\n   * @returns Promise that resolves when the refetch completes successfully\n   * @throws Error if the refetch fails\n   */\n  clearError: () => Promise<void>\n}\n\n/**\n * Creates query collection options for use with a standard Collection.\n * This integrates TanStack Query with TanStack DB for automatic synchronization.\n *\n * Supports automatic type inference following the priority order:\n * 1. Schema inference (highest priority)\n * 2. QueryFn return type inference (second priority)\n *\n * @template T - Type of the schema if a schema is provided otherwise it is the type of the values returned by the queryFn\n * @template TError - The type of errors that can occur during queries\n * @template TQueryKey - The type of the query key\n * @template TKey - The type of the item keys\n * @param config - Configuration options for the Query collection\n * @returns Collection options with utilities for direct writes and manual operations\n *\n * @example\n * // Type inferred from queryFn return type (NEW!)\n * const todosCollection = createCollection(\n *   queryCollectionOptions({\n *     queryKey: ['todos'],\n *     queryFn: async () => {\n *       const response = await fetch('/api/todos')\n *       return response.json() as Todo[] // Type automatically inferred!\n *     },\n *     queryClient,\n *     getKey: (item) => item.id, // item is typed as Todo\n *   })\n * )\n *\n * @example\n * // Explicit type\n * const todosCollection = createCollection<Todo>(\n *   queryCollectionOptions({\n *     queryKey: ['todos'],\n *     queryFn: async () => fetch('/api/todos').then(r => r.json()),\n *     queryClient,\n *     getKey: (item) => item.id,\n *   })\n * )\n *\n * @example\n * // Schema inference\n * const todosCollection = createCollection(\n *   queryCollectionOptions({\n *     queryKey: ['todos'],\n *     queryFn: async () => fetch('/api/todos').then(r => r.json()),\n *     queryClient,\n *     schema: todoSchema, // Type inferred from schema\n *     getKey: (item) => item.id,\n *   })\n * )\n *\n * @example\n * // With persistence handlers\n * const todosCollection = createCollection(\n *   queryCollectionOptions({\n *     queryKey: ['todos'],\n *     queryFn: fetchTodos,\n *     queryClient,\n *     getKey: (item) => item.id,\n *     onInsert: async ({ transaction }) => {\n *       await api.createTodos(transaction.mutations.map(m => m.modified))\n *     },\n *     onUpdate: async ({ transaction }) => {\n *       await api.updateTodos(transaction.mutations)\n *     },\n *     onDelete: async ({ transaction }) => {\n *       await api.deleteTodos(transaction.mutations.map(m => m.key))\n *     }\n *   })\n * )\n *\n * @example\n * // The select option extracts the items array from a response with metadata\n * const todosCollection = createCollection(\n *   queryCollectionOptions({\n *     queryKey: ['todos'],\n *     queryFn: async () => fetch('/api/todos').then(r => r.json()),\n *     select: (data) => data.items, // Extract the array of items\n *     queryClient,\n *     schema: todoSchema,\n *     getKey: (item) => item.id,\n *   })\n * )\n */\n// Overload for when schema is provided and select present\nexport function queryCollectionOptions<\n  T extends StandardSchemaV1,\n  TQueryFn extends (context: QueryFunctionContext<any>) => Promise<any>,\n  TError = unknown,\n  TQueryKey extends QueryKey = QueryKey,\n  TKey extends string | number = string | number,\n  TQueryData = Awaited<ReturnType<TQueryFn>>,\n>(\n  config: QueryCollectionConfig<\n    InferSchemaOutput<T>,\n    TQueryFn,\n    TError,\n    TQueryKey,\n    TKey,\n    T\n  > & {\n    schema: T\n    select: (data: TQueryData) => Array<InferSchemaInput<T>>\n  }\n): CollectionConfig<InferSchemaOutput<T>, TKey, T> & {\n  schema: T\n  utils: QueryCollectionUtils<\n    InferSchemaOutput<T>,\n    TKey,\n    InferSchemaInput<T>,\n    TError\n  >\n}\n\n// Overload for when no schema is provided and select present\nexport function queryCollectionOptions<\n  T extends object,\n  TQueryFn extends (context: QueryFunctionContext<any>) => Promise<any> = (\n    context: QueryFunctionContext<any>\n  ) => Promise<any>,\n  TError = unknown,\n  TQueryKey extends QueryKey = QueryKey,\n  TKey extends string | number = string | number,\n  TQueryData = Awaited<ReturnType<TQueryFn>>,\n>(\n  config: QueryCollectionConfig<\n    T,\n    TQueryFn,\n    TError,\n    TQueryKey,\n    TKey,\n    never,\n    TQueryData\n  > & {\n    schema?: never // prohibit schema\n    select: (data: TQueryData) => Array<T>\n  }\n): CollectionConfig<T, TKey> & {\n  schema?: never // no schema in the result\n  utils: QueryCollectionUtils<T, TKey, T, TError>\n}\n\n// Overload for when schema is provided\nexport function queryCollectionOptions<\n  T extends StandardSchemaV1,\n  TError = unknown,\n  TQueryKey extends QueryKey = QueryKey,\n  TKey extends string | number = string | number,\n>(\n  config: QueryCollectionConfig<\n    InferSchemaOutput<T>,\n    (\n      context: QueryFunctionContext<any>\n    ) => Promise<Array<InferSchemaOutput<T>>>,\n    TError,\n    TQueryKey,\n    TKey,\n    T\n  > & {\n    schema: T\n  }\n): CollectionConfig<InferSchemaOutput<T>, TKey, T> & {\n  schema: T\n  utils: QueryCollectionUtils<\n    InferSchemaOutput<T>,\n    TKey,\n    InferSchemaInput<T>,\n    TError\n  >\n}\n\n// Overload for when no schema is provided\nexport function queryCollectionOptions<\n  T extends object,\n  TError = unknown,\n  TQueryKey extends QueryKey = QueryKey,\n  TKey extends string | number = string | number,\n>(\n  config: QueryCollectionConfig<\n    T,\n    (context: QueryFunctionContext<any>) => Promise<Array<T>>,\n    TError,\n    TQueryKey,\n    TKey\n  > & {\n    schema?: never // prohibit schema\n  }\n): CollectionConfig<T, TKey> & {\n  schema?: never // no schema in the result\n  utils: QueryCollectionUtils<T, TKey, T, TError>\n}\n\nexport function queryCollectionOptions(\n  config: QueryCollectionConfig<Record<string, unknown>>\n): CollectionConfig & {\n  utils: QueryCollectionUtils\n} {\n  const {\n    queryKey,\n    queryFn,\n    select,\n    queryClient,\n    enabled,\n    refetchInterval,\n    retry,\n    retryDelay,\n    staleTime,\n    getKey,\n    onInsert,\n    onUpdate,\n    onDelete,\n    meta,\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  // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition\n  if (!getKey) {\n    throw new GetKeyRequiredError()\n  }\n\n  /** The last error encountered by the query */\n  let lastError: any\n  /** The number of consecutive sync failures */\n  let errorCount = 0\n  /** The timestamp for when the query most recently returned the status as \"error\" */\n  let lastErrorUpdatedAt = 0\n  /** Reference to the QueryObserver for imperative refetch */\n  let queryObserver: QueryObserver<Array<any>, any, Array<any>, Array<any>, any>\n\n  const internalSync: SyncConfig<any>[`sync`] = (params) => {\n    const { begin, write, commit, markReady, collection } = params\n\n    const observerOptions: QueryObserverOptions<\n      Array<any>,\n      any,\n      Array<any>,\n      Array<any>,\n      any\n    > = {\n      queryKey: queryKey,\n      queryFn: queryFn,\n      structuralSharing: true,\n      notifyOnChangeProps: `all`,\n      // Only include options that are explicitly defined to allow QueryClient defaultOptions to be used\n      ...(meta !== undefined && { meta }),\n      ...(enabled !== undefined && { enabled }),\n      ...(refetchInterval !== undefined && { refetchInterval }),\n      ...(retry !== undefined && { retry }),\n      ...(retryDelay !== undefined && { retryDelay }),\n      ...(staleTime !== undefined && { staleTime }),\n    }\n\n    const localObserver = new QueryObserver<\n      Array<any>,\n      any,\n      Array<any>,\n      Array<any>,\n      any\n    >(queryClient, observerOptions)\n\n    // Store reference for imperative refetch\n    queryObserver = localObserver\n\n    let isSubscribed = false\n    let actualUnsubscribeFn: (() => void) | null = null\n\n    type UpdateHandler = Parameters<typeof localObserver.subscribe>[0]\n    const handleQueryResult: UpdateHandler = (result) => {\n      if (result.isSuccess) {\n        // Clear error state\n        lastError = undefined\n        errorCount = 0\n\n        const rawData = result.data\n        const newItemsArray = select ? select(rawData) : rawData\n\n        if (\n          !Array.isArray(newItemsArray) ||\n          newItemsArray.some((item) => typeof item !== `object`)\n        ) {\n          const errorMessage = select\n            ? `@tanstack/query-db-collection: select() must return an array of objects. Got: ${typeof newItemsArray} for queryKey ${JSON.stringify(queryKey)}`\n            : `@tanstack/query-db-collection: queryFn must return an array of objects. Got: ${typeof newItemsArray} for queryKey ${JSON.stringify(queryKey)}`\n\n          console.error(errorMessage)\n          return\n        }\n\n        const currentSyncedItems: Map<string | number, any> = new Map(\n          collection._state.syncedData.entries()\n        )\n        const newItemsMap = new Map<string | number, any>()\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            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        if (result.errorUpdatedAt !== lastErrorUpdatedAt) {\n          lastError = result.error\n          errorCount++\n          lastErrorUpdatedAt = result.errorUpdatedAt\n        }\n\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    const subscribeToQuery = () => {\n      if (!isSubscribed) {\n        actualUnsubscribeFn = localObserver.subscribe(handleQueryResult)\n        isSubscribed = true\n      }\n    }\n\n    const unsubscribeFromQuery = () => {\n      if (isSubscribed && actualUnsubscribeFn) {\n        actualUnsubscribeFn()\n        actualUnsubscribeFn = null\n        isSubscribed = false\n      }\n    }\n\n    // Always subscribe when sync starts (this could be from preload(), startSync config, or first subscriber)\n    // We'll dynamically unsubscribe/resubscribe based on subscriber count to maintain staleTime behavior\n    subscribeToQuery()\n\n    // Set up event listener for subscriber changes\n    const unsubscribeFromCollectionEvents = collection.on(\n      `subscribers:change`,\n      ({ subscriberCount }) => {\n        if (subscriberCount > 0) {\n          subscribeToQuery()\n        } else if (subscriberCount === 0) {\n          unsubscribeFromQuery()\n        }\n      }\n    )\n\n    // Ensure we process any existing query data (QueryObserver doesn't invoke its callback automatically with initial\n    // state)\n    handleQueryResult(localObserver.getCurrentResult())\n\n    return async () => {\n      unsubscribeFromCollectionEvents()\n      unsubscribeFromQuery()\n      await queryClient.cancelQueries({ queryKey })\n      queryClient.removeQueries({ queryKey })\n    }\n  }\n\n  /**\n   * Refetch the query data\n   *\n   * Uses queryObserver.refetch() because:\n   * - Bypasses `enabled: false` to support manual/imperative refetch patterns (e.g., button-triggered fetch)\n   * - Ensures clearError() works even when enabled: false\n   * - Always refetches THIS specific collection (exact targeting via observer)\n   * - Respects retry, retryDelay, and other observer options\n   *\n   * This matches TanStack Query's hook behavior where refetch() bypasses enabled: false.\n   * See: https://tanstack.com/query/latest/docs/framework/react/guides/disabling-queries\n   *\n   * Used by both:\n   * - utils.refetch() - for explicit user-triggered refetches\n   * - Internal handlers (onInsert/onUpdate/onDelete) - after mutations to get fresh data\n   *\n   * @returns Promise that resolves when the refetch is complete, with QueryObserverResult\n   */\n  const refetch: RefetchFn = async (opts) => {\n    // Observer is created when sync starts. If never synced, nothing to refetch.\n    // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition\n    if (!queryObserver) {\n      return\n    }\n    // Return the QueryObserverResult for users to inspect\n    return queryObserver.refetch({\n      throwOnError: opts?.throwOnError,\n    })\n  }\n\n  // Create write context for manual write operations\n  let writeContext: {\n    collection: any\n    queryClient: QueryClient\n    queryKey: Array<unknown>\n    getKey: (item: any) => string | number\n    begin: () => void\n    write: (message: Omit<ChangeMessage<any>, `key`>) => void\n    commit: () => void\n  } | null = null\n\n  // Enhanced internalSync that captures write functions for manual use\n  const enhancedInternalSync: SyncConfig<any>[`sync`] = (params) => {\n    const { begin, write, commit, collection } = params\n\n    // Store references for manual write operations\n    writeContext = {\n      collection,\n      queryClient,\n      queryKey: queryKey as unknown as Array<unknown>,\n      getKey: getKey as (item: any) => string | number,\n      begin,\n      write,\n      commit,\n    }\n\n    // Call the original internalSync logic\n    return internalSync(params)\n  }\n\n  // Create write utils using the manual-sync module\n  const writeUtils = createWriteUtils<any, string | number, any>(\n    () => writeContext\n  )\n\n  // Create wrapper handlers for direct persistence operations that handle refetching\n  const wrappedOnInsert = onInsert\n    ? async (params: InsertMutationFnParams<any>) => {\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<any>) => {\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<any>) => {\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: enhancedInternalSync },\n    onInsert: wrappedOnInsert,\n    onUpdate: wrappedOnUpdate,\n    onDelete: wrappedOnDelete,\n    utils: {\n      refetch,\n      ...writeUtils,\n      lastError: () => lastError,\n      isError: () => !!lastError,\n      errorCount: () => errorCount,\n      clearError: async () => {\n        lastError = undefined\n        errorCount = 0\n        lastErrorUpdatedAt = 0\n        await refetch({ throwOnError: true })\n      },\n    },\n  }\n}\n"],"names":["QueryKeyRequiredError","QueryFnRequiredError","QueryClientRequiredError","GetKeyRequiredError","QueryObserver","createWriteUtils"],"mappings":"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"}

package/dist/cjs/query.d.cts

@@ -1,4 +1,4 @@
-import { QueryClient, QueryFunctionContext, QueryKey, QueryObserverOptions } from '@tanstack/query-core';
+import { QueryClient, QueryFunctionContext, QueryKey, QueryObserverOptions, QueryObserverResult } from '@tanstack/query-core';
 import { BaseCollectionConfig, CollectionConfig, UtilsRecord } from '@tanstack/db';
 import { StandardSchemaV1 } from '@standard-schema/spec';
 export type { SyncOperation } from './manual-sync.cjs';
@@ -51,10 +51,11 @@ export interface QueryCollectionConfig<T extends object = object, TQueryFn exten
 }
 /**
  * Type for the refetch utility function
+ * Returns the QueryObserverResult from TanStack Query
  */
 export type RefetchFn = (opts?: {
     throwOnError?: boolean;
-}) => Promise<void>;
+}) => Promise<QueryObserverResult<any, any> | void>;
 /**
  * Utility methods available on Query Collections for direct writes and manual operations.
  * Direct writes bypass the normal query/mutation flow and write directly to the synced data store.

package/dist/esm/query.d.ts

@@ -1,4 +1,4 @@
-import { QueryClient, QueryFunctionContext, QueryKey, QueryObserverOptions } from '@tanstack/query-core';
+import { QueryClient, QueryFunctionContext, QueryKey, QueryObserverOptions, QueryObserverResult } from '@tanstack/query-core';
 import { BaseCollectionConfig, CollectionConfig, UtilsRecord } from '@tanstack/db';
 import { StandardSchemaV1 } from '@standard-schema/spec';
 export type { SyncOperation } from './manual-sync.js';
@@ -51,10 +51,11 @@ export interface QueryCollectionConfig<T extends object = object, TQueryFn exten
 }
 /**
  * Type for the refetch utility function
+ * Returns the QueryObserverResult from TanStack Query
  */
 export type RefetchFn = (opts?: {
     throwOnError?: boolean;
-}) => Promise<void>;
+}) => Promise<QueryObserverResult<any, any> | void>;
 /**
  * Utility methods available on Query Collections for direct writes and manual operations.
  * Direct writes bypass the normal query/mutation flow and write directly to the synced data store.

package/dist/esm/query.js

@@ -34,6 +34,7 @@ function queryCollectionOptions(config) {
   let lastError;
   let errorCount = 0;
   let lastErrorUpdatedAt = 0;
+  let queryObserver;
   const internalSync = (params) => {
     const { begin, write, commit, markReady, collection } = params;
     const observerOptions = {
@@ -50,6 +51,7 @@ function queryCollectionOptions(config) {
       ...staleTime !== void 0 && { staleTime }
     };
     const localObserver = new QueryObserver(queryClient, observerOptions);
+    queryObserver = localObserver;
     let isSubscribed = false;
     let actualUnsubscribeFn = null;
     const handleQueryResult = (result) => {
@@ -144,15 +146,13 @@ function queryCollectionOptions(config) {
       queryClient.removeQueries({ queryKey });
     };
   };
-  const refetch = (opts) => {
-    return queryClient.refetchQueries(
-      {
-        queryKey
-      },
-      {
-        throwOnError: opts?.throwOnError
-      }
-    );
+  const refetch = async (opts) => {
+    if (!queryObserver) {
+      return;
+    }
+    return queryObserver.refetch({
+      throwOnError: opts?.throwOnError
+    });
   };
   let writeContext = null;
   const enhancedInternalSync = (params) => {
@@ -208,11 +208,11 @@ function queryCollectionOptions(config) {
       lastError: () => lastError,
       isError: () => !!lastError,
       errorCount: () => errorCount,
-      clearError: () => {
+      clearError: async () => {
         lastError = void 0;
         errorCount = 0;
         lastErrorUpdatedAt = 0;
-        return refetch({ throwOnError: true });
+        await refetch({ throwOnError: true });
       }
     }
   };

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 {\n  GetKeyRequiredError,\n  QueryClientRequiredError,\n  QueryFnRequiredError,\n  QueryKeyRequiredError,\n} from \"./errors\"\nimport { createWriteUtils } from \"./manual-sync\"\nimport type {\n  QueryClient,\n  QueryFunctionContext,\n  QueryKey,\n  QueryObserverOptions,\n} from \"@tanstack/query-core\"\nimport type {\n  BaseCollectionConfig,\n  ChangeMessage,\n  CollectionConfig,\n  DeleteMutationFnParams,\n  InsertMutationFnParams,\n  SyncConfig,\n  UpdateMutationFnParams,\n  UtilsRecord,\n} from \"@tanstack/db\"\nimport type { StandardSchemaV1 } from \"@standard-schema/spec\"\n\n// Re-export for external use\nexport type { SyncOperation } from \"./manual-sync\"\n\n// Schema output type inference helper (matches electric.ts pattern)\ntype InferSchemaOutput<T> = T extends StandardSchemaV1\n  ? StandardSchemaV1.InferOutput<T> extends object\n    ? StandardSchemaV1.InferOutput<T>\n    : Record<string, unknown>\n  : Record<string, unknown>\n\n// Schema input type inference helper (matches electric.ts pattern)\ntype InferSchemaInput<T> = T extends StandardSchemaV1\n  ? StandardSchemaV1.InferInput<T> extends object\n    ? StandardSchemaV1.InferInput<T>\n    : Record<string, unknown>\n  : Record<string, unknown>\n\n/**\n * Configuration options for creating a Query Collection\n * @template T - The explicit type of items stored in the collection\n * @template TQueryFn - The queryFn type\n * @template TError - The type of errors that can occur during queries\n * @template TQueryKey - The type of the query key\n * @template TKey - The type of the item keys\n * @template TSchema - The schema type for validation\n */\nexport interface QueryCollectionConfig<\n  T extends object = object,\n  TQueryFn extends (context: QueryFunctionContext<any>) => Promise<any> = (\n    context: QueryFunctionContext<any>\n  ) => Promise<any>,\n  TError = unknown,\n  TQueryKey extends QueryKey = QueryKey,\n  TKey extends string | number = string | number,\n  TSchema extends StandardSchemaV1 = never,\n  TQueryData = Awaited<ReturnType<TQueryFn>>,\n> extends BaseCollectionConfig<T, TKey, TSchema> {\n  /** The query key used by TanStack Query to identify this query */\n  queryKey: TQueryKey\n  /** Function that fetches data from the server. Must return the complete collection state */\n  queryFn: TQueryFn extends (\n    context: QueryFunctionContext<TQueryKey>\n  ) => Promise<Array<any>>\n    ? (context: QueryFunctionContext<TQueryKey>) => Promise<Array<T>>\n    : TQueryFn\n  /* Function that extracts array items from wrapped API responses (e.g metadata, pagination)  */\n  select?: (data: TQueryData) => Array<T>\n  /** The TanStack Query client instance */\n  queryClient: QueryClient\n\n  // Query-specific options\n  /** Whether the query should automatically run (default: true) */\n  enabled?: boolean\n  refetchInterval?: QueryObserverOptions<\n    Array<T>,\n    TError,\n    Array<T>,\n    Array<T>,\n    TQueryKey\n  >[`refetchInterval`]\n  retry?: QueryObserverOptions<\n    Array<T>,\n    TError,\n    Array<T>,\n    Array<T>,\n    TQueryKey\n  >[`retry`]\n  retryDelay?: QueryObserverOptions<\n    Array<T>,\n    TError,\n    Array<T>,\n    Array<T>,\n    TQueryKey\n  >[`retryDelay`]\n  staleTime?: QueryObserverOptions<\n    Array<T>,\n    TError,\n    Array<T>,\n    Array<T>,\n    TQueryKey\n  >[`staleTime`]\n\n  /**\n   * Metadata to pass to the query.\n   * Available in queryFn via context.meta\n   *\n   * @example\n   * // Using meta for error context\n   * queryFn: async (context) => {\n   *   try {\n   *     return await api.getTodos(userId)\n   *   } catch (error) {\n   *     // Use meta for better error messages\n   *     throw new Error(\n   *       context.meta?.errorMessage || 'Failed to load todos'\n   *     )\n   *   }\n   * },\n   * meta: {\n   *   errorMessage: `Failed to load todos for user ${userId}`\n   * }\n   */\n  meta?: Record<string, unknown>\n}\n\n/**\n * Type for the refetch utility function\n */\nexport type RefetchFn = (opts?: { throwOnError?: boolean }) => Promise<void>\n\n/**\n * Utility methods available on Query Collections for direct writes and manual operations.\n * Direct writes bypass the normal query/mutation flow and write directly to the synced data store.\n * @template TItem - The type of items stored in the collection\n * @template TKey - The type of the item keys\n * @template TInsertInput - The type accepted for insert operations\n * @template TError - The type of errors that can occur during queries\n */\nexport interface QueryCollectionUtils<\n  TItem extends object = Record<string, unknown>,\n  TKey extends string | number = string | number,\n  TInsertInput extends object = TItem,\n  TError = unknown,\n> extends UtilsRecord {\n  /** Manually trigger a refetch of the query */\n  refetch: RefetchFn\n  /** Insert one or more items directly into the synced data store without triggering a query refetch or optimistic update */\n  writeInsert: (data: TInsertInput | Array<TInsertInput>) => void\n  /** Update one or more items directly in the synced data store without triggering a query refetch or optimistic update */\n  writeUpdate: (updates: Partial<TItem> | Array<Partial<TItem>>) => void\n  /** Delete one or more items directly from the synced data store without triggering a query refetch or optimistic update */\n  writeDelete: (keys: TKey | Array<TKey>) => void\n  /** Insert or update one or more items directly in the synced data store without triggering a query refetch or optimistic update */\n  writeUpsert: (data: Partial<TItem> | Array<Partial<TItem>>) => void\n  /** Execute multiple write operations as a single atomic batch to the synced data store */\n  writeBatch: (callback: () => void) => void\n  /** Get the last error encountered by the query (if any); reset on success */\n  lastError: () => TError | undefined\n  /** Check if the collection is in an error state */\n  isError: () => boolean\n  /**\n   * Get the number of consecutive sync failures.\n   * Incremented only when query fails completely (not per retry attempt); reset on success.\n   */\n  errorCount: () => number\n  /**\n   * Clear the error state and trigger a refetch of the query\n   * @returns Promise that resolves when the refetch completes successfully\n   * @throws Error if the refetch fails\n   */\n  clearError: () => Promise<void>\n}\n\n/**\n * Creates query collection options for use with a standard Collection.\n * This integrates TanStack Query with TanStack DB for automatic synchronization.\n *\n * Supports automatic type inference following the priority order:\n * 1. Schema inference (highest priority)\n * 2. QueryFn return type inference (second priority)\n *\n * @template T - Type of the schema if a schema is provided otherwise it is the type of the values returned by the queryFn\n * @template TError - The type of errors that can occur during queries\n * @template TQueryKey - The type of the query key\n * @template TKey - The type of the item keys\n * @param config - Configuration options for the Query collection\n * @returns Collection options with utilities for direct writes and manual operations\n *\n * @example\n * // Type inferred from queryFn return type (NEW!)\n * const todosCollection = createCollection(\n *   queryCollectionOptions({\n *     queryKey: ['todos'],\n *     queryFn: async () => {\n *       const response = await fetch('/api/todos')\n *       return response.json() as Todo[] // Type automatically inferred!\n *     },\n *     queryClient,\n *     getKey: (item) => item.id, // item is typed as Todo\n *   })\n * )\n *\n * @example\n * // Explicit type\n * const todosCollection = createCollection<Todo>(\n *   queryCollectionOptions({\n *     queryKey: ['todos'],\n *     queryFn: async () => fetch('/api/todos').then(r => r.json()),\n *     queryClient,\n *     getKey: (item) => item.id,\n *   })\n * )\n *\n * @example\n * // Schema inference\n * const todosCollection = createCollection(\n *   queryCollectionOptions({\n *     queryKey: ['todos'],\n *     queryFn: async () => fetch('/api/todos').then(r => r.json()),\n *     queryClient,\n *     schema: todoSchema, // Type inferred from schema\n *     getKey: (item) => item.id,\n *   })\n * )\n *\n * @example\n * // With persistence handlers\n * const todosCollection = createCollection(\n *   queryCollectionOptions({\n *     queryKey: ['todos'],\n *     queryFn: fetchTodos,\n *     queryClient,\n *     getKey: (item) => item.id,\n *     onInsert: async ({ transaction }) => {\n *       await api.createTodos(transaction.mutations.map(m => m.modified))\n *     },\n *     onUpdate: async ({ transaction }) => {\n *       await api.updateTodos(transaction.mutations)\n *     },\n *     onDelete: async ({ transaction }) => {\n *       await api.deleteTodos(transaction.mutations.map(m => m.key))\n *     }\n *   })\n * )\n *\n * @example\n * // The select option extracts the items array from a response with metadata\n * const todosCollection = createCollection(\n *   queryCollectionOptions({\n *     queryKey: ['todos'],\n *     queryFn: async () => fetch('/api/todos').then(r => r.json()),\n *     select: (data) => data.items, // Extract the array of items\n *     queryClient,\n *     schema: todoSchema,\n *     getKey: (item) => item.id,\n *   })\n * )\n */\n// Overload for when schema is provided and select present\nexport function queryCollectionOptions<\n  T extends StandardSchemaV1,\n  TQueryFn extends (context: QueryFunctionContext<any>) => Promise<any>,\n  TError = unknown,\n  TQueryKey extends QueryKey = QueryKey,\n  TKey extends string | number = string | number,\n  TQueryData = Awaited<ReturnType<TQueryFn>>,\n>(\n  config: QueryCollectionConfig<\n    InferSchemaOutput<T>,\n    TQueryFn,\n    TError,\n    TQueryKey,\n    TKey,\n    T\n  > & {\n    schema: T\n    select: (data: TQueryData) => Array<InferSchemaInput<T>>\n  }\n): CollectionConfig<InferSchemaOutput<T>, TKey, T> & {\n  schema: T\n  utils: QueryCollectionUtils<\n    InferSchemaOutput<T>,\n    TKey,\n    InferSchemaInput<T>,\n    TError\n  >\n}\n\n// Overload for when no schema is provided and select present\nexport function queryCollectionOptions<\n  T extends object,\n  TQueryFn extends (context: QueryFunctionContext<any>) => Promise<any> = (\n    context: QueryFunctionContext<any>\n  ) => Promise<any>,\n  TError = unknown,\n  TQueryKey extends QueryKey = QueryKey,\n  TKey extends string | number = string | number,\n  TQueryData = Awaited<ReturnType<TQueryFn>>,\n>(\n  config: QueryCollectionConfig<\n    T,\n    TQueryFn,\n    TError,\n    TQueryKey,\n    TKey,\n    never,\n    TQueryData\n  > & {\n    schema?: never // prohibit schema\n    select: (data: TQueryData) => Array<T>\n  }\n): CollectionConfig<T, TKey> & {\n  schema?: never // no schema in the result\n  utils: QueryCollectionUtils<T, TKey, T, TError>\n}\n\n// Overload for when schema is provided\nexport function queryCollectionOptions<\n  T extends StandardSchemaV1,\n  TError = unknown,\n  TQueryKey extends QueryKey = QueryKey,\n  TKey extends string | number = string | number,\n>(\n  config: QueryCollectionConfig<\n    InferSchemaOutput<T>,\n    (\n      context: QueryFunctionContext<any>\n    ) => Promise<Array<InferSchemaOutput<T>>>,\n    TError,\n    TQueryKey,\n    TKey,\n    T\n  > & {\n    schema: T\n  }\n): CollectionConfig<InferSchemaOutput<T>, TKey, T> & {\n  schema: T\n  utils: QueryCollectionUtils<\n    InferSchemaOutput<T>,\n    TKey,\n    InferSchemaInput<T>,\n    TError\n  >\n}\n\n// Overload for when no schema is provided\nexport function queryCollectionOptions<\n  T extends object,\n  TError = unknown,\n  TQueryKey extends QueryKey = QueryKey,\n  TKey extends string | number = string | number,\n>(\n  config: QueryCollectionConfig<\n    T,\n    (context: QueryFunctionContext<any>) => Promise<Array<T>>,\n    TError,\n    TQueryKey,\n    TKey\n  > & {\n    schema?: never // prohibit schema\n  }\n): CollectionConfig<T, TKey> & {\n  schema?: never // no schema in the result\n  utils: QueryCollectionUtils<T, TKey, T, TError>\n}\n\nexport function queryCollectionOptions(\n  config: QueryCollectionConfig<Record<string, unknown>>\n): CollectionConfig & {\n  utils: QueryCollectionUtils\n} {\n  const {\n    queryKey,\n    queryFn,\n    select,\n    queryClient,\n    enabled,\n    refetchInterval,\n    retry,\n    retryDelay,\n    staleTime,\n    getKey,\n    onInsert,\n    onUpdate,\n    onDelete,\n    meta,\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  // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition\n  if (!getKey) {\n    throw new GetKeyRequiredError()\n  }\n\n  /** The last error encountered by the query */\n  let lastError: any\n  /** The number of consecutive sync failures */\n  let errorCount = 0\n  /** The timestamp for when the query most recently returned the status as \"error\" */\n  let lastErrorUpdatedAt = 0\n\n  const internalSync: SyncConfig<any>[`sync`] = (params) => {\n    const { begin, write, commit, markReady, collection } = params\n\n    const observerOptions: QueryObserverOptions<\n      Array<any>,\n      any,\n      Array<any>,\n      Array<any>,\n      any\n    > = {\n      queryKey: queryKey,\n      queryFn: queryFn,\n      structuralSharing: true,\n      notifyOnChangeProps: `all`,\n      // Only include options that are explicitly defined to allow QueryClient defaultOptions to be used\n      ...(meta !== undefined && { meta }),\n      ...(enabled !== undefined && { enabled }),\n      ...(refetchInterval !== undefined && { refetchInterval }),\n      ...(retry !== undefined && { retry }),\n      ...(retryDelay !== undefined && { retryDelay }),\n      ...(staleTime !== undefined && { staleTime }),\n    }\n\n    const localObserver = new QueryObserver<\n      Array<any>,\n      any,\n      Array<any>,\n      Array<any>,\n      any\n    >(queryClient, observerOptions)\n\n    let isSubscribed = false\n    let actualUnsubscribeFn: (() => void) | null = null\n\n    type UpdateHandler = Parameters<typeof localObserver.subscribe>[0]\n    const handleQueryResult: UpdateHandler = (result) => {\n      if (result.isSuccess) {\n        // Clear error state\n        lastError = undefined\n        errorCount = 0\n\n        const rawData = result.data\n        const newItemsArray = select ? select(rawData) : rawData\n\n        if (\n          !Array.isArray(newItemsArray) ||\n          newItemsArray.some((item) => typeof item !== `object`)\n        ) {\n          const errorMessage = select\n            ? `@tanstack/query-db-collection: select() must return an array of objects. Got: ${typeof newItemsArray} for queryKey ${JSON.stringify(queryKey)}`\n            : `@tanstack/query-db-collection: queryFn must return an array of objects. Got: ${typeof newItemsArray} for queryKey ${JSON.stringify(queryKey)}`\n\n          console.error(errorMessage)\n          return\n        }\n\n        const currentSyncedItems: Map<string | number, any> = new Map(\n          collection._state.syncedData.entries()\n        )\n        const newItemsMap = new Map<string | number, any>()\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            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        if (result.errorUpdatedAt !== lastErrorUpdatedAt) {\n          lastError = result.error\n          errorCount++\n          lastErrorUpdatedAt = result.errorUpdatedAt\n        }\n\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    const subscribeToQuery = () => {\n      if (!isSubscribed) {\n        actualUnsubscribeFn = localObserver.subscribe(handleQueryResult)\n        isSubscribed = true\n      }\n    }\n\n    const unsubscribeFromQuery = () => {\n      if (isSubscribed && actualUnsubscribeFn) {\n        actualUnsubscribeFn()\n        actualUnsubscribeFn = null\n        isSubscribed = false\n      }\n    }\n\n    // Always subscribe when sync starts (this could be from preload(), startSync config, or first subscriber)\n    // We'll dynamically unsubscribe/resubscribe based on subscriber count to maintain staleTime behavior\n    subscribeToQuery()\n\n    // Set up event listener for subscriber changes\n    const unsubscribeFromCollectionEvents = collection.on(\n      `subscribers:change`,\n      ({ subscriberCount }) => {\n        if (subscriberCount > 0) {\n          subscribeToQuery()\n        } else if (subscriberCount === 0) {\n          unsubscribeFromQuery()\n        }\n      }\n    )\n\n    // Ensure we process any existing query data (QueryObserver doesn't invoke its callback automatically with initial\n    // state)\n    handleQueryResult(localObserver.getCurrentResult())\n\n    return async () => {\n      unsubscribeFromCollectionEvents()\n      unsubscribeFromQuery()\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 = (opts) => {\n    return queryClient.refetchQueries(\n      {\n        queryKey: queryKey,\n      },\n      {\n        throwOnError: opts?.throwOnError,\n      }\n    )\n  }\n\n  // Create write context for manual write operations\n  let writeContext: {\n    collection: any\n    queryClient: QueryClient\n    queryKey: Array<unknown>\n    getKey: (item: any) => string | number\n    begin: () => void\n    write: (message: Omit<ChangeMessage<any>, `key`>) => void\n    commit: () => void\n  } | null = null\n\n  // Enhanced internalSync that captures write functions for manual use\n  const enhancedInternalSync: SyncConfig<any>[`sync`] = (params) => {\n    const { begin, write, commit, collection } = params\n\n    // Store references for manual write operations\n    writeContext = {\n      collection,\n      queryClient,\n      queryKey: queryKey as unknown as Array<unknown>,\n      getKey: getKey as (item: any) => string | number,\n      begin,\n      write,\n      commit,\n    }\n\n    // Call the original internalSync logic\n    return internalSync(params)\n  }\n\n  // Create write utils using the manual-sync module\n  const writeUtils = createWriteUtils<any, string | number, any>(\n    () => writeContext\n  )\n\n  // Create wrapper handlers for direct persistence operations that handle refetching\n  const wrappedOnInsert = onInsert\n    ? async (params: InsertMutationFnParams<any>) => {\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<any>) => {\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<any>) => {\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: enhancedInternalSync },\n    onInsert: wrappedOnInsert,\n    onUpdate: wrappedOnUpdate,\n    onDelete: wrappedOnDelete,\n    utils: {\n      refetch,\n      ...writeUtils,\n      lastError: () => lastError,\n      isError: () => !!lastError,\n      errorCount: () => errorCount,\n      clearError: () => {\n        lastError = undefined\n        errorCount = 0\n        lastErrorUpdatedAt = 0\n        return refetch({ throwOnError: true })\n      },\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 { createWriteUtils } from \"./manual-sync\"\nimport type {\n  QueryClient,\n  QueryFunctionContext,\n  QueryKey,\n  QueryObserverOptions,\n  QueryObserverResult,\n} from \"@tanstack/query-core\"\nimport type {\n  BaseCollectionConfig,\n  ChangeMessage,\n  CollectionConfig,\n  DeleteMutationFnParams,\n  InsertMutationFnParams,\n  SyncConfig,\n  UpdateMutationFnParams,\n  UtilsRecord,\n} from \"@tanstack/db\"\nimport type { StandardSchemaV1 } from \"@standard-schema/spec\"\n\n// Re-export for external use\nexport type { SyncOperation } from \"./manual-sync\"\n\n// Schema output type inference helper (matches electric.ts pattern)\ntype InferSchemaOutput<T> = T extends StandardSchemaV1\n  ? StandardSchemaV1.InferOutput<T> extends object\n    ? StandardSchemaV1.InferOutput<T>\n    : Record<string, unknown>\n  : Record<string, unknown>\n\n// Schema input type inference helper (matches electric.ts pattern)\ntype InferSchemaInput<T> = T extends StandardSchemaV1\n  ? StandardSchemaV1.InferInput<T> extends object\n    ? StandardSchemaV1.InferInput<T>\n    : Record<string, unknown>\n  : Record<string, unknown>\n\n/**\n * Configuration options for creating a Query Collection\n * @template T - The explicit type of items stored in the collection\n * @template TQueryFn - The queryFn type\n * @template TError - The type of errors that can occur during queries\n * @template TQueryKey - The type of the query key\n * @template TKey - The type of the item keys\n * @template TSchema - The schema type for validation\n */\nexport interface QueryCollectionConfig<\n  T extends object = object,\n  TQueryFn extends (context: QueryFunctionContext<any>) => Promise<any> = (\n    context: QueryFunctionContext<any>\n  ) => Promise<any>,\n  TError = unknown,\n  TQueryKey extends QueryKey = QueryKey,\n  TKey extends string | number = string | number,\n  TSchema extends StandardSchemaV1 = never,\n  TQueryData = Awaited<ReturnType<TQueryFn>>,\n> extends BaseCollectionConfig<T, TKey, TSchema> {\n  /** The query key used by TanStack Query to identify this query */\n  queryKey: TQueryKey\n  /** Function that fetches data from the server. Must return the complete collection state */\n  queryFn: TQueryFn extends (\n    context: QueryFunctionContext<TQueryKey>\n  ) => Promise<Array<any>>\n    ? (context: QueryFunctionContext<TQueryKey>) => Promise<Array<T>>\n    : TQueryFn\n  /* Function that extracts array items from wrapped API responses (e.g metadata, pagination)  */\n  select?: (data: TQueryData) => Array<T>\n  /** The TanStack Query client instance */\n  queryClient: QueryClient\n\n  // Query-specific options\n  /** Whether the query should automatically run (default: true) */\n  enabled?: boolean\n  refetchInterval?: QueryObserverOptions<\n    Array<T>,\n    TError,\n    Array<T>,\n    Array<T>,\n    TQueryKey\n  >[`refetchInterval`]\n  retry?: QueryObserverOptions<\n    Array<T>,\n    TError,\n    Array<T>,\n    Array<T>,\n    TQueryKey\n  >[`retry`]\n  retryDelay?: QueryObserverOptions<\n    Array<T>,\n    TError,\n    Array<T>,\n    Array<T>,\n    TQueryKey\n  >[`retryDelay`]\n  staleTime?: QueryObserverOptions<\n    Array<T>,\n    TError,\n    Array<T>,\n    Array<T>,\n    TQueryKey\n  >[`staleTime`]\n\n  /**\n   * Metadata to pass to the query.\n   * Available in queryFn via context.meta\n   *\n   * @example\n   * // Using meta for error context\n   * queryFn: async (context) => {\n   *   try {\n   *     return await api.getTodos(userId)\n   *   } catch (error) {\n   *     // Use meta for better error messages\n   *     throw new Error(\n   *       context.meta?.errorMessage || 'Failed to load todos'\n   *     )\n   *   }\n   * },\n   * meta: {\n   *   errorMessage: `Failed to load todos for user ${userId}`\n   * }\n   */\n  meta?: Record<string, unknown>\n}\n\n/**\n * Type for the refetch utility function\n * Returns the QueryObserverResult from TanStack Query\n */\nexport type RefetchFn = (opts?: {\n  throwOnError?: boolean\n}) => Promise<QueryObserverResult<any, any> | void>\n\n/**\n * Utility methods available on Query Collections for direct writes and manual operations.\n * Direct writes bypass the normal query/mutation flow and write directly to the synced data store.\n * @template TItem - The type of items stored in the collection\n * @template TKey - The type of the item keys\n * @template TInsertInput - The type accepted for insert operations\n * @template TError - The type of errors that can occur during queries\n */\nexport interface QueryCollectionUtils<\n  TItem extends object = Record<string, unknown>,\n  TKey extends string | number = string | number,\n  TInsertInput extends object = TItem,\n  TError = unknown,\n> extends UtilsRecord {\n  /** Manually trigger a refetch of the query */\n  refetch: RefetchFn\n  /** Insert one or more items directly into the synced data store without triggering a query refetch or optimistic update */\n  writeInsert: (data: TInsertInput | Array<TInsertInput>) => void\n  /** Update one or more items directly in the synced data store without triggering a query refetch or optimistic update */\n  writeUpdate: (updates: Partial<TItem> | Array<Partial<TItem>>) => void\n  /** Delete one or more items directly from the synced data store without triggering a query refetch or optimistic update */\n  writeDelete: (keys: TKey | Array<TKey>) => void\n  /** Insert or update one or more items directly in the synced data store without triggering a query refetch or optimistic update */\n  writeUpsert: (data: Partial<TItem> | Array<Partial<TItem>>) => void\n  /** Execute multiple write operations as a single atomic batch to the synced data store */\n  writeBatch: (callback: () => void) => void\n  /** Get the last error encountered by the query (if any); reset on success */\n  lastError: () => TError | undefined\n  /** Check if the collection is in an error state */\n  isError: () => boolean\n  /**\n   * Get the number of consecutive sync failures.\n   * Incremented only when query fails completely (not per retry attempt); reset on success.\n   */\n  errorCount: () => number\n  /**\n   * Clear the error state and trigger a refetch of the query\n   * @returns Promise that resolves when the refetch completes successfully\n   * @throws Error if the refetch fails\n   */\n  clearError: () => Promise<void>\n}\n\n/**\n * Creates query collection options for use with a standard Collection.\n * This integrates TanStack Query with TanStack DB for automatic synchronization.\n *\n * Supports automatic type inference following the priority order:\n * 1. Schema inference (highest priority)\n * 2. QueryFn return type inference (second priority)\n *\n * @template T - Type of the schema if a schema is provided otherwise it is the type of the values returned by the queryFn\n * @template TError - The type of errors that can occur during queries\n * @template TQueryKey - The type of the query key\n * @template TKey - The type of the item keys\n * @param config - Configuration options for the Query collection\n * @returns Collection options with utilities for direct writes and manual operations\n *\n * @example\n * // Type inferred from queryFn return type (NEW!)\n * const todosCollection = createCollection(\n *   queryCollectionOptions({\n *     queryKey: ['todos'],\n *     queryFn: async () => {\n *       const response = await fetch('/api/todos')\n *       return response.json() as Todo[] // Type automatically inferred!\n *     },\n *     queryClient,\n *     getKey: (item) => item.id, // item is typed as Todo\n *   })\n * )\n *\n * @example\n * // Explicit type\n * const todosCollection = createCollection<Todo>(\n *   queryCollectionOptions({\n *     queryKey: ['todos'],\n *     queryFn: async () => fetch('/api/todos').then(r => r.json()),\n *     queryClient,\n *     getKey: (item) => item.id,\n *   })\n * )\n *\n * @example\n * // Schema inference\n * const todosCollection = createCollection(\n *   queryCollectionOptions({\n *     queryKey: ['todos'],\n *     queryFn: async () => fetch('/api/todos').then(r => r.json()),\n *     queryClient,\n *     schema: todoSchema, // Type inferred from schema\n *     getKey: (item) => item.id,\n *   })\n * )\n *\n * @example\n * // With persistence handlers\n * const todosCollection = createCollection(\n *   queryCollectionOptions({\n *     queryKey: ['todos'],\n *     queryFn: fetchTodos,\n *     queryClient,\n *     getKey: (item) => item.id,\n *     onInsert: async ({ transaction }) => {\n *       await api.createTodos(transaction.mutations.map(m => m.modified))\n *     },\n *     onUpdate: async ({ transaction }) => {\n *       await api.updateTodos(transaction.mutations)\n *     },\n *     onDelete: async ({ transaction }) => {\n *       await api.deleteTodos(transaction.mutations.map(m => m.key))\n *     }\n *   })\n * )\n *\n * @example\n * // The select option extracts the items array from a response with metadata\n * const todosCollection = createCollection(\n *   queryCollectionOptions({\n *     queryKey: ['todos'],\n *     queryFn: async () => fetch('/api/todos').then(r => r.json()),\n *     select: (data) => data.items, // Extract the array of items\n *     queryClient,\n *     schema: todoSchema,\n *     getKey: (item) => item.id,\n *   })\n * )\n */\n// Overload for when schema is provided and select present\nexport function queryCollectionOptions<\n  T extends StandardSchemaV1,\n  TQueryFn extends (context: QueryFunctionContext<any>) => Promise<any>,\n  TError = unknown,\n  TQueryKey extends QueryKey = QueryKey,\n  TKey extends string | number = string | number,\n  TQueryData = Awaited<ReturnType<TQueryFn>>,\n>(\n  config: QueryCollectionConfig<\n    InferSchemaOutput<T>,\n    TQueryFn,\n    TError,\n    TQueryKey,\n    TKey,\n    T\n  > & {\n    schema: T\n    select: (data: TQueryData) => Array<InferSchemaInput<T>>\n  }\n): CollectionConfig<InferSchemaOutput<T>, TKey, T> & {\n  schema: T\n  utils: QueryCollectionUtils<\n    InferSchemaOutput<T>,\n    TKey,\n    InferSchemaInput<T>,\n    TError\n  >\n}\n\n// Overload for when no schema is provided and select present\nexport function queryCollectionOptions<\n  T extends object,\n  TQueryFn extends (context: QueryFunctionContext<any>) => Promise<any> = (\n    context: QueryFunctionContext<any>\n  ) => Promise<any>,\n  TError = unknown,\n  TQueryKey extends QueryKey = QueryKey,\n  TKey extends string | number = string | number,\n  TQueryData = Awaited<ReturnType<TQueryFn>>,\n>(\n  config: QueryCollectionConfig<\n    T,\n    TQueryFn,\n    TError,\n    TQueryKey,\n    TKey,\n    never,\n    TQueryData\n  > & {\n    schema?: never // prohibit schema\n    select: (data: TQueryData) => Array<T>\n  }\n): CollectionConfig<T, TKey> & {\n  schema?: never // no schema in the result\n  utils: QueryCollectionUtils<T, TKey, T, TError>\n}\n\n// Overload for when schema is provided\nexport function queryCollectionOptions<\n  T extends StandardSchemaV1,\n  TError = unknown,\n  TQueryKey extends QueryKey = QueryKey,\n  TKey extends string | number = string | number,\n>(\n  config: QueryCollectionConfig<\n    InferSchemaOutput<T>,\n    (\n      context: QueryFunctionContext<any>\n    ) => Promise<Array<InferSchemaOutput<T>>>,\n    TError,\n    TQueryKey,\n    TKey,\n    T\n  > & {\n    schema: T\n  }\n): CollectionConfig<InferSchemaOutput<T>, TKey, T> & {\n  schema: T\n  utils: QueryCollectionUtils<\n    InferSchemaOutput<T>,\n    TKey,\n    InferSchemaInput<T>,\n    TError\n  >\n}\n\n// Overload for when no schema is provided\nexport function queryCollectionOptions<\n  T extends object,\n  TError = unknown,\n  TQueryKey extends QueryKey = QueryKey,\n  TKey extends string | number = string | number,\n>(\n  config: QueryCollectionConfig<\n    T,\n    (context: QueryFunctionContext<any>) => Promise<Array<T>>,\n    TError,\n    TQueryKey,\n    TKey\n  > & {\n    schema?: never // prohibit schema\n  }\n): CollectionConfig<T, TKey> & {\n  schema?: never // no schema in the result\n  utils: QueryCollectionUtils<T, TKey, T, TError>\n}\n\nexport function queryCollectionOptions(\n  config: QueryCollectionConfig<Record<string, unknown>>\n): CollectionConfig & {\n  utils: QueryCollectionUtils\n} {\n  const {\n    queryKey,\n    queryFn,\n    select,\n    queryClient,\n    enabled,\n    refetchInterval,\n    retry,\n    retryDelay,\n    staleTime,\n    getKey,\n    onInsert,\n    onUpdate,\n    onDelete,\n    meta,\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  // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition\n  if (!getKey) {\n    throw new GetKeyRequiredError()\n  }\n\n  /** The last error encountered by the query */\n  let lastError: any\n  /** The number of consecutive sync failures */\n  let errorCount = 0\n  /** The timestamp for when the query most recently returned the status as \"error\" */\n  let lastErrorUpdatedAt = 0\n  /** Reference to the QueryObserver for imperative refetch */\n  let queryObserver: QueryObserver<Array<any>, any, Array<any>, Array<any>, any>\n\n  const internalSync: SyncConfig<any>[`sync`] = (params) => {\n    const { begin, write, commit, markReady, collection } = params\n\n    const observerOptions: QueryObserverOptions<\n      Array<any>,\n      any,\n      Array<any>,\n      Array<any>,\n      any\n    > = {\n      queryKey: queryKey,\n      queryFn: queryFn,\n      structuralSharing: true,\n      notifyOnChangeProps: `all`,\n      // Only include options that are explicitly defined to allow QueryClient defaultOptions to be used\n      ...(meta !== undefined && { meta }),\n      ...(enabled !== undefined && { enabled }),\n      ...(refetchInterval !== undefined && { refetchInterval }),\n      ...(retry !== undefined && { retry }),\n      ...(retryDelay !== undefined && { retryDelay }),\n      ...(staleTime !== undefined && { staleTime }),\n    }\n\n    const localObserver = new QueryObserver<\n      Array<any>,\n      any,\n      Array<any>,\n      Array<any>,\n      any\n    >(queryClient, observerOptions)\n\n    // Store reference for imperative refetch\n    queryObserver = localObserver\n\n    let isSubscribed = false\n    let actualUnsubscribeFn: (() => void) | null = null\n\n    type UpdateHandler = Parameters<typeof localObserver.subscribe>[0]\n    const handleQueryResult: UpdateHandler = (result) => {\n      if (result.isSuccess) {\n        // Clear error state\n        lastError = undefined\n        errorCount = 0\n\n        const rawData = result.data\n        const newItemsArray = select ? select(rawData) : rawData\n\n        if (\n          !Array.isArray(newItemsArray) ||\n          newItemsArray.some((item) => typeof item !== `object`)\n        ) {\n          const errorMessage = select\n            ? `@tanstack/query-db-collection: select() must return an array of objects. Got: ${typeof newItemsArray} for queryKey ${JSON.stringify(queryKey)}`\n            : `@tanstack/query-db-collection: queryFn must return an array of objects. Got: ${typeof newItemsArray} for queryKey ${JSON.stringify(queryKey)}`\n\n          console.error(errorMessage)\n          return\n        }\n\n        const currentSyncedItems: Map<string | number, any> = new Map(\n          collection._state.syncedData.entries()\n        )\n        const newItemsMap = new Map<string | number, any>()\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            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        if (result.errorUpdatedAt !== lastErrorUpdatedAt) {\n          lastError = result.error\n          errorCount++\n          lastErrorUpdatedAt = result.errorUpdatedAt\n        }\n\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    const subscribeToQuery = () => {\n      if (!isSubscribed) {\n        actualUnsubscribeFn = localObserver.subscribe(handleQueryResult)\n        isSubscribed = true\n      }\n    }\n\n    const unsubscribeFromQuery = () => {\n      if (isSubscribed && actualUnsubscribeFn) {\n        actualUnsubscribeFn()\n        actualUnsubscribeFn = null\n        isSubscribed = false\n      }\n    }\n\n    // Always subscribe when sync starts (this could be from preload(), startSync config, or first subscriber)\n    // We'll dynamically unsubscribe/resubscribe based on subscriber count to maintain staleTime behavior\n    subscribeToQuery()\n\n    // Set up event listener for subscriber changes\n    const unsubscribeFromCollectionEvents = collection.on(\n      `subscribers:change`,\n      ({ subscriberCount }) => {\n        if (subscriberCount > 0) {\n          subscribeToQuery()\n        } else if (subscriberCount === 0) {\n          unsubscribeFromQuery()\n        }\n      }\n    )\n\n    // Ensure we process any existing query data (QueryObserver doesn't invoke its callback automatically with initial\n    // state)\n    handleQueryResult(localObserver.getCurrentResult())\n\n    return async () => {\n      unsubscribeFromCollectionEvents()\n      unsubscribeFromQuery()\n      await queryClient.cancelQueries({ queryKey })\n      queryClient.removeQueries({ queryKey })\n    }\n  }\n\n  /**\n   * Refetch the query data\n   *\n   * Uses queryObserver.refetch() because:\n   * - Bypasses `enabled: false` to support manual/imperative refetch patterns (e.g., button-triggered fetch)\n   * - Ensures clearError() works even when enabled: false\n   * - Always refetches THIS specific collection (exact targeting via observer)\n   * - Respects retry, retryDelay, and other observer options\n   *\n   * This matches TanStack Query's hook behavior where refetch() bypasses enabled: false.\n   * See: https://tanstack.com/query/latest/docs/framework/react/guides/disabling-queries\n   *\n   * Used by both:\n   * - utils.refetch() - for explicit user-triggered refetches\n   * - Internal handlers (onInsert/onUpdate/onDelete) - after mutations to get fresh data\n   *\n   * @returns Promise that resolves when the refetch is complete, with QueryObserverResult\n   */\n  const refetch: RefetchFn = async (opts) => {\n    // Observer is created when sync starts. If never synced, nothing to refetch.\n    // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition\n    if (!queryObserver) {\n      return\n    }\n    // Return the QueryObserverResult for users to inspect\n    return queryObserver.refetch({\n      throwOnError: opts?.throwOnError,\n    })\n  }\n\n  // Create write context for manual write operations\n  let writeContext: {\n    collection: any\n    queryClient: QueryClient\n    queryKey: Array<unknown>\n    getKey: (item: any) => string | number\n    begin: () => void\n    write: (message: Omit<ChangeMessage<any>, `key`>) => void\n    commit: () => void\n  } | null = null\n\n  // Enhanced internalSync that captures write functions for manual use\n  const enhancedInternalSync: SyncConfig<any>[`sync`] = (params) => {\n    const { begin, write, commit, collection } = params\n\n    // Store references for manual write operations\n    writeContext = {\n      collection,\n      queryClient,\n      queryKey: queryKey as unknown as Array<unknown>,\n      getKey: getKey as (item: any) => string | number,\n      begin,\n      write,\n      commit,\n    }\n\n    // Call the original internalSync logic\n    return internalSync(params)\n  }\n\n  // Create write utils using the manual-sync module\n  const writeUtils = createWriteUtils<any, string | number, any>(\n    () => writeContext\n  )\n\n  // Create wrapper handlers for direct persistence operations that handle refetching\n  const wrappedOnInsert = onInsert\n    ? async (params: InsertMutationFnParams<any>) => {\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<any>) => {\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<any>) => {\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: enhancedInternalSync },\n    onInsert: wrappedOnInsert,\n    onUpdate: wrappedOnUpdate,\n    onDelete: wrappedOnDelete,\n    utils: {\n      refetch,\n      ...writeUtils,\n      lastError: () => lastError,\n      isError: () => !!lastError,\n      errorCount: () => errorCount,\n      clearError: async () => {\n        lastError = undefined\n        errorCount = 0\n        lastErrorUpdatedAt = 0\n        await refetch({ throwOnError: true })\n      },\n    },\n  }\n}\n"],"names":[],"mappings":"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"}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@tanstack/query-db-collection",
   "description": "TanStack Query collection for TanStack DB",
-  "version": "0.2.36",
+  "version": "0.2.37",
   "dependencies": {
     "@standard-schema/spec": "^1.0.0",
     "@tanstack/db": "0.4.14"

package/src/query.ts

@@ -11,6 +11,7 @@ import type {
   QueryFunctionContext,
   QueryKey,
   QueryObserverOptions,
+  QueryObserverResult,
 } from "@tanstack/query-core"
 import type {
   BaseCollectionConfig,
@@ -131,8 +132,11 @@ export interface QueryCollectionConfig<
 
 /**
  * Type for the refetch utility function
+ * Returns the QueryObserverResult from TanStack Query
  */
-export type RefetchFn = (opts?: { throwOnError?: boolean }) => Promise<void>
+export type RefetchFn = (opts?: {
+  throwOnError?: boolean
+}) => Promise<QueryObserverResult<any, any> | void>
 
 /**
  * Utility methods available on Query Collections for direct writes and manual operations.
@@ -420,6 +424,8 @@ export function queryCollectionOptions(
   let errorCount = 0
   /** The timestamp for when the query most recently returned the status as "error" */
   let lastErrorUpdatedAt = 0
+  /** Reference to the QueryObserver for imperative refetch */
+  let queryObserver: QueryObserver<Array<any>, any, Array<any>, Array<any>, any>
 
   const internalSync: SyncConfig<any>[`sync`] = (params) => {
     const { begin, write, commit, markReady, collection } = params
@@ -452,6 +458,9 @@ export function queryCollectionOptions(
       any
     >(queryClient, observerOptions)
 
+    // Store reference for imperative refetch
+    queryObserver = localObserver
+
     let isSubscribed = false
     let actualUnsubscribeFn: (() => void) | null = null
 
@@ -595,17 +604,32 @@ export function queryCollectionOptions(
 
   /**
    * Refetch the query data
-   * @returns Promise that resolves when the refetch is complete
+   *
+   * Uses queryObserver.refetch() because:
+   * - Bypasses `enabled: false` to support manual/imperative refetch patterns (e.g., button-triggered fetch)
+   * - Ensures clearError() works even when enabled: false
+   * - Always refetches THIS specific collection (exact targeting via observer)
+   * - Respects retry, retryDelay, and other observer options
+   *
+   * This matches TanStack Query's hook behavior where refetch() bypasses enabled: false.
+   * See: https://tanstack.com/query/latest/docs/framework/react/guides/disabling-queries
+   *
+   * Used by both:
+   * - utils.refetch() - for explicit user-triggered refetches
+   * - Internal handlers (onInsert/onUpdate/onDelete) - after mutations to get fresh data
+   *
+   * @returns Promise that resolves when the refetch is complete, with QueryObserverResult
    */
-  const refetch: RefetchFn = (opts) => {
-    return queryClient.refetchQueries(
-      {
-        queryKey: queryKey,
-      },
-      {
-        throwOnError: opts?.throwOnError,
-      }
-    )
+  const refetch: RefetchFn = async (opts) => {
+    // Observer is created when sync starts. If never synced, nothing to refetch.
+    // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+    if (!queryObserver) {
+      return
+    }
+    // Return the QueryObserverResult for users to inspect
+    return queryObserver.refetch({
+      throwOnError: opts?.throwOnError,
+    })
   }
 
   // Create write context for manual write operations
@@ -699,11 +723,11 @@ export function queryCollectionOptions(
       lastError: () => lastError,
       isError: () => !!lastError,
       errorCount: () => errorCount,
-      clearError: () => {
+      clearError: async () => {
         lastError = undefined
         errorCount = 0
         lastErrorUpdatedAt = 0
-        return refetch({ throwOnError: true })
+        await refetch({ throwOnError: true })
       },
     },
   }