@pylonts/dsl 1.1.6 → 1.1.11

package/dist/dao.js

@@ -1,29 +1,308 @@
+/** The tenant column of the dao table when the app declares a tenant.
+ *  Deterministic name derivation: `{tenant.phrase}_{tenant.pk}` (e.g. shop
+ *  with pk id → `shop_id`) — checked directly against the table columns,
+ *  no FK traversal. Tables without that column are global tables (valid:
+ *  system config tables carry no tenant id). Exported for generator/linter. */
+export function tenantFkOf(dao) {
+    const tenant = dao.app.tenant;
+    if (!tenant)
+        return undefined;
+    const pk = tenant.primaryKey;
+    const phrase = tenant.phrase;
+    if (!pk || Array.isArray(pk) || !phrase) {
+        throw new Error(`app '${dao.app.name}' tenant table '${tenant.name}' must declare a single-column primaryKey and a phrase (tenant column name = {phrase}_{pk})`);
+    }
+    return dao.table.columns[`${phrase.name}_${pk.name}`];
+}
+/** The optimistic-lock version column of the dao table (table-level
+ *  declaration), machine-enforced: update args must carry it, set must not
+ *  touch it. */
+function versionOf(dao) {
+    return dao.table.version;
+}
+/** Validates a ValueExpr: column refs belong to the dao table, param names
+ *  are unique, literal/bin types are numeric-compatible. */
+function validateValueExpr(dao, expr, params, methodName) {
+    const table = dao.table;
+    const cols = Object.values(table.columns);
+    switch (expr.kind) {
+        case 'col':
+            if (!cols.includes(expr.field)) {
+                throw new Error(`dao ${dao.name}.${methodName}: expr references column '${expr.field.name}' which is not a column of table ${table.name}`);
+            }
+            return;
+        case 'lit':
+            if (typeof expr.value === 'string') {
+                throw new Error(`dao ${dao.name}.${methodName}: string literal in a numeric expression — use a param instead`);
+            }
+            return;
+        case 'param':
+            if (params.has(expr.name)) {
+                throw new Error(`dao ${dao.name}.${methodName}: duplicate param '${expr.name}' in set expressions`);
+            }
+            params.add(expr.name);
+            return;
+        case 'bin':
+            validateValueExpr(dao, expr.left, params, methodName);
+            validateValueExpr(dao, expr.right, params, methodName);
+            return;
+    }
+}
+function validateUpdateSet(dao, methodName, m) {
+    const argCols = new Set(m.args.columns.map((c) => c.name));
+    const version = versionOf(dao);
+    for (const setExpr of m.set ?? []) {
+        if (version && setExpr.col === version) {
+            throw new Error(`dao ${dao.name}.${methodName}: set must not touch version column '${version.name}' — the optimistic lock manages it`);
+        }
+        if (!Object.values(dao.table.columns).includes(setExpr.col)) {
+            throw new Error(`dao ${dao.name}.${methodName}: set column '${setExpr.col.name}' is not a column of table ${dao.table.name}`);
+        }
+        if (argCols.has(setExpr.col.name)) {
+            throw new Error(`dao ${dao.name}.${methodName}: set column '${setExpr.col.name}' also appears in args '${m.args.name}' — a column is either directly assigned or expression-set, never both`);
+        }
+        validateValueExpr(dao, setExpr.expr, new Set(), methodName);
+    }
+}
+/** Validates read-method result columns: external reference columns must be
+ *  reachable through a main-table foreign key (FK = join condition). */
+function assertColumnReachable(dao, methodName, c) {
+    const table = dao.table;
+    if (!c.schema) {
+        throw new Error(`dao ${dao.name}.${methodName}: row column '${c.name}' has no schema`);
+    }
+    if (c.schema === table)
+        return;
+    const srcTable = c.schema;
+    const reachable = Object.values(table.foreignKeys ?? {}).some((fk) => {
+        const refs = Array.isArray(fk.references) ? fk.references : [fk.references];
+        return refs.some((r) => r.schema === srcTable);
+    });
+    if (!reachable) {
+        throw new Error(`dao ${dao.name}.${methodName}: row column '${c.name}' belongs to table ${srcTable.name} but ${table.name} has no foreign key pointing to it`);
+    }
+}
+/** Validates read-method result columns: external reference columns must be
+ *  reachable through a main-table foreign key (FK = join condition). */
+function validateRowColumns(dao, methodName, row) {
+    for (const c of row.columns)
+        assertColumnReachable(dao, methodName, c);
+}
+/** Validates key args (get/delete): every key field must be a main-table
+ *  column; the tenant column is injected as a separate parameter and can
+ *  never be a key (a duplicate parameter would render). */
+function validateKeyArgs(dao, methodName, args) {
+    const cols = Object.values(dao.table.columns);
+    const keys = Array.isArray(args) ? args : [args];
+    for (const k of keys) {
+        if (!cols.includes(k)) {
+            throw new Error(`dao ${dao.name}.${methodName}: key column '${k.name}' is not a column of table ${dao.table.name}`);
+        }
+    }
+    const tenant = tenantFkOf(dao);
+    if (tenant && keys.includes(tenant)) {
+        throw new Error(`dao ${dao.name}.${methodName}: key '${tenant.name}' is the tenant column — it is injected as a separate parameter, never a key`);
+    }
+}
+/** Update runs without JOINs, so its where criteria must all reference
+ *  main-table columns — a cross-table criterion would render a raw column
+ *  name that no table in the query provides. Also requires at least one
+ *  locating criterion: without a pk/tenant/version/filter the generated
+ *  UPDATE would have an empty WHERE and touch every row. */
+function validateUpdateWhere(dao, methodName, m) {
+    if (m.where) {
+        for (const c of m.where.conditions) {
+            if (c.field.schema !== dao.table) {
+                const srcName = c.field.schema?.name ?? 'unknown';
+                throw new Error(`dao ${dao.name}.${methodName}: where criterion on '${c.field.name}' belongs to table '${srcName}' — update is single-table and cannot join`);
+            }
+            if (c.optional) {
+                throw new Error(`dao ${dao.name}.${methodName}: where criterion on '${c.field.name}' is optional — update criteria must be required (a missing value would silently drop the criterion)`);
+            }
+            if (!m.args.columns.includes(c.field)) {
+                throw new Error(`dao ${dao.name}.${methodName}: where criterion on '${c.field.name}' is not carried by args '${m.args.name}' — the generated UPDATE reads it from the row`);
+            }
+        }
+    }
+    const pk = dao.table.primaryKey;
+    const hasPk = pk !== undefined && (Array.isArray(pk) ? pk.length > 0 : true);
+    const hasLocator = hasPk || tenantFkOf(dao) !== undefined || versionOf(dao) !== undefined || (m.where !== undefined && m.where.conditions.length > 0);
+    if (!hasLocator) {
+        throw new Error(`dao ${dao.name}.${methodName}: update on table '${dao.table.name}' has no locating criteria — declare a primaryKey, tenant, version column, or a where filter (an empty WHERE updates every row)`);
+    }
+}
+/** Order-by columns must be part of the result row: the generated ORDER BY
+ *  uses the row's result keys, which only exist for selected columns. */
+function validateOrderBy(dao, methodName, m) {
+    if (!m.orderBy)
+        return;
+    const orders = Array.isArray(m.orderBy) ? m.orderBy : [m.orderBy];
+    for (const o of orders) {
+        if (!m.results.columns.includes(o.column)) {
+            throw new Error(`dao ${dao.name}.${methodName}: orderBy column '${o.column.name}' is not part of results '${m.results.name}'`);
+        }
+    }
+}
+/** Aggregate results: the result entity must carry at least one column; every
+ *  plain column (grouping dimension) and every aggregate field's underlying
+ *  column must be reachable (same rule as read results). */
+function validateAggregateResults(dao, methodName, m) {
+    const columns = m.results.columns;
+    if (columns.length === 0) {
+        throw new Error(`dao ${dao.name}.${methodName}: aggregate has no results`);
+    }
+    for (const c of columns) {
+        if (c.type === 'aggregate') {
+            if (c.expr.field)
+                assertColumnReachable(dao, methodName, c.expr.field);
+        }
+        else {
+            assertColumnReachable(dao, methodName, c);
+        }
+    }
+}
+/** Upsert conflict keys: must equal the pk or a complete unique index column
+ *  set, and every key must be carried by args. Auto-increment tables are
+ *  forbidden (MySQL auto_increment burns ids on duplicate-key updates). */
+function validateUpsert(dao, methodName, m) {
+    const table = dao.table;
+    if (table.autoIncrement) {
+        throw new Error(`dao ${dao.name}.${methodName}: upsert on table '${table.name}' with auto-increment pk is forbidden (MySQL auto_increment burns ids on duplicate-key updates)`);
+    }
+    const keys = Array.isArray(m.keys) ? m.keys : [m.keys];
+    if (keys.length === 0) {
+        throw new Error(`dao ${dao.name}.${methodName}: upsert keys must be non-empty`);
+    }
+    for (const k of keys) {
+        if (k.schema !== table) {
+            throw new Error(`dao ${dao.name}.${methodName}: upsert key '${k.name}' is not a column of table ${table.name}`);
+        }
+    }
+    const keyNames = keys.map((k) => k.name).sort();
+    const candidates = [];
+    const uniqueCols = new Set();
+    const pk = table.primaryKey;
+    if (pk) {
+        const cs = (Array.isArray(pk) ? pk : [pk]).map((c) => c.name);
+        candidates.push(cs.sort());
+        for (const n of cs)
+            uniqueCols.add(n);
+    }
+    for (const idx of table.indexes ?? []) {
+        if (idx.unique) {
+            const cs = (Array.isArray(idx.columns) ? idx.columns : [idx.columns]).map((c) => c.name);
+            candidates.push(cs.sort());
+            for (const n of cs)
+                uniqueCols.add(n);
+        }
+    }
+    const matches = candidates.some((c) => c.length === keyNames.length && c.every((n, i) => n === keyNames[i]));
+    if (!matches) {
+        throw new Error(`dao ${dao.name}.${methodName}: upsert keys [${keys.map((k) => k.name).join(', ')}] must equal the pk or a complete unique index column set of table ${table.name}`);
+    }
+    for (const k of keys) {
+        if (!m.args.columns.includes(k)) {
+            throw new Error(`dao ${dao.name}.${methodName}: upsert args '${m.args.name}' must carry conflict key '${k.name}'`);
+        }
+    }
+    // ON DUPLICATE KEY UPDATE has no WHERE — tenant isolation is only possible
+    // when the tenant column participates in the conflict key.
+    const tenant = tenantFkOf(dao);
+    if (tenant && !keys.includes(tenant)) {
+        throw new Error(`dao ${dao.name}.${methodName}: upsert on tenant-scoped table '${table.name}' must include tenant column '${tenant.name}' in keys (ON DUPLICATE KEY UPDATE has no WHERE — tenant isolation requires the tenant column to be part of the conflict key)`);
+    }
+    // The merge clause (col = new.col) only writes non-key writable columns —
+    // conflict keys are the conflict identity, readOnly columns stay
+    // DB-managed, and every pk/unique column is excluded: a merge writing a
+    // unique column could collide with another row's value and chain-fire the
+    // duplicate-key handler (unique columns are conflict identity, not data).
+    const mergeCols = m.args.columns.filter((c) => !keys.includes(c) && !c.readOnly && !uniqueCols.has(c.name));
+    if (mergeCols.length === 0) {
+        throw new Error(`dao ${dao.name}.${methodName}: upsert has no merge columns — args '${m.args.name}' carries only conflict keys, pk/unique and readOnly columns (ON DUPLICATE KEY UPDATE needs at least one writable non-unique column)`);
+    }
+}
+/** Validates write-method args: every column must come from the dao table
+ *  (single-table atomicity). */
+function validateWriteArgs(dao, methodName, args) {
+    const cols = Object.values(dao.table.columns);
+    for (const c of args.columns) {
+        if (!cols.includes(c)) {
+            throw new Error(`dao ${dao.name}.${methodName}: args column '${c.name}' of '${args.name}' is not a column of table ${dao.table.name}`);
+        }
+    }
+}
+/** Enforces the tenant/version column presence on row-carried methods
+ *  (decisions: insert = declared in args; update = extracted from row).
+ *  Tenant is required on both writes (the column is always scoped); version
+ *  is required only on update — inserts let the DB default initialize it. */
+function validateRowCarriedColumns(dao, methodName, method) {
+    const tenant = tenantFkOf(dao);
+    if (tenant) {
+        if (!method.args.columns.includes(tenant)) {
+            throw new Error(`dao ${dao.name}.${methodName}: args '${method.args.name}' must include tenant column '${tenant.name}'`);
+        }
+    }
+    if (method.type === 'update') {
+        const version = versionOf(dao);
+        if (version && !method.args.columns.includes(version)) {
+            throw new Error(`dao ${dao.name}.${methodName}: args '${method.args.name}' must include version column '${version.name}' — the optimistic lock reads it from the row`);
+        }
+    }
+}
 export function defineDao(options) {
+    if (!options.api.apps.includes(options.app)) {
+        throw new Error(`dao ${options.name}: api '${options.api.name}' does not serve app '${options.app.name}'`);
+    }
     const schema = {
         type: 'dao',
         name: options.name,
         description: options.description,
+        api: options.api,
         app: options.app,
         table: options.table,
         methods: {},
     };
     for (const key of Object.keys(options.methods)) {
         const method = options.methods[key];
+        for (const ref of [method.args, 'where' in method ? method.where : undefined]) {
+            if (isFilterSchema(ref) && (ref.api !== options.api || ref.app !== options.app)) {
+                throw new Error(`dao ${options.name}: method '${key}' references filter '${ref.name}' bound to ${ref.api.name}/${ref.app.name} but the dao is bound to ${options.api.name}/${options.app.name}`);
+            }
+        }
+        // Method-kind validation (declaration is complete — every kind is checked).
+        if (method.type === 'insert' || method.type === 'update' || method.type === 'upsert') {
+            const m = method;
+            validateWriteArgs(schema, key, m.args);
+            validateRowCarriedColumns(schema, key, m);
+            if (method.type === 'update') {
+                validateUpdateSet(schema, key, method);
+                validateUpdateWhere(schema, key, method);
+            }
+            if (method.type === 'upsert') {
+                validateUpsert(schema, key, method);
+            }
+        }
+        if (method.type === 'get' || method.type === 'delete') {
+            validateKeyArgs(schema, key, method.args);
+        }
+        if (method.type === 'find' || method.type === 'get') {
+            validateRowColumns(schema, key, method.results);
+        }
+        if (method.type === 'find') {
+            validateOrderBy(schema, key, method);
+        }
+        if (method.type === 'aggregate') {
+            validateAggregateResults(schema, key, method);
+        }
         // Spread of a union loses discriminant correlation; the cast is safe
         // (the builder only adds name and the back-reference field).
         schema.methods[key] = { ...method, name: key, schema };
     }
     return schema;
 }
-/** 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' };
-    },
-};
+function isFilterSchema(value) {
+    if (typeof value !== 'object' || value === null)
+        return false;
+    const v = value;
+    return v.type === 'filter' && typeof v.name === 'string';
+}

package/dist/db.d.ts

@@ -17,6 +17,9 @@ export interface TableSchemaOptions<N extends string = string, C extends Record<
     autoIncrement?: Field;
     /** 本表用于关联显示的名称字段（如 name / username）。被外键引用时，自动用该字段做 label 展示。 */
     label?: Field;
+    /** Optimistic lock version column: updates auto-manage `version = version + 1`
+     *  and `WHERE version = ?` (value taken from the row). Must be an integer column. */
+    version?: Field;
     primaryKey?: Field | Field[];
     indexes?: Index[];
     foreignKeys?: Record<string, ForeignKey>;
@@ -44,6 +47,9 @@ export declare class TableSchema<N extends string = string, C extends Record<str
     foreignKeys?: Record<string, ForeignKey>;
     /** 本表用于关联显示的名称字段（如 name / username）。被外键引用时，自动用该字段做 label 展示。 */
     label?: Field;
+    /** Optimistic lock version column: updates auto-manage `version = version + 1`
+     *  and `WHERE version = ?` (value taken from the row). Must be an integer column. */
+    version?: Field;
     /** 引用的实体短语（词典条目）：本表归属的实体；关联表等多实体场景不需要 */
     phrase?: EntityPhrase;
     /** 本表引用的所有枚举定义（map，key 为枚举标识），显式声明供 gen-enums 收集 */

package/dist/db.js

@@ -18,6 +18,9 @@ export class TableSchema {
     foreignKeys;
     /** 本表用于关联显示的名称字段（如 name / username）。被外键引用时，自动用该字段做 label 展示。 */
     label;
+    /** Optimistic lock version column: updates auto-manage `version = version + 1`
+     *  and `WHERE version = ?` (value taken from the row). Must be an integer column. */
+    version;
     /** 引用的实体短语（词典条目）：本表归属的实体；关联表等多实体场景不需要 */
     phrase;
     /** 本表引用的所有枚举定义（map，key 为枚举标识），显式声明供 gen-enums 收集 */
@@ -40,6 +43,7 @@ export class TableSchema {
         this.indexes = options.indexes;
         this.foreignKeys = options.foreignKeys;
         this.label = options.label;
+        this.version = options.version;
         this.phrase = options.phrase;
         this.enums = options.enums;
         this.columns = options.columns;
@@ -61,6 +65,12 @@ export function defineTable(name, schema) {
     if (table.label && !Object.values(table.columns).includes(table.label)) {
         throw new Error(`table '${name}': label field '${table.label.name}' must be one of the table's columns`);
     }
+    if (table.version && !Object.values(table.columns).includes(table.version)) {
+        throw new Error(`table '${name}': version field '${table.version.name}' must be one of the table's columns`);
+    }
+    if (table.version && table.version.jsType !== 'number') {
+        throw new Error(`table '${name}': version field '${table.version.name}' must be an integer column`);
+    }
     for (const key of Object.keys(table.columns)) {
         const field = table.columns[key];
         if (field.schema && field.schema !== table) {

package/dist/domain-event.d.ts

@@ -0,0 +1,48 @@
+import { SchemaBase } from './dsl.js';
+import type { DtoField } from './dto.js';
+import type { FlowSchema } from './flow.js';
+/**
+ * Domain event declaration: a fact that has happened ("OrderCancelled"),
+ * carrying a data snapshot (not references). Declared as a first-class schema
+ * so the flow `publish` action can be compile-time checked against it (event
+ * name exists, payload fields match) and the outbox table + handler wiring can
+ * be generated.
+ *
+ * Command vs event: a command says "do something" (future tense, one receiver,
+ * caller senses failure); an event says "something happened" (past tense, zero
+ * to many subscribers, publisher does not care who handles it).
+ */
+export interface DomainEventSchema extends SchemaBase {
+    type: 'domain-event';
+    /** Payload fields: data snapshot, not references. */
+    fields: Record<string, DtoField>;
+}
+export declare function defineDomainEvent(options: {
+    name: string;
+    fields: Record<string, DtoField>;
+    description?: string;
+}): DomainEventSchema;
+/**
+ * Event subscription: declares that a handler processes a domain event.
+ * The processing logic is a flow (the flow model is the execution model — a
+ * handler flow receives the event payload as its input slot). A plain async
+ * function is accepted as the runtime path until a flow executor exists; the
+ * declared flow is then compile-time checked (payload fields match the event)
+ * and drives generation.
+ */
+export interface EventHandlerSchema extends SchemaBase {
+    type: 'event-handler';
+    /** Subscribed event name (must match a defineDomainEvent name). */
+    event: string;
+    /** Processing flow — receives the event payload as its input slot. */
+    flow?: FlowSchema;
+    /** Runtime handler function (used directly when no flow executor exists). */
+    handler?: (payload: Record<string, unknown>) => Promise<void> | void;
+}
+export declare function defineEventHandler(options: {
+    name: string;
+    event: string;
+    flow?: FlowSchema;
+    handler?: (payload: Record<string, unknown>) => Promise<void> | void;
+    description?: string;
+}): EventHandlerSchema;

package/dist/domain-event.js

@@ -0,0 +1,24 @@
+export function defineDomainEvent(options) {
+    if (Object.keys(options.fields).length === 0) {
+        throw new Error(`domain event '${options.name}': fields must not be empty`);
+    }
+    return {
+        type: 'domain-event',
+        name: options.name,
+        description: options.description,
+        fields: options.fields,
+    };
+}
+export function defineEventHandler(options) {
+    if (options.flow === undefined && options.handler === undefined) {
+        throw new Error(`event handler '${options.name}': at least one of flow or handler is required`);
+    }
+    return {
+        type: 'event-handler',
+        name: options.name,
+        description: options.description,
+        event: options.event,
+        flow: options.flow,
+        handler: options.handler,
+    };
+}

package/dist/dsl.d.ts

@@ -1,7 +1,8 @@
 import type { ImportBase } from './import-base.js';
 import type { MockDescriptor } from './mock.js';
+import type { ComputeExpr } from './expr.js';
 /** Field query comparison operators (search field semantics). */
-export type Operator = 'eq' | 'gt' | 'gte' | 'lt' | 'lte' | 'like' | 'ne';
+export type Operator = 'eq' | 'gt' | 'gte' | 'lt' | 'lte' | 'like' | 'ne' | 'in' | 'null' | 'notNull';
 export interface SchemaBase {
     name: string;
     description?: string;
@@ -113,7 +114,17 @@ interface ObjectField extends BaseField {
     jsType: 'object';
     properties: Record<string, Field>;
 }
-export type Field = StringField | TextField | IntField | BigintField | DecimalField | RateField | BooleanField | DateField | TimeField | DateTimeField | EnumField | JsonField | ArrayField | ObjectField;
+/** Aggregate result column (count/sum/avg) of an aggregate query — a Field
+ *  so that aggregate result entities can carry it like any other column.
+ *  jsType follows the aggregate precision rule: count → number;
+ *  sum/avg over an integer column → number, anything else → string. */
+interface AggregateField extends BaseField {
+    type: 'aggregate';
+    jsType: 'number' | 'string';
+    /** The aggregate expression producing this column. */
+    expr: ComputeExpr;
+}
+export type Field = StringField | TextField | IntField | BigintField | DecimalField | RateField | BooleanField | DateField | TimeField | DateTimeField | EnumField | JsonField | ArrayField | ObjectField | AggregateField;
 type FieldExtras<T extends Field> = Omit<T, 'name' | 'type' | 'jsType'>;
 export declare function stringField(extra?: FieldExtras<StringField>): StringField;
 export declare function textField(extra?: FieldExtras<TextField>): TextField;
@@ -129,4 +140,8 @@ export declare function jsonField(extra?: FieldExtras<JsonField>): JsonField;
 export declare function arrayField(extra: FieldExtras<ArrayField>): ArrayField;
 export declare function objectField(extra: FieldExtras<ObjectField>): ObjectField;
 export declare function enumField(extra: Omit<EnumField, 'name' | 'type' | 'jsType'>): EnumField;
+/** Aggregate result column field: count → number; sum/avg over an integer
+ *  column → number, anything else (decimal/bigint/rate…) → string.
+ *  Used in aggregate-query result entities (see AggregateSchema). */
+export declare function aggField(name: string, expr: ComputeExpr): AggregateField;
 export {};

package/dist/dsl.js

@@ -53,3 +53,10 @@ export function enumField(extra) {
     const jsType = extra.enum.valueType === 'integer' ? 'number' : 'string';
     return { name: '', type: 'enum', jsType, ...extra };
 }
+/** Aggregate result column field: count → number; sum/avg over an integer
+ *  column → number, anything else (decimal/bigint/rate…) → string.
+ *  Used in aggregate-query result entities (see AggregateSchema). */
+export function aggField(name, expr) {
+    const jsType = expr.field === undefined || expr.field.type === 'integer' ? 'number' : 'string';
+    return { name, type: 'aggregate', jsType, expr };
+}

package/dist/dto.d.ts

@@ -1,5 +1,6 @@
 import { BaseField, CollectionSchemaBase, Field, Operator, SchemaBase } from './dsl.js';
 import { TableSchema } from './db.js';
+import type { EntitySchema } from './entity.js';
 import type { ImportBase } from './import-base.js';
 import type { ThirdMethodSchema } from './third-service.js';
 /** Re-export — Operator lives on the DSL level (see dsl.ts). */
@@ -100,8 +101,9 @@ export declare function buildInput(name: string, fields: Record<string, DtoField
 export declare function buildOutput(name: string, fields: Record<string, DtoField>, description?: string): DtoMessage;
 export declare function buildQuery(name: string, fields: Record<string, DtoField>, description?: string): DtoMessage;
 export declare function buildPk(name: string, fields: Record<string, DtoField>, description?: string): DtoMessage;
-/** Field-collection source a DTO can project from: a DB table or a third-party method message. */
-export type DtoFieldSource = TableSchema | ThirdMethodSchema;
-/** Project fields from a field-collection source (table or third-party method
- *  message) and wrap them as DTO fields (aligned with dto.from). */
+/** Field-collection source a DTO can project from: a DB table, a third-party
+ *  method message, or an entity (which may carry aggregate fields). */
+export type DtoFieldSource = TableSchema | ThirdMethodSchema | EntitySchema;
+/** Project fields from a field-collection source (table, third-party method
+ *  message or entity) and wrap them as DTO fields (aligned with dto.from). */
 export declare function from(source: DtoFieldSource, fields: Field[]): Record<string, DtoField>;

package/dist/dto.js

@@ -174,16 +174,17 @@ function ownsField(source, field) {
         return Object.values(source.fields).includes(field);
     return Object.values(source.columns).includes(field);
 }
-/** Project fields from a field-collection source (table or third-party method
- *  message) and wrap them as DTO fields (aligned with dto.from). */
+/** Project fields from a field-collection source (table, third-party method
+ *  message or entity) and wrap them as DTO fields (aligned with dto.from). */
 export function from(source, fields) {
     const out = {};
     for (const field of fields) {
         if (!ownsField(source, field)) {
             throw new Error(`dto.from(${source.name}): field ${field.name} does not belong to this ${source.type}`);
         }
-        // DB columns map to camelCase interface names (mer_id → merId); wire-format
-        // names are protocol names themselves and stay untouched.
+        // DB columns map to camelCase interface names (mer_id → merId); aggregate
+        // field names are already camel and pass through; wire-format names are
+        // protocol names themselves and stay untouched.
         out[isThirdMethod(source) ? field.name : toCamelCase(field.name)] = dtoField(field);
     }
     return out;

package/dist/entity.d.ts

@@ -0,0 +1,29 @@
+import type { Field, SchemaBase } from './dsl.js';
+import type { FrontAppSchema, ProjectApiSchema } from './project.js';
+/** A row object: a set of database columns. Columns may come from one table
+ *  (write args of insert/update/upsert) or span tables through the main
+ *  table's foreign keys (read results of find/get) — where the columns come
+ *  from is the responsibility of the consuming position, not of this schema.
+ *  Storage is entity_schema/{api.name}/{app.name}/entity/{table}.entity.ts:
+ *  one file per table (the main table), any number of entities per file.
+ *  "Row" is only a naming convention for read-shaped entities
+ *  (OrderListRow, OrderDetailRow) — they are all defineEntity declarations. */
+export interface EntitySchema extends SchemaBase {
+    type: 'entity';
+    /** The backend api module this entity belongs to (shared instance from
+     *  project.config.ts apis). Entities are always backend-side. */
+    api: ProjectApiSchema;
+    /** The frontend app this entity belongs to (shared instance from project.config). */
+    app: FrontAppSchema;
+    /** The columns of this row object: main-table columns, external reference
+     *  columns, and — for aggregate result entities — aggField columns
+     *  (count/sum/avg outputs). */
+    columns: Field[];
+}
+export declare function defineEntity(options: {
+    name: string;
+    api: ProjectApiSchema;
+    app: FrontAppSchema;
+    columns: Field[];
+    description?: string;
+}): EntitySchema;

package/dist/entity.js

@@ -0,0 +1,13 @@
+export function defineEntity(options) {
+    if (!options.api.apps.includes(options.app)) {
+        throw new Error(`entity ${options.name}: api '${options.api.name}' does not serve app '${options.app.name}'`);
+    }
+    return {
+        type: 'entity',
+        name: options.name,
+        description: options.description,
+        api: options.api,
+        app: options.app,
+        columns: options.columns,
+    };
+}

package/dist/exception.d.ts

@@ -3,12 +3,18 @@ import type { ImportBase } from './import-base.js';
 /** Describes an exception a method can throw. */
 export interface ExceptionSchema extends SchemaBase, Omit<ImportBase, 'type'> {
     type: 'exception';
-    /** Whether the caller may safely retry after catching this exception. */
-    retryable: boolean;
 }
 export declare function defineException(options: {
     name: string;
     from: string;
-    retryable: boolean;
     description?: string;
 }): ExceptionSchema;
+/** Timeout or unrecoverable I/O failure */
+export declare const IOException: ExceptionSchema;
+/** Business error code carried by the exception*/
+export declare const CodeException: ExceptionSchema;
+/** Business rule violation (maps to 422) */
+export declare const BusinessException: ExceptionSchema;
+/** Anything else — unexpected, carries no business semantics. Rendered as a
+ *  plain Error / system exception, no dedicated runtime class. */
+export declare const UnexpectedException: ExceptionSchema;

package/dist/exception.js

@@ -3,7 +3,31 @@ export function defineException(options) {
         type: 'exception',
         name: options.name,
         from: options.from,
-        retryable: options.retryable,
         description: options.description,
     };
 }
+/** Timeout or unrecoverable I/O failure */
+export const IOException = defineException({
+    name: 'IOException',
+    from: '@pylonts/core',
+    description: 'Network timeout or unrecoverable error',
+});
+/** Business error code carried by the exception*/
+export const CodeException = defineException({
+    name: 'CodeException',
+    from: '@pylonts/core',
+    description: 'Business error code',
+});
+/** Business rule violation (maps to 422) */
+export const BusinessException = defineException({
+    name: 'BusinessException',
+    from: '@pylonts/core',
+    description: 'Business rule violation',
+});
+/** Anything else — unexpected, carries no business semantics. Rendered as a
+ *  plain Error / system exception, no dedicated runtime class. */
+export const UnexpectedException = defineException({
+    name: 'UnexpectedException',
+    from: '',
+    description: 'Unexpected error',
+});