@pylonts/dsl 1.1.6 → 1.1.12

package/dist/expr.d.ts

@@ -0,0 +1,45 @@
+import type { Field } from './dsl.js';
+/** Binary operator on numeric values. */
+export type BinOp = 'add' | 'sub' | 'mul' | 'div';
+/** A value expression: column reference / literal / method parameter / binary
+ *  operation. Recursive — leaves are col/lit/param, bin combines them. */
+export type ValueExpr = {
+    kind: 'col';
+    field: Field;
+} | {
+    kind: 'lit';
+    value: string | number;
+} | {
+    kind: 'param';
+    name: string;
+} | {
+    kind: 'bin';
+    op: BinOp;
+    left: ValueExpr;
+    right: ValueExpr;
+};
+/** An update SET assignment: `col = expr` (besides the direct-assignment
+ *  columns carried by the args entity — a column must not appear in both). */
+export interface SetExpr {
+    col: Field;
+    expr: ValueExpr;
+}
+export declare function col(field: Field): ValueExpr;
+export declare function lit(value: string | number): ValueExpr;
+export declare function param(name: string): ValueExpr;
+export declare function bin(op: BinOp, left: ValueExpr, right: ValueExpr): ValueExpr;
+/** Convenience builders for the common self-increment/decrement shapes. */
+export declare const incr: (field: Field, by: ValueExpr) => SetExpr;
+export declare const decr: (field: Field, by: ValueExpr) => SetExpr;
+/** Aggregate expression result of an aggregate query column. */
+export interface ComputeExpr {
+    fn: 'sum' | 'avg' | 'count';
+    /** Column the function applies to; absent for count(*). */
+    field?: Field;
+}
+/** Aggregate expressions: Compute.sum(col) / Compute.avg(col) / Compute.count(). */
+export declare const Compute: {
+    sum(field: Field): ComputeExpr;
+    avg(field: Field): ComputeExpr;
+    count(): ComputeExpr;
+};

package/dist/expr.js

@@ -0,0 +1,32 @@
+// Value expression model: the single declarative way to express computed
+// values in dao methods — update SET expressions and criteria right sides.
+// Structural AST (never SQL strings): column references are Field objects
+// (definition-time ownership checks), values bind as parameters at render
+// time. New node kinds can be added without touching existing declarations.
+export function col(field) {
+    return { kind: 'col', field };
+}
+export function lit(value) {
+    return { kind: 'lit', value };
+}
+export function param(name) {
+    return { kind: 'param', name };
+}
+export function bin(op, left, right) {
+    return { kind: 'bin', op, left, right };
+}
+/** Convenience builders for the common self-increment/decrement shapes. */
+export const incr = (field, by) => ({ col: field, expr: bin('add', col(field), by) });
+export const decr = (field, by) => ({ col: field, expr: bin('sub', col(field), by) });
+/** Aggregate expressions: Compute.sum(col) / Compute.avg(col) / Compute.count(). */
+export const Compute = {
+    sum(field) {
+        return { fn: 'sum', field };
+    },
+    avg(field) {
+        return { fn: 'avg', field };
+    },
+    count() {
+        return { fn: 'count' };
+    },
+};

package/dist/filter.d.ts

@@ -0,0 +1,45 @@
+import type { Field, Operator, SchemaBase } from './dsl.js';
+import type { ValueExpr } from './expr.js';
+import type { FrontAppSchema, ProjectApiSchema } from './project.js';
+/** One AND-combined criterion: a column plus its comparison operator. */
+export interface FilterCondition {
+    /** Column to compare (any table — cross-table filters are allowed). */
+    field: Field;
+    /** Comparison operator; defaults to 'eq'. */
+    op?: Operator;
+    /** Right side of the comparison. Absent = the args parameter named after
+     *  the column (existing semantics); present = an explicit value expression
+     *  (column-vs-column, literal, computation). */
+    right?: ValueExpr;
+    /** Required (default) or optional criterion. A filter has one semantics:
+     *  dao filters are required (missing criteria = error), page filters are
+     *  optional (missing criteria = no WHERE). Declared by the filter author. */
+    optional?: boolean;
+}
+/** Query filter: AND-combined conditions plus an optional keyword search. */
+export interface FilterSchema extends SchemaBase {
+    type: 'filter';
+    /** The backend api module this filter belongs to (shared instance from
+     *  project.config.ts apis). Filters are backend-side, so storage is
+     *  filter_schema/{api.name}/{app.name}/filter/. */
+    api: ProjectApiSchema;
+    /** The frontend app this filter belongs to (shared instance from project.config). */
+    app: FrontAppSchema;
+    /** AND-combined conditions (may be empty when keyword is present). */
+    conditions: FilterCondition[];
+    /** Fuzzy keyword search: one input value matched against multiple columns
+     *  via OR-like. Presence drives the keyword query endpoint. */
+    keyword?: {
+        columns: Field[];
+    };
+}
+export declare function defineFilter(options: {
+    name: string;
+    api: ProjectApiSchema;
+    app: FrontAppSchema;
+    conditions?: FilterCondition[];
+    keyword?: {
+        columns: Field[];
+    };
+    description?: string;
+}): FilterSchema;

package/dist/filter.js

@@ -0,0 +1,21 @@
+export function defineFilter(options) {
+    if (!options.api.apps.includes(options.app)) {
+        throw new Error(`filter ${options.name}: api '${options.api.name}' does not serve app '${options.app.name}'`);
+    }
+    const conditions = options.conditions ?? [];
+    if (conditions.length === 0 && options.keyword === undefined) {
+        throw new Error(`filter ${options.name}: conditions and keyword cannot both be empty`);
+    }
+    if (options.keyword !== undefined && options.keyword.columns.length === 0) {
+        throw new Error(`filter ${options.name}: keyword columns must be non-empty`);
+    }
+    return {
+        type: 'filter',
+        name: options.name,
+        description: options.description,
+        api: options.api,
+        app: options.app,
+        conditions,
+        keyword: options.keyword,
+    };
+}

package/dist/flow-script.d.ts

@@ -0,0 +1,108 @@
+import type { DtoMessage } from './dto.js';
+import type { DomainEventSchema } from './domain-event.js';
+import type { ExceptionSchema } from './exception.js';
+import type { FlowMethodRef, FlowSchema, FlowSlot, FlowSlots, GuardCondition } from './flow.js';
+/** A method call in statement position: invoke(m) mutates the input slot in
+ *  place, invoke(m, args) passes one explicit arg slot, invoke(m, args, result)
+ *  additionally assigns the method's results to a slot. args may be a slot
+ *  list (multi-input methods — e.g. a predicate over two slots). In condition
+ *  position (IF(...)), the same call is a utils predicate (result is rejected). */
+export interface InvokeStep {
+    kind: 'invoke';
+    method: FlowMethodRef;
+    args?: FlowSlot | FlowSlot[];
+    result?: FlowSlot;
+}
+/** A construction: the slot is assigned without a method call. */
+export interface WriteStep {
+    kind: 'write';
+    slot: FlowSlot;
+}
+/** An unconditional throw (terminal — nothing runs after it in its block). */
+export interface ThrowStep {
+    kind: 'throw';
+    exception: ExceptionSchema;
+    message?: string;
+}
+/** An early return to the flow's return end (terminal in its block). */
+export interface ReturnStep {
+    kind: 'return';
+}
+/** A domain event publication: writes the event to the outbox inside the
+ *  surrounding transaction. The payload slot defaults to the flow input. */
+export interface PublishStep {
+    kind: 'publish';
+    event: DomainEventSchema;
+    payload?: FlowSlot;
+}
+/** A conditional: the then-branch runs when the condition holds, the
+ *  else-branch (or the next statement) otherwise. */
+export interface IfStep {
+    kind: 'if';
+    cond: GuardCondition;
+    then: ScriptStep[];
+    else?: ScriptStep[];
+}
+export type CatchRoute = [exception: ExceptionSchema, steps: ScriptStep[]];
+/** A protected region: body and catch handlers (and optional finally) compile
+ *  to sub-flows; a catch's steps may be empty (swallow). */
+export interface TryStep {
+    kind: 'try';
+    name?: string;
+    body: ScriptStep[];
+    catches: CatchRoute[];
+    finally?: ScriptStep[];
+}
+/** A named sub-flow region (a private method inlined as a sub-flow). */
+export interface SubStep {
+    kind: 'sub';
+    name: string;
+    steps: ScriptStep[];
+    description?: string;
+}
+export type ScriptStep = InvokeStep | WriteStep | ThrowStep | ReturnStep | PublishStep | IfStep | TryStep | SubStep;
+/** Call a method as a statement or (in IF position) as a utils predicate. */
+export declare function invoke(method: FlowMethodRef, args?: FlowSlot | FlowSlot[], result?: FlowSlot): InvokeStep;
+/** Assign a slot without a method call (a construction). */
+export declare function write(slot: FlowSlot): WriteStep;
+/** Throw an exception — inside an IF branch the condition and the exit merge
+ *  into one guard check; bare in a block it is an unconditional exit. */
+export declare function THROW(exception: ExceptionSchema, message?: string): ThrowStep;
+/** Return early to the flow's return end. */
+export declare function RETURN(): ReturnStep;
+/** Publish a domain event — the outbox write joins the surrounding
+ *  transaction. The payload slot must carry exactly the event's fields
+ *  (compile-time checked against the slot's declared message). */
+export declare function publish(event: DomainEventSchema, payload?: FlowSlot): PublishStep;
+export interface IfBuilder {
+    THEN(...steps: ScriptStep[]): IfBuilt;
+}
+export interface IfBuilt extends IfStep {
+    ELSE(...steps: ScriptStep[]): IfStep;
+}
+/** Conditional step: IF(cond).THEN(...) with optional .ELSE(...). The
+ *  condition is a comparison (lt/gt/eq/...) or a predicate call — an
+ *  invoke(...) in this position is a utils predicate. */
+export declare function IF(cond: GuardCondition | InvokeStep): IfBuilder;
+export interface TryBuilt extends TryStep {
+    CATCH(...routes: CatchRoute[]): TryBuilt;
+    FINALLY(steps: ScriptStep[]): TryBuilt;
+}
+/** Protected region: TRY([...]).CATCH([Exception, [...]], ...).FINALLY([...]). */
+export declare function TRY(body: ScriptStep[], name?: string): TryBuilt;
+/** A named sub-flow region. */
+export declare function sub(name: string, steps: ScriptStep[], description?: string): SubStep;
+/** The script's slot registry: ctx.slots.args and named slots from options.slots. */
+export interface FlowCtx {
+    /** Append statements — they run in order. */
+    next(...steps: ScriptStep[]): void;
+    slots: FlowSlots;
+}
+/** Compile a sequential script into a FlowSchema. options.slots declares the
+ *  named slots (message bindings); every declared slot must be used somewhere
+ *  in the compiled flow. */
+export declare function flowScript(name: string, options: {
+    args: DtoMessage;
+    slots?: Record<string, unknown>;
+    description?: string;
+}, build: (ctx: FlowCtx) => void): FlowSchema;