@cicctencent/json-orm 0.1.1

package/dist/esm/json-backend-fs.js

@@ -0,0 +1,241 @@
+/**
+ * 默认存储后端：本地 JSON 文件（fs/promises）
+ *
+ * 语义等同改造前的本地落盘：`<根>/<表>/<主键>.json`，tmp+rename 原子写；
+ * 序列器与锁文件位于 `<根>/_meta/<表>.json`（迁出表目录，避免序列器写入
+ * 刷表目录 mtime，多进程下触发对等进程整表重载的失效风暴）；
+ * 跨进程互斥经 `.lock` 文件（`O_EXCL` 原子创建 + 退避重试 + 孤儿锁回收）。
+ * 无第三方依赖，跨平台。
+ */
+import * as fsp from 'fs/promises';
+import * as path from 'path';
+const META_SUFFIX = '/_meta.json';
+/**
+ * 元信息路径判定（与平台分隔符无关）：`<表>/_meta.json` → 表名，否则 null。
+ * Windows 下 `path.join(表, '_meta.json')` 产出 `表\_meta.json`，仅按 POSIX 分隔符
+ * 判断会把序列器写回表目录，使「迁出表目录」的设计失效。
+ */
+function metaTableOf(relPath) {
+    const norm = relPath.replace(/\\/g, '/');
+    if (!norm.endsWith(META_SUFFIX))
+        return null;
+    const table = norm.slice(0, -META_SUFFIX.length);
+    return table && !table.includes('/') ? table : null;
+}
+export class FsStorageBackend {
+    rootDir;
+    lockTimeoutMs;
+    lockStaleMs;
+    constructor(rootDir, options) {
+        this.rootDir = rootDir;
+        this.lockTimeoutMs = options?.lockTimeoutMs ?? 5000;
+        this.lockStaleMs = options?.lockStaleMs ?? 30000;
+    }
+    resolve(relPath) {
+        // 序列器/元信息迁出表目录：`<表>/_meta.json` → `<根>/_meta/<表>.json`
+        const table = metaTableOf(relPath);
+        if (table)
+            return path.join(this.rootDir, '_meta', `${table}.json`);
+        return path.join(this.rootDir, relPath);
+    }
+    async readFile(relPath) {
+        try {
+            return await fsp.readFile(this.resolve(relPath), 'utf8');
+        }
+        catch (err) {
+            if (err?.code === 'ENOENT')
+                return null;
+            throw err;
+        }
+    }
+    async writeFileAtomic(relPath, data) {
+        const file = this.resolve(relPath);
+        await fsp.mkdir(path.dirname(file), { recursive: true });
+        // 临时文件名含 pid + 随机量：并发写同一目标时各写独立 tmp，
+        // 避免内容交错、以及他人已 rename 走 tmp 后本进程 rename 抛 ENOENT
+        const tmp = `${file}.${process.pid}.${Math.random().toString(36).slice(2)}.tmp`;
+        try {
+            await fsp.writeFile(tmp, data, 'utf8');
+            await fsp.rename(tmp, file);
+        }
+        catch (err) {
+            try {
+                await fsp.rm(tmp, { force: true });
+            }
+            catch {
+                /* 清理自身临时文件失败不影响原始错误 */
+            }
+            throw err;
+        }
+        if (metaTableOf(relPath) !== null) {
+            // 旧布局迁移：尽力清理 `<表>/_meta.json`；读路径不读旧位置，
+            // 序列连续性由集合层水位下限保证（清理失败无害，旧文件不再被读取）
+            try {
+                await fsp.rm(path.join(this.rootDir, relPath), { force: true });
+            }
+            catch {
+                /* ignore */
+            }
+        }
+    }
+    async readDir(relPath) {
+        try {
+            return await fsp.readdir(this.resolve(relPath));
+        }
+        catch (err) {
+            if (err?.code === 'ENOENT')
+                return [];
+            throw err;
+        }
+    }
+    async deleteFile(relPath) {
+        try {
+            await fsp.rm(this.resolve(relPath), { force: true });
+        }
+        catch {
+            /* 文件已不存在则忽略 */
+        }
+        if (metaTableOf(relPath) !== null) {
+            /* 布局迁移：一并清理遗留的 <表>/_meta.json（幂等） */
+            try {
+                await fsp.rm(path.join(this.rootDir, relPath), { force: true });
+            }
+            catch {
+                /* 同上 */
+            }
+        }
+    }
+    async mkdir(relPath) {
+        await fsp.mkdir(this.resolve(relPath), { recursive: true });
+    }
+    async stat(relPath) {
+        try {
+            const s = await fsp.stat(this.resolve(relPath));
+            return { mtimeMs: s.mtimeMs, size: s.size };
+        }
+        catch (err) {
+            if (err?.code === 'ENOENT')
+                return null;
+            throw err;
+        }
+    }
+    async withLock(relPath, fn) {
+        const lockFile = `${this.resolve(relPath)}.lock`;
+        await fsp.mkdir(path.dirname(lockFile), { recursive: true });
+        const start = Date.now();
+        // 归属令牌：释放前校验，避免删除「已被回收、现由他人持有」的锁
+        const token = `${process.pid}-${Math.random().toString(36).slice(2)}`;
+        for (;;) {
+            // 超时判定置于循环开头：孤儿回收重试与 stat 失败重试分支同样受约束，避免热自旋
+            if (Date.now() - start > this.lockTimeoutMs) {
+                throw new Error(`[json-storage] 获取存储锁超时：${relPath}`);
+            }
+            let fd = null;
+            try {
+                fd = await fsp.open(lockFile, 'wx');
+            }
+            catch (err) {
+                if (err?.code !== 'EEXIST')
+                    throw err;
+                // 孤儿锁回收：mtime 超阈值视为持有者已崩溃，强制删除后重新竞争
+                // （临界区仅包裹毫秒级元数据操作，30s 余量充足；两进程同时回收时 O_EXCL 保证唯一胜者）
+                try {
+                    const st = await fsp.stat(lockFile);
+                    if (Date.now() - st.mtimeMs > this.lockStaleMs) {
+                        await fsp.rm(lockFile, { force: true });
+                        continue;
+                    }
+                }
+                catch {
+                    continue; // 锁已在间隙被释放，直接重试
+                }
+                await new Promise((r) => setTimeout(r, 10 + Math.random() * 40));
+                continue;
+            }
+            try {
+                // 写入持有者信息（token/PID/时间）便于孤儿锁诊断与归属校验
+                await fd.write(JSON.stringify({ token, pid: process.pid, at: new Date().toISOString() }));
+                await fd.close();
+                fd = null;
+                try {
+                    return await fn();
+                }
+                finally {
+                    await this.releaseLock(lockFile, token);
+                }
+            }
+            catch (err) {
+                if (fd) {
+                    try {
+                        await fd.close();
+                    }
+                    catch {
+                        /* ignore */
+                    }
+                }
+                await this.releaseLock(lockFile, token);
+                throw err;
+            }
+        }
+    }
+    /** 释放锁：仅当锁内容中的令牌与本进程一致时删除（否则锁已被回收并被他人持有） */
+    async releaseLock(lockFile, token) {
+        try {
+            const raw = await fsp.readFile(lockFile, 'utf8');
+            const holder = JSON.parse(raw);
+            if (holder?.token !== token)
+                return; // 他人持有：保留，交由回收阈值兜底
+        }
+        catch {
+            /* 锁文件已不存在或不可解析：无需释放 */
+            return;
+        }
+        try {
+            await fsp.rm(lockFile, { force: true });
+        }
+        catch {
+            /* 释放失败仅留孤儿锁文件，超阈值后会被回收；不阻断 */
+        }
+    }
+    async nextId(relPath, key) {
+        return this.withLock(relPath, async () => {
+            let seq = 0;
+            const raw = await this.readFile(relPath);
+            if (raw) {
+                try {
+                    const obj = JSON.parse(raw);
+                    const v = obj[key];
+                    if (typeof v === 'number')
+                        seq = v;
+                }
+                catch {
+                    /* 损坏的 _meta.json → 从 0 起 */
+                }
+            }
+            seq += 1;
+            await this.writeFileAtomic(relPath, JSON.stringify({ [key]: seq }));
+            return seq;
+        });
+    }
+    async ensureSeqAtLeast(relPath, key, value) {
+        await this.withLock(relPath, async () => {
+            let seq = 0;
+            const raw = await this.readFile(relPath);
+            if (raw) {
+                try {
+                    const obj = JSON.parse(raw);
+                    const v = obj[key];
+                    if (typeof v === 'number')
+                        seq = v;
+                }
+                catch {
+                    /* 损坏的 _meta.json → 以传入 value 为准 */
+                }
+            }
+            if (value > seq) {
+                await this.writeFileAtomic(relPath, JSON.stringify({ [key]: value }));
+            }
+        });
+    }
+}
+//# sourceMappingURL=json-backend-fs.js.map

package/dist/esm/json-backend-fs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"json-backend-fs.js","sourceRoot":"","sources":["../../src/json-backend-fs.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,KAAK,GAAG,MAAM,aAAa,CAAC;AACnC,OAAO,KAAK,IAAI,MAAM,MAAM,CAAC;AAU7B,MAAM,WAAW,GAAG,aAAa,CAAC;AAElC;;;;GAIG;AACH,SAAS,WAAW,CAAC,OAAe;IAClC,MAAM,IAAI,GAAG,OAAO,CAAC,OAAO,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC;IACzC,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,WAAW,CAAC;QAAE,OAAO,IAAI,CAAC;IAC7C,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,WAAW,CAAC,MAAM,CAAC,CAAC;IACjD,OAAO,KAAK,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC;AACtD,CAAC;AAED,MAAM,OAAO,gBAAgB;IAIE;IAHZ,aAAa,CAAS;IACtB,WAAW,CAAS;IAErC,YAA6B,OAAe,EAAE,OAAiC;QAAlD,YAAO,GAAP,OAAO,CAAQ;QAC1C,IAAI,CAAC,aAAa,GAAG,OAAO,EAAE,aAAa,IAAI,IAAI,CAAC;QACpD,IAAI,CAAC,WAAW,GAAG,OAAO,EAAE,WAAW,IAAI,KAAK,CAAC;IACnD,CAAC;IAEO,OAAO,CAAC,OAAe;QAC7B,uDAAuD;QACvD,MAAM,KAAK,GAAG,WAAW,CAAC,OAAO,CAAC,CAAC;QACnC,IAAI,KAAK;YAAE,OAAO,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,OAAO,EAAE,GAAG,KAAK,OAAO,CAAC,CAAC;QACpE,OAAO,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;IAC1C,CAAC;IAED,KAAK,CAAC,QAAQ,CAAC,OAAe;QAC5B,IAAI,CAAC;YACH,OAAO,MAAM,GAAG,CAAC,QAAQ,CAAC,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC,CAAC;QAC3D,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,IAAK,GAA6B,EAAE,IAAI,KAAK,QAAQ;gBAAE,OAAO,IAAI,CAAC;YACnE,MAAM,GAAG,CAAC;QACZ,CAAC;IACH,CAAC;IAED,KAAK,CAAC,eAAe,CAAC,OAAe,EAAE,IAAY;QACjD,MAAM,IAAI,GAAG,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC;QACnC,MAAM,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;QACzD,qCAAqC;QACrC,iDAAiD;QACjD,MAAM,GAAG,GAAG,GAAG,IAAI,IAAI,OAAO,CAAC,GAAG,IAAI,IAAI,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC;QAChF,IAAI,CAAC;YACH,MAAM,GAAG,CAAC,SAAS,CAAC,GAAG,EAAE,IAAI,EAAE,MAAM,CAAC,CAAC;YACvC,MAAM,GAAG,CAAC,MAAM,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC;QAC9B,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,IAAI,CAAC;gBACH,MAAM,GAAG,CAAC,EAAE,CAAC,GAAG,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;YACrC,CAAC;YAAC,MAAM,CAAC;gBACP,uBAAuB;YACzB,CAAC;YACD,MAAM,GAAG,CAAC;QACZ,CAAC;QACD,IAAI,WAAW,CAAC,OAAO,CAAC,KAAK,IAAI,EAAE,CAAC;YAClC,wCAAwC;YACxC,mCAAmC;YACnC,IAAI,CAAC;gBACH,MAAM,GAAG,CAAC,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,OAAO,CAAC,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;YAClE,CAAC;YAAC,MAAM,CAAC;gBACP,YAAY;YACd,CAAC;QACH,CAAC;IACH,CAAC;IAED,KAAK,CAAC,OAAO,CAAC,OAAe;QAC3B,IAAI,CAAC;YACH,OAAO,MAAM,GAAG,CAAC,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC;QAClD,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,IAAK,GAA6B,EAAE,IAAI,KAAK,QAAQ;gBAAE,OAAO,EAAE,CAAC;YACjE,MAAM,GAAG,CAAC;QACZ,CAAC;IACH,CAAC;IAED,KAAK,CAAC,UAAU,CAAC,OAAe;QAC9B,IAAI,CAAC;YACH,MAAM,GAAG,CAAC,EAAE,CAAC,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;QACvD,CAAC;QAAC,MAAM,CAAC;YACP,eAAe;QACjB,CAAC;QACD,IAAI,WAAW,CAAC,OAAO,CAAC,KAAK,IAAI,EAAE,CAAC;YAClC,qCAAqC;YACrC,IAAI,CAAC;gBACH,MAAM,GAAG,CAAC,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,OAAO,CAAC,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;YAClE,CAAC;YAAC,MAAM,CAAC;gBACP,QAAQ;YACV,CAAC;QACH,CAAC;IACH,CAAC;IAED,KAAK,CAAC,KAAK,CAAC,OAAe;QACzB,MAAM,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IAC9D,CAAC;IAED,KAAK,CAAC,IAAI,CAAC,OAAe;QACxB,IAAI,CAAC;YACH,MAAM,CAAC,GAAG,MAAM,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC;YAChD,OAAO,EAAE,OAAO,EAAE,CAAC,CAAC,OAAO,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC;QAC9C,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,IAAK,GAA6B,EAAE,IAAI,KAAK,QAAQ;gBAAE,OAAO,IAAI,CAAC;YACnE,MAAM,GAAG,CAAC;QACZ,CAAC;IACH,CAAC;IAED,KAAK,CAAC,QAAQ,CAAI,OAAe,EAAE,EAAoB;QACrD,MAAM,QAAQ,GAAG,GAAG,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,OAAO,CAAC;QACjD,MAAM,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;QAC7D,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QACzB,iCAAiC;QACjC,MAAM,KAAK,GAAG,GAAG,OAAO,CAAC,GAAG,IAAI,IAAI,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC;QACtE,SAAS,CAAC;YACR,4CAA4C;YAC5C,IAAI,IAAI,CAAC,GAAG,EAAE,GAAG,KAAK,GAAG,IAAI,CAAC,aAAa,EAAE,CAAC;gBAC5C,MAAM,IAAI,KAAK,CAAC,0BAA0B,OAAO,EAAE,CAAC,CAAC;YACvD,CAAC;YACD,IAAI,EAAE,GAA0B,IAAI,CAAC;YACrC,IAAI,CAAC;gBACH,EAAE,GAAG,MAAM,GAAG,CAAC,IAAI,CAAC,QAAQ,EAAE,IAAI,CAAC,CAAC;YACtC,CAAC;YAAC,OAAO,GAAG,EAAE,CAAC;gBACb,IAAK,GAA6B,EAAE,IAAI,KAAK,QAAQ;oBAAE,MAAM,GAAG,CAAC;gBACjE,oCAAoC;gBACpC,mDAAmD;gBACnD,IAAI,CAAC;oBACH,MAAM,EAAE,GAAG,MAAM,GAAG,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;oBACpC,IAAI,IAAI,CAAC,GAAG,EAAE,GAAG,EAAE,CAAC,OAAO,GAAG,IAAI,CAAC,WAAW,EAAE,CAAC;wBAC/C,MAAM,GAAG,CAAC,EAAE,CAAC,QAAQ,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;wBACxC,SAAS;oBACX,CAAC;gBACH,CAAC;gBAAC,MAAM,CAAC;oBACP,SAAS,CAAC,gBAAgB;gBAC5B,CAAC;gBACD,MAAM,IAAI,OAAO,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,UAAU,CAAC,CAAC,EAAE,EAAE,GAAG,IAAI,CAAC,MAAM,EAAE,GAAG,EAAE,CAAC,CAAC,CAAC;gBACjE,SAAS;YACX,CAAC;YACD,IAAI,CAAC;gBACH,oCAAoC;gBACpC,MAAM,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC,SAAS,CAAC,EAAE,KAAK,EAAE,GAAG,EAAE,OAAO,CAAC,GAAG,EAAE,EAAE,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,EAAE,CAAC,CAAC,CAAC;gBAC1F,MAAM,EAAE,CAAC,KAAK,EAAE,CAAC;gBACjB,EAAE,GAAG,IAAI,CAAC;gBACV,IAAI,CAAC;oBACH,OAAO,MAAM,EAAE,EAAE,CAAC;gBACpB,CAAC;wBAAS,CAAC;oBACT,MAAM,IAAI,CAAC,WAAW,CAAC,QAAQ,EAAE,KAAK,CAAC,CAAC;gBAC1C,CAAC;YACH,CAAC;YAAC,OAAO,GAAG,EAAE,CAAC;gBACb,IAAI,EAAE,EAAE,CAAC;oBACP,IAAI,CAAC;wBACH,MAAM,EAAE,CAAC,KAAK,EAAE,CAAC;oBACnB,CAAC;oBAAC,MAAM,CAAC;wBACP,YAAY;oBACd,CAAC;gBACH,CAAC;gBACD,MAAM,IAAI,CAAC,WAAW,CAAC,QAAQ,EAAE,KAAK,CAAC,CAAC;gBACxC,MAAM,GAAG,CAAC;YACZ,CAAC;QACH,CAAC;IACH,CAAC;IAED,4CAA4C;IACpC,KAAK,CAAC,WAAW,CAAC,QAAgB,EAAE,KAAa;QACvD,IAAI,CAAC;YACH,MAAM,GAAG,GAAG,MAAM,GAAG,CAAC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC;YACjD,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAuB,CAAC;YACrD,IAAI,MAAM,EAAE,KAAK,KAAK,KAAK;gBAAE,OAAO,CAAC,mBAAmB;QAC1D,CAAC;QAAC,MAAM,CAAC;YACP,uBAAuB;YACvB,OAAO;QACT,CAAC;QACD,IAAI,CAAC;YACH,MAAM,GAAG,CAAC,EAAE,CAAC,QAAQ,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;QAC1C,CAAC;QAAC,MAAM,CAAC;YACP,8BAA8B;QAChC,CAAC;IACH,CAAC;IAED,KAAK,CAAC,MAAM,CAAC,OAAe,EAAE,GAAW;QACvC,OAAO,IAAI,CAAC,QAAQ,CAAC,OAAO,EAAE,KAAK,IAAI,EAAE;YACvC,IAAI,GAAG,GAAG,CAAC,CAAC;YACZ,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC;YACzC,IAAI,GAAG,EAAE,CAAC;gBACR,IAAI,CAAC;oBACH,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAA4B,CAAC;oBACvD,MAAM,CAAC,GAAG,GAAG,CAAC,GAAG,CAAC,CAAC;oBACnB,IAAI,OAAO,CAAC,KAAK,QAAQ;wBAAE,GAAG,GAAG,CAAC,CAAC;gBACrC,CAAC;gBAAC,MAAM,CAAC;oBACP,4BAA4B;gBAC9B,CAAC;YACH,CAAC;YACD,GAAG,IAAI,CAAC,CAAC;YACT,MAAM,IAAI,CAAC,eAAe,CAAC,OAAO,EAAE,IAAI,CAAC,SAAS,CAAC,EAAE,CAAC,GAAG,CAAC,EAAE,GAAG,EAAE,CAAC,CAAC,CAAC;YACpE,OAAO,GAAG,CAAC;QACb,CAAC,CAAC,CAAC;IACL,CAAC;IAED,KAAK,CAAC,gBAAgB,CAAC,OAAe,EAAE,GAAW,EAAE,KAAa;QAChE,MAAM,IAAI,CAAC,QAAQ,CAAC,OAAO,EAAE,KAAK,IAAI,EAAE;YACtC,IAAI,GAAG,GAAG,CAAC,CAAC;YACZ,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC;YACzC,IAAI,GAAG,EAAE,CAAC;gBACR,IAAI,CAAC;oBACH,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAA4B,CAAC;oBACvD,MAAM,CAAC,GAAG,GAAG,CAAC,GAAG,CAAC,CAAC;oBACnB,IAAI,OAAO,CAAC,KAAK,QAAQ;wBAAE,GAAG,GAAG,CAAC,CAAC;gBACrC,CAAC;gBAAC,MAAM,CAAC;oBACP,mCAAmC;gBACrC,CAAC;YACH,CAAC;YACD,IAAI,KAAK,GAAG,GAAG,EAAE,CAAC;gBAChB,MAAM,IAAI,CAAC,eAAe,CAAC,OAAO,EAAE,IAAI,CAAC,SAAS,CAAC,EAAE,CAAC,GAAG,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC;YACxE,CAAC;QACH,CAAC,CAAC,CAAC;IACL,CAAC;CACF"}

package/dist/esm/json-collection.d.ts

@@ -0,0 +1,70 @@
+import { type JsonStorageBackend } from './json-config.js';
+import type { JsonEntityMeta } from './json-entity-meta.js';
+/** 行对象：属性名 → 值（实体表）或原始列名 → 值（非实体表） */
+export type JsonRow = Record<string, unknown>;
+export declare class JsonCollection {
+    private meta;
+    readonly tableName: string;
+    /** 主键属性（实体表）或主键列（非实体表）；未知时为 undefined */
+    readonly primaryProperty?: string;
+    /** 当前集合使用的后端实例（供 getCollection 检测运行时重注后重建） */
+    readonly backend: JsonStorageBackend;
+    private readonly metaRelPath;
+    private readonly reloadTtlMs;
+    private rows;
+    private loaded;
+    private seq;
+    /** 已知后备存储（表目录）mtime；外部变更触发重载（etag 优先判定） */
+    private cacheMtime;
+    /** 已知后备存储（表目录）etag；后端提供时优先于 mtime 判定外部变更 */
+    private cacheEtag;
+    /** 上次失效校验时间戳（ms），受 reloadTtlMs 节流 */
+    private lastCheckedAt;
+    /** 进行中的加载 Promise（single-flight：并发首载/重载共享，不重复整表 I/O） */
+    private loadPromise;
+    constructor(tableName: string, meta: JsonEntityMeta | null);
+    /**
+     * 表内全部行（惰性加载后返回**深拷贝**，调用方原地修改不会污染内存集合或静默分叉磁盘）。
+     * 与 TypeORM 一致：返回的行不会因未 save 而落库。
+     */
+    all(): Promise<JsonRow[]>;
+    /** 按主键取行（返回深拷贝，调用方原地修改不影响内存集合与磁盘） */
+    get(pk: unknown): Promise<JsonRow | undefined>;
+    /** 按谓词查找（返回深拷贝，调用方原地修改不影响内存集合与磁盘） */
+    findWhere(pred: (row: JsonRow) => boolean): Promise<JsonRow[]>;
+    /** 写入（新增或整行覆盖），返回落盘后的行 */
+    write(row: JsonRow): Promise<JsonRow>;
+    /** 删除行，返回是否删除 */
+    delete(pk: unknown): Promise<boolean>;
+    /** 分配下一个自增主键（后端级原子序列器，跨进程唯一；不低于集合已知水位） */
+    nextId(): Promise<number>;
+    /** 清空内存缓存并删除落盘数据（TRUNCATE 与测试隔离使用） */
+    clear(): Promise<void>;
+    /** @deprecated 兼容别名，请使用 clear() */
+    clearForTest(): Promise<void>;
+    /** 读取前确保集合已加载，并按 TTL 节流做跨进程失效校验 */
+    private ensureLoaded;
+    /** 失效判定：任一侧提供 etag 时以 etag 不等为变更，否则以 mtime 增大为变更 */
+    private isExternalChange;
+    /** 记录一次已确认的后备状态（etag + mtime） */
+    private rememberStat;
+    /** 经后端把表目录读入内存（single-flight：并发加载共享同一 Promise） */
+    private loadFromBackend;
+    /** 加载体：局部构建后整体交换；加载前后 stat 不一致（窗口内并发写入）则有界重试 */
+    private doLoadFromBackend;
+    /** 写/删后同步已知后备状态，使下次失效校验以本进程写入为基准 */
+    private refreshCacheMtime;
+    private resolveKey;
+    private rowKey;
+    private rowFileRel;
+}
+/**
+ * 获取（或创建）表的集合单例。
+ * 运行时重注后端（configureJsonStorage）后，旧集合的内存缓存属于旧数据源，
+ * 检测到后端实例变更即丢弃重建（已外传的旧 Repository/Collection 引用不追踪：
+ * 重注应在首次访问前完成，测试中配合 resetCollectionsForTest）。
+ */
+export declare function getCollection(tableName: string, meta: JsonEntityMeta | null): JsonCollection;
+/** 仅供测试：清空全部集合缓存 */
+export declare function resetCollectionsForTest(): void;
+//# sourceMappingURL=json-collection.d.ts.map

package/dist/esm/json-collection.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"json-collection.d.ts","sourceRoot":"","sources":["../../src/json-collection.ts"],"names":[],"mappings":"AAgBA,OAAO,EAGL,KAAK,kBAAkB,EAExB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAK5D,sCAAsC;AACtC,MAAM,MAAM,OAAO,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAuC9C,qBAAa,cAAc;IAsBM,OAAO,CAAC,IAAI;IArB3C,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,yCAAyC;IACzC,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,CAAC;IAElC,8CAA8C;IAC9C,QAAQ,CAAC,OAAO,EAAE,kBAAkB,CAAC;IACrC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAS;IACrC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAS;IAErC,OAAO,CAAC,IAAI,CAA8B;IAC1C,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,GAAG,CAAqB;IAChC,2CAA2C;IAC3C,OAAO,CAAC,UAAU,CAAK;IACvB,4CAA4C;IAC5C,OAAO,CAAC,SAAS,CAAqB;IACtC,qCAAqC;IACrC,OAAO,CAAC,aAAa,CAAK;IAC1B,wDAAwD;IACxD,OAAO,CAAC,WAAW,CAA8B;gBAErC,SAAS,EAAE,MAAM,EAAU,IAAI,EAAE,cAAc,GAAG,IAAI;IAQlE;;;OAGG;IACG,GAAG,IAAI,OAAO,CAAC,OAAO,EAAE,CAAC;IAK/B,qCAAqC;IAC/B,GAAG,CAAC,EAAE,EAAE,OAAO,GAAG,OAAO,CAAC,OAAO,GAAG,SAAS,CAAC;IAMpD,qCAAqC;IAC/B,SAAS,CAAC,IAAI,EAAE,CAAC,GAAG,EAAE,OAAO,KAAK,OAAO,GAAG,OAAO,CAAC,OAAO,EAAE,CAAC;IAKpE,0BAA0B;IACpB,KAAK,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC;IAkB3C,iBAAiB;IACX,MAAM,CAAC,EAAE,EAAE,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC;IAS3C,0CAA0C;IACpC,MAAM,IAAI,OAAO,CAAC,MAAM,CAAC;IAe/B,sCAAsC;IAChC,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAmB5B,mCAAmC;IACnC,YAAY,IAAI,OAAO,CAAC,IAAI,CAAC;IAM7B,mCAAmC;YACrB,YAAY;IAuB1B,oDAAoD;IACpD,OAAO,CAAC,gBAAgB;IAOxB,iCAAiC;IACjC,OAAO,CAAC,YAAY;IAKpB,kDAAkD;IAClD,OAAO,CAAC,eAAe;IASvB,gDAAgD;YAClC,iBAAiB;IA+D/B,oCAAoC;YACtB,iBAAiB;IAU/B,OAAO,CAAC,UAAU;IAelB,OAAO,CAAC,MAAM;IAId,OAAO,CAAC,UAAU;CAKnB;AAID;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,cAAc,GAAG,IAAI,GAAG,cAAc,CAW5F;AAED,oBAAoB;AACpB,wBAAgB,uBAAuB,IAAI,IAAI,CAE9C"}

package/dist/esm/json-collection.js

@@ -0,0 +1,346 @@
+/**
+ * JSON 回退存储：文件型表集合（json-fallback-storage 规格）
+ *
+ * 落盘布局：`<根>/<表名>/<主键>.json`（每行一个 JSON 文件，属性名为键；
+ * 根经 `configureJsonStorage()` 注入的 `JsonStorageBackend` 解析），
+ * 自增序列器与表元信息存于 `<根>/_meta/<表名>.json`（与表目录分离，
+ * 序列器/锁写入不触发表级失效信号）。
+ *
+ * - 惰性加载：首次访问时把表目录经后端读入内存（single-flight 共享加载）
+ * - 原子写：先写临时文件再 rename，避免进程中断产生半截文件
+ * - datetime 类型列读取时还原为 Date（保证与 TypeORM 行为一致，可参与比较/排序）
+ * - 跨进程缓存失效：读取前经 `backend.stat(表目录)` 检测外部变更（etag 优先、
+ *   mtime 兜底；stat 返回 null 视为无变更），变更则重载
+ *   （`reloadTtlMs` 节流；默认 0 即每次访问校验）
+ */
+import * as path from 'path';
+import { requireStorageBackend, getReloadTtlMs, } from "./json-config.js";
+import { getNonEntityPrimaryColumn } from "./json-entity-meta.js";
+const META_FILE = '_meta.json';
+/**
+ * 深拷贝行值，保留 Date 等内置类型（递归，避免把 Date 折回 ISO 字符串）。
+ * 用于读路径隔离：调用方拿到的是独立副本，原地修改不会污染内存集合，
+ * 也不会在未 write 时与磁盘文件静默分叉（与 TypeORM「返回受管实体、未 save 不落库」一致）。
+ */
+function cloneValue(value) {
+    if (value === null || typeof value !== 'object')
+        return value;
+    if (value instanceof Date)
+        return new Date(value.getTime());
+    if (Array.isArray(value))
+        return value.map(cloneValue);
+    // 内置容器保真：退化为索引对象/空对象会让落盘形态被静默改写
+    if (Buffer.isBuffer(value))
+        return Buffer.from(value);
+    if (ArrayBuffer.isView(value)) {
+        return value.slice();
+    }
+    if (value instanceof ArrayBuffer)
+        return value.slice(0);
+    if (value instanceof Map)
+        return new Map([...value].map(([k, v]) => [k, cloneValue(v)]));
+    if (value instanceof Set)
+        return new Set([...value].map(cloneValue));
+    if (value instanceof RegExp)
+        return new RegExp(value.source, value.flags);
+    // 类实例等非普通对象按引用返回：宁可共享引用，也不把形态改写成裸对象
+    const proto = Object.getPrototypeOf(value);
+    if (proto !== Object.prototype && proto !== null)
+        return value;
+    const out = {};
+    for (const k of Object.keys(value)) {
+        out[k] = cloneValue(value[k]);
+    }
+    return out;
+}
+/** 行深拷贝（见 cloneValue；保留 Date） */
+function cloneRow(row) {
+    return cloneValue(row);
+}
+export class JsonCollection {
+    meta;
+    tableName;
+    /** 主键属性（实体表）或主键列（非实体表）；未知时为 undefined */
+    primaryProperty;
+    /** 当前集合使用的后端实例（供 getCollection 检测运行时重注后重建） */
+    backend;
+    metaRelPath;
+    reloadTtlMs;
+    rows = new Map();
+    loaded = false;
+    seq;
+    /** 已知后备存储（表目录）mtime；外部变更触发重载（etag 优先判定） */
+    cacheMtime = 0;
+    /** 已知后备存储（表目录）etag；后端提供时优先于 mtime 判定外部变更 */
+    cacheEtag;
+    /** 上次失效校验时间戳（ms），受 reloadTtlMs 节流 */
+    lastCheckedAt = 0;
+    /** 进行中的加载 Promise（single-flight：并发首载/重载共享，不重复整表 I/O） */
+    loadPromise = null;
+    constructor(tableName, meta) {
+        this.meta = meta;
+        this.tableName = tableName;
+        this.backend = requireStorageBackend();
+        this.metaRelPath = path.join(tableName, META_FILE);
+        this.reloadTtlMs = getReloadTtlMs();
+        this.primaryProperty = meta?.primaryProperty ?? getNonEntityPrimaryColumn(tableName);
+    }
+    /**
+     * 表内全部行（惰性加载后返回**深拷贝**，调用方原地修改不会污染内存集合或静默分叉磁盘）。
+     * 与 TypeORM 一致：返回的行不会因未 save 而落库。
+     */
+    async all() {
+        await this.ensureLoaded();
+        return [...this.rows.values()].map(cloneRow);
+    }
+    /** 按主键取行（返回深拷贝，调用方原地修改不影响内存集合与磁盘） */
+    async get(pk) {
+        await this.ensureLoaded();
+        const row = this.rows.get(this.rowKey(pk));
+        return row ? cloneRow(row) : undefined;
+    }
+    /** 按谓词查找（返回深拷贝，调用方原地修改不影响内存集合与磁盘） */
+    async findWhere(pred) {
+        await this.ensureLoaded();
+        return [...this.rows.values()].filter(pred).map(cloneRow);
+    }
+    /** 写入（新增或整行覆盖），返回落盘后的行 */
+    async write(row) {
+        await this.ensureLoaded(true);
+        const pk = this.resolveKey(row);
+        // 显式写入更大的数字主键时抬升序列器，避免同进程/跨进程后续 nextId() 撞已有主键
+        const n = Number(row[this.primaryProperty]);
+        if (Number.isInteger(n) && n > (this.seq ?? 0)) {
+            this.seq = n;
+            await this.backend.ensureSeqAtLeast(this.metaRelPath, 'seq', n);
+        }
+        const stored = { ...row };
+        // 先落盘再更新内存：落盘失败不留「内存有、磁盘无」的幽灵行
+        await this.backend.writeFileAtomic(this.rowFileRel(pk), JSON.stringify(stored, null, 2));
+        // 内存快照存独立深拷贝：调用方原地修改返回值（或其嵌套对象）不污染集合
+        this.rows.set(pk, cloneRow(stored));
+        await this.refreshCacheMtime();
+        return stored;
+    }
+    /** 删除行，返回是否删除 */
+    async delete(pk) {
+        await this.ensureLoaded(true);
+        const key = this.rowKey(pk);
+        if (!this.rows.delete(key))
+            return false;
+        await this.backend.deleteFile(this.rowFileRel(key));
+        await this.refreshCacheMtime();
+        return true;
+    }
+    /** 分配下一个自增主键（后端级原子序列器，跨进程唯一；不低于集合已知水位） */
+    async nextId() {
+        await this.ensureLoaded(true);
+        let id = await this.backend.nextId(this.metaRelPath, 'seq');
+        const floor = this.seq ?? 0;
+        if (id <= floor) {
+            // 后端序列器损坏/丢失/被重置 → 回绕分配会撞存量主键并静默覆盖行：
+            // 先抬升后端序列器至水位再重取（异常路径，代价一次额外锁内往返）
+            await this.backend.ensureSeqAtLeast(this.metaRelPath, 'seq', floor);
+            id = await this.backend.nextId(this.metaRelPath, 'seq');
+        }
+        this.seq = id;
+        await this.refreshCacheMtime();
+        return id;
+    }
+    /** 清空内存缓存并删除落盘数据（TRUNCATE 与测试隔离使用） */
+    async clear() {
+        // 必须先加载：否则「本进程未读过该表」时 rows 为空，只删 meta 而行文件全残留
+        await this.ensureLoaded();
+        // 等待在飞的加载结束，避免其用已被删除的文件重新填充 rows
+        if (this.loadPromise)
+            await this.loadPromise;
+        const keys = [...this.rows.keys()];
+        for (const k of keys) {
+            await this.backend.deleteFile(this.rowFileRel(k));
+        }
+        await this.backend.deleteFile(this.metaRelPath);
+        this.rows.clear();
+        this.seq = undefined;
+        this.loaded = false;
+        this.loadPromise = null;
+        this.cacheMtime = 0;
+        this.cacheEtag = undefined;
+        this.lastCheckedAt = 0;
+    }
+    /** @deprecated 兼容别名，请使用 clear() */
+    clearForTest() {
+        return this.clear();
+    }
+    // ---- 内部实现 ----
+    /** 读取前确保集合已加载，并按 TTL 节流做跨进程失效校验 */
+    async ensureLoaded(force = false) {
+        if (this.loaded) {
+            const now = Date.now();
+            // 写路径强制校验（绕过 TTL 节流）：确保写入前快照已含他进程写入，
+            // 使写入后记录的水位与实际快照一致，不掩蔽他进程变更
+            if (!force && now - this.lastCheckedAt < this.reloadTtlMs)
+                return;
+            const st = await this.backend.stat(this.tableName);
+            this.lastCheckedAt = now;
+            // 表目录不存在：视为无变更，保留内存快照（避免每次访问全量重载的读放大）
+            if (!st)
+                return;
+            if (this.isExternalChange(st)) {
+                // 外部进程已变更 → 丢弃内存快照后重载
+                this.rows.clear();
+                this.seq = undefined;
+                this.loaded = false;
+            }
+            else {
+                this.rememberStat(st);
+                return;
+            }
+        }
+        await this.loadFromBackend();
+    }
+    /** 失效判定：任一侧提供 etag 时以 etag 不等为变更，否则以 mtime 增大为变更 */
+    isExternalChange(st) {
+        if (st.etag !== undefined || this.cacheEtag !== undefined) {
+            return st.etag !== this.cacheEtag;
+        }
+        return st.mtimeMs > this.cacheMtime;
+    }
+    /** 记录一次已确认的后备状态（etag + mtime） */
+    rememberStat(st) {
+        this.cacheMtime = st.mtimeMs;
+        this.cacheEtag = st.etag;
+    }
+    /** 经后端把表目录读入内存（single-flight：并发加载共享同一 Promise） */
+    loadFromBackend() {
+        if (!this.loadPromise) {
+            this.loadPromise = this.doLoadFromBackend().finally(() => {
+                this.loadPromise = null;
+            });
+        }
+        return this.loadPromise;
+    }
+    /** 加载体：局部构建后整体交换；加载前后 stat 不一致（窗口内并发写入）则有界重试 */
+    async doLoadFromBackend() {
+        const datetimeProps = this.meta?.datetimeProperties ?? new Set();
+        for (let attempt = 0; attempt < 3; attempt += 1) {
+            const before = await this.backend.stat(this.tableName);
+            const rows = new Map();
+            const entries = await this.backend.readDir(this.tableName);
+            for (const name of entries) {
+                if (!name.endsWith('.json') || name === META_FILE)
+                    continue;
+                try {
+                    const raw = await this.backend.readFile(path.join(this.tableName, name));
+                    if (!raw)
+                        continue;
+                    const row = JSON.parse(raw);
+                    // datetime 列还原为 Date（ISO 字符串 → Date，与 TypeORM 读取行为一致）
+                    for (const prop of datetimeProps) {
+                        const v = row[prop];
+                        if (typeof v === 'string' && v)
+                            row[prop] = new Date(v);
+                    }
+                    const key = this.primaryProperty
+                        ? this.rowKey(row[this.primaryProperty])
+                        : decodeURIComponent(name.slice(0, -5));
+                    if (key && key !== 'undefined')
+                        rows.set(key, row);
+                }
+                catch (err) {
+                    // 单个损坏文件不阻塞整表加载；fail-loud 记日志
+                    // eslint-disable-next-line no-console
+                    console.warn(`[json-storage] 跳过损坏文件 ${this.tableName}/${name}:`, err.message);
+                }
+            }
+            // 初始化序列器：取现有最大数字主键与 _meta.json 序列器较大者
+            let max = 0;
+            for (const key of rows.keys()) {
+                const n = Number(key);
+                if (Number.isInteger(n) && n > max)
+                    max = n;
+            }
+            const metaRaw = await this.backend.readFile(this.metaRelPath);
+            if (metaRaw) {
+                try {
+                    const metaFile = JSON.parse(metaRaw);
+                    if (typeof metaFile.seq === 'number')
+                        max = Math.max(max, metaFile.seq);
+                }
+                catch {
+                    /* 无/损坏 _meta.json → 以现有最大主键为准 */
+                }
+            }
+            const after = await this.backend.stat(this.tableName);
+            // 加载窗口稳定：两侧 stat 一致（etag 与 mtime 均未变），或重试耗尽取最后快照
+            const stable = (before?.mtimeMs ?? 0) >= (after?.mtimeMs ?? 0) && (before?.etag ?? undefined) === (after?.etag ?? undefined);
+            if (stable || attempt === 2) {
+                this.rows = rows;
+                this.seq = max;
+                if (after)
+                    this.rememberStat(after);
+                else {
+                    // 目录不存在：水位基线记 0（而非墙上时钟），使目录后续出现时任何 mtime
+                    // 都能被判定为变更（时钟回拨/备份恢复下 Date.now() 会永久失灵）
+                    this.cacheMtime = 0;
+                    this.cacheEtag = undefined;
+                }
+                this.loaded = true;
+                this.lastCheckedAt = Date.now();
+                return;
+            }
+        }
+    }
+    /** 写/删后同步已知后备状态，使下次失效校验以本进程写入为基准 */
+    async refreshCacheMtime() {
+        const st = await this.backend.stat(this.tableName);
+        if (st)
+            this.rememberStat(st);
+        else {
+            this.cacheMtime = 0;
+            this.cacheEtag = undefined;
+        }
+        this.lastCheckedAt = Date.now();
+    }
+    resolveKey(row) {
+        if (!this.primaryProperty) {
+            throw new Error(`[json-storage] 表 ${this.tableName} 缺少主键定义，无法落盘行：${JSON.stringify(row).slice(0, 200)}`);
+        }
+        const pk = row[this.primaryProperty];
+        if (pk === undefined || pk === null || pk === '') {
+            throw new Error(`[json-storage] 表 ${this.tableName} 行主键 ${this.primaryProperty} 为空，无法落盘`);
+        }
+        return this.rowKey(pk);
+    }
+    rowKey(pk) {
+        return String(pk);
+    }
+    rowFileRel(key) {
+        // 字符串主键（如 cacheKey、lock_name）经 encodeURIComponent 保证文件名安全；
+        // `*` 未被 encodeURIComponent 转义，需显式转义（Windows 非法文件名字符）
+        return path.join(this.tableName, `${encodeURIComponent(key).replace(/\*/g, '%2A')}.json`);
+    }
+}
+const collectionCache = new Map();
+/**
+ * 获取（或创建）表的集合单例。
+ * 运行时重注后端（configureJsonStorage）后，旧集合的内存缓存属于旧数据源，
+ * 检测到后端实例变更即丢弃重建（已外传的旧 Repository/Collection 引用不追踪：
+ * 重注应在首次访问前完成，测试中配合 resetCollectionsForTest）。
+ */
+export function getCollection(tableName, meta) {
+    let c = collectionCache.get(tableName);
+    if (c && c.backend !== requireStorageBackend()) {
+        collectionCache.delete(tableName);
+        c = undefined;
+    }
+    if (!c) {
+        c = new JsonCollection(tableName, meta);
+        collectionCache.set(tableName, c);
+    }
+    return c;
+}
+/** 仅供测试：清空全部集合缓存 */
+export function resetCollectionsForTest() {
+    collectionCache.clear();
+}
+//# sourceMappingURL=json-collection.js.map