@rocicorp/zero 0.25.0 → 0.26.0-canary.0

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

@@ -1,257 +1,215 @@
 import { assert } from "../../../shared/src/asserts.js";
-import { mergeConstraints, } from "./planner-constraint.js";
-/**
- * Represents a connection to a source (table scan).
- *
- * # Dual State Pattern
- * Like all planner nodes, PlannerConnection separates:
- * 1. immutable structure: Ordering, filters, cost model (set at construction)
- * 2. mutable state: Pinned status, constraints (mutated during planning)
- *
- * # Cost Estimation
- * The ordering and filters determine the initial cost. As planning progresses,
- * constraints from parent joins refine the cost estimate.
- *
- * # Constraint Flow
- * When a connection is pinned as the outer loop, it reveals constraints for
- * connected joins. These constraints propagate through the graph, allowing
- * other connections to update their cost estimates.
- *
- * Example:
- *
- * ```ts
- * builder.issue.whereExists('assignee', a => a.where('name', 'Alice'))
- * ```
- *
- * ```
- * [issue]  [assignee]
- *   |         |
- *   |         +-- where name = 'Alice'
- *    \        /
- *     \      /
- *      [join]
- *        |
- * ```
- *
- * - Initial state: Both connections have no constraints, costs are unconstrained
- * - If `issue` chosen first: Reveals constraint `assignee_id` for assignee connection
- * - If `assignee` chosen first: Reveals constraint `assignee_id` for issue connection
- * - Updated costs guide the next selection
- *
- * # Lifecycle
- * 1. Construct with immutable structure (ordering, filters, cost model)
- * 2. Wire to output node during graph construction
- * 3. Planning mutates pinned status and accumulates constraints
- * 4. reset() clears mutable state for replanning
- */
-export class PlannerConnection {
-    kind = 'connection';
-    // ========================================================================
-    // IMMUTABLE STRUCTURE (set during construction, never changes)
-    // ========================================================================
-    #sort;
-    #filters;
-    #model;
-    table;
-    name; // Human-readable name for debugging (defaults to table name)
-    #baseConstraints; // Constraints from parent correlation
-    #baseLimit; // Original limit from query structure (never modified)
-    selectivity; // Fraction of rows passing filters (1.0 = no filtering)
-    #output; // Set once during graph construction
-    // ========================================================================
-    // MUTABLE PLANNING STATE (changes during plan search)
-    // ========================================================================
-    /**
-     * Current limit during planning. Can be cleared (set to undefined) when a
-     * parent join is flipped, indicating this connection is now in an outer loop
-     * and should not be limited by EXISTS semantics.
-     */
-    limit;
-    /**
-     * Constraints accumulated from parent joins during planning.
-     * Key is a path through the graph (e.g., "0,1" for branch pattern [0,1]).
-     *
-     * Undefined constraints are possible when a FO converts to UFO and only
-     * a single join in the UFO is flipped - other branches report undefined.
-     */
-    #constraints;
-    #isRoot;
-    /**
-     * Cached per-constraint costs to avoid redundant cost model calls.
-     * Maps constraint key (branch pattern string) to computed cost.
-     * Invalidated when constraints change.
-     */
-    #cachedConstraintCosts = new Map();
-    constructor(table, model, sort, filters, isRoot, baseConstraints, limit, name) {
-        this.table = table;
-        this.name = name ?? table;
-        this.#sort = sort;
-        this.#filters = filters;
-        this.#model = model;
-        this.#baseConstraints = baseConstraints;
-        this.#baseLimit = limit;
-        this.limit = limit;
-        this.#constraints = new Map();
-        this.#isRoot = isRoot;
-        // Compute selectivity for EXISTS child connections (baseLimit === 1)
-        // Selectivity = fraction of rows that pass filters
-        if (limit !== undefined && filters) {
-            const costWithFilters = model(table, sort, filters, undefined);
-            const costWithoutFilters = model(table, sort, undefined, undefined);
-            this.selectivity =
-                costWithoutFilters.rows > 0
-                    ? costWithFilters.rows / costWithoutFilters.rows
-                    : 1.0;
-        }
-        else {
-            // Root connections or connections without filters
-            this.selectivity = 1.0;
-        }
+import { mergeConstraints } from "./planner-constraint.js";
+import { omitFanout } from "./planner-node.js";
+class PlannerConnection {
+  kind = "connection";
+  // ========================================================================
+  // IMMUTABLE STRUCTURE (set during construction, never changes)
+  // ========================================================================
+  #sort;
+  #filters;
+  #model;
+  table;
+  name;
+  // Human-readable name for debugging (defaults to table name)
+  #baseConstraints;
+  // Constraints from parent correlation
+  #baseLimit;
+  // Original limit from query structure (never modified)
+  selectivity;
+  // Fraction of rows passing filters (1.0 = no filtering)
+  #output;
+  // Set once during graph construction
+  // ========================================================================
+  // MUTABLE PLANNING STATE (changes during plan search)
+  // ========================================================================
+  /**
+   * Current limit during planning. Can be cleared (set to undefined) when a
+   * parent join is flipped, indicating this connection is now in an outer loop
+   * and should not be limited by EXISTS semantics.
+   */
+  limit;
+  /**
+   * Constraints accumulated from parent joins during planning.
+   * Key is a path through the graph (e.g., "0,1" for branch pattern [0,1]).
+   *
+   * Undefined constraints are possible when a FO converts to UFO and only
+   * a single join in the UFO is flipped - other branches report undefined.
+   */
+  #constraints;
+  #isRoot;
+  /**
+   * Cached per-constraint costs to avoid redundant cost model calls.
+   * Maps constraint key (branch pattern string) to computed cost.
+   * Invalidated when constraints change.
+   */
+  #cachedConstraintCosts = /* @__PURE__ */ new Map();
+  constructor(table, model, sort, filters, isRoot, baseConstraints, limit, name) {
+    this.table = table;
+    this.name = name ?? table;
+    this.#sort = sort;
+    this.#filters = filters;
+    this.#model = model;
+    this.#baseConstraints = baseConstraints;
+    this.#baseLimit = limit;
+    this.limit = limit;
+    this.#constraints = /* @__PURE__ */ new Map();
+    this.#isRoot = isRoot;
+    if (limit !== void 0 && filters) {
+      const costWithFilters = model(table, sort, filters, void 0);
+      const costWithoutFilters = model(table, sort, void 0, void 0);
+      this.selectivity = costWithoutFilters.rows > 0 ? costWithFilters.rows / costWithoutFilters.rows : 1;
+    } else {
+      this.selectivity = 1;
     }
-    setOutput(node) {
-        this.#output = node;
+  }
+  setOutput(node) {
+    this.#output = node;
+  }
+  get output() {
+    assert(this.#output !== void 0, "Output not set");
+    return this.#output;
+  }
+  closestJoinOrSource() {
+    return "connection";
+  }
+  /**
+   * Constraints are uniquely identified by their path through the
+   * graph.
+   *
+   * FO represents all sub-joins as a single path.
+   * UFO represents each sub-join as a separate path.
+   * The first branch in a UFO will match the path of FO so no re-set needs to happen
+   * when swapping from FO to UFO.
+   *
+   * FO swaps to UFO when a join inside FO-FI gets flipped.
+   *
+   * The max of the last element of the paths is the number of
+   * root branches.
+   */
+  propagateConstraints(path, c, from, planDebugger) {
+    const key = path.join(",");
+    this.#constraints.set(key, c);
+    this.#cachedConstraintCosts.clear();
+    planDebugger?.log({
+      type: "node-constraint",
+      nodeType: "connection",
+      node: this.name,
+      branchPattern: path,
+      constraint: c,
+      from: from?.kind ?? "unknown"
+    });
+  }
+  estimateCost(downstreamChildSelectivity, branchPattern, planDebugger) {
+    const key = branchPattern.join(",");
+    let cost = this.#cachedConstraintCosts.get(key);
+    if (cost !== void 0) {
+      return cost;
     }
-    get output() {
-        assert(this.#output !== undefined, 'Output not set');
-        return this.#output;
+    const constraint = this.#constraints.get(key);
+    const mergedConstraint = mergeConstraints(
+      this.#baseConstraints,
+      constraint
+    );
+    const { startupCost, fanout, rows } = this.#model(
+      this.table,
+      this.#sort,
+      this.#filters,
+      mergedConstraint
+    );
+    cost = {
+      startupCost,
+      scanEst: this.limit === void 0 ? rows : Math.min(rows, this.limit / downstreamChildSelectivity),
+      cost: 0,
+      returnedRows: rows,
+      selectivity: this.selectivity,
+      limit: this.limit,
+      fanout
+    };
+    this.#cachedConstraintCosts.set(key, cost);
+    if (planDebugger) {
+      planDebugger.log({
+        type: "node-cost",
+        nodeType: "connection",
+        node: this.name,
+        branchPattern,
+        downstreamChildSelectivity,
+        costEstimate: omitFanout(cost),
+        filters: this.#filters,
+        ordering: this.#sort
+      });
     }
-    closestJoinOrSource() {
-        return 'connection';
+    return cost;
+  }
+  /**
+   * Remove the limit from this connection.
+   * Called when a parent join is flipped, making this connection part of an
+   * outer loop that should produce all rows rather than stopping at the limit.
+   */
+  unlimit() {
+    if (this.#isRoot) {
+      return;
     }
-    /**
-     * Constraints are uniquely identified by their path through the
-     * graph.
-     *
-     * FO represents all sub-joins as a single path.
-     * UFO represents each sub-join as a separate path.
-     * The first branch in a UFO will match the path of FO so no re-set needs to happen
-     * when swapping from FO to UFO.
-     *
-     * FO swaps to UFO when a join inside FO-FI gets flipped.
-     *
-     * The max of the last element of the paths is the number of
-     * root branches.
-     */
-    propagateConstraints(path, c, from, planDebugger) {
-        const key = path.join(',');
-        this.#constraints.set(key, c);
-        // Constraints changed, invalidate cost caches
-        this.#cachedConstraintCosts.clear();
-        planDebugger?.log({
-            type: 'node-constraint',
-            nodeType: 'connection',
-            node: this.name,
-            branchPattern: path,
-            constraint: c,
-            from: from?.kind ?? 'unknown',
-        });
+    if (this.limit !== void 0) {
+      this.limit = void 0;
     }
-    estimateCost(downstreamChildSelectivity, branchPattern, planDebugger) {
-        // Branch pattern specified - return cost for this specific branch
-        const key = branchPattern.join(',');
-        // Check per-constraint cache first
-        let cost = this.#cachedConstraintCosts.get(key);
-        if (cost !== undefined) {
-            return cost;
-        }
-        // Cache miss - compute and cache
-        const constraint = this.#constraints.get(key);
-        // Merge base constraints with propagated constraints
-        const mergedConstraint = mergeConstraints(this.#baseConstraints, constraint);
-        const { startupCost, rows } = this.#model(this.table, this.#sort, this.#filters, mergedConstraint);
-        cost = {
-            startupCost,
-            scanEst: this.limit === undefined
-                ? rows
-                : Math.min(rows, this.limit / downstreamChildSelectivity),
-            cost: 0,
-            returnedRows: rows,
-            selectivity: this.selectivity,
-            limit: this.limit,
-        };
-        this.#cachedConstraintCosts.set(key, cost);
-        planDebugger?.log({
-            type: 'node-cost',
-            nodeType: 'connection',
-            node: this.name,
-            branchPattern,
-            downstreamChildSelectivity,
-            costEstimate: cost,
-            filters: this.#filters,
-        });
-        return cost;
+  }
+  /**
+   * Propagate unlimiting when a parent join is flipped.
+   * For connections, we simply remove the limit.
+   */
+  propagateUnlimitFromFlippedJoin() {
+    this.unlimit();
+  }
+  reset() {
+    this.#constraints.clear();
+    this.limit = this.#baseLimit;
+    this.#cachedConstraintCosts.clear();
+  }
+  /**
+   * Capture constraint state for snapshotting.
+   * Used by PlannerGraph to save/restore planning state.
+   */
+  captureConstraints() {
+    return new Map(this.#constraints);
+  }
+  /**
+   * Restore constraint state from a snapshot.
+   * Used by PlannerGraph to restore planning state.
+   */
+  restoreConstraints(constraints) {
+    this.#constraints.clear();
+    for (const [key, value] of constraints) {
+      this.#constraints.set(key, value);
     }
-    /**
-     * Remove the limit from this connection.
-     * Called when a parent join is flipped, making this connection part of an
-     * outer loop that should produce all rows rather than stopping at the limit.
-     */
-    unlimit() {
-        if (this.#isRoot) {
-            // We cannot unlimit root connections
-            return;
-        }
-        if (this.limit !== undefined) {
-            this.limit = undefined;
-            // Limit changes do not impact connection costs.
-            // Limit is taken into account at the join level.
-            // Given that, we do not need to invalidate cost caches here.
-        }
+    this.#cachedConstraintCosts.clear();
+  }
+  /** Get current constraints for debugging. */
+  getConstraintsForDebug() {
+    const record = {};
+    for (const [key, value] of this.#constraints) {
+      record[key] = value;
     }
-    /**
-     * Propagate unlimiting when a parent join is flipped.
-     * For connections, we simply remove the limit.
-     */
-    propagateUnlimitFromFlippedJoin() {
-        this.unlimit();
-    }
-    reset() {
-        this.#constraints.clear();
-        this.limit = this.#baseLimit;
-        // Clear all cost caches
-        this.#cachedConstraintCosts.clear();
-    }
-    /**
-     * Capture constraint state for snapshotting.
-     * Used by PlannerGraph to save/restore planning state.
-     */
-    captureConstraints() {
-        return new Map(this.#constraints);
-    }
-    /**
-     * Restore constraint state from a snapshot.
-     * Used by PlannerGraph to restore planning state.
-     */
-    restoreConstraints(constraints) {
-        this.#constraints.clear();
-        for (const [key, value] of constraints) {
-            this.#constraints.set(key, value);
-        }
-        // Constraints changed, invalidate cost caches
-        this.#cachedConstraintCosts.clear();
-    }
-    /**
-     * Get current constraints for debugging.
-     * Returns a copy of the constraints map.
-     */
-    getConstraintsForDebug() {
-        return new Map(this.#constraints);
-    }
-    /**
-     * Get filters for debugging.
-     * Returns the filters applied to this connection.
-     */
-    getFiltersForDebug() {
-        return this.#filters;
-    }
-    /**
-     * Get estimated cost for each constraint branch.
-     * Returns a map of constraint key to cost estimate.
-     * Forces cost calculation if not already cached.
-     */
-    getConstraintCostsForDebug() {
-        // Return copy of cached costs
-        return new Map(this.#cachedConstraintCosts);
+    return record;
+  }
+  /** Get filters for debugging. */
+  getFiltersForDebug() {
+    return this.#filters;
+  }
+  /** Get sort/ordering for debugging. */
+  getSortForDebug() {
+    return this.#sort;
+  }
+  /** Get estimated cost for each constraint branch. */
+  getConstraintCostsForDebug() {
+    const record = {};
+    for (const [key, value] of this.#cachedConstraintCosts) {
+      record[key] = value;
     }
+    return record;
+  }
 }
-//# sourceMappingURL=planner-connection.js.map
+export {
+  PlannerConnection
+};
+//# sourceMappingURL=planner-connection.js.map

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

@@ -1 +1 @@
-{"version":3,"file":"planner-connection.js","sourceRoot":"","sources":["../../../../../zql/src/planner/planner-connection.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"planner-connection.js","sources":["../../../../../zql/src/planner/planner-connection.ts"],"sourcesContent":["import {assert} from '../../../shared/src/asserts.ts';\nimport type {Condition, Ordering} from '../../../zero-protocol/src/ast.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';\n\n/**\n * Represents a connection to a source (table scan).\n *\n * # Dual State Pattern\n * Like all planner nodes, PlannerConnection separates:\n * 1. immutable structure: Ordering, filters, cost model (set at construction)\n * 2. mutable state: Pinned status, constraints (mutated during planning)\n *\n * # Cost Estimation\n * The ordering and filters determine the initial cost. As planning progresses,\n * constraints from parent joins refine the cost estimate.\n *\n * # Constraint Flow\n * When a connection is pinned as the outer loop, it reveals constraints for\n * connected joins. These constraints propagate through the graph, allowing\n * other connections to update their cost estimates.\n *\n * Example:\n *\n * ```ts\n * builder.issue.whereExists('assignee', a => a.where('name', 'Alice'))\n * ```\n *\n * ```\n * [issue]  [assignee]\n *   |         |\n *   |         +-- where name = 'Alice'\n *    \\        /\n *     \\      /\n *      [join]\n *        |\n * ```\n *\n * - Initial state: Both connections have no constraints, costs are unconstrained\n * - If `issue` chosen first: Reveals constraint `assignee_id` for assignee connection\n * - If `assignee` chosen first: Reveals constraint `assignee_id` for issue connection\n * - Updated costs guide the next selection\n *\n * # Lifecycle\n * 1. Construct with immutable structure (ordering, filters, cost model)\n * 2. Wire to output node during graph construction\n * 3. Planning mutates pinned status and accumulates constraints\n * 4. reset() clears mutable state for replanning\n */\nexport class PlannerConnection {\n  readonly kind = 'connection' as const;\n\n  // ========================================================================\n  // IMMUTABLE STRUCTURE (set during construction, never changes)\n  // ========================================================================\n  readonly #sort: Ordering;\n  readonly #filters: Condition | undefined;\n  readonly #model: ConnectionCostModel;\n  readonly table: string;\n  readonly name: string; // Human-readable name for debugging (defaults to table name)\n  readonly #baseConstraints: PlannerConstraint | undefined; // Constraints from parent correlation\n  readonly #baseLimit: number | undefined; // Original limit from query structure (never modified)\n  readonly selectivity: number; // Fraction of rows passing filters (1.0 = no filtering)\n  #output?: PlannerNode | undefined; // Set once during graph construction\n\n  // ========================================================================\n  // MUTABLE PLANNING STATE (changes during plan search)\n  // ========================================================================\n  /**\n   * Current limit during planning. Can be cleared (set to undefined) when a\n   * parent join is flipped, indicating this connection is now in an outer loop\n   * and should not be limited by EXISTS semantics.\n   */\n  limit: number | undefined;\n\n  /**\n   * Constraints accumulated from parent joins during planning.\n   * Key is a path through the graph (e.g., \"0,1\" for branch pattern [0,1]).\n   *\n   * Undefined constraints are possible when a FO converts to UFO and only\n   * a single join in the UFO is flipped - other branches report undefined.\n   */\n  readonly #constraints: Map<string, PlannerConstraint | undefined>;\n\n  readonly #isRoot: boolean;\n\n  /**\n   * Cached per-constraint costs to avoid redundant cost model calls.\n   * Maps constraint key (branch pattern string) to computed cost.\n   * Invalidated when constraints change.\n   */\n  #cachedConstraintCosts: Map<string, CostEstimate> = new Map();\n\n  constructor(\n    table: string,\n    model: ConnectionCostModel,\n    sort: Ordering,\n    filters: Condition | undefined,\n    isRoot: boolean,\n    baseConstraints?: PlannerConstraint,\n    limit?: number,\n    name?: string,\n  ) {\n    this.table = table;\n    this.name = name ?? table;\n    this.#sort = sort;\n    this.#filters = filters;\n    this.#model = model;\n    this.#baseConstraints = baseConstraints;\n    this.#baseLimit = limit;\n    this.limit = limit;\n    this.#constraints = new Map();\n    this.#isRoot = isRoot;\n\n    // Compute selectivity for EXISTS child connections (baseLimit === 1)\n    // Selectivity = fraction of rows that pass filters\n    if (limit !== undefined && filters) {\n      const costWithFilters = model(table, sort, filters, undefined);\n      const costWithoutFilters = model(table, sort, undefined, undefined);\n      this.selectivity =\n        costWithoutFilters.rows > 0\n          ? costWithFilters.rows / costWithoutFilters.rows\n          : 1.0;\n    } else {\n      // Root connections or connections without filters\n      this.selectivity = 1.0;\n    }\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 'connection';\n  }\n\n  /**\n   * Constraints are uniquely identified by their path through the\n   * graph.\n   *\n   * FO represents all sub-joins as a single path.\n   * UFO represents each sub-join as a separate path.\n   * The first branch in a UFO will match the path of FO so no re-set needs to happen\n   * when swapping from FO to UFO.\n   *\n   * FO swaps to UFO when a join inside FO-FI gets flipped.\n   *\n   * The max of the last element of the paths is the number of\n   * root branches.\n   */\n  propagateConstraints(\n    path: number[],\n    c: PlannerConstraint | undefined,\n    from?: PlannerNode,\n    planDebugger?: PlanDebugger,\n  ): void {\n    const key = path.join(',');\n    this.#constraints.set(key, c);\n    // Constraints changed, invalidate cost caches\n    this.#cachedConstraintCosts.clear();\n\n    planDebugger?.log({\n      type: 'node-constraint',\n      nodeType: 'connection',\n      node: this.name,\n      branchPattern: path,\n      constraint: c,\n      from: from?.kind ?? 'unknown',\n    });\n  }\n\n  estimateCost(\n    downstreamChildSelectivity: number,\n    branchPattern: number[],\n    planDebugger?: PlanDebugger,\n  ): CostEstimate {\n    // Branch pattern specified - return cost for this specific branch\n    const key = branchPattern.join(',');\n\n    // Check per-constraint cache first\n    let cost = this.#cachedConstraintCosts.get(key);\n    if (cost !== undefined) {\n      return cost;\n    }\n\n    // Cache miss - compute and cache\n    const constraint = this.#constraints.get(key);\n    // Merge base constraints with propagated constraints\n    const mergedConstraint = mergeConstraints(\n      this.#baseConstraints,\n      constraint,\n    );\n    const {startupCost, fanout, rows} = this.#model(\n      this.table,\n      this.#sort,\n      this.#filters,\n      mergedConstraint,\n    );\n    cost = {\n      startupCost,\n      scanEst:\n        this.limit === undefined\n          ? rows\n          : Math.min(rows, this.limit / downstreamChildSelectivity),\n      cost: 0,\n      returnedRows: rows,\n      selectivity: this.selectivity,\n      limit: this.limit,\n      fanout,\n    };\n    this.#cachedConstraintCosts.set(key, cost);\n\n    if (planDebugger) {\n      planDebugger.log({\n        type: 'node-cost',\n        nodeType: 'connection',\n        node: this.name,\n        branchPattern,\n        downstreamChildSelectivity,\n        costEstimate: omitFanout(cost),\n        filters: this.#filters,\n        ordering: this.#sort,\n      });\n    }\n\n    return cost;\n  }\n\n  /**\n   * Remove the limit from this connection.\n   * Called when a parent join is flipped, making this connection part of an\n   * outer loop that should produce all rows rather than stopping at the limit.\n   */\n  unlimit(): void {\n    if (this.#isRoot) {\n      // We cannot unlimit root connections\n      return;\n    }\n    if (this.limit !== undefined) {\n      this.limit = undefined;\n      // Limit changes do not impact connection costs.\n      // Limit is taken into account at the join level.\n      // Given that, we do not need to invalidate cost caches here.\n    }\n  }\n\n  /**\n   * Propagate unlimiting when a parent join is flipped.\n   * For connections, we simply remove the limit.\n   */\n  propagateUnlimitFromFlippedJoin(): void {\n    this.unlimit();\n  }\n\n  reset() {\n    this.#constraints.clear();\n    this.limit = this.#baseLimit;\n    // Clear all cost caches\n    this.#cachedConstraintCosts.clear();\n  }\n\n  /**\n   * Capture constraint state for snapshotting.\n   * Used by PlannerGraph to save/restore planning state.\n   */\n  captureConstraints(): Map<string, PlannerConstraint | undefined> {\n    return new Map(this.#constraints);\n  }\n\n  /**\n   * Restore constraint state from a snapshot.\n   * Used by PlannerGraph to restore planning state.\n   */\n  restoreConstraints(\n    constraints: Map<string, PlannerConstraint | undefined>,\n  ): void {\n    this.#constraints.clear();\n    for (const [key, value] of constraints) {\n      this.#constraints.set(key, value);\n    }\n    // Constraints changed, invalidate cost caches\n    this.#cachedConstraintCosts.clear();\n  }\n\n  /** Get current constraints for debugging. */\n  getConstraintsForDebug(): Record<string, PlannerConstraint | undefined> {\n    const record: Record<string, PlannerConstraint | undefined> = {};\n    for (const [key, value] of this.#constraints) {\n      record[key] = value;\n    }\n    return record;\n  }\n\n  /** Get filters for debugging. */\n  getFiltersForDebug(): Condition | undefined {\n    return this.#filters;\n  }\n\n  /** Get sort/ordering for debugging. */\n  getSortForDebug(): Ordering {\n    return this.#sort;\n  }\n\n  /** Get estimated cost for each constraint branch. */\n  getConstraintCostsForDebug(): Record<string, CostEstimate> {\n    const record: Record<string, CostEstimate> = {};\n    for (const [key, value] of this.#cachedConstraintCosts) {\n      record[key] = value;\n    }\n    return record;\n  }\n}\n\ntype FanoutEst = {\n  fanout: number;\n  confidence: 'high' | 'med' | 'none';\n};\nexport type FanoutCostModel = (columns: string[]) => FanoutEst;\n\nexport type CostModelCost = {\n  startupCost: number;\n  rows: number;\n  fanout: FanoutCostModel;\n};\nexport type ConnectionCostModel = (\n  table: string,\n  sort: Ordering,\n  filters: Condition | undefined,\n  constraint: PlannerConstraint | undefined,\n) => CostModelCost;\n"],"names":[],"mappings":"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"}

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

@@ -1,12 +1,9 @@
-/**
- * Multiple flipped joins will contribute extra constraints to a parent join.
- * These need to be merged.
- */
-export function mergeConstraints(a, b) {
-    if (!a)
-        return b;
-    if (!b)
-        return a;
-    return { ...a, ...b };
+function mergeConstraints(a, b) {
+  if (!a) return b;
+  if (!b) return a;
+  return { ...a, ...b };
 }
-//# sourceMappingURL=planner-constraint.js.map
+export {
+  mergeConstraints
+};
+//# sourceMappingURL=planner-constraint.js.map

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

@@ -1 +1 @@
-{"version":3,"file":"planner-constraint.js","sourceRoot":"","sources":["../../../../../zql/src/planner/planner-constraint.ts"],"names":[],"mappings":"AASA;;;GAGG;AACH,MAAM,UAAU,gBAAgB,CAC9B,CAAgC,EAChC,CAAgC;IAEhC,IAAI,CAAC,CAAC;QAAE,OAAO,CAAC,CAAC;IACjB,IAAI,CAAC,CAAC;QAAE,OAAO,CAAC,CAAC;IACjB,OAAO,EAAC,GAAG,CAAC,EAAE,GAAG,CAAC,EAAC,CAAC;AACtB,CAAC"}
+{"version":3,"file":"planner-constraint.js","sources":["../../../../../zql/src/planner/planner-constraint.ts"],"sourcesContent":["/**\n * We do not know the value a constraint will take until runtime.\n *\n * However, we do know the column.\n *\n * E.g., we know that `issue.assignee_id` will be constrained to typeof issue.assignee_id.\n */\nexport type PlannerConstraint = Record<string, undefined>;\n\n/**\n * Multiple flipped joins will contribute extra constraints to a parent join.\n * These need to be merged.\n */\nexport function mergeConstraints(\n  a: PlannerConstraint | undefined,\n  b: PlannerConstraint | undefined,\n): PlannerConstraint | undefined {\n  if (!a) return b;\n  if (!b) return a;\n  return {...a, ...b};\n}\n"],"names":[],"mappings":"AAaO,SAAS,iBACd,GACA,GAC+B;AAC/B,MAAI,CAAC,EAAG,QAAO;AACf,MAAI,CAAC,EAAG,QAAO;AACf,SAAO,EAAC,GAAG,GAAG,GAAG,EAAA;AACnB;"}