@pylonts/dsl 1.1.20 → 1.1.22

package/dist/flow.d.ts

@@ -94,13 +94,30 @@ export interface Comparison {
     value?: string | number | EnumValue;
 }
 /** The machine-readable condition behind a guard check or a branch edge
- *  (optional): a utils predicate call (its boolean result decides) or a field
- *  comparison. */
-export type GuardCondition = FlowCall | Comparison;
+ *  (optional): a utils predicate call (its boolean result decides), a field
+ *  comparison, or a composite (not/and/or over sub-conditions). */
+export type GuardCondition = FlowCall | Comparison | ConditionGroup;
+/** A composite condition: not (exactly one sub-condition), and/or (two or
+ *  more). Renderers parenthesize sub-groups, so nesting stays unambiguous. */
+export interface ConditionGroup {
+    kind: 'not' | 'and' | 'or';
+    conds: GuardCondition[];
+}
+export declare function isConditionGroup(c: unknown): c is ConditionGroup;
+/** Negation — the only way to invert a condition (e.g. !predicate). */
+export declare function not(...conds: GuardCondition[]): ConditionGroup;
+/** Conjunction — every sub-condition must hold. */
+export declare function and(...conds: GuardCondition[]): ConditionGroup;
+/** Disjunction — at least one sub-condition holds. */
+export declare function or(...conds: GuardCondition[]): ConditionGroup;
 /** True when the condition operand is the slot itself (slot-level null check),
  *  not a field access on it. Slot metadata (name) lives on the proxy target and
  *  reads without field interception; a field access resolves to { slot, field }. */
 export declare function isFlowSlot(v: unknown): v is FlowSlot;
+/** True when the slot carries a scalar Field (its declared type has a jsType)
+ *  rather than a message — scalar slots support full comparisons
+ *  (gt(slots.total, 100)); message slots only slot-level null checks. */
+export declare function isScalarSlot(slot: FlowSlot): boolean;
 export declare function lt(field: unknown, value: string | number): Comparison;
 export declare function le(field: unknown, value: string | number): Comparison;
 export declare function gt(field: unknown, value: string | number): Comparison;

package/dist/flow.js

@@ -80,19 +80,61 @@ export function isCall(m) {
 export function methodOf(m) {
     return isCall(m) ? m.method : m;
 }
+export function isConditionGroup(c) {
+    return (typeof c === 'object' &&
+        c !== null &&
+        (c.kind === 'not' || c.kind === 'and' || c.kind === 'or') &&
+        Array.isArray(c.conds));
+}
+/** Negation — the only way to invert a condition (e.g. !predicate). */
+export function not(...conds) {
+    if (conds.length !== 1) {
+        throw new Error('not: takes exactly one condition');
+    }
+    return { kind: 'not', conds };
+}
+/** Conjunction — every sub-condition must hold. */
+export function and(...conds) {
+    if (conds.length < 2) {
+        throw new Error('and: requires at least two conditions');
+    }
+    return { kind: 'and', conds };
+}
+/** Disjunction — at least one sub-condition holds. */
+export function or(...conds) {
+    if (conds.length < 2) {
+        throw new Error('or: requires at least two conditions');
+    }
+    return { kind: 'or', conds };
+}
 /** True when the condition operand is the slot itself (slot-level null check),
  *  not a field access on it. Slot metadata (name) lives on the proxy target and
  *  reads without field interception; a field access resolves to { slot, field }. */
 export function isFlowSlot(v) {
     return typeof v === 'object' && v !== null && typeof v.name === 'string';
 }
+/** True when the slot carries a scalar Field (its declared type has a jsType)
+ *  rather than a message — scalar slots support full comparisons
+ *  (gt(slots.total, 100)); message slots only slot-level null checks. */
+export function isScalarSlot(slot) {
+    const t = slot.type;
+    return typeof t === 'object' && t !== null && t.jsType !== undefined;
+}
 function comparison(op, field, value) {
     if (isFlowSlot(field)) {
-        if (op !== 'isNull' && op !== 'isNotNull') {
-            throw new Error(`${op}: a slot-level check only supports isNull/isNotNull — field comparisons need slots.args.amt`);
+        const nullOp = op === 'isNull' || op === 'isNotNull';
+        if (nullOp) {
+            if (value !== undefined) {
+                throw new Error(`${op}: takes no value`);
+            }
         }
-        if (value !== undefined) {
-            throw new Error(`${op}: takes no value`);
+        else {
+            if (!isScalarSlot(field)) {
+                throw new Error(`${op}: a slot-level check only supports isNull/isNotNull — field comparisons need slots.args.amt`);
+            }
+            if (value === undefined) {
+                throw new Error(`${op}: requires a value`);
+            }
         }
         return { kind: 'comparison', op, field, value };
     }
@@ -495,18 +537,39 @@ function validateGuardChecks(schema) {
     }
 }
 // A condition must be a utils predicate call (boolean result, no result
-// slot) or a field comparison whose op is known and whose value presence and
-// type match the operator.
+// slot), a field comparison whose op is known and whose value presence and
+// type match the operator, or a composite (not/and/or) whose sub-conditions
+// are each valid.
 const COMPARE_OPS = ['lt', 'le', 'gt', 'ge', 'eq', 'ne', 'isNull', 'isNotNull'];
 function validateCondition(where, c) {
+    if (isConditionGroup(c)) {
+        if (c.kind === 'not') {
+            if (c.conds.length !== 1) {
+                throw new Error(`${where}: not() takes exactly one condition`);
+            }
+        }
+        else if (c.conds.length < 2) {
+            throw new Error(`${where}: ${c.kind}() takes at least two conditions`);
+        }
+        for (const sub of c.conds)
+            validateCondition(where, sub);
+        return;
+    }
     if (!isCall(c)) {
         if (isFlowSlot(c.field)) {
             const nullOp = c.op === 'isNull' || c.op === 'isNotNull';
-            if (!nullOp) {
-                throw new Error(`${where}: a slot-level check only supports isNull/isNotNull`);
+            if (nullOp) {
+                if (c.value !== undefined) {
+                    throw new Error(`${where}: ${c.op} takes no value`);
+                }
             }
-            if (c.value !== undefined) {
-                throw new Error(`${where}: ${c.op} takes no value`);
+            else {
+                if (!isScalarSlot(c.field)) {
+                    throw new Error(`${where}: a slot-level check only supports isNull/isNotNull`);
+                }
+                if (c.value === undefined) {
+                    throw new Error(`${where}: ${c.op} requires a value`);
+                }
             }
             return;
         }
@@ -540,10 +603,18 @@ function validateCondition(where, c) {
     if (c.result !== undefined) {
         throw new Error(`${where}: a predicate call cannot bind a result slot`);
     }
+    if (m.result === undefined || m.result.jsType !== 'boolean') {
+        const declared = m.result === undefined ? 'void' : m.result.jsType;
+        throw new Error(`${where}: utils predicate "${m.name}" must declare a boolean result (got ${declared}) — ` +
+            `predicates (can/is/has) return boolean; defense guards (assert/validate/ensure) throw internally and are invoked, not used in IF`);
+    }
 }
 /** Slots a condition reads: a comparison's field slot (or the slot itself for
- *  slot-level checks) or a predicate call's arg slots. */
+ *  slot-level checks), a predicate call's arg slots, or every sub-condition's
+ *  slots for a composite. */
 function conditionSlots(c) {
+    if (isConditionGroup(c))
+        return c.conds.flatMap(conditionSlots);
     if (!isCall(c))
         return [isFlowSlot(c.field) ? c.field : c.field.slot];
     return c.args ?? [];

package/dist/index.d.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/dist/index.js

@@ -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/dist/journey.d.ts

@@ -0,0 +1,23 @@
+import { SchemaBase } from './dsl.js';
+import type { ActionSchema } from './action.js';
+/** 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 declare function defineJourney(options: {
+    name: string;
+    title: string;
+    goal: string;
+    actions: ActionSchema[];
+    description?: string;
+}): JourneySchema;

package/dist/journey.js

@@ -0,0 +1,26 @@
+/**
+ * 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) {
+    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/dist/mermaid-driver.js

@@ -1,4 +1,4 @@
-import { isCall, isFlowSlot, methodOf } from './flow.js';
+import { isCall, isConditionGroup, isFlowSlot, methodOf } from './flow.js';
 // 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
@@ -214,6 +214,11 @@ function renderDataLine(n, outgoing) {
     const addCondition = (c) => {
         if (c === undefined)
             return;
+        if (isConditionGroup(c)) {
+            for (const s of c.conds)
+                addCondition(s);
+            return;
+        }
         if (!isCall(c)) {
             reads.add(isFlowSlot(c.field) ? c.field.name : c.field.slot.name);
             return;

package/dist/navigation.d.ts

@@ -1,8 +1,8 @@
 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/dist/page-action.d.ts

@@ -0,0 +1,39 @@
+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';
+/** 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 declare function definePageAction(name: string, description?: string): PageActionSchema;
+/** 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 declare function route(key: string): DataRef;
+/** Create a page-data reference. */
+export declare function data(key: string): DataRef;
+export interface CallAction extends PageActionSchema {
+    type: 'call';
+    func: ControllerMethodSchema;
+    args?: Record<string, DtoField | DtoMessage | DtoArrayField | DtoObjectField | RefSchema | string>;
+}
+export declare function call(func: ControllerMethodSchema, args?: Record<string, DtoField | DtoMessage | DtoArrayField | DtoObjectField | RefSchema | string>): CallAction;
+/** 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 declare function setData(call: CallAction, field: DtoField): SetDataAction;

package/dist/page-action.js

@@ -0,0 +1,17 @@
+export function definePageAction(name, description) {
+    return { name, description, type: 'gesture' };
+}
+/** Create a route-parameter reference. */
+export function route(key) {
+    return { type: 'route', key };
+}
+/** Create a page-data reference. */
+export function data(key) {
+    return { type: 'data', key };
+}
+export function call(func, args) {
+    return { name: func.name, type: 'call', func, args };
+}
+export function setData(call, field) {
+    return { name: 'setData', type: 'setData', call, field };
+}

package/dist/page-def.d.ts

@@ -2,21 +2,21 @@ 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';
 /** 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 declare const events: {
-    onLoad(actions?: ActionSchema[], description?: string): EventSchema;
-    onShow(actions?: ActionSchema[], description?: string): EventSchema;
-    onHide(actions?: ActionSchema[], description?: string): EventSchema;
-    onPullDownRefresh(actions?: ActionSchema[], description?: string): EventSchema;
-    onReachBottom(actions?: ActionSchema[], description?: string): EventSchema;
+    onLoad(actions?: PageActionSchema[], description?: string): EventSchema;
+    onShow(actions?: PageActionSchema[], description?: string): EventSchema;
+    onHide(actions?: PageActionSchema[], description?: string): EventSchema;
+    onPullDownRefresh(actions?: PageActionSchema[], description?: string): EventSchema;
+    onReachBottom(actions?: PageActionSchema[], description?: string): EventSchema;
 };
 /** Page data: a named collection of fields that defines the page's data shape. */
 export interface PageDataSchema extends CollectionSchemaBase {
@@ -30,7 +30,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/dist/page-flow.d.ts

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

package/dist/popup.d.ts

@@ -1,13 +1,13 @@
-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/dist/repository.d.ts

@@ -5,8 +5,8 @@ import type { DomainAggregate } from './aggregate.js';
  * 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 via FK }
- *   load(id)     = rootDao.get + memberDao by via FK
+ *   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

package/dist/task.d.ts

@@ -0,0 +1,20 @@
+import { CollectionSchemaBase } from './dsl.js';
+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 declare function defineTask(options: {
+    name: string;
+    label: string;
+    cron: string;
+    description?: string;
+}): TaskSchema;

package/dist/task.js

@@ -0,0 +1,21 @@
+/**
+ * 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) {
+    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,
+    };
+}

package/dist/utils.d.ts

@@ -1,5 +1,6 @@
 import type { CollectionSchemaBase, Field, SchemaBase } from './dsl.js';
 import type { DtoField } from './dto.js';
+import type { ExceptionSchema } from './exception.js';
 import type { FrontAppSchema, ProjectApiSchema } from './project.js';
 /** A utility method with a full signature. */
 export interface UtilsMethodSchema extends SchemaBase {
@@ -12,6 +13,12 @@ export interface UtilsMethodSchema extends SchemaBase {
      *  computed amounts, ...). The method output is a fresh value, never a
      *  shared table column. Omit for void methods (pure actions). */
     result?: Field;
+    /** Exceptions this method may throw — the failure contract of a defense
+     *  guard (assert/validate/ensure: void, throws internally). Flows route
+     *  invoked guards' throws into their escape set automatically, so a
+     *  guard's throws must be declared by the calling service method (or
+     *  caught in a TRY). Predicates (can/is/has, boolean) do not throw. */
+    throws?: ExceptionSchema[];
 }
 /** Method input for defineUtils: type/schema/name are set by the builder. */
 export type UtilsMethodDef = Omit<UtilsMethodSchema, 'type' | 'schema' | 'name'>;

package/dist/utils.js

@@ -1,3 +1,4 @@
+import { assertNoInlineContainers } from './dto.js';
 export function defineUtils(options) {
     if (options.api !== undefined && options.app !== undefined && !options.api.apps.includes(options.app)) {
         throw new Error(`utils ${options.name}: api '${options.api.name}' does not serve app '${options.app.name}'`);
@@ -12,6 +13,9 @@ export function defineUtils(options) {
     };
     for (const key of Object.keys(options.methods)) {
         const method = options.methods[key];
+        // Same rule as DTO fields: args must not nest inline containers — use a
+        // DTO field reference (args: { items: SubmitRequest.fields.items }).
+        assertNoInlineContainers(options.name, method.args);
         const methodSchema = {
             type: 'utilsMethod',
             name: key,
@@ -19,14 +23,18 @@ export function defineUtils(options) {
             schema,
             args: method.args,
             result: method.result,
+            throws: method.throws,
         };
         // Args: write back on the DtoField wrapper only (safe: wrappers are
-        // created per method via dtoField(), never shared). Inline fields get
-        // their underlying Field written back too; fields wrapping table columns
-        // (domain rules) keep the shared column instance untouched — its
-        // name/schema already point to the table.
+        // created per method via dtoField(), never shared). Shared instances —
+        // DTO fields passed by reference (args: { items: OrderSubmitRequest.fields.items })
+        // and fields wrapping table columns (domain rules) — stay untouched: the
+        // DTO owns its field name/schema, the shared column instance keeps its
+        // table identity.
         for (const argKey of Object.keys(methodSchema.args)) {
             const df = methodSchema.args[argKey];
+            if (df.schema !== undefined)
+                continue;
             df.name = argKey;
             df.schema = schema;
             if (df.field.schema === undefined) {