@cicctencent/json-orm 0.1.1

package/examples/04-non-entity-table.ts

@@ -0,0 +1,70 @@
+/**
+ * 示例 04：非实体表（仅经原生 SQL 访问）
+ *
+ * 演示：
+ *   - configureJsonStorage({ nonEntityTables }) 注册「无 @Entity 定义、仅原始 SQL 访问」的表
+ *   - 这类表没有实体元数据，只能用 ds.query 读写（无 Repository 投影/属性映射）
+ *   - 列名即数据库列名（无属性名映射层）
+ *   - 配套的 isNonEntityTable / listNonEntityTables 等查询函数
+ *
+ * 运行：
+ *   npx tsx examples/04-non-entity-table.ts
+ */
+import * as os from 'os';
+import * as path from 'path';
+import {
+  configureJsonStorage,
+  getJsonDataSource,
+  isNonEntityTable,
+  listNonEntityTables,
+  getNonEntityPrimaryColumn,
+} from '@cicctencent/json-orm';
+
+async function main(): Promise<void> {
+  // 注册非实体表：表名 → 主键列（与可选唯一列组）
+  configureJsonStorage({
+    dbDir: path.join(os.tmpdir(), 'json-orm-example-04'),
+    nonEntityTables: {
+      t_kv_store: {
+        primaryColumn: 'k',
+        uniqueColumns: [['k']],
+      },
+    },
+  });
+
+  // 注入后可经工具函数查询注册信息
+  console.log('is t_kv_store non-entity:', isNonEntityTable('t_kv_store'));
+  console.log('registered tables:', listNonEntityTables());
+  console.log('primary column:', getNonEntityPrimaryColumn('t_kv_store'));
+
+  const ds = getJsonDataSource();
+
+  // 写入（列名即落盘键）
+  await ds.query('INSERT INTO t_kv_store (k, v, expire_at) VALUES (?, ?, ?)', [
+    'token:1',
+    'secret',
+    '2099-01-01 00:00:00',
+  ]);
+  await ds.query('INSERT INTO t_kv_store (k, v) VALUES (?, ?)', ['config:theme', 'dark']);
+
+  // 读取
+  const rows = await ds.query('SELECT * FROM t_kv_store WHERE k LIKE ?', ['token:%']);
+  console.log('token rows:', rows);
+
+  // 按唯一列 upsert（ODKU）
+  await ds.query(
+    `INSERT INTO t_kv_store (k, v) VALUES (?, ?)
+     ON DUPLICATE KEY UPDATE v = VALUES(v)`,
+    ['config:theme', 'light'],
+  );
+  console.log('after upsert:', await ds.query('SELECT * FROM t_kv_store WHERE k = ?', ['config:theme']));
+
+  // 删除
+  await ds.query('DELETE FROM t_kv_store WHERE k = ?', ['token:1']);
+  console.log('count after delete:', (await ds.query('SELECT COUNT(*) AS c FROM t_kv_store'))[0].c);
+}
+
+main().catch((e) => {
+  console.error(e);
+  process.exit(1);
+});

package/examples/05-custom-backend.ts

@@ -0,0 +1,145 @@
+/**
+ * 示例 05：注入自定义存储后端（ JsonStorageBackend 接口）
+ *
+ * 演示：
+ *   - 引擎全部持久化 I/O 经可注入的 JsonStorageBackend 完成，不直接依赖 fs
+ *   - 实现该异步接口即可把存储指向对象存储（COS/S3）、内存或任意远程后端
+ *   - 注入方式：configureJsonStorage({ backend })（优先于 dbDir）
+ *
+ * 下面给出一个最小可用的「内存后端」实现，便于测试/嵌入与理解接口契约。
+ *
+ * 运行：
+ *   npx tsx examples/05-custom-backend.ts
+ */
+import 'reflect-metadata';
+import { Entity, PrimaryGeneratedColumn, Column } from 'typeorm';
+import {
+  configureJsonStorage,
+  getJsonDataSource,
+  type JsonStorageBackend,
+  type JsonStorageFileStat,
+} from '@cicctencent/json-orm';
+
+/** 最小可用的内存后端：文件存于进程内 Map，序列器独立维护 */
+class MemoryStorageBackend implements JsonStorageBackend {
+  private files = new Map<string, string>();
+  private seq = new Map<string, number>();
+  private chains = new Map<string, Promise<unknown>>();
+
+  async readFile(relPath: string): Promise<string | null> {
+    return this.files.get(relPath) ?? null;
+  }
+
+  async writeFileAtomic(relPath: string, data: string): Promise<void> {
+    this.files.set(relPath, data);
+  }
+
+  async readDir(relPath: string): Promise<string[]> {
+    const prefix = relPath === '' ? '' : relPath.replace(/\/$/, '') + '/';
+    const out = new Set<string>();
+    for (const f of this.files.keys()) {
+      if (prefix && !f.startsWith(prefix)) continue;
+      const rest = f.slice(prefix.length);
+      const slash = rest.indexOf('/');
+      out.add(slash >= 0 ? rest.slice(0, slash) : rest);
+    }
+    return [...out];
+  }
+
+  async deleteFile(relPath: string): Promise<void> {
+    this.files.delete(relPath);
+  }
+
+  async mkdir(_relPath: string): Promise<void> {
+    /* 内存后端无需真实建目录 */
+  }
+
+  async stat(relPath: string): Promise<JsonStorageFileStat | null> {
+    const prefix = relPath === '' ? '' : relPath.replace(/\/$/, '') + '/';
+    let found = prefix === '';
+    if (!found) {
+      for (const f of this.files.keys()) {
+        if (f.startsWith(prefix)) {
+          found = true;
+          break;
+        }
+      }
+    }
+    // 表目录不存在返回 null：引擎视为无变更、不触发重载。
+    // 这里按内容合成 etag 而非返回 Date.now()——后者每次都变，会让引擎
+    // 在每次访问时判定「外部已变更」并整表重载（等于放弃了缓存）
+    return found ? { mtimeMs: Date.now(), size: 0, etag: this.contentEtag(prefix) } : null;
+  }
+
+  /** 按目录内容合成版本标识（内容不变则 etag 不变） */
+  private contentEtag(prefix: string): string {
+    let h = 0;
+    for (const [k, v] of [...this.files.entries()].sort(([a], [b]) => (a < b ? -1 : 1))) {
+      if (prefix && !k.startsWith(prefix)) continue;
+      for (let i = 0; i < v.length; i += 1) {
+        h = (h * 31 + v.charCodeAt(i)) | 0;
+      }
+    }
+    return `mem-${h}`;
+  }
+
+  /** 跨进程临界区：这里用单进程互斥链近似；真实远程后端应改用对象存储的原子锁 */
+  async withLock<T>(relPath: string, fn: () => Promise<T>): Promise<T> {
+    const prev = this.chains.get(relPath) ?? Promise.resolve();
+    let release!: () => void;
+    const next = new Promise<void>((res) => {
+      release = res;
+    });
+    this.chains.set(relPath, prev.then(() => next));
+    await prev;
+    try {
+      return await fn();
+    } finally {
+      release();
+    }
+  }
+
+  /** 后端级原子自增（跨进程唯一主键） */
+  async nextId(relPath: string, key: string): Promise<number> {
+    const k = `${relPath}#${key}`;
+    const cur = this.seq.get(k) ?? 0;
+    const v = cur + 1;
+    this.seq.set(k, v);
+    return v;
+  }
+
+  async ensureSeqAtLeast(relPath: string, key: string, value: number): Promise<void> {
+    const k = `${relPath}#${key}`;
+    const cur = this.seq.get(k) ?? 0;
+    if (value > cur) this.seq.set(k, value);
+  }
+}
+
+@Entity('t_memory_user')
+class MemoryUser {
+  @PrimaryGeneratedColumn()
+  id!: number;
+
+  @Column({ name: 'Fname', type: 'varchar' })
+  name!: string;
+}
+
+async function main(): Promise<void> {
+  // 注入自定义后端（优先于 dbDir）；同进程内其余代码无感知
+  configureJsonStorage({ backend: new MemoryStorageBackend() });
+
+  const ds = getJsonDataSource();
+  const repo = ds.getRepository(MemoryUser);
+
+  const a = await repo.save({ name: 'Alice' });
+  const b = await repo.save({ name: 'Bob' });
+  console.log('saved ids (from memory backend):', a.id, b.id);
+
+  console.log('all:', await repo.find());
+  console.log('count:', await repo.count());
+}
+
+main().catch((e) => {
+  console.error(e);
+  process.exit(1);
+});

package/examples/06-find-operators.ts

@@ -0,0 +1,75 @@
+/**
+ * 示例 06：Repository 查询条件（FindOperator）
+ *
+ * 演示 where 条件支持的对象语法（与 TypeORM FindOptionsWhere 一致）：
+ *   - 数组 = OR
+ *   - In / Like / Not / IsNull / MoreThan / MoreThanOrEqual / LessThan / Between
+ * 属性名即实体字段名（非数据库列名）。
+ *
+ * 运行：
+ *   npx tsx examples/06-find-operators.ts
+ */
+import 'reflect-metadata';
+import {
+  Entity,
+  PrimaryGeneratedColumn,
+  Column,
+  In,
+  Like,
+  Not,
+  IsNull,
+  MoreThan,
+  Between,
+} from 'typeorm';
+import * as os from 'os';
+import * as path from 'path';
+import { configureJsonStorage, getJsonDataSource } from '@cicctencent/json-orm';
+
+@Entity('t_city')
+class City {
+  @PrimaryGeneratedColumn()
+  id!: number;
+
+  @Column({ name: 'Fname', type: 'varchar' })
+  name!: string;
+
+  @Column({ name: 'Fcountry', type: 'varchar' })
+  country!: string;
+
+  @Column({ name: 'Fpopulation', type: 'int' })
+  population!: number;
+}
+
+async function main(): Promise<void> {
+  configureJsonStorage({ dbDir: path.join(os.tmpdir(), 'json-orm-example-06') });
+  const repo = getJsonDataSource().getRepository(City);
+
+  await repo.save([
+    { name: 'Beijing', country: 'CN', population: 21_000_000 },
+    { name: 'Shanghai', country: 'CN', population: 24_000_000 },
+    { name: 'Tokyo', country: 'JP', population: 37_000_000 },
+    { name: 'Paris', country: 'FR', population: 11_000_000 },
+    { name: 'Unknown', country: null as unknown as string, population: 0 },
+  ]);
+
+  console.log('国家为 CN 或 JP：', await repo.find({ where: { country: In(['CN', 'JP']) } }));
+
+  console.log('名字含 "a"（Like 透传 % 通配给求值器）：',
+    await repo.find({ where: { name: Like('%a%') } }));
+
+  console.log('人口 > 20,000,000：', await repo.find({ where: { population: MoreThan(20_000_000) } }));
+
+  console.log('人口在 10M~25M 区间：', await repo.find({ where: { population: Between(10_000_000, 25_000_000) } }));
+
+  console.log('country 为空（IsNull）：', await repo.find({ where: { country: IsNull() } }));
+
+  console.log('country 不为空（Not + IsNull）：', await repo.find({ where: { country: Not(IsNull()) } }));
+
+  console.log('数组 OR：name=Beijing 或 population<5M：',
+    await repo.find({ where: [{ name: 'Beijing' }, { population: MoreThan(5_000_000) }] }));
+}
+
+main().catch((e) => {
+  console.error(e);
+  process.exit(1);
+});

package/examples/README.md

@@ -0,0 +1,73 @@
+# @cicctencent/json-orm 使用示例
+
+本目录是可直接运行的示例，覆盖最常见的接入场景。所有示例都从消费方视角使用
+`@cicctencent/json-orm`（与 README 一致）；在**本仓库内**运行示例前需先产出 `dist`：
+
+```bash
+pnpm --filter @cicctencent/json-orm build
+```
+
+然后用 [tsx](https://github.com/tsx-doten/tsx)（或任意 TS 运行器）执行：
+
+```bash
+npx tsx examples/01-basic-entity.ts
+npx tsx examples/02-query-builder.ts
+npx tsx examples/03-raw-sql.ts
+npx tsx examples/04-non-entity-table.ts
+npx tsx examples/05-custom-backend.ts
+npx tsx examples/06-find-operators.ts
+```
+
+> 若示例改在本仓库内以源码方式运行，把示例顶部的
+> `import { ... } from '@cicctencent/json-orm'` 换成相对源码路径
+> `from '../src/index.ts'` 即可（无需先 `build`）。
+
+## 关键约定（务必先读）
+
+1. **首次访问前必须注入存储配置**：调用 `configureJsonStorage({ dbDir })`
+   或 `configureJsonStorage({ backend })`。未注入时引擎抛明确错误，不静默回退。
+2. **实体用 TypeORM 装饰器定义**：`@Entity('t_xxx')`、`@PrimaryGeneratedColumn()`、
+   `@Column({ name: 'Fxxx' })`、`@CreateDateColumn` / `@UpdateDateColumn`。
+   别忘了在文件顶部 `import 'reflect-metadata'`（装饰器元数据来源）。
+3. **两套命名空间**：
+   - Repository / QueryBuilder **对象条件**用**实体属性名**（如 `city`）。
+   - **原生 SQL 字符串**（`ds.query`）的列名用**数据库列名**（如 `Fcity`），
+     与 `@Column({ name })` 对应。
+4. **合并写语义**：`save` / `update` / `upsert` 的 `partial` 中值为 `undefined`
+   的字段表示「不修改」，与 TypeORM 一致，不会把存量列擦除。
+5. **多进程安全**：序列器与锁写入位于 `<根>/_meta/<表>.json`，不触发表目录失效信号；
+   默认后端 `FsStorageBackend` 已实现孤儿锁回收与序列器水位下限。
+6. **原生 SQL 的位置参数（`?`）按 SQL 文本顺序绑定**（与 MySQL 一致）：解析期为每个
+   `?` 分配语句内序号，绑定结果不受求值顺序/求值次数影响
+   （如 `SET f = f + ? WHERE k = ?` 传入 `[增量, 键]`）。也支持命名参数（`:name`），
+   见 `03-raw-sql.ts`。
+
+## 示例清单
+
+| 文件 | 场景 |
+| --- | --- |
+| `01-basic-entity.ts` | 定义实体 + Repository 的 save/find/findOneBy/findAndCount/update/delete |
+| `02-query-builder.ts` | QueryBuilder：字符串/对象条件、LEFT JOIN、GROUP BY 聚合、分页计数 |
+| `03-raw-sql.ts` | `ds.query`：SELECT/INSERT/UPDATE/DELETE、ODKU upsert、TRUNCATE；位置/命名参数 |
+| `04-non-entity-table.ts` | 非实体表（仅原始 SQL 访问）+ `nonEntityTables` 注册与查询函数 |
+| `05-custom-backend.ts` | 实现 `JsonStorageBackend` 注入自定义（内存）后端，理解接口契约 |
+| `06-find-operators.ts` | Repository `where` 的 FindOperator：In/Like/Not/IsNull/MoreThan/Between、数组 OR |
+
+## 最小可运行骨架
+
+```ts
+import 'reflect-metadata';
+import { Entity, PrimaryGeneratedColumn, Column } from 'typeorm';
+import { configureJsonStorage, getJsonDataSource } from '@cicctencent/json-orm';
+
+@Entity('t_user')
+class User {
+  @PrimaryGeneratedColumn() id!: number;
+  @Column({ name: 'Fname', type: 'varchar' }) name!: string;
+}
+
+configureJsonStorage({ dbDir: './data/db' });
+const userRepo = getJsonDataSource().getRepository(User);
+await userRepo.save({ name: 'Alice' });
+console.log(await userRepo.find());
+```

package/examples/tsconfig.json

@@ -0,0 +1,20 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "lib": ["ES2022"],
+    "strict": false,
+    "esModuleInterop": true,
+    "allowSyntheticDefaultImports": true,
+    "resolveJsonModule": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "noEmit": true,
+    "experimentalDecorators": true,
+    "emitDecoratorMetadata": true,
+    "types": ["node", "reflect-metadata"]
+  },
+  "include": ["./**/*.ts"],
+  "exclude": ["../dist"]
+}

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@cicctencent/json-orm",
+  "version": "0.1.1",
+  "description": "TypeORM-compatible JSON file storage engine — datasource facade, repository shim, query builder and in-memory SQL evaluator, with injectable storage root (framework-agnostic).",
+  "type": "module",
+  "main": "./dist/cjs/index.js",
+  "module": "./dist/esm/index.js",
+  "types": "./dist/esm/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/esm/index.d.ts",
+      "import": "./dist/esm/index.js",
+      "require": "./dist/cjs/index.js"
+    },
+    "./*.js": {
+      "types": "./dist/esm/*.d.ts",
+      "import": "./dist/esm/*.js",
+      "require": "./dist/cjs/*.js"
+    }
+  },
+  "scripts": {
+    "build": "npm run build:esm && npm run build:cjs && npm run build:fixup",
+    "build:esm": "tsc -p tsconfig.esm.json",
+    "build:cjs": "tsc -p tsconfig.cjs.json",
+    "build:fixup": "node scripts/fixup-cjs.js",
+    "typecheck": "tsc -p tsconfig.esm.json --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "prepublishOnly": "npm run build"
+  },
+  "peerDependencies": {
+    "reflect-metadata": "^0.2.2",
+    "typeorm": "^0.3.31"
+  },
+  "devDependencies": {
+    "@types/node": "^22.20.1",
+    "reflect-metadata": "^0.2.2",
+    "typeorm": "^0.3.31",
+    "typescript": "~5.8.3",
+    "vitest": "^2.1.9"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "files": [
+    "dist/**/*",
+    "examples/**/*",
+    "README.md",
+    "package.json"
+  ],
+  "license": "MIT"
+}