@cicctencent/json-orm 0.1.1

package/dist/esm/json-where.js

@@ -0,0 +1,342 @@
+/**
+ * 跨 typeorm 多副本安全的 FindOperator 判定。
+ * 本包与消费方（如 app/work-space）常因 pnpm 解析到不同 typeorm 副本，
+ * 导致 `instanceof FindOperator` 跨模块实例失效；改用运行时类名鸭子类型检测，
+ * 避免把 FindOperator 误判为普通值。
+ */
+export function isFindOperator(value) {
+    return (value != null &&
+        typeof value === 'object' &&
+        !Array.isArray(value) &&
+        value.constructor?.name === 'FindOperator' &&
+        typeof value.type === 'string');
+}
+// 按长度降序：确保 `->>` 不被 `->` 抢先切分（否则 `->>` 永不可达且解析抛错）
+const MULTI_OPS = ['>=', '<=', '<>', '!=', '->>', '->'];
+const SINGLE_OPS = '=<>+-*/%';
+export function tokenizeSql(sql) {
+    const tokens = [];
+    let i = 0;
+    while (i < sql.length) {
+        const ch = sql[i];
+        if (/\s/.test(ch)) {
+            i += 1;
+            continue;
+        }
+        // 行注释
+        if (ch === '-' && sql[i + 1] === '-') {
+            while (i < sql.length && sql[i] !== '\n')
+                i += 1;
+            continue;
+        }
+        // 字符串（单引号，'' 转义）与双引号字符串
+        if (ch === "'" || ch === '"') {
+            const quote = ch;
+            let v = '';
+            i += 1;
+            while (i < sql.length) {
+                if (sql[i] === quote) {
+                    if (sql[i + 1] === quote) {
+                        v += quote;
+                        i += 2;
+                        continue;
+                    }
+                    i += 1;
+                    break;
+                }
+                v += sql[i];
+                i += 1;
+            }
+            tokens.push({ type: 'string', value: v, pos: i });
+            continue;
+        }
+        // 反引号标识符
+        if (ch === '`') {
+            const end = sql.indexOf('`', i + 1);
+            if (end < 0)
+                throw new Error(`[json-storage] SQL 分词失败：未闭合的反引号（${sql.slice(i, i + 20)}…）`);
+            tokens.push({ type: 'ident', value: sql.slice(i + 1, end), pos: i });
+            i = end + 1;
+            continue;
+        }
+        // 命名参数 :name / 展开参数 :...name
+        if (ch === ':') {
+            let j = i + 1;
+            let spread = false;
+            if (sql.slice(j, j + 3) === '...') {
+                spread = true;
+                j += 3;
+            }
+            let name = '';
+            while (j < sql.length && /[A-Za-z0-9_$]/.test(sql[j])) {
+                name += sql[j];
+                j += 1;
+            }
+            if (!name)
+                throw new Error(`[json-storage] SQL 分词失败：非法参数占位符（位置 ${i}）`);
+            tokens.push({ type: 'param', value: spread ? `...${name}` : name, pos: i });
+            i = j;
+            continue;
+        }
+        if (ch === '?') {
+            tokens.push({ type: 'qmark', value: '?', pos: i });
+            i += 1;
+            continue;
+        }
+        if (/[0-9]/.test(ch)) {
+            let v = '';
+            while (i < sql.length && /[0-9.]/.test(sql[i])) {
+                v += sql[i];
+                i += 1;
+            }
+            tokens.push({ type: 'number', value: v, pos: i });
+            continue;
+        }
+        if (/[A-Za-z_$]/.test(ch)) {
+            let v = '';
+            while (i < sql.length && /[A-Za-z0-9_$]/.test(sql[i])) {
+                v += sql[i];
+                i += 1;
+            }
+            tokens.push({ type: 'ident', value: v, pos: i });
+            continue;
+        }
+        const two = sql.slice(i, i + 3);
+        const multi = MULTI_OPS.find(op => two.startsWith(op));
+        if (multi) {
+            tokens.push({ type: 'op', value: multi, pos: i });
+            i += multi.length;
+            continue;
+        }
+        if (SINGLE_OPS.includes(ch)) {
+            tokens.push({ type: 'op', value: ch, pos: i });
+            i += 1;
+            continue;
+        }
+        if (ch === '(') {
+            tokens.push({ type: 'lparen', value: ch, pos: i });
+            i += 1;
+            continue;
+        }
+        if (ch === ')') {
+            tokens.push({ type: 'rparen', value: ch, pos: i });
+            i += 1;
+            continue;
+        }
+        if (ch === ',') {
+            tokens.push({ type: 'comma', value: ch, pos: i });
+            i += 1;
+            continue;
+        }
+        if (ch === '.') {
+            tokens.push({ type: 'dot', value: ch, pos: i });
+            i += 1;
+            continue;
+        }
+        throw new Error(`[json-storage] SQL 分词失败：不支持的字符 "${ch}"（位置 ${i}）`);
+    }
+    tokens.push({ type: 'eof', value: '', pos: sql.length });
+    return tokens;
+}
+/** 分词游标（供条件/表达式解析共用） */
+export class TokenCursor {
+    tokens;
+    idx = 0;
+    constructor(tokens) {
+        this.tokens = tokens;
+    }
+    peek(offset = 0) {
+        return this.tokens[Math.min(this.idx + offset, this.tokens.length - 1)];
+    }
+    next() {
+        const t = this.tokens[this.idx];
+        if (t.type !== 'eof')
+            this.idx += 1;
+        return t;
+    }
+    /** 当前 ident 是否关键字（大小写不敏感） */
+    isKeyword(word, offset = 0) {
+        const t = this.peek(offset);
+        return t.type === 'ident' && t.value.toUpperCase() === word;
+    }
+    expectKeyword(word) {
+        if (!this.isKeyword(word)) {
+            throw new Error(`[json-storage] 解析失败：期望 ${word}，实际 "${this.peek().value || this.peek().type}"`);
+        }
+        this.next();
+    }
+    expect(type, value) {
+        const t = this.peek();
+        if (t.type !== type || (value !== undefined && t.value !== value)) {
+            throw new Error(`[json-storage] 解析失败：期望 ${value ?? type}，实际 "${t.value || t.type}"`);
+        }
+        return this.next();
+    }
+    atEnd() {
+        return this.peek().type === 'eof';
+    }
+}
+// ---------------- 值比较 / LIKE ----------------
+/** 稳健比较：数字按数值、日期按时间戳、字符串按字典序；类型不可比时按字符串 */
+export function compareValues(a, b) {
+    // 任一侧为 Date：统一换算为时间戳比较（字符串先尝试 Date.parse，兼容 MySQL datetime 文本）
+    if (a instanceof Date || b instanceof Date) {
+        const ta = dateToTs(a);
+        const tb = dateToTs(b);
+        if (ta !== null && tb !== null)
+            return ta < tb ? -1 : ta > tb ? 1 : 0;
+    }
+    const na = toNumber(a);
+    const nb = toNumber(b);
+    if (na !== null && nb !== null) {
+        return na < nb ? -1 : na > nb ? 1 : 0;
+    }
+    const sa = String(a ?? '');
+    const sb = String(b ?? '');
+    return sa < sb ? -1 : sa > sb ? 1 : 0;
+}
+function dateToTs(v) {
+    if (v instanceof Date)
+        return Number.isNaN(v.getTime()) ? null : v.getTime();
+    if (typeof v === 'number')
+        return v;
+    if (typeof v === 'string' && v.trim() !== '') {
+        const t = Date.parse(v.replace(' ', 'T'));
+        return Number.isNaN(t) ? null : t;
+    }
+    return null;
+}
+function toNumber(v) {
+    if (typeof v === 'number')
+        return v;
+    if (typeof v === 'boolean')
+        return v ? 1 : 0;
+    if (v instanceof Date)
+        return v.getTime();
+    if (typeof v === 'string' && v.trim() !== '' && !Number.isNaN(Number(v)))
+        return Number(v);
+    return null;
+}
+/** SQL LIKE：`%` 任意串、`_` 单字符 */
+export function likeMatch(input, pattern) {
+    const escaped = pattern
+        .replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+        .replace(/%/g, '.*')
+        .replace(/_/g, '.');
+    // 转义已覆盖全部正则元字符，构造不会失败；不再保留「去 % 后子串包含」的误判兜底
+    return new RegExp(`^${escaped}$`, 'is').test(input);
+}
+/** 宽松等值（Date/ISO 字符串、数字/字符串数字） */
+export function looseEqual(a, b) {
+    if (a === b)
+        return true;
+    if (a === null || a === undefined || b === null || b === undefined)
+        return false;
+    if (a instanceof Date || b instanceof Date) {
+        const ta = a instanceof Date ? a.getTime() : Date.parse(String(a));
+        const tb = b instanceof Date ? b.getTime() : Date.parse(String(b));
+        return ta === tb && !Number.isNaN(ta);
+    }
+    const na = toNumber(a);
+    const nb = toNumber(b);
+    if (na !== null && nb !== null)
+        return na === nb;
+    // 对象/数组不得退化为 String() 比较：任意两个 {} 会得到 '[object Object]' 而误判相等，
+    // 使 upsert 冲突检测与唯一索引匹配把不相关的行判为冲突并错误合并到首行
+    if (typeof a === 'object' || typeof b === 'object')
+        return deepEqual(a, b);
+    return String(a) === String(b);
+}
+/** 结构化深比较（供 looseEqual 对对象/数组值使用） */
+function deepEqual(a, b) {
+    if (a === b)
+        return true;
+    if (typeof a !== 'object' || typeof b !== 'object' || a === null || b === null)
+        return false;
+    if (Array.isArray(a) !== Array.isArray(b))
+        return false;
+    if (Array.isArray(a) && Array.isArray(b)) {
+        return a.length === b.length && a.every((v, i) => deepEqual(v, b[i]));
+    }
+    const ra = a;
+    const rb = b;
+    const ka = Object.keys(ra);
+    const kb = Object.keys(rb);
+    if (ka.length !== kb.length)
+        return false;
+    return ka.every(k => k in rb && deepEqual(ra[k], rb[k]));
+}
+// ---------------- FindOptionsWhere 对象匹配 ----------------
+/**
+ * 匹配 FindOptionsWhere（对象或对象数组=OR）。
+ * 键为属性名（若为数据库列名则经 meta 映射），值支持原始值与 FindOperator。
+ */
+export function matchesWhere(row, where, meta) {
+    if (where === null || where === undefined)
+        return true;
+    if (Array.isArray(where))
+        return where.some(w => matchesWhere(row, w, meta));
+    if (typeof where !== 'object') {
+        throw new Error(`[json-storage] 不支持的 where 形式：${JSON.stringify(where)}`);
+    }
+    for (const [key, expected] of Object.entries(where)) {
+        const prop = meta?.columnByDbName.get(key) ?? key;
+        const actual = row[prop];
+        if (isFindOperator(expected)) {
+            if (!evalFindOperator(expected, actual))
+                return false;
+            continue;
+        }
+        if (expected !== null && expected !== undefined && typeof expected === 'object' && !(expected instanceof Date)) {
+            throw new Error(`[json-storage] 不支持的 where 嵌套对象（属性 ${key}）——JSON 回退模式暂不支持关系嵌套查询`);
+        }
+        if (expected === null || expected === undefined) {
+            if (actual !== null && actual !== undefined)
+                return false;
+            continue;
+        }
+        if (!looseEqual(actual, expected))
+            return false;
+    }
+    return true;
+}
+function evalFindOperator(op, actual) {
+    const type = op.type;
+    const child = op.child;
+    switch (type) {
+        case 'equal':
+            return looseEqual(actual, op.value);
+        case 'not':
+            if (child)
+                return !evalFindOperator(child, actual);
+            return !looseEqual(actual, op.value);
+        case 'like':
+            return likeMatch(String(actual ?? ''), String(op.value ?? ''));
+        case 'ilike':
+            return likeMatch(String(actual ?? '').toLowerCase(), String(op.value ?? '').toLowerCase());
+        case 'in':
+        case 'any': {
+            const arr = Array.isArray(op.value) ? op.value : [op.value];
+            return arr.some(v => looseEqual(actual, v));
+        }
+        case 'between': {
+            const arr = Array.isArray(op.value) ? op.value : [op.value];
+            return compareValues(actual, arr[0]) >= 0 && compareValues(actual, arr[1]) <= 0;
+        }
+        case 'lessThan':
+            return actual !== null && actual !== undefined && compareValues(actual, op.value) < 0;
+        case 'lessThanOrEqual':
+            return actual !== null && actual !== undefined && compareValues(actual, op.value) <= 0;
+        case 'moreThan':
+            return actual !== null && actual !== undefined && compareValues(actual, op.value) > 0;
+        case 'moreThanOrEqual':
+            return actual !== null && actual !== undefined && compareValues(actual, op.value) >= 0;
+        case 'isNull':
+            return actual === null || actual === undefined;
+        case 'raw':
+            throw new Error('[json-storage] Raw() 操作符在 JSON 回退模式不受支持（fail-loud）');
+        default:
+            throw new Error(`[json-storage] 不支持的 FindOperator 类型：${type}`);
+    }
+}
+//# sourceMappingURL=json-where.js.map

package/dist/esm/json-where.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"json-where.js","sourceRoot":"","sources":["../../src/json-where.ts"],"names":[],"mappings":"AAgBA;;;;;GAKG;AACH,MAAM,UAAU,cAAc,CAAC,KAAc;IAC3C,OAAO,CACL,KAAK,IAAI,IAAI;QACb,OAAO,KAAK,KAAK,QAAQ;QACzB,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC;QACpB,KAA6C,CAAC,WAAW,EAAE,IAAI,KAAK,cAAc;QACnF,OAAQ,KAA4B,CAAC,IAAI,KAAK,QAAQ,CACvD,CAAC;AACJ,CAAC;AAuBD,kDAAkD;AAClD,MAAM,SAAS,GAAG,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,CAAC,CAAC;AACxD,MAAM,UAAU,GAAG,UAAU,CAAC;AAE9B,MAAM,UAAU,WAAW,CAAC,GAAW;IACrC,MAAM,MAAM,GAAY,EAAE,CAAC;IAC3B,IAAI,CAAC,GAAG,CAAC,CAAC;IACV,OAAO,CAAC,GAAG,GAAG,CAAC,MAAM,EAAE,CAAC;QACtB,MAAM,EAAE,GAAG,GAAG,CAAC,CAAC,CAAC,CAAC;QAClB,IAAI,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,EAAE,CAAC;YAClB,CAAC,IAAI,CAAC,CAAC;YACP,SAAS;QACX,CAAC;QACD,MAAM;QACN,IAAI,EAAE,KAAK,GAAG,IAAI,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,KAAK,GAAG,EAAE,CAAC;YACrC,OAAO,CAAC,GAAG,GAAG,CAAC,MAAM,IAAI,GAAG,CAAC,CAAC,CAAC,KAAK,IAAI;gBAAE,CAAC,IAAI,CAAC,CAAC;YACjD,SAAS;QACX,CAAC;QACD,wBAAwB;QACxB,IAAI,EAAE,KAAK,GAAG,IAAI,EAAE,KAAK,GAAG,EAAE,CAAC;YAC7B,MAAM,KAAK,GAAG,EAAE,CAAC;YACjB,IAAI,CAAC,GAAG,EAAE,CAAC;YACX,CAAC,IAAI,CAAC,CAAC;YACP,OAAO,CAAC,GAAG,GAAG,CAAC,MAAM,EAAE,CAAC;gBACtB,IAAI,GAAG,CAAC,CAAC,CAAC,KAAK,KAAK,EAAE,CAAC;oBACrB,IAAI,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,KAAK,KAAK,EAAE,CAAC;wBACzB,CAAC,IAAI,KAAK,CAAC;wBACX,CAAC,IAAI,CAAC,CAAC;wBACP,SAAS;oBACX,CAAC;oBACD,CAAC,IAAI,CAAC,CAAC;oBACP,MAAM;gBACR,CAAC;gBACD,CAAC,IAAI,GAAG,CAAC,CAAC,CAAC,CAAC;gBACZ,CAAC,IAAI,CAAC,CAAC;YACT,CAAC;YACD,MAAM,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,KAAK,EAAE,CAAC,EAAE,GAAG,EAAE,CAAC,EAAE,CAAC,CAAC;YAClD,SAAS;QACX,CAAC;QACD,SAAS;QACT,IAAI,EAAE,KAAK,GAAG,EAAE,CAAC;YACf,MAAM,GAAG,GAAG,GAAG,CAAC,OAAO,CAAC,GAAG,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;YACpC,IAAI,GAAG,GAAG,CAAC;gBAAE,MAAM,IAAI,KAAK,CAAC,mCAAmC,GAAG,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,CAAC;YAC1F,MAAM,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,GAAG,CAAC,KAAK,CAAC,CAAC,GAAG,CAAC,EAAE,GAAG,CAAC,EAAE,GAAG,EAAE,CAAC,EAAE,CAAC,CAAC;YACrE,CAAC,GAAG,GAAG,GAAG,CAAC,CAAC;YACZ,SAAS;QACX,CAAC;QACD,6BAA6B;QAC7B,IAAI,EAAE,KAAK,GAAG,EAAE,CAAC;YACf,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;YACd,IAAI,MAAM,GAAG,KAAK,CAAC;YACnB,IAAI,GAAG,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,GAAG,CAAC,CAAC,KAAK,KAAK,EAAE,CAAC;gBAClC,MAAM,GAAG,IAAI,CAAC;gBACd,CAAC,IAAI,CAAC,CAAC;YACT,CAAC;YACD,IAAI,IAAI,GAAG,EAAE,CAAC;YACd,OAAO,CAAC,GAAG,GAAG,CAAC,MAAM,IAAI,eAAe,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;gBACtD,IAAI,IAAI,GAAG,CAAC,CAAC,CAAC,CAAC;gBACf,CAAC,IAAI,CAAC,CAAC;YACT,CAAC;YACD,IAAI,CAAC,IAAI;gBAAE,MAAM,IAAI,KAAK,CAAC,sCAAsC,CAAC,GAAG,CAAC,CAAC;YACvE,MAAM,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,CAAC,CAAC,CAAC,MAAM,IAAI,EAAE,CAAC,CAAC,CAAC,IAAI,EAAE,GAAG,EAAE,CAAC,EAAE,CAAC,CAAC;YAC5E,CAAC,GAAG,CAAC,CAAC;YACN,SAAS;QACX,CAAC;QACD,IAAI,EAAE,KAAK,GAAG,EAAE,CAAC;YACf,MAAM,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,GAAG,EAAE,GAAG,EAAE,CAAC,EAAE,CAAC,CAAC;YACnD,CAAC,IAAI,CAAC,CAAC;YACP,SAAS;QACX,CAAC;QACD,IAAI,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC,EAAE,CAAC;YACrB,IAAI,CAAC,GAAG,EAAE,CAAC;YACX,OAAO,CAAC,GAAG,GAAG,CAAC,MAAM,IAAI,QAAQ,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;gBAC/C,CAAC,IAAI,GAAG,CAAC,CAAC,CAAC,CAAC;gBACZ,CAAC,IAAI,CAAC,CAAC;YACT,CAAC;YACD,MAAM,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,KAAK,EAAE,CAAC,EAAE,GAAG,EAAE,CAAC,EAAE,CAAC,CAAC;YAClD,SAAS;QACX,CAAC;QACD,IAAI,YAAY,CAAC,IAAI,CAAC,EAAE,CAAC,EAAE,CAAC;YAC1B,IAAI,CAAC,GAAG,EAAE,CAAC;YACX,OAAO,CAAC,GAAG,GAAG,CAAC,MAAM,IAAI,eAAe,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;gBACtD,CAAC,IAAI,GAAG,CAAC,CAAC,CAAC,CAAC;gBACZ,CAAC,IAAI,CAAC,CAAC;YACT,CAAC;YACD,MAAM,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC,EAAE,GAAG,EAAE,CAAC,EAAE,CAAC,CAAC;YACjD,SAAS;QACX,CAAC;QACD,MAAM,GAAG,GAAG,GAAG,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;QAChC,MAAM,KAAK,GAAG,SAAS,CAAC,IAAI,CAAC,EAAE,CAAC,EAAE,CAAC,GAAG,CAAC,UAAU,CAAC,EAAE,CAAC,CAAC,CAAC;QACvD,IAAI,KAAK,EAAE,CAAC;YACV,MAAM,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,KAAK,EAAE,GAAG,EAAE,CAAC,EAAE,CAAC,CAAC;YAClD,CAAC,IAAI,KAAK,CAAC,MAAM,CAAC;YAClB,SAAS;QACX,CAAC;QACD,IAAI,UAAU,CAAC,QAAQ,CAAC,EAAE,CAAC,EAAE,CAAC;YAC5B,MAAM,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,EAAE,EAAE,GAAG,EAAE,CAAC,EAAE,CAAC,CAAC;YAC/C,CAAC,IAAI,CAAC,CAAC;YACP,SAAS;QACX,CAAC;QACD,IAAI,EAAE,KAAK,GAAG,EAAE,CAAC;YACf,MAAM,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,KAAK,EAAE,EAAE,EAAE,GAAG,EAAE,CAAC,EAAE,CAAC,CAAC;YACnD,CAAC,IAAI,CAAC,CAAC;YACP,SAAS;QACX,CAAC;QACD,IAAI,EAAE,KAAK,GAAG,EAAE,CAAC;YACf,MAAM,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,KAAK,EAAE,EAAE,EAAE,GAAG,EAAE,CAAC,EAAE,CAAC,CAAC;YACnD,CAAC,IAAI,CAAC,CAAC;YACP,SAAS;QACX,CAAC;QACD,IAAI,EAAE,KAAK,GAAG,EAAE,CAAC;YACf,MAAM,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,EAAE,EAAE,GAAG,EAAE,CAAC,EAAE,CAAC,CAAC;YAClD,CAAC,IAAI,CAAC,CAAC;YACP,SAAS;QACX,CAAC;QACD,IAAI,EAAE,KAAK,GAAG,EAAE,CAAC;YACf,MAAM,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,KAAK,EAAE,KAAK,EAAE,EAAE,EAAE,GAAG,EAAE,CAAC,EAAE,CAAC,CAAC;YAChD,CAAC,IAAI,CAAC,CAAC;YACP,SAAS;QACX,CAAC;QACD,MAAM,IAAI,KAAK,CAAC,mCAAmC,EAAE,QAAQ,CAAC,GAAG,CAAC,CAAC;IACrE,CAAC;IACD,MAAM,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,KAAK,EAAE,KAAK,EAAE,EAAE,EAAE,GAAG,EAAE,GAAG,CAAC,MAAM,EAAE,CAAC,CAAC;IACzD,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,wBAAwB;AACxB,MAAM,OAAO,WAAW;IAED;IADb,GAAG,GAAG,CAAC,CAAC;IAChB,YAAqB,MAAe;QAAf,WAAM,GAAN,MAAM,CAAS;IAAG,CAAC;IAExC,IAAI,CAAC,MAAM,GAAG,CAAC;QACb,OAAO,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,GAAG,GAAG,MAAM,EAAE,IAAI,CAAC,MAAM,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC;IAC1E,CAAC;IAED,IAAI;QACF,MAAM,CAAC,GAAG,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QAChC,IAAI,CAAC,CAAC,IAAI,KAAK,KAAK;YAAE,IAAI,CAAC,GAAG,IAAI,CAAC,CAAC;QACpC,OAAO,CAAC,CAAC;IACX,CAAC;IAED,6BAA6B;IAC7B,SAAS,CAAC,IAAY,EAAE,MAAM,GAAG,CAAC;QAChC,MAAM,CAAC,GAAG,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;QAC5B,OAAO,CAAC,CAAC,IAAI,KAAK,OAAO,IAAI,CAAC,CAAC,KAAK,CAAC,WAAW,EAAE,KAAK,IAAI,CAAC;IAC9D,CAAC;IAED,aAAa,CAAC,IAAY;QACxB,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,EAAE,CAAC;YAC1B,MAAM,IAAI,KAAK,CAAC,0BAA0B,IAAI,QAAQ,IAAI,CAAC,IAAI,EAAE,CAAC,KAAK,IAAI,IAAI,CAAC,IAAI,EAAE,CAAC,IAAI,GAAG,CAAC,CAAC;QAClG,CAAC;QACD,IAAI,CAAC,IAAI,EAAE,CAAC;IACd,CAAC;IAED,MAAM,CAAC,IAAe,EAAE,KAAc;QACpC,MAAM,CAAC,GAAG,IAAI,CAAC,IAAI,EAAE,CAAC;QACtB,IAAI,CAAC,CAAC,IAAI,KAAK,IAAI,IAAI,CAAC,KAAK,KAAK,SAAS,IAAI,CAAC,CAAC,KAAK,KAAK,KAAK,CAAC,EAAE,CAAC;YAClE,MAAM,IAAI,KAAK,CACb,0BAA0B,KAAK,IAAI,IAAI,QAAQ,CAAC,CAAC,KAAK,IAAI,CAAC,CAAC,IAAI,GAAG,CACpE,CAAC;QACJ,CAAC;QACD,OAAO,IAAI,CAAC,IAAI,EAAE,CAAC;IACrB,CAAC;IAED,KAAK;QACH,OAAO,IAAI,CAAC,IAAI,EAAE,CAAC,IAAI,KAAK,KAAK,CAAC;IACpC,CAAC;CACF;AAED,+CAA+C;AAE/C,2CAA2C;AAC3C,MAAM,UAAU,aAAa,CAAC,CAAU,EAAE,CAAU;IAClD,+DAA+D;IAC/D,IAAI,CAAC,YAAY,IAAI,IAAI,CAAC,YAAY,IAAI,EAAE,CAAC;QAC3C,MAAM,EAAE,GAAG,QAAQ,CAAC,CAAC,CAAC,CAAC;QACvB,MAAM,EAAE,GAAG,QAAQ,CAAC,CAAC,CAAC,CAAC;QACvB,IAAI,EAAE,KAAK,IAAI,IAAI,EAAE,KAAK,IAAI;YAAE,OAAO,EAAE,GAAG,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,GAAG,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IACxE,CAAC;IACD,MAAM,EAAE,GAAG,QAAQ,CAAC,CAAC,CAAC,CAAC;IACvB,MAAM,EAAE,GAAG,QAAQ,CAAC,CAAC,CAAC,CAAC;IACvB,IAAI,EAAE,KAAK,IAAI,IAAI,EAAE,KAAK,IAAI,EAAE,CAAC;QAC/B,OAAO,EAAE,GAAG,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,GAAG,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IACxC,CAAC;IACD,MAAM,EAAE,GAAG,MAAM,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC;IAC3B,MAAM,EAAE,GAAG,MAAM,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC;IAC3B,OAAO,EAAE,GAAG,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,GAAG,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;AACxC,CAAC;AAED,SAAS,QAAQ,CAAC,CAAU;IAC1B,IAAI,CAAC,YAAY,IAAI;QAAE,OAAO,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC;IAC7E,IAAI,OAAO,CAAC,KAAK,QAAQ;QAAE,OAAO,CAAC,CAAC;IACpC,IAAI,OAAO,CAAC,KAAK,QAAQ,IAAI,CAAC,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC;QAC7C,MAAM,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,OAAO,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC,CAAC;QAC1C,OAAO,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC;IACpC,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED,SAAS,QAAQ,CAAC,CAAU;IAC1B,IAAI,OAAO,CAAC,KAAK,QAAQ;QAAE,OAAO,CAAC,CAAC;IACpC,IAAI,OAAO,CAAC,KAAK,SAAS;QAAE,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IAC7C,IAAI,CAAC,YAAY,IAAI;QAAE,OAAO,CAAC,CAAC,OAAO,EAAE,CAAC;IAC1C,IAAI,OAAO,CAAC,KAAK,QAAQ,IAAI,CAAC,CAAC,IAAI,EAAE,KAAK,EAAE,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC;QAAE,OAAO,MAAM,CAAC,CAAC,CAAC,CAAC;IAC3F,OAAO,IAAI,CAAC;AACd,CAAC;AAED,+BAA+B;AAC/B,MAAM,UAAU,SAAS,CAAC,KAAa,EAAE,OAAe;IACtD,MAAM,OAAO,GAAG,OAAO;SACpB,OAAO,CAAC,qBAAqB,EAAE,MAAM,CAAC;SACtC,OAAO,CAAC,IAAI,EAAE,IAAI,CAAC;SACnB,OAAO,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;IACtB,2CAA2C;IAC3C,OAAO,IAAI,MAAM,CAAC,IAAI,OAAO,GAAG,EAAE,IAAI,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;AACtD,CAAC;AAED,kCAAkC;AAClC,MAAM,UAAU,UAAU,CAAC,CAAU,EAAE,CAAU;IAC/C,IAAI,CAAC,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IACzB,IAAI,CAAC,KAAK,IAAI,IAAI,CAAC,KAAK,SAAS,IAAI,CAAC,KAAK,IAAI,IAAI,CAAC,KAAK,SAAS;QAAE,OAAO,KAAK,CAAC;IACjF,IAAI,CAAC,YAAY,IAAI,IAAI,CAAC,YAAY,IAAI,EAAE,CAAC;QAC3C,MAAM,EAAE,GAAG,CAAC,YAAY,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC;QACnE,MAAM,EAAE,GAAG,CAAC,YAAY,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC;QACnE,OAAO,EAAE,KAAK,EAAE,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;IACxC,CAAC;IACD,MAAM,EAAE,GAAG,QAAQ,CAAC,CAAC,CAAC,CAAC;IACvB,MAAM,EAAE,GAAG,QAAQ,CAAC,CAAC,CAAC,CAAC;IACvB,IAAI,EAAE,KAAK,IAAI,IAAI,EAAE,KAAK,IAAI;QAAE,OAAO,EAAE,KAAK,EAAE,CAAC;IACjD,8DAA8D;IAC9D,yCAAyC;IACzC,IAAI,OAAO,CAAC,KAAK,QAAQ,IAAI,OAAO,CAAC,KAAK,QAAQ;QAAE,OAAO,SAAS,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;IAC3E,OAAO,MAAM,CAAC,CAAC,CAAC,KAAK,MAAM,CAAC,CAAC,CAAC,CAAC;AACjC,CAAC;AAED,qCAAqC;AACrC,SAAS,SAAS,CAAC,CAAU,EAAE,CAAU;IACvC,IAAI,CAAC,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IACzB,IAAI,OAAO,CAAC,KAAK,QAAQ,IAAI,OAAO,CAAC,KAAK,QAAQ,IAAI,CAAC,KAAK,IAAI,IAAI,CAAC,KAAK,IAAI;QAAE,OAAO,KAAK,CAAC;IAC7F,IAAI,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,KAAK,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC;QAAE,OAAO,KAAK,CAAC;IACxD,IAAI,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,CAAC;QACzC,OAAO,CAAC,CAAC,MAAM,KAAK,CAAC,CAAC,MAAM,IAAI,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,SAAS,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IACxE,CAAC;IACD,MAAM,EAAE,GAAG,CAA4B,CAAC;IACxC,MAAM,EAAE,GAAG,CAA4B,CAAC;IACxC,MAAM,EAAE,GAAG,MAAM,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IAC3B,MAAM,EAAE,GAAG,MAAM,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IAC3B,IAAI,EAAE,CAAC,MAAM,KAAK,EAAE,CAAC,MAAM;QAAE,OAAO,KAAK,CAAC;IAC1C,OAAO,EAAE,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,IAAI,EAAE,IAAI,SAAS,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;AAC3D,CAAC;AAED,0DAA0D;AAE1D;;;GAGG;AACH,MAAM,UAAU,YAAY,CAC1B,GAA4B,EAC5B,KAAc,EACd,IAA2B;IAE3B,IAAI,KAAK,KAAK,IAAI,IAAI,KAAK,KAAK,SAAS;QAAE,OAAO,IAAI,CAAC;IACvD,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC;QAAE,OAAO,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,YAAY,CAAC,GAAG,EAAE,CAAC,EAAE,IAAI,CAAC,CAAC,CAAC;IAC7E,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QAC9B,MAAM,IAAI,KAAK,CAAC,gCAAgC,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;IAC3E,CAAC;IACD,KAAK,MAAM,CAAC,GAAG,EAAE,QAAQ,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,KAAgC,CAAC,EAAE,CAAC;QAC/E,MAAM,IAAI,GAAG,IAAI,EAAE,cAAc,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,GAAG,CAAC;QAClD,MAAM,MAAM,GAAG,GAAG,CAAC,IAAI,CAAC,CAAC;QACzB,IAAI,cAAc,CAAC,QAAQ,CAAC,EAAE,CAAC;YAC7B,IAAI,CAAC,gBAAgB,CAAC,QAAQ,EAAE,MAAM,CAAC;gBAAE,OAAO,KAAK,CAAC;YACtD,SAAS;QACX,CAAC;QACD,IAAI,QAAQ,KAAK,IAAI,IAAI,QAAQ,KAAK,SAAS,IAAI,OAAO,QAAQ,KAAK,QAAQ,IAAI,CAAC,CAAC,QAAQ,YAAY,IAAI,CAAC,EAAE,CAAC;YAC/G,MAAM,IAAI,KAAK,CACb,qCAAqC,GAAG,wBAAwB,CACjE,CAAC;QACJ,CAAC;QACD,IAAI,QAAQ,KAAK,IAAI,IAAI,QAAQ,KAAK,SAAS,EAAE,CAAC;YAChD,IAAI,MAAM,KAAK,IAAI,IAAI,MAAM,KAAK,SAAS;gBAAE,OAAO,KAAK,CAAC;YAC1D,SAAS;QACX,CAAC;QACD,IAAI,CAAC,UAAU,CAAC,MAAM,EAAE,QAAQ,CAAC;YAAE,OAAO,KAAK,CAAC;IAClD,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED,SAAS,gBAAgB,CAAC,EAAyB,EAAE,MAAe;IAClE,MAAM,IAAI,GAAG,EAAE,CAAC,IAAI,CAAC;IACrB,MAAM,KAAK,GAAG,EAAE,CAAC,KAAK,CAAC;IACvB,QAAQ,IAAI,EAAE,CAAC;QACb,KAAK,OAAO;YACV,OAAO,UAAU,CAAC,MAAM,EAAE,EAAE,CAAC,KAAK,CAAC,CAAC;QACtC,KAAK,KAAK;YACR,IAAI,KAAK;gBAAE,OAAO,CAAC,gBAAgB,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC;YACnD,OAAO,CAAC,UAAU,CAAC,MAAM,EAAE,EAAE,CAAC,KAAK,CAAC,CAAC;QACvC,KAAK,MAAM;YACT,OAAO,SAAS,CAAC,MAAM,CAAC,MAAM,IAAI,EAAE,CAAC,EAAE,MAAM,CAAC,EAAE,CAAC,KAAK,IAAI,EAAE,CAAC,CAAC,CAAC;QACjE,KAAK,OAAO;YACV,OAAO,SAAS,CAAC,MAAM,CAAC,MAAM,IAAI,EAAE,CAAC,CAAC,WAAW,EAAE,EAAE,MAAM,CAAC,EAAE,CAAC,KAAK,IAAI,EAAE,CAAC,CAAC,WAAW,EAAE,CAAC,CAAC;QAC7F,KAAK,IAAI,CAAC;QACV,KAAK,KAAK,CAAC,CAAC,CAAC;YACX,MAAM,GAAG,GAAG,KAAK,CAAC,OAAO,CAAC,EAAE,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,KAAK,CAAC,CAAC;YAC5D,OAAO,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,UAAU,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,CAAC;QAC9C,CAAC;QACD,KAAK,SAAS,CAAC,CAAC,CAAC;YACf,MAAM,GAAG,GAAG,KAAK,CAAC,OAAO,CAAC,EAAE,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,KAAK,CAAC,CAAC;YAC5D,OAAO,aAAa,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,aAAa,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;QAClF,CAAC;QACD,KAAK,UAAU;YACb,OAAO,MAAM,KAAK,IAAI,IAAI,MAAM,KAAK,SAAS,IAAI,aAAa,CAAC,MAAM,EAAE,EAAE,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;QACxF,KAAK,iBAAiB;YACpB,OAAO,MAAM,KAAK,IAAI,IAAI,MAAM,KAAK,SAAS,IAAI,aAAa,CAAC,MAAM,EAAE,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;QACzF,KAAK,UAAU;YACb,OAAO,MAAM,KAAK,IAAI,IAAI,MAAM,KAAK,SAAS,IAAI,aAAa,CAAC,MAAM,EAAE,EAAE,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;QACxF,KAAK,iBAAiB;YACpB,OAAO,MAAM,KAAK,IAAI,IAAI,MAAM,KAAK,SAAS,IAAI,aAAa,CAAC,MAAM,EAAE,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;QACzF,KAAK,QAAQ;YACX,OAAO,MAAM,KAAK,IAAI,IAAI,MAAM,KAAK,SAAS,CAAC;QACjD,KAAK,KAAK;YACR,MAAM,IAAI,KAAK,CAAC,oDAAoD,CAAC,CAAC;QACxE;YACE,MAAM,IAAI,KAAK,CAAC,uCAAuC,IAAI,EAAE,CAAC,CAAC;IACnE,CAAC;AACH,CAAC"}

package/dist/esm/package.json

@@ -0,0 +1,3 @@
+{
+  "type": "module"
+}

package/examples/01-basic-entity.ts

@@ -0,0 +1,89 @@
+/**
+ * 示例 01：定义实体 + 通过 DataSource 仓储读写
+ *
+ * 演示：
+ *   - 用 TypeORM 装饰器定义实体（表名 + 列名映射）
+ *   - 首次访问前经 configureJsonStorage 注入存储根目录
+ *   - Repository 的 save / find / findOneBy / findAndCount / update / delete
+ *
+ * 运行（需先产出 dist，或直接在本仓库内运行）：
+ *   npx tsx examples/01-basic-entity.ts
+ *
+ * 消费已发布包时，把下方 import 改为：
+ *   import { configureJsonStorage, getJsonDataSource } from '@cicctencent/json-orm';
+ */
+import 'reflect-metadata';
+import { Entity, PrimaryGeneratedColumn, Column, CreateDateColumn, UpdateDateColumn } from 'typeorm';
+import * as os from 'os';
+import * as path from 'path';
+import { configureJsonStorage, getJsonDataSource } from '@cicctencent/json-orm';
+
+@Entity('t_user')
+class User {
+  @PrimaryGeneratedColumn()
+  id!: number;
+
+  @Column({ name: 'Fname', type: 'varchar' })
+  name!: string;
+
+  @Column({ name: 'Fage', type: 'int', nullable: true })
+  age!: number;
+
+  @Column({ name: 'Fcity', type: 'varchar', nullable: true })
+  city!: string;
+
+  @CreateDateColumn({ name: 'Fcreate_time' })
+  createTime!: Date;
+
+  @UpdateDateColumn({ name: 'Fmodify_time' })
+  modifyTime!: Date;
+}
+
+async function main(): Promise<void> {
+  // 1) 首次访问前注入存储根目录（自动构造 FsStorageBackend）
+  configureJsonStorage({ dbDir: path.join(os.tmpdir(), 'json-orm-example-01') });
+
+  const ds = getJsonDataSource();
+  const userRepo = ds.getRepository(User);
+
+  // 2) 新增：save 自动按主键合并 + 填充 createTime / modifyTime；
+  //    自增主键下可不传 id（传 0 也视为未赋值）。
+  const u1 = await userRepo.save({ name: 'Alice', age: 30, city: 'Beijing' });
+  const u2 = await userRepo.save({ name: 'Bob', age: 25, city: 'Shanghai' });
+  console.log('saved ids:', u1.id, u2.id);
+
+  // 3) 全表查询（返回深拷贝，原地修改不会污染磁盘/内存，须 save 才落库）
+  const all = await userRepo.find();
+  console.log('all users:', all);
+
+  // 4) 条件 + 排序 + 分页
+  const beijing = await userRepo.find({
+    where: { city: 'Beijing' },
+    order: { age: 'DESC' },
+    take: 10,
+  });
+  console.log('beijing users:', beijing);
+
+  // 5) 计数 + 分页：findAndCount 返回 [行, 总数]
+  const [page, total] = await userRepo.findAndCount({ skip: 0, take: 1 });
+  console.log('page:', page, 'total:', total);
+
+  // 6) 主键查询
+  const one = await userRepo.findOneBy({ id: u1.id });
+  console.log('findOneBy id:', one);
+
+  // 7) 部分更新：partial 中 undefined 视为「不修改」，不会擦除其它列
+  //    （等价于 TypeORM update 语义，自动刷新 modifyTime）
+  await userRepo.update({ id: u1.id }, { age: 31 });
+  const refreshed = await userRepo.findOneBy({ id: u1.id });
+  console.log('after update:', refreshed);
+
+  // 8) 删除（硬删除）
+  await userRepo.delete({ id: u2.id });
+  console.log('after delete count:', await userRepo.count());
+}
+
+main().catch((e) => {
+  console.error(e);
+  process.exit(1);
+});

package/examples/02-query-builder.ts

@@ -0,0 +1,114 @@
+/**
+ * 示例 02：QueryBuilder（SELECT / 联表 / 聚合）
+ *
+ * 演示：
+ *   - repo.createQueryBuilder(alias) 链式拼装 SELECT
+ *   - 字符串条件用「别名.属性名」，对象条件用属性名（等价 FindOptionsWhere）
+ *   - getMany / getManyAndCount / getRawMany / getRawOne
+ *   - LEFT JOIN + GROUP BY + 聚合函数（COUNT/SUM/MAX/CASE WHEN）
+ *
+ * 运行：
+ *   npx tsx examples/02-query-builder.ts
+ */
+import 'reflect-metadata';
+import { Entity, PrimaryGeneratedColumn, Column, Index } from 'typeorm';
+import * as os from 'os';
+import * as path from 'path';
+import { configureJsonStorage, getJsonDataSource } from '@cicctencent/json-orm';
+
+@Entity('t_article')
+class Article {
+  @PrimaryGeneratedColumn()
+  id!: number;
+
+  @Column({ name: 'Ftitle', type: 'varchar' })
+  title!: string;
+
+  @Column({ name: 'Fauthor', type: 'varchar' })
+  author!: string;
+
+  @Column({ name: 'Fviews', type: 'int', default: 0 })
+  views!: number;
+
+  @Column({ name: 'Fstatus', type: 'varchar', default: 'draft' })
+  status!: string;
+}
+
+@Entity('t_article_tag')
+class ArticleTag {
+  @PrimaryGeneratedColumn()
+  id!: number;
+
+  @Column({ name: 'Farticle_id', type: 'int' })
+  articleId!: number;
+
+  @Column({ name: 'Ftag', type: 'varchar' })
+  tag!: string;
+}
+
+async function main(): Promise<void> {
+  configureJsonStorage({ dbDir: path.join(os.tmpdir(), 'json-orm-example-02') });
+  const ds = getJsonDataSource();
+  const articleRepo = ds.getRepository(Article);
+  const tagRepo = ds.getRepository(ArticleTag);
+
+  await articleRepo.save([
+    { title: 'Hello', author: 'Alice', views: 10, status: 'published' },
+    { title: 'World', author: 'Bob', views: 5, status: 'draft' },
+    { title: 'Foo', author: 'Alice', views: 20, status: 'published' },
+  ]);
+  await tagRepo.save([
+    { articleId: 1, tag: 'ts' },
+    { articleId: 1, tag: 'db' },
+    { articleId: 3, tag: 'ts' },
+  ]);
+
+  // 1) 命名参数 + 排序 + 分页 + 计数
+  const [rows, total] = await articleRepo
+    .createQueryBuilder('a')
+    .where('a.author = :author', { author: 'Alice' })
+    .andWhere('a.status = :status', { status: 'published' })
+    .orderBy('a.views', 'DESC')
+    .skip(0)
+    .take(10)
+    .getManyAndCount();
+  console.log('Alice 已发布文章：', rows, 'total =', total);
+
+  // 2) 对象条件（属性名，等价于 FindOptionsWhere）：未发布草稿
+  const drafts = await articleRepo
+    .createQueryBuilder('a')
+    .where({ status: 'draft' })
+    .getMany();
+  console.log('drafts:', drafts);
+
+  // 3) LEFT JOIN 取每篇文章的标签（原始列投影）
+  const withTags = await articleRepo
+    .createQueryBuilder('a')
+    .leftJoin(ArticleTag, 't', 't.articleId = a.id')
+    .select(['a.id AS id', 'a.title AS title', 't.tag AS tag'])
+    .where('a.author = :author', { author: 'Alice' })
+    .getRawMany();
+  console.log('articles + tags:', withTags);
+
+  // 4) GROUP BY + 聚合：按作者统计文章数与总阅读量
+  const stats = await articleRepo
+    .createQueryBuilder('a')
+    .select('a.author', 'author')
+    .addSelect('COUNT(*)', 'cnt')
+    .addSelect('SUM(a.views)', 'totalViews')
+    .groupBy('a.author')
+    .getRawMany();
+  console.log('per-author stats:', stats);
+
+  // 5) 单值聚合
+  const maxViews = await articleRepo
+    .createQueryBuilder('a')
+    .select('MAX(a.views)', 'maxViews')
+    .getRawOne();
+  console.log('max views:', maxViews);
+}
+
+main().catch((e) => {
+  console.error(e);
+  process.exit(1);
+});

package/examples/03-raw-sql.ts

@@ -0,0 +1,105 @@
+/**
+ * 示例 03：原生 SQL（TypeORM DataSource.query 兼容）
+ *
+ * 演示：
+ *   - ds.query(sql, params) 执行内存 SQL 求值器（MySQL 方言子集）
+ *   - 位置参数（?）与命名参数（:name）两种占位符
+ *   - SELECT / INSERT / UPDATE / DELETE / INSERT ... ON DUPLICATE KEY UPDATE / TRUNCATE
+ *   - 原生 SQL 字符串中的列名使用「数据库列名」(Fxxx)，与实体 @Column({ name }) 对应
+ *   - Repository.upsert 冲突合并（conflictPaths）
+ *
+ * 运行：
+ *   npx tsx examples/03-raw-sql.ts
+ */
+import 'reflect-metadata';
+import { Entity, PrimaryGeneratedColumn, Column, Index } from 'typeorm';
+import * as os from 'os';
+import * as path from 'path';
+import { configureJsonStorage, getJsonDataSource } from '@cicctencent/json-orm';
+
+@Entity('t_product')
+@Index('uk_product_sku', ['sku'], { unique: true })
+class Product {
+  @PrimaryGeneratedColumn()
+  id!: number;
+
+  @Column({ name: 'Fsku', type: 'varchar' })
+  sku!: string;
+
+  @Column({ name: 'Fname', type: 'varchar' })
+  name!: string;
+
+  @Column({ name: 'Fprice', type: 'int' })
+  price!: number;
+
+  @Column({ name: 'Fstock', type: 'int', default: 0 })
+  stock!: number;
+}
+
+async function main(): Promise<void> {
+  configureJsonStorage({ dbDir: path.join(os.tmpdir(), 'json-orm-example-03') });
+  const ds = getJsonDataSource();
+
+  // 通过 Repository 写入几行基线数据（落盘属性名键、SQL 用列名）
+  const repo = ds.getRepository(Product);
+  await repo.save([
+    { sku: 'K1', name: 'A', price: 10, stock: 3 },
+    { sku: 'K2', name: 'B', price: 80, stock: 1 },
+  ]);
+
+  // 1) SELECT：位置参数 + 排序
+  const cheap = await ds.query('SELECT * FROM t_product WHERE Fprice < ? ORDER BY Fprice ASC', [50]);
+  console.log('price < 50:', cheap);
+
+  // 2) SELECT：命名参数（params 显式标注为 Record<string, unknown>，避免与位置参数数组类型混淆）
+  const bySkuParams: Record<string, unknown> = { sku: 'K1' };
+  const bySku = await ds.query('SELECT * FROM t_product WHERE Fsku = :sku', bySkuParams);
+  console.log('sku=K1:', bySku);
+
+  // 3) INSERT
+  await ds.query(
+    'INSERT INTO t_product (Fsku, Fname, Fprice, Fstock) VALUES (?, ?, ?, ?)',
+    ['K3', 'C', 9, 0],
+  );
+
+  // 4) UPDATE：返回 OkPacket 形态（含 affectedRows）；列名做算术。
+  //    位置参数（?）按 SQL 文本顺序绑定：SET 的 ? 取第 1 个参数、WHERE 的 ? 取第 2 个。
+  //    这里改用命名参数（:inc / :sku），两种写法都支持。
+  const updParams: Record<string, unknown> = { inc: 5, sku: 'K1' };
+  const upd = await ds.query(
+    'UPDATE t_product SET Fstock = Fstock + :inc WHERE Fsku = :sku',
+    updParams,
+  );
+  console.log('update affectedRows:', upd.affectedRows);
+
+  // 5) DELETE
+  await ds.query('DELETE FROM t_product WHERE Fprice >= ?', [100]);
+  console.log('after delete count:', await repo.count());
+
+  // 6) INSERT ... ON DUPLICATE KEY UPDATE（按唯一列 upsert）
+  await ds.query(
+    `INSERT INTO t_product (Fsku, Fname, Fprice, Fstock) VALUES (?, ?, ?, ?)
+     ON DUPLICATE KEY UPDATE Fname = VALUES(Fname), Fprice = VALUES(Fprice), Fstock = Fstock + VALUES(Fstock)`,
+    ['K1', 'A2', 12, 7],
+  );
+  console.log('after ODKU:', await ds.query('SELECT * FROM t_product WHERE Fsku = ?', ['K1']));
+
+  // 7) Repository.upsert：按 conflictPaths 冲突合并（undefined 视为不修改）
+  await repo.upsert(
+    [
+      { sku: 'K2', name: 'B2', stock: 9 },
+      { sku: 'K9', name: 'New', price: 5, stock: 2 },
+    ],
+    { conflictPaths: ['sku'] },
+  );
+  console.log('after repo.upsert:', await ds.query('SELECT Fsku, Fname, Fprice, Fstock FROM t_product'));
+
+  // 8) TRUNCATE：返回时已清空落盘
+  await ds.query('TRUNCATE TABLE t_product');
+  console.log('after truncate count:', await repo.count());
+}
+
+main().catch((e) => {
+  console.error(e);
+  process.exit(1);
+});