@pylonts/dsl 1.1.21 → 1.1.22

package/src/curd.ts

@@ -1,7 +1,7 @@
 import { SchemaBase, Field } from './dsl.js';
 import { TableSchema } from './db.js';
 import { FrontAppSchema } from './project.js';
-import { ActionSchema } from './action.js';
+import { PageActionSchema } from './page-action.js';
 import type { FilterSchema } from './filter.js';
 import { toKebabCase } from '@pylonts/core';
 
@@ -51,7 +51,7 @@ export interface CurdSchema extends SchemaBase {
   /** Sidebar menu section (group) this CRUD page belongs to. */
   section: string;
   /** Extra user actions on this page (beyond the standard CRUD). */
-  actions?: ActionSchema[];
+  actions?: PageActionSchema[];
   /** Add/update/detail action pages. */
   actionPages?: {
     add?: ActionPage;

package/src/index.ts

@@ -16,6 +16,8 @@ export * from './pattern.js';
 export * from './patterns/retry.js';
 export * from './flow.js';
 export * from './action.js';
+export * from './journey.js';
+export * from './page-action.js';
 export * from './event.js';
 export * from './component.js';
 export * from './convert.js';
@@ -31,6 +33,7 @@ export * from './aggregate.js';
 export * from './repository.js';
 export * from './domain-event.js';
 export * from './third-service.js';
+export * from './task.js';
 export * from './token.js';
 export * from './field-rule.js';
 export * from './exception.js';

package/src/journey.ts

@@ -0,0 +1,61 @@
+import { SchemaBase } from './dsl.js';
+import type { ActionSchema } from './action.js';
+
+// Journey definitions: a cross-app business journey — one data's story along
+// the time axis. A journey is a plain running list (流水账) of actions:
+// page → page → controller → third → db → task, in business order.
+//
+// Design principles:
+// - The protagonist (the data the journey is about) is IMPLICIT — derived
+//   from the actions, never declared. Like a TV protagonist: no label on the
+//   forehead.
+// - Blueprint first, anchored later: actions start as names (text), then
+//   upgrade to real references (page/controller/third/db/task instances).
+//   The name-vs-reference ratio is the refinement level.
+// - Every action is `type + properties + data` (ActionSchema). No from/to
+//   state transitions, no branches — a journey is a single line.
+
+/** One business journey: a goal-directed line of actions. */
+export interface JourneySchema extends SchemaBase {
+  /** Chinese title of the journey. */
+  title: string;
+  /** The business goal the journey achieves (what it is for). */
+  goal: string;
+  /** The running list of actions, in business order. */
+  actions: ActionSchema[];
+}
+
+/**
+ * Defines a business journey. `name` is kebab-case (e.g. 'merchant-onboarding');
+ * the export symbol is the kebab-camel of the name (merchantOnboarding).
+ * File name is the name plus '.journey.ts' (journey_schema/merchant-onboarding.journey.ts).
+ */
+export function defineJourney(options: {
+  name: string;
+  title: string;
+  goal: string;
+  actions: ActionSchema[];
+  description?: string;
+}): JourneySchema {
+  if (!/^[a-z][a-z0-9-]*$/.test(options.name)) {
+    throw new Error(
+      `journey ${options.name}: name must be kebab-case (lowercase letters/digits/dashes)`,
+    );
+  }
+  if (!options.title) {
+    throw new Error(`journey ${options.name}: title is required`);
+  }
+  if (!options.goal) {
+    throw new Error(`journey ${options.name}: goal is required`);
+  }
+  if (!options.actions || options.actions.length === 0) {
+    throw new Error(`journey ${options.name}: actions must be non-empty (a journey is a line of actions)`);
+  }
+  return {
+    name: options.name,
+    title: options.title,
+    goal: options.goal,
+    description: options.description,
+    actions: options.actions,
+  };
+}

package/src/navigation.ts

@@ -1,9 +1,9 @@
 import type { RouteDataSchema } from './route.js';
-import type { ActionSchema } from './action.js';
+import type { PageActionSchema } from './page-action.js';
 import { PageSchema } from './page.js';
 
 /** Navigation primitives: front-end routing actions that are not provider calls. */
-export interface NavigationAction extends ActionSchema {
+export interface NavigationAction extends PageActionSchema {
   type: 'navigation';
   method: 'back' | 'push' | 'popup' | 'home';
   /** Target page for push navigation. */

package/src/page-action.ts

@@ -0,0 +1,59 @@
+import { SchemaBase } from './dsl.js';
+import type { DtoField, DtoMessage, DtoArrayField, DtoObjectField } from './dto.js';
+import type { RefSchema } from './ref.js';
+import type { ControllerMethodSchema } from './controller.js';
+
+// Page actions: what a user can do ON a page (e.g. submit, approve, reject).
+// Distinguished from the cross-domain Action (journey): page actions live in
+// the page skeleton (PageDef.actions / PageSchema.pageDef) and describe the
+// page's own operation surface; journey actions describe what happens along a
+// business line (page / controller / third / db / task). Subclasses use
+// `type` as the discriminator.
+
+/** An action a user can perform on a page (e.g. submit, approve, reject).
+ *  Subclasses use `type` as the discriminator. */
+export interface PageActionSchema extends SchemaBase {
+  type: string;
+}
+
+export function definePageAction(name: string, description?: string): PageActionSchema {
+  return { name, description, type: 'gesture' };
+}
+
+/** 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 PageActionSchema {
+  type: 'call';
+  func: ControllerMethodSchema;
+  args?: Record<string, DtoField | DtoMessage | DtoArrayField | DtoObjectField | RefSchema | string>;
+}
+
+export function call(func: ControllerMethodSchema, args?: Record<string, DtoField | DtoMessage | DtoArrayField | DtoObjectField | RefSchema | string>): CallAction {
+  return { name: func.name, type: 'call', func, args };
+}
+
+/** Assign a call's result to a page data field.
+ *  React: setState({ [field]: await ... }). Mini-program: this.setData({ [field]: ... }). */
+export interface SetDataAction extends PageActionSchema {
+  type: 'setData';
+  call: CallAction;
+  field: DtoField;
+}
+
+export function setData(call: CallAction, field: DtoField): SetDataAction {
+  return { name: 'setData', type: 'setData', call, field };
+}

package/src/page-def.ts

@@ -2,7 +2,7 @@ import type { ImportableSchemaBase, CollectionSchemaBase, SchemaBase } from './d
 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';
+import type { PageActionSchema } from './page-action.js';
 
 export type { RouteDataSchema } from './route.js';
 export { defineRouteData } from './route.js';
@@ -14,24 +14,24 @@ export { defineRouteData } from './route.js';
 /** 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[];
+  /** Page actions that fire when this event occurs. */
+  actions?: PageActionSchema[];
 }
 
 export const events = {
-  onLoad(actions?: ActionSchema[], description?: string): EventSchema {
+  onLoad(actions?: PageActionSchema[], description?: string): EventSchema {
     return { name: 'onLoad', type: 'onLoad', actions, description };
   },
-  onShow(actions?: ActionSchema[], description?: string): EventSchema {
+  onShow(actions?: PageActionSchema[], description?: string): EventSchema {
     return { name: 'onShow', type: 'onShow', actions, description };
   },
-  onHide(actions?: ActionSchema[], description?: string): EventSchema {
+  onHide(actions?: PageActionSchema[], description?: string): EventSchema {
     return { name: 'onHide', type: 'onHide', actions, description };
   },
-  onPullDownRefresh(actions?: ActionSchema[], description?: string): EventSchema {
+  onPullDownRefresh(actions?: PageActionSchema[], description?: string): EventSchema {
     return { name: 'onPullDownRefresh', type: 'onPullDownRefresh', actions, description };
   },
-  onReachBottom(actions?: ActionSchema[], description?: string): EventSchema {
+  onReachBottom(actions?: PageActionSchema[], description?: string): EventSchema {
     return { name: 'onReachBottom', type: 'onReachBottom', actions, description };
   },
 };
@@ -64,7 +64,7 @@ export interface PageDef extends ImportableSchemaBase {
   /** Lifecycle events that trigger data loading. */
   events: EventSchema[];
   /** Page actions (provider calls, navigation, etc.). */
-  actions: ActionSchema[];
+  actions: PageActionSchema[];
   /** UI component declarations that make up the page skeleton. */
   components: ComponentSchema[];
   /** Whether the driver should generate page-level loading / error / empty state wrappers. */

package/src/page-flow.ts

@@ -1,5 +1,5 @@
 import { SchemaBase } from './dsl.js';
-import type { ActionSchema } from './action.js';
+import type { PageActionSchema } from './page-action.js';
 import { Page, getRegisteredPages, clearRegisteredPages } from './page.js';
 import type { PageDef } from './page-def.js';
 import type { NavigationAction } from './navigation.js';
@@ -10,8 +10,8 @@ import type { NavigationAction } from './navigation.js';
 // models the flow graph between pages.
 
 export interface PageEdge extends SchemaBase {
-  /** Trigger action; undefined = default path (success/normal). */
-  when?: ActionSchema;
+  /** Trigger page action; undefined = default path (success/normal). */
+  when?: PageActionSchema;
   start: Page;
   end: Page;
 }
@@ -24,7 +24,7 @@ export interface PageFlow extends SchemaBase {
   edges: PageEdge[];
 }
 
-export function pageEdge(start: Page, end: Page, when?: ActionSchema, description?: string): PageEdge {
+export function pageEdge(start: Page, end: Page, when?: PageActionSchema, description?: string): PageEdge {
   // Auto name for uniformity with SchemaBase; `when` stays the branch marker.
   return { name: `${start.name}->${end.name}`, start, end, when, description };
 }

package/src/popup.ts

@@ -1,15 +1,15 @@
-import type { ActionSchema } from './action.js';
+import type { PageActionSchema } from './page-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 {
+export interface ToastAction extends PageActionSchema {
   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 {
+export interface AlertAction extends PageActionSchema {
   type: 'alert';
   title: string | RefSchema;
   content: string | RefSchema;

package/src/repository.ts

@@ -1,35 +1,35 @@
-import { SchemaBase } from './dsl.js';
-import type { DomainAggregate } from './aggregate.js';
-
-/**
- * Aggregate-grained storage entry. The repository binds one aggregate and
- * exposes the three fixed operation skeletons (load / save / delete) that the
- * generator expands from the aggregate structure:
- *
- *   save(order)  = tx { rootDao.upsert + memberDao cascade by FK / extends }
- *   load(id)     = rootDao.get + memberDao by FK / extends
- *   delete(id)   = tx { memberDao delete + rootDao delete }
- *
- * Callers face the domain concept (Order), never the tables. DAO stays
- * single-table; Repository is the multi-table (aggregate) unit; Service is the
- * use-case unit. Inter-aggregate joins are prohibited — repositories only
- * reference each other by root ID.
- */
-export interface RepositorySchema extends SchemaBase {
-  type: 'repository';
-  /** The aggregate this repository persists (shared instance). */
-  aggregate: DomainAggregate;
-}
-
-export function defineRepository(options: {
-  name: string;
-  aggregate: DomainAggregate;
-  description?: string;
-}): RepositorySchema {
-  return {
-    type: 'repository',
-    name: options.name,
-    description: options.description,
-    aggregate: options.aggregate,
-  };
-}
+import { SchemaBase } from './dsl.js';
+import type { DomainAggregate } from './aggregate.js';
+
+/**
+ * Aggregate-grained storage entry. The repository binds one aggregate and
+ * exposes the three fixed operation skeletons (load / save / delete) that the
+ * generator expands from the aggregate structure:
+ *
+ *   save(order)  = tx { rootDao.upsert + memberDao cascade by FK / extends }
+ *   load(id)     = rootDao.get + memberDao by FK / extends
+ *   delete(id)   = tx { memberDao delete + rootDao delete }
+ *
+ * Callers face the domain concept (Order), never the tables. DAO stays
+ * single-table; Repository is the multi-table (aggregate) unit; Service is the
+ * use-case unit. Inter-aggregate joins are prohibited — repositories only
+ * reference each other by root ID.
+ */
+export interface RepositorySchema extends SchemaBase {
+  type: 'repository';
+  /** The aggregate this repository persists (shared instance). */
+  aggregate: DomainAggregate;
+}
+
+export function defineRepository(options: {
+  name: string;
+  aggregate: DomainAggregate;
+  description?: string;
+}): RepositorySchema {
+  return {
+    type: 'repository',
+    name: options.name,
+    description: options.description,
+    aggregate: options.aggregate,
+  };
+}

package/src/task.ts

@@ -0,0 +1,52 @@
+import { CollectionSchemaBase } from './dsl.js';
+
+// Task definitions: scheduled (timer) operations — the second member of the
+// action closure (action = controller | task | third callback).
+//
+// A task is a contract: name + cron + what it does. It declares NO state
+// changes — state changes are expressed by journey steps. Task implementation
+// (scan logic, idempotency) lives in the implementation layer (e.g. pylon-flow
+// steps).
+//
+// Task represents ONLY timers (cron-driven). Async/event-driven operations
+// belong to the event system (EventObserver / EventNotifier, pending), not
+// here.
+
+export interface TaskSchema extends CollectionSchemaBase {
+  type: 'task';
+  /** Display label (Chinese) for the task. */
+  label: string;
+  /** Cron expression — the timer schedule. */
+  cron: string;
+}
+
+/**
+ * Defines a scheduled task. `name` must end with 'Task' (PascalCase,
+ * e.g. 'AutoRefundTask'); the export symbol equals the name. File name is the
+ * name minus the Task suffix, kebab-cased, plus '.task.ts'
+ * (AutoRefundTask → task_schema/auto-refund.task.ts).
+ */
+export function defineTask(options: {
+  name: string;
+  label: string;
+  cron: string;
+  description?: string;
+}): TaskSchema {
+  if (!/(Task)$/.test(options.name)) {
+    throw new Error(
+      `task ${options.name}: name must end with 'Task' (PascalCase, e.g. 'AutoRefundTask')`,
+    );
+  }
+  if (!options.cron || options.cron.trim() === '') {
+    throw new Error(
+      `task ${options.name}: cron is required (a task is a timer)`,
+    );
+  }
+  return {
+    type: 'task',
+    name: options.name,
+    label: options.label,
+    description: options.description,
+    cron: options.cron,
+  };
+}