@pylonts/dsl 1.1.1 → 1.1.2

package/src/flow.ts

@@ -1,104 +1,104 @@
-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`);
-    }
-  }
+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/index.ts

@@ -1,21 +1,31 @@
-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 './page.js';
-export * from './curd.js';
-export * from './page-flow.js';
-export * from './mermaid-driver.js';
+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

@@ -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

@@ -1,45 +1,12 @@
-/**
- * Pure-data mock descriptor. Stored on DTO fields, consumed by gen-cli mock
- * or runtime resolveMock. 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;
-  [param: string]: unknown;
-}
-
-/**
- * Result of a descriptor factory call: pure-data descriptor + lazy generator.
- * generate is non-enumerable — JSON.stringify / spread won't pick it up.
- */
-export interface MockSchema {
-  descriptor: MockDescriptor;
-  generate: () => unknown;
-}
-
-type Params = Record<string, unknown>;
-
-/**
- * Define a mock descriptor factory.
- *
- * @param fn      mock function name (for descriptor & dispatch)
- * @param resolve converts descriptor params to a no-arg generator
- * @returns       (params?) => { descriptor, generate }
- */
-export function defineMock(
-  fn: string,
-  resolve: (d: Params) => () => unknown,
-): (params?: Params) => MockSchema {
-  return (params?: Params) => {
-    const d: MockDescriptor = { fn, ...params };
-    const result = { descriptor: d } as MockSchema;
-    Object.defineProperty(result, 'generate', {
-      value: resolve(d),
-      enumerable: false,
-    });
-    return result;
-  };
-}
+/**
+ * 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;
+}

package/src/mysql-driver.ts

@@ -3,6 +3,11 @@ import { ForeignKey, Index, TableSchema } from './db.js';
 
 // MySQL driver: converts a TableSchema into a CREATE TABLE statement.
 
+/** Default value constant for created_at columns. */
+export const CURRENT_TIMESTAMP = 'CURRENT_TIMESTAMP';
+/** Default value constant for updated_at columns (with auto-update). */
+export const CURRENT_TIMESTAMP_ON_UPDATE = 'CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP';
+
 function columnType(field: Field): string {
   switch (field.type) {
     case 'string':
@@ -34,8 +39,9 @@ function columnType(field: Field): string {
 
 function renderDefault(field: Field): string {
   if (field.default === undefined) return '';
-  // CURRENT_TIMESTAMP is a MySQL function keyword, not a string literal.
-  if (field.default === 'CURRENT_TIMESTAMP') return ' DEFAULT CURRENT_TIMESTAMP';
+  // MySQL keyword expressions (CURRENT_TIMESTAMP, CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
+  // NULL, etc.) — render bare, no quotes.
+  if (/^[A-Z]/.test(field.default)) return ` DEFAULT ${field.default}`;
   // Numeric columns take a bare literal, not a quoted one.
   if (field.type === 'integer' || field.type === 'bigint' || field.type === 'decimal' || field.type === 'boolean') {
     return ` DEFAULT ${field.default}`;

package/src/navigation.ts

@@ -0,0 +1,29 @@
+import type { RouteDataSchema } from './route.js';
+import type { ActionSchema } from './action.js';
+import { PageSchema } from './page.js';
+
+/** Navigation primitives: front-end routing actions that are not provider calls. */
+export interface NavigationAction extends ActionSchema {
+  type: 'navigation';
+  method: 'back' | 'push' | 'popup' | 'home';
+  /** Target page for push navigation. */
+  target?: PageSchema;
+  /** Route params type for push navigation. Auto-derived from target.params if omitted. */
+  params?: RouteDataSchema;
+}
+
+export const navigation = {
+  back(description?: string): NavigationAction {
+    return { name: 'back', type: 'navigation', method: 'back', description };
+  },
+  push(options: { target: PageSchema; params?: RouteDataSchema; description?: string }): NavigationAction {
+    const { target, params, description } = options;
+    return { name: 'push', type: 'navigation', method: 'push', target, params: params ?? target.params, description };
+  },
+  popup(description?: string): NavigationAction {
+    return { name: 'popup', type: 'navigation', method: 'popup', description };
+  },
+  home(description?: string): NavigationAction {
+    return { name: 'home', type: 'navigation', method: 'home', description };
+  },
+};

package/src/page-def.ts

@@ -0,0 +1,80 @@
+import type { ImportableSchemaBase, CollectionSchemaBase, SchemaBase } from './dsl.js';
+import { DtoField } from './dto.js';
+import type { DtoMessage, DtoArrayField, DtoObjectField } from './dto.js';
+import type { ComponentSchema } from './component.js';
+import type { ActionSchema } from './action.js';
+
+export type { RouteDataSchema } from './route.js';
+export { defineRouteData } from './route.js';
+
+// PageDef: a page skeleton declaration. Describes what data a page needs
+// and where each field comes from (route params, provider calls, or literals).
+// Driver identifies the source by inspecting each field's .schema back-reference.
+
+/** Page lifecycle events that trigger data loading. */
+export interface EventSchema extends SchemaBase {
+  type: 'onLoad' | 'onShow' | 'onHide' | 'onPullDownRefresh' | 'onReachBottom';
+  /** Actions that fire when this event occurs. */
+  actions?: ActionSchema[];
+}
+
+export const events = {
+  onLoad(actions?: ActionSchema[], description?: string): EventSchema {
+    return { name: 'onLoad', type: 'onLoad', actions, description };
+  },
+  onShow(actions?: ActionSchema[], description?: string): EventSchema {
+    return { name: 'onShow', type: 'onShow', actions, description };
+  },
+  onHide(actions?: ActionSchema[], description?: string): EventSchema {
+    return { name: 'onHide', type: 'onHide', actions, description };
+  },
+  onPullDownRefresh(actions?: ActionSchema[], description?: string): EventSchema {
+    return { name: 'onPullDownRefresh', type: 'onPullDownRefresh', actions, description };
+  },
+  onReachBottom(actions?: ActionSchema[], description?: string): EventSchema {
+    return { name: 'onReachBottom', type: 'onReachBottom', actions, description };
+  },
+};
+
+/** Page data: a named collection of fields that defines the page's data shape. */
+export interface PageDataSchema extends CollectionSchemaBase {
+  type: 'pageData';
+  fields: Record<string, DtoField | DtoMessage | DtoArrayField | DtoObjectField>;
+}
+
+export function definePageData(fields: PageDataSchema['fields']): PageDataSchema {
+  // Page data has no meaningful identity of its own; the page name already
+  // scopes it, so the schema name defaults to 'data'.
+  const data: PageDataSchema = { name: 'data', type: 'pageData', fields };
+  // Write back field names (same convention as buildMessage) so defineRef
+  // produces refs with a real field name instead of ''.
+  for (const key of Object.keys(data.fields)) {
+    const df = data.fields[key];
+    if (df instanceof DtoField) {
+      df.name = key;
+      df.schema = data;
+    }
+  }
+  return data;
+}
+
+/** Page skeleton definition. */
+export interface PageDef extends ImportableSchemaBase {
+  data: PageDataSchema;
+  /** Lifecycle events that trigger data loading. */
+  events: EventSchema[];
+  /** Page actions (provider calls, navigation, etc.). */
+  actions: ActionSchema[];
+  /** UI component declarations that make up the page skeleton. */
+  components: ComponentSchema[];
+  /** Whether the driver should generate page-level loading / error / empty state wrappers. */
+  handleStates?: boolean;
+}
+
+/** Define a page skeleton. */
+export function definePageDef(
+  name: string,
+  schema: Omit<PageDef, 'name'>,
+): PageDef {
+  return { name, ...schema };
+}

package/src/page-flow.ts

@@ -1,5 +1,8 @@
 import { SchemaBase } from './dsl.js';
-import { ActionSchema, Page } from './page.js';
+import type { ActionSchema } from './action.js';
+import { Page, getRegisteredPages, clearRegisteredPages } from './page.js';
+import type { PageDef } from './page-def.js';
+import type { NavigationAction } from './navigation.js';
 
 // 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.
@@ -16,7 +19,7 @@ export interface PageEdge extends SchemaBase {
 export interface PageFlow extends SchemaBase {
   /** Entry page. */
   start: Page;
-  /** All pages, collected from edges (deduplicated by object identity). */
+  /** All pages explicitly declared by the caller. */
   pages: Page[];
   edges: PageEdge[];
 }
@@ -30,23 +33,122 @@ export function definePageFlow(
   name: string,
   schema: {
     start: Page;
+    pages: 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);
-      }
+  const { start, pages, edges: explicitEdges, description } = schema;
+
+  // Resolve the back action from any page's actions list (PageSchema at runtime)
+  const backAction = findBackAction(pages);
+
+  // Auto-generate back edges: for every explicit edge A→B (not itself a back),
+  // if B has no explicit back edge and no existing edge B→A, add B→A with back.
+  const hasExplicitBack = new Set<Page>();
+  for (const e of explicitEdges) {
+    if (e.when && e.when.name === 'back') hasExplicitBack.add(e.start);
+  }
+  const hasReverse = new Set<string>();
+  for (const e of explicitEdges) {
+    hasReverse.add(`${e.start.name}->${e.end.name}`);
+  }
+  const generatedBackEdges: PageEdge[] = [];
+  if (backAction) {
+    for (const e of explicitEdges) {
+      if (e.when && e.when.name === 'back') continue;
+      if (hasExplicitBack.has(e.end)) continue;
+      if (hasReverse.has(`${e.end.name}->${e.start.name}`)) continue;
+      generatedBackEdges.push({
+        name: `${e.end.name}->${e.start.name}`,
+        start: e.end,
+        end: e.start,
+        when: backAction,
+        description: 'auto-generated back edge',
+      });
+      hasExplicitBack.add(e.end);
+    }
+  }
+  const edges = [...explicitEdges, ...generatedBackEdges];
+
+  // Validate: every registered page must be in the flow's pages
+  const registered = getRegisteredPages();
+  const orphaned: string[] = [];
+  for (const rp of registered) {
+    // Compare by object identity — caller passes the same reference
+    if (!pages.includes(rp as unknown as Page)) {
+      orphaned.push(rp.name);
+    }
+  }
+  if (orphaned.length > 0) {
+    throw new Error(
+      `[definePageFlow "${name}"] orphaned pages (defined but not in flow): ${orphaned.join(', ')}`,
+    );
+  }
+  clearRegisteredPages();
+
+  // Validate: start must be in pages
+  if (!pages.includes(start)) {
+    throw new Error(
+      `[definePageFlow "${name}"] start page "${start.name}" not in pages`,
+    );
+  }
+
+  // Validate: every page appears in at least one edge
+  const inEdge = new Set<Page>();
+  for (const e of edges) {
+    inEdge.add(e.start);
+    inEdge.add(e.end);
+  }
+  const isolated: string[] = [];
+  for (const p of pages) {
+    if (!inEdge.has(p)) isolated.push(p.name);
+  }
+  if (isolated.length > 0) {
+    throw new Error(
+      `[definePageFlow "${name}"] isolated pages (no edges): ${isolated.join(', ')}`,
+    );
+  }
+
+  // Validate: all pages reachable from start
+  const adj = new Map<Page, Page[]>();
+  for (const p of pages) adj.set(p, []);
+  for (const e of edges) {
+    const neighbors = adj.get(e.start);
+    if (neighbors) neighbors.push(e.end);
+  }
+  const visited = new Set<Page>();
+  const stack: Page[] = [start];
+  while (stack.length > 0) {
+    const cur = stack.pop()!;
+    if (visited.has(cur)) continue;
+    visited.add(cur);
+    for (const next of adj.get(cur) ?? []) {
+      if (!visited.has(next)) stack.push(next);
     }
   }
-  if (!seen.has(schema.start)) {
-    seen.add(schema.start);
-    pages.push(schema.start);
+  const unreachable: string[] = [];
+  for (const p of pages) {
+    if (!visited.has(p)) unreachable.push(p.name);
+  }
+  if (unreachable.length > 0) {
+    throw new Error(
+      `[definePageFlow "${name}"] unreachable pages: ${unreachable.join(', ')}`,
+    );
+  }
+
+  return { name, description, start, pages, edges };
+}
+
+/** Walk all pages' pageDef.actions (PageSchema runtime shape) to find a NavigationAction with method 'back'. */
+function findBackAction(pages: Page[]): NavigationAction | undefined {
+  for (const p of pages) {
+    const pageDef = (p as unknown as Record<string, unknown>).pageDef as PageDef | undefined;
+    if (!pageDef?.actions) continue;
+    for (const a of pageDef.actions) {
+      const na = a as NavigationAction;
+      if (na.type === 'navigation' && na.method === 'back') return na;
+    }
   }
-  return { name, description: schema.description, start: schema.start, pages, edges: schema.edges };
+  return undefined;
 }