@tanstack/db 0.0.5 → 0.0.7

package/dist/esm/transactions.js.map

@@ -1 +1 @@
-{"version":3,"file":"transactions.js","sources":["../../src/transactions.ts"],"sourcesContent":["import { createDeferred } from \"./deferred\"\nimport type { Deferred } from \"./deferred\"\nimport type {\n  PendingMutation,\n  TransactionConfig,\n  TransactionState,\n} from \"./types\"\n\nfunction generateUUID() {\n  // Check if crypto.randomUUID is available (modern browsers and Node.js 15+)\n  if (\n    typeof crypto !== `undefined` &&\n    typeof crypto.randomUUID === `function`\n  ) {\n    return crypto.randomUUID()\n  }\n\n  // Fallback implementation for older environments\n  return `xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx`.replace(/[xy]/g, function (c) {\n    const r = (Math.random() * 16) | 0\n    const v = c === `x` ? r : (r & 0x3) | 0x8\n    return v.toString(16)\n  })\n}\n\nconst transactions: Array<Transaction> = []\nlet transactionStack: Array<Transaction> = []\n\nexport function createTransaction(config: TransactionConfig): Transaction {\n  if (typeof config.mutationFn === `undefined`) {\n    throw `mutationFn is required when creating a transaction`\n  }\n\n  let transactionId = config.id\n  if (!transactionId) {\n    transactionId = generateUUID()\n  }\n  const newTransaction = new Transaction({ ...config, id: transactionId })\n\n  transactions.push(newTransaction)\n\n  return newTransaction\n}\n\nexport function getActiveTransaction(): Transaction | undefined {\n  if (transactionStack.length > 0) {\n    return transactionStack.slice(-1)[0]\n  } else {\n    return undefined\n  }\n}\n\nfunction registerTransaction(tx: Transaction) {\n  transactionStack.push(tx)\n}\n\nfunction unregisterTransaction(tx: Transaction) {\n  transactionStack = transactionStack.filter((t) => t.id !== tx.id)\n}\n\nfunction removeFromPendingList(tx: Transaction) {\n  const index = transactions.findIndex((t) => t.id === tx.id)\n  if (index !== -1) {\n    transactions.splice(index, 1)\n  }\n}\n\nexport class Transaction {\n  public id: string\n  public state: TransactionState\n  public mutationFn\n  public mutations: Array<PendingMutation<any>>\n  public isPersisted: Deferred<Transaction>\n  public autoCommit: boolean\n  public createdAt: Date\n  public metadata: Record<string, unknown>\n  public error?: {\n    message: string\n    error: Error\n  }\n\n  constructor(config: TransactionConfig) {\n    this.id = config.id!\n    this.mutationFn = config.mutationFn\n    this.state = `pending`\n    this.mutations = []\n    this.isPersisted = createDeferred()\n    this.autoCommit = config.autoCommit ?? true\n    this.createdAt = new Date()\n    this.metadata = config.metadata ?? {}\n  }\n\n  setState(newState: TransactionState) {\n    this.state = newState\n\n    if (newState === `completed` || newState === `failed`) {\n      removeFromPendingList(this)\n    }\n  }\n\n  mutate(callback: () => void): Transaction {\n    if (this.state !== `pending`) {\n      throw `You can no longer call .mutate() as the transaction is no longer pending`\n    }\n\n    registerTransaction(this)\n    try {\n      callback()\n    } finally {\n      unregisterTransaction(this)\n    }\n\n    if (this.autoCommit) {\n      this.commit()\n    }\n\n    return this\n  }\n\n  applyMutations(mutations: Array<PendingMutation<any>>): void {\n    for (const newMutation of mutations) {\n      const existingIndex = this.mutations.findIndex(\n        (m) => m.key === newMutation.key\n      )\n\n      if (existingIndex >= 0) {\n        // Replace existing mutation\n        this.mutations[existingIndex] = newMutation\n      } else {\n        // Insert new mutation\n        this.mutations.push(newMutation)\n      }\n    }\n  }\n\n  rollback(config?: { isSecondaryRollback?: boolean }): Transaction {\n    const isSecondaryRollback = config?.isSecondaryRollback ?? false\n    if (this.state === `completed`) {\n      throw `You can no longer call .rollback() as the transaction is already completed`\n    }\n\n    this.setState(`failed`)\n\n    // See if there's any other transactions w/ mutations on the same ids\n    // and roll them back as well.\n    if (!isSecondaryRollback) {\n      const mutationIds = new Set()\n      this.mutations.forEach((m) => mutationIds.add(m.key))\n      for (const t of transactions) {\n        t.state === `pending` &&\n          t.mutations.some((m) => mutationIds.has(m.key)) &&\n          t.rollback({ isSecondaryRollback: true })\n      }\n    }\n\n    // Reject the promise\n    this.isPersisted.reject(this.error?.error)\n    this.touchCollection()\n\n    return this\n  }\n\n  // Tell collection that something has changed with the transaction\n  touchCollection(): void {\n    const hasCalled = new Set()\n    for (const mutation of this.mutations) {\n      if (!hasCalled.has(mutation.collection.id)) {\n        mutation.collection.transactions.setState((state) => state)\n        mutation.collection.commitPendingTransactions()\n        hasCalled.add(mutation.collection.id)\n      }\n    }\n  }\n\n  async commit(): Promise<Transaction> {\n    if (this.state !== `pending`) {\n      throw `You can no longer call .commit() as the transaction is no longer pending`\n    }\n\n    this.setState(`persisting`)\n\n    if (this.mutations.length === 0) {\n      this.setState(`completed`)\n    }\n\n    // Run mutationFn\n    try {\n      await this.mutationFn({ transaction: this })\n\n      this.setState(`completed`)\n      this.touchCollection()\n\n      this.isPersisted.resolve(this)\n    } catch (error) {\n      // Update transaction with error information\n      this.error = {\n        message: error instanceof Error ? error.message : String(error),\n        error: error instanceof Error ? error : new Error(String(error)),\n      }\n\n      // rollback the transaction\n      return this.rollback()\n    }\n\n    return this\n  }\n}\n"],"names":[],"mappings":"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"}
+{"version":3,"file":"transactions.js","sources":["../../src/transactions.ts"],"sourcesContent":["import { createDeferred } from \"./deferred\"\nimport type { Deferred } from \"./deferred\"\nimport type {\n  PendingMutation,\n  TransactionConfig,\n  TransactionState,\n  TransactionWithMutations,\n} from \"./types\"\n\nfunction generateUUID() {\n  // Check if crypto.randomUUID is available (modern browsers and Node.js 15+)\n  if (\n    typeof crypto !== `undefined` &&\n    typeof crypto.randomUUID === `function`\n  ) {\n    return crypto.randomUUID()\n  }\n\n  // Fallback implementation for older environments\n  return `xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx`.replace(/[xy]/g, function (c) {\n    const r = (Math.random() * 16) | 0\n    const v = c === `x` ? r : (r & 0x3) | 0x8\n    return v.toString(16)\n  })\n}\n\nconst transactions: Array<Transaction> = []\nlet transactionStack: Array<Transaction> = []\n\nexport function createTransaction(config: TransactionConfig): Transaction {\n  if (typeof config.mutationFn === `undefined`) {\n    throw `mutationFn is required when creating a transaction`\n  }\n\n  let transactionId = config.id\n  if (!transactionId) {\n    transactionId = generateUUID()\n  }\n  const newTransaction = new Transaction({ ...config, id: transactionId })\n\n  transactions.push(newTransaction)\n\n  return newTransaction\n}\n\nexport function getActiveTransaction(): Transaction | undefined {\n  if (transactionStack.length > 0) {\n    return transactionStack.slice(-1)[0]\n  } else {\n    return undefined\n  }\n}\n\nfunction registerTransaction(tx: Transaction) {\n  transactionStack.push(tx)\n}\n\nfunction unregisterTransaction(tx: Transaction) {\n  transactionStack = transactionStack.filter((t) => t.id !== tx.id)\n}\n\nfunction removeFromPendingList(tx: Transaction) {\n  const index = transactions.findIndex((t) => t.id === tx.id)\n  if (index !== -1) {\n    transactions.splice(index, 1)\n  }\n}\n\nexport class Transaction {\n  public id: string\n  public state: TransactionState\n  public mutationFn\n  public mutations: Array<PendingMutation<any>>\n  public isPersisted: Deferred<Transaction>\n  public autoCommit: boolean\n  public createdAt: Date\n  public metadata: Record<string, unknown>\n  public error?: {\n    message: string\n    error: Error\n  }\n\n  constructor(config: TransactionConfig) {\n    this.id = config.id!\n    this.mutationFn = config.mutationFn\n    this.state = `pending`\n    this.mutations = []\n    this.isPersisted = createDeferred()\n    this.autoCommit = config.autoCommit ?? true\n    this.createdAt = new Date()\n    this.metadata = config.metadata ?? {}\n  }\n\n  setState(newState: TransactionState) {\n    this.state = newState\n\n    if (newState === `completed` || newState === `failed`) {\n      removeFromPendingList(this)\n    }\n  }\n\n  mutate(callback: () => void): Transaction {\n    if (this.state !== `pending`) {\n      throw `You can no longer call .mutate() as the transaction is no longer pending`\n    }\n\n    registerTransaction(this)\n    try {\n      callback()\n    } finally {\n      unregisterTransaction(this)\n    }\n\n    if (this.autoCommit) {\n      this.commit()\n    }\n\n    return this\n  }\n\n  applyMutations(mutations: Array<PendingMutation<any>>): void {\n    for (const newMutation of mutations) {\n      const existingIndex = this.mutations.findIndex(\n        (m) => m.key === newMutation.key\n      )\n\n      if (existingIndex >= 0) {\n        // Replace existing mutation\n        this.mutations[existingIndex] = newMutation\n      } else {\n        // Insert new mutation\n        this.mutations.push(newMutation)\n      }\n    }\n  }\n\n  rollback(config?: { isSecondaryRollback?: boolean }): Transaction {\n    const isSecondaryRollback = config?.isSecondaryRollback ?? false\n    if (this.state === `completed`) {\n      throw `You can no longer call .rollback() as the transaction is already completed`\n    }\n\n    this.setState(`failed`)\n\n    // See if there's any other transactions w/ mutations on the same ids\n    // and roll them back as well.\n    if (!isSecondaryRollback) {\n      const mutationIds = new Set()\n      this.mutations.forEach((m) => mutationIds.add(m.key))\n      for (const t of transactions) {\n        t.state === `pending` &&\n          t.mutations.some((m) => mutationIds.has(m.key)) &&\n          t.rollback({ isSecondaryRollback: true })\n      }\n    }\n\n    // Reject the promise\n    this.isPersisted.reject(this.error?.error)\n    this.touchCollection()\n\n    return this\n  }\n\n  // Tell collection that something has changed with the transaction\n  touchCollection(): void {\n    const hasCalled = new Set()\n    for (const mutation of this.mutations) {\n      if (!hasCalled.has(mutation.collection.id)) {\n        mutation.collection.transactions.setState((state) => state)\n        mutation.collection.commitPendingTransactions()\n        hasCalled.add(mutation.collection.id)\n      }\n    }\n  }\n\n  async commit(): Promise<Transaction> {\n    if (this.state !== `pending`) {\n      throw `You can no longer call .commit() as the transaction is no longer pending`\n    }\n\n    this.setState(`persisting`)\n\n    if (this.mutations.length === 0) {\n      this.setState(`completed`)\n\n      return this\n    }\n\n    // Run mutationFn\n    try {\n      // At this point we know there's at least one mutation\n      // Use type assertion to tell TypeScript about this guarantee\n      const transactionWithMutations =\n        this as unknown as TransactionWithMutations\n      await this.mutationFn({ transaction: transactionWithMutations })\n\n      this.setState(`completed`)\n      this.touchCollection()\n\n      this.isPersisted.resolve(this)\n    } catch (error) {\n      // Update transaction with error information\n      this.error = {\n        message: error instanceof Error ? error.message : String(error),\n        error: error instanceof Error ? error : new Error(String(error)),\n      }\n\n      // rollback the transaction\n      return this.rollback()\n    }\n\n    return this\n  }\n}\n"],"names":[],"mappings":";AASA,SAAS,eAAe;AAEtB,MACE,OAAO,WAAW,eAClB,OAAO,OAAO,eAAe,YAC7B;AACA,WAAO,OAAO,WAAW;AAAA,EAAA;AAI3B,SAAO,uCAAuC,QAAQ,SAAS,SAAU,GAAG;AAC1E,UAAM,IAAK,KAAK,OAAO,IAAI,KAAM;AACjC,UAAM,IAAI,MAAM,MAAM,IAAK,IAAI,IAAO;AAC/B,WAAA,EAAE,SAAS,EAAE;AAAA,EAAA,CACrB;AACH;AAEA,MAAM,eAAmC,CAAC;AAC1C,IAAI,mBAAuC,CAAC;AAErC,SAAS,kBAAkB,QAAwC;AACpE,MAAA,OAAO,OAAO,eAAe,aAAa;AACtC,UAAA;AAAA,EAAA;AAGR,MAAI,gBAAgB,OAAO;AAC3B,MAAI,CAAC,eAAe;AAClB,oBAAgB,aAAa;AAAA,EAAA;AAEzB,QAAA,iBAAiB,IAAI,YAAY,EAAE,GAAG,QAAQ,IAAI,eAAe;AAEvE,eAAa,KAAK,cAAc;AAEzB,SAAA;AACT;AAEO,SAAS,uBAAgD;AAC1D,MAAA,iBAAiB,SAAS,GAAG;AAC/B,WAAO,iBAAiB,MAAM,EAAE,EAAE,CAAC;AAAA,EAAA,OAC9B;AACE,WAAA;AAAA,EAAA;AAEX;AAEA,SAAS,oBAAoB,IAAiB;AAC5C,mBAAiB,KAAK,EAAE;AAC1B;AAEA,SAAS,sBAAsB,IAAiB;AAC9C,qBAAmB,iBAAiB,OAAO,CAAC,MAAM,EAAE,OAAO,GAAG,EAAE;AAClE;AAEA,SAAS,sBAAsB,IAAiB;AACxC,QAAA,QAAQ,aAAa,UAAU,CAAC,MAAM,EAAE,OAAO,GAAG,EAAE;AAC1D,MAAI,UAAU,IAAI;AACH,iBAAA,OAAO,OAAO,CAAC;AAAA,EAAA;AAEhC;AAEO,MAAM,YAAY;AAAA,EAcvB,YAAY,QAA2B;AACrC,SAAK,KAAK,OAAO;AACjB,SAAK,aAAa,OAAO;AACzB,SAAK,QAAQ;AACb,SAAK,YAAY,CAAC;AAClB,SAAK,cAAc,eAAe;AAC7B,SAAA,aAAa,OAAO,cAAc;AAClC,SAAA,gCAAgB,KAAK;AACrB,SAAA,WAAW,OAAO,YAAY,CAAC;AAAA,EAAA;AAAA,EAGtC,SAAS,UAA4B;AACnC,SAAK,QAAQ;AAET,QAAA,aAAa,eAAe,aAAa,UAAU;AACrD,4BAAsB,IAAI;AAAA,IAAA;AAAA,EAC5B;AAAA,EAGF,OAAO,UAAmC;AACpC,QAAA,KAAK,UAAU,WAAW;AACtB,YAAA;AAAA,IAAA;AAGR,wBAAoB,IAAI;AACpB,QAAA;AACO,eAAA;AAAA,IAAA,UACT;AACA,4BAAsB,IAAI;AAAA,IAAA;AAG5B,QAAI,KAAK,YAAY;AACnB,WAAK,OAAO;AAAA,IAAA;AAGP,WAAA;AAAA,EAAA;AAAA,EAGT,eAAe,WAA8C;AAC3D,eAAW,eAAe,WAAW;AAC7B,YAAA,gBAAgB,KAAK,UAAU;AAAA,QACnC,CAAC,MAAM,EAAE,QAAQ,YAAY;AAAA,MAC/B;AAEA,UAAI,iBAAiB,GAAG;AAEjB,aAAA,UAAU,aAAa,IAAI;AAAA,MAAA,OAC3B;AAEA,aAAA,UAAU,KAAK,WAAW;AAAA,MAAA;AAAA,IACjC;AAAA,EACF;AAAA,EAGF,SAAS,QAAyD;;AAC1D,UAAA,uBAAsB,iCAAQ,wBAAuB;AACvD,QAAA,KAAK,UAAU,aAAa;AACxB,YAAA;AAAA,IAAA;AAGR,SAAK,SAAS,QAAQ;AAItB,QAAI,CAAC,qBAAqB;AAClB,YAAA,kCAAkB,IAAI;AACvB,WAAA,UAAU,QAAQ,CAAC,MAAM,YAAY,IAAI,EAAE,GAAG,CAAC;AACpD,iBAAW,KAAK,cAAc;AAC5B,UAAE,UAAU,aACV,EAAE,UAAU,KAAK,CAAC,MAAM,YAAY,IAAI,EAAE,GAAG,CAAC,KAC9C,EAAE,SAAS,EAAE,qBAAqB,MAAM;AAAA,MAAA;AAAA,IAC5C;AAIF,SAAK,YAAY,QAAO,UAAK,UAAL,mBAAY,KAAK;AACzC,SAAK,gBAAgB;AAEd,WAAA;AAAA,EAAA;AAAA;AAAA,EAIT,kBAAwB;AAChB,UAAA,gCAAgB,IAAI;AACf,eAAA,YAAY,KAAK,WAAW;AACrC,UAAI,CAAC,UAAU,IAAI,SAAS,WAAW,EAAE,GAAG;AAC1C,iBAAS,WAAW,aAAa,SAAS,CAAC,UAAU,KAAK;AAC1D,iBAAS,WAAW,0BAA0B;AACpC,kBAAA,IAAI,SAAS,WAAW,EAAE;AAAA,MAAA;AAAA,IACtC;AAAA,EACF;AAAA,EAGF,MAAM,SAA+B;AAC/B,QAAA,KAAK,UAAU,WAAW;AACtB,YAAA;AAAA,IAAA;AAGR,SAAK,SAAS,YAAY;AAEtB,QAAA,KAAK,UAAU,WAAW,GAAG;AAC/B,WAAK,SAAS,WAAW;AAElB,aAAA;AAAA,IAAA;AAIL,QAAA;AAGF,YAAM,2BACJ;AACF,YAAM,KAAK,WAAW,EAAE,aAAa,0BAA0B;AAE/D,WAAK,SAAS,WAAW;AACzB,WAAK,gBAAgB;AAEhB,WAAA,YAAY,QAAQ,IAAI;AAAA,aACtB,OAAO;AAEd,WAAK,QAAQ;AAAA,QACX,SAAS,iBAAiB,QAAQ,MAAM,UAAU,OAAO,KAAK;AAAA,QAC9D,OAAO,iBAAiB,QAAQ,QAAQ,IAAI,MAAM,OAAO,KAAK,CAAC;AAAA,MACjE;AAGA,aAAO,KAAK,SAAS;AAAA,IAAA;AAGhB,WAAA;AAAA,EAAA;AAEX;"}

package/dist/esm/types.d.ts

@@ -3,6 +3,14 @@ import { Collection } from './collection.js';
 import { StandardSchemaV1 } from '@standard-schema/spec';
 import { Transaction } from './transactions.js';
 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
@@ -27,6 +35,13 @@ export type MutationFnParams = {
     transaction: Transaction;
 };
 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;
@@ -100,6 +115,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<ChangeMessage<T>>;
 /**

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@tanstack/db",
   "description": "A reactive client store for building super fast apps on sync",
-  "version": "0.0.5",
+  "version": "0.0.7",
   "dependencies": {
     "@electric-sql/d2ts": "^0.1.6",
     "@standard-schema/spec": "^1.0.0",

package/src/collection.ts

@@ -1,26 +1,30 @@
 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,
   CollectionConfig,
+  Fn,
   InsertConfig,
   OperationConfig,
   OptimisticChangeMessage,
   PendingMutation,
   StandardSchema,
-  Transaction,
+  Transaction as TransactionType,
+  UtilsRecord,
 } from "./types"
 
 // Store collections in memory using Tanstack store
-export const collectionsStore = new Store(new Map<string, Collection<any>>())
+export const collectionsStore = new Store(
+  new Map<string, CollectionImpl<any>>()
+)
 
 // Map to track loading collections
 
 const loadingCollections = new Map<
   string,
-  Promise<Collection<Record<string, unknown>>>
+  Promise<CollectionImpl<Record<string, unknown>>>
 >()
 
 interface PendingSyncedTransaction<T extends object = Record<string, unknown>> {
@@ -28,17 +32,40 @@ interface PendingSyncedTransaction<T extends object = Record<string, unknown>> {
   operations: Array<OptimisticChangeMessage<T>>
 }
 
+/**
+ * Enhanced Collection interface that includes both data type T and utilities TUtils
+ * @template T - The type of items in the collection
+ * @template TUtils - The utilities record type
+ */
+export interface Collection<
+  T extends object = Record<string, unknown>,
+  TUtils extends UtilsRecord = {},
+> extends CollectionImpl<T> {
+  readonly utils: TUtils
+}
+
 /**
  * Creates a new Collection instance with the given configuration
  *
  * @template T - The type of items in the collection
- * @param config - Configuration for the collection, including id and sync
- * @returns A new Collection instance
+ * @template TUtils - The utilities record type
+ * @param options - Collection options with optional utilities
+ * @returns A new Collection with utilities exposed both at top level and under .utils
  */
-export function createCollection<T extends object = Record<string, unknown>>(
-  config: CollectionConfig<T>
-): Collection<T> {
-  return new Collection<T>(config)
+export function createCollection<
+  T extends object = Record<string, unknown>,
+  TUtils extends UtilsRecord = {},
+>(options: CollectionConfig<T> & { utils?: TUtils }): Collection<T, TUtils> {
+  const collection = new CollectionImpl<T>(options)
+
+  // Copy utils to both top level and .utils namespace
+  if (options.utils) {
+    collection.utils = { ...options.utils }
+  } else {
+    collection.utils = {} as TUtils
+  }
+
+  return collection as Collection<T, TUtils>
 }
 
 /**
@@ -69,7 +96,7 @@ export function createCollection<T extends object = Record<string, unknown>>(
  */
 export function preloadCollection<T extends object = Record<string, unknown>>(
   config: CollectionConfig<T>
-): Promise<Collection<T>> {
+): Promise<CollectionImpl<T>> {
   if (!config.id) {
     throw new Error(`The id property is required for preloadCollection`)
   }
@@ -86,7 +113,7 @@ export function preloadCollection<T extends object = Record<string, unknown>>(
 
   // If the collection is in the process of loading, return its promise
   if (loadingCollections.has(config.id)) {
-    return loadingCollections.get(config.id)! as Promise<Collection<T>>
+    return loadingCollections.get(config.id)! as Promise<CollectionImpl<T>>
   }
 
   // Create a new collection instance if it doesn't exist
@@ -98,7 +125,7 @@ export function preloadCollection<T extends object = Record<string, unknown>>(
       }
       next.set(
         config.id,
-        new Collection<T>({
+        createCollection<T>({
           id: config.id,
           getId: config.getId,
           sync: config.sync,
@@ -113,9 +140,9 @@ export function preloadCollection<T extends object = Record<string, unknown>>(
 
   // Create a promise that will resolve after the first commit
   let resolveFirstCommit: () => void
-  const firstCommitPromise = new Promise<Collection<T>>((resolve) => {
+  const firstCommitPromise = new Promise<CollectionImpl<T>>((resolve) => {
     resolveFirstCommit = () => {
-      resolve(collection)
+      resolve(collection as CollectionImpl<T>)
     }
   })
 
@@ -133,7 +160,7 @@ export function preloadCollection<T extends object = Record<string, unknown>>(
   // Store the loading promise
   loadingCollections.set(
     config.id,
-    firstCommitPromise as Promise<Collection<Record<string, unknown>>>
+    firstCommitPromise as Promise<CollectionImpl<Record<string, unknown>>>
   )
 
   return firstCommitPromise
@@ -168,8 +195,13 @@ export class SchemaValidationError extends Error {
   }
 }
 
-export class Collection<T extends object = Record<string, unknown>> {
-  public transactions: Store<SortedMap<string, Transaction>>
+export class CollectionImpl<T extends object = Record<string, unknown>> {
+  /**
+   * Utilities namespace
+   * This is populated by createCollection
+   */
+  public utils: Record<string, Fn> = {}
+  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 +250,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 +636,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 +652,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 +698,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()
+
+      // Add the transaction to the collection's transactions store
+      this.transactions.setState((sortedMap) => {
+        sortedMap.set(directOpTransaction.id, directOpTransaction)
+        return sortedMap
+      })
 
-    return transaction
+      return directOpTransaction
+    }
   }
 
   /**
@@ -715,13 +774,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 +791,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 +891,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 +941,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 +980,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/index.ts

@@ -9,4 +9,4 @@ export * from "./proxy"
 export * from "./query/index.js"
 
 // Re-export some stuff explicitly to ensure the type & value is exported
-export { Collection } from "./collection"
+export type { Collection } from "./collection"

package/src/query/compiled-query.ts

@@ -1,7 +1,8 @@
 import { D2, MessageType, MultiSet, output } from "@electric-sql/d2ts"
 import { Effect, batch } from "@tanstack/store"
-import { Collection } from "../collection.js"
+import { createCollection } from "../collection.js"
 import { compileQueryPipeline } from "./pipeline-compiler.js"
+import type { Collection } from "../collection.js"
 import type { ChangeMessage, SyncConfig } from "../types.js"
 import type {
   IStreamBuilder,
@@ -97,9 +98,9 @@ export class CompiledQuery<TResults extends object = Record<string, unknown>> {
 
     this.graph = graph
     this.inputs = inputs
-    this.resultCollection = new Collection<TResults>({
+    this.resultCollection = createCollection<TResults>({
       id: crypto.randomUUID(), // TODO: remove when we don't require any more
-      getId: (val) => {
+      getId: (val: unknown) => {
         return (val as any)._key
       },
       sync: {

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