@tanstack/db 0.0.16 → 0.0.18

package/src/types.ts

@@ -209,41 +209,73 @@ export interface InsertConfig {
   metadata?: Record<string, unknown>
 }
 
-export type UpdateMutationFnParams<T extends object = Record<string, unknown>> =
-  {
-    transaction: TransactionWithMutations<T, `update`>
-  }
+export type UpdateMutationFnParams<
+  T extends object = Record<string, unknown>,
+  TKey extends string | number = string | number,
+  TUtils extends UtilsRecord = Record<string, Fn>,
+> = {
+  transaction: TransactionWithMutations<T, `update`>
+  collection: Collection<T, TKey, TUtils>
+}
 
-export type InsertMutationFnParams<T extends object = Record<string, unknown>> =
-  {
-    transaction: TransactionWithMutations<T, `insert`>
-  }
+export type InsertMutationFnParams<
+  T extends object = Record<string, unknown>,
+  TKey extends string | number = string | number,
+  TUtils extends UtilsRecord = Record<string, Fn>,
+> = {
+  transaction: TransactionWithMutations<T, `insert`>
+  collection: Collection<T, TKey, TUtils>
+}
 
-export type DeleteMutationFnParams<T extends object = Record<string, unknown>> =
-  {
-    transaction: TransactionWithMutations<T, `delete`>
-  }
+export type DeleteMutationFnParams<
+  T extends object = Record<string, unknown>,
+  TKey extends string | number = string | number,
+  TUtils extends UtilsRecord = Record<string, Fn>,
+> = {
+  transaction: TransactionWithMutations<T, `delete`>
+  collection: Collection<T, TKey, TUtils>
+}
 
-export type InsertMutationFn<T extends object = Record<string, unknown>> = (
-  params: InsertMutationFnParams<T>
-) => Promise<any>
+export type InsertMutationFn<
+  T extends object = Record<string, unknown>,
+  TKey extends string | number = string | number,
+  TUtils extends UtilsRecord = Record<string, Fn>,
+> = (params: InsertMutationFnParams<T, TKey, TUtils>) => Promise<any>
 
-export type UpdateMutationFn<T extends object = Record<string, unknown>> = (
-  params: UpdateMutationFnParams<T>
-) => Promise<any>
+export type UpdateMutationFn<
+  T extends object = Record<string, unknown>,
+  TKey extends string | number = string | number,
+  TUtils extends UtilsRecord = Record<string, Fn>,
+> = (params: UpdateMutationFnParams<T, TKey, TUtils>) => Promise<any>
 
-export type DeleteMutationFn<T extends object = Record<string, unknown>> = (
-  params: DeleteMutationFnParams<T>
-) => Promise<any>
+export type DeleteMutationFn<
+  T extends object = Record<string, unknown>,
+  TKey extends string | number = string | number,
+  TUtils extends UtilsRecord = Record<string, Fn>,
+> = (params: DeleteMutationFnParams<T, TKey, TUtils>) => Promise<any>
 
 /**
  * Collection status values for lifecycle management
+ * @example
+ * // Check collection status
+ * if (collection.status === "loading") {
+ *   console.log("Collection is loading initial data")
+ * } else if (collection.status === "ready") {
+ *   console.log("Collection is ready for use")
+ * }
+ *
+ * @example
+ * // Status transitions
+ * // idle → loading → initialCommit → ready
+ * // Any status can transition to → error or cleaned-up
  */
 export type CollectionStatus =
   /** Collection is created but sync hasn't started yet (when startSync config is false) */
   | `idle`
   /** Sync has started but hasn't received the first commit yet */
   | `loading`
+  /** Collection is in the process of committing its first transaction */
+  | `initialCommit`
   /** Collection has received at least one commit and is ready for use */
   | `ready`
   /** An error occurred during sync initialization */
@@ -294,22 +326,132 @@ export interface CollectionConfig<
   compare?: (x: T, y: T) => number
   /**
    * Optional asynchronous handler function called before an insert operation
-   * @param params Object containing transaction and mutation information
+   * @param params Object containing transaction and collection information
    * @returns Promise resolving to any value
+   * @example
+   * // Basic insert handler
+   * onInsert: async ({ transaction, collection }) => {
+   *   const newItem = transaction.mutations[0].modified
+   *   await api.createTodo(newItem)
+   * }
+   *
+   * @example
+   * // Insert handler with multiple items
+   * onInsert: async ({ transaction, collection }) => {
+   *   const items = transaction.mutations.map(m => m.modified)
+   *   await api.createTodos(items)
+   * }
+   *
+   * @example
+   * // Insert handler with error handling
+   * onInsert: async ({ transaction, collection }) => {
+   *   try {
+   *     const newItem = transaction.mutations[0].modified
+   *     const result = await api.createTodo(newItem)
+   *     return result
+   *   } catch (error) {
+   *     console.error('Insert failed:', error)
+   *     throw error // This will cause the transaction to fail
+   *   }
+   * }
+   *
+   * @example
+   * // Insert handler with metadata
+   * onInsert: async ({ transaction, collection }) => {
+   *   const mutation = transaction.mutations[0]
+   *   await api.createTodo(mutation.modified, {
+   *     source: mutation.metadata?.source,
+   *     timestamp: mutation.createdAt
+   *   })
+   * }
    */
-  onInsert?: InsertMutationFn<T>
+  onInsert?: InsertMutationFn<T, TKey>
   /**
    * Optional asynchronous handler function called before an update operation
-   * @param params Object containing transaction and mutation information
+   * @param params Object containing transaction and collection information
    * @returns Promise resolving to any value
+   * @example
+   * // Basic update handler
+   * onUpdate: async ({ transaction, collection }) => {
+   *   const updatedItem = transaction.mutations[0].modified
+   *   await api.updateTodo(updatedItem.id, updatedItem)
+   * }
+   *
+   * @example
+   * // Update handler with partial updates
+   * onUpdate: async ({ transaction, collection }) => {
+   *   const mutation = transaction.mutations[0]
+   *   const changes = mutation.changes // Only the changed fields
+   *   await api.updateTodo(mutation.original.id, changes)
+   * }
+   *
+   * @example
+   * // Update handler with multiple items
+   * onUpdate: async ({ transaction, collection }) => {
+   *   const updates = transaction.mutations.map(m => ({
+   *     id: m.key,
+   *     changes: m.changes
+   *   }))
+   *   await api.updateTodos(updates)
+   * }
+   *
+   * @example
+   * // Update handler with optimistic rollback
+   * onUpdate: async ({ transaction, collection }) => {
+   *   const mutation = transaction.mutations[0]
+   *   try {
+   *     await api.updateTodo(mutation.original.id, mutation.changes)
+   *   } catch (error) {
+   *     // Transaction will automatically rollback optimistic changes
+   *     console.error('Update failed, rolling back:', error)
+   *     throw error
+   *   }
+   * }
    */
-  onUpdate?: UpdateMutationFn<T>
+  onUpdate?: UpdateMutationFn<T, TKey>
   /**
    * Optional asynchronous handler function called before a delete operation
-   * @param params Object containing transaction and mutation information
+   * @param params Object containing transaction and collection information
    * @returns Promise resolving to any value
+   * @example
+   * // Basic delete handler
+   * onDelete: async ({ transaction, collection }) => {
+   *   const deletedKey = transaction.mutations[0].key
+   *   await api.deleteTodo(deletedKey)
+   * }
+   *
+   * @example
+   * // Delete handler with multiple items
+   * onDelete: async ({ transaction, collection }) => {
+   *   const keysToDelete = transaction.mutations.map(m => m.key)
+   *   await api.deleteTodos(keysToDelete)
+   * }
+   *
+   * @example
+   * // Delete handler with confirmation
+   * onDelete: async ({ transaction, collection }) => {
+   *   const mutation = transaction.mutations[0]
+   *   const shouldDelete = await confirmDeletion(mutation.original)
+   *   if (!shouldDelete) {
+   *     throw new Error('Delete cancelled by user')
+   *   }
+   *   await api.deleteTodo(mutation.original.id)
+   * }
+   *
+   * @example
+   * // Delete handler with optimistic rollback
+   * onDelete: async ({ transaction, collection }) => {
+   *   const mutation = transaction.mutations[0]
+   *   try {
+   *     await api.deleteTodo(mutation.original.id)
+   *   } catch (error) {
+   *     // Transaction will automatically rollback optimistic changes
+   *     console.error('Delete failed, rolling back:', error)
+   *     throw error
+   *   }
+   * }
    */
-  onDelete?: DeleteMutationFn<T>
+  onDelete?: DeleteMutationFn<T, TKey>
 }
 
 export type ChangesPayload<T extends object = Record<string, unknown>> = Array<
@@ -351,6 +493,37 @@ export type KeyedNamespacedRow = [unknown, NamespacedRow]
  */
 export type NamespacedAndKeyedStream = IStreamBuilder<KeyedNamespacedRow>
 
+/**
+ * Function type for listening to collection changes
+ * @param changes - Array of change messages describing what happened
+ * @example
+ * // Basic change listener
+ * const listener: ChangeListener = (changes) => {
+ *   changes.forEach(change => {
+ *     console.log(`${change.type}: ${change.key}`, change.value)
+ *   })
+ * }
+ *
+ * collection.subscribeChanges(listener)
+ *
+ * @example
+ * // Handle different change types
+ * const listener: ChangeListener<Todo> = (changes) => {
+ *   for (const change of changes) {
+ *     switch (change.type) {
+ *       case 'insert':
+ *         addToUI(change.value)
+ *         break
+ *       case 'update':
+ *         updateInUI(change.key, change.value, change.previousValue)
+ *         break
+ *       case 'delete':
+ *         removeFromUI(change.key)
+ *         break
+ *     }
+ *   }
+ * }
+ */
 export type ChangeListener<
   T extends object = Record<string, unknown>,
   TKey extends string | number = string | number,