docs(canvas): explain document changes and history lifecycle in Chinese
This commit is contained in:
@@ -1,12 +1,21 @@
|
||||
/**
|
||||
* 内核共享的值操作:错误归一化、JSON 值复制/比较,以及运行时只读集合。
|
||||
* 这些工具不读取网络或编辑器状态。注意类型上的 readonly 与运行时不可修改不是一回事;
|
||||
* readMap/readSet 通过隐藏可变容器实现后者,freeze 不会使 Map 的 set 方法失效。
|
||||
*/
|
||||
import type { Id, Json, ReadonlyValueSet } from './types.ts';
|
||||
|
||||
/** 构造携带稳定错误码和相关对象 ID 的错误,供命令层返回可解释的拒绝结果。 */
|
||||
export function fault(code: string, targets: readonly Id[] = []): Error & { code: string; targets: readonly Id[] } {
|
||||
return Object.assign(new Error(code), { code, targets });
|
||||
}
|
||||
/** 将捕获的异常归一化为只读 rejected 结果;无领域错误码时使用 invalid_command。 */
|
||||
export function reject(error: unknown) {
|
||||
const value = error as { code?: string; targets?: readonly string[] };
|
||||
return Object.freeze({ status: 'rejected' as const, code: value?.code || 'invalid_command', targets: value?.targets || [] });
|
||||
}
|
||||
/** 递归冻结普通对象/数组的可枚举值;已冻结对象直接返回,不继续检查其子树。
|
||||
* 调用者负责提供适合此工具的数据,不能用它证明任意外部对象已经深度不可变。 */
|
||||
export function freeze<T>(value: T): T {
|
||||
if (value && typeof value === 'object' && !Object.isFrozen(value)) {
|
||||
for (const child of Object.values(value)) freeze(child);
|
||||
@@ -14,30 +23,40 @@ export function freeze<T>(value: T): T {
|
||||
}
|
||||
return value;
|
||||
}
|
||||
/** JSON 往返复制已验证的数据,切断共享引用;undefined 原样返回。
|
||||
* 此处不是校验器:JSON 会丢弃某些非法字段,因此外部输入必须在复制前验证。 */
|
||||
export function clone<T>(value: T): T {
|
||||
if (value === undefined) return value;
|
||||
return JSON.parse(JSON.stringify(value)) as T;
|
||||
}
|
||||
/** 按可枚举自有键递归比较 JSON 风格的值;数组与对象不能互相视为相等。
|
||||
* 不处理任意循环对象,也不把 Map/Set 等实例当成业务值来比较。 */
|
||||
export function equal(a: unknown, b: unknown): boolean {
|
||||
if (Object.is(a, b)) return true;
|
||||
if (!a || !b || typeof a !== 'object' || typeof b !== 'object' || Array.isArray(a) !== Array.isArray(b)) return false;
|
||||
const left = Object.keys(a), right = Object.keys(b);
|
||||
return left.length === right.length && left.every(key => Object.prototype.hasOwnProperty.call(b, key) && equal((a as Record<string, unknown>)[key], (b as Record<string, unknown>)[key]));
|
||||
}
|
||||
// 只在本模块中标记只读视图的来源,WeakSet 不会阻止无引用的视图被回收。
|
||||
const ownedMapViews=new WeakSet<object>();
|
||||
/** Internal provenance only; table ownership does not imply immutable values. */
|
||||
/** 查询“是否由 readMap 创建”,不证明表内每个 value 已冻结或通过 schema。 */
|
||||
export function isOwnedMapView(value:object){return ownedMapViews.has(value);}
|
||||
/** A capability-safe read view: unlike TS ReadonlyMap, no .set is exposed at runtime. */
|
||||
/** 复制表成员并仅暴露读取能力,外部既拿不到原 Map,也拿不到 set/delete。
|
||||
* value 保留原引用,深度不可变性由生产这些 value 的模块负责。 */
|
||||
export function readMap<K, V>(input: ReadonlyMap<K, V>): ReadonlyMap<K, V> {
|
||||
const map = new Map(input);
|
||||
const view: ReadonlyMap<K, V> = {
|
||||
get size() { return map.size; }, get: key => map.get(key), has: key => map.has(key),
|
||||
entries: () => map.entries(), keys: () => map.keys(), values: () => map.values(),
|
||||
[Symbol.iterator]: () => map[Symbol.iterator](),
|
||||
// 回调的第三个参数也必须是安全视图,不能把内部可变 Map 泄漏出去。
|
||||
forEach: (callback, thisArg) => map.forEach((value, key) => callback.call(thisArg, value, key, view)),
|
||||
};
|
||||
const result=Object.freeze(view);ownedMapViews.add(result);return result;
|
||||
}
|
||||
/** 捕获一份成员集合并隐藏 add/delete;回调同样只接触只读视图。 */
|
||||
export function readSet<T>(input: Iterable<T>): ReadonlyValueSet<T> {
|
||||
const set = new Set(input);
|
||||
const view: ReadonlyValueSet<T> = {
|
||||
@@ -46,6 +65,8 @@ export function readSet<T>(input: Iterable<T>): ReadonlyValueSet<T> {
|
||||
};
|
||||
return Object.freeze(view);
|
||||
}
|
||||
/** 递归检查 JSON 值域:排除 undefined/函数/非有限数,最多允许 64 层。
|
||||
* 这里只检查值形状,不验证组件 schema,也不是所有原型/属性描述符的严格捕获器。 */
|
||||
export function validJson(value: unknown, depth = 0): value is Json {
|
||||
if (depth > 64) return false;
|
||||
if (value === null || typeof value === 'string' || typeof value === 'boolean') return true;
|
||||
|
||||
Reference in New Issue
Block a user