@tanstack/db 0.5.33 → 0.6.1

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 { CompareOptions } from './builder/types'\nimport type { Collection, CollectionImpl } from '../collection/index.js'\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  singleResult?: 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 | Select\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 =\n  | BasicExpression<boolean>\n  | { expression: BasicExpression<boolean>; residual?: 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\n/**\n * Runtime helper to detect IR expression-like objects.\n * Prefer this over ad-hoc local implementations to keep behavior consistent.\n */\nexport function isExpressionLike(value: any): boolean {\n  return (\n    value instanceof Aggregate ||\n    value instanceof Func ||\n    value instanceof PropRef ||\n    value instanceof Value\n  )\n}\n\n/**\n * Helper functions for working with Where clauses\n */\n\n/**\n * Extract the expression from a Where clause\n */\nexport function getWhereExpression(where: Where): BasicExpression<boolean> {\n  return typeof where === `object` && `expression` in where\n    ? where.expression\n    : where\n}\n\n/**\n * Extract the expression from a HAVING clause\n * HAVING clauses can contain aggregates, unlike regular WHERE clauses\n */\nexport function getHavingExpression(\n  having: Having,\n): BasicExpression | Aggregate {\n  return typeof having === `object` && `expression` in having\n    ? having.expression\n    : having\n}\n\n/**\n * Check if a Where clause is marked as residual\n */\nexport function isResidualWhere(where: Where): boolean {\n  return (\n    typeof where === `object` &&\n    `expression` in where &&\n    where.residual === true\n  )\n}\n\n/**\n * Create a residual Where clause from an expression\n */\nexport function createResidualWhere(\n  expression: BasicExpression<boolean>,\n): Where {\n  return { expression, residual: true }\n}\n\nfunction getRefFromAlias(\n  query: QueryIR,\n  alias: string,\n): CollectionRef | QueryRef | void {\n  if (query.from.alias === alias) {\n    return query.from\n  }\n\n  for (const join of query.join || []) {\n    if (join.from.alias === alias) {\n      return join.from\n    }\n  }\n}\n\n/**\n * Follows the given reference in a query\n * until its finds the root field the reference points to.\n * @returns The collection, its alias, and the path to the root field in this collection\n */\nexport function followRef(\n  query: QueryIR,\n  ref: PropRef<any>,\n  collection: Collection,\n): { collection: Collection; path: Array<string> } | void {\n  if (ref.path.length === 0) {\n    return\n  }\n\n  if (ref.path.length === 1) {\n    // This field should be part of this collection\n    const field = ref.path[0]!\n    // is it part of the select clause?\n    if (query.select) {\n      const selectedField = query.select[field]\n      if (selectedField && selectedField.type === `ref`) {\n        return followRef(query, selectedField, collection)\n      }\n    }\n\n    // Either this field is not part of the select clause\n    // and thus it must be part of the collection itself\n    // or it is part of the select but is not a reference\n    // so we can stop here and don't have to follow it\n    return { collection, path: [field] }\n  }\n\n  if (ref.path.length > 1) {\n    // This is a nested field\n    const [alias, ...rest] = ref.path\n    const aliasRef = getRefFromAlias(query, alias!)\n    if (!aliasRef) {\n      return\n    }\n\n    if (aliasRef.type === `queryRef`) {\n      return followRef(aliasRef.query, new PropRef(rest), collection)\n    } else {\n      // This is a reference to a collection\n      // we can't follow it further\n      // so the field must be on the collection itself\n      return { collection: aliasRef.collection, path: rest }\n    }\n  }\n}\n"],"names":[],"mappings":";;AAiEA,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;AAMO,SAAS,iBAAiB,OAAqB;AACpD,SACE,iBAAiB,aACjB,iBAAiB,QACjB,iBAAiB,WACjB,iBAAiB;AAErB;AASO,SAAS,mBAAmB,OAAwC;AACzE,SAAO,OAAO,UAAU,YAAY,gBAAgB,QAChD,MAAM,aACN;AACN;AAMO,SAAS,oBACd,QAC6B;AAC7B,SAAO,OAAO,WAAW,YAAY,gBAAgB,SACjD,OAAO,aACP;AACN;AAKO,SAAS,gBAAgB,OAAuB;AACrD,SACE,OAAO,UAAU,YACjB,gBAAgB,SAChB,MAAM,aAAa;AAEvB;AAKO,SAAS,oBACd,YACO;AACP,SAAO,EAAE,YAAY,UAAU,KAAA;AACjC;AAEA,SAAS,gBACP,OACA,OACiC;AACjC,MAAI,MAAM,KAAK,UAAU,OAAO;AAC9B,WAAO,MAAM;AAAA,EACf;AAEA,aAAW,QAAQ,MAAM,QAAQ,CAAA,GAAI;AACnC,QAAI,KAAK,KAAK,UAAU,OAAO;AAC7B,aAAO,KAAK;AAAA,IACd;AAAA,EACF;AACF;AAOO,SAAS,UACd,OACA,KACA,YACwD;AACxD,MAAI,IAAI,KAAK,WAAW,GAAG;AACzB;AAAA,EACF;AAEA,MAAI,IAAI,KAAK,WAAW,GAAG;AAEzB,UAAM,QAAQ,IAAI,KAAK,CAAC;AAExB,QAAI,MAAM,QAAQ;AAChB,YAAM,gBAAgB,MAAM,OAAO,KAAK;AACxC,UAAI,iBAAiB,cAAc,SAAS,OAAO;AACjD,eAAO,UAAU,OAAO,eAAe,UAAU;AAAA,MACnD;AAAA,IACF;AAMA,WAAO,EAAE,YAAY,MAAM,CAAC,KAAK,EAAA;AAAA,EACnC;AAEA,MAAI,IAAI,KAAK,SAAS,GAAG;AAEvB,UAAM,CAAC,OAAO,GAAG,IAAI,IAAI,IAAI;AAC7B,UAAM,WAAW,gBAAgB,OAAO,KAAM;AAC9C,QAAI,CAAC,UAAU;AACb;AAAA,IACF;AAEA,QAAI,SAAS,SAAS,YAAY;AAChC,aAAO,UAAU,SAAS,OAAO,IAAI,QAAQ,IAAI,GAAG,UAAU;AAAA,IAChE,OAAO;AAIL,aAAO,EAAE,YAAY,SAAS,YAAY,MAAM,KAAA;AAAA,IAClD;AAAA,EACF;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 { Collection, CollectionImpl } from '../collection/index.js'\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  singleResult?: 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 IncludesMaterialization = `collection` | `array` | `concat`\n\nexport const INCLUDES_SCALAR_FIELD = `__includes_scalar__`\n\nexport type From = CollectionRef | QueryRef\n\nexport type Select = {\n  [alias: string]: BasicExpression | Aggregate | Select | IncludesSubquery\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 =\n  | BasicExpression<boolean>\n  | { expression: BasicExpression<boolean>; residual?: 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\nexport class IncludesSubquery extends BaseExpression {\n  public type = `includesSubquery` as const\n  constructor(\n    public query: QueryIR, // Child query (correlation WHERE removed)\n    public correlationField: PropRef, // Parent-side ref (e.g., project.id)\n    public childCorrelationField: PropRef, // Child-side ref (e.g., issue.projectId)\n    public fieldName: string, // Result field name (e.g., \"issues\")\n    public parentFilters?: Array<Where>, // WHERE clauses referencing parent aliases (applied post-join)\n    public parentProjection?: Array<PropRef>, // Parent field refs used by parentFilters\n    public materialization: IncludesMaterialization = `collection`,\n    public scalarField?: string,\n  ) {\n    super()\n  }\n}\n\n/**\n * Runtime helper to detect IR expression-like objects.\n * Prefer this over ad-hoc local implementations to keep behavior consistent.\n */\nexport function isExpressionLike(value: any): boolean {\n  return (\n    value instanceof Aggregate ||\n    value instanceof Func ||\n    value instanceof PropRef ||\n    value instanceof Value ||\n    value instanceof IncludesSubquery\n  )\n}\n\n/**\n * Helper functions for working with Where clauses\n */\n\n/**\n * Extract the expression from a Where clause\n */\nexport function getWhereExpression(where: Where): BasicExpression<boolean> {\n  return typeof where === `object` && `expression` in where\n    ? where.expression\n    : where\n}\n\n/**\n * Extract the expression from a HAVING clause\n * HAVING clauses can contain aggregates, unlike regular WHERE clauses\n */\nexport function getHavingExpression(\n  having: Having,\n): BasicExpression | Aggregate {\n  return typeof having === `object` && `expression` in having\n    ? having.expression\n    : having\n}\n\n/**\n * Check if a Where clause is marked as residual\n */\nexport function isResidualWhere(where: Where): boolean {\n  return (\n    typeof where === `object` &&\n    `expression` in where &&\n    where.residual === true\n  )\n}\n\n/**\n * Create a residual Where clause from an expression\n */\nexport function createResidualWhere(\n  expression: BasicExpression<boolean>,\n): Where {\n  return { expression, residual: true }\n}\n\nfunction getRefFromAlias(\n  query: QueryIR,\n  alias: string,\n): CollectionRef | QueryRef | void {\n  if (query.from.alias === alias) {\n    return query.from\n  }\n\n  for (const join of query.join || []) {\n    if (join.from.alias === alias) {\n      return join.from\n    }\n  }\n}\n\n/**\n * Follows the given reference in a query\n * until its finds the root field the reference points to.\n * @returns The collection, its alias, and the path to the root field in this collection\n */\nexport function followRef(\n  query: QueryIR,\n  ref: PropRef<any>,\n  collection: Collection,\n): { collection: Collection; path: Array<string> } | void {\n  if (ref.path.length === 0) {\n    return\n  }\n\n  if (ref.path.length === 1) {\n    // This field should be part of this collection\n    const field = ref.path[0]!\n    // is it part of the select clause?\n    if (query.select) {\n      const selectedField = query.select[field]\n      if (selectedField && selectedField.type === `ref`) {\n        return followRef(query, selectedField, collection)\n      }\n    }\n\n    // Either this field is not part of the select clause\n    // and thus it must be part of the collection itself\n    // or it is part of the select but is not a reference\n    // so we can stop here and don't have to follow it\n    return { collection, path: [field] }\n  }\n\n  if (ref.path.length > 1) {\n    // This is a nested field\n    const [alias, ...rest] = ref.path\n    const aliasRef = getRefFromAlias(query, alias!)\n    if (!aliasRef) {\n      return\n    }\n\n    if (aliasRef.type === `queryRef`) {\n      return followRef(aliasRef.query, new PropRef(rest), collection)\n    } else {\n      // This is a reference to a collection\n      // we can't follow it further\n      // so the field must be on the collection itself\n      return { collection: aliasRef.collection, path: rest }\n    }\n  }\n}\n"],"names":[],"mappings":"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"}

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

@@ -17,9 +17,11 @@ export interface QueryIR {
     fnWhere?: Array<(row: NamespacedRow) => any>;
     fnHaving?: Array<(row: NamespacedRow) => any>;
 }
+export type IncludesMaterialization = `collection` | `array` | `concat`;
+export declare const INCLUDES_SCALAR_FIELD = "__includes_scalar__";
 export type From = CollectionRef | QueryRef;
 export type Select = {
-    [alias: string]: BasicExpression | Aggregate | Select;
+    [alias: string]: BasicExpression | Aggregate | Select | IncludesSubquery;
 };
 export type Join = Array<JoinClause>;
 export interface JoinClause {
@@ -84,6 +86,24 @@ export declare class Aggregate<T = any> extends BaseExpression<T> {
     constructor(name: string, // such as count, avg, sum, min, max, etc.
     args: Array<BasicExpression>);
 }
+export declare class IncludesSubquery extends BaseExpression {
+    query: QueryIR;
+    correlationField: PropRef;
+    childCorrelationField: PropRef;
+    fieldName: string;
+    parentFilters?: Array<Where> | undefined;
+    parentProjection?: Array<PropRef> | undefined;
+    materialization: IncludesMaterialization;
+    scalarField?: string | undefined;
+    type: "includesSubquery";
+    constructor(query: QueryIR, // Child query (correlation WHERE removed)
+    correlationField: PropRef, // Parent-side ref (e.g., project.id)
+    childCorrelationField: PropRef, // Child-side ref (e.g., issue.projectId)
+    fieldName: string, // Result field name (e.g., "issues")
+    parentFilters?: Array<Where> | undefined, // WHERE clauses referencing parent aliases (applied post-join)
+    parentProjection?: Array<PropRef> | undefined, // Parent field refs used by parentFilters
+    materialization?: IncludesMaterialization, scalarField?: string | undefined);
+}
 /**
  * Runtime helper to detect IR expression-like objects.
  * Prefer this over ad-hoc local implementations to keep behavior consistent.

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

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 const dbIvm = require("@tanstack/db-ivm");
 const index = require("../compiler/index.cjs");
+const index$1 = require("../../collection/index.cjs");
 const errors = require("../../errors.cjs");
 const scheduler = require("../../scheduler.cjs");
 const transactions = require("../../transactions.cjs");
@@ -27,7 +28,10 @@ class CollectionConfigBuilder {
     this.lazySources = /* @__PURE__ */ new Set();
     this.optimizableOrderByCollections = {};
     this.id = config.id || `live-query-${++liveQueryCollectionCounter}`;
-    this.query = utils.buildQueryFromConfig(config);
+    this.query = utils.buildQueryFromConfig({
+      query: config.query,
+      requireObjectResult: true
+    });
     this.collections = utils.extractCollectionsFromQuery(this.query);
     const collectionAliasesById = utils.extractCollectionAliases(this.query);
     this.collectionByAlias = {};
@@ -362,6 +366,7 @@ class CollectionConfigBuilder {
       this.inputsCache = void 0;
       this.pipelineCache = void 0;
       this.sourceWhereClausesCache = void 0;
+      this.includesCache = void 0;
       this.lazySources.clear();
       this.optimizableOrderByCollections = {};
       this.lazySourcesCallbacks = {};
@@ -399,6 +404,7 @@ class CollectionConfigBuilder {
     this.pipelineCache = compilation.pipeline;
     this.sourceWhereClausesCache = compilation.sourceWhereClauses;
     this.compiledAliasToCollectionId = compilation.aliasToCollectionId;
+    this.includesCache = compilation.includes;
     const missingAliases = Object.keys(this.compiledAliasToCollectionId).filter(
       (alias) => !Object.hasOwn(this.inputsCache, alias)
     );
@@ -427,8 +433,14 @@ class CollectionConfigBuilder {
         messages.reduce(accumulateChanges, pendingChanges);
       })
     );
+    const includesState = this.setupIncludesOutput(
+      this.includesCache,
+      syncState
+    );
     syncState.flushPendingChanges = () => {
-      if (pendingChanges.size === 0) {
+      const hasParentChanges = pendingChanges.size > 0;
+      const hasChildChanges = hasPendingIncludesChanges(includesState);
+      if (!hasParentChanges && !hasChildChanges) {
         return;
       }
       let changesToApply = pendingChanges;
@@ -452,10 +464,19 @@ class CollectionConfigBuilder {
         }
         changesToApply = merged;
       }
-      begin();
-      changesToApply.forEach(this.applyChanges.bind(this, config));
-      commit();
+      if (hasParentChanges) {
+        begin();
+        changesToApply.forEach(this.applyChanges.bind(this, config));
+        commit();
+      }
       pendingChanges = /* @__PURE__ */ new Map();
+      flushIncludesState(
+        includesState,
+        config.collection,
+        this.id,
+        hasParentChanges ? changesToApply : null,
+        config
+      );
     };
     graph.finalize();
     syncState.graph = graph;
@@ -463,6 +484,65 @@ class CollectionConfigBuilder {
     syncState.pipeline = pipeline;
     return syncState;
   }
+  /**
+   * Sets up output callbacks for includes child pipelines.
+   * Each includes entry gets its own output callback that accumulates child changes,
+   * and a child registry that maps correlation key → child Collection.
+   */
+  setupIncludesOutput(includesEntries, syncState) {
+    if (!includesEntries || includesEntries.length === 0) {
+      return [];
+    }
+    return includesEntries.map((entry) => {
+      const state = {
+        fieldName: entry.fieldName,
+        childCorrelationField: entry.childCorrelationField,
+        hasOrderBy: entry.hasOrderBy,
+        materialization: entry.materialization,
+        scalarField: entry.scalarField,
+        childRegistry: /* @__PURE__ */ new Map(),
+        pendingChildChanges: /* @__PURE__ */ new Map(),
+        correlationToParentKeys: /* @__PURE__ */ new Map()
+      };
+      entry.pipeline.pipe(
+        dbIvm.output((data) => {
+          const messages = data.getInner();
+          syncState.messagesCount += messages.length;
+          for (const [[childKey, tupleData], multiplicity] of messages) {
+            const [childResult, _orderByIndex, correlationKey, parentContext] = tupleData;
+            const routingKey = computeRoutingKey(correlationKey, parentContext);
+            let byChild = state.pendingChildChanges.get(routingKey);
+            if (!byChild) {
+              byChild = /* @__PURE__ */ new Map();
+              state.pendingChildChanges.set(routingKey, byChild);
+            }
+            const existing = byChild.get(childKey) || {
+              deletes: 0,
+              inserts: 0,
+              value: childResult,
+              orderByIndex: _orderByIndex
+            };
+            if (multiplicity < 0) {
+              existing.deletes += Math.abs(multiplicity);
+            } else if (multiplicity > 0) {
+              existing.inserts += multiplicity;
+              existing.value = childResult;
+            }
+            byChild.set(childKey, existing);
+          }
+        })
+      );
+      if (entry.childCompilationResult.includes) {
+        state.nestedSetups = setupNestedPipelines(
+          entry.childCompilationResult.includes,
+          syncState
+        );
+        state.nestedRoutingIndex = /* @__PURE__ */ new Map();
+        state.nestedRoutingReverseIndex = /* @__PURE__ */ new Map();
+      }
+      return state;
+    });
+  }
   applyChanges(config, changes, key) {
     const { write, collection } = config;
     const { deletes, inserts, value, orderByIndex } = changes;
@@ -606,6 +686,422 @@ function createOrderByComparator(orderByIndices) {
     return 0;
   };
 }
+function materializesInline(state) {
+  return state.materialization !== `collection`;
+}
+function materializeIncludedValue(state, entry) {
+  if (!entry) {
+    if (state.materialization === `array`) {
+      return [];
+    }
+    if (state.materialization === `concat`) {
+      return ``;
+    }
+    return void 0;
+  }
+  if (state.materialization === `collection`) {
+    return entry.collection;
+  }
+  const rows = [...entry.collection.toArray];
+  const values = state.scalarField ? rows.map((row) => row?.[state.scalarField]) : rows;
+  if (state.materialization === `array`) {
+    return values;
+  }
+  return values.map((value) => String(value ?? ``)).join(``);
+}
+function setupNestedPipelines(includes, syncState) {
+  return includes.map((entry) => {
+    const buffer = /* @__PURE__ */ new Map();
+    entry.pipeline.pipe(
+      dbIvm.output((data) => {
+        const messages = data.getInner();
+        syncState.messagesCount += messages.length;
+        for (const [[childKey, tupleData], multiplicity] of messages) {
+          const [childResult, _orderByIndex, correlationKey, parentContext] = tupleData;
+          const routingKey = computeRoutingKey(correlationKey, parentContext);
+          let byChild = buffer.get(routingKey);
+          if (!byChild) {
+            byChild = /* @__PURE__ */ new Map();
+            buffer.set(routingKey, byChild);
+          }
+          const existing = byChild.get(childKey) || {
+            deletes: 0,
+            inserts: 0,
+            value: childResult,
+            orderByIndex: _orderByIndex
+          };
+          if (multiplicity < 0) {
+            existing.deletes += Math.abs(multiplicity);
+          } else if (multiplicity > 0) {
+            existing.inserts += multiplicity;
+            existing.value = childResult;
+          }
+          byChild.set(childKey, existing);
+        }
+      })
+    );
+    const setup = {
+      compilationResult: entry,
+      buffer
+    };
+    if (entry.childCompilationResult.includes) {
+      setup.nestedSetups = setupNestedPipelines(
+        entry.childCompilationResult.includes,
+        syncState
+      );
+    }
+    return setup;
+  });
+}
+function createPerEntryIncludesStates(setups) {
+  return setups.map((setup) => {
+    const state = {
+      fieldName: setup.compilationResult.fieldName,
+      childCorrelationField: setup.compilationResult.childCorrelationField,
+      hasOrderBy: setup.compilationResult.hasOrderBy,
+      materialization: setup.compilationResult.materialization,
+      scalarField: setup.compilationResult.scalarField,
+      childRegistry: /* @__PURE__ */ new Map(),
+      pendingChildChanges: /* @__PURE__ */ new Map(),
+      correlationToParentKeys: /* @__PURE__ */ new Map()
+    };
+    if (setup.nestedSetups) {
+      state.nestedSetups = setup.nestedSetups;
+      state.nestedRoutingIndex = /* @__PURE__ */ new Map();
+      state.nestedRoutingReverseIndex = /* @__PURE__ */ new Map();
+    }
+    return state;
+  });
+}
+function drainNestedBuffers(state) {
+  const dirtyCorrelationKeys = /* @__PURE__ */ new Set();
+  if (!state.nestedSetups) return dirtyCorrelationKeys;
+  for (let i = 0; i < state.nestedSetups.length; i++) {
+    const setup = state.nestedSetups[i];
+    const toDelete = [];
+    for (const [nestedCorrelationKey, childChanges] of setup.buffer) {
+      const parentCorrelationKey = state.nestedRoutingIndex.get(nestedCorrelationKey);
+      if (parentCorrelationKey === void 0) {
+        continue;
+      }
+      const entry = state.childRegistry.get(parentCorrelationKey);
+      if (!entry || !entry.includesStates) {
+        continue;
+      }
+      const entryState = entry.includesStates[i];
+      for (const [childKey, changes] of childChanges) {
+        let byChild = entryState.pendingChildChanges.get(nestedCorrelationKey);
+        if (!byChild) {
+          byChild = /* @__PURE__ */ new Map();
+          entryState.pendingChildChanges.set(nestedCorrelationKey, byChild);
+        }
+        const existing = byChild.get(childKey);
+        if (existing) {
+          existing.inserts += changes.inserts;
+          existing.deletes += changes.deletes;
+          if (changes.inserts > 0) {
+            existing.value = changes.value;
+            if (changes.orderByIndex !== void 0) {
+              existing.orderByIndex = changes.orderByIndex;
+            }
+          }
+        } else {
+          byChild.set(childKey, { ...changes });
+        }
+      }
+      dirtyCorrelationKeys.add(parentCorrelationKey);
+      toDelete.push(nestedCorrelationKey);
+    }
+    for (const key of toDelete) {
+      setup.buffer.delete(key);
+    }
+  }
+  return dirtyCorrelationKeys;
+}
+function updateRoutingIndex(state, correlationKey, childChanges) {
+  if (!state.nestedSetups) return;
+  for (const setup of state.nestedSetups) {
+    for (const [, change] of childChanges) {
+      if (change.inserts > 0) {
+        const nestedRouting = change.value[index.INCLUDES_ROUTING]?.[setup.compilationResult.fieldName];
+        const nestedCorrelationKey = nestedRouting?.correlationKey;
+        const nestedParentContext = nestedRouting?.parentContext ?? null;
+        const nestedRoutingKey = computeRoutingKey(
+          nestedCorrelationKey,
+          nestedParentContext
+        );
+        if (nestedCorrelationKey != null) {
+          state.nestedRoutingIndex.set(nestedRoutingKey, correlationKey);
+          let reverseSet = state.nestedRoutingReverseIndex.get(correlationKey);
+          if (!reverseSet) {
+            reverseSet = /* @__PURE__ */ new Set();
+            state.nestedRoutingReverseIndex.set(correlationKey, reverseSet);
+          }
+          reverseSet.add(nestedRoutingKey);
+        }
+      } else if (change.deletes > 0 && change.inserts === 0) {
+        const nestedRouting2 = change.value[index.INCLUDES_ROUTING]?.[setup.compilationResult.fieldName];
+        const nestedCorrelationKey = nestedRouting2?.correlationKey;
+        const nestedParentContext2 = nestedRouting2?.parentContext ?? null;
+        const nestedRoutingKey = computeRoutingKey(
+          nestedCorrelationKey,
+          nestedParentContext2
+        );
+        if (nestedCorrelationKey != null) {
+          state.nestedRoutingIndex.delete(nestedRoutingKey);
+          const reverseSet = state.nestedRoutingReverseIndex.get(correlationKey);
+          if (reverseSet) {
+            reverseSet.delete(nestedRoutingKey);
+            if (reverseSet.size === 0) {
+              state.nestedRoutingReverseIndex.delete(correlationKey);
+            }
+          }
+        }
+      }
+    }
+  }
+}
+function cleanRoutingIndexOnDelete(state, correlationKey) {
+  if (!state.nestedRoutingReverseIndex) return;
+  const nestedKeys = state.nestedRoutingReverseIndex.get(correlationKey);
+  if (nestedKeys) {
+    for (const nestedKey of nestedKeys) {
+      state.nestedRoutingIndex.delete(nestedKey);
+    }
+    state.nestedRoutingReverseIndex.delete(correlationKey);
+  }
+}
+function hasNestedBufferChanges(setups) {
+  for (const setup of setups) {
+    if (setup.buffer.size > 0) return true;
+    if (setup.nestedSetups && hasNestedBufferChanges(setup.nestedSetups))
+      return true;
+  }
+  return false;
+}
+function computeRoutingKey(correlationKey, parentContext) {
+  if (parentContext == null) return correlationKey;
+  return JSON.stringify([correlationKey, parentContext]);
+}
+function createChildCollectionEntry(parentId, fieldName, correlationKey, hasOrderBy, nestedSetups) {
+  const resultKeys = /* @__PURE__ */ new WeakMap();
+  const orderByIndices = hasOrderBy ? /* @__PURE__ */ new WeakMap() : null;
+  let syncMethods = null;
+  const compare = orderByIndices ? createOrderByComparator(orderByIndices) : void 0;
+  const collection = index$1.createCollection({
+    id: `__child-collection:${parentId}-${fieldName}-${dbIvm.serializeValue(correlationKey)}`,
+    getKey: (item) => resultKeys.get(item),
+    compare,
+    sync: {
+      rowUpdateMode: `full`,
+      sync: (methods) => {
+        syncMethods = methods;
+        return () => {
+          syncMethods = null;
+        };
+      }
+    },
+    startSync: true
+  });
+  const entry = {
+    collection,
+    get syncMethods() {
+      return syncMethods;
+    },
+    resultKeys,
+    orderByIndices
+  };
+  if (nestedSetups) {
+    entry.includesStates = createPerEntryIncludesStates(nestedSetups);
+  }
+  return entry;
+}
+function flushIncludesState(includesState, parentCollection, parentId, parentChanges, parentSyncMethods) {
+  for (const state of includesState) {
+    if (parentChanges) {
+      for (const [parentKey, changes] of parentChanges) {
+        if (changes.inserts > 0) {
+          const parentResult = changes.value;
+          const routing = parentResult[index.INCLUDES_ROUTING]?.[state.fieldName];
+          const correlationKey = routing?.correlationKey;
+          const parentContext = routing?.parentContext ?? null;
+          const routingKey = computeRoutingKey(correlationKey, parentContext);
+          if (correlationKey != null) {
+            if (!state.childRegistry.has(routingKey)) {
+              const entry = createChildCollectionEntry(
+                parentId,
+                state.fieldName,
+                routingKey,
+                state.hasOrderBy,
+                state.nestedSetups
+              );
+              state.childRegistry.set(routingKey, entry);
+            }
+            let parentKeys = state.correlationToParentKeys.get(routingKey);
+            if (!parentKeys) {
+              parentKeys = /* @__PURE__ */ new Set();
+              state.correlationToParentKeys.set(routingKey, parentKeys);
+            }
+            parentKeys.add(parentKey);
+            const childValue = materializeIncludedValue(
+              state,
+              state.childRegistry.get(routingKey)
+            );
+            parentResult[state.fieldName] = childValue;
+            const storedParent = parentCollection.get(parentKey);
+            if (storedParent && storedParent !== parentResult) {
+              storedParent[state.fieldName] = childValue;
+            }
+          }
+        }
+      }
+    }
+    const affectedCorrelationKeys = materializesInline(state) ? new Set(state.pendingChildChanges.keys()) : null;
+    const entriesWithChildChanges = /* @__PURE__ */ new Map();
+    if (state.pendingChildChanges.size > 0) {
+      for (const [correlationKey, childChanges] of state.pendingChildChanges) {
+        let entry = state.childRegistry.get(correlationKey);
+        if (!entry) {
+          entry = createChildCollectionEntry(
+            parentId,
+            state.fieldName,
+            correlationKey,
+            state.hasOrderBy,
+            state.nestedSetups
+          );
+          state.childRegistry.set(correlationKey, entry);
+        }
+        if (state.materialization === `collection`) {
+          attachChildCollectionToParent(
+            parentCollection,
+            state.fieldName,
+            correlationKey,
+            state.correlationToParentKeys,
+            entry.collection
+          );
+        }
+        if (entry.syncMethods) {
+          entry.syncMethods.begin();
+          for (const [childKey, change] of childChanges) {
+            entry.resultKeys.set(change.value, childKey);
+            if (entry.orderByIndices && change.orderByIndex !== void 0) {
+              entry.orderByIndices.set(change.value, change.orderByIndex);
+            }
+            if (change.inserts > 0 && change.deletes === 0) {
+              entry.syncMethods.write({ value: change.value, type: `insert` });
+            } else if (change.inserts > change.deletes || change.inserts === change.deletes && entry.syncMethods.collection.has(
+              entry.syncMethods.collection.getKeyFromItem(change.value)
+            )) {
+              entry.syncMethods.write({ value: change.value, type: `update` });
+            } else if (change.deletes > 0) {
+              entry.syncMethods.write({ value: change.value, type: `delete` });
+            }
+          }
+          entry.syncMethods.commit();
+        }
+        updateRoutingIndex(state, correlationKey, childChanges);
+        entriesWithChildChanges.set(correlationKey, { entry, childChanges });
+      }
+      state.pendingChildChanges.clear();
+    }
+    const dirtyFromBuffers = drainNestedBuffers(state);
+    for (const [, { entry, childChanges }] of entriesWithChildChanges) {
+      if (entry.includesStates) {
+        flushIncludesState(
+          entry.includesStates,
+          entry.collection,
+          entry.collection.id,
+          childChanges,
+          entry.syncMethods
+        );
+      }
+    }
+    for (const correlationKey of dirtyFromBuffers) {
+      if (entriesWithChildChanges.has(correlationKey)) continue;
+      const entry = state.childRegistry.get(correlationKey);
+      if (entry?.includesStates) {
+        flushIncludesState(
+          entry.includesStates,
+          entry.collection,
+          entry.collection.id,
+          null,
+          entry.syncMethods
+        );
+      }
+    }
+    const inlineReEmitKeys = materializesInline(state) ? /* @__PURE__ */ new Set([...affectedCorrelationKeys || [], ...dirtyFromBuffers]) : null;
+    if (parentSyncMethods && inlineReEmitKeys && inlineReEmitKeys.size > 0) {
+      const events = [];
+      for (const correlationKey of inlineReEmitKeys) {
+        const parentKeys = state.correlationToParentKeys.get(correlationKey);
+        if (!parentKeys) continue;
+        const entry = state.childRegistry.get(correlationKey);
+        for (const parentKey of parentKeys) {
+          const item = parentCollection.get(parentKey);
+          if (item) {
+            const key = parentSyncMethods.collection.getKeyFromItem(item);
+            const previousValue = { ...item };
+            item[state.fieldName] = materializeIncludedValue(state, entry);
+            events.push({
+              type: `update`,
+              key,
+              value: item,
+              previousValue
+            });
+          }
+        }
+      }
+      if (events.length > 0) {
+        const changesManager = parentCollection._changes;
+        changesManager.emitEvents(events, true);
+      }
+    }
+    if (parentChanges) {
+      for (const [parentKey, changes] of parentChanges) {
+        if (changes.deletes > 0 && changes.inserts === 0) {
+          const routing = changes.value[index.INCLUDES_ROUTING]?.[state.fieldName];
+          const correlationKey = routing?.correlationKey;
+          const parentContext = routing?.parentContext ?? null;
+          const routingKey = computeRoutingKey(correlationKey, parentContext);
+          if (correlationKey != null) {
+            const parentKeys = state.correlationToParentKeys.get(routingKey);
+            if (parentKeys) {
+              parentKeys.delete(parentKey);
+              if (parentKeys.size === 0) {
+                cleanRoutingIndexOnDelete(state, routingKey);
+                state.childRegistry.delete(routingKey);
+                state.correlationToParentKeys.delete(routingKey);
+              }
+            }
+          }
+        }
+      }
+    }
+  }
+  if (parentChanges) {
+    for (const [, changes] of parentChanges) {
+      delete changes.value[index.INCLUDES_ROUTING];
+    }
+  }
+}
+function hasPendingIncludesChanges(states) {
+  for (const state of states) {
+    if (state.pendingChildChanges.size > 0) return true;
+    if (state.nestedSetups && hasNestedBufferChanges(state.nestedSetups))
+      return true;
+  }
+  return false;
+}
+function attachChildCollectionToParent(parentCollection, fieldName, correlationKey, correlationToParentKeys, childCollection) {
+  const parentKeys = correlationToParentKeys.get(correlationKey);
+  if (!parentKeys) return;
+  for (const parentKey of parentKeys) {
+    const item = parentCollection.get(parentKey);
+    if (item) {
+      item[fieldName] = childCollection;
+    }
+  }
+}
 function accumulateChanges(acc, [[key, tupleData], multiplicity]) {
   const [value, orderByIndex] = tupleData;
   const changes = acc.get(key) || {