@quereus/quereus 0.1.0

package/dist/src/planner/scopes/multi.js

@@ -0,0 +1,35 @@
+import { Ambiguous } from "./scope.js";
+import { QuereusError } from "../../common/errors.js";
+import { StatusCode } from "../../common/types.js";
+import { BaseScope } from "./base.js";
+/**
+ * A Scope that contains multiple other scopes.
+ * Symbols are resolved in order, and the first match is used.
+ * If a symbol is found in multiple scopes, an error is thrown.
+ */
+export class MultiScope extends BaseScope {
+    scopes;
+    constructor(scopes) {
+        super();
+        this.scopes = scopes;
+    }
+    registerSymbol(_symbolKey, _getReference) {
+        throw new QuereusError('MultiScope does not support registering symbols.', StatusCode.ERROR);
+    }
+    resolveSymbol(symbolKey, expression) {
+        // In SQL, inner scopes shadow outer scopes for unqualified names
+        // Return the first match, don't treat multiple matches as ambiguous
+        for (const scope of this.scopes) {
+            const result = scope.resolveSymbol(symbolKey, expression);
+            if (result === Ambiguous) {
+                return Ambiguous;
+            }
+            if (result) {
+                this.addReference(result);
+                return result;
+            }
+        }
+        return undefined;
+    }
+}
+//# sourceMappingURL=multi.js.map

package/dist/src/planner/scopes/multi.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"multi.js","sourceRoot":"","sources":["../../../../src/planner/scopes/multi.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAEvC,OAAO,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AACtD,OAAO,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAC;AAGnD,OAAO,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAEtC;;;;GAIG;AACH,MAAM,OAAO,UAAW,SAAQ,SAAS;IAEvB;IADjB,YACiB,MAAe;QAE/B,KAAK,EAAE,CAAC;QAFQ,WAAM,GAAN,MAAM,CAAS;IAGhC,CAAC;IAED,cAAc,CAAC,UAAkB,EAAE,aAA4E;QAC9G,MAAM,IAAI,YAAY,CAAC,kDAAkD,EAAE,UAAU,CAAC,KAAK,CAAC,CAAC;IAC9F,CAAC;IAED,aAAa,CAAC,SAAiB,EAAE,UAA0B;QAC1D,iEAAiE;QACjE,oEAAoE;QACpE,KAAK,MAAM,KAAK,IAAI,IAAI,CAAC,MAAM,EAAE,CAAC;YACjC,MAAM,MAAM,GAAG,KAAK,CAAC,aAAa,CAAC,SAAS,EAAE,UAAU,CAAC,CAAC;YAC1D,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;gBAC1B,OAAO,SAAS,CAAC;YAClB,CAAC;YACD,IAAI,MAAM,EAAE,CAAC;gBACZ,IAAI,CAAC,YAAY,CAAC,MAAM,CAAC,CAAC;gBAC1B,OAAO,MAAM,CAAC;YACf,CAAC;QACF,CAAC;QACD,OAAO,SAAS,CAAC;IAClB,CAAC;CACD"}

package/dist/src/planner/scopes/param.d.ts

@@ -0,0 +1,23 @@
+import type * as AST from '../../parser/ast.js';
+import { ParameterReferenceNode } from '../nodes/reference.js';
+import { BaseScope } from './base.js';
+import { Ambiguous, type Scope } from './scope.js';
+import type { ScalarType } from '../../common/datatype.js';
+import type { PlanNode } from '../nodes/plan-node.js';
+/**
+ * A scope that resolves query parameters (e.g., :name, :1, ?).
+ * It makes these parameters available via an accessor.
+ */
+export declare class ParameterScope extends BaseScope {
+    readonly parentScope: Scope;
+    private _nextAnonymousIndex;
+    private readonly _parameters;
+    private readonly _parameterTypeHints;
+    constructor(parentScope: Scope, parameterTypeHints?: ReadonlyMap<string | number, ScalarType>);
+    resolveSymbol(symbolKey: string, expression: AST.Expression): PlanNode | typeof Ambiguous | undefined;
+    /**
+     * Returns all parameters resolved by this scope.
+     */
+    getParameters(): ReadonlyMap<string | number, ParameterReferenceNode>;
+}
+//# sourceMappingURL=param.d.ts.map

package/dist/src/planner/scopes/param.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"param.d.ts","sourceRoot":"","sources":["../../../../src/planner/scopes/param.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,GAAG,MAAM,qBAAqB,CAAC;AAChD,OAAO,EAAE,sBAAsB,EAAE,MAAM,uBAAuB,CAAC;AAC/D,OAAO,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AACtC,OAAO,EAAE,SAAS,EAAE,KAAK,KAAK,EAAE,MAAM,YAAY,CAAC;AACnD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,0BAA0B,CAAC;AAE3D,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AAStD;;;GAGG;AACH,qBAAa,cAAe,SAAQ,SAAS;aAM3B,WAAW,EAAE,KAAK;IALnC,OAAO,CAAC,mBAAmB,CAAa;IACxC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAA2D;IACvF,OAAO,CAAC,QAAQ,CAAC,mBAAmB,CAA2C;gBAG9D,WAAW,EAAE,KAAK,EAClC,kBAAkB,CAAC,EAAE,WAAW,CAAC,MAAM,GAAG,MAAM,EAAE,UAAU,CAAC;IAM9D,aAAa,CAAC,SAAS,EAAE,MAAM,EAAE,UAAU,EAAE,GAAG,CAAC,UAAU,GAAG,QAAQ,GAAG,OAAO,SAAS,GAAG,SAAS;IAkDrG;;OAEG;IACH,aAAa,IAAI,WAAW,CAAC,MAAM,GAAG,MAAM,EAAE,sBAAsB,CAAC;CAUrE"}

package/dist/src/planner/scopes/param.js

@@ -0,0 +1,78 @@
+import { ParameterReferenceNode } from '../nodes/reference.js'; // Corrected import
+import { BaseScope } from './base.js';
+import { SqlDataType } from '../../common/types.js';
+// Default type for parameters when not otherwise specified.
+const DEFAULT_PARAMETER_TYPE = {
+    typeClass: 'scalar',
+    affinity: SqlDataType.TEXT,
+    nullable: true,
+};
+/**
+ * A scope that resolves query parameters (e.g., :name, :1, ?).
+ * It makes these parameters available via an accessor.
+ */
+export class ParameterScope extends BaseScope {
+    parentScope;
+    _nextAnonymousIndex = 1;
+    _parameters = new Map();
+    _parameterTypeHints;
+    constructor(parentScope, parameterTypeHints) {
+        super();
+        this.parentScope = parentScope;
+        this._parameterTypeHints = parameterTypeHints || new Map();
+    }
+    resolveSymbol(symbolKey, expression) {
+        let identifier;
+        let parameterNode;
+        // The expression should be an AST.ParameterExpr when symbolKey indicates a parameter
+        const parameterExpression = expression;
+        let resolvedType = DEFAULT_PARAMETER_TYPE;
+        if (symbolKey === '?') {
+            // Use the current _nextAnonymousIndex as the potential identifier for this '?'
+            const currentAnonymousId = this._nextAnonymousIndex;
+            // Check if this specific anonymous parameter (by its future index) has a type hint
+            if (this._parameterTypeHints.has(currentAnonymousId)) {
+                resolvedType = this._parameterTypeHints.get(currentAnonymousId);
+            }
+            // Note: We don't check _parameters here for '?' because each '?' AST node should resolve,
+            // potentially creating a new ParameterReferenceNode if it's a new '?' instance in the query,
+            // even if it gets the same numeric index as a previous one *if* they were different AST nodes.
+            // The _parameters map is more for caching resolved nodes per unique AST node or name.
+            // For '?', the ParameterReferenceNode constructor expects the numeric index.
+            // We use currentAnonymousId as the identifier and increment after creation.
+            identifier = currentAnonymousId;
+            parameterNode = new ParameterReferenceNode(this, parameterExpression, identifier, resolvedType);
+            this._parameters.set(identifier, parameterNode); // Cache it by its assigned numeric ID
+            this._nextAnonymousIndex++; // Increment for the *next* '?'
+        }
+        else if (symbolKey.startsWith(':')) {
+            const nameOrIndex = symbolKey.substring(1);
+            const numIndex = parseInt(nameOrIndex, 10);
+            identifier = isNaN(numIndex) ? nameOrIndex : numIndex;
+            if (this._parameters.has(identifier)) {
+                parameterNode = this._parameters.get(identifier);
+                // If already exists, its type was set at creation. Type hints are for new nodes.
+            }
+            else {
+                if (this._parameterTypeHints.has(identifier)) {
+                    resolvedType = this._parameterTypeHints.get(identifier);
+                }
+                parameterNode = new ParameterReferenceNode(this, parameterExpression, identifier, resolvedType);
+                this._parameters.set(identifier, parameterNode);
+            }
+        }
+        else {
+            // Not a parameter symbol, delegate to parent scope
+            return this.parentScope.resolveSymbol(symbolKey, expression);
+        }
+        this.addReference(parameterNode);
+        return parameterNode;
+    }
+    /**
+     * Returns all parameters resolved by this scope.
+     */
+    getParameters() {
+        return this._parameters;
+    }
+}
+//# sourceMappingURL=param.js.map

package/dist/src/planner/scopes/param.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"param.js","sourceRoot":"","sources":["../../../../src/planner/scopes/param.ts"],"names":[],"mappings":"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"}

package/dist/src/planner/scopes/registered.d.ts

@@ -0,0 +1,47 @@
+import type { PlanNode } from '../nodes/plan-node.js';
+import * as AST from '../../parser/ast.js';
+import { type ReferenceCallback, type Scope, Ambiguous } from './scope.js';
+/**
+ * The Scope object provides context for symbol resolution during query planning.
+ * It encapsulates the logic for looking up columns, parameters, functions, and CTEs
+ * based on the current position in the PlanNode tree.
+ */
+export declare class RegisteredScope implements Scope {
+    /** The parent scope, if any. The root scope of a query has no parent. */
+    readonly parent?: Scope | undefined;
+    /** References that have been resolved through this scope. */
+    private _references;
+    /** Symbols that have been registered in this scope. */
+    private registeredSymbols;
+    constructor(
+    /** The parent scope, if any. The root scope of a query has no parent. */
+    parent?: Scope | undefined);
+    /**
+     * Registers a symbol (like a table alias, CTE name, or parameter) with a factory function
+     * that can produce a ReferenceNode for it when encountered in an expression.
+     *
+     * @param symbolKey The unique string key for this symbol in the current scope.
+     *  For tables/aliases: lower-case name.
+     *  For qualified schema.table: "schema.table" (lower-case).
+     *  For parameters: ":name" or ":index".
+     * @param getReference A factory function that takes the matching symbol and the current Scope,
+     *  and returns an appropriate ReferenceNode.
+     */
+    registerSymbol(symbolKey: string, getReference: ReferenceCallback): void;
+    resolveSymbol(symbolKey: string, expression: AST.Expression): PlanNode | typeof Ambiguous | undefined;
+    /**
+     * Returns all references that have been resolved through this scope.
+     * This includes references from both this scope and any parent scopes.
+     *
+     * @returns An array of all resolved references.
+     */
+    getReferences(): readonly PlanNode[];
+    addReference(reference: PlanNode): void;
+    /**
+     * Returns all symbols that have been registered in this scope.
+     *
+     * @returns An array of all [symbolKey, ReferenceCallback].
+     */
+    getSymbols(): readonly [string, ReferenceCallback][];
+}
+//# sourceMappingURL=registered.d.ts.map

package/dist/src/planner/scopes/registered.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"registered.d.ts","sourceRoot":"","sources":["../../../../src/planner/scopes/registered.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AACtD,OAAO,KAAK,GAAG,MAAM,qBAAqB,CAAC;AAC3C,OAAO,EAAE,KAAK,iBAAiB,EAAE,KAAK,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAE3E;;;;GAIG;AACH,qBAAa,eAAgB,YAAW,KAAK;IAQ3C,yEAAyE;aACzD,MAAM,CAAC,EAAE,KAAK;IAR/B,6DAA6D;IAC7D,OAAO,CAAC,WAAW,CAAkB;IAErC,uDAAuD;IACvD,OAAO,CAAC,iBAAiB,CAA6C;;IAGrE,yEAAyE;IACzD,MAAM,CAAC,EAAE,KAAK,YAAA;IAG/B;;;;;;;;;;OAUG;IACH,cAAc,CAAC,SAAS,EAAE,MAAM,EAAE,YAAY,EAAE,iBAAiB,GAAG,IAAI;IAQxE,aAAa,CAAC,SAAS,EAAE,MAAM,EAAE,UAAU,EAAE,GAAG,CAAC,UAAU,GAAG,QAAQ,GAAG,OAAO,SAAS,GAAG,SAAS;IAarG;;;;;OAKG;IACH,aAAa,IAAI,SAAS,QAAQ,EAAE;IAIpC,YAAY,CAAC,SAAS,EAAE,QAAQ,GAAG,IAAI;IAIvC;;;;OAIG;IACH,UAAU,IAAI,SAAS,CAAC,MAAM,EAAE,iBAAiB,CAAC,EAAE;CAGpD"}

package/dist/src/planner/scopes/registered.js

@@ -0,0 +1,70 @@
+import { StatusCode } from '../../common/types.js';
+import { QuereusError } from '../../common/errors.js';
+/**
+ * The Scope object provides context for symbol resolution during query planning.
+ * It encapsulates the logic for looking up columns, parameters, functions, and CTEs
+ * based on the current position in the PlanNode tree.
+ */
+export class RegisteredScope {
+    parent;
+    /** References that have been resolved through this scope. */
+    _references = [];
+    /** Symbols that have been registered in this scope. */
+    registeredSymbols = new Map();
+    constructor(
+    /** The parent scope, if any. The root scope of a query has no parent. */
+    parent) {
+        this.parent = parent;
+    }
+    /**
+     * Registers a symbol (like a table alias, CTE name, or parameter) with a factory function
+     * that can produce a ReferenceNode for it when encountered in an expression.
+     *
+     * @param symbolKey The unique string key for this symbol in the current scope.
+     *  For tables/aliases: lower-case name.
+     *  For qualified schema.table: "schema.table" (lower-case).
+     *  For parameters: ":name" or ":index".
+     * @param getReference A factory function that takes the matching symbol and the current Scope,
+     *  and returns an appropriate ReferenceNode.
+     */
+    registerSymbol(symbolKey, getReference) {
+        const lowerSymbolKey = symbolKey.toLowerCase();
+        if (this.registeredSymbols.has(lowerSymbolKey)) {
+            throw new QuereusError(`Symbol '${lowerSymbolKey}' already exists in the same scope.`, StatusCode.ERROR);
+        }
+        this.registeredSymbols.set(lowerSymbolKey, getReference);
+    }
+    resolveSymbol(symbolKey, expression) {
+        const reference = this.registeredSymbols.get(symbolKey.toLowerCase());
+        if (reference) {
+            const node = reference(expression, this);
+            this.addReference(node);
+            return node;
+        }
+        if (this.parent) {
+            return this.parent.resolveSymbol(symbolKey, expression);
+        }
+        return undefined;
+    }
+    /**
+     * Returns all references that have been resolved through this scope.
+     * This includes references from both this scope and any parent scopes.
+     *
+     * @returns An array of all resolved references.
+     */
+    getReferences() {
+        return this._references;
+    }
+    addReference(reference) {
+        this._references.push(reference);
+    }
+    /**
+     * Returns all symbols that have been registered in this scope.
+     *
+     * @returns An array of all [symbolKey, ReferenceCallback].
+     */
+    getSymbols() {
+        return Array.from(this.registeredSymbols.entries());
+    }
+}
+//# sourceMappingURL=registered.js.map

package/dist/src/planner/scopes/registered.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"registered.js","sourceRoot":"","sources":["../../../../src/planner/scopes/registered.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAC;AACnD,OAAO,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AAKtD;;;;GAIG;AACH,MAAM,OAAO,eAAe;IASV;IARjB,6DAA6D;IACrD,WAAW,GAAe,EAAE,CAAC;IAErC,uDAAuD;IAC/C,iBAAiB,GAAmC,IAAI,GAAG,EAAE,CAAC;IAEtE;IACC,yEAAyE;IACzD,MAAc;QAAd,WAAM,GAAN,MAAM,CAAQ;IAC3B,CAAC;IAEL;;;;;;;;;;OAUG;IACH,cAAc,CAAC,SAAiB,EAAE,YAA+B;QAChE,MAAM,cAAc,GAAG,SAAS,CAAC,WAAW,EAAE,CAAC;QAC/C,IAAI,IAAI,CAAC,iBAAiB,CAAC,GAAG,CAAC,cAAc,CAAC,EAAE,CAAC;YAChD,MAAM,IAAI,YAAY,CAAC,WAAW,cAAc,qCAAqC,EAAE,UAAU,CAAC,KAAK,CAAC,CAAC;QAC1G,CAAC;QACD,IAAI,CAAC,iBAAiB,CAAC,GAAG,CAAC,cAAc,EAAE,YAAY,CAAC,CAAC;IAC1D,CAAC;IAED,aAAa,CAAC,SAAiB,EAAE,UAA0B;QAC1D,MAAM,SAAS,GAAG,IAAI,CAAC,iBAAiB,CAAC,GAAG,CAAC,SAAS,CAAC,WAAW,EAAE,CAAC,CAAC;QACtE,IAAI,SAAS,EAAE,CAAC;YACf,MAAM,IAAI,GAAG,SAAS,CAAC,UAAU,EAAE,IAAI,CAAC,CAAC;YACzC,IAAI,CAAC,YAAY,CAAC,IAAI,CAAC,CAAC;YACxB,OAAO,IAAI,CAAC;QACb,CAAC;QACD,IAAI,IAAI,CAAC,MAAM,EAAE,CAAC;YACjB,OAAO,IAAI,CAAC,MAAM,CAAC,aAAa,CAAC,SAAS,EAAE,UAAU,CAAC,CAAC;QACzD,CAAC;QACD,OAAO,SAAS,CAAC;IAClB,CAAC;IAED;;;;;OAKG;IACH,aAAa;QACZ,OAAO,IAAI,CAAC,WAAW,CAAC;IACzB,CAAC;IAED,YAAY,CAAC,SAAmB;QAC/B,IAAI,CAAC,WAAW,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;IAClC,CAAC;IAED;;;;OAIG;IACH,UAAU;QACT,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,iBAAiB,CAAC,OAAO,EAAE,CAAC,CAAC;IACrD,CAAC;CACD"}

package/dist/src/planner/scopes/scope.d.ts

@@ -0,0 +1,21 @@
+import type { PlanNode } from '../nodes/plan-node.js';
+import * as AST from '../../parser/ast.js';
+export declare const Ambiguous: unique symbol;
+export type ReferenceCallback = (expression: AST.Expression, currentScope: Scope) => PlanNode;
+/**
+ * The Scope object provides context for symbol resolution during query planning.
+ * It encapsulates the logic for looking up columns, parameters, functions, and CTEs
+ * based on the current position in the PlanNode tree.
+ */
+export interface Scope {
+    resolveSymbol(symbolKey: string, expression: AST.Expression): PlanNode | typeof Ambiguous | undefined;
+    /**
+     * Returns all references that have been resolved through this scope.
+     * This includes references from both this scope and any parent scopes.
+     *
+     * @returns An array of all resolved references.
+     */
+    getReferences(): readonly PlanNode[];
+    addReference(reference: PlanNode): void;
+}
+//# sourceMappingURL=scope.d.ts.map

package/dist/src/planner/scopes/scope.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scope.d.ts","sourceRoot":"","sources":["../../../../src/planner/scopes/scope.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AACtD,OAAO,KAAK,GAAG,MAAM,qBAAqB,CAAC;AAG3C,eAAO,MAAM,SAAS,eAAW,CAAC;AAElC,MAAM,MAAM,iBAAiB,GAAG,CAAC,UAAU,EAAE,GAAG,CAAC,UAAU,EAAE,YAAY,EAAE,KAAK,KAAK,QAAQ,CAAC;AAE9F;;;;GAIG;AACH,MAAM,WAAW,KAAK;IACrB,aAAa,CAAC,SAAS,EAAE,MAAM,EAAE,UAAU,EAAE,GAAG,CAAC,UAAU,GAAG,QAAQ,GAAG,OAAO,SAAS,GAAG,SAAS,CAAC;IAEtG;;;;;OAKG;IACH,aAAa,IAAI,SAAS,QAAQ,EAAE,CAAC;IAErC,YAAY,CAAC,SAAS,EAAE,QAAQ,GAAG,IAAI,CAAC;CACxC"}

package/dist/src/planner/scopes/scope.js

@@ -0,0 +1,3 @@
+// Create a javascript symbol that represents an ambiguous symbol.
+export const Ambiguous = Symbol();
+//# sourceMappingURL=scope.js.map

package/dist/src/planner/scopes/scope.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"scope.js","sourceRoot":"","sources":["../../../../src/planner/scopes/scope.ts"],"names":[],"mappings":"AAGA,kEAAkE;AAClE,MAAM,CAAC,MAAM,SAAS,GAAG,MAAM,EAAE,CAAC"}

package/dist/src/planner/stats/basic-estimates.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Basic row and cost estimation utilities for plan nodes
+ * Used when more sophisticated statistics are not available
+ */
+import type { RelationalPlanNode } from '../nodes/plan-node.js';
+import type { OptimizerTuning } from '../optimizer-tuning.js';
+/**
+ * Basic row estimation heuristics
+ */
+export declare class BasicRowEstimator {
+    private readonly tuning;
+    constructor(tuning: OptimizerTuning);
+    /**
+     * Estimate rows for a filter operation
+     * Default assumes 30% selectivity for most predicates
+     */
+    estimateFilter(sourceRows: number): number;
+    /**
+     * Estimate rows for a join operation
+     */
+    estimateJoin(leftRows: number, rightRows: number, joinType: string): number;
+    /**
+     * Estimate rows for aggregation
+     */
+    estimateAggregate(sourceRows: number, groupByCount: number): number;
+    /**
+     * Estimate rows for distinct operation
+     */
+    estimateDistinct(sourceRows: number): number;
+    /**
+     * Estimate rows for limit operation
+     */
+    estimateLimit(sourceRows: number, limit: number, offset?: number): number;
+    /**
+     * Get default row estimate when no information is available
+     */
+    getDefaultEstimate(): number;
+}
+/**
+ * Helper to safely get row estimate from a relational node
+ */
+export declare function getRowEstimate(node: RelationalPlanNode, tuning: OptimizerTuning): number;
+/**
+ * Helper to set row estimate on a node if not already set
+ */
+export declare function ensureRowEstimate(node: RelationalPlanNode, estimate: number): void;
+//# sourceMappingURL=basic-estimates.d.ts.map

package/dist/src/planner/stats/basic-estimates.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"basic-estimates.d.ts","sourceRoot":"","sources":["../../../../src/planner/stats/basic-estimates.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAC;AAChE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAE9D;;GAEG;AACH,qBAAa,iBAAiB;IACjB,OAAO,CAAC,QAAQ,CAAC,MAAM;gBAAN,MAAM,EAAE,eAAe;IAEpD;;;OAGG;IACH,cAAc,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM;IAI1C;;OAEG;IACH,YAAY,CAAC,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM;IAyB3E;;OAEG;IACH,iBAAiB,CAAC,UAAU,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,MAAM;IASnE;;OAEG;IACH,gBAAgB,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM;IAK5C;;OAEG;IACH,aAAa,CAAC,UAAU,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,GAAE,MAAU,GAAG,MAAM;IAI5E;;OAEG;IACH,kBAAkB,IAAI,MAAM;CAG5B;AAED;;GAEG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,kBAAkB,EAAE,MAAM,EAAE,eAAe,GAAG,MAAM,CAExF;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,kBAAkB,EAAE,QAAQ,EAAE,MAAM,GAAG,IAAI,CAWlF"}

package/dist/src/planner/stats/basic-estimates.js

@@ -0,0 +1,99 @@
+/**
+ * Basic row and cost estimation utilities for plan nodes
+ * Used when more sophisticated statistics are not available
+ */
+/**
+ * Basic row estimation heuristics
+ */
+export class BasicRowEstimator {
+    tuning;
+    constructor(tuning) {
+        this.tuning = tuning;
+    }
+    /**
+     * Estimate rows for a filter operation
+     * Default assumes 30% selectivity for most predicates
+     */
+    estimateFilter(sourceRows) {
+        return Math.max(1, Math.floor(sourceRows * 0.3));
+    }
+    /**
+     * Estimate rows for a join operation
+     */
+    estimateJoin(leftRows, rightRows, joinType) {
+        switch (joinType.toLowerCase()) {
+            case 'inner':
+                // Inner join: assume moderate correlation
+                return Math.max(1, Math.floor(leftRows * rightRows * 0.1));
+            case 'left':
+            case 'left outer':
+                // Left join: at least as many as left side
+                return Math.max(leftRows, Math.floor(leftRows * rightRows * 0.1));
+            case 'right':
+            case 'right outer':
+                // Right join: at least as many as right side
+                return Math.max(rightRows, Math.floor(leftRows * rightRows * 0.1));
+            case 'full':
+            case 'full outer':
+                // Full outer join: sum minus overlap
+                return leftRows + rightRows - Math.floor(leftRows * rightRows * 0.1);
+            case 'cross':
+                // Cross join: cartesian product
+                return leftRows * rightRows;
+            default:
+                return Math.max(leftRows, rightRows);
+        }
+    }
+    /**
+     * Estimate rows for aggregation
+     */
+    estimateAggregate(sourceRows, groupByCount) {
+        if (groupByCount === 0) {
+            return 1; // Single aggregate row
+        }
+        // Assume reasonable grouping factor
+        const groupingFactor = Math.min(0.8, Math.max(0.1, groupByCount * 0.2));
+        return Math.max(1, Math.floor(sourceRows * groupingFactor));
+    }
+    /**
+     * Estimate rows for distinct operation
+     */
+    estimateDistinct(sourceRows) {
+        // Assume moderate duplication - 70% unique rows
+        return Math.max(1, Math.floor(sourceRows * 0.7));
+    }
+    /**
+     * Estimate rows for limit operation
+     */
+    estimateLimit(sourceRows, limit, offset = 0) {
+        return Math.min(sourceRows, Math.max(0, limit - offset));
+    }
+    /**
+     * Get default row estimate when no information is available
+     */
+    getDefaultEstimate() {
+        return this.tuning.defaultRowEstimate;
+    }
+}
+/**
+ * Helper to safely get row estimate from a relational node
+ */
+export function getRowEstimate(node, tuning) {
+    return node.estimatedRows ?? tuning.defaultRowEstimate;
+}
+/**
+ * Helper to set row estimate on a node if not already set
+ */
+export function ensureRowEstimate(node, estimate) {
+    if (node.estimatedRows === undefined) {
+        // Use Object.defineProperty to set a non-enumerable property
+        // This maintains the immutability principle while adding metadata
+        Object.defineProperty(node, 'estimatedRows', {
+            value: estimate,
+            writable: false,
+            enumerable: true,
+            configurable: false
+        });
+    }
+}
+//# sourceMappingURL=basic-estimates.js.map

package/dist/src/planner/stats/basic-estimates.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"basic-estimates.js","sourceRoot":"","sources":["../../../../src/planner/stats/basic-estimates.ts"],"names":[],"mappings":"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"}

package/dist/src/planner/stats/index.d.ts

@@ -0,0 +1,88 @@
+/**
+ * Statistics provider abstraction for the Quereus optimizer
+ * Provides cardinality estimates and selectivity information for cost-based optimization
+ */
+import type { ScalarPlanNode } from '../nodes/plan-node.js';
+import type { TableSchema } from '../../schema/table.js';
+/**
+ * Statistics provider interface for optimizer
+ */
+export interface StatsProvider {
+    /**
+     * Get estimated row count for a base table
+     * @param table Table schema
+     * @returns Estimated row count, or undefined if unknown
+     */
+    tableRows(table: TableSchema): number | undefined;
+    /**
+     * Get selectivity estimate for a predicate on a table
+     * @param table Table schema
+     * @param predicate Predicate expression
+     * @returns Selectivity factor (0.0 to 1.0), or undefined if unknown
+     */
+    selectivity(table: TableSchema, predicate: ScalarPlanNode): number | undefined;
+    /**
+     * Get join selectivity estimate
+     * @param leftTable Left table schema
+     * @param rightTable Right table schema
+     * @param joinCondition Join condition
+     * @returns Join selectivity factor, or undefined if unknown
+     */
+    joinSelectivity?(leftTable: TableSchema, rightTable: TableSchema, joinCondition: ScalarPlanNode): number | undefined;
+    /**
+     * Get number of distinct values for a column
+     * @param table Table schema
+     * @param columnName Column name
+     * @returns Estimated distinct values, or undefined if unknown
+     */
+    distinctValues?(table: TableSchema, columnName: string): number | undefined;
+    /**
+     * Get index selectivity information
+     * @param table Table schema
+     * @param indexName Index name (if applicable)
+     * @param predicate Predicate expression
+     * @returns Index selectivity factor, or undefined if unknown
+     */
+    indexSelectivity?(table: TableSchema, indexName: string, predicate: ScalarPlanNode): number | undefined;
+}
+/**
+ * Naive statistics provider using simple heuristics
+ * Used as fallback when no better statistics are available
+ */
+export declare class NaiveStatsProvider implements StatsProvider {
+    private readonly defaultTableRows;
+    private readonly defaultSelectivity;
+    constructor(defaultTableRows?: number, defaultSelectivity?: number);
+    tableRows(table: TableSchema): number | undefined;
+    selectivity(table: TableSchema, predicate: ScalarPlanNode): number | undefined;
+    joinSelectivity(leftTable: TableSchema, rightTable: TableSchema, _joinCondition: ScalarPlanNode): number | undefined;
+    distinctValues(table: TableSchema, columnName: string): number | undefined;
+    indexSelectivity(table: TableSchema, indexName: string, predicate: ScalarPlanNode): number | undefined;
+    private estimatePredicateSelectivity;
+}
+/**
+ * Statistics provider that delegates to virtual table modules
+ * Allows VTab modules to provide their own statistics
+ */
+export declare class VTabStatsProvider implements StatsProvider {
+    private readonly fallback;
+    constructor(fallback?: StatsProvider);
+    tableRows(table: TableSchema): number | undefined;
+    selectivity(table: TableSchema, predicate: ScalarPlanNode): number | undefined;
+    joinSelectivity(leftTable: TableSchema, rightTable: TableSchema, joinCondition: ScalarPlanNode): number | undefined;
+    distinctValues(table: TableSchema, columnName: string): number | undefined;
+    indexSelectivity(table: TableSchema, indexName: string, predicate: ScalarPlanNode): number | undefined;
+}
+/**
+ * Default statistics provider instance
+ */
+export declare const defaultStatsProvider: NaiveStatsProvider;
+/**
+ * VTab-aware statistics provider instance
+ */
+export declare const vtabStatsProvider: VTabStatsProvider;
+/**
+ * Create a custom statistics provider
+ */
+export declare function createStatsProvider(tableRowsMap?: Map<string, number>, selectivityMap?: Map<string, number>): StatsProvider;
+//# sourceMappingURL=index.d.ts.map

package/dist/src/planner/stats/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/planner/stats/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAC5D,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC;AAKzD;;GAEG;AACH,MAAM,WAAW,aAAa;IAC7B;;;;OAIG;IACH,SAAS,CAAC,KAAK,EAAE,WAAW,GAAG,MAAM,GAAG,SAAS,CAAC;IAElD;;;;;OAKG;IACH,WAAW,CAAC,KAAK,EAAE,WAAW,EAAE,SAAS,EAAE,cAAc,GAAG,MAAM,GAAG,SAAS,CAAC;IAE/E;;;;;;OAMG;IACH,eAAe,CAAC,CAAC,SAAS,EAAE,WAAW,EAAE,UAAU,EAAE,WAAW,EAAE,aAAa,EAAE,cAAc,GAAG,MAAM,GAAG,SAAS,CAAC;IAErH;;;;;OAKG;IACH,cAAc,CAAC,CAAC,KAAK,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAAC;IAE5E;;;;;;OAMG;IACH,gBAAgB,CAAC,CAAC,KAAK,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,cAAc,GAAG,MAAM,GAAG,SAAS,CAAC;CACxG;AAED;;;GAGG;AACH,qBAAa,kBAAmB,YAAW,aAAa;IAEtD,OAAO,CAAC,QAAQ,CAAC,gBAAgB;IACjC,OAAO,CAAC,QAAQ,CAAC,kBAAkB;gBADlB,gBAAgB,GAAE,MAAa,EAC/B,kBAAkB,GAAE,MAAY;IAMlD,SAAS,CAAC,KAAK,EAAE,WAAW,GAAG,MAAM,GAAG,SAAS;IAQjD,WAAW,CAAC,KAAK,EAAE,WAAW,EAAE,SAAS,EAAE,cAAc,GAAG,MAAM,GAAG,SAAS;IAO9E,eAAe,CAAC,SAAS,EAAE,WAAW,EAAE,UAAU,EAAE,WAAW,EAAE,cAAc,EAAE,cAAc,GAAG,MAAM,GAAG,SAAS;IAWpH,cAAc,CAAC,KAAK,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS;IAU1E,gBAAgB,CAAC,KAAK,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,cAAc,GAAG,MAAM,GAAG,SAAS;IAQtG,OAAO,CAAC,4BAA4B;CAmBpC;AAED;;;GAGG;AACH,qBAAa,iBAAkB,YAAW,aAAa;IAErD,OAAO,CAAC,QAAQ,CAAC,QAAQ;gBAAR,QAAQ,GAAE,aAAwC;IAKpE,SAAS,CAAC,KAAK,EAAE,WAAW,GAAG,MAAM,GAAG,SAAS;IAkBjD,WAAW,CAAC,KAAK,EAAE,WAAW,EAAE,SAAS,EAAE,cAAc,GAAG,MAAM,GAAG,SAAS;IAkB9E,eAAe,CAAC,SAAS,EAAE,WAAW,EAAE,UAAU,EAAE,WAAW,EAAE,aAAa,EAAE,cAAc,GAAG,MAAM,GAAG,SAAS;IAInH,cAAc,CAAC,KAAK,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS;IAI1E,gBAAgB,CAAC,KAAK,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,cAAc,GAAG,MAAM,GAAG,SAAS;CAGtG;AAED;;GAEG;AACH,eAAO,MAAM,oBAAoB,oBAA2B,CAAC;AAE7D;;GAEG;AACH,eAAO,MAAM,iBAAiB,mBAA0B,CAAC;AAEzD;;GAEG;AACH,wBAAgB,mBAAmB,CAClC,YAAY,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,EAClC,cAAc,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,GAClC,aAAa,CAWf"}