@tanstack/query-db-collection 1.0.6 → 1.0.8

package/src/manual-sync.ts

@@ -3,9 +3,9 @@ import {
   DuplicateKeyInBatchError,
   SyncNotInitializedError,
   UpdateOperationItemNotFoundError,
-} from "./errors"
-import type { QueryClient } from "@tanstack/query-core"
-import type { ChangeMessage, Collection } from "@tanstack/db"
+} from './errors'
+import type { QueryClient } from '@tanstack/query-core'
+import type { ChangeMessage, Collection } from '@tanstack/db'
 
 // Track active batch operations per context to prevent cross-collection contamination
 const activeBatchContexts = new WeakMap<
@@ -38,6 +38,12 @@ export interface SyncContext<
   begin: () => void
   write: (message: Omit<ChangeMessage<TRow>, `key`>) => void
   commit: () => void
+  /**
+   * Optional function to update the query cache with the latest synced data.
+   * Handles both direct array caches and wrapped response formats (when `select` is used).
+   * If not provided, falls back to directly setting the cache with the raw array.
+   */
+  updateCacheData?: (items: Array<TRow>) => void
 }
 
 interface NormalizedOperation<
@@ -58,7 +64,7 @@ function normalizeOperations<
   ops:
     | SyncOperation<TRow, TKey, TInsertInput>
     | Array<SyncOperation<TRow, TKey, TInsertInput>>,
-  ctx: SyncContext<TRow, TKey>
+  ctx: SyncContext<TRow, TKey>,
 ): Array<NormalizedOperation<TRow, TKey>> {
   const operations = Array.isArray(ops) ? ops : [ops]
   const normalized: Array<NormalizedOperation<TRow, TKey>> = []
@@ -80,7 +86,7 @@ function normalizeOperations<
           // For insert/upsert, validate and resolve the full item first
           const resolved = ctx.collection.validateData(
             item,
-            op.type === `upsert` ? `insert` : op.type
+            op.type === `upsert` ? `insert` : op.type,
           )
           key = ctx.getKey(resolved)
         }
@@ -98,7 +104,7 @@ function validateOperations<
   TKey extends string | number = string | number,
 >(
   operations: Array<NormalizedOperation<TRow, TKey>>,
-  ctx: SyncContext<TRow, TKey>
+  ctx: SyncContext<TRow, TKey>,
 ): void {
   const seenKeys = new Set<TKey>()
 
@@ -133,7 +139,7 @@ export function performWriteOperations<
   operations:
     | SyncOperation<TRow, TKey, TInsertInput>
     | Array<SyncOperation<TRow, TKey, TInsertInput>>,
-  ctx: SyncContext<TRow, TKey>
+  ctx: SyncContext<TRow, TKey>,
 ): void {
   const normalized = normalizeOperations(operations, ctx)
   validateOperations(normalized, ctx)
@@ -160,7 +166,7 @@ export function performWriteOperations<
         const resolved = ctx.collection.validateData(
           updatedItem,
           `update`,
-          op.key
+          op.key,
         )
         ctx.write({
           type: `update`,
@@ -183,7 +189,7 @@ export function performWriteOperations<
         const resolved = ctx.collection.validateData(
           op.data,
           existsInSyncedStore ? `update` : `insert`,
-          op.key
+          op.key,
         )
         if (existsInSyncedStore) {
           ctx.write({
@@ -205,7 +211,12 @@ export function performWriteOperations<
 
   // Update query cache after successful commit
   const updatedData = Array.from(ctx.collection._state.syncedData.values())
-  ctx.queryClient.setQueryData(ctx.queryKey, updatedData)
+  if (ctx.updateCacheData) {
+    ctx.updateCacheData(updatedData)
+  } else {
+    // Fallback: directly set the cache with raw array (for non-Query Collection consumers)
+    ctx.queryClient.setQueryData(ctx.queryKey, updatedData)
+  }
 }
 
 // Factory function to create write utils
@@ -300,7 +311,7 @@ export function createWriteUtils<
       const existingBatch = activeBatchContexts.get(ctx)
       if (existingBatch?.isActive) {
         throw new Error(
-          `Cannot nest writeBatch calls. Complete the current batch before starting a new one.`
+          `Cannot nest writeBatch calls. Complete the current batch before starting a new one.`,
         )
       }
 
@@ -326,7 +337,7 @@ export function createWriteUtils<
           typeof result.then === `function`
         ) {
           throw new Error(
-            `writeBatch does not support async callbacks. The callback must be synchronous.`
+            `writeBatch does not support async callbacks. The callback must be synchronous.`,
           )
         }
 

package/src/query.ts

@@ -1,13 +1,13 @@
-import { QueryObserver, hashKey } from "@tanstack/query-core"
-import { deepEquals } from "@tanstack/db"
+import { QueryObserver, hashKey } from '@tanstack/query-core'
+import { deepEquals } from '@tanstack/db'
 import {
   GetKeyRequiredError,
   QueryClientRequiredError,
   QueryFnRequiredError,
   QueryKeyRequiredError,
-} from "./errors"
-import { createWriteUtils } from "./manual-sync"
-import { serializeLoadSubsetOptions } from "./serialization"
+} from './errors'
+import { createWriteUtils } from './manual-sync'
+import { serializeLoadSubsetOptions } from './serialization'
 import type {
   BaseCollectionConfig,
   ChangeMessage,
@@ -18,7 +18,7 @@ import type {
   SyncConfig,
   UpdateMutationFnParams,
   UtilsRecord,
-} from "@tanstack/db"
+} from '@tanstack/db'
 import type {
   FetchStatus,
   QueryClient,
@@ -26,11 +26,11 @@ import type {
   QueryKey,
   QueryObserverOptions,
   QueryObserverResult,
-} from "@tanstack/query-core"
-import type { StandardSchemaV1 } from "@standard-schema/spec"
+} from '@tanstack/query-core'
+import type { StandardSchemaV1 } from '@standard-schema/spec'
 
 // Re-export for external use
-export type { SyncOperation } from "./manual-sync"
+export type { SyncOperation } from './manual-sync'
 
 // Schema output type inference helper (matches electric.ts pattern)
 type InferSchemaOutput<T> = T extends StandardSchemaV1
@@ -60,7 +60,7 @@ type TQueryKeyBuilder<TQueryKey> = (opts: LoadSubsetOptions) => TQueryKey
 export interface QueryCollectionConfig<
   T extends object = object,
   TQueryFn extends (context: QueryFunctionContext<any>) => Promise<any> = (
-    context: QueryFunctionContext<any>
+    context: QueryFunctionContext<any>,
   ) => Promise<any>,
   TError = unknown,
   TQueryKey extends QueryKey = QueryKey,
@@ -72,7 +72,7 @@ export interface QueryCollectionConfig<
   queryKey: TQueryKey | TQueryKeyBuilder<TQueryKey>
   /** Function that fetches data from the server. Must return the complete collection state */
   queryFn: TQueryFn extends (
-    context: QueryFunctionContext<TQueryKey>
+    context: QueryFunctionContext<TQueryKey>,
   ) => Promise<Array<any>>
     ? (context: QueryFunctionContext<TQueryKey>) => Promise<Array<T>>
     : TQueryFn
@@ -232,7 +232,7 @@ class QueryCollectionUtilsImpl {
   constructor(
     state: QueryCollectionState,
     refetch: RefetchFn,
-    writeUtils: ReturnType<typeof createWriteUtils>
+    writeUtils: ReturnType<typeof createWriteUtils>,
   ) {
     this.state = state
     this.refetchFn = refetch
@@ -270,21 +270,21 @@ class QueryCollectionUtilsImpl {
   public get isFetching() {
     // check if any observer is fetching
     return Array.from(this.state.observers.values()).some(
-      (observer) => observer.getCurrentResult().isFetching
+      (observer) => observer.getCurrentResult().isFetching,
     )
   }
 
   public get isRefetching() {
     // check if any observer is refetching
     return Array.from(this.state.observers.values()).some(
-      (observer) => observer.getCurrentResult().isRefetching
+      (observer) => observer.getCurrentResult().isRefetching,
     )
   }
 
   public get isLoading() {
     // check if any observer is loading
     return Array.from(this.state.observers.values()).some(
-      (observer) => observer.getCurrentResult().isLoading
+      (observer) => observer.getCurrentResult().isLoading,
     )
   }
 
@@ -293,14 +293,14 @@ class QueryCollectionUtilsImpl {
     return Math.max(
       0,
       ...Array.from(this.state.observers.values()).map(
-        (observer) => observer.getCurrentResult().dataUpdatedAt
-      )
+        (observer) => observer.getCurrentResult().dataUpdatedAt,
+      ),
     )
   }
 
   public get fetchStatus(): Array<FetchStatus> {
     return Array.from(this.state.observers.values()).map(
-      (observer) => observer.getCurrentResult().fetchStatus
+      (observer) => observer.getCurrentResult().fetchStatus,
     )
   }
 }
@@ -409,7 +409,7 @@ export function queryCollectionOptions<
   > & {
     schema: T
     select: (data: TQueryData) => Array<InferSchemaInput<T>>
-  }
+  },
 ): CollectionConfig<
   InferSchemaOutput<T>,
   TKey,
@@ -429,7 +429,7 @@ export function queryCollectionOptions<
 export function queryCollectionOptions<
   T extends object,
   TQueryFn extends (context: QueryFunctionContext<any>) => Promise<any> = (
-    context: QueryFunctionContext<any>
+    context: QueryFunctionContext<any>,
   ) => Promise<any>,
   TError = unknown,
   TQueryKey extends QueryKey = QueryKey,
@@ -447,7 +447,7 @@ export function queryCollectionOptions<
   > & {
     schema?: never // prohibit schema
     select: (data: TQueryData) => Array<T>
-  }
+  },
 ): CollectionConfig<
   T,
   TKey,
@@ -468,7 +468,7 @@ export function queryCollectionOptions<
   config: QueryCollectionConfig<
     InferSchemaOutput<T>,
     (
-      context: QueryFunctionContext<any>
+      context: QueryFunctionContext<any>,
     ) => Promise<Array<InferSchemaOutput<T>>>,
     TError,
     TQueryKey,
@@ -476,7 +476,7 @@ export function queryCollectionOptions<
     T
   > & {
     schema: T
-  }
+  },
 ): CollectionConfig<
   InferSchemaOutput<T>,
   TKey,
@@ -507,7 +507,7 @@ export function queryCollectionOptions<
     TKey
   > & {
     schema?: never // prohibit schema
-  }
+  },
 ): CollectionConfig<
   T,
   TKey,
@@ -519,7 +519,7 @@ export function queryCollectionOptions<
 }
 
 export function queryCollectionOptions(
-  config: QueryCollectionConfig<Record<string, unknown>>
+  config: QueryCollectionConfig<Record<string, unknown>>,
 ): CollectionConfig<
   Record<string, unknown>,
   string | number,
@@ -663,7 +663,7 @@ export function queryCollectionOptions(
 
     const createQueryFromOpts = (
       opts: LoadSubsetOptions = {},
-      queryFunction: typeof queryFn = queryFn
+      queryFunction: typeof queryFn = queryFn,
     ): true | Promise<void> => {
       // Generate key using common function
       const key = generateQueryKeyFromOptions(opts)
@@ -675,7 +675,7 @@ export function queryCollectionOptions(
         // Increment reference count since another consumer is using this observer
         queryRefCounts.set(
           hashedQueryKey,
-          (queryRefCounts.get(hashedQueryKey) || 0) + 1
+          (queryRefCounts.get(hashedQueryKey) || 0) + 1,
         )
 
         // Get the current result and return based on its state
@@ -739,7 +739,7 @@ export function queryCollectionOptions(
       // Increment reference count for this query
       queryRefCounts.set(
         hashedQueryKey,
-        (queryRefCounts.get(hashedQueryKey) || 0) + 1
+        (queryRefCounts.get(hashedQueryKey) || 0) + 1,
       )
 
       // Create a promise that resolves when the query result is first available
@@ -790,7 +790,7 @@ export function queryCollectionOptions(
           }
 
           const currentSyncedItems: Map<string | number, any> = new Map(
-            collection._state.syncedData.entries()
+            collection._state.syncedData.entries(),
           )
           const newItemsMap = new Map<string | number, any>()
           newItemsArray.forEach((item) => {
@@ -833,7 +833,7 @@ export function queryCollectionOptions(
 
           console.error(
             `[QueryCollection] Error observing query ${String(queryKey)}:`,
-            result.error
+            result.error,
           )
 
           // Mark collection as ready even on error to avoid blocking apps
@@ -849,7 +849,7 @@ export function queryCollectionOptions(
 
     const subscribeToQuery = (
       observer: QueryObserver<Array<any>, any, Array<any>, Array<any>, any>,
-      hashedQueryKey: string
+      hashedQueryKey: string,
     ) => {
       if (!isSubscribed(hashedQueryKey)) {
         const cachedQueryKey = hashToQueryKey.get(hashedQueryKey)!
@@ -889,7 +889,7 @@ export function queryCollectionOptions(
         } else if (subscriberCount === 0) {
           unsubscribeFromQueries()
         }
-      }
+      },
     )
 
     // If syncMode is eager, create the initial query without any predicates
@@ -989,7 +989,7 @@ export function queryCollectionOptions(
       if (refcount > 0) {
         console.warn(
           `[cleanupQueryIfIdle] Invariant violation: refcount=${refcount} but no listeners. Cleaning up to prevent leak.`,
-          { hashedQueryKey }
+          { hashedQueryKey },
         )
       }
 
@@ -1040,7 +1040,7 @@ export function queryCollectionOptions(
         allQueryKeys.map(async (qKey) => {
           await queryClient.cancelQueries({ queryKey: qKey, exact: true })
           queryClient.removeQueries({ queryKey: qKey, exact: true })
-        })
+        }),
       )
     }
 
@@ -1130,6 +1130,73 @@ export function queryCollectionOptions(
     await Promise.all(refetchPromises)
   }
 
+  /**
+   * Updates the query cache with new items, handling both direct arrays
+   * and wrapped response formats (when `select` is used).
+   */
+  const updateCacheData = (items: Array<any>): void => {
+    // Get the base query key (handle both static and function-based keys)
+    const key =
+      typeof queryKey === `function`
+        ? queryKey({})
+        : (queryKey as unknown as QueryKey)
+
+    if (select) {
+      // When `select` is used, the cache contains a wrapped response (e.g., { data: [...], meta: {...} })
+      // We need to update the cache while preserving the wrapper structure
+      queryClient.setQueryData(key, (oldData: any) => {
+        if (!oldData || typeof oldData !== `object`) {
+          // No existing cache or not an object - don't corrupt the cache
+          return oldData
+        }
+
+        if (Array.isArray(oldData)) {
+          // Cache is already a raw array (shouldn't happen with select, but handle it)
+          return items
+        }
+
+        // Use the select function to identify which property contains the items array.
+        // This is more robust than guessing based on property order.
+        const selectedArray = select(oldData)
+
+        if (Array.isArray(selectedArray)) {
+          // Find the property that matches the selected array by reference equality
+          for (const propKey of Object.keys(oldData)) {
+            if (oldData[propKey] === selectedArray) {
+              // Found the exact property - create a shallow copy with updated items
+              return { ...oldData, [propKey]: items }
+            }
+          }
+        }
+
+        // Fallback: check common property names used for data arrays
+        if (Array.isArray(oldData.data)) {
+          return { ...oldData, data: items }
+        }
+        if (Array.isArray(oldData.items)) {
+          return { ...oldData, items: items }
+        }
+        if (Array.isArray(oldData.results)) {
+          return { ...oldData, results: items }
+        }
+
+        // Last resort: find first array property
+        for (const propKey of Object.keys(oldData)) {
+          if (Array.isArray(oldData[propKey])) {
+            return { ...oldData, [propKey]: items }
+          }
+        }
+
+        // Couldn't safely identify the array property - don't corrupt the cache
+        // Return oldData unchanged to avoid breaking select
+        return oldData
+      })
+    } else {
+      // No select - cache contains raw array, just set it directly
+      queryClient.setQueryData(key, items)
+    }
+  }
+
   // Create write context for manual write operations
   let writeContext: {
     collection: any
@@ -1139,21 +1206,29 @@ export function queryCollectionOptions(
     begin: () => void
     write: (message: Omit<ChangeMessage<any>, `key`>) => void
     commit: () => void
+    updateCacheData?: (items: Array<any>) => void
   } | null = null
 
   // Enhanced internalSync that captures write functions for manual use
   const enhancedInternalSync: SyncConfig<any>[`sync`] = (params) => {
     const { begin, write, commit, collection } = params
 
+    // Get the base query key for the context (handle both static and function-based keys)
+    const contextQueryKey =
+      typeof queryKey === `function`
+        ? (queryKey({}) as unknown as Array<unknown>)
+        : (queryKey as unknown as Array<unknown>)
+
     // Store references for manual write operations
     writeContext = {
       collection,
       queryClient,
-      queryKey: queryKey as unknown as Array<unknown>,
+      queryKey: contextQueryKey,
       getKey: getKey as (item: any) => string | number,
       begin,
       write,
       commit,
+      updateCacheData,
     }
 
     // Call the original internalSync logic
@@ -1162,7 +1237,7 @@ export function queryCollectionOptions(
 
   // Create write utils using the manual-sync module
   const writeUtils = createWriteUtils<any, string | number, any>(
-    () => writeContext
+    () => writeContext,
   )
 
   // Create wrapper handlers for direct persistence operations that handle refetching

package/src/serialization.ts

@@ -1,11 +1,13 @@
-import type { IR, LoadSubsetOptions } from "@tanstack/db"
+import type { IR, LoadSubsetOptions } from '@tanstack/db'
 
 /**
- * Serializes LoadSubsetOptions into a stable, hashable format for query keys
+ * Serializes LoadSubsetOptions into a stable, hashable format for query keys.
+ * Includes where, orderBy, limit, and offset for pagination support.
+ * Note: cursor expressions are not serialized as they are backend-specific.
  * @internal
  */
 export function serializeLoadSubsetOptions(
-  options: LoadSubsetOptions | undefined
+  options: LoadSubsetOptions | undefined,
 ): string | undefined {
   if (!options) {
     return undefined
@@ -43,6 +45,11 @@ export function serializeLoadSubsetOptions(
     result.limit = options.limit
   }
 
+  // Include offset for pagination support
+  if (options.offset !== undefined) {
+    result.offset = options.offset
+  }
+
   return Object.keys(result).length === 0 ? undefined : JSON.stringify(result)
 }
 
@@ -120,7 +127,7 @@ function serializeValue(value: unknown): unknown {
       Object.entries(value as Record<string, unknown>).map(([key, val]) => [
         key,
         serializeValue(val),
-      ])
+      ]),
     )
   }