@pylonts/dsl 1.0.0 → 1.0.2

package/src/enum-driver.ts

@@ -1,6 +1,6 @@
-import { EnumField } from './dsl';
+import { EnumDef } from './dsl';
 
-// Enum driver: renders an EnumField into a standalone TypeScript enum file.
+// 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 {
@@ -26,11 +26,10 @@ function labelName(jsName: string): string {
   return `${jsName.replace(/([a-z0-9])([A-Z])/g, '$1_$2').toUpperCase()}_LABEL`;
 }
 
-export function renderEnum(field: EnumField): string {
-  if (!field.jsName) throw new Error(`enum field ${field.name} requires jsName to render`);
-  const name = field.jsName;
-  const members = field.values.map((v) => `  ${v.symbol} = ${renderValue(v.value)},`);
-  const labels = field.values.map((v) => `  [${name}.${v.symbol}]: ${renderString(v.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,
@@ -41,4 +40,4 @@ export function renderEnum(field: EnumField): string {
     '};',
     '',
   ].join('\n');
-}
+}

package/src/flow.ts

@@ -0,0 +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`);
+    }
+  }
+}

package/src/index.ts

@@ -1,5 +1,14 @@
 export * from './dsl';
 export * from './dto';
+export * from './project';
+export * from './prototype';
+export * from './dictionary';
 export * from './mysql-driver';
 export * from './enum-driver';
 export * from './typebox-driver';
+export * from './pattern';
+export * from './patterns/retry';
+export * from './flow';
+export * from './page';
+export * from './page-flow';
+export * from './mermaid-driver';

package/src/mermaid-driver.ts

@@ -0,0 +1,81 @@
+import { FlowEdge, FlowNode, FlowSchema } from './flow';
+import { Page } from './page';
+import { PageEdge, PageFlow } from './page-flow';
+
+// 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
+// globally unique. A node with a sub-flow renders as a subgraph block whose
+// internals are rendered recursively. ok edges render as -->, conditional
+// edges render as -->|"WHEN"|.
+
+function escapeLabel(s: string): string {
+  return s.replace(/"/g, '\\"').replace(/\n/g, '<br/>');
+}
+
+export function renderFlowMermaid(schema: FlowSchema): string {
+  const lines: string[] = ['flowchart TD'];
+  const ids = new Map<FlowNode, string>();
+  renderFlow(schema, 'n', lines, ids);
+  lines.push('');
+  lines.push('    classDef start fill:#e6f4ea,stroke:#333,stroke-width:1px;');
+  lines.push(`    class ${ids.get(schema.start)} start;`);
+  return lines.join('\n');
+}
+
+function renderFlow(schema: FlowSchema, prefix: string, lines: string[], ids: Map<FlowNode, string>): void {
+  schema.nodes.forEach((n, i) => ids.set(n, `${prefix}${i}`));
+  for (const n of schema.nodes) {
+    const id = ids.get(n)!;
+    if (n.flow) {
+      lines.push(`    subgraph ${id}["${escapeLabel(n.name)}"]`);
+      renderFlow(n.flow, `${id}_`, lines, ids);
+      lines.push('    end');
+    } else {
+      lines.push(`    ${id}["${escapeLabel(n.name)}"]`);
+    }
+  }
+  for (const e of schema.edges) {
+    lines.push(renderEdge(e, ids));
+  }
+}
+
+function renderEdge(e: FlowEdge, ids: Map<FlowNode, string>): string {
+  const label = e.when ? `|"${escapeLabel(e.when)}"|` : '';
+  return `    ${ids.get(e.start)} -->${label} ${ids.get(e.end)}`;
+}
+
+// Page-driven flow renderer: groups pages by their app into swimlane
+// subgraphs, then renders edges across the whole flow.
+
+export function renderPageFlowMermaid(schema: PageFlow): string {
+  const lines: string[] = ['flowchart TD'];
+  const ids = new Map<Page, string>();
+
+  const byApp = new Map<string, Page[]>();
+  for (const p of schema.pages) {
+    const list = byApp.get(p.app.name) ?? [];
+    list.push(p);
+    byApp.set(p.app.name, list);
+  }
+
+  let appIdx = 0;
+  for (const [appName, pages] of byApp) {
+    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)}"]`);
+    }
+    appIdx++;
+    lines.push('    end');
+  }
+
+  for (const e of schema.edges) {
+    const label = e.when ? `|"${escapeLabel(e.when.name)}"|` : '';
+    lines.push(`    ${ids.get(e.start)} -->${label} ${ids.get(e.end)}`);
+  }
+
+  lines.push('');
+  lines.push('    classDef start fill:#e6f4ea,stroke:#333,stroke-width:1px;');
+  lines.push(`    class ${ids.get(schema.start)} start;`);
+  return lines.join('\n');
+}

package/src/mysql-driver.ts

@@ -1,4 +1,4 @@
-import { Field, Index, TableSchema } from './dsl';
+import { Field, ForeignKey, Index, TableSchema } from './dsl';
 
 // MySQL driver: converts a TableSchema into a CREATE TABLE statement.
 
@@ -25,16 +25,17 @@ function columnType(field: Field): string {
       return 'DATETIME';
     case 'enum':
       // Enum is stored as a plain column: string -> VARCHAR(20), integer -> TINYINT.
-      return field.valueType === 'integer' ? 'TINYINT' : 'VARCHAR(20)';
+      return field.enum.valueType === 'integer' ? 'TINYINT' : 'VARCHAR(20)';
     case 'json':
       return 'JSON';
   }
 }
 
-function columnDef(field: Field): string {
+function columnDef(field: Field, autoIncrement?: Field): string {
   const parts = [field.name, columnType(field)];
   if (field.optional === false) parts.push('NOT NULL');
   if (field.default !== undefined) parts.push(`DEFAULT '${field.default}'`);
+  if (field === autoIncrement) parts.push('AUTO_INCREMENT');
   return parts.join(' ');
 }
 
@@ -51,10 +52,30 @@ function indexClause(index: Index): string {
   return `${kind} ${name} (${fields.map((f) => f.name).join(', ')})`;
 }
 
-export function buildCreateTableSql(schema: TableSchema): string {
-  const lines = Object.values(schema.fields).map(columnDef);
+function foreignKeyClause(name: string, fk: ForeignKey): string {
+  const fields = Array.isArray(fk.fields) ? fk.fields : [fk.fields];
+  const refs = Array.isArray(fk.references) ? fk.references : [fk.references];
+  const refTable = refs[0].schema?.name;
+  if (!refTable) throw new Error(`foreign key ${name}: references field has no schema`);
+  const fkCols = fields.map((f) => f.name).join(', ');
+  const refCols = refs.map((r) => r.name).join(', ');
+  return `CONSTRAINT \`${name}\` FOREIGN KEY (${fkCols}) REFERENCES \`${refTable}\` (${refCols})`;
+}
+
+export interface BuildCreateTableSqlOptions {
+  /** 是否生成外键约束，默认 false（不生成） */
+  generateForeignKeys?: boolean;
+}
+
+export function buildCreateTableSql(schema: TableSchema, options: BuildCreateTableSqlOptions = {}): string {
+  const lines = Object.values(schema.fields).map((field) => columnDef(field, schema.autoIncrement));
   const pk = primaryKeyClause(schema);
   if (pk) lines.push(pk);
   for (const index of schema.indexes ?? []) lines.push(indexClause(index));
+  if (options.generateForeignKeys) {
+    for (const [name, fk] of Object.entries(schema.foreignKeys ?? {})) {
+      lines.push(foreignKeyClause(name, fk));
+    }
+  }
   return `CREATE TABLE \`${schema.name}\` (\n  ${lines.join(',\n  ')}\n);`;
 }

package/src/page-flow.ts

@@ -0,0 +1,52 @@
+import { SchemaBase } from './dsl';
+import { ActionSchema, Page } from './page';
+
+// Page-driven flow: every node is a page, and a page belongs to an app.
+// Leaf nodes are pages too — a journey starts at a page and ends at a page.
+// Page definitions (PageSchema/Page/actions) live in page.ts; this file
+// models the flow graph between pages.
+
+export interface PageEdge extends SchemaBase {
+  /** Trigger action; undefined = default path (success/normal). */
+  when?: ActionSchema;
+  start: Page;
+  end: Page;
+}
+
+export interface PageFlow extends SchemaBase {
+  /** Entry page. */
+  start: Page;
+  /** All pages, collected from edges (deduplicated by object identity). */
+  pages: Page[];
+  edges: PageEdge[];
+}
+
+export function pageEdge(start: Page, end: Page, when?: ActionSchema, description?: string): PageEdge {
+  // Auto name for uniformity with SchemaBase; `when` stays the branch marker.
+  return { name: `${start.name}->${end.name}`, start, end, when, description };
+}
+
+export function definePageFlow(
+  name: string,
+  schema: {
+    start: Page;
+    edges: PageEdge[];
+    description?: string;
+  },
+): PageFlow {
+  const seen = new Set<Page>();
+  const pages: Page[] = [];
+  for (const e of schema.edges) {
+    for (const p of [e.start, e.end]) {
+      if (!seen.has(p)) {
+        seen.add(p);
+        pages.push(p);
+      }
+    }
+  }
+  if (!seen.has(schema.start)) {
+    seen.add(schema.start);
+    pages.push(schema.start);
+  }
+  return { name, description: schema.description, start: schema.start, pages, edges: schema.edges };
+}

package/src/page.ts

@@ -0,0 +1,40 @@
+import { SchemaBase } from './dsl';
+import { FrontApp } from './project';
+
+// Page definitions: standalone page schemas and the page node type used by
+// page-driven flows. Kept separate from page-flow.ts (the flow graph itself).
+
+/** Standalone page definition. A page is a shared value object: it lists
+ *  the actions a user can perform, and belongs to exactly one frontend app. */
+export interface PageSchema extends SchemaBase {
+  /** The frontend app this page belongs to (shared instance from project.config). */
+  app: FrontApp;
+  /** Actions a user can perform on this page (e.g. submit, approve, reject). */
+  actions: ActionSchema[];
+}
+
+/** An action a user can perform on a page (e.g. submit, approve, reject). */
+export interface ActionSchema extends SchemaBase {}
+
+export function defineAction(name: string, description?: string): ActionSchema {
+  return { name, description };
+}
+
+export function definePage(schema: {
+  name: string;
+  description?: string;
+  app: FrontApp;
+  actions: ActionSchema[];
+}): PageSchema {
+  return { ...schema };
+}
+
+/** A page node in a page-driven flow: every node is a page, and a page belongs to an app. */
+export interface Page extends SchemaBase {
+  /** The frontend app this page belongs to (shared instance from project.config). */
+  app: FrontApp;
+}
+
+export function page(app: FrontApp, name: string, description?: string): Page {
+  return { name, app, description };
+}

package/src/pattern.ts

@@ -0,0 +1,27 @@
+// Pattern core: minimal definitions to bootstrap the Flow × Pattern DSL.
+// A Pattern is a reusable solution ("how to guarantee success") declared as
+// pure data. Concrete usage fills its params and action injection points.
+
+export interface PatternParamDef {
+  type: 'int' | 'string';
+  min?: number;
+  default?: number | string;
+}
+
+export interface PatternDef {
+  name: string;
+  params: Record<string, PatternParamDef>;
+}
+
+export interface PatternRef {
+  ref: string;
+  args: Record<string, unknown>;
+}
+
+export function definePattern(def: PatternDef): PatternDef {
+  return def;
+}
+
+export function ref(name: string, args: Record<string, unknown>): PatternRef {
+  return { ref: name, args };
+}

package/src/patterns/retry.ts

@@ -0,0 +1,55 @@
+import { PatternDef } from '../pattern';
+
+// Retry pattern: blind mechanical retry for read-only operations.
+// Valid because a read-only action is idempotent by nature: clicking a query
+// button any number of times never changes the result, so retrying the same
+// call is always safe. No idempotency key, no query-and-resume, no compensate.
+
+export const retryPattern: PatternDef = {
+  name: 'retry',
+  params: {
+    max: { type: 'int', min: 1, default: 3 },
+    backoffMs: { type: 'int', min: 0, default: 0 },
+  },
+};
+
+export interface RetryAction {
+  /** Function to call, e.g. 'queryOrderList' */
+  call: string;
+  /** Type name of the single argument passed through, e.g. 'OrderQueryParams' */
+  params?: string;
+}
+
+export interface RetryRefArgs {
+  max?: number;
+  backoffMs?: number;
+  action: RetryAction;
+  /** Generated function name; defaults to '<call>WithRetry' */
+  fnName?: string;
+}
+
+export function renderRetry(args: RetryRefArgs): string {
+  if (args.max !== undefined && args.max < 1) throw new Error('retry: max must be >= 1');
+  if (!args.action.call) throw new Error('retry: action.call is required');
+
+  const max = args.max ?? 3;
+  const backoffMs = args.backoffMs ?? 0;
+  const call = args.action.call;
+  const paramType = args.action.params ?? 'unknown';
+  const fnName = args.fnName ?? `${call}WithRetry`;
+  const retryLine = backoffMs > 0 ? `      await sleep(${backoffMs});` : '';
+
+  return [
+    `export async function ${fnName}(params: ${paramType}) {`,
+    `  for (let attempt = 1; ; attempt++) {`,
+    `    try {`,
+    `      return await ${call}(params);`,
+    `    } catch (err) {`,
+    `      if (attempt >= ${max}) throw err;`,
+    retryLine,
+    `    }`,
+    `  }`,
+    `}`,
+    '',
+  ].join('\n');
+}

package/src/project.ts

@@ -0,0 +1,55 @@
+import { SchemaBase } from './dsl';
+
+// Project topology definitions: describe the applications (frontends) and
+// backend APIs of a repository, and which frontends each API serves.
+
+/** Frontend form factor. Closed enum, extend when new form factors appear. */
+export type FrontType = 'admin' | 'wxmini';
+
+/** A frontend application (e.g. admin console, wechat mini program). */
+export interface FrontApp extends SchemaBase {
+  type: FrontType;
+  /** Source directory relative to project root, e.g. 'web-admin/'. */
+  dir: string;
+}
+
+/** A backend API service. apps references shared FrontApp instances. */
+export interface ProjectApi extends SchemaBase {
+  /** Source directory relative to project root, e.g. 'api/'. */
+  dir: string;
+  /** Frontends this API serves. Direct instance references (see defineProject). */
+  apps: FrontApp[];
+  /** API base URL prefix shared by all apps it serves, e.g. '/mall'. '' = no prefix. */
+  contextPath?: string;
+}
+
+/** A third-party system (e.g. wechat pay, unionpay). Owns its own
+ *  implementation dir and contract (controller_types), just like an API,
+ *  but is not part of this repo's served surface. */
+export interface ThirdApi extends SchemaBase {
+  /** Source directory relative to project root, e.g. 'wechat/'. */
+  dir: string;
+}
+
+export interface ProjectSchema extends SchemaBase {
+  apps: FrontApp[];
+  apis: ProjectApi[];
+  thirdApis: ThirdApi[];
+}
+
+/**
+ * Defines the project topology. FrontApp instances are shared value objects:
+ * api.apps references the same instances from project.apps, so an app served
+ * by multiple APIs is defined once and referenced many times.
+ */
+export function defineProject(
+  name: string,
+  schema: {
+    description?: string;
+    apps: FrontApp[];
+    apis: ProjectApi[];
+    thirdApis?: ThirdApi[];
+  },
+): ProjectSchema {
+  return { name, ...schema, thirdApis: schema.thirdApis ?? [] };
+}

package/src/prototype.ts

@@ -0,0 +1,30 @@
+import { SchemaBase } from './dsl';
+
+// Prototype definitions: high-level design of a page. A prototype lists only
+// the fields a page needs — no types, no bindings to apps/APIs/tables. Field
+// details (DTO/table definitions) are written separately and connected later.
+
+/** Display metadata for a prototype field. */
+export interface PrototypeFieldMeta {
+  label: string;
+  description?: string;
+}
+
+export interface PrototypeSchema extends SchemaBase {
+  /** Field requirements: key is the field name, value is display metadata. */
+  fields: Record<string, PrototypeFieldMeta>;
+}
+
+/**
+ * Defines a page prototype. The field keys become the names referenced by
+ * later DTO/table definitions; here they only carry label/description.
+ */
+export function definePrototype(
+  name: string,
+  schema: {
+    description?: string;
+    fields: Record<string, PrototypeFieldMeta>;
+  },
+): PrototypeSchema {
+  return { name, ...schema };
+}

package/src/typebox-driver.ts

@@ -50,9 +50,8 @@ function renderBasic(field: Field, pattern: string | undefined, resolver: EnumRe
     case 'json':
       return 'Type.Unknown()';
     case 'enum': {
-      if (!field.jsName) throw new Error(`enum field ${field.name} requires jsName to render`);
-      const ref = resolver?.(field.jsName);
-      if (!ref) throw new Error(`enum field ${field.name}: no import ref for ${field.jsName} — pass an EnumResolver`);
+      const ref = resolver?.(field.enum.jsName);
+      if (!ref) throw new Error(`enum field ${field.name}: no import ref for ${field.enum.jsName} — pass an EnumResolver`);
       return `Type.Enum(${ref.name})`;
     }
     default:
@@ -97,9 +96,8 @@ function collectEnumImports(
     return;
   }
   if (f.field.type === 'enum') {
-    if (!f.field.jsName) throw new Error(`enum field ${f.field.name} requires jsName to render`);
-    const ref = resolver?.(f.field.jsName);
-    if (!ref) throw new Error(`enum field ${f.field.name}: no import ref for ${f.field.jsName} — pass an EnumResolver`);
+    const ref = resolver?.(f.field.enum.jsName);
+    if (!ref) throw new Error(`enum field ${f.field.name}: no import ref for ${f.field.enum.jsName} — pass an EnumResolver`);
     out.set(`${ref.from}#${ref.name}`, ref);
   }
 }