docs(canvas): explain import parsers, identities and integrity gates
This commit is contained in:
@@ -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;}}));
|
||||
}
|
||||
|
||||
Reference in New Issue
Block a user