@pylonts/dsl 1.1.12 → 1.1.13

package/src/entity.ts

@@ -1,43 +1,44 @@
-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,
-  };
+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).
+   *  Unset = api-level common domain entity shared by all modules of the api. */
+  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.app && !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/expr.ts

@@ -1,65 +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' };
-  },
+// 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

@@ -1,70 +1,72 @@
-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,
-  };
+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/ — app unset = the api-level
+   *  common domain layer, stored at filter_schema/{api.name}/common/filter/. */
+  api: ProjectApiSchema;
+  /** The frontend app this filter belongs to (shared instance from project.config).
+   *  Unset = api-level common domain filter shared by all modules of the api. */
+  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.app && !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,
+  };
 }