@pylonts/dsl 1.1.5 → 1.1.11

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/field-rule.ts

@@ -0,0 +1,47 @@
+import type { SchemaBase } from './dsl.js';
+
+// Field rules: the third semantic dimension of a Field. A rule is a named
+// transformation between two ends — scale (fen↔yuan), encrypt/decrypt,
+// mask/unmask. The rule owns both ends; a binding says which field plays
+// which end. Rules are unique per semantic name (checked at definition).
+
+/** One end of a field rule (e.g. 'fen' / 'yuan', 'plain' / 'cipher', 'raw' / 'masked'). */
+export interface FieldRuleEnd {
+  /** End name — written back by defineFieldRule from the ends map key. */
+  name: string;
+  description?: string;
+}
+
+/** A semantic transformation rule between two field representations. */
+export interface FieldRuleSchema extends SchemaBase {
+  type: 'fieldRule';
+  /** Rule name — the semantic uniqueness key. */
+  name: string;
+  /** The two ends of the rule, keyed by end name. */
+  ends: Record<string, FieldRuleEnd>;
+}
+
+/** One rule per semantic name. Defining the same name twice throws. */
+const ruleRegistry = new Map<string, FieldRuleSchema>();
+
+export function defineFieldRule(options: {
+  name: string;
+  ends: Record<string, Omit<FieldRuleEnd, 'name'>>;
+  description?: string;
+}): FieldRuleSchema {
+  if (ruleRegistry.has(options.name)) {
+    throw new Error(`fieldRule '${options.name}' is already defined — one rule per semantic`);
+  }
+  const ends: Record<string, FieldRuleEnd> = {};
+  for (const key of Object.keys(options.ends)) {
+    ends[key] = { name: key, description: options.ends[key].description };
+  }
+  const rule: FieldRuleSchema = {
+    type: 'fieldRule',
+    name: options.name,
+    description: options.description,
+    ends,
+  };
+  ruleRegistry.set(options.name, rule);
+  return rule;
+}

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,
+  };
+}