@tanstack/db 0.0.5 → 0.0.7

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

@@ -5,6 +5,16 @@ import type { Transaction } from "./transactions"
 
 export type TransactionState = `pending` | `persisting` | `completed` | `failed`
 
+/**
+ * Represents a utility function that can be attached to a collection
+ */
+export type Fn = (...args: Array<any>) => any
+
+/**
+ * A record of utility functions that can be attached to a collection
+ */
+export type UtilsRecord = Record<string, Fn>
+
 /**
  * Represents a pending mutation within a transaction
  * Contains information about the original and modified data, as well as metadata
@@ -32,6 +42,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 +150,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<