@pylonts/dsl 1.0.3 → 1.0.5

package/dist/typebox-driver.js

@@ -1,14 +1,23 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.collectDtoImports = collectDtoImports;
+exports.renderDtoExport = renderDtoExport;
+exports.renderDtoTypeExport = renderDtoTypeExport;
 exports.renderDtoMessage = renderDtoMessage;
 const dto_1 = require("./dto");
 function renderString(s) {
     return `'${s.replace(/\\/g, '\\\\').replace(/'/g, "\\'")}'`;
 }
-function renderBasic(field, pattern, resolver) {
+function renderDefault(v) {
+    if (typeof v === 'string')
+        return renderString(v);
+    return JSON.stringify(v);
+}
+function renderBasic(field, pattern, defaultValue, resolver) {
     if (pattern !== undefined && field.type !== 'string') {
         throw new Error(`pattern is only supported on string fields, got ${field.type} (${field.name})`);
     }
+    const def = defaultValue !== undefined ? `default: ${renderDefault(defaultValue)}` : undefined;
     switch (field.type) {
         case 'string': {
             const opts = [];
@@ -18,16 +27,20 @@ function renderBasic(field, pattern, resolver) {
                 opts.push(`maxLength: ${field.maxLength}`);
             if (pattern !== undefined)
                 opts.push(`pattern: ${renderString(pattern)}`);
+            if (def !== undefined)
+                opts.push(def);
             return opts.length > 0 ? `Type.String({ ${opts.join(', ')} })` : 'Type.String()';
         }
         case 'text':
-            return 'Type.String()';
+            return def !== undefined ? `Type.String({ ${def} })` : 'Type.String()';
         case 'integer': {
             const opts = [];
             if (field.min !== undefined)
                 opts.push(`minimum: ${field.min}`);
             if (field.max !== undefined)
                 opts.push(`maximum: ${field.max}`);
+            if (def !== undefined)
+                opts.push(def);
             return opts.length > 0 ? `Type.Integer({ ${opts.join(', ')} })` : 'Type.Integer()';
         }
         case 'bigint':
@@ -37,15 +50,22 @@ function renderBasic(field, pattern, resolver) {
         case 'datetime':
             // Transmitted as string over HTTP: bigint/decimal keep full precision,
             // date/time serialize to string.
-            return 'Type.String()';
+            return def !== undefined ? `Type.String({ ${def} })` : 'Type.String()';
         case 'boolean':
-            return 'Type.Boolean()';
+            return def !== undefined ? `Type.Boolean({ ${def} })` : 'Type.Boolean()';
         case 'json':
-            return 'Type.Unknown()';
+            return def !== undefined ? `Type.Unknown({ ${def} })` : 'Type.Unknown()';
         case 'enum': {
             const ref = resolver?.(field.enum.jsName);
             if (!ref)
                 throw new Error(`enum field ${field.name}: no import ref for ${field.enum.jsName} — pass an EnumResolver`);
+            if (def !== undefined) {
+                const member = field.enum.values.find((v) => v.value === defaultValue);
+                if (!member) {
+                    throw new Error(`enum field ${field.name}: default ${renderDefault(defaultValue)} is not a member of ${field.enum.jsName}`);
+                }
+                return `Type.Enum(${ref.name}, { default: ${ref.name}.${member.symbol} })`;
+            }
             return `Type.Enum(${ref.name})`;
         }
         default:
@@ -70,7 +90,10 @@ function renderValue(f, indent, resolver) {
         return renderObject(f.properties(), indent + 1, resolver);
     }
     // DtoField only wraps a database Field; array/object defs live in the subclasses.
-    return renderBasic(f.field, f.pattern, resolver);
+    // DTO-level default wins over the DB field default; the DB default (string)
+    // is used as a fallback so from() picks carry it into the API contract.
+    const defaultValue = f.default !== undefined ? f.default : f.field.default;
+    return renderBasic(f.field, f.pattern, defaultValue, resolver);
 }
 function collectEnumImports(f, resolver, out) {
     if (f instanceof dto_1.DtoArrayField) {
@@ -89,34 +112,47 @@ function collectEnumImports(f, resolver, out) {
         out.set(`${ref.from}#${ref.name}`, ref);
     }
 }
+/** Collect all imports needed to render a DTO: include() bases + enum references. */
+function collectDtoImports(schema, resolver, out) {
+    for (const base of schema.bases ?? [])
+        out.set(`${base.from}#${base.name}`, base);
+    for (const f of Object.values(schema.fields))
+        collectEnumImports(f, resolver, out);
+}
+/** Render one DTO export (const + type) — no file header, for file-level generation. */
+function renderDtoExport(schema, resolver) {
+    const object = renderObject(schema.fields, 1, resolver);
+    const bases = schema.bases ?? [];
+    const body = bases.length > 0
+        ? `Type.Intersect([${bases.map(renderBase).join(', ')}, ${object}])`
+        : object;
+    return `export const ${schema.name} = ${body};`;
+}
+/** Render the Static type export for a DTO. */
+function renderDtoTypeExport(name) {
+    return `export type ${name} = Static<typeof ${name}>;`;
+}
 function renderDtoMessage(schema, options = {}) {
     const { resolver, source } = options;
     const imports = new Map();
-    for (const base of schema.bases ?? [])
-        imports.set(`${base.from}#${base.name}`, base);
-    for (const f of Object.values(schema.fields))
-        collectEnumImports(f, resolver, imports);
+    collectDtoImports(schema, resolver, imports);
     const header = [
         '// AUTO-GENERATED by typebox-driver — DO NOT EDIT',
         ...(source !== undefined ? [`// Source: ${source}`] : []),
         "import { Type, Static } from '@sinclair/typebox';",
         ...[...imports.values()].map((r) => `import { ${r.name} } from '${r.from}';`),
     ];
-    const object = renderObject(schema.fields, 1, resolver);
-    const bases = schema.bases ?? [];
-    const body = bases.length > 0
-        ? `Type.Intersect([${bases.map(renderBase).join(', ')}, ${object}])`
-        : object;
     return [
         ...header,
         '',
-        `export const ${schema.name} = ${body};`,
-        `export type ${schema.name} = Static<typeof ${schema.name}>;`,
+        renderDtoExport(schema, resolver),
+        renderDtoTypeExport(schema.name),
         '',
     ].join('\n');
 }
 function renderBase(base) {
-    return base.args !== undefined && base.args.length > 0
-        ? `${base.name}(${base.args.join(', ')})`
-        : base.name;
+    if (base.args === undefined || base.args.length === 0)
+        return base.name;
+    const args = base.args.map((a) => (typeof a === 'string' ? a : a.name));
+    return `${base.name}(${args.join(', ')})`;
 }

package/dist/utils.d.ts

@@ -0,0 +1,2 @@
+/** snake_case → camelCase: mer_id → merId; names without underscores are unchanged */
+export declare function toCamelCase(name: string): string;

package/dist/utils.js

@@ -0,0 +1,8 @@
+"use strict";
+// ── naming conversions ──
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.toCamelCase = toCamelCase;
+/** snake_case → camelCase: mer_id → merId; names without underscores are unchanged */
+function toCamelCase(name) {
+    return name.replace(/_([a-z])/g, (_, c) => c.toUpperCase());
+}

package/docs/dto.md

@@ -1,13 +1,13 @@
 # 定义 DTO（四种方向）
 
-DTO 描述接口出入参。方向决定语义与可选性规则：
+DTO 描述接口出入参。方向决定可选性规则，由各方向工厂设置；**规则统一只在 `field.optional === undefined` 时生效**（作者已显式设置的跳过）：
 
-| 构建器 | 方向 | 用途 |
+| 构建器 | 方向 | 可选性规则 |
 |---|---|---|
-| `buildInput` | input | 新增/修改请求体 |
-| `buildOutput` | output | 响应体 |
-| `buildQuery` | query | 分页 + 过滤查询（字段恒为可选） |
-| `buildPk` | pk | 按主键取详情 |
+| `buildInput` | input | 按 DB 列规则：可空 / 有默认 / 自增列 → 可选；NOT NULL 无默认 → 必填 |
+| `buildOutput` | output | 不设置（保持字段构建器/作者设置） |
+| `buildQuery` | query | 全部可选 |
+| `buildPk` | pk | 主键字段必填，其他字段可选 |
 
 ## 从表提取字段
 
@@ -22,7 +22,7 @@ buildOutput('OrderRow', from(order, [order.fields.id, order.fields.order_no]));
 
 // 查询：分页 + 过滤（query 字段恒为可选，.op() 声明比较操作符）
 buildQuery('OrderPageQuery', {
-  keyword: dtoField(stringField({ maxLength: 32 })).op('like'),
+  keyword: dtoField(stringField({ maxLength: 32 })).setOperator('like'),
   ...from(order, [order.fields.mer_id]),
 });
 
@@ -30,16 +30,23 @@ buildQuery('OrderPageQuery', {
 buildPk('OrderDetailRequest', from(order, [order.fields.id]));
 ```
 
-`from(table, fields)` 提取表字段包装为 DTO 字段，字段实例与表共享，`name/schema` 保持指向表。
+`from(table, fields)` 提取表字段包装为 DTO 字段，字段实例与表共享，`name/schema` 保持指向表。**DTO 字段名转 camelCase**（`mer_id` → `merId`），与 DB 列名（snake_case）分离。`from()` 本身不做任何可选性推断——推断在各方向工厂。
 
 ## 独立字段
 
-不来自表的内联字段直接用 `dtoField(...)` 包装任意字段构建器，可加 `pattern`、`optional`、`operator`。
+不来自表的内联字段直接用 `dtoField(...)` 包装任意字段构建器，可加 `pattern`、`optional`、`operator`、`default`。
 
 ```ts
-dtoField(stringField({ maxLength: 32 })).op('like')
+dtoField(stringField({ maxLength: 32 })).setOperator('like')
+dtoField(intField()).setDefault(0)        // TypeBox default 注解
 ```
 
+## 默认值
+
+- `setDefault(v)` 设 DTO 层默认值，渲染为 TypeBox `default:` 注解（`Type.String({ default: 'PENDING' })`、`Type.Enum(OrderStatus, { default: OrderStatus.PENDING })`）。
+- 枚举默认值必须是该枚举的成员值（value），渲染时解析为成员引用；非成员值直接报错。
+- 未显式设置时，fallback 到字段构建器的 `default`（DB 默认值，string），`from()` 提取的字段自动带出。
+
 ## 继承基础 schema
 
 ```ts

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pylonts/dsl",
-  "version": "1.0.3",
+  "version": "1.0.5",
   "description": "Schema definition DSL with drivers: MySQL DDL, TS enum, TypeBox schema codegen.",
   "type": "commonjs",
   "main": "src/index.ts",

package/src/bases.ts

@@ -0,0 +1,20 @@
+import type { DtoMessage, ImportRef } from './dto';
+
+// 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 */
+export const PageRequest: ImportRef = { from: '@pylonts/core', name: 'PageRequest' };
+
+/** Paginated list response base — renders `import { PageResult } from '@pylonts/core'` + `PageResult(<row>)` */
+export const PageResult = (row: DtoMessage): ImportRef => ({
+  from: '@pylonts/core',
+  name: 'PageResult',
+  args: [row],
+});

package/src/check-inheritance.ts

@@ -0,0 +1,86 @@
+import type { DtoMessage } from './dto';
+import type { TableSchema } from './dsl';
+
+// Inheritance check — find DTO fields that should inherit from a DB column
+// (via from()) but were written by hand, so they miss the column's
+// type / semantic / optionality backfill.
+//
+// Inference: the tables a DSL file is about are inferred from the referenced
+// fields in the same file (each Field carries schema identity via .schema).
+// A field without a table ref whose name matches a column of an inferred table
+// is a candidate for inheritance. Fields with an explicit semantic or enum type
+// are treated as author-intent and skipped.
+//
+// False-positive boundary: when a DSL file has zero referenced fields, no table
+// can be inferred and nothing is reported (never guess which table a hand-written
+// field belongs to).
+
+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[];
+}
+
+/** snake_case → camelCase: order_no → orderNo; names without underscores are unchanged */
+function toCamelCase(name: string): string {
+  return name.replace(/_([a-z])/g, (_, c: string) => c.toUpperCase());
+}
+
+function isDtoMessage(v: unknown): v is DtoMessage {
+  if (typeof v !== 'object' || v === null) return false;
+  const o = v as Record<string, unknown>;
+  return o.type === 'dto' && typeof o.name === 'string' && typeof o.fields === 'object' && o.fields !== null;
+}
+
+interface FieldEntry {
+  name: string;
+  field: { schema?: { type?: string }; semantic?: string; type?: string };
+  container: string;
+}
+
+function collectFields(mod: Record<string, unknown>): FieldEntry[] {
+  const out: FieldEntry[] = [];
+  for (const [name, v] of Object.entries(mod)) {
+    if (isDtoMessage(v)) {
+      const container = v as { fields: Record<string, { field: FieldEntry['field'] }> };
+      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. */
+export function checkInheritance(mod: Record<string, unknown>, file: string): InheritanceIssue[] {
+  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<string, Map<string, string>>(); // table -> camelCol -> origCol
+  for (const f of fields) {
+    const schema = f.field.schema;
+    if (schema?.type !== 'table') continue;
+    const table = schema as TableSchema;
+    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: InheritanceIssue[] = [];
+  for (const f of fields) {
+    if (f.field.schema?.type === 'table') continue;
+    if (f.field.semantic !== undefined || f.field.type === 'enum') continue;
+    const candidates: string[] = [];
+    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/src/dsl.ts

@@ -8,17 +8,24 @@ export interface SchemaBase {
   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 {
@@ -132,7 +139,24 @@ export type ForeignKey = {
   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 class TableSchema implements CollectionSchemaBase {
+  type = 'table';
+  name: string;
+  description?: string;
   /** 分页 */
   paginated?: boolean;
   /** 系统操作者（如小程序为 C 端用户，管理端为运营） */
@@ -148,6 +172,28 @@ export interface TableSchema extends SchemaBase {
   /** 引用的实体短语（词典条目）：本表归属的实体；关联表等多实体场景不需要 */
   phrase?: DictionaryEntry;
   fields: Record<string, Field>;
+
+  constructor(name: string, options: TableSchemaOptions) {
+    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: Field): boolean {
+    if (this.primaryKey === undefined) return false;
+    return Array.isArray(this.primaryKey)
+      ? this.primaryKey.includes(fieldRef)
+      : this.primaryKey === fieldRef;
+  }
 }
 
 // Field builders: type and jsType are fixed, pass extra properties only.
@@ -200,23 +246,8 @@ export function enumField(extra: Omit<EnumField, 'name' | 'type' | 'jsType'>): E
   return { name: '', type: 'enum', jsType, ...extra };
 }
 
-export 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 {
-  const table: TableSchema = { name, ...schema };
+export function defineTable(name: string, schema: TableSchemaOptions): TableSchema {
+  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/src/dto.ts

@@ -1,4 +1,5 @@
-import { BaseField, Field, SchemaBase, TableSchema } from './dsl';
+import { BaseField, CollectionSchemaBase, Field, SchemaBase, TableSchema } from './dsl';
+import { toCamelCase } from './utils';
 
 // Interface (DTO) field definitions.
 // Naming convention: all DTO types and builders use the Dto prefix.
@@ -16,18 +17,15 @@ 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';
@@ -40,23 +38,24 @@ export type DtoObjectFieldDef = BaseField & {
   properties: Record<string, DtoField>;
 };
 
-export class DtoField {
+export 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;
+  /** TypeBox default annotation (API contract level); falls back to field.default (DB default) */
+  default?: unknown;
 
-  constructor(field: Field | DtoArrayFieldDef | DtoObjectFieldDef, extra: DtoExtras = {}) {
+  constructor(field: Field | DtoArrayFieldDef | DtoObjectFieldDef) {
     this.name = '';
     this.field = field;
-    this.pattern = extra.pattern;
-    this.optional = extra.optional;
-    this.operator = extra.operator;
   }
 
   setPattern(value: string): this {
@@ -64,15 +63,34 @@ export class DtoField {
     return this;
   }
 
+  setDescription(value: string): this {
+    this.description = value;
+    return this;
+  }
+
+  getDescription(): string | undefined {
+    return this.description;
+  }
+
+  /** True when this field wraps a DB column (picked via from()); false for inline fields. */
+  isColumn(): boolean {
+    return this.field.schema?.type === 'table';
+  }
+
   setOptional(value: boolean): this {
     this.optional = value;
     return this;
   }
 
+  /** Set a default value — emitted as a TypeBox schema default annotation */
+  setDefault(value: unknown): this {
+    this.default = value;
+    return this;
+  }
+
   /** 查询比较操作符（query 方向字段）。Rule B: 查询字段恒为可选 */
-  op(value: Operator): this {
+  setOperator(value: Operator): this {
     this.operator = value;
-    this.optional = true;
     return this;
   }
 
@@ -99,46 +117,55 @@ export class DtoObjectField extends DtoField {
   }
 }
 
-export type DtoDirection = 'input' | 'output' | 'query' | 'pk';
+export enum DtoDirection {
+  Input = 'input',
+  Output = 'output',
+  Query = 'query',
+  Pk = 'pk',
+}
 
-export interface DtoMessage extends SchemaBase {
+export class DtoMessage implements CollectionSchemaBase {
+  type = 'dto';
+  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) {
+    this.name = name;
+    this.direction = direction;
+    this.fields = fields;
+    this.description = description;
+  }
+
   /** 引用已存在的 TypeBox base schema，例如 include({ from: '@pylonts/core', name: 'PageRequest' }) */
-  include(...refs: ImportRef[]): DtoMessage;
+  include(...refs: ImportRef[]): this {
+    this.bases.push(...refs);
+    return this;
+  }
 }
 
-export function dtoField(field: Field, extra: DtoExtras = {}): DtoField {
-  return new DtoField(field, extra);
+export function dtoField(field: Field): DtoField {
+  return new DtoField(field);
 }
 
-export function dtoArrayField(def: { items: DtoField } & Omit<BaseField, 'name'>, extra: DtoExtras = {}): DtoArrayField {
-  return new DtoArrayField({ name: '', type: 'array', jsType: 'array', ...def }, extra);
+export function dtoArrayField(def: { items: DtoField | DtoMessage } & Omit<BaseField, 'name'>): DtoArrayField {
+  // 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 });
 }
 
-export function dtoObjectField(def: { properties: Record<string, DtoField> } & Omit<BaseField, 'name'>, extra: DtoExtras = {}): DtoObjectField {
-  return new DtoObjectField({ name: '', type: 'object', jsType: 'object', ...def }, extra);
+export function dtoObjectField(def: { properties: Record<string, DtoField> } & Omit<BaseField, 'name'>): DtoObjectField {
+  return new DtoObjectField({ name: '', type: 'object', jsType: 'object', ...def });
 }
 
 function buildMessage(name: string, direction: DtoDirection, fields: Record<string, DtoField>, description?: string): DtoMessage {
-  const message: DtoMessage = {
-    name,
-    direction,
-    description,
-    fields,
-    bases: [],
-    include(...refs: ImportRef[]): DtoMessage {
-      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)) {
@@ -157,19 +184,40 @@ function buildMessage(name: string, direction: DtoDirection, fields: Record<stri
 }
 
 export function buildInput(name: string, fields: Record<string, DtoField>, description?: string): DtoMessage {
-  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 as Field;
+    if (f.schema?.type !== 'table') continue;
+    const table = f.schema as TableSchema;
+    field.optional = f.optional !== false || f.default !== undefined || table.autoIncrement === f;
+  }
+  return message;
 }
 
 export function buildOutput(name: string, fields: Record<string, DtoField>, description?: string): DtoMessage {
-  return buildMessage(name, 'output', fields, description);
+  return buildMessage(name, DtoDirection.Output, fields, description);
 }
 
 export function buildQuery(name: string, fields: Record<string, DtoField>, description?: string): DtoMessage {
-  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;
 }
 
 export function buildPk(name: string, fields: Record<string, DtoField>, description?: string): DtoMessage {
-  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 as Field;
+    const table = f.schema as TableSchema | undefined;
+    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). */
@@ -179,7 +227,9 @@ export function from(table: TableSchema, fields: Field[]): Record<string, DtoFie
     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[toCamelCase(field.name)] = dtoField(field);
   }
   return out;
 }