rust-store-node 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 rust-store contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,43 @@
+# rust-store-node
+
+`rust-store` 的 **Node 绑定（napi-rs）**：把 Rust core 的 Command 契约暴露给 JS Host。
+
+- 语言无关核心见 `../core`（GQL / 权限 / 计算列 / 命令规划 / SQL 方言翻译，纯逻辑无 IO）。
+- 绑定层只做「JSON in → JSON out」的类型转换与转发，不持有数据库驱动，不执行任何 IO。
+- Python 侧同构绑定见 `../core-py`（`rust-store-py`）。
+
+## 安装
+
+```bash
+npm i rust-store-node
+```
+
+平台原生二进制按 `optionalDependencies` 分包发布，安装后自动匹配当前平台。
+
+## 使用
+
+```js
+const { Registry } = require('rust-store-node');
+
+const reg = new Registry();
+reg.register({ name: 'User', collection: 'users', fields: { name: { type: 'string' } }, relations: {} });
+
+const plan = reg.planQuery('User{name}', {}, null); // → Mongo 命令 JSON
+```
+
+同步计算列回调经 `setFn` 注册；异步计算列（`asyncFn`）由 Host 走 `prepareQuery` / `stripQuery` 两段式执行。
+
+## 本地构建（开发）
+
+产物在发布期由 `napi build --platform` 生成平台包；开发期可用 cargo 手工构建：
+
+```powershell
+cargo build --manifest-path core-node/Cargo.toml
+Copy-Item core-node/target/debug/rust_store_node.dll core-node/dist/rust-store-node.node -Force
+```
+
+`dist/rust-store-node.node` 仅供本仓库测试与相邻 Host 调试使用，**不会**随 npm 包发布。
+
+## License
+
+[MIT](LICENSE)

package/index.d.ts

@@ -0,0 +1,128 @@
+/* tslint:disable */
+/* eslint-disable */
+
+/* auto-generated by NAPI-RS */
+
+/**
+ * 系统内部调用上下文工厂：`{ internal: true }` —— 权限引擎全放行、不注入 owner
+ * 条件。供 Host 的内部路径（索引创建、归档回填、后台任务等）显式表达「系统调用」，
+ * 与 `undefined`（未传上下文，`require_context` 开启时报错）区分。
+ */
+export declare function systemContext(): any
+export declare class Registry {
+  /** 逐条后处理文档（默认值 → 同步 fn → 递归下钻 → 权限裁剪），返回 `{doc}` */
+  processNode(gql: string, doc: any, ctx?: any | undefined | null): any
+  /** 需由 Host 异步执行的计算列 `fnRef` 列表（已按 `comp.read` 权限过滤） */
+  asyncFnRefs(model: string, ctx?: any | undefined | null): Array<string>
+  /** 收集关系依赖并注入 AST，返回 `{relDeps, ast, injectInfo}` */
+  injectDepends(gql: string): any
+  /** 剥离 asyncFn 依赖注入的字段，返回 `{items}` */
+  stripDepInjected(injectInfo: any, items: Array<any>): any
+  /** finalize 第一阶段：逐条 `process_node`，返回 `{items, fnRefs}` */
+  prepareQuery(postprocess: any, items: Array<any>, ctx?: any | undefined | null): any
+  /** finalize 第三阶段：剥离 asyncFn 依赖注入的字段，返回 `{items}` */
+  stripQuery(postprocess: any, items: Array<any>): any
+  /**
+   * 解析 schema 绑定的数据源 kind（`"mongo"` / `"mysql"` / `"postgres"` / `"sqlite"`）
+   *
+   * `config` 形状：`{ "sources": { "<name>": "<kind>" } }`；`null` → 单源 Mongo。
+   */
+  resolveDatasource(schemaName: string, config?: any | undefined | null): string
+  /** schema 声明的数据源名（未声明 → `null`，语义为 `default`） */
+  schemaDatasource(schemaName: string): string | null
+  /** 把一条 Mongo 命令 JSON 翻译为指定后端的 SQL 语句序列（见 `translate::translate`）。 */
+  dialectTranslate(backend: string, cmd: any): any
+  /** 把 `{rowShape, rows}` 还原为嵌套 Mongo 文档数组（平铺 JOIN 行 → 文档） */
+  restoreRows(shape: any, rows: any): any
+  /** 把 introspection 行 JSON → schemaJSON（`{rows}` 内含 tables/columns/fks/indexes） */
+  schemaFromRows(rows: any, backend: string): any
+  /** 合并 introspected 基础 schema 与本地 overlay（权限 / 计算列 / 覆盖） */
+  mergeSchema(base: any, overlay: any): any
+  /**
+   * 生成联邦计划：按 schema 的 `(datasource, namespace)` 与数据源 kind 把一条 GQL
+   * 拆成「各源命令序列 + 内存 join 边」；Host 逐源执行命令后调 `mergeFederated`
+   *
+   * `dsConfig`：`{ "sources": { name: kind } }`（与 `init` 的数据源声明一致；
+   * `null` = 单源 Mongo）。SQL 同源跨 namespace 仍下推（qualified JOIN），
+   * Mongo 跨 db 剥离为内存 join。
+   *
+   * 返回 `{v, kind:"federated", root, sources, join, postprocess, degraded}`；
+   * 单源（无跨源关系）时 `sources` 仅根单元、`join.edges` 为空。
+   */
+  planFederated(gql: string, params: any, ctx?: any | undefined | null, dsConfig?: any | undefined | null): any
+  /** 合并各源结果 → 嵌套文档数组；`results` 必须与 `plan.sources` **同序同长** */
+  mergeFederated(plan: any, results: Array<any>): any
+  canRead(model: string, ctx?: any | undefined | null): boolean
+  canWrite(model: string, ctx?: any | undefined | null): boolean
+  shouldInjectOwner(model: string, ctx?: any | undefined | null): boolean
+  /** 非 admin 用户只看自己数据时叠加 owner 条件；无上下文时原样返回 */
+  mergeOwnerCondition(model: string, ctx?: any | undefined | null, condition?: any | undefined | null): any
+  readableFields(model: string, ctx?: any | undefined | null): any
+  readableRelations(model: string, ctx?: any | undefined | null): any
+  writableFields(model: string, ctx?: any | undefined | null): any
+  filterWritableData(model: string, ctx: any | undefined | null, data: any): any
+  /** 解析 GQL 并构建 pipeline / projection，返回 `{tokens, ast, pipeline, projection}` */
+  buildPipeline(gql: string, params: any, ctx?: any | undefined | null): any
+  planQuery(gql: string, params: any, ctx?: any | undefined | null, routeOverride?: any | undefined | null): any
+  /** queryOne 计划：未显式 `$limit` 时强制下推 `$limit(1)`（`$pipeline` 全权模式不注入） */
+  planQueryOne(gql: string, params: any, ctx?: any | undefined | null, routeOverride?: any | undefined | null): any
+  /** 列表 + total；`total` 由 Host 执行 `countCommand` 后回喂，用于算 `hasMore` */
+  planQueryWithCount(gql: string, params: any, ctx?: any | undefined | null, total?: number | undefined | null, routeOverride?: any | undefined | null): any
+  resolvePage(gql: string, params: any): any
+  /** 两阶段查询后按阶段一 `_id` 顺序重排，返回 `{items}` */
+  restoreSortOrder(items: Array<any>, ids: Array<any>, sort?: any | undefined | null): any
+  /** 生成插入命令；`now` / `newId` 由 Host 提供（core 无时钟与随机源） */
+  planInsert(model: string, data: any, now: number, newId: string, ctx?: any | undefined | null, routeOverride?: any | undefined | null): any
+  planExists(model: string, condition: any, routeOverride?: any | undefined | null): any
+  planCount(model: string, filter?: any | undefined | null, routeOverride?: any | undefined | null): any
+  planAggregate(model: string, pipeline: Array<any>, routeOverride?: any | undefined | null): any
+  /** 批量插入命令；`newIds` 按需消费（仅无 `_id` 的文档取用） */
+  planInsertMany(model: string, docs: Array<any>, now: number, newIds: Array<string>, ctx?: any | undefined | null, routeOverride?: any | undefined | null): any
+  /**
+   * 更新一条（findOneAndUpdate + returnDocument AFTER）。
+   *
+   * creator 写权限需探针时返回 `{"needsProbe": cmd}`；Host 执行探针后携
+   * `probeFound`（true/false）与 `probeDoc` 重入即得 `{"command": cmd}`。
+   */
+  planUpdate(model: string, condition: any, data: any, options: any | undefined | null, now: number, ctx?: any | undefined | null, probeFound?: boolean | undefined | null, probeDoc?: any | undefined | null, routeOverride?: any | undefined | null): any
+  /** 批量更新（guest / 无写授权直接拒绝，不走 creator 探针） */
+  planUpdateMany(model: string, condition: any, data: any, now: number, ctx?: any | undefined | null, routeOverride?: any | undefined | null): any
+  /**
+   * 删除计划：归档表存在时返回 findCommand（Host 取源文档后调 planArchiveDocs）+
+   * deleteCommand。creator 探针语义同 planUpdate。
+   */
+  planRemove(model: string, condition: any, ctx?: any | undefined | null, probeFound?: boolean | undefined | null, probeDoc?: any | undefined | null, routeOverride?: any | undefined | null): any
+  /** 归档文档命令：源文档补 `deletedAt` 后批量写入 `<collection>_deleted` */
+  planArchiveDocs(model: string, docs: Array<any>, now: number, routeOverride?: any | undefined | null): any
+  /** 显式条件 upsert；`newId` 仅在需生成 `_id` 时被使用 */
+  planUpsert(model: string, condition: any, data: any, options: any | undefined | null, now: number, newId: string, ctx?: any | undefined | null, routeOverride?: any | undefined | null): any
+  /**
+   * mutation 规划：展开为有序步骤序列 `{steps: [{model, command}]}`，
+   * 父子依赖用 `{{step.<N>._id}}` 占位符表达，由 Host 依次执行并回填
+   */
+  planMutation(model: string, data: any, now: number, newIds: Array<string>, ctx?: any | undefined | null, routeOverride?: any | undefined | null): any
+  /**
+   * 写路径结果回喂：对 findOneAndUpdate 返回文档补默认值 / 同步计算列
+   * （对齐 JS `applyDefaultsAndComputes(result, s)`）
+   */
+  applyWriteDefaults(model: string, doc: any): any
+  sortsByRelation(sort?: any | undefined | null): boolean
+  constructor()
+  /** 注册 schema（自动派生 `<Name>Deleted` 归档表；`timestamps !== false` 时补时间戳字段） */
+  register(defn: any): void
+  has(name: string): boolean
+  list(): Array<string>
+  /** 注册同步计算列回调（schema 里 `fn: true` 的 `fnRef`，缺省为计算列名） */
+  setFn(fnRef: string, callback: (arg: any) => any): void
+  clearFns(): void
+  /** 开关用户 $pipeline 直通（默认允许；AI 查询宿主建议关闭作纵深防御） */
+  setAllowUserPipeline(allow: boolean): void
+  /**
+   * 开关「上下文强制」（默认关闭 = fail-open，保持 JS parity）。
+   * 开启后：plan 入口遇 `ctx` 缺失抛 `ERR_NO_CONTEXT`（fail-secure），
+   * 内部调用须显式传系统上下文 `systemContext()`。
+   */
+  setRequireContext(require: boolean): void
+  /** 「上下文强制」开关当前值 */
+  requireContext(): boolean
+}

package/index.js

@@ -0,0 +1,316 @@
+/* tslint:disable */
+/* eslint-disable */
+/* prettier-ignore */
+
+/* auto-generated by NAPI-RS */
+
+const { existsSync, readFileSync } = require('fs')
+const { join } = require('path')
+
+const { platform, arch } = process
+
+let nativeBinding = null
+let localFileExisted = false
+let loadError = null
+
+function isMusl() {
+  // For Node 10
+  if (!process.report || typeof process.report.getReport !== 'function') {
+    try {
+      const lddPath = require('child_process').execSync('which ldd').toString().trim()
+      return readFileSync(lddPath, 'utf8').includes('musl')
+    } catch (e) {
+      return true
+    }
+  } else {
+    const { glibcVersionRuntime } = process.report.getReport().header
+    return !glibcVersionRuntime
+  }
+}
+
+switch (platform) {
+  case 'android':
+    switch (arch) {
+      case 'arm64':
+        localFileExisted = existsSync(join(__dirname, 'rust-store-node.android-arm64.node'))
+        try {
+          if (localFileExisted) {
+            nativeBinding = require('./rust-store-node.android-arm64.node')
+          } else {
+            nativeBinding = require('rust-store-node-android-arm64')
+          }
+        } catch (e) {
+          loadError = e
+        }
+        break
+      case 'arm':
+        localFileExisted = existsSync(join(__dirname, 'rust-store-node.android-arm-eabi.node'))
+        try {
+          if (localFileExisted) {
+            nativeBinding = require('./rust-store-node.android-arm-eabi.node')
+          } else {
+            nativeBinding = require('rust-store-node-android-arm-eabi')
+          }
+        } catch (e) {
+          loadError = e
+        }
+        break
+      default:
+        throw new Error(`Unsupported architecture on Android ${arch}`)
+    }
+    break
+  case 'win32':
+    switch (arch) {
+      case 'x64':
+        localFileExisted = existsSync(
+          join(__dirname, 'rust-store-node.win32-x64-msvc.node')
+        )
+        try {
+          if (localFileExisted) {
+            nativeBinding = require('./rust-store-node.win32-x64-msvc.node')
+          } else {
+            nativeBinding = require('rust-store-node-win32-x64-msvc')
+          }
+        } catch (e) {
+          loadError = e
+        }
+        break
+      case 'ia32':
+        localFileExisted = existsSync(
+          join(__dirname, 'rust-store-node.win32-ia32-msvc.node')
+        )
+        try {
+          if (localFileExisted) {
+            nativeBinding = require('./rust-store-node.win32-ia32-msvc.node')
+          } else {
+            nativeBinding = require('rust-store-node-win32-ia32-msvc')
+          }
+        } catch (e) {
+          loadError = e
+        }
+        break
+      case 'arm64':
+        localFileExisted = existsSync(
+          join(__dirname, 'rust-store-node.win32-arm64-msvc.node')
+        )
+        try {
+          if (localFileExisted) {
+            nativeBinding = require('./rust-store-node.win32-arm64-msvc.node')
+          } else {
+            nativeBinding = require('rust-store-node-win32-arm64-msvc')
+          }
+        } catch (e) {
+          loadError = e
+        }
+        break
+      default:
+        throw new Error(`Unsupported architecture on Windows: ${arch}`)
+    }
+    break
+  case 'darwin':
+    localFileExisted = existsSync(join(__dirname, 'rust-store-node.darwin-universal.node'))
+    try {
+      if (localFileExisted) {
+        nativeBinding = require('./rust-store-node.darwin-universal.node')
+      } else {
+        nativeBinding = require('rust-store-node-darwin-universal')
+      }
+      break
+    } catch {}
+    switch (arch) {
+      case 'x64':
+        localFileExisted = existsSync(join(__dirname, 'rust-store-node.darwin-x64.node'))
+        try {
+          if (localFileExisted) {
+            nativeBinding = require('./rust-store-node.darwin-x64.node')
+          } else {
+            nativeBinding = require('rust-store-node-darwin-x64')
+          }
+        } catch (e) {
+          loadError = e
+        }
+        break
+      case 'arm64':
+        localFileExisted = existsSync(
+          join(__dirname, 'rust-store-node.darwin-arm64.node')
+        )
+        try {
+          if (localFileExisted) {
+            nativeBinding = require('./rust-store-node.darwin-arm64.node')
+          } else {
+            nativeBinding = require('rust-store-node-darwin-arm64')
+          }
+        } catch (e) {
+          loadError = e
+        }
+        break
+      default:
+        throw new Error(`Unsupported architecture on macOS: ${arch}`)
+    }
+    break
+  case 'freebsd':
+    if (arch !== 'x64') {
+      throw new Error(`Unsupported architecture on FreeBSD: ${arch}`)
+    }
+    localFileExisted = existsSync(join(__dirname, 'rust-store-node.freebsd-x64.node'))
+    try {
+      if (localFileExisted) {
+        nativeBinding = require('./rust-store-node.freebsd-x64.node')
+      } else {
+        nativeBinding = require('rust-store-node-freebsd-x64')
+      }
+    } catch (e) {
+      loadError = e
+    }
+    break
+  case 'linux':
+    switch (arch) {
+      case 'x64':
+        if (isMusl()) {
+          localFileExisted = existsSync(
+            join(__dirname, 'rust-store-node.linux-x64-musl.node')
+          )
+          try {
+            if (localFileExisted) {
+              nativeBinding = require('./rust-store-node.linux-x64-musl.node')
+            } else {
+              nativeBinding = require('rust-store-node-linux-x64-musl')
+            }
+          } catch (e) {
+            loadError = e
+          }
+        } else {
+          localFileExisted = existsSync(
+            join(__dirname, 'rust-store-node.linux-x64-gnu.node')
+          )
+          try {
+            if (localFileExisted) {
+              nativeBinding = require('./rust-store-node.linux-x64-gnu.node')
+            } else {
+              nativeBinding = require('rust-store-node-linux-x64-gnu')
+            }
+          } catch (e) {
+            loadError = e
+          }
+        }
+        break
+      case 'arm64':
+        if (isMusl()) {
+          localFileExisted = existsSync(
+            join(__dirname, 'rust-store-node.linux-arm64-musl.node')
+          )
+          try {
+            if (localFileExisted) {
+              nativeBinding = require('./rust-store-node.linux-arm64-musl.node')
+            } else {
+              nativeBinding = require('rust-store-node-linux-arm64-musl')
+            }
+          } catch (e) {
+            loadError = e
+          }
+        } else {
+          localFileExisted = existsSync(
+            join(__dirname, 'rust-store-node.linux-arm64-gnu.node')
+          )
+          try {
+            if (localFileExisted) {
+              nativeBinding = require('./rust-store-node.linux-arm64-gnu.node')
+            } else {
+              nativeBinding = require('rust-store-node-linux-arm64-gnu')
+            }
+          } catch (e) {
+            loadError = e
+          }
+        }
+        break
+      case 'arm':
+        if (isMusl()) {
+          localFileExisted = existsSync(
+            join(__dirname, 'rust-store-node.linux-arm-musleabihf.node')
+          )
+          try {
+            if (localFileExisted) {
+              nativeBinding = require('./rust-store-node.linux-arm-musleabihf.node')
+            } else {
+              nativeBinding = require('rust-store-node-linux-arm-musleabihf')
+            }
+          } catch (e) {
+            loadError = e
+          }
+        } else {
+          localFileExisted = existsSync(
+            join(__dirname, 'rust-store-node.linux-arm-gnueabihf.node')
+          )
+          try {
+            if (localFileExisted) {
+              nativeBinding = require('./rust-store-node.linux-arm-gnueabihf.node')
+            } else {
+              nativeBinding = require('rust-store-node-linux-arm-gnueabihf')
+            }
+          } catch (e) {
+            loadError = e
+          }
+        }
+        break
+      case 'riscv64':
+        if (isMusl()) {
+          localFileExisted = existsSync(
+            join(__dirname, 'rust-store-node.linux-riscv64-musl.node')
+          )
+          try {
+            if (localFileExisted) {
+              nativeBinding = require('./rust-store-node.linux-riscv64-musl.node')
+            } else {
+              nativeBinding = require('rust-store-node-linux-riscv64-musl')
+            }
+          } catch (e) {
+            loadError = e
+          }
+        } else {
+          localFileExisted = existsSync(
+            join(__dirname, 'rust-store-node.linux-riscv64-gnu.node')
+          )
+          try {
+            if (localFileExisted) {
+              nativeBinding = require('./rust-store-node.linux-riscv64-gnu.node')
+            } else {
+              nativeBinding = require('rust-store-node-linux-riscv64-gnu')
+            }
+          } catch (e) {
+            loadError = e
+          }
+        }
+        break
+      case 's390x':
+        localFileExisted = existsSync(
+          join(__dirname, 'rust-store-node.linux-s390x-gnu.node')
+        )
+        try {
+          if (localFileExisted) {
+            nativeBinding = require('./rust-store-node.linux-s390x-gnu.node')
+          } else {
+            nativeBinding = require('rust-store-node-linux-s390x-gnu')
+          }
+        } catch (e) {
+          loadError = e
+        }
+        break
+      default:
+        throw new Error(`Unsupported architecture on Linux: ${arch}`)
+    }
+    break
+  default:
+    throw new Error(`Unsupported OS: ${platform}, architecture: ${arch}`)
+}
+
+if (!nativeBinding) {
+  if (loadError) {
+    throw loadError
+  }
+  throw new Error(`Failed to load native binding`)
+}
+
+const { Registry, systemContext } = nativeBinding
+
+module.exports.Registry = Registry
+module.exports.systemContext = systemContext

package/package.json

@@ -0,0 +1,65 @@
+{
+  "name": "rust-store-node",
+  "version": "1.0.0",
+  "description": "rust-store 的 Node 绑定（napi-rs）：把 core 的 Command 契约暴露给 JS Host",
+  "main": "index.js",
+  "types": "index.d.ts",
+  "files": [
+    "index.js",
+    "index.d.ts",
+    "*.node",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "napi": {
+    "name": "rust-store-node",
+    "triples": {
+      "defaults": false,
+      "additional": [
+        "x86_64-pc-windows-msvc",
+        "x86_64-unknown-linux-gnu",
+        "aarch64-unknown-linux-gnu",
+        "x86_64-apple-darwin",
+        "aarch64-apple-darwin"
+      ]
+    }
+  },
+  "scripts": {
+    "build": "napi build --platform --release",
+    "build:debug": "napi build --platform",
+    "artifacts": "napi artifacts",
+    "prepublishOnly": "napi prepublish -t npm --skip-gh-release",
+    "test": "node --test \"test/**/*.test.js\""
+  },
+  "keywords": [
+    "rust-store",
+    "napi-rs",
+    "binding",
+    "gql",
+    "data-layer"
+  ],
+  "author": "leo <coen_ddt@qq.com>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/coenddt/rust-store.git"
+  },
+  "bugs": {
+    "url": "https://github.com/coenddt/rust-store/issues"
+  },
+  "homepage": "https://github.com/coenddt/rust-store#readme",
+  "devDependencies": {
+    "@napi-rs/cli": "^2.18.4",
+    "sql.js": "^1.8.0"
+  },
+  "optionalDependencies": {
+    "rust-store-node-win32-x64-msvc": "1.0.0",
+    "rust-store-node-linux-x64-gnu": "1.0.0",
+    "rust-store-node-linux-arm64-gnu": "1.0.0",
+    "rust-store-node-darwin-x64": "1.0.0",
+    "rust-store-node-darwin-arm64": "1.0.0"
+  }
+}