@tanstack/db 0.1.0 → 0.1.3

package/dist/cjs/query/builder/types.d.cts

@@ -1,6 +1,7 @@
 import { CollectionImpl } from '../../collection.js';
-import { Aggregate, BasicExpression } from '../ir.js';
+import { Aggregate, BasicExpression, OrderByDirection } from '../ir.js';
 import { QueryBuilder } from './index.js';
+import { ResolveType } from '../../types.js';
 export interface Context {
     baseSchema: ContextSchema;
     schema: ContextSchema;
@@ -13,17 +14,37 @@ export type ContextSchema = Record<string, unknown>;
 export type Source = {
     [alias: string]: CollectionImpl<any, any> | QueryBuilder<Context>;
 };
-export type InferCollectionType<T> = T extends CollectionImpl<infer U> ? U : never;
+export type InferCollectionType<T> = T extends CollectionImpl<infer U, any, any, infer TSchema, any> ? ResolveType<U, TSchema, U> : never;
 export type SchemaFromSource<T extends Source> = Prettify<{
-    [K in keyof T]: T[K] extends CollectionImpl<infer U> ? U : T[K] extends QueryBuilder<infer TContext> ? GetResult<TContext> : never;
+    [K in keyof T]: T[K] extends CollectionImpl<any, any, any, any, any> ? InferCollectionType<T[K]> : T[K] extends QueryBuilder<infer TContext> ? GetResult<TContext> : never;
 }>;
 export type GetAliases<TContext extends Context> = keyof TContext[`schema`];
 export type WhereCallback<TContext extends Context> = (refs: RefProxyForContext<TContext>) => any;
 export type SelectObject<T extends Record<string, BasicExpression | Aggregate | RefProxy | RefProxyFor<any>> = Record<string, BasicExpression | Aggregate | RefProxy | RefProxyFor<any>>> = T;
 export type ResultTypeFromSelect<TSelectObject> = {
-    [K in keyof TSelectObject]: TSelectObject[K] extends RefProxy<infer T> ? T : TSelectObject[K] extends BasicExpression<infer T> ? T : TSelectObject[K] extends Aggregate<infer T> ? T : TSelectObject[K] extends RefProxyFor<infer T> ? T : never;
+    [K in keyof TSelectObject]: TSelectObject[K] extends RefProxy<infer T> ? T : TSelectObject[K] extends BasicExpression<infer T> ? T : TSelectObject[K] extends Aggregate<infer T> ? T : TSelectObject[K] extends RefProxyFor<infer T> ? T : TSelectObject[K] extends undefined ? undefined : TSelectObject[K] extends {
+        __type: infer U;
+    } ? U : never;
 };
 export type OrderByCallback<TContext extends Context> = (refs: RefProxyForContext<TContext>) => any;
+export type OrderByOptions = {
+    direction?: OrderByDirection;
+    nulls?: `first` | `last`;
+} & StringSortOpts;
+export type StringSortOpts = {
+    stringSort?: `lexical`;
+} | {
+    stringSort?: `locale`;
+    locale?: string;
+    localeOptions?: object;
+};
+export type CompareOptions = {
+    direction: OrderByDirection;
+    nulls: `first` | `last`;
+    stringSort: `lexical` | `locale`;
+    locale?: string;
+    localeOptions?: object;
+};
 export type GroupByCallback<TContext extends Context> = (refs: RefProxyForContext<TContext>) => any;
 export type JoinOnCallback<TContext extends Context> = (refs: RefProxyForContext<TContext>) => any;
 export type RefProxyForContext<TContext extends Context> = {
@@ -33,9 +54,9 @@ type IsExactlyUndefined<T> = [T] extends [undefined] ? true : false;
 type IsOptional<T> = undefined extends T ? true : false;
 type NonUndefined<T> = T extends undefined ? never : T;
 export type RefProxyFor<T> = OmitRefProxy<IsExactlyUndefined<T> extends true ? RefProxy<T> : IsOptional<T> extends true ? NonUndefined<T> extends Record<string, any> ? {
-    [K in keyof NonUndefined<T>]: NonUndefined<T>[K] extends Record<string, any> ? RefProxyFor<NonUndefined<T>[K] | undefined> & RefProxy<NonUndefined<T>[K] | undefined> : RefProxy<NonUndefined<T>[K] | undefined>;
+    [K in keyof NonUndefined<T>]-?: NonUndefined<T>[K] extends Record<string, any> ? RefProxyFor<NonUndefined<T>[K]> & RefProxy<NonUndefined<T>[K] | undefined> : RefProxy<NonUndefined<T>[K] | undefined>;
 } & RefProxy<T> : RefProxy<T> : T extends Record<string, any> ? {
-    [K in keyof T]: T[K] extends Record<string, any> ? RefProxyFor<T[K]> & RefProxy<T[K]> : RefProxy<T[K]>;
+    [K in keyof T]-?: undefined extends T[K] ? T[K] extends Record<string, any> ? RefProxyFor<T[K]> & RefProxy<T[K]> : RefProxy<T[K]> : T[K] extends Record<string, any> ? RefProxyFor<T[K]> & RefProxy<T[K]> : RefProxy<T[K]>;
 } & RefProxy<T> : RefProxy<T>>;
 export type Ref<T> = RefProxyFor<T>;
 type OmitRefProxy<T> = Omit<T, `__refProxy` | `__path` | `__type`>;

package/dist/cjs/query/compiler/order-by.cjs

@@ -6,7 +6,7 @@ const evaluators = require("./evaluators.cjs");
 function processOrderBy(pipeline, orderByClause, limit, offset) {
   const compiledOrderBy = orderByClause.map((clause) => ({
     compiledExpression: evaluators.compileExpression(clause.expression),
-    direction: clause.direction
+    compareOptions: clause.compareOptions
   }));
   const valueExtractor = (row) => {
     const orderByContext = { ...row };
@@ -23,29 +23,27 @@ function processOrderBy(pipeline, orderByClause, limit, offset) {
     }
     return null;
   };
-  const makeComparator = () => {
-    return (a, b) => {
-      if (orderByClause.length > 1) {
-        const arrayA = a;
-        const arrayB = b;
-        for (let i = 0; i < orderByClause.length; i++) {
-          const direction = orderByClause[i].direction;
-          const compareFn = direction === `desc` ? comparison.descComparator : comparison.ascComparator;
-          const result = compareFn(arrayA[i], arrayB[i]);
-          if (result !== 0) {
-            return result;
-          }
+  const comparator = (a, b) => {
+    if (orderByClause.length > 1) {
+      const arrayA = a;
+      const arrayB = b;
+      for (let i = 0; i < orderByClause.length; i++) {
+        const clause = orderByClause[i];
+        const compareFn = comparison.makeComparator(clause.compareOptions);
+        const result = compareFn(arrayA[i], arrayB[i]);
+        if (result !== 0) {
+          return result;
         }
-        return arrayA.length - arrayB.length;
-      }
-      if (orderByClause.length === 1) {
-        const direction = orderByClause[0].direction;
-        return direction === `desc` ? comparison.descComparator(a, b) : comparison.ascComparator(a, b);
       }
-      return comparison.ascComparator(a, b);
-    };
+      return arrayA.length - arrayB.length;
+    }
+    if (orderByClause.length === 1) {
+      const clause = orderByClause[0];
+      const compareFn = comparison.makeComparator(clause.compareOptions);
+      return compareFn(a, b);
+    }
+    return comparison.defaultComparator(a, b);
   };
-  const comparator = makeComparator();
   return pipeline.pipe(
     dbIvm.orderByWithFractionalIndex(valueExtractor, {
       limit,

package/dist/cjs/query/compiler/order-by.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"order-by.cjs","sources":["../../../../src/query/compiler/order-by.ts"],"sourcesContent":["import { orderByWithFractionalIndex } from \"@tanstack/db-ivm\"\nimport { ascComparator, descComparator } from \"../../utils/comparison.js\"\nimport { compileExpression } from \"./evaluators.js\"\nimport type { OrderByClause } from \"../ir.js\"\nimport type { NamespacedAndKeyedStream, NamespacedRow } from \"../../types.js\"\nimport type { IStreamBuilder, KeyValue } from \"@tanstack/db-ivm\"\n\n/**\n * Processes the ORDER BY clause\n * Works with the new structure that has both namespaced row data and __select_results\n * Always uses fractional indexing and adds the index as __ordering_index to the result\n */\nexport function processOrderBy(\n  pipeline: NamespacedAndKeyedStream,\n  orderByClause: Array<OrderByClause>,\n  limit?: number,\n  offset?: number\n): IStreamBuilder<KeyValue<unknown, [NamespacedRow, string]>> {\n  // Pre-compile all order by expressions\n  const compiledOrderBy = orderByClause.map((clause) => ({\n    compiledExpression: compileExpression(clause.expression),\n    direction: clause.direction,\n  }))\n\n  // Create a value extractor function for the orderBy operator\n  const valueExtractor = (row: NamespacedRow & { __select_results?: any }) => {\n    // For ORDER BY expressions, we need to provide access to both:\n    // 1. The original namespaced row data (for direct table column references)\n    // 2. The __select_results (for SELECT alias references)\n\n    // Create a merged context for expression evaluation\n    const orderByContext = { ...row }\n\n    // If there are select results, merge them at the top level for alias access\n    if (row.__select_results) {\n      // Add select results as top-level properties for alias access\n      Object.assign(orderByContext, row.__select_results)\n    }\n\n    if (orderByClause.length > 1) {\n      // For multiple orderBy columns, create a composite key\n      return compiledOrderBy.map((compiled) =>\n        compiled.compiledExpression(orderByContext)\n      )\n    } else if (orderByClause.length === 1) {\n      // For a single orderBy column, use the value directly\n      const compiled = compiledOrderBy[0]!\n      return compiled.compiledExpression(orderByContext)\n    }\n\n    // Default case - no ordering\n    return null\n  }\n\n  // Create a multi-property comparator that respects the order and direction of each property\n  const makeComparator = () => {\n    return (a: unknown, b: unknown) => {\n      // If we're comparing arrays (multiple properties), compare each property in order\n      if (orderByClause.length > 1) {\n        const arrayA = a as Array<unknown>\n        const arrayB = b as Array<unknown>\n        for (let i = 0; i < orderByClause.length; i++) {\n          const direction = orderByClause[i]!.direction\n          const compareFn =\n            direction === `desc` ? descComparator : ascComparator\n          const result = compareFn(arrayA[i], arrayB[i])\n          if (result !== 0) {\n            return result\n          }\n        }\n        return arrayA.length - arrayB.length\n      }\n\n      // Single property comparison\n      if (orderByClause.length === 1) {\n        const direction = orderByClause[0]!.direction\n        return direction === `desc` ? descComparator(a, b) : ascComparator(a, b)\n      }\n\n      return ascComparator(a, b)\n    }\n  }\n\n  const comparator = makeComparator()\n\n  // Use fractional indexing and return the tuple [value, index]\n  return pipeline.pipe(\n    orderByWithFractionalIndex(valueExtractor, {\n      limit,\n      offset,\n      comparator,\n    })\n    // orderByWithFractionalIndex returns [key, [value, index]] - we keep this format\n  )\n}\n"],"names":["compileExpression","descComparator","ascComparator","orderByWithFractionalIndex"],"mappings":";;;;;AAYO,SAAS,eACd,UACA,eACA,OACA,QAC4D;AAE5D,QAAM,kBAAkB,cAAc,IAAI,CAAC,YAAY;AAAA,IACrD,oBAAoBA,WAAAA,kBAAkB,OAAO,UAAU;AAAA,IACvD,WAAW,OAAO;AAAA,EAAA,EAClB;AAGF,QAAM,iBAAiB,CAAC,QAAoD;AAM1E,UAAM,iBAAiB,EAAE,GAAG,IAAA;AAG5B,QAAI,IAAI,kBAAkB;AAExB,aAAO,OAAO,gBAAgB,IAAI,gBAAgB;AAAA,IACpD;AAEA,QAAI,cAAc,SAAS,GAAG;AAE5B,aAAO,gBAAgB;AAAA,QAAI,CAAC,aAC1B,SAAS,mBAAmB,cAAc;AAAA,MAAA;AAAA,IAE9C,WAAW,cAAc,WAAW,GAAG;AAErC,YAAM,WAAW,gBAAgB,CAAC;AAClC,aAAO,SAAS,mBAAmB,cAAc;AAAA,IACnD;AAGA,WAAO;AAAA,EACT;AAGA,QAAM,iBAAiB,MAAM;AAC3B,WAAO,CAAC,GAAY,MAAe;AAEjC,UAAI,cAAc,SAAS,GAAG;AAC5B,cAAM,SAAS;AACf,cAAM,SAAS;AACf,iBAAS,IAAI,GAAG,IAAI,cAAc,QAAQ,KAAK;AAC7C,gBAAM,YAAY,cAAc,CAAC,EAAG;AACpC,gBAAM,YACJ,cAAc,SAASC,WAAAA,iBAAiBC,WAAAA;AAC1C,gBAAM,SAAS,UAAU,OAAO,CAAC,GAAG,OAAO,CAAC,CAAC;AAC7C,cAAI,WAAW,GAAG;AAChB,mBAAO;AAAA,UACT;AAAA,QACF;AACA,eAAO,OAAO,SAAS,OAAO;AAAA,MAChC;AAGA,UAAI,cAAc,WAAW,GAAG;AAC9B,cAAM,YAAY,cAAc,CAAC,EAAG;AACpC,eAAO,cAAc,SAASD,WAAAA,eAAe,GAAG,CAAC,IAAIC,WAAAA,cAAc,GAAG,CAAC;AAAA,MACzE;AAEA,aAAOA,WAAAA,cAAc,GAAG,CAAC;AAAA,IAC3B;AAAA,EACF;AAEA,QAAM,aAAa,eAAA;AAGnB,SAAO,SAAS;AAAA,IACdC,MAAAA,2BAA2B,gBAAgB;AAAA,MACzC;AAAA,MACA;AAAA,MACA;AAAA,IAAA,CACD;AAAA;AAAA,EAAA;AAGL;;"}
+{"version":3,"file":"order-by.cjs","sources":["../../../../src/query/compiler/order-by.ts"],"sourcesContent":["import { orderByWithFractionalIndex } from \"@tanstack/db-ivm\"\nimport { defaultComparator, makeComparator } from \"../../utils/comparison.js\"\nimport { compileExpression } from \"./evaluators.js\"\nimport type { OrderByClause } from \"../ir.js\"\nimport type { NamespacedAndKeyedStream, NamespacedRow } from \"../../types.js\"\nimport type { IStreamBuilder, KeyValue } from \"@tanstack/db-ivm\"\n\n/**\n * Processes the ORDER BY clause\n * Works with the new structure that has both namespaced row data and __select_results\n * Always uses fractional indexing and adds the index as __ordering_index to the result\n */\nexport function processOrderBy(\n  pipeline: NamespacedAndKeyedStream,\n  orderByClause: Array<OrderByClause>,\n  limit?: number,\n  offset?: number\n): IStreamBuilder<KeyValue<unknown, [NamespacedRow, string]>> {\n  // Pre-compile all order by expressions\n  const compiledOrderBy = orderByClause.map((clause) => ({\n    compiledExpression: compileExpression(clause.expression),\n    compareOptions: clause.compareOptions,\n  }))\n\n  // Create a value extractor function for the orderBy operator\n  const valueExtractor = (row: NamespacedRow & { __select_results?: any }) => {\n    // For ORDER BY expressions, we need to provide access to both:\n    // 1. The original namespaced row data (for direct table column references)\n    // 2. The __select_results (for SELECT alias references)\n\n    // Create a merged context for expression evaluation\n    const orderByContext = { ...row }\n\n    // If there are select results, merge them at the top level for alias access\n    if (row.__select_results) {\n      // Add select results as top-level properties for alias access\n      Object.assign(orderByContext, row.__select_results)\n    }\n\n    if (orderByClause.length > 1) {\n      // For multiple orderBy columns, create a composite key\n      return compiledOrderBy.map((compiled) =>\n        compiled.compiledExpression(orderByContext)\n      )\n    } else if (orderByClause.length === 1) {\n      // For a single orderBy column, use the value directly\n      const compiled = compiledOrderBy[0]!\n      return compiled.compiledExpression(orderByContext)\n    }\n\n    // Default case - no ordering\n    return null\n  }\n\n  // Create a multi-property comparator that respects the order and direction of each property\n  const comparator = (a: unknown, b: unknown) => {\n    // If we're comparing arrays (multiple properties), compare each property in order\n    if (orderByClause.length > 1) {\n      const arrayA = a as Array<unknown>\n      const arrayB = b as Array<unknown>\n      for (let i = 0; i < orderByClause.length; i++) {\n        const clause = orderByClause[i]!\n        const compareFn = makeComparator(clause.compareOptions)\n        const result = compareFn(arrayA[i], arrayB[i])\n        if (result !== 0) {\n          return result\n        }\n      }\n      return arrayA.length - arrayB.length\n    }\n\n    // Single property comparison\n    if (orderByClause.length === 1) {\n      const clause = orderByClause[0]!\n      const compareFn = makeComparator(clause.compareOptions)\n      return compareFn(a, b)\n    }\n\n    return defaultComparator(a, b)\n  }\n\n  // Use fractional indexing and return the tuple [value, index]\n  return pipeline.pipe(\n    orderByWithFractionalIndex(valueExtractor, {\n      limit,\n      offset,\n      comparator,\n    })\n    // orderByWithFractionalIndex returns [key, [value, index]] - we keep this format\n  )\n}\n"],"names":["compileExpression","makeComparator","defaultComparator","orderByWithFractionalIndex"],"mappings":";;;;;AAYO,SAAS,eACd,UACA,eACA,OACA,QAC4D;AAE5D,QAAM,kBAAkB,cAAc,IAAI,CAAC,YAAY;AAAA,IACrD,oBAAoBA,WAAAA,kBAAkB,OAAO,UAAU;AAAA,IACvD,gBAAgB,OAAO;AAAA,EAAA,EACvB;AAGF,QAAM,iBAAiB,CAAC,QAAoD;AAM1E,UAAM,iBAAiB,EAAE,GAAG,IAAA;AAG5B,QAAI,IAAI,kBAAkB;AAExB,aAAO,OAAO,gBAAgB,IAAI,gBAAgB;AAAA,IACpD;AAEA,QAAI,cAAc,SAAS,GAAG;AAE5B,aAAO,gBAAgB;AAAA,QAAI,CAAC,aAC1B,SAAS,mBAAmB,cAAc;AAAA,MAAA;AAAA,IAE9C,WAAW,cAAc,WAAW,GAAG;AAErC,YAAM,WAAW,gBAAgB,CAAC;AAClC,aAAO,SAAS,mBAAmB,cAAc;AAAA,IACnD;AAGA,WAAO;AAAA,EACT;AAGA,QAAM,aAAa,CAAC,GAAY,MAAe;AAE7C,QAAI,cAAc,SAAS,GAAG;AAC5B,YAAM,SAAS;AACf,YAAM,SAAS;AACf,eAAS,IAAI,GAAG,IAAI,cAAc,QAAQ,KAAK;AAC7C,cAAM,SAAS,cAAc,CAAC;AAC9B,cAAM,YAAYC,WAAAA,eAAe,OAAO,cAAc;AACtD,cAAM,SAAS,UAAU,OAAO,CAAC,GAAG,OAAO,CAAC,CAAC;AAC7C,YAAI,WAAW,GAAG;AAChB,iBAAO;AAAA,QACT;AAAA,MACF;AACA,aAAO,OAAO,SAAS,OAAO;AAAA,IAChC;AAGA,QAAI,cAAc,WAAW,GAAG;AAC9B,YAAM,SAAS,cAAc,CAAC;AAC9B,YAAM,YAAYA,WAAAA,eAAe,OAAO,cAAc;AACtD,aAAO,UAAU,GAAG,CAAC;AAAA,IACvB;AAEA,WAAOC,WAAAA,kBAAkB,GAAG,CAAC;AAAA,EAC/B;AAGA,SAAO,SAAS;AAAA,IACdC,MAAAA,2BAA2B,gBAAgB;AAAA,MACzC;AAAA,MACA;AAAA,MACA;AAAA,IAAA,CACD;AAAA;AAAA,EAAA;AAGL;;"}

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

@@ -1 +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  distinct?: true\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 PropRef<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> = PropRef<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":";;AA6DA,MAAe,eAAwB;AAIvC;AAEO,MAAM,sBAAsB,eAAe;AAAA,EAEhD,YACS,YACA,OACP;AACA,UAAA;AAHO,SAAA,aAAA;AACA,SAAA,QAAA;AAHT,SAAO,OAAO;AAAA,EAMd;AACF;AAEO,MAAM,iBAAiB,eAAe;AAAA,EAE3C,YACS,OACA,OACP;AACA,UAAA;AAHO,SAAA,QAAA;AACA,SAAA,QAAA;AAHT,SAAO,OAAO;AAAA,EAMd;AACF;AAEO,MAAM,gBAAyB,eAAkB;AAAA,EAEtD,YACS,MACP;AACA,UAAA;AAFO,SAAA,OAAA;AAFT,SAAO,OAAO;AAAA,EAKd;AACF;AAEO,MAAM,cAAuB,eAAkB;AAAA,EAEpD,YACS,OACP;AACA,UAAA;AAFO,SAAA,QAAA;AAFT,SAAO,OAAO;AAAA,EAKd;AACF;AAEO,MAAM,aAAsB,eAAkB;AAAA,EAEnD,YACS,MACA,MACP;AACA,UAAA;AAHO,SAAA,OAAA;AACA,SAAA,OAAA;AAHT,SAAO,OAAO;AAAA,EAMd;AACF;AAOO,MAAM,kBAA2B,eAAkB;AAAA,EAExD,YACS,MACA,MACP;AACA,UAAA;AAHO,SAAA,OAAA;AACA,SAAA,OAAA;AAHT,SAAO,OAAO;AAAA,EAMd;AACF;;;;;;;"}
+{"version":3,"file":"ir.cjs","sources":["../../../src/query/ir.ts"],"sourcesContent":["/*\nThis is the intermediate representation of the query.\n*/\n\nimport type { CompareOptions } from \"./builder/types\"\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  distinct?: true\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  compareOptions: CompareOptions\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 PropRef<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> = PropRef<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":";;AA8DA,MAAe,eAAwB;AAIvC;AAEO,MAAM,sBAAsB,eAAe;AAAA,EAEhD,YACS,YACA,OACP;AACA,UAAA;AAHO,SAAA,aAAA;AACA,SAAA,QAAA;AAHT,SAAO,OAAO;AAAA,EAMd;AACF;AAEO,MAAM,iBAAiB,eAAe;AAAA,EAE3C,YACS,OACA,OACP;AACA,UAAA;AAHO,SAAA,QAAA;AACA,SAAA,QAAA;AAHT,SAAO,OAAO;AAAA,EAMd;AACF;AAEO,MAAM,gBAAyB,eAAkB;AAAA,EAEtD,YACS,MACP;AACA,UAAA;AAFO,SAAA,OAAA;AAFT,SAAO,OAAO;AAAA,EAKd;AACF;AAEO,MAAM,cAAuB,eAAkB;AAAA,EAEpD,YACS,OACP;AACA,UAAA;AAFO,SAAA,QAAA;AAFT,SAAO,OAAO;AAAA,EAKd;AACF;AAEO,MAAM,aAAsB,eAAkB;AAAA,EAEnD,YACS,MACA,MACP;AACA,UAAA;AAHO,SAAA,OAAA;AACA,SAAA,OAAA;AAHT,SAAO,OAAO;AAAA,EAMd;AACF;AAOO,MAAM,kBAA2B,eAAkB;AAAA,EAExD,YACS,MACA,MACP;AACA,UAAA;AAHO,SAAA,OAAA;AACA,SAAA,OAAA;AAHT,SAAO,OAAO;AAAA,EAMd;AACF;;;;;;;"}

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

@@ -1,3 +1,4 @@
+import { CompareOptions } from './builder/types.cjs';
 import { CollectionImpl } from '../collection.cjs';
 import { NamespacedRow } from '../types.cjs';
 export interface QueryIR {
@@ -32,7 +33,7 @@ export type Having = Where;
 export type OrderBy = Array<OrderByClause>;
 export type OrderByClause = {
     expression: BasicExpression;
-    direction: OrderByDirection;
+    compareOptions: CompareOptions;
 };
 export type OrderByDirection = `asc` | `desc`;
 export type Limit = number;

package/dist/cjs/transactions.cjs

@@ -231,6 +231,7 @@ class Transaction {
     this.setState(`persisting`);
     if (this.mutations.length === 0) {
       this.setState(`completed`);
+      this.isPersisted.resolve(this);
       return this;
     }
     try {

package/dist/cjs/transactions.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"transactions.cjs","sources":["../../src/transactions.ts"],"sourcesContent":["import { createDeferred } from \"./deferred\"\nimport {\n  MissingMutationFunctionError,\n  TransactionAlreadyCompletedRollbackError,\n  TransactionNotPendingCommitError,\n  TransactionNotPendingMutateError,\n} from \"./errors\"\nimport type { Deferred } from \"./deferred\"\nimport type {\n  MutationFn,\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\n/**\n * Creates a new transaction for grouping multiple collection operations\n * @param config - Transaction configuration with mutation function\n * @returns A new Transaction instance\n * @example\n * // Basic transaction usage\n * const tx = createTransaction({\n *   mutationFn: async ({ transaction }) => {\n *     // Send all mutations to API\n *     await api.saveChanges(transaction.mutations)\n *   }\n * })\n *\n * tx.mutate(() => {\n *   collection.insert({ id: \"1\", text: \"Buy milk\" })\n *   collection.update(\"2\", draft => { draft.completed = true })\n * })\n *\n * await tx.isPersisted.promise\n *\n * @example\n * // Handle transaction errors\n * try {\n *   const tx = createTransaction({\n *     mutationFn: async () => { throw new Error(\"API failed\") }\n *   })\n *\n *   tx.mutate(() => {\n *     collection.insert({ id: \"1\", text: \"New item\" })\n *   })\n *\n *   await tx.isPersisted.promise\n * } catch (error) {\n *   console.log('Transaction failed:', error)\n * }\n *\n * @example\n * // Manual commit control\n * const tx = createTransaction({\n *   autoCommit: false,\n *   mutationFn: async () => {\n *     // API call\n *   }\n * })\n *\n * tx.mutate(() => {\n *   collection.insert({ id: \"1\", text: \"Item\" })\n * })\n *\n * // Commit later\n * await tx.commit()\n */\nexport function createTransaction<T extends object = Record<string, unknown>>(\n  config: TransactionConfig<T>\n): Transaction<T> {\n  const newTransaction = new Transaction<T>(config)\n  transactions.push(newTransaction)\n  return newTransaction\n}\n\n/**\n * Gets the currently active ambient transaction, if any\n * Used internally by collection operations to join existing transactions\n * @returns The active transaction or undefined if none is active\n * @example\n * // Check if operations will join an ambient transaction\n * const ambientTx = getActiveTransaction()\n * if (ambientTx) {\n *   console.log('Operations will join transaction:', ambientTx.id)\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<T extends object = Record<string, unknown>> {\n  public id: string\n  public state: TransactionState\n  public mutationFn: MutationFn<T>\n  public mutations: Array<PendingMutation<T>>\n  public isPersisted: Deferred<Transaction<T>>\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 new MissingMutationFunctionError()\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>>()\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  /**\n   * Execute collection operations within this transaction\n   * @param callback - Function containing collection operations to group together\n   * @returns This transaction for chaining\n   * @example\n   * // Group multiple operations\n   * const tx = createTransaction({ mutationFn: async () => {\n   *   // Send to API\n   * }})\n   *\n   * tx.mutate(() => {\n   *   collection.insert({ id: \"1\", text: \"Buy milk\" })\n   *   collection.update(\"2\", draft => { draft.completed = true })\n   *   collection.delete(\"3\")\n   * })\n   *\n   * await tx.isPersisted.promise\n   *\n   * @example\n   * // Handle mutate errors\n   * try {\n   *   tx.mutate(() => {\n   *     collection.insert({ id: \"invalid\" }) // This might throw\n   *   })\n   * } catch (error) {\n   *   console.log('Mutation failed:', error)\n   * }\n   *\n   * @example\n   * // Manual commit control\n   * const tx = createTransaction({ autoCommit: false, mutationFn: async () => {} })\n   *\n   * tx.mutate(() => {\n   *   collection.insert({ id: \"1\", text: \"Item\" })\n   * })\n   *\n   * // Commit later when ready\n   * await tx.commit()\n   */\n  mutate(callback: () => void): Transaction<T> {\n    if (this.state !== `pending`) {\n      throw new TransactionNotPendingMutateError()\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  /**\n   * Rollback the transaction and any conflicting transactions\n   * @param config - Configuration for rollback behavior\n   * @returns This transaction for chaining\n   * @example\n   * // Manual rollback\n   * const tx = createTransaction({ mutationFn: async () => {\n   *   // Send to API\n   * }})\n   *\n   * tx.mutate(() => {\n   *   collection.insert({ id: \"1\", text: \"Buy milk\" })\n   * })\n   *\n   * // Rollback if needed\n   * if (shouldCancel) {\n   *   tx.rollback()\n   * }\n   *\n   * @example\n   * // Handle rollback cascade (automatic)\n   * const tx1 = createTransaction({ mutationFn: async () => {} })\n   * const tx2 = createTransaction({ mutationFn: async () => {} })\n   *\n   * tx1.mutate(() => collection.update(\"1\", draft => { draft.value = \"A\" }))\n   * tx2.mutate(() => collection.update(\"1\", draft => { draft.value = \"B\" })) // Same item\n   *\n   * tx1.rollback() // This will also rollback tx2 due to conflict\n   *\n   * @example\n   * // Handle rollback in error scenarios\n   * try {\n   *   await tx.isPersisted.promise\n   * } catch (error) {\n   *   console.log('Transaction was rolled back:', error)\n   *   // Transaction automatically rolled back on mutation function failure\n   * }\n   */\n  rollback(config?: { isSecondaryRollback?: boolean }): Transaction<T> {\n    const isSecondaryRollback = config?.isSecondaryRollback ?? false\n    if (this.state === `completed`) {\n      throw new TransactionAlreadyCompletedRollbackError()\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  /**\n   * Commit the transaction and execute the mutation function\n   * @returns Promise that resolves to this transaction when complete\n   * @example\n   * // Manual commit (when autoCommit is false)\n   * const tx = createTransaction({\n   *   autoCommit: false,\n   *   mutationFn: async ({ transaction }) => {\n   *     await api.saveChanges(transaction.mutations)\n   *   }\n   * })\n   *\n   * tx.mutate(() => {\n   *   collection.insert({ id: \"1\", text: \"Buy milk\" })\n   * })\n   *\n   * await tx.commit() // Manually commit\n   *\n   * @example\n   * // Handle commit errors\n   * try {\n   *   const tx = createTransaction({\n   *     mutationFn: async () => { throw new Error(\"API failed\") }\n   *   })\n   *\n   *   tx.mutate(() => {\n   *     collection.insert({ id: \"1\", text: \"Item\" })\n   *   })\n   *\n   *   await tx.commit()\n   * } catch (error) {\n   *   console.log('Commit failed, transaction rolled back:', error)\n   * }\n   *\n   * @example\n   * // Check transaction state after commit\n   * await tx.commit()\n   * console.log(tx.state) // \"completed\" or \"failed\"\n   */\n  async commit(): Promise<Transaction<T>> {\n    if (this.state !== `pending`) {\n      throw new TransactionNotPendingCommitError()\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":["MissingMutationFunctionError","createDeferred","TransactionNotPendingMutateError","TransactionAlreadyCompletedRollbackError","TransactionNotPendingCommitError"],"mappings":"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"}
+{"version":3,"file":"transactions.cjs","sources":["../../src/transactions.ts"],"sourcesContent":["import { createDeferred } from \"./deferred\"\nimport {\n  MissingMutationFunctionError,\n  TransactionAlreadyCompletedRollbackError,\n  TransactionNotPendingCommitError,\n  TransactionNotPendingMutateError,\n} from \"./errors\"\nimport type { Deferred } from \"./deferred\"\nimport type {\n  MutationFn,\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\n/**\n * Creates a new transaction for grouping multiple collection operations\n * @param config - Transaction configuration with mutation function\n * @returns A new Transaction instance\n * @example\n * // Basic transaction usage\n * const tx = createTransaction({\n *   mutationFn: async ({ transaction }) => {\n *     // Send all mutations to API\n *     await api.saveChanges(transaction.mutations)\n *   }\n * })\n *\n * tx.mutate(() => {\n *   collection.insert({ id: \"1\", text: \"Buy milk\" })\n *   collection.update(\"2\", draft => { draft.completed = true })\n * })\n *\n * await tx.isPersisted.promise\n *\n * @example\n * // Handle transaction errors\n * try {\n *   const tx = createTransaction({\n *     mutationFn: async () => { throw new Error(\"API failed\") }\n *   })\n *\n *   tx.mutate(() => {\n *     collection.insert({ id: \"1\", text: \"New item\" })\n *   })\n *\n *   await tx.isPersisted.promise\n * } catch (error) {\n *   console.log('Transaction failed:', error)\n * }\n *\n * @example\n * // Manual commit control\n * const tx = createTransaction({\n *   autoCommit: false,\n *   mutationFn: async () => {\n *     // API call\n *   }\n * })\n *\n * tx.mutate(() => {\n *   collection.insert({ id: \"1\", text: \"Item\" })\n * })\n *\n * // Commit later\n * await tx.commit()\n */\nexport function createTransaction<T extends object = Record<string, unknown>>(\n  config: TransactionConfig<T>\n): Transaction<T> {\n  const newTransaction = new Transaction<T>(config)\n  transactions.push(newTransaction)\n  return newTransaction\n}\n\n/**\n * Gets the currently active ambient transaction, if any\n * Used internally by collection operations to join existing transactions\n * @returns The active transaction or undefined if none is active\n * @example\n * // Check if operations will join an ambient transaction\n * const ambientTx = getActiveTransaction()\n * if (ambientTx) {\n *   console.log('Operations will join transaction:', ambientTx.id)\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<T extends object = Record<string, unknown>> {\n  public id: string\n  public state: TransactionState\n  public mutationFn: MutationFn<T>\n  public mutations: Array<PendingMutation<T>>\n  public isPersisted: Deferred<Transaction<T>>\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 new MissingMutationFunctionError()\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>>()\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  /**\n   * Execute collection operations within this transaction\n   * @param callback - Function containing collection operations to group together\n   * @returns This transaction for chaining\n   * @example\n   * // Group multiple operations\n   * const tx = createTransaction({ mutationFn: async () => {\n   *   // Send to API\n   * }})\n   *\n   * tx.mutate(() => {\n   *   collection.insert({ id: \"1\", text: \"Buy milk\" })\n   *   collection.update(\"2\", draft => { draft.completed = true })\n   *   collection.delete(\"3\")\n   * })\n   *\n   * await tx.isPersisted.promise\n   *\n   * @example\n   * // Handle mutate errors\n   * try {\n   *   tx.mutate(() => {\n   *     collection.insert({ id: \"invalid\" }) // This might throw\n   *   })\n   * } catch (error) {\n   *   console.log('Mutation failed:', error)\n   * }\n   *\n   * @example\n   * // Manual commit control\n   * const tx = createTransaction({ autoCommit: false, mutationFn: async () => {} })\n   *\n   * tx.mutate(() => {\n   *   collection.insert({ id: \"1\", text: \"Item\" })\n   * })\n   *\n   * // Commit later when ready\n   * await tx.commit()\n   */\n  mutate(callback: () => void): Transaction<T> {\n    if (this.state !== `pending`) {\n      throw new TransactionNotPendingMutateError()\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  /**\n   * Rollback the transaction and any conflicting transactions\n   * @param config - Configuration for rollback behavior\n   * @returns This transaction for chaining\n   * @example\n   * // Manual rollback\n   * const tx = createTransaction({ mutationFn: async () => {\n   *   // Send to API\n   * }})\n   *\n   * tx.mutate(() => {\n   *   collection.insert({ id: \"1\", text: \"Buy milk\" })\n   * })\n   *\n   * // Rollback if needed\n   * if (shouldCancel) {\n   *   tx.rollback()\n   * }\n   *\n   * @example\n   * // Handle rollback cascade (automatic)\n   * const tx1 = createTransaction({ mutationFn: async () => {} })\n   * const tx2 = createTransaction({ mutationFn: async () => {} })\n   *\n   * tx1.mutate(() => collection.update(\"1\", draft => { draft.value = \"A\" }))\n   * tx2.mutate(() => collection.update(\"1\", draft => { draft.value = \"B\" })) // Same item\n   *\n   * tx1.rollback() // This will also rollback tx2 due to conflict\n   *\n   * @example\n   * // Handle rollback in error scenarios\n   * try {\n   *   await tx.isPersisted.promise\n   * } catch (error) {\n   *   console.log('Transaction was rolled back:', error)\n   *   // Transaction automatically rolled back on mutation function failure\n   * }\n   */\n  rollback(config?: { isSecondaryRollback?: boolean }): Transaction<T> {\n    const isSecondaryRollback = config?.isSecondaryRollback ?? false\n    if (this.state === `completed`) {\n      throw new TransactionAlreadyCompletedRollbackError()\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  /**\n   * Commit the transaction and execute the mutation function\n   * @returns Promise that resolves to this transaction when complete\n   * @example\n   * // Manual commit (when autoCommit is false)\n   * const tx = createTransaction({\n   *   autoCommit: false,\n   *   mutationFn: async ({ transaction }) => {\n   *     await api.saveChanges(transaction.mutations)\n   *   }\n   * })\n   *\n   * tx.mutate(() => {\n   *   collection.insert({ id: \"1\", text: \"Buy milk\" })\n   * })\n   *\n   * await tx.commit() // Manually commit\n   *\n   * @example\n   * // Handle commit errors\n   * try {\n   *   const tx = createTransaction({\n   *     mutationFn: async () => { throw new Error(\"API failed\") }\n   *   })\n   *\n   *   tx.mutate(() => {\n   *     collection.insert({ id: \"1\", text: \"Item\" })\n   *   })\n   *\n   *   await tx.commit()\n   * } catch (error) {\n   *   console.log('Commit failed, transaction rolled back:', error)\n   * }\n   *\n   * @example\n   * // Check transaction state after commit\n   * await tx.commit()\n   * console.log(tx.state) // \"completed\" or \"failed\"\n   */\n  async commit(): Promise<Transaction<T>> {\n    if (this.state !== `pending`) {\n      throw new TransactionNotPendingCommitError()\n    }\n\n    this.setState(`persisting`)\n\n    if (this.mutations.length === 0) {\n      this.setState(`completed`)\n      this.isPersisted.resolve(this)\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":["MissingMutationFunctionError","createDeferred","TransactionNotPendingMutateError","TransactionAlreadyCompletedRollbackError","TransactionNotPendingCommitError"],"mappings":"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"}

package/dist/cjs/utils/comparison.cjs

@@ -10,16 +10,19 @@ function getObjectId(obj) {
   objectIds.set(obj, id);
   return id;
 }
-const ascComparator = (a, b) => {
+const ascComparator = (a, b, opts) => {
+  const { nulls } = opts;
   if (a == null && b == null) return 0;
-  if (a == null) return -1;
-  if (b == null) return 1;
+  if (a == null) return nulls === `first` ? -1 : 1;
+  if (b == null) return nulls === `first` ? 1 : -1;
   if (typeof a === `string` && typeof b === `string`) {
-    return a.localeCompare(b);
+    if (opts.stringSort === `locale`) {
+      return a.localeCompare(b, opts.locale, opts.localeOptions);
+    }
   }
   if (Array.isArray(a) && Array.isArray(b)) {
     for (let i = 0; i < Math.min(a.length, b.length); i++) {
-      const result = ascComparator(a[i], b[i]);
+      const result = ascComparator(a[i], b[i], opts);
       if (result !== 0) {
         return result;
       }
@@ -44,9 +47,28 @@ const ascComparator = (a, b) => {
   if (a > b) return 1;
   return 0;
 };
-const descComparator = (a, b) => {
-  return ascComparator(b, a);
+const descComparator = (a, b, opts) => {
+  return ascComparator(b, a, {
+    ...opts,
+    nulls: opts.nulls === `first` ? `last` : `first`
+  });
 };
+function makeComparator(opts) {
+  return (a, b) => {
+    if (opts.direction === `asc`) {
+      return ascComparator(a, b, opts);
+    } else {
+      return descComparator(a, b, opts);
+    }
+  };
+}
+const defaultComparator = makeComparator({
+  direction: `asc`,
+  nulls: `first`,
+  stringSort: `locale`
+});
 exports.ascComparator = ascComparator;
+exports.defaultComparator = defaultComparator;
 exports.descComparator = descComparator;
+exports.makeComparator = makeComparator;
 //# sourceMappingURL=comparison.cjs.map

package/dist/cjs/utils/comparison.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"comparison.cjs","sources":["../../../src/utils/comparison.ts"],"sourcesContent":["// WeakMap to store stable IDs for objects\nconst objectIds = new WeakMap<object, number>()\nlet nextObjectId = 1\n\n/**\n * Get or create a stable ID for an object\n */\nfunction getObjectId(obj: object): number {\n  if (objectIds.has(obj)) {\n    return objectIds.get(obj)!\n  }\n  const id = nextObjectId++\n  objectIds.set(obj, id)\n  return id\n}\n\n/**\n * Universal comparison function for all data types\n * Handles null/undefined, strings, arrays, dates, objects, and primitives\n * Always sorts null/undefined values first\n */\nexport const ascComparator = (a: any, b: any): number => {\n  // Handle null/undefined\n  if (a == null && b == null) return 0\n  if (a == null) return -1\n  if (b == null) return 1\n\n  // if a and b are both strings, compare them based on locale\n  if (typeof a === `string` && typeof b === `string`) {\n    return a.localeCompare(b)\n  }\n\n  // if a and b are both arrays, compare them element by element\n  if (Array.isArray(a) && Array.isArray(b)) {\n    for (let i = 0; i < Math.min(a.length, b.length); i++) {\n      const result = ascComparator(a[i], b[i])\n      if (result !== 0) {\n        return result\n      }\n    }\n    // All elements are equal up to the minimum length\n    return a.length - b.length\n  }\n\n  // If both are dates, compare them\n  if (a instanceof Date && b instanceof Date) {\n    return a.getTime() - b.getTime()\n  }\n\n  // If at least one of the values is an object, use stable IDs for comparison\n  const aIsObject = typeof a === `object`\n  const bIsObject = typeof b === `object`\n\n  if (aIsObject || bIsObject) {\n    // If both are objects, compare their stable IDs\n    if (aIsObject && bIsObject) {\n      const aId = getObjectId(a)\n      const bId = getObjectId(b)\n      return aId - bId\n    }\n\n    // If only one is an object, objects come after primitives\n    if (aIsObject) return 1\n    if (bIsObject) return -1\n  }\n\n  // For primitive values, use direct comparison\n  if (a < b) return -1\n  if (a > b) return 1\n  return 0\n}\n\n/**\n * Descending comparator function for ordering values\n * Handles null/undefined as largest values (opposite of ascending)\n */\nexport const descComparator = (a: unknown, b: unknown): number => {\n  return ascComparator(b, a)\n}\n"],"names":[],"mappings":";;AACA,MAAM,gCAAgB,QAAA;AACtB,IAAI,eAAe;AAKnB,SAAS,YAAY,KAAqB;AACxC,MAAI,UAAU,IAAI,GAAG,GAAG;AACtB,WAAO,UAAU,IAAI,GAAG;AAAA,EAC1B;AACA,QAAM,KAAK;AACX,YAAU,IAAI,KAAK,EAAE;AACrB,SAAO;AACT;AAOO,MAAM,gBAAgB,CAAC,GAAQ,MAAmB;AAEvD,MAAI,KAAK,QAAQ,KAAK,KAAM,QAAO;AACnC,MAAI,KAAK,KAAM,QAAO;AACtB,MAAI,KAAK,KAAM,QAAO;AAGtB,MAAI,OAAO,MAAM,YAAY,OAAO,MAAM,UAAU;AAClD,WAAO,EAAE,cAAc,CAAC;AAAA,EAC1B;AAGA,MAAI,MAAM,QAAQ,CAAC,KAAK,MAAM,QAAQ,CAAC,GAAG;AACxC,aAAS,IAAI,GAAG,IAAI,KAAK,IAAI,EAAE,QAAQ,EAAE,MAAM,GAAG,KAAK;AACrD,YAAM,SAAS,cAAc,EAAE,CAAC,GAAG,EAAE,CAAC,CAAC;AACvC,UAAI,WAAW,GAAG;AAChB,eAAO;AAAA,MACT;AAAA,IACF;AAEA,WAAO,EAAE,SAAS,EAAE;AAAA,EACtB;AAGA,MAAI,aAAa,QAAQ,aAAa,MAAM;AAC1C,WAAO,EAAE,YAAY,EAAE,QAAA;AAAA,EACzB;AAGA,QAAM,YAAY,OAAO,MAAM;AAC/B,QAAM,YAAY,OAAO,MAAM;AAE/B,MAAI,aAAa,WAAW;AAE1B,QAAI,aAAa,WAAW;AAC1B,YAAM,MAAM,YAAY,CAAC;AACzB,YAAM,MAAM,YAAY,CAAC;AACzB,aAAO,MAAM;AAAA,IACf;AAGA,QAAI,UAAW,QAAO;AACtB,QAAI,UAAW,QAAO;AAAA,EACxB;AAGA,MAAI,IAAI,EAAG,QAAO;AAClB,MAAI,IAAI,EAAG,QAAO;AAClB,SAAO;AACT;AAMO,MAAM,iBAAiB,CAAC,GAAY,MAAuB;AAChE,SAAO,cAAc,GAAG,CAAC;AAC3B;;;"}
+{"version":3,"file":"comparison.cjs","sources":["../../../src/utils/comparison.ts"],"sourcesContent":["import type { CompareOptions } from \"../query/builder/types\"\n\n// WeakMap to store stable IDs for objects\nconst objectIds = new WeakMap<object, number>()\nlet nextObjectId = 1\n\n/**\n * Get or create a stable ID for an object\n */\nfunction getObjectId(obj: object): number {\n  if (objectIds.has(obj)) {\n    return objectIds.get(obj)!\n  }\n  const id = nextObjectId++\n  objectIds.set(obj, id)\n  return id\n}\n\n/**\n * Universal comparison function for all data types\n * Handles null/undefined, strings, arrays, dates, objects, and primitives\n * Always sorts null/undefined values first\n */\nexport const ascComparator = (a: any, b: any, opts: CompareOptions): number => {\n  const { nulls } = opts\n\n  // Handle null/undefined\n  if (a == null && b == null) return 0\n  if (a == null) return nulls === `first` ? -1 : 1\n  if (b == null) return nulls === `first` ? 1 : -1\n\n  // if a and b are both strings, compare them based on locale\n  if (typeof a === `string` && typeof b === `string`) {\n    if (opts.stringSort === `locale`) {\n      return a.localeCompare(b, opts.locale, opts.localeOptions)\n    }\n    // For lexical sort we rely on direct comparison for primitive values\n  }\n\n  // if a and b are both arrays, compare them element by element\n  if (Array.isArray(a) && Array.isArray(b)) {\n    for (let i = 0; i < Math.min(a.length, b.length); i++) {\n      const result = ascComparator(a[i], b[i], opts)\n      if (result !== 0) {\n        return result\n      }\n    }\n    // All elements are equal up to the minimum length\n    return a.length - b.length\n  }\n\n  // If both are dates, compare them\n  if (a instanceof Date && b instanceof Date) {\n    return a.getTime() - b.getTime()\n  }\n\n  // If at least one of the values is an object, use stable IDs for comparison\n  const aIsObject = typeof a === `object`\n  const bIsObject = typeof b === `object`\n\n  if (aIsObject || bIsObject) {\n    // If both are objects, compare their stable IDs\n    if (aIsObject && bIsObject) {\n      const aId = getObjectId(a)\n      const bId = getObjectId(b)\n      return aId - bId\n    }\n\n    // If only one is an object, objects come after primitives\n    if (aIsObject) return 1\n    if (bIsObject) return -1\n  }\n\n  // For primitive values, use direct comparison\n  if (a < b) return -1\n  if (a > b) return 1\n  return 0\n}\n\n/**\n * Descending comparator function for ordering values\n * Handles null/undefined as largest values (opposite of ascending)\n */\nexport const descComparator = (\n  a: unknown,\n  b: unknown,\n  opts: CompareOptions\n): number => {\n  return ascComparator(b, a, {\n    ...opts,\n    nulls: opts.nulls === `first` ? `last` : `first`,\n  })\n}\n\nexport function makeComparator(\n  opts: CompareOptions\n): (a: any, b: any) => number {\n  return (a, b) => {\n    if (opts.direction === `asc`) {\n      return ascComparator(a, b, opts)\n    } else {\n      return descComparator(a, b, opts)\n    }\n  }\n}\n\n/** Default comparator orders values in ascending order with nulls first and locale string comparison. */\nexport const defaultComparator = makeComparator({\n  direction: `asc`,\n  nulls: `first`,\n  stringSort: `locale`,\n})\n"],"names":[],"mappings":";;AAGA,MAAM,gCAAgB,QAAA;AACtB,IAAI,eAAe;AAKnB,SAAS,YAAY,KAAqB;AACxC,MAAI,UAAU,IAAI,GAAG,GAAG;AACtB,WAAO,UAAU,IAAI,GAAG;AAAA,EAC1B;AACA,QAAM,KAAK;AACX,YAAU,IAAI,KAAK,EAAE;AACrB,SAAO;AACT;AAOO,MAAM,gBAAgB,CAAC,GAAQ,GAAQ,SAAiC;AAC7E,QAAM,EAAE,UAAU;AAGlB,MAAI,KAAK,QAAQ,KAAK,KAAM,QAAO;AACnC,MAAI,KAAK,KAAM,QAAO,UAAU,UAAU,KAAK;AAC/C,MAAI,KAAK,KAAM,QAAO,UAAU,UAAU,IAAI;AAG9C,MAAI,OAAO,MAAM,YAAY,OAAO,MAAM,UAAU;AAClD,QAAI,KAAK,eAAe,UAAU;AAChC,aAAO,EAAE,cAAc,GAAG,KAAK,QAAQ,KAAK,aAAa;AAAA,IAC3D;AAAA,EAEF;AAGA,MAAI,MAAM,QAAQ,CAAC,KAAK,MAAM,QAAQ,CAAC,GAAG;AACxC,aAAS,IAAI,GAAG,IAAI,KAAK,IAAI,EAAE,QAAQ,EAAE,MAAM,GAAG,KAAK;AACrD,YAAM,SAAS,cAAc,EAAE,CAAC,GAAG,EAAE,CAAC,GAAG,IAAI;AAC7C,UAAI,WAAW,GAAG;AAChB,eAAO;AAAA,MACT;AAAA,IACF;AAEA,WAAO,EAAE,SAAS,EAAE;AAAA,EACtB;AAGA,MAAI,aAAa,QAAQ,aAAa,MAAM;AAC1C,WAAO,EAAE,YAAY,EAAE,QAAA;AAAA,EACzB;AAGA,QAAM,YAAY,OAAO,MAAM;AAC/B,QAAM,YAAY,OAAO,MAAM;AAE/B,MAAI,aAAa,WAAW;AAE1B,QAAI,aAAa,WAAW;AAC1B,YAAM,MAAM,YAAY,CAAC;AACzB,YAAM,MAAM,YAAY,CAAC;AACzB,aAAO,MAAM;AAAA,IACf;AAGA,QAAI,UAAW,QAAO;AACtB,QAAI,UAAW,QAAO;AAAA,EACxB;AAGA,MAAI,IAAI,EAAG,QAAO;AAClB,MAAI,IAAI,EAAG,QAAO;AAClB,SAAO;AACT;AAMO,MAAM,iBAAiB,CAC5B,GACA,GACA,SACW;AACX,SAAO,cAAc,GAAG,GAAG;AAAA,IACzB,GAAG;AAAA,IACH,OAAO,KAAK,UAAU,UAAU,SAAS;AAAA,EAAA,CAC1C;AACH;AAEO,SAAS,eACd,MAC4B;AAC5B,SAAO,CAAC,GAAG,MAAM;AACf,QAAI,KAAK,cAAc,OAAO;AAC5B,aAAO,cAAc,GAAG,GAAG,IAAI;AAAA,IACjC,OAAO;AACL,aAAO,eAAe,GAAG,GAAG,IAAI;AAAA,IAClC;AAAA,EACF;AACF;AAGO,MAAM,oBAAoB,eAAe;AAAA,EAC9C,WAAW;AAAA,EACX,OAAO;AAAA,EACP,YAAY;AACd,CAAC;;;;;"}

package/dist/cjs/utils/comparison.d.cts

@@ -1,11 +1,15 @@
+import { CompareOptions } from '../query/builder/types.cjs';
 /**
  * Universal comparison function for all data types
  * Handles null/undefined, strings, arrays, dates, objects, and primitives
  * Always sorts null/undefined values first
  */
-export declare const ascComparator: (a: any, b: any) => number;
+export declare const ascComparator: (a: any, b: any, opts: CompareOptions) => number;
 /**
  * Descending comparator function for ordering values
  * Handles null/undefined as largest values (opposite of ascending)
  */
-export declare const descComparator: (a: unknown, b: unknown) => number;
+export declare const descComparator: (a: unknown, b: unknown, opts: CompareOptions) => number;
+export declare function makeComparator(opts: CompareOptions): (a: any, b: any) => number;
+/** Default comparator orders values in ascending order with nulls first and locale string comparison. */
+export declare const defaultComparator: (a: any, b: any) => number;

package/dist/esm/collection.d.ts

@@ -92,8 +92,16 @@ export interface Collection<T extends object = Record<string, unknown>, TKey ext
  *   sync: { sync: () => {} }
  * })
  *
- * // Note: You must provide either an explicit type or a schema, but not both.
+ * // Note: You can provide an explicit type, a schema, or both. When both are provided, the explicit type takes precedence.
  */
+export declare function createCollection<TSchema extends StandardSchemaV1, TKey extends string | number = string | number, TUtils extends UtilsRecord = {}, TFallback extends object = Record<string, unknown>>(options: CollectionConfig<ResolveType<unknown, TSchema, TFallback>, TKey, TSchema, ResolveInsertInput<unknown, TSchema, TFallback>> & {
+    schema: TSchema;
+    utils?: TUtils;
+}): Collection<ResolveType<unknown, TSchema, TFallback>, TKey, TUtils, TSchema, ResolveInsertInput<unknown, TSchema, TFallback>>;
+export declare function createCollection<TExplicit extends object, TKey extends string | number = string | number, TUtils extends UtilsRecord = {}, TSchema extends StandardSchemaV1 = StandardSchemaV1, TFallback extends object = Record<string, unknown>>(options: CollectionConfig<ResolveType<TExplicit, TSchema, TFallback>, TKey, TSchema, ResolveInsertInput<TExplicit, TSchema, TFallback>> & {
+    schema: TSchema;
+    utils?: TUtils;
+}): Collection<ResolveType<TExplicit, TSchema, TFallback>, TKey, TUtils, TSchema, ResolveInsertInput<TExplicit, TSchema, TFallback>>;
 export declare function createCollection<TExplicit = unknown, TKey extends string | number = string | number, TUtils extends UtilsRecord = {}, TSchema extends StandardSchemaV1 = StandardSchemaV1, TFallback extends object = Record<string, unknown>>(options: CollectionConfig<ResolveType<TExplicit, TSchema, TFallback>, TKey, TSchema, ResolveInsertInput<TExplicit, TSchema, TFallback>> & {
     utils?: TUtils;
 }): Collection<ResolveType<TExplicit, TSchema, TFallback>, TKey, TUtils, TSchema, ResolveInsertInput<TExplicit, TSchema, TFallback>>;
@@ -289,6 +297,11 @@ export declare class CollectionImpl<T extends object = Record<string, unknown>,
      * This method processes operations from pending transactions and applies them to the synced data
      */
     commitPendingTransactions: () => void;
+    /**
+     * Schedule cleanup of a transaction when it completes
+     * @private
+     */
+    private scheduleTransactionCleanup;
     private ensureStandardSchema;
     getKeyFromItem(item: T): TKey;
     generateGlobalKey(key: any, item: any): string;
@@ -343,7 +356,7 @@ export declare class CollectionImpl<T extends object = Record<string, unknown>,
      */
     private updateIndexes;
     private deepEqual;
-    private validateData;
+    validateData(data: unknown, type: `insert` | `update`, key?: TKey): T | never;
     /**
      * Inserts one or more items into the collection
      * @param items - Single item or array of items to insert

package/dist/esm/collection.js

@@ -252,6 +252,7 @@ class CollectionImpl {
       if (ambientTransaction) {
         ambientTransaction.applyMutations(mutations);
         this.transactions.set(ambientTransaction.id, ambientTransaction);
+        this.scheduleTransactionCleanup(ambientTransaction);
         this.recomputeOptimisticState(true);
         return ambientTransaction;
       } else {
@@ -266,6 +267,7 @@ class CollectionImpl {
         directOpTransaction.applyMutations(mutations);
         directOpTransaction.commit();
         this.transactions.set(directOpTransaction.id, directOpTransaction);
+        this.scheduleTransactionCleanup(directOpTransaction);
         this.recomputeOptimisticState(true);
         return directOpTransaction;
       }
@@ -306,6 +308,7 @@ class CollectionImpl {
       if (ambientTransaction) {
         ambientTransaction.applyMutations(mutations);
         this.transactions.set(ambientTransaction.id, ambientTransaction);
+        this.scheduleTransactionCleanup(ambientTransaction);
         this.recomputeOptimisticState(true);
         return ambientTransaction;
       }
@@ -321,6 +324,7 @@ class CollectionImpl {
       directOpTransaction.applyMutations(mutations);
       directOpTransaction.commit();
       this.transactions.set(directOpTransaction.id, directOpTransaction);
+      this.scheduleTransactionCleanup(directOpTransaction);
       this.recomputeOptimisticState(true);
       return directOpTransaction;
     };
@@ -661,11 +665,8 @@ class CollectionImpl {
     this.optimisticUpserts.clear();
     this.optimisticDeletes.clear();
     const activeTransactions = [];
-    const completedTransactions = [];
     for (const transaction of this.transactions.values()) {
-      if (transaction.state === `completed`) {
-        completedTransactions.push(transaction);
-      } else if (![`completed`, `failed`].includes(transaction.state)) {
+      if (![`completed`, `failed`].includes(transaction.state)) {
         activeTransactions.push(transaction);
       }
     }
@@ -700,19 +701,11 @@ class CollectionImpl {
     });
     if (this.pendingSyncedTransactions.length > 0 && !triggeredByUserAction) {
       const pendingSyncKeys = /* @__PURE__ */ new Set();
-      const completedTransactionMutations = /* @__PURE__ */ new Set();
       for (const transaction of this.pendingSyncedTransactions) {
         for (const operation of transaction.operations) {
           pendingSyncKeys.add(operation.key);
         }
       }
-      for (const tx of completedTransactions) {
-        for (const mutation of tx.mutations) {
-          if (mutation.collection === this) {
-            completedTransactionMutations.add(mutation.mutationId);
-          }
-        }
-      }
       const filteredEvents = filteredEventsBySyncStatus.filter((event) => {
         if (event.type === `delete` && pendingSyncKeys.has(event.key)) {
           const hasActiveOptimisticMutation = activeTransactions.some(
@@ -933,6 +926,20 @@ class CollectionImpl {
     }
     return result;
   }
+  /**
+   * Schedule cleanup of a transaction when it completes
+   * @private
+   */
+  scheduleTransactionCleanup(transaction) {
+    if (transaction.state === `completed`) {
+      this.transactions.delete(transaction.id);
+      return;
+    }
+    transaction.isPersisted.promise.then(() => {
+      this.transactions.delete(transaction.id);
+    }).catch(() => {
+    });
+  }
   ensureStandardSchema(schema) {
     if (schema && `~standard` in schema) {
       return schema;
@@ -1213,11 +1220,13 @@ class CollectionImpl {
         }
       });
       emptyTransaction.commit();
+      this.scheduleTransactionCleanup(emptyTransaction);
       return emptyTransaction;
     }
     if (ambientTransaction) {
       ambientTransaction.applyMutations(mutations);
       this.transactions.set(ambientTransaction.id, ambientTransaction);
+      this.scheduleTransactionCleanup(ambientTransaction);
       this.recomputeOptimisticState(true);
       return ambientTransaction;
     }
@@ -1232,6 +1241,7 @@ class CollectionImpl {
     directOpTransaction.applyMutations(mutations);
     directOpTransaction.commit();
     this.transactions.set(directOpTransaction.id, directOpTransaction);
+    this.scheduleTransactionCleanup(directOpTransaction);
     this.recomputeOptimisticState(true);
     return directOpTransaction;
   }