@pylonts/dsl 1.1.6 → 1.1.12

package/src/business-flow.ts

@@ -0,0 +1,80 @@
+// business-flow: the minimal form of a flow — a chart. Steps are [from, when,
+// to] tuples (the condition sits between source and target; a two-element
+// [from, to] step has no label); nodes are collected by name from the edges
+// (a name shared by several steps is one node); the first step's from is the
+// start; every node with no outgoing edge falls through to the flow's return
+// end. A node with several outgoing edges is a decision — the mermaid driver
+// draws it as a diamond, and every branch edge must carry a when label or the
+// chart cannot be read (nor later upgraded to machine conditions).
+//
+// The chart compiles to the same graph IR as flow-script: mermaid rendering,
+// reachability checks, and future consumers (an executor) all work unchanged.
+// A chart is the skeleton — upgrade a decision to IF(cond) and a node to
+// invoke(...) when the business logic arrives.
+
+import { defineFlow, edge, node } from './flow.js';
+import type { FlowEdge, FlowNode, FlowSchema, FlowStep } from './flow.js';
+
+/** One chart step: from → to, the optional branch label between them
+ *  (mandatory for decision branches). */
+export type ChartStep = [from: string, to: string] | [from: string, when: string, to: string];
+
+/** Compile a tuple chart into a FlowSchema. */
+export function flowChart(
+  name: string,
+  steps: ChartStep[],
+  options: { description?: string; start?: string } = {},
+): FlowSchema {
+  if (steps.length === 0) {
+    throw new Error(`business-flow ${name}: at least one step is required`);
+  }
+  for (const step of steps) {
+    const from = step[0];
+    const to = step.length === 3 ? step[2] : step[1];
+    if (from === '' || to === '') {
+      throw new Error(`business-flow ${name}: node names must not be empty`);
+    }
+  }
+  if (options.start !== undefined && !steps.some((step) => step[0] === options.start)) {
+    throw new Error(`business-flow ${name}: start "${options.start}" is not the source of any step`);
+  }
+  const nodes = new Map<string, FlowNode>();
+  const byName = (n: string): FlowNode => {
+    let found = nodes.get(n);
+    if (found === undefined) {
+      found = node(n, {});
+      nodes.set(n, found);
+    }
+    return found;
+  };
+  const edges: FlowEdge[] = steps.map((step) => {
+    const from = step[0];
+    const to = step.length === 3 ? step[2] : step[1];
+    const when = step.length === 3 ? step[1] : undefined;
+    return edge(byName(from), byName(to), { when });
+  });
+  // Decision rule: every branch of a multi-outgoing node must carry a label.
+  const outgoing = new Map<FlowStep, FlowEdge[]>();
+  for (const e of edges) {
+    const list = outgoing.get(e.start);
+    if (list === undefined) outgoing.set(e.start, [e]);
+    else list.push(e);
+  }
+  for (const [n, list] of outgoing) {
+    if (list.length > 1 && list.some((e) => e.when === undefined)) {
+      throw new Error(`business-flow ${name}: decision node "${n.name}" — every outgoing branch edge needs a when label`);
+    }
+  }
+  return defineFlow(name, {
+    start: byName(options.start ?? steps[0][0]),
+    description: options.description,
+    edges: (flow) => {
+      // Every path ends somewhere: nodes with no outgoing edge return.
+      const sinks: FlowEdge[] = [];
+      for (const n of nodes.values()) {
+        if (!outgoing.has(n)) sinks.push(edge(n, flow.returnEnd));
+      }
+      return [...edges, ...sinks];
+    },
+  });
+}

package/src/controller.ts

@@ -1,40 +1,54 @@
 import { SchemaBase } from './dsl.js';
-import { FrontAppSchema } from './project.js';
-import type { EndpointSchema } from './endpoint.js';
+import { FrontAppSchema, ProjectApiSchema } from './project.js';
+import type { DtoMessage } from './dto.js';
 
 /** A backend RPC controller. Strong constraints:
  *  - a backend module maps 1:1 to a frontend app (they are peers);
  *  - a controller serves exactly one frontend app — no cross-module calls. */
 export interface ControllerSchema extends SchemaBase {
   type: 'controller';
+  /** The backend api module this controller belongs to (shared instance from
+   *  project.config.ts apis). Controllers are always backend-side, so storage
+   *  is controller_schema/{api.name}/{app.name}/controller/. */
+  api: ProjectApiSchema;
   /** The frontend app this controller serves (shared instance from project.config). */
   app: FrontAppSchema;
-  /** RPC methods exposed by this controller. */
-  methods: ControllerMethodSchema[];
+  /** RPC methods, keyed by method name (key === method.name, enforced by the builder). */
+  methods: Record<string, ControllerMethodSchema>;
 }
 
 export function defineController(options: {
   name: string;
+  api: ProjectApiSchema;
   app: FrontAppSchema;
-  /** Method declarations: type/schema are injected by this builder. */
-  methods: Array<Omit<ControllerMethodSchema, 'type' | 'schema'>>;
+  /** Method declarations: type/schema/name are injected by this builder. */
+  methods: Record<string, Omit<ControllerMethodSchema, 'type' | 'schema' | 'name'>>;
   description?: string;
 }): ControllerSchema {
+  if (!options.api.apps.includes(options.app)) {
+    throw new Error(`controller ${options.name}: api '${options.api.name}' does not serve app '${options.app.name}'`);
+  }
   const schema: ControllerSchema = {
     type: 'controller',
     name: options.name,
     description: options.description,
+    api: options.api,
     app: options.app,
-    methods: [],
+    methods: {},
   };
-  schema.methods = options.methods.map((method) => ({ type: 'method', schema, ...method }));
+  for (const [key, method] of Object.entries(options.methods)) {
+    schema.methods[key] = { type: 'method', schema, name: key, ...method };
+  }
   return schema;
 }
 
-/** An RPC method exposed by a controller. */
+/** An RPC method exposed by a controller. Carries the shared API call
+ *  signature: one request DTO in, one response shape out. Referenced by
+ *  frontend page actions — both sides use the exact same instance, so
+ *  drift is impossible. */
 export interface ControllerMethodSchema extends SchemaBase {
   type: 'method';
   schema: ControllerSchema;
-  /** Shared API signature — same instance the page-side provider references. */
-  signature: EndpointSchema;
+  args: DtoMessage;
+  results: DtoMessage | number | boolean | string;
 }

package/src/convert.ts

@@ -1,43 +1,79 @@
 import type { SchemaBase } from './dsl.js';
 import type { DtoMessage } from './dto.js';
 import type { TableSchema } from './db.js';
+import type { EntitySchema } from './entity.js';
 import type { ThirdMethodSchema } from './third-service.js';
-import type { FrontAppSchema } from './project.js';
+import type { FrontAppSchema, ProjectApiSchema } from './project.js';
 
 // Schema-collection integration: multiple source collections combine into
 // one target collection (e.g. two entity tables into one dto, or entity
 // columns plus a dto into one third-party wire message).
+//
+// A convert file binds to ONE source identity — a table (internal mapping,
+// {Table}Convert.ts) or a third-party service (anti-corruption translation,
+// {third-service}.convert.ts) — and holds N methods keyed by name (same
+// shape as defineService / defineDao).
 
-/** A source/target collection of a convert — dto, entity or third-party message. */
-export type ConvertSourceSchema = DtoMessage | TableSchema | ThirdMethodSchema;
+/** A source/target collection of a convert — dto, entity, table or
+ *  third-party message. Entity sources may carry aggregate fields
+ *  (aggField), e.g. an aggregate result entity projected into a wire
+ *  message. */
+export type ConvertSourceSchema = DtoMessage | TableSchema | ThirdMethodSchema | EntitySchema;
 
-/** Declares a multi-source → single-target schema integration. */
-export interface ConvertSchema extends SchemaBase {
-  type: 'convert';
-  /** The app (module) this convert belongs to — its artifact lands in modules/{app}/convert/. */
-  app: FrontAppSchema;
+/** Method input for defineConvert: type/schema/name are set by the builder. */
+export type ConvertMethodDef = Omit<ConvertMethodSchema, 'type' | 'schema' | 'name'>;
+
+/** One conversion: multiple source collections → single target collection. */
+export interface ConvertMethodSchema extends SchemaBase {
+  type: 'convertMethod';
+  /** The convert file this method belongs to. */
+  schema: ConvertSchema;
   /** Source schemas — one or more, mixed dimensions. */
   sources: ConvertSourceSchema[];
   /** Target schema — the single integrated collection. */
   target: ConvertSourceSchema;
 }
 
+/** Declares multi-source → single-target schema integrations grouped by source identity. */
+export interface ConvertSchema extends SchemaBase {
+  type: 'convert';
+  /** The backend api module this convert belongs to (shared instance from
+   *  project.config.ts apis). Storage is convert_schema/{api.name}/{app.name}/
+   *  — same layout as service_schema. */
+  api: ProjectApiSchema;
+  /** The app (module) this convert belongs to — its artifact lands in modules/{app}/convert/. */
+  app: FrontAppSchema;
+  /** Methods keyed by name — the map key is written back as the method name. */
+  methods: Record<string, ConvertMethodSchema>;
+}
+
 export function defineConvert(options: {
   name: string;
+  api: ProjectApiSchema;
   app: FrontAppSchema;
-  sources: ConvertSourceSchema[];
-  target: ConvertSourceSchema;
+  methods: Record<string, ConvertMethodDef>;
   description?: string;
 }): ConvertSchema {
-  if (options.sources.length === 0) {
-    throw new Error(`convert '${options.name}': sources must not be empty`);
+  if (Object.keys(options.methods).length === 0) {
+    throw new Error(`convert '${options.name}': methods must not be empty`);
+  }
+  if (!options.api.apps.includes(options.app)) {
+    throw new Error(`convert '${options.name}': api '${options.api.name}' does not serve app '${options.app.name}'`);
   }
-  return {
+  const schema: ConvertSchema = {
     type: 'convert',
     name: options.name,
     description: options.description,
+    api: options.api,
     app: options.app,
-    sources: options.sources,
-    target: options.target,
+    methods: {},
   };
+  for (const key of Object.keys(options.methods)) {
+    const method = options.methods[key] as ConvertMethodDef;
+    if (method.sources.length === 0) {
+      throw new Error(`convert '${options.name}': method '${key}' sources must not be empty`);
+    }
+    schema.methods[key] = { type: 'convertMethod', schema, ...method, name: key };
+  }
+  return schema;
 }

package/src/curd.ts

@@ -1,7 +1,8 @@
-import { SchemaBase, Field, Operator } from './dsl.js';
+import { SchemaBase, Field } from './dsl.js';
 import { TableSchema } from './db.js';
 import { FrontAppSchema } from './project.js';
 import { ActionSchema } from './action.js';
+import type { FilterSchema } from './filter.js';
 import { toKebabCase } from '@pylonts/core';
 
 // Admin-only CRUD page standard: binds one entity table to a frontend admin
@@ -26,12 +27,13 @@ export interface CurdListConfig {
   /** List columns; required, non-empty. Every field the list shows must be
    *  listed explicitly. May include cross-table fields via foreign refs. */
   columns: Field[];
-  /** Fuzzy keyword search on this table's columns. */
-  keyword?: { columns: Field[] };
+  /** Page filter (search form + keyword search). Conditions declared on the
+   *  filter render the search form; the filter's keyword (when present)
+   *  drives the keyword query endpoint. Optional — a page without a filter
+   *  has no search form. */
+  filter?: FilterSchema;
   /** Default sort. Required — column and direction are both mandatory. */
   orderBy: { column: Field; direction: 'asc' | 'desc' };
-  /** Search condition fields; op defaults to 'eq'. */
-  searchFields?: { field: Field; op?: Operator }[];
   /** Column header text overrides: Field.name → header text. */
   columnTitles?: Record<string, string>;
 }
@@ -93,7 +95,11 @@ export function defineCurd(name: string, schema: Omit<CurdSchema, 'name'>): Curd
   for (const [pageName, page] of Object.entries(curd.actionPages ?? {})) {
     if (page) assertColumns(curd, `actionPages.${pageName}`, page.columns);
   }
-  assertFieldsOwnTable(curd, 'keyword', curd.list.keyword?.columns ?? []);
+  if (curd.list.filter !== undefined && curd.list.filter.app !== curd.app) {
+    throw new Error(
+      `curd ${name}: list.filter '${curd.list.filter.name}' is bound to app '${curd.list.filter.app.name}' but the curd belongs to app '${curd.app.name}'`,
+    );
+  }
   assertFieldsOwnTable(curd, 'orderBy', [curd.list.orderBy.column]);
   return curd;
 }