@tanstack/db 0.5.30 → 0.5.32

package/dist/esm/query/query-once.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"query-once.js","sources":["../../../src/query/query-once.ts"],"sourcesContent":["import { createLiveQueryCollection } from './live-query-collection.js'\nimport type { InitialQueryBuilder, QueryBuilder } from './builder/index.js'\nimport type { Context, InferResultType } from './builder/types.js'\n\n/**\n * Configuration options for queryOnce\n */\nexport interface QueryOnceConfig<TContext extends Context> {\n  /**\n   * Query builder function that defines the query\n   */\n  query:\n    | ((q: InitialQueryBuilder) => QueryBuilder<TContext>)\n    | QueryBuilder<TContext>\n  // Future: timeout, signal, etc.\n}\n\n// Overload 1: Simple query function returning array (non-single result)\n/**\n * Executes a one-shot query and returns the results as an array.\n *\n * This function creates a live query collection, preloads it, extracts the results,\n * and automatically cleans up the collection. It's ideal for:\n * - AI/LLM context building\n * - Data export\n * - Background processing\n * - Testing\n *\n * @param queryFn - A function that receives the query builder and returns a query\n * @returns A promise that resolves to an array of query results\n *\n * @example\n * ```typescript\n * // Basic query\n * const users = await queryOnce((q) =>\n *   q.from({ user: usersCollection })\n * )\n *\n * // With filtering and projection\n * const activeUserNames = await queryOnce((q) =>\n *   q.from({ user: usersCollection })\n *    .where(({ user }) => eq(user.active, true))\n *    .select(({ user }) => ({ name: user.name }))\n * )\n * ```\n */\nexport function queryOnce<TContext extends Context>(\n  queryFn: (q: InitialQueryBuilder) => QueryBuilder<TContext>,\n): Promise<InferResultType<TContext>>\n\n// Overload 2: Config object form returning array (non-single result)\n/**\n * Executes a one-shot query using a configuration object.\n *\n * @param config - Configuration object with the query function\n * @returns A promise that resolves to an array of query results\n *\n * @example\n * ```typescript\n * const recentOrders = await queryOnce({\n *   query: (q) =>\n *     q.from({ order: ordersCollection })\n *      .orderBy(({ order }) => desc(order.createdAt))\n *      .limit(100),\n * })\n * ```\n */\nexport function queryOnce<TContext extends Context>(\n  config: QueryOnceConfig<TContext>,\n): Promise<InferResultType<TContext>>\n\n// Implementation\nexport async function queryOnce<TContext extends Context>(\n  configOrQuery:\n    | QueryOnceConfig<TContext>\n    | ((q: InitialQueryBuilder) => QueryBuilder<TContext>),\n): Promise<InferResultType<TContext>> {\n  // Normalize input\n  const config: QueryOnceConfig<TContext> =\n    typeof configOrQuery === `function`\n      ? { query: configOrQuery }\n      : configOrQuery\n\n  const query = (q: InitialQueryBuilder) => {\n    const queryConfig = config.query\n    return typeof queryConfig === `function` ? queryConfig(q) : queryConfig\n  }\n\n  // Create collection with minimal GC time; preload handles sync start\n  const collection = createLiveQueryCollection({\n    query,\n    gcTime: 1, // Cleanup in next tick when no subscribers (0 disables GC)\n  })\n\n  try {\n    // Wait for initial data load\n    await collection.preload()\n\n    // Check if this is a single-result query (findOne was called)\n    const isSingleResult =\n      (collection.config as { singleResult?: boolean }).singleResult === true\n\n    // Extract and return results\n    if (isSingleResult) {\n      const first = collection.values().next().value as\n        | InferResultType<TContext>\n        | undefined\n      return first as InferResultType<TContext>\n    }\n    return collection.toArray as InferResultType<TContext>\n  } finally {\n    // Always cleanup, even on error\n    await collection.cleanup()\n  }\n}\n"],"names":[],"mappings":";AAwEA,eAAsB,UACpB,eAGoC;AAEpC,QAAM,SACJ,OAAO,kBAAkB,aACrB,EAAE,OAAO,kBACT;AAEN,QAAM,QAAQ,CAAC,MAA2B;AACxC,UAAM,cAAc,OAAO;AAC3B,WAAO,OAAO,gBAAgB,aAAa,YAAY,CAAC,IAAI;AAAA,EAC9D;AAGA,QAAM,aAAa,0BAA0B;AAAA,IAC3C;AAAA,IACA,QAAQ;AAAA;AAAA,EAAA,CACT;AAED,MAAI;AAEF,UAAM,WAAW,QAAA;AAGjB,UAAM,iBACH,WAAW,OAAsC,iBAAiB;AAGrE,QAAI,gBAAgB;AAClB,YAAM,QAAQ,WAAW,OAAA,EAAS,OAAO;AAGzC,aAAO;AAAA,IACT;AACA,WAAO,WAAW;AAAA,EACpB,UAAA;AAEE,UAAM,WAAW,QAAA;AAAA,EACnB;AACF;"}

package/dist/esm/query/subset-dedupe.js

@@ -34,22 +34,23 @@ class DeduplicatedLoadSubset {
         prom.then(() => this.onDeduplicate?.(options)).catch();
         return prom;
       }
-      const clonedOptions = cloneOptions(options);
+      const trackingOptions = cloneOptions(options);
+      const loadOptions = cloneOptions(options);
       if (this.unlimitedWhere !== void 0 && options.limit === void 0) {
-        clonedOptions.where = minusWherePredicates(clonedOptions.where, this.unlimitedWhere) ?? clonedOptions.where;
+        loadOptions.where = minusWherePredicates(loadOptions.where, this.unlimitedWhere) ?? loadOptions.where;
       }
-      const resultPromise = this._loadSubset(clonedOptions);
+      const resultPromise = this._loadSubset(loadOptions);
       if (resultPromise === true) {
-        this.updateTracking(clonedOptions);
+        this.updateTracking(trackingOptions);
         return true;
       } else {
         const capturedGeneration = this.generation;
         const inflightEntry = {
-          options: clonedOptions,
-          // Store cloned options for subset matching
+          options: loadOptions,
+          // Store load options for subset matching of in-flight requests
           promise: resultPromise.then((result) => {
             if (capturedGeneration === this.generation) {
-              this.updateTracking(clonedOptions);
+              this.updateTracking(trackingOptions);
             }
             return result;
           }).finally(() => {

package/dist/esm/query/subset-dedupe.js.map

@@ -1 +1 @@
-{"version":3,"file":"subset-dedupe.js","sources":["../../../src/query/subset-dedupe.ts"],"sourcesContent":["import {\n  isPredicateSubset,\n  isWhereSubset,\n  minusWherePredicates,\n  unionWherePredicates,\n} from './predicate-utils.js'\nimport type { BasicExpression } from './ir.js'\nimport type { LoadSubsetOptions } from '../types.js'\n\n/**\n * Deduplicated wrapper for a loadSubset function.\n * Tracks what data has been loaded and avoids redundant calls by applying\n * subset logic to predicates.\n *\n * @param opts - The options for the DeduplicatedLoadSubset\n * @param opts.loadSubset - The underlying loadSubset function to wrap\n * @param opts.onDeduplicate - An optional callback function that is invoked when a loadSubset call is deduplicated.\n *                              If the call is deduplicated because the requested data is being loaded by an inflight request,\n *                              then this callback is invoked when the inflight request completes successfully and the data is fully loaded.\n *                              This callback is useful if you need to track rows per query, in which case you can't ignore deduplicated calls\n *                              because you need to know which rows were loaded for each query.\n * @example\n * const dedupe = new DeduplicatedLoadSubset({ loadSubset: myLoadSubset, onDeduplicate: (opts) => console.log(`Call was deduplicated:`, opts) })\n *\n * // First call - fetches data\n * await dedupe.loadSubset({ where: gt(ref('age'), val(10)) })\n *\n * // Second call - subset of first, returns true immediately\n * await dedupe.loadSubset({ where: gt(ref('age'), val(20)) })\n *\n * // Clear state to start fresh\n * dedupe.reset()\n */\nexport class DeduplicatedLoadSubset {\n  // The underlying loadSubset function to wrap\n  private readonly _loadSubset: (\n    options: LoadSubsetOptions,\n  ) => true | Promise<void>\n\n  // An optional callback function that is invoked when a loadSubset call is deduplicated.\n  private readonly onDeduplicate:\n    | ((options: LoadSubsetOptions) => void)\n    | undefined\n\n  // Combined where predicate for all unlimited calls (no limit)\n  private unlimitedWhere: BasicExpression<boolean> | undefined = undefined\n\n  // Flag to track if we've loaded all data (unlimited call with no where clause)\n  private hasLoadedAllData = false\n\n  // List of all limited calls (with limit, possibly with orderBy)\n  // We clone options before storing to prevent mutation of stored predicates\n  private limitedCalls: Array<LoadSubsetOptions> = []\n\n  // Track in-flight calls to prevent concurrent duplicate requests\n  // We store both the options and the promise so we can apply subset logic\n  private inflightCalls: Array<{\n    options: LoadSubsetOptions\n    promise: Promise<void>\n  }> = []\n\n  // Generation counter to invalidate in-flight requests after reset()\n  // When reset() is called, this increments, and any in-flight completion handlers\n  // check if their captured generation matches before updating tracking state\n  private generation = 0\n\n  constructor(opts: {\n    loadSubset: (options: LoadSubsetOptions) => true | Promise<void>\n    onDeduplicate?: (options: LoadSubsetOptions) => void\n  }) {\n    this._loadSubset = opts.loadSubset\n    this.onDeduplicate = opts.onDeduplicate\n  }\n\n  /**\n   * Load a subset of data, with automatic deduplication based on previously\n   * loaded predicates and in-flight requests.\n   *\n   * This method is auto-bound, so it can be safely passed as a callback without\n   * losing its `this` context (e.g., `loadSubset: dedupe.loadSubset` in a sync config).\n   *\n   * @param options - The predicate options (where, orderBy, limit)\n   * @returns true if data is already loaded, or a Promise that resolves when data is loaded\n   */\n  loadSubset = (options: LoadSubsetOptions): true | Promise<void> => {\n    // If we've loaded all data, everything is covered\n    if (this.hasLoadedAllData) {\n      this.onDeduplicate?.(options)\n      return true\n    }\n\n    // Check against unlimited combined predicate\n    // If we've loaded all data matching a where clause, we don't need to refetch subsets\n    if (this.unlimitedWhere !== undefined && options.where !== undefined) {\n      if (isWhereSubset(options.where, this.unlimitedWhere)) {\n        this.onDeduplicate?.(options)\n        return true // Data already loaded via unlimited call\n      }\n    }\n\n    // Check against limited calls\n    if (options.limit !== undefined) {\n      const alreadyLoaded = this.limitedCalls.some((loaded) =>\n        isPredicateSubset(options, loaded),\n      )\n\n      if (alreadyLoaded) {\n        this.onDeduplicate?.(options)\n        return true // Already loaded\n      }\n    }\n\n    // Check against in-flight calls using the same subset logic as resolved calls\n    // This prevents duplicate requests when concurrent calls have subset relationships\n    const matchingInflight = this.inflightCalls.find((inflight) =>\n      isPredicateSubset(options, inflight.options),\n    )\n\n    if (matchingInflight !== undefined) {\n      // An in-flight call will load data that covers this request\n      // Return the same promise so this caller waits for the data to load\n      // The in-flight promise already handles tracking updates when it completes\n      const prom = matchingInflight.promise\n      // Call `onDeduplicate` when the inflight request has loaded the data\n      prom.then(() => this.onDeduplicate?.(options)).catch() // ignore errors\n      return prom\n    }\n\n    // Not fully covered by existing data\n    // Compute the subset of data that is not covered by the existing data\n    // such that we only have to load that subset of missing data\n    const clonedOptions = cloneOptions(options)\n    if (this.unlimitedWhere !== undefined && options.limit === undefined) {\n      // Compute difference to get only the missing data\n      // We can only do this for unlimited queries\n      // and we can only remove data that was loaded from unlimited queries\n      // because with limited queries we have no way to express that we already loaded part of the matching data\n      clonedOptions.where =\n        minusWherePredicates(clonedOptions.where, this.unlimitedWhere) ??\n        clonedOptions.where\n    }\n\n    // Call underlying loadSubset to load the missing data\n    const resultPromise = this._loadSubset(clonedOptions)\n\n    // Handle both sync (true) and async (Promise<void>) return values\n    if (resultPromise === true) {\n      // Sync return - update tracking synchronously\n      // Clone options before storing to protect against caller mutation\n      this.updateTracking(clonedOptions)\n      return true\n    } else {\n      // Async return - track the promise and update tracking after it resolves\n\n      // Capture the current generation - this lets us detect if reset() was called\n      // while this request was in-flight, so we can skip updating tracking state\n      const capturedGeneration = this.generation\n\n      // We need to create a reference to the in-flight entry so we can remove it later\n      const inflightEntry = {\n        options: clonedOptions, // Store cloned options for subset matching\n        promise: resultPromise\n          .then((result) => {\n            // Only update tracking if this request is still from the current generation\n            // If reset() was called, the generation will have incremented and we should\n            // not repopulate the state that was just cleared\n            if (capturedGeneration === this.generation) {\n              // Use the cloned options that we captured before any caller mutations\n              // This ensures we track exactly what was loaded, not what the caller changed\n              this.updateTracking(clonedOptions)\n            }\n            return result\n          })\n          .finally(() => {\n            // Always remove from in-flight array on completion OR rejection\n            // This ensures failed requests can be retried instead of being cached forever\n            const index = this.inflightCalls.indexOf(inflightEntry)\n            if (index !== -1) {\n              this.inflightCalls.splice(index, 1)\n            }\n          }),\n      }\n\n      // Store the in-flight entry so concurrent subset calls can wait for it\n      this.inflightCalls.push(inflightEntry)\n      return inflightEntry.promise\n    }\n  }\n\n  /**\n   * Reset all tracking state.\n   * Clears the history of loaded predicates and in-flight calls.\n   * Use this when you want to start fresh, for example after clearing the underlying data store.\n   *\n   * Note: Any in-flight requests will still complete, but they will not update the tracking\n   * state after the reset. This prevents old requests from repopulating cleared state.\n   */\n  reset(): void {\n    this.unlimitedWhere = undefined\n    this.hasLoadedAllData = false\n    this.limitedCalls = []\n    this.inflightCalls = []\n    // Increment generation to invalidate any in-flight completion handlers\n    // This ensures requests that were started before reset() don't repopulate the state\n    this.generation++\n  }\n\n  private updateTracking(options: LoadSubsetOptions): void {\n    // Update tracking based on whether this was a limited or unlimited call\n    if (options.limit === undefined) {\n      // Unlimited call - update combined where predicate\n      // We ignore orderBy for unlimited calls as mentioned in requirements\n      if (options.where === undefined) {\n        // No where clause = all data loaded\n        this.hasLoadedAllData = true\n        this.unlimitedWhere = undefined\n        this.limitedCalls = []\n        this.inflightCalls = []\n      } else if (this.unlimitedWhere === undefined) {\n        this.unlimitedWhere = options.where\n      } else {\n        this.unlimitedWhere = unionWherePredicates([\n          this.unlimitedWhere,\n          options.where,\n        ])\n      }\n    } else {\n      // Limited call - add to list for future subset checks\n      // Options are already cloned by caller to prevent mutation issues\n      this.limitedCalls.push(options)\n    }\n  }\n}\n\n/**\n * Clones a LoadSubsetOptions object to prevent mutation of stored predicates.\n * This is crucial because callers often reuse the same options object and mutate\n * properties like limit or where between calls. Without cloning, our stored history\n * would reflect the mutated values rather than what was actually loaded.\n */\nexport function cloneOptions(options: LoadSubsetOptions): LoadSubsetOptions {\n  return { ...options }\n}\n"],"names":[],"mappings":"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"}
+{"version":3,"file":"subset-dedupe.js","sources":["../../../src/query/subset-dedupe.ts"],"sourcesContent":["import {\n  isPredicateSubset,\n  isWhereSubset,\n  minusWherePredicates,\n  unionWherePredicates,\n} from './predicate-utils.js'\nimport type { BasicExpression } from './ir.js'\nimport type { LoadSubsetOptions } from '../types.js'\n\n/**\n * Deduplicated wrapper for a loadSubset function.\n * Tracks what data has been loaded and avoids redundant calls by applying\n * subset logic to predicates.\n *\n * @param opts - The options for the DeduplicatedLoadSubset\n * @param opts.loadSubset - The underlying loadSubset function to wrap\n * @param opts.onDeduplicate - An optional callback function that is invoked when a loadSubset call is deduplicated.\n *                              If the call is deduplicated because the requested data is being loaded by an inflight request,\n *                              then this callback is invoked when the inflight request completes successfully and the data is fully loaded.\n *                              This callback is useful if you need to track rows per query, in which case you can't ignore deduplicated calls\n *                              because you need to know which rows were loaded for each query.\n * @example\n * const dedupe = new DeduplicatedLoadSubset({ loadSubset: myLoadSubset, onDeduplicate: (opts) => console.log(`Call was deduplicated:`, opts) })\n *\n * // First call - fetches data\n * await dedupe.loadSubset({ where: gt(ref('age'), val(10)) })\n *\n * // Second call - subset of first, returns true immediately\n * await dedupe.loadSubset({ where: gt(ref('age'), val(20)) })\n *\n * // Clear state to start fresh\n * dedupe.reset()\n */\nexport class DeduplicatedLoadSubset {\n  // The underlying loadSubset function to wrap\n  private readonly _loadSubset: (\n    options: LoadSubsetOptions,\n  ) => true | Promise<void>\n\n  // An optional callback function that is invoked when a loadSubset call is deduplicated.\n  private readonly onDeduplicate:\n    | ((options: LoadSubsetOptions) => void)\n    | undefined\n\n  // Combined where predicate for all unlimited calls (no limit)\n  private unlimitedWhere: BasicExpression<boolean> | undefined = undefined\n\n  // Flag to track if we've loaded all data (unlimited call with no where clause)\n  private hasLoadedAllData = false\n\n  // List of all limited calls (with limit, possibly with orderBy)\n  // We clone options before storing to prevent mutation of stored predicates\n  private limitedCalls: Array<LoadSubsetOptions> = []\n\n  // Track in-flight calls to prevent concurrent duplicate requests\n  // We store both the options and the promise so we can apply subset logic\n  private inflightCalls: Array<{\n    options: LoadSubsetOptions\n    promise: Promise<void>\n  }> = []\n\n  // Generation counter to invalidate in-flight requests after reset()\n  // When reset() is called, this increments, and any in-flight completion handlers\n  // check if their captured generation matches before updating tracking state\n  private generation = 0\n\n  constructor(opts: {\n    loadSubset: (options: LoadSubsetOptions) => true | Promise<void>\n    onDeduplicate?: (options: LoadSubsetOptions) => void\n  }) {\n    this._loadSubset = opts.loadSubset\n    this.onDeduplicate = opts.onDeduplicate\n  }\n\n  /**\n   * Load a subset of data, with automatic deduplication based on previously\n   * loaded predicates and in-flight requests.\n   *\n   * This method is auto-bound, so it can be safely passed as a callback without\n   * losing its `this` context (e.g., `loadSubset: dedupe.loadSubset` in a sync config).\n   *\n   * @param options - The predicate options (where, orderBy, limit)\n   * @returns true if data is already loaded, or a Promise that resolves when data is loaded\n   */\n  loadSubset = (options: LoadSubsetOptions): true | Promise<void> => {\n    // If we've loaded all data, everything is covered\n    if (this.hasLoadedAllData) {\n      this.onDeduplicate?.(options)\n      return true\n    }\n\n    // Check against unlimited combined predicate\n    // If we've loaded all data matching a where clause, we don't need to refetch subsets\n    if (this.unlimitedWhere !== undefined && options.where !== undefined) {\n      if (isWhereSubset(options.where, this.unlimitedWhere)) {\n        this.onDeduplicate?.(options)\n        return true // Data already loaded via unlimited call\n      }\n    }\n\n    // Check against limited calls\n    if (options.limit !== undefined) {\n      const alreadyLoaded = this.limitedCalls.some((loaded) =>\n        isPredicateSubset(options, loaded),\n      )\n\n      if (alreadyLoaded) {\n        this.onDeduplicate?.(options)\n        return true // Already loaded\n      }\n    }\n\n    // Check against in-flight calls using the same subset logic as resolved calls\n    // This prevents duplicate requests when concurrent calls have subset relationships\n    const matchingInflight = this.inflightCalls.find((inflight) =>\n      isPredicateSubset(options, inflight.options),\n    )\n\n    if (matchingInflight !== undefined) {\n      // An in-flight call will load data that covers this request\n      // Return the same promise so this caller waits for the data to load\n      // The in-flight promise already handles tracking updates when it completes\n      const prom = matchingInflight.promise\n      // Call `onDeduplicate` when the inflight request has loaded the data\n      prom.then(() => this.onDeduplicate?.(options)).catch() // ignore errors\n      return prom\n    }\n\n    // Not fully covered by existing data — load the missing subset.\n    // We need two clones: trackingOptions preserves the original predicate for\n    // accurate tracking (e.g., where=undefined means \"all data\"), while loadOptions\n    // may be narrowed with a difference expression for the actual backend request.\n    const trackingOptions = cloneOptions(options)\n    const loadOptions = cloneOptions(options)\n    if (this.unlimitedWhere !== undefined && options.limit === undefined) {\n      // Compute difference to get only the missing data\n      // We can only do this for unlimited queries\n      // and we can only remove data that was loaded from unlimited queries\n      // because with limited queries we have no way to express that we already loaded part of the matching data\n      loadOptions.where =\n        minusWherePredicates(loadOptions.where, this.unlimitedWhere) ??\n        loadOptions.where\n    }\n\n    // Call underlying loadSubset to load the missing data\n    const resultPromise = this._loadSubset(loadOptions)\n\n    // Handle both sync (true) and async (Promise<void>) return values\n    if (resultPromise === true) {\n      // Sync return - update tracking with the original predicate\n      this.updateTracking(trackingOptions)\n      return true\n    } else {\n      // Async return - track the promise and update tracking after it resolves\n\n      // Capture the current generation - this lets us detect if reset() was called\n      // while this request was in-flight, so we can skip updating tracking state\n      const capturedGeneration = this.generation\n\n      // We need to create a reference to the in-flight entry so we can remove it later\n      const inflightEntry = {\n        options: loadOptions, // Store load options for subset matching of in-flight requests\n        promise: resultPromise\n          .then((result) => {\n            // Only update tracking if this request is still from the current generation\n            // If reset() was called, the generation will have incremented and we should\n            // not repopulate the state that was just cleared\n            if (capturedGeneration === this.generation) {\n              this.updateTracking(trackingOptions)\n            }\n            return result\n          })\n          .finally(() => {\n            // Always remove from in-flight array on completion OR rejection\n            // This ensures failed requests can be retried instead of being cached forever\n            const index = this.inflightCalls.indexOf(inflightEntry)\n            if (index !== -1) {\n              this.inflightCalls.splice(index, 1)\n            }\n          }),\n      }\n\n      // Store the in-flight entry so concurrent subset calls can wait for it\n      this.inflightCalls.push(inflightEntry)\n      return inflightEntry.promise\n    }\n  }\n\n  /**\n   * Reset all tracking state.\n   * Clears the history of loaded predicates and in-flight calls.\n   * Use this when you want to start fresh, for example after clearing the underlying data store.\n   *\n   * Note: Any in-flight requests will still complete, but they will not update the tracking\n   * state after the reset. This prevents old requests from repopulating cleared state.\n   */\n  reset(): void {\n    this.unlimitedWhere = undefined\n    this.hasLoadedAllData = false\n    this.limitedCalls = []\n    this.inflightCalls = []\n    // Increment generation to invalidate any in-flight completion handlers\n    // This ensures requests that were started before reset() don't repopulate the state\n    this.generation++\n  }\n\n  private updateTracking(options: LoadSubsetOptions): void {\n    // Update tracking based on whether this was a limited or unlimited call\n    if (options.limit === undefined) {\n      // Unlimited call - update combined where predicate\n      // We ignore orderBy for unlimited calls as mentioned in requirements\n      if (options.where === undefined) {\n        // No where clause = all data loaded\n        this.hasLoadedAllData = true\n        this.unlimitedWhere = undefined\n        this.limitedCalls = []\n        this.inflightCalls = []\n      } else if (this.unlimitedWhere === undefined) {\n        this.unlimitedWhere = options.where\n      } else {\n        this.unlimitedWhere = unionWherePredicates([\n          this.unlimitedWhere,\n          options.where,\n        ])\n      }\n    } else {\n      // Limited call - add to list for future subset checks\n      // Options are already cloned by caller to prevent mutation issues\n      this.limitedCalls.push(options)\n    }\n  }\n}\n\n/**\n * Clones a LoadSubsetOptions object to prevent mutation of stored predicates.\n * This is crucial because callers often reuse the same options object and mutate\n * properties like limit or where between calls. Without cloning, our stored history\n * would reflect the mutated values rather than what was actually loaded.\n */\nexport function cloneOptions(options: LoadSubsetOptions): LoadSubsetOptions {\n  return { ...options }\n}\n"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tanstack/db",
-  "version": "0.5.30",
+  "version": "0.5.32",
   "description": "A reactive client store for building super fast apps on sync",
   "author": "Kyle Mathews",
   "license": "MIT",
@@ -34,7 +34,8 @@
   "sideEffects": false,
   "files": [
     "dist",
-    "src"
+    "src",
+    "skills"
   ],
   "dependencies": {
     "@standard-schema/spec": "^1.1.0",

package/skills/db-core/SKILL.md

@@ -0,0 +1,61 @@
+---
+name: db-core
+description: >
+  TanStack DB core concepts: createCollection with queryCollectionOptions,
+  electricCollectionOptions, powerSyncCollectionOptions, rxdbCollectionOptions,
+  trailbaseCollectionOptions, localOnlyCollectionOptions. Live queries via
+  query builder (from, where, join, select, groupBy, orderBy, limit). Optimistic
+  mutations with draft proxy (collection.insert, collection.update,
+  collection.delete). createOptimisticAction, createTransaction,
+  createPacedMutations. Entry point for all TanStack DB skills.
+type: core
+library: db
+library_version: '0.5.30'
+---
+
+# TanStack DB — Core Concepts
+
+TanStack DB is a reactive client-side data store. It loads data into typed
+collections from any backend (REST APIs, sync engines, local storage), provides
+sub-millisecond live queries via differential dataflow, and supports instant
+optimistic mutations with automatic rollback.
+
+Framework packages (`@tanstack/react-db`, `@tanstack/vue-db`, `@tanstack/svelte-db`,
+`@tanstack/solid-db`) re-export everything from `@tanstack/db` plus framework-specific
+hooks. In framework projects, import from the framework package directly.
+`@tanstack/angular-db` is the exception -- import operators from `@tanstack/db` separately.
+
+## Sub-Skills
+
+| Need to...                                       | Read                                                 |
+| ------------------------------------------------ | ---------------------------------------------------- |
+| Create a collection, pick an adapter, add schema | db-core/collection-setup/SKILL.md                    |
+| Query data with where, join, groupBy, select     | db-core/live-queries/SKILL.md                        |
+| Insert, update, delete with optimistic UI        | db-core/mutations-optimistic/SKILL.md                |
+| Build a custom sync adapter                      | db-core/custom-adapter/SKILL.md                      |
+| Preload collections in route loaders             | meta-framework/SKILL.md                              |
+| Add offline transaction queueing                 | offline/SKILL.md (in @tanstack/offline-transactions) |
+
+For framework-specific hooks:
+
+| Framework | Read                |
+| --------- | ------------------- |
+| React     | react-db/SKILL.md   |
+| Vue       | vue-db/SKILL.md     |
+| Svelte    | svelte-db/SKILL.md  |
+| Solid     | solid-db/SKILL.md   |
+| Angular   | angular-db/SKILL.md |
+
+## Quick Decision Tree
+
+- Setting up for the first time? → db-core/collection-setup
+- Building queries on collection data? → db-core/live-queries
+- Writing data / handling optimistic state? → db-core/mutations-optimistic
+- Using React hooks? → react-db
+- Preloading in route loaders (Start, Next, Remix)? → meta-framework
+- Building an adapter for a new backend? → db-core/custom-adapter
+- Need offline transaction persistence? → offline
+
+## Version
+
+Targets @tanstack/db v0.5.30.

package/skills/db-core/collection-setup/SKILL.md

@@ -0,0 +1,427 @@
+---
+name: db-core/collection-setup
+description: >
+  Creating typed collections with createCollection. Adapter selection:
+  queryCollectionOptions (REST/TanStack Query), electricCollectionOptions
+  (ElectricSQL real-time sync), powerSyncCollectionOptions (PowerSync SQLite),
+  rxdbCollectionOptions (RxDB), trailbaseCollectionOptions (TrailBase),
+  localOnlyCollectionOptions, localStorageCollectionOptions. CollectionConfig
+  options: getKey, schema, sync, gcTime, autoIndex, syncMode (eager/on-demand/
+  progressive). StandardSchema validation with Zod/Valibot/ArkType. Collection
+  lifecycle (idle/loading/ready/error). Adapter-specific sync patterns including
+  Electric txid tracking and Query direct writes.
+type: sub-skill
+library: db
+library_version: '0.5.30'
+sources:
+  - 'TanStack/db:docs/overview.md'
+  - 'TanStack/db:docs/guides/schemas.md'
+  - 'TanStack/db:docs/collections/query-collection.md'
+  - 'TanStack/db:docs/collections/electric-collection.md'
+  - 'TanStack/db:docs/collections/powersync-collection.md'
+  - 'TanStack/db:docs/collections/rxdb-collection.md'
+  - 'TanStack/db:docs/collections/trailbase-collection.md'
+  - 'TanStack/db:packages/db/src/collection/index.ts'
+---
+
+This skill builds on db-core. Read it first for the overall mental model.
+
+# Collection Setup & Schema
+
+## Setup
+
+```ts
+import { createCollection } from '@tanstack/react-db'
+import { queryCollectionOptions } from '@tanstack/query-db-collection'
+import { QueryClient } from '@tanstack/query-core'
+import { z } from 'zod'
+
+const queryClient = new QueryClient()
+
+const todoSchema = z.object({
+  id: z.number(),
+  text: z.string(),
+  completed: z.boolean().default(false),
+  created_at: z
+    .union([z.string(), z.date()])
+    .transform((val) => (typeof val === 'string' ? new Date(val) : val)),
+})
+
+const todoCollection = createCollection(
+  queryCollectionOptions({
+    queryKey: ['todos'],
+    queryFn: async () => {
+      const res = await fetch('/api/todos')
+      return res.json()
+    },
+    queryClient,
+    getKey: (item) => item.id,
+    schema: todoSchema,
+    onInsert: async ({ transaction }) => {
+      await api.todos.create(transaction.mutations[0].modified)
+      await todoCollection.utils.refetch()
+    },
+    onUpdate: async ({ transaction }) => {
+      const mut = transaction.mutations[0]
+      await api.todos.update(mut.key, mut.changes)
+      await todoCollection.utils.refetch()
+    },
+    onDelete: async ({ transaction }) => {
+      await api.todos.delete(transaction.mutations[0].key)
+      await todoCollection.utils.refetch()
+    },
+  }),
+)
+```
+
+## Choosing an Adapter
+
+| Backend                          | Adapter                         | Package                             |
+| -------------------------------- | ------------------------------- | ----------------------------------- |
+| REST API / TanStack Query        | `queryCollectionOptions`        | `@tanstack/query-db-collection`     |
+| ElectricSQL (real-time Postgres) | `electricCollectionOptions`     | `@tanstack/electric-db-collection`  |
+| PowerSync (SQLite offline)       | `powerSyncCollectionOptions`    | `@tanstack/powersync-db-collection` |
+| RxDB (reactive database)         | `rxdbCollectionOptions`         | `@tanstack/rxdb-db-collection`      |
+| TrailBase (event streaming)      | `trailbaseCollectionOptions`    | `@tanstack/trailbase-db-collection` |
+| No backend (UI state)            | `localOnlyCollectionOptions`    | `@tanstack/db`                      |
+| Browser localStorage             | `localStorageCollectionOptions` | `@tanstack/db`                      |
+
+If the user specifies a backend (e.g. Electric, PowerSync), use that adapter directly. Only use `localOnlyCollectionOptions` when there is no backend yet — the collection API is uniform, so swapping to a real adapter later only changes the options creator.
+
+## Sync Modes
+
+```ts
+queryCollectionOptions({
+  syncMode: 'eager', // default — loads all data upfront
+  // syncMode: "on-demand", // loads only what live queries request
+  // syncMode: "progressive", // (Electric only) query subset first, full sync in background
+})
+```
+
+| Mode          | Best for                                       | Data size |
+| ------------- | ---------------------------------------------- | --------- |
+| `eager`       | Mostly-static datasets                         | <10k rows |
+| `on-demand`   | Search, catalogs, large tables                 | >50k rows |
+| `progressive` | Collaborative apps needing instant first paint | Any       |
+
+## Core Patterns
+
+### Local-only collection for prototyping
+
+```ts
+import {
+  createCollection,
+  localOnlyCollectionOptions,
+} from '@tanstack/react-db'
+
+const todoCollection = createCollection(
+  localOnlyCollectionOptions({
+    getKey: (item) => item.id,
+    initialData: [{ id: 1, text: 'Learn TanStack DB', completed: false }],
+  }),
+)
+```
+
+### Schema with type transformations
+
+```ts
+const schema = z.object({
+  id: z.number(),
+  title: z.string(),
+  due_date: z
+    .union([z.string(), z.date()])
+    .transform((val) => (typeof val === 'string' ? new Date(val) : val)),
+  priority: z.number().default(0),
+})
+```
+
+Use `z.union([z.string(), z.date()])` for transformed fields — this ensures `TInput` is a superset of `TOutput` so that `update()` works correctly with the draft proxy.
+
+### ElectricSQL with txid tracking
+
+Always use a schema with Electric — without one, the collection types as `Record<string, unknown>`.
+
+```ts
+import { electricCollectionOptions } from '@tanstack/electric-db-collection'
+import { z } from 'zod'
+
+const todoSchema = z.object({
+  id: z.string(),
+  text: z.string(),
+  completed: z.boolean(),
+  created_at: z.coerce.date(),
+})
+
+const todoCollection = createCollection(
+  electricCollectionOptions({
+    schema: todoSchema,
+    shapeOptions: { url: '/api/electric/todos' },
+    getKey: (item) => item.id,
+    onInsert: async ({ transaction }) => {
+      const res = await api.todos.create(transaction.mutations[0].modified)
+      return { txid: res.txid }
+    },
+  }),
+)
+```
+
+The returned `txid` tells the collection to hold optimistic state until Electric streams back that transaction. See the [Electric adapter reference](references/electric-adapter.md) for the full dual-path pattern (schema + parser).
+
+## Common Mistakes
+
+### CRITICAL queryFn returning empty array deletes all data
+
+Wrong:
+
+```ts
+queryCollectionOptions({
+  queryFn: async () => {
+    const res = await fetch('/api/todos?status=active')
+    return res.json() // returns [] when no active todos — deletes everything
+  },
+})
+```
+
+Correct:
+
+```ts
+queryCollectionOptions({
+  queryFn: async () => {
+    const res = await fetch('/api/todos') // fetch complete state
+    return res.json()
+  },
+  // Use on-demand mode + live query where() for filtering
+  syncMode: 'on-demand',
+})
+```
+
+`queryFn` result is treated as complete server state. Returning `[]` means "server has no items", deleting all existing collection data.
+
+Source: docs/collections/query-collection.md
+
+### CRITICAL Not using the correct adapter for your backend
+
+Wrong:
+
+```ts
+const todoCollection = createCollection(
+  localOnlyCollectionOptions({
+    getKey: (item) => item.id,
+  }),
+)
+// Manually fetching and inserting...
+```
+
+Correct:
+
+```ts
+const todoCollection = createCollection(
+  queryCollectionOptions({
+    queryKey: ['todos'],
+    queryFn: async () => fetch('/api/todos').then((r) => r.json()),
+    queryClient,
+    getKey: (item) => item.id,
+  }),
+)
+```
+
+Each backend has a dedicated adapter that handles sync, mutation handlers, and utilities. Using `localOnlyCollectionOptions` or bare `createCollection` for a real backend bypasses all of this.
+
+Source: docs/overview.md
+
+### CRITICAL Electric txid queried outside mutation transaction
+
+Wrong:
+
+```ts
+// Backend handler
+app.post('/api/todos', async (req, res) => {
+  const txid = await generateTxId(sql) // WRONG: separate transaction
+  await sql`INSERT INTO todos ${sql(req.body)}`
+  res.json({ txid })
+})
+```
+
+Correct:
+
+```ts
+app.post('/api/todos', async (req, res) => {
+  let txid
+  await sql.begin(async (tx) => {
+    txid = await generateTxId(tx) // CORRECT: same transaction
+    await tx`INSERT INTO todos ${tx(req.body)}`
+  })
+  res.json({ txid })
+})
+```
+
+`pg_current_xact_id()` must be queried inside the same SQL transaction as the mutation. Otherwise the txid doesn't match and `awaitTxId` stalls forever.
+
+Source: docs/collections/electric-collection.md
+
+### CRITICAL queryFn returning partial data without merging
+
+Wrong:
+
+```ts
+queryCollectionOptions({
+  queryFn: async () => {
+    const newItems = await fetch('/api/todos?since=' + lastSync)
+    return newItems.json() // only new items — everything else deleted
+  },
+})
+```
+
+Correct:
+
+```ts
+queryCollectionOptions({
+  queryFn: async (ctx) => {
+    const existing = ctx.queryClient.getQueryData(['todos']) || []
+    const newItems = await fetch('/api/todos?since=' + lastSync).then((r) =>
+      r.json(),
+    )
+    return [...existing, ...newItems]
+  },
+})
+```
+
+`queryFn` result replaces all collection data. For incremental fetches, merge with existing data.
+
+Source: docs/collections/query-collection.md
+
+### HIGH Using async schema validation
+
+Wrong:
+
+```ts
+const schema = z.object({
+  email: z.string().refine(async (val) => {
+    const exists = await checkEmail(val)
+    return !exists
+  }),
+})
+```
+
+Correct:
+
+```ts
+const schema = z.object({
+  email: z.string().email(),
+})
+// Do async validation in the mutation handler instead
+```
+
+Schema validation must be synchronous. Async validation throws `SchemaMustBeSynchronousError` at mutation time.
+
+Source: packages/db/src/collection/mutations.ts:101
+
+### HIGH getKey returning undefined for some items
+
+Wrong:
+
+```ts
+createCollection(
+  queryCollectionOptions({
+    getKey: (item) => item.metadata.id, // undefined if metadata missing
+  }),
+)
+```
+
+Correct:
+
+```ts
+createCollection(
+  queryCollectionOptions({
+    getKey: (item) => item.id, // always present
+  }),
+)
+```
+
+`getKey` must return a defined value for every item. Throws `UndefinedKeyError` otherwise.
+
+Source: packages/db/src/collection/mutations.ts:148
+
+### HIGH TInput not a superset of TOutput with schema transforms
+
+Wrong:
+
+```ts
+const schema = z.object({
+  created_at: z.string().transform((val) => new Date(val)),
+})
+// update() fails — draft.created_at is Date but schema only accepts string
+```
+
+Correct:
+
+```ts
+const schema = z.object({
+  created_at: z
+    .union([z.string(), z.date()])
+    .transform((val) => (typeof val === 'string' ? new Date(val) : val)),
+})
+```
+
+When a schema transforms types, `TInput` must accept both the pre-transform and post-transform types for `update()` to work with the draft proxy.
+
+Source: docs/guides/schemas.md
+
+### HIGH React Native missing crypto.randomUUID polyfill
+
+TanStack DB uses `crypto.randomUUID()` internally. React Native doesn't provide this. Install `react-native-random-uuid` and import it at your app entry point.
+
+Source: docs/overview.md
+
+### MEDIUM Providing both explicit type parameter and schema
+
+Wrong:
+
+```ts
+createCollection<Todo>(queryCollectionOptions({ schema: todoSchema, ... }))
+```
+
+Correct:
+
+```ts
+createCollection(queryCollectionOptions({ schema: todoSchema, ... }))
+```
+
+When a schema is provided, the collection infers types from it. An explicit generic creates conflicting type constraints.
+
+Source: docs/overview.md
+
+### MEDIUM Direct writes overridden by next query sync
+
+Wrong:
+
+```ts
+todoCollection.utils.writeInsert(newItem)
+// Next queryFn execution replaces all data, losing the direct write
+```
+
+Correct:
+
+```ts
+todoCollection.utils.writeInsert(newItem)
+// Use staleTime to prevent immediate refetch
+// Or return { refetch: false } from mutation handlers
+```
+
+Direct writes update the collection immediately, but the next `queryFn` returns complete server state which overwrites them.
+
+Source: docs/collections/query-collection.md
+
+## References
+
+- [TanStack Query adapter](references/query-adapter.md)
+- [ElectricSQL adapter](references/electric-adapter.md)
+- [PowerSync adapter](references/powersync-adapter.md)
+- [RxDB adapter](references/rxdb-adapter.md)
+- [TrailBase adapter](references/trailbase-adapter.md)
+- [Local adapters (local-only, localStorage)](references/local-adapters.md)
+- [Schema validation patterns](references/schema-patterns.md)
+
+See also: db-core/mutations-optimistic/SKILL.md — mutation handlers configured here execute during mutations.
+
+See also: db-core/custom-adapter/SKILL.md — for building your own adapter.