@mldong/jeeflow 1.6.5 → 1.7.0

package/dist/meta.d.ts

@@ -0,0 +1,78 @@
+import { DatabaseSync } from 'node:sqlite';
+import type { DynamicTableWriter } from './persist.js';
+/** 字段存储类型（对齐 mldong dev_schema_field 1-5 语义） */
+export declare enum StorageType {
+    Normal = 1,// 直写列
+    Expand = 2,// 对象展开为多列（expandFields 定义子字段列映射）
+    Json = 3,// 对象/数组序列化为 JSON 串写列
+    One2One = 4,// 子表单条（外键=主表主键，同事务）
+    One2Many = 5
+}
+/** 解析 storageType：支持名称（"EXPAND"）与数字（2，mldong 语义） */
+export declare function parseStorageType(v: unknown): StorageType;
+/** 字段元数据——表单字段 → 存储语义映射 */
+export interface FieldMeta {
+    name: string;
+    columnName?: string;
+    storageType?: StorageType;
+    expandFields?: Record<string, string>;
+    targetTable?: string;
+    foreignKey?: string;
+}
+/** 表元数据——一张业务表的字段存储规范 */
+export interface TableMeta {
+    tableName: string;
+    primaryKey?: string;
+    fields: FieldMeta[];
+}
+export declare function columnOf(f: FieldMeta): string;
+export declare function pkOf(m: TableMeta): string;
+export declare function findField(m: TableMeta, name: string): FieldMeta | undefined;
+export declare function findFieldByColumn(m: TableMeta, columnName: string): FieldMeta | undefined;
+/** 驼峰转下划线（companyName → company_name） */
+export declare function toUnderline(name: string): string;
+/** 元数据提供者 SPI——集成方只实现这一件事；未定义返回 null（回落表结构探测） */
+export interface IDynamicMetaProvider {
+    loadTableMeta(tableName: string): TableMeta | null;
+}
+/** 内置 JSON 配置加载器——从目录加载（文件名 = 表名，如 biz_leave.json） */
+export declare class JsonMetaProvider implements IDynamicMetaProvider {
+    private dir;
+    private cache;
+    constructor(dir: string);
+    loadTableMeta(tableName: string): TableMeta | null;
+}
+/** 元数据驱动的动态写入器——按 TableMeta.storageType 语义执行插入；
+ *  无元数据时完全委托基础 writer（回落现状，零破坏）。读侧由 MetaTableReader 提供。 */
+export declare class MetaTableWriter implements DynamicTableWriter {
+    private base;
+    private provider;
+    constructor(base: DynamicTableWriter, provider: IDynamicMetaProvider);
+    filterColumns(tableName: string, columns: string[]): string[] | Promise<string[]>;
+    insert(tableName: string, data: Record<string, unknown>): unknown;
+    exists(tableName: string, bizKey: string, bizKeyValue: unknown): boolean | Promise<boolean>;
+    fillSystemFields(data: Record<string, unknown>, isInsert: boolean): void;
+    private expandInto;
+    private insertSubTable;
+    private insertSubRow;
+}
+/** 业务表查询器——按列等值查询原始行（与写入器职责分离） */
+export declare class JdbcTableReader {
+    private db;
+    constructor(db: DatabaseSync);
+    queryFirst(tableName: string, whereColumn: string, value: unknown): Record<string, unknown> | null;
+    queryList(tableName: string, whereColumn: string, value: unknown, limit: number): Record<string, unknown>[];
+}
+/** 元数据驱动的动态读取器——按流程实例回显业务数据。
+ *  边界（不做）：通用条件分页 / 动态条件语法 / 数据权限 / 排序。 */
+export declare class MetaTableReader {
+    private reader;
+    private provider;
+    constructor(reader: JdbcTableReader, provider: IDynamicMetaProvider);
+    readByProcessInstance(tableName: string, processInstanceId: unknown): Record<string, unknown> | null;
+    assemble(meta: TableMeta, row: Record<string, unknown>): Record<string, unknown>;
+    private expandFrom;
+    private readSubTable;
+}
+/** 按列名取值（宽松：忽略大小写） */
+export declare function findRowValue(row: Record<string, unknown>, columnName: string): unknown;

package/dist/meta.js

@@ -0,0 +1,268 @@
+// ═══ 元数据驱动的动态写入/读取规范（issues/23）— 与 Java/Go/Python 契约一致 ═══
+/** 字段存储类型（对齐 mldong dev_schema_field 1-5 语义） */
+export var StorageType;
+(function (StorageType) {
+    StorageType[StorageType["Normal"] = 1] = "Normal";
+    StorageType[StorageType["Expand"] = 2] = "Expand";
+    StorageType[StorageType["Json"] = 3] = "Json";
+    StorageType[StorageType["One2One"] = 4] = "One2One";
+    StorageType[StorageType["One2Many"] = 5] = "One2Many";
+})(StorageType || (StorageType = {}));
+/** 解析 storageType：支持名称（"EXPAND"）与数字（2，mldong 语义） */
+export function parseStorageType(v) {
+    if (typeof v === 'number')
+        return v;
+    if (typeof v === 'string')
+        return StorageType[v] ?? StorageType.Normal;
+    return StorageType.Normal;
+}
+export function columnOf(f) {
+    return f.columnName || toUnderline(f.name);
+}
+export function pkOf(m) {
+    return m.primaryKey || 'id';
+}
+export function findField(m, name) {
+    return m.fields.find(f => f.name.toLowerCase() === name.toLowerCase());
+}
+export function findFieldByColumn(m, columnName) {
+    return m.fields.find(f => columnOf(f).toLowerCase() === columnName.toLowerCase());
+}
+/** 驼峰转下划线（companyName → company_name） */
+export function toUnderline(name) {
+    return name.replace(/([A-Z])/g, (c, _, i) => (i > 0 ? '_' : '') + c.toLowerCase());
+}
+/** 内置 JSON 配置加载器——从目录加载（文件名 = 表名，如 biz_leave.json） */
+export class JsonMetaProvider {
+    dir;
+    cache = new Map();
+    constructor(dir) {
+        this.dir = dir;
+    }
+    loadTableMeta(tableName) {
+        if (this.cache.has(tableName))
+            return this.cache.get(tableName);
+        const data = readFileSyncSafe(`${this.dir}/${tableName}.json`);
+        if (data === null)
+            return null;
+        const raw = JSON.parse(data);
+        const meta = {
+            tableName: raw.tableName ?? tableName,
+            primaryKey: raw.primaryKey ?? 'id',
+            fields: (raw.fields ?? []).map((f) => ({
+                name: f.name,
+                columnName: f.columnName,
+                storageType: parseStorageType(f.storageType ?? 1),
+                expandFields: f.expandFields,
+                targetTable: f.targetTable,
+                foreignKey: f.foreignKey,
+            })),
+        };
+        this.cache.set(tableName, meta);
+        return meta;
+    }
+}
+import { readFileSync } from 'node:fs';
+function readFileSyncSafe(path) {
+    try {
+        return readFileSync(path, 'utf-8');
+    }
+    catch {
+        return null;
+    }
+}
+// ═══ MetaTableWriter（写，纯写职责） ═══════════════════════════════════════════
+/** 元数据驱动的动态写入器——按 TableMeta.storageType 语义执行插入；
+ *  无元数据时完全委托基础 writer（回落现状，零破坏）。读侧由 MetaTableReader 提供。 */
+export class MetaTableWriter {
+    base;
+    provider;
+    constructor(base, provider) {
+        this.base = base;
+        this.provider = provider;
+    }
+    filterColumns(tableName, columns) {
+        return this.base.filterColumns(tableName, columns);
+    }
+    insert(tableName, data) {
+        const meta = this.provider.loadTableMeta(tableName);
+        if (!meta)
+            return this.base.insert(tableName, data); // 无元数据：回落现状
+        const subData = new Map();
+        const row = {};
+        for (const f of meta.fields) {
+            const v = data[f.name];
+            if (v === undefined || v === null)
+                continue;
+            const st = f.storageType ?? StorageType.Normal;
+            if (st === StorageType.Json) {
+                row[columnOf(f)] = JSON.stringify(v);
+            }
+            else if (st === StorageType.Expand) {
+                this.expandInto(f, v, row);
+            }
+            else if (st === StorageType.One2One || st === StorageType.One2Many) {
+                subData.set(f.name, v);
+            }
+            else {
+                row[columnOf(f)] = v;
+            }
+        }
+        // 未消费字段（流程上下文 process_instance_id 等）直通基础 writer
+        for (const [k, v] of Object.entries(data)) {
+            if (!findField(meta, k))
+                row[k] ??= v;
+        }
+        this.base.fillSystemFields(row, true);
+        let pk = this.base.insert(tableName, row); // 主表插入（自增/生成器返回主键）
+        if (pk === undefined || pk === null)
+            pk = findRowValue(row, pkOf(meta));
+        // 子表递归插入（外键=主表主键）
+        for (const [name, v] of subData) {
+            this.insertSubTable(meta, findField(meta, name), v, pk);
+        }
+        return pk;
+    }
+    exists(tableName, bizKey, bizKeyValue) {
+        return this.base.exists(tableName, bizKey, bizKeyValue);
+    }
+    fillSystemFields(data, isInsert) {
+        this.base.fillSystemFields(data, isInsert);
+    }
+    expandInto(f, v, row) {
+        if (typeof v !== 'object' || v === null)
+            return;
+        const obj = v;
+        for (const [sub, col] of Object.entries(f.expandFields ?? {})) {
+            if (obj[sub] !== undefined && obj[sub] !== null)
+                row[col] = obj[sub];
+        }
+    }
+    insertSubTable(parentMeta, f, v, parentPk) {
+        if (parentPk === undefined || parentPk === null) {
+            throw new Error(`persist: parent primary key missing, cannot insert sub table ${f.name}`);
+        }
+        const fk = f.foreignKey || pkOf(parentMeta);
+        const st = f.storageType ?? StorageType.Normal;
+        if (st === StorageType.One2One && typeof v === 'object' && v !== null) {
+            this.insertSubRow(f, v, fk, parentPk);
+        }
+        else if (st === StorageType.One2Many && Array.isArray(v)) {
+            for (const item of v) {
+                if (typeof item === 'object' && item !== null) {
+                    this.insertSubRow(f, item, fk, parentPk);
+                }
+            }
+        }
+    }
+    insertSubRow(f, subData, fk, parentPk) {
+        const row = { ...subData, [fk]: parentPk };
+        this.insert(f.targetTable, row); // 递归走子表自身元数据
+    }
+}
+// ═══ JdbcTableReader（读侧底层） ═══════════════════════════════════════════════
+/** 业务表查询器——按列等值查询原始行（与写入器职责分离） */
+export class JdbcTableReader {
+    db;
+    constructor(db) {
+        this.db = db;
+    }
+    queryFirst(tableName, whereColumn, value) {
+        const rows = this.queryList(tableName, whereColumn, value, 1);
+        return rows.length > 0 ? rows[0] : null;
+    }
+    queryList(tableName, whereColumn, value, limit) {
+        const sql = `SELECT * FROM ${tableName} WHERE ${whereColumn} = ?${limit > 0 ? ` LIMIT ${limit}` : ''}`;
+        return this.db.prepare(sql).all(value);
+    }
+}
+// ═══ MetaTableReader（读，流程回显最小闭环） ═══════════════════════════════════
+/** 元数据驱动的动态读取器——按流程实例回显业务数据。
+ *  边界（不做）：通用条件分页 / 动态条件语法 / 数据权限 / 排序。 */
+export class MetaTableReader {
+    reader;
+    provider;
+    constructor(reader, provider) {
+        this.reader = reader;
+        this.provider = provider;
+    }
+    readByProcessInstance(tableName, processInstanceId) {
+        const row = this.reader.queryFirst(tableName, 'process_instance_id', processInstanceId);
+        if (!row)
+            return null;
+        const meta = this.provider.loadTableMeta(tableName);
+        if (!meta)
+            return row; // 无元数据：原样返回（列名→值）
+        return this.assemble(meta, row);
+    }
+    assemble(meta, row) {
+        const result = {};
+        for (const f of meta.fields) {
+            const v = findRowValue(row, columnOf(f));
+            const st = f.storageType ?? StorageType.Normal;
+            if (st === StorageType.Json) {
+                if (v !== undefined && v !== null) {
+                    try {
+                        result[f.name] = JSON.parse(String(v));
+                    }
+                    catch {
+                        result[f.name] = v;
+                    }
+                }
+            }
+            else if (st === StorageType.Expand) {
+                const obj = this.expandFrom(row, f);
+                if (Object.keys(obj).length > 0)
+                    result[f.name] = obj;
+            }
+            else if (st === StorageType.One2One || st === StorageType.One2Many) {
+                const sub = this.readSubTable(meta, f, row);
+                if (sub !== undefined && sub !== null)
+                    result[f.name] = sub;
+            }
+            else if (v !== undefined && v !== null) {
+                result[f.name] = v;
+            }
+        }
+        // 未在元数据中的列带出（key 统一小写）
+        for (const [k, v] of Object.entries(row)) {
+            if (!findFieldByColumn(meta, k))
+                result[k.toLowerCase()] ??= v;
+        }
+        return result;
+    }
+    expandFrom(row, f) {
+        const obj = {};
+        for (const [sub, col] of Object.entries(f.expandFields ?? {})) {
+            const v = findRowValue(row, col);
+            if (v !== undefined && v !== null)
+                obj[sub] = v;
+        }
+        return obj;
+    }
+    readSubTable(parentMeta, f, row) {
+        const parentPk = findRowValue(row, pkOf(parentMeta));
+        if (parentPk === undefined || parentPk === null)
+            return null;
+        const fk = f.foreignKey || pkOf(parentMeta);
+        const subMeta = this.provider.loadTableMeta(f.targetTable);
+        const st = f.storageType ?? StorageType.Normal;
+        if (st === StorageType.One2One) {
+            const sub = this.reader.queryFirst(f.targetTable, fk, parentPk);
+            if (!sub)
+                return null;
+            return subMeta ? this.assemble(subMeta, sub) : sub;
+        }
+        // ONE2MANY
+        const subs = this.reader.queryList(f.targetTable, fk, parentPk, 0);
+        return subs.map(sub => (subMeta ? this.assemble(subMeta, sub) : sub));
+    }
+}
+/** 按列名取值（宽松：忽略大小写） */
+export function findRowValue(row, columnName) {
+    for (const [k, v] of Object.entries(row)) {
+        if (k.toLowerCase() === columnName.toLowerCase())
+            return v;
+    }
+    return undefined;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mldong/jeeflow",
-  "version": "1.6.5",
+  "version": "1.7.0",
   "description": "jeeflow workflow engine — Node.js / TypeScript implementation",
   "type": "module",
   "main": "./dist/index.js",