@pylonts/dsl 1.1.5 → 1.1.11

package/src/db.ts

@@ -1,182 +1,200 @@
-// DB table definitions.
-// Shape: { type: 'table', <extension fields> }
-
-import type { EntityPhrase } from './dictionary.js';
-import type { CollectionSchemaBase, EnumDef, Field } from './dsl.js';
-
-export type Index = {
-  name?: string;
-  columns: Field | Field[];
-  unique?: boolean;
-};
-
-export type ForeignKey = {
-  columns: Field | Field[];
-  references: Field | Field[];
-};
-
-export interface TableSchemaOptions<
-  N extends string = string,
-  C extends Record<string, Field> = Record<string, Field>,
-  E extends Record<string, EnumDef> = Record<string, EnumDef>
-> {
-  description?: string;
-  paginated: boolean;
-  actor?: boolean;
-  generator?: string;
-  autoIncrement?: Field;
-  /** 本表用于关联显示的名称字段（如 name / username）。被外键引用时，自动用该字段做 label 展示。 */
-  label?: Field;
-  primaryKey?: Field | Field[];
-  indexes?: Index[];
-  foreignKeys?: Record<string, ForeignKey>;
-  /** 引用的实体短语（词典条目）：本表归属的实体；关联表等多实体场景不需要 */
-  phrase?: EntityPhrase;
-  /** 本表引用的所有枚举定义（map，key 为枚举标识），显式声明供 gen-enums 收集 */
-  enums: E;
-  columns: C;
-}
-
-export class TableSchema<
-  N extends string = string,
-  C extends Record<string, Field> = Record<string, Field>,
-  E extends Record<string, EnumDef> = Record<string, EnumDef>
-> implements CollectionSchemaBase {
-  type = 'table';
-  name: N;
-  description?: string;
-  /** 分页 */
-  paginated: boolean;
-  /** 系统操作者（如小程序为 C 端用户，管理端为运营） */
-  actor?: boolean;
-  /** id 生成器 */
-  generator?: string;
-  /** 自增主键字段 */
-  autoIncrement?: Field;
-  primaryKey?: Field | Field[];
-  indexes?: Index[];
-  /** 外键，引用其他表的字段 */
-  foreignKeys?: Record<string, ForeignKey>;
-  /** 本表用于关联显示的名称字段（如 name / username）。被外键引用时，自动用该字段做 label 展示。 */
-  label?: Field;
-  /** 引用的实体短语（词典条目）：本表归属的实体；关联表等多实体场景不需要 */
-  phrase?: EntityPhrase;
-  /** 本表引用的所有枚举定义（map，key 为枚举标识），显式声明供 gen-enums 收集 */
-  enums: E;
-  columns: C;
-
-  constructor(name: N, options: TableSchemaOptions<N, C, E>) {
-    if (!options.enums) {
-      throw new Error(`table '${name}': enums is required — declare enums: {} when the table has no enums`);
-    }
-    if (options.paginated === undefined || options.paginated === null) {
-      throw new Error(`table '${name}': paginated is required — discuss with user whether this table needs pagination, then set paginated: true or paginated: false`);
-    }
-    this.name = name;
-    this.description = options.description;
-    this.paginated = options.paginated;
-    this.actor = options.actor;
-    this.generator = options.generator;
-    this.autoIncrement = options.autoIncrement;
-    this.primaryKey = options.primaryKey;
-    this.indexes = options.indexes;
-    this.foreignKeys = options.foreignKeys;
-    this.label = options.label;
-    this.phrase = options.phrase;
-    this.enums = options.enums;
-    this.columns = options.columns;
-  }
-
-  /** True when the field is part of this table's primary key */
-  isPk(fieldRef: Field): boolean {
-    if (this.primaryKey === undefined) return false;
-    return Array.isArray(this.primaryKey)
-      ? this.primaryKey.includes(fieldRef)
-      : this.primaryKey === fieldRef;
-  }
-}
-
-export function defineTable<
-  N extends string,
-  C extends Record<string, Field>,
-  E extends Record<string, EnumDef> = Record<string, EnumDef>
->(
-  name: N,
-  schema: TableSchemaOptions<N, C, E>,
-): TableSchema<N, C, E> {
-  const table = new TableSchema<N, C, E>(name, schema);
-  if (table.generator && table.autoIncrement) {
-    throw new Error(`table '${name}': generator and autoIncrement are mutually exclusive`);
-  }
-  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`);
-  }
-  for (const key of Object.keys(table.columns)) {
-    const field = table.columns[key] as Field;
-    if (field.schema && field.schema !== table) {
-      throw new Error(
-        `field ${key}: belongs to table ${field.schema.name}, cannot reuse in table ${table.name}`,
-      );
-    }
-  }
-  for (const key of Object.keys(table.columns)) {
-    table.columns[key].name = key;
-    table.columns[key].schema = table;
-  }
-  if (table.primaryKey) {
-    const pkFields = Array.isArray(table.primaryKey) ? table.primaryKey : [table.primaryKey];
-    const colRefs = Object.values(table.columns);
-    for (const pk of pkFields) {
-      if (!colRefs.includes(pk)) {
-        throw new Error(
-          `table '${name}': primaryKey field '${pk.name}' must be the exact same object as the corresponding column (extract it to a const and reuse)`,
-        );
-      }
-    }
-  }
-  for (const [fkName, fk] of Object.entries(table.foreignKeys ?? {})) {
-    const refs = Array.isArray(fk.references) ? fk.references : [fk.references];
-    const fields = Array.isArray(fk.columns) ? fk.columns : [fk.columns];
-    const colRefs = Object.values(table.columns);
-    for (const fkField of fields) {
-      if (!colRefs.includes(fkField)) {
-        throw new Error(
-          `foreign key ${fkName}: column '${fkField.name}' must be the exact same object as the corresponding column in the table (extract it to a const and reuse)`,
-        );
-      }
-    }
-    for (let i = 0; i < refs.length; i++) {
-      const ref = refs[i];
-      if (!ref.schema) throw new Error(`foreign key ${fkName}: references field has no schema`);
-      if (ref.schema === table) throw new Error(`foreign key ${fkName}: cannot reference own table ${table.name}`);
-      const phrase = (ref.schema as TableSchema).phrase;
-      if (!phrase) throw new Error(`foreign key ${fkName}: referenced table ${ref.schema.name} has no phrase, cannot check field naming`);
-      const expected = `${phrase.name}_${ref.name}`;
-      const fkField = fields[i];
-      if (fkField.name !== expected) {
-        throw new Error(
-          `foreign key ${fkName}: field must be named ${expected} (phrase ${phrase.name} + ${ref.name}), got ${fkField.name}`,
-        );
-      }
-    }
-  }
-  for (const [idxKey, index] of Object.entries(table.indexes ?? {})) {
-    const cols = Array.isArray(index.columns) ? index.columns : [index.columns];
-    const colRefs = Object.values(table.columns);
-    for (const col of cols) {
-      if (typeof col !== 'object' || col === null || typeof (col as Field).type !== 'string') {
-        const idxName = index.name ?? idxKey;
-        throw new Error(
-          `index ${idxName}: columns must be Field instances (stringField()/intField()/...), got ${JSON.stringify(col)}`,
-        );
-      }
-      if (!colRefs.includes(col)) {
-        const idxName = index.name ?? idxKey;
-        throw new Error(
-          `index ${idxName}: column '${col.name}' must be the exact same object as the corresponding column in the table (extract it to a const and reuse)`,
-        );
-      }
-    }
-  }
-  return table;
+// DB table definitions.
+// Shape: { type: 'table', <extension fields> }
+
+import type { EntityPhrase } from './dictionary.js';
+import type { CollectionSchemaBase, EnumDef, Field } from './dsl.js';
+
+export type Index = {
+  name?: string;
+  columns: Field | Field[];
+  unique?: boolean;
+};
+
+export type ForeignKey = {
+  columns: Field | Field[];
+  references: Field | Field[];
+};
+
+export interface TableSchemaOptions<
+  N extends string = string,
+  C extends Record<string, Field> = Record<string, Field>,
+  E extends Record<string, EnumDef> = Record<string, EnumDef>
+> {
+  description?: string;
+  paginated: boolean;
+  actor?: boolean;
+  generator?: string;
+  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>;
+  /** 引用的实体短语（词典条目）：本表归属的实体；关联表等多实体场景不需要 */
+  phrase?: EntityPhrase;
+  /** 本表引用的所有枚举定义（map，key 为枚举标识），显式声明供 gen-enums 收集 */
+  enums: E;
+  columns: C;
+}
+
+export class TableSchema<
+  N extends string = string,
+  C extends Record<string, Field> = Record<string, Field>,
+  E extends Record<string, EnumDef> = Record<string, EnumDef>
+> implements CollectionSchemaBase {
+  type = 'table';
+  name: N;
+  description?: string;
+  /** 分页 */
+  paginated: boolean;
+  /** 系统操作者（如小程序为 C 端用户，管理端为运营） */
+  actor?: boolean;
+  /** id 生成器 */
+  generator?: string;
+  /** 自增主键字段 */
+  autoIncrement?: Field;
+  primaryKey?: Field | Field[];
+  indexes?: Index[];
+  /** 外键，引用其他表的字段 */
+  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 收集 */
+  enums: E;
+  columns: C;
+
+  constructor(name: N, options: TableSchemaOptions<N, C, E>) {
+    if (!options.enums) {
+      throw new Error(`table '${name}': enums is required — declare enums: {} when the table has no enums`);
+    }
+    if (options.paginated === undefined || options.paginated === null) {
+      throw new Error(`table '${name}': paginated is required — discuss with user whether this table needs pagination, then set paginated: true or paginated: false`);
+    }
+    this.name = name;
+    this.description = options.description;
+    this.paginated = options.paginated;
+    this.actor = options.actor;
+    this.generator = options.generator;
+    this.autoIncrement = options.autoIncrement;
+    this.primaryKey = options.primaryKey;
+    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;
+  }
+
+  /** True when the field is part of this table's primary key */
+  isPk(fieldRef: Field): boolean {
+    if (this.primaryKey === undefined) return false;
+    return Array.isArray(this.primaryKey)
+      ? this.primaryKey.includes(fieldRef)
+      : this.primaryKey === fieldRef;
+  }
+}
+
+export function defineTable<
+  N extends string,
+  C extends Record<string, Field>,
+  E extends Record<string, EnumDef> = Record<string, EnumDef>
+>(
+  name: N,
+  schema: TableSchemaOptions<N, C, E>,
+): TableSchema<N, C, E> {
+  const table = new TableSchema<N, C, E>(name, schema);
+  if (table.generator && table.autoIncrement) {
+    throw new Error(`table '${name}': generator and autoIncrement are mutually exclusive`);
+  }
+  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] as Field;
+    if (field.schema && field.schema !== table) {
+      throw new Error(
+        `field ${key}: belongs to table ${field.schema.name}, cannot reuse in table ${table.name}`,
+      );
+    }
+    if (field.type === 'array' || field.type === 'object') {
+      throw new Error(
+        `table '${name}': column '${key}' cannot be a nested ${field.type} field — wire-format nesting is not a table column`,
+      );
+    }
+  }
+  for (const key of Object.keys(table.columns)) {
+    table.columns[key].name = key;
+    table.columns[key].schema = table;
+  }
+  if (table.primaryKey) {
+    const pkFields = Array.isArray(table.primaryKey) ? table.primaryKey : [table.primaryKey];
+    const colRefs = Object.values(table.columns);
+    for (const pk of pkFields) {
+      if (!colRefs.includes(pk)) {
+        throw new Error(
+          `table '${name}': primaryKey field '${pk.name}' must be the exact same object as the corresponding column (extract it to a const and reuse)`,
+        );
+      }
+    }
+  }
+  for (const [fkName, fk] of Object.entries(table.foreignKeys ?? {})) {
+    const refs = Array.isArray(fk.references) ? fk.references : [fk.references];
+    const fields = Array.isArray(fk.columns) ? fk.columns : [fk.columns];
+    const colRefs = Object.values(table.columns);
+    for (const fkField of fields) {
+      if (!colRefs.includes(fkField)) {
+        throw new Error(
+          `foreign key ${fkName}: column '${fkField.name}' must be the exact same object as the corresponding column in the table (extract it to a const and reuse)`,
+        );
+      }
+    }
+    for (let i = 0; i < refs.length; i++) {
+      const ref = refs[i];
+      if (!ref.schema) throw new Error(`foreign key ${fkName}: references field has no schema`);
+      if (ref.schema === table) throw new Error(`foreign key ${fkName}: cannot reference own table ${table.name}`);
+      const phrase = (ref.schema as TableSchema).phrase;
+      if (!phrase) throw new Error(`foreign key ${fkName}: referenced table ${ref.schema.name} has no phrase, cannot check field naming`);
+      const expected = `${phrase.name}_${ref.name}`;
+      const fkField = fields[i];
+      if (fkField.name !== expected) {
+        throw new Error(
+          `foreign key ${fkName}: field must be named ${expected} (phrase ${phrase.name} + ${ref.name}), got ${fkField.name}`,
+        );
+      }
+    }
+  }
+  for (const [idxKey, index] of Object.entries(table.indexes ?? {})) {
+    const cols = Array.isArray(index.columns) ? index.columns : [index.columns];
+    const colRefs = Object.values(table.columns);
+    for (const col of cols) {
+      if (typeof col !== 'object' || col === null || typeof (col as Field).type !== 'string') {
+        const idxName = index.name ?? idxKey;
+        throw new Error(
+          `index ${idxName}: columns must be Field instances (stringField()/intField()/...), got ${JSON.stringify(col)}`,
+        );
+      }
+      if (!colRefs.includes(col)) {
+        const idxName = index.name ?? idxKey;
+        throw new Error(
+          `index ${idxName}: column '${col.name}' must be the exact same object as the corresponding column in the table (extract it to a const and reuse)`,
+        );
+      }
+    }
+  }
+  return table;
 }

package/src/domain-event.ts

@@ -0,0 +1,74 @@
+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 function defineDomainEvent(options: {
+  name: string;
+  fields: Record<string, DtoField>;
+  description?: string;
+}): DomainEventSchema {
+  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,
+  };
+}
+
+/**
+ * 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 function defineEventHandler(options: {
+  name: string;
+  event: string;
+  flow?: FlowSchema;
+  handler?: (payload: Record<string, unknown>) => Promise<void> | void;
+  description?: string;
+}): EventHandlerSchema {
+  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/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;
@@ -143,6 +144,32 @@ interface JsonField extends BaseField {
   jsType: 'object';
 }
 
+/** Recursive array field — wire-format nesting (third-party messages), not a table column. */
+interface ArrayField extends BaseField {
+  type: 'array';
+  jsType: 'array';
+  /** Element type: any Field, including nested array/object. */
+  items: Field;
+}
+
+/** Recursive object field — wire-format nesting (third-party messages), not a table column. */
+interface ObjectField extends BaseField {
+  type: 'object';
+  jsType: 'object';
+  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
@@ -155,7 +182,10 @@ export type Field =
   | TimeField
   | DateTimeField
   | EnumField
-  | JsonField;
+  | JsonField
+  | ArrayField
+  | 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).
@@ -206,7 +236,23 @@ export function jsonField(extra: FieldExtras<JsonField> = {}): JsonField {
   return { name: '', type: 'json', jsType: 'object', ...extra };
 }
 
+export function arrayField(extra: FieldExtras<ArrayField>): ArrayField {
+  return { name: '', type: 'array', jsType: 'array', ...extra };
+}
+
+export function objectField(extra: FieldExtras<ObjectField>): ObjectField {
+  return { name: '', type: 'object', jsType: 'object', ...extra };
+}
+
 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 };
 }