@pylonts/dsl 1.0.0

package/dist/typebox-driver.js

@@ -0,0 +1,126 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.renderDtoMessage = renderDtoMessage;
+const dto_1 = require("./dto");
+function renderString(s) {
+    return `'${s.replace(/\\/g, '\\\\').replace(/'/g, "\\'")}'`;
+}
+function renderBasic(field, pattern, resolver) {
+    if (pattern !== undefined && field.type !== 'string') {
+        throw new Error(`pattern is only supported on string fields, got ${field.type} (${field.name})`);
+    }
+    switch (field.type) {
+        case 'string': {
+            const opts = [];
+            if (field.minLength !== undefined)
+                opts.push(`minLength: ${field.minLength}`);
+            if (field.maxLength !== undefined)
+                opts.push(`maxLength: ${field.maxLength}`);
+            if (pattern !== undefined)
+                opts.push(`pattern: ${renderString(pattern)}`);
+            return opts.length > 0 ? `Type.String({ ${opts.join(', ')} })` : 'Type.String()';
+        }
+        case 'text':
+            return 'Type.String()';
+        case 'integer': {
+            const opts = [];
+            if (field.min !== undefined)
+                opts.push(`minimum: ${field.min}`);
+            if (field.max !== undefined)
+                opts.push(`maximum: ${field.max}`);
+            return opts.length > 0 ? `Type.Integer({ ${opts.join(', ')} })` : 'Type.Integer()';
+        }
+        case 'bigint':
+        case 'decimal':
+        case 'time':
+        case 'date':
+        case 'datetime':
+            // Transmitted as string over HTTP: bigint/decimal keep full precision,
+            // date/time serialize to string.
+            return 'Type.String()';
+        case 'boolean':
+            return 'Type.Boolean()';
+        case 'json':
+            return 'Type.Unknown()';
+        case 'enum': {
+            if (!field.jsName)
+                throw new Error(`enum field ${field.name} requires jsName to render`);
+            const ref = resolver?.(field.jsName);
+            if (!ref)
+                throw new Error(`enum field ${field.name}: no import ref for ${field.jsName} — pass an EnumResolver`);
+            return `Type.Enum(${ref.name})`;
+        }
+        default:
+            // Field union is exhaustive; this branch is unreachable at runtime.
+            throw new Error(`unsupported field type: ${String(field.type)}`);
+    }
+}
+function renderObject(fields, indent, resolver) {
+    const pad = '  '.repeat(indent);
+    const entries = Object.entries(fields).map(([name, f]) => `${pad}${name}: ${renderField(f, indent, resolver)}`);
+    return `Type.Object({\n${entries.join(',\n')}\n${'  '.repeat(indent - 1)}})`;
+}
+function renderField(f, indent, resolver) {
+    const base = renderValue(f, indent, resolver);
+    return f.isOptional() ? `Type.Optional(${base})` : base;
+}
+function renderValue(f, indent, resolver) {
+    if (f instanceof dto_1.DtoArrayField) {
+        return `Type.Array(${renderField(f.items(), indent + 1, resolver)})`;
+    }
+    if (f instanceof dto_1.DtoObjectField) {
+        return renderObject(f.properties(), indent + 1, resolver);
+    }
+    // DtoField only wraps a database Field; array/object defs live in the subclasses.
+    return renderBasic(f.field, f.pattern, resolver);
+}
+function collectEnumImports(f, resolver, out) {
+    if (f instanceof dto_1.DtoArrayField) {
+        collectEnumImports(f.items(), resolver, out);
+        return;
+    }
+    if (f instanceof dto_1.DtoObjectField) {
+        for (const child of Object.values(f.properties()))
+            collectEnumImports(child, resolver, out);
+        return;
+    }
+    if (f.field.type === 'enum') {
+        if (!f.field.jsName)
+            throw new Error(`enum field ${f.field.name} requires jsName to render`);
+        const ref = resolver?.(f.field.jsName);
+        if (!ref)
+            throw new Error(`enum field ${f.field.name}: no import ref for ${f.field.jsName} — pass an EnumResolver`);
+        out.set(`${ref.from}#${ref.name}`, ref);
+    }
+}
+function renderDtoMessage(schema, options = {}) {
+    const { resolver, source } = options;
+    const imports = new Map();
+    for (const base of schema.bases ?? [])
+        imports.set(`${base.from}#${base.name}`, base);
+    for (const f of Object.values(schema.fields))
+        collectEnumImports(f, resolver, imports);
+    const header = [
+        '// AUTO-GENERATED by typebox-driver — DO NOT EDIT',
+        ...(source !== undefined ? [`// Source: ${source}`] : []),
+        "import { Type, Static } from '@sinclair/typebox';",
+        ...[...imports.values()].map((r) => `import { ${r.name} } from '${r.from}';`),
+    ];
+    const object = renderObject(schema.fields, 1, resolver);
+    const bases = schema.bases ?? [];
+    const body = bases.length > 0
+        ? `Type.Intersect([${bases.map(renderBase).join(', ')}, ${object}])`
+        : object;
+    return [
+        ...header,
+        '',
+        `export const ${schema.name} = ${body};`,
+        `export type ${schema.name} = Static<typeof ${schema.name}>;`,
+        '',
+    ].join('\n');
+}
+function renderBase(base) {
+    return base.args !== undefined && base.args.length > 0
+        ? `${base.name}(${base.args.join(', ')})`
+        : base.name;
+}

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "@pylonts/dsl",
+  "version": "1.0.0",
+  "description": "Schema definition DSL with drivers: MySQL DDL, TS enum, TypeBox schema codegen.",
+  "type": "commonjs",
+  "main": "src/index.ts",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "src"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "prepublishOnly": "npm run build",
+    "typecheck": "npx tsc --noEmit"
+  },
+  "keywords": [
+    "dsl",
+    "schema",
+    "typebox",
+    "mysql"
+  ],
+  "author": "",
+  "license": "MIT",
+  "devDependencies": {
+    "typescript": "^7.0.2"
+  }
+}

package/src/dsl.ts

@@ -0,0 +1,209 @@
+// DSL field type definitions.
+// Shape: { type: <type name>, <extension fields> }
+
+export interface SchemaBase {
+  name: string;
+  description?: string;
+}
+
+export interface BaseField {
+  name: string;
+  /** 显示名称（中文标签） */
+  label?: string;
+  /** 字段描述 */
+  description?: string;
+  optional?: boolean;
+  readOnly?: boolean;
+  default?: string;
+  /** 所属 schema（db 或 dto） */
+  schema?: SchemaBase;
+}
+
+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;
+}
+
+export interface EnumField extends BaseField {
+  type: 'enum';
+  jsType: 'string' | 'number';
+  valueType: 'string' | 'integer';
+  /** JS 定义名称，如 MerchantStatus */
+  jsName?: string;
+  values: EnumValue[];
+}
+
+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 TableSchema extends SchemaBase {
+  /** 分页 */
+  paginated?: boolean;
+  /** 系统操作者（如小程序为 C 端用户，管理端为运营） */
+  actor?: boolean;
+  /** id 生成器 */
+  generator?: string;
+  primaryKey?: Field | Field[];
+  indexes?: Index[];
+  /** 外键，引用其他表的字段 */
+  foreignKeys?: Record<string, ForeignKey>;
+  fields: Record<string, Field>;
+}
+
+// Field builders: type and jsType are fixed, pass extra properties only.
+// The field name is written back from the map key later (see buildTable).
+
+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.valueType === 'integer' ? 'number' : 'string';
+  return { name: '', type: 'enum', jsType, ...extra };
+}
+
+export function buildTable(
+  name: string,
+  schema: {
+    description?: string;
+    paginated?: boolean;
+    actor?: boolean;
+    generator?: string;
+    primaryKey?: Field | Field[];
+    indexes?: Index[];
+    foreignKeys?: Record<string, ForeignKey>;
+    fields: Record<string, Field>;
+  },
+): TableSchema {
+  const table: TableSchema = { name, ...schema };
+  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];
+    for (const ref of refs) {
+      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}`);
+    }
+  }
+  return table;
+}

package/src/dto.ts

@@ -0,0 +1,185 @@
+import { BaseField, Field, SchemaBase, TableSchema } from './dsl';
+
+// Interface (DTO) field definitions.
+// Naming convention: all DTO types and builders use the Dto prefix.
+// A DtoField stores the database Field and the API-only extras separately.
+
+export type Operator = 'eq' | 'gt' | 'gte' | 'lt' | 'lte' | 'like' | 'ne';
+
+/**
+ * Reference to an existing TypeBox base schema by its import location.
+ * Serializable metadata: the driver renders `import { name } from 'from'`
+ * and `Type.Intersect([name, ...])` — the runtime schema is never loaded by the DSL.
+ */
+export interface ImportRef {
+  /** Module specifier, e.g. '@pylonts/core' */
+  from: string;
+  /** Named export, e.g. 'PageRequest' */
+  name: string;
+  /** Generic type arguments for the base schema (same-file DTO export names), e.g. PageResult(AdvertRow) */
+  args?: string[];
+}
+
+export type DtoExtras = {
+  pattern?: string;
+  /** 联合判断是否可选，定义后优先级高于 field.optional */
+  optional?: boolean;
+  /** 查询比较操作符（query 方向字段） */
+  operator?: Operator;
+};
+
+export type DtoArrayFieldDef = BaseField & {
+  type: 'array';
+  jsType: 'array';
+  items: DtoField;
+};
+
+export type DtoObjectFieldDef = BaseField & {
+  type: 'object';
+  jsType: 'object';
+  properties: Record<string, DtoField>;
+};
+
+export class DtoField {
+  /** DTO 语义字段名（接口字段名），与 field.name（数据库列名）含义不同。
+   *  构造时未知，由 buildMessage 从 map key 反写。 */
+  name: string;
+  /** 所属 DTO 容器（buildMessage 反写） */
+  schema?: DtoMessage;
+  field: Field | DtoArrayFieldDef | DtoObjectFieldDef;
+  pattern?: string;
+  optional?: boolean;
+  operator?: Operator;
+
+  constructor(field: Field | DtoArrayFieldDef | DtoObjectFieldDef, extra: DtoExtras = {}) {
+    this.name = '';
+    this.field = field;
+    this.pattern = extra.pattern;
+    this.optional = extra.optional;
+    this.operator = extra.operator;
+  }
+
+  setPattern(value: string): this {
+    this.pattern = value;
+    return this;
+  }
+
+  setOptional(value: boolean): this {
+    this.optional = value;
+    return this;
+  }
+
+  /** 查询比较操作符（query 方向字段）。Rule B: 查询字段恒为可选 */
+  op(value: Operator): this {
+    this.operator = value;
+    this.optional = true;
+    return this;
+  }
+
+  /** optional 优先于 field.optional */
+  isOptional(): boolean {
+    if (this.optional !== undefined) return this.optional;
+    return this.field.optional ?? false;
+  }
+}
+
+export class DtoArrayField extends DtoField {
+  declare field: DtoArrayFieldDef;
+
+  items(): DtoField {
+    return this.field.items;
+  }
+}
+
+export class DtoObjectField extends DtoField {
+  declare field: DtoObjectFieldDef;
+
+  properties(): Record<string, DtoField> {
+    return this.field.properties;
+  }
+}
+
+export type DtoDirection = 'input' | 'output' | 'query' | 'pk';
+
+export interface DtoMessage extends SchemaBase {
+  /** 方向：输入或输出 */
+  direction: DtoDirection;
+  fields: Record<string, DtoField>;
+  /** TypeBox base schemas to intersect with at generation time (e.g. PageRequest) */
+  bases?: ImportRef[];
+  /** 引用已存在的 TypeBox base schema，例如 include({ from: '@pylonts/core', name: 'PageRequest' }) */
+  include(...refs: ImportRef[]): DtoMessage;
+}
+
+export function dtoField(field: Field, extra: DtoExtras = {}): DtoField {
+  return new DtoField(field, extra);
+}
+
+export function dtoArrayField(def: { items: DtoField } & Omit<BaseField, 'name'>, extra: DtoExtras = {}): DtoArrayField {
+  return new DtoArrayField({ name: '', type: 'array', jsType: 'array', ...def }, extra);
+}
+
+export function dtoObjectField(def: { properties: Record<string, DtoField> } & Omit<BaseField, 'name'>, extra: DtoExtras = {}): DtoObjectField {
+  return new DtoObjectField({ name: '', type: 'object', jsType: 'object', ...def }, extra);
+}
+
+function buildMessage(name: string, direction: DtoDirection, fields: Record<string, DtoField>, description?: string): DtoMessage {
+  const message: DtoMessage = {
+    name,
+    direction,
+    description,
+    fields,
+    bases: [],
+    include(...refs: ImportRef[]): DtoMessage {
+      this.bases!.push(...refs);
+      return this;
+    },
+  };
+  if (direction === 'query') {
+    // Rule B: query/search fields are always optional.
+    for (const field of Object.values(message.fields)) field.optional = true;
+  }
+  // Write back the DTO field name from the map key (safe: DtoField instances
+  // are created per DTO, never shared).
+  for (const key of Object.keys(message.fields)) {
+    const df = message.fields[key];
+    df.name = key;
+    df.schema = message;
+    // Custom (inline) fields are owned by this DTO: write back name + schema.
+    // Fields picked via from() share the database Field instance whose
+    // name/schema already point to the table — leave them untouched.
+    if (df.field.schema === undefined) {
+      df.field.name = key;
+      df.field.schema = message;
+    }
+  }
+  return message;
+}
+
+export function buildInput(name: string, fields: Record<string, DtoField>, description?: string): DtoMessage {
+  return buildMessage(name, 'input', fields, description);
+}
+
+export function buildOutput(name: string, fields: Record<string, DtoField>, description?: string): DtoMessage {
+  return buildMessage(name, 'output', fields, description);
+}
+
+export function buildQuery(name: string, fields: Record<string, DtoField>, description?: string): DtoMessage {
+  return buildMessage(name, 'query', fields, description);
+}
+
+export function buildPk(name: string, fields: Record<string, DtoField>, description?: string): DtoMessage {
+  return buildMessage(name, 'pk', fields, description);
+}
+
+/** Pick columns from a built table and wrap them as DTO fields (aligned with dto.from). */
+export function from(table: TableSchema, fields: Field[]): Record<string, DtoField> {
+  const out: Record<string, DtoField> = {};
+  for (const field of fields) {
+    if (field.schema !== table) {
+      throw new Error(`dto.from(${table.name}): field ${field.name} does not belong to this table`);
+    }
+    out[field.name] = dtoField(field);
+  }
+  return out;
+}

package/src/enum-driver.ts

@@ -0,0 +1,44 @@
+import { EnumField } from './dsl';
+
+// Enum driver: renders an EnumField into a standalone TypeScript enum file.
+// Shape matches the generated-enum product consumed by the TypeBox driver (Type.Enum):
+//
+//   export enum UserStatus {
+//     ACTIVE = 'ACTIVE',
+//     DISABLED = 'DISABLED',
+//   }
+//
+//   export const USER_STATUS_LABEL: Record<UserStatus, string> = {
+//     [UserStatus.ACTIVE]: '启用',
+//     [UserStatus.DISABLED]: '禁用',
+//   };
+
+function renderString(s: string): string {
+  return `'${s.replace(/\\/g, '\\\\').replace(/'/g, "\\'")}'`;
+}
+
+function renderValue(value: string | number): string {
+  return typeof value === 'number' ? String(value) : renderString(value);
+}
+
+/** 'UserStatus' → 'USER_STATUS_LABEL' (matches the label map naming convention) */
+function labelName(jsName: string): string {
+  return `${jsName.replace(/([a-z0-9])([A-Z])/g, '$1_$2').toUpperCase()}_LABEL`;
+}
+
+export function renderEnum(field: EnumField): string {
+  if (!field.jsName) throw new Error(`enum field ${field.name} requires jsName to render`);
+  const name = field.jsName;
+  const members = field.values.map((v) => `  ${v.symbol} = ${renderValue(v.value)},`);
+  const labels = field.values.map((v) => `  [${name}.${v.symbol}]: ${renderString(v.label)},`);
+  return [
+    `export enum ${name} {`,
+    ...members,
+    '}',
+    '',
+    `export const ${labelName(name)}: Record<${name}, string> = {`,
+    ...labels,
+    '};',
+    '',
+  ].join('\n');
+}

package/src/index.ts

@@ -0,0 +1,5 @@
+export * from './dsl';
+export * from './dto';
+export * from './mysql-driver';
+export * from './enum-driver';
+export * from './typebox-driver';

package/src/mysql-driver.ts

@@ -0,0 +1,60 @@
+import { Field, Index, TableSchema } from './dsl';
+
+// MySQL driver: converts a TableSchema into a CREATE TABLE statement.
+
+function columnType(field: Field): string {
+  switch (field.type) {
+    case 'string':
+      if (!field.maxLength) throw new Error(`field ${field.name} (string) requires maxLength`);
+      return `VARCHAR(${field.maxLength})`;
+    case 'text':
+      return 'TEXT';
+    case 'integer':
+      return 'INT';
+    case 'bigint':
+      return 'BIGINT';
+    case 'decimal':
+      return `DECIMAL(${field.precision}, ${field.scale})`;
+    case 'boolean':
+      return 'TINYINT(1)';
+    case 'date':
+      return 'DATE';
+    case 'time':
+      return 'TIME';
+    case 'datetime':
+      return 'DATETIME';
+    case 'enum':
+      // Enum is stored as a plain column: string -> VARCHAR(20), integer -> TINYINT.
+      return field.valueType === 'integer' ? 'TINYINT' : 'VARCHAR(20)';
+    case 'json':
+      return 'JSON';
+  }
+}
+
+function columnDef(field: Field): string {
+  const parts = [field.name, columnType(field)];
+  if (field.optional === false) parts.push('NOT NULL');
+  if (field.default !== undefined) parts.push(`DEFAULT '${field.default}'`);
+  return parts.join(' ');
+}
+
+function primaryKeyClause(schema: TableSchema): string | null {
+  if (!schema.primaryKey) return null;
+  const fields = Array.isArray(schema.primaryKey) ? schema.primaryKey : [schema.primaryKey];
+  return `PRIMARY KEY (${fields.map((f) => f.name).join(', ')})`;
+}
+
+function indexClause(index: Index): string {
+  const fields = Array.isArray(index.fields) ? index.fields : [index.fields];
+  const kind = index.unique ? 'UNIQUE KEY' : 'KEY';
+  const name = index.name ?? fields.map((f) => f.name).join('_');
+  return `${kind} ${name} (${fields.map((f) => f.name).join(', ')})`;
+}
+
+export function buildCreateTableSql(schema: TableSchema): string {
+  const lines = Object.values(schema.fields).map(columnDef);
+  const pk = primaryKeyClause(schema);
+  if (pk) lines.push(pk);
+  for (const index of schema.indexes ?? []) lines.push(indexClause(index));
+  return `CREATE TABLE \`${schema.name}\` (\n  ${lines.join(',\n  ')}\n);`;
+}