@tanstack/db/dist/esm/query/compiler/joins.js

A reactive client store for building super fast apps on sync

import { map, tap, join, filter } from "@tanstack/db-ivm";
import { JoinCollectionNotFoundError, UnsupportedJoinTypeError, SubscriptionNotFoundError, UnsupportedJoinSourceTypeError, CollectionInputNotFoundError, InvalidJoinConditionSourceMismatchError, InvalidJoinConditionSameSourceError, InvalidJoinConditionLeftSourceError, InvalidJoinConditionRightSourceError, InvalidJoinCondition } from "../../errors.js";
import { normalizeValue } from "../../utils/comparison.js";
import { ensureIndexForField } from "../../indexes/auto-index.js";
import { PropRef } from "../ir.js";
import { inArray } from "../builder/functions.js";
import { compileExpression } from "./evaluators.js";
import { getLazyLoadTargets } from "./lazy-targets.js";
function processJoins(pipeline, joinClauses, sources, mainCollectionId, mainSource, allInputs, cache, queryMapping, collections, subscriptions, callbacks, lazySources, optimizableOrderByCollections, setWindowFn, rawQuery, onCompileSubquery, aliasToCollectionId, aliasRemapping, sourceWhereClauses) {
  let resultPipeline = pipeline;
  for (const joinClause of joinClauses) {
    resultPipeline = processJoin(
      resultPipeline,
      joinClause,
      sources,
      mainCollectionId,
      mainSource,
      allInputs,
      cache,
      queryMapping,
      collections,
      subscriptions,
      callbacks,
      lazySources,
      optimizableOrderByCollections,
      setWindowFn,
      rawQuery,
      onCompileSubquery,
      aliasToCollectionId,
      aliasRemapping,
      sourceWhereClauses
    );
  }
  return resultPipeline;
}
function processJoin(pipeline, joinClause, sources, mainCollectionId, mainSource, allInputs, cache, queryMapping, collections, subscriptions, callbacks, lazySources, optimizableOrderByCollections, setWindowFn, rawQuery, onCompileSubquery, aliasToCollectionId, aliasRemapping, sourceWhereClauses) {
  const isCollectionRef = joinClause.from.type === `collectionRef`;
  const {
    alias: joinedSource,
    input: joinedInput,
    collectionId: joinedCollectionId
  } = processJoinSource(
    joinClause.from,
    allInputs,
    collections,
    subscriptions,
    callbacks,
    lazySources,
    optimizableOrderByCollections,
    setWindowFn,
    cache,
    queryMapping,
    onCompileSubquery,
    aliasToCollectionId,
    aliasRemapping,
    sourceWhereClauses
  );
  sources[joinedSource] = joinedInput;
  if (isCollectionRef) {
    aliasToCollectionId[joinedSource] = joinedCollectionId;
  }
  const mainCollection = collections[mainCollectionId];
  const joinedCollection = collections[joinedCollectionId];
  if (!mainCollection) {
    throw new JoinCollectionNotFoundError(mainCollectionId);
  }
  if (!joinedCollection) {
    throw new JoinCollectionNotFoundError(joinedCollectionId);
  }
  const { activeSource, lazySource } = getActiveAndLazySources(
    joinClause.type,
    mainCollection,
    joinedCollection
  );
  const availableSources = Object.keys(sources);
  const { mainExpr, joinedExpr } = analyzeJoinExpressions(
    joinClause.left,
    joinClause.right,
    availableSources,
    joinedSource,
    rawQuery.from.type === `unionAll`
  );
  const compiledMainExpr = compileExpression(mainExpr);
  const compiledJoinedExpr = compileExpression(joinedExpr);
  let mainPipeline = pipeline.pipe(
    map(([currentKey, namespacedRow]) => {
      const mainKey = normalizeValue(compiledMainExpr(namespacedRow));
      return [mainKey, [currentKey, namespacedRow]];
    })
  );
  let joinedPipeline = joinedInput.pipe(
    map(([currentKey, row]) => {
      const namespacedRow = { [joinedSource]: row };
      const joinedKey = normalizeValue(compiledJoinedExpr(namespacedRow));
      return [joinedKey, [currentKey, namespacedRow]];
    })
  );
  if (![`inner`, `left`, `right`, `full`].includes(joinClause.type)) {
    throw new UnsupportedJoinTypeError(joinClause.type);
  }
  if (activeSource) {
    const lazyFrom = activeSource === `main` ? joinClause.from : rawQuery.from;
    const limitedSubquery = lazyFrom.type === `queryRef` && (lazyFrom.query.limit || lazyFrom.query.offset);
    const resultUnionLazySide = lazyFrom.type === `unionAll`;
    const lazySourceJoinExpr = activeSource === `main` ? joinedExpr : mainExpr;
    const lazyAlias = activeSource === `main` ? joinedSource : mainSource;
    const lazyTargets = resultUnionLazySide ? [] : getLazyLoadTargets(
      rawQuery,
      lazyFrom,
      lazyAlias,
      lazySourceJoinExpr,
      lazySource,
      aliasRemapping
    );
    if (!limitedSubquery && lazyTargets.length > 0) {
      for (const target of lazyTargets) {
        lazySources.add(target.alias);
      }
      const activePipeline = activeSource === `main` ? mainPipeline : joinedPipeline;
      for (const target of lazyTargets) {
        const fieldName = target.path[0];
        if (fieldName) {
          ensureIndexForField(fieldName, target.path, target.collection);
        }
      }
      const activePipelineWithLoading = activePipeline.pipe(
        tap((data) => {
          const joinKeys = [
            ...new Set(
              data.getInner().map(([[joinKey]]) => joinKey).filter((key) => key != null)
            )
          ];
          if (joinKeys.length === 0) {
            return;
          }
          for (const target of lazyTargets) {
            const lazySourceSubscription = subscriptions[target.alias];
            if (!lazySourceSubscription) {
              throw new SubscriptionNotFoundError(
                target.alias,
                lazyAlias,
                target.collection.id,
                Object.keys(subscriptions)
              );
            }
            if (lazySourceSubscription.hasLoadedInitialState()) {
              continue;
            }
            const lazyJoinRef = new PropRef(target.path);
            const loaded = lazySourceSubscription.requestSnapshot({
              where: inArray(lazyJoinRef, joinKeys),
              optimizedOnly: true
            });
            if (!loaded) {
              const collectionId = target.collection.id;
              const fieldPath = target.path.join(`.`);
              console.warn(
                `[TanStack DB]${collectionId ? ` [${collectionId}]` : ``} Join requires an index on "${fieldPath}" for efficient loading. Falling back to loading all data. Consider creating an index on the collection with collection.createIndex((row) => row.${fieldPath}) or enable auto-indexing with autoIndex: 'eager' and a defaultIndexType.`
              );
              lazySourceSubscription.requestSnapshot();
            }
          }
        })
      );
      if (activeSource === `main`) {
        mainPipeline = activePipelineWithLoading;
      } else {
        joinedPipeline = activePipelineWithLoading;
      }
    }
  }
  return mainPipeline.pipe(
    join(joinedPipeline, joinClause.type),
    processJoinResults(joinClause.type)
  );
}
function analyzeJoinExpressions(left, right, allAvailableSourceAliases, joinedSource, allowResultFields = false) {
  const availableSources = allAvailableSourceAliases.filter(
    (alias) => alias !== joinedSource
  );
  const leftSourceAliases = getSourceAliasesFromExpression(left);
  const rightSourceAliases = getSourceAliasesFromExpression(right);
  const leftReferencesJoined = leftSourceAliases.has(joinedSource);
  const rightReferencesJoined = rightSourceAliases.has(joinedSource);
  const leftAvailableAliases = [...leftSourceAliases].filter(
    (alias) => availableSources.includes(alias) || allowResultFields && alias !== joinedSource
  );
  const rightAvailableAliases = [...rightSourceAliases].filter(
    (alias) => availableSources.includes(alias) || allowResultFields && alias !== joinedSource
  );
  if (leftAvailableAliases.length > 0 && !leftReferencesJoined && rightReferencesJoined && rightAvailableAliases.length === 0) {
    return { mainExpr: left, joinedExpr: right };
  }
  if (leftReferencesJoined && leftAvailableAliases.length === 0 && rightAvailableAliases.length > 0 && !rightReferencesJoined) {
    return { mainExpr: right, joinedExpr: left };
  }
  if (leftSourceAliases.size === 0 || rightSourceAliases.size === 0) {
    throw new InvalidJoinConditionSourceMismatchError();
  }
  if (leftSourceAliases.size === 1 && rightSourceAliases.size === 1 && [...leftSourceAliases][0] === [...rightSourceAliases][0]) {
    throw new InvalidJoinConditionSameSourceError([...leftSourceAliases][0]);
  }
  if (leftAvailableAliases.length === 0) {
    throw new InvalidJoinConditionLeftSourceError([...leftSourceAliases][0]);
  }
  if (!rightReferencesJoined) {
    throw new InvalidJoinConditionRightSourceError(joinedSource);
  }
  throw new InvalidJoinCondition();
}
function getSourceAliasesFromExpression(expr) {
  switch (expr.type) {
    case `ref`:
      return new Set(expr.path[0] ? [expr.path[0]] : []);
    case `func`: {
      const sourceAliases = /* @__PURE__ */ new Set();
      for (const arg of expr.args) {
        for (const alias of getSourceAliasesFromExpression(arg)) {
          sourceAliases.add(alias);
        }
      }
      return sourceAliases;
    }
    default:
      return /* @__PURE__ */ new Set();
  }
}
function processJoinSource(from, allInputs, collections, subscriptions, callbacks, lazySources, optimizableOrderByCollections, setWindowFn, cache, queryMapping, onCompileSubquery, aliasToCollectionId, aliasRemapping, sourceWhereClauses) {
  switch (from.type) {
    case `collectionRef`: {
      const input = allInputs[from.alias];
      if (!input) {
        throw new CollectionInputNotFoundError(
          from.alias,
          from.collection.id,
          Object.keys(allInputs)
        );
      }
      aliasToCollectionId[from.alias] = from.collection.id;
      return { alias: from.alias, input, collectionId: from.collection.id };
    }
    case `queryRef`: {
      const originalQuery = queryMapping.get(from.query) || from.query;
      const subQueryResult = onCompileSubquery(
        originalQuery,
        allInputs,
        collections,
        subscriptions,
        callbacks,
        lazySources,
        optimizableOrderByCollections,
        setWindowFn,
        cache,
        queryMapping
      );
      Object.assign(aliasToCollectionId, subQueryResult.aliasToCollectionId);
      Object.assign(aliasRemapping, subQueryResult.aliasRemapping);
      const isUserDefinedSubquery = queryMapping.has(from.query);
      const fromInnerAlias = getFirstFromAlias(from.query);
      const isOptimizerCreated = !isUserDefinedSubquery && fromInnerAlias !== void 0 && from.alias === fromInnerAlias;
      if (!isOptimizerCreated) {
        for (const [alias, whereClause] of subQueryResult.sourceWhereClauses) {
          sourceWhereClauses.set(alias, whereClause);
        }
      }
      const innerAlias = Object.keys(subQueryResult.aliasToCollectionId).find(
        (alias) => subQueryResult.aliasToCollectionId[alias] === subQueryResult.collectionId
      );
      if (innerAlias && innerAlias !== from.alias) {
        aliasRemapping[from.alias] = innerAlias;
      }
      const subQueryInput = subQueryResult.pipeline;
      const extractedInput = subQueryInput.pipe(
        map((data) => {
          const [key, [value, _orderByIndex]] = data;
          return [key, value];
        })
      );
      return {
        alias: from.alias,
        input: extractedInput,
        collectionId: subQueryResult.collectionId
      };
    }
    default:
      throw new UnsupportedJoinSourceTypeError(from.type);
  }
}
function getFirstFromAlias(query) {
  if (query.from.type === `unionFrom`) {
    return query.from.sources[0]?.alias;
  }
  if (query.from.type === `unionAll`) {
    return void 0;
  }
  return query.from.alias;
}
function processJoinResults(joinType) {
  return function(pipeline) {
    return pipeline.pipe(
      // Process the join result and handle nulls
      filter((result) => {
        const [_key, [main, joined]] = result;
        const mainNamespacedRow = main?.[1];
        const joinedNamespacedRow = joined?.[1];
        if (joinType === `inner`) {
          return !!(mainNamespacedRow && joinedNamespacedRow);
        }
        if (joinType === `left`) {
          return !!mainNamespacedRow;
        }
        if (joinType === `right`) {
          return !!joinedNamespacedRow;
        }
        return true;
      }),
      map((result) => {
        const [_key, [main, joined]] = result;
        const mainKey = main?.[0];
        const mainNamespacedRow = main?.[1];
        const joinedKey = joined?.[0];
        const joinedNamespacedRow = joined?.[1];
        const mergedNamespacedRow = {};
        if (mainNamespacedRow) {
          Object.assign(mergedNamespacedRow, mainNamespacedRow);
        }
        if (joinedNamespacedRow) {
          Object.assign(mergedNamespacedRow, joinedNamespacedRow);
        }
        const resultKey = `[${mainKey},${joinedKey}]`;
        return [resultKey, mergedNamespacedRow];
      })
    );
  };
}
function getActiveAndLazySources(joinType, leftCollection, rightCollection) {
  switch (joinType) {
    case `left`:
      return { activeSource: `main`, lazySource: rightCollection };
    case `right`:
      return { activeSource: `joined`, lazySource: leftCollection };
    case `inner`:
      return leftCollection.size < rightCollection.size ? { activeSource: `main`, lazySource: rightCollection } : { activeSource: `joined`, lazySource: leftCollection };
    default:
      return { activeSource: void 0, lazySource: void 0 };
  }
}
export {
  processJoins
};
//# sourceMappingURL=joins.js.map