@pylonts/dsl 1.0.5 → 1.1.1

package/src/db.ts

@@ -0,0 +1,142 @@
+// 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;
+  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>;
+  /** 引用的实体短语（词典条目）：本表归属的实体；关联表等多实体场景不需要 */
+  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`);
+    }
+    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.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);
+  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;
+  }
+  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];
+    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];
+    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)}`,
+        );
+      }
+    }
+  }
+  return table;
+}

package/src/dictionary.ts

@@ -1,20 +1,46 @@
-import { SchemaBase } from './dsl';
-
-// Dictionary definitions: vocabulary shared across the team — what a term
-// means and what it is called.
-
-/** A vocabulary entry. */
-export interface DictionaryEntry extends SchemaBase {
-  /** Display label (Chinese) for the term. */
-  label?: string;
-}
-
-/**
- * Explains a phrase — the returned entry IS the phrase. `name` is the phrase
- * itself (column-name stem, e.g. mer / bd / amt), not a full entity name;
- * label/description explain what it means. Convention: short phrase, not long
- * name.
- */
-export function definePhrase(extra: DictionaryEntry): DictionaryEntry {
-  return extra;
+import { SchemaBase } from './dsl.js';
+
+// Dictionary definitions: vocabulary shared across the team — what a term
+// means and what it is called.
+
+/** Kind of a dictionary entry: which naming rule the phrase participates in. */
+export enum DictionaryEntryType {
+  Entity = 'entity',
+  Business = 'business',
+}
+
+/** A vocabulary entry. */
+export interface DictionaryEntry extends SchemaBase {
+  /**
+   * Entry kind. Entity phrases (abbreviation of an entity, e.g. mer) must be
+   * the FIRST segment of a field name; business phrases (attribute of an
+   * entity, e.g. rate) must be the LAST segment.
+   */
+  type: DictionaryEntryType;
+  /** Display label (Chinese) for the term. */
+  label?: string;
+}
+
+/** An entity phrase entry — type narrowed to Entity. */
+export interface EntityPhrase extends DictionaryEntry {
+  type: DictionaryEntryType.Entity;
+}
+
+/**
+ * Explains an entity phrase — the returned entry IS the phrase. `name` is the
+ * phrase itself (column-name stem, e.g. mer / bd), not a full entity name;
+ * label/description explain what it means. Convention: short phrase, not long
+ * name. Entity phrases appear as the first segment of a field name (mer_id).
+ */
+export function defineEntityPhrase(extra: Omit<DictionaryEntry, 'type'>): EntityPhrase {
+  return { type: DictionaryEntryType.Entity, ...extra };
+}
+
+/**
+ * Explains a business phrase (an attribute of an entity) — the returned entry
+ * IS the phrase. `name` is the phrase itself (column-name stem, e.g. amt /
+ * rate). Business phrases appear as the last segment of a field name (bd_rate).
+ */
+export function defineBusinessPhrase(extra: Omit<DictionaryEntry, 'type'>): DictionaryEntry {
+  return { type: DictionaryEntryType.Business, ...extra };
 }

package/src/dsl.ts

@@ -1,282 +1,183 @@
-// DSL field type definitions.
-// Shape: { type: <type name>, <extension fields> }
-
-import type { DictionaryEntry } from './dictionary';
-
-export interface SchemaBase {
-  name: string;
-  description?: string;
-}
-
-/** Field collection schemas (DB table vs DTO message); `type` is the discriminator */
-export interface CollectionSchemaBase extends SchemaBase {
-  type: string;
-}
-
-export interface BaseField {
-  name: string;
-  /** 显示名称（中文标签） */
-  label?: string;
-  /** 字段描述 */
-  description?: string;
-  /** 业务语义码（如 'merchant_name'），驱动 mock 生成等下游消费 */
-  semantic?: string;
-  optional?: boolean;
-  readOnly?: boolean;
-  default?: string;
-  /** 所属 schema（db 或 dto） */
-  schema?: CollectionSchemaBase;
-}
-
-interface StringField extends BaseField {
-  type: 'string';
-  jsType: 'string';
-  minLength?: number;
-  maxLength?: number;
-}
-
-interface TextField extends BaseField {
-  type: 'text';
-  jsType: 'string';
-}
-
-interface IntField extends BaseField {
-  type: 'integer';
-  jsType: 'number';
-  min?: number;
-  max?: number;
-}
-
-interface BigintField extends BaseField {
-  type: 'bigint';
-  jsType: 'string';
-  // Value is transported as string to keep precision beyond 2^53.
-}
-
-interface DecimalField extends BaseField {
-  type: 'decimal';
-  jsType: 'string';
-  precision: number;
-  scale: number;
-  // Value is transported as string to avoid binary float error.
-}
-
-interface BooleanField extends BaseField {
-  type: 'boolean';
-  jsType: 'boolean';
-}
-
-interface DateField extends BaseField {
-  type: 'date';
-  jsType: 'Date';
-}
-
-interface TimeField extends BaseField {
-  type: 'time';
-  jsType: 'string';
-}
-
-interface DateTimeField extends BaseField {
-  type: 'datetime';
-  jsType: 'Date';
-}
-
-export interface EnumValue {
-  value: string | number;
-  symbol: string;
-  label: string;
-}
-
-/** Shared enum definition. Pure value object, safe to reference from multiple fields/tables. */
-export interface EnumDef {
-  /** JS 定义名称，如 MerchantStatus */
-  jsName: string;
-  valueType: 'string' | 'integer';
-  values: EnumValue[];
-}
-
-export function defineEnum(
-  jsName: string,
-  valueType: 'string' | 'integer',
-  values: EnumValue[],
-): EnumDef {
-  return { jsName, valueType, values };
-}
-
-export interface EnumField extends BaseField {
-  type: 'enum';
-  jsType: 'string' | 'number';
-  /** Reference to a shared enum definition (see defineEnum). */
-  enum: EnumDef;
-}
-
-interface JsonField extends BaseField {
-  type: 'json';
-  jsType: 'object';
-}
-
-export type Field =
-  | StringField
-  | TextField
-  | IntField
-  | BigintField
-  | DecimalField
-  | BooleanField
-  | DateField
-  | TimeField
-  | DateTimeField
-  | EnumField
-  | JsonField;
-
-export type Index = {
-  name?: string;
-  fields: Field | Field[];
-  unique?: boolean;
-};
-
-export type ForeignKey = {
-  fields: Field | Field[];
-  references: Field | Field[];
-};
-
-export interface TableSchemaOptions {
-  description?: string;
-  paginated?: boolean;
-  actor?: boolean;
-  generator?: string;
-  autoIncrement?: Field;
-  primaryKey?: Field | Field[];
-  indexes?: Index[];
-  foreignKeys?: Record<string, ForeignKey>;
-  /** 引用的实体短语（词典条目）：本表归属的实体；关联表等多实体场景不需要 */
-  phrase?: DictionaryEntry;
-  fields: Record<string, Field>;
-}
-
-export class TableSchema implements CollectionSchemaBase {
-  type = 'table';
-  name: string;
-  description?: string;
-  /** 分页 */
-  paginated?: boolean;
-  /** 系统操作者（如小程序为 C 端用户，管理端为运营） */
-  actor?: boolean;
-  /** id 生成器 */
-  generator?: string;
-  /** 自增主键字段 */
-  autoIncrement?: Field;
-  primaryKey?: Field | Field[];
-  indexes?: Index[];
-  /** 外键，引用其他表的字段 */
-  foreignKeys?: Record<string, ForeignKey>;
-  /** 引用的实体短语（词典条目）：本表归属的实体；关联表等多实体场景不需要 */
-  phrase?: DictionaryEntry;
-  fields: Record<string, Field>;
-
-  constructor(name: string, options: TableSchemaOptions) {
-    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.phrase = options.phrase;
-    this.fields = options.fields;
-  }
-
-  /** 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;
-  }
-}
-
-// Field builders: type and jsType are fixed, pass extra properties only.
-// The field name is written back from the map key later (see defineTable).
-
-type FieldExtras<T extends Field> = Omit<T, 'name' | 'type' | 'jsType'>;
-
-export function stringField(extra: FieldExtras<StringField> = {}): StringField {
-  return { name: '', type: 'string', jsType: 'string', ...extra };
-}
-
-export function textField(extra: FieldExtras<TextField> = {}): TextField {
-  return { name: '', type: 'text', jsType: 'string', ...extra };
-}
-
-export function intField(extra: FieldExtras<IntField> = {}): IntField {
-  return { name: '', type: 'integer', jsType: 'number', ...extra };
-}
-
-export function bigintField(extra: FieldExtras<BigintField> = {}): BigintField {
-  return { name: '', type: 'bigint', jsType: 'string', ...extra };
-}
-
-export function decimalField(extra: FieldExtras<DecimalField>): DecimalField {
-  return { name: '', type: 'decimal', jsType: 'string', ...extra };
-}
-
-export function booleanField(extra: FieldExtras<BooleanField> = {}): BooleanField {
-  return { name: '', type: 'boolean', jsType: 'boolean', ...extra };
-}
-
-export function dateField(extra: FieldExtras<DateField> = {}): DateField {
-  return { name: '', type: 'date', jsType: 'Date', ...extra };
-}
-
-export function timeField(extra: FieldExtras<TimeField> = {}): TimeField {
-  return { name: '', type: 'time', jsType: 'string', ...extra };
-}
-
-export function datetimeField(extra: FieldExtras<DateTimeField> = {}): DateTimeField {
-  return { name: '', type: 'datetime', jsType: 'Date', ...extra };
-}
-
-export function jsonField(extra: FieldExtras<JsonField> = {}): JsonField {
-  return { name: '', type: 'json', 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 };
-}
-
-export function defineTable(name: string, schema: TableSchemaOptions): TableSchema {
-  const table = new TableSchema(name, schema);
-  for (const key of Object.keys(table.fields)) {
-    const field = table.fields[key];
-    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.fields)) {
-    table.fields[key].name = key;
-    table.fields[key].schema = table;
-  }
-  for (const [fkName, fk] of Object.entries(table.foreignKeys ?? {})) {
-    const refs = Array.isArray(fk.references) ? fk.references : [fk.references];
-    const fields = Array.isArray(fk.fields) ? fk.fields : [fk.fields];
-    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}`,
-        );
-      }
-    }
-  }
-  return table;
+// DSL field type definitions.
+// Shape: { type: <type name>, <extension fields> }
+
+import type { DictionaryEntry } from './dictionary.js';
+import type { MockDescriptor } from './mock.js';
+
+/** Field query comparison operators (search field semantics). */
+export type Operator = 'eq' | 'gt' | 'gte' | 'lt' | 'lte' | 'like' | 'ne';
+
+export interface SchemaBase {
+  name: string;
+  description?: string;
+}
+
+/** Field collection schemas (DB table vs DTO message); `type` is the discriminator */
+export interface CollectionSchemaBase extends SchemaBase {
+  type: string;
+}
+
+export interface BaseField {
+  name: string;
+  /** 显示名称（中文标签） */
+  label?: string;
+  /** 字段描述 */
+  description?: string;
+  optional?: boolean;
+  readOnly?: boolean;
+  default?: string;
+  /** 所属 schema（db 或 dto） */
+  schema?: CollectionSchemaBase;
+  /** Pure-data mock descriptor for test data generation */
+  mock?: MockDescriptor;
+}
+
+interface StringField extends BaseField {
+  type: 'string';
+  jsType: 'string';
+  minLength?: number;
+  maxLength?: number;
+}
+
+interface TextField extends BaseField {
+  type: 'text';
+  jsType: 'string';
+}
+
+interface IntField extends BaseField {
+  type: 'integer';
+  jsType: 'number';
+  min?: number;
+  max?: number;
+}
+
+interface BigintField extends BaseField {
+  type: 'bigint';
+  jsType: 'string';
+  // Value is transported as string to keep precision beyond 2^53.
+}
+
+interface DecimalField extends BaseField {
+  type: 'decimal';
+  jsType: 'string';
+  precision: number;
+  scale: number;
+  // Value is transported as string to avoid binary float error.
+}
+
+interface BooleanField extends BaseField {
+  type: 'boolean';
+  jsType: 'boolean';
+}
+
+interface DateField extends BaseField {
+  type: 'date';
+  jsType: 'Date';
+}
+
+interface TimeField extends BaseField {
+  type: 'time';
+  jsType: 'string';
+}
+
+interface DateTimeField extends BaseField {
+  type: 'datetime';
+  jsType: 'Date';
+}
+
+export interface EnumValue {
+  value: string | number;
+  symbol: string;
+  label: string;
+}
+
+/** Shared enum definition. Pure value object, safe to reference from multiple fields/tables. */
+export interface EnumDef {
+  /** JS 定义名称，如 MerchantStatus */
+  jsName: string;
+  valueType: 'string' | 'integer';
+  values: EnumValue[];
+}
+
+export function defineEnum(
+  jsName: string,
+  valueType: 'string' | 'integer',
+  values: EnumValue[],
+): EnumDef {
+  return { jsName, valueType, values };
+}
+
+export interface EnumField extends BaseField {
+  type: 'enum';
+  jsType: 'string' | 'number';
+  /** Reference to a shared enum definition (see defineEnum). */
+  enum: EnumDef;
+}
+
+interface JsonField extends BaseField {
+  type: 'json';
+  jsType: 'object';
+}
+
+export type Field =
+  | StringField
+  | TextField
+  | IntField
+  | BigintField
+  | DecimalField
+  | BooleanField
+  | DateField
+  | TimeField
+  | DateTimeField
+  | EnumField
+  | JsonField;
+
+// Field builders: type and jsType are fixed, pass extra properties only.
+// The field name is written back from the map key later (see defineTable).
+
+type FieldExtras<T extends Field> = Omit<T, 'name' | 'type' | 'jsType'>;
+
+export function stringField(extra: FieldExtras<StringField> = {}): StringField {
+  return { name: '', type: 'string', jsType: 'string', ...extra };
+}
+
+export function textField(extra: FieldExtras<TextField> = {}): TextField {
+  return { name: '', type: 'text', jsType: 'string', ...extra };
+}
+
+export function intField(extra: FieldExtras<IntField> = {}): IntField {
+  return { name: '', type: 'integer', jsType: 'number', ...extra };
+}
+
+export function bigintField(extra: FieldExtras<BigintField> = {}): BigintField {
+  return { name: '', type: 'bigint', jsType: 'string', ...extra };
+}
+
+export function decimalField(extra: FieldExtras<DecimalField>): DecimalField {
+  return { name: '', type: 'decimal', jsType: 'string', ...extra };
+}
+
+export function booleanField(extra: FieldExtras<BooleanField> = {}): BooleanField {
+  return { name: '', type: 'boolean', jsType: 'boolean', ...extra };
+}
+
+export function dateField(extra: FieldExtras<DateField> = {}): DateField {
+  return { name: '', type: 'date', jsType: 'Date', ...extra };
+}
+
+export function timeField(extra: FieldExtras<TimeField> = {}): TimeField {
+  return { name: '', type: 'time', jsType: 'string', ...extra };
+}
+
+export function datetimeField(extra: FieldExtras<DateTimeField> = {}): DateTimeField {
+  return { name: '', type: 'datetime', jsType: 'Date', ...extra };
+}
+
+export function jsonField(extra: FieldExtras<JsonField> = {}): JsonField {
+  return { name: '', type: 'json', 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 };
 }