Remove circular imports (TanStack#605)

bradleyayers · web-flow · commit 32f221278e2a · 2025-09-30T12:27:15.000+01:00
* Enable import-x/no-cycle ESLint rule This will prevent circular dependencies in the codebase which cause issues like TanStack#567. * Fix circular import of `and` * Fix circular import of `followRef` * Fix circular import in compiler * Fix linting issues * Add changeset for circular import fix
diff --git a/.changeset/wise-snakes-tie.md b/.changeset/wise-snakes-tie.md
@@ -0,0 +1,5 @@
+---
+"@tanstack/db": patch
+---
+
+Remove circular imports to fix compatibility with Metro bundler
diff --git a/eslint.config.js b/eslint.config.js
@@ -19,6 +19,11 @@ export default [
       stylistic: stylisticPlugin,
       prettier: prettierPlugin,
     },
+    settings: {
+      // import-x/* settings required for import/no-cycle.
+      "import-x/resolver": { typescript: true },
+      "import-x/extensions": [".ts", ".tsx", ".js", ".jsx", ".cjs", ".mjs"],
+    },
     rules: {
       "prettier/prettier": `error`,
       "stylistic/quotes": [`error`, `backtick`],
@@ -42,6 +47,7 @@ export default [
           leadingUnderscore: `allow`,
         },
       ],
+      "import/no-cycle": `error`,
     },
   },
 ]
diff --git a/package.json b/package.json
@@ -36,6 +36,7 @@
     "@vitejs/plugin-react": "^4.7.0",
     "eslint": "^9.36.0",
     "eslint-config-prettier": "^10.1.8",
+    "eslint-import-resolver-typescript": "^4.4.4",
     "eslint-plugin-prettier": "^5.5.4",
     "eslint-plugin-react": "^7.37.5",
     "husky": "^9.1.7",
diff --git a/packages/db-ivm/src/operators/filterBy.ts b/packages/db-ivm/src/operators/filterBy.ts
@@ -1,8 +1,7 @@
 import { map } from "./map.js"
 import { innerJoin } from "./join.js"
 import { consolidate } from "./consolidate.js"
-import type { KeyValue } from "../types.js"
-import type { IStreamBuilder, PipedOperator } from "../types"
+import type { IStreamBuilder, KeyValue, PipedOperator } from "../types.js"
 
 /**
  * Filters the elements of a keyed stream, by keys of another stream.
diff --git a/packages/db-ivm/src/operators/orderBy.ts b/packages/db-ivm/src/operators/orderBy.ts
@@ -3,8 +3,7 @@ import { topKWithFractionalIndex } from "./topKWithFractionalIndex.js"
 import { map } from "./map.js"
 import { innerJoin } from "./join.js"
 import { consolidate } from "./consolidate.js"
-import type { KeyValue } from "../types.js"
-import type { IStreamBuilder } from "../types"
+import type { IStreamBuilder, KeyValue } from "../types.js"
 
 export interface OrderByOptions<Ve> {
   comparator?: (a: Ve, b: Ve) => number
diff --git a/packages/db-ivm/src/operators/topK.ts b/packages/db-ivm/src/operators/topK.ts
@@ -1,7 +1,6 @@
 import { MultiSet } from "../multiset.js"
 import { reduce } from "./reduce.js"
-import type { IStreamBuilder, PipedOperator } from "../types"
-import type { KeyValue } from "../types.js"
+import type { IStreamBuilder, KeyValue, PipedOperator } from "../types"
 
 interface TopKOptions {
   limit?: number
diff --git a/packages/db/src/collection/subscription.ts b/packages/db/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,
diff --git a/packages/db/src/query/compiler/index.ts b/packages/db/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
diff --git a/packages/db/src/query/compiler/joins.ts b/packages/db/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,
diff --git a/packages/db/src/query/compiler/order-by.ts b/packages/db/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"
diff --git a/packages/db/src/query/ir.ts b/packages/db/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 }
+    }
+  }
+}
diff --git a/packages/svelte-db/src/useLiveQuery.svelte.ts b/packages/svelte-db/src/useLiveQuery.svelte.ts
@@ -1,6 +1,8 @@
+// eslint-disable-next-line import/no-duplicates -- See https://github.com/un-ts/eslint-plugin-import-x/issues/308
 import { flushSync, untrack } from "svelte"
-import { createLiveQueryCollection } from "@tanstack/db"
+// eslint-disable-next-line import/no-duplicates -- See https://github.com/un-ts/eslint-plugin-import-x/issues/308
 import { SvelteMap } from "svelte/reactivity"
+import { createLiveQueryCollection } from "@tanstack/db"
 import type {
   ChangeMessage,
   Collection,
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml

-Original file line number
+Diff line change
@@ @@ -0,0 +1,5 @@ @@
 +---
 +"@tanstack/db": patch
 +---
++
 +Remove circular imports to fix compatibility with Metro bundler
Original file line number	Diff line number	Diff line change
`@@ -127,7 +127,8 @@ export function compileQuery(`
`127`	`127`	`callbacks,`
`128`	`128`	`lazyCollections,`
`129`	`129`	`optimizableOrderByCollections,`
`130`		`- rawQuery`
	`130`	`+ rawQuery,`
	`131`	`+ compileQuery`
`131`	`132`	`)`
`132`	`133`	`}`
`133`	`134`
`@@ -512,3 +513,5 @@ export function followRef(`
`512`	`513`	`}`
`513`	`514`	`}`
`514`	`515`	`}`
	`516`	`+`
	`517`	`+export type CompileQueryFn = typeof compileQuery`