@pylonts/dsl 1.1.19 → 1.1.21

package/src/flow.ts

@@ -210,9 +210,49 @@ export interface Comparison {
 }
 
 /** 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 function isConditionGroup(c: unknown): c is ConditionGroup {
+  return (
+    typeof c === 'object' &&
+    c !== null &&
+    ((c as { kind?: unknown }).kind === 'not' || (c as { kind?: unknown }).kind === 'and' || (c as { kind?: unknown }).kind === 'or') &&
+    Array.isArray((c as { conds?: unknown }).conds)
+  );
+}
+
+/** Negation — the only way to invert a condition (e.g. !predicate). */
+export function not(...conds: GuardCondition[]): ConditionGroup {
+  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: GuardCondition[]): ConditionGroup {
+  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: GuardCondition[]): ConditionGroup {
+  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
@@ -221,13 +261,28 @@ export function isFlowSlot(v: unknown): v is FlowSlot {
   return typeof v === 'object' && v !== null && typeof (v as FlowSlot).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: FlowSlot): boolean {
+  const t = slot.type as { jsType?: unknown } | undefined;
+  return typeof t === 'object' && t !== null && t.jsType !== undefined;
+}
+
 function comparison(op: CompareOp, field: unknown, value?: string | number | EnumValue): Comparison {
   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`);
-    }
-    if (value !== undefined) {
-      throw new Error(`${op}: takes no value`);
+    const nullOp = op === 'isNull' || op === 'isNotNull';
+    if (nullOp) {
+      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 };
   }
@@ -869,19 +924,37 @@ function validateGuardChecks(schema: FlowSchema): void {
 }
 
 // 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: readonly CompareOp[] = ['lt', 'le', 'gt', 'ge', 'eq', 'ne', 'isNull', 'isNotNull'];
 
 function validateCondition(where: string, c: GuardCondition): void {
+  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 (c.value !== undefined) {
-        throw new Error(`${where}: ${c.op} takes no value`);
+      if (nullOp) {
+        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;
     }
@@ -908,18 +981,27 @@ function validateCondition(where: string, c: GuardCondition): void {
     }
     return;
   }
-  const m = c.method as { type?: string; name: string };
+  const m = c.method as Partial<UtilsMethodSchema> & { type?: string; name: string };
   if (m.type !== 'utilsMethod') {
     throw new Error(`${where}: check call must be a utils predicate, got ${m.type ?? m.name}`);
   }
   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: GuardCondition): FlowSlot[] {
+  if (isConditionGroup(c)) return c.conds.flatMap(conditionSlots);
   if (!isCall(c)) return [isFlowSlot(c.field) ? c.field : c.field.slot];
   return c.args ?? [];
 }

package/src/mermaid-driver.ts

@@ -1,5 +1,5 @@
 import { FlowEdge, FlowEnd, FlowNode, FlowSchema, FlowStep, FlowNodeOrEnd, GuardNode, TryNode, IfNode } from './flow.js';
-import { isCall, isFlowSlot, methodOf } from './flow.js';
+import { isCall, isConditionGroup, isFlowSlot, methodOf } from './flow.js';
 import type { FlowMethodRef, FlowNodeMethodRef, GuardCondition } from './flow.js';
 import { Page } from './page.js';
 import { PageEdge, PageFlow } from './page-flow.js';
@@ -219,6 +219,10 @@ function renderDataLine(n: FlowNode | GuardNode | IfNode, outgoing: FlowEdge[]):
   const writes = new Set<string>();
   const addCondition = (c: GuardCondition | undefined): void => {
     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/src/repository.ts

@@ -6,8 +6,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/src/typebox-driver.ts

@@ -1,4 +1,4 @@
-import { DtoArrayField, DtoField, DtoMessage, DtoObjectField, ImportBase, ImportRef, isDtoField, isDtoMessage } from './dto.js';
+import { DtoArrayField, DtoField, DtoMessage, DtoObjectField, ImportBase, ImportRef, isDtoField, isDtoMessage, resolveDtoRefChain } from './dto.js';
 import { collectEnumRefs, EnumField, Field } from './dsl.js';
 import type { TableSchema } from './db.js';
 import type { TokenSchema } from './token.js';
@@ -34,21 +34,6 @@ function dtoFieldDescription(f: DtoField): string | undefined {
   return f.description ?? fieldDescription(f.field);
 }
 
-/** Resolve a ref chain to its terminal field (the one without .ref).
- *  Cycles are a DSL definition error — fail loudly at render time. */
-function resolveRefChain(f: DtoField): DtoField {
-  const seen = new Set<DtoField>();
-  let cur: DtoField = f;
-  while (cur.ref !== undefined) {
-    if (seen.has(cur.ref)) {
-      throw new Error(`dto field ${cur.name}: circular ref chain (field references itself)`);
-    }
-    seen.add(cur.ref);
-    cur = cur.ref;
-  }
-  return cur;
-}
-
 function renderBasic(
   field: Field,
   pattern: string | undefined,
@@ -198,7 +183,7 @@ function renderField(f: DtoField, indent: number, resolver: EnumResolver | undef
  *  chain, inherit the terminal field's type/constraints, keep the referencing
  *  field's own overrides (pattern / default / description). */
 function renderRefBase(f: DtoField, indent: number, resolver: EnumResolver | undefined): string {
-  const target = resolveRefChain(f);
+  const target = resolveDtoRefChain(f);
   const targetField = target.field as Field;
   const pattern = f.pattern ?? target.pattern;
   const defaultValue = f.default ?? target.default;
@@ -210,7 +195,7 @@ function renderRefBase(f: DtoField, indent: number, resolver: EnumResolver | und
  *  override first, then the chain's DtoField-level optional, then the bare
  *  column optionality. */
 function renderRefField(f: DtoField, indent: number, resolver: EnumResolver | undefined): string {
-  const target = resolveRefChain(f);
+  const target = resolveDtoRefChain(f);
   const optional = f.optional ?? target.optional ?? (target.field as Field).optional ?? false;
   const base = renderRefBase(f, indent, resolver);
   return optional ? `Type.Optional(${base})` : base;
@@ -253,7 +238,7 @@ function collectEnumImports(
   out: Map<string, ImportBase>,
 ): void {
   if (f.ref !== undefined) {
-    collectEnumImports(resolveRefChain(f), resolver, out);
+    collectEnumImports(resolveDtoRefChain(f), resolver, out);
     return;
   }
   if (f.field.type === 'array') {
@@ -303,14 +288,25 @@ export function collectDtoImports(
   for (const f of Object.values(schema.fields)) collectEnumImports(f, resolver, out);
 }
 
+/** JSON Schema readOnly annotation on a rendered scalar schema: the token
+ *  owns the field, the client must not send it (the __inject adapter
+ *  overwrites any client-supplied value anyway). Injection fields are always
+ *  scalar columns (tables forbid nested columns), so the only object literal
+ *  in a rendered scalar base is its options block. */
+function withReadOnly(base: string): string {
+  const idx = base.lastIndexOf('{');
+  if (idx === -1) return base.replace(/\(\s*\)$/, '({ readOnly: true })');
+  return `${base.slice(0, idx + 1)} readOnly: true,${base.slice(idx + 1)}`;
+}
+
 /** Render the server-injection base: token-injected fields as Optional
- *  properties of a TypeBox object, plus a non-enumerable __inject adapter
- *  (same mechanism as hand-written bases, see pylon __inject docs) that fills
- *  each field from the token at runtime. */
+ *  readOnly properties of a TypeBox object, plus a non-enumerable __inject
+ *  adapter (same mechanism as hand-written bases, see pylon __inject docs)
+ *  that fills each field from the token at runtime. */
 function renderInjectBase(fields: Record<string, DtoField>, resolver: EnumResolver | undefined): string {
   const entries = Object.entries(fields).map(([name, f]) => {
     const base = f.ref !== undefined ? renderRefBase(f, 1, resolver) : renderValue(f, 1, resolver);
-    return `  ${name}: Type.Optional(${base})`;
+    return `  ${name}: Type.Optional(${withReadOnly(base)})`;
   });
   const inner = `Type.Object({\n${entries.join(',\n')}\n})`;
   const assigns = Object.keys(fields)

package/src/utils.ts

@@ -1,5 +1,7 @@
 import type { CollectionSchemaBase, Field, SchemaBase } from './dsl.js';
+import { assertNoInlineContainers } from './dto.js';
 import type { DtoField } from './dto.js';
+import type { ExceptionSchema } from './exception.js';
 import type { FrontAppSchema, ProjectApiSchema } from './project.js';
 
 // Base utility modules — business-agnostic helpers with full method
@@ -20,8 +22,14 @@ export interface UtilsMethodSchema extends SchemaBase {
   args: Record<string, DtoField>;
   /** Output field — a plain inline Field (boolean for checks, decimal for
    *  computed amounts, ...). The method output is a fresh value, never a
-   *  shared table column. */
-  result: Field;
+   *  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. */
@@ -62,6 +70,9 @@ export function defineUtils(options: {
   };
   for (const key of Object.keys(options.methods)) {
     const method = options.methods[key] as UtilsMethodDef;
+    // 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: UtilsMethodSchema = {
       type: 'utilsMethod',
       name: key,
@@ -69,14 +80,17 @@ 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] as DtoField;
+      if (df.schema !== undefined) continue;
       df.name = argKey;
       df.schema = schema;
       if (df.field.schema === undefined) {
@@ -84,9 +98,13 @@ export function defineUtils(options: {
         df.field.schema = schema;
       }
     }
-    // Result: a plain inline Field — write name/schema back directly.
-    methodSchema.result.name = key;
-    methodSchema.result.schema = schema;
+    // Result (optional): a plain inline Field — write name/schema back only
+    // when it is unowned (schema === undefined); shared instances (table
+    // columns, fields already claimed by another container) stay untouched.
+    if (methodSchema.result !== undefined && methodSchema.result.schema === undefined) {
+      methodSchema.result.name = key;
+      methodSchema.result.schema = schema;
+    }
     schema.methods[key] = methodSchema;
   }
   return schema;