Skip to content

🪢 Open source agent evals & observability: Trace, evaluate, and improve LLM applications with one open platform.

5.5 KB
Raw Blame
import {
  type IdentifierNode,
  type OperationNode,
  type SelectQueryNode,
} from "kysely";

/**
 * ClickHouse `ARRAY JOIN` / `LEFT ARRAY JOIN` / `INNER ARRAY JOIN`.
 *
 * Not a Kysely `OperationNode` kind — Kysely's `kind` union is closed, so a
 * real custom kind would collapse to `never`. These nodes live as extra
 * fields on {@link ClickHouseSelectQueryNode}. Children (`expression`,
 * `alias`) are traced Kysely nodes, not raw SQL.
 */
export type ArrayJoinVariant = "default" | "left" | "inner";

type ArrayJoinItemNode = {
  readonly expression: OperationNode;
  readonly alias: IdentifierNode;
};

export type ArrayJoinNode = {
  readonly kind: "ArrayJoinNode";
  readonly variant: ArrayJoinVariant;
  readonly items: ReadonlyArray<ArrayJoinItemNode>;
};

export const ArrayJoinNode = {
  is(node: { kind: string }): node is ArrayJoinNode {
    return node.kind === "ArrayJoinNode";
  },
  create(
    items: ReadonlyArray<ArrayJoinItemNode>,
    variant: ArrayJoinVariant = "default",
  ): ArrayJoinNode {
    return Object.freeze({
      kind: "ArrayJoinNode",
      variant,
      items: Object.freeze([...items]),
    });
  },
};

/**
 * ClickHouse `LIMIT n BY col1, col2, ...`.
 *
 * Distinct from Kysely's `LimitNode` (`LIMIT n`). ClickHouse places LIMIT BY
 * after ORDER BY and before a plain LIMIT.
 */
export type LimitByNode = {
  readonly kind: "LimitByNode";
  readonly count: OperationNode;
  readonly columns: ReadonlyArray<OperationNode>;
};

export const LimitByNode = {
  is(node: { kind: string }): node is LimitByNode {
    return node.kind === "LimitByNode";
  },
  create(
    count: OperationNode,
    columns: ReadonlyArray<OperationNode>,
  ): LimitByNode {
    return Object.freeze({
      kind: "LimitByNode",
      count,
      columns: Object.freeze([...columns]),
    });
  },
};

/**
 * ClickHouse array subscript `arr[index]`. Children are traced nodes
 * (typically a `mapFromArrays(...)` FunctionNode and a bound key), not raw SQL.
 *
 * Same closed-`kind` constraint as ARRAY JOIN: not a Kysely visitor-map
 * kind. The dialect compiler and transformer special-case this object.
 */
export type ArrayIndexNode = {
  readonly kind: "ArrayIndexNode";
  readonly array: OperationNode;
  readonly index: OperationNode;
  /**
   * `metadata[key]` over one relation's `metadata_names`/`metadata_values`,
   * so events routing can keep a short metadata predicate on `events_core`.
   */
  readonly metadataLookup?: true;
};

export const ArrayIndexNode = {
  is(node: { kind: string }): node is ArrayIndexNode {
    return node.kind === "ArrayIndexNode";
  },
  create(
    array: OperationNode,
    index: OperationNode,
    metadataLookup = false,
  ): ArrayIndexNode {
    return Object.freeze({
      kind: "ArrayIndexNode",
      array,
      index,
      ...(metadataLookup ? { metadataLookup: true as const } : {}),
    });
  },
};

/**
 * Select query extended with ClickHouse-only clauses.
 * Extra fields are ignored by Kysely's default compiler/transformer; our
 * dialect compiler and {@link ClickHouseOperationNodeTransformer} are the
 * ones that read them. Tenancy is stamped by identity (WeakSet), not a
 * copyable property on this node.
 */
export type ClickHouseSelectQueryNode = SelectQueryNode & {
  readonly arrayJoins?: ReadonlyArray<ArrayJoinNode>;
  readonly limitBy?: LimitByNode;
  /** Set by `includeDeleted()`: the soft-delete pass skips this select. */
  readonly includeDeleted?: true;
  /**
   * Set by `softDeleteAfterLimit()`: the soft-delete pass filters this
   * select's output instead of its relation.
   */
  readonly softDeleteAfterLimit?: true;
};

export function isClickHouseSelectQueryNode(
  node: OperationNode,
): node is ClickHouseSelectQueryNode {
  return node.kind === "SelectQueryNode";
}

/**
 * ClickHouse `FROM <table> FINAL` / `JOIN <table> AS alias FINAL`.
 *
 * Wraps a table expression (bare `TableNode` or `AliasNode`) so the compiler
 * emits `final` after that expression. Same closed-`kind` constraint as
 * ARRAY JOIN: not a Kysely visitor-map kind. The dialect compiler and
 * transformer special-case this object.
 */
export type FinalTableNode = {
  readonly kind: "FinalTableNode";
  readonly table: OperationNode;
};

export const FinalTableNode = {
  is(node: { kind: string }): node is FinalTableNode {
    return node.kind === "FinalTableNode";
  },
  create(table: OperationNode): FinalTableNode {
    return Object.freeze({
      kind: "FinalTableNode",
      table,
    });
  },
};

/** {@link FinalTableNode.create}, typed as the FROM/JOIN item it stands in for. */
export function finalTable(table: OperationNode): OperationNode {
  return FinalTableNode.create(table) as unknown as OperationNode;
}

/**
 * Read the wrapped table expression. `FinalTableNode.kind` is outside
 * Kysely's closed `OperationNodeKind`, so a narrowed
 * `OperationNode & FinalTableNode` is `never` and `.table` is unreadable
 * without this cast.
 */
export function unwrapFinalTable(node: { kind: string }): OperationNode {
  return (node as unknown as FinalTableNode).table;
}

/**
 * Calls `visit` on every node object under `value`, ClickHouse extra fields
 * included, parents before children. `visit` returns `false` to skip a
 * node's children.
 */
export function walkNodes(
  value: unknown,
  visit: (node: OperationNode) => boolean | void,
): void {
  if (!value || typeof value !== "object") return;
  if ("kind" in value && typeof value.kind === "string") {
    if (visit(value as OperationNode) === false) return;
  }
  for (const child of Object.values(value)) walkNodes(child, visit);
}