@pylonts/dsl 1.1.12 → 1.1.14

package/src/dto.ts

@@ -1,8 +1,7 @@
-import { BaseField, CollectionSchemaBase, Field, Operator, SchemaBase } from './dsl.js';
+import { BaseField, CollectionSchemaBase, Field, Operator, SchemaBase, walkContainer } from './dsl.js';
 import { TableSchema } from './db.js';
 import type { EntitySchema } from './entity.js';
 import type { ImportBase } from './import-base.js';
-import type { ThirdMethodSchema } from './third-service.js';
 import { toCamelCase } from '@pylonts/core';
 
 // Interface (DTO) field definitions.
@@ -60,6 +59,8 @@ export class DtoField implements SchemaBase {
   operator?: Operator;
   /** TypeBox default annotation (API contract level); falls back to field.default (DB default) */
   default?: unknown;
+  /** Optional reference to another DtoField — this field reuses the referenced field's type/constraints */
+  ref?: DtoField;
 
   constructor(field: Field | DtoArrayFieldDef | DtoObjectFieldDef) {
     this.name = '';
@@ -96,6 +97,12 @@ export class DtoField implements SchemaBase {
     return this;
   }
 
+  /** Reference another DtoField — this field reuses the referenced field's type/constraints */
+  setRef(value: DtoField): this {
+    this.ref = value;
+    return this;
+  }
+
   /** 查询比较操作符（query 方向字段）。Rule B: 查询字段恒为可选 */
   setOperator(value: Operator): this {
     this.operator = value;
@@ -157,10 +164,22 @@ export class DtoMessage implements CollectionSchemaBase {
   }
 }
 
-export function dtoField(field: Field): DtoField {
+export function dtoField(field: Field | DtoArrayFieldDef | DtoObjectFieldDef): DtoField {
   return new DtoField(field);
 }
 
+/** Structural check — DtoMessage instances may come from a different module copy, so instanceof is unreliable. */
+export function isDtoMessage(v: unknown): v is DtoMessage {
+  if (typeof v !== 'object' || v === null) return false;
+  return (v as Record<string, unknown>).type === 'dto';
+}
+
+/** Structural check — a DtoField wraps a Field in a .field property and has no .type of its own. */
+export function isDtoField(v: unknown): v is DtoField {
+  if (typeof v !== 'object' || v === null) return false;
+  return 'field' in v && !('type' in v);
+}
+
 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>)).
@@ -193,10 +212,55 @@ function buildMessage(name: string, direction: DtoDirection, fields: Record<stri
       df.field.name = key;
       df.field.schema = message;
     }
+    writeBackNested(df, message);
   }
   return message;
 }
 
+/** Write back name/schema on nested DTO fields (array items, object
+ *  properties) — both plain-Field containers (objectField/arrayField) and
+ *  DtoField containers (dtoObjectField/dtoArrayField). DtoMessage item
+ *  references are skipped — they carry their own identity. */
+function writeBackNested(df: DtoField, message: DtoMessage): void {
+  const f = df.field;
+  if (f.type === 'array') {
+    const items = f.items;
+    if (isDtoMessage(items)) return;
+    if (isDtoField(items)) {
+      writeBackNested(items, message);
+      return;
+    }
+    walkContainer(items, writeBackLeaf(message));
+    return;
+  }
+  if (f.type === 'object') {
+    for (const [key, child] of Object.entries(f.properties)) {
+      if (isDtoField(child)) {
+        child.name = key;
+        child.schema = message;
+        if (child.field.schema === undefined) {
+          child.field.name = key;
+          child.field.schema = message;
+        }
+        writeBackNested(child, message);
+      } else {
+        writeBackLeaf(message)(child, key);
+      }
+    }
+  }
+}
+
+/** Name/schema write-back for a plain Field (own fields only — shared
+ *  instances keep their original identity). */
+function writeBackLeaf(message: DtoMessage): (f: Field, key?: string) => void {
+  return (f, key) => {
+    if (key !== undefined && f.schema === undefined) {
+      f.name = key;
+      f.schema = 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
@@ -235,33 +299,34 @@ export function buildPk(name: string, fields: Record<string, DtoField>, descript
   return message;
 }
 
-/** Field-collection source a DTO can project from: a DB table, a third-party
- *  method message, or an entity (which may carry aggregate fields). */
-export type DtoFieldSource = TableSchema | ThirdMethodSchema | EntitySchema;
-
-// 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';
-}
+/** Field-collection source a DTO can project from: a DB table, another DTO
+ *  message (protocol fields keep their names), or an entity (which may carry
+ *  aggregate fields). */
+export type DtoFieldSource = TableSchema | DtoMessage | EntitySchema;
 
-function ownsField(source: DtoFieldSource, field: Field): boolean {
-  if (isThirdMethod(source)) return Object.values(source.fields).includes(field);
-  return Object.values(source.columns).includes(field);
+function ownsField(source: DtoFieldSource, field: Field | DtoArrayFieldDef | DtoObjectFieldDef): boolean {
+  if (isDtoMessage(source)) {
+    return Object.values(source.fields).some((df) => df.field === field);
+  }
+  return Object.values(source.columns).some((c) => c === field);
 }
 
-/** Project fields from a field-collection source (table, third-party method
- *  message or entity) and wrap them as DTO fields (aligned with dto.from). */
-export function from(source: DtoFieldSource, fields: Field[]): Record<string, DtoField> {
+/** Project fields from a field-collection source (table, DTO message or
+ *  entity) and wrap them as DTO fields (aligned with dto.from). Shared Field
+ *  instances keep their original identity — the projection references them. */
+export function from(
+  source: DtoFieldSource,
+  fields: (Field | DtoArrayFieldDef | DtoObjectFieldDef)[],
+): 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}`);
+      throw new Error(`dto.from(${source.name}): field ${field.name} does not belong to this ${isDtoMessage(source) ? 'dto' : source.type}`);
     }
     // DB columns map to camelCase interface names (mer_id → merId); aggregate
-    // field names are already camel and pass through; wire-format names are
+    // field names are already camel and pass through; DTO message fields are
     // protocol names themselves and stay untouched.
-    out[isThirdMethod(source) ? field.name : toCamelCase(field.name)] = dtoField(field);
+    out[isDtoMessage(source) ? field.name : toCamelCase(field.name)] = dtoField(field);
   }
   return out;
 }

package/src/entity.ts

@@ -1,43 +1,44 @@
-import type { Field, SchemaBase } from './dsl.js';
-import type { FrontAppSchema, ProjectApiSchema } from './project.js';
-
-/** A row object: a set of database columns. Columns may come from one table
- *  (write args of insert/update/upsert) or span tables through the main
- *  table's foreign keys (read results of find/get) — where the columns come
- *  from is the responsibility of the consuming position, not of this schema.
- *  Storage is entity_schema/{api.name}/{app.name}/entity/{table}.entity.ts:
- *  one file per table (the main table), any number of entities per file.
- *  "Row" is only a naming convention for read-shaped entities
- *  (OrderListRow, OrderDetailRow) — they are all defineEntity declarations. */
-export interface EntitySchema extends SchemaBase {
-  type: 'entity';
-  /** The backend api module this entity belongs to (shared instance from
-   *  project.config.ts apis). Entities are always backend-side. */
-  api: ProjectApiSchema;
-  /** The frontend app this entity belongs to (shared instance from project.config). */
-  app: FrontAppSchema;
-  /** The columns of this row object: main-table columns, external reference
-   *  columns, and — for aggregate result entities — aggField columns
-   *  (count/sum/avg outputs). */
-  columns: Field[];
-}
-
-export function defineEntity(options: {
-  name: string;
-  api: ProjectApiSchema;
-  app: FrontAppSchema;
-  columns: Field[];
-  description?: string;
-}): EntitySchema {
-  if (!options.api.apps.includes(options.app)) {
-    throw new Error(`entity ${options.name}: api '${options.api.name}' does not serve app '${options.app.name}'`);
-  }
-  return {
-    type: 'entity',
-    name: options.name,
-    description: options.description,
-    api: options.api,
-    app: options.app,
-    columns: options.columns,
-  };
+import type { Field, SchemaBase } from './dsl.js';
+import type { FrontAppSchema, ProjectApiSchema } from './project.js';
+
+/** A row object: a set of database columns. Columns may come from one table
+ *  (write args of insert/update/upsert) or span tables through the main
+ *  table's foreign keys (read results of find/get) — where the columns come
+ *  from is the responsibility of the consuming position, not of this schema.
+ *  Storage is entity_schema/{api.name}/{app.name}/entity/{table}.entity.ts:
+ *  one file per table (the main table), any number of entities per file.
+ *  "Row" is only a naming convention for read-shaped entities
+ *  (OrderListRow, OrderDetailRow) — they are all defineEntity declarations. */
+export interface EntitySchema extends SchemaBase {
+  type: 'entity';
+  /** The backend api module this entity belongs to (shared instance from
+   *  project.config.ts apis). Entities are always backend-side. */
+  api: ProjectApiSchema;
+  /** The frontend app this entity belongs to (shared instance from project.config).
+   *  Unset = api-level common domain entity shared by all modules of the api. */
+  app?: FrontAppSchema;
+  /** The columns of this row object: main-table columns, external reference
+   *  columns, and — for aggregate result entities — aggField columns
+   *  (count/sum/avg outputs). */
+  columns: Field[];
+}
+
+export function defineEntity(options: {
+  name: string;
+  api: ProjectApiSchema;
+  app?: FrontAppSchema;
+  columns: Field[];
+  description?: string;
+}): EntitySchema {
+  if (options.app && !options.api.apps.includes(options.app)) {
+    throw new Error(`entity ${options.name}: api '${options.api.name}' does not serve app '${options.app.name}'`);
+  }
+  return {
+    type: 'entity',
+    name: options.name,
+    description: options.description,
+    api: options.api,
+    app: options.app,
+    columns: options.columns,
+  };
 }

package/src/expr.ts

@@ -1,65 +1,65 @@
-// Value expression model: the single declarative way to express computed
-// values in dao methods — update SET expressions and criteria right sides.
-// Structural AST (never SQL strings): column references are Field objects
-// (definition-time ownership checks), values bind as parameters at render
-// time. New node kinds can be added without touching existing declarations.
-
-import type { Field } from './dsl.js';
-
-/** Binary operator on numeric values. */
-export type BinOp = 'add' | 'sub' | 'mul' | 'div';
-
-/** A value expression: column reference / literal / method parameter / binary
- *  operation. Recursive — leaves are col/lit/param, bin combines them. */
-export type ValueExpr =
-  | { kind: 'col'; field: Field }
-  | { kind: 'lit'; value: string | number }
-  | { kind: 'param'; name: string }
-  | { kind: 'bin'; op: BinOp; left: ValueExpr; right: ValueExpr };
-
-/** An update SET assignment: `col = expr` (besides the direct-assignment
- *  columns carried by the args entity — a column must not appear in both). */
-export interface SetExpr {
-  col: Field;
-  expr: ValueExpr;
-}
-
-export function col(field: Field): ValueExpr {
-  return { kind: 'col', field };
-}
-
-export function lit(value: string | number): ValueExpr {
-  return { kind: 'lit', value };
-}
-
-export function param(name: string): ValueExpr {
-  return { kind: 'param', name };
-}
-
-export function bin(op: BinOp, left: ValueExpr, right: ValueExpr): ValueExpr {
-  return { kind: 'bin', op, left, right };
-}
-
-/** Convenience builders for the common self-increment/decrement shapes. */
-export const incr = (field: Field, by: ValueExpr): SetExpr => ({ col: field, expr: bin('add', col(field), by) });
-export const decr = (field: Field, by: ValueExpr): SetExpr => ({ col: field, expr: bin('sub', col(field), by) });
-
-/** Aggregate expression result of an aggregate query column. */
-export interface ComputeExpr {
-  fn: 'sum' | 'avg' | 'count';
-  /** Column the function applies to; absent for count(*). */
-  field?: Field;
-}
-
-/** Aggregate expressions: Compute.sum(col) / Compute.avg(col) / Compute.count(). */
-export const Compute = {
-  sum(field: Field): ComputeExpr {
-    return { fn: 'sum', field };
-  },
-  avg(field: Field): ComputeExpr {
-    return { fn: 'avg', field };
-  },
-  count(): ComputeExpr {
-    return { fn: 'count' };
-  },
+// Value expression model: the single declarative way to express computed
+// values in dao methods — update SET expressions and criteria right sides.
+// Structural AST (never SQL strings): column references are Field objects
+// (definition-time ownership checks), values bind as parameters at render
+// time. New node kinds can be added without touching existing declarations.
+
+import type { Field } from './dsl.js';
+
+/** Binary operator on numeric values. */
+export type BinOp = 'add' | 'sub' | 'mul' | 'div';
+
+/** A value expression: column reference / literal / method parameter / binary
+ *  operation. Recursive — leaves are col/lit/param, bin combines them. */
+export type ValueExpr =
+  | { kind: 'col'; field: Field }
+  | { kind: 'lit'; value: string | number }
+  | { kind: 'param'; name: string }
+  | { kind: 'bin'; op: BinOp; left: ValueExpr; right: ValueExpr };
+
+/** An update SET assignment: `col = expr` (besides the direct-assignment
+ *  columns carried by the args entity — a column must not appear in both). */
+export interface SetExpr {
+  col: Field;
+  expr: ValueExpr;
+}
+
+export function col(field: Field): ValueExpr {
+  return { kind: 'col', field };
+}
+
+export function lit(value: string | number): ValueExpr {
+  return { kind: 'lit', value };
+}
+
+export function param(name: string): ValueExpr {
+  return { kind: 'param', name };
+}
+
+export function bin(op: BinOp, left: ValueExpr, right: ValueExpr): ValueExpr {
+  return { kind: 'bin', op, left, right };
+}
+
+/** Convenience builders for the common self-increment/decrement shapes. */
+export const incr = (field: Field, by: ValueExpr): SetExpr => ({ col: field, expr: bin('add', col(field), by) });
+export const decr = (field: Field, by: ValueExpr): SetExpr => ({ col: field, expr: bin('sub', col(field), by) });
+
+/** Aggregate expression result of an aggregate query column. */
+export interface ComputeExpr {
+  fn: 'sum' | 'avg' | 'count';
+  /** Column the function applies to; absent for count(*). */
+  field?: Field;
+}
+
+/** Aggregate expressions: Compute.sum(col) / Compute.avg(col) / Compute.count(). */
+export const Compute = {
+  sum(field: Field): ComputeExpr {
+    return { fn: 'sum', field };
+  },
+  avg(field: Field): ComputeExpr {
+    return { fn: 'avg', field };
+  },
+  count(): ComputeExpr {
+    return { fn: 'count' };
+  },
 };

package/src/filter.ts

@@ -1,70 +1,72 @@
-import type { Field, Operator, SchemaBase } from './dsl.js';
-import type { ValueExpr } from './expr.js';
-import type { FrontAppSchema, ProjectApiSchema } from './project.js';
-
-// Filter: the single declarative model for query conditions, shared by
-// dao_schema methods and curd page lists. Conditions are AND-combined and
-// may reference any table (cross-table filters render JOINs at the usage
-// site, which owns the main table). Pagination is NOT part of a filter —
-// it stays on the dao method (mode) and the curd list config.
-
-/** One AND-combined criterion: a column plus its comparison operator. */
-export interface FilterCondition {
-  /** Column to compare (any table — cross-table filters are allowed). */
-  field: Field;
-  /** Comparison operator; defaults to 'eq'. */
-  op?: Operator;
-  /** Right side of the comparison. Absent = the args parameter named after
-   *  the column (existing semantics); present = an explicit value expression
-   *  (column-vs-column, literal, computation). */
-  right?: ValueExpr;
-  /** Required (default) or optional criterion. A filter has one semantics:
-   *  dao filters are required (missing criteria = error), page filters are
-   *  optional (missing criteria = no WHERE). Declared by the filter author. */
-  optional?: boolean;
-}
-
-/** Query filter: AND-combined conditions plus an optional keyword search. */
-export interface FilterSchema extends SchemaBase {
-  type: 'filter';
-  /** The backend api module this filter belongs to (shared instance from
-   *  project.config.ts apis). Filters are backend-side, so storage is
-   *  filter_schema/{api.name}/{app.name}/filter/. */
-  api: ProjectApiSchema;
-  /** The frontend app this filter belongs to (shared instance from project.config). */
-  app: FrontAppSchema;
-  /** AND-combined conditions (may be empty when keyword is present). */
-  conditions: FilterCondition[];
-  /** Fuzzy keyword search: one input value matched against multiple columns
-   *  via OR-like. Presence drives the keyword query endpoint. */
-  keyword?: { columns: Field[] };
-}
-
-export function defineFilter(options: {
-  name: string;
-  api: ProjectApiSchema;
-  app: FrontAppSchema;
-  conditions?: FilterCondition[];
-  keyword?: { columns: Field[] };
-  description?: string;
-}): FilterSchema {
-  if (!options.api.apps.includes(options.app)) {
-    throw new Error(`filter ${options.name}: api '${options.api.name}' does not serve app '${options.app.name}'`);
-  }
-  const conditions = options.conditions ?? [];
-  if (conditions.length === 0 && options.keyword === undefined) {
-    throw new Error(`filter ${options.name}: conditions and keyword cannot both be empty`);
-  }
-  if (options.keyword !== undefined && options.keyword.columns.length === 0) {
-    throw new Error(`filter ${options.name}: keyword columns must be non-empty`);
-  }
-  return {
-    type: 'filter',
-    name: options.name,
-    description: options.description,
-    api: options.api,
-    app: options.app,
-    conditions,
-    keyword: options.keyword,
-  };
+import type { Field, Operator, SchemaBase } from './dsl.js';
+import type { ValueExpr } from './expr.js';
+import type { FrontAppSchema, ProjectApiSchema } from './project.js';
+
+// Filter: the single declarative model for query conditions, shared by
+// dao_schema methods and curd page lists. Conditions are AND-combined and
+// may reference any table (cross-table filters render JOINs at the usage
+// site, which owns the main table). Pagination is NOT part of a filter —
+// it stays on the dao method (mode) and the curd list config.
+
+/** One AND-combined criterion: a column plus its comparison operator. */
+export interface FilterCondition {
+  /** Column to compare (any table — cross-table filters are allowed). */
+  field: Field;
+  /** Comparison operator; defaults to 'eq'. */
+  op?: Operator;
+  /** Right side of the comparison. Absent = the args parameter named after
+   *  the column (existing semantics); present = an explicit value expression
+   *  (column-vs-column, literal, computation). */
+  right?: ValueExpr;
+  /** Required (default) or optional criterion. A filter has one semantics:
+   *  dao filters are required (missing criteria = error), page filters are
+   *  optional (missing criteria = no WHERE). Declared by the filter author. */
+  optional?: boolean;
+}
+
+/** Query filter: AND-combined conditions plus an optional keyword search. */
+export interface FilterSchema extends SchemaBase {
+  type: 'filter';
+  /** The backend api module this filter belongs to (shared instance from
+   *  project.config.ts apis). Filters are backend-side, so storage is
+   *  filter_schema/{api.name}/{app.name}/filter/ — app unset = the api-level
+   *  common domain layer, stored at filter_schema/{api.name}/common/filter/. */
+  api: ProjectApiSchema;
+  /** The frontend app this filter belongs to (shared instance from project.config).
+   *  Unset = api-level common domain filter shared by all modules of the api. */
+  app?: FrontAppSchema;
+  /** AND-combined conditions (may be empty when keyword is present). */
+  conditions: FilterCondition[];
+  /** Fuzzy keyword search: one input value matched against multiple columns
+   *  via OR-like. Presence drives the keyword query endpoint. */
+  keyword?: { columns: Field[] };
+}
+
+export function defineFilter(options: {
+  name: string;
+  api: ProjectApiSchema;
+  app?: FrontAppSchema;
+  conditions?: FilterCondition[];
+  keyword?: { columns: Field[] };
+  description?: string;
+}): FilterSchema {
+  if (options.app && !options.api.apps.includes(options.app)) {
+    throw new Error(`filter ${options.name}: api '${options.api.name}' does not serve app '${options.app.name}'`);
+  }
+  const conditions = options.conditions ?? [];
+  if (conditions.length === 0 && options.keyword === undefined) {
+    throw new Error(`filter ${options.name}: conditions and keyword cannot both be empty`);
+  }
+  if (options.keyword !== undefined && options.keyword.columns.length === 0) {
+    throw new Error(`filter ${options.name}: keyword columns must be non-empty`);
+  }
+  return {
+    type: 'filter',
+    name: options.name,
+    description: options.description,
+    api: options.api,
+    app: options.app,
+    conditions,
+    keyword: options.keyword,
+  };
 }