@pylonts/dsl 1.0.6 → 1.1.2

package/src/mysql-driver.ts

@@ -1,7 +1,13 @@
-import { Field, ForeignKey, Index, TableSchema } from './dsl';
+import { Field } from './dsl.js';
+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':
@@ -31,11 +37,24 @@ function columnType(field: Field): string {
   }
 }
 
+function renderDefault(field: Field): string {
+  if (field.default === undefined) return '';
+  // 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}`;
+  }
+  return ` DEFAULT '${field.default}'`;
+}
+
 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}'`);
+  parts.push(renderDefault(field));
   if (field === autoIncrement) parts.push('AUTO_INCREMENT');
+  if (field.description) parts.push(`COMMENT '${field.description.replace(/'/g, "\\'")}'`);
   return parts.join(' ');
 }
 
@@ -46,14 +65,14 @@ function primaryKeyClause(schema: TableSchema): string | null {
 }
 
 function indexClause(index: Index): string {
-  const fields = Array.isArray(index.fields) ? index.fields : [index.fields];
+  const fields = Array.isArray(index.columns) ? index.columns : [index.columns];
   const kind = index.unique ? 'UNIQUE KEY' : 'KEY';
   const name = index.name ?? fields.map((f) => f.name).join('_');
   return `${kind} ${name} (${fields.map((f) => f.name).join(', ')})`;
 }
 
 function foreignKeyClause(name: string, fk: ForeignKey): string {
-  const fields = Array.isArray(fk.fields) ? fk.fields : [fk.fields];
+  const fields = Array.isArray(fk.columns) ? fk.columns : [fk.columns];
   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`);
@@ -68,7 +87,7 @@ export interface BuildCreateTableSqlOptions {
 }
 
 export function buildCreateTableSql(schema: TableSchema, options: BuildCreateTableSqlOptions = {}): string {
-  const lines = Object.values(schema.fields).map((field) => columnDef(field, schema.autoIncrement));
+  const lines = Object.values(schema.columns).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));
@@ -77,5 +96,5 @@ export function buildCreateTableSql(schema: TableSchema, options: BuildCreateTab
       lines.push(foreignKeyClause(name, fk));
     }
   }
-  return `CREATE TABLE \`${schema.name}\` (\n  ${lines.join(',\n  ')}\n);`;
+  return `CREATE TABLE IF NOT EXISTS \`${schema.name}\` (\n  ${lines.join(',\n  ')}\n);`;
 }

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';
-import { ActionSchema, Page } from './page';
+import { SchemaBase } from './dsl.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 (!seen.has(schema.start)) {
-    seen.add(schema.start);
-    pages.push(schema.start);
+  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);
   }
-  return { name, description: schema.description, start: schema.start, pages, edges: schema.edges };
+  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);
+    }
+  }
+  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 undefined;
+}

package/src/page.ts

@@ -1,40 +1,77 @@
-import { SchemaBase } from './dsl';
-import { FrontApp } from './project';
+import { SchemaBase } from './dsl.js';
+import { FrontAppSchema } from './project.js';
+import type { PageDef } from './page-def.js';
+import type { RouteDataSchema } from './route.js';
 
 // 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[];
+// Module-level registry: every definePage/defineTabPage call registers its
+// result so definePageFlow can check that no page is left out.
+const _pageRegistry = new Set<PageSchema>();
+
+export function getRegisteredPages(): ReadonlySet<PageSchema> {
+  return _pageRegistry;
 }
 
-/** An action a user can perform on a page (e.g. submit, approve, reject). */
-export interface ActionSchema extends SchemaBase {}
+export function clearRegisteredPages(): void {
+  _pageRegistry.clear();
+}
 
-export function defineAction(name: string, description?: string): ActionSchema {
-  return { name, description };
+/** Standalone page definition. A page is a shared value object: it belongs to
+ *  exactly one frontend app. Actions live in the page skeleton (PageDef.actions),
+ *  not on the page itself — the page only carries what the flow/topology needs. */
+export interface PageSchema extends SchemaBase {
+  /** Short display name for topology diagrams. */
+  label: string;
+  /** The frontend app this page belongs to (shared instance from project.config). */
+  app: FrontAppSchema;
+  /** Full page skeleton definition (optional). */
+  pageDef?: PageDef;
+  /** Route params this page expects (e.g. detail page expects productId). */
+  params?: RouteDataSchema;
 }
 
 export function definePage(schema: {
   name: string;
+  label: string;
   description?: string;
-  app: FrontApp;
-  actions: ActionSchema[];
+  app: FrontAppSchema;
+  pageDef?: PageDef;
+  params?: RouteDataSchema;
 }): PageSchema {
-  return { ...schema };
+  const p: PageSchema = { ...schema };
+  _pageRegistry.add(p);
+  return p;
+}
+
+/** Page with bottom tab navigation. tabs collects the child pages reachable via tab switch. */
+export interface TabPageSchema extends PageSchema {
+  tabs: PageSchema[];
+}
+
+export function defineTabPage(schema: {
+  name: string;
+  label: string;
+  description?: string;
+  app: FrontAppSchema;
+  tabs: PageSchema[];
+  pageDef?: PageDef;
+  params?: RouteDataSchema;
+}): TabPageSchema {
+  const p: TabPageSchema = { ...schema };
+  _pageRegistry.add(p);
+  return p;
 }
 
 /** 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 {
+  /** Short display name for topology diagrams. */
+  label?: string;
   /** The frontend app this page belongs to (shared instance from project.config). */
-  app: FrontApp;
+  app: FrontAppSchema;
 }
 
-export function page(app: FrontApp, name: string, description?: string): Page {
-  return { name, app, description };
-}
+export function page(app: FrontAppSchema, name: string, description?: string, label?: string): Page {
+  return { name, label, app, description };
+}

package/src/patterns/retry.ts

@@ -1,55 +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');
+import { PatternDef } from '../pattern.js';
+
+// 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/popup.ts

@@ -0,0 +1,25 @@
+import type { ActionSchema } from './action.js';
+import type { RefSchema } from './ref.js';
+
+/** Display a toast notification. React: toast/message UI. Mini-program: wx.showToast. */
+export interface ToastAction extends ActionSchema {
+  type: 'toast';
+  message: string | RefSchema;
+  icon?: 'success' | 'error' | 'loading' | 'none';
+}
+
+/** Display an alert dialog. React: modal. Mini-program: wx.showModal. */
+export interface AlertAction extends ActionSchema {
+  type: 'alert';
+  title: string | RefSchema;
+  content: string | RefSchema;
+}
+
+export const popup = {
+  toast(message: string | RefSchema, icon?: 'success' | 'error' | 'loading' | 'none'): ToastAction {
+    return { name: 'toast', type: 'toast', message, icon };
+  },
+  alert(title: string | RefSchema, content: string | RefSchema): AlertAction {
+    return { name: 'alert', type: 'alert', title, content };
+  },
+};