docs(canvas): explain import parsers, identities and integrity gates

This commit is contained in:
2026-11-12 00:31:08 +08:00
parent 68e655b52c
commit 72e84a6cc1
10 changed files with 150 additions and 0 deletions
@@ -1,10 +1,17 @@
/**
* 一个导入runner的稳定source key→新ID分配器,复用持久job.stableIds而非重开重新随机分配。
* 使用copy-on-write避免每条无新依赖的记录都复制完整映射;本模块只检查本映射内重复,项目全局身份由上层校验。
*/
import {dataRecord} from '../canvas-core/data-containers.ts';
import type {Id} from '../canvas-core/types.ts';
import {fault} from '../canvas-core/values.ts';
/** 源记录/依赖键到目标ID的只读字典,element/canvas前缀由调用者约定。 */
type Ids=Readonly<Record<string,Id>>;
/** One runner's last immutable ID index. Copies are deferred until allocation. */
/** 返回带clear方法的捕获工厂,每次为一个源记录的准备提供reserve/has/finish私有上下文。 */
export function createImportIdentities(){
let cached:{ids:Ids;used:Set<Id>}|undefined;
/** 相同已冻结纯字符串属性表可复用used索引;其它输入先复制为无原型字典。 */
const capture=(input:Ids,createId:()=>Id)=>{
let identity=cached?.ids===input?cached:undefined;
if(!identity){
@@ -13,6 +20,7 @@ export function createImportIdentities(){
}
let ids=identity.ids,used=identity.used,owned=ids!==input;
return Object.freeze({
/** 已有键返回原ID;首次遇到依赖才分配并检查本任务冲突,第一次写入时才复制映射/Set。 */
reserve(key:string){
if(typeof key!=='string'||!key)throw fault('invalid_import_key');
if(Object.hasOwn(ids,key))return ids[key];
@@ -20,9 +28,12 @@ export function createImportIdentities(){
if(!owned){ids=Object.assign(Object.create(null),ids);used=new Set(used);owned=true;}
(ids as Record<string,Id>)[key]=id;used.add(id);return id;
},
/** 判断目标ID是否已被本映射使用,不声称该ID已加入文档或已同步。 */
has:(id:Id)=>used.has(id),
/** 返回本次分配后的只读映射;没有新分配时保留输入身份便于下一记录复用索引。 */
finish:():Ids=>owned?dataRecord(ids):ids,
});
};
/** clear只丢弃临时复用索引,不清除已持久化job的stableIds。 */
return Object.freeze(Object.assign(capture,{clear(){cached=undefined;}}));
}