nodejs-store 1.0.0

package/src/index.js

@@ -0,0 +1,236 @@
+'use strict';
+
+/**
+ * nodejs-store — 轻量多后端数据层（Node.js 版，Rust 单核心架构；支持 MongoDB / MySQL / SQLite / PostgreSQL）
+ *
+ * 核心理念:
+ *   1. 纯 JSON schema 定义，零代码
+ *   2. Rust core 统一实现 GQL 解析 / 权限 / 计算列 / 命令规划（core-node 绑定）
+ *   3. src/*.js 为薄 Host 适配层：驱动 IO + 回调 + 占位符替换
+ *   4. Python 侧（core-py）复用同一 Rust core，双端语义天然一致
+ *
+ * Rust core 与 Node/Python 绑定位于独立仓库 rust-store，本仓库通过其绑定产物引用。
+ *
+ * 用法:
+ *   const { MongoClient } = require('mongodb');
+ *   const { init, store } = require('nodejs-store');
+ *
+ *   const client = new MongoClient(uri);
+ *   await client.connect();
+ *   await init(client.db('mydb'));
+ *   const items = await store.query('Model($condition:@c0) { field1, field2 }', { c0: {} });
+ */
+
+const crud = require('./crud');
+const datasource = require('./datasource');
+const executors = require('./executors');
+const introspect = require('./introspect');
+const permission = require('./permission');
+const schema = require('./schema');
+const { syncSchema } = require('./sync');
+
+class Store {
+  // ── Schema 管理 ──
+  register(defn) {
+    return schema.register(defn);
+  }
+
+  get(name) {
+    return schema.get(name);
+  }
+
+  has(name) {
+    return schema.has(name);
+  }
+
+  list() {
+    return schema.list();
+  }
+
+  // ── CRUD ──
+  /**
+   * GQL 查询。`routeOverride`（可选）：`{ source?, namespace? }` 多租户路由，
+   * 覆盖命令定位（权限/计算列仍按结构 schema 判定）。下同。
+   */
+  async query(gql, params, routeOverride) {
+    return crud.query(gql, params, routeOverride);
+  }
+
+  async queryOne(gql, params, routeOverride) {
+    return crud.queryOne(gql, params, routeOverride);
+  }
+
+  async queryWithCount(gql, params, routeOverride) {
+    return crud.queryWithCount(gql, params, routeOverride);
+  }
+
+  /** 跨库联邦查询（一条 GQL 跨多数据源：各源取数 → 内存 join → 统一后处理） */
+  async queryFederated(gql, params) {
+    return crud.queryFederated(gql, params);
+  }
+
+  async insert(schemaName, data, routeOverride) {
+    return crud.insert(schemaName, data, routeOverride);
+  }
+
+  async insertMany(schemaName, docs, routeOverride) {
+    return crud.insertMany(schemaName, docs, routeOverride);
+  }
+
+  async update(schemaName, condition, data, options, routeOverride) {
+    return crud.update(schemaName, condition, data, options, routeOverride);
+  }
+
+  async updateMany(schemaName, condition, data, routeOverride) {
+    return crud.updateMany(schemaName, condition, data, routeOverride);
+  }
+
+  async remove(schemaName, condition, routeOverride) {
+    return crud.remove(schemaName, condition, routeOverride);
+  }
+
+  async exists(schemaName, condition, routeOverride) {
+    return crud.exists(schemaName, condition, routeOverride);
+  }
+
+  async count(schemaName, filter, routeOverride) {
+    return crud.count(schemaName, filter, routeOverride);
+  }
+
+  // ── Mutation / Upsert ──
+  async mutation(schemaName, data, routeOverride) {
+    return crud.mutation(schemaName, data, routeOverride);
+  }
+
+  async upsert(schemaName, condition, data, options, routeOverride) {
+    return crud.upsert(schemaName, condition, data, options, routeOverride);
+  }
+
+  // ── 原生聚合 ──
+  async aggregate(schemaName, pl, routeOverride) {
+    return crud.aggregate(schemaName, pl, routeOverride);
+  }
+
+  // ── 结构同步（SQL 数据源：introspect → schemaFromRows → mergeSchema → register） ──
+  async syncSchema(opts) {
+    return syncSchema(opts);
+  }
+
+  // ── 底层工具（调试/高级用法） ──
+  /** 解析 GQL 并构建 pipeline，返回 `{tokens, ast, pipeline, projection}` */
+  buildPipeline(gql, params) {
+    return schema.core.buildPipeline(gql, params ?? {}, permission.getContext() ?? null);
+  }
+
+  // ── 权限控制（AsyncLocalStorage 上下文） ──
+  setContext(ctx) {
+    return permission.setContext(ctx);
+  }
+
+  getContext() {
+    return permission.getContext();
+  }
+
+  scopedRoles(roles, fn) {
+    return permission.scopedRoles(roles, fn);
+  }
+
+  async runAsInternal(fn) {
+    return permission.runAsInternal(fn);
+  }
+}
+
+/** 自定义权限错误（实例可被 store.PermissionError 捕获） */
+Store.prototype.PermissionError = permission.PermissionError;
+
+const store = new Store();
+
+/**
+ * 索引名对齐 MongoDB 自动命名（k1_v1_k2_v2），用于幂等创建。
+ *
+ * 按 source 分派：Mongo 源执行 `_createIndexesIfNeeded`；SQL 后端**不建索引**
+ * （`schema.indexes` 仅作元数据，见执行文档 Phase 3 动作 5）。
+ */
+async function _createIndexesIfNeeded() {
+  const names = schema.list();
+  for (const name of names) {
+    const s = schema.get(name);
+    // 索引创建是初始化的辅助动作（非命令路由）：schema 绑定的 source 暂未在
+    // 当前连接映射中时跳过，不阻塞 init（命令路由的 fail fast 不在此处）
+    let db;
+    try {
+      db = datasource.dbOfSchema(name); // Mongo 按 (datasource, namespace) 解析；SQL 源返回 null
+    } catch (e) {
+      continue;
+    }
+    if (!db) continue; // SQL 后端不建索引
+
+    const coll = db.collection(s.collection);
+
+    let existingIndexes;
+    try {
+      existingIndexes = await coll.listIndexes().toArray();
+    } catch (e) {
+      existingIndexes = [];
+    }
+
+    for (const idx of s.indexes || []) {
+      try {
+        const keys = idx.keys;
+        if (!keys) continue;
+
+        // 合并 inline 选项（unique/sparse/expireAfterSeconds 等）与显式 options
+        const explicitOptions = idx.options || {};
+        const finalOptions = {};
+        for (const [k, v] of Object.entries(idx)) {
+          if (k !== 'keys' && k !== 'options') finalOptions[k] = v;
+        }
+        Object.assign(finalOptions, explicitOptions);
+
+        // 检查是否已有同 key 模式的索引（忽略选项差异）
+        const nameFromKeys = Object.entries(keys).map(([k, v]) => `${k}_${v}`).join('_');
+        if (existingIndexes.some((ei) => ei.name === nameFromKeys)) continue;
+
+        await coll.createIndex(Object.entries(keys), finalOptions);
+      } catch (e) {
+        console.error(`[MongoStore] 创建索引失败 ${s.collection}: ${e && e.message ? e.message : e}`);
+      }
+    }
+  }
+}
+
+/**
+ * 初始化 store — 传入数据源连接映射
+ *
+ *   - 多源：`init({ default: db, mongo_b: client, pg_a: { kind: 'postgres', exec }, ... })`
+ *   - 单源简写：`init(db)` / `init(client)`（Mongo db 实例或 MongoClient，自动归一为
+ *     `{ default: 连接 }`）
+ *
+ * 连接按命令的 `source` 路由、`namespace` 定位库（schema 声明）；缺省绑定回落 `default`。
+ */
+async function init(connections) {
+  if (!connections || typeof connections !== 'object') {
+    throw new TypeError('init(connections) 需要数据源连接映射（或单个 MongoDB db 实例）');
+  }
+  datasource.setConnections(connections);
+
+  // 自动创建索引（仅 Mongo 源）— 幂等安全
+  await _createIndexesIfNeeded();
+
+  return store;
+}
+
+module.exports = {
+  init,
+  store,
+  Store,
+  aggregate: crud.aggregate,
+  PermissionError: permission.PermissionError,
+  datasource,
+  schema,
+  permission,
+  crud,
+  executors,
+  introspect,
+  syncSchema,
+};

package/src/introspect/index.js

@@ -0,0 +1,24 @@
+'use strict';
+
+/**
+ * introspection 分派：按后端名把驱动交对应模块，产出统一的规范化行 JSON。
+ *
+ * 统一输出（交 core `schemaFromRows`）：
+ *   `{ tables:[{name}], columns:[{table,name,type,notnull,pk}],
+ *      fks:[{table,column,refTable,refColumn}], indexes:[{table,name,columns,unique}] }`
+ */
+
+const mysql = require('./mysql');
+const postgres = require('./postgres');
+const sqlite = require('./sqlite');
+
+const _BACKENDS = { mysql, postgres, sqlite };
+
+/** 按后端名执行 introspection（sqlite 同步、mysql/postgres 异步，统一 await 返回） */
+async function run(backend, driver, options) {
+  const mod = _BACKENDS[backend];
+  if (!mod) throw new Error(`未知 introspection 后端: ${backend}（支持 mysql/postgres/sqlite）`);
+  return mod.introspect(driver, options);
+}
+
+module.exports = { run, mysql, postgres, sqlite };

package/src/introspect/mysql.js

@@ -0,0 +1,98 @@
+'use strict';
+
+/**
+ * MySQL introspection（驱动：mysql2/promise）
+ *
+ * 只发 `information_schema` 只读查询（铁律 6：绝不写 DDL 回库），产出规范化行 JSON，
+ * 交 core `schemaFromRows` 做纯映射。建议使用只读账号；库名取当前连接的 `DATABASE()`。
+ */
+
+const _TABLES = `
+  SELECT table_name AS name
+  FROM information_schema.tables
+  WHERE table_schema = DATABASE() AND table_type = 'BASE TABLE'
+  ORDER BY table_name`;
+
+const _COLUMNS = `
+  SELECT table_name  AS "table",
+         column_name AS name,
+         column_type AS type,
+         is_nullable AS nullable,
+         column_key  AS columnKey
+  FROM information_schema.columns
+  WHERE table_schema = DATABASE()
+  ORDER BY table_name, ordinal_position`;
+
+const _FKS = `
+  SELECT table_name            AS "table",
+         column_name           AS \`column\`,
+         referenced_table_name AS "refTable",
+         referenced_column_name AS "refColumn"
+  FROM information_schema.key_column_usage
+  WHERE table_schema = DATABASE() AND referenced_table_name IS NOT NULL
+  ORDER BY table_name, ordinal_position`;
+
+const _INDEXES = `
+  SELECT table_name  AS "table",
+         index_name  AS name,
+         non_unique  AS nonUnique,
+         seq_in_index AS seq,
+         column_name AS \`column\`
+  FROM information_schema.statistics
+  WHERE table_schema = DATABASE()
+  ORDER BY table_name, index_name, seq_in_index`;
+
+/** 把 `{table,name,nonUnique,column}` 行按索引名归并出 columns 数组 */
+function _groupIndexes(rows) {
+  const byKey = new Map();
+  for (const r of rows) {
+    const key = `${r.table}::${r.name}`;
+    let entry = byKey.get(key);
+    if (!entry) {
+      entry = { table: r.table, name: r.name, columns: [], unique: Number(r.nonUnique) ? 0 : 1 };
+      byKey.set(key, entry);
+    }
+    entry.columns.push(r.column);
+  }
+  return [...byKey.values()];
+}
+
+async function introspect(driver, { database = null } = {}) {
+  if (!driver || typeof driver.execute !== 'function') {
+    throw new TypeError('mysql introspection 需要 mysql2/promise 的连接或连接池');
+  }
+  // 显式传 database（连接串不带库或跨库同步）→ 参数化 table_schema；
+  // 缺省用当前连接的 DATABASE()。显式库名会作为 namespace 透出到 def。
+  const schemaFilter = database != null ? 'table_schema = ?' : 'table_schema = DATABASE()';
+  const params = database != null ? [database] : [];
+  const tablesSql = (base) => base.replace('table_schema = DATABASE()', schemaFilter);
+
+  const run = async (sql, args = []) => {
+    const [rows] = await driver.execute(sql, args);
+    return rows;
+  };
+  const [tables, columns, fks, indexRows] = await Promise.all([
+    run(tablesSql(_TABLES), params),
+    run(tablesSql(_COLUMNS), params),
+    run(tablesSql(_FKS), params),
+    run(tablesSql(_INDEXES), params),
+  ]);
+
+  return {
+    // 显式库名 → 行携带 namespace（core schemaFromRows 会写进 def）
+    tables: database != null
+      ? tables.map((t) => ({ ...t, namespace: database }))
+      : tables,
+    columns: columns.map((c) => ({
+      table: c.table,
+      name: c.name,
+      type: c.type || '',
+      notnull: c.nullable === 'NO' ? 1 : 0,
+      pk: c.columnKey === 'PRI' ? 1 : 0,
+    })),
+    fks,
+    indexes: _groupIndexes(indexRows),
+  };
+}
+
+module.exports = { introspect };

package/src/introspect/postgres.js

@@ -0,0 +1,113 @@
+'use strict';
+
+/**
+ * PostgreSQL introspection（驱动：pg）
+ *
+ * 只发 `information_schema` / `pg_catalog` 只读查询（铁律 6：绝不写 DDL 回库），
+ * 产出规范化行 JSON，交 core `schemaFromRows` 做纯映射。建议使用只读账号。
+ */
+
+const _TABLES = `
+  SELECT table_name AS name
+  FROM information_schema.tables
+  WHERE table_schema = $1 AND table_type = 'BASE TABLE'
+  ORDER BY table_name`;
+
+const _COLUMNS = `
+  SELECT c.table_name AS "table",
+         c.column_name AS name,
+         c.data_type   AS type,
+         c.is_nullable AS nullable,
+         CASE WHEN pk.column_name IS NULL THEN 0 ELSE 1 END AS pk
+  FROM information_schema.columns c
+  LEFT JOIN (
+    SELECT kcu.table_schema, kcu.table_name, kcu.column_name
+    FROM information_schema.table_constraints tc
+    JOIN information_schema.key_column_usage kcu
+      ON kcu.constraint_name = tc.constraint_name
+     AND kcu.table_schema = tc.table_schema
+    WHERE tc.constraint_type = 'PRIMARY KEY' AND tc.table_schema = $1
+  ) pk
+    ON pk.table_schema = c.table_schema
+   AND pk.table_name = c.table_name
+   AND pk.column_name = c.column_name
+  WHERE c.table_schema = $1
+  ORDER BY c.table_name, c.ordinal_position`;
+
+const _FKS = `
+  SELECT src.relname AS "table",
+         sa.attname  AS column,
+         ref.relname AS "refTable",
+         ra.attname  AS "refColumn"
+  FROM pg_constraint con
+  JOIN pg_class src ON src.oid = con.conrelid
+  JOIN pg_class ref ON ref.oid = con.confrelid
+  JOIN pg_namespace ns ON ns.oid = src.relnamespace
+  JOIN LATERAL unnest(con.conkey) WITH ORDINALITY AS k(attnum, ord) ON true
+  JOIN LATERAL unnest(con.confkey) WITH ORDINALITY AS f(attnum, ord) ON f.ord = k.ord
+  JOIN pg_attribute sa ON sa.attrelid = con.conrelid AND sa.attnum = k.attnum
+  JOIN pg_attribute ra ON ra.attrelid = con.confrelid AND ra.attnum = f.attnum
+  WHERE con.contype = 'f' AND ns.nspname = $1
+  ORDER BY src.relname, k.ord`;
+
+const _INDEXES = `
+  SELECT t.relname AS "table",
+         i.relname AS name,
+         CASE WHEN ix.indisunique THEN 1 ELSE 0 END AS unique,
+         a.attname AS column
+  FROM pg_index ix
+  JOIN pg_class t ON t.oid = ix.indrelid
+  JOIN pg_class i ON i.oid = ix.indexrelid
+  JOIN pg_namespace ns ON ns.oid = t.relnamespace
+  JOIN pg_attribute a ON a.attrelid = t.oid AND a.attnum = ANY(ix.indkey)
+  WHERE ns.nspname = $1 AND NOT ix.indisprimary
+  ORDER BY t.relname, i.relname`;
+
+/** 把 `{table,name,unique,column}` 行按索引名归并出 columns 数组 */
+function _groupIndexes(rows) {
+  const byKey = new Map();
+  for (const r of rows) {
+    const key = `${r.table}::${r.name}`;
+    let entry = byKey.get(key);
+    if (!entry) {
+      entry = { table: r.table, name: r.name, columns: [], unique: Number(r.unique) };
+      byKey.set(key, entry);
+    }
+    entry.columns.push(r.column);
+  }
+  return [...byKey.values()];
+}
+
+async function introspect(driver, opts = {}) {
+  if (!driver || typeof driver.query !== 'function') {
+    throw new TypeError('postgres introspection 需要 pg 的 Pool/Client 实例');
+  }
+  // 查询按 schema 过滤（缺省 public）；显式传入 schema/namespace 时作为 namespace
+  // 透出到 def（缺省不透出 = 连接默认 search_path，保持既有行为零变更）。
+  const explicit = opts.schema !== undefined || opts.namespace !== undefined;
+  const schema = opts.schema ?? opts.namespace ?? 'public';
+  const namespace = explicit ? schema : null;
+  const [tables, columns, fks, indexRows] = await Promise.all([
+    driver.query(_TABLES, [schema]),
+    driver.query(_COLUMNS, [schema]),
+    driver.query(_FKS, [schema]),
+    driver.query(_INDEXES, [schema]),
+  ]);
+
+  return {
+    tables: namespace
+      ? tables.rows.map((t) => ({ ...t, namespace }))
+      : tables.rows,
+    columns: columns.rows.map((c) => ({
+      table: c.table,
+      name: c.name,
+      type: c.type || '',
+      notnull: c.nullable === 'NO' ? 1 : 0,
+      pk: Number(c.pk) || 0,
+    })),
+    fks: fks.rows,
+    indexes: _groupIndexes(indexRows.rows),
+  };
+}
+
+module.exports = { introspect };

package/src/introspect/sqlite.js

@@ -0,0 +1,79 @@
+'use strict';
+
+/**
+ * SQLite introspection（驱动：better-sqlite3）
+ *
+ * 只发 `sqlite_master` / `PRAGMA` 只读查询（铁律 6：绝不写 DDL 回库），产出规范化
+ * 行 JSON，交 core `schemaFromRows` 做纯映射（本模块不做任何 schema 推断）。
+ *
+ * 返回：`{ tables, columns, fks, indexes }`（见 `dialect/introspect.rs` 的输入约定）。
+ */
+
+/** PRAGMA 不支持参数化，需内联表名；标识符来自 sqlite_master（非用户输入），并做引号转义 */
+function _quote(name) {
+  return `"${String(name).replace(/"/g, '""')}"`;
+}
+
+function introspect(db, { database = null } = {}) {
+  if (!db || typeof db.prepare !== 'function') {
+    throw new TypeError('sqlite introspection 需要 better-sqlite3 Database 实例');
+  }
+  const tables = [];
+  const columns = [];
+  const fks = [];
+  const indexes = [];
+
+  // attached db 过滤：PRAGMA database_list 校验库名存在（main/temp/ATTACH 的库名），
+  // 表清单改从 `<db>.sqlite_master` 读取；显式库名作为 namespace 透出到 def。
+  let masterFrom = 'sqlite_master';
+  if (database != null) {
+    const known = db.prepare('PRAGMA database_list').all().some((r) => r.name === database);
+    if (!known) {
+      const names = db.prepare('PRAGMA database_list').all().map((r) => r.name).join(', ');
+      throw new Error(`SQLite attached db 不存在: ${database}（当前 attached: ${names}）`);
+    }
+    masterFrom = `${_quote(database)}.sqlite_master`;
+  }
+
+  const tableRows = db
+    .prepare(`SELECT name FROM ${masterFrom} WHERE type = 'table' AND name NOT LIKE 'sqlite_%' ORDER BY name`)
+    .all();
+
+  for (const { name } of tableRows) {
+    tables.push(database != null ? { name, namespace: database } : { name });
+
+    for (const c of db.prepare(`PRAGMA table_info(${_quote(name)})`).all()) {
+      columns.push({
+        table: name,
+        name: c.name,
+        type: c.type || '',
+        notnull: c.notnull ? 1 : 0,
+        pk: c.pk ? 1 : 0,
+      });
+    }
+
+    for (const f of db.prepare(`PRAGMA foreign_key_list(${_quote(name)})`).all()) {
+      fks.push({
+        table: name,
+        column: f.from,
+        refTable: f.table,
+        refColumn: f.to || '_id',
+      });
+    }
+
+    for (const idx of db.prepare(`PRAGMA index_list(${_quote(name)})`).all()) {
+      if (idx.origin === 'pk') continue; // 主键索引不重复登记
+      const info = db.prepare(`PRAGMA index_info(${_quote(idx.name)})`).all();
+      indexes.push({
+        table: name,
+        name: idx.name,
+        columns: info.map((i) => i.name),
+        unique: idx.unique ? 1 : 0,
+      });
+    }
+  }
+
+  return { tables, columns, fks, indexes };
+}
+
+module.exports = { introspect };

package/src/permission.js

@@ -0,0 +1,60 @@
+'use strict';
+
+/**
+ * 权限上下文 — AsyncLocalStorage 请求上下文 + 自定义错误
+ *
+ * 角色评估、字段过滤、所有者条件注入等权限逻辑已全部下沉 Rust core；
+ * 本模块只保留 Host 侧职责：
+ *   - 请求上下文的隐式传递（core 的 ctx 一律显式入参，由本模块取出后传入）
+ *   - PermissionError（core 返回的权限类错误消息由 crud.js 映射为本错误类型）
+ */
+
+const { AsyncLocalStorage } = require('node:async_hooks');
+
+const _als = new AsyncLocalStorage();
+
+/** 设置当前请求的上下文，每次请求开始时调用一次 */
+function setContext(ctx) {
+  _als.enterWith(ctx);
+}
+
+/** 获取当前请求的上下文，无则 undefined */
+function getContext() {
+  return _als.getStore();
+}
+
+/**
+ * 以指定角色进入临时权限上下文（嵌套安全），执行 fn 后自动恢复原上下文。
+ *
+ * 供 AI 查询执行等显式角色注入场景使用，取代 setContext + finally setContext(null)
+ * 的清空式写法（后者嵌套时会误清外层上下文，且「无上下文 = 权限全放行」，清空即静默失守方向）。
+ */
+function scopedRoles(roles, fn) {
+  const next = { ...(getContext() || {}), roles };
+  return _als.run(next, () => fn());
+}
+
+/** 在内部上下文中执行操作（绕过权限检查），结束后自动恢复上下文 */
+async function runAsInternal(fn) {
+  const prev = getContext();
+  const next = { ...(prev || {}), internal: true };
+  return _als.run(next, () => fn());
+}
+
+// ─── 自定义错误 ──────────────────────────────────────────────
+
+class PermissionError extends Error {
+  constructor(message, status = 403) {
+    super(message);
+    this.name = 'PermissionError';
+    this.status = status;
+  }
+}
+
+module.exports = {
+  setContext,
+  getContext,
+  scopedRoles,
+  runAsInternal,
+  PermissionError,
+};