@pylonts/dsl 1.0.6 → 1.1.2

package/src/dsl.ts

@@ -1,13 +1,23 @@
 // DSL field type definitions.
 // Shape: { type: <type name>, <extension fields> }
 
-import type { DictionaryEntry } from './dictionary';
+import type { DictionaryEntry } from './dictionary.js';
+import type { ImportBase } from './import-base.js';
+import type { MockDescriptor } from './mock.js';
+
+/** Field query comparison operators (search field semantics). */
+export type Operator = 'eq' | 'gt' | 'gte' | 'lt' | 'lte' | 'like' | 'ne';
 
 export interface SchemaBase {
   name: string;
   description?: string;
 }
 
+/** Schema base for cross-file entities. importRef locates the generating module; inline schemas omit it. */
+export interface ImportableSchemaBase extends SchemaBase {
+  importRef?: ImportBase;
+}
+
 /** Field collection schemas (DB table vs DTO message); `type` is the discriminator */
 export interface CollectionSchemaBase extends SchemaBase {
   type: string;
@@ -19,13 +29,13 @@ export interface BaseField {
   label?: string;
   /** 字段描述 */
   description?: string;
-  /** 业务语义码（如 'merchant_name'），驱动 mock 生成等下游消费 */
-  semantic?: string;
   optional?: boolean;
   readOnly?: boolean;
   default?: string;
   /** 所属 schema（db 或 dto） */
   schema?: CollectionSchemaBase;
+  /** Pure-data mock descriptor for test data generation */
+  mock?: MockDescriptor;
 }
 
 interface StringField extends BaseField {
@@ -128,74 +138,6 @@ export type Field =
   | EnumField
   | JsonField;
 
-export type Index = {
-  name?: string;
-  fields: Field | Field[];
-  unique?: boolean;
-};
-
-export type ForeignKey = {
-  fields: Field | Field[];
-  references: Field | Field[];
-};
-
-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 端用户，管理端为运营） */
-  actor?: boolean;
-  /** id 生成器 */
-  generator?: string;
-  /** 自增主键字段 */
-  autoIncrement?: Field;
-  primaryKey?: Field | Field[];
-  indexes?: Index[];
-  /** 外键，引用其他表的字段 */
-  foreignKeys?: Record<string, ForeignKey>;
-  /** 引用的实体短语（词典条目）：本表归属的实体；关联表等多实体场景不需要 */
-  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.
 // The field name is written back from the map key later (see defineTable).
 
@@ -244,39 +186,4 @@ export function jsonField(extra: FieldExtras<JsonField> = {}): JsonField {
 export function enumField(extra: Omit<EnumField, 'name' | 'type' | 'jsType'>): EnumField {
   const jsType = extra.enum.valueType === 'integer' ? 'number' : 'string';
   return { name: '', type: 'enum', jsType, ...extra };
-}
-
-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) {
-      throw new Error(
-        `field ${key}: belongs to table ${field.schema.name}, cannot reuse in table ${table.name}`,
-      );
-    }
-  }
-  for (const key of Object.keys(table.fields)) {
-    table.fields[key].name = key;
-    table.fields[key].schema = table;
-  }
-  for (const [fkName, fk] of Object.entries(table.foreignKeys ?? {})) {
-    const refs = Array.isArray(fk.references) ? fk.references : [fk.references];
-    const fields = Array.isArray(fk.fields) ? fk.fields : [fk.fields];
-    for (let i = 0; i < refs.length; i++) {
-      const ref = refs[i];
-      if (!ref.schema) throw new Error(`foreign key ${fkName}: references field has no schema`);
-      if (ref.schema === table) throw new Error(`foreign key ${fkName}: cannot reference own table ${table.name}`);
-      const phrase = (ref.schema as TableSchema).phrase;
-      if (!phrase) throw new Error(`foreign key ${fkName}: referenced table ${ref.schema.name} has no phrase, cannot check field naming`);
-      const expected = `${phrase.name}_${ref.name}`;
-      const fkField = fields[i];
-      if (fkField.name !== expected) {
-        throw new Error(
-          `foreign key ${fkName}: field must be named ${expected} (phrase ${phrase.name} + ${ref.name}), got ${fkField.name}`,
-        );
-      }
-    }
-  }
-  return table;
 }

package/src/dto.ts

@@ -1,22 +1,27 @@
-import { BaseField, CollectionSchemaBase, Field, SchemaBase, TableSchema } from './dsl';
-import { toCamelCase } from './utils';
+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.
 
-export type Operator = 'eq' | 'gt' | 'gte' | 'lt' | 'lte' | 'like' | 'ne';
+/** 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 {
-  /** Module specifier, e.g. '@pylonts/core' */
-  from: string;
-  /** Named export, e.g. 'PageRequest' */
-  name: string;
+export interface ImportRef extends ImportBase {
   /**
    * Generic type arguments for the base schema (e.g. PageResult(OrderRow)).
    * Two forms, both local DTOs:
@@ -45,8 +50,8 @@ export class DtoField implements SchemaBase {
   name: string;
   /** 字段描述 */
   description?: string;
-  /** 所属 DTO 容器（buildMessage 反写） */
-  schema?: DtoMessage;
+  /** 所属容器（buildMessage / defineRouteData / definePageData 反写） */
+  schema?: CollectionSchemaBase;
   field: Field | DtoArrayFieldDef | DtoObjectFieldDef;
   pattern?: string;
   optional?: boolean;
@@ -170,6 +175,13 @@ function buildMessage(name: string, direction: DtoDirection, fields: Record<stri
   // 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.
@@ -186,13 +198,14 @@ function buildMessage(name: string, direction: DtoDirection, fields: Record<stri
 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 / auto-increment → optional, else required.
+  // 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 = f.optional !== false || f.default !== undefined || table.autoIncrement === f;
+    field.optional = table.isPk(f) ? false : f.optional !== false || f.default !== undefined;
   }
   return message;
 }

package/src/enum-driver.ts

@@ -1,43 +1,43 @@
-import { EnumDef } from './dsl';
-
-// Enum driver: renders an EnumDef into a standalone TypeScript enum file.
-// Shape matches the generated-enum product consumed by the TypeBox driver (Type.Enum):
-//
-//   export enum UserStatus {
-//     ACTIVE = 'ACTIVE',
-//     DISABLED = 'DISABLED',
-//   }
-//
-//   export const USER_STATUS_LABEL: Record<UserStatus, string> = {
-//     [UserStatus.ACTIVE]: '启用',
-//     [UserStatus.DISABLED]: '禁用',
-//   };
-
-function renderString(s: string): string {
-  return `'${s.replace(/\\/g, '\\\\').replace(/'/g, "\\'")}'`;
-}
-
-function renderValue(value: string | number): string {
-  return typeof value === 'number' ? String(value) : renderString(value);
-}
-
-/** 'UserStatus' → 'USER_STATUS_LABEL' (matches the label map naming convention) */
-function labelName(jsName: string): string {
-  return `${jsName.replace(/([a-z0-9])([A-Z])/g, '$1_$2').toUpperCase()}_LABEL`;
-}
-
-export function renderEnum(def: EnumDef): string {
-  const name = def.jsName;
-  const members = def.values.map((v) => `  ${v.symbol} = ${renderValue(v.value)},`);
-  const labels = def.values.map((v) => `  [${name}.${v.symbol}]: ${renderString(v.label)},`);
-  return [
-    `export enum ${name} {`,
-    ...members,
-    '}',
-    '',
-    `export const ${labelName(name)}: Record<${name}, string> = {`,
-    ...labels,
-    '};',
-    '',
-  ].join('\n');
+import { EnumDef } from './dsl.js';
+
+// Enum driver: renders an EnumDef into a standalone TypeScript enum file.
+// Shape matches the generated-enum product consumed by the TypeBox driver (Type.Enum):
+//
+//   export enum UserStatus {
+//     ACTIVE = 'ACTIVE',
+//     DISABLED = 'DISABLED',
+//   }
+//
+//   export const USER_STATUS_LABEL: Record<UserStatus, string> = {
+//     [UserStatus.ACTIVE]: '启用',
+//     [UserStatus.DISABLED]: '禁用',
+//   };
+
+function renderString(s: string): string {
+  return `'${s.replace(/\\/g, '\\\\').replace(/'/g, "\\'")}'`;
+}
+
+function renderValue(value: string | number): string {
+  return typeof value === 'number' ? String(value) : renderString(value);
+}
+
+/** 'UserStatus' → 'USER_STATUS_LABEL' (matches the label map naming convention) */
+function labelName(jsName: string): string {
+  return `${jsName.replace(/([a-z0-9])([A-Z])/g, '$1_$2').toUpperCase()}_LABEL`;
+}
+
+export function renderEnum(def: EnumDef): string {
+  const name = def.jsName;
+  const members = def.values.map((v) => `  ${v.symbol} = ${renderValue(v.value)},`);
+  const labels = def.values.map((v) => `  [${name}.${v.symbol}]: ${renderString(v.label)},`);
+  return [
+    `export enum ${name} {`,
+    ...members,
+    '}',
+    '',
+    `export const ${labelName(name)}: Record<${name}, string> = {`,
+    ...labels,
+    '};',
+    '',
+  ].join('\n');
 }

package/src/event.ts

@@ -0,0 +1,12 @@
+import type { CollectionSchemaBase } from './dsl.js';
+import type { DtoField } from './dto.js';
+
+/** Data carried by a component event (e.g. e.detail from a Tab onChange). */
+export interface EventDataSchema extends CollectionSchemaBase {
+  type: 'event';
+  fields: Record<string, DtoField>;
+}
+
+export function defineEventData(name: string, fields: Record<string, DtoField>): EventDataSchema {
+  return { name, type: 'event', fields };
+}

package/src/flow.ts

@@ -1,104 +1,104 @@
-import { SchemaBase } from './dsl';
-
-// Flow model: nodes and edges are separate entities. A FlowNode is a plain
-// named step; a FlowEdge references its start/end node objects directly (no
-// ids). Because a node object may appear in many edges, the graph can share
-// nodes, merge branches, and form cycles (e.g. poll-and-retry loops).
-
-export interface FlowNode extends SchemaBase {
-  /** Optional sub-flow. When present, entering this node runs the sub-flow;
-   *  after the sub-flow reaches any terminal node, the outer flow continues
-   *  via this node's outgoing edges. Sub-flows nest recursively. */
-  flow?: FlowSchema;
-}
-
-export interface FlowEdge extends SchemaBase {
-  /** Trigger condition; undefined = default path (success/normal). */
-  when?: string;
-  start: FlowNode;
-  end: FlowNode;
-}
-
-export interface FlowSchema extends SchemaBase {
-  /** Entry node. */
-  start: FlowNode;
-  /** All nodes, collected from edges (deduplicated by object identity). */
-  nodes: FlowNode[];
-  /** Independent edges; a node may be start of many edges, so cycles are expressible. */
-  edges: FlowEdge[];
-}
-
-export function node(name: string, flow?: FlowSchema, description?: string): FlowNode {
-  return { name, flow, description };
-}
-
-export function edge(start: FlowNode, end: FlowNode, when?: string, description?: string): FlowEdge {
-  // Auto name for uniformity with SchemaBase; `when` stays the branch marker.
-  return { name: `${start.name}->${end.name}`, start, end, when, description };
-}
-
-export function defineFlow(
-  name: string,
-  schema: {
-    start: FlowNode;
-    edges: FlowEdge[];
-    description?: string;
-  },
-): FlowSchema {
-  const seen = new Set<FlowNode>();
-  const nodes: FlowNode[] = [];
-  for (const e of schema.edges) {
-    for (const n of [e.start, e.end]) {
-      if (!seen.has(n)) {
-        seen.add(n);
-        nodes.push(n);
-      }
-    }
-  }
-  if (!seen.has(schema.start)) {
-    seen.add(schema.start);
-    nodes.push(schema.start);
-  }
-  const flow: FlowSchema = { name, description: schema.description, start: schema.start, nodes, edges: schema.edges };
-  validate(flow);
-  return flow;
-}
-
-// Nodes that never appear as an edge start are terminals. Reverse BFS from all
-// terminals marks every node that can reach a terminal; unmarked nodes sit on
-// a path that never ends (e.g. a cycle without an exit) — reject them at
-// definition time.
-function validate(schema: FlowSchema): void {
-  const starts = new Set<FlowNode>();
-  for (const e of schema.edges) starts.add(e.start);
-
-  const reverse = new Map<FlowNode, FlowNode[]>();
-  for (const n of schema.nodes) reverse.set(n, []);
-  for (const e of schema.edges) {
-    reverse.get(e.end)!.push(e.start);
-  }
-
-  const reached = new Set<FlowNode>();
-  const queue: FlowNode[] = [];
-  for (const n of schema.nodes) {
-    if (!starts.has(n)) {
-      reached.add(n);
-      queue.push(n);
-    }
-  }
-  while (queue.length > 0) {
-    const cur = queue.shift()!;
-    for (const prev of reverse.get(cur)!) {
-      if (!reached.has(prev)) {
-        reached.add(prev);
-        queue.push(prev);
-      }
-    }
-  }
-
-  for (const n of schema.nodes) {
-    if (!reached.has(n)) {
-      throw new Error(`flow ${schema.name}: node "${n.name}" cannot reach a terminal`);
-    }
-  }
+import { SchemaBase } from './dsl.js';
+
+// Flow model: nodes and edges are separate entities. A FlowNode is a plain
+// named step; a FlowEdge references its start/end node objects directly (no
+// ids). Because a node object may appear in many edges, the graph can share
+// nodes, merge branches, and form cycles (e.g. poll-and-retry loops).
+
+export interface FlowNode extends SchemaBase {
+  /** Optional sub-flow. When present, entering this node runs the sub-flow;
+   *  after the sub-flow reaches any terminal node, the outer flow continues
+   *  via this node's outgoing edges. Sub-flows nest recursively. */
+  flow?: FlowSchema;
+}
+
+export interface FlowEdge extends SchemaBase {
+  /** Trigger condition; undefined = default path (success/normal). */
+  when?: string;
+  start: FlowNode;
+  end: FlowNode;
+}
+
+export interface FlowSchema extends SchemaBase {
+  /** Entry node. */
+  start: FlowNode;
+  /** All nodes, collected from edges (deduplicated by object identity). */
+  nodes: FlowNode[];
+  /** Independent edges; a node may be start of many edges, so cycles are expressible. */
+  edges: FlowEdge[];
+}
+
+export function node(name: string, flow?: FlowSchema, description?: string): FlowNode {
+  return { name, flow, description };
+}
+
+export function edge(start: FlowNode, end: FlowNode, when?: string, description?: string): FlowEdge {
+  // Auto name for uniformity with SchemaBase; `when` stays the branch marker.
+  return { name: `${start.name}->${end.name}`, start, end, when, description };
+}
+
+export function defineFlow(
+  name: string,
+  schema: {
+    start: FlowNode;
+    edges: FlowEdge[];
+    description?: string;
+  },
+): FlowSchema {
+  const seen = new Set<FlowNode>();
+  const nodes: FlowNode[] = [];
+  for (const e of schema.edges) {
+    for (const n of [e.start, e.end]) {
+      if (!seen.has(n)) {
+        seen.add(n);
+        nodes.push(n);
+      }
+    }
+  }
+  if (!seen.has(schema.start)) {
+    seen.add(schema.start);
+    nodes.push(schema.start);
+  }
+  const flow: FlowSchema = { name, description: schema.description, start: schema.start, nodes, edges: schema.edges };
+  validate(flow);
+  return flow;
+}
+
+// Nodes that never appear as an edge start are terminals. Reverse BFS from all
+// terminals marks every node that can reach a terminal; unmarked nodes sit on
+// a path that never ends (e.g. a cycle without an exit) — reject them at
+// definition time.
+function validate(schema: FlowSchema): void {
+  const starts = new Set<FlowNode>();
+  for (const e of schema.edges) starts.add(e.start);
+
+  const reverse = new Map<FlowNode, FlowNode[]>();
+  for (const n of schema.nodes) reverse.set(n, []);
+  for (const e of schema.edges) {
+    reverse.get(e.end)!.push(e.start);
+  }
+
+  const reached = new Set<FlowNode>();
+  const queue: FlowNode[] = [];
+  for (const n of schema.nodes) {
+    if (!starts.has(n)) {
+      reached.add(n);
+      queue.push(n);
+    }
+  }
+  while (queue.length > 0) {
+    const cur = queue.shift()!;
+    for (const prev of reverse.get(cur)!) {
+      if (!reached.has(prev)) {
+        reached.add(prev);
+        queue.push(prev);
+      }
+    }
+  }
+
+  for (const n of schema.nodes) {
+    if (!reached.has(n)) {
+      throw new Error(`flow ${schema.name}: node "${n.name}" cannot reach a terminal`);
+    }
+  }
 }

package/src/import-base.ts

@@ -0,0 +1,15 @@
+/**
+ * Reference to a named export from another module, by its import location.
+ * Serializable metadata: the driver renders `import { name } from 'from'`.
+ * Used for enum types and plain imports that need no generic arguments.
+ */
+export interface ImportBase {
+  /** Module specifier, e.g. '@pylonts/core' */
+  from: string;
+  /** Named export, e.g. 'PageRequest' */
+  name: string;
+  /** Type-only import (`import type`); defaults to a value import. */
+  type?: boolean;
+  /** Default import (`import X from '...'`) instead of named (`import { X }`). */
+  default?: boolean;
+}

package/src/index.ts

@@ -1,17 +1,31 @@
-export * from './dsl';
-export * from './dto';
-export * from './bases';
-export * from './utils';
-export * from './project';
-export * from './prototype';
-export * from './dictionary';
-export * from './mysql-driver';
-export * from './enum-driver';
-export * from './typebox-driver';
-export * from './check-inheritance';
-export * from './pattern';
-export * from './patterns/retry';
-export * from './flow';
-export * from './page';
-export * from './page-flow';
-export * from './mermaid-driver';
+export * from './dsl.js';
+export * from './db.js';
+export * from './mock.js';
+export * from './asset.js';
+export * from './dto.js';
+export * from './db-config.js';
+export * from './bases.js';
+export * from './utils.js';
+export * from './project.js';
+export * from './prototype.js';
+export * from './dictionary.js';
+export * from './mysql-driver.js';
+export * from './enum-driver.js';
+export * from './typebox-driver.js';
+export * from './pattern.js';
+export * from './patterns/retry.js';
+export * from './flow.js';
+export * from './action.js';
+export * from './event.js';
+export * from './component.js';
+export * from './convert.js';
+export * from './ref.js';
+export * from './route.js';
+export * from './page.js';
+export * from './curd.js';
+export * from './page-flow.js';
+export * from './provider.js';
+export * from './page-def.js';
+export * from './mermaid-driver.js';
+export * from './navigation.js';
+export * from './popup.js';

package/src/mermaid-driver.ts

@@ -1,6 +1,6 @@
-import { FlowEdge, FlowNode, FlowSchema } from './flow';
-import { Page } from './page';
-import { PageEdge, PageFlow } from './page-flow';
+import { FlowEdge, FlowNode, FlowSchema } from './flow.js';
+import { Page } from './page.js';
+import { PageEdge, PageFlow } from './page-flow.js';
 
 // Mermaid driver: converts a FlowSchema into a Mermaid flowchart (TD).
 // Node ids are hierarchical (n0, n0_0, n0_0_0, ...) so nested sub-flows stay
@@ -66,7 +66,8 @@ export function renderPageFlowMermaid(schema: PageFlow): string {
     lines.push(`    subgraph app${appIdx}["${escapeLabel(appName)}"]`);
     pages.forEach((p, i) => ids.set(p, `app${appIdx}_p${i}`));
     for (const p of pages) {
-      lines.push(`    ${ids.get(p)}["${escapeLabel(p.name)}"]`);
+      const display = p.label ?? p.name;
+      lines.push(`    ${ids.get(p)}["${escapeLabel(display)}"]`);
     }
     appIdx++;
     lines.push('    end');

package/src/mock.ts

@@ -0,0 +1,12 @@
+/**
+ * Pure-data mock descriptor. Stored on DTO fields, consumed by pylonts lint mock
+ * or MockRegistry.resolve. No function references — serializable and gen-readable.
+ *
+ * @example { fn: 'abc', count: 20 }
+ * @example { fn: 'amt', min: 10, max: 500 }
+ * @example { fn: 'phone' }
+ */
+export interface MockDescriptor {
+  fn: string;
+  [args: string]: unknown;
+}