@tanstack/db 0.0.14 → 0.0.15

package/dist/cjs/query/ir.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"ir.cjs","sources":["../../../src/query/ir.ts"],"sourcesContent":["/*\nThis is the intermediate representation of the query.\n*/\n\nimport type { CollectionImpl } from \"../collection\"\nimport type { NamespacedRow } from \"../types\"\n\nexport interface QueryIR {\n  from: From\n  select?: Select\n  join?: Join\n  where?: Array<Where>\n  groupBy?: GroupBy\n  having?: Array<Having>\n  orderBy?: OrderBy\n  limit?: Limit\n  offset?: Offset\n\n  // Functional variants\n  fnSelect?: (row: NamespacedRow) => any\n  fnWhere?: Array<(row: NamespacedRow) => any>\n  fnHaving?: Array<(row: NamespacedRow) => any>\n}\n\nexport type From = CollectionRef | QueryRef\n\nexport type Select = {\n  [alias: string]: BasicExpression | Aggregate\n}\n\nexport type Join = Array<JoinClause>\n\nexport interface JoinClause {\n  from: CollectionRef | QueryRef\n  type: `left` | `right` | `inner` | `outer` | `full` | `cross`\n  left: BasicExpression\n  right: BasicExpression\n}\n\nexport type Where = BasicExpression<boolean>\n\nexport type GroupBy = Array<BasicExpression>\n\nexport type Having = Where\n\nexport type OrderBy = Array<OrderByClause>\n\nexport type OrderByClause = {\n  expression: BasicExpression\n  direction: OrderByDirection\n}\n\nexport type OrderByDirection = `asc` | `desc`\n\nexport type Limit = number\n\nexport type Offset = number\n\n/* Expressions */\n\nabstract class BaseExpression<T = any> {\n  public abstract type: string\n  /** @internal - Type brand for TypeScript inference */\n  declare readonly __returnType: T\n}\n\nexport class CollectionRef extends BaseExpression {\n  public type = `collectionRef` as const\n  constructor(\n    public collection: CollectionImpl,\n    public alias: string\n  ) {\n    super()\n  }\n}\n\nexport class QueryRef extends BaseExpression {\n  public type = `queryRef` as const\n  constructor(\n    public query: QueryIR,\n    public alias: string\n  ) {\n    super()\n  }\n}\n\nexport class Ref<T = any> extends BaseExpression<T> {\n  public type = `ref` as const\n  constructor(\n    public path: Array<string> // path to the property in the collection, with the alias as the first element\n  ) {\n    super()\n  }\n}\n\nexport class Value<T = any> extends BaseExpression<T> {\n  public type = `val` as const\n  constructor(\n    public value: T // any js value\n  ) {\n    super()\n  }\n}\n\nexport class Func<T = any> extends BaseExpression<T> {\n  public type = `func` as const\n  constructor(\n    public name: string, // such as eq, gt, lt, upper, lower, etc.\n    public args: Array<BasicExpression>\n  ) {\n    super()\n  }\n}\n\n// This is the basic expression type that is used in the majority of expression\n// builder callbacks (select, where, groupBy, having, orderBy, etc.)\n// it doesn't include aggregate functions as those are only used in the select clause\nexport type BasicExpression<T = any> = Ref<T> | Value<T> | Func<T>\n\nexport class Aggregate<T = any> extends BaseExpression<T> {\n  public type = `agg` as const\n  constructor(\n    public name: string, // such as count, avg, sum, min, max, etc.\n    public args: Array<BasicExpression>\n  ) {\n    super()\n  }\n}\n"],"names":[],"mappings":";;AA4DA,MAAe,eAAwB;AAIvC;AAEO,MAAM,sBAAsB,eAAe;AAAA,EAEhD,YACS,YACA,OACP;AACM,UAAA;AAHC,SAAA,aAAA;AACA,SAAA,QAAA;AAHT,SAAO,OAAO;AAAA,EAAA;AAOhB;AAEO,MAAM,iBAAiB,eAAe;AAAA,EAE3C,YACS,OACA,OACP;AACM,UAAA;AAHC,SAAA,QAAA;AACA,SAAA,QAAA;AAHT,SAAO,OAAO;AAAA,EAAA;AAOhB;AAEO,MAAM,YAAqB,eAAkB;AAAA,EAElD,YACS,MACP;AACM,UAAA;AAFC,SAAA,OAAA;AAFT,SAAO,OAAO;AAAA,EAAA;AAMhB;AAEO,MAAM,cAAuB,eAAkB;AAAA,EAEpD,YACS,OACP;AACM,UAAA;AAFC,SAAA,QAAA;AAFT,SAAO,OAAO;AAAA,EAAA;AAMhB;AAEO,MAAM,aAAsB,eAAkB;AAAA,EAEnD,YACS,MACA,MACP;AACM,UAAA;AAHC,SAAA,OAAA;AACA,SAAA,OAAA;AAHT,SAAO,OAAO;AAAA,EAAA;AAOhB;AAOO,MAAM,kBAA2B,eAAkB;AAAA,EAExD,YACS,MACA,MACP;AACM,UAAA;AAHC,SAAA,OAAA;AACA,SAAA,OAAA;AAHT,SAAO,OAAO;AAAA,EAAA;AAOhB;;;;;;;"}

package/dist/cjs/query/ir.d.cts

@@ -0,0 +1,81 @@
+import { CollectionImpl } from '../collection.cjs';
+import { NamespacedRow } from '../types.cjs';
+export interface QueryIR {
+    from: From;
+    select?: Select;
+    join?: Join;
+    where?: Array<Where>;
+    groupBy?: GroupBy;
+    having?: Array<Having>;
+    orderBy?: OrderBy;
+    limit?: Limit;
+    offset?: Offset;
+    fnSelect?: (row: NamespacedRow) => any;
+    fnWhere?: Array<(row: NamespacedRow) => any>;
+    fnHaving?: Array<(row: NamespacedRow) => any>;
+}
+export type From = CollectionRef | QueryRef;
+export type Select = {
+    [alias: string]: BasicExpression | Aggregate;
+};
+export type Join = Array<JoinClause>;
+export interface JoinClause {
+    from: CollectionRef | QueryRef;
+    type: `left` | `right` | `inner` | `outer` | `full` | `cross`;
+    left: BasicExpression;
+    right: BasicExpression;
+}
+export type Where = BasicExpression<boolean>;
+export type GroupBy = Array<BasicExpression>;
+export type Having = Where;
+export type OrderBy = Array<OrderByClause>;
+export type OrderByClause = {
+    expression: BasicExpression;
+    direction: OrderByDirection;
+};
+export type OrderByDirection = `asc` | `desc`;
+export type Limit = number;
+export type Offset = number;
+declare abstract class BaseExpression<T = any> {
+    abstract type: string;
+    /** @internal - Type brand for TypeScript inference */
+    readonly __returnType: T;
+}
+export declare class CollectionRef extends BaseExpression {
+    collection: CollectionImpl;
+    alias: string;
+    type: "collectionRef";
+    constructor(collection: CollectionImpl, alias: string);
+}
+export declare class QueryRef extends BaseExpression {
+    query: QueryIR;
+    alias: string;
+    type: "queryRef";
+    constructor(query: QueryIR, alias: string);
+}
+export declare class Ref<T = any> extends BaseExpression<T> {
+    path: Array<string>;
+    type: "ref";
+    constructor(path: Array<string>);
+}
+export declare class Value<T = any> extends BaseExpression<T> {
+    value: T;
+    type: "val";
+    constructor(value: T);
+}
+export declare class Func<T = any> extends BaseExpression<T> {
+    name: string;
+    args: Array<BasicExpression>;
+    type: "func";
+    constructor(name: string, // such as eq, gt, lt, upper, lower, etc.
+    args: Array<BasicExpression>);
+}
+export type BasicExpression<T = any> = Ref<T> | Value<T> | Func<T>;
+export declare class Aggregate<T = any> extends BaseExpression<T> {
+    name: string;
+    args: Array<BasicExpression>;
+    type: "agg";
+    constructor(name: string, // such as count, avg, sum, min, max, etc.
+    args: Array<BasicExpression>);
+}
+export {};

package/dist/cjs/query/live-query-collection.cjs

@@ -0,0 +1,224 @@
+"use strict";
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const d2mini = require("@electric-sql/d2mini");
+const collection = require("../collection.cjs");
+const index$1 = require("./compiler/index.cjs");
+const index = require("./builder/index.cjs");
+let liveQueryCollectionCounter = 0;
+function liveQueryCollectionOptions(config) {
+  const id = config.id || `live-query-${++liveQueryCollectionCounter}`;
+  const query = index.buildQuery(config.query);
+  const resultKeys = /* @__PURE__ */ new WeakMap();
+  const orderByIndices = /* @__PURE__ */ new WeakMap();
+  const compare = query.orderBy && query.orderBy.length > 0 ? (val1, val2) => {
+    const index1 = orderByIndices.get(val1);
+    const index2 = orderByIndices.get(val2);
+    if (index1 && index2) {
+      if (index1 < index2) {
+        return -1;
+      } else if (index1 > index2) {
+        return 1;
+      } else {
+        return 0;
+      }
+    }
+    return 0;
+  } : void 0;
+  const collections = extractCollectionsFromQuery(query);
+  const allCollectionsReady = () => {
+    return Object.values(collections).every(
+      (collection2) => collection2.status === `ready`
+    );
+  };
+  let graphCache;
+  let inputsCache;
+  let pipelineCache;
+  const compileBasePipeline = () => {
+    graphCache = new d2mini.D2();
+    inputsCache = Object.fromEntries(
+      Object.entries(collections).map(([key]) => [
+        key,
+        graphCache.newInput()
+      ])
+    );
+    pipelineCache = index$1.compileQuery(
+      query,
+      inputsCache
+    );
+  };
+  const maybeCompileBasePipeline = () => {
+    if (!graphCache || !inputsCache || !pipelineCache) {
+      compileBasePipeline();
+    }
+    return {
+      graph: graphCache,
+      inputs: inputsCache,
+      pipeline: pipelineCache
+    };
+  };
+  compileBasePipeline();
+  const sync = {
+    rowUpdateMode: `full`,
+    sync: ({ begin, write, commit, collection: theCollection }) => {
+      const { graph, inputs, pipeline } = maybeCompileBasePipeline();
+      let messagesCount = 0;
+      pipeline.pipe(
+        d2mini.output((data) => {
+          const messages = data.getInner();
+          messagesCount += messages.length;
+          begin();
+          messages.reduce((acc, [[key, tupleData], multiplicity]) => {
+            const [value, orderByIndex] = tupleData;
+            const changes = acc.get(key) || {
+              deletes: 0,
+              inserts: 0,
+              value,
+              orderByIndex
+            };
+            if (multiplicity < 0) {
+              changes.deletes += Math.abs(multiplicity);
+            } else if (multiplicity > 0) {
+              changes.inserts += multiplicity;
+              changes.value = value;
+              changes.orderByIndex = orderByIndex;
+            }
+            acc.set(key, changes);
+            return acc;
+          }, /* @__PURE__ */ new Map()).forEach((changes, rawKey) => {
+            const { deletes, inserts, value, orderByIndex } = changes;
+            resultKeys.set(value, rawKey);
+            if (orderByIndex !== void 0) {
+              orderByIndices.set(value, orderByIndex);
+            }
+            if (inserts && deletes === 0) {
+              write({
+                value,
+                type: `insert`
+              });
+            } else if (
+              // Insert & update(s) (updates are a delete & insert)
+              inserts > deletes || // Just update(s) but the item is already in the collection (so
+              // was inserted previously).
+              inserts === deletes && theCollection.has(rawKey)
+            ) {
+              write({
+                value,
+                type: `update`
+              });
+            } else if (deletes > 0) {
+              write({
+                value,
+                type: `delete`
+              });
+            } else {
+              throw new Error(
+                `This should never happen ${JSON.stringify(changes)}`
+              );
+            }
+          });
+          commit();
+        })
+      );
+      graph.finalize();
+      const maybeRunGraph = () => {
+        if (allCollectionsReady()) {
+          graph.run();
+          if (messagesCount === 0) {
+            begin();
+            commit();
+          }
+        }
+      };
+      const unsubscribeCallbacks = /* @__PURE__ */ new Set();
+      Object.entries(collections).forEach(([collectionId, collection2]) => {
+        const input = inputs[collectionId];
+        const unsubscribe = collection2.subscribeChanges(
+          (changes) => {
+            sendChangesToInput(input, changes, collection2.config.getKey);
+            maybeRunGraph();
+          },
+          { includeInitialState: true }
+        );
+        unsubscribeCallbacks.add(unsubscribe);
+      });
+      maybeRunGraph();
+      return () => {
+        unsubscribeCallbacks.forEach((unsubscribe) => unsubscribe());
+      };
+    }
+  };
+  return {
+    id,
+    getKey: config.getKey || ((item) => resultKeys.get(item)),
+    sync,
+    compare,
+    gcTime: config.gcTime || 5e3,
+    // 5 seconds by default for live queries
+    schema: config.schema,
+    onInsert: config.onInsert,
+    onUpdate: config.onUpdate,
+    onDelete: config.onDelete,
+    startSync: config.startSync
+  };
+}
+function createLiveQueryCollection(configOrQuery) {
+  if (typeof configOrQuery === `function`) {
+    const config = {
+      query: configOrQuery
+    };
+    const options = liveQueryCollectionOptions(config);
+    return bridgeToCreateCollection(options);
+  } else {
+    const config = configOrQuery;
+    const options = liveQueryCollectionOptions(config);
+    return bridgeToCreateCollection({
+      ...options,
+      utils: config.utils
+    });
+  }
+}
+function bridgeToCreateCollection(options) {
+  return collection.createCollection(options);
+}
+function sendChangesToInput(input, changes, getKey) {
+  const multiSetArray = [];
+  for (const change of changes) {
+    const key = getKey(change.value);
+    if (change.type === `insert`) {
+      multiSetArray.push([[key, change.value], 1]);
+    } else if (change.type === `update`) {
+      multiSetArray.push([[key, change.previousValue], -1]);
+      multiSetArray.push([[key, change.value], 1]);
+    } else {
+      multiSetArray.push([[key, change.value], -1]);
+    }
+  }
+  input.sendData(new d2mini.MultiSet(multiSetArray));
+}
+function extractCollectionsFromQuery(query) {
+  const collections = {};
+  function extractFromSource(source) {
+    if (source.type === `collectionRef`) {
+      collections[source.collection.id] = source.collection;
+    } else if (source.type === `queryRef`) {
+      extractFromQuery(source.query);
+    }
+  }
+  function extractFromQuery(q) {
+    if (q.from) {
+      extractFromSource(q.from);
+    }
+    if (q.join && Array.isArray(q.join)) {
+      for (const joinClause of q.join) {
+        if (joinClause.from) {
+          extractFromSource(joinClause.from);
+        }
+      }
+    }
+  }
+  extractFromQuery(query);
+  return collections;
+}
+exports.createLiveQueryCollection = createLiveQueryCollection;
+exports.liveQueryCollectionOptions = liveQueryCollectionOptions;
+//# sourceMappingURL=live-query-collection.cjs.map

package/dist/cjs/query/live-query-collection.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"live-query-collection.cjs","sources":["../../../src/query/live-query-collection.ts"],"sourcesContent":["import { D2, MultiSet, output } from \"@electric-sql/d2mini\"\nimport { createCollection } from \"../collection.js\"\nimport { compileQuery } from \"./compiler/index.js\"\nimport { buildQuery } from \"./builder/index.js\"\nimport type { InitialQueryBuilder, QueryBuilder } from \"./builder/index.js\"\nimport type { Collection } from \"../collection.js\"\nimport type {\n  ChangeMessage,\n  CollectionConfig,\n  KeyedStream,\n  ResultStream,\n  SyncConfig,\n  UtilsRecord,\n} from \"../types.js\"\nimport type { Context, GetResult } from \"./builder/types.js\"\nimport type { MultiSetArray, RootStreamBuilder } from \"@electric-sql/d2mini\"\n\n// Global counter for auto-generated collection IDs\nlet liveQueryCollectionCounter = 0\n\n/**\n * Configuration interface for live query collection options\n *\n * @example\n * ```typescript\n * const config: LiveQueryCollectionConfig<any, any> = {\n *   // id is optional - will auto-generate \"live-query-1\", \"live-query-2\", etc.\n *   query: (q) => q\n *     .from({ comment: commentsCollection })\n *     .join(\n *       { user: usersCollection },\n *       ({ comment, user }) => eq(comment.user_id, user.id)\n *     )\n *     .where(({ comment }) => eq(comment.active, true))\n *     .select(({ comment, user }) => ({\n *       id: comment.id,\n *       content: comment.content,\n *       authorName: user.name,\n *     })),\n *   // getKey is optional - defaults to using stream key\n *   getKey: (item) => item.id,\n * }\n * ```\n */\nexport interface LiveQueryCollectionConfig<\n  TContext extends Context,\n  TResult extends object = GetResult<TContext> & object,\n> {\n  /**\n   * Unique identifier for the collection\n   * If not provided, defaults to `live-query-${number}` with auto-incrementing number\n   */\n  id?: string\n\n  /**\n   * Query builder function that defines the live query\n   */\n  query: (q: InitialQueryBuilder) => QueryBuilder<TContext>\n\n  /**\n   * Function to extract the key from result items\n   * If not provided, defaults to using the key from the D2 stream\n   */\n  getKey?: (item: TResult) => string | number\n\n  /**\n   * Optional schema for validation\n   */\n  schema?: CollectionConfig<TResult>[`schema`]\n\n  /**\n   * Optional mutation handlers\n   */\n  onInsert?: CollectionConfig<TResult>[`onInsert`]\n  onUpdate?: CollectionConfig<TResult>[`onUpdate`]\n  onDelete?: CollectionConfig<TResult>[`onDelete`]\n\n  /**\n   * Start sync / the query immediately\n   */\n  startSync?: boolean\n\n  /**\n   * GC time for the collection\n   */\n  gcTime?: number\n}\n\n/**\n * Creates live query collection options for use with createCollection\n *\n * @example\n * ```typescript\n * const options = liveQueryCollectionOptions({\n *   // id is optional - will auto-generate if not provided\n *   query: (q) => q\n *     .from({ post: postsCollection })\n *     .where(({ post }) => eq(post.published, true))\n *     .select(({ post }) => ({\n *       id: post.id,\n *       title: post.title,\n *       content: post.content,\n *     })),\n *   // getKey is optional - will use stream key if not provided\n * })\n *\n * const collection = createCollection(options)\n * ```\n *\n * @param config - Configuration options for the live query collection\n * @returns Collection options that can be passed to createCollection\n */\nexport function liveQueryCollectionOptions<\n  TContext extends Context,\n  TResult extends object = GetResult<TContext>,\n>(\n  config: LiveQueryCollectionConfig<TContext, TResult>\n): CollectionConfig<TResult> {\n  // Generate a unique ID if not provided\n  const id = config.id || `live-query-${++liveQueryCollectionCounter}`\n\n  // Build the query using the provided query builder function\n  const query = buildQuery<TContext>(config.query)\n\n  // WeakMap to store the keys of the results so that we can retreve them in the\n  // getKey function\n  const resultKeys = new WeakMap<object, unknown>()\n\n  // WeakMap to store the orderBy index for each result\n  const orderByIndices = new WeakMap<object, string>()\n\n  // Create compare function for ordering if the query has orderBy\n  const compare =\n    query.orderBy && query.orderBy.length > 0\n      ? (val1: TResult, val2: TResult): number => {\n          // Use the orderBy index stored in the WeakMap\n          const index1 = orderByIndices.get(val1)\n          const index2 = orderByIndices.get(val2)\n\n          // Compare fractional indices lexicographically\n          if (index1 && index2) {\n            if (index1 < index2) {\n              return -1\n            } else if (index1 > index2) {\n              return 1\n            } else {\n              return 0\n            }\n          }\n\n          // Fallback to no ordering if indices are missing\n          return 0\n        }\n      : undefined\n\n  const collections = extractCollectionsFromQuery(query)\n\n  const allCollectionsReady = () => {\n    return Object.values(collections).every(\n      (collection) => collection.status === `ready`\n    )\n  }\n\n  let graphCache: D2 | undefined\n  let inputsCache: Record<string, RootStreamBuilder<unknown>> | undefined\n  let pipelineCache: ResultStream | undefined\n\n  const compileBasePipeline = () => {\n    graphCache = new D2()\n    inputsCache = Object.fromEntries(\n      Object.entries(collections).map(([key]) => [\n        key,\n        graphCache!.newInput<any>(),\n      ])\n    )\n    pipelineCache = compileQuery(\n      query,\n      inputsCache as Record<string, KeyedStream>\n    )\n  }\n\n  const maybeCompileBasePipeline = () => {\n    if (!graphCache || !inputsCache || !pipelineCache) {\n      compileBasePipeline()\n    }\n    return {\n      graph: graphCache!,\n      inputs: inputsCache!,\n      pipeline: pipelineCache!,\n    }\n  }\n\n  // Compile the base pipeline once initially\n  // This is done to ensure that any errors are thrown immediately and synchronously\n  compileBasePipeline()\n\n  // Create the sync configuration\n  const sync: SyncConfig<TResult> = {\n    rowUpdateMode: `full`,\n    sync: ({ begin, write, commit, collection: theCollection }) => {\n      const { graph, inputs, pipeline } = maybeCompileBasePipeline()\n      let messagesCount = 0\n      pipeline.pipe(\n        output((data) => {\n          const messages = data.getInner()\n          messagesCount += messages.length\n\n          begin()\n          messages\n            .reduce((acc, [[key, tupleData], multiplicity]) => {\n              // All queries now consistently return [value, orderByIndex] format\n              // where orderByIndex is undefined for queries without ORDER BY\n              const [value, orderByIndex] = tupleData as [\n                TResult,\n                string | undefined,\n              ]\n\n              const changes = acc.get(key) || {\n                deletes: 0,\n                inserts: 0,\n                value,\n                orderByIndex,\n              }\n              if (multiplicity < 0) {\n                changes.deletes += Math.abs(multiplicity)\n              } else if (multiplicity > 0) {\n                changes.inserts += multiplicity\n                changes.value = value\n                changes.orderByIndex = orderByIndex\n              }\n              acc.set(key, changes)\n              return acc\n            }, new Map<unknown, { deletes: number; inserts: number; value: TResult; orderByIndex: string | undefined }>())\n            .forEach((changes, rawKey) => {\n              const { deletes, inserts, value, orderByIndex } = changes\n\n              // Store the key of the result so that we can retrieve it in the\n              // getKey function\n              resultKeys.set(value, rawKey)\n\n              // Store the orderBy index if it exists\n              if (orderByIndex !== undefined) {\n                orderByIndices.set(value, orderByIndex)\n              }\n\n              // Simple singular insert.\n              if (inserts && deletes === 0) {\n                write({\n                  value,\n                  type: `insert`,\n                })\n              } else if (\n                // Insert & update(s) (updates are a delete & insert)\n                inserts > deletes ||\n                // Just update(s) but the item is already in the collection (so\n                // was inserted previously).\n                (inserts === deletes &&\n                  theCollection.has(rawKey as string | number))\n              ) {\n                write({\n                  value,\n                  type: `update`,\n                })\n                // Only delete is left as an option\n              } else if (deletes > 0) {\n                write({\n                  value,\n                  type: `delete`,\n                })\n              } else {\n                throw new Error(\n                  `This should never happen ${JSON.stringify(changes)}`\n                )\n              }\n            })\n          commit()\n        })\n      )\n\n      graph.finalize()\n\n      const maybeRunGraph = () => {\n        // We only run the graph if all the collections are ready\n        if (allCollectionsReady()) {\n          graph.run()\n          // On the initial run, we may need to do an empty commit to ensure that\n          // the collection is initialized\n          if (messagesCount === 0) {\n            begin()\n            commit()\n          }\n        }\n      }\n\n      // Unsubscribe callbacks\n      const unsubscribeCallbacks = new Set<() => void>()\n\n      // Set up data flow from input collections to the compiled query\n      Object.entries(collections).forEach(([collectionId, collection]) => {\n        const input = inputs[collectionId]!\n\n        // Subscribe to changes\n        const unsubscribe = collection.subscribeChanges(\n          (changes: Array<ChangeMessage>) => {\n            sendChangesToInput(input, changes, collection.config.getKey)\n            maybeRunGraph()\n          },\n          { includeInitialState: true }\n        )\n        unsubscribeCallbacks.add(unsubscribe)\n      })\n\n      // Initial run\n      maybeRunGraph()\n\n      // Return the unsubscribe function\n      return () => {\n        unsubscribeCallbacks.forEach((unsubscribe) => unsubscribe())\n      }\n    },\n  }\n\n  // Return collection configuration\n  return {\n    id,\n    getKey:\n      config.getKey || ((item) => resultKeys.get(item) as string | number),\n    sync,\n    compare,\n    gcTime: config.gcTime || 5000, // 5 seconds by default for live queries\n    schema: config.schema,\n    onInsert: config.onInsert,\n    onUpdate: config.onUpdate,\n    onDelete: config.onDelete,\n    startSync: config.startSync,\n  }\n}\n\n/**\n * Creates a live query collection directly\n *\n * @example\n * ```typescript\n * // Minimal usage - just pass a query function\n * const activeUsers = createLiveQueryCollection(\n *   (q) => q\n *     .from({ user: usersCollection })\n *     .where(({ user }) => eq(user.active, true))\n *     .select(({ user }) => ({ id: user.id, name: user.name }))\n * )\n *\n * // Full configuration with custom options\n * const searchResults = createLiveQueryCollection({\n *   id: \"search-results\", // Custom ID (auto-generated if omitted)\n *   query: (q) => q\n *     .from({ post: postsCollection })\n *     .where(({ post }) => like(post.title, `%${searchTerm}%`))\n *     .select(({ post }) => ({\n *       id: post.id,\n *       title: post.title,\n *       excerpt: post.excerpt,\n *     })),\n *   getKey: (item) => item.id, // Custom key function (uses stream key if omitted)\n *   utils: {\n *     updateSearchTerm: (newTerm: string) => {\n *       // Custom utility functions\n *     }\n *   }\n * })\n * ```\n */\n\n// Overload 1: Accept just the query function\nexport function createLiveQueryCollection<\n  TContext extends Context,\n  TResult extends object = GetResult<TContext>,\n>(\n  query: (q: InitialQueryBuilder) => QueryBuilder<TContext>\n): Collection<TResult, string | number, {}>\n\n// Overload 2: Accept full config object with optional utilities\nexport function createLiveQueryCollection<\n  TContext extends Context,\n  TResult extends object = GetResult<TContext>,\n  TUtils extends UtilsRecord = {},\n>(\n  config: LiveQueryCollectionConfig<TContext, TResult> & { utils?: TUtils }\n): Collection<TResult, string | number, TUtils>\n\n// Implementation\nexport function createLiveQueryCollection<\n  TContext extends Context,\n  TResult extends object = GetResult<TContext>,\n  TUtils extends UtilsRecord = {},\n>(\n  configOrQuery:\n    | (LiveQueryCollectionConfig<TContext, TResult> & { utils?: TUtils })\n    | ((q: InitialQueryBuilder) => QueryBuilder<TContext>)\n): Collection<TResult, string | number, TUtils> {\n  // Determine if the argument is a function (query) or a config object\n  if (typeof configOrQuery === `function`) {\n    // Simple query function case\n    const config: LiveQueryCollectionConfig<TContext, TResult> = {\n      query: configOrQuery,\n    }\n    const options = liveQueryCollectionOptions<TContext, TResult>(config)\n\n    // Use a bridge function that handles the type compatibility cleanly\n    return bridgeToCreateCollection(options)\n  } else {\n    // Config object case\n    const config = configOrQuery as LiveQueryCollectionConfig<\n      TContext,\n      TResult\n    > & { utils?: TUtils }\n    const options = liveQueryCollectionOptions<TContext, TResult>(config)\n\n    // Use a bridge function that handles the type compatibility cleanly\n    return bridgeToCreateCollection({\n      ...options,\n      utils: config.utils,\n    })\n  }\n}\n\n/**\n * Bridge function that handles the type compatibility between query2's TResult\n * and core collection's ResolveType without exposing ugly type assertions to users\n */\nfunction bridgeToCreateCollection<\n  TResult extends object,\n  TUtils extends UtilsRecord = {},\n>(\n  options: CollectionConfig<TResult> & { utils?: TUtils }\n): Collection<TResult, string | number, TUtils> {\n  // This is the only place we need a type assertion, hidden from user API\n  return createCollection(options as any) as unknown as Collection<\n    TResult,\n    string | number,\n    TUtils\n  >\n}\n\n/**\n * Helper function to send changes to a D2 input stream\n */\nfunction sendChangesToInput(\n  input: RootStreamBuilder<unknown>,\n  changes: Array<ChangeMessage>,\n  getKey: (item: ChangeMessage[`value`]) => any\n) {\n  const multiSetArray: MultiSetArray<unknown> = []\n  for (const change of changes) {\n    const key = getKey(change.value)\n    if (change.type === `insert`) {\n      multiSetArray.push([[key, change.value], 1])\n    } else if (change.type === `update`) {\n      multiSetArray.push([[key, change.previousValue], -1])\n      multiSetArray.push([[key, change.value], 1])\n    } else {\n      // change.type === `delete`\n      multiSetArray.push([[key, change.value], -1])\n    }\n  }\n  input.sendData(new MultiSet(multiSetArray))\n}\n\n/**\n * Helper function to extract collections from a compiled query\n * Traverses the query IR to find all collection references\n * Maps collections by their ID (not alias) as expected by the compiler\n */\nfunction extractCollectionsFromQuery(\n  query: any\n): Record<string, Collection<any, any, any>> {\n  const collections: Record<string, any> = {}\n\n  // Helper function to recursively extract collections from a query or source\n  function extractFromSource(source: any) {\n    if (source.type === `collectionRef`) {\n      collections[source.collection.id] = source.collection\n    } else if (source.type === `queryRef`) {\n      // Recursively extract from subquery\n      extractFromQuery(source.query)\n    }\n  }\n\n  // Helper function to recursively extract collections from a query\n  function extractFromQuery(q: any) {\n    // Extract from FROM clause\n    if (q.from) {\n      extractFromSource(q.from)\n    }\n\n    // Extract from JOIN clauses\n    if (q.join && Array.isArray(q.join)) {\n      for (const joinClause of q.join) {\n        if (joinClause.from) {\n          extractFromSource(joinClause.from)\n        }\n      }\n    }\n  }\n\n  // Start extraction from the root query\n  extractFromQuery(query)\n\n  return collections\n}\n"],"names":["buildQuery","collection","D2","compileQuery","output","createCollection","MultiSet"],"mappings":"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"}

package/dist/cjs/query/live-query-collection.d.cts

@@ -0,0 +1,124 @@
+import { InitialQueryBuilder, QueryBuilder } from './builder/index.js';
+import { Collection } from '../collection.js';
+import { CollectionConfig, UtilsRecord } from '../types.js';
+import { Context, GetResult } from './builder/types.js';
+/**
+ * Configuration interface for live query collection options
+ *
+ * @example
+ * ```typescript
+ * const config: LiveQueryCollectionConfig<any, any> = {
+ *   // id is optional - will auto-generate "live-query-1", "live-query-2", etc.
+ *   query: (q) => q
+ *     .from({ comment: commentsCollection })
+ *     .join(
+ *       { user: usersCollection },
+ *       ({ comment, user }) => eq(comment.user_id, user.id)
+ *     )
+ *     .where(({ comment }) => eq(comment.active, true))
+ *     .select(({ comment, user }) => ({
+ *       id: comment.id,
+ *       content: comment.content,
+ *       authorName: user.name,
+ *     })),
+ *   // getKey is optional - defaults to using stream key
+ *   getKey: (item) => item.id,
+ * }
+ * ```
+ */
+export interface LiveQueryCollectionConfig<TContext extends Context, TResult extends object = GetResult<TContext> & object> {
+    /**
+     * Unique identifier for the collection
+     * If not provided, defaults to `live-query-${number}` with auto-incrementing number
+     */
+    id?: string;
+    /**
+     * Query builder function that defines the live query
+     */
+    query: (q: InitialQueryBuilder) => QueryBuilder<TContext>;
+    /**
+     * Function to extract the key from result items
+     * If not provided, defaults to using the key from the D2 stream
+     */
+    getKey?: (item: TResult) => string | number;
+    /**
+     * Optional schema for validation
+     */
+    schema?: CollectionConfig<TResult>[`schema`];
+    /**
+     * Optional mutation handlers
+     */
+    onInsert?: CollectionConfig<TResult>[`onInsert`];
+    onUpdate?: CollectionConfig<TResult>[`onUpdate`];
+    onDelete?: CollectionConfig<TResult>[`onDelete`];
+    /**
+     * Start sync / the query immediately
+     */
+    startSync?: boolean;
+    /**
+     * GC time for the collection
+     */
+    gcTime?: number;
+}
+/**
+ * Creates live query collection options for use with createCollection
+ *
+ * @example
+ * ```typescript
+ * const options = liveQueryCollectionOptions({
+ *   // id is optional - will auto-generate if not provided
+ *   query: (q) => q
+ *     .from({ post: postsCollection })
+ *     .where(({ post }) => eq(post.published, true))
+ *     .select(({ post }) => ({
+ *       id: post.id,
+ *       title: post.title,
+ *       content: post.content,
+ *     })),
+ *   // getKey is optional - will use stream key if not provided
+ * })
+ *
+ * const collection = createCollection(options)
+ * ```
+ *
+ * @param config - Configuration options for the live query collection
+ * @returns Collection options that can be passed to createCollection
+ */
+export declare function liveQueryCollectionOptions<TContext extends Context, TResult extends object = GetResult<TContext>>(config: LiveQueryCollectionConfig<TContext, TResult>): CollectionConfig<TResult>;
+/**
+ * Creates a live query collection directly
+ *
+ * @example
+ * ```typescript
+ * // Minimal usage - just pass a query function
+ * const activeUsers = createLiveQueryCollection(
+ *   (q) => q
+ *     .from({ user: usersCollection })
+ *     .where(({ user }) => eq(user.active, true))
+ *     .select(({ user }) => ({ id: user.id, name: user.name }))
+ * )
+ *
+ * // Full configuration with custom options
+ * const searchResults = createLiveQueryCollection({
+ *   id: "search-results", // Custom ID (auto-generated if omitted)
+ *   query: (q) => q
+ *     .from({ post: postsCollection })
+ *     .where(({ post }) => like(post.title, `%${searchTerm}%`))
+ *     .select(({ post }) => ({
+ *       id: post.id,
+ *       title: post.title,
+ *       excerpt: post.excerpt,
+ *     })),
+ *   getKey: (item) => item.id, // Custom key function (uses stream key if omitted)
+ *   utils: {
+ *     updateSearchTerm: (newTerm: string) => {
+ *       // Custom utility functions
+ *     }
+ *   }
+ * })
+ * ```
+ */
+export declare function createLiveQueryCollection<TContext extends Context, TResult extends object = GetResult<TContext>>(query: (q: InitialQueryBuilder) => QueryBuilder<TContext>): Collection<TResult, string | number, {}>;
+export declare function createLiveQueryCollection<TContext extends Context, TResult extends object = GetResult<TContext>, TUtils extends UtilsRecord = {}>(config: LiveQueryCollectionConfig<TContext, TResult> & {
+    utils?: TUtils;
+}): Collection<TResult, string | number, TUtils>;

package/dist/cjs/transactions.cjs

@@ -3,18 +3,9 @@ Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 const deferred = require("./deferred.cjs");
 const transactions = [];
 let transactionStack = [];
+let sequenceNumber = 0;
 function createTransaction(config) {
-  if (typeof config.mutationFn === `undefined`) {
-    throw `mutationFn is required when creating a transaction`;
-  }
-  let transactionId = config.id;
-  if (!transactionId) {
-    transactionId = crypto.randomUUID();
-  }
-  const newTransaction = new Transaction({
-    ...config,
-    id: transactionId
-  });
+  const newTransaction = new Transaction(config);
   transactions.push(newTransaction);
   return newTransaction;
 }
@@ -39,13 +30,17 @@ function removeFromPendingList(tx) {
 }
 class Transaction {
   constructor(config) {
-    this.id = config.id;
+    if (typeof config.mutationFn === `undefined`) {
+      throw `mutationFn is required when creating a transaction`;
+    }
+    this.id = config.id ?? crypto.randomUUID();
     this.mutationFn = config.mutationFn;
     this.state = `pending`;
     this.mutations = [];
     this.isPersisted = deferred.createDeferred();
     this.autoCommit = config.autoCommit ?? true;
     this.createdAt = /* @__PURE__ */ new Date();
+    this.sequenceNumber = sequenceNumber++;
     this.metadata = config.metadata ?? {};
   }
   setState(newState) {
@@ -137,8 +132,20 @@ class Transaction {
     }
     return this;
   }
+  /**
+   * Compare two transactions by their createdAt time and sequence number in order
+   * to sort them in the order they were created.
+   * @param other - The other transaction to compare to
+   * @returns -1 if this transaction was created before the other, 1 if it was created after, 0 if they were created at the same time
+   */
+  compareCreatedAt(other) {
+    const createdAtComparison = this.createdAt.getTime() - other.createdAt.getTime();
+    if (createdAtComparison !== 0) {
+      return createdAtComparison;
+    }
+    return this.sequenceNumber - other.sequenceNumber;
+  }
 }
-exports.Transaction = Transaction;
 exports.createTransaction = createTransaction;
 exports.getActiveTransaction = getActiveTransaction;
 //# sourceMappingURL=transactions.cjs.map

package/dist/cjs/transactions.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"transactions.cjs","sources":["../../src/transactions.ts"],"sourcesContent":["import { createDeferred } from \"./deferred\"\nimport type { Deferred } from \"./deferred\"\nimport type {\n  MutationFn,\n  OperationType,\n  PendingMutation,\n  TransactionConfig,\n  TransactionState,\n  TransactionWithMutations,\n} from \"./types\"\n\nconst transactions: Array<Transaction<any>> = []\nlet transactionStack: Array<Transaction<any>> = []\n\nexport function createTransaction<\n  TData extends object = Record<string, unknown>,\n>(config: TransactionConfig<TData>): Transaction<TData> {\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 = crypto.randomUUID()\n  }\n  const newTransaction = new Transaction<TData>({\n    ...config,\n    id: transactionId,\n  })\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<any>) {\n  transactionStack.push(tx)\n}\n\nfunction unregisterTransaction(tx: Transaction<any>) {\n  transactionStack = transactionStack.filter((t) => t.id !== tx.id)\n}\n\nfunction removeFromPendingList(tx: Transaction<any>) {\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  T extends object = Record<string, unknown>,\n  TOperation extends OperationType = OperationType,\n> {\n  public id: string\n  public state: TransactionState\n  public mutationFn: MutationFn<T>\n  public mutations: Array<PendingMutation<T, TOperation>>\n  public isPersisted: Deferred<Transaction<T, TOperation>>\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<T>) {\n    this.id = config.id!\n    this.mutationFn = config.mutationFn\n    this.state = `pending`\n    this.mutations = []\n    this.isPersisted = createDeferred<Transaction<T, TOperation>>()\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<T> {\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.globalKey === newMutation.globalKey\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<T> {\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.globalKey))\n      for (const t of transactions) {\n        t.state === `pending` &&\n          t.mutations.some((m) => mutationIds.has(m.globalKey)) &&\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.onTransactionStateChange()\n\n        // Only call commitPendingTransactions if there are pending sync transactions\n        if (mutation.collection.pendingSyncedTransactions.length > 0) {\n          mutation.collection.commitPendingTransactions()\n        }\n\n        hasCalled.add(mutation.collection.id)\n      }\n    }\n  }\n\n  async commit(): Promise<Transaction<T>> {\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      // We've already verified mutations is non-empty, so this cast is safe\n      // Use a direct type assertion instead of object spreading to preserve the original type\n      await this.mutationFn({\n        transaction: this as unknown as TransactionWithMutations<T>,\n      })\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":["createDeferred"],"mappings":"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"}
+{"version":3,"file":"transactions.cjs","sources":["../../src/transactions.ts"],"sourcesContent":["import { createDeferred } from \"./deferred\"\nimport type { Deferred } from \"./deferred\"\nimport type {\n  MutationFn,\n  OperationType,\n  PendingMutation,\n  TransactionConfig,\n  TransactionState,\n  TransactionWithMutations,\n} from \"./types\"\n\nconst transactions: Array<Transaction<any>> = []\nlet transactionStack: Array<Transaction<any>> = []\n\nlet sequenceNumber = 0\n\nexport function createTransaction<\n  TData extends object = Record<string, unknown>,\n>(config: TransactionConfig<TData>): Transaction<TData> {\n  const newTransaction = new Transaction<TData>(config)\n  transactions.push(newTransaction)\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<any>) {\n  transactionStack.push(tx)\n}\n\nfunction unregisterTransaction(tx: Transaction<any>) {\n  transactionStack = transactionStack.filter((t) => t.id !== tx.id)\n}\n\nfunction removeFromPendingList(tx: Transaction<any>) {\n  const index = transactions.findIndex((t) => t.id === tx.id)\n  if (index !== -1) {\n    transactions.splice(index, 1)\n  }\n}\n\nclass Transaction<\n  T extends object = Record<string, unknown>,\n  TOperation extends OperationType = OperationType,\n> {\n  public id: string\n  public state: TransactionState\n  public mutationFn: MutationFn<T>\n  public mutations: Array<PendingMutation<T, TOperation>>\n  public isPersisted: Deferred<Transaction<T, TOperation>>\n  public autoCommit: boolean\n  public createdAt: Date\n  public sequenceNumber: number\n  public metadata: Record<string, unknown>\n  public error?: {\n    message: string\n    error: Error\n  }\n\n  constructor(config: TransactionConfig<T>) {\n    if (typeof config.mutationFn === `undefined`) {\n      throw `mutationFn is required when creating a transaction`\n    }\n    this.id = config.id ?? crypto.randomUUID()\n    this.mutationFn = config.mutationFn\n    this.state = `pending`\n    this.mutations = []\n    this.isPersisted = createDeferred<Transaction<T, TOperation>>()\n    this.autoCommit = config.autoCommit ?? true\n    this.createdAt = new Date()\n    this.sequenceNumber = sequenceNumber++\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<T> {\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.globalKey === newMutation.globalKey\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<T> {\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.globalKey))\n      for (const t of transactions) {\n        t.state === `pending` &&\n          t.mutations.some((m) => mutationIds.has(m.globalKey)) &&\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.onTransactionStateChange()\n\n        // Only call commitPendingTransactions if there are pending sync transactions\n        if (mutation.collection.pendingSyncedTransactions.length > 0) {\n          mutation.collection.commitPendingTransactions()\n        }\n\n        hasCalled.add(mutation.collection.id)\n      }\n    }\n  }\n\n  async commit(): Promise<Transaction<T>> {\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      // We've already verified mutations is non-empty, so this cast is safe\n      // Use a direct type assertion instead of object spreading to preserve the original type\n      await this.mutationFn({\n        transaction: this as unknown as TransactionWithMutations<T>,\n      })\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  /**\n   * Compare two transactions by their createdAt time and sequence number in order\n   * to sort them in the order they were created.\n   * @param other - The other transaction to compare to\n   * @returns -1 if this transaction was created before the other, 1 if it was created after, 0 if they were created at the same time\n   */\n  compareCreatedAt(other: Transaction<any>): number {\n    const createdAtComparison =\n      this.createdAt.getTime() - other.createdAt.getTime()\n    if (createdAtComparison !== 0) {\n      return createdAtComparison\n    }\n    return this.sequenceNumber - other.sequenceNumber\n  }\n}\n\nexport type { Transaction }\n"],"names":["createDeferred"],"mappings":"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"}

package/dist/cjs/transactions.d.cts

@@ -2,7 +2,7 @@ import { Deferred } from './deferred.cjs';
 import { MutationFn, OperationType, PendingMutation, TransactionConfig, TransactionState } from './types.cjs';
 export declare function createTransaction<TData extends object = Record<string, unknown>>(config: TransactionConfig<TData>): Transaction<TData>;
 export declare function getActiveTransaction(): Transaction | undefined;
-export declare class Transaction<T extends object = Record<string, unknown>, TOperation extends OperationType = OperationType> {
+declare class Transaction<T extends object = Record<string, unknown>, TOperation extends OperationType = OperationType> {
     id: string;
     state: TransactionState;
     mutationFn: MutationFn<T>;
@@ -10,6 +10,7 @@ export declare class Transaction<T extends object = Record<string, unknown>, TOp
     isPersisted: Deferred<Transaction<T, TOperation>>;
     autoCommit: boolean;
     createdAt: Date;
+    sequenceNumber: number;
     metadata: Record<string, unknown>;
     error?: {
         message: string;
@@ -24,4 +25,12 @@ export declare class Transaction<T extends object = Record<string, unknown>, TOp
     }): Transaction<T>;
     touchCollection(): void;
     commit(): Promise<Transaction<T>>;
+    /**
+     * Compare two transactions by their createdAt time and sequence number in order
+     * to sort them in the order they were created.
+     * @param other - The other transaction to compare to
+     * @returns -1 if this transaction was created before the other, 1 if it was created after, 0 if they were created at the same time
+     */
+    compareCreatedAt(other: Transaction<any>): number;
 }
+export type { Transaction };

package/dist/cjs/types.d.cts

@@ -99,6 +99,14 @@ export interface SyncConfig<T extends object = Record<string, unknown>, TKey ext
      * @returns Record containing relation information
      */
     getSyncMetadata?: () => Record<string, unknown>;
+    /**
+     * The row update mode used to sync to the collection.
+     * @default `partial`
+     * @description
+     * - `partial`: Updates contain only the changes to the row.
+     * - `full`: Updates contain the entire row.
+     */
+    rowUpdateMode?: `partial` | `full`;
 }
 export interface ChangeMessage<T extends object = Record<string, unknown>, TKey extends string | number = string | number> {
     key: TKey;
@@ -222,6 +230,11 @@ export type InputRow = [unknown, Record<string, unknown>];
  * This is used as the inputs from a collection to a query
  */
 export type KeyedStream = IStreamBuilder<InputRow>;
+/**
+ * Result stream type representing the output of compiled queries
+ * Always returns [key, [result, orderByIndex]] where orderByIndex is undefined for unordered queries
+ */
+export type ResultStream = IStreamBuilder<[unknown, [any, string | undefined]]>;
 /**
  * A namespaced row is a row withing a pipeline that had each table wrapped in its alias
  */