@tanstack/db-collections/dist/cjs/query.cjs.map

A collection for (aspirationally) every way of loading your data

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