@pylonts/dsl 1.0.3 → 1.0.5

package/dist/bases.d.ts

@@ -0,0 +1,5 @@
+import type { DtoMessage, ImportRef } from './dto';
+/** Paginated query request base — renders `import { PageRequest } from '@pylonts/core'` + Intersect */
+export declare const PageRequest: ImportRef;
+/** Paginated list response base — renders `import { PageResult } from '@pylonts/core'` + `PageResult(<row>)` */
+export declare const PageResult: (row: DtoMessage) => ImportRef;

package/dist/bases.js

@@ -0,0 +1,20 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PageResult = exports.PageRequest = void 0;
+// Named base-schema references for common protocol DTOs.
+//
+// These are ImportRef metadata (not re-exports of the actual TypeBox schemas):
+// the DSL stores { from, name } so the generator can emit the import line and
+// the identifier — the runtime schema object itself is never loaded by the DSL.
+//
+// `import { PageRequest } from '@pylonts/dsl'` therefore gives .include() an
+// already-resolved reference — no static analysis or name lookup needed.
+/** Paginated query request base — renders `import { PageRequest } from '@pylonts/core'` + Intersect */
+exports.PageRequest = { from: '@pylonts/core', name: 'PageRequest' };
+/** Paginated list response base — renders `import { PageResult } from '@pylonts/core'` + `PageResult(<row>)` */
+const PageResult = (row) => ({
+    from: '@pylonts/core',
+    name: 'PageResult',
+    args: [row],
+});
+exports.PageResult = PageResult;

package/dist/check-inheritance.d.ts

@@ -0,0 +1,9 @@
+export interface InheritanceIssue {
+    file: string;
+    container: string;
+    field: string;
+    /** e.g. ["t_order.order_no"] or ["t_order.id", "t_merchant.id"] when several inferred tables share the name */
+    candidates: string[];
+}
+/** Check one loaded DSL module (its exports) for inheritance gaps. */
+export declare function checkInheritance(mod: Record<string, unknown>, file: string): InheritanceIssue[];

package/dist/check-inheritance.js

@@ -0,0 +1,61 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.checkInheritance = checkInheritance;
+/** snake_case → camelCase: order_no → orderNo; names without underscores are unchanged */
+function toCamelCase(name) {
+    return name.replace(/_([a-z])/g, (_, c) => c.toUpperCase());
+}
+function isDtoMessage(v) {
+    if (typeof v !== 'object' || v === null)
+        return false;
+    const o = v;
+    return o.type === 'dto' && typeof o.name === 'string' && typeof o.fields === 'object' && o.fields !== null;
+}
+function collectFields(mod) {
+    const out = [];
+    for (const [name, v] of Object.entries(mod)) {
+        if (isDtoMessage(v)) {
+            const container = v;
+            for (const [fname, f] of Object.entries(container.fields)) {
+                out.push({ name: fname, field: f.field, container: name });
+            }
+        }
+    }
+    return out;
+}
+/** Check one loaded DSL module (its exports) for inheritance gaps. */
+function checkInheritance(mod, file) {
+    const fields = collectFields(mod);
+    if (fields.length === 0)
+        return [];
+    // Infer the tables this file is about from the referenced fields' schema identity.
+    const tables = new Map(); // table -> camelCol -> origCol
+    for (const f of fields) {
+        const schema = f.field.schema;
+        if (schema?.type !== 'table')
+            continue;
+        const table = schema;
+        if (!tables.has(table.name))
+            tables.set(table.name, new Map());
+        tables.get(table.name).set(toCamelCase(f.name), f.name);
+    }
+    if (tables.size === 0)
+        return [];
+    const issues = [];
+    for (const f of fields) {
+        if (f.field.schema?.type === 'table')
+            continue;
+        if (f.field.semantic !== undefined || f.field.type === 'enum')
+            continue;
+        const candidates = [];
+        for (const [t, cols] of tables) {
+            const orig = cols.get(f.name);
+            if (orig !== undefined)
+                candidates.push(`${t}.${orig}`);
+        }
+        if (candidates.length > 0) {
+            issues.push({ file, container: f.container, field: f.name, candidates });
+        }
+    }
+    return issues;
+}

package/dist/dsl.d.ts

@@ -3,17 +3,23 @@ export interface SchemaBase {
     name: string;
     description?: string;
 }
+/** Field collection schemas (DB table vs DTO message); `type` is the discriminator */
+export interface CollectionSchemaBase extends SchemaBase {
+    type: string;
+}
 export interface BaseField {
     name: string;
     /** 显示名称（中文标签） */
     label?: string;
     /** 字段描述 */
     description?: string;
+    /** 业务语义码（如 'merchant_name'），驱动 mock 生成等下游消费 */
+    semantic?: string;
     optional?: boolean;
     readOnly?: boolean;
     default?: string;
     /** 所属 schema（db 或 dto） */
-    schema?: SchemaBase;
+    schema?: CollectionSchemaBase;
 }
 interface StringField extends BaseField {
     type: 'string';
@@ -90,7 +96,23 @@ export type ForeignKey = {
     fields: Field | Field[];
     references: Field | Field[];
 };
-export interface TableSchema extends SchemaBase {
+export interface TableSchemaOptions {
+    description?: string;
+    paginated?: boolean;
+    actor?: boolean;
+    generator?: string;
+    autoIncrement?: Field;
+    primaryKey?: Field | Field[];
+    indexes?: Index[];
+    foreignKeys?: Record<string, ForeignKey>;
+    /** 引用的实体短语（词典条目）：本表归属的实体；关联表等多实体场景不需要 */
+    phrase?: DictionaryEntry;
+    fields: Record<string, Field>;
+}
+export declare class TableSchema implements CollectionSchemaBase {
+    type: string;
+    name: string;
+    description?: string;
     /** 分页 */
     paginated?: boolean;
     /** 系统操作者（如小程序为 C 端用户，管理端为运营） */
@@ -106,6 +128,9 @@ export interface TableSchema extends SchemaBase {
     /** 引用的实体短语（词典条目）：本表归属的实体；关联表等多实体场景不需要 */
     phrase?: DictionaryEntry;
     fields: Record<string, Field>;
+    constructor(name: string, options: TableSchemaOptions);
+    /** True when the field is part of this table's primary key */
+    isPk(fieldRef: Field): boolean;
 }
 type FieldExtras<T extends Field> = Omit<T, 'name' | 'type' | 'jsType'>;
 export declare function stringField(extra?: FieldExtras<StringField>): StringField;
@@ -119,17 +144,5 @@ export declare function timeField(extra?: FieldExtras<TimeField>): TimeField;
 export declare function datetimeField(extra?: FieldExtras<DateTimeField>): DateTimeField;
 export declare function jsonField(extra?: FieldExtras<JsonField>): JsonField;
 export declare function enumField(extra: Omit<EnumField, 'name' | 'type' | 'jsType'>): EnumField;
-export declare function defineTable(name: string, schema: {
-    description?: string;
-    paginated?: boolean;
-    actor?: boolean;
-    generator?: string;
-    autoIncrement?: Field;
-    primaryKey?: Field | Field[];
-    indexes?: Index[];
-    foreignKeys?: Record<string, ForeignKey>;
-    /** 引用的实体短语（词典条目） */
-    phrase?: DictionaryEntry;
-    fields: Record<string, Field>;
-}): TableSchema;
+export declare function defineTable(name: string, schema: TableSchemaOptions): TableSchema;
 export {};

package/dist/dsl.js

@@ -2,6 +2,7 @@
 // DSL field type definitions.
 // Shape: { type: <type name>, <extension fields> }
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.TableSchema = void 0;
 exports.defineEnum = defineEnum;
 exports.stringField = stringField;
 exports.textField = textField;
@@ -18,6 +19,48 @@ exports.defineTable = defineTable;
 function defineEnum(jsName, valueType, values) {
     return { jsName, valueType, values };
 }
+class TableSchema {
+    type = 'table';
+    name;
+    description;
+    /** 分页 */
+    paginated;
+    /** 系统操作者（如小程序为 C 端用户，管理端为运营） */
+    actor;
+    /** id 生成器 */
+    generator;
+    /** 自增主键字段 */
+    autoIncrement;
+    primaryKey;
+    indexes;
+    /** 外键，引用其他表的字段 */
+    foreignKeys;
+    /** 引用的实体短语（词典条目）：本表归属的实体；关联表等多实体场景不需要 */
+    phrase;
+    fields;
+    constructor(name, options) {
+        this.name = name;
+        this.description = options.description;
+        this.paginated = options.paginated;
+        this.actor = options.actor;
+        this.generator = options.generator;
+        this.autoIncrement = options.autoIncrement;
+        this.primaryKey = options.primaryKey;
+        this.indexes = options.indexes;
+        this.foreignKeys = options.foreignKeys;
+        this.phrase = options.phrase;
+        this.fields = options.fields;
+    }
+    /** True when the field is part of this table's primary key */
+    isPk(fieldRef) {
+        if (this.primaryKey === undefined)
+            return false;
+        return Array.isArray(this.primaryKey)
+            ? this.primaryKey.includes(fieldRef)
+            : this.primaryKey === fieldRef;
+    }
+}
+exports.TableSchema = TableSchema;
 function stringField(extra = {}) {
     return { name: '', type: 'string', jsType: 'string', ...extra };
 }
@@ -53,7 +96,7 @@ function enumField(extra) {
     return { name: '', type: 'enum', jsType, ...extra };
 }
 function defineTable(name, schema) {
-    const table = { name, ...schema };
+    const table = new TableSchema(name, schema);
     for (const key of Object.keys(table.fields)) {
         const field = table.fields[key];
         if (field.schema && field.schema !== table) {

package/dist/dto.d.ts

@@ -1,4 +1,4 @@
-import { BaseField, Field, SchemaBase, TableSchema } from './dsl';
+import { BaseField, CollectionSchemaBase, Field, SchemaBase, TableSchema } from './dsl';
 export type Operator = 'eq' | 'gt' | 'gte' | 'lt' | 'lte' | 'like' | 'ne';
 /**
  * Reference to an existing TypeBox base schema by its import location.
@@ -10,16 +10,14 @@ export interface ImportRef {
     from: string;
     /** Named export, e.g. 'PageRequest' */
     name: string;
-    /** Generic type arguments for the base schema (same-file DTO export names), e.g. PageResult(AdvertRow) */
-    args?: string[];
+    /**
+     * Generic type arguments for the base schema (e.g. PageResult(OrderRow)).
+     * Two forms, both local DTOs:
+     *   string     — the DTO export name
+     *   DtoMessage — the DTO instance itself; the driver resolves it to its name
+     */
+    args?: (string | DtoMessage)[];
 }
-export type DtoExtras = {
-    pattern?: string;
-    /** 联合判断是否可选，定义后优先级高于 field.optional */
-    optional?: boolean;
-    /** 查询比较操作符（query 方向字段） */
-    operator?: Operator;
-};
 export type DtoArrayFieldDef = BaseField & {
     type: 'array';
     jsType: 'array';
@@ -30,21 +28,31 @@ export type DtoObjectFieldDef = BaseField & {
     jsType: 'object';
     properties: Record<string, DtoField>;
 };
-export declare class DtoField {
+export declare class DtoField implements SchemaBase {
     /** DTO 语义字段名（接口字段名），与 field.name（数据库列名）含义不同。
      *  构造时未知，由 buildMessage 从 map key 反写。 */
     name: string;
+    /** 字段描述 */
+    description?: string;
     /** 所属 DTO 容器（buildMessage 反写） */
     schema?: DtoMessage;
     field: Field | DtoArrayFieldDef | DtoObjectFieldDef;
     pattern?: string;
     optional?: boolean;
     operator?: Operator;
-    constructor(field: Field | DtoArrayFieldDef | DtoObjectFieldDef, extra?: DtoExtras);
+    /** TypeBox default annotation (API contract level); falls back to field.default (DB default) */
+    default?: unknown;
+    constructor(field: Field | DtoArrayFieldDef | DtoObjectFieldDef);
     setPattern(value: string): this;
+    setDescription(value: string): this;
+    getDescription(): string | undefined;
+    /** True when this field wraps a DB column (picked via from()); false for inline fields. */
+    isColumn(): boolean;
     setOptional(value: boolean): this;
+    /** Set a default value — emitted as a TypeBox schema default annotation */
+    setDefault(value: unknown): this;
     /** 查询比较操作符（query 方向字段）。Rule B: 查询字段恒为可选 */
-    op(value: Operator): this;
+    setOperator(value: Operator): this;
     /** optional 优先于 field.optional */
     isOptional(): boolean;
 }
@@ -56,23 +64,32 @@ export declare class DtoObjectField extends DtoField {
     field: DtoObjectFieldDef;
     properties(): Record<string, DtoField>;
 }
-export type DtoDirection = 'input' | 'output' | 'query' | 'pk';
-export interface DtoMessage extends SchemaBase {
+export declare enum DtoDirection {
+    Input = "input",
+    Output = "output",
+    Query = "query",
+    Pk = "pk"
+}
+export declare class DtoMessage implements CollectionSchemaBase {
+    type: string;
+    name: string;
+    description?: string;
     /** 方向：输入或输出 */
     direction: DtoDirection;
     fields: Record<string, DtoField>;
     /** TypeBox base schemas to intersect with at generation time (e.g. PageRequest) */
-    bases?: ImportRef[];
+    bases: ImportRef[];
+    constructor(name: string, direction: DtoDirection, fields: Record<string, DtoField>, description?: string);
     /** 引用已存在的 TypeBox base schema，例如 include({ from: '@pylonts/core', name: 'PageRequest' }) */
-    include(...refs: ImportRef[]): DtoMessage;
+    include(...refs: ImportRef[]): this;
 }
-export declare function dtoField(field: Field, extra?: DtoExtras): DtoField;
+export declare function dtoField(field: Field): DtoField;
 export declare function dtoArrayField(def: {
-    items: DtoField;
-} & Omit<BaseField, 'name'>, extra?: DtoExtras): DtoArrayField;
+    items: DtoField | DtoMessage;
+} & Omit<BaseField, 'name'>): DtoArrayField;
 export declare function dtoObjectField(def: {
     properties: Record<string, DtoField>;
-} & Omit<BaseField, 'name'>, extra?: DtoExtras): DtoObjectField;
+} & Omit<BaseField, 'name'>): DtoObjectField;
 export declare function buildInput(name: string, fields: Record<string, DtoField>, description?: string): DtoMessage;
 export declare function buildOutput(name: string, fields: Record<string, DtoField>, description?: string): DtoMessage;
 export declare function buildQuery(name: string, fields: Record<string, DtoField>, description?: string): DtoMessage;

package/dist/dto.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.DtoObjectField = exports.DtoArrayField = exports.DtoField = void 0;
+exports.DtoMessage = exports.DtoDirection = exports.DtoObjectField = exports.DtoArrayField = exports.DtoField = void 0;
 exports.dtoField = dtoField;
 exports.dtoArrayField = dtoArrayField;
 exports.dtoObjectField = dtoObjectField;
@@ -9,35 +9,52 @@ exports.buildOutput = buildOutput;
 exports.buildQuery = buildQuery;
 exports.buildPk = buildPk;
 exports.from = from;
+const utils_1 = require("./utils");
 class DtoField {
     /** DTO 语义字段名（接口字段名），与 field.name（数据库列名）含义不同。
      *  构造时未知，由 buildMessage 从 map key 反写。 */
     name;
+    /** 字段描述 */
+    description;
     /** 所属 DTO 容器（buildMessage 反写） */
     schema;
     field;
     pattern;
     optional;
     operator;
-    constructor(field, extra = {}) {
+    /** TypeBox default annotation (API contract level); falls back to field.default (DB default) */
+    default;
+    constructor(field) {
         this.name = '';
         this.field = field;
-        this.pattern = extra.pattern;
-        this.optional = extra.optional;
-        this.operator = extra.operator;
     }
     setPattern(value) {
         this.pattern = value;
         return this;
     }
+    setDescription(value) {
+        this.description = value;
+        return this;
+    }
+    getDescription() {
+        return this.description;
+    }
+    /** True when this field wraps a DB column (picked via from()); false for inline fields. */
+    isColumn() {
+        return this.field.schema?.type === 'table';
+    }
     setOptional(value) {
         this.optional = value;
         return this;
     }
+    /** Set a default value — emitted as a TypeBox schema default annotation */
+    setDefault(value) {
+        this.default = value;
+        return this;
+    }
     /** 查询比较操作符（query 方向字段）。Rule B: 查询字段恒为可选 */
-    op(value) {
+    setOperator(value) {
         this.operator = value;
-        this.optional = true;
         return this;
     }
     /** optional 优先于 field.optional */
@@ -60,32 +77,50 @@ class DtoObjectField extends DtoField {
     }
 }
 exports.DtoObjectField = DtoObjectField;
-function dtoField(field, extra = {}) {
-    return new DtoField(field, extra);
+var DtoDirection;
+(function (DtoDirection) {
+    DtoDirection["Input"] = "input";
+    DtoDirection["Output"] = "output";
+    DtoDirection["Query"] = "query";
+    DtoDirection["Pk"] = "pk";
+})(DtoDirection || (exports.DtoDirection = DtoDirection = {}));
+class DtoMessage {
+    type = 'dto';
+    name;
+    description;
+    /** 方向：输入或输出 */
+    direction;
+    fields;
+    /** TypeBox base schemas to intersect with at generation time (e.g. PageRequest) */
+    bases = [];
+    constructor(name, direction, fields, description) {
+        this.name = name;
+        this.direction = direction;
+        this.fields = fields;
+        this.description = description;
+    }
+    /** 引用已存在的 TypeBox base schema，例如 include({ from: '@pylonts/core', name: 'PageRequest' }) */
+    include(...refs) {
+        this.bases.push(...refs);
+        return this;
+    }
+}
+exports.DtoMessage = DtoMessage;
+function dtoField(field) {
+    return new DtoField(field);
 }
-function dtoArrayField(def, extra = {}) {
-    return new DtoArrayField({ name: '', type: 'array', jsType: 'array', ...def }, extra);
+function dtoArrayField(def) {
+    // Reuse an existing DTO as the array element: expand its fields into an object.
+    const items = def.items instanceof DtoMessage
+        ? new DtoObjectField({ name: '', type: 'object', jsType: 'object', properties: def.items.fields })
+        : def.items;
+    return new DtoArrayField({ name: '', type: 'array', jsType: 'array', ...def, items });
 }
-function dtoObjectField(def, extra = {}) {
-    return new DtoObjectField({ name: '', type: 'object', jsType: 'object', ...def }, extra);
+function dtoObjectField(def) {
+    return new DtoObjectField({ name: '', type: 'object', jsType: 'object', ...def });
 }
 function buildMessage(name, direction, fields, description) {
-    const message = {
-        name,
-        direction,
-        description,
-        fields,
-        bases: [],
-        include(...refs) {
-            this.bases.push(...refs);
-            return this;
-        },
-    };
-    if (direction === 'query') {
-        // Rule B: query/search fields are always optional.
-        for (const field of Object.values(message.fields))
-            field.optional = true;
-    }
+    const message = new DtoMessage(name, direction, fields, description);
     // Write back the DTO field name from the map key (safe: DtoField instances
     // are created per DTO, never shared).
     for (const key of Object.keys(message.fields)) {
@@ -103,16 +138,41 @@ function buildMessage(name, direction, fields, description) {
     return message;
 }
 function buildInput(name, fields, description) {
-    return buildMessage(name, 'input', fields, description);
+    const message = buildMessage(name, DtoDirection.Input, fields, description);
+    // Rule A — set optionality from the DB column rule (skips fields the author
+    // already set): nullable / default / auto-increment → optional, else required.
+    for (const field of Object.values(message.fields)) {
+        if (field.optional !== undefined)
+            continue;
+        const f = field.field;
+        if (f.schema?.type !== 'table')
+            continue;
+        const table = f.schema;
+        field.optional = f.optional !== false || f.default !== undefined || table.autoIncrement === f;
+    }
+    return message;
 }
 function buildOutput(name, fields, description) {
-    return buildMessage(name, 'output', fields, description);
+    return buildMessage(name, DtoDirection.Output, fields, description);
 }
 function buildQuery(name, fields, description) {
-    return buildMessage(name, 'query', fields, description);
+    const message = buildMessage(name, DtoDirection.Query, fields, description);
+    // Rule B: query/search fields are always optional.
+    for (const field of Object.values(message.fields))
+        field.optional = true;
+    return message;
 }
 function buildPk(name, fields, description) {
-    return buildMessage(name, 'pk', fields, description);
+    const message = buildMessage(name, DtoDirection.Pk, fields, description);
+    // Rule P: PK locator fields are required, other fields are optional.
+    for (const field of Object.values(message.fields)) {
+        if (field.optional !== undefined)
+            continue;
+        const f = field.field;
+        const table = f.schema;
+        field.optional = table !== undefined && table.isPk(f) ? false : true;
+    }
+    return message;
 }
 /** Pick columns from a built table and wrap them as DTO fields (aligned with dto.from). */
 function from(table, fields) {
@@ -121,7 +181,9 @@ function from(table, fields) {
         if (field.schema !== table) {
             throw new Error(`dto.from(${table.name}): field ${field.name} does not belong to this table`);
         }
-        out[field.name] = dtoField(field);
+        // DTO field name is camelCase (mer_id → merId); the underlying field.name
+        // stays snake_case (DB column).
+        out[(0, utils_1.toCamelCase)(field.name)] = dtoField(field);
     }
     return out;
 }

package/dist/index.d.ts

@@ -1,11 +1,14 @@
 export * from './dsl';
 export * from './dto';
+export * from './bases';
+export * from './utils';
 export * from './project';
 export * from './prototype';
 export * from './dictionary';
 export * from './mysql-driver';
 export * from './enum-driver';
 export * from './typebox-driver';
+export * from './check-inheritance';
 export * from './pattern';
 export * from './patterns/retry';
 export * from './flow';

package/dist/index.js

@@ -16,12 +16,15 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
 Object.defineProperty(exports, "__esModule", { value: true });
 __exportStar(require("./dsl"), exports);
 __exportStar(require("./dto"), exports);
+__exportStar(require("./bases"), exports);
+__exportStar(require("./utils"), exports);
 __exportStar(require("./project"), exports);
 __exportStar(require("./prototype"), exports);
 __exportStar(require("./dictionary"), exports);
 __exportStar(require("./mysql-driver"), exports);
 __exportStar(require("./enum-driver"), exports);
 __exportStar(require("./typebox-driver"), exports);
+__exportStar(require("./check-inheritance"), exports);
 __exportStar(require("./pattern"), exports);
 __exportStar(require("./patterns/retry"), exports);
 __exportStar(require("./flow"), exports);

package/dist/mermaid-driver.js

@@ -47,9 +47,13 @@ function renderPageFlowMermaid(schema) {
     const ids = new Map();
     const byApp = new Map();
     for (const p of schema.pages) {
-        const list = byApp.get(p.app.name) ?? [];
-        list.push(p);
-        byApp.set(p.app.name, list);
+        const list = byApp.get(p.app.name);
+        if (!list) {
+            byApp.set(p.app.name, [p]);
+        }
+        else {
+            list.push(p);
+        }
     }
     let appIdx = 0;
     for (const [appName, pages] of byApp) {

package/dist/typebox-driver.d.ts

@@ -1,5 +1,11 @@
 import { DtoMessage, ImportRef } from './dto';
 export type EnumResolver = (enumName: string) => ImportRef | undefined;
+/** Collect all imports needed to render a DTO: include() bases + enum references. */
+export declare function collectDtoImports(schema: DtoMessage, resolver: EnumResolver | undefined, out: Map<string, ImportRef>): void;
+/** Render one DTO export (const + type) — no file header, for file-level generation. */
+export declare function renderDtoExport(schema: DtoMessage, resolver: EnumResolver | undefined): string;
+/** Render the Static type export for a DTO. */
+export declare function renderDtoTypeExport(name: string): string;
 export declare function renderDtoMessage(schema: DtoMessage, options?: {
     resolver?: EnumResolver;
     source?: string;