@pylonts/dsl 1.1.5 → 1.1.6

package/src/dto.ts

@@ -1,248 +1,264 @@
-import { BaseField, CollectionSchemaBase, Field, Operator, SchemaBase } from './dsl.js';
-import { TableSchema } from './db.js';
-import type { ImportBase } from './import-base.js';
-import { toCamelCase } from './utils.js';
-
-// Interface (DTO) field definitions.
-// Naming convention: all DTO types and builders use the Dto prefix.
-// A DtoField stores the database Field and the API-only extras separately.
-
-/** Re-export — Operator lives on the DSL level (see dsl.ts). */
-export type { Operator } from './dsl.js';
-
-/** Re-export — ImportBase lives on its own module (see import-base.ts). */
-export type { ImportBase } from './import-base.js';
-
-/** Re-export — MockDescriptor lives on its own module (see mock.ts). */
-export type { MockDescriptor } from './mock.js';
-
-/**
- * Reference to an existing TypeBox base schema by its import location.
- * Serializable metadata: the driver renders `import { name } from 'from'`
- * and `Type.Intersect([name, ...])` — the runtime schema is never loaded by the DSL.
- */
-export interface ImportRef extends ImportBase {
-  /**
-   * 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 DtoArrayFieldDef = BaseField & {
-  type: 'array';
-  jsType: 'array';
-  /** Element type: inline DtoField, or a reference to an existing DTO (rendered by name) */
-  items: DtoField | DtoMessage;
-};
-
-export type DtoObjectFieldDef = BaseField & {
-  type: 'object';
-  jsType: 'object';
-  properties: Record<string, DtoField>;
-};
-
-export class DtoField implements SchemaBase {
-  /** DTO 语义字段名（接口字段名），与 field.name（数据库列名）含义不同。
-   *  构造时未知，由 buildMessage 从 map key 反写。 */
-  name: string;
-  /** 字段描述 */
-  description?: string;
-  /** 所属容器（buildMessage / defineRouteData / definePageData 反写） */
-  schema?: CollectionSchemaBase;
-  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) {
-    this.name = '';
-    this.field = field;
-  }
-
-  setPattern(value: string): this {
-    this.pattern = value;
-    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: 查询字段恒为可选 */
-  setOperator(value: Operator): this {
-    this.operator = value;
-    return this;
-  }
-
-  /** optional 优先于 field.optional */
-  isOptional(): boolean {
-    if (this.optional !== undefined) return this.optional;
-    return this.field.optional ?? false;
-  }
-}
-
-export class DtoArrayField extends DtoField {
-  declare field: DtoArrayFieldDef;
-
-  /** Element type: inline DtoField or a referenced DtoMessage (rendered by name). */
-  items(): DtoField | DtoMessage {
-    return this.field.items;
-  }
-}
-
-export class DtoObjectField extends DtoField {
-  declare field: DtoObjectFieldDef;
-
-  properties(): Record<string, DtoField> {
-    return this.field.properties;
-  }
-}
-
-export enum DtoDirection {
-  Input = 'input',
-  Output = 'output',
-  Query = 'query',
-  Pk = 'pk',
-}
-
-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[] = [];
-
-  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[]): this {
-    this.bases.push(...refs);
-    return this;
-  }
-}
-
-export function dtoField(field: Field): DtoField {
-  return new DtoField(field);
-}
-
-export function dtoArrayField(def: { items: DtoField | DtoMessage } & Omit<BaseField, 'name'>): DtoArrayField {
-  // Items stay as-is: an inline DtoField is rendered inline, a DtoMessage is
-  // referenced by name (the driver renders Type.Array(<DtoName>)).
-  return new DtoArrayField({ name: '', type: 'array', jsType: 'array', ...def });
-}
-
-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 = 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)) {
-    const df = message.fields[key];
-    if (!(df instanceof DtoField)) {
-      const got = df === null || df === undefined ? String(df) : `${(df as object).constructor.name ?? typeof df}`;
-      throw new Error(
-        `[dto] DTO "${name}" field "${key}" must be a DtoField (created with dtoField()/dtoArrayField()/dtoObjectField()), got ${got}. ` +
-        `Did you pass enumField(...) directly? Use dtoField(enumField({...})) instead.`
-      );
-    }
-    df.name = key;
-    df.schema = message;
-    // Custom (inline) fields are owned by this DTO: write back name + schema.
-    // Fields picked via from() share the database Field instance whose
-    // name/schema already point to the table — leave them untouched.
-    if (df.field.schema === undefined) {
-      df.field.name = key;
-      df.field.schema = message;
-    }
-  }
-  return message;
-}
-
-export function buildInput(name: string, fields: Record<string, DtoField>, description?: string): DtoMessage {
-  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 → optional, else required.
-  // PK columns are always 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 = table.isPk(f) ? false : f.optional !== false || f.default !== undefined;
-  }
-  return message;
-}
-
-export function buildOutput(name: string, fields: Record<string, DtoField>, description?: string): DtoMessage {
-  return buildMessage(name, DtoDirection.Output, fields, description);
-}
-
-export function buildQuery(name: string, fields: Record<string, DtoField>, description?: string): DtoMessage {
-  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 {
-  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). */
-export function from(table: TableSchema, fields: Field[]): Record<string, DtoField> {
-  const out: Record<string, DtoField> = {};
-  for (const field of fields) {
-    if (field.schema !== table) {
-      throw new Error(`dto.from(${table.name}): field ${field.name} does not belong to this table`);
-    }
-    // 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;
+import { BaseField, CollectionSchemaBase, Field, Operator, SchemaBase } from './dsl.js';
+import { TableSchema } from './db.js';
+import type { ImportBase } from './import-base.js';
+import type { ThirdMethodSchema } from './third-service.js';
+import { toCamelCase } from '@pylonts/core';
+
+// Interface (DTO) field definitions.
+// Naming convention: all DTO types and builders use the Dto prefix.
+// A DtoField stores the database Field and the API-only extras separately.
+
+/** Re-export — Operator lives on the DSL level (see dsl.ts). */
+export type { Operator } from './dsl.js';
+
+/** Re-export — ImportBase lives on its own module (see import-base.ts). */
+export type { ImportBase } from './import-base.js';
+
+/** Re-export — MockDescriptor lives on its own module (see mock.ts). */
+export type { MockDescriptor } from './mock.js';
+
+/**
+ * Reference to an existing TypeBox base schema by its import location.
+ * Serializable metadata: the driver renders `import { name } from 'from'`
+ * and `Type.Intersect([name, ...])` — the runtime schema is never loaded by the DSL.
+ */
+export interface ImportRef extends ImportBase {
+  /**
+   * 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 DtoArrayFieldDef = BaseField & {
+  type: 'array';
+  jsType: 'array';
+  /** Element type: inline DtoField, or a reference to an existing DTO (rendered by name) */
+  items: DtoField | DtoMessage;
+};
+
+export type DtoObjectFieldDef = BaseField & {
+  type: 'object';
+  jsType: 'object';
+  properties: Record<string, DtoField>;
+};
+
+export class DtoField implements SchemaBase {
+  /** DTO 语义字段名（接口字段名），与 field.name（数据库列名）含义不同。
+   *  构造时未知，由 buildMessage 从 map key 反写。 */
+  name: string;
+  /** 字段描述 */
+  description?: string;
+  /** 所属容器（buildMessage / defineRouteData / definePageData 反写） */
+  schema?: CollectionSchemaBase;
+  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) {
+    this.name = '';
+    this.field = field;
+  }
+
+  setPattern(value: string): this {
+    this.pattern = value;
+    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: 查询字段恒为可选 */
+  setOperator(value: Operator): this {
+    this.operator = value;
+    return this;
+  }
+
+  /** optional 优先于 field.optional */
+  isOptional(): boolean {
+    if (this.optional !== undefined) return this.optional;
+    return this.field.optional ?? false;
+  }
+}
+
+export class DtoArrayField extends DtoField {
+  declare field: DtoArrayFieldDef;
+
+  /** Element type: inline DtoField or a referenced DtoMessage (rendered by name). */
+  items(): DtoField | DtoMessage {
+    return this.field.items;
+  }
+}
+
+export class DtoObjectField extends DtoField {
+  declare field: DtoObjectFieldDef;
+
+  properties(): Record<string, DtoField> {
+    return this.field.properties;
+  }
+}
+
+export enum DtoDirection {
+  Input = 'input',
+  Output = 'output',
+  Query = 'query',
+  Pk = 'pk',
+}
+
+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[] = [];
+
+  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[]): this {
+    this.bases.push(...refs);
+    return this;
+  }
+}
+
+export function dtoField(field: Field): DtoField {
+  return new DtoField(field);
+}
+
+export function dtoArrayField(def: { items: DtoField | DtoMessage } & Omit<BaseField, 'name'>): DtoArrayField {
+  // Items stay as-is: an inline DtoField is rendered inline, a DtoMessage is
+  // referenced by name (the driver renders Type.Array(<DtoName>)).
+  return new DtoArrayField({ name: '', type: 'array', jsType: 'array', ...def });
+}
+
+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 = 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)) {
+    const df = message.fields[key];
+    if (!(df instanceof DtoField)) {
+      const got = df === null || df === undefined ? String(df) : `${(df as object).constructor.name ?? typeof df}`;
+      throw new Error(
+        `[dto] DTO "${name}" field "${key}" must be a DtoField (created with dtoField()/dtoArrayField()/dtoObjectField()), got ${got}. ` +
+        `Did you pass enumField(...) directly? Use dtoField(enumField({...})) instead.`
+      );
+    }
+    df.name = key;
+    df.schema = message;
+    // Custom (inline) fields are owned by this DTO: write back name + schema.
+    // Fields picked via from() share the database Field instance whose
+    // name/schema already point to the table — leave them untouched.
+    if (df.field.schema === undefined) {
+      df.field.name = key;
+      df.field.schema = message;
+    }
+  }
+  return message;
+}
+
+export function buildInput(name: string, fields: Record<string, DtoField>, description?: string): DtoMessage {
+  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 → optional, else required.
+  // PK columns are always 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 = table.isPk(f) ? false : f.optional !== false || f.default !== undefined;
+  }
+  return message;
+}
+
+export function buildOutput(name: string, fields: Record<string, DtoField>, description?: string): DtoMessage {
+  return buildMessage(name, DtoDirection.Output, fields, description);
+}
+
+export function buildQuery(name: string, fields: Record<string, DtoField>, description?: string): DtoMessage {
+  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 {
+  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?.type === 'table' ? (f.schema as TableSchema) : undefined;
+    field.optional = table !== undefined && table.isPk(f) ? false : true;
+  }
+  return message;
+}
+
+/** Field-collection source a DTO can project from: a DB table or a third-party method message. */
+export type DtoFieldSource = TableSchema | ThirdMethodSchema;
+
+// Type guard instead of a plain discriminant check: TableSchema.type is declared
+// as a class property, so TS widens it to string and cannot narrow the union.
+function isThirdMethod(source: DtoFieldSource): source is ThirdMethodSchema {
+  return source.type === 'thirdMethod';
+}
+
+function ownsField(source: DtoFieldSource, field: Field): boolean {
+  if (isThirdMethod(source)) return Object.values(source.fields).includes(field);
+  return Object.values(source.columns).includes(field);
+}
+
+/** Project fields from a field-collection source (table or third-party method
+ *  message) and wrap them as DTO fields (aligned with dto.from). */
+export function from(source: DtoFieldSource, fields: Field[]): Record<string, DtoField> {
+  const out: Record<string, DtoField> = {};
+  for (const field of fields) {
+    if (!ownsField(source, field)) {
+      throw new Error(`dto.from(${source.name}): field ${field.name} does not belong to this ${source.type}`);
+    }
+    // DB columns map to camelCase interface names (mer_id → merId); wire-format
+    // names are protocol names themselves and stay untouched.
+    out[isThirdMethod(source) ? field.name : toCamelCase(field.name)] = dtoField(field);
+  }
+  return out;
 }

package/src/endpoint.ts

@@ -0,0 +1,18 @@
+import { SchemaBase } from './dsl.js';
+import type { DtoMessage } from './dto.js';
+
+/** Shared API call signature: one request DTO in, one response shape out.
+ *  Referenced by both backend controller methods and frontend page providers —
+ *  both sides must use the exact same instance, so drift is impossible. */
+export interface EndpointSchema extends SchemaBase {
+  type: 'endpoint';
+  args: DtoMessage;
+  results: DtoMessage | number | boolean | string;
+}
+
+export function defineEndpoint(
+  name: string,
+  options: { args: DtoMessage; results: DtoMessage | number | boolean | string; description?: string },
+): EndpointSchema {
+  return { type: 'endpoint', name, args: options.args, results: options.results, description: options.description };
+}

package/src/exception.ts

@@ -0,0 +1,28 @@
+import type { SchemaBase } from './dsl.js';
+import type { ImportBase } from './import-base.js';
+
+// Exception declarations (logic-flatten-spec §5.3): each method declares the
+// exceptions it throws, with retryability. The runtime class is referenced by
+// import location — never loaded by the DSL.
+
+/** Describes an exception a method can throw. */
+export interface ExceptionSchema extends SchemaBase, Omit<ImportBase, 'type'> {
+  type: 'exception';
+  /** Whether the caller may safely retry after catching this exception. */
+  retryable: boolean;
+}
+
+export function defineException(options: {
+  name: string;
+  from: string;
+  retryable: boolean;
+  description?: string;
+}): ExceptionSchema {
+  return {
+    type: 'exception',
+    name: options.name,
+    from: options.from,
+    retryable: options.retryable,
+    description: options.description,
+  };
+}

package/src/field-rule.ts

@@ -0,0 +1,47 @@
+import type { SchemaBase } from './dsl.js';
+
+// Field rules: the third semantic dimension of a Field. A rule is a named
+// transformation between two ends — scale (fen↔yuan), encrypt/decrypt,
+// mask/unmask. The rule owns both ends; a binding says which field plays
+// which end. Rules are unique per semantic name (checked at definition).
+
+/** One end of a field rule (e.g. 'fen' / 'yuan', 'plain' / 'cipher', 'raw' / 'masked'). */
+export interface FieldRuleEnd {
+  /** End name — written back by defineFieldRule from the ends map key. */
+  name: string;
+  description?: string;
+}
+
+/** A semantic transformation rule between two field representations. */
+export interface FieldRuleSchema extends SchemaBase {
+  type: 'fieldRule';
+  /** Rule name — the semantic uniqueness key. */
+  name: string;
+  /** The two ends of the rule, keyed by end name. */
+  ends: Record<string, FieldRuleEnd>;
+}
+
+/** One rule per semantic name. Defining the same name twice throws. */
+const ruleRegistry = new Map<string, FieldRuleSchema>();
+
+export function defineFieldRule(options: {
+  name: string;
+  ends: Record<string, Omit<FieldRuleEnd, 'name'>>;
+  description?: string;
+}): FieldRuleSchema {
+  if (ruleRegistry.has(options.name)) {
+    throw new Error(`fieldRule '${options.name}' is already defined — one rule per semantic`);
+  }
+  const ends: Record<string, FieldRuleEnd> = {};
+  for (const key of Object.keys(options.ends)) {
+    ends[key] = { name: key, description: options.ends[key].description };
+  }
+  const rule: FieldRuleSchema = {
+    type: 'fieldRule',
+    name: options.name,
+    description: options.description,
+    ends,
+  };
+  ruleRegistry.set(options.name, rule);
+  return rule;
+}