pure-js-db 0.0.0-stage → 2.53.0

package/src/optimizer/limit-pushdown.js

@@ -0,0 +1,70 @@
+/**
+ * optimizer/limit-pushdown.js — LimitPushdownRule（post 阶段）
+ *
+ * 将 LIMIT 下推到子查询/派生表，减少中间结果集大小。
+ * 衔接 P-P0-2：LIMIT 下推进计划。
+ */
+
+import { OptimizerRule } from './optimizer-rule.js';
+
+export class LimitPushdownRule extends OptimizerRule {
+  name = 'limit-pushdown';
+  phase = 'post';
+  dependsOn = [];
+
+  /**
+     * 检测 stmt 含 LIMIT + 子查询/派生表
+     * @param {Object} stmt
+     * @param {Object} ctx
+     * @returns {boolean}
+     */
+  applies(stmt, _ctx) {
+    if (!stmt) {
+      return false;
+    }
+    if (stmt.limit === null || stmt.limit === undefined) {
+      return false;
+    }
+    if (!stmt.from) {
+      return false;
+    }
+    return stmt.from.some(item => item && (item.subquery || item.derived));
+  }
+
+  /**
+     * 将 LIMIT 下推到子查询/派生表
+     * @param {Object} stmt
+     * @param {Object} ctx
+     * @returns {{ changed: boolean, stats?: Object }}
+     */
+  rewrite(stmt, ctx) {
+    try {
+      if (!this.applies(stmt, ctx)) {
+        return { changed: false };
+      }
+
+      let pushedCount = 0;
+      const limitValue = stmt.limit;
+
+      for (const item of stmt.from) {
+        if (item && item.subquery && item.subquery.limit === undefined) {
+          item.subquery.limit = limitValue;
+          pushedCount++;
+        }
+        if (item && item.derived && item.derived.limit === undefined) {
+          item.derived.limit = limitValue;
+          pushedCount++;
+        }
+      }
+
+      if (pushedCount > 0) {
+        return { changed: true, stats: { pushedCount } };
+      }
+      return { changed: false };
+    } catch (e) {
+      return { changed: false, stats: { error: e.message } };
+    }
+  }
+}
+
+export default LimitPushdownRule;

package/src/optimizer/optimized-plan.js

@@ -0,0 +1,54 @@
+/**
+ * optimizer/optimized-plan.js — OptimizedPlan 统一计划对象
+ *
+ * 扩展 QueryPlan，新增优化管线产出的计划字段。
+ * 增量兼容：新增字段默认 undefined，executor 消费时 undefined 走旧逻辑。
+ */
+
+import { QueryPlan } from './optimizer.js';
+
+export class OptimizedPlan extends QueryPlan {
+  /**
+     * @param {string} type - 访问路径类型（'full_scan' | 'index_eq' | 'index_range' | 'index_in'）
+     * @param {string} tableName - 表名
+     */
+  constructor(type, tableName) {
+    super(type, tableName);
+    /** @type {Object|null} 访问路径（full_scan/index_eq/index_range + 索引名） */
+    this.accessPath = undefined;
+    /** @type {Object[]|null} 连接顺序（JOIN 重排结果） */
+    this.joinOrder = undefined;
+    /** @type {Object[]|null} 谓词（下推后的剩余谓词） */
+    this.predicates = undefined;
+    /** @type {Object|null} LIMIT 下推信息 */
+    this.limitPushdown = undefined;
+    /** @type {Object|null} 并行度提示 */
+    this.parallelHint = undefined;
+  }
+
+  /**
+     * 序列化供 EXPLAIN 与计划缓存
+     * @returns {Object}
+     */
+  toJSON() {
+    return {
+      type: this.type,
+      tableName: this.tableName,
+      estimatedCost: this.estimatedCost,
+      estimatedRows: this.estimatedRows,
+      indexName: this.indexName,
+      columnName: this.columnName,
+      indexValue: this.indexValue,
+      rangeStart: this.rangeStart,
+      rangeEnd: this.rangeEnd,
+      inValues: this.inValues,
+      accessPath: this.accessPath,
+      joinOrder: this.joinOrder,
+      predicates: this.predicates,
+      limitPushdown: this.limitPushdown,
+      parallelHint: this.parallelHint,
+    };
+  }
+}
+
+export default OptimizedPlan;

package/src/optimizer/optimizer-rule.js

@@ -0,0 +1,295 @@
+/**
+ * optimizer/optimizer-rule.js — 优化器统一管线基础设施
+ *
+ * 包含：
+ *   - OptimizerRule：规则统一接口（RBO 与 CBO 同构）
+ *   - OptimizeContext：贯穿管线的上下文对象
+ *   - OptimizationTrace / TraceEntry：trace 累积器
+ *   - OptimizerRegistry：规则注册表（拓扑排序 + 循环检测）
+ *   - OptimizerConfigError：循环依赖错误
+ *
+ * 设计原则：
+ *   - 规则间依赖序通过 dependsOn 声明，拓扑排序后执行
+ *   - 循环依赖 fail-closed（抛 OptimizerConfigError 禁止带环启动）
+ *   - 跨 phase 依赖禁止（RBO 规则不能依赖 CBO 规则）
+ */
+
+/**
+ * 循环依赖错误（fail-closed）
+ */
+export class OptimizerConfigError extends Error {
+  /**
+     * @param {string} message
+     * @param {string[]} cycleRules - 参与环的规则名列表
+     */
+  constructor(message, cycleRules = []) {
+    super(message);
+    this.name = 'OptimizerConfigError';
+    this.cycleRules = cycleRules;
+  }
+}
+
+/**
+ * 规则统一接口（RBO 与 CBO 同构）
+ */
+export class OptimizerRule {
+  /** @type {string} 规则名（如 'predicate-pushdown'） */
+  name = '';
+
+  /** @type {'rbo'|'cbo'|'post'} 阶段 */
+  phase = 'rbo';
+
+  /** @type {string[]} 依赖规则名列表（只引用同 phase 内规则） */
+  dependsOn = [];
+
+  /**
+     * 快速判定是否命中
+     * @param {Object} stmt - SELECT AST
+     * @param {OptimizeContext} ctx
+     * @returns {boolean}
+     */
+  applies(_stmt, _ctx) {
+    throw new Error('OptimizerRule.applies: not implemented');
+  }
+
+  /**
+     * 原地改写 AST，返回 { changed, stats } 或新计划片段
+     * @param {Object} stmt - SELECT AST
+     * @param {OptimizeContext} ctx
+     * @returns {{ changed: boolean, stats?: Object }}
+     */
+  rewrite(_stmt, _ctx) {
+    throw new Error('OptimizerRule.rewrite: not implemented');
+  }
+}
+
+/**
+ * 贯穿管线的上下文对象
+ */
+export class OptimizeContext {
+  /**
+     * @param {Object} opts
+     * @param {Object} opts.db - TableStorage 句柄
+     * @param {Object|null} [opts.stats] - 统计句柄（缺失时 CBO 降级为 RBO）
+     * @param {Object|null} [opts.snapshot] - MVCC 读快照句柄
+     * @param {OptimizationTrace} [opts.trace] - trace 累积器
+     */
+  constructor({ db, stats = null, snapshot = null, trace = null }) {
+    this.db = db;
+    this.stats = stats;
+    this.snapshot = snapshot;
+    this.trace = trace || new OptimizationTrace();
+    /** @type {Object|null} 输出计划（管线填充） */
+    this.optimizedPlan = null;
+  }
+}
+
+/**
+ * trace 条目（单规则执行记录）
+ */
+export class TraceEntry {
+  /**
+     * @param {Object} opts
+     * @param {string} opts.ruleName
+     * @param {string} opts.phase
+     * @param {boolean} opts.hit - 是否命中
+     * @param {number} opts.durationMs - 耗时
+     * @param {boolean} [opts.changed] - 是否改写
+     * @param {boolean} [opts.degraded] - CBO 降级标注
+     * @param {boolean} [opts.stale] - 统计过期标注
+     * @param {string} [opts.error] - 异常信息
+     */
+  constructor({ ruleName, phase, hit, durationMs, changed = false, degraded = false, stale = false, error = null }) {
+    this.ruleName = ruleName;
+    this.phase = phase;
+    this.hit = hit;
+    this.durationMs = durationMs;
+    this.changed = changed;
+    this.degraded = degraded;
+    this.stale = stale;
+    this.error = error;
+  }
+}
+
+/**
+ * trace 累积器
+ */
+export class OptimizationTrace {
+  constructor() {
+    /** @type {TraceEntry[]} */
+    this.entries = [];
+    this._enabled = false;
+  }
+
+  enable() {
+    this._enabled = true;
+  }
+
+  /**
+     * 累加一条 trace
+     * @param {TraceEntry} entry
+     */
+  add(entry) {
+    this.entries.push(entry);
+  }
+
+  /**
+     * 序列化供 EXPLAIN 消费
+     * @returns {Object}
+     */
+  toJSON() {
+    return {
+      entries: this.entries.map(e => ({
+        rule: e.ruleName,
+        phase: e.phase,
+        hit: e.hit,
+        durationMs: e.durationMs,
+        changed: e.changed,
+        degraded: e.degraded,
+        stale: e.stale,
+        error: e.error,
+      })),
+    };
+  }
+}
+
+/**
+ * 规则注册表（拓扑排序 + 循环检测）
+ */
+export class OptimizerRegistry {
+  constructor() {
+    /** @type {Map<string, OptimizerRule>} 规则名 → 规则实例 */
+    this._rules = new Map();
+    /** @type {Map<string, string[]>} phase → 拓扑序规则名列表 */
+    this._topoCache = new Map();
+  }
+
+  /**
+     * 注册规则
+     * @param {OptimizerRule} rule
+     * @throws {OptimizerConfigError} 跨 phase 依赖
+     */
+  registerRule(rule) {
+    if (!(rule instanceof OptimizerRule)) {
+      throw new OptimizerConfigError(`注册的不是 OptimizerRule 实例: ${rule}`);
+    }
+    if (!rule.name) {
+      throw new OptimizerConfigError('规则名不能为空');
+    }
+    if (this._rules.has(rule.name)) {
+      throw new OptimizerConfigError(`规则已存在: ${rule.name}`);
+    }
+
+    // 检查 dependsOn 只引用同 phase 内规则
+    for (const dep of rule.dependsOn) {
+      const depRule = this._rules.get(dep);
+      if (depRule && depRule.phase !== rule.phase) {
+        throw new OptimizerConfigError(
+          `规则 "${rule.name}"（phase=${rule.phase}）依赖 "${dep}"（phase=${depRule.phase}）：跨 phase 依赖禁止`,
+        );
+      }
+    }
+
+    this._rules.set(rule.name, rule);
+    // 清空拓扑缓存（下次 getTopoOrder 重新计算）
+    this._topoCache.delete(rule.phase);
+  }
+
+  /**
+     * 获取某 phase 的规则列表
+     * @param {'rbo'|'cbo'|'post'} phase
+     * @returns {OptimizerRule[]}
+     */
+  getRulesByPhase(phase) {
+    const result = [];
+    for (const rule of this._rules.values()) {
+      if (rule.phase === phase) {
+        result.push(rule);
+      }
+    }
+    return result;
+  }
+
+  /**
+     * 获取某 phase 的拓扑序规则名列表（Kahn 算法）
+     * @param {'rbo'|'cbo'|'post'} phase
+     * @returns {string[]}
+     * @throws {OptimizerConfigError} 循环依赖
+     */
+  getTopoOrder(phase) {
+    if (this._topoCache.has(phase)) {
+      return this._topoCache.get(phase);
+    }
+
+    const rules = this.getRulesByPhase(phase);
+    const ruleNames = new Set(rules.map(r => r.name));
+
+    // 构建邻接表与入度表
+    const inDegree = new Map();
+    const adj = new Map();
+    for (const rule of rules) {
+      inDegree.set(rule.name, 0);
+      adj.set(rule.name, []);
+    }
+    for (const rule of rules) {
+      for (const dep of rule.dependsOn) {
+        if (ruleNames.has(dep)) {
+          adj.get(dep).push(rule.name);
+          inDegree.set(rule.name, inDegree.get(rule.name) + 1);
+        }
+      }
+    }
+
+    // Kahn 算法
+    const queue = [];
+    for (const [name, deg] of inDegree) {
+      if (deg === 0) {
+        queue.push(name);
+      }
+    }
+    const sorted = [];
+    while (queue.length > 0) {
+      const name = queue.shift();
+      sorted.push(name);
+      for (const next of adj.get(name)) {
+        inDegree.set(next, inDegree.get(next) - 1);
+        if (inDegree.get(next) === 0) {
+          queue.push(next);
+        }
+      }
+    }
+
+    // 检测循环依赖
+    if (sorted.length < rules.length) {
+      const cycleRules = rules.filter(r => !sorted.includes(r.name)).map(r => r.name);
+      throw new OptimizerConfigError(
+        `phase="${phase}" 存在循环依赖，参与环规则: ${cycleRules.join(', ')}`,
+        cycleRules,
+      );
+    }
+
+    this._topoCache.set(phase, sorted);
+    return sorted;
+  }
+
+  /**
+     * 检测全部 phase 的循环依赖
+     * @throws {OptimizerConfigError} 循环依赖
+     */
+  detectCycle() {
+    for (const phase of ['rbo', 'cbo', 'post']) {
+      this.getTopoOrder(phase);
+    }
+  }
+
+  /**
+     * 获取规则实例
+     * @param {string} name
+     * @returns {OptimizerRule|undefined}
+     */
+  getRule(name) {
+    return this._rules.get(name);
+  }
+}
+
+export default OptimizerRule;