@calcit/procs 0.11.5 → 0.11.6

package/editing-history/2026-0223-0834-migrate-to-defstruct.md

@@ -0,0 +1,91 @@
+# 2026-0223-0834 — 迁移到 defstruct 方案并实现 `%{}?` 可选字段 Record 宏
+
+## 背景
+
+将 Calcit Record 系统从旧的 `new-record`/`defrecord`/`defrecord!` 方案全面迁移到基于 `defstruct` 的新方案，同时新增 `%{}?` / `&%{}?` 支持可选字段初始化与更新。
+
+---
+
+## 知识点一：`%{}?` 与 `&%{}?` 的语义设计
+
+`struct` 初始化为 record 时，部分字段在语义上是可选的，对应 TypeScript 中的 `{ a?: number; b?: number }`。原有的 `%{}` / `&%{}` 要求所有字段都必须显式传入。
+
+### `%{}?`（macro）
+
+- 初始化 record 时允许省略字段，省略的字段自动填 `nil`。
+- 用法：`%{}? MyRecord (:x 1)`
+
+### `&%{}?`（proc）
+
+`call_record_partial` 的语义：
+
+- **proto 是 Struct**：以全 `nil` 为基础 `values`，用传入的 k-v 覆盖对应位置。
+- 传入未知字段 → 报错；传入重复字段 → 报错；`(args_size - 1) % 2 != 0` → 报错。
+
+关键实现细节：`CalcitStruct.fields` 元素类型是 `EdnTag`，比较时用 `f.ref_str()` 而非 `f.as_ref()`（后者无 `AsRef` impl）。
+
+### `%{}?` 宏定义
+
+```cirru
+defmacro %{}? (R & xs)
+  if
+    not $ and (list? xs) (every? xs list?)
+    raise $ str-spaced "|%{}? expects field entries in list, got:" xs
+  &let
+    args $ &list:concat & xs
+    quasiquote $ &%{}? ~R ~@args
+```
+
+---
+
+## 知识点二：Rust proc 注册流程
+
+新增一个内置 proc 需要同时修改四处：
+
+| 文件                       | 修改内容                                                 |
+| -------------------------- | -------------------------------------------------------- |
+| `src/calcit/proc_name.rs`  | 添加枚举变体 `NativeRecordPartial` + `ProcTypeSignature` |
+| `src/builtins/records.rs`  | 实现 `call_record_partial` 函数                          |
+| `src/builtins.rs`          | 在 `match proc` 中添加分发分支                           |
+| `src/runner/preprocess.rs` | 将新 proc 加入"跳过 arity 检查"的 `matches!` 列表        |
+
+---
+
+## 知识点三：`%{}` 严格要求 Struct proto
+
+- `call_record`（`%{}`）：若 proto 为 `Calcit::Record`，直接返回错误提示改用 `defstruct`。
+- `defstruct` 产生 `Calcit::Struct`（含 `field_types`），并作为 `%{}` / `%{}?` 的唯一原型来源。
+
+### `&record:get-name` / `&record:struct` 的参数约束
+
+- 两者统一要求传入 `record`，避免 `struct` / `record` 混用语义。
+
+### `&record:matches?` 的参数约束
+
+- 第一参数要求 `record`。
+- 第二参数接受 `record` 或 `struct`（用于 `record-match` 的模式匹配场景）。
+
+---
+
+## 修改文件
+
+| 文件                          | 变更内容                                                                                                      |
+| ----------------------------- | ------------------------------------------------------------------------------------------------------------- |
+| `src/calcit/proc_name.rs`     | 新增 `NativeRecordPartial` 枚举变体与类型签名；移除 `NewRecord` 变体                                          |
+| `src/builtins/records.rs`     | 新增 `call_record_partial`（struct-only）；`matches` 调整为 `(record, record/struct)`；移除 `new_record` 函数 |
+| `src/builtins.rs`             | 分发 `NativeRecordPartial`；移除 `NewRecord` 分发                                                             |
+| `src/runner/preprocess.rs`    | arity 检查豁免新增 `NativeRecordPartial`                                                                      |
+| `src/cirru/calcit-core.cirru` | 新增 `%{}?` 宏定义与 `&%{}?` 文档条目；`defrecord`/`defrecord!` 改为 raise error；删除 `new-record` 定义      |
+| `calcit/test-record.cirru`    | Cat/BirdShape/Person/City/A/B/C/Demo 全部改为 `defstruct`；删除所有 `new-record` let 绑定；修复各测试函数体   |
+| `docs/CalcitAgent.md`         | 类型标注示例中 `new-record` 改为 `defstruct`                                                                  |
+
+---
+
+## 验证
+
+```bash
+cargo run --bin cr -- calcit/test-record.cirru -1
+cargo clippy -- -D warnings
+```
+
+全部通过，无 warning。

package/lib/js-record.mjs

@@ -169,6 +169,34 @@ export let _$n__PCT__$M_ = (proto, ...xs) => {
         return new CalcitRecord(recordProto.name, recordProto.fields, values, recordProto.structRef);
     }
 };
+export let _$n__PCT__$M__$q_ = (proto, ...xs) => {
+    let recordProto;
+    let values;
+    if (proto instanceof CalcitStruct) {
+        recordProto = new CalcitRecord(proto.name, proto.fields, new Array(proto.fields.length).fill(null), proto);
+        values = recordProto.values.slice();
+    }
+    else {
+        throw new Error("Expected prototype to be a struct");
+    }
+    if (xs.length % 2 !== 0) {
+        throw new Error("Expected even number of key/value");
+    }
+    let touched = new Set();
+    for (let i = 0; i < xs.length; i += 2) {
+        let k = castTag(xs[i]);
+        let idx = findInFields(recordProto.fields, k);
+        if (idx < 0) {
+            throw new Error(`Cannot find field ${k} among ${recordProto.fields}`);
+        }
+        if (touched.has(idx)) {
+            throw new Error(`record field already has value, probably duplicated key: ${k}`);
+        }
+        touched.add(idx);
+        values[idx] = xs[i + 1];
+    }
+    return new CalcitRecord(recordProto.name, recordProto.fields, values, recordProto.structRef);
+};
 /// update record with new values
 export let _$n_record_$o_with = (proto, ...xs) => {
     if (proto instanceof CalcitRecord) {
@@ -208,23 +236,28 @@ export let _$n_record_$o_struct = (x) => {
     }
 };
 export let _$n_record_$o_from_map = (proto, data) => {
-    if (!(proto instanceof CalcitRecord))
-        throw new Error("Expected prototype to be record");
+    let recordProto;
+    if (proto instanceof CalcitStruct) {
+        recordProto = new CalcitRecord(proto.name, proto.fields, new Array(proto.fields.length).fill(null), proto);
+    }
+    else {
+        throw new Error("Expected prototype to be struct");
+    }
     if (data instanceof CalcitRecord) {
-        if (fieldsEqual(proto.fields, data.fields)) {
-            return new CalcitRecord(proto.name, proto.fields, data.values);
+        if (fieldsEqual(recordProto.fields, data.fields)) {
+            return new CalcitRecord(recordProto.name, recordProto.fields, data.values, recordProto.structRef);
         }
         else {
             let values = [];
-            for (let i = 0; i < proto.fields.length; i++) {
-                let field = proto.fields[i];
+            for (let i = 0; i < recordProto.fields.length; i++) {
+                let field = recordProto.fields[i];
                 let idx = findInFields(data.fields, field);
                 if (idx < 0) {
                     throw new Error(`Cannot find field ${field} among ${data.fields}`);
                 }
                 values.push(data.values[idx]);
             }
-            return new CalcitRecord(proto.name, proto.fields, values);
+            return new CalcitRecord(recordProto.name, recordProto.fields, values, recordProto.structRef);
         }
     }
     else if (data instanceof CalcitMap || data instanceof CalcitSliceMap) {
@@ -238,8 +271,8 @@ export let _$n_record_$o_from_map = (proto, data) => {
         // mutable sort
         pairs_buffer.sort((pair1, pair2) => pair1[0].cmp(pair2[0]));
         let values = [];
-        outerLoop: for (let i = 0; i < proto.fields.length; i++) {
-            let field = proto.fields[i];
+        outerLoop: for (let i = 0; i < recordProto.fields.length; i++) {
+            let field = recordProto.fields[i];
             for (let idx = 0; idx < pairs_buffer.length; idx++) {
                 let pair = pairs_buffer[idx];
                 if (pair[0] === field) {
@@ -249,7 +282,7 @@ export let _$n_record_$o_from_map = (proto, data) => {
             }
             throw new Error(`Cannot find field ${field} among ${pairs_buffer}`);
         }
-        return new CalcitRecord(proto.name, proto.fields, values);
+        return new CalcitRecord(recordProto.name, recordProto.fields, values, recordProto.structRef);
     }
     else {
         throw new Error("Expected record or data for making a record");
@@ -268,16 +301,25 @@ export let _$n_record_$o_to_map = (x) => {
     }
 };
 export let _$n_record_$o_matches_$q_ = (x, y) => {
-    if (!(x instanceof CalcitRecord)) {
-        throw new Error("Expected first argument to be record");
+    let targetStruct;
+    if (y instanceof CalcitRecord) {
+        targetStruct = y.structRef;
     }
-    if (!(y instanceof CalcitRecord)) {
-        throw new Error("Expected second argument to be record");
+    else if (y instanceof CalcitStruct) {
+        targetStruct = y;
     }
-    if (x.name !== y.name) {
-        return false;
+    else {
+        throw new Error("Expected second argument to be record or struct");
+    }
+    if (x instanceof CalcitRecord) {
+        if (x.name !== targetStruct.name) {
+            return false;
+        }
+        return fieldsEqual(x.fields, targetStruct.fields);
+    }
+    else {
+        throw new Error("Expected first argument to be record");
     }
-    return fieldsEqual(x.fields, y.fields);
 };
 export function _$n_record_$o_extend_as(obj, new_name, new_key, new_value) {
     if (arguments.length !== 4)

package/lib/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@calcit/procs",
-    "version": "0.11.5",
+    "version": "0.11.6",
     "main": "./lib/calcit.procs.mjs",
     "devDependencies": {
         "@types/node": "^25.0.9",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@calcit/procs",
-  "version": "0.11.5",
+  "version": "0.11.6",
   "main": "./lib/calcit.procs.mjs",
   "devDependencies": {
     "@types/node": "^25.0.9",

package/ts-src/js-record.mts

@@ -176,6 +176,37 @@ export let _$n__PCT__$M_ = (proto: CalcitValue, ...xs: Array<CalcitValue>): Calc
   }
 };
 
+export let _$n__PCT__$M__$q_ = (proto: CalcitValue, ...xs: Array<CalcitValue>): CalcitValue => {
+  let recordProto: CalcitRecord;
+  let values: Array<CalcitValue>;
+  if (proto instanceof CalcitStruct) {
+    recordProto = new CalcitRecord(proto.name, proto.fields, new Array(proto.fields.length).fill(null), proto);
+    values = recordProto.values.slice();
+  } else {
+    throw new Error("Expected prototype to be a struct");
+  }
+
+  if (xs.length % 2 !== 0) {
+    throw new Error("Expected even number of key/value");
+  }
+
+  let touched = new Set<number>();
+  for (let i = 0; i < xs.length; i += 2) {
+    let k = castTag(xs[i]);
+    let idx = findInFields(recordProto.fields, k);
+    if (idx < 0) {
+      throw new Error(`Cannot find field ${k} among ${recordProto.fields}`);
+    }
+    if (touched.has(idx)) {
+      throw new Error(`record field already has value, probably duplicated key: ${k}`);
+    }
+    touched.add(idx);
+    values[idx] = xs[i + 1];
+  }
+
+  return new CalcitRecord(recordProto.name, recordProto.fields, values, recordProto.structRef);
+};
+
 /// update record with new values
 export let _$n_record_$o_with = (proto: CalcitValue, ...xs: Array<CalcitValue>): CalcitValue => {
   if (proto instanceof CalcitRecord) {
@@ -198,7 +229,7 @@ export let _$n_record_$o_with = (proto: CalcitValue, ...xs: Array<CalcitValue>):
   }
 };
 
-export let _$n_record_$o_get_name = (x: CalcitRecord): CalcitTag => {
+export let _$n_record_$o_get_name = (x: CalcitValue): CalcitTag => {
   if (x instanceof CalcitRecord) {
     return x.name;
   } else {
@@ -206,7 +237,7 @@ export let _$n_record_$o_get_name = (x: CalcitRecord): CalcitTag => {
   }
 };
 
-export let _$n_record_$o_struct = (x: CalcitRecord): CalcitValue => {
+export let _$n_record_$o_struct = (x: CalcitValue): CalcitValue => {
   if (x instanceof CalcitRecord) {
     return x.structRef ?? null;
   } else {
@@ -215,22 +246,27 @@ export let _$n_record_$o_struct = (x: CalcitRecord): CalcitValue => {
 };
 
 export let _$n_record_$o_from_map = (proto: CalcitValue, data: CalcitValue): CalcitValue => {
-  if (!(proto instanceof CalcitRecord)) throw new Error("Expected prototype to be record");
+  let recordProto: CalcitRecord;
+  if (proto instanceof CalcitStruct) {
+    recordProto = new CalcitRecord(proto.name, proto.fields, new Array(proto.fields.length).fill(null), proto);
+  } else {
+    throw new Error("Expected prototype to be struct");
+  }
 
   if (data instanceof CalcitRecord) {
-    if (fieldsEqual(proto.fields, data.fields)) {
-      return new CalcitRecord(proto.name, proto.fields, data.values);
+    if (fieldsEqual(recordProto.fields, data.fields)) {
+      return new CalcitRecord(recordProto.name, recordProto.fields, data.values, recordProto.structRef);
     } else {
       let values: Array<CalcitValue> = [];
-      for (let i = 0; i < proto.fields.length; i++) {
-        let field = proto.fields[i];
+      for (let i = 0; i < recordProto.fields.length; i++) {
+        let field = recordProto.fields[i];
         let idx = findInFields(data.fields, field);
         if (idx < 0) {
           throw new Error(`Cannot find field ${field} among ${data.fields}`);
         }
         values.push(data.values[idx]);
       }
-      return new CalcitRecord(proto.name, proto.fields, values);
+      return new CalcitRecord(recordProto.name, recordProto.fields, values, recordProto.structRef);
     }
   } else if (data instanceof CalcitMap || data instanceof CalcitSliceMap) {
     let pairs_buffer: Array<[CalcitTag, CalcitValue]> = [];
@@ -244,8 +280,8 @@ export let _$n_record_$o_from_map = (proto: CalcitValue, data: CalcitValue): Cal
     pairs_buffer.sort((pair1, pair2) => pair1[0].cmp(pair2[0]));
 
     let values: Array<CalcitValue> = [];
-    outerLoop: for (let i = 0; i < proto.fields.length; i++) {
-      let field = proto.fields[i];
+    outerLoop: for (let i = 0; i < recordProto.fields.length; i++) {
+      let field = recordProto.fields[i];
       for (let idx = 0; idx < pairs_buffer.length; idx++) {
         let pair = pairs_buffer[idx];
         if (pair[0] === field) {
@@ -255,7 +291,7 @@ export let _$n_record_$o_from_map = (proto: CalcitValue, data: CalcitValue): Cal
       }
       throw new Error(`Cannot find field ${field} among ${pairs_buffer}`);
     }
-    return new CalcitRecord(proto.name, proto.fields, values);
+    return new CalcitRecord(recordProto.name, recordProto.fields, values, recordProto.structRef);
   } else {
     throw new Error("Expected record or data for making a record");
   }
@@ -274,17 +310,23 @@ export let _$n_record_$o_to_map = (x: CalcitValue): CalcitValue => {
 };
 
 export let _$n_record_$o_matches_$q_ = (x: CalcitValue, y: CalcitValue): boolean => {
-  if (!(x instanceof CalcitRecord)) {
-    throw new Error("Expected first argument to be record");
-  }
-  if (!(y instanceof CalcitRecord)) {
-    throw new Error("Expected second argument to be record");
+  let targetStruct: CalcitStruct;
+  if (y instanceof CalcitRecord) {
+    targetStruct = y.structRef;
+  } else if (y instanceof CalcitStruct) {
+    targetStruct = y;
+  } else {
+    throw new Error("Expected second argument to be record or struct");
   }
 
-  if (x.name !== y.name) {
-    return false;
+  if (x instanceof CalcitRecord) {
+    if (x.name !== targetStruct.name) {
+      return false;
+    }
+    return fieldsEqual(x.fields, targetStruct.fields);
+  } else {
+    throw new Error("Expected first argument to be record");
   }
-  return fieldsEqual(x.fields, y.fields);
 };
 
 export function _$n_record_$o_extend_as(obj: CalcitValue, new_name: CalcitValue, new_key: CalcitValue, new_value: CalcitValue) {