rust-store-node 3.1.0 → 4.0.0

package/README.md

@@ -27,6 +27,39 @@ const plan = reg.planQuery('User{name}', {}, null); // → Mongo 命令 JSON
 
 同步计算列回调经 `setFn` 注册；异步计算列（`asyncFn`）由 Host 走 `prepareQuery` / `stripQuery` 两段式执行。
 
+## 命名规范与翻译摘要
+
+归一实现唯一在 `core::naming`，经 `core-node` / `core-py` 透出，宿主不得重复实现。本语言（Node）归一匹配示例：实现 `orderTotal` ↔ 逻辑 `Order.total`。
+
+<!-- SPEC:NAMING-STYLE:BEGIN -->
+### Naming: freeform definitions, system-directed translation
+
+Definitions (`collection`, fields, referenced relation fields, computed-column keys, `fnRef` values, index names) may use any style; the engine translates them to the target style. Contract keys (`fnRef`, `localField`, `foreignField`, `asyncFn`, `type`, ...) and the schema `name` are never translated.
+
+| Target | Style | Example (`orderTotal`) |
+|---|---|---|
+| MySQL / PostgreSQL / SQLite (physical) | snake_case | `order_total` |
+| MongoDB (physical) | camelCase | `orderTotal` |
+| Node.js / Java / C# / Rust (code; computed columns follow) | camelCase | `orderTotal` |
+| Go (code; computed columns follow) | PascalCase (must be exported) | `OrderTotal` |
+| Python (code; computed columns follow) | snake_case | `order_total` |
+
+Canonicalization (single implementation `core::naming`, re-exported by the bindings; hosts must not re-implement it): split on `_`, `-`, `.`, space and at lower/digit-to-upper boundaries; a trailing uppercase in a run followed by a lowercase starts the next token (`HTTPServer` -> `[http, server]`, `userID` -> `[user, id]`); digits stay inside a token (`order2Items` -> `[order2, items]`). Reassembly: snake = `t1_t2`, camel = `t1T2`, pascal = `T1T2`.
+
+Two logical names in one schema that canonicalize equal (`orderTotal` vs `order_total`), or a name that canonicalizes onto a reserved contract key (e.g. `fnref`), is an error `ERR_NAME_CONFLICT:` and the service does not start (never silently overwritten).
+<!-- SPEC:NAMING-STYLE:END -->
+
+<!-- SPEC:FNREF:BEGIN -->
+### Computed columns: `fnRef` binding by composite name + canonical match
+
+Computed columns live at the schema top level, `computes: { <key>: { type, fn | asyncFn | agg, fnRef?, depends?, read? } }` (`fn` / `asyncFn` / `agg` are mutually exclusive).
+
+- The logical `fnRef` defaults to `<schema.name>.<computed-column key>` (generated, never hand-written); since `name` is globally unique, the `fnRef` is globally unique too.
+- Host implementations bind by canonicalization: both the implementation's name in the host language style and the schema's logical `fnRef` are canonicalized to token sequences and compared. So Node's `orderAmountLabel` and Python's `order_amount_label` bind to the same logical computed column.
+- Reusing one implementation across schemas: write an explicit shared name (e.g. `"fnRef": "common.moneyLabel"`); naming goes from required to optional.
+- Every declared `fnRef` must have an implementation, otherwise the service fails to start with `ERR_FN_MISSING`.
+<!-- SPEC:FNREF:END -->
+
 ## 本地构建（开发）
 
 产物在发布期由 `napi build --platform` 生成平台包；开发期可用 cargo 手工构建：

package/index.d.ts

@@ -9,6 +9,18 @@
  * 与 `undefined`（未传上下文，`require_context` 开启时报错）区分。
  */
 export declare function systemContext(): any
+/** 命名归一（设计 §6.2）：用户任意写法 → 全小写 token 序列。 */
+export declare function canonical(s: string): Array<string>
+/** token 序列 → snake_case */
+export declare function toSnake(tokens: Array<string>): string
+/** token 序列 → camelCase */
+export declare function toCamel(tokens: Array<string>): string
+/** token 序列 → PascalCase */
+export declare function toPascal(tokens: Array<string>): string
+/** 逻辑名 → 目标风格物理名；`target` 非法 ⇒ 抛错（禁静默回落）。 */
+export declare function translateName(logical: string, target: string): string
+/** 命名冲突检测（A7）：一组逻辑名归一后撞名 / 撞保留键 ⇒ 抛错。 */
+export declare function detectConflicts(names: Array<string>): void
 export declare class Registry {
   /** 逐条后处理文档（默认值 → 同步 fn → 递归下钻 → 权限裁剪），返回 `{doc}` */
   processNode(gql: string, doc: any, ctx?: any | undefined | null): any
@@ -41,11 +53,11 @@ export declare class Registry {
   /** 原生 SQL 语句编译：位置档透传 / 命名档 `:name` 编译 + 读写推断（C4；js 端 `rawStmtCompile`） */
   rawStmtCompile(backend: string, text: string, params: any, isWrite?: boolean | undefined | null): any
   /**
-   * 生成联邦计划：按 schema 的 `(datasource, namespace)` 与数据源 kind 把一条 GQL
+   * 生成联邦计划：按 schema 的 `(source, database, schema)` 与数据源 kind 把一条 GQL
    * 拆成「各源命令序列 + 内存 join 边」；Host 逐源执行命令后调 `mergeFederated`
    *
    * `dsConfig`：`{ "sources": { name: kind } }`（与 `init` 的数据源声明一致；
-   * `null` = 单源 Mongo）。SQL 同源跨 namespace 仍下推（qualified JOIN），
+   * `null` = 单源 Mongo）。SQL 同源跨 database/schema 仍下推（qualified JOIN），
    * Mongo 跨 db 剥离为内存 join。
    *
    * 返回 `{v, kind:"federated", root, sources, join, postprocess, degraded, maxRowsPerSource}`；
@@ -54,6 +66,15 @@ export declare class Registry {
   planFederated(gql: string, params: any, ctx?: any | undefined | null, dsConfig?: any | undefined | null): any
   /** 合并各源结果 → 嵌套文档数组；`results` 必须与 `plan.sources` **同序同长** */
   mergeFederated(plan: any, results: Array<any>): any
+  /**
+   * 目录语义纯规划：`store.config.json` + 目录扫描结果 → 定位后的装载项。
+   *
+   * `config` = `{sources, defs}`；`files` = `[{rel, defn}]`（`rel` = 相对 defs-root 的路径）。
+   * 返回 `[{defn, location:{source,database,schema}}]`（主在前、其后从；组间按 name 字典序）。
+   */
+  planLoad(config: any, files: any): any
+  /** 带定位批量注册（D13 批次唯一）；`items` = `[{defn, location}]`，`ctx` 缺省 = 无上下文。 */
+  registerBatch(items: any, ctx?: any | undefined | null): void
   canRead(model: string, ctx?: any | undefined | null): boolean
   canWrite(model: string, ctx?: any | undefined | null): boolean
   shouldInjectOwner(model: string, ctx?: any | undefined | null): boolean
@@ -176,4 +197,16 @@ export declare class Registry {
   setDenyWriteRoles(roles: Array<string>): void
   /** 未配置姿态（"open" / "closed"）；未知值抛错（fail-fast，对齐 setRbac） */
   setUnconfiguredPolicy(policy: string): void
+  /**
+   * 定义层门禁策略（`closed=true` 时仅 internal 或 `roles` 白名单可注册/覆盖）。
+   * 判决唯一在 core；默认 Open（全放行，保持既有 parity）。
+   */
+  setMetaPolicy(closed: boolean, roles: Array<string>): void
+  /**
+   * 带 ctx 的 schema 注册：定义层门禁按当前 metaPolicy 判决；`ctx` 缺省 = 无上下文。
+   * 拒绝抛 `ERR_PERMISSION:` 前缀错误（定义不变）。
+   */
+  registerWithCtx(defn: any, ctx?: any | undefined | null): void
+  /** 只读定义层判决（`workflow` 宿主面复用；判决唯一在 core）。`ctx` 缺省 = 无上下文。 */
+  canRegister(ctx?: any | undefined | null): boolean
 }

package/index.js

@@ -310,7 +310,13 @@ if (!nativeBinding) {
   throw new Error(`Failed to load native binding`)
 }
 
-const { Registry, systemContext } = nativeBinding
+const { Registry, systemContext, canonical, toSnake, toCamel, toPascal, translateName, detectConflicts } = nativeBinding
 
 module.exports.Registry = Registry
 module.exports.systemContext = systemContext
+module.exports.canonical = canonical
+module.exports.toSnake = toSnake
+module.exports.toCamel = toCamel
+module.exports.toPascal = toPascal
+module.exports.translateName = translateName
+module.exports.detectConflicts = detectConflicts

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rust-store-node",
-  "version": "3.1.0",
+  "version": "4.0.0",
   "description": "Node.js binding (napi-rs) for the rust-store multi-backend data engine: GQL parsing, permissions, computed columns and SQL dialect translation for MongoDB, MySQL, SQLite and PostgreSQL",
   "main": "index.js",
   "types": "index.d.ts",
@@ -68,10 +68,10 @@
     "sql.js": "^1.8.0"
   },
   "optionalDependencies": {
-    "rust-store-node-win32-x64-msvc": "3.1.0",
-    "rust-store-node-linux-x64-gnu": "3.1.0",
-    "rust-store-node-linux-arm64-gnu": "3.1.0",
-    "rust-store-node-darwin-x64": "3.1.0",
-    "rust-store-node-darwin-arm64": "3.1.0"
+    "rust-store-node-win32-x64-msvc": "4.0.0",
+    "rust-store-node-linux-x64-gnu": "4.0.0",
+    "rust-store-node-linux-arm64-gnu": "4.0.0",
+    "rust-store-node-darwin-x64": "4.0.0",
+    "rust-store-node-darwin-arm64": "4.0.0"
   }
 }