@rocicorp/zero 0.25.0-canary.0 → 0.25.0-canary.10

package/out/zql/src/planner/planner-join.js

@@ -0,0 +1,244 @@
+import { assert } from "../../../shared/src/asserts.js";
+import { mergeConstraints } from "./planner-constraint.js";
+import { omitFanout } from "./planner-node.js";
+function translateConstraintsForFlippedJoin(incomingConstraint, parentConstraint, childConstraint) {
+  if (!incomingConstraint) return void 0;
+  const parentKeys = Object.keys(parentConstraint);
+  const childKeys = Object.keys(childConstraint);
+  const translated = {};
+  for (const [key, value] of Object.entries(incomingConstraint)) {
+    const index = parentKeys.indexOf(key);
+    if (index !== -1) {
+      translated[childKeys[index]] = value;
+    }
+  }
+  return Object.keys(translated).length > 0 ? translated : void 0;
+}
+class PlannerJoin {
+  kind = "join";
+  #parent;
+  #child;
+  #parentConstraint;
+  #childConstraint;
+  #flippable;
+  planId;
+  #output;
+  // Set once during graph construction
+  // Reset between planning attempts
+  #type;
+  #initialType;
+  constructor(parent, child, parentConstraint, childConstraint, flippable, planId, initialType = "semi") {
+    this.#type = initialType;
+    this.#initialType = initialType;
+    this.#parent = parent;
+    this.#child = child;
+    this.#childConstraint = childConstraint;
+    this.#parentConstraint = parentConstraint;
+    this.#flippable = flippable;
+    this.planId = planId;
+  }
+  setOutput(node) {
+    this.#output = node;
+  }
+  get output() {
+    assert(this.#output !== void 0, "Output not set");
+    return this.#output;
+  }
+  closestJoinOrSource() {
+    return "join";
+  }
+  flipIfNeeded(input) {
+    if (input === this.#child) {
+      this.flip();
+    } else {
+      assert(
+        input === this.#parent,
+        "Can only flip a join from one of its inputs"
+      );
+    }
+  }
+  flip() {
+    assert(this.#type === "semi", "Can only flip a semi-join");
+    if (!this.#flippable) {
+      throw new UnflippableJoinError(
+        "Cannot flip a non-flippable join (e.g., NOT EXISTS)"
+      );
+    }
+    this.#type = "flipped";
+  }
+  get type() {
+    return this.#type;
+  }
+  isFlippable() {
+    return this.#flippable;
+  }
+  /**
+   * Propagate unlimiting when this join is flipped.
+   * When a join is flipped:
+   * 1. Child becomes outer loop → produces all rows (unlimited)
+   * 2. Parent is fetched once per child row → effectively unlimited
+   *
+   * Example: If child produces 896 rows, parent is fetched 896 times.
+   * Even if each fetch returns 1 row, parent produces 896 total rows.
+   *
+   * Propagation rules:
+   * - Connection: call unlimit()
+   * - Semi-join: continue to parent (outer loop)
+   * - Flipped join: stop (already unlimited when it was flipped)
+   * - Fan-out/Fan-in: propagate to all inputs
+   */
+  propagateUnlimit() {
+    assert(this.#type === "flipped", "Can only unlimit a flipped join");
+    this.#child.propagateUnlimitFromFlippedJoin();
+  }
+  /**
+   * Called when a parent join is flipped and this join is part of its child subgraph.
+   * Continue propagation to parent (the outer loop).
+   * If we are hitting a semi-join, the parent drives.
+   * If we are hitting a flip-join, well now we have to unlimit its parent too!
+   */
+  propagateUnlimitFromFlippedJoin() {
+    this.#parent.propagateUnlimitFromFlippedJoin();
+  }
+  propagateConstraints(branchPattern, constraint, from, planDebugger) {
+    planDebugger?.log({
+      type: "node-constraint",
+      nodeType: "join",
+      node: this.getName(),
+      branchPattern,
+      constraint,
+      from: from ? getNodeName(from) : "unknown"
+    });
+    if (this.#type === "semi") {
+      this.#child.propagateConstraints(
+        branchPattern,
+        this.#childConstraint,
+        this,
+        planDebugger
+      );
+      this.#parent.propagateConstraints(
+        branchPattern,
+        constraint,
+        this,
+        planDebugger
+      );
+    } else if (this.#type === "flipped") {
+      const translatedConstraint = translateConstraintsForFlippedJoin(
+        constraint,
+        this.#parentConstraint,
+        this.#childConstraint
+      );
+      this.#child.propagateConstraints(
+        branchPattern,
+        translatedConstraint,
+        this,
+        planDebugger
+      );
+      this.#parent.propagateConstraints(
+        branchPattern,
+        mergeConstraints(constraint, this.#parentConstraint),
+        this,
+        planDebugger
+      );
+    }
+  }
+  reset() {
+    this.#type = this.#initialType;
+  }
+  estimateCost(downstreamChildSelectivity, branchPattern, planDebugger) {
+    const child = this.#child.estimateCost(1, branchPattern, planDebugger);
+    const fanoutFactor = child.fanout(Object.keys(this.#childConstraint));
+    const scaledChildSelectivity = 1 - Math.pow(1 - child.selectivity, fanoutFactor.fanout);
+    const parent = this.#parent.estimateCost(
+      // Selectivity flows up the graph from child to parent
+      // so we can determine the total selectivity of all ANDed exists checks.
+      this.#type === "flipped" ? 1 * downstreamChildSelectivity : scaledChildSelectivity * downstreamChildSelectivity,
+      branchPattern,
+      planDebugger
+    );
+    let costEstimate;
+    if (this.type === "semi") {
+      costEstimate = {
+        startupCost: parent.startupCost,
+        scanEst: parent.limit === void 0 ? parent.returnedRows : Math.min(
+          parent.returnedRows,
+          downstreamChildSelectivity === 0 ? 0 : parent.limit / downstreamChildSelectivity
+        ),
+        cost: parent.cost + parent.scanEst * (child.startupCost + child.cost + child.scanEst),
+        returnedRows: parent.returnedRows * child.selectivity,
+        selectivity: child.selectivity * parent.selectivity,
+        limit: parent.limit,
+        fanout: parent.fanout
+      };
+    } else {
+      costEstimate = {
+        startupCost: child.startupCost,
+        scanEst: parent.limit === void 0 ? parent.returnedRows * child.returnedRows : Math.min(
+          parent.returnedRows * child.returnedRows,
+          downstreamChildSelectivity === 0 ? 0 : parent.limit / downstreamChildSelectivity
+        ),
+        cost: child.cost + child.scanEst * (parent.startupCost + parent.cost + parent.scanEst),
+        returnedRows: parent.returnedRows * child.returnedRows * child.selectivity,
+        selectivity: parent.selectivity * child.selectivity,
+        limit: parent.limit,
+        fanout: parent.fanout
+      };
+    }
+    if (planDebugger) {
+      planDebugger.log({
+        type: "node-cost",
+        nodeType: "join",
+        node: this.getName(),
+        branchPattern,
+        downstreamChildSelectivity,
+        costEstimate: omitFanout(costEstimate),
+        joinType: this.#type
+      });
+    }
+    return costEstimate;
+  }
+  /**
+   * Get a human-readable name for this join for debugging.
+   * Format: "parentName ⋈ childName"
+   */
+  getName() {
+    const parentName = getNodeName(this.#parent);
+    const childName = getNodeName(this.#child);
+    return `${parentName} ⋈ ${childName}`;
+  }
+  /**
+   * Get debug information about this join's state.
+   */
+  getDebugInfo() {
+    return {
+      name: this.getName(),
+      type: this.#type,
+      planId: this.planId
+    };
+  }
+}
+class UnflippableJoinError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "UnflippableJoinError";
+  }
+}
+function getNodeName(node) {
+  switch (node.kind) {
+    case "connection":
+      return node.name;
+    case "join":
+      return node.getName();
+    case "fan-out":
+      return "FO";
+    case "fan-in":
+      return "FI";
+    case "terminus":
+      return "terminus";
+  }
+}
+export {
+  PlannerJoin,
+  UnflippableJoinError
+};
+//# sourceMappingURL=planner-join.js.map

package/out/zql/src/planner/planner-join.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"planner-join.js","sources":["../../../../../zql/src/planner/planner-join.ts"],"sourcesContent":["import {assert} from '../../../shared/src/asserts.ts';\nimport {\n  mergeConstraints,\n  type PlannerConstraint,\n} from './planner-constraint.ts';\nimport type {PlanDebugger} from './planner-debug.ts';\nimport {omitFanout} from './planner-node.ts';\nimport type {\n  CostEstimate,\n  JoinOrConnection,\n  PlannerNode,\n} from './planner-node.ts';\nimport type {PlannerTerminus} from './planner-terminus.ts';\n\n/**\n * Translate constraints for a flipped join from parent space to child space.\n * Matches the runtime behavior of FlippedJoin.fetch() which translates\n * parent constraints to child constraints using index-based key mapping.\n *\n * Example:\n *   parentConstraint = {issueID: undefined, projectID: undefined}\n *   childConstraint = {id: undefined, projectID: undefined}\n *   incomingConstraint = {issueID: 5}\n *   result = {id: 5}  // issueID at index 0 maps to id at index 0\n */\nfunction translateConstraintsForFlippedJoin(\n  incomingConstraint: PlannerConstraint | undefined,\n  parentConstraint: PlannerConstraint,\n  childConstraint: PlannerConstraint,\n): PlannerConstraint | undefined {\n  if (!incomingConstraint) return undefined;\n\n  const parentKeys = Object.keys(parentConstraint);\n  const childKeys = Object.keys(childConstraint);\n  const translated: PlannerConstraint = {};\n\n  for (const [key, value] of Object.entries(incomingConstraint)) {\n    const index = parentKeys.indexOf(key);\n    if (index !== -1) {\n      // Found this key in parent at position `index`\n      // Map to child key at same position\n      translated[childKeys[index]] = value;\n    }\n  }\n\n  return Object.keys(translated).length > 0 ? translated : undefined;\n}\n\n/**\n * Semi-join overhead multiplier.\n *\n * Semi-joins represent correlated subqueries (EXISTS checks) which have\n * execution overhead compared to flipped joins, even when logical row counts\n * are identical. This overhead comes from:\n * - Need to execute a separate correlation check for each parent row\n * - Cannot leverage combined constraint checking as effectively as flipped joins\n *\n * A multiplier of 1.5 means semi-joins are estimated to be ~50% more expensive\n * than equivalent flipped joins, which empirically matches observed performance\n * differences in production workloads (e.g., 1.7x in zbugs benchmarks).\n *\n * Flipped joins have a different overhead in that they become unlimited. This\n * is accounted for when propagating unlimits rather than here.\n */\n// const SEMI_JOIN_OVERHEAD_MULTIPLIER = 1.5;\n\n/**\n * Represents a join between two data streams (parent and child).\n *\n * # Dual-State Pattern\n * Like all planner nodes, PlannerJoin separates:\n * 1. IMMUTABLE STRUCTURE: Parent/child nodes, constraints, flippability\n * 2. MUTABLE STATE: Join type (semi/flipped), pinned status\n *\n * # Join Flipping\n * A join can be in two states:\n * - 'semi': Parent is outer loop, child is inner (semi-join for EXISTS)\n * - 'flipped': Child is outer loop, parent is inner\n *\n * Flipping is the key optimization: choosing which table scans first.\n * NOT EXISTS joins cannot be flipped (#flippable = false).\n *\n * # Constraint Propagation\n * - Semi-join: Sends childConstraint to child, forwards received constraints to parent\n * - Flipped join: Sends undefined to child, merges parentConstraint with received to parent\n * - Unpinned join: Only forwards constraints to parent (doesn't constrain child yet)\n *\n * # Lifecycle\n * 1. Construct with immutable structure (parent, child, constraints, flippability)\n * 2. Wire to output node during graph construction\n * 3. Planning calls flipIfNeeded() based on connection selection order\n * 4. pin() locks the join type once chosen\n * 5. reset() clears mutable state (type → 'semi', pinned → false)\n */\nexport class PlannerJoin {\n  readonly kind = 'join' as const;\n\n  readonly #parent: Exclude<PlannerNode, PlannerTerminus>;\n  readonly #child: Exclude<PlannerNode, PlannerTerminus>;\n  readonly #parentConstraint: PlannerConstraint;\n  readonly #childConstraint: PlannerConstraint;\n  readonly #flippable: boolean;\n  readonly planId: number;\n  #output?: PlannerNode | undefined; // Set once during graph construction\n\n  // Reset between planning attempts\n  #type: 'semi' | 'flipped';\n  readonly #initialType: 'semi' | 'flipped';\n\n  constructor(\n    parent: Exclude<PlannerNode, PlannerTerminus>,\n    child: Exclude<PlannerNode, PlannerTerminus>,\n    parentConstraint: PlannerConstraint,\n    childConstraint: PlannerConstraint,\n    flippable: boolean,\n    planId: number,\n    initialType: 'semi' | 'flipped' = 'semi',\n  ) {\n    this.#type = initialType;\n    this.#initialType = initialType;\n    this.#parent = parent;\n    this.#child = child;\n    this.#childConstraint = childConstraint;\n    this.#parentConstraint = parentConstraint;\n    this.#flippable = flippable;\n    this.planId = planId;\n  }\n\n  setOutput(node: PlannerNode): void {\n    this.#output = node;\n  }\n\n  get output(): PlannerNode {\n    assert(this.#output !== undefined, 'Output not set');\n    return this.#output;\n  }\n\n  closestJoinOrSource(): JoinOrConnection {\n    return 'join';\n  }\n\n  flipIfNeeded(input: PlannerNode): void {\n    if (input === this.#child) {\n      this.flip();\n    } else {\n      assert(\n        input === this.#parent,\n        'Can only flip a join from one of its inputs',\n      );\n    }\n  }\n\n  flip(): void {\n    assert(this.#type === 'semi', 'Can only flip a semi-join');\n    if (!this.#flippable) {\n      throw new UnflippableJoinError(\n        'Cannot flip a non-flippable join (e.g., NOT EXISTS)',\n      );\n    }\n    this.#type = 'flipped';\n  }\n\n  get type(): 'semi' | 'flipped' {\n    return this.#type;\n  }\n  isFlippable(): boolean {\n    return this.#flippable;\n  }\n\n  /**\n   * Propagate unlimiting when this join is flipped.\n   * When a join is flipped:\n   * 1. Child becomes outer loop → produces all rows (unlimited)\n   * 2. Parent is fetched once per child row → effectively unlimited\n   *\n   * Example: If child produces 896 rows, parent is fetched 896 times.\n   * Even if each fetch returns 1 row, parent produces 896 total rows.\n   *\n   * Propagation rules:\n   * - Connection: call unlimit()\n   * - Semi-join: continue to parent (outer loop)\n   * - Flipped join: stop (already unlimited when it was flipped)\n   * - Fan-out/Fan-in: propagate to all inputs\n   */\n  propagateUnlimit(): void {\n    assert(this.#type === 'flipped', 'Can only unlimit a flipped join');\n    // Parent stays limited; child becomes unlimited\n    this.#child.propagateUnlimitFromFlippedJoin(); // Up the child chain\n  }\n\n  /**\n   * Called when a parent join is flipped and this join is part of its child subgraph.\n   * Continue propagation to parent (the outer loop).\n   * If we are hitting a semi-join, the parent drives.\n   * If we are hitting a flip-join, well now we have to unlimit its parent too!\n   */\n  propagateUnlimitFromFlippedJoin(): void {\n    this.#parent.propagateUnlimitFromFlippedJoin();\n  }\n\n  propagateConstraints(\n    branchPattern: number[],\n    constraint: PlannerConstraint | undefined,\n    from?: PlannerNode,\n    planDebugger?: PlanDebugger,\n  ): void {\n    planDebugger?.log({\n      type: 'node-constraint',\n      nodeType: 'join',\n      node: this.getName(),\n      branchPattern,\n      constraint,\n      from: from ? getNodeName(from) : 'unknown',\n    });\n\n    if (this.#type === 'semi') {\n      // A semi-join always has constraints for its child.\n      // They are defined by the correlation between parent and child.\n      this.#child.propagateConstraints(\n        branchPattern,\n        this.#childConstraint,\n        this,\n        planDebugger,\n      );\n      // A semi-join forwards constraints to its parent.\n      this.#parent.propagateConstraints(\n        branchPattern,\n        constraint,\n        this,\n        planDebugger,\n      );\n    } else if (this.#type === 'flipped') {\n      // A flipped join translates constraints from parent space to child space.\n      // This matches FlippedJoin.fetch() runtime behavior where parent constraints\n      // on join keys are translated to child constraints.\n      // Example: If parent has {issueID: 5} and join maps issueID→id,\n      // child gets {id: 5} allowing index usage.\n      const translatedConstraint = translateConstraintsForFlippedJoin(\n        constraint,\n        this.#parentConstraint,\n        this.#childConstraint,\n      );\n      this.#child.propagateConstraints(\n        branchPattern,\n        translatedConstraint,\n        this,\n        planDebugger,\n      );\n      // A flipped join will have constraints to send to its parent.\n      // - The constraints its output sent\n      // - The constraints its child creates\n      this.#parent.propagateConstraints(\n        branchPattern,\n        mergeConstraints(constraint, this.#parentConstraint),\n        this,\n        planDebugger,\n      );\n    }\n  }\n\n  reset(): void {\n    this.#type = this.#initialType;\n  }\n\n  estimateCost(\n    /**\n     * This argument is to deal with consecutive `andExists` statements.\n     * Each one will constrain how often a parent row passes all constraints.\n     * This means that we have to scan more and more parent rows the more\n     * constraints we add.\n     *\n     * DownstreamChildSelectivity factors in fanout factor\n     * from parent -> child\n     */\n    downstreamChildSelectivity: number,\n    /**\n     * branchPattern uniquely identifies OR branches in the graph.\n     * Each path through an OR will have unique constraints to apply to the source\n     * connection.\n     * branchPattern allows us to correlate a path through the graph\n     * to the constraints that should be applied for that path.\n     *\n     * Example graph:\n     *  UFO\n     * /  \\\n     * J1   J2\n     * \\  /\n     *  UFI\n     *\n     * J1 and J2 are joins inside an OR (FO).\n     * branchPattern [0] = path through J1\n     * branchPattern [1] = path through J2\n     *\n     * If many ORs are nested, branchPattern will have multiple elements\n     * representing each level of OR.\n     *\n     * If no joins are flipped within the `OR`, then only a single\n     * branchPattern element will be needed, as FO represents all sub-joins\n     * as a single path.\n     */\n    branchPattern: number[],\n    planDebugger?: PlanDebugger,\n  ): CostEstimate {\n    /**\n     * downstreamChildSelectivity accumulates up a parent chain, not\n     * up child chains. Child chains represent independent sub-graphs.\n     * So we pass 1 for `downstreamChildSelectivity` when estimating child cost.\n     * Put another way, downstreamChildSelectivity impacts how many parent\n     * rows are returned.\n     */\n    const child = this.#child.estimateCost(1, branchPattern, planDebugger);\n\n    const fanoutFactor = child.fanout(Object.keys(this.#childConstraint));\n    // Factor in how many child rows match a parent row.\n    // E.g., if an issue has 10 comments on average then we're more\n    // likely to hit a comment compared to if an issue has 1 comment on average.\n    // If an index is all nulls (no parents match any children)\n    // this will collapse to 0.\n    const scaledChildSelectivity =\n      1 - Math.pow(1 - child.selectivity, fanoutFactor.fanout);\n\n    /**\n     * How selective is the graph from this point forward?\n     * If we are _very_ selective then we must scan more parent rows\n     * before finding a match.\n     * E.g., if childSelectivity = 0.1 and downstreamChildSelectivity = 0.5\n     * then we only pass 5% of parent rows (0.1 * 0.5 = 0.05).\n     *\n     * This is used to estimate how many rows will be pulled from the parent\n     * when trying to satisfy downstream constraints and a limit.\n     *\n     * NOTE: We do not know if the probabilities are correlated so we assume independence.\n     * This is a fundamental limitation of the planner.\n     */\n    const parent = this.#parent.estimateCost(\n      // Selectivity flows up the graph from child to parent\n      // so we can determine the total selectivity of all ANDed exists checks.\n      this.#type === 'flipped'\n        ? 1 * downstreamChildSelectivity\n        : scaledChildSelectivity * downstreamChildSelectivity,\n      branchPattern,\n      planDebugger,\n    );\n\n    let costEstimate: CostEstimate;\n\n    if (this.type === 'semi') {\n      costEstimate = {\n        startupCost: parent.startupCost,\n        scanEst:\n          parent.limit === undefined\n            ? parent.returnedRows\n            : Math.min(\n                parent.returnedRows,\n                downstreamChildSelectivity === 0\n                  ? 0\n                  : parent.limit / downstreamChildSelectivity,\n              ),\n        cost:\n          parent.cost +\n          parent.scanEst * (child.startupCost + child.cost + child.scanEst),\n        returnedRows: parent.returnedRows * child.selectivity,\n        selectivity: child.selectivity * parent.selectivity,\n        limit: parent.limit,\n        fanout: parent.fanout,\n      };\n    } else {\n      costEstimate = {\n        startupCost: child.startupCost,\n        scanEst:\n          parent.limit === undefined\n            ? parent.returnedRows * child.returnedRows\n            : Math.min(\n                parent.returnedRows * child.returnedRows,\n                downstreamChildSelectivity === 0\n                  ? 0\n                  : parent.limit / downstreamChildSelectivity,\n              ),\n        cost:\n          child.cost +\n          child.scanEst * (parent.startupCost + parent.cost + parent.scanEst),\n        returnedRows:\n          parent.returnedRows * child.returnedRows * child.selectivity,\n        selectivity: parent.selectivity * child.selectivity,\n        limit: parent.limit,\n        fanout: parent.fanout,\n      };\n    }\n\n    if (planDebugger) {\n      planDebugger.log({\n        type: 'node-cost',\n        nodeType: 'join',\n        node: this.getName(),\n        branchPattern,\n        downstreamChildSelectivity,\n        costEstimate: omitFanout(costEstimate),\n        joinType: this.#type,\n      });\n    }\n\n    return costEstimate;\n  }\n\n  /**\n   * Get a human-readable name for this join for debugging.\n   * Format: \"parentName ⋈ childName\"\n   */\n  getName(): string {\n    const parentName = getNodeName(this.#parent);\n    const childName = getNodeName(this.#child);\n    return `${parentName} ⋈ ${childName}`;\n  }\n\n  /**\n   * Get debug information about this join's state.\n   */\n  getDebugInfo(): {\n    name: string;\n    type: 'semi' | 'flipped';\n    planId: number;\n  } {\n    return {\n      name: this.getName(),\n      type: this.#type,\n      planId: this.planId,\n    };\n  }\n}\n\nexport class UnflippableJoinError extends Error {\n  constructor(message: string) {\n    super(message);\n    this.name = 'UnflippableJoinError';\n  }\n}\n\n/**\n * Get a human-readable name for any planner node.\n * Used for debugging and tracing.\n */\nfunction getNodeName(node: PlannerNode): string {\n  switch (node.kind) {\n    case 'connection':\n      return node.name;\n    case 'join':\n      return node.getName();\n    case 'fan-out':\n      return 'FO';\n    case 'fan-in':\n      return 'FI';\n    case 'terminus':\n      return 'terminus';\n  }\n}\n"],"names":[],"mappings":"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"}

package/out/zql/src/planner/planner-node.d.ts

@@ -0,0 +1,53 @@
+import type { FanoutCostModel, PlannerConnection } from './planner-connection.ts';
+import type { PlannerFanIn } from './planner-fan-in.ts';
+import type { PlannerFanOut } from './planner-fan-out.ts';
+import type { PlannerJoin } from './planner-join.ts';
+import type { PlannerTerminus } from './planner-terminus.ts';
+/**
+ * Union of all node types that can appear in the planner graph.
+ * All nodes follow the dual-state pattern described above.
+ */
+export type PlannerNode = PlannerJoin | PlannerConnection | PlannerFanOut | PlannerFanIn | PlannerTerminus;
+export type CostEstimate = {
+    startupCost: number;
+    scanEst: number;
+    /**
+     * The cumulative cost to run the pipeline so far.
+     *
+     * In a semi-join, each row output by the parent is multiplied by the cost to evaluate the child.
+     * In a flipped join, each row output by the child is multiplied by the cost to evaluate the parent.
+     *
+     * "each row output by the parent" is determined by the downstreamChildSelectivity parameter in combination
+     * with the limit or the rows output by the parent node.
+     *
+     * We pull on the parent and stop when hitting a limit or exhausting rows.
+     */
+    cost: number;
+    /**
+     * The number of rows output from a node.
+     * - For a connection, this is the estimated number of rows returned by the source query.
+     * - For a semi-join, this is the estimated number of rows that pass the semi-join filter.
+     * - For a flipped join, this is the estimated number of rows that match all child rows.
+     * - For fan-in, this is the sum of the rows from each input.
+     * - For fan-out, this is the rows from its input.
+     */
+    returnedRows: number;
+    /**
+     * The selectivity of the node.
+     * For a connection, this is the fraction of rows passing filters (1.0 = no filtering).
+     * For joins, this is the fraction of parent rows that match child rows.
+     * For fan-in, this is the probability of a match in any branch, assuming independent events.
+     * For fan-out, this is the selectivity of its input.
+     */
+    selectivity: number;
+    limit: number | undefined;
+    fanout: FanoutCostModel;
+};
+/**
+ * Omit the fanout function from a cost estimate for serialization.
+ */
+export declare function omitFanout(cost: CostEstimate): Omit<CostEstimate, 'fanout'>;
+export type NodeType = PlannerNode['kind'];
+export type JoinOrConnection = 'join' | 'connection';
+export type JoinType = PlannerJoin['type'];
+//# sourceMappingURL=planner-node.d.ts.map

package/out/zql/src/planner/planner-node.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"planner-node.d.ts","sourceRoot":"","sources":["../../../../../zql/src/planner/planner-node.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAC,eAAe,EAAE,iBAAiB,EAAC,MAAM,yBAAyB,CAAC;AAChF,OAAO,KAAK,EAAC,YAAY,EAAC,MAAM,qBAAqB,CAAC;AACtD,OAAO,KAAK,EAAC,aAAa,EAAC,MAAM,sBAAsB,CAAC;AACxD,OAAO,KAAK,EAAC,WAAW,EAAC,MAAM,mBAAmB,CAAC;AACnD,OAAO,KAAK,EAAC,eAAe,EAAC,MAAM,uBAAuB,CAAC;AAE3D;;;GAGG;AACH,MAAM,MAAM,WAAW,GACnB,WAAW,GACX,iBAAiB,GACjB,aAAa,GACb,YAAY,GACZ,eAAe,CAAC;AAEpB,MAAM,MAAM,YAAY,GAAG;IACzB,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,MAAM,CAAC;IAEhB;;;;;;;;;;OAUG;IACH,IAAI,EAAE,MAAM,CAAC;IAEb;;;;;;;OAOG;IACH,YAAY,EAAE,MAAM,CAAC;IAErB;;;;;;OAMG;IACH,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,EAAE,MAAM,GAAG,SAAS,CAAC;IAE1B,MAAM,EAAE,eAAe,CAAC;CACzB,CAAC;AAEF;;GAEG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,YAAY,GAAG,IAAI,CAAC,YAAY,EAAE,QAAQ,CAAC,CAG3E;AAED,MAAM,MAAM,QAAQ,GAAG,WAAW,CAAC,MAAM,CAAC,CAAC;AAE3C,MAAM,MAAM,gBAAgB,GAAG,MAAM,GAAG,YAAY,CAAC;AAErD,MAAM,MAAM,QAAQ,GAAG,WAAW,CAAC,MAAM,CAAC,CAAC"}

package/out/zql/src/planner/planner-node.js

@@ -0,0 +1,8 @@
+function omitFanout(cost) {
+  const { fanout: _, ...rest } = cost;
+  return rest;
+}
+export {
+  omitFanout
+};
+//# sourceMappingURL=planner-node.js.map

package/out/zql/src/planner/planner-node.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"planner-node.js","sources":["../../../../../zql/src/planner/planner-node.ts"],"sourcesContent":["import type {FanoutCostModel, PlannerConnection} from './planner-connection.ts';\nimport type {PlannerFanIn} from './planner-fan-in.ts';\nimport type {PlannerFanOut} from './planner-fan-out.ts';\nimport type {PlannerJoin} from './planner-join.ts';\nimport type {PlannerTerminus} from './planner-terminus.ts';\n\n/**\n * Union of all node types that can appear in the planner graph.\n * All nodes follow the dual-state pattern described above.\n */\nexport type PlannerNode =\n  | PlannerJoin\n  | PlannerConnection\n  | PlannerFanOut\n  | PlannerFanIn\n  | PlannerTerminus;\n\nexport type CostEstimate = {\n  startupCost: number;\n  scanEst: number;\n\n  /**\n   * The cumulative cost to run the pipeline so far.\n   *\n   * In a semi-join, each row output by the parent is multiplied by the cost to evaluate the child.\n   * In a flipped join, each row output by the child is multiplied by the cost to evaluate the parent.\n   *\n   * \"each row output by the parent\" is determined by the downstreamChildSelectivity parameter in combination\n   * with the limit or the rows output by the parent node.\n   *\n   * We pull on the parent and stop when hitting a limit or exhausting rows.\n   */\n  cost: number;\n\n  /**\n   * The number of rows output from a node.\n   * - For a connection, this is the estimated number of rows returned by the source query.\n   * - For a semi-join, this is the estimated number of rows that pass the semi-join filter.\n   * - For a flipped join, this is the estimated number of rows that match all child rows.\n   * - For fan-in, this is the sum of the rows from each input.\n   * - For fan-out, this is the rows from its input.\n   */\n  returnedRows: number;\n\n  /**\n   * The selectivity of the node.\n   * For a connection, this is the fraction of rows passing filters (1.0 = no filtering).\n   * For joins, this is the fraction of parent rows that match child rows.\n   * For fan-in, this is the probability of a match in any branch, assuming independent events.\n   * For fan-out, this is the selectivity of its input.\n   */\n  selectivity: number;\n  limit: number | undefined;\n\n  fanout: FanoutCostModel;\n};\n\n/**\n * Omit the fanout function from a cost estimate for serialization.\n */\nexport function omitFanout(cost: CostEstimate): Omit<CostEstimate, 'fanout'> {\n  const {fanout: _, ...rest} = cost;\n  return rest;\n}\n\nexport type NodeType = PlannerNode['kind'];\n\nexport type JoinOrConnection = 'join' | 'connection';\n\nexport type JoinType = PlannerJoin['type'];\n"],"names":[],"mappings":"AA4DO,SAAS,WAAW,MAAkD;AAC3E,QAAM,EAAC,QAAQ,GAAG,GAAG,SAAQ;AAC7B,SAAO;AACT;"}

package/out/zql/src/planner/planner-source.d.ts

@@ -0,0 +1,11 @@
+import type { Condition, Ordering } from '../../../zero-protocol/src/ast.ts';
+import { PlannerConnection, type ConnectionCostModel } from './planner-connection.ts';
+import type { PlannerConstraint } from './planner-constraint.ts';
+export type { ConnectionCostModel };
+export declare class PlannerSource {
+    #private;
+    readonly name: string;
+    constructor(name: string, model: ConnectionCostModel);
+    connect(sort: Ordering, filters: Condition | undefined, isRoot: boolean, baseConstraints?: PlannerConstraint, limit?: number): PlannerConnection;
+}
+//# sourceMappingURL=planner-source.d.ts.map

package/out/zql/src/planner/planner-source.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"planner-source.d.ts","sourceRoot":"","sources":["../../../../../zql/src/planner/planner-source.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAC,SAAS,EAAE,QAAQ,EAAC,MAAM,mCAAmC,CAAC;AAC3E,OAAO,EACL,iBAAiB,EACjB,KAAK,mBAAmB,EACzB,MAAM,yBAAyB,CAAC;AACjC,OAAO,KAAK,EAAC,iBAAiB,EAAC,MAAM,yBAAyB,CAAC;AAE/D,YAAY,EAAC,mBAAmB,EAAC,CAAC;AAElC,qBAAa,aAAa;;IACxB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;gBAGV,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,mBAAmB;IAKpD,OAAO,CACL,IAAI,EAAE,QAAQ,EACd,OAAO,EAAE,SAAS,GAAG,SAAS,EAC9B,MAAM,EAAE,OAAO,EACf,eAAe,CAAC,EAAE,iBAAiB,EACnC,KAAK,CAAC,EAAE,MAAM,GACb,iBAAiB;CAWrB"}

package/out/zql/src/planner/planner-source.js

@@ -0,0 +1,24 @@
+import { PlannerConnection } from "./planner-connection.js";
+class PlannerSource {
+  name;
+  #model;
+  constructor(name, model) {
+    this.name = name;
+    this.#model = model;
+  }
+  connect(sort, filters, isRoot, baseConstraints, limit) {
+    return new PlannerConnection(
+      this.name,
+      this.#model,
+      sort,
+      filters,
+      isRoot,
+      baseConstraints,
+      limit
+    );
+  }
+}
+export {
+  PlannerSource
+};
+//# sourceMappingURL=planner-source.js.map

package/out/zql/src/planner/planner-source.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"planner-source.js","sources":["../../../../../zql/src/planner/planner-source.ts"],"sourcesContent":["import type {Condition, Ordering} from '../../../zero-protocol/src/ast.ts';\nimport {\n  PlannerConnection,\n  type ConnectionCostModel,\n} from './planner-connection.ts';\nimport type {PlannerConstraint} from './planner-constraint.ts';\n\nexport type {ConnectionCostModel};\n\nexport class PlannerSource {\n  readonly name: string;\n  readonly #model: ConnectionCostModel;\n\n  constructor(name: string, model: ConnectionCostModel) {\n    this.name = name;\n    this.#model = model;\n  }\n\n  connect(\n    sort: Ordering,\n    filters: Condition | undefined,\n    isRoot: boolean,\n    baseConstraints?: PlannerConstraint,\n    limit?: number,\n  ): PlannerConnection {\n    return new PlannerConnection(\n      this.name,\n      this.#model,\n      sort,\n      filters,\n      isRoot,\n      baseConstraints,\n      limit,\n    );\n  }\n}\n"],"names":[],"mappings":";AASO,MAAM,cAAc;AAAA,EAChB;AAAA,EACA;AAAA,EAET,YAAY,MAAc,OAA4B;AACpD,SAAK,OAAO;AACZ,SAAK,SAAS;AAAA,EAChB;AAAA,EAEA,QACE,MACA,SACA,QACA,iBACA,OACmB;AACnB,WAAO,IAAI;AAAA,MACT,KAAK;AAAA,MACL,KAAK;AAAA,MACL;AAAA,MACA;AAAA,MACA;AAAA,MACA;AAAA,MACA;AAAA,IAAA;AAAA,EAEJ;AACF;"}

package/out/zql/src/planner/planner-terminus.d.ts

@@ -0,0 +1,17 @@
+import type { PlanDebugger } from './planner-debug.ts';
+import type { CostEstimate, JoinOrConnection, PlannerNode } from './planner-node.ts';
+export declare class PlannerTerminus {
+    #private;
+    readonly kind: "terminus";
+    constructor(input: Exclude<PlannerNode, PlannerTerminus>);
+    get pinned(): boolean;
+    closestJoinOrSource(): JoinOrConnection;
+    propagateConstraints(planDebugger?: PlanDebugger): void;
+    estimateCost(planDebugger?: PlanDebugger): CostEstimate;
+    /**
+     * Propagate unlimiting when a parent join is flipped.
+     * Terminus doesn't participate in unlimiting.
+     */
+    propagateUnlimitFromFlippedJoin(): void;
+}
+//# sourceMappingURL=planner-terminus.d.ts.map

package/out/zql/src/planner/planner-terminus.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"planner-terminus.d.ts","sourceRoot":"","sources":["../../../../../zql/src/planner/planner-terminus.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAC,YAAY,EAAC,MAAM,oBAAoB,CAAC;AACrD,OAAO,KAAK,EACV,YAAY,EACZ,gBAAgB,EAChB,WAAW,EACZ,MAAM,mBAAmB,CAAC;AAE3B,qBAAa,eAAe;;IAC1B,QAAQ,CAAC,IAAI,EAAG,UAAU,CAAU;gBAGxB,KAAK,EAAE,OAAO,CAAC,WAAW,EAAE,eAAe,CAAC;IAIxD,IAAI,MAAM,IAAI,OAAO,CAEpB;IAED,mBAAmB,IAAI,gBAAgB;IAIvC,oBAAoB,CAAC,YAAY,CAAC,EAAE,YAAY,GAAG,IAAI;IAIvD,YAAY,CAAC,YAAY,CAAC,EAAE,YAAY,GAAG,YAAY;IAKvD;;;OAGG;IACH,+BAA+B,IAAI,IAAI;CAGxC"}

package/out/zql/src/planner/planner-terminus.js

@@ -0,0 +1,29 @@
+class PlannerTerminus {
+  kind = "terminus";
+  #input;
+  constructor(input) {
+    this.#input = input;
+  }
+  get pinned() {
+    return true;
+  }
+  closestJoinOrSource() {
+    return this.#input.closestJoinOrSource();
+  }
+  propagateConstraints(planDebugger) {
+    this.#input.propagateConstraints([], void 0, this, planDebugger);
+  }
+  estimateCost(planDebugger) {
+    return this.#input.estimateCost(1, [], planDebugger);
+  }
+  /**
+   * Propagate unlimiting when a parent join is flipped.
+   * Terminus doesn't participate in unlimiting.
+   */
+  propagateUnlimitFromFlippedJoin() {
+  }
+}
+export {
+  PlannerTerminus
+};
+//# sourceMappingURL=planner-terminus.js.map

package/out/zql/src/planner/planner-terminus.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"planner-terminus.js","sources":["../../../../../zql/src/planner/planner-terminus.ts"],"sourcesContent":["import type {PlanDebugger} from './planner-debug.ts';\nimport type {\n  CostEstimate,\n  JoinOrConnection,\n  PlannerNode,\n} from './planner-node.ts';\n\nexport class PlannerTerminus {\n  readonly kind = 'terminus' as const;\n  readonly #input: Exclude<PlannerNode, PlannerTerminus>;\n\n  constructor(input: Exclude<PlannerNode, PlannerTerminus>) {\n    this.#input = input;\n  }\n\n  get pinned(): boolean {\n    return true;\n  }\n\n  closestJoinOrSource(): JoinOrConnection {\n    return this.#input.closestJoinOrSource();\n  }\n\n  propagateConstraints(planDebugger?: PlanDebugger): void {\n    this.#input.propagateConstraints([], undefined, this, planDebugger);\n  }\n\n  estimateCost(planDebugger?: PlanDebugger): CostEstimate {\n    // Terminus starts the cost estimation flow with empty branch pattern\n    return this.#input.estimateCost(1, [], planDebugger);\n  }\n\n  /**\n   * Propagate unlimiting when a parent join is flipped.\n   * Terminus doesn't participate in unlimiting.\n   */\n  propagateUnlimitFromFlippedJoin(): void {\n    // No-op: terminus doesn't need to unlimit anything\n  }\n}\n"],"names":[],"mappings":"AAOO,MAAM,gBAAgB;AAAA,EAClB,OAAO;AAAA,EACP;AAAA,EAET,YAAY,OAA8C;AACxD,SAAK,SAAS;AAAA,EAChB;AAAA,EAEA,IAAI,SAAkB;AACpB,WAAO;AAAA,EACT;AAAA,EAEA,sBAAwC;AACtC,WAAO,KAAK,OAAO,oBAAA;AAAA,EACrB;AAAA,EAEA,qBAAqB,cAAmC;AACtD,SAAK,OAAO,qBAAqB,CAAA,GAAI,QAAW,MAAM,YAAY;AAAA,EACpE;AAAA,EAEA,aAAa,cAA2C;AAEtD,WAAO,KAAK,OAAO,aAAa,GAAG,CAAA,GAAI,YAAY;AAAA,EACrD;AAAA;AAAA;AAAA;AAAA;AAAA,EAMA,kCAAwC;AAAA,EAExC;AACF;"}

package/out/zql/src/query/complete-ordering.d.ts

@@ -0,0 +1,5 @@
+import type { AST, Ordering } from '../../../zero-protocol/src/ast.ts';
+import type { PrimaryKey } from '../../../zero-protocol/src/primary-key.ts';
+export declare function completeOrdering(ast: AST, getPrimaryKey: (tableName: string) => PrimaryKey): AST;
+export declare function assertOrderingIncludesPK(ordering: Ordering, pk: PrimaryKey): void;
+//# sourceMappingURL=complete-ordering.d.ts.map

package/out/zql/src/query/complete-ordering.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"complete-ordering.d.ts","sourceRoot":"","sources":["../../../../../zql/src/query/complete-ordering.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAC,GAAG,EAAa,QAAQ,EAAC,MAAM,mCAAmC,CAAC;AAChF,OAAO,KAAK,EAAC,UAAU,EAAC,MAAM,2CAA2C,CAAC;AAE1E,wBAAgB,gBAAgB,CAC9B,GAAG,EAAE,GAAG,EACR,aAAa,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,UAAU,GAC/C,GAAG,CAmBL;AAED,wBAAgB,wBAAwB,CACtC,QAAQ,EAAE,QAAQ,EAClB,EAAE,EAAE,UAAU,GACb,IAAI,CAWN"}

package/out/zql/src/query/complete-ordering.js

@@ -0,0 +1,71 @@
+import { assert } from "../../../shared/src/asserts.js";
+import { must } from "../../../shared/src/must.js";
+function completeOrdering(ast, getPrimaryKey) {
+  const primaryKey = must(getPrimaryKey(ast.table));
+  return {
+    ...ast,
+    ...ast.related ? {
+      related: ast.related?.map((r) => ({
+        ...r,
+        subquery: completeOrdering(r.subquery, getPrimaryKey)
+      }))
+    } : void 0,
+    ...ast.where ? {
+      where: completeOrderingInCondition(ast.where, getPrimaryKey)
+    } : void 0,
+    orderBy: addPrimaryKeys(primaryKey, ast.orderBy)
+  };
+}
+function assertOrderingIncludesPK(ordering, pk) {
+  const orderingFields = ordering.map(([field]) => field);
+  const missingFields = pk.filter((pkField) => !orderingFields.includes(pkField));
+  assert(
+    missingFields.length === 0,
+    `Ordering must include all primary key fields. Missing: ${missingFields.join(
+      ", "
+    )}.`
+  );
+}
+function completeOrderingInCondition(condition, getPrimaryKey) {
+  if (!condition) {
+    return condition;
+  }
+  if (condition.type === "simple") {
+    return condition;
+  }
+  if (condition.type === "correlatedSubquery") {
+    return {
+      ...condition,
+      related: {
+        ...condition.related,
+        subquery: completeOrdering(condition.related.subquery, getPrimaryKey)
+      }
+    };
+  }
+  condition.type;
+  return {
+    ...condition,
+    conditions: condition.conditions.map(
+      (c) => completeOrderingInCondition(c, getPrimaryKey)
+    )
+  };
+}
+function addPrimaryKeys(primaryKey, orderBy) {
+  orderBy = orderBy ?? [];
+  const primaryKeysToAdd = new Set(primaryKey);
+  for (const [field] of orderBy) {
+    primaryKeysToAdd.delete(field);
+  }
+  if (primaryKeysToAdd.size === 0) {
+    return orderBy;
+  }
+  return [
+    ...orderBy,
+    ...[...primaryKeysToAdd].map((key) => [key, "asc"])
+  ];
+}
+export {
+  assertOrderingIncludesPK,
+  completeOrdering
+};
+//# sourceMappingURL=complete-ordering.js.map

package/out/zql/src/query/complete-ordering.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"complete-ordering.js","sources":["../../../../../zql/src/query/complete-ordering.ts"],"sourcesContent":["import {assert} from '../../../shared/src/asserts.ts';\nimport {must} from '../../../shared/src/must.ts';\nimport type {AST, Condition, Ordering} from '../../../zero-protocol/src/ast.ts';\nimport type {PrimaryKey} from '../../../zero-protocol/src/primary-key.ts';\n\nexport function completeOrdering(\n  ast: AST,\n  getPrimaryKey: (tableName: string) => PrimaryKey,\n): AST {\n  const primaryKey = must(getPrimaryKey(ast.table));\n  return {\n    ...ast,\n    ...(ast.related\n      ? {\n          related: ast.related?.map(r => ({\n            ...r,\n            subquery: completeOrdering(r.subquery, getPrimaryKey),\n          })),\n        }\n      : undefined),\n    ...(ast.where\n      ? {\n          where: completeOrderingInCondition(ast.where, getPrimaryKey),\n        }\n      : undefined),\n    orderBy: addPrimaryKeys(primaryKey, ast.orderBy),\n  };\n}\n\nexport function assertOrderingIncludesPK(\n  ordering: Ordering,\n  pk: PrimaryKey,\n): void {\n  // oxlint-disable-next-line unicorn/prefer-set-has -- Array is more appropriate here for small collections\n  const orderingFields = ordering.map(([field]) => field);\n  const missingFields = pk.filter(pkField => !orderingFields.includes(pkField));\n\n  assert(\n    missingFields.length === 0,\n    `Ordering must include all primary key fields. Missing: ${missingFields.join(\n      ', ',\n    )}.`,\n  );\n}\n\nfunction completeOrderingInCondition<C extends Condition | undefined>(\n  condition: C,\n  getPrimaryKey: (tableName: string) => PrimaryKey,\n): C {\n  if (!condition) {\n    return condition;\n  }\n  if (condition.type === 'simple') {\n    return condition;\n  }\n  if (condition.type === 'correlatedSubquery') {\n    return {\n      ...condition,\n      related: {\n        ...condition.related,\n        subquery: completeOrdering(condition.related.subquery, getPrimaryKey),\n      },\n    };\n  }\n  condition.type satisfies 'and' | 'or';\n  return {\n    ...condition,\n    conditions: condition.conditions.map(c =>\n      completeOrderingInCondition(c, getPrimaryKey),\n    ),\n  };\n}\n\nfunction addPrimaryKeys(\n  primaryKey: PrimaryKey,\n  orderBy: Ordering | undefined,\n): Ordering {\n  orderBy = orderBy ?? [];\n  const primaryKeysToAdd = new Set(primaryKey);\n\n  for (const [field] of orderBy) {\n    primaryKeysToAdd.delete(field);\n  }\n\n  if (primaryKeysToAdd.size === 0) {\n    return orderBy;\n  }\n\n  return [\n    ...orderBy,\n    ...[...primaryKeysToAdd].map(key => [key, 'asc'] as [string, 'asc']),\n  ];\n}\n"],"names":[],"mappings":";;AAKO,SAAS,iBACd,KACA,eACK;AACL,QAAM,aAAa,KAAK,cAAc,IAAI,KAAK,CAAC;AAChD,SAAO;AAAA,IACL,GAAG;AAAA,IACH,GAAI,IAAI,UACJ;AAAA,MACE,SAAS,IAAI,SAAS,IAAI,CAAA,OAAM;AAAA,QAC9B,GAAG;AAAA,QACH,UAAU,iBAAiB,EAAE,UAAU,aAAa;AAAA,MAAA,EACpD;AAAA,IAAA,IAEJ;AAAA,IACJ,GAAI,IAAI,QACJ;AAAA,MACE,OAAO,4BAA4B,IAAI,OAAO,aAAa;AAAA,IAAA,IAE7D;AAAA,IACJ,SAAS,eAAe,YAAY,IAAI,OAAO;AAAA,EAAA;AAEnD;AAEO,SAAS,yBACd,UACA,IACM;AAEN,QAAM,iBAAiB,SAAS,IAAI,CAAC,CAAC,KAAK,MAAM,KAAK;AACtD,QAAM,gBAAgB,GAAG,OAAO,CAAA,YAAW,CAAC,eAAe,SAAS,OAAO,CAAC;AAE5E;AAAA,IACE,cAAc,WAAW;AAAA,IACzB,0DAA0D,cAAc;AAAA,MACtE;AAAA,IAAA,CACD;AAAA,EAAA;AAEL;AAEA,SAAS,4BACP,WACA,eACG;AACH,MAAI,CAAC,WAAW;AACd,WAAO;AAAA,EACT;AACA,MAAI,UAAU,SAAS,UAAU;AAC/B,WAAO;AAAA,EACT;AACA,MAAI,UAAU,SAAS,sBAAsB;AAC3C,WAAO;AAAA,MACL,GAAG;AAAA,MACH,SAAS;AAAA,QACP,GAAG,UAAU;AAAA,QACb,UAAU,iBAAiB,UAAU,QAAQ,UAAU,aAAa;AAAA,MAAA;AAAA,IACtE;AAAA,EAEJ;AACA,YAAU;AACV,SAAO;AAAA,IACL,GAAG;AAAA,IACH,YAAY,UAAU,WAAW;AAAA,MAAI,CAAA,MACnC,4BAA4B,GAAG,aAAa;AAAA,IAAA;AAAA,EAC9C;AAEJ;AAEA,SAAS,eACP,YACA,SACU;AACV,YAAU,WAAW,CAAA;AACrB,QAAM,mBAAmB,IAAI,IAAI,UAAU;AAE3C,aAAW,CAAC,KAAK,KAAK,SAAS;AAC7B,qBAAiB,OAAO,KAAK;AAAA,EAC/B;AAEA,MAAI,iBAAiB,SAAS,GAAG;AAC/B,WAAO;AAAA,EACT;AAEA,SAAO;AAAA,IACL,GAAG;AAAA,IACH,GAAG,CAAC,GAAG,gBAAgB,EAAE,IAAI,CAAA,QAAO,CAAC,KAAK,KAAK,CAAoB;AAAA,EAAA;AAEvE;"}

package/out/zql/src/query/create-builder.d.ts

@@ -0,0 +1,7 @@
+import type { Schema } from '../../../zero-types/src/schema.ts';
+import type { SchemaQuery } from './schema-query.ts';
+/**
+ * Returns a set of query builders for the given schema.
+ */
+export declare function createBuilder<S extends Schema>(schema: S): SchemaQuery<S>;
+//# sourceMappingURL=create-builder.d.ts.map

package/out/zql/src/query/create-builder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"create-builder.d.ts","sourceRoot":"","sources":["../../../../../zql/src/query/create-builder.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAC,MAAM,EAAC,MAAM,mCAAmC,CAAC;AAG9D,OAAO,KAAK,EAAC,WAAW,EAAC,MAAM,mBAAmB,CAAC;AAEnD;;GAEG;AACH,wBAAgB,aAAa,CAAC,CAAC,SAAS,MAAM,EAAE,MAAM,EAAE,CAAC,GAAG,WAAW,CAAC,CAAC,CAAC,CA4CzE"}

package/out/zql/src/query/create-builder.js

@@ -0,0 +1,44 @@
+import { newQuery } from "./query-impl.js";
+function createBuilder(schema) {
+  const cache = /* @__PURE__ */ new Map();
+  const { tables } = schema;
+  function getQuery(prop) {
+    const cached = cache.get(prop);
+    if (cached) {
+      return cached;
+    }
+    if (!Object.hasOwn(schema.tables, prop)) {
+      return void 0;
+    }
+    const q = newQuery(schema, prop);
+    cache.set(prop, q);
+    return q;
+  }
+  return new Proxy(tables, {
+    get: (_target, prop) => {
+      if (typeof prop === "symbol") {
+        return void 0;
+      }
+      const q = getQuery(prop);
+      if (!q) {
+        throw new Error(`Table ${String(prop)} does not exist in schema`);
+      }
+      return q;
+    },
+    getOwnPropertyDescriptor: (_target, prop) => {
+      if (typeof prop === "symbol") {
+        return void 0;
+      }
+      const value = getQuery(prop);
+      if (!value) {
+        return void 0;
+      }
+      const desc = Reflect.getOwnPropertyDescriptor(tables, prop);
+      return { ...desc, value };
+    }
+  });
+}
+export {
+  createBuilder
+};
+//# sourceMappingURL=create-builder.js.map

package/out/zql/src/query/create-builder.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"create-builder.js","sources":["../../../../../zql/src/query/create-builder.ts"],"sourcesContent":["import type {Schema} from '../../../zero-types/src/schema.ts';\nimport {newQuery} from './query-impl.ts';\nimport type {Query} from './query.ts';\nimport type {SchemaQuery} from './schema-query.ts';\n\n/**\n * Returns a set of query builders for the given schema.\n */\nexport function createBuilder<S extends Schema>(schema: S): SchemaQuery<S> {\n  // oxlint-disable-next-line no-explicit-any\n  const cache = new Map<string, Query<string, S, any>>();\n  const {tables} = schema;\n\n  function getQuery(prop: string) {\n    const cached = cache.get(prop);\n    if (cached) {\n      return cached;\n    }\n\n    if (!Object.hasOwn(schema.tables, prop)) {\n      return undefined;\n    }\n\n    const q = newQuery(schema, prop);\n    cache.set(prop, q);\n    return q;\n  }\n\n  return new Proxy(tables, {\n    get: (_target, prop) => {\n      if (typeof prop === 'symbol') {\n        return undefined;\n      }\n      const q = getQuery(prop);\n      if (!q) {\n        throw new Error(`Table ${String(prop)} does not exist in schema`);\n      }\n      return q;\n    },\n\n    getOwnPropertyDescriptor: (_target, prop) => {\n      if (typeof prop === 'symbol') {\n        return undefined;\n      }\n      const value = getQuery(prop);\n      if (!value) {\n        return undefined;\n      }\n      const desc = Reflect.getOwnPropertyDescriptor(tables, prop);\n      return {...desc, value};\n    },\n  }) as unknown as SchemaQuery<S>;\n}\n"],"names":[],"mappings":";AAQO,SAAS,cAAgC,QAA2B;AAEzE,QAAM,4BAAY,IAAA;AAClB,QAAM,EAAC,WAAU;AAEjB,WAAS,SAAS,MAAc;AAC9B,UAAM,SAAS,MAAM,IAAI,IAAI;AAC7B,QAAI,QAAQ;AACV,aAAO;AAAA,IACT;AAEA,QAAI,CAAC,OAAO,OAAO,OAAO,QAAQ,IAAI,GAAG;AACvC,aAAO;AAAA,IACT;AAEA,UAAM,IAAI,SAAS,QAAQ,IAAI;AAC/B,UAAM,IAAI,MAAM,CAAC;AACjB,WAAO;AAAA,EACT;AAEA,SAAO,IAAI,MAAM,QAAQ;AAAA,IACvB,KAAK,CAAC,SAAS,SAAS;AACtB,UAAI,OAAO,SAAS,UAAU;AAC5B,eAAO;AAAA,MACT;AACA,YAAM,IAAI,SAAS,IAAI;AACvB,UAAI,CAAC,GAAG;AACN,cAAM,IAAI,MAAM,SAAS,OAAO,IAAI,CAAC,2BAA2B;AAAA,MAClE;AACA,aAAO;AAAA,IACT;AAAA,IAEA,0BAA0B,CAAC,SAAS,SAAS;AAC3C,UAAI,OAAO,SAAS,UAAU;AAC5B,eAAO;AAAA,MACT;AACA,YAAM,QAAQ,SAAS,IAAI;AAC3B,UAAI,CAAC,OAAO;AACV,eAAO;AAAA,MACT;AACA,YAAM,OAAO,QAAQ,yBAAyB,QAAQ,IAAI;AAC1D,aAAO,EAAC,GAAG,MAAM,MAAA;AAAA,IACnB;AAAA,EAAA,CACD;AACH;"}

package/out/zql/src/query/error.d.ts

@@ -0,0 +1,4 @@
+export declare class QueryParseError extends Error {
+    constructor(opts: ErrorOptions);
+}
+//# sourceMappingURL=error.d.ts.map

package/out/zql/src/query/error.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"error.d.ts","sourceRoot":"","sources":["../../../../../zql/src/query/error.ts"],"names":[],"mappings":"AAAA,qBAAa,eAAgB,SAAQ,KAAK;gBAC5B,IAAI,EAAE,YAAY;CAS/B"}

package/out/zql/src/query/error.js

@@ -0,0 +1,13 @@
+class QueryParseError extends Error {
+  constructor(opts) {
+    super(
+      opts?.cause instanceof Error ? `Failed to parse arguments for query: ${opts.cause.message}` : `Failed to parse arguments for query`,
+      opts
+    );
+    this.name = "QueryParseError";
+  }
+}
+export {
+  QueryParseError
+};
+//# sourceMappingURL=error.js.map