@pylonts/dsl 1.1.1 → 1.1.3

package/src/page.ts

@@ -1,40 +1,77 @@
 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. */
+// 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;
+}
+
+export function clearRegisteredPages(): void {
+  _pageRegistry.clear();
+}
+
+/** 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;
-  /** Actions a user can perform on this page (e.g. submit, approve, reject). */
-  actions: ActionSchema[];
+  /** Full page skeleton definition (optional). */
+  pageDef?: PageDef;
+  /** Route params this page expects (e.g. detail page expects productId). */
+  params?: RouteDataSchema;
 }
 
-/** An action a user can perform on a page (e.g. submit, approve, reject). */
-export interface ActionSchema extends SchemaBase {}
+export function definePage(schema: {
+  name: string;
+  label: string;
+  description?: string;
+  app: FrontAppSchema;
+  pageDef?: PageDef;
+  params?: RouteDataSchema;
+}): PageSchema {
+  const p: PageSchema = { ...schema };
+  _pageRegistry.add(p);
+  return p;
+}
 
-export function defineAction(name: string, description?: string): ActionSchema {
-  return { name, description };
+/** Page with bottom tab navigation. tabs collects the child pages reachable via tab switch. */
+export interface TabPageSchema extends PageSchema {
+  tabs: PageSchema[];
 }
 
-export function definePage(schema: {
+export function defineTabPage(schema: {
   name: string;
+  label: string;
   description?: string;
   app: FrontAppSchema;
-  actions: ActionSchema[];
-}): PageSchema {
-  return { ...schema };
+  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: FrontAppSchema;
 }
 
-export function page(app: FrontAppSchema, 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.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');
+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 };
+  },
+};

package/src/project.ts

@@ -1,91 +1,98 @@
-import { SchemaBase } from './dsl.js';
-
-// 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 FrontAppSchema extends SchemaBase {
-  type: FrontType;
-  /** Source directory relative to project root, e.g. 'web-admin/'. */
-  dir: string;
-}
-
-/** A backend API service. apps references shared FrontAppSchema instances. */
-export interface ProjectApiSchema extends SchemaBase {
-  /** Source directory relative to project root, e.g. 'api/'. */
-  dir: string;
-  /** Frontends this API serves. Direct instance references (see defineProject). */
-  apps: FrontAppSchema[];
-  /** API base URL prefix shared by all apps it serves, e.g. '/mall'. '' = no prefix. */
-  contextPath?: string;
-  /** API service base URL for node clients, e.g. 'http://127.0.0.1:3000'. */
-  baseUrl?: 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 ThirdApiSchema extends SchemaBase {
-  /** Source directory relative to project root, e.g. 'wechat/'. */
-  dir: string;
-}
-
-export interface ProjectSchema extends SchemaBase {
-  apps: FrontAppSchema[];
-  apis: ProjectApiSchema[];
-  thirdApis: ThirdApiSchema[];
-}
-
-/**
- * Defines the project topology. FrontAppSchema 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.
- *
- * Runtime-validates app type whitelist, unique names and api.apps reference
- * integrity (same style as defineTable/defineCurd).
- */
-export function defineProject(
-  name: string,
-  schema: {
-    description?: string;
-    apps: FrontAppSchema[];
-    apis: ProjectApiSchema[];
-    thirdApis?: ThirdApiSchema[];
-  },
-): ProjectSchema {
-  const project: ProjectSchema = { name, ...schema, thirdApis: schema.thirdApis ?? [] };
-
-  const appNames = new Set<string>();
-  for (const app of project.apps) {
-    if (!app.name) throw new Error(`project ${name}: app name is required`);
-    if (appNames.has(app.name)) throw new Error(`project ${name}: duplicate app name '${app.name}'`);
-    appNames.add(app.name);
-    if (app.type !== 'admin' && app.type !== 'wxmini') {
-      throw new Error(`project ${name}: app '${app.name}' must be type 'admin' or 'wxmini' (got '${app.type}')`);
-    }
-    if (!app.dir) throw new Error(`project ${name}: app '${app.name}' dir is required`);
-  }
-
-  const apiNames = new Set<string>();
-  for (const api of project.apis) {
-    if (!api.name) throw new Error(`project ${name}: api name is required`);
-    if (apiNames.has(api.name)) throw new Error(`project ${name}: duplicate api name '${api.name}'`);
-    apiNames.add(api.name);
-    if (!api.dir) throw new Error(`project ${name}: api '${api.name}' dir is required`);
-    for (const ref of api.apps) {
-      if (!project.apps.includes(ref)) {
-        throw new Error(`project ${name}: api '${api.name}' references app '${ref.name}' that is not a shared instance in project.apps (define once and reference it)`);
-      }
-    }
-  }
-
-  for (const third of project.thirdApis) {
-    if (!third.name) throw new Error(`project ${name}: thirdApi name is required`);
-    if (!third.dir) throw new Error(`project ${name}: thirdApi '${third.name}' dir is required`);
-  }
-
-  return project;
+import { SchemaBase } from './dsl.js';
+import type { TableSchema } from './db.js';
+
+// 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 FrontAppSchema extends SchemaBase {
+  type: FrontType;
+  /** Source directory relative to project root, e.g. 'web-admin/'. */
+  dir: string;
+  /**
+   * Tenant table for this app. When set, all tables with a foreign key
+   * pointing to this table get automatic tenant scoping: the tenant PK
+   * value is injected from `user.id` into all curd operations.
+   */
+  tenant?: TableSchema;
+}
+
+/** A backend API service. apps references shared FrontAppSchema instances. */
+export interface ProjectApiSchema extends SchemaBase {
+  /** Source directory relative to project root, e.g. 'api/'. */
+  dir: string;
+  /** Frontends this API serves. Direct instance references (see defineProject). */
+  apps: FrontAppSchema[];
+  /** API base URL prefix shared by all apps it serves, e.g. '/mall'. '' = no prefix. */
+  contextPath?: string;
+  /** API service base URL for node clients, e.g. 'http://127.0.0.1:3000'. */
+  baseUrl?: 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 ThirdApiSchema extends SchemaBase {
+  /** Source directory relative to project root, e.g. 'wechat/'. */
+  dir: string;
+}
+
+export interface ProjectSchema extends SchemaBase {
+  apps: FrontAppSchema[];
+  apis: ProjectApiSchema[];
+  thirdApis: ThirdApiSchema[];
+}
+
+/**
+ * Defines the project topology. FrontAppSchema 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.
+ *
+ * Runtime-validates app type whitelist, unique names and api.apps reference
+ * integrity (same style as defineTable/defineCurd).
+ */
+export function defineProject(
+  name: string,
+  schema: {
+    description?: string;
+    apps: FrontAppSchema[];
+    apis: ProjectApiSchema[];
+    thirdApis?: ThirdApiSchema[];
+  },
+): ProjectSchema {
+  const project: ProjectSchema = { name, ...schema, thirdApis: schema.thirdApis ?? [] };
+
+  const appNames = new Set<string>();
+  for (const app of project.apps) {
+    if (!app.name) throw new Error(`project ${name}: app name is required`);
+    if (appNames.has(app.name)) throw new Error(`project ${name}: duplicate app name '${app.name}'`);
+    appNames.add(app.name);
+    if (app.type !== 'admin' && app.type !== 'wxmini') {
+      throw new Error(`project ${name}: app '${app.name}' must be type 'admin' or 'wxmini' (got '${app.type}')`);
+    }
+    if (!app.dir) throw new Error(`project ${name}: app '${app.name}' dir is required`);
+  }
+
+  const apiNames = new Set<string>();
+  for (const api of project.apis) {
+    if (!api.name) throw new Error(`project ${name}: api name is required`);
+    if (apiNames.has(api.name)) throw new Error(`project ${name}: duplicate api name '${api.name}'`);
+    apiNames.add(api.name);
+    if (!api.dir) throw new Error(`project ${name}: api '${api.name}' dir is required`);
+    for (const ref of api.apps) {
+      if (!project.apps.includes(ref)) {
+        throw new Error(`project ${name}: api '${api.name}' references app '${ref.name}' that is not a shared instance in project.apps (define once and reference it)`);
+      }
+    }
+  }
+
+  for (const third of project.thirdApis) {
+    if (!third.name) throw new Error(`project ${name}: thirdApi name is required`);
+    if (!third.dir) throw new Error(`project ${name}: thirdApi '${third.name}' dir is required`);
+  }
+
+  return project;
 }

package/src/prototype.ts

@@ -1,30 +1,30 @@
-import { SchemaBase } from './dsl.js';
-
-// 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 };
+import { SchemaBase } from './dsl.js';
+
+// 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/provider.ts

@@ -0,0 +1,73 @@
+import type { ImportBase } from './import-base.js';
+import type { ImportableSchemaBase } from './dsl.js';
+import type { DtoField, DtoMessage, DtoArrayField, DtoObjectField } from './dto.js';
+import type { ActionSchema } from './action.js';
+import type { RefSchema } from './ref.js';
+import type { ConvertSchema } from './convert.js';
+
+// ProviderSchema: an API function signature (args DTO + results DTO).
+
+/** Parameter data source for a call argument. */
+export type DataRef =
+  | { type: 'route'; key: string }
+  | { type: 'data';  key: string }
+  | { type: 'value'; value: unknown };
+
+/** Create a route-parameter reference. */
+export function route(key: string): DataRef {
+  return { type: 'route', key };
+}
+
+/** Create a page-data reference. */
+export function data(key: string): DataRef {
+  return { type: 'data', key };
+}
+
+export interface CallAction extends ActionSchema {
+  type: 'call';
+  func: ProviderSchema;
+  args?: Record<string, DtoField | DtoMessage | DtoArrayField | DtoObjectField | RefSchema | string>;
+}
+
+
+export function call(func: ProviderSchema, args?: Record<string, DtoField | DtoMessage | DtoArrayField | DtoObjectField | RefSchema | string>): CallAction {
+  return { name: func.name, type: 'call', func, args };
+}
+
+/** Provider function signature. The generated API client exposes one function
+ *  per endpoint; ProviderSchema gives that function a name and types. */
+export interface ProviderSchema extends ImportableSchemaBase {
+  isAsync: boolean;
+  /** Input DTO (buildInput / buildQuery / buildPk result). */
+  args: DtoMessage;
+  /** Output DTO (buildOutput result) or primitive. */
+  results: DtoMessage | number | boolean | string;
+}
+
+/** Define a provider function. */
+export function defineProvider(
+  name: string,
+  schema: {
+    isAsync: boolean;
+    args: DtoMessage;
+    results: DtoMessage | number | boolean | string;
+    description?: string;
+    importRef?: ImportBase;
+  },
+): ProviderSchema {
+  return { name, ...schema };
+}
+
+/** Assign a call's result to a page data field.
+ *  React: setState({ [field]: await ... }). Mini-program: this.setData({ [field]: ... }). */
+export interface SetDataAction extends ActionSchema {
+  type: 'setData';
+  call: CallAction;
+  field: DtoField;
+  /** Optional field-level transform before assignment. */
+  convert?: ConvertSchema;
+}
+
+export function setData(call: CallAction, field: DtoField, convert?: ConvertSchema): SetDataAction {
+  return { name: 'setData', type: 'setData', call, field, convert };
+}

package/src/ref.ts

@@ -0,0 +1,19 @@
+import type { CollectionSchemaBase } from './dsl.js';
+import type { DtoField } from './dto.js';
+
+/** A reference to a field within another schema. Carries a .schema back-reference
+ *  so the driver knows where the data comes from (route params, page data, etc.). */
+export interface RefSchema {
+  name: string;
+  /** Schema back-reference — tells driver the data source. */
+  schema: CollectionSchemaBase;
+  /** The referenced field instance. */
+  field: DtoField;
+}
+
+/** Create a reference to a field in a source schema.
+ *  Writes back field.schema to the source so the driver can trace origin. */
+export function defineRef(source: CollectionSchemaBase, field: DtoField): RefSchema {
+  field.schema = source;
+  return { name: field.name, schema: source, field };
+}

package/src/route.ts

@@ -0,0 +1,12 @@
+import type { CollectionSchemaBase } from './dsl.js';
+import type { DtoField } from './dto.js';
+
+/** Route params: data that arrives from the navigation URL / route. */
+export interface RouteDataSchema extends CollectionSchemaBase {
+  type: 'route';
+  fields: Record<string, DtoField>;
+}
+
+export function defineRouteData(name: string, fields: RouteDataSchema['fields']): RouteDataSchema {
+  return { name, type: 'route', fields };
+}

package/src/utils.ts

@@ -1,11 +1,11 @@
-// ── naming conversions ──
-
-/** snake_case → camelCase: mer_id → merId; names without underscores are unchanged */
-export function toCamelCase(name: string): string {
-  return name.replace(/_([a-z])/g, (_, c: string) => c.toUpperCase());
-}
-
-/** snake_case → PascalCase: mer_id → MerId */
-export function toPascalCase(snake: string): string {
-  return snake.replace(/(^|_)([a-z])/g, (_m, _p, c: string) => c.toUpperCase());
+// ── naming conversions ──
+
+/** snake_case → camelCase: mer_id → merId; names without underscores are unchanged */
+export function toCamelCase(name: string): string {
+  return name.replace(/_([a-z])/g, (_, c: string) => c.toUpperCase());
+}
+
+/** snake_case → PascalCase: mer_id → MerId */
+export function toPascalCase(snake: string): string {
+  return snake.replace(/(^|_)([a-z])/g, (_m, _p, c: string) => c.toUpperCase());
 }