@pylonts/dsl 1.0.0 → 1.0.2

package/README.md

@@ -1,94 +1,26 @@
 # @pylonts/dsl
 
-Schema 定义与产物生成分离的 DSL 系统：先写 DSL 元数据（表 / DTO），再由 driver 翻译成目标产物（SQL、TS 枚举、TypeBox 源码）。
+Schema 定义与产物生成分离的 DSL 系统：先写 DSL 元数据（表 / DTO / 原型 / 项目 / 词典），再由 driver 翻译成目标产物（SQL、TS 枚举、TypeBox 源码）。
 
-## 结构
+## 分层结构
 
-```
-dsl/
-├── src/
-│   ├── dsl.ts            # 表 / 字段定义 + builder（stringField / intField / buildTable …）
-│   ├── dto.ts            # 接口层：buildInput / buildOutput / buildQuery / buildPk / from / include / op
-│   ├── mysql-driver.ts   # 表 → CREATE TABLE SQL
-│   ├── enum-driver.ts    # 枚举字段 → TS enum + LABEL 映射源码
-│   └── typebox-driver.ts # DTO → TypeBox 源码（fastify v5 校验）
-└── package.json
-```
-
-## 核心概念：driver 模式
-
-DSL 定义元数据，driver 翻译成目标语言产物。产物与定义解耦，同一份定义可生成不同目标：
-
-| 定义 | Driver | 产物 | 消费方 |
-|---|---|---|---|
-| `TableSchema` | mysql-driver | `CREATE TABLE` | MySQL |
-| `EnumField` | enum-driver | `export enum Xxx { … }` + `XXX_LABEL` | 业务代码 |
-| `DtoMessage` | typebox-driver | `Type.Object({…})` + `Static` 推导 | fastify v5 参数校验 |
+从概要设计到详细设计的自顶向下链路：
 
-## 用法
-
-### 定义表
-
-```ts
-import { bigintField, buildTable, decimalField, stringField } from './src/dsl';
-
-const id = bigintField({ readOnly: true, label: '主键' });
-const merId = bigintField({ label: '商户' });
-
-export const order = buildTable('order', {
-  description: '订单',
-  generator: 'auto_increment',
-  fields: {
-    id,
-    order_no: stringField({ label: '订单号', maxLength: 32, optional: false }),
-    mer_id: merId,
-    amount: decimalField({ precision: 18, scale: 2, label: '金额' }),
-  },
-  primaryKey: id,
-  indexes: [{ fields: merId }],
-});
 ```
-
-### 定义 DTO（四种方向）
-
-```ts
-import { buildInput, buildPk, buildQuery, dtoField, from } from './src/dto';
-
-// 输入：新增订单
-buildInput('OrderAddRequest', { ...from(order, [order.fields.mer_id, order.fields.amount]) });
-
-// 输出：订单行
-buildOutput('OrderRow', from(order, [order.fields.id, order.fields.order_no]));
-
-// 查询：分页 + 过滤（query 字段恒为可选，.op() 声明比较操作符）
-buildQuery('OrderPageQuery', {
-  keyword: dtoField(stringField({ maxLength: 32 })).op('like'),
-  ...from(order, [order.fields.mer_id]),
-}).include({ from: '@pylonts/core', name: 'PageRequest' });
-
-// 主键：按 id 取详情
-buildPk('OrderDetailRequest', from(order, [order.fields.id]));
-```
-
-### 生成产物
-
-```ts
-import { buildCreateTableSql } from './src/mysql-driver';
-import { renderEnum } from './src/enum-driver';
-import { renderDtoMessage } from './src/typebox-driver';
-
-buildCreateTableSql(order);                                  // SQL
-renderEnum(statusField);                                    // TS enum 源码
-renderDtoMessage(orderPageQuery, {
-  source: 'dto_schema/order/order.dsl.dto.ts',
-  resolver: (name) => ({ from: '@mall/enums/user', name }), // 枚举引用解析
-});
+project（地图：应用与 API 拓扑）
+  → dictionary（词典：命名与数据类型标准）
+    → prototype（概要设计：页面与字段）
+      → table / dto（详细设计）
+        → driver 生成产物（SQL / 枚举 / TypeBox）
 ```
 
-## 关键语义
+## 文档
 
-- **字段两层名**：`DtoField.name` 是接口字段名（DTO 容器 map key 反写）；`field.name` 是数据库列名（buildTable 反写）。`from()` 提取的字段共享表 Field 实例，`name/schema` 保持指向表，不会被 DTO 覆盖。
-- **可选性优先级**：DTO 层 `optional` 优先于字段层 `optional`；query 方向所有字段强制可选（Rule B）。
-- **枚举外部引用**：枚举由 enum-driver 生成独立文件，typebox-driver 只渲染 `Type.Enum(名称)` + import 引用，不内联。
-- **HTTP 传 string**：bigint / decimal / date / time 在接口层渲染为 `Type.String()`，保证精度与序列化语义。
-- **继承分页**：`.include({ from, name, args })` 渲染 `Type.Intersect([PageRequest, Type.Object({…})])`。
+- [project.md](./docs/project.md) — 项目拓扑（地图）
+- [dictionary.md](./docs/dictionary.md) — 短语词典（命名标准）
+- [prototype.md](./docs/prototype.md) — 页面原型（概要设计）
+- [table.md](./docs/table.md) — 定义表（详细设计）
+- [dto.md](./docs/dto.md) — 定义 DTO
+- [enum.md](./docs/enum.md) — 定义枚举
+- [driver.md](./docs/driver.md) — driver 模式与产物生成
+- [mysql-connection.md](./docs/mysql-connection.md) — MySQL 连接说明

package/dist/dictionary.d.ts

@@ -0,0 +1,8 @@
+import { SchemaBase } from './dsl';
+/** A vocabulary entry. */
+export interface DictionaryEntry extends SchemaBase {
+    /** Display label (Chinese) for the term. */
+    label?: string;
+}
+/** Creates a phrase entry. */
+export declare function definePhrase(extra: DictionaryEntry): DictionaryEntry;

package/dist/dictionary.js

@@ -0,0 +1,7 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.definePhrase = definePhrase;
+/** Creates a phrase entry. */
+function definePhrase(extra) {
+    return extra;
+}

package/dist/dsl.d.ts

@@ -1,3 +1,4 @@
+import type { DictionaryEntry } from './dictionary';
 export interface SchemaBase {
     name: string;
     description?: string;
@@ -61,13 +62,19 @@ export interface EnumValue {
     symbol: string;
     label: string;
 }
+/** Shared enum definition. Pure value object, safe to reference from multiple fields/tables. */
+export interface EnumDef {
+    /** JS 定义名称，如 MerchantStatus */
+    jsName: string;
+    valueType: 'string' | 'integer';
+    values: EnumValue[];
+}
+export declare function defineEnum(jsName: string, valueType: 'string' | 'integer', values: EnumValue[]): EnumDef;
 export interface EnumField extends BaseField {
     type: 'enum';
     jsType: 'string' | 'number';
-    valueType: 'string' | 'integer';
-    /** JS 定义名称，如 MerchantStatus */
-    jsName?: string;
-    values: EnumValue[];
+    /** Reference to a shared enum definition (see defineEnum). */
+    enum: EnumDef;
 }
 interface JsonField extends BaseField {
     type: 'json';
@@ -90,10 +97,14 @@ export interface TableSchema extends SchemaBase {
     actor?: boolean;
     /** id 生成器 */
     generator?: string;
+    /** 自增主键字段 */
+    autoIncrement?: Field;
     primaryKey?: Field | Field[];
     indexes?: Index[];
     /** 外键，引用其他表的字段 */
     foreignKeys?: Record<string, ForeignKey>;
+    /** 引用的实体短语（词典条目）：本表归属的实体；关联表等多实体场景不需要 */
+    phrase?: DictionaryEntry;
     fields: Record<string, Field>;
 }
 type FieldExtras<T extends Field> = Omit<T, 'name' | 'type' | 'jsType'>;
@@ -108,14 +119,17 @@ export declare function timeField(extra?: FieldExtras<TimeField>): TimeField;
 export declare function datetimeField(extra?: FieldExtras<DateTimeField>): DateTimeField;
 export declare function jsonField(extra?: FieldExtras<JsonField>): JsonField;
 export declare function enumField(extra: Omit<EnumField, 'name' | 'type' | 'jsType'>): EnumField;
-export declare function buildTable(name: string, schema: {
+export declare function defineTable(name: string, schema: {
     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>;
 }): TableSchema;
 export {};

package/dist/dsl.js

@@ -2,6 +2,7 @@
 // DSL field type definitions.
 // Shape: { type: <type name>, <extension fields> }
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.defineEnum = defineEnum;
 exports.stringField = stringField;
 exports.textField = textField;
 exports.intField = intField;
@@ -13,7 +14,10 @@ exports.timeField = timeField;
 exports.datetimeField = datetimeField;
 exports.jsonField = jsonField;
 exports.enumField = enumField;
-exports.buildTable = buildTable;
+exports.defineTable = defineTable;
+function defineEnum(jsName, valueType, values) {
+    return { jsName, valueType, values };
+}
 function stringField(extra = {}) {
     return { name: '', type: 'string', jsType: 'string', ...extra };
 }
@@ -45,22 +49,38 @@ function jsonField(extra = {}) {
     return { name: '', type: 'json', jsType: 'object', ...extra };
 }
 function enumField(extra) {
-    const jsType = extra.valueType === 'integer' ? 'number' : 'string';
+    const jsType = extra.enum.valueType === 'integer' ? 'number' : 'string';
     return { name: '', type: 'enum', jsType, ...extra };
 }
-function buildTable(name, schema) {
+function defineTable(name, schema) {
     const table = { 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];
-        for (const ref of refs) {
+        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.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/dist/enum-driver.d.ts

@@ -1,2 +1,2 @@
-import { EnumField } from './dsl';
-export declare function renderEnum(field: EnumField): string;
+import { EnumDef } from './dsl';
+export declare function renderEnum(def: EnumDef): string;

package/dist/enum-driver.js

@@ -1,7 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.renderEnum = renderEnum;
-// 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 {
@@ -23,12 +23,10 @@ function renderValue(value) {
 function labelName(jsName) {
     return `${jsName.replace(/([a-z0-9])([A-Z])/g, '$1_$2').toUpperCase()}_LABEL`;
 }
-function renderEnum(field) {
-    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)},`);
+function renderEnum(def) {
+    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,

package/dist/flow.d.ts

@@ -0,0 +1,28 @@
+import { SchemaBase } from './dsl';
+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 declare function node(name: string, flow?: FlowSchema, description?: string): FlowNode;
+export declare function edge(start: FlowNode, end: FlowNode, when?: string, description?: string): FlowEdge;
+export declare function defineFlow(name: string, schema: {
+    start: FlowNode;
+    edges: FlowEdge[];
+    description?: string;
+}): FlowSchema;

package/dist/flow.js

@@ -0,0 +1,68 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.node = node;
+exports.edge = edge;
+exports.defineFlow = defineFlow;
+function node(name, flow, description) {
+    return { name, flow, description };
+}
+function edge(start, end, when, description) {
+    // Auto name for uniformity with SchemaBase; `when` stays the branch marker.
+    return { name: `${start.name}->${end.name}`, start, end, when, description };
+}
+function defineFlow(name, schema) {
+    const seen = new Set();
+    const nodes = [];
+    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 = { 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) {
+    const starts = new Set();
+    for (const e of schema.edges)
+        starts.add(e.start);
+    const reverse = new Map();
+    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();
+    const queue = [];
+    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/dist/index.d.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/dist/index.js

@@ -16,6 +16,15 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
 Object.defineProperty(exports, "__esModule", { value: true });
 __exportStar(require("./dsl"), exports);
 __exportStar(require("./dto"), exports);
+__exportStar(require("./project"), exports);
+__exportStar(require("./prototype"), exports);
+__exportStar(require("./dictionary"), exports);
 __exportStar(require("./mysql-driver"), exports);
 __exportStar(require("./enum-driver"), exports);
 __exportStar(require("./typebox-driver"), exports);
+__exportStar(require("./pattern"), exports);
+__exportStar(require("./patterns/retry"), exports);
+__exportStar(require("./flow"), exports);
+__exportStar(require("./page"), exports);
+__exportStar(require("./page-flow"), exports);
+__exportStar(require("./mermaid-driver"), exports);

package/dist/mermaid-driver.d.ts

@@ -0,0 +1,4 @@
+import { FlowSchema } from './flow';
+import { PageFlow } from './page-flow';
+export declare function renderFlowMermaid(schema: FlowSchema): string;
+export declare function renderPageFlowMermaid(schema: PageFlow): string;

package/dist/mermaid-driver.js

@@ -0,0 +1,72 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.renderFlowMermaid = renderFlowMermaid;
+exports.renderPageFlowMermaid = renderPageFlowMermaid;
+// 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) {
+    return s.replace(/"/g, '\\"').replace(/\n/g, '<br/>');
+}
+function renderFlowMermaid(schema) {
+    const lines = ['flowchart TD'];
+    const ids = new Map();
+    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, prefix, lines, ids) {
+    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, ids) {
+    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.
+function renderPageFlowMermaid(schema) {
+    const lines = ['flowchart TD'];
+    const ids = new Map();
+    const byApp = new Map();
+    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/dist/mysql-driver.d.ts

@@ -1,2 +1,6 @@
 import { TableSchema } from './dsl';
-export declare function buildCreateTableSql(schema: TableSchema): string;
+export interface BuildCreateTableSqlOptions {
+    /** 是否生成外键约束，默认 false（不生成） */
+    generateForeignKeys?: boolean;
+}
+export declare function buildCreateTableSql(schema: TableSchema, options?: BuildCreateTableSqlOptions): string;

package/dist/mysql-driver.js

@@ -26,17 +26,19 @@ function columnType(field) {
             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) {
+function columnDef(field, autoIncrement) {
     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(' ');
 }
 function primaryKeyClause(schema) {
@@ -51,12 +53,27 @@ function indexClause(index) {
     const name = index.name ?? fields.map((f) => f.name).join('_');
     return `${kind} ${name} (${fields.map((f) => f.name).join(', ')})`;
 }
-function buildCreateTableSql(schema) {
-    const lines = Object.values(schema.fields).map(columnDef);
+function foreignKeyClause(name, fk) {
+    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})`;
+}
+function buildCreateTableSql(schema, options = {}) {
+    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/dist/page-flow.d.ts

@@ -0,0 +1,21 @@
+import { SchemaBase } from './dsl';
+import { ActionSchema, Page } from './page';
+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 declare function pageEdge(start: Page, end: Page, when?: ActionSchema, description?: string): PageEdge;
+export declare function definePageFlow(name: string, schema: {
+    start: Page;
+    edges: PageEdge[];
+    description?: string;
+}): PageFlow;

package/dist/page-flow.js

@@ -0,0 +1,25 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.pageEdge = pageEdge;
+exports.definePageFlow = definePageFlow;
+function pageEdge(start, end, when, description) {
+    // Auto name for uniformity with SchemaBase; `when` stays the branch marker.
+    return { name: `${start.name}->${end.name}`, start, end, when, description };
+}
+function definePageFlow(name, schema) {
+    const seen = new Set();
+    const pages = [];
+    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/dist/page.d.ts

@@ -0,0 +1,26 @@
+import { SchemaBase } from './dsl';
+import { FrontApp } from './project';
+/** 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 declare function defineAction(name: string, description?: string): ActionSchema;
+export declare function definePage(schema: {
+    name: string;
+    description?: string;
+    app: FrontApp;
+    actions: ActionSchema[];
+}): PageSchema;
+/** 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 declare function page(app: FrontApp, name: string, description?: string): Page;

package/dist/page.js

@@ -0,0 +1,14 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.defineAction = defineAction;
+exports.definePage = definePage;
+exports.page = page;
+function defineAction(name, description) {
+    return { name, description };
+}
+function definePage(schema) {
+    return { ...schema };
+}
+function page(app, name, description) {
+    return { name, app, description };
+}