@yss123/cage-kernel 0.0.0-stage → 0.2.0

package/dist/primitives/flow.js

@@ -0,0 +1,90 @@
+import { z } from 'zod';
+import { APPROVAL, JOB, QUERY, REACTION, UNSAFE } from '../brands.js';
+import { declError } from '../errors.js';
+export function reaction(ev, def) {
+    if (def.target && def.target !== def.command.agg) {
+        throw declError('CAGE-REACT-001', `反应的 target 与 command 所属聚合不一致`);
+    }
+    return Object.freeze({
+        [REACTION]: true,
+        event: ev,
+        command: def.command,
+        target: def.command.agg,
+        map: def.map,
+        tx: def.tx ?? 'outbox',
+        acquires: def.acquires,
+        releases: def.releases,
+        name: def.name,
+    });
+}
+export function query(name, def) {
+    if (!/^[a-z][A-Za-z0-9]*$/.test(name))
+        throw declError('CAGE-NAME-005', `查询名 ${name} 必须是小驼峰`);
+    if (!def.sql === !def.build)
+        throw declError('CAGE-QUERY-001', `查询 ${name} 必须二选一：sql 或 build`);
+    if (def.sql && /\bcore\.|\bsys\./i.test(def.sql)) {
+        throw declError('CAGE-QUERY-002', `查询 ${name} 引用了基表，只能引用 safe.* 安全视图`);
+    }
+    return Object.freeze({
+        [QUERY]: true,
+        name,
+        reads: Object.freeze([...def.reads]),
+        input: (def.input ?? z.object({})),
+        sql: def.sql,
+        build: def.build,
+        description: def.description,
+    });
+}
+export function approval(agg, def) {
+    for (const f of def.routable) {
+        if (!(f in agg.fields))
+            throw declError('CAGE-APPR-001', `可路由字段 ${agg.name}.${f} 不存在`);
+    }
+    for (const c of [def.onApproved, def.onRejected]) {
+        if (c.agg !== agg)
+            throw declError('CAGE-APPR-002', `审批结论命令必须属于 ${agg.name}`);
+        if (!c.invokedBy.includes('process')) {
+            throw declError('CAGE-APPR-003', `审批结论命令必须声明 invokedBy: 'process'`);
+        }
+    }
+    return Object.freeze({
+        [APPROVAL]: true,
+        agg,
+        process: def.process,
+        start: def.start,
+        cancelOn: Object.freeze([...(def.cancelOn ?? [])]),
+        routable: Object.freeze([...def.routable]),
+        onApproved: def.onApproved,
+        onRejected: def.onRejected,
+    });
+}
+export function job(name, def) {
+    if (!/^[a-z][A-Za-z0-9]*$/.test(name))
+        throw declError('CAGE-NAME-006', `任务名 ${name} 必须是小驼峰`);
+    if (def.cron.trim().split(/\s+/).length < 5)
+        throw declError('CAGE-JOB-001', `任务 ${name} 的 cron 表达式不合法`);
+    return Object.freeze({
+        [JOB]: true,
+        name,
+        cron: def.cron,
+        reads: Object.freeze([...(def.reads ?? [])]),
+        calls: Object.freeze([...(def.calls ?? [])]),
+        run: def.run,
+        description: def.description,
+    });
+}
+/** 前 N 天 */
+export function daysAgo(n, from = new Date()) {
+    return new Date(from.getTime() - n * 24 * 3600 * 1000);
+}
+/**
+ * 逃生口：声明表达不了时使用，必须写明原因和负责人。lint 检查参数，计数进 PR 摘要。
+ *   const v = unsafe({ reason: '…', owner: 'zhangsan' }, () => …)
+ */
+export function unsafe(tag, fn) {
+    if (!tag?.reason || !tag?.owner)
+        throw declError('CAGE-UNSAFE-001', 'unsafe 必须写明 reason 和 owner');
+    return fn();
+}
+unsafe[UNSAFE] = true;
+//# sourceMappingURL=flow.js.map

package/dist/primitives/flow.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"flow.js","sourceRoot":"","sources":["../../src/primitives/flow.ts"],"names":[],"mappings":"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"}

package/dist/primitives/states.d.ts

@@ -0,0 +1,19 @@
+import { STATES } from '../brands.js';
+export interface StatesDef<S extends string = string> {
+    readonly [STATES]: true;
+    readonly values: readonly S[];
+    readonly terminal: readonly S[];
+    readonly initial: S;
+}
+type StatesOpts<S extends string> = {
+    terminal?: NoInfer<S>[];
+    initial?: NoInfer<S>;
+};
+/**
+ * states('draft', 'pending_approval', 'approved', { terminal: ['approved'] })
+ */
+export declare function states<const S extends string>(...args: [...S[]] | [...S[], StatesOpts<S>]): StatesDef<S>;
+export declare function isStates(v: unknown): v is StatesDef;
+/** 没有声明状态的聚合使用默认生命周期：active → deleted（业务数据不物理删除） */
+export declare const DEFAULT_STATES: StatesDef<string>;
+export {};

package/dist/primitives/states.js

@@ -0,0 +1,37 @@
+// states 原语：有限状态集，可标记终态。第一个状态是新建命令的默认初始状态。
+import { STATES } from '../brands.js';
+import { declError } from '../errors.js';
+/**
+ * states('draft', 'pending_approval', 'approved', { terminal: ['approved'] })
+ */
+export function states(...args) {
+    const all = args;
+    const last = all[all.length - 1];
+    const opts = (typeof last === 'object' && last !== null ? last : {});
+    const values = all.filter((a) => typeof a === 'string');
+    if (values.length === 0)
+        throw declError('CAGE-STATE-002', 'states() 至少需要一个状态');
+    for (const v of values) {
+        if (!/^[a-z][a-z0-9_]*$/.test(v))
+            throw declError('CAGE-STATE-003', `状态名 ${v} 必须是小写下划线`);
+    }
+    if (new Set(values).size !== values.length)
+        throw declError('CAGE-STATE-004', '状态名重复');
+    const terminal = opts.terminal ?? [];
+    for (const t of [...terminal, ...(opts.initial ? [opts.initial] : [])]) {
+        if (!values.includes(t))
+            throw declError('CAGE-STATE-001', `状态 ${t} 未在 states 中声明`);
+    }
+    return Object.freeze({
+        [STATES]: true,
+        values: Object.freeze([...values]),
+        terminal: Object.freeze([...terminal]),
+        initial: (opts.initial ?? values[0]),
+    });
+}
+export function isStates(v) {
+    return !!v && typeof v === 'object' && v[STATES] === true;
+}
+/** 没有声明状态的聚合使用默认生命周期：active → deleted（业务数据不物理删除） */
+export const DEFAULT_STATES = states('active', 'deleted', { terminal: ['deleted'] });
+//# sourceMappingURL=states.js.map

package/dist/primitives/states.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"states.js","sourceRoot":"","sources":["../../src/primitives/states.ts"],"names":[],"mappings":"AAAA,2CAA2C;AAC3C,OAAO,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AACtC,OAAO,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAWzC;;GAEG;AACH,MAAM,UAAU,MAAM,CAAyB,GAAG,IAAwC;IACxF,MAAM,GAAG,GAAG,IAAiB,CAAC;IAC9B,MAAM,IAAI,GAAG,GAAG,CAAC,GAAG,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;IACjC,MAAM,IAAI,GAAG,CAAC,OAAO,IAAI,KAAK,QAAQ,IAAI,IAAI,KAAK,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAoC,CAAC;IACxG,MAAM,MAAM,GAAG,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,EAAU,EAAE,CAAC,OAAO,CAAC,KAAK,QAAQ,CAAC,CAAC;IAChE,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC;QAAE,MAAM,SAAS,CAAC,gBAAgB,EAAE,mBAAmB,CAAC,CAAC;IAChF,KAAK,MAAM,CAAC,IAAI,MAAM,EAAE,CAAC;QACvB,IAAI,CAAC,mBAAmB,CAAC,IAAI,CAAC,CAAC,CAAC;YAAE,MAAM,SAAS,CAAC,gBAAgB,EAAE,OAAO,CAAC,WAAW,CAAC,CAAC;IAC3F,CAAC;IACD,IAAI,IAAI,GAAG,CAAC,MAAM,CAAC,CAAC,IAAI,KAAK,MAAM,CAAC,MAAM;QAAE,MAAM,SAAS,CAAC,gBAAgB,EAAE,OAAO,CAAC,CAAC;IACvF,MAAM,QAAQ,GAAG,IAAI,CAAC,QAAQ,IAAI,EAAE,CAAC;IACrC,KAAK,MAAM,CAAC,IAAI,CAAC,GAAG,QAAQ,EAAE,GAAG,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC;QACvE,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC;YAAE,MAAM,SAAS,CAAC,gBAAgB,EAAE,MAAM,CAAC,gBAAgB,CAAC,CAAC;IACtF,CAAC;IACD,OAAO,MAAM,CAAC,MAAM,CAAC;QACnB,CAAC,MAAM,CAAC,EAAE,IAAa;QACvB,MAAM,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC,GAAG,MAAM,CAAC,CAAC;QAClC,QAAQ,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC,GAAG,QAAQ,CAAC,CAAC;QACtC,OAAO,EAAE,CAAC,IAAI,CAAC,OAAO,IAAI,MAAM,CAAC,CAAC,CAAC,CAAM;KAC1C,CAAC,CAAC;AACL,CAAC;AAED,MAAM,UAAU,QAAQ,CAAC,CAAU;IACjC,OAAO,CAAC,CAAC,CAAC,IAAI,OAAO,CAAC,KAAK,QAAQ,IAAK,CAAS,CAAC,MAAM,CAAC,KAAK,IAAI,CAAC;AACrE,CAAC;AAED,oDAAoD;AACpD,MAAM,CAAC,MAAM,cAAc,GAAG,MAAM,CAAC,QAAQ,EAAE,SAAS,EAAE,EAAE,QAAQ,EAAE,CAAC,SAAS,CAAC,EAAE,CAAC,CAAC"}

package/dist/read.d.ts

@@ -0,0 +1,53 @@
+import { type Transaction } from 'kysely';
+import { z } from 'zod';
+import type { Kernel } from './kernel.js';
+import { type AnyAggregate } from './primitives/aggregate.js';
+import type { AnyQuery } from './primitives/flow.js';
+import type { Ctx } from './types.js';
+export interface ListParams {
+    page?: number | string;
+    pageSize?: number | string;
+    /** 排序：字段名，前面加 - 表示倒序，例如 -createdAt */
+    sort?: string;
+    createdAfter?: string;
+    createdBefore?: string;
+    /** 其他键：字段等值过滤；status 可以逗号分隔多个 */
+    [field: string]: unknown;
+}
+export interface Page<T> {
+    items: T[];
+    total: number;
+    page: number;
+    pageSize: number;
+}
+export declare class ReadSide {
+    private readonly k;
+    constructor(k: Kernel);
+    /** 读侧账号上的只读事务，已写入会话变量 */
+    tx<T>(ctx: Ctx, fn: (tx: Transaction<any>) => Promise<T>, isolation?: 'read committed' | 'repeatable read'): Promise<T>;
+    private agg;
+    private need;
+    /** 明文读取敏感字段要写读审计 */
+    private auditUnmask;
+    get(a: AnyAggregate | string, id: string, ctx: Ctx): Promise<Record<string, any>>;
+    list(a: AnyAggregate | string, params: ListParams, ctx: Ctx): Promise<Page<Record<string, any>>>;
+    /** 关联按需分页：先确认所属对象可见，再从目标安全视图读取；两侧能力、范围和掩码都生效。 */
+    related(a: AnyAggregate | string, id: string, fieldName: string, params: ListParams, ctx: Ctx): Promise<Page<Record<string, any>>>;
+    private listIn;
+    /**
+     * worker 使用的导出构建器：同一只读快照内分批读取，避免翻页期间数据变化导致漏行或重复。
+     * 上限用于约束单任务内存与数据库文件存储；超限明确失败，绝不能静默截断成“成功文件”。
+     * HTTP 只提交任务，保留本方法供受控的服务端调用。
+     */
+    export(a: AnyAggregate | string, params: ListParams, ctx: Ctx): Promise<{
+        filename: string;
+        contentType: string;
+        body: string;
+        rows: number;
+    }>;
+    /** 执行 query 声明：需要 reads 里每个聚合的 read 能力；手写 SQL 用 :name 占位，全部参数化 */
+    run(q: AnyQuery | string, raw: unknown, ctx: Ctx): Promise<Record<string, any>[]>;
+}
+/** :name 占位 → 参数化 SQL（:: 类型转换不受影响） */
+export declare function compileNamedSql(text: string, input: Record<string, unknown>): import("kysely").RawBuilder<Record<string, unknown>>;
+export declare const listParamsSchema: z.ZodRecord<z.ZodString, z.ZodUnknown>;

package/dist/read.js

@@ -0,0 +1,217 @@
+// 读侧：只用读侧账号，只查 safe 模式下的安全视图；内核在只读事务开头写会话变量，
+// 行级策略和掩码由数据库兜底。忘了设置上下文时一条都查不到。
+import { sql } from 'kysely';
+import { z } from 'zod';
+import { viewRowToObject } from './db/rows.js';
+import { setSessionVars } from './db/session.js';
+import { cageError } from './errors.js';
+import { hiddenFields, sensitiveFields } from './primitives/aggregate.js';
+import { isRelation } from './primitives/fields.js';
+import { snake } from './util/names.js';
+import { csvCell } from './transfer/csv.js';
+import { relationTable } from './relations.js';
+const SYS = { id: 'id', status: 'status', version: 'version', createdAt: 'created_at', updatedAt: 'updated_at' };
+const RESERVED = new Set(['page', 'pageSize', 'sort', 'createdAfter', 'createdBefore']);
+function coerce(kind, v) {
+    if (typeof v !== 'string')
+        return v;
+    if (kind === 'int' || kind === 'number')
+        return Number(v);
+    if (kind === 'bool')
+        return v === 'true';
+    return v;
+}
+export class ReadSide {
+    k;
+    constructor(k) {
+        this.k = k;
+    }
+    /** 读侧账号上的只读事务，已写入会话变量 */
+    async tx(ctx, fn, isolation = 'read committed') {
+        return this.k.readDb
+            .transaction()
+            .setIsolationLevel(isolation)
+            .setAccessMode('read only')
+            .execute(async (tx) => {
+            await setSessionVars(tx, ctx);
+            return fn(tx);
+        });
+    }
+    agg(a) {
+        const agg = typeof a === 'string' ? this.k.registry.aggregate(a) : a;
+        if (!agg)
+            throw cageError('NOT_FOUND');
+        return agg;
+    }
+    need(ctx, cap) {
+        if (!ctx.actor || ctx.actor.kind === 'anonymous')
+            throw cageError('UNAUTHENTICATED');
+        if (!ctx.capabilities.has(cap))
+            throw cageError('FORBIDDEN', { capability: cap });
+    }
+    /** 明文读取敏感字段要写读审计 */
+    async auditUnmask(agg, ctx, ids, kind) {
+        const kinds = [...new Set(Object.values(sensitiveFields(agg)))].filter((x) => ctx.unmask.includes(`${agg.name}.${x}`) || ctx.unmask.includes(`*.${x}`));
+        if (kind === 'read' && kinds.length === 0)
+            return;
+        await this.k.writeAudit(this.k.app, {
+            tenantId: ctx.tenantId, actor: ctx.actor?.id ?? 'anonymous', actorKind: ctx.actor?.kind ?? 'anonymous',
+            onBehalfOf: ctx.onBehalfOf ?? null, source: ctx.source, kind: 'read',
+            capability: `${agg.name}.${kind}`, command: null, aggregate: agg.name,
+            aggregateId: ids.length === 1 ? ids[0] : null, result: 'ok',
+            diff: { unmasked: kinds, rows: ids.length }, requestId: ctx.requestId ?? null, client: ctx.client ?? null,
+        }).catch((e) => {
+            // 导出会产生可离线保存的文件，审计失败不能交付文件；交给任务系统重试。
+            if (kind === 'export')
+                throw e;
+            this.k.log.warn({ err: String(e) }, '读审计写入失败');
+        });
+    }
+    async get(a, id, ctx) {
+        const agg = this.agg(a);
+        this.need(ctx, `${agg.name}.read`);
+        if (!/^[0-9a-f-]{36}$/i.test(id))
+            throw cageError('NOT_FOUND');
+        const row = await this.tx(ctx, (tx) => tx.selectFrom(`safe.${agg.table.name}`).selectAll().where('id', '=', id).executeTakeFirst());
+        if (!row)
+            throw cageError('NOT_FOUND');
+        void this.auditUnmask(agg, ctx, [id], 'read');
+        return viewRowToObject(row);
+    }
+    async list(a, params, ctx) {
+        const agg = this.agg(a);
+        this.need(ctx, `${agg.name}.read`);
+        const res = await this.tx(ctx, (tx) => this.listIn(tx, agg, params, 200));
+        void this.auditUnmask(agg, ctx, res.items.map((r) => r.id), 'read');
+        return res;
+    }
+    /** 关联按需分页：先确认所属对象可见，再从目标安全视图读取；两侧能力、范围和掩码都生效。 */
+    async related(a, id, fieldName, params, ctx) {
+        const owner = this.agg(a), field = owner.fields[fieldName];
+        this.need(ctx, `${owner.name}.read`);
+        if (!field || !isRelation(field) || !/^[0-9a-f-]{36}$/i.test(id))
+            throw cageError('NOT_FOUND');
+        const target = this.agg(field.ref);
+        this.need(ctx, `${target.name}.read`);
+        const res = await this.tx(ctx, async (tx) => {
+            const source = await tx.selectFrom(`safe.${owner.table.name}`).select('id').where('id', '=', id).where('status', '<>', 'deleted').executeTakeFirst();
+            if (!source)
+                throw cageError('NOT_FOUND');
+            const table = relationTable(owner, fieldName);
+            const restrict = field.kind === 'hasMany'
+                ? (q) => q.where(sql.ref(snake(field.mappedBy)), '=', id)
+                : (q) => q.where('id', 'in', tx.selectFrom(`safe.${table.name}`).select('target_id').where('source_id', '=', id));
+            return this.listIn(tx, target, params, 200, true, restrict);
+        }, 'repeatable read');
+        void this.auditUnmask(target, ctx, res.items.map((row) => row.id), 'read');
+        return res;
+    }
+    async listIn(tx, agg, params, maxPageSize, count = true, restrict = (q) => q) {
+        const page = Math.max(1, Number(params.page ?? 1) || 1);
+        const pageSize = Math.min(maxPageSize, Math.max(1, Number(params.pageSize ?? 20) || 20));
+        const hidden = new Set(hiddenFields(agg));
+        const view = `safe.${agg.table.name}`;
+        const apply = (q) => {
+            for (const [k, v] of Object.entries(params)) {
+                if (RESERVED.has(k) || v === undefined || v === '')
+                    continue;
+                const f = agg.fields[k];
+                const col = SYS[k] ?? (f && !isRelation(f) && !hidden.has(k) && f.sql !== 'jsonb' && !f.sensitiveKind ? snake(k) : undefined);
+                if (!col)
+                    throw cageError('INVALID_INPUT', [{ path: k, message: `不能按 ${k} 过滤` }]);
+                if (k === 'status' && typeof v === 'string' && v.includes(','))
+                    q = q.where('status', 'in', v.split(','));
+                else
+                    q = q.where(sql.ref(col), '=', coerce(f?.kind ?? 'text', v));
+            }
+            if (params.status === undefined)
+                q = q.where('status', '<>', 'deleted');
+            if (params.createdAfter)
+                q = q.where('created_at', '>=', new Date(String(params.createdAfter)));
+            if (params.createdBefore)
+                q = q.where('created_at', '<', new Date(String(params.createdBefore)));
+            return restrict(q);
+        };
+        let q = apply(tx.selectFrom(view).selectAll());
+        const sortKey = typeof params.sort === 'string' && params.sort ? params.sort.replace(/^-/, '') : 'createdAt';
+        const sortField = agg.fields[sortKey];
+        const sortCol = SYS[sortKey] ?? (sortField && !isRelation(sortField) && !hidden.has(sortKey) ? snake(sortKey) : undefined);
+        if (!sortCol)
+            throw cageError('INVALID_INPUT', [{ path: 'sort', message: `不能按 ${sortKey} 排序` }]);
+        const desc = typeof params.sort === 'string' ? params.sort.startsWith('-') : true;
+        q = q.orderBy(sql.ref(sortCol), desc ? 'desc' : 'asc').orderBy('id').limit(pageSize).offset((page - 1) * pageSize);
+        const rows = await q.execute();
+        const cnt = count ? await apply(tx.selectFrom(view).select(sql `count(*)::int`.as('n'))).executeTakeFirst() : null;
+        return { items: rows.map(viewRowToObject), total: Number(cnt?.n ?? 0), page, pageSize };
+    }
+    /**
+     * worker 使用的导出构建器：同一只读快照内分批读取，避免翻页期间数据变化导致漏行或重复。
+     * 上限用于约束单任务内存与数据库文件存储；超限明确失败，绝不能静默截断成“成功文件”。
+     * HTTP 只提交任务，保留本方法供受控的服务端调用。
+     */
+    async export(a, params, ctx) {
+        const agg = this.agg(a);
+        this.need(ctx, `${agg.name}.export`);
+        const cols = ['id', ...Object.entries(agg.fields).filter(([, f]) => !f.isHidden && !isRelation(f)).map(([k]) => k), 'status', 'version', 'createdAt', 'updatedAt'];
+        const lines = ['\uFEFF' + cols.map(csvCell).join(',')], ids = [];
+        let bytes = Buffer.byteLength(lines[0]);
+        await this.tx(ctx, async (tx) => {
+            let total = 0;
+            for (let page = 1; page === 1 || ids.length < total; page++) {
+                const res = await this.listIn(tx, agg, { ...params, page, pageSize: 1000 }, 1000, page === 1);
+                if (page === 1)
+                    total = res.total;
+                if (total > 100_000)
+                    throw cageError('INVALID_INPUT', '导出最多支持 100000 行，请缩小筛选范围');
+                for (const row of res.items) {
+                    const line = cols.map((c) => csvCell(row[c])).join(',');
+                    bytes += Buffer.byteLength(line) + 1;
+                    if (bytes > 20 * 1024 * 1024)
+                        throw cageError('INVALID_INPUT', '导出文件超过 20 MiB，请缩小筛选范围');
+                    lines.push(line);
+                    ids.push(row.id);
+                }
+            }
+        }, 'repeatable read');
+        await this.auditUnmask(agg, ctx, ids, 'export');
+        return { filename: `${agg.table.name}.csv`, contentType: 'text/csv; charset=utf-8', body: lines.join('\n'), rows: ids.length };
+    }
+    /** 执行 query 声明：需要 reads 里每个聚合的 read 能力；手写 SQL 用 :name 占位，全部参数化 */
+    async run(q, raw, ctx) {
+        const query = typeof q === 'string' ? this.k.registry.queries.find((x) => x.name === q) : q;
+        if (!query)
+            throw cageError('NOT_FOUND');
+        for (const a of query.reads)
+            this.need(ctx, `${a.name}.read`);
+        const parsed = query.input.safeParse(raw ?? {});
+        if (!parsed.success)
+            throw cageError('INVALID_INPUT', parsed.error.issues.map((i) => ({ path: i.path.join('.'), message: i.message })));
+        const input = parsed.data;
+        const rows = await this.tx(ctx, async (tx) => {
+            if (query.build)
+                return (await query.build(tx, input).execute());
+            const compiled = compileNamedSql(query.sql, input);
+            const r = await compiled.execute(tx);
+            return r.rows;
+        });
+        return rows.map(viewRowToObject);
+    }
+}
+/** :name 占位 → 参数化 SQL（:: 类型转换不受影响） */
+export function compileNamedSql(text, input) {
+    const parts = [];
+    const re = /(?<![:\w]):([a-zA-Z_][a-zA-Z0-9_]*)/g;
+    let last = 0;
+    let m;
+    while ((m = re.exec(text))) {
+        parts.push(sql.raw(text.slice(last, m.index)));
+        if (!(m[1] in input))
+            throw cageError('INVALID_INPUT', [{ path: m[1], message: `缺少查询参数 ${m[1]}` }]);
+        parts.push(sql `${input[m[1]]}`);
+        last = m.index + m[0].length;
+    }
+    parts.push(sql.raw(text.slice(last)));
+    return sql `${sql.join(parts, sql.raw(''))}`;
+}
+export const listParamsSchema = z.record(z.string(), z.unknown());
+//# sourceMappingURL=read.js.map

package/dist/read.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"read.js","sourceRoot":"","sources":["../src/read.ts"],"names":[],"mappings":"AAAA,6CAA6C;AAC7C,gCAAgC;AAChC,OAAO,EAAe,GAAG,EAAoB,MAAM,QAAQ,CAAC;AAC5D,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAC/C,OAAO,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AACjD,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAExC,OAAO,EAAqB,YAAY,EAAE,eAAe,EAAE,MAAM,2BAA2B,CAAC;AAC7F,OAAO,EAAE,UAAU,EAAe,MAAM,wBAAwB,CAAC;AAGjE,OAAO,EAAE,KAAK,EAAE,MAAM,iBAAiB,CAAC;AACxC,OAAO,EAAE,OAAO,EAAE,MAAM,mBAAmB,CAAC;AAC5C,OAAO,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAoB/C,MAAM,GAAG,GAA2B,EAAE,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,OAAO,EAAE,SAAS,EAAE,SAAS,EAAE,YAAY,EAAE,SAAS,EAAE,YAAY,EAAE,CAAC;AACzI,MAAM,QAAQ,GAAG,IAAI,GAAG,CAAC,CAAC,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,cAAc,EAAE,eAAe,CAAC,CAAC,CAAC;AAExF,SAAS,MAAM,CAAC,IAAY,EAAE,CAAU;IACtC,IAAI,OAAO,CAAC,KAAK,QAAQ;QAAE,OAAO,CAAC,CAAC;IACpC,IAAI,IAAI,KAAK,KAAK,IAAI,IAAI,KAAK,QAAQ;QAAE,OAAO,MAAM,CAAC,CAAC,CAAC,CAAC;IAC1D,IAAI,IAAI,KAAK,MAAM;QAAE,OAAO,CAAC,KAAK,MAAM,CAAC;IACzC,OAAO,CAAC,CAAC;AACX,CAAC;AAED,MAAM,OAAO,QAAQ;IACU;IAA7B,YAA6B,CAAS;QAAT,MAAC,GAAD,CAAC,CAAQ;IAAG,CAAC;IAE1C,yBAAyB;IACzB,KAAK,CAAC,EAAE,CAAI,GAAQ,EAAE,EAAwC,EAAE,YAAkD,gBAAgB;QAChI,OAAO,IAAI,CAAC,CAAC,CAAC,MAAM;aACjB,WAAW,EAAE;aACb,iBAAiB,CAAC,SAAS,CAAC;aAC5B,aAAa,CAAC,WAAW,CAAC;aAC1B,OAAO,CAAC,KAAK,EAAE,EAAE,EAAE,EAAE;YACpB,MAAM,cAAc,CAAC,EAAE,EAAE,GAAG,CAAC,CAAC;YAC9B,OAAO,EAAE,CAAC,EAAE,CAAC,CAAC;QAChB,CAAC,CAAC,CAAC;IACP,CAAC;IAEO,GAAG,CAAC,CAAwB;QAClC,MAAM,GAAG,GAAG,OAAO,CAAC,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,QAAQ,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;QACrE,IAAI,CAAC,GAAG;YAAE,MAAM,SAAS,CAAC,WAAW,CAAC,CAAC;QACvC,OAAO,GAAG,CAAC;IACb,CAAC;IAEO,IAAI,CAAC,GAAQ,EAAE,GAAW;QAChC,IAAI,CAAC,GAAG,CAAC,KAAK,IAAI,GAAG,CAAC,KAAK,CAAC,IAAI,KAAK,WAAW;YAAE,MAAM,SAAS,CAAC,iBAAiB,CAAC,CAAC;QACrF,IAAI,CAAC,GAAG,CAAC,YAAY,CAAC,GAAG,CAAC,GAAG,CAAC;YAAE,MAAM,SAAS,CAAC,WAAW,EAAE,EAAE,UAAU,EAAE,GAAG,EAAE,CAAC,CAAC;IACpF,CAAC;IAED,oBAAoB;IACZ,KAAK,CAAC,WAAW,CAAC,GAAiB,EAAE,GAAQ,EAAE,GAAa,EAAE,IAAuB;QAC3F,MAAM,KAAK,GAAG,CAAC,GAAG,IAAI,GAAG,CAAC,MAAM,CAAC,MAAM,CAAC,eAAe,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,CAAC,MAAM,CAAC,QAAQ,CAAC,GAAG,GAAG,CAAC,IAAI,IAAI,CAAC,EAAE,CAAC,IAAI,GAAG,CAAC,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC,CAAC;QACxJ,IAAI,IAAI,KAAK,MAAM,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC;YAAE,OAAO;QAClD,MAAM,IAAI,CAAC,CAAC,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC,CAAC,GAAG,EAAE;YAClC,QAAQ,EAAE,GAAG,CAAC,QAAQ,EAAE,KAAK,EAAE,GAAG,CAAC,KAAK,EAAE,EAAE,IAAI,WAAW,EAAE,SAAS,EAAE,GAAG,CAAC,KAAK,EAAE,IAAI,IAAI,WAAW;YACtG,UAAU,EAAE,GAAG,CAAC,UAAU,IAAI,IAAI,EAAE,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,IAAI,EAAE,MAAM;YACpE,UAAU,EAAE,GAAG,GAAG,CAAC,IAAI,IAAI,IAAI,EAAE,EAAE,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,GAAG,CAAC,IAAI;YACrE,WAAW,EAAE,GAAG,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI;YAC3D,IAAI,EAAE,EAAE,QAAQ,EAAE,KAAK,EAAE,IAAI,EAAE,GAAG,CAAC,MAAM,EAAE,EAAE,SAAS,EAAE,GAAG,CAAC,SAAS,IAAI,IAAI,EAAE,MAAM,EAAE,GAAG,CAAC,MAAM,IAAI,IAAI;SAC1G,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,EAAE;YACb,qCAAqC;YACrC,IAAI,IAAI,KAAK,QAAQ;gBAAE,MAAM,CAAC,CAAC;YAC/B,IAAI,CAAC,CAAC,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,GAAG,EAAE,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,SAAS,CAAC,CAAC;QACjD,CAAC,CAAC,CAAC;IACL,CAAC;IAED,KAAK,CAAC,GAAG,CAAC,CAAwB,EAAE,EAAU,EAAE,GAAQ;QACtD,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;QACxB,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,GAAG,CAAC,IAAI,OAAO,CAAC,CAAC;QACnC,IAAI,CAAC,kBAAkB,CAAC,IAAI,CAAC,EAAE,CAAC;YAAE,MAAM,SAAS,CAAC,WAAW,CAAC,CAAC;QAC/D,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,EAAE,CAAC,GAAG,EAAE,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,CAAC,UAAU,CAAC,QAAQ,GAAG,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC,CAAC,SAAS,EAAE,CAAC,KAAK,CAAC,IAAI,EAAE,GAAG,EAAE,EAAE,CAAC,CAAC,gBAAgB,EAAE,CAAC,CAAC;QACpI,IAAI,CAAC,GAAG;YAAE,MAAM,SAAS,CAAC,WAAW,CAAC,CAAC;QACvC,KAAK,IAAI,CAAC,WAAW,CAAC,GAAG,EAAE,GAAG,EAAE,CAAC,EAAE,CAAC,EAAE,MAAM,CAAC,CAAC;QAC9C,OAAO,eAAe,CAAC,GAAG,CAAC,CAAC;IAC9B,CAAC;IAED,KAAK,CAAC,IAAI,CAAC,CAAwB,EAAE,MAAkB,EAAE,GAAQ;QAC/D,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;QACxB,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,GAAG,CAAC,IAAI,OAAO,CAAC,CAAC;QACnC,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,EAAE,CAAC,GAAG,EAAE,CAAC,EAAE,EAAE,EAAE,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,CAAC,CAAC,CAAC;QAC1E,KAAK,IAAI,CAAC,WAAW,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,MAAM,CAAC,CAAC;QACpE,OAAO,GAAG,CAAC;IACb,CAAC;IAED,iDAAiD;IACjD,KAAK,CAAC,OAAO,CAAC,CAAwB,EAAE,EAAU,EAAE,SAAiB,EAAE,MAAkB,EAAE,GAAQ;QACjG,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,KAAK,GAAI,KAAK,CAAC,MAAiB,CAAC,SAAS,CAAC,CAAC;QACvE,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,KAAK,CAAC,IAAI,OAAO,CAAC,CAAC;QACrC,IAAI,CAAC,KAAK,IAAI,CAAC,UAAU,CAAC,KAAK,CAAC,IAAI,CAAC,kBAAkB,CAAC,IAAI,CAAC,EAAE,CAAC;YAAE,MAAM,SAAS,CAAC,WAAW,CAAC,CAAC;QAC/F,MAAM,MAAM,GAAG,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,GAAI,CAAC,CAAC;QACpC,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,MAAM,CAAC,IAAI,OAAO,CAAC,CAAC;QACtC,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,EAAE,CAAC,GAAG,EAAE,KAAK,EAAE,EAAE,EAAE,EAAE;YAC1C,MAAM,MAAM,GAAG,MAAM,EAAE,CAAC,UAAU,CAAC,QAAQ,KAAK,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,KAAK,CAAC,IAAI,EAAE,GAAG,EAAE,EAAE,CAAC,CAAC,KAAK,CAAC,QAAQ,EAAE,IAAI,EAAE,SAAS,CAAC,CAAC,gBAAgB,EAAE,CAAC;YACrJ,IAAI,CAAC,MAAM;gBAAE,MAAM,SAAS,CAAC,WAAW,CAAC,CAAC;YAC1C,MAAM,KAAK,GAAG,aAAa,CAAC,KAAK,EAAE,SAAS,CAAC,CAAC;YAC9C,MAAM,QAAQ,GAAG,KAAK,CAAC,IAAI,KAAK,SAAS;gBACvC,CAAC,CAAC,CAAC,CAAM,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC,KAAK,CAAC,KAAK,CAAC,QAAS,CAAC,CAAC,EAAE,GAAG,EAAE,EAAE,CAAC;gBAC/D,CAAC,CAAC,CAAC,CAAM,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,EAAE,IAAI,EAAE,EAAE,CAAC,UAAU,CAAC,QAAQ,KAAK,CAAC,IAAI,EAAE,CAAC,CAAC,MAAM,CAAC,WAAW,CAAC,CAAC,KAAK,CAAC,WAAW,EAAE,GAAG,EAAE,EAAE,CAAC,CAAC,CAAC;YACzH,OAAO,IAAI,CAAC,MAAM,CAAC,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,GAAG,EAAE,IAAI,EAAE,QAAQ,CAAC,CAAC;QAC9D,CAAC,EAAE,iBAAiB,CAAC,CAAC;QACtB,KAAK,IAAI,CAAC,WAAW,CAAC,MAAM,EAAE,GAAG,EAAE,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,CAAC,EAAE,CAAC,EAAE,MAAM,CAAC,CAAC;QAC3E,OAAO,GAAG,CAAC;IACb,CAAC;IAEO,KAAK,CAAC,MAAM,CAAC,EAAoB,EAAE,GAAiB,EAAE,MAAkB,EAAE,WAAmB,EAAE,KAAK,GAAG,IAAI,EAAE,WAA4B,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;QACvJ,MAAM,IAAI,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,MAAM,CAAC,MAAM,CAAC,IAAI,IAAI,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC;QACxD,MAAM,QAAQ,GAAG,IAAI,CAAC,GAAG,CAAC,WAAW,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,MAAM,CAAC,MAAM,CAAC,QAAQ,IAAI,EAAE,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC;QACzF,MAAM,MAAM,GAAG,IAAI,GAAG,CAAC,YAAY,CAAC,GAAG,CAAC,CAAC,CAAC;QAC1C,MAAM,IAAI,GAAG,QAAQ,GAAG,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC;QACtC,MAAM,KAAK,GAAG,CAAC,CAAM,EAAE,EAAE;YACvB,KAAK,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC;gBAC5C,IAAI,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,SAAS,IAAI,CAAC,KAAK,EAAE;oBAAE,SAAS;gBAC7D,MAAM,CAAC,GAAI,GAAG,CAAC,MAAiB,CAAC,CAAC,CAAC,CAAC;gBACpC,MAAM,GAAG,GAAG,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,GAAG,KAAK,OAAO,IAAI,CAAC,CAAC,CAAC,aAAa,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC;gBAC9H,IAAI,CAAC,GAAG;oBAAE,MAAM,SAAS,CAAC,eAAe,EAAE,CAAC,EAAE,IAAI,EAAE,CAAC,EAAE,OAAO,EAAE,OAAO,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC;gBAClF,IAAI,CAAC,KAAK,QAAQ,IAAI,OAAO,CAAC,KAAK,QAAQ,IAAI,CAAC,CAAC,QAAQ,CAAC,GAAG,CAAC;oBAAE,CAAC,GAAG,CAAC,CAAC,KAAK,CAAC,QAAQ,EAAE,IAAI,EAAE,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC;;oBACrG,CAAC,GAAG,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,GAAG,EAAE,MAAM,CAAC,CAAC,EAAE,IAAI,IAAI,MAAM,EAAE,CAAC,CAAC,CAAC,CAAC;YACpE,CAAC;YACD,IAAI,MAAM,CAAC,MAAM,KAAK,SAAS;gBAAE,CAAC,GAAG,CAAC,CAAC,KAAK,CAAC,QAAQ,EAAE,IAAI,EAAE,SAAS,CAAC,CAAC;YACxE,IAAI,MAAM,CAAC,YAAY;gBAAE,CAAC,GAAG,CAAC,CAAC,KAAK,CAAC,YAAY,EAAE,IAAI,EAAE,IAAI,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC;YAChG,IAAI,MAAM,CAAC,aAAa;gBAAE,CAAC,GAAG,CAAC,CAAC,KAAK,CAAC,YAAY,EAAE,GAAG,EAAE,IAAI,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC;YACjG,OAAO,QAAQ,CAAC,CAAC,CAAC,CAAC;QACrB,CAAC,CAAC;QACF,IAAI,CAAC,GAAG,KAAK,CAAC,EAAE,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC,SAAS,EAAE,CAAC,CAAC;QAC/C,MAAM,OAAO,GAAG,OAAO,MAAM,CAAC,IAAI,KAAK,QAAQ,IAAI,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,WAAW,CAAC;QAC7G,MAAM,SAAS,GAAI,GAAG,CAAC,MAAiB,CAAC,OAAO,CAAC,CAAC;QAClD,MAAM,OAAO,GAAG,GAAG,CAAC,OAAO,CAAC,IAAI,CAAC,SAAS,IAAI,CAAC,UAAU,CAAC,SAAS,CAAC,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC;QAC3H,IAAI,CAAC,OAAO;YAAE,MAAM,SAAS,CAAC,eAAe,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,OAAO,KAAK,EAAE,CAAC,CAAC,CAAC;QACjG,MAAM,IAAI,GAAG,OAAO,MAAM,CAAC,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;QAClF,CAAC,GAAG,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,OAAO,CAAC,EAAE,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,CAAC,IAAI,GAAG,CAAC,CAAC,GAAG,QAAQ,CAAC,CAAC;QACnH,MAAM,IAAI,GAAG,MAAM,CAAC,CAAC,OAAO,EAAE,CAAC;QAC/B,MAAM,GAAG,GAAG,KAAK,CAAC,CAAC,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC,MAAM,CAAC,GAAG,CAAQ,eAAe,CAAC,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,gBAAgB,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC;QAC1H,OAAO,EAAE,KAAK,EAAE,IAAI,CAAC,GAAG,CAAC,eAAe,CAAC,EAAE,KAAK,EAAE,MAAM,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,CAAC;IAC1F,CAAC;IAED;;;;OAIG;IACH,KAAK,CAAC,MAAM,CAAC,CAAwB,EAAE,MAAkB,EAAE,GAAQ;QACjE,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;QACxB,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,GAAG,CAAC,IAAI,SAAS,CAAC,CAAC;QACrC,MAAM,IAAI,GAAG,CAAC,IAAI,EAAE,GAAG,MAAM,CAAC,OAAO,CAAC,GAAG,CAAC,MAAgB,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,QAAQ,IAAI,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,SAAS,EAAE,WAAW,EAAE,WAAW,CAAC,CAAC;QAC7K,MAAM,KAAK,GAAG,CAAC,QAAQ,GAAG,IAAI,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,GAAG,GAAa,EAAE,CAAC;QAC3E,IAAI,KAAK,GAAG,MAAM,CAAC,UAAU,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;QACxC,MAAM,IAAI,CAAC,EAAE,CAAC,GAAG,EAAE,KAAK,EAAE,EAAE,EAAE,EAAE;YAC9B,IAAI,KAAK,GAAG,CAAC,CAAC;YACd,KAAK,IAAI,IAAI,GAAG,CAAC,EAAE,IAAI,KAAK,CAAC,IAAI,GAAG,CAAC,MAAM,GAAG,KAAK,EAAE,IAAI,EAAE,EAAE,CAAC;gBAC5D,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,EAAE,EAAE,GAAG,EAAE,EAAE,GAAG,MAAM,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE,EAAE,IAAI,EAAE,IAAI,KAAK,CAAC,CAAC,CAAC;gBAC9F,IAAI,IAAI,KAAK,CAAC;oBAAE,KAAK,GAAG,GAAG,CAAC,KAAK,CAAC;gBAClC,IAAI,KAAK,GAAG,OAAO;oBAAE,MAAM,SAAS,CAAC,eAAe,EAAE,yBAAyB,CAAC,CAAC;gBACjF,KAAK,MAAM,GAAG,IAAI,GAAG,CAAC,KAAK,EAAE,CAAC;oBAC5B,MAAM,IAAI,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;oBACxD,KAAK,IAAI,MAAM,CAAC,UAAU,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;oBACrC,IAAI,KAAK,GAAG,EAAE,GAAG,IAAI,GAAG,IAAI;wBAAE,MAAM,SAAS,CAAC,eAAe,EAAE,uBAAuB,CAAC,CAAC;oBACxF,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;oBAAC,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;gBACrC,CAAC;YACH,CAAC;QACH,CAAC,EAAE,iBAAiB,CAAC,CAAC;QACtB,MAAM,IAAI,CAAC,WAAW,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,QAAQ,CAAC,CAAC;QAChD,OAAO,EAAE,QAAQ,EAAE,GAAG,GAAG,CAAC,KAAK,CAAC,IAAI,MAAM,EAAE,WAAW,EAAE,yBAAyB,EAAE,IAAI,EAAE,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,GAAG,CAAC,MAAM,EAAE,CAAC;IACjI,CAAC;IAED,kEAAkE;IAClE,KAAK,CAAC,GAAG,CAAC,CAAoB,EAAE,GAAY,EAAE,GAAQ;QACpD,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,QAAQ,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;QAC5F,IAAI,CAAC,KAAK;YAAE,MAAM,SAAS,CAAC,WAAW,CAAC,CAAC;QACzC,KAAK,MAAM,CAAC,IAAI,KAAK,CAAC,KAAK;YAAE,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC,IAAI,OAAO,CAAC,CAAC;QAC9D,MAAM,MAAM,GAAG,KAAK,CAAC,KAAK,CAAC,SAAS,CAAC,GAAG,IAAI,EAAE,CAAC,CAAC;QAChD,IAAI,CAAC,MAAM,CAAC,OAAO;YAAE,MAAM,SAAS,CAAC,eAAe,EAAE,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,OAAO,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,CAAC;QACxI,MAAM,KAAK,GAAG,MAAM,CAAC,IAA+B,CAAC;QACrD,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC,EAAE,CAAC,GAAG,EAAE,KAAK,EAAE,EAAE,EAAE,EAAE;YAC3C,IAAI,KAAK,CAAC,KAAK;gBAAE,OAAO,CAAC,MAAM,KAAK,CAAC,KAAK,CAAC,EAA4B,EAAE,KAAY,CAAC,CAAC,OAAO,EAAE,CAA8B,CAAC;YAC/H,MAAM,QAAQ,GAAG,eAAe,CAAC,KAAK,CAAC,GAAI,EAAE,KAAK,CAAC,CAAC;YACpD,MAAM,CAAC,GAAG,MAAM,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC;YACrC,OAAO,CAAC,CAAC,IAAiC,CAAC;QAC7C,CAAC,CAAC,CAAC;QACH,OAAO,IAAI,CAAC,GAAG,CAAC,eAAe,CAAC,CAAC;IACnC,CAAC;CACF;AAED,sCAAsC;AACtC,MAAM,UAAU,eAAe,CAAC,IAAY,EAAE,KAA8B;IAC1E,MAAM,KAAK,GAAU,EAAE,CAAC;IACxB,MAAM,EAAE,GAAG,sCAAsC,CAAC;IAClD,IAAI,IAAI,GAAG,CAAC,CAAC;IACb,IAAI,CAAyB,CAAC;IAC9B,OAAO,CAAC,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,EAAE,CAAC;QAC3B,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;QAC/C,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,KAAK,CAAC;YAAE,MAAM,SAAS,CAAC,eAAe,EAAE,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,UAAU,CAAC,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC;QACpG,KAAK,CAAC,IAAI,CAAC,GAAG,CAAA,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;QAChC,IAAI,GAAG,CAAC,CAAC,KAAK,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC;IAC/B,CAAC;IACD,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IACtC,OAAO,GAAG,CAAyB,GAAG,GAAG,CAAC,IAAI,CAAC,KAAK,EAAE,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC;AACvE,CAAC;AAED,MAAM,CAAC,MAAM,gBAAgB,GAAG,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC"}

package/dist/registry.d.ts

@@ -0,0 +1,71 @@
+import { CONNECTOR, INBOUND, OUTBOUND, ROUTE } from './brands.js';
+import { type AnyAggregate } from './primitives/aggregate.js';
+import type { AnyCommand } from './primitives/command.js';
+import type { AnyEvent } from './primitives/event.js';
+import type { AnyQuery, AnyReaction, Approval, Job } from './primitives/flow.js';
+export interface RegisteredCommand {
+    readonly cmd: AnyCommand;
+    /** 命令名（导出名或显式 name） */
+    readonly name: string;
+    /** 能力点：聚合名.命令名 */
+    readonly capability: string;
+    readonly exportName: string;
+}
+export interface CatalogEntry {
+    capability: string;
+    kind: 'command' | 'read' | 'export' | 'unmask' | 'system';
+    aggregate?: string;
+    description?: string;
+    /** 命令的调用方限制，管理界面据此提示 */
+    invokedBy?: readonly string[];
+}
+export interface RuntimeExtension {
+    kind: 'CONNECTOR' | 'OUTBOUND' | 'INBOUND' | 'ROUTE';
+    name: string;
+    value: any;
+}
+export interface Registry {
+    readonly aggregates: readonly AnyAggregate[];
+    readonly commands: readonly RegisteredCommand[];
+    readonly events: readonly AnyEvent[];
+    readonly reactions: readonly {
+        r: AnyReaction;
+        name: string;
+    }[];
+    readonly queries: readonly AnyQuery[];
+    readonly approvals: readonly {
+        a: Approval;
+        name: string;
+    }[];
+    readonly jobs: readonly Job[];
+    readonly extensions: readonly RuntimeExtension[];
+    readonly systemDdl: readonly string[];
+    aggregate(name: string): AnyAggregate | undefined;
+    /** 按能力点或命令对象找命令 */
+    command(ref: string | AnyCommand): RegisteredCommand | undefined;
+    capabilityOf(cmd: AnyCommand): string;
+    /** 任意原语对象的导出名 */
+    nameOf(v: object): string | undefined;
+    reactionsFor(eventName: string): {
+        r: AnyReaction;
+        name: string;
+    }[];
+    approvalFor(aggName: string): {
+        a: Approval;
+        name: string;
+    } | undefined;
+    approvalByProcess(process: string): {
+        a: Approval;
+        name: string;
+    } | undefined;
+    capabilityCatalog(): CatalogEntry[];
+    /** 带 CONSUMERS 标记的声明对象（连接器出站映射等） */
+    consumerProviders(): any[];
+}
+export interface RegistryOptions {
+    /** 框架额外的系统能力点，例如 Sys.audit.read */
+    extraCapabilities?: CatalogEntry[];
+}
+/** 遍历一个或多个 domain 模块的导出，建立注册表。 */
+export declare function buildRegistry(domains: object | object[], opts?: RegistryOptions): Registry;
+export { CONNECTOR, INBOUND, OUTBOUND, ROUTE };