@tanstack/db 0.4.2 → 0.4.3

package/dist/esm/query/ir.js

@@ -61,6 +61,43 @@ function isResidualWhere(where) {
 function createResidualWhere(expression) {
   return { expression, residual: true };
 }
+function getRefFromAlias(query, alias) {
+  if (query.from.alias === alias) {
+    return query.from;
+  }
+  for (const join of query.join || []) {
+    if (join.from.alias === alias) {
+      return join.from;
+    }
+  }
+}
+function followRef(query, ref, collection) {
+  if (ref.path.length === 0) {
+    return;
+  }
+  if (ref.path.length === 1) {
+    const field = ref.path[0];
+    if (query.select) {
+      const selectedField = query.select[field];
+      if (selectedField && selectedField.type === `ref`) {
+        return followRef(query, selectedField, collection);
+      }
+    }
+    return { collection, path: [field] };
+  }
+  if (ref.path.length > 1) {
+    const [alias, ...rest] = ref.path;
+    const aliasRef = getRefFromAlias(query, alias);
+    if (!aliasRef) {
+      return;
+    }
+    if (aliasRef.type === `queryRef`) {
+      return followRef(aliasRef.query, new PropRef(rest), collection);
+    } else {
+      return { collection: aliasRef.collection, path: rest };
+    }
+  }
+}
 export {
   Aggregate,
   CollectionRef,
@@ -69,6 +106,7 @@ export {
   QueryRef,
   Value,
   createResidualWhere,
+  followRef,
   getHavingExpression,
   getWhereExpression,
   isExpressionLike,

package/dist/esm/query/ir.js.map

@@ -1 +1 @@
-{"version":3,"file":"ir.js","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/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\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"],"names":[],"mappings":"AAgEA,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;"}
+{"version":3,"file":"ir.js","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\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":"AAgEA,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;"}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@tanstack/db",
   "description": "A reactive client store for building super fast apps on sync",
-  "version": "0.4.2",
+  "version": "0.4.3",
   "dependencies": {
     "@standard-schema/spec": "^1.0.0",
     "@tanstack/db-ivm": "0.1.9"

package/src/collection/subscription.ts

@@ -1,5 +1,5 @@
 import { ensureIndexForExpression } from "../indexes/auto-index.js"
-import { and } from "../query/index.js"
+import { and } from "../query/builder/functions.js"
 import {
   createFilterFunctionFromExpression,
   createFilteredCallback,

package/src/query/compiler/index.ts

@@ -127,7 +127,8 @@ export function compileQuery(
       callbacks,
       lazyCollections,
       optimizableOrderByCollections,
-      rawQuery
+      rawQuery,
+      compileQuery
     )
   }
 
@@ -512,3 +513,5 @@ export function followRef(
     }
   }
 }
+
+export type CompileQueryFn = typeof compileQuery

package/src/query/compiler/joins.ts

@@ -17,10 +17,10 @@ import {
   UnsupportedJoinTypeError,
 } from "../../errors.js"
 import { ensureIndexForField } from "../../indexes/auto-index.js"
-import { PropRef } from "../ir.js"
+import { PropRef, followRef } from "../ir.js"
 import { inArray } from "../builder/functions.js"
 import { compileExpression } from "./evaluators.js"
-import { compileQuery, followRef } from "./index.js"
+import type { CompileQueryFn } from "./index.js"
 import type { OrderByOptimizationInfo } from "./order-by.js"
 import type {
   BasicExpression,
@@ -62,7 +62,8 @@ export function processJoins(
   callbacks: Record<string, LazyCollectionCallbacks>,
   lazyCollections: Set<string>,
   optimizableOrderByCollections: Record<string, OrderByOptimizationInfo>,
-  rawQuery: QueryIR
+  rawQuery: QueryIR,
+  onCompileSubquery: CompileQueryFn
 ): NamespacedAndKeyedStream {
   let resultPipeline = pipeline
 
@@ -81,7 +82,8 @@ export function processJoins(
       callbacks,
       lazyCollections,
       optimizableOrderByCollections,
-      rawQuery
+      rawQuery,
+      onCompileSubquery
     )
   }
 
@@ -105,7 +107,8 @@ function processJoin(
   callbacks: Record<string, LazyCollectionCallbacks>,
   lazyCollections: Set<string>,
   optimizableOrderByCollections: Record<string, OrderByOptimizationInfo>,
-  rawQuery: QueryIR
+  rawQuery: QueryIR,
+  onCompileSubquery: CompileQueryFn
 ): NamespacedAndKeyedStream {
   // Get the joined table alias and input stream
   const {
@@ -121,7 +124,8 @@ function processJoin(
     lazyCollections,
     optimizableOrderByCollections,
     cache,
-    queryMapping
+    queryMapping,
+    onCompileSubquery
   )
 
   // Add the joined table to the tables map
@@ -392,7 +396,8 @@ function processJoinSource(
   lazyCollections: Set<string>,
   optimizableOrderByCollections: Record<string, OrderByOptimizationInfo>,
   cache: QueryCache,
-  queryMapping: QueryMapping
+  queryMapping: QueryMapping,
+  onCompileSubquery: CompileQueryFn
 ): { alias: string; input: KeyedStream; collectionId: string } {
   switch (from.type) {
     case `collectionRef`: {
@@ -407,7 +412,7 @@ function processJoinSource(
       const originalQuery = queryMapping.get(from.query) || from.query
 
       // Recursively compile the sub-query with cache
-      const subQueryResult = compileQuery(
+      const subQueryResult = onCompileSubquery(
         originalQuery,
         allInputs,
         collections,

package/src/query/compiler/order-by.ts

@@ -1,11 +1,10 @@
 import { orderByWithFractionalIndex } from "@tanstack/db-ivm"
 import { defaultComparator, makeComparator } from "../../utils/comparison.js"
-import { PropRef } from "../ir.js"
+import { PropRef, followRef } from "../ir.js"
 import { ensureIndexForField } from "../../indexes/auto-index.js"
 import { findIndexForField } from "../../utils/index-optimization.js"
 import { compileExpression } from "./evaluators.js"
 import { replaceAggregatesByRefs } from "./group-by.js"
-import { followRef } from "./index.js"
 import type { CompiledSingleRowExpression } from "./evaluators.js"
 import type { OrderByClause, QueryIR, Select } from "../ir.js"
 import type { NamespacedAndKeyedStream, NamespacedRow } from "../../types.js"

package/src/query/ir.ts

@@ -3,7 +3,7 @@ This is the intermediate representation of the query.
 */
 
 import type { CompareOptions } from "./builder/types"
-import type { CollectionImpl } from "../collection/index.js"
+import type { Collection, CollectionImpl } from "../collection/index.js"
 import type { NamespacedRow } from "../types"
 
 export interface QueryIR {
@@ -188,3 +188,69 @@ export function createResidualWhere(
 ): Where {
   return { expression, residual: true }
 }
+
+function getRefFromAlias(
+  query: QueryIR,
+  alias: string
+): CollectionRef | QueryRef | void {
+  if (query.from.alias === alias) {
+    return query.from
+  }
+
+  for (const join of query.join || []) {
+    if (join.from.alias === alias) {
+      return join.from
+    }
+  }
+}
+
+/**
+ * Follows the given reference in a query
+ * until its finds the root field the reference points to.
+ * @returns The collection, its alias, and the path to the root field in this collection
+ */
+export function followRef(
+  query: QueryIR,
+  ref: PropRef<any>,
+  collection: Collection
+): { collection: Collection; path: Array<string> } | void {
+  if (ref.path.length === 0) {
+    return
+  }
+
+  if (ref.path.length === 1) {
+    // This field should be part of this collection
+    const field = ref.path[0]!
+    // is it part of the select clause?
+    if (query.select) {
+      const selectedField = query.select[field]
+      if (selectedField && selectedField.type === `ref`) {
+        return followRef(query, selectedField, collection)
+      }
+    }
+
+    // Either this field is not part of the select clause
+    // and thus it must be part of the collection itself
+    // or it is part of the select but is not a reference
+    // so we can stop here and don't have to follow it
+    return { collection, path: [field] }
+  }
+
+  if (ref.path.length > 1) {
+    // This is a nested field
+    const [alias, ...rest] = ref.path
+    const aliasRef = getRefFromAlias(query, alias!)
+    if (!aliasRef) {
+      return
+    }
+
+    if (aliasRef.type === `queryRef`) {
+      return followRef(aliasRef.query, new PropRef(rest), collection)
+    } else {
+      // This is a reference to a collection
+      // we can't follow it further
+      // so the field must be on the collection itself
+      return { collection: aliasRef.collection, path: rest }
+    }
+  }
+}