@tanstack/db 0.0.16 → 0.0.18

package/src/collection.ts

@@ -53,12 +53,52 @@ export interface Collection<
  * @returns A new Collection with utilities exposed both at top level and under .utils
  *
  * @example
- * // Using explicit type
- * const todos = createCollection<Todo>({
+ * // Pattern 1: With operation handlers (direct collection calls)
+ * const todos = createCollection({
+ *   id: "todos",
  *   getKey: (todo) => todo.id,
+ *   schema,
+ *   onInsert: async ({ transaction, collection }) => {
+ *     // Send to API
+ *     await api.createTodo(transaction.mutations[0].modified)
+ *   },
+ *   onUpdate: async ({ transaction, collection }) => {
+ *     await api.updateTodo(transaction.mutations[0].modified)
+ *   },
+ *   onDelete: async ({ transaction, collection }) => {
+ *     await api.deleteTodo(transaction.mutations[0].key)
+ *   },
  *   sync: { sync: () => {} }
  * })
  *
+ * // Direct usage (handlers manage transactions)
+ * const tx = todos.insert({ id: "1", text: "Buy milk", completed: false })
+ * await tx.isPersisted.promise
+ *
+ * @example
+ * // Pattern 2: Manual transaction management
+ * const todos = createCollection({
+ *   getKey: (todo) => todo.id,
+ *   schema: todoSchema,
+ *   sync: { sync: () => {} }
+ * })
+ *
+ * // Explicit transaction usage
+ * const tx = createTransaction({
+ *   mutationFn: async ({ transaction }) => {
+ *     // Handle all mutations in transaction
+ *     await api.saveChanges(transaction.mutations)
+ *   }
+ * })
+ *
+ * tx.mutate(() => {
+ *   todos.insert({ id: "1", text: "Buy milk" })
+ *   todos.update("2", draft => { draft.completed = true })
+ * })
+ *
+ * await tx.isPersisted.promise
+ *
+ * @example
  * // Using schema for type inference (preferred as it also gives you client side validation)
  * const todoSchema = z.object({
  *   id: z.string(),
@@ -72,7 +112,7 @@ export interface Collection<
  *   sync: { sync: () => {} }
  * })
  *
- * // Note: You must provide either an explicit type or a schema, but not both
+ * // Note: You must provide either an explicit type or a schema, but not both.
  */
 export function createCollection<
   TExplicit = unknown,
@@ -138,6 +178,7 @@ export class SchemaValidationError extends Error {
 export class CollectionImpl<
   T extends object = Record<string, unknown>,
   TKey extends string | number = string | number,
+  TUtils extends UtilsRecord = {},
 > {
   public config: CollectionConfig<T, TKey, any>
 
@@ -187,6 +228,11 @@ export class CollectionImpl<
    * Register a callback to be executed on the next commit
    * Useful for preloading collections
    * @param callback Function to call after the next commit
+   * @example
+   * collection.onFirstCommit(() => {
+   *   console.log('Collection has received first data')
+   *   // Safe to access collection.state now
+   * })
    */
   public onFirstCommit(callback: () => void): void {
     this.onFirstCommitCallbacks.push(callback)
@@ -237,7 +283,8 @@ export class CollectionImpl<
       Array<CollectionStatus>
     > = {
       idle: [`loading`, `error`, `cleaned-up`],
-      loading: [`ready`, `error`, `cleaned-up`],
+      loading: [`initialCommit`, `error`, `cleaned-up`],
+      initialCommit: [`ready`, `error`, `cleaned-up`],
       ready: [`cleaned-up`, `error`],
       error: [`cleaned-up`, `idle`],
       "cleaned-up": [`loading`, `error`],
@@ -382,14 +429,18 @@ export class CollectionImpl<
 
           pendingTransaction.committed = true
 
-          // Update status to ready
-          // We do this before committing as we want the events from the changes to
-          // be from a "ready" state.
+          // Update status to initialCommit when transitioning from loading
+          // This indicates we're in the process of committing the first transaction
           if (this._status === `loading`) {
-            this.setStatus(`ready`)
+            this.setStatus(`initialCommit`)
           }
 
           this.commitPendingTransactions()
+
+          // Transition from initialCommit to ready after the first commit is complete
+          if (this._status === `initialCommit`) {
+            this.setStatus(`ready`)
+          }
         },
       })
 
@@ -1238,21 +1289,38 @@ export class CollectionImpl<
   /**
    * Inserts one or more items into the collection
    * @param items - Single item or array of items to insert
-   * @param config - Optional configuration including metadata and custom keys
-   * @returns A TransactionType object representing the insert operation(s)
+   * @param config - Optional configuration including metadata
+   * @returns A Transaction object representing the insert operation(s)
    * @throws {SchemaValidationError} If the data fails schema validation
    * @example
-   * // Insert a single item
-   * insert({ text: "Buy groceries", completed: false })
+   * // Insert a single todo (requires onInsert handler)
+   * const tx = collection.insert({ id: "1", text: "Buy milk", completed: false })
+   * await tx.isPersisted.promise
    *
-   * // Insert multiple items
-   * insert([
-   *   { text: "Buy groceries", completed: false },
-   *   { text: "Walk dog", completed: false }
+   * @example
+   * // Insert multiple todos at once
+   * const tx = collection.insert([
+   *   { id: "1", text: "Buy milk", completed: false },
+   *   { id: "2", text: "Walk dog", completed: true }
    * ])
+   * await tx.isPersisted.promise
+   *
+   * @example
+   * // Insert with metadata
+   * const tx = collection.insert({ id: "1", text: "Buy groceries" },
+   *   { metadata: { source: "mobile-app" } }
+   * )
+   * await tx.isPersisted.promise
    *
-   * // Insert with custom key
-   * insert({ text: "Buy groceries" }, { key: "grocery-task" })
+   * @example
+   * // Handle errors
+   * try {
+   *   const tx = collection.insert({ id: "1", text: "New item" })
+   *   await tx.isPersisted.promise
+   *   console.log('Insert successful')
+   * } catch (error) {
+   *   console.log('Insert failed:', error)
+   * }
    */
   insert = (data: T | Array<T>, config?: InsertConfig) => {
     this.validateCollectionUsable(`insert`)
@@ -1311,8 +1379,11 @@ export class CollectionImpl<
       // Create a new transaction with a mutation function that calls the onInsert handler
       const directOpTransaction = createTransaction<T>({
         mutationFn: async (params) => {
-          // Call the onInsert handler with the transaction
-          return this.config.onInsert!(params)
+          // Call the onInsert handler with the transaction and collection
+          return this.config.onInsert!({
+            ...params,
+            collection: this as unknown as Collection<T, TKey, TUtils>,
+          })
         },
       })
 
@@ -1330,43 +1401,44 @@ export class CollectionImpl<
 
   /**
    * Updates one or more items in the collection using a callback function
-   * @param items - Single item/key or array of items/keys to update
+   * @param keys - Single key or array of keys to update
    * @param configOrCallback - Either update configuration or update callback
    * @param maybeCallback - Update callback if config was provided
    * @returns A Transaction object representing the update operation(s)
    * @throws {SchemaValidationError} If the updated data fails schema validation
    * @example
-   * // Update a single item
-   * update(todo, (draft) => { draft.completed = true })
-   *
-   * // Update multiple items
-   * update([todo1, todo2], (drafts) => {
-   *   drafts.forEach(draft => { draft.completed = true })
+   * // Update single item by key
+   * const tx = collection.update("todo-1", (draft) => {
+   *   draft.completed = true
    * })
+   * await tx.isPersisted.promise
    *
-   * // Update with metadata
-   * update(todo, { metadata: { reason: "user update" } }, (draft) => { draft.text = "Updated text" })
-   */
-
-  /**
-   * Updates one or more items in the collection using a callback function
-   * @param ids - Single ID or array of IDs to update
-   * @param configOrCallback - Either update configuration or update callback
-   * @param maybeCallback - Update callback if config was provided
-   * @returns A Transaction object representing the update operation(s)
-   * @throws {SchemaValidationError} If the updated data fails schema validation
    * @example
-   * // Update a single item
-   * update("todo-1", (draft) => { draft.completed = true })
-   *
    * // Update multiple items
-   * update(["todo-1", "todo-2"], (drafts) => {
+   * const tx = collection.update(["todo-1", "todo-2"], (drafts) => {
    *   drafts.forEach(draft => { draft.completed = true })
    * })
+   * await tx.isPersisted.promise
    *
+   * @example
    * // Update with metadata
-   * update("todo-1", { metadata: { reason: "user update" } }, (draft) => { draft.text = "Updated text" })
+   * const tx = collection.update("todo-1",
+   *   { metadata: { reason: "user update" } },
+   *   (draft) => { draft.text = "Updated text" }
+   * )
+   * await tx.isPersisted.promise
+   *
+   * @example
+   * // Handle errors
+   * try {
+   *   const tx = collection.update("item-1", draft => { draft.value = "new" })
+   *   await tx.isPersisted.promise
+   *   console.log('Update successful')
+   * } catch (error) {
+   *   console.log('Update failed:', error)
+   * }
    */
+
   // Overload 1: Update multiple items with a callback
   update<TItem extends object = T>(
     key: Array<TKey | unknown>,
@@ -1533,8 +1605,11 @@ export class CollectionImpl<
     // Create a new transaction with a mutation function that calls the onUpdate handler
     const directOpTransaction = createTransaction<T>({
       mutationFn: async (params) => {
-        // Call the onUpdate handler with the transaction
-        return this.config.onUpdate!(params)
+        // Call the onUpdate handler with the transaction and collection
+        return this.config.onUpdate!({
+          ...params,
+          collection: this as unknown as Collection<T, TKey, TUtils>,
+        })
       },
     })
 
@@ -1552,18 +1627,33 @@ export class CollectionImpl<
 
   /**
    * Deletes one or more items from the collection
-   * @param ids - Single ID or array of IDs to delete
+   * @param keys - Single key or array of keys to delete
    * @param config - Optional configuration including metadata
-   * @returns A TransactionType object representing the delete operation(s)
+   * @returns A Transaction object representing the delete operation(s)
    * @example
    * // Delete a single item
-   * delete("todo-1")
+   * const tx = collection.delete("todo-1")
+   * await tx.isPersisted.promise
    *
+   * @example
    * // Delete multiple items
-   * delete(["todo-1", "todo-2"])
+   * const tx = collection.delete(["todo-1", "todo-2"])
+   * await tx.isPersisted.promise
    *
+   * @example
    * // Delete with metadata
-   * delete("todo-1", { metadata: { reason: "completed" } })
+   * const tx = collection.delete("todo-1", { metadata: { reason: "completed" } })
+   * await tx.isPersisted.promise
+   *
+   * @example
+   * // Handle errors
+   * try {
+   *   const tx = collection.delete("item-1")
+   *   await tx.isPersisted.promise
+   *   console.log('Delete successful')
+   * } catch (error) {
+   *   console.log('Delete failed:', error)
+   * }
    */
   delete = (
     keys: Array<TKey> | TKey,
@@ -1629,8 +1719,11 @@ export class CollectionImpl<
     const directOpTransaction = createTransaction<T>({
       autoCommit: true,
       mutationFn: async (params) => {
-        // Call the onDelete handler with the transaction
-        return this.config.onDelete!(params)
+        // Call the onDelete handler with the transaction and collection
+        return this.config.onDelete!({
+          ...params,
+          collection: this as unknown as Collection<T, TKey, TUtils>,
+        })
       },
     })
 
@@ -1646,8 +1739,19 @@ export class CollectionImpl<
 
   /**
    * Gets the current state of the collection as a Map
+   * @returns Map containing all items in the collection, with keys as identifiers
+   * @example
+   * const itemsMap = collection.state
+   * console.log(`Collection has ${itemsMap.size} items`)
+   *
+   * for (const [key, item] of itemsMap) {
+   *   console.log(`${key}: ${item.title}`)
+   * }
    *
-   * @returns A Map containing all items in the collection, with keys as identifiers
+   * // Check if specific item exists
+   * if (itemsMap.has("todo-1")) {
+   *   console.log("Todo 1 exists:", itemsMap.get("todo-1"))
+   * }
    */
   get state() {
     const result = new Map<TKey, T>()
@@ -1720,8 +1824,24 @@ export class CollectionImpl<
 
   /**
    * Subscribe to changes in the collection
-   * @param callback - A function that will be called with the changes in the collection
-   * @returns A function that can be called to unsubscribe from the changes
+   * @param callback - Function called when items change
+   * @param options.includeInitialState - If true, immediately calls callback with current data
+   * @returns Unsubscribe function - Call this to stop listening for changes
+   * @example
+   * // Basic subscription
+   * const unsubscribe = collection.subscribeChanges((changes) => {
+   *   changes.forEach(change => {
+   *     console.log(`${change.type}: ${change.key}`, change.value)
+   *   })
+   * })
+   *
+   * // Later: unsubscribe()
+   *
+   * @example
+   * // Include current state immediately
+   * const unsubscribe = collection.subscribeChanges((changes) => {
+   *   updateUI(changes)
+   * }, { includeInitialState: true })
    */
   public subscribeChanges(
     callback: (changes: Array<ChangeMessage<T>>) => void,

package/src/proxy.ts

@@ -505,7 +505,6 @@ export function createChangeProxy<
                   if (typeof callback === `function`) {
                     // Replace the original callback with our wrapped version
                     const wrappedCallback = function (
-                      // eslint-disable-next-line
                       this: unknown,
                       // eslint-disable-next-line
                       value: unknown,

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

@@ -162,7 +162,8 @@ export function liveQueryCollectionOptions<
 
   const allCollectionsReady = () => {
     return Object.values(collections).every(
-      (collection) => collection.status === `ready`
+      (collection) =>
+        collection.status === `ready` || collection.status === `initialCommit`
     )
   }
 

package/src/transactions.ts

@@ -14,6 +14,58 @@ let transactionStack: Array<Transaction<any>> = []
 
 let sequenceNumber = 0
 
+/**
+ * Creates a new transaction for grouping multiple collection operations
+ * @param config - Transaction configuration with mutation function
+ * @returns A new Transaction instance
+ * @example
+ * // Basic transaction usage
+ * const tx = createTransaction({
+ *   mutationFn: async ({ transaction }) => {
+ *     // Send all mutations to API
+ *     await api.saveChanges(transaction.mutations)
+ *   }
+ * })
+ *
+ * tx.mutate(() => {
+ *   collection.insert({ id: "1", text: "Buy milk" })
+ *   collection.update("2", draft => { draft.completed = true })
+ * })
+ *
+ * await tx.isPersisted.promise
+ *
+ * @example
+ * // Handle transaction errors
+ * try {
+ *   const tx = createTransaction({
+ *     mutationFn: async () => { throw new Error("API failed") }
+ *   })
+ *
+ *   tx.mutate(() => {
+ *     collection.insert({ id: "1", text: "New item" })
+ *   })
+ *
+ *   await tx.isPersisted.promise
+ * } catch (error) {
+ *   console.log('Transaction failed:', error)
+ * }
+ *
+ * @example
+ * // Manual commit control
+ * const tx = createTransaction({
+ *   autoCommit: false,
+ *   mutationFn: async () => {
+ *     // API call
+ *   }
+ * })
+ *
+ * tx.mutate(() => {
+ *   collection.insert({ id: "1", text: "Item" })
+ * })
+ *
+ * // Commit later
+ * await tx.commit()
+ */
 export function createTransaction<
   TData extends object = Record<string, unknown>,
 >(config: TransactionConfig<TData>): Transaction<TData> {
@@ -22,6 +74,17 @@ export function createTransaction<
   return newTransaction
 }
 
+/**
+ * Gets the currently active ambient transaction, if any
+ * Used internally by collection operations to join existing transactions
+ * @returns The active transaction or undefined if none is active
+ * @example
+ * // Check if operations will join an ambient transaction
+ * const ambientTx = getActiveTransaction()
+ * if (ambientTx) {
+ *   console.log('Operations will join transaction:', ambientTx.id)
+ * }
+ */
 export function getActiveTransaction(): Transaction | undefined {
   if (transactionStack.length > 0) {
     return transactionStack.slice(-1)[0]
@@ -86,6 +149,45 @@ class Transaction<
     }
   }
 
+  /**
+   * Execute collection operations within this transaction
+   * @param callback - Function containing collection operations to group together
+   * @returns This transaction for chaining
+   * @example
+   * // Group multiple operations
+   * const tx = createTransaction({ mutationFn: async () => {
+   *   // Send to API
+   * }})
+   *
+   * tx.mutate(() => {
+   *   collection.insert({ id: "1", text: "Buy milk" })
+   *   collection.update("2", draft => { draft.completed = true })
+   *   collection.delete("3")
+   * })
+   *
+   * await tx.isPersisted.promise
+   *
+   * @example
+   * // Handle mutate errors
+   * try {
+   *   tx.mutate(() => {
+   *     collection.insert({ id: "invalid" }) // This might throw
+   *   })
+   * } catch (error) {
+   *   console.log('Mutation failed:', error)
+   * }
+   *
+   * @example
+   * // Manual commit control
+   * const tx = createTransaction({ autoCommit: false, mutationFn: async () => {} })
+   *
+   * tx.mutate(() => {
+   *   collection.insert({ id: "1", text: "Item" })
+   * })
+   *
+   * // Commit later when ready
+   * await tx.commit()
+   */
   mutate(callback: () => void): Transaction<T> {
     if (this.state !== `pending`) {
       throw `You can no longer call .mutate() as the transaction is no longer pending`
@@ -121,6 +223,44 @@ class Transaction<
     }
   }
 
+  /**
+   * Rollback the transaction and any conflicting transactions
+   * @param config - Configuration for rollback behavior
+   * @returns This transaction for chaining
+   * @example
+   * // Manual rollback
+   * const tx = createTransaction({ mutationFn: async () => {
+   *   // Send to API
+   * }})
+   *
+   * tx.mutate(() => {
+   *   collection.insert({ id: "1", text: "Buy milk" })
+   * })
+   *
+   * // Rollback if needed
+   * if (shouldCancel) {
+   *   tx.rollback()
+   * }
+   *
+   * @example
+   * // Handle rollback cascade (automatic)
+   * const tx1 = createTransaction({ mutationFn: async () => {} })
+   * const tx2 = createTransaction({ mutationFn: async () => {} })
+   *
+   * tx1.mutate(() => collection.update("1", draft => { draft.value = "A" }))
+   * tx2.mutate(() => collection.update("1", draft => { draft.value = "B" })) // Same item
+   *
+   * tx1.rollback() // This will also rollback tx2 due to conflict
+   *
+   * @example
+   * // Handle rollback in error scenarios
+   * try {
+   *   await tx.isPersisted.promise
+   * } catch (error) {
+   *   console.log('Transaction was rolled back:', error)
+   *   // Transaction automatically rolled back on mutation function failure
+   * }
+   */
   rollback(config?: { isSecondaryRollback?: boolean }): Transaction<T> {
     const isSecondaryRollback = config?.isSecondaryRollback ?? false
     if (this.state === `completed`) {
@@ -165,6 +305,45 @@ class Transaction<
     }
   }
 
+  /**
+   * Commit the transaction and execute the mutation function
+   * @returns Promise that resolves to this transaction when complete
+   * @example
+   * // Manual commit (when autoCommit is false)
+   * const tx = createTransaction({
+   *   autoCommit: false,
+   *   mutationFn: async ({ transaction }) => {
+   *     await api.saveChanges(transaction.mutations)
+   *   }
+   * })
+   *
+   * tx.mutate(() => {
+   *   collection.insert({ id: "1", text: "Buy milk" })
+   * })
+   *
+   * await tx.commit() // Manually commit
+   *
+   * @example
+   * // Handle commit errors
+   * try {
+   *   const tx = createTransaction({
+   *     mutationFn: async () => { throw new Error("API failed") }
+   *   })
+   *
+   *   tx.mutate(() => {
+   *     collection.insert({ id: "1", text: "Item" })
+   *   })
+   *
+   *   await tx.commit()
+   * } catch (error) {
+   *   console.log('Commit failed, transaction rolled back:', error)
+   * }
+   *
+   * @example
+   * // Check transaction state after commit
+   * await tx.commit()
+   * console.log(tx.state) // "completed" or "failed"
+   */
   async commit(): Promise<Transaction<T>> {
     if (this.state !== `pending`) {
       throw `You can no longer call .commit() as the transaction is no longer pending`