@tanstack/db 0.5.33 → 0.6.1

package/dist/esm/utils.js

@@ -61,8 +61,8 @@ function deepEqualsInternal(a, b, visited) {
     return false;
   }
   if (isTemporal(a) && isTemporal(b)) {
-    const aTag = getStringTag(a);
-    const bTag = getStringTag(b);
+    const aTag = a[Symbol.toStringTag];
+    const bTag = b[Symbol.toStringTag];
     if (aTag !== bTag) return false;
     if (typeof a.equals === `function`) {
       return a.equals(b);
@@ -102,7 +102,7 @@ function deepEqualsInternal(a, b, visited) {
   }
   return false;
 }
-const temporalTypes = [
+const temporalTypes = /* @__PURE__ */ new Set([
   `Temporal.Duration`,
   `Temporal.Instant`,
   `Temporal.PlainDate`,
@@ -111,13 +111,11 @@ const temporalTypes = [
   `Temporal.PlainTime`,
   `Temporal.PlainYearMonth`,
   `Temporal.ZonedDateTime`
-];
-function getStringTag(a) {
-  return a[Symbol.toStringTag];
-}
+]);
 function isTemporal(a) {
-  const tag = getStringTag(a);
-  return typeof tag === `string` && temporalTypes.includes(tag);
+  if (a == null || typeof a !== `object`) return false;
+  const tag = a[Symbol.toStringTag];
+  return typeof tag === `string` && temporalTypes.has(tag);
 }
 const DEFAULT_COMPARE_OPTIONS = {
   direction: `asc`,

package/dist/esm/utils.js.map

@@ -1 +1 @@
-{"version":3,"file":"utils.js","sources":["../../src/utils.ts"],"sourcesContent":["/**\n * Generic utility functions\n */\n\nimport type { CompareOptions } from './query/builder/types'\n\ninterface TypedArray {\n  length: number\n  [index: number]: number\n}\n\n/**\n * Deep equality function that compares two values recursively\n * Handles primitives, objects, arrays, Date, RegExp, Map, Set, TypedArrays, and Temporal objects\n *\n * @param a - First value to compare\n * @param b - Second value to compare\n * @returns True if the values are deeply equal, false otherwise\n *\n * @example\n * ```typescript\n * deepEquals({ a: 1, b: 2 }, { b: 2, a: 1 }) // true (property order doesn't matter)\n * deepEquals([1, { x: 2 }], [1, { x: 2 }]) // true\n * deepEquals({ a: 1 }, { a: 2 }) // false\n * deepEquals(new Date('2023-01-01'), new Date('2023-01-01')) // true\n * deepEquals(new Map([['a', 1]]), new Map([['a', 1]])) // true\n * ```\n */\nexport function deepEquals(a: any, b: any): boolean {\n  return deepEqualsInternal(a, b, new Map())\n}\n\n/**\n * Internal implementation with cycle detection to prevent infinite recursion\n */\nfunction deepEqualsInternal(\n  a: any,\n  b: any,\n  visited: Map<object, object>,\n): boolean {\n  // Handle strict equality (primitives, same reference)\n  if (a === b) return true\n\n  // Handle null/undefined\n  if (a == null || b == null) return false\n\n  // Handle different types\n  if (typeof a !== typeof b) return false\n\n  // Handle Date objects\n  if (a instanceof Date) {\n    if (!(b instanceof Date)) return false\n    return a.getTime() === b.getTime()\n  }\n  // Symmetric check: if b is Date but a is not, they're not equal\n  if (b instanceof Date) return false\n\n  // Handle RegExp objects\n  if (a instanceof RegExp) {\n    if (!(b instanceof RegExp)) return false\n    return a.source === b.source && a.flags === b.flags\n  }\n  // Symmetric check: if b is RegExp but a is not, they're not equal\n  if (b instanceof RegExp) return false\n\n  // Handle Map objects - only if both are Maps\n  if (a instanceof Map) {\n    if (!(b instanceof Map)) return false\n    if (a.size !== b.size) return false\n\n    // Check for circular references\n    if (visited.has(a)) {\n      return visited.get(a) === b\n    }\n    visited.set(a, b)\n\n    const entries = Array.from(a.entries())\n    const result = entries.every(([key, val]) => {\n      return b.has(key) && deepEqualsInternal(val, b.get(key), visited)\n    })\n\n    visited.delete(a)\n    return result\n  }\n  // Symmetric check: if b is Map but a is not, they're not equal\n  if (b instanceof Map) return false\n\n  // Handle Set objects - only if both are Sets\n  if (a instanceof Set) {\n    if (!(b instanceof Set)) return false\n    if (a.size !== b.size) return false\n\n    // Check for circular references\n    if (visited.has(a)) {\n      return visited.get(a) === b\n    }\n    visited.set(a, b)\n\n    // Convert to arrays for comparison\n    const aValues = Array.from(a)\n    const bValues = Array.from(b)\n\n    // Simple comparison for primitive values\n    if (aValues.every((val) => typeof val !== `object`)) {\n      visited.delete(a)\n      return aValues.every((val) => b.has(val))\n    }\n\n    // For objects in sets, we need to do a more complex comparison\n    // This is a simplified approach and may not work for all cases\n    const result = aValues.length === bValues.length\n    visited.delete(a)\n    return result\n  }\n  // Symmetric check: if b is Set but a is not, they're not equal\n  if (b instanceof Set) return false\n\n  // Handle TypedArrays\n  if (\n    ArrayBuffer.isView(a) &&\n    ArrayBuffer.isView(b) &&\n    !(a instanceof DataView) &&\n    !(b instanceof DataView)\n  ) {\n    const typedA = a as unknown as TypedArray\n    const typedB = b as unknown as TypedArray\n    if (typedA.length !== typedB.length) return false\n\n    for (let i = 0; i < typedA.length; i++) {\n      if (typedA[i] !== typedB[i]) return false\n    }\n\n    return true\n  }\n  // Symmetric check: if b is TypedArray but a is not, they're not equal\n  if (\n    ArrayBuffer.isView(b) &&\n    !(b instanceof DataView) &&\n    !ArrayBuffer.isView(a)\n  ) {\n    return false\n  }\n\n  // Handle Temporal objects\n  // Check if both are Temporal objects of the same type\n  if (isTemporal(a) && isTemporal(b)) {\n    const aTag = getStringTag(a)\n    const bTag = getStringTag(b)\n\n    // If they're different Temporal types, they're not equal\n    if (aTag !== bTag) return false\n\n    // Use Temporal's built-in equals method if available\n    if (typeof a.equals === `function`) {\n      return a.equals(b)\n    }\n\n    // Fallback to toString comparison for other types\n    return a.toString() === b.toString()\n  }\n  // Symmetric check: if b is Temporal but a is not, they're not equal\n  if (isTemporal(b)) return false\n\n  // Handle arrays\n  if (Array.isArray(a)) {\n    if (!Array.isArray(b) || a.length !== b.length) return false\n\n    // Check for circular references\n    if (visited.has(a)) {\n      return visited.get(a) === b\n    }\n    visited.set(a, b)\n\n    const result = a.every((item, index) =>\n      deepEqualsInternal(item, b[index], visited),\n    )\n    visited.delete(a)\n    return result\n  }\n  // Symmetric check: if b is array but a is not, they're not equal\n  if (Array.isArray(b)) return false\n\n  // Handle objects\n  if (typeof a === `object`) {\n    // Check for circular references\n    if (visited.has(a)) {\n      return visited.get(a) === b\n    }\n    visited.set(a, b)\n\n    // Get all keys from both objects\n    const keysA = Object.keys(a)\n    const keysB = Object.keys(b)\n\n    // Check if they have the same number of keys\n    if (keysA.length !== keysB.length) {\n      visited.delete(a)\n      return false\n    }\n\n    // Check if all keys exist in both objects and their values are equal\n    const result = keysA.every(\n      (key) => key in b && deepEqualsInternal(a[key], b[key], visited),\n    )\n\n    visited.delete(a)\n    return result\n  }\n\n  // For primitives that aren't strictly equal\n  return false\n}\n\nconst temporalTypes = [\n  `Temporal.Duration`,\n  `Temporal.Instant`,\n  `Temporal.PlainDate`,\n  `Temporal.PlainDateTime`,\n  `Temporal.PlainMonthDay`,\n  `Temporal.PlainTime`,\n  `Temporal.PlainYearMonth`,\n  `Temporal.ZonedDateTime`,\n]\n\nfunction getStringTag(a: any): any {\n  return a[Symbol.toStringTag]\n}\n\n/** Checks if the value is a Temporal object by checking for the Temporal brand */\nexport function isTemporal(a: any): boolean {\n  const tag = getStringTag(a)\n  return typeof tag === `string` && temporalTypes.includes(tag)\n}\n\nexport const DEFAULT_COMPARE_OPTIONS: CompareOptions = {\n  direction: `asc`,\n  nulls: `first`,\n  stringSort: `locale`,\n}\n"],"names":[],"mappings":"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"}
+{"version":3,"file":"utils.js","sources":["../../src/utils.ts"],"sourcesContent":["/**\n * Generic utility functions\n */\n\nimport type { CompareOptions } from './query/builder/types'\n\ninterface TypedArray {\n  length: number\n  [index: number]: number\n}\n\n/**\n * Deep equality function that compares two values recursively\n * Handles primitives, objects, arrays, Date, RegExp, Map, Set, TypedArrays, and Temporal objects\n *\n * @param a - First value to compare\n * @param b - Second value to compare\n * @returns True if the values are deeply equal, false otherwise\n *\n * @example\n * ```typescript\n * deepEquals({ a: 1, b: 2 }, { b: 2, a: 1 }) // true (property order doesn't matter)\n * deepEquals([1, { x: 2 }], [1, { x: 2 }]) // true\n * deepEquals({ a: 1 }, { a: 2 }) // false\n * deepEquals(new Date('2023-01-01'), new Date('2023-01-01')) // true\n * deepEquals(new Map([['a', 1]]), new Map([['a', 1]])) // true\n * ```\n */\nexport function deepEquals(a: any, b: any): boolean {\n  return deepEqualsInternal(a, b, new Map())\n}\n\n/**\n * Internal implementation with cycle detection to prevent infinite recursion\n */\nfunction deepEqualsInternal(\n  a: any,\n  b: any,\n  visited: Map<object, object>,\n): boolean {\n  // Handle strict equality (primitives, same reference)\n  if (a === b) return true\n\n  // Handle null/undefined\n  if (a == null || b == null) return false\n\n  // Handle different types\n  if (typeof a !== typeof b) return false\n\n  // Handle Date objects\n  if (a instanceof Date) {\n    if (!(b instanceof Date)) return false\n    return a.getTime() === b.getTime()\n  }\n  // Symmetric check: if b is Date but a is not, they're not equal\n  if (b instanceof Date) return false\n\n  // Handle RegExp objects\n  if (a instanceof RegExp) {\n    if (!(b instanceof RegExp)) return false\n    return a.source === b.source && a.flags === b.flags\n  }\n  // Symmetric check: if b is RegExp but a is not, they're not equal\n  if (b instanceof RegExp) return false\n\n  // Handle Map objects - only if both are Maps\n  if (a instanceof Map) {\n    if (!(b instanceof Map)) return false\n    if (a.size !== b.size) return false\n\n    // Check for circular references\n    if (visited.has(a)) {\n      return visited.get(a) === b\n    }\n    visited.set(a, b)\n\n    const entries = Array.from(a.entries())\n    const result = entries.every(([key, val]) => {\n      return b.has(key) && deepEqualsInternal(val, b.get(key), visited)\n    })\n\n    visited.delete(a)\n    return result\n  }\n  // Symmetric check: if b is Map but a is not, they're not equal\n  if (b instanceof Map) return false\n\n  // Handle Set objects - only if both are Sets\n  if (a instanceof Set) {\n    if (!(b instanceof Set)) return false\n    if (a.size !== b.size) return false\n\n    // Check for circular references\n    if (visited.has(a)) {\n      return visited.get(a) === b\n    }\n    visited.set(a, b)\n\n    // Convert to arrays for comparison\n    const aValues = Array.from(a)\n    const bValues = Array.from(b)\n\n    // Simple comparison for primitive values\n    if (aValues.every((val) => typeof val !== `object`)) {\n      visited.delete(a)\n      return aValues.every((val) => b.has(val))\n    }\n\n    // For objects in sets, we need to do a more complex comparison\n    // This is a simplified approach and may not work for all cases\n    const result = aValues.length === bValues.length\n    visited.delete(a)\n    return result\n  }\n  // Symmetric check: if b is Set but a is not, they're not equal\n  if (b instanceof Set) return false\n\n  // Handle TypedArrays\n  if (\n    ArrayBuffer.isView(a) &&\n    ArrayBuffer.isView(b) &&\n    !(a instanceof DataView) &&\n    !(b instanceof DataView)\n  ) {\n    const typedA = a as unknown as TypedArray\n    const typedB = b as unknown as TypedArray\n    if (typedA.length !== typedB.length) return false\n\n    for (let i = 0; i < typedA.length; i++) {\n      if (typedA[i] !== typedB[i]) return false\n    }\n\n    return true\n  }\n  // Symmetric check: if b is TypedArray but a is not, they're not equal\n  if (\n    ArrayBuffer.isView(b) &&\n    !(b instanceof DataView) &&\n    !ArrayBuffer.isView(a)\n  ) {\n    return false\n  }\n\n  // Handle Temporal objects\n  // Check if both are Temporal objects of the same type\n  if (isTemporal(a) && isTemporal(b)) {\n    const aTag = a[Symbol.toStringTag]\n    const bTag = b[Symbol.toStringTag]\n\n    // If they're different Temporal types, they're not equal\n    if (aTag !== bTag) return false\n\n    // Use Temporal's built-in equals method if available\n    if (typeof a.equals === `function`) {\n      return a.equals(b)\n    }\n\n    // Fallback to toString comparison for other types\n    return a.toString() === b.toString()\n  }\n  // Symmetric check: if b is Temporal but a is not, they're not equal\n  if (isTemporal(b)) return false\n\n  // Handle arrays\n  if (Array.isArray(a)) {\n    if (!Array.isArray(b) || a.length !== b.length) return false\n\n    // Check for circular references\n    if (visited.has(a)) {\n      return visited.get(a) === b\n    }\n    visited.set(a, b)\n\n    const result = a.every((item, index) =>\n      deepEqualsInternal(item, b[index], visited),\n    )\n    visited.delete(a)\n    return result\n  }\n  // Symmetric check: if b is array but a is not, they're not equal\n  if (Array.isArray(b)) return false\n\n  // Handle objects\n  if (typeof a === `object`) {\n    // Check for circular references\n    if (visited.has(a)) {\n      return visited.get(a) === b\n    }\n    visited.set(a, b)\n\n    // Get all keys from both objects\n    const keysA = Object.keys(a)\n    const keysB = Object.keys(b)\n\n    // Check if they have the same number of keys\n    if (keysA.length !== keysB.length) {\n      visited.delete(a)\n      return false\n    }\n\n    // Check if all keys exist in both objects and their values are equal\n    const result = keysA.every(\n      (key) => key in b && deepEqualsInternal(a[key], b[key], visited),\n    )\n\n    visited.delete(a)\n    return result\n  }\n\n  // For primitives that aren't strictly equal\n  return false\n}\n\nconst temporalTypes = new Set([\n  `Temporal.Duration`,\n  `Temporal.Instant`,\n  `Temporal.PlainDate`,\n  `Temporal.PlainDateTime`,\n  `Temporal.PlainMonthDay`,\n  `Temporal.PlainTime`,\n  `Temporal.PlainYearMonth`,\n  `Temporal.ZonedDateTime`,\n])\n\nexport interface TemporalLike {\n  [Symbol.toStringTag]: string\n  toString: () => string\n  equals?: (other: unknown) => boolean\n}\n\n/** Checks if the value is a Temporal object by checking for the Temporal brand */\nexport function isTemporal(a: unknown): a is TemporalLike {\n  if (a == null || typeof a !== `object`) return false\n  const tag = (a as Record<symbol, unknown>)[Symbol.toStringTag]\n  return typeof tag === `string` && temporalTypes.has(tag)\n}\n\nexport const DEFAULT_COMPARE_OPTIONS: CompareOptions = {\n  direction: `asc`,\n  nulls: `first`,\n  stringSort: `locale`,\n}\n"],"names":[],"mappings":"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"}

package/dist/esm/virtual-props.d.ts

@@ -0,0 +1,196 @@
+/**
+ * Virtual Properties for TanStack DB
+ *
+ * Virtual properties are computed, read-only properties that provide metadata about rows
+ * (sync status, source, selection state) without being part of the persisted data model.
+ *
+ * Virtual properties are prefixed with `$` to distinguish them from user data fields.
+ * User schemas should not include `$`-prefixed fields as they are reserved.
+ */
+/**
+ * Origin of the last confirmed change to a row, from the current client's perspective.
+ *
+ * - `'local'`: The change originated from this client (e.g., a mutation made here)
+ * - `'remote'`: The change was received via sync from another client/server
+ *
+ * Note: This reflects the client's perspective, not the original creator.
+ * User A creates order → $origin = 'local' on User A's client
+ * Order syncs to server
+ * User B receives order → $origin = 'remote' on User B's client
+ */
+export type VirtualOrigin = 'local' | 'remote';
+/**
+ * Virtual properties available on every row in TanStack DB collections.
+ *
+ * These properties are:
+ * - Computed (not stored in the data model)
+ * - Read-only (cannot be mutated directly)
+ * - Available in queries (WHERE, ORDER BY, SELECT)
+ * - Included when spreading rows (`...user`)
+ *
+ * @template TKey - The type of the row's key (string or number)
+ *
+ * @example
+ * ```typescript
+ * // Accessing virtual properties on a row
+ * const user = collection.get('user-1')
+ * if (user.$synced) {
+ *   console.log('Confirmed by backend')
+ * }
+ * if (user.$origin === 'local') {
+ *   console.log('Created/modified locally')
+ * }
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Using virtual properties in queries
+ * const confirmedOrders = createLiveQueryCollection({
+ *   query: (q) => q
+ *     .from({ order: orders })
+ *     .where(({ order }) => eq(order.$synced, true))
+ * })
+ * ```
+ */
+export interface VirtualRowProps<TKey extends string | number = string | number> {
+    /**
+     * Whether this row reflects confirmed state from the backend.
+     *
+     * - `true`: Row is confirmed by the backend (no pending optimistic mutations)
+     * - `false`: Row has pending optimistic mutations that haven't been confirmed
+     *
+     * For local-only collections (no sync), this is always `true`.
+     * For live query collections, this is passed through from the source collection.
+     */
+    readonly $synced: boolean;
+    /**
+     * Origin of the last confirmed change to this row, from the current client's perspective.
+     *
+     * - `'local'`: The change originated from this client
+     * - `'remote'`: The change was received via sync
+     *
+     * For local-only collections, this is always `'local'`.
+     * For live query collections, this is passed through from the source collection.
+     */
+    readonly $origin: VirtualOrigin;
+    /**
+     * The row's key (primary identifier).
+     *
+     * This is the same value returned by `collection.config.getKey(row)`.
+     * Useful when you need the key in projections or computations.
+     */
+    readonly $key: TKey;
+    /**
+     * The ID of the source collection this row originated from.
+     *
+     * In joins, this can help identify which collection each row came from.
+     * For live query collections, this is the ID of the upstream collection.
+     */
+    readonly $collectionId: string;
+}
+/**
+ * Adds virtual properties to a row type.
+ *
+ * @template T - The base row type
+ * @template TKey - The type of the row's key
+ *
+ * @example
+ * ```typescript
+ * type User = { id: string; name: string }
+ * type UserWithVirtual = WithVirtualProps<User, string>
+ * // { id: string; name: string; $synced: boolean; $origin: 'local' | 'remote'; $key: string; $collectionId: string }
+ * ```
+ */
+export type WithVirtualProps<T extends object, TKey extends string | number = string | number> = T & VirtualRowProps<TKey>;
+/**
+ * Extracts the base type from a type that may have virtual properties.
+ * Useful when you need to work with the raw data without virtual properties.
+ *
+ * @template T - The type that may include virtual properties
+ *
+ * @example
+ * ```typescript
+ * type UserWithVirtual = { id: string; name: string; $synced: boolean; $origin: 'local' | 'remote' }
+ * type User = WithoutVirtualProps<UserWithVirtual>
+ * // { id: string; name: string }
+ * ```
+ */
+export type WithoutVirtualProps<T> = Omit<T, keyof VirtualRowProps>;
+/**
+ * Checks if a value has virtual properties attached.
+ *
+ * @param value - The value to check
+ * @returns true if the value has virtual properties
+ *
+ * @example
+ * ```typescript
+ * if (hasVirtualProps(row)) {
+ *   console.log('Synced:', row.$synced)
+ * }
+ * ```
+ */
+export declare function hasVirtualProps(value: unknown): value is VirtualRowProps<string | number>;
+/**
+ * Creates virtual properties for a row in a source collection.
+ *
+ * This is the internal function used by collections to add virtual properties
+ * to rows when emitting change messages.
+ *
+ * @param key - The row's key
+ * @param collectionId - The collection's ID
+ * @param isSynced - Whether the row is synced (not optimistic)
+ * @param origin - Whether the change was local or remote
+ * @returns Virtual properties object to merge with the row
+ *
+ * @internal
+ */
+export declare function createVirtualProps<TKey extends string | number>(key: TKey, collectionId: string, isSynced: boolean, origin: VirtualOrigin): VirtualRowProps<TKey>;
+/**
+ * Enriches a row with virtual properties using the "add-if-missing" pattern.
+ *
+ * If the row already has virtual properties (from an upstream collection),
+ * they are preserved. If not, new virtual properties are computed and added.
+ *
+ * This is the key function that enables pass-through semantics for nested
+ * live query collections.
+ *
+ * @param row - The row to enrich
+ * @param key - The row's key
+ * @param collectionId - The collection's ID
+ * @param computeSynced - Function to compute $synced if missing
+ * @param computeOrigin - Function to compute $origin if missing
+ * @returns The row with virtual properties (possibly the same object if already present)
+ *
+ * @internal
+ */
+export declare function enrichRowWithVirtualProps<T extends object, TKey extends string | number>(row: T, key: TKey, collectionId: string, computeSynced: () => boolean, computeOrigin: () => VirtualOrigin): WithVirtualProps<T, TKey>;
+/**
+ * Computes aggregate virtual properties for a group of rows.
+ *
+ * For aggregates:
+ * - `$synced`: true if ALL rows in the group are synced; false if ANY row is optimistic
+ * - `$origin`: 'local' if ANY row in the group is local; otherwise 'remote'
+ *
+ * @param rows - The rows in the group
+ * @param groupKey - The group key
+ * @param collectionId - The collection ID
+ * @returns Virtual properties for the aggregate row
+ *
+ * @internal
+ */
+export declare function computeAggregateVirtualProps<TKey extends string | number>(rows: Array<Partial<VirtualRowProps<string | number>>>, groupKey: TKey, collectionId: string): VirtualRowProps<TKey>;
+/**
+ * List of virtual property names for iteration and checking.
+ * @internal
+ */
+export declare const VIRTUAL_PROP_NAMES: readonly ["$synced", "$origin", "$key", "$collectionId"];
+/**
+ * Checks if a property name is a virtual property.
+ * @internal
+ */
+export declare function isVirtualPropName(name: string): boolean;
+/**
+ * Checks whether a property path references a virtual property.
+ * @internal
+ */
+export declare function hasVirtualPropPath(path: Array<string>): boolean;

package/dist/esm/virtual-props.js

@@ -0,0 +1,33 @@
+function hasVirtualProps(value) {
+  return typeof value === "object" && value !== null && VIRTUAL_PROP_NAMES.every((name) => name in value);
+}
+function enrichRowWithVirtualProps(row, key, collectionId, computeSynced, computeOrigin) {
+  const existingRow = row;
+  return {
+    ...row,
+    $synced: existingRow.$synced ?? computeSynced(),
+    $origin: existingRow.$origin ?? computeOrigin(),
+    $key: existingRow.$key ?? key,
+    $collectionId: existingRow.$collectionId ?? collectionId
+  };
+}
+const VIRTUAL_PROP_NAMES = [
+  "$synced",
+  "$origin",
+  "$key",
+  "$collectionId"
+];
+function isVirtualPropName(name) {
+  return VIRTUAL_PROP_NAMES.includes(name);
+}
+function hasVirtualPropPath(path) {
+  return path.some((segment) => isVirtualPropName(segment));
+}
+export {
+  VIRTUAL_PROP_NAMES,
+  enrichRowWithVirtualProps,
+  hasVirtualPropPath,
+  hasVirtualProps,
+  isVirtualPropName
+};
+//# sourceMappingURL=virtual-props.js.map

package/dist/esm/virtual-props.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"virtual-props.js","sources":["../../src/virtual-props.ts"],"sourcesContent":["/**\n * Virtual Properties for TanStack DB\n *\n * Virtual properties are computed, read-only properties that provide metadata about rows\n * (sync status, source, selection state) without being part of the persisted data model.\n *\n * Virtual properties are prefixed with `$` to distinguish them from user data fields.\n * User schemas should not include `$`-prefixed fields as they are reserved.\n */\n\n/**\n * Origin of the last confirmed change to a row, from the current client's perspective.\n *\n * - `'local'`: The change originated from this client (e.g., a mutation made here)\n * - `'remote'`: The change was received via sync from another client/server\n *\n * Note: This reflects the client's perspective, not the original creator.\n * User A creates order → $origin = 'local' on User A's client\n * Order syncs to server\n * User B receives order → $origin = 'remote' on User B's client\n */\nexport type VirtualOrigin = 'local' | 'remote'\n\n/**\n * Virtual properties available on every row in TanStack DB collections.\n *\n * These properties are:\n * - Computed (not stored in the data model)\n * - Read-only (cannot be mutated directly)\n * - Available in queries (WHERE, ORDER BY, SELECT)\n * - Included when spreading rows (`...user`)\n *\n * @template TKey - The type of the row's key (string or number)\n *\n * @example\n * ```typescript\n * // Accessing virtual properties on a row\n * const user = collection.get('user-1')\n * if (user.$synced) {\n *   console.log('Confirmed by backend')\n * }\n * if (user.$origin === 'local') {\n *   console.log('Created/modified locally')\n * }\n * ```\n *\n * @example\n * ```typescript\n * // Using virtual properties in queries\n * const confirmedOrders = createLiveQueryCollection({\n *   query: (q) => q\n *     .from({ order: orders })\n *     .where(({ order }) => eq(order.$synced, true))\n * })\n * ```\n */\nexport interface VirtualRowProps<\n  TKey extends string | number = string | number,\n> {\n  /**\n   * Whether this row reflects confirmed state from the backend.\n   *\n   * - `true`: Row is confirmed by the backend (no pending optimistic mutations)\n   * - `false`: Row has pending optimistic mutations that haven't been confirmed\n   *\n   * For local-only collections (no sync), this is always `true`.\n   * For live query collections, this is passed through from the source collection.\n   */\n  readonly $synced: boolean\n\n  /**\n   * Origin of the last confirmed change to this row, from the current client's perspective.\n   *\n   * - `'local'`: The change originated from this client\n   * - `'remote'`: The change was received via sync\n   *\n   * For local-only collections, this is always `'local'`.\n   * For live query collections, this is passed through from the source collection.\n   */\n  readonly $origin: VirtualOrigin\n\n  /**\n   * The row's key (primary identifier).\n   *\n   * This is the same value returned by `collection.config.getKey(row)`.\n   * Useful when you need the key in projections or computations.\n   */\n  readonly $key: TKey\n\n  /**\n   * The ID of the source collection this row originated from.\n   *\n   * In joins, this can help identify which collection each row came from.\n   * For live query collections, this is the ID of the upstream collection.\n   */\n  readonly $collectionId: string\n}\n\n/**\n * Adds virtual properties to a row type.\n *\n * @template T - The base row type\n * @template TKey - The type of the row's key\n *\n * @example\n * ```typescript\n * type User = { id: string; name: string }\n * type UserWithVirtual = WithVirtualProps<User, string>\n * // { id: string; name: string; $synced: boolean; $origin: 'local' | 'remote'; $key: string; $collectionId: string }\n * ```\n */\nexport type WithVirtualProps<\n  T extends object,\n  TKey extends string | number = string | number,\n> = T & VirtualRowProps<TKey>\n\n/**\n * Extracts the base type from a type that may have virtual properties.\n * Useful when you need to work with the raw data without virtual properties.\n *\n * @template T - The type that may include virtual properties\n *\n * @example\n * ```typescript\n * type UserWithVirtual = { id: string; name: string; $synced: boolean; $origin: 'local' | 'remote' }\n * type User = WithoutVirtualProps<UserWithVirtual>\n * // { id: string; name: string }\n * ```\n */\nexport type WithoutVirtualProps<T> = Omit<T, keyof VirtualRowProps>\n\n/**\n * Checks if a value has virtual properties attached.\n *\n * @param value - The value to check\n * @returns true if the value has virtual properties\n *\n * @example\n * ```typescript\n * if (hasVirtualProps(row)) {\n *   console.log('Synced:', row.$synced)\n * }\n * ```\n */\nexport function hasVirtualProps(\n  value: unknown,\n): value is VirtualRowProps<string | number> {\n  return (\n    typeof value === 'object' &&\n    value !== null &&\n    VIRTUAL_PROP_NAMES.every((name) => name in value)\n  )\n}\n\n/**\n * Creates virtual properties for a row in a source collection.\n *\n * This is the internal function used by collections to add virtual properties\n * to rows when emitting change messages.\n *\n * @param key - The row's key\n * @param collectionId - The collection's ID\n * @param isSynced - Whether the row is synced (not optimistic)\n * @param origin - Whether the change was local or remote\n * @returns Virtual properties object to merge with the row\n *\n * @internal\n */\nexport function createVirtualProps<TKey extends string | number>(\n  key: TKey,\n  collectionId: string,\n  isSynced: boolean,\n  origin: VirtualOrigin,\n): VirtualRowProps<TKey> {\n  return {\n    $synced: isSynced,\n    $origin: origin,\n    $key: key,\n    $collectionId: collectionId,\n  }\n}\n\n/**\n * Enriches a row with virtual properties using the \"add-if-missing\" pattern.\n *\n * If the row already has virtual properties (from an upstream collection),\n * they are preserved. If not, new virtual properties are computed and added.\n *\n * This is the key function that enables pass-through semantics for nested\n * live query collections.\n *\n * @param row - The row to enrich\n * @param key - The row's key\n * @param collectionId - The collection's ID\n * @param computeSynced - Function to compute $synced if missing\n * @param computeOrigin - Function to compute $origin if missing\n * @returns The row with virtual properties (possibly the same object if already present)\n *\n * @internal\n */\nexport function enrichRowWithVirtualProps<\n  T extends object,\n  TKey extends string | number,\n>(\n  row: T,\n  key: TKey,\n  collectionId: string,\n  computeSynced: () => boolean,\n  computeOrigin: () => VirtualOrigin,\n): WithVirtualProps<T, TKey> {\n  // Use nullish coalescing to preserve existing virtual properties (pass-through)\n  // This is the \"add-if-missing\" pattern described in the RFC\n  const existingRow = row as Partial<VirtualRowProps<TKey>>\n\n  return {\n    ...row,\n    $synced: existingRow.$synced ?? computeSynced(),\n    $origin: existingRow.$origin ?? computeOrigin(),\n    $key: existingRow.$key ?? key,\n    $collectionId: existingRow.$collectionId ?? collectionId,\n  } as WithVirtualProps<T, TKey>\n}\n\n/**\n * Computes aggregate virtual properties for a group of rows.\n *\n * For aggregates:\n * - `$synced`: true if ALL rows in the group are synced; false if ANY row is optimistic\n * - `$origin`: 'local' if ANY row in the group is local; otherwise 'remote'\n *\n * @param rows - The rows in the group\n * @param groupKey - The group key\n * @param collectionId - The collection ID\n * @returns Virtual properties for the aggregate row\n *\n * @internal\n */\nexport function computeAggregateVirtualProps<TKey extends string | number>(\n  rows: Array<Partial<VirtualRowProps<string | number>>>,\n  groupKey: TKey,\n  collectionId: string,\n): VirtualRowProps<TKey> {\n  // $synced = true only if ALL rows are synced (false if ANY is optimistic)\n  const allSynced = rows.every((row) => row.$synced ?? true)\n\n  // $origin = 'local' if ANY row is local (consistent with \"local influence\" semantics)\n  const hasLocal = rows.some((row) => row.$origin === 'local')\n\n  return {\n    $synced: allSynced,\n    $origin: hasLocal ? 'local' : 'remote',\n    $key: groupKey,\n    $collectionId: collectionId,\n  }\n}\n\n/**\n * List of virtual property names for iteration and checking.\n * @internal\n */\nexport const VIRTUAL_PROP_NAMES = [\n  '$synced',\n  '$origin',\n  '$key',\n  '$collectionId',\n] as const\n\n/**\n * Checks if a property name is a virtual property.\n * @internal\n */\nexport function isVirtualPropName(name: string): boolean {\n  return VIRTUAL_PROP_NAMES.includes(name as any)\n}\n\n/**\n * Checks whether a property path references a virtual property.\n * @internal\n */\nexport function hasVirtualPropPath(path: Array<string>): boolean {\n  return path.some((segment) => isVirtualPropName(segment))\n}\n"],"names":[],"mappings":"AAgJO,SAAS,gBACd,OAC2C;AAC3C,SACE,OAAO,UAAU,YACjB,UAAU,QACV,mBAAmB,MAAM,CAAC,SAAS,QAAQ,KAAK;AAEpD;AAgDO,SAAS,0BAId,KACA,KACA,cACA,eACA,eAC2B;AAG3B,QAAM,cAAc;AAEpB,SAAO;AAAA,IACL,GAAG;AAAA,IACH,SAAS,YAAY,WAAW,cAAA;AAAA,IAChC,SAAS,YAAY,WAAW,cAAA;AAAA,IAChC,MAAM,YAAY,QAAQ;AAAA,IAC1B,eAAe,YAAY,iBAAiB;AAAA,EAAA;AAEhD;AAuCO,MAAM,qBAAqB;AAAA,EAChC;AAAA,EACA;AAAA,EACA;AAAA,EACA;AACF;AAMO,SAAS,kBAAkB,MAAuB;AACvD,SAAO,mBAAmB,SAAS,IAAW;AAChD;AAMO,SAAS,mBAAmB,MAA8B;AAC/D,SAAO,KAAK,KAAK,CAAC,YAAY,kBAAkB,OAAO,CAAC;AAC1D;"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tanstack/db",
-  "version": "0.5.33",
+  "version": "0.6.1",
   "description": "A reactive client store for building super fast apps on sync",
   "author": "Kyle Mathews",
   "license": "MIT",
@@ -12,7 +12,8 @@
   "homepage": "https://tanstack.com/db",
   "keywords": [
     "optimistic",
-    "typescript"
+    "typescript",
+    "tanstack-intent"
   ],
   "type": "module",
   "main": "dist/cjs/index.cjs",
@@ -40,7 +41,7 @@
   "dependencies": {
     "@standard-schema/spec": "^1.1.0",
     "@tanstack/pacer-lite": "^0.2.1",
-    "@tanstack/db-ivm": "0.1.17"
+    "@tanstack/db-ivm": "0.1.18"
   },
   "peerDependencies": {
     "typescript": ">=4.7"

package/skills/db-core/SKILL.md

@@ -10,7 +10,7 @@ description: >
   createPacedMutations. Entry point for all TanStack DB skills.
 type: core
 library: db
-library_version: '0.5.30'
+library_version: '0.6.0'
 ---
 
 # TanStack DB — Core Concepts
@@ -33,6 +33,7 @@ hooks. In framework projects, import from the framework package directly.
 | 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                      |
+| Persist collections to SQLite (offline cache)    | db-core/persistence/SKILL.md                         |
 | Preload collections in route loaders             | meta-framework/SKILL.md                              |
 | Add offline transaction queueing                 | offline/SKILL.md (in @tanstack/offline-transactions) |
 
@@ -54,8 +55,9 @@ For framework-specific hooks:
 - 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
+- Persisting collections to SQLite? → db-core/persistence
 - Need offline transaction persistence? → offline
 
 ## Version
 
-Targets @tanstack/db v0.5.30.
+Targets @tanstack/db v0.6.0.

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

@@ -6,13 +6,14 @@ description: >
   (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.
+  options: getKey, schema, sync, gcTime, autoIndex (default off), defaultIndexType,
+  syncMode (eager/on-demand, plus progressive for Electric). StandardSchema validation
+  with Zod/Valibot/ArkType. Collection lifecycle (idle/loading/ready/error).
+  Adapter-specific sync patterns including Electric txid tracking, Query direct
+  writes, and PowerSync query-driven sync with onLoad/onLoadSubset hooks.
 type: sub-skill
 library: db
-library_version: '0.5.30'
+library_version: '0.6.0'
 sources:
   - 'TanStack/db:docs/overview.md'
   - 'TanStack/db:docs/guides/schemas.md'
@@ -98,11 +99,29 @@ queryCollectionOptions({
 })
 ```
 
-| 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       |
+| 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 (Electric only) | Any       |
+
+## Indexing
+
+Indexing is opt-in. The `autoIndex` option defaults to `"off"`. To enable automatic indexing, set `autoIndex: "eager"` and provide a `defaultIndexType`:
+
+```ts
+import { BasicIndex } from '@tanstack/db'
+
+createCollection(
+  queryCollectionOptions({
+    autoIndex: 'eager',
+    defaultIndexType: BasicIndex,
+    // ...
+  }),
+)
+```
+
+Without `defaultIndexType`, setting `autoIndex: "eager"` throws a `CollectionConfigurationError`. You can also create indexes manually with `collection.createIndex()` and remove them with `collection.removeIndex()`.
 
 ## Core Patterns
 
@@ -255,7 +274,7 @@ app.post('/api/todos', async (req, res) => {
 })
 ```
 
-`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.
+`pg_current_xact_id()` must be queried inside the same SQL transaction as the mutation. Otherwise the txid doesn't match and `awaitTxId` times out (default 5 seconds).
 
 Source: docs/collections/electric-collection.md
 

package/skills/db-core/collection-setup/references/electric-adapter.md

@@ -78,7 +78,7 @@ onInsert: async ({ transaction }) => {
 
 ## Utility Methods (`collection.utils`)
 
-- `awaitTxId(txid, timeout?)` -- wait for txid in Electric stream; default timeout 30s
+- `awaitTxId(txid, timeout?)` -- wait for txid in Electric stream; default timeout 5s
 - `awaitMatch(matchFn, timeout?)` -- wait for message matching predicate; default timeout 3000ms
 
 ### Helper Exports

package/skills/db-core/collection-setup/references/powersync-adapter.md

@@ -196,6 +196,10 @@ await tx.commit()
 await tx.isPersisted.promise
 ```
 
+## On-Demand Sync Mode
+
+PowerSync supports `on-demand` sync mode (query-driven sync), where only rows matching active live query predicates are loaded from SQLite into the collection. This can be combined with Sync Streams via `onLoad` (eager) or `onLoadSubset` (on-demand) hooks to also control which data the PowerSync Service syncs to the device. Use `extractSimpleComparisons` or `parseWhereExpression` to derive Sync Stream parameters dynamically from live query predicates.
+
 ## Complete Example
 
 ```typescript

package/skills/db-core/collection-setup/references/query-adapter.md

@@ -176,6 +176,38 @@ const productsCollection = createCollection(
 )
 ```
 
+## Common Mistakes
+
+### HIGH Function-based queryKey without shared prefix
+
+Wrong:
+
+```ts
+queryCollectionOptions({
+  queryKey: (opts) => {
+    if (opts.where) {
+      return ['products-filtered', JSON.stringify(opts.where)]
+    }
+    return ['products-all']
+  },
+})
+```
+
+Correct:
+
+```ts
+queryCollectionOptions({
+  queryKey: (opts) => {
+    if (opts.where) {
+      return ['products', JSON.stringify(opts.where)]
+    }
+    return ['products']
+  },
+})
+```
+
+When using a function-based `queryKey`, all derived keys must share the base key (`queryKey({})`) as a prefix. TanStack Query uses prefix matching for cache operations; if derived keys don't share the base prefix, cache updates silently miss entries, leading to stale data.
+
 ## Key Behaviors
 
 - `queryFn` result is treated as **complete state** -- missing items are deleted

package/skills/db-core/custom-adapter/SKILL.md

@@ -2,15 +2,17 @@
 name: db-core/custom-adapter
 description: >
   Building custom collection adapters for new backends. SyncConfig interface:
-  sync function receiving begin, write, commit, markReady, truncate primitives.
-  ChangeMessage format (insert, update, delete). loadSubset for on-demand sync.
-  LoadSubsetOptions (where, orderBy, limit, cursor). Expression parsing:
-  parseWhereExpression, parseOrderByExpression, extractSimpleComparisons,
-  parseLoadSubsetOptions. Collection options creator pattern. rowUpdateMode
-  (partial vs full). Subscription lifecycle and cleanup functions.
+  sync function receiving begin, write, commit, markReady, truncate, metadata
+  primitives. ChangeMessage format (insert, update, delete). loadSubset for
+  on-demand sync. LoadSubsetOptions (where, orderBy, limit, cursor). Expression
+  parsing: parseWhereExpression, parseOrderByExpression,
+  extractSimpleComparisons, parseLoadSubsetOptions. Collection options creator
+  pattern. rowUpdateMode (partial vs full). Subscription lifecycle and cleanup
+  functions. Persisted sync metadata API (metadata.row and metadata.collection)
+  for storing per-row and per-collection adapter state.
 type: sub-skill
 library: db
-library_version: '0.5.30'
+library_version: '0.6.0'
 sources:
   - 'TanStack/db:docs/guides/collection-options-creator.md'
   - 'TanStack/db:packages/db/src/collection/sync.ts'
@@ -38,7 +40,7 @@ function myBackendCollectionOptions<T>(config: {
   return {
     getKey: config.getKey,
     sync: {
-      sync: ({ begin, write, commit, markReady, collection }) => {
+      sync: ({ begin, write, commit, markReady, metadata, collection }) => {
         let isInitialSyncComplete = false
         const bufferedEvents: Array<any> = []
 
@@ -157,6 +159,53 @@ Mutation handlers must not resolve until server changes have synced back to the
 4. **Version/timestamp**: wait until sync stream catches up to mutation time
 5. **Provider method**: `await backend.waitForPendingWrites()`
 
+### Persisted sync metadata
+
+The `metadata` API on the sync config allows adapters to store per-row and per-collection metadata that persists across sync transactions. This is useful for tracking resume tokens, cursors, LSNs, or other adapter-specific state.
+
+The `metadata` object is available as a property on the sync config argument alongside `begin`, `write`, `commit`, etc. It is always provided, but without persistence the metadata is in-memory only and does not survive reloads. With persistence, metadata is durable across sessions.
+
+```ts
+sync: ({ begin, write, commit, markReady, metadata }) => {
+  // Row metadata: store per-row state (e.g. server version, ETag)
+  metadata.row.get(key) // => unknown | undefined
+  metadata.row.set(key, { version: 3, etag: 'abc' })
+  metadata.row.delete(key)
+
+  // Collection metadata: store per-collection state (e.g. resume cursor)
+  metadata.collection.get('cursor') // => unknown | undefined
+  metadata.collection.set('cursor', 'token_abc123')
+  metadata.collection.delete('cursor')
+  metadata.collection.list() // => [{ key: 'cursor', value: 'token_abc123' }]
+  metadata.collection.list('resume') // filter by prefix
+}
+```
+
+Row metadata writes are tied to the current transaction. When a row is deleted via `write({ type: 'delete', ... })`, its row metadata is automatically deleted. When a row is inserted, its metadata is set from `message.metadata` if provided, or deleted otherwise.
+
+Collection metadata writes staged before `truncate()` are preserved and commit atomically with the truncate transaction.
+
+**Typical usage — resume token:**
+
+```ts
+sync: ({ begin, write, commit, markReady, metadata }) => {
+  const lastCursor = metadata.collection.get('cursor') as string | undefined
+
+  const stream = subscribeFromCursor(lastCursor)
+  stream.on('data', (batch) => {
+    begin()
+    for (const item of batch.items) {
+      write({ type: item.type, key: item.id, value: item.data })
+    }
+    metadata.collection.set('cursor', batch.cursor)
+    commit()
+  })
+
+  stream.on('ready', () => markReady())
+  return () => stream.close()
+}
+```
+
 ### Expression parsing for predicate push-down
 
 ```ts
@@ -282,4 +331,4 @@ Source: packages/db/src/collection/sync.ts:110
 
 Getting-started simplicity (localOnly, eager mode) conflicts with production correctness (on-demand sync, race condition prevention, proper markReady handling). Agents optimizing for quick setup tend to skip buffering, markReady, and cleanup functions.
 
-See also: db-core/collection-setup/SKILL.md -- for built-in adapter patterns to model after.
+See also: db-core/collection-setup/SKILL.md — for built-in adapter patterns to model after.