@pylonts/dsl 1.1.12 → 1.1.13

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pylonts/dsl",
-  "version": "1.1.12",
+  "version": "1.1.13",
   "description": "Schema definition DSL with drivers: MySQL DDL, TS enum, TypeBox schema codegen.",
   "type": "module",
   "main": "dist/index.js",

package/src/action.ts

@@ -1,52 +1,52 @@
-import { SchemaBase } from './dsl.js';
-import type { DtoField, DtoMessage, DtoArrayField, DtoObjectField } from './dto.js';
-import type { RefSchema } from './ref.js';
-import type { ControllerMethodSchema } from './controller.js';
-
-/** An action a user can perform on a page (e.g. submit, approve, reject).
- *  Subclasses use `type` as the discriminator. */
-export interface ActionSchema extends SchemaBase {
-  type: string;
-}
-
-export function defineAction(name: string, description?: string): ActionSchema {
-  return { name, description, type: 'gesture' };
-}
-
-/** Parameter data source for a call argument. */
-export type DataRef =
-  | { type: 'route'; key: string }
-  | { type: 'data';  key: string }
-  | { type: 'value'; value: unknown };
-
-/** Create a route-parameter reference. */
-export function route(key: string): DataRef {
-  return { type: 'route', key };
-}
-
-/** Create a page-data reference. */
-export function data(key: string): DataRef {
-  return { type: 'data', key };
-}
-
-export interface CallAction extends ActionSchema {
-  type: 'call';
-  func: ControllerMethodSchema;
-  args?: Record<string, DtoField | DtoMessage | DtoArrayField | DtoObjectField | RefSchema | string>;
-}
-
-export function call(func: ControllerMethodSchema, args?: Record<string, DtoField | DtoMessage | DtoArrayField | DtoObjectField | RefSchema | string>): CallAction {
-  return { name: func.name, type: 'call', func, args };
-}
-
-/** Assign a call's result to a page data field.
- *  React: setState({ [field]: await ... }). Mini-program: this.setData({ [field]: ... }). */
-export interface SetDataAction extends ActionSchema {
-  type: 'setData';
-  call: CallAction;
-  field: DtoField;
-}
-
-export function setData(call: CallAction, field: DtoField): SetDataAction {
-  return { name: 'setData', type: 'setData', call, field };
+import { SchemaBase } from './dsl.js';
+import type { DtoField, DtoMessage, DtoArrayField, DtoObjectField } from './dto.js';
+import type { RefSchema } from './ref.js';
+import type { ControllerMethodSchema } from './controller.js';
+
+/** An action a user can perform on a page (e.g. submit, approve, reject).
+ *  Subclasses use `type` as the discriminator. */
+export interface ActionSchema extends SchemaBase {
+  type: string;
+}
+
+export function defineAction(name: string, description?: string): ActionSchema {
+  return { name, description, type: 'gesture' };
+}
+
+/** Parameter data source for a call argument. */
+export type DataRef =
+  | { type: 'route'; key: string }
+  | { type: 'data';  key: string }
+  | { type: 'value'; value: unknown };
+
+/** Create a route-parameter reference. */
+export function route(key: string): DataRef {
+  return { type: 'route', key };
+}
+
+/** Create a page-data reference. */
+export function data(key: string): DataRef {
+  return { type: 'data', key };
+}
+
+export interface CallAction extends ActionSchema {
+  type: 'call';
+  func: ControllerMethodSchema;
+  args?: Record<string, DtoField | DtoMessage | DtoArrayField | DtoObjectField | RefSchema | string>;
+}
+
+export function call(func: ControllerMethodSchema, args?: Record<string, DtoField | DtoMessage | DtoArrayField | DtoObjectField | RefSchema | string>): CallAction {
+  return { name: func.name, type: 'call', func, args };
+}
+
+/** Assign a call's result to a page data field.
+ *  React: setState({ [field]: await ... }). Mini-program: this.setData({ [field]: ... }). */
+export interface SetDataAction extends ActionSchema {
+  type: 'setData';
+  call: CallAction;
+  field: DtoField;
+}
+
+export function setData(call: CallAction, field: DtoField): SetDataAction {
+  return { name: 'setData', type: 'setData', call, field };
 }

package/src/controller.ts

@@ -1,54 +1,54 @@
-import { SchemaBase } from './dsl.js';
-import { FrontAppSchema, ProjectApiSchema } from './project.js';
-import type { DtoMessage } from './dto.js';
-
-/** A backend RPC controller. Strong constraints:
- *  - a backend module maps 1:1 to a frontend app (they are peers);
- *  - a controller serves exactly one frontend app — no cross-module calls. */
-export interface ControllerSchema extends SchemaBase {
-  type: 'controller';
-  /** The backend api module this controller belongs to (shared instance from
-   *  project.config.ts apis). Controllers are always backend-side, so storage
-   *  is controller_schema/{api.name}/{app.name}/controller/. */
-  api: ProjectApiSchema;
-  /** The frontend app this controller serves (shared instance from project.config). */
-  app: FrontAppSchema;
-  /** RPC methods, keyed by method name (key === method.name, enforced by the builder). */
-  methods: Record<string, ControllerMethodSchema>;
-}
-
-export function defineController(options: {
-  name: string;
-  api: ProjectApiSchema;
-  app: FrontAppSchema;
-  /** Method declarations: type/schema/name are injected by this builder. */
-  methods: Record<string, Omit<ControllerMethodSchema, 'type' | 'schema' | 'name'>>;
-  description?: string;
-}): ControllerSchema {
-  if (!options.api.apps.includes(options.app)) {
-    throw new Error(`controller ${options.name}: api '${options.api.name}' does not serve app '${options.app.name}'`);
-  }
-  const schema: ControllerSchema = {
-    type: 'controller',
-    name: options.name,
-    description: options.description,
-    api: options.api,
-    app: options.app,
-    methods: {},
-  };
-  for (const [key, method] of Object.entries(options.methods)) {
-    schema.methods[key] = { type: 'method', schema, name: key, ...method };
-  }
-  return schema;
-}
-
-/** An RPC method exposed by a controller. Carries the shared API call
- *  signature: one request DTO in, one response shape out. Referenced by
- *  frontend page actions — both sides use the exact same instance, so
- *  drift is impossible. */
-export interface ControllerMethodSchema extends SchemaBase {
-  type: 'method';
-  schema: ControllerSchema;
-  args: DtoMessage;
-  results: DtoMessage | number | boolean | string;
+import { SchemaBase } from './dsl.js';
+import { FrontAppSchema, ProjectApiSchema } from './project.js';
+import type { DtoMessage } from './dto.js';
+
+/** A backend RPC controller. Strong constraints:
+ *  - a backend module maps 1:1 to a frontend app (they are peers);
+ *  - a controller serves exactly one frontend app — no cross-module calls. */
+export interface ControllerSchema extends SchemaBase {
+  type: 'controller';
+  /** The backend api module this controller belongs to (shared instance from
+   *  project.config.ts apis). Controllers are always backend-side, so storage
+   *  is controller_schema/{api.name}/{app.name}/controller/. */
+  api: ProjectApiSchema;
+  /** The frontend app this controller serves (shared instance from project.config). */
+  app: FrontAppSchema;
+  /** RPC methods, keyed by method name (key === method.name, enforced by the builder). */
+  methods: Record<string, ControllerMethodSchema>;
+}
+
+export function defineController(options: {
+  name: string;
+  api: ProjectApiSchema;
+  app: FrontAppSchema;
+  /** Method declarations: type/schema/name are injected by this builder. */
+  methods: Record<string, Omit<ControllerMethodSchema, 'type' | 'schema' | 'name'>>;
+  description?: string;
+}): ControllerSchema {
+  if (!options.api.apps.includes(options.app)) {
+    throw new Error(`controller ${options.name}: api '${options.api.name}' does not serve app '${options.app.name}'`);
+  }
+  const schema: ControllerSchema = {
+    type: 'controller',
+    name: options.name,
+    description: options.description,
+    api: options.api,
+    app: options.app,
+    methods: {},
+  };
+  for (const [key, method] of Object.entries(options.methods)) {
+    schema.methods[key] = { type: 'method', schema, name: key, ...method };
+  }
+  return schema;
+}
+
+/** An RPC method exposed by a controller. Carries the shared API call
+ *  signature: one request DTO in, one response shape out. Referenced by
+ *  frontend page actions — both sides use the exact same instance, so
+ *  drift is impossible. */
+export interface ControllerMethodSchema extends SchemaBase {
+  type: 'method';
+  schema: ControllerSchema;
+  args: DtoMessage;
+  results: DtoMessage | number | boolean | string;
 }

package/src/convert.ts

@@ -1,79 +1,77 @@
-import type { SchemaBase } from './dsl.js';
-import type { DtoMessage } from './dto.js';
-import type { TableSchema } from './db.js';
-import type { EntitySchema } from './entity.js';
-import type { ThirdMethodSchema } from './third-service.js';
-import type { FrontAppSchema, ProjectApiSchema } from './project.js';
-
-// Schema-collection integration: multiple source collections combine into
-// one target collection (e.g. two entity tables into one dto, or entity
-// columns plus a dto into one third-party wire message).
-//
-// A convert file binds to ONE source identity — a table (internal mapping,
-// {Table}Convert.ts) or a third-party service (anti-corruption translation,
-// {third-service}.convert.ts) — and holds N methods keyed by name (same
-// shape as defineService / defineDao).
-
-/** A source/target collection of a convert — dto, entity, table or
- *  third-party message. Entity sources may carry aggregate fields
- *  (aggField), e.g. an aggregate result entity projected into a wire
- *  message. */
-export type ConvertSourceSchema = DtoMessage | TableSchema | ThirdMethodSchema | EntitySchema;
-
-/** Method input for defineConvert: type/schema/name are set by the builder. */
-export type ConvertMethodDef = Omit<ConvertMethodSchema, 'type' | 'schema' | 'name'>;
-
-/** One conversion: multiple source collections → single target collection. */
-export interface ConvertMethodSchema extends SchemaBase {
-  type: 'convertMethod';
-  /** The convert file this method belongs to. */
-  schema: ConvertSchema;
-  /** Source schemas — one or more, mixed dimensions. */
-  sources: ConvertSourceSchema[];
-  /** Target schema — the single integrated collection. */
-  target: ConvertSourceSchema;
-}
-
-/** Declares multi-source → single-target schema integrations grouped by source identity. */
-export interface ConvertSchema extends SchemaBase {
-  type: 'convert';
-  /** The backend api module this convert belongs to (shared instance from
-   *  project.config.ts apis). Storage is convert_schema/{api.name}/{app.name}/
-   *  — same layout as service_schema. */
-  api: ProjectApiSchema;
-  /** The app (module) this convert belongs to — its artifact lands in modules/{app}/convert/. */
-  app: FrontAppSchema;
-  /** Methods keyed by name — the map key is written back as the method name. */
-  methods: Record<string, ConvertMethodSchema>;
-}
-
-export function defineConvert(options: {
-  name: string;
-  api: ProjectApiSchema;
-  app: FrontAppSchema;
-  methods: Record<string, ConvertMethodDef>;
-  description?: string;
-}): ConvertSchema {
-  if (Object.keys(options.methods).length === 0) {
-    throw new Error(`convert '${options.name}': methods must not be empty`);
-  }
-  if (!options.api.apps.includes(options.app)) {
-    throw new Error(`convert '${options.name}': api '${options.api.name}' does not serve app '${options.app.name}'`);
-  }
-  const schema: ConvertSchema = {
-    type: 'convert',
-    name: options.name,
-    description: options.description,
-    api: options.api,
-    app: options.app,
-    methods: {},
-  };
-  for (const key of Object.keys(options.methods)) {
-    const method = options.methods[key] as ConvertMethodDef;
-    if (method.sources.length === 0) {
-      throw new Error(`convert '${options.name}': method '${key}' sources must not be empty`);
-    }
-    schema.methods[key] = { type: 'convertMethod', schema, ...method, name: key };
-  }
-  return schema;
+import type { CollectionSchemaBase, SchemaBase } from './dsl.js';
+import type { DtoMessage } from './dto.js';
+import type { TableSchema } from './db.js';
+import type { EntitySchema } from './entity.js';
+import type { FrontAppSchema, ProjectApiSchema } from './project.js';
+
+// Schema-collection integration: multiple source collections combine into
+// one target collection (e.g. two entity tables into one dto, or entity
+// columns plus a dto into one third-party wire message).
+//
+// A convert file binds to ONE source identity — a table (internal mapping,
+// {Table}Convert.ts) or a third-party service (anti-corruption translation,
+// {third-service}.convert.ts) — and holds N methods keyed by name (same
+// shape as defineService / defineDao).
+
+/** A source/target collection of a convert — dto, entity or table. Entity
+ *  sources may carry aggregate fields (aggField), e.g. an aggregate result
+ *  entity projected into a wire message. */
+export type ConvertSourceSchema = DtoMessage | TableSchema | EntitySchema;
+
+/** Method input for defineConvert: type/schema/name are set by the builder. */
+export type ConvertMethodDef = Omit<ConvertMethodSchema, 'type' | 'schema' | 'name'>;
+
+/** One conversion: multiple source collections → single target collection. */
+export interface ConvertMethodSchema extends SchemaBase {
+  type: 'convertMethod';
+  /** The convert file this method belongs to. */
+  schema: ConvertSchema;
+  /** Source schemas — one or more, mixed dimensions. */
+  sources: ConvertSourceSchema[];
+  /** Target schema — the single integrated collection. */
+  target: ConvertSourceSchema;
+}
+
+/** Declares multi-source → single-target schema integrations grouped by source identity. */
+export interface ConvertSchema extends CollectionSchemaBase {
+  type: 'convert';
+  /** The backend api module this convert belongs to (shared instance from
+   *  project.config.ts apis). Storage is convert_schema/{api.name}/{app.name}/
+   *  — same layout as service_schema. */
+  api: ProjectApiSchema;
+  /** The app (module) this convert belongs to — its artifact lands in modules/{app}/convert/. */
+  app: FrontAppSchema;
+  /** Methods keyed by name — the map key is written back as the method name. */
+  methods: Record<string, ConvertMethodSchema>;
+}
+
+export function defineConvert(options: {
+  name: string;
+  api: ProjectApiSchema;
+  app: FrontAppSchema;
+  methods: Record<string, ConvertMethodDef>;
+  description?: string;
+}): ConvertSchema {
+  if (Object.keys(options.methods).length === 0) {
+    throw new Error(`convert '${options.name}': methods must not be empty`);
+  }
+  if (!options.api.apps.includes(options.app)) {
+    throw new Error(`convert '${options.name}': api '${options.api.name}' does not serve app '${options.app.name}'`);
+  }
+  const schema: ConvertSchema = {
+    type: 'convert',
+    name: options.name,
+    description: options.description,
+    api: options.api,
+    app: options.app,
+    methods: {},
+  };
+  for (const key of Object.keys(options.methods)) {
+    const method = options.methods[key] as ConvertMethodDef;
+    if (method.sources.length === 0) {
+      throw new Error(`convert '${options.name}': method '${key}' sources must not be empty`);
+    }
+    schema.methods[key] = { type: 'convertMethod', schema, ...method, name: key };
+  }
+  return schema;
 }

package/src/curd.ts

@@ -1,105 +1,105 @@
-import { SchemaBase, Field } from './dsl.js';
-import { TableSchema } from './db.js';
-import { FrontAppSchema } from './project.js';
-import { ActionSchema } from './action.js';
-import type { FilterSchema } from './filter.js';
-import { toKebabCase } from '@pylonts/core';
-
-// Admin-only CRUD page standard: binds one entity table to a frontend admin
-// app, describing everything needed to generate the list page plus optional
-// add/update/detail pages. Field-level columns are plain Field instances
-// (table fields, cross-table refs allowed) — DTOs are derived by the generator,
-// the schema itself never references DtoMessage.
-
-/** Mode of an action page: modal dialog or standalone route. */
-export type ActionPageMode = 'modal' | 'route';
-
-/** One CRUD action page (add / update / detail). */
-export interface ActionPage {
-  mode: ActionPageMode;
-  /** Fields rendered on this page. Required, non-empty — every field the
-   *  frontend shows must be listed explicitly. */
-  columns: Field[];
-}
-
-/** List page configuration. */
-export interface CurdListConfig {
-  /** List columns; required, non-empty. Every field the list shows must be
-   *  listed explicitly. May include cross-table fields via foreign refs. */
-  columns: Field[];
-  /** Page filter (search form + keyword search). Conditions declared on the
-   *  filter render the search form; the filter's keyword (when present)
-   *  drives the keyword query endpoint. Optional — a page without a filter
-   *  has no search form. */
-  filter?: FilterSchema;
-  /** Default sort. Required — column and direction are both mandatory. */
-  orderBy: { column: Field; direction: 'asc' | 'desc' };
-  /** Column header text overrides: Field.name → header text. */
-  columnTitles?: Record<string, string>;
-}
-
-/** Admin-only CRUD page standard: binds one entity table to a frontend
- *  admin app. Drives generation of the list page plus optional
- *  add/update/detail pages. */
-export interface CurdSchema extends SchemaBase {
-  /** The admin frontend app this CRUD belongs to (shared instance, type must be 'admin'). */
-  app: FrontAppSchema;
-  /** The bound entity table (shared instance). */
-  table: TableSchema;
-  /** List page Chinese title. */
-  title: string;
-  /** Sidebar menu section (group) this CRUD page belongs to. */
-  section: string;
-  /** Extra user actions on this page (beyond the standard CRUD). */
-  actions?: ActionSchema[];
-  /** Add/update/detail action pages. */
-  actionPages?: {
-    add?: ActionPage;
-    update?: ActionPage;
-    detail?: ActionPage;
-  };
-  list: CurdListConfig;
-}
-
-function assertColumns(curd: CurdSchema, pageName: string, columns: Field[]): void {
-  if (columns.length === 0) {
-    throw new Error(`curd ${curd.name}: ${pageName}.columns must be non-empty`);
-  }
-}
-
-function assertFieldsOwnTable(curd: CurdSchema, label: string, fields: Field[]): void {
-  for (const f of fields) {
-    if (f.schema !== curd.table) {
-      throw new Error(`curd ${curd.name}: ${label} field ${f.name} does not belong to table ${curd.table.name}`);
-    }
-  }
-}
-
-/** Defines an admin CRUD page standard. Runtime-validates admin app binding,
- *  non-empty columns and table field ownership (same style as defineTable). */
-export function defineCurd(name: string, schema: Omit<CurdSchema, 'name'>): CurdSchema {
-  const curd: CurdSchema = { name, ...schema };
-  if (curd.app.type !== 'admin') {
-    throw new Error(`curd ${name}: app ${curd.app.name} must be type 'admin' (got '${curd.app.type}')`);
-  }
-  // The name is the admin route path — it must be the kebab-case table name
-  // so paths cannot drift from the table they serve.
-  const expectedName = toKebabCase(curd.table.name);
-  if (name !== expectedName) {
-    throw new Error(`curd name must be '${expectedName}' (kebab-case of table '${curd.table.name}'); got '${name}'`);
-  }
-  if (!curd.section) {
-    throw new Error(`curd ${name}: section is required (sidebar menu group, e.g. '商户管理')`);
-  }
-  assertColumns(curd, 'list', curd.list.columns);
-  for (const [pageName, page] of Object.entries(curd.actionPages ?? {})) {
-    if (page) assertColumns(curd, `actionPages.${pageName}`, page.columns);
-  }
-  if (curd.list.filter !== undefined && curd.list.filter.app !== curd.app) {
-    throw new Error(
-      `curd ${name}: list.filter '${curd.list.filter.name}' is bound to app '${curd.list.filter.app.name}' but the curd belongs to app '${curd.app.name}'`,
-    );
-  }
-  assertFieldsOwnTable(curd, 'orderBy', [curd.list.orderBy.column]);
-  return curd;
+import { SchemaBase, Field } from './dsl.js';
+import { TableSchema } from './db.js';
+import { FrontAppSchema } from './project.js';
+import { ActionSchema } from './action.js';
+import type { FilterSchema } from './filter.js';
+import { toKebabCase } from '@pylonts/core';
+
+// Admin-only CRUD page standard: binds one entity table to a frontend admin
+// app, describing everything needed to generate the list page plus optional
+// add/update/detail pages. Field-level columns are plain Field instances
+// (table fields, cross-table refs allowed) — DTOs are derived by the generator,
+// the schema itself never references DtoMessage.
+
+/** Mode of an action page: modal dialog or standalone route. */
+export type ActionPageMode = 'modal' | 'route';
+
+/** One CRUD action page (add / update / detail). */
+export interface ActionPage {
+  mode: ActionPageMode;
+  /** Fields rendered on this page. Required, non-empty — every field the
+   *  frontend shows must be listed explicitly. */
+  columns: Field[];
+}
+
+/** List page configuration. */
+export interface CurdListConfig {
+  /** List columns; required, non-empty. Every field the list shows must be
+   *  listed explicitly. May include cross-table fields via foreign refs. */
+  columns: Field[];
+  /** Page filter (search form + keyword search). Conditions declared on the
+   *  filter render the search form; the filter's keyword (when present)
+   *  drives the keyword query endpoint. Optional — a page without a filter
+   *  has no search form. */
+  filter?: FilterSchema;
+  /** Default sort. Required — column and direction are both mandatory. */
+  orderBy: { column: Field; direction: 'asc' | 'desc' };
+  /** Column header text overrides: Field.name → header text. */
+  columnTitles?: Record<string, string>;
+}
+
+/** Admin-only CRUD page standard: binds one entity table to a frontend
+ *  admin app. Drives generation of the list page plus optional
+ *  add/update/detail pages. */
+export interface CurdSchema extends SchemaBase {
+  /** The admin frontend app this CRUD belongs to (shared instance, type must be 'admin'). */
+  app: FrontAppSchema;
+  /** The bound entity table (shared instance). */
+  table: TableSchema;
+  /** List page Chinese title. */
+  title: string;
+  /** Sidebar menu section (group) this CRUD page belongs to. */
+  section: string;
+  /** Extra user actions on this page (beyond the standard CRUD). */
+  actions?: ActionSchema[];
+  /** Add/update/detail action pages. */
+  actionPages?: {
+    add?: ActionPage;
+    update?: ActionPage;
+    detail?: ActionPage;
+  };
+  list: CurdListConfig;
+}
+
+function assertColumns(curd: CurdSchema, pageName: string, columns: Field[]): void {
+  if (columns.length === 0) {
+    throw new Error(`curd ${curd.name}: ${pageName}.columns must be non-empty`);
+  }
+}
+
+function assertFieldsOwnTable(curd: CurdSchema, label: string, fields: Field[]): void {
+  for (const f of fields) {
+    if (f.schema !== curd.table) {
+      throw new Error(`curd ${curd.name}: ${label} field ${f.name} does not belong to table ${curd.table.name}`);
+    }
+  }
+}
+
+/** Defines an admin CRUD page standard. Runtime-validates admin app binding,
+ *  non-empty columns and table field ownership (same style as defineTable). */
+export function defineCurd(name: string, schema: Omit<CurdSchema, 'name'>): CurdSchema {
+  const curd: CurdSchema = { name, ...schema };
+  if (curd.app.type !== 'admin') {
+    throw new Error(`curd ${name}: app ${curd.app.name} must be type 'admin' (got '${curd.app.type}')`);
+  }
+  // The name is the admin route path — it must be the kebab-case table name
+  // so paths cannot drift from the table they serve.
+  const expectedName = toKebabCase(curd.table.name);
+  if (name !== expectedName) {
+    throw new Error(`curd name must be '${expectedName}' (kebab-case of table '${curd.table.name}'); got '${name}'`);
+  }
+  if (!curd.section) {
+    throw new Error(`curd ${name}: section is required (sidebar menu group, e.g. '商户管理')`);
+  }
+  assertColumns(curd, 'list', curd.list.columns);
+  for (const [pageName, page] of Object.entries(curd.actionPages ?? {})) {
+    if (page) assertColumns(curd, `actionPages.${pageName}`, page.columns);
+  }
+  if (curd.list.filter !== undefined && curd.list.filter.app !== curd.app) {
+    throw new Error(
+      `curd ${name}: list.filter '${curd.list.filter.name}' is bound to ${curd.list.filter.app?.name ?? 'common'} but the curd belongs to app '${curd.app.name}'`,
+    );
+  }
+  assertFieldsOwnTable(curd, 'orderBy', [curd.list.orderBy.column]);
+  return curd;
 }