@tanstack/db 0.1.3 → 0.1.4

package/dist/esm/query/compiler/joins.js.map

@@ -1 +1 @@
-{"version":3,"file":"joins.js","sources":["../../../../src/query/compiler/joins.ts"],"sourcesContent":["import {\n  consolidate,\n  filter,\n  join as joinOperator,\n  map,\n} from \"@tanstack/db-ivm\"\nimport {\n  CollectionInputNotFoundError,\n  InvalidJoinConditionSameTableError,\n  InvalidJoinConditionTableMismatchError,\n  InvalidJoinConditionWrongTablesError,\n  UnsupportedJoinSourceTypeError,\n  UnsupportedJoinTypeError,\n} from \"../../errors.js\"\nimport { compileExpression } from \"./evaluators.js\"\nimport { compileQuery } from \"./index.js\"\nimport type { IStreamBuilder, JoinType } from \"@tanstack/db-ivm\"\nimport type {\n  BasicExpression,\n  CollectionRef,\n  JoinClause,\n  QueryRef,\n} from \"../ir.js\"\nimport type {\n  KeyedStream,\n  NamespacedAndKeyedStream,\n  NamespacedRow,\n} from \"../../types.js\"\nimport type { QueryCache, QueryMapping } from \"./types.js\"\n\n/**\n * Processes all join clauses in a query\n */\nexport function processJoins(\n  pipeline: NamespacedAndKeyedStream,\n  joinClauses: Array<JoinClause>,\n  tables: Record<string, KeyedStream>,\n  mainTableAlias: string,\n  allInputs: Record<string, KeyedStream>,\n  cache: QueryCache,\n  queryMapping: QueryMapping\n): NamespacedAndKeyedStream {\n  let resultPipeline = pipeline\n\n  for (const joinClause of joinClauses) {\n    resultPipeline = processJoin(\n      resultPipeline,\n      joinClause,\n      tables,\n      mainTableAlias,\n      allInputs,\n      cache,\n      queryMapping\n    )\n  }\n\n  return resultPipeline\n}\n\n/**\n * Processes a single join clause\n */\nfunction processJoin(\n  pipeline: NamespacedAndKeyedStream,\n  joinClause: JoinClause,\n  tables: Record<string, KeyedStream>,\n  mainTableAlias: string,\n  allInputs: Record<string, KeyedStream>,\n  cache: QueryCache,\n  queryMapping: QueryMapping\n): NamespacedAndKeyedStream {\n  // Get the joined table alias and input stream\n  const { alias: joinedTableAlias, input: joinedInput } = processJoinSource(\n    joinClause.from,\n    allInputs,\n    cache,\n    queryMapping\n  )\n\n  // Add the joined table to the tables map\n  tables[joinedTableAlias] = joinedInput\n\n  // Convert join type to D2 join type\n  const joinType: JoinType =\n    joinClause.type === `cross`\n      ? `inner`\n      : joinClause.type === `outer`\n        ? `full`\n        : (joinClause.type as JoinType)\n\n  // Analyze which table each expression refers to and swap if necessary\n  const { mainExpr, joinedExpr } = analyzeJoinExpressions(\n    joinClause.left,\n    joinClause.right,\n    mainTableAlias,\n    joinedTableAlias\n  )\n\n  // Pre-compile the join expressions\n  const compiledMainExpr = compileExpression(mainExpr)\n  const compiledJoinedExpr = compileExpression(joinedExpr)\n\n  // Prepare the main pipeline for joining\n  const mainPipeline = pipeline.pipe(\n    map(([currentKey, namespacedRow]) => {\n      // Extract the join key from the main table expression\n      const mainKey = compiledMainExpr(namespacedRow)\n\n      // Return [joinKey, [originalKey, namespacedRow]]\n      return [mainKey, [currentKey, namespacedRow]] as [\n        unknown,\n        [string, typeof namespacedRow],\n      ]\n    })\n  )\n\n  // Prepare the joined pipeline\n  const joinedPipeline = joinedInput.pipe(\n    map(([currentKey, row]) => {\n      // Wrap the row in a namespaced structure\n      const namespacedRow: NamespacedRow = { [joinedTableAlias]: row }\n\n      // Extract the join key from the joined table expression\n      const joinedKey = compiledJoinedExpr(namespacedRow)\n\n      // Return [joinKey, [originalKey, namespacedRow]]\n      return [joinedKey, [currentKey, namespacedRow]] as [\n        unknown,\n        [string, typeof namespacedRow],\n      ]\n    })\n  )\n\n  // Apply the join operation\n  if (![`inner`, `left`, `right`, `full`].includes(joinType)) {\n    throw new UnsupportedJoinTypeError(joinClause.type)\n  }\n  return mainPipeline.pipe(\n    joinOperator(joinedPipeline, joinType),\n    consolidate(),\n    processJoinResults(joinClause.type)\n  )\n}\n\n/**\n * Analyzes join expressions to determine which refers to which table\n * and returns them in the correct order (main table expression first, joined table expression second)\n */\nfunction analyzeJoinExpressions(\n  left: BasicExpression,\n  right: BasicExpression,\n  mainTableAlias: string,\n  joinedTableAlias: string\n): { mainExpr: BasicExpression; joinedExpr: BasicExpression } {\n  const leftTableAlias = getTableAliasFromExpression(left)\n  const rightTableAlias = getTableAliasFromExpression(right)\n\n  // If left expression refers to main table and right refers to joined table, keep as is\n  if (\n    leftTableAlias === mainTableAlias &&\n    rightTableAlias === joinedTableAlias\n  ) {\n    return { mainExpr: left, joinedExpr: right }\n  }\n\n  // If left expression refers to joined table and right refers to main table, swap them\n  if (\n    leftTableAlias === joinedTableAlias &&\n    rightTableAlias === mainTableAlias\n  ) {\n    return { mainExpr: right, joinedExpr: left }\n  }\n\n  // If both expressions refer to the same alias, this is an invalid join\n  if (leftTableAlias === rightTableAlias) {\n    throw new InvalidJoinConditionSameTableError(leftTableAlias || `unknown`)\n  }\n\n  // If one expression doesn't refer to either table, this is an invalid join\n  if (!leftTableAlias || !rightTableAlias) {\n    throw new InvalidJoinConditionTableMismatchError(\n      mainTableAlias,\n      joinedTableAlias\n    )\n  }\n\n  // If expressions refer to tables not involved in this join, this is an invalid join\n  throw new InvalidJoinConditionWrongTablesError(\n    leftTableAlias,\n    rightTableAlias,\n    mainTableAlias,\n    joinedTableAlias\n  )\n}\n\n/**\n * Extracts the table alias from a join expression\n */\nfunction getTableAliasFromExpression(expr: BasicExpression): string | null {\n  switch (expr.type) {\n    case `ref`:\n      // PropRef path has the table alias as the first element\n      return expr.path[0] || null\n    case `func`: {\n      // For function expressions, we need to check if all arguments refer to the same table\n      const tableAliases = new Set<string>()\n      for (const arg of expr.args) {\n        const alias = getTableAliasFromExpression(arg)\n        if (alias) {\n          tableAliases.add(alias)\n        }\n      }\n      // If all arguments refer to the same table, return that table alias\n      return tableAliases.size === 1 ? Array.from(tableAliases)[0]! : null\n    }\n    default:\n      // Values (type='val') don't reference any table\n      return null\n  }\n}\n\n/**\n * Processes the join source (collection or sub-query)\n */\nfunction processJoinSource(\n  from: CollectionRef | QueryRef,\n  allInputs: Record<string, KeyedStream>,\n  cache: QueryCache,\n  queryMapping: QueryMapping\n): { alias: string; input: KeyedStream } {\n  switch (from.type) {\n    case `collectionRef`: {\n      const input = allInputs[from.collection.id]\n      if (!input) {\n        throw new CollectionInputNotFoundError(from.collection.id)\n      }\n      return { alias: from.alias, input }\n    }\n    case `queryRef`: {\n      // Find the original query for caching purposes\n      const originalQuery = queryMapping.get(from.query) || from.query\n\n      // Recursively compile the sub-query with cache\n      const subQueryResult = compileQuery(\n        originalQuery,\n        allInputs,\n        cache,\n        queryMapping\n      )\n\n      // Extract the pipeline from the compilation result\n      const subQueryInput = subQueryResult.pipeline\n\n      // Subqueries may return [key, [value, orderByIndex]] (with ORDER BY) or [key, value] (without ORDER BY)\n      // We need to extract just the value for use in parent queries\n      const extractedInput = subQueryInput.pipe(\n        map((data: any) => {\n          const [key, [value, _orderByIndex]] = data\n          return [key, value] as [unknown, any]\n        })\n      )\n\n      return { alias: from.alias, input: extractedInput as KeyedStream }\n    }\n    default:\n      throw new UnsupportedJoinSourceTypeError((from as any).type)\n  }\n}\n\n/**\n * Processes the results of a join operation\n */\nfunction processJoinResults(joinType: string) {\n  return function (\n    pipeline: IStreamBuilder<\n      [\n        key: string,\n        [\n          [string, NamespacedRow] | undefined,\n          [string, NamespacedRow] | undefined,\n        ],\n      ]\n    >\n  ): NamespacedAndKeyedStream {\n    return pipeline.pipe(\n      // Process the join result and handle nulls\n      filter((result) => {\n        const [_key, [main, joined]] = result\n        const mainNamespacedRow = main?.[1]\n        const joinedNamespacedRow = joined?.[1]\n\n        // Handle different join types\n        if (joinType === `inner`) {\n          return !!(mainNamespacedRow && joinedNamespacedRow)\n        }\n\n        if (joinType === `left`) {\n          return !!mainNamespacedRow\n        }\n\n        if (joinType === `right`) {\n          return !!joinedNamespacedRow\n        }\n\n        // For full joins, always include\n        return true\n      }),\n      map((result) => {\n        const [_key, [main, joined]] = result\n        const mainKey = main?.[0]\n        const mainNamespacedRow = main?.[1]\n        const joinedKey = joined?.[0]\n        const joinedNamespacedRow = joined?.[1]\n\n        // Merge the namespaced rows\n        const mergedNamespacedRow: NamespacedRow = {}\n\n        // Add main row data if it exists\n        if (mainNamespacedRow) {\n          Object.assign(mergedNamespacedRow, mainNamespacedRow)\n        }\n\n        // Add joined row data if it exists\n        if (joinedNamespacedRow) {\n          Object.assign(mergedNamespacedRow, joinedNamespacedRow)\n        }\n\n        // We create a composite key that combines the main and joined keys\n        const resultKey = `[${mainKey},${joinedKey}]`\n\n        return [resultKey, mergedNamespacedRow] as [string, NamespacedRow]\n      })\n    )\n  }\n}\n"],"names":["joinOperator"],"mappings":"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"}
+{"version":3,"file":"joins.js","sources":["../../../../src/query/compiler/joins.ts"],"sourcesContent":["import {\n  consolidate,\n  filter,\n  join as joinOperator,\n  map,\n  tap,\n} from \"@tanstack/db-ivm\"\nimport {\n  CollectionInputNotFoundError,\n  InvalidJoinConditionSameTableError,\n  InvalidJoinConditionTableMismatchError,\n  InvalidJoinConditionWrongTablesError,\n  JoinCollectionNotFoundError,\n  UnsupportedJoinSourceTypeError,\n  UnsupportedJoinTypeError,\n} from \"../../errors.js\"\nimport { findIndexForField } from \"../../utils/index-optimization.js\"\nimport { ensureIndexForField } from \"../../indexes/auto-index.js\"\nimport { compileExpression } from \"./evaluators.js\"\nimport { compileQuery, followRef } from \"./index.js\"\nimport type { OrderByOptimizationInfo } from \"./order-by.js\"\nimport type {\n  BasicExpression,\n  CollectionRef,\n  JoinClause,\n  PropRef,\n  QueryIR,\n  QueryRef,\n} from \"../ir.js\"\nimport type { IStreamBuilder, JoinType } from \"@tanstack/db-ivm\"\nimport type { Collection } from \"../../collection.js\"\nimport type {\n  KeyedStream,\n  NamespacedAndKeyedStream,\n  NamespacedRow,\n} from \"../../types.js\"\nimport type { QueryCache, QueryMapping } from \"./types.js\"\nimport type { BaseIndex } from \"../../indexes/base-index.js\"\n\nexport type LoadKeysFn = (key: Set<string | number>) => void\nexport type LazyCollectionCallbacks = {\n  loadKeys: LoadKeysFn\n  loadInitialState: () => void\n}\n\n/**\n * Processes all join clauses in a query\n */\nexport function processJoins(\n  pipeline: NamespacedAndKeyedStream,\n  joinClauses: Array<JoinClause>,\n  tables: Record<string, KeyedStream>,\n  mainTableId: string,\n  mainTableAlias: string,\n  allInputs: Record<string, KeyedStream>,\n  cache: QueryCache,\n  queryMapping: QueryMapping,\n  collections: Record<string, Collection>,\n  callbacks: Record<string, LazyCollectionCallbacks>,\n  lazyCollections: Set<string>,\n  optimizableOrderByCollections: Record<string, OrderByOptimizationInfo>,\n  rawQuery: QueryIR\n): NamespacedAndKeyedStream {\n  let resultPipeline = pipeline\n\n  for (const joinClause of joinClauses) {\n    resultPipeline = processJoin(\n      resultPipeline,\n      joinClause,\n      tables,\n      mainTableId,\n      mainTableAlias,\n      allInputs,\n      cache,\n      queryMapping,\n      collections,\n      callbacks,\n      lazyCollections,\n      optimizableOrderByCollections,\n      rawQuery\n    )\n  }\n\n  return resultPipeline\n}\n\n/**\n * Processes a single join clause\n */\nfunction processJoin(\n  pipeline: NamespacedAndKeyedStream,\n  joinClause: JoinClause,\n  tables: Record<string, KeyedStream>,\n  mainTableId: string,\n  mainTableAlias: string,\n  allInputs: Record<string, KeyedStream>,\n  cache: QueryCache,\n  queryMapping: QueryMapping,\n  collections: Record<string, Collection>,\n  callbacks: Record<string, LazyCollectionCallbacks>,\n  lazyCollections: Set<string>,\n  optimizableOrderByCollections: Record<string, OrderByOptimizationInfo>,\n  rawQuery: QueryIR\n): NamespacedAndKeyedStream {\n  // Get the joined table alias and input stream\n  const {\n    alias: joinedTableAlias,\n    input: joinedInput,\n    collectionId: joinedCollectionId,\n  } = processJoinSource(\n    joinClause.from,\n    allInputs,\n    collections,\n    callbacks,\n    lazyCollections,\n    optimizableOrderByCollections,\n    cache,\n    queryMapping\n  )\n\n  // Add the joined table to the tables map\n  tables[joinedTableAlias] = joinedInput\n\n  const mainCollection = collections[mainTableId]\n  const joinedCollection = collections[joinedCollectionId]\n\n  if (!mainCollection) {\n    throw new JoinCollectionNotFoundError(mainTableId)\n  }\n\n  if (!joinedCollection) {\n    throw new JoinCollectionNotFoundError(joinedCollectionId)\n  }\n\n  const { activeCollection, lazyCollection } = getActiveAndLazyCollections(\n    joinClause.type,\n    mainCollection,\n    joinedCollection\n  )\n\n  // Analyze which table each expression refers to and swap if necessary\n  const { mainExpr, joinedExpr } = analyzeJoinExpressions(\n    joinClause.left,\n    joinClause.right,\n    mainTableAlias,\n    joinedTableAlias\n  )\n\n  // Pre-compile the join expressions\n  const compiledMainExpr = compileExpression(mainExpr)\n  const compiledJoinedExpr = compileExpression(joinedExpr)\n\n  // Prepare the main pipeline for joining\n  let mainPipeline = pipeline.pipe(\n    map(([currentKey, namespacedRow]) => {\n      // Extract the join key from the main table expression\n      const mainKey = compiledMainExpr(namespacedRow)\n\n      // Return [joinKey, [originalKey, namespacedRow]]\n      return [mainKey, [currentKey, namespacedRow]] as [\n        unknown,\n        [string, typeof namespacedRow],\n      ]\n    })\n  )\n\n  // Prepare the joined pipeline\n  let joinedPipeline = joinedInput.pipe(\n    map(([currentKey, row]) => {\n      // Wrap the row in a namespaced structure\n      const namespacedRow: NamespacedRow = { [joinedTableAlias]: row }\n\n      // Extract the join key from the joined table expression\n      const joinedKey = compiledJoinedExpr(namespacedRow)\n\n      // Return [joinKey, [originalKey, namespacedRow]]\n      return [joinedKey, [currentKey, namespacedRow]] as [\n        unknown,\n        [string, typeof namespacedRow],\n      ]\n    })\n  )\n\n  // Apply the join operation\n  if (![`inner`, `left`, `right`, `full`].includes(joinClause.type)) {\n    throw new UnsupportedJoinTypeError(joinClause.type)\n  }\n\n  if (activeCollection) {\n    // This join can be optimized by having the active collection\n    // dynamically load keys into the lazy collection\n    // based on the value of the joinKey and by looking up\n    // matching rows in the index of the lazy collection\n\n    // Mark the lazy collection as lazy\n    // this Set is passed by the liveQueryCollection to the compiler\n    // such that the liveQueryCollection can check it after compilation\n    // to know which collections are lazy collections\n    lazyCollections.add(lazyCollection.id)\n\n    const activePipeline =\n      activeCollection === `main` ? mainPipeline : joinedPipeline\n\n    let index: BaseIndex<string | number> | undefined\n\n    const lazyCollectionJoinExpr =\n      activeCollection === `main`\n        ? (joinedExpr as PropRef)\n        : (mainExpr as PropRef)\n\n    const activeColl =\n      activeCollection === `main` ? collections[mainTableId]! : lazyCollection\n\n    const followRefResult = followRef(\n      rawQuery,\n      lazyCollectionJoinExpr,\n      activeColl\n    )!\n    const followRefCollection = followRefResult.collection\n\n    const fieldName = followRefResult.path[0]\n    if (fieldName) {\n      ensureIndexForField(fieldName, followRefResult.path, followRefCollection)\n    }\n\n    let deoptimized = false\n\n    const activePipelineWithLoading: IStreamBuilder<\n      [key: unknown, [originalKey: string, namespacedRow: NamespacedRow]]\n    > = activePipeline.pipe(\n      tap(([joinKey, _]) => {\n        if (deoptimized) {\n          return\n        }\n\n        // Find the index for the path we join on\n        // we need to find the index inside the map operator\n        // because the indexes are only available after the initial sync\n        // so we can't fetch it during compilation\n        index ??= findIndexForField(\n          followRefCollection.indexes,\n          followRefResult.path\n        )\n\n        // The `callbacks` object is passed by the liveQueryCollection to the compiler.\n        // It contains a function to lazy load keys for each lazy collection\n        // as well as a function to switch back to a regular collection\n        // (useful when there's no index for available for lazily loading the collection)\n        const collectionCallbacks = callbacks[lazyCollection.id]\n        if (!collectionCallbacks) {\n          throw new Error(\n            `Internal error: callbacks for collection are missing in join pipeline. Make sure the live query collection sets them before running the pipeline.`\n          )\n        }\n\n        const { loadKeys, loadInitialState } = collectionCallbacks\n\n        if (index && index.supports(`eq`)) {\n          // Use the index to fetch the PKs of the rows in the lazy collection\n          // that match this row from the active collection based on the value of the joinKey\n          const matchingKeys = index.lookup(`eq`, joinKey)\n          // Inform the lazy collection that those keys need to be loaded\n          loadKeys(matchingKeys)\n        } else {\n          // We can't optimize the join because there is no index for the join key\n          // on the lazy collection, so we load the initial state\n          deoptimized = true\n          loadInitialState()\n        }\n      })\n    )\n\n    if (activeCollection === `main`) {\n      mainPipeline = activePipelineWithLoading\n    } else {\n      joinedPipeline = activePipelineWithLoading\n    }\n  }\n\n  return mainPipeline.pipe(\n    joinOperator(joinedPipeline, joinClause.type as JoinType),\n    consolidate(),\n    processJoinResults(joinClause.type)\n  )\n}\n\n/**\n * Analyzes join expressions to determine which refers to which table\n * and returns them in the correct order (main table expression first, joined table expression second)\n */\nfunction analyzeJoinExpressions(\n  left: BasicExpression,\n  right: BasicExpression,\n  mainTableAlias: string,\n  joinedTableAlias: string\n): { mainExpr: BasicExpression; joinedExpr: BasicExpression } {\n  const leftTableAlias = getTableAliasFromExpression(left)\n  const rightTableAlias = getTableAliasFromExpression(right)\n\n  // If left expression refers to main table and right refers to joined table, keep as is\n  if (\n    leftTableAlias === mainTableAlias &&\n    rightTableAlias === joinedTableAlias\n  ) {\n    return { mainExpr: left, joinedExpr: right }\n  }\n\n  // If left expression refers to joined table and right refers to main table, swap them\n  if (\n    leftTableAlias === joinedTableAlias &&\n    rightTableAlias === mainTableAlias\n  ) {\n    return { mainExpr: right, joinedExpr: left }\n  }\n\n  // If both expressions refer to the same alias, this is an invalid join\n  if (leftTableAlias === rightTableAlias) {\n    throw new InvalidJoinConditionSameTableError(leftTableAlias || `unknown`)\n  }\n\n  // If one expression doesn't refer to either table, this is an invalid join\n  if (!leftTableAlias || !rightTableAlias) {\n    throw new InvalidJoinConditionTableMismatchError(\n      mainTableAlias,\n      joinedTableAlias\n    )\n  }\n\n  // If expressions refer to tables not involved in this join, this is an invalid join\n  throw new InvalidJoinConditionWrongTablesError(\n    leftTableAlias,\n    rightTableAlias,\n    mainTableAlias,\n    joinedTableAlias\n  )\n}\n\n/**\n * Extracts the table alias from a join expression\n */\nfunction getTableAliasFromExpression(expr: BasicExpression): string | null {\n  switch (expr.type) {\n    case `ref`:\n      // PropRef path has the table alias as the first element\n      return expr.path[0] || null\n    case `func`: {\n      // For function expressions, we need to check if all arguments refer to the same table\n      const tableAliases = new Set<string>()\n      for (const arg of expr.args) {\n        const alias = getTableAliasFromExpression(arg)\n        if (alias) {\n          tableAliases.add(alias)\n        }\n      }\n      // If all arguments refer to the same table, return that table alias\n      return tableAliases.size === 1 ? Array.from(tableAliases)[0]! : null\n    }\n    default:\n      // Values (type='val') don't reference any table\n      return null\n  }\n}\n\n/**\n * Processes the join source (collection or sub-query)\n */\nfunction processJoinSource(\n  from: CollectionRef | QueryRef,\n  allInputs: Record<string, KeyedStream>,\n  collections: Record<string, Collection>,\n  callbacks: Record<string, LazyCollectionCallbacks>,\n  lazyCollections: Set<string>,\n  optimizableOrderByCollections: Record<string, OrderByOptimizationInfo>,\n  cache: QueryCache,\n  queryMapping: QueryMapping\n): { alias: string; input: KeyedStream; collectionId: string } {\n  switch (from.type) {\n    case `collectionRef`: {\n      const input = allInputs[from.collection.id]\n      if (!input) {\n        throw new CollectionInputNotFoundError(from.collection.id)\n      }\n      return { alias: from.alias, input, collectionId: from.collection.id }\n    }\n    case `queryRef`: {\n      // Find the original query for caching purposes\n      const originalQuery = queryMapping.get(from.query) || from.query\n\n      // Recursively compile the sub-query with cache\n      const subQueryResult = compileQuery(\n        originalQuery,\n        allInputs,\n        collections,\n        callbacks,\n        lazyCollections,\n        optimizableOrderByCollections,\n        cache,\n        queryMapping\n      )\n\n      // Extract the pipeline from the compilation result\n      const subQueryInput = subQueryResult.pipeline\n\n      // Subqueries may return [key, [value, orderByIndex]] (with ORDER BY) or [key, value] (without ORDER BY)\n      // We need to extract just the value for use in parent queries\n      const extractedInput = subQueryInput.pipe(\n        map((data: any) => {\n          const [key, [value, _orderByIndex]] = data\n          return [key, value] as [unknown, any]\n        })\n      )\n\n      return {\n        alias: from.alias,\n        input: extractedInput as KeyedStream,\n        collectionId: subQueryResult.collectionId,\n      }\n    }\n    default:\n      throw new UnsupportedJoinSourceTypeError((from as any).type)\n  }\n}\n\n/**\n * Processes the results of a join operation\n */\nfunction processJoinResults(joinType: string) {\n  return function (\n    pipeline: IStreamBuilder<\n      [\n        key: string,\n        [\n          [string, NamespacedRow] | undefined,\n          [string, NamespacedRow] | undefined,\n        ],\n      ]\n    >\n  ): NamespacedAndKeyedStream {\n    return pipeline.pipe(\n      // Process the join result and handle nulls\n      filter((result) => {\n        const [_key, [main, joined]] = result\n        const mainNamespacedRow = main?.[1]\n        const joinedNamespacedRow = joined?.[1]\n\n        // Handle different join types\n        if (joinType === `inner`) {\n          return !!(mainNamespacedRow && joinedNamespacedRow)\n        }\n\n        if (joinType === `left`) {\n          return !!mainNamespacedRow\n        }\n\n        if (joinType === `right`) {\n          return !!joinedNamespacedRow\n        }\n\n        // For full joins, always include\n        return true\n      }),\n      map((result) => {\n        const [_key, [main, joined]] = result\n        const mainKey = main?.[0]\n        const mainNamespacedRow = main?.[1]\n        const joinedKey = joined?.[0]\n        const joinedNamespacedRow = joined?.[1]\n\n        // Merge the namespaced rows\n        const mergedNamespacedRow: NamespacedRow = {}\n\n        // Add main row data if it exists\n        if (mainNamespacedRow) {\n          Object.assign(mergedNamespacedRow, mainNamespacedRow)\n        }\n\n        // Add joined row data if it exists\n        if (joinedNamespacedRow) {\n          Object.assign(mergedNamespacedRow, joinedNamespacedRow)\n        }\n\n        // We create a composite key that combines the main and joined keys\n        const resultKey = `[${mainKey},${joinedKey}]`\n\n        return [resultKey, mergedNamespacedRow] as [string, NamespacedRow]\n      })\n    )\n  }\n}\n\n/**\n * Returns the active and lazy collections for a join clause.\n * The active collection is the one that we need to fully iterate over\n * and it can be the main table (i.e. left collection) or the joined table (i.e. right collection).\n * The lazy collection is the one that we should join-in lazily based on matches in the active collection.\n * @param joinClause - The join clause to analyze\n * @param leftCollection - The left collection\n * @param rightCollection - The right collection\n * @returns The active and lazy collections. They are undefined if we need to loop over both collections (i.e. both are active)\n */\nfunction getActiveAndLazyCollections(\n  joinType: JoinClause[`type`],\n  leftCollection: Collection,\n  rightCollection: Collection\n):\n  | { activeCollection: `main` | `joined`; lazyCollection: Collection }\n  | { activeCollection: undefined; lazyCollection: undefined } {\n  if (leftCollection.id === rightCollection.id) {\n    // We can't apply this optimization if there's only one collection\n    // because `liveQueryCollection` will detect that the collection is lazy\n    // and treat it lazily (because the collection is shared)\n    // and thus it will not load any keys because both sides of the join\n    // will be handled lazily\n    return { activeCollection: undefined, lazyCollection: undefined }\n  }\n\n  switch (joinType) {\n    case `left`:\n      return { activeCollection: `main`, lazyCollection: rightCollection }\n    case `right`:\n      return { activeCollection: `joined`, lazyCollection: leftCollection }\n    case `inner`:\n      // The smallest collection should be the active collection\n      // and the biggest collection should be lazy\n      return leftCollection.size < rightCollection.size\n        ? { activeCollection: `main`, lazyCollection: rightCollection }\n        : { activeCollection: `joined`, lazyCollection: leftCollection }\n    default:\n      return { activeCollection: undefined, lazyCollection: undefined }\n  }\n}\n"],"names":["joinOperator"],"mappings":"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"}

package/dist/esm/query/compiler/order-by.d.ts

@@ -1,9 +1,19 @@
-import { OrderByClause } from '../ir.js';
+import { OrderByClause, QueryIR } from '../ir.js';
 import { NamespacedAndKeyedStream, NamespacedRow } from '../../types.js';
 import { IStreamBuilder, KeyValue } from '@tanstack/db-ivm';
+import { BaseIndex } from '../../indexes/base-index.js';
+import { Collection } from '../../collection.js';
+export type OrderByOptimizationInfo = {
+    offset: number;
+    limit: number;
+    comparator: (a: Record<string, unknown> | null | undefined, b: Record<string, unknown> | null | undefined) => number;
+    valueExtractorForRawRow: (row: Record<string, unknown>) => any;
+    index: BaseIndex<string | number>;
+    dataNeeded?: () => number;
+};
 /**
  * Processes the ORDER BY clause
  * Works with the new structure that has both namespaced row data and __select_results
  * Always uses fractional indexing and adds the index as __ordering_index to the result
  */
-export declare function processOrderBy(pipeline: NamespacedAndKeyedStream, orderByClause: Array<OrderByClause>, limit?: number, offset?: number): IStreamBuilder<KeyValue<unknown, [NamespacedRow, string]>>;
+export declare function processOrderBy(rawQuery: QueryIR, pipeline: NamespacedAndKeyedStream, orderByClause: Array<OrderByClause>, collection: Collection, optimizableOrderByCollections: Record<string, OrderByOptimizationInfo>, limit?: number, offset?: number): IStreamBuilder<KeyValue<unknown, [NamespacedRow, string]>>;

package/dist/esm/query/compiler/order-by.js

@@ -1,7 +1,11 @@
 import { orderByWithFractionalIndex } from "@tanstack/db-ivm";
 import { makeComparator, defaultComparator } from "../../utils/comparison.js";
+import { PropRef } from "../ir.js";
+import { ensureIndexForField } from "../../indexes/auto-index.js";
+import { findIndexForField } from "../../utils/index-optimization.js";
 import { compileExpression } from "./evaluators.js";
-function processOrderBy(pipeline, orderByClause, limit, offset) {
+import { followRef } from "./index.js";
+function processOrderBy(rawQuery, pipeline, orderByClause, collection, optimizableOrderByCollections, limit, offset) {
   const compiledOrderBy = orderByClause.map((clause) => ({
     compiledExpression: compileExpression(clause.expression),
     compareOptions: clause.compareOptions
@@ -21,7 +25,7 @@ function processOrderBy(pipeline, orderByClause, limit, offset) {
     }
     return null;
   };
-  const comparator = (a, b) => {
+  const compare = (a, b) => {
     if (orderByClause.length > 1) {
       const arrayA = a;
       const arrayB = b;
@@ -42,11 +46,66 @@ function processOrderBy(pipeline, orderByClause, limit, offset) {
     }
     return defaultComparator(a, b);
   };
+  let setSizeCallback;
+  if (limit && orderByClause.length === 1) {
+    const clause = orderByClause[0];
+    const orderByExpression = clause.expression;
+    if (orderByExpression.type === `ref`) {
+      const followRefResult = followRef(
+        rawQuery,
+        orderByExpression,
+        collection
+      );
+      const followRefCollection = followRefResult.collection;
+      const fieldName = followRefResult.path[0];
+      if (fieldName) {
+        ensureIndexForField(
+          fieldName,
+          followRefResult.path,
+          followRefCollection,
+          compare
+        );
+      }
+      const valueExtractorForRawRow = compileExpression(
+        new PropRef(followRefResult.path),
+        true
+      );
+      const comparator = (a, b) => {
+        const extractedA = a ? valueExtractorForRawRow(a) : a;
+        const extractedB = b ? valueExtractorForRawRow(b) : b;
+        return compare(extractedA, extractedB);
+      };
+      const index = findIndexForField(
+        followRefCollection.indexes,
+        followRefResult.path
+      );
+      if (index && index.supports(`gt`)) {
+        const orderByOptimizationInfo = {
+          offset: offset ?? 0,
+          limit,
+          comparator,
+          valueExtractorForRawRow,
+          index
+        };
+        optimizableOrderByCollections[followRefCollection.id] = orderByOptimizationInfo;
+        setSizeCallback = (getSize) => {
+          optimizableOrderByCollections[followRefCollection.id] = {
+            ...optimizableOrderByCollections[followRefCollection.id],
+            dataNeeded: () => {
+              const size = getSize();
+              return Math.max(0, limit - size);
+            }
+          };
+        };
+      }
+    }
+  }
   return pipeline.pipe(
     orderByWithFractionalIndex(valueExtractor, {
       limit,
       offset,
-      comparator
+      comparator: compare,
+      setSizeCallback
     })
     // orderByWithFractionalIndex returns [key, [value, index]] - we keep this format
   );

package/dist/esm/query/compiler/order-by.js.map

@@ -1 +1 @@
-{"version":3,"file":"order-by.js","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":[],"mappings":";;;AAYO,SAAS,eACd,UACA,eACA,OACA,QAC4D;AAE5D,QAAM,kBAAkB,cAAc,IAAI,CAAC,YAAY;AAAA,IACrD,oBAAoB,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,YAAY,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,YAAY,eAAe,OAAO,cAAc;AACtD,aAAO,UAAU,GAAG,CAAC;AAAA,IACvB;AAEA,WAAO,kBAAkB,GAAG,CAAC;AAAA,EAC/B;AAGA,SAAO,SAAS;AAAA,IACd,2BAA2B,gBAAgB;AAAA,MACzC;AAAA,MACA;AAAA,MACA;AAAA,IAAA,CACD;AAAA;AAAA,EAAA;AAGL;"}
+{"version":3,"file":"order-by.js","sources":["../../../../src/query/compiler/order-by.ts"],"sourcesContent":["import { orderByWithFractionalIndex } from \"@tanstack/db-ivm\"\nimport { defaultComparator, makeComparator } from \"../../utils/comparison.js\"\nimport { PropRef } from \"../ir.js\"\nimport { ensureIndexForField } from \"../../indexes/auto-index.js\"\nimport { findIndexForField } from \"../../utils/index-optimization.js\"\nimport { compileExpression } from \"./evaluators.js\"\nimport { followRef } from \"./index.js\"\nimport type { CompiledSingleRowExpression } from \"./evaluators.js\"\nimport type { OrderByClause, QueryIR } from \"../ir.js\"\nimport type { NamespacedAndKeyedStream, NamespacedRow } from \"../../types.js\"\nimport type { IStreamBuilder, KeyValue } from \"@tanstack/db-ivm\"\nimport type { BaseIndex } from \"../../indexes/base-index.js\"\nimport type { Collection } from \"../../collection.js\"\n\nexport type OrderByOptimizationInfo = {\n  offset: number\n  limit: number\n  comparator: (\n    a: Record<string, unknown> | null | undefined,\n    b: Record<string, unknown> | null | undefined\n  ) => number\n  valueExtractorForRawRow: (row: Record<string, unknown>) => any\n  index: BaseIndex<string | number>\n  dataNeeded?: () => number\n}\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  rawQuery: QueryIR,\n  pipeline: NamespacedAndKeyedStream,\n  orderByClause: Array<OrderByClause>,\n  collection: Collection,\n  optimizableOrderByCollections: Record<string, OrderByOptimizationInfo>,\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 compare = (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  let setSizeCallback: ((getSize: () => number) => void) | undefined\n\n  // Optimize the orderBy operator to lazily load elements\n  // by using the range index of the collection.\n  // Only for orderBy clause on a single column for now (no composite ordering)\n  if (limit && orderByClause.length === 1) {\n    const clause = orderByClause[0]!\n    const orderByExpression = clause.expression\n\n    if (orderByExpression.type === `ref`) {\n      const followRefResult = followRef(\n        rawQuery,\n        orderByExpression,\n        collection\n      )!\n\n      const followRefCollection = followRefResult.collection\n      const fieldName = followRefResult.path[0]\n      if (fieldName) {\n        ensureIndexForField(\n          fieldName,\n          followRefResult.path,\n          followRefCollection,\n          compare\n        )\n      }\n\n      const valueExtractorForRawRow = compileExpression(\n        new PropRef(followRefResult.path),\n        true\n      ) as CompiledSingleRowExpression\n\n      const comparator = (\n        a: Record<string, unknown> | null | undefined,\n        b: Record<string, unknown> | null | undefined\n      ) => {\n        const extractedA = a ? valueExtractorForRawRow(a) : a\n        const extractedB = b ? valueExtractorForRawRow(b) : b\n        return compare(extractedA, extractedB)\n      }\n\n      const index: BaseIndex<string | number> | undefined = findIndexForField(\n        followRefCollection.indexes,\n        followRefResult.path\n      )\n\n      if (index && index.supports(`gt`)) {\n        // We found an index that we can use to lazily load ordered data\n        const orderByOptimizationInfo = {\n          offset: offset ?? 0,\n          limit,\n          comparator,\n          valueExtractorForRawRow,\n          index,\n        }\n\n        optimizableOrderByCollections[followRefCollection.id] =\n          orderByOptimizationInfo\n\n        setSizeCallback = (getSize: () => number) => {\n          optimizableOrderByCollections[followRefCollection.id] = {\n            ...optimizableOrderByCollections[followRefCollection.id]!,\n            dataNeeded: () => {\n              const size = getSize()\n              return Math.max(0, limit - size)\n            },\n          }\n        }\n      }\n    }\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: compare,\n      setSizeCallback,\n    })\n    // orderByWithFractionalIndex returns [key, [value, index]] - we keep this format\n  )\n}\n"],"names":[],"mappings":"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"}

package/dist/esm/query/live-query-collection.js

@@ -1,5 +1,6 @@
 import { D2, output, MultiSet } from "@tanstack/db-ivm";
 import { createCollection } from "../collection.js";
+import { createFilterFunctionFromExpression } from "../change-events.js";
 import { compileQuery } from "./compiler/index.js";
 import { buildQuery, getQueryIR } from "./builder/index.js";
 import { convertToBasicExpression } from "./compiler/expressions.js";
@@ -25,6 +26,11 @@ function liveQueryCollectionOptions(config) {
   } : void 0;
   const collections = extractCollectionsFromQuery(query);
   const allCollectionsReady = () => {
+    return Object.values(collections).every(
+      (collection) => collection.isReady()
+    );
+  };
+  const allCollectionsReadyOrInitialCommit = () => {
     return Object.values(collections).every(
       (collection) => collection.status === `ready` || collection.status === `initialCommit`
     );
@@ -33,6 +39,9 @@ function liveQueryCollectionOptions(config) {
   let inputsCache;
   let pipelineCache;
   let collectionWhereClausesCache;
+  const lazyCollectionsCallbacks = {};
+  const lazyCollections = /* @__PURE__ */ new Set();
+  const optimizableOrderByCollections = {};
   const compileBasePipeline = () => {
     graphCache = new D2();
     inputsCache = Object.fromEntries(
@@ -44,7 +53,14 @@ function liveQueryCollectionOptions(config) {
     ({
       pipeline: pipelineCache,
       collectionWhereClauses: collectionWhereClausesCache
-    } = compileQuery(query, inputsCache));
+    } = compileQuery(
+      query,
+      inputsCache,
+      collections,
+      lazyCollectionsCallbacks,
+      lazyCollections,
+      optimizableOrderByCollections
+    ));
   };
   const maybeCompileBasePipeline = () => {
     if (!graphCache || !inputsCache || !pipelineCache) {
@@ -120,14 +136,18 @@ function liveQueryCollectionOptions(config) {
         })
       );
       graph.finalize();
-      const maybeRunGraph = () => {
-        if (allCollectionsReady()) {
+      let subscribedToAllCollections = false;
+      const maybeRunGraph = (callback) => {
+        if (allCollectionsReadyOrInitialCommit() && subscribedToAllCollections) {
           graph.run();
+          const ready = (callback == null ? void 0 : callback()) ?? true;
           if (messagesCount === 0) {
             begin();
             commit();
           }
-          markReady();
+          if (ready && allCollectionsReady()) {
+            markReady();
+          }
         }
       };
       const unsubscribeCallbacks = /* @__PURE__ */ new Set();
@@ -135,39 +155,159 @@ function liveQueryCollectionOptions(config) {
         const input = inputs[collectionId];
         const collectionAlias = findCollectionAlias(collectionId, query);
         const whereClause = collectionAlias && collectionWhereClausesCache ? collectionWhereClausesCache.get(collectionAlias) : void 0;
+        const sendChangesToPipeline = (changes, callback) => {
+          sendChangesToInput(input, changes, collection.config.getKey);
+          maybeRunGraph(callback);
+        };
+        const sendVisibleChangesToPipeline = (changes, loadedInitialState, sentKeys) => {
+          if (loadedInitialState) {
+            return sendChangesToPipeline(changes);
+          }
+          const newChanges = [];
+          for (const change of changes) {
+            let newChange = change;
+            if (!sentKeys.has(change.key)) {
+              if (change.type === `update`) {
+                newChange = { ...change, type: `insert` };
+              } else if (change.type === `delete`) {
+                continue;
+              }
+            }
+            newChanges.push(newChange);
+          }
+          return sendChangesToPipeline(newChanges);
+        };
+        const loadKeys = (keys, sentKeys, filterFn) => {
+          for (const key of keys) {
+            if (sentKeys.has(key)) continue;
+            const value = collection.get(key);
+            if (value !== void 0 && filterFn(value)) {
+              sentKeys.add(key);
+              sendChangesToPipeline([{ type: `insert`, key, value }]);
+            }
+          }
+        };
+        const subscribeToAllChanges = (whereExpression) => {
+          const unsubscribe = collection.subscribeChanges(
+            sendChangesToPipeline,
+            {
+              includeInitialState: true,
+              ...whereExpression ? { whereExpression } : void 0
+            }
+          );
+          return unsubscribe;
+        };
+        const subscribeToMatchingChanges = (whereExpression) => {
+          let loadedInitialState = false;
+          const sentKeys = /* @__PURE__ */ new Set();
+          const sendVisibleChanges = (changes) => {
+            sendVisibleChangesToPipeline(changes, loadedInitialState, sentKeys);
+          };
+          const unsubscribe = collection.subscribeChanges(sendVisibleChanges, {
+            whereExpression
+          });
+          const filterFn = whereExpression ? createFilterFunctionFromExpression(whereExpression) : () => true;
+          const loadKs = (keys) => {
+            return loadKeys(keys, sentKeys, filterFn);
+          };
+          lazyCollectionsCallbacks[collectionId] = {
+            loadKeys: loadKs,
+            loadInitialState: () => {
+              if (loadedInitialState) return;
+              loadedInitialState = true;
+              const changes = collection.currentStateAsChanges({
+                whereExpression
+              });
+              sendChangesToPipeline(changes);
+            }
+          };
+          return unsubscribe;
+        };
+        const subscribeToOrderedChanges = (whereExpression) => {
+          const {
+            offset,
+            limit,
+            comparator,
+            index,
+            dataNeeded,
+            valueExtractorForRawRow
+          } = optimizableOrderByCollections[collectionId];
+          if (!dataNeeded) {
+            throw new Error(
+              `Missing dataNeeded callback for collection ${collectionId}`
+            );
+          }
+          const loadMoreIfNeeded = () => {
+            const n = dataNeeded();
+            if (n > 0) {
+              loadNextItems(n);
+            }
+            return n === 0;
+          };
+          const sentValuesInfo = {
+            sentKeys: /* @__PURE__ */ new Set(),
+            biggest: void 0
+          };
+          const sendChangesToPipelineWithTracking = (changes) => {
+            const trackedChanges = trackSentValues(
+              changes,
+              comparator,
+              sentValuesInfo
+            );
+            sendChangesToPipeline(trackedChanges, loadMoreIfNeeded);
+          };
+          const loadNextItems = (n) => {
+            const biggestSentRow = sentValuesInfo.biggest;
+            const biggestSentValue = biggestSentRow ? valueExtractorForRawRow(biggestSentRow) : biggestSentRow;
+            const nextOrderedKeys = index.take(n, biggestSentValue);
+            const nextInserts = nextOrderedKeys.map((key) => {
+              return { type: `insert`, key, value: collection.get(key) };
+            });
+            sendChangesToPipelineWithTracking(nextInserts);
+          };
+          loadNextItems(offset + limit);
+          const sendChangesInRange = (changes) => {
+            const splittedChanges = splitUpdates(changes);
+            const filteredChanges = filterChangesSmallerOrEqualToMax(
+              splittedChanges,
+              comparator,
+              sentValuesInfo.biggest
+            );
+            sendChangesToPipeline(filteredChanges, loadMoreIfNeeded);
+          };
+          const unsubscribe = collection.subscribeChanges(sendChangesInRange, {
+            whereExpression
+          });
+          return unsubscribe;
+        };
+        const subscribeToChanges = (whereExpression) => {
+          let unsubscribe;
+          if (lazyCollections.has(collectionId)) {
+            unsubscribe = subscribeToMatchingChanges(whereExpression);
+          } else if (Object.hasOwn(optimizableOrderByCollections, collectionId)) {
+            unsubscribe = subscribeToOrderedChanges(whereExpression);
+          } else {
+            unsubscribe = subscribeToAllChanges(whereExpression);
+          }
+          unsubscribeCallbacks.add(unsubscribe);
+        };
         if (whereClause) {
           const whereExpression = convertToBasicExpression(
             whereClause,
             collectionAlias
           );
           if (whereExpression) {
-            const subscription = collection.subscribeChanges(
-              (changes) => {
-                sendChangesToInput(input, changes, collection.config.getKey);
-                maybeRunGraph();
-              },
-              {
-                includeInitialState: true,
-                whereExpression
-              }
-            );
-            unsubscribeCallbacks.add(subscription);
+            subscribeToChanges(whereExpression);
           } else {
             throw new Error(
               `Failed to convert WHERE clause to collection filter for collection '${collectionId}'. This indicates a bug in the query optimization logic.`
             );
           }
         } else {
-          const subscription = collection.subscribeChanges(
-            (changes) => {
-              sendChangesToInput(input, changes, collection.config.getKey);
-              maybeRunGraph();
-            },
-            { includeInitialState: true }
-          );
-          unsubscribeCallbacks.add(subscription);
+          subscribeToChanges();
         }
       });
+      subscribedToAllCollections = true;
       maybeRunGraph();
       return () => {
         unsubscribeCallbacks.forEach((unsubscribe) => unsubscribe());
@@ -260,6 +400,39 @@ function findCollectionAlias(collectionId, query) {
   }
   return void 0;
 }
+function* trackSentValues(changes, comparator, tracker) {
+  for (const change of changes) {
+    tracker.sentKeys.add(change.key);
+    if (!tracker.biggest) {
+      tracker.biggest = change.value;
+    } else if (comparator(tracker.biggest, change.value) < 0) {
+      tracker.biggest = change.value;
+    }
+    yield change;
+  }
+}
+function* splitUpdates(changes) {
+  for (const change of changes) {
+    if (change.type === `update`) {
+      yield { type: `delete`, key: change.key, value: change.previousValue };
+      yield { type: `insert`, key: change.key, value: change.value };
+    } else {
+      yield change;
+    }
+  }
+}
+function* filterChanges(changes, f) {
+  for (const change of changes) {
+    if (f(change)) {
+      yield change;
+    }
+  }
+}
+function* filterChangesSmallerOrEqualToMax(changes, comparator, maxValue) {
+  yield* filterChanges(changes, (change) => {
+    return !maxValue || comparator(change.value, maxValue) <= 0;
+  });
+}
 export {
   createLiveQueryCollection,
   liveQueryCollectionOptions