@tanstack/db 0.0.22 → 0.0.24

package/src/transactions.ts

@@ -2,7 +2,6 @@ import { createDeferred } from "./deferred"
 import type { Deferred } from "./deferred"
 import type {
   MutationFn,
-  OperationType,
   PendingMutation,
   TransactionConfig,
   TransactionState,
@@ -66,10 +65,10 @@ let sequenceNumber = 0
  * // Commit later
  * await tx.commit()
  */
-export function createTransaction<
-  TData extends object = Record<string, unknown>,
->(config: TransactionConfig<TData>): Transaction<TData> {
-  const newTransaction = new Transaction<TData>(config)
+export function createTransaction<T extends object = Record<string, unknown>>(
+  config: TransactionConfig<T>
+): Transaction<T> {
+  const newTransaction = new Transaction<T>(config)
   transactions.push(newTransaction)
   return newTransaction
 }
@@ -108,15 +107,12 @@ function removeFromPendingList(tx: Transaction<any>) {
   }
 }
 
-class Transaction<
-  T extends object = Record<string, unknown>,
-  TOperation extends OperationType = OperationType,
-> {
+class Transaction<T extends object = Record<string, unknown>> {
   public id: string
   public state: TransactionState
   public mutationFn: MutationFn<T>
-  public mutations: Array<PendingMutation<T, TOperation>>
-  public isPersisted: Deferred<Transaction<T, TOperation>>
+  public mutations: Array<PendingMutation<T>>
+  public isPersisted: Deferred<Transaction<T>>
   public autoCommit: boolean
   public createdAt: Date
   public sequenceNumber: number
@@ -134,7 +130,7 @@ class Transaction<
     this.mutationFn = config.mutationFn
     this.state = `pending`
     this.mutations = []
-    this.isPersisted = createDeferred<Transaction<T, TOperation>>()
+    this.isPersisted = createDeferred<Transaction<T>>()
     this.autoCommit = config.autoCommit ?? true
     this.createdAt = new Date()
     this.sequenceNumber = sequenceNumber++

package/src/types.ts

@@ -14,6 +14,40 @@ export type InferSchemaOutput<T> = T extends StandardSchemaV1
     : Record<string, unknown>
   : Record<string, unknown>
 
+/**
+ * Helper type to extract the input type from a standard schema
+ *
+ * @internal This is used for collection insert type inference
+ */
+export type InferSchemaInput<T> = T extends StandardSchemaV1
+  ? StandardSchemaV1.InferInput<T> extends object
+    ? StandardSchemaV1.InferInput<T>
+    : Record<string, unknown>
+  : Record<string, unknown>
+
+/**
+ * Helper type to determine the insert input type
+ * This takes the raw generics (TExplicit, TSchema, TFallback) instead of the resolved T.
+ *
+ * Priority:
+ * 1. Explicit generic TExplicit (if not 'unknown')
+ * 2. Schema input type (if schema provided)
+ * 3. Fallback type TFallback
+ *
+ * @internal This is used for collection insert type inference
+ */
+export type ResolveInsertInput<
+  TExplicit = unknown,
+  TSchema extends StandardSchemaV1 = never,
+  TFallback extends object = Record<string, unknown>,
+> = unknown extends TExplicit
+  ? [TSchema] extends [never]
+    ? TFallback
+    : InferSchemaInput<TSchema>
+  : TExplicit extends object
+    ? TExplicit
+    : Record<string, unknown>
+
 /**
  * Helper type to determine the final type based on priority:
  * 1. Explicit generic TExplicit (if not 'unknown')
@@ -48,6 +82,17 @@ export type Fn = (...args: Array<any>) => any
  */
 export type UtilsRecord = Record<string, Fn>
 
+/**
+ *
+ * @remarks `update` and `insert` are both represented as `Partial<T>`, but changes for `insert` could me made more precise by inferring the schema input type. In practice, this has almost 0 real world impact so it's not worth the added type complexity.
+ *
+ * @see  https://github.com/TanStack/db/pull/209#issuecomment-3053001206
+ */
+export type ResolveTransactionChanges<
+  T extends object = Record<string, unknown>,
+  TOperation extends OperationType = OperationType,
+> = TOperation extends `delete` ? T : Partial<T>
+
 /**
  * Represents a pending mutation within a transaction
  * Contains information about the original and modified data, as well as metadata
@@ -55,25 +100,32 @@ export type UtilsRecord = Record<string, Fn>
 export interface PendingMutation<
   T extends object = Record<string, unknown>,
   TOperation extends OperationType = OperationType,
+  TCollection extends Collection<T, any, any, any, any> = Collection<
+    T,
+    any,
+    any,
+    any,
+    any
+  >,
 > {
   mutationId: string
+  // The state of the object before the mutation.
   original: TOperation extends `insert` ? {} : T
+  // The result state of the object after all mutations.
   modified: T
-  changes: TOperation extends `insert`
-    ? T
-    : TOperation extends `delete`
-      ? T
-      : Partial<T>
+  // Only the actual changes to the object by the mutation.
+  changes: ResolveTransactionChanges<T, TOperation>
   globalKey: string
+
   key: any
-  type: OperationType
+  type: TOperation
   metadata: unknown
   syncMetadata: Record<string, unknown>
   /** Whether this mutation should be applied optimistically (defaults to true) */
   optimistic: boolean
   createdAt: Date
   updatedAt: Date
-  collection: Collection<T, any, any>
+  collection: TCollection
 }
 
 /**
@@ -99,7 +151,7 @@ export type NonEmptyArray<T> = [T, ...Array<T>]
 export type TransactionWithMutations<
   T extends object = Record<string, unknown>,
   TOperation extends OperationType = OperationType,
-> = Transaction<T, TOperation> & {
+> = Transaction<T> & {
   mutations: NonEmptyArray<PendingMutation<T, TOperation>>
 }
 
@@ -116,12 +168,14 @@ export interface TransactionConfig<T extends object = Record<string, unknown>> {
 /**
  * Options for the createOptimisticAction helper
  */
-export interface CreateOptimisticActionsOptions<TVars = unknown>
-  extends Omit<TransactionConfig, `mutationFn`> {
+export interface CreateOptimisticActionsOptions<
+  TVars = unknown,
+  T extends object = Record<string, unknown>,
+> extends Omit<TransactionConfig<T>, `mutationFn`> {
   /** Function to apply optimistic updates locally before the mutation completes */
   onMutate: (vars: TVars) => void
   /** Function to execute the mutation on the server */
-  mutationFn: (vars: TVars, params: MutationFnParams) => Promise<any>
+  mutationFn: (vars: TVars, params: MutationFnParams<T>) => Promise<any>
 }
 
 export type { Transaction }
@@ -145,7 +199,7 @@ export interface SyncConfig<
   TKey extends string | number = string | number,
 > {
   sync: (params: {
-    collection: Collection<T, TKey>
+    collection: Collection<T, TKey, any, any, any>
     begin: () => void
     write: (message: Omit<ChangeMessage<T>, `key`>) => void
     commit: () => void
@@ -232,7 +286,6 @@ export type InsertMutationFnParams<
   transaction: TransactionWithMutations<T, `insert`>
   collection: Collection<T, TKey, TUtils>
 }
-
 export type DeleteMutationFnParams<
   T extends object = Record<string, unknown>,
   TKey extends string | number = string | number,
@@ -293,6 +346,7 @@ export interface CollectionConfig<
   T extends object = Record<string, unknown>,
   TKey extends string | number = string | number,
   TSchema extends StandardSchemaV1 = StandardSchemaV1,
+  TInsertInput extends object = T,
 > {
   // If an id isn't passed in, a UUID will be
   // generated for it.
@@ -371,7 +425,8 @@ export interface CollectionConfig<
    *   })
    * }
    */
-  onInsert?: InsertMutationFn<T, TKey>
+  onInsert?: InsertMutationFn<TInsertInput, TKey>
+
   /**
    * Optional asynchronous handler function called before an update operation
    * @param params Object containing transaction and collection information

package/src/utils.ts

@@ -0,0 +1,86 @@
+/**
+ * Generic utility functions
+ */
+
+/**
+ * Deep equality function that compares two values recursively
+ *
+ * @param a - First value to compare
+ * @param b - Second value to compare
+ * @returns True if the values are deeply equal, false otherwise
+ *
+ * @example
+ * ```typescript
+ * deepEquals({ a: 1, b: 2 }, { b: 2, a: 1 }) // true (property order doesn't matter)
+ * deepEquals([1, { x: 2 }], [1, { x: 2 }]) // true
+ * deepEquals({ a: 1 }, { a: 2 }) // false
+ * ```
+ */
+export function deepEquals(a: any, b: any): boolean {
+  return deepEqualsInternal(a, b, new Map())
+}
+
+/**
+ * Internal implementation with cycle detection to prevent infinite recursion
+ */
+function deepEqualsInternal(
+  a: any,
+  b: any,
+  visited: Map<object, object>
+): boolean {
+  // Handle strict equality (primitives, same reference)
+  if (a === b) return true
+
+  // Handle null/undefined
+  if (a == null || b == null) return false
+
+  // Handle different types
+  if (typeof a !== typeof b) return false
+
+  // Handle arrays
+  if (Array.isArray(a)) {
+    if (!Array.isArray(b) || a.length !== b.length) return false
+
+    // Check for circular references
+    if (visited.has(a)) {
+      return visited.get(a) === b
+    }
+    visited.set(a, b)
+
+    const result = a.every((item, index) =>
+      deepEqualsInternal(item, b[index], visited)
+    )
+    visited.delete(a)
+    return result
+  }
+
+  // Handle objects
+  if (typeof a === `object`) {
+    // Check for circular references
+    if (visited.has(a)) {
+      return visited.get(a) === b
+    }
+    visited.set(a, b)
+
+    // Get all keys from both objects
+    const keysA = Object.keys(a)
+    const keysB = Object.keys(b)
+
+    // Check if they have the same number of keys
+    if (keysA.length !== keysB.length) {
+      visited.delete(a)
+      return false
+    }
+
+    // Check if all keys exist in both objects and their values are equal
+    const result = keysA.every(
+      (key) => key in b && deepEqualsInternal(a[key], b[key], visited)
+    )
+
+    visited.delete(a)
+    return result
+  }
+
+  // For primitives that aren't strictly equal
+  return false
+}