nodejs-store 1.0.0

package/src/crud/query.js

@@ -0,0 +1,123 @@
+'use strict';
+
+/**
+ * 读路径 —— find 快路径 / 两阶段（取 ID → 关联 → 还原排序）/ 标准聚合 + asyncFn 尾处理
+ * / 跨库联邦（逐源执行 → 内存 hash join）
+ */
+
+const { core: _core, getAsyncFn } = require('../schema');
+const { _call, _ctx, _exec, _execOn, resolvePlaceholders } = require('./exec');
+
+/** 执行读命令序列：find 快路径 / 两阶段（取 ID → 关联 → 还原排序）/ 标准聚合 */
+async function _runQueryPlan(plan) {
+  if (plan.mode === 'two_phase') {
+    const idDocs = await _exec(plan.commands[0]);
+    const ids = idDocs.map((d) => d._id);
+    if (!ids.length) return [];
+    const cmd2 = resolvePlaceholders(plan.commands[1], { ids });
+    const items = await _exec(cmd2);
+    return _core.restoreSortOrder(items, ids, plan.sort ?? null).items;
+  }
+  return _exec(plan.commands[0]);
+}
+
+/** 读路径尾处理两段式：core 后处理 → Host 执行 asyncFn → core 剥离注入依赖 */
+async function _finalize(plan, items) {
+  if (!plan.postprocess) return items;
+  const prepared = _core.prepareQuery(plan.postprocess, items, _ctx());
+  for (const ref of prepared.fnRefs) {
+    const fn = getAsyncFn(ref);
+    if (!fn) throw new Error(`asyncFn 计算列 ${ref} 未注册实现`);
+    await fn(prepared.items, _ctx());
+  }
+  return _core.stripQuery(plan.postprocess, prepared.items).items;
+}
+
+/**
+ * GQL 查询（返回数组）
+ *
+ * 支持的 params 键（通过 GQL 的 @key 引用）:
+ *   $condition / $sort / $skip / $limit / $pipeline
+ * 使用 $pipeline 时，框架不追加 compute 层、不补默认值、不裁剪，完全由用户控制。
+ *
+ * `routeOverride`（多租户路由，可选）：`{ source?, namespace? }`，覆盖命令定位，
+ * 权限/计算列仍按结构 schema 判定（见 multi-datasource-routing-plan.md §6）。
+ */
+async function query(gql, params = null, routeOverride = null) {
+  const plan = _call(() => _core.planQuery(gql, params ?? {}, _ctx(), routeOverride));
+  return _finalize(plan, await _runQueryPlan(plan));
+}
+
+/** GQL 查询（返回单条） */
+async function queryOne(gql, params = null, routeOverride = null) {
+  const items = await query(gql, params, routeOverride);
+  return items.length ? items[0] : null;
+}
+
+/**
+ * 执行单个联邦取数单元（按 `sources[].source` 精确路由；two_phase 走两阶段）
+ *
+ * 与单库 `_runQueryPlan` 同形：只差路由键（单元自带 source，不按 collection 反查）。
+ */
+async function _runFederatedUnit(unit) {
+  const commands = unit.commands || [];
+  if (unit.mode === 'two_phase') {
+    const idDocs = await _execOn(unit.source, commands[0]);
+    const ids = idDocs.map((d) => d._id);
+    if (!ids.length) return [];
+    const cmd2 = resolvePlaceholders(commands[1], { ids });
+    const items = await _execOn(unit.source, cmd2);
+    return _core.restoreSortOrder(items, ids, unit.sort ?? null).items;
+  }
+  return _execOn(unit.source, commands[0]);
+}
+
+/**
+ * 跨库联邦查询（返回嵌套文档数组）
+ *
+ * Host 四步：core `planFederated` 拆源 → 逐源执行 → core `mergeFederated`
+ * 内存 hash join → 统一后处理（`_finalize`，与单库同一路径）。
+ *
+ * `postprocess` 取自根单元快照（含全部关系），因此结果形状与单库 `query` 完全一致。
+ * 每源取数上限 `MAX_FEDERATION_ROWS` 由 core 强制（超限即报错，拒绝静默全表拉取）；
+ * 无法下推的分页/排序进 `plan.degraded` 并告警，不阻断查询。
+ */
+async function queryFederated(gql, params = null) {
+  const plan = _call(() => _core.planFederated(gql, params ?? {}, _ctx()));
+
+  for (const d of plan.degraded || []) {
+    console.warn(`[federation] 降级 ${(d && d.code) || ''}: ${(d && d.message) || ''}`);
+  }
+
+  const results = [];
+  for (const unit of plan.sources || []) {
+    results.push(await _runFederatedUnit(unit));
+  }
+
+  const merged = _call(() => _core.mergeFederated(plan, results));
+  return _finalize(plan, merged);
+}
+
+/**
+ * GQL 查询（返回 items + total + 分页元数据）
+ *
+ * 支持两种分页参数方式：
+ *   1. page/pageSize（推荐）— 自动计算 skip/limit，page 默认 0，pageSize 默认 50
+ *   2. 传统 $skip/$limit — 从 GQL 参数推导 page/pageSize
+ * pageSize 上限 5000，防止拖库。
+ */
+async function queryWithCount(gql, params = null, routeOverride = null) {
+  const plan = _call(() =>
+    _core.planQueryWithCount(gql, params ?? {}, _ctx(), null, routeOverride));
+  const items = await _finalize(plan, await _runQueryPlan(plan));
+  const total = await _exec(plan.countCommand);
+  return {
+    items,
+    total,
+    hasMore: (plan.page + 1) * plan.pageSize < total,
+    page: plan.page,
+    pageSize: plan.pageSize,
+  };
+}
+
+module.exports = { query, queryOne, queryWithCount, queryFederated };

package/src/crud/write.js

@@ -0,0 +1,103 @@
+'use strict';
+
+/**
+ * 写路径 —— 单条/批量插入、更新、删除归档、存在性与计数
+ */
+
+const { core: _core, get: _getSchema } = require('../schema');
+const { _call, _ctx, _exec, _now } = require('./exec');
+const { _generateId } = require('./id');
+
+/** creator 写权限探针：先规划，若 needsProbe 则执行探针命令后重入 */
+async function _planWithProbe(planFn) {
+  let out = planFn(null, null);
+  if (out.needsProbe) {
+    const probeDoc = await _exec(out.needsProbe);
+    out = planFn(probeDoc !== null && probeDoc !== undefined, probeDoc ?? null);
+  }
+  return out;
+}
+
+/** 插入一条（`routeOverride` 可选：`{ source?, namespace? }` 多租户路由） */
+async function insert(schemaName, data, routeOverride = null) {
+  const s = _getSchema(schemaName);
+  const plan = _call(() =>
+    _core.planInsert(schemaName, data ?? null, _now(), s.idPrefix ? _generateId(s) : '', _ctx(),
+      routeOverride));
+  await _exec(plan.command);
+  return plan.returns;
+}
+
+/** 批量插入（带权限检查，自动生成 _id 和时间戳；空数组直接返回空） */
+async function insertMany(schemaName, docs, routeOverride = null) {
+  if (!Array.isArray(docs) || !docs.length) return [];
+
+  const s = _getSchema(schemaName);
+  const plan = _call(() => _core.planInsertMany(
+    schemaName,
+    docs,
+    _now(),
+    // core 按需消费（仅无 _id 的文档取用），多备无害
+    docs.map(() => (s.idPrefix ? _generateId(s) : '')),
+    _ctx(),
+    routeOverride,
+  ));
+  if (plan.command) await _exec(plan.command);
+  return plan.returns;
+}
+
+/**
+ * 更新一条（支持原生操作符，不触发默认值）
+ *
+ * data 的 key 以 '$' 开头 → 原生 MongoDB 操作符（$set/$inc/$unset 等）直接透传。
+ * 否则自动包装为 $set 模式。`routeOverride` 可选（多租户路由）。
+ */
+async function update(schemaName, condition, data, options = null, routeOverride = null) {
+  const out = await _planWithProbe((found, doc) => _call(() =>
+    _core.planUpdate(schemaName, condition ?? null, data ?? null, options ?? null, _now(), _ctx(),
+      found, doc, routeOverride)));
+  const result = await _exec(out.command);
+  return result ? _call(() => _core.applyWriteDefaults(schemaName, result)) : null;
+}
+
+/** 批量更新（支持原生操作符） */
+async function updateMany(schemaName, condition, data, routeOverride = null) {
+  const out = _call(() =>
+    _core.planUpdateMany(schemaName, condition ?? null, data ?? null, _now(), _ctx(), routeOverride));
+  const result = await _exec(out.command);
+  return { modifiedCount: result.modifiedCount };
+}
+
+/** 删除 —— 原表数据先归档到对应 `_deleted` 附表（附 deletedAt），再物理删除原表数据 */
+async function remove(schemaName, condition, routeOverride = null) {
+  const out = await _planWithProbe((found, doc) => _call(() =>
+    _core.planRemove(schemaName, condition ?? null, _ctx(), found, doc, routeOverride)));
+
+  let archivedCount = 0;
+  if (out.findCommand) {
+    const docs = await _exec(out.findCommand);
+    if (docs.length) {
+      const arch = _call(() => _core.planArchiveDocs(schemaName, docs, _now(), routeOverride));
+      await _exec(arch.command);
+      archivedCount = docs.length;
+    }
+  }
+
+  const result = await _exec(out.deleteCommand);
+  return { deletedCount: result.deletedCount, archivedCount };
+}
+
+/** 判断是否存在 */
+async function exists(schemaName, condition, routeOverride = null) {
+  const cmd = _call(() => _core.planExists(schemaName, condition ?? null, routeOverride));
+  const doc = await _exec(cmd);
+  return doc !== null && doc !== undefined;
+}
+
+/** 统计符合条件的文档数量 */
+async function count(schemaName, filter = null, routeOverride = null) {
+  const cmd = _call(() => _core.planCount(schemaName, filter ?? null, routeOverride));
+  return _exec(cmd);
+}
+
+module.exports = { insert, insertMany, update, updateMany, remove, exists, count };

package/src/datasource.js

@@ -0,0 +1,148 @@
+'use strict';
+
+/**
+ * 数据源路由（多后端）
+ *
+ * core 产出的 Command 携带 `source` / `namespace` / `collection` 三元组
+ * （见 rust-store/core 的 Command 契约），Host 只按 `source` 选连接、
+ * 按 `namespace` 定位连接内的库/schema：
+ *   - Mongo 源：直接交原生驱动（`db.collection(...)`）
+ *   - SQL 源（mysql / postgres / sqlite）：先经 core `dialectTranslate` 翻译为
+ *     SQL 语句序列，再交该连接的 `exec` 执行器
+ *
+ * Mongo 连接支持两种形态（绝不猜，按命令的 namespace 严格校验）：
+ *   - db 实例：命令 `namespace` 必须为 null（db 实例无法跨库，非 null 显式报错）
+ *   - MongoClient：命令 `namespace` 必须非 null（db 名）→ `client.db(ns).collection(...)`
+ *
+ * 数据源名缺省为 `default`；`init` 传入单个 Mongo db 实例时自动归一为
+ * `{ default: db }`，保证既有单库调用零变更。
+ */
+
+const { core: _core, get: _getSchema } = require('./schema');
+const executors = require('./executors');
+
+const DEFAULT_SOURCE = 'default';
+
+let _connections = Object.create(null);
+
+/** Mongo 形态判别：db 实例（collection 为函数）或 MongoClient（db 为函数且无 collection） */
+function _isMongoHandle(x) {
+  return (
+    !!x &&
+    (typeof x.collection === 'function' ||
+      (typeof x.db === 'function' && typeof x.collection !== 'function'))
+  );
+}
+
+/** 归一化连接映射：单个 Mongo db 实例 / MongoClient → `{ default: 连接 }` */
+function _normalize(connections) {
+  if (_isMongoHandle(connections)) {
+    return { [DEFAULT_SOURCE]: connections };
+  }
+  return connections || {};
+}
+
+/** 设置数据源连接映射（Mongo 传 db 实例或 MongoClient；SQL 传 `{ kind, exec }` 描述符） */
+function setConnections(connections) {
+  _connections = Object.assign(Object.create(null), _normalize(connections));
+}
+
+/** 取指定数据源连接（未配置即报错） */
+function getConnection(source) {
+  const conn = _connections[source];
+  if (conn === undefined) {
+    throw new Error(
+      `数据源未配置: ${source}（请检查 init(connections) 与 schema 的 datasource 绑定）`,
+    );
+  }
+  return conn;
+}
+
+/**
+ * Mongo 源：按命令的 `namespace` 解析目标 db（两种形态，绝不猜）
+ *
+ *   - db 实例（`db.collection` 为函数）：namespace 必须为 null，非 null 显式报错；
+ *   - MongoClient（`db` 为函数且无 `collection`）：namespace 必须非 null，
+ *     返回 `client.db(namespace)`；
+ *   - 非 Mongo（SQL 描述符）返回 null，由调用方走 SQL 路径。
+ */
+function mongoDb(connection, source, namespace) {
+  if (typeof connection.collection === 'function') {
+    if (namespace) {
+      throw new Error(
+        `数据源 ${source} 是 Mongo db 实例，命令携带了 namespace="${namespace}"（db 实例不支持跨库；跨库请改传 MongoClient 并用 schema.namespace 声明库名）`,
+      );
+    }
+    return connection;
+  }
+  if (typeof connection.db === 'function') {
+    if (!namespace) {
+      throw new Error(
+        `数据源 ${source} 是 MongoClient，命令缺少 namespace（ MongoClient 形态必须在 schema 声明 namespace 即 db 名）`,
+      );
+    }
+    return connection.db(namespace);
+  }
+  return null;
+}
+
+/** schema 声明的数据源名（缺省 `default`） */
+function sourceOfSchema(name) {
+  return _getSchema(name).datasource || DEFAULT_SOURCE;
+}
+
+/** 某 schema 所属数据源的连接（供 Host 侧直连场景） */
+function connectionOfSchema(name) {
+  return getConnection(sourceOfSchema(name));
+}
+
+/** 某 schema 的 Mongo db 句柄（按镜像的 datasource + namespace 解析；SQL 源返回 null） */
+function dbOfSchema(name) {
+  const s = _getSchema(name);
+  const source = s.datasource || DEFAULT_SOURCE;
+  return mongoDb(getConnection(source), source, s.namespace || null);
+}
+
+/** Command.source → `{ source, connection }`（三元组中的 source 精确路由） */
+function route(cmd) {
+  const source = cmd.source || DEFAULT_SOURCE;
+  return { source, connection: getConnection(source) };
+}
+
+/**
+ * SQL 路径：translate（core 纯逻辑）→ exec（连接执行器）→ 结果塑形
+ *
+ * 执行器只做「绑定参数 + 执行 + restoreRows」，返回中立包络；此处依 command.kind
+ * 塑形为 Mongo 驱动等价返回值（见 `./executors/index.js#shapeResult`），
+ * 使上层（crud/*）对 Mongo / SQL 两条路径无感。
+ */
+async function execSql(source, connection, cmd) {
+  if (typeof connection.exec !== 'function') {
+    throw new Error(
+      `SQL 数据源 ${source}(${connection.kind}) 的执行器未接入（见执行文档 Phase 4）`,
+    );
+  }
+  const plan = _core.dialectTranslate(connection.kind, cmd);
+  // Host 兜底：core 标记了无法安全下推的组合（如 $lookup 子 $limit 每父 top-N）时，
+  // 绝不执行「缺少该段」的 SQL（会静默返回错误结果），改为显式报错，由调用方降级重查。
+  if (Array.isArray(plan.unsupported) && plan.unsupported.length > 0) {
+    const codes = plan.unsupported.map((u) => (u && u.code) || String(u)).join(', ');
+    throw new Error(
+      `SQL 下推不支持（${connection.kind}）: ${codes}；${(plan.warnings || []).join(' / ')}`,
+    );
+  }
+  const out = await connection.exec(plan);
+  return executors.shapeResult(cmd, out);
+}
+
+module.exports = {
+  DEFAULT_SOURCE,
+  setConnections,
+  getConnection,
+  mongoDb,
+  sourceOfSchema,
+  connectionOfSchema,
+  dbOfSchema,
+  route,
+  execSql,
+};

package/src/executors/index.js

@@ -0,0 +1,60 @@
+'use strict';
+
+/**
+ * SQL 执行器注册与结果塑形（Phase 4）
+ *
+ * 分层（对齐铁律 1/8）：
+ *   core `dialectTranslate`（纯逻辑，产 SQL + rowShape）
+ *     → 执行器 `{mysql,postgres,sqlite}`（绑定参数 + 执行 + `restoreRows`）
+ *     → 本模块把中立包络 `{docs, rows, affectedRows}` 塑形为 **Mongo 驱动等价返回值**
+ *
+ * 塑形规则与 `crud/exec.js#_execMongo` 逐一对应，保证 Mongo / SQL 两条路径对上层
+ * （`crud/query|write|mutation`）透明：上层只看到同一套返回值语义。
+ */
+
+const mysql = require('./mysql');
+const postgres = require('./postgres');
+const sqlite = require('./sqlite');
+
+const _BACKENDS = { mysql, postgres, sqlite };
+
+/** 创建 SQL 数据源连接描述符 `{ kind, exec }`（driver 为对应驱动实例/连接） */
+function createConnection(kind, driver, options) {
+  const mod = _BACKENDS[kind];
+  if (!mod) throw new Error(`未知 SQL 后端: ${kind}（支持 mysql/postgres/sqlite）`);
+  return mod.create(driver, options);
+}
+
+/** 取行首列标量（COUNT 等聚合列无稳定别名，取首个值；PG 的 bigint 为字符串需数值化） */
+function _scalar(rows) {
+  const row = rows && rows[0];
+  if (!row) return 0;
+  const v = Object.values(row)[0];
+  return typeof v === 'string' ? Number(v) : v;
+}
+
+/** 中立包络 → Mongo 驱动等价返回值 */
+function shapeResult(cmd, out) {
+  switch (cmd.kind) {
+    case 'find':
+    case 'aggregate':
+      return out.docs || [];
+    case 'findOne':
+    case 'findOneAndUpdate':
+      return (out.docs && out.docs[0]) || null;
+    case 'countDocuments':
+      return _scalar(out.rows);
+    case 'insertOne':
+      return cmd.doc;
+    case 'insertMany':
+      return { insertedCount: (cmd.docs || []).length };
+    case 'updateMany':
+      return { modifiedCount: out.affectedRows };
+    case 'deleteMany':
+      return { deletedCount: out.affectedRows };
+    default:
+      return out;
+  }
+}
+
+module.exports = { createConnection, shapeResult, mysql, postgres, sqlite };

package/src/executors/mysql.js

@@ -0,0 +1,46 @@
+'use strict';
+
+/**
+ * MySQL 执行器（驱动：mysql2/promise）
+ *
+ * 只做「绑定参数 + 执行 + 回喂」（铁律 1/8）：SQL 全部由 core `dialectTranslate`
+ * 产出（占位符为 `?`），本模块不拼任何 SQL。MySQL 无 `RETURNING`，写后回读由 core
+ * 产出「UPDATE/INSERT + SELECT」两条语句，本模块按序执行并取回读结果即可。
+ * 返回中立包络 `{ docs, rows, affectedRows }`，由 `./index.js` 依 command.kind 塑形。
+ */
+
+const { core: _core } = require('../schema');
+
+/** mysql2 返回 RowDataPacket 实例，转普通对象后再交 core（绑定层只认纯 JSON） */
+function _plain(row) {
+  const out = {};
+  for (const k of Object.keys(row)) out[k] = row[k];
+  return out;
+}
+
+/** 创建执行器描述符（可直接作为 `init(connections)` 的一个 SQL 数据源连接） */
+function create(driver, _options = {}) {
+  if (!driver || typeof driver.execute !== 'function') {
+    throw new TypeError('mysql 执行器需要 mysql2/promise 的连接或连接池');
+  }
+  return {
+    kind: 'mysql',
+    async exec(plan) {
+      let docs = null;
+      let rows = null;
+      let affectedRows = 0;
+      for (const stmt of plan.stmts) {
+        const [raw] = await driver.execute(stmt.text, stmt.params || []);
+        if (Array.isArray(raw)) {
+          rows = raw.map(_plain);
+          if (stmt.rowShape) docs = _core.restoreRows(stmt.rowShape, rows);
+        } else {
+          affectedRows = Number(raw.affectedRows || 0);
+        }
+      }
+      return { docs, rows, affectedRows };
+    },
+  };
+}
+
+module.exports = { create };

package/src/executors/postgres.js

@@ -0,0 +1,36 @@
+'use strict';
+
+/**
+ * PostgreSQL 执行器（驱动：pg）
+ *
+ * 只做「绑定参数 + 执行 + 回喂」（铁律 1/8）：SQL 全部由 core `dialectTranslate`
+ * 产出（占位符为 `$n`，params 顺序一致），本模块不拼任何 SQL。PG 原生支持
+ * `RETURNING`，故写后回读为单语句。返回中立包络 `{ docs, rows, affectedRows }`，
+ * 由 `./index.js` 依 command.kind 塑形为 Mongo 驱动等价返回值。
+ */
+
+const { core: _core } = require('../schema');
+
+/** 创建执行器描述符（可直接作为 `init(connections)` 的一个 SQL 数据源连接） */
+function create(driver, _options = {}) {
+  if (!driver || typeof driver.query !== 'function') {
+    throw new TypeError('postgres 执行器需要 pg 的 Pool/Client 实例');
+  }
+  return {
+    kind: 'postgres',
+    async exec(plan) {
+      let docs = null;
+      let rows = null;
+      let affectedRows = 0;
+      for (const stmt of plan.stmts) {
+        const res = await driver.query(stmt.text, stmt.params || []);
+        rows = res.rows || [];
+        affectedRows = Number(res.rowCount || 0);
+        if (stmt.rowShape) docs = _core.restoreRows(stmt.rowShape, rows);
+      }
+      return { docs, rows, affectedRows };
+    },
+  };
+}
+
+module.exports = { create };

package/src/executors/sqlite.js

@@ -0,0 +1,49 @@
+'use strict';
+
+/**
+ * SQLite 执行器（驱动：better-sqlite3）
+ *
+ * 只做「绑定参数 + 执行 + 回喂」（铁律 1/8）：SQL 全部由 core `dialectTranslate`
+ * 产出，本模块不拼任何 SQL；带 `rowShape` 的语句结果交 core `restoreRows` 还原为
+ * 嵌套文档。返回值是中立包络 `{ docs, rows, affectedRows }`，由 `./index.js`
+ * 依 command.kind 塑形为 Mongo 驱动等价返回值。
+ */
+
+const { core: _core } = require('../schema');
+
+/** better-sqlite3 只接受 number/string/bigint/Buffer/null，布尔需显式转 0/1 */
+function _bind(params) {
+  return (params || []).map((v) => {
+    if (v === true) return 1;
+    if (v === false) return 0;
+    return v === undefined ? null : v;
+  });
+}
+
+/** 创建执行器描述符（可直接作为 `init(connections)` 的一个 SQL 数据源连接） */
+function create(db, _options = {}) {
+  if (!db || typeof db.prepare !== 'function') {
+    throw new TypeError('sqlite 执行器需要 better-sqlite3 Database 实例');
+  }
+  return {
+    kind: 'sqlite',
+    exec(plan) {
+      let docs = null;
+      let rows = null;
+      let affectedRows = 0;
+      for (const stmt of plan.stmts) {
+        const params = _bind(stmt.params);
+        // 带 RETURNING 的写语句同样返回行 → 必须用 all() 取回；其余写语句用 run() 取影响行数
+        if (!stmt.isWrite || stmt.rowShape) {
+          rows = db.prepare(stmt.text).all(...params);
+          if (stmt.rowShape) docs = _core.restoreRows(stmt.rowShape, rows);
+        } else {
+          affectedRows = Number(db.prepare(stmt.text).run(...params).changes || 0);
+        }
+      }
+      return { docs, rows, affectedRows };
+    },
+  };
+}
+
+module.exports = { create };