@tanstack/db 0.2.4 → 0.3.0

package/src/local-only.ts

@@ -1,9 +1,10 @@
 import type {
+  BaseCollectionConfig,
   CollectionConfig,
   DeleteMutationFnParams,
+  InferSchemaOutput,
   InsertMutationFnParams,
   OperationType,
-  ResolveType,
   SyncConfig,
   UpdateMutationFnParams,
   UtilsRecord,
@@ -12,76 +13,23 @@ import type { StandardSchemaV1 } from "@standard-schema/spec"
 
 /**
  * Configuration interface for Local-only collection options
- * @template TExplicit - The explicit type of items in the collection (highest priority)
- * @template TSchema - The schema type for validation and type inference (second priority)
- * @template TFallback - The fallback type if no explicit or schema type is provided
- * @template TKey - The type of the key returned by getKey
- *
- * @remarks
- * Type resolution follows a priority order:
- * 1. If you provide an explicit type via generic parameter, it will be used
- * 2. If no explicit type is provided but a schema is, the schema's output type will be inferred
- * 3. If neither explicit type nor schema is provided, the fallback type will be used
- *
- * You should provide EITHER an explicit type OR a schema, but not both, as they would conflict.
+ * @template T - The type of items in the collection
+ * @template TSchema - The schema type for validation
+ * @template TKey - The type of the key returned by `getKey`
  */
 export interface LocalOnlyCollectionConfig<
-  TExplicit = unknown,
+  T extends object = object,
   TSchema extends StandardSchemaV1 = never,
-  TFallback extends Record<string, unknown> = Record<string, unknown>,
   TKey extends string | number = string | number,
-> {
-  /**
-   * Standard Collection configuration properties
-   */
-  id?: string
-  schema?: TSchema
-  getKey: (item: ResolveType<TExplicit, TSchema, TFallback>) => TKey
-
+> extends Omit<
+    BaseCollectionConfig<T, TKey, TSchema, LocalOnlyCollectionUtils>,
+    `gcTime` | `startSync`
+  > {
   /**
    * Optional initial data to populate the collection with on creation
    * This data will be applied during the initial sync process
    */
-  initialData?: Array<ResolveType<TExplicit, TSchema, TFallback>>
-
-  /**
-   * Optional asynchronous handler function called after an insert operation
-   * @param params Object containing transaction and collection information
-   * @returns Promise resolving to any value
-   */
-  onInsert?: (
-    params: InsertMutationFnParams<
-      ResolveType<TExplicit, TSchema, TFallback>,
-      TKey,
-      LocalOnlyCollectionUtils
-    >
-  ) => Promise<any>
-
-  /**
-   * Optional asynchronous handler function called after an update operation
-   * @param params Object containing transaction and collection information
-   * @returns Promise resolving to any value
-   */
-  onUpdate?: (
-    params: UpdateMutationFnParams<
-      ResolveType<TExplicit, TSchema, TFallback>,
-      TKey,
-      LocalOnlyCollectionUtils
-    >
-  ) => Promise<any>
-
-  /**
-   * Optional asynchronous handler function called after a delete operation
-   * @param params Object containing transaction and collection information
-   * @returns Promise resolving to any value
-   */
-  onDelete?: (
-    params: DeleteMutationFnParams<
-      ResolveType<TExplicit, TSchema, TFallback>,
-      TKey,
-      LocalOnlyCollectionUtils
-    >
-  ) => Promise<any>
+  initialData?: Array<T>
 }
 
 /**
@@ -96,9 +44,7 @@ export interface LocalOnlyCollectionUtils extends UtilsRecord {}
  * that immediately "syncs" all optimistic changes to the collection, making them permanent.
  * Perfect for local-only data that doesn't need persistence or external synchronization.
  *
- * @template TExplicit - The explicit type of items in the collection (highest priority)
- * @template TSchema - The schema type for validation and type inference (second priority)
- * @template TFallback - The fallback type if no explicit or schema type is provided
+ * @template T - The schema type if a schema is provided, otherwise the type of items in the collection
  * @template TKey - The type of the key returned by getKey
  * @param config - Configuration options for the Local-only collection
  * @returns Collection options with utilities (currently empty but follows the pattern)
@@ -135,29 +81,55 @@ export interface LocalOnlyCollectionUtils extends UtilsRecord {}
  *   })
  * )
  */
+
+// Overload for when schema is provided
 export function localOnlyCollectionOptions<
-  TExplicit = unknown,
-  TSchema extends StandardSchemaV1 = never,
-  TFallback extends Record<string, unknown> = Record<string, unknown>,
+  T extends StandardSchemaV1,
   TKey extends string | number = string | number,
 >(
-  config: LocalOnlyCollectionConfig<TExplicit, TSchema, TFallback, TKey>
-): CollectionConfig<ResolveType<TExplicit, TSchema, TFallback>, TKey> & {
+  config: LocalOnlyCollectionConfig<InferSchemaOutput<T>, T, TKey> & {
+    schema: T
+  }
+): CollectionConfig<InferSchemaOutput<T>, TKey, T> & {
   utils: LocalOnlyCollectionUtils
-} {
-  type ResolvedType = ResolveType<TExplicit, TSchema, TFallback>
+  schema: T
+}
+
+// Overload for when no schema is provided
+// the type T needs to be passed explicitly unless it can be inferred from the getKey function in the config
+export function localOnlyCollectionOptions<
+  T extends object,
+  TKey extends string | number = string | number,
+>(
+  config: LocalOnlyCollectionConfig<T, never, TKey> & {
+    schema?: never // prohibit schema
+  }
+): CollectionConfig<T, TKey> & {
+  utils: LocalOnlyCollectionUtils
+  schema?: never // no schema in the result
+}
 
+export function localOnlyCollectionOptions(
+  config: LocalOnlyCollectionConfig<any, any, string | number>
+): CollectionConfig<any, string | number, any> & {
+  utils: LocalOnlyCollectionUtils
+  schema?: StandardSchemaV1
+} {
   const { initialData, onInsert, onUpdate, onDelete, ...restConfig } = config
 
   // Create the sync configuration with transaction confirmation capability
-  const syncResult = createLocalOnlySync<ResolvedType, TKey>(initialData)
+  const syncResult = createLocalOnlySync(initialData)
 
   /**
    * Create wrapper handlers that call user handlers first, then confirm transactions
    * Wraps the user's onInsert handler to also confirm the transaction immediately
    */
   const wrappedOnInsert = async (
-    params: InsertMutationFnParams<ResolvedType, TKey, LocalOnlyCollectionUtils>
+    params: InsertMutationFnParams<
+      any,
+      string | number,
+      LocalOnlyCollectionUtils
+    >
   ) => {
     // Call user handler first if provided
     let handlerResult
@@ -175,7 +147,11 @@ export function localOnlyCollectionOptions<
    * Wrapper for onUpdate handler that also confirms the transaction immediately
    */
   const wrappedOnUpdate = async (
-    params: UpdateMutationFnParams<ResolvedType, TKey, LocalOnlyCollectionUtils>
+    params: UpdateMutationFnParams<
+      any,
+      string | number,
+      LocalOnlyCollectionUtils
+    >
   ) => {
     // Call user handler first if provided
     let handlerResult
@@ -193,7 +169,11 @@ export function localOnlyCollectionOptions<
    * Wrapper for onDelete handler that also confirms the transaction immediately
    */
   const wrappedOnDelete = async (
-    params: DeleteMutationFnParams<ResolvedType, TKey, LocalOnlyCollectionUtils>
+    params: DeleteMutationFnParams<
+      any,
+      string | number,
+      LocalOnlyCollectionUtils
+    >
   ) => {
     // Call user handler first if provided
     let handlerResult

package/src/local-storage.ts

@@ -7,10 +7,11 @@ import {
   StorageKeyRequiredError,
 } from "./errors"
 import type {
+  BaseCollectionConfig,
   CollectionConfig,
   DeleteMutationFnParams,
+  InferSchemaOutput,
   InsertMutationFnParams,
-  ResolveType,
   SyncConfig,
   UpdateMutationFnParams,
   UtilsRecord,
@@ -46,23 +47,15 @@ interface StoredItem<T> {
 
 /**
  * Configuration interface for localStorage collection options
- * @template TExplicit - The explicit type of items in the collection (highest priority)
- * @template TSchema - The schema type for validation and type inference (second priority)
- * @template TFallback - The fallback type if no explicit or schema type is provided
- *
- * @remarks
- * Type resolution follows a priority order:
- * 1. If you provide an explicit type via generic parameter, it will be used
- * 2. If no explicit type is provided but a schema is, the schema's output type will be inferred
- * 3. If neither explicit type nor schema is provided, the fallback type will be used
- *
- * You should provide EITHER an explicit type OR a schema, but not both, as they would conflict.
+ * @template T - The type of items in the collection
+ * @template TSchema - The schema type for validation
+ * @template TKey - The type of the key returned by `getKey`
  */
 export interface LocalStorageCollectionConfig<
-  TExplicit = unknown,
+  T extends object = object,
   TSchema extends StandardSchemaV1 = never,
-  TFallback extends object = Record<string, unknown>,
-> {
+  TKey extends string | number = string | number,
+> extends BaseCollectionConfig<T, TKey, TSchema> {
   /**
    * The key to use for storing the collection data in localStorage/sessionStorage
    */
@@ -79,41 +72,6 @@ export interface LocalStorageCollectionConfig<
    * Can be any object that implements addEventListener/removeEventListener for storage events
    */
   storageEventApi?: StorageEventApi
-
-  /**
-   * Collection identifier (defaults to "local-collection:{storageKey}" if not provided)
-   */
-  id?: string
-  schema?: TSchema
-  getKey: CollectionConfig<ResolveType<TExplicit, TSchema, TFallback>>[`getKey`]
-  sync?: CollectionConfig<ResolveType<TExplicit, TSchema, TFallback>>[`sync`]
-
-  /**
-   * Optional asynchronous handler function called before an insert operation
-   * @param params Object containing transaction and collection information
-   * @returns Promise resolving to any value
-   */
-  onInsert?: (
-    params: InsertMutationFnParams<ResolveType<TExplicit, TSchema, TFallback>>
-  ) => Promise<any>
-
-  /**
-   * Optional asynchronous handler function called before an update operation
-   * @param params Object containing transaction and collection information
-   * @returns Promise resolving to any value
-   */
-  onUpdate?: (
-    params: UpdateMutationFnParams<ResolveType<TExplicit, TSchema, TFallback>>
-  ) => Promise<any>
-
-  /**
-   * Optional asynchronous handler function called before a delete operation
-   * @param params Object containing transaction and collection information
-   * @returns Promise resolving to any value
-   */
-  onDelete?: (
-    params: DeleteMutationFnParams<ResolveType<TExplicit, TSchema, TFallback>>
-  ) => Promise<any>
 }
 
 /**
@@ -202,18 +160,43 @@ function generateUuid(): string {
  *   })
  * )
  */
+
+// Overload for when schema is provided
 export function localStorageCollectionOptions<
-  TExplicit = unknown,
-  TSchema extends StandardSchemaV1 = never,
-  TFallback extends object = Record<string, unknown>,
+  T extends StandardSchemaV1,
+  TKey extends string | number = string | number,
 >(
-  config: LocalStorageCollectionConfig<TExplicit, TSchema, TFallback>
-): Omit<CollectionConfig<ResolveType<TExplicit, TSchema, TFallback>>, `id`> & {
+  config: LocalStorageCollectionConfig<InferSchemaOutput<T>, T, TKey> & {
+    schema: T
+  }
+): CollectionConfig<InferSchemaOutput<T>, TKey, T> & {
   id: string
   utils: LocalStorageCollectionUtils
-} {
-  type ResolvedType = ResolveType<TExplicit, TSchema, TFallback>
+  schema: T
+}
 
+// Overload for when no schema is provided
+// the type T needs to be passed explicitly unless it can be inferred from the getKey function in the config
+export function localStorageCollectionOptions<
+  T extends object,
+  TKey extends string | number = string | number,
+>(
+  config: LocalStorageCollectionConfig<T, never, TKey> & {
+    schema?: never // prohibit schema
+  }
+): CollectionConfig<T, TKey> & {
+  id: string
+  utils: LocalStorageCollectionUtils
+  schema?: never // no schema in the result
+}
+
+export function localStorageCollectionOptions(
+  config: LocalStorageCollectionConfig<any, any, string | number>
+): Omit<CollectionConfig<any, string | number, any>, `id`> & {
+  id: string
+  utils: LocalStorageCollectionUtils
+  schema?: StandardSchemaV1
+} {
   // Validate required parameters
   if (!config.storageKey) {
     throw new StorageKeyRequiredError()
@@ -237,10 +220,10 @@ export function localStorageCollectionOptions<
   }
 
   // Track the last known state to detect changes
-  const lastKnownData = new Map<string | number, StoredItem<ResolvedType>>()
+  const lastKnownData = new Map<string | number, StoredItem<any>>()
 
   // Create the sync configuration
-  const sync = createLocalStorageSync<ResolvedType>(
+  const sync = createLocalStorageSync<any>(
     config.storageKey,
     storage,
     storageEventApi,
@@ -263,11 +246,11 @@ export function localStorageCollectionOptions<
    * @param dataMap - Map of items with version tracking to save to storage
    */
   const saveToStorage = (
-    dataMap: Map<string | number, StoredItem<ResolvedType>>
+    dataMap: Map<string | number, StoredItem<any>>
   ): void => {
     try {
       // Convert Map to object format for storage
-      const objectData: Record<string, StoredItem<ResolvedType>> = {}
+      const objectData: Record<string, StoredItem<any>> = {}
       dataMap.forEach((storedItem, key) => {
         objectData[String(key)] = storedItem
       })
@@ -302,9 +285,7 @@ export function localStorageCollectionOptions<
    * Create wrapper handlers for direct persistence operations that perform actual storage operations
    * Wraps the user's onInsert handler to also save changes to localStorage
    */
-  const wrappedOnInsert = async (
-    params: InsertMutationFnParams<ResolvedType>
-  ) => {
+  const wrappedOnInsert = async (params: InsertMutationFnParams<any>) => {
     // Validate that all values in the transaction can be JSON serialized
     params.transaction.mutations.forEach((mutation) => {
       validateJsonSerializable(mutation.modified, `insert`)
@@ -318,15 +299,12 @@ export function localStorageCollectionOptions<
 
     // Always persist to storage
     // Load current data from storage
-    const currentData = loadFromStorage<ResolvedType>(
-      config.storageKey,
-      storage
-    )
+    const currentData = loadFromStorage<any>(config.storageKey, storage)
 
     // Add new items with version keys
     params.transaction.mutations.forEach((mutation) => {
       const key = config.getKey(mutation.modified)
-      const storedItem: StoredItem<ResolvedType> = {
+      const storedItem: StoredItem<any> = {
         versionKey: generateUuid(),
         data: mutation.modified,
       }
@@ -342,9 +320,7 @@ export function localStorageCollectionOptions<
     return handlerResult
   }
 
-  const wrappedOnUpdate = async (
-    params: UpdateMutationFnParams<ResolvedType>
-  ) => {
+  const wrappedOnUpdate = async (params: UpdateMutationFnParams<any>) => {
     // Validate that all values in the transaction can be JSON serialized
     params.transaction.mutations.forEach((mutation) => {
       validateJsonSerializable(mutation.modified, `update`)
@@ -358,15 +334,12 @@ export function localStorageCollectionOptions<
 
     // Always persist to storage
     // Load current data from storage
-    const currentData = loadFromStorage<ResolvedType>(
-      config.storageKey,
-      storage
-    )
+    const currentData = loadFromStorage<any>(config.storageKey, storage)
 
     // Update items with new version keys
     params.transaction.mutations.forEach((mutation) => {
       const key = config.getKey(mutation.modified)
-      const storedItem: StoredItem<ResolvedType> = {
+      const storedItem: StoredItem<any> = {
         versionKey: generateUuid(),
         data: mutation.modified,
       }
@@ -382,9 +355,7 @@ export function localStorageCollectionOptions<
     return handlerResult
   }
 
-  const wrappedOnDelete = async (
-    params: DeleteMutationFnParams<ResolvedType>
-  ) => {
+  const wrappedOnDelete = async (params: DeleteMutationFnParams<any>) => {
     // Call the user handler BEFORE persisting changes (if provided)
     let handlerResult: any = {}
     if (config.onDelete) {
@@ -393,15 +364,12 @@ export function localStorageCollectionOptions<
 
     // Always persist to storage
     // Load current data from storage
-    const currentData = loadFromStorage<ResolvedType>(
-      config.storageKey,
-      storage
-    )
+    const currentData = loadFromStorage<any>(config.storageKey, storage)
 
     // Remove items
     params.transaction.mutations.forEach((mutation) => {
       // For delete operations, mutation.original contains the full object
-      const key = config.getKey(mutation.original as ResolvedType)
+      const key = config.getKey(mutation.original)
       currentData.delete(key)
     })
 

package/src/query/builder/types.ts

@@ -8,7 +8,6 @@ import type {
   Value,
 } from "../ir.js"
 import type { QueryBuilder } from "./index.js"
-import type { ResolveType } from "../../types.js"
 
 /**
  * Context - The central state container for query builder operations
@@ -77,19 +76,11 @@ export type Source = {
 /**
  * InferCollectionType - Extracts the TypeScript type from a CollectionImpl
  *
- * This helper ensures we get the same type that would be used when creating
- * the collection itself. It uses the internal `ResolveType` logic to maintain
- * consistency between collection creation and query type inference.
- *
- * The complex generic parameters extract:
- * - U: The base document type
- * - TSchema: The schema definition
- * - The resolved type combines these with any transforms
+ * This helper ensures we get the same type that was used when creating the collection itself.
+ * This can be an explicit type passed by the user or the schema output type.
  */
 export type InferCollectionType<T> =
-  T extends CollectionImpl<infer U, any, any, infer TSchema, any>
-    ? ResolveType<U, TSchema, U>
-    : never
+  T extends CollectionImpl<infer TOutput, any, any, any, any> ? TOutput : never
 
 /**
  * SchemaFromSource - Converts a Source definition into a ContextSchema

package/src/query/live-query-collection.ts

@@ -130,7 +130,7 @@ export function createLiveQueryCollection<
 
 /**
  * Bridge function that handles the type compatibility between query2's TResult
- * and core collection's ResolveType without exposing ugly type assertions to users
+ * and core collection's output type without exposing ugly type assertions to users
  */
 function bridgeToCreateCollection<
   TResult extends object,

package/src/transactions.ts

@@ -19,6 +19,86 @@ let transactionStack: Array<Transaction<any>> = []
 
 let sequenceNumber = 0
 
+/**
+ * Merges two pending mutations for the same item within a transaction
+ *
+ * Merge behavior truth table:
+ * - (insert, update) → insert (merge changes, keep empty original)
+ * - (insert, delete) → null (cancel both mutations)
+ * - (update, delete) → delete (delete dominates)
+ * - (update, update) → update (replace with latest, union changes)
+ * - (delete, delete) → delete (replace with latest)
+ * - (insert, insert) → insert (replace with latest)
+ *
+ * Note: (delete, update) and (delete, insert) should never occur as the collection
+ * layer prevents operations on deleted items within the same transaction.
+ *
+ * @param existing - The existing mutation in the transaction
+ * @param incoming - The new mutation being applied
+ * @returns The merged mutation, or null if both should be removed
+ */
+function mergePendingMutations<T extends object>(
+  existing: PendingMutation<T>,
+  incoming: PendingMutation<T>
+): PendingMutation<T> | null {
+  // Truth table implementation
+  switch (`${existing.type}-${incoming.type}` as const) {
+    case `insert-update`: {
+      // Update after insert: keep as insert but merge changes
+      // For insert-update, the key should remain the same since collections don't allow key changes
+      return {
+        ...existing,
+        type: `insert` as const,
+        original: {},
+        modified: incoming.modified,
+        changes: { ...existing.changes, ...incoming.changes },
+        // Keep existing keys (key changes not allowed in updates)
+        key: existing.key,
+        globalKey: existing.globalKey,
+        // Merge metadata (last-write-wins)
+        metadata: incoming.metadata ?? existing.metadata,
+        syncMetadata: { ...existing.syncMetadata, ...incoming.syncMetadata },
+        // Update tracking info
+        mutationId: incoming.mutationId,
+        updatedAt: incoming.updatedAt,
+      }
+    }
+
+    case `insert-delete`:
+      // Delete after insert: cancel both mutations
+      return null
+
+    case `update-delete`:
+      // Delete after update: delete dominates
+      return incoming
+
+    case `update-update`: {
+      // Update after update: replace with latest, union changes
+      return {
+        ...incoming,
+        // Keep original from first update
+        original: existing.original,
+        // Union the changes from both updates
+        changes: { ...existing.changes, ...incoming.changes },
+        // Merge metadata
+        metadata: incoming.metadata ?? existing.metadata,
+        syncMetadata: { ...existing.syncMetadata, ...incoming.syncMetadata },
+      }
+    }
+
+    case `delete-delete`:
+    case `insert-insert`:
+      // Same type: replace with latest
+      return incoming
+
+    default: {
+      // Exhaustiveness check
+      const _exhaustive: never = `${existing.type}-${incoming.type}` as never
+      throw new Error(`Unhandled mutation combination: ${_exhaustive}`)
+    }
+  }
+}
+
 /**
  * Creates a new transaction for grouping multiple collection operations
  * @param config - Transaction configuration with mutation function
@@ -203,12 +283,32 @@ class Transaction<T extends object = Record<string, unknown>> {
     }
 
     if (this.autoCommit) {
-      this.commit()
+      this.commit().catch(() => {
+        // Errors from autoCommit are handled via isPersisted.promise
+        // This catch prevents unhandled promise rejections
+      })
     }
 
     return this
   }
 
+  /**
+   * Apply new mutations to this transaction, intelligently merging with existing mutations
+   *
+   * When mutations operate on the same item (same globalKey), they are merged according to
+   * the following rules:
+   *
+   * - **insert + update** → insert (merge changes, keep empty original)
+   * - **insert + delete** → removed (mutations cancel each other out)
+   * - **update + delete** → delete (delete dominates)
+   * - **update + update** → update (union changes, keep first original)
+   * - **same type** → replace with latest
+   *
+   * This merging reduces over-the-wire churn and keeps the optimistic local view
+   * aligned with user intent.
+   *
+   * @param mutations - Array of new mutations to apply
+   */
   applyMutations(mutations: Array<PendingMutation<any>>): void {
     for (const newMutation of mutations) {
       const existingIndex = this.mutations.findIndex(
@@ -216,8 +316,16 @@ class Transaction<T extends object = Record<string, unknown>> {
       )
 
       if (existingIndex >= 0) {
-        // Replace existing mutation
-        this.mutations[existingIndex] = newMutation
+        const existingMutation = this.mutations[existingIndex]!
+        const mergeResult = mergePendingMutations(existingMutation, newMutation)
+
+        if (mergeResult === null) {
+          // Remove the mutation (e.g., delete after insert cancels both)
+          this.mutations.splice(existingIndex, 1)
+        } else {
+          // Replace with merged mutation
+          this.mutations[existingIndex] = mergeResult
+        }
       } else {
         // Insert new mutation
         this.mutations.push(newMutation)
@@ -374,14 +482,21 @@ class Transaction<T extends object = Record<string, unknown>> {
 
       this.isPersisted.resolve(this)
     } catch (error) {
+      // Preserve the original error for rethrowing
+      const originalError =
+        error instanceof Error ? error : new Error(String(error))
+
       // Update transaction with error information
       this.error = {
-        message: error instanceof Error ? error.message : String(error),
-        error: error instanceof Error ? error : new Error(String(error)),
+        message: originalError.message,
+        error: originalError,
       }
 
       // rollback the transaction
-      return this.rollback()
+      this.rollback()
+
+      // Re-throw the original error to preserve identity and stack
+      throw originalError
     }
 
     return this