@pylonts/dsl 1.1.5 → 1.1.6

package/src/dao.ts

@@ -1,13 +1,172 @@
-import { SchemaBase } from './dsl.js';
-import { FrontAppSchema } from './project.js';
-
-/** A data-access layer bound to exactly one frontend app. */
-export interface DaoSchema extends SchemaBase {
-  type: 'dao';
-  /** The frontend app this DAO belongs to (shared instance from project.config). */
-  app: FrontAppSchema;
-}
-
-export function defineDao(name: string, app: FrontAppSchema, description?: string): DaoSchema {
-  return { name, type: 'dao', app, description };
-}
+import { SchemaBase, Field, Operator } from './dsl.js';
+import { FrontAppSchema } from './project.js';
+import type { DtoMessage } from './dto.js';
+import { TableSchema } from './db.js';
+
+/** A data-access layer bound to exactly one frontend app. */
+export interface DaoSchema extends SchemaBase {
+  type: 'dao';
+  /** The frontend app this DAO belongs to (shared instance from project.config). */
+  app: FrontAppSchema;
+  /** The table this DAO operates on (single-table atomicity). */
+  table: TableSchema;
+  /** Methods keyed by name — the map key is written back as the method name. */
+  methods: Record<string, DaoMethodSchema>;
+}
+
+/** Method input for defineDao: name is written back from the methods map key. */
+export type DaoMethodDef =
+  | Omit<FindSchema, 'schema' | 'name'>
+  | Omit<GetSchema, 'schema' | 'name'>
+  | Omit<InsertSchema, 'schema' | 'name'>
+  | Omit<UpdateSchema, 'schema' | 'name'>
+  | Omit<DeleteSchema, 'schema' | 'name'>
+  | Omit<AggregateSchema, 'schema' | 'name'>;
+
+export function defineDao(options: {
+  name: string;
+  app: FrontAppSchema;
+  table: TableSchema;
+  methods: Record<string, DaoMethodDef>;
+  description?: string;
+}): DaoSchema {
+  const schema: DaoSchema = {
+    type: 'dao',
+    name: options.name,
+    description: options.description,
+    app: options.app,
+    table: options.table,
+    methods: {},
+  };
+  for (const key of Object.keys(options.methods)) {
+    const method = options.methods[key] as DaoMethodDef;
+    // 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 } as DaoMethodSchema;
+  }
+  return schema;
+}
+
+// DAO method kinds. Signature only: name + params + result. No logic —
+// complex SQL goes into description (text), never into schema.
+
+/** One AND-combined criterion: a column plus its comparison operator. */
+export interface QueryField {
+  /** Column to compare. */
+  field: Field;
+  /** Comparison operator; defaults to 'eq'. */
+  op?: Operator;
+}
+
+/** Query criteria for find methods. */
+export interface QuerySchema extends SchemaBase {
+  type: 'query';
+  /** Criteria; all fields are AND-combined. */
+  fields: QueryField[];
+}
+
+/** Sort specification for find results. */
+export interface OrderBySchema {
+  /** Column to sort by. */
+  column: Field;
+  /** Sort direction. */
+  sort: 'asc' | 'desc';
+}
+
+/** Query rows by criteria; returns a list of row objects. */
+export interface FindSchema extends SchemaBase {
+  type: 'find';
+  schema: DaoSchema;
+  /** Query criteria; omit = all rows. */
+  args?: QuerySchema;
+  /** Pagination marker: 'page' (page/pageSize) or 'limit' (position/limit).
+   *  Only presence matters — parameter shapes are a generator convention. */
+  mode?: 'page' | 'limit';
+  /** Result sort; omit = no explicit order. */
+  orderBy?: OrderBySchema | OrderBySchema[];
+  /** Row type of the result list. */
+  results: EntitySchema;
+}
+
+/** Fetch a single row by primary key. Composite PK is not supported. */
+export interface GetSchema extends SchemaBase {
+  type: 'get';
+  schema: DaoSchema;
+  /** Single PK scalar value. */
+  args: Field;
+  /** Row type. Get may miss the row: the generated signature returns Entity | null. */
+  results: EntitySchema;
+}
+
+/** Insert one row; returns number (insert id). */
+export interface InsertSchema extends SchemaBase {
+  type: 'insert';
+  schema: DaoSchema;
+  /** Row object. */
+  args: EntitySchema;
+}
+
+/** Update one row; returns number (affected rows). The where key is derived
+ *  from the PK columns inside args. */
+export interface UpdateSchema extends SchemaBase {
+  type: 'update';
+  schema: DaoSchema;
+  /** Row object containing the PK columns plus the columns to set. */
+  args: EntitySchema;
+  /** Additional criteria beyond the derived PK (AND-combined). */
+  where?: QuerySchema;
+}
+
+/** Delete one row by primary key; returns number (affected rows).
+ *  Composite PK is not supported. */
+export interface DeleteSchema extends SchemaBase {
+  type: 'delete';
+  schema: DaoSchema;
+  /** Single PK scalar value. */
+  args: Field;
+}
+
+export type DaoMethodSchema =
+  | FindSchema
+  | GetSchema
+  | InsertSchema
+  | UpdateSchema
+  | DeleteSchema
+  | AggregateSchema;
+
+/** Aggregate expression result for aggregate queries. */
+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' };
+  },
+};
+
+/** Aggregate query (count/sum/avg): returns computed scalar values. */
+export interface AggregateSchema extends SchemaBase {
+  type: 'aggregate';
+  schema: DaoSchema;
+  /** Criteria, same shape as find. */
+  args?: QuerySchema;
+  /** Computed results: key = result field name. */
+  results: Record<string, ComputeExpr>;
+}
+
+/** A database entity backed by a table. */
+export interface EntitySchema extends SchemaBase {
+  type: 'entity';
+  /** The table columns of this entity. */
+  columns: Field[];
+}

package/src/db.ts

@@ -1,182 +1,187 @@
-// 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;
+  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}`,
+      );
+    }
+    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/dsl.ts

@@ -143,6 +143,21 @@ 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>;
+}
+
 export type Field =
   | StringField
   | TextField
@@ -155,7 +170,9 @@ export type Field =
   | TimeField
   | DateTimeField
   | EnumField
-  | JsonField;
+  | JsonField
+  | ArrayField
+  | ObjectField;
 
 // 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,6 +223,14 @@ 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 };