@tanstack/db 0.0.5 → 0.0.6

package/src/collection.ts

@@ -1,6 +1,6 @@
 import { Derived, Store, batch } from "@tanstack/store"
 import { withArrayChangeTracking, withChangeTracking } from "./proxy"
-import { getActiveTransaction } from "./transactions"
+import { Transaction, getActiveTransaction } from "./transactions"
 import { SortedMap } from "./SortedMap"
 import type {
   ChangeMessage,
@@ -10,7 +10,7 @@ import type {
   OptimisticChangeMessage,
   PendingMutation,
   StandardSchema,
-  Transaction,
+  Transaction as TransactionType,
 } from "./types"
 
 // Store collections in memory using Tanstack store
@@ -169,7 +169,7 @@ export class SchemaValidationError extends Error {
 }
 
 export class Collection<T extends object = Record<string, unknown>> {
-  public transactions: Store<SortedMap<string, Transaction>>
+  public transactions: Store<SortedMap<string, TransactionType>>
   public optimisticOperations: Derived<Array<OptimisticChangeMessage<T>>>
   public derivedState: Derived<Map<string, T>>
   public derivedArray: Derived<Array<T>>
@@ -218,7 +218,7 @@ export class Collection<T extends object = Record<string, unknown>> {
     }
 
     this.transactions = new Store(
-      new SortedMap<string, Transaction>(
+      new SortedMap<string, TransactionType>(
         (a, b) => a.createdAt.getTime() - b.createdAt.getTime()
       )
     )
@@ -604,7 +604,7 @@ export class Collection<T extends object = Record<string, unknown>> {
    * 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 Transaction object representing the insert operation(s)
+   * @returns A TransactionType object representing the insert operation(s)
    * @throws {SchemaValidationError} If the data fails schema validation
    * @example
    * // Insert a single item
@@ -620,9 +620,13 @@ export class Collection<T extends object = Record<string, unknown>> {
    * insert({ text: "Buy groceries" }, { key: "grocery-task" })
    */
   insert = (data: T | Array<T>, config?: InsertConfig) => {
-    const transaction = getActiveTransaction()
-    if (typeof transaction === `undefined`) {
-      throw `no transaction found when calling collection.insert`
+    const ambientTransaction = getActiveTransaction()
+
+    // If no ambient transaction exists, check for an onInsert handler early
+    if (!ambientTransaction && !this.config.onInsert) {
+      throw new Error(
+        `Collection.insert called directly (not within an explicit transaction) but no 'onInsert' handler is configured.`
+      )
     }
 
     const items = Array.isArray(data) ? data : [data]
@@ -662,14 +666,37 @@ export class Collection<T extends object = Record<string, unknown>> {
       mutations.push(mutation)
     })
 
-    transaction.applyMutations(mutations)
+    // If an ambient transaction exists, use it
+    if (ambientTransaction) {
+      ambientTransaction.applyMutations(mutations)
 
-    this.transactions.setState((sortedMap) => {
-      sortedMap.set(transaction.id, transaction)
-      return sortedMap
-    })
+      this.transactions.setState((sortedMap) => {
+        sortedMap.set(ambientTransaction.id, ambientTransaction)
+        return sortedMap
+      })
+
+      return ambientTransaction
+    } else {
+      // Create a new transaction with a mutation function that calls the onInsert handler
+      const directOpTransaction = new Transaction({
+        mutationFn: async (params) => {
+          // Call the onInsert handler with the transaction
+          return this.config.onInsert!(params)
+        },
+      })
+
+      // Apply mutations to the new transaction
+      directOpTransaction.applyMutations(mutations)
+      directOpTransaction.commit()
 
-    return transaction
+      // Add the transaction to the collection's transactions store
+      this.transactions.setState((sortedMap) => {
+        sortedMap.set(directOpTransaction.id, directOpTransaction)
+        return sortedMap
+      })
+
+      return directOpTransaction
+    }
   }
 
   /**
@@ -715,13 +742,13 @@ export class Collection<T extends object = Record<string, unknown>> {
     id: unknown,
     configOrCallback: ((draft: TItem) => void) | OperationConfig,
     maybeCallback?: (draft: TItem) => void
-  ): Transaction
+  ): TransactionType
 
   update<TItem extends object = T>(
     ids: Array<unknown>,
     configOrCallback: ((draft: Array<TItem>) => void) | OperationConfig,
     maybeCallback?: (draft: Array<TItem>) => void
-  ): Transaction
+  ): TransactionType
 
   update<TItem extends object = T>(
     ids: unknown | Array<unknown>,
@@ -732,9 +759,13 @@ export class Collection<T extends object = Record<string, unknown>> {
       throw new Error(`The first argument to update is missing`)
     }
 
-    const transaction = getActiveTransaction()
-    if (typeof transaction === `undefined`) {
-      throw `no transaction found when calling collection.update`
+    const ambientTransaction = getActiveTransaction()
+
+    // If no ambient transaction exists, check for an onUpdate handler early
+    if (!ambientTransaction && !this.config.onUpdate) {
+      throw new Error(
+        `Collection.update called directly (not within an explicit transaction) but no 'onUpdate' handler is configured.`
+      )
     }
 
     const isArray = Array.isArray(ids)
@@ -828,21 +859,46 @@ export class Collection<T extends object = Record<string, unknown>> {
       throw new Error(`No changes were made to any of the objects`)
     }
 
-    transaction.applyMutations(mutations)
+    // If an ambient transaction exists, use it
+    if (ambientTransaction) {
+      ambientTransaction.applyMutations(mutations)
+
+      this.transactions.setState((sortedMap) => {
+        sortedMap.set(ambientTransaction.id, ambientTransaction)
+        return sortedMap
+      })
+
+      return ambientTransaction
+    }
+
+    // No need to check for onUpdate handler here as we've already checked at the beginning
 
+    // Create a new transaction with a mutation function that calls the onUpdate handler
+    const directOpTransaction = new Transaction({
+      mutationFn: async (transaction) => {
+        // Call the onUpdate handler with the transaction
+        return this.config.onUpdate!(transaction)
+      },
+    })
+
+    // Apply mutations to the new transaction
+    directOpTransaction.applyMutations(mutations)
+    directOpTransaction.commit()
+
+    // Add the transaction to the collection's transactions store
     this.transactions.setState((sortedMap) => {
-      sortedMap.set(transaction.id, transaction)
+      sortedMap.set(directOpTransaction.id, directOpTransaction)
       return sortedMap
     })
 
-    return transaction
+    return directOpTransaction
   }
 
   /**
    * Deletes one or more items from the collection
    * @param ids - Single ID or array of IDs to delete
    * @param config - Optional configuration including metadata
-   * @returns A Transaction object representing the delete operation(s)
+   * @returns A TransactionType object representing the delete operation(s)
    * @example
    * // Delete a single item
    * delete("todo-1")
@@ -853,10 +909,17 @@ export class Collection<T extends object = Record<string, unknown>> {
    * // Delete with metadata
    * delete("todo-1", { metadata: { reason: "completed" } })
    */
-  delete = (ids: Array<string> | string, config?: OperationConfig) => {
-    const transaction = getActiveTransaction()
-    if (typeof transaction === `undefined`) {
-      throw `no transaction found when calling collection.delete`
+  delete = (
+    ids: Array<string> | string,
+    config?: OperationConfig
+  ): TransactionType => {
+    const ambientTransaction = getActiveTransaction()
+
+    // If no ambient transaction exists, check for an onDelete handler early
+    if (!ambientTransaction && !this.config.onDelete) {
+      throw new Error(
+        `Collection.delete called directly (not within an explicit transaction) but no 'onDelete' handler is configured.`
+      )
     }
 
     const idsArray = (Array.isArray(ids) ? ids : [ids]).map((id) =>
@@ -885,14 +948,38 @@ export class Collection<T extends object = Record<string, unknown>> {
       mutations.push(mutation)
     }
 
-    transaction.applyMutations(mutations)
+    // If an ambient transaction exists, use it
+    if (ambientTransaction) {
+      ambientTransaction.applyMutations(mutations)
+
+      this.transactions.setState((sortedMap) => {
+        sortedMap.set(ambientTransaction.id, ambientTransaction)
+        return sortedMap
+      })
+
+      return ambientTransaction
+    }
+
+    // Create a new transaction with a mutation function that calls the onDelete handler
+    const directOpTransaction = new Transaction({
+      autoCommit: true,
+      mutationFn: async (transaction) => {
+        // Call the onDelete handler with the transaction
+        return this.config.onDelete!(transaction)
+      },
+    })
+
+    // Apply mutations to the new transaction
+    directOpTransaction.applyMutations(mutations)
+    directOpTransaction.commit()
 
+    // Add the transaction to the collection's transactions store
     this.transactions.setState((sortedMap) => {
-      sortedMap.set(transaction.id, transaction)
+      sortedMap.set(directOpTransaction.id, directOpTransaction)
       return sortedMap
     })
 
-    return transaction
+    return directOpTransaction
   }
 
   /**

package/src/query/evaluators.ts

@@ -6,9 +6,36 @@ import type {
   ConditionOperand,
   LogicalOperator,
   SimpleCondition,
+  Where,
+  WhereCallback,
 } from "./schema.js"
 import type { NamespacedRow } from "../types.js"
 
+/**
+ * Evaluates a Where clause (which is always an array of conditions and/or callbacks) against a nested row structure
+ */
+export function evaluateWhereOnNamespacedRow(
+  namespacedRow: NamespacedRow,
+  where: Where,
+  mainTableAlias?: string,
+  joinedTableAlias?: string
+): boolean {
+  // Where is always an array of conditions and/or callbacks
+  // Evaluate all items and combine with AND logic
+  return where.every((item) => {
+    if (typeof item === `function`) {
+      return (item as WhereCallback)(namespacedRow)
+    } else {
+      return evaluateConditionOnNamespacedRow(
+        namespacedRow,
+        item as Condition,
+        mainTableAlias,
+        joinedTableAlias
+      )
+    }
+  })
+}
+
 /**
  * Evaluates a condition against a nested row structure
  */

package/src/query/pipeline-compiler.ts

@@ -1,5 +1,5 @@
 import { filter, map } from "@electric-sql/d2ts"
-import { evaluateConditionOnNamespacedRow } from "./evaluators.js"
+import { evaluateWhereOnNamespacedRow } from "./evaluators.js"
 import { processJoinClause } from "./joins.js"
 import { processGroupBy } from "./group-by.js"
 import { processOrderBy } from "./order-by.js"
@@ -95,7 +95,7 @@ export function compileQueryPipeline<T extends IStreamBuilder<unknown>>(
   if (query.where) {
     pipeline = pipeline.pipe(
       filter(([_key, row]) => {
-        const result = evaluateConditionOnNamespacedRow(
+        const result = evaluateWhereOnNamespacedRow(
           row,
           query.where!,
           mainTableAlias
@@ -117,7 +117,7 @@ export function compileQueryPipeline<T extends IStreamBuilder<unknown>>(
       filter(([_key, row]) => {
         // For HAVING, we're working with the flattened row that contains both
         // the group by keys and the aggregate results directly
-        const result = evaluateConditionOnNamespacedRow(
+        const result = evaluateWhereOnNamespacedRow(
           row,
           query.having!,
           mainTableAlias

package/src/query/query-builder.ts

@@ -10,6 +10,7 @@ import type {
   OrderBy,
   Query,
   Select,
+  WhereCallback,
   WithQuery,
 } from "./schema.js"
 import type {
@@ -197,8 +198,9 @@ export class BaseQueryBuilder<TContext extends Context<Schema>> {
   /**
    * Specify what columns to select.
    * Overwrites any previous select clause.
+   * Also supports callback functions that receive the row context and return selected data.
    *
-   * @param selects The columns to select
+   * @param selects The columns to select (can include callbacks)
    * @returns A new QueryBuilder with the select clause set
    */
   select<TSelects extends Array<Select<TContext>>>(
@@ -296,17 +298,23 @@ export class BaseQueryBuilder<TContext extends Context<Schema>> {
    */
   where(condition: Condition<TContext>): QueryBuilder<TContext>
 
+  /**
+   * Add a where clause with a callback function.
+   */
+  where(callback: WhereCallback<TContext>): QueryBuilder<TContext>
+
   /**
    * Add a where clause to filter the results.
    * Can be called multiple times to add AND conditions.
+   * Also supports callback functions that receive the row context.
    *
-   * @param leftOrCondition The left operand or complete condition
+   * @param leftOrConditionOrCallback The left operand, complete condition, or callback function
    * @param operator Optional comparison operator
    * @param right Optional right operand
    * @returns A new QueryBuilder with the where clause added
    */
   where(
-    leftOrCondition: any,
+    leftOrConditionOrCallback: any,
     operator?: any,
     right?: any
   ): QueryBuilder<TContext> {
@@ -317,22 +325,23 @@ export class BaseQueryBuilder<TContext extends Context<Schema>> {
 
     let condition: any
 
-    // Determine if this is a complete condition or individual parts
-    if (operator !== undefined && right !== undefined) {
+    // Determine if this is a callback, complete condition, or individual parts
+    if (typeof leftOrConditionOrCallback === `function`) {
+      // It's a callback function
+      condition = leftOrConditionOrCallback
+    } else if (operator !== undefined && right !== undefined) {
       // Create a condition from parts
-      condition = [leftOrCondition, operator, right]
+      condition = [leftOrConditionOrCallback, operator, right]
     } else {
       // Use the provided condition directly
-      condition = leftOrCondition
+      condition = leftOrConditionOrCallback
     }
 
+    // Where is always an array, so initialize or append
     if (!newBuilder.query.where) {
-      newBuilder.query.where = condition
+      newBuilder.query.where = [condition]
     } else {
-      // Create a composite condition with AND
-      // Use any to bypass type checking issues
-      const andArray: any = [newBuilder.query.where, `and`, condition]
-      newBuilder.query.where = andArray
+      newBuilder.query.where = [...newBuilder.query.where, condition]
     }
 
     return newBuilder as unknown as QueryBuilder<TContext>
@@ -354,17 +363,24 @@ export class BaseQueryBuilder<TContext extends Context<Schema>> {
    */
   having(condition: Condition<TContext>): QueryBuilder<TContext>
 
+  /**
+   * Add a having clause with a callback function.
+   * For filtering results after they have been grouped.
+   */
+  having(callback: WhereCallback<TContext>): QueryBuilder<TContext>
+
   /**
    * Add a having clause to filter the grouped results.
    * Can be called multiple times to add AND conditions.
+   * Also supports callback functions that receive the row context.
    *
-   * @param leftOrCondition The left operand or complete condition
+   * @param leftOrConditionOrCallback The left operand, complete condition, or callback function
    * @param operator Optional comparison operator
    * @param right Optional right operand
    * @returns A new QueryBuilder with the having clause added
    */
   having(
-    leftOrCondition: any,
+    leftOrConditionOrCallback: any,
     operator?: any,
     right?: any
   ): QueryBuilder<TContext> {
@@ -374,22 +390,23 @@ export class BaseQueryBuilder<TContext extends Context<Schema>> {
 
     let condition: any
 
-    // Determine if this is a complete condition or individual parts
-    if (operator !== undefined && right !== undefined) {
+    // Determine if this is a callback, complete condition, or individual parts
+    if (typeof leftOrConditionOrCallback === `function`) {
+      // It's a callback function
+      condition = leftOrConditionOrCallback
+    } else if (operator !== undefined && right !== undefined) {
       // Create a condition from parts
-      condition = [leftOrCondition, operator, right]
+      condition = [leftOrConditionOrCallback, operator, right]
     } else {
       // Use the provided condition directly
-      condition = leftOrCondition
+      condition = leftOrConditionOrCallback
     }
 
+    // Having is always an array, so initialize or append
     if (!newBuilder.query.having) {
-      newBuilder.query.having = condition
+      newBuilder.query.having = [condition]
     } else {
-      // Create a composite condition with AND
-      // Use any to bypass type checking issues
-      const andArray: any = [newBuilder.query.having, `and`, condition]
-      newBuilder.query.having = andArray
+      newBuilder.query.having = [...newBuilder.query.having, condition]
     }
 
     return newBuilder as QueryBuilder<TContext>

package/src/query/schema.ts

@@ -191,6 +191,11 @@ export type Select<TContext extends Context = Context> =
         | AggregateFunctionCall<TContext>
     }
   | WildcardReferenceString<TContext>
+  | SelectCallback<TContext>
+
+export type SelectCallback<TContext extends Context = Context> = (
+  context: TContext extends { schema: infer S } ? S : any
+) => any
 
 export type As<TContext extends Context = Context> = string
 
@@ -199,14 +204,21 @@ export type From<TContext extends Context = Context> = InputReference<{
   schema: TContext[`baseSchema`]
 }>
 
-export type Where<TContext extends Context = Context> = Condition<TContext>
+export type WhereCallback<TContext extends Context = Context> = (
+  context: TContext extends { schema: infer S } ? S : any
+) => boolean
+
+export type Where<TContext extends Context = Context> = Array<
+  Condition<TContext> | WhereCallback<TContext>
+>
+
+// Having is the same implementation as a where clause, its just run after the group by
+export type Having<TContext extends Context = Context> = Where<TContext>
 
 export type GroupBy<TContext extends Context = Context> =
   | PropertyReference<TContext>
   | Array<PropertyReference<TContext>>
 
-export type Having<TContext extends Context = Context> = Condition<TContext>
-
 export type Limit<TContext extends Context = Context> = number
 
 export type Offset<TContext extends Context = Context> = number
@@ -220,9 +232,9 @@ export interface BaseQuery<TContext extends Context = Context> {
   as?: As<TContext>
   from: From<TContext>
   join?: Array<JoinClause<TContext>>
-  where?: Condition<TContext>
+  where?: Where<TContext>
   groupBy?: GroupBy<TContext>
-  having?: Condition<TContext>
+  having?: Having<TContext>
   orderBy?: OrderBy<TContext>
   limit?: Limit<TContext>
   offset?: Offset<TContext>

package/src/query/select.ts

@@ -3,7 +3,7 @@ import {
   evaluateOperandOnNamespacedRow,
   extractValueFromNamespacedRow,
 } from "./extractors"
-import type { ConditionOperand, Query } from "./schema"
+import type { ConditionOperand, Query, SelectCallback } from "./schema"
 import type { KeyedStream, NamespacedAndKeyedStream } from "../types"
 
 export function processSelect(
@@ -31,6 +31,29 @@ export function processSelect(
       }
 
       for (const item of query.select) {
+        // Handle callback functions
+        if (typeof item === `function`) {
+          const callback = item as SelectCallback
+          const callbackResult = callback(namespacedRow)
+
+          // If the callback returns an object, merge its properties into the result
+          if (
+            callbackResult &&
+            typeof callbackResult === `object` &&
+            !Array.isArray(callbackResult)
+          ) {
+            Object.assign(result, callbackResult)
+          } else {
+            // If the callback returns a primitive value, we can't merge it
+            // This would need a specific key, but since we don't have one, we'll skip it
+            // In practice, select callbacks should return objects with keys
+            console.warn(
+              `SelectCallback returned a non-object value. SelectCallbacks should return objects with key-value pairs.`
+            )
+          }
+          continue
+        }
+
         if (typeof item === `string`) {
           // Handle wildcard select - all columns from all tables
           if ((item as string) === `@*`) {

package/src/transactions.ts

@@ -4,6 +4,7 @@ import type {
   PendingMutation,
   TransactionConfig,
   TransactionState,
+  TransactionWithMutations,
 } from "./types"
 
 function generateUUID() {
@@ -181,11 +182,17 @@ export class Transaction {
 
     if (this.mutations.length === 0) {
       this.setState(`completed`)
+
+      return this
     }
 
     // Run mutationFn
     try {
-      await this.mutationFn({ transaction: this })
+      // At this point we know there's at least one mutation
+      // Use type assertion to tell TypeScript about this guarantee
+      const transactionWithMutations =
+        this as unknown as TransactionWithMutations
+      await this.mutationFn({ transaction: transactionWithMutations })
 
       this.setState(`completed`)
       this.touchCollection()

package/src/types.ts

@@ -32,6 +32,16 @@ export type MutationFnParams = {
 
 export type MutationFn = (params: MutationFnParams) => Promise<any>
 
+/**
+ * Utility type for a Transaction with at least one mutation
+ * This is used internally by the Transaction.commit method
+ */
+export type TransactionWithMutations<
+  T extends object = Record<string, unknown>,
+> = Transaction & {
+  mutations: [PendingMutation<T>, ...Array<PendingMutation<T>>]
+}
+
 export interface TransactionConfig {
   /** Unique identifier for the transaction */
   id?: string
@@ -130,6 +140,24 @@ export interface CollectionConfig<T extends object = Record<string, unknown>> {
    * getId: (item) => item.uuid
    */
   getId: (item: T) => any
+  /**
+   * Optional asynchronous handler function called before an insert operation
+   * @param params Object containing transaction and mutation information
+   * @returns Promise resolving to any value
+   */
+  onInsert?: MutationFn
+  /**
+   * Optional asynchronous handler function called before an update operation
+   * @param params Object containing transaction and mutation information
+   * @returns Promise resolving to any value
+   */
+  onUpdate?: MutationFn
+  /**
+   * Optional asynchronous handler function called before a delete operation
+   * @param params Object containing transaction and mutation information
+   * @returns Promise resolving to any value
+   */
+  onDelete?: MutationFn
 }
 
 export type ChangesPayload<T extends object = Record<string, unknown>> = Array<