@pylonts/dsl 1.1.6 → 1.1.11

package/src/dsl.ts

@@ -4,9 +4,10 @@
 import type { DictionaryEntry } from './dictionary.js';
 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;
@@ -158,6 +159,17 @@ interface ObjectField extends BaseField {
   properties: Record<string, Field>;
 }
 
+/** 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
@@ -172,7 +184,8 @@ export type Field =
   | EnumField
   | JsonField
   | ArrayField
-  | ObjectField;
+  | ObjectField
+  | AggregateField;
 
 // Field builders: type and jsType are fixed, pass extra properties only.
 // The field name is written back from the map key later (see defineTable).
@@ -234,4 +247,12 @@ export function objectField(extra: FieldExtras<ObjectField>): ObjectField {
 export function enumField(extra: Omit<EnumField, 'name' | 'type' | 'jsType'>): EnumField {
   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: string, expr: ComputeExpr): AggregateField {
+  const jsType = expr.field === undefined || expr.field.type === 'integer' ? 'number' : 'string';
+  return { name, type: 'aggregate', jsType, expr };
 }

package/src/dto.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';
 import { toCamelCase } from '@pylonts/core';
@@ -234,8 +235,9 @@ export function buildPk(name: string, fields: Record<string, DtoField>, descript
   return message;
 }
 
-/** Field-collection source a DTO can project from: a DB table or a third-party method message. */
-export type DtoFieldSource = TableSchema | ThirdMethodSchema;
+/** 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;
 
 // Type guard instead of a plain discriminant check: TableSchema.type is declared
 // as a class property, so TS widens it to string and cannot narrow the union.
@@ -248,16 +250,17 @@ function ownsField(source: DtoFieldSource, field: Field): boolean {
   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: DtoFieldSource, fields: Field[]): Record<string, DtoField> {
   const out: Record<string, DtoField> = {};
   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/src/entity.ts

@@ -0,0 +1,43 @@
+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 function defineEntity(options: {
+  name: string;
+  api: ProjectApiSchema;
+  app: FrontAppSchema;
+  columns: Field[];
+  description?: string;
+}): EntitySchema {
+  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/src/exception.ts

@@ -8,21 +8,46 @@ 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 function defineException(options: {
   name: string;
   from: string;
-  retryable: boolean;
   description?: string;
 }): ExceptionSchema {
   return {
     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',
+});

package/src/expr.ts

@@ -0,0 +1,65 @@
+// 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.
+
+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 function col(field: Field): ValueExpr {
+  return { kind: 'col', field };
+}
+
+export function lit(value: string | number): ValueExpr {
+  return { kind: 'lit', value };
+}
+
+export function param(name: string): ValueExpr {
+  return { kind: 'param', name };
+}
+
+export function bin(op: BinOp, left: ValueExpr, right: ValueExpr): ValueExpr {
+  return { kind: 'bin', op, left, right };
+}
+
+/** Convenience builders for the common self-increment/decrement shapes. */
+export const incr = (field: Field, by: ValueExpr): SetExpr => ({ col: field, expr: bin('add', col(field), by) });
+export const decr = (field: Field, by: ValueExpr): SetExpr => ({ col: field, expr: bin('sub', col(field), by) });
+
+/** 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 const Compute = {
+  sum(field: Field): ComputeExpr {
+    return { fn: 'sum', field };
+  },
+  avg(field: Field): ComputeExpr {
+    return { fn: 'avg', field };
+  },
+  count(): ComputeExpr {
+    return { fn: 'count' };
+  },
+};

package/src/filter.ts

@@ -0,0 +1,70 @@
+import type { Field, Operator, SchemaBase } from './dsl.js';
+import type { ValueExpr } from './expr.js';
+import type { FrontAppSchema, ProjectApiSchema } from './project.js';
+
+// Filter: the single declarative model for query conditions, shared by
+// dao_schema methods and curd page lists. Conditions are AND-combined and
+// may reference any table (cross-table filters render JOINs at the usage
+// site, which owns the main table). Pagination is NOT part of a filter —
+// it stays on the dao method (mode) and the curd list config.
+
+/** 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 function defineFilter(options: {
+  name: string;
+  api: ProjectApiSchema;
+  app: FrontAppSchema;
+  conditions?: FilterCondition[];
+  keyword?: { columns: Field[] };
+  description?: string;
+}): FilterSchema {
+  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,
+  };
+}