@pylonts/dsl 1.1.4 → 1.1.5

package/docs/table.md

@@ -1,136 +1,136 @@
-# 定义表 (TableSchema)
-
-## 字段类型
-
-| 构建器 | 类型 | jsType | MySQL 列 | 备注 |
-|---|---|---|---|---|
-| `stringField` | string | string | VARCHAR | 必填 `maxLength` |
-| `textField` | text | string | TEXT | |
-| `intField` | integer | number | INT | |
-| `bigintField` | bigint | string | BIGINT | 传输层走 string 保精度 |
-| `decimalField` | decimal | string | DECIMAL | 必填 `precision` / `scale`，传输层走 string 避免浮点误差 |
-| `booleanField` | boolean | boolean | TINYINT(1) | |
-| `dateField` | date | Date | DATE | |
-| `timeField` | time | string | TIME | |
-| `datetimeField` | datetime | Date | DATETIME | |
-| `enumField` | enum | string / number | VARCHAR(20) / TINYINT | 引用共享枚举定义，见 [enum.md](./enum.md) |
-| `jsonField` | json | object | JSON | |
-
-通用扩展属性（构建器参数）：`label`（中文标签）、`description`、`optional`、`readOnly`、`default`。
-
-**`optional` 默认语义（MySQL 惯例）**：不写 `optional` 或写 `optional: true` → 列可空，DDL 不渲染 `NOT NULL`；写 `optional: false` → 列必填（`NOT NULL`）。业务上必填的列必须显式声明。
-
-## 定义表
-
-```ts
-import { bigintField, defineTable, decimalField, stringField } from '@pylonts/dsl';
-
-const id = bigintField({ readOnly: true, label: '主键' });
-
-export const order = defineTable('order', {
-  description: '订单',
-  autoIncrement: id,
-  columns: {
-    id,
-    order_no: stringField({ label: '订单号', maxLength: 32, optional: false }),
-    amount: decimalField({ precision: 18, scale: 2, label: '金额', optional: false }),
-  },
-  primaryKey: id,
-});
-```
-
-- 字段名从 map key 反写，`columns` 里的 key 就是列名。
-- 字段实例不可跨表复用（复用同一字段实例会抛错），枚举除外。
-
-## 主键生成策略
-
-`autoIncrement` 与 `generator` 互斥，二者选一：
-
-| 属性 | 含义 | 例子 |
-|---|---|---|
-| `autoIncrement` | 引用自增主键字段，数据库负责生成值（MySQL `AUTO_INCREMENT`）。设了该属性的字段在 DTO 中自动标记为 optional（写入时不需要传） | `autoIncrement: id` |
-| `generator` | 主键由业务侧生成（非数据库自增），告诉下游工具用哪个 ID 生成器 | `generator: 'snowflake'` |
-
-```ts
-// 数据库自增主键
-export const t1 = defineTable('t1', {
-  autoIncrement: id,
-  columns: { id: bigintField({ readOnly: true, label: '主键' }) },
-  primaryKey: id,
-});
-
-// 业务生成主键（snowflake）
-export const t2 = defineTable('t2', {
-  generator: 'snowflake',
-  columns: { id: bigintField({ readOnly: true, label: '主键' }) },
-  primaryKey: id,
-});
-```
-
-## 索引
-
-```ts
-indexes: [
-  { name: 'uk_uuid', columns: c_uuid, unique: true },
-  { columns: [c_enum, c_date] },   // 名字缺省时 = 字段名 join '_'
-],
-```
-
-## 外键与短语检查链
-
-短语统一定义在 `schema/_dictionary.ts`（见 [dictionary.md](./dictionary.md)），表文件从那里 import：
-
-```ts
-// schema/_dictionary.ts
-import { defineEntityPhrase } from '@pylonts/dsl';
-
-export const bd = defineEntityPhrase({ name: 'bd', label: 'BD推广员', description: '线下拓展商户的推广人员' });
-```
-
-```ts
-// schema/bd.table.ts
-import { bigintField, defineTable } from '@pylonts/dsl';
-import { bd as bdPhrase } from './_dictionary';
-
-const bdId = bigintField({ readOnly: true, label: 'BD ID' });
-
-export const bd = defineTable('bd', {
-  description: 'BD',
-  phrase: bdPhrase,       // 链接词典条目：本表归属的实体
-  columns: { id: bdId },
-  primaryKey: bdId,
-});
-```
-
-```ts
-// schema/audit.table.ts
-import { bigintField, defineTable } from '@pylonts/dsl';
-import { bd } from './bd.table';
-
-const auditBdId = bigintField({ label: 'BD' });
-
-export const audit = defineTable('audit', {
-  description: '审核',
-  columns: {
-    bd_id: auditBdId,    // 列名必须 = 短语 + '_' + 被引用字段名
-  },
-  foreignKeys: {
-    fk_audit_bd: { columns: auditBdId, references: bd.columns.id },
-  },
-});
-```
-
-**规则（defineTable 时强制检查）**：外键字段名必须等于 `被引用表.phrase.name + "_" + 被引用字段名`。即引用 `bd.id` 的字段必须叫 `bd_id`——`bd` 来自词典（权威短语），`id` 是 `bd` 表主键。
-
-**短语口径**：`defineEntityPhrase`（实体短语）解释的**就是短语本身**——`name` 即短语词干（如 `mer`），不是实体全名。引用 `merchant` 实体的字段用短语 `mer`（`mer_id`），**不用长语**（`merchant_id`）。短语要短（mer / bd / amt 三字母左右），语义由 `label`/`description` 解释。`TableSchema.phrase` 只接受实体短语（`defineEntityPhrase` 产物）；业务短语（`defineBusinessPhrase`）用于字段命名后缀校验，见 [field-check.md](../../lint/docs/field-check.md)。
-
-- 被引用表未定义 `phrase` → 抛错（检查链要求每个被引用表都有短语）。
-- 命名不匹配 → 抛错并提示期望名，例如：
-  `foreign key bad: field must be named bd_id (phrase bd + id), got merchant_id`
-- 关联表不需要 `phrase`。
-
-> **外键是逻辑作用**：`foreignKeys` 用于定义期命名强校验与关系表达，**DDL 默认不渲染物理 FOREIGN KEY 约束**（`pylonts gen sql init` 不传 `generateForeignKeys`）。数据完整性由 Service/DAO 层保证；如需物理约束，调用 `buildCreateTableSql(schema, { generateForeignKeys: true })`。
-
-## 生成 SQL
-
+# 定义表 (TableSchema)
+
+## 字段类型
+
+| 构建器 | 类型 | jsType | MySQL 列 | 备注 |
+|---|---|---|---|---|
+| `stringField` | string | string | VARCHAR | 必填 `maxLength` |
+| `textField` | text | string | TEXT | |
+| `intField` | integer | number | INT | |
+| `bigintField` | bigint | string | BIGINT | 传输层走 string 保精度 |
+| `decimalField` | decimal | string | DECIMAL | 必填 `precision` / `scale`，传输层走 string 避免浮点误差 |
+| `booleanField` | boolean | boolean | TINYINT(1) | |
+| `dateField` | date | Date | DATE | |
+| `timeField` | time | string | TIME | |
+| `datetimeField` | datetime | Date | DATETIME | |
+| `enumField` | enum | string / number | VARCHAR(20) / TINYINT | 引用共享枚举定义，见 [enum.md](./enum.md) |
+| `jsonField` | json | object | JSON | |
+
+通用扩展属性（构建器参数）：`label`（中文标签）、`description`、`optional`、`readOnly`、`default`。
+
+**`optional` 默认语义（MySQL 惯例）**：不写 `optional` 或写 `optional: true` → 列可空，DDL 不渲染 `NOT NULL`；写 `optional: false` → 列必填（`NOT NULL`）。业务上必填的列必须显式声明。
+
+## 定义表
+
+```ts
+import { bigintField, defineTable, decimalField, stringField } from '@pylonts/dsl';
+
+const id = bigintField({ readOnly: true, label: '主键' });
+
+export const order = defineTable('order', {
+  description: '订单',
+  autoIncrement: id,
+  columns: {
+    id,
+    order_no: stringField({ label: '订单号', maxLength: 32, optional: false }),
+    amount: decimalField({ precision: 18, scale: 2, label: '金额', optional: false }),
+  },
+  primaryKey: id,
+});
+```
+
+- 字段名从 map key 反写，`columns` 里的 key 就是列名。
+- 字段实例不可跨表复用（复用同一字段实例会抛错），枚举除外。
+
+## 主键生成策略
+
+`autoIncrement` 与 `generator` 互斥，二者选一：
+
+| 属性 | 含义 | 例子 |
+|---|---|---|
+| `autoIncrement` | 引用自增主键字段，数据库负责生成值（MySQL `AUTO_INCREMENT`）。设了该属性的字段在 DTO 中自动标记为 optional（写入时不需要传） | `autoIncrement: id` |
+| `generator` | 主键由业务侧生成（非数据库自增），告诉下游工具用哪个 ID 生成器 | `generator: 'snowflake'` |
+
+```ts
+// 数据库自增主键
+export const t1 = defineTable('t1', {
+  autoIncrement: id,
+  columns: { id: bigintField({ readOnly: true, label: '主键' }) },
+  primaryKey: id,
+});
+
+// 业务生成主键（snowflake）
+export const t2 = defineTable('t2', {
+  generator: 'snowflake',
+  columns: { id: bigintField({ readOnly: true, label: '主键' }) },
+  primaryKey: id,
+});
+```
+
+## 索引
+
+```ts
+indexes: [
+  { name: 'uk_uuid', columns: c_uuid, unique: true },
+  { columns: [c_enum, c_date] },   // 名字缺省时 = 字段名 join '_'
+],
+```
+
+## 外键与短语检查链
+
+短语统一定义在 `schema/_dictionary.ts`（见 [dictionary.md](./dictionary.md)），表文件从那里 import：
+
+```ts
+// schema/_dictionary.ts
+import { defineEntityPhrase } from '@pylonts/dsl';
+
+export const bd = defineEntityPhrase({ name: 'bd', label: 'BD推广员', description: '线下拓展商户的推广人员' });
+```
+
+```ts
+// schema/bd.table.ts
+import { bigintField, defineTable } from '@pylonts/dsl';
+import { bd as bdPhrase } from './_dictionary';
+
+const bdId = bigintField({ readOnly: true, label: 'BD ID' });
+
+export const bd = defineTable('bd', {
+  description: 'BD',
+  phrase: bdPhrase,       // 链接词典条目：本表归属的实体
+  columns: { id: bdId },
+  primaryKey: bdId,
+});
+```
+
+```ts
+// schema/audit.table.ts
+import { bigintField, defineTable } from '@pylonts/dsl';
+import { bd } from './bd.table';
+
+const auditBdId = bigintField({ label: 'BD' });
+
+export const audit = defineTable('audit', {
+  description: '审核',
+  columns: {
+    bd_id: auditBdId,    // 列名必须 = 短语 + '_' + 被引用字段名
+  },
+  foreignKeys: {
+    fk_audit_bd: { columns: auditBdId, references: bd.columns.id },
+  },
+});
+```
+
+**规则（defineTable 时强制检查）**：外键字段名必须等于 `被引用表.phrase.name + "_" + 被引用字段名`。即引用 `bd.id` 的字段必须叫 `bd_id`——`bd` 来自词典（权威短语），`id` 是 `bd` 表主键。
+
+**短语口径**：`defineEntityPhrase`（实体短语）解释的**就是短语本身**——`name` 即短语词干（如 `mer`），不是实体全名。引用 `merchant` 实体的字段用短语 `mer`（`mer_id`），**不用长语**（`merchant_id`）。短语要短（mer / bd / amt 三字母左右），语义由 `label`/`description` 解释。`TableSchema.phrase` 只接受实体短语（`defineEntityPhrase` 产物）；业务短语（`defineBusinessPhrase`）用于字段命名后缀校验，见 [field-check.md](../../lint/docs/field-check.md)。
+
+- 被引用表未定义 `phrase` → 抛错（检查链要求每个被引用表都有短语）。
+- 命名不匹配 → 抛错并提示期望名，例如：
+  `foreign key bad: field must be named bd_id (phrase bd + id), got merchant_id`
+- 关联表不需要 `phrase`。
+
+> **外键是逻辑作用**：`foreignKeys` 用于定义期命名强校验与关系表达，**DDL 默认不渲染物理 FOREIGN KEY 约束**（`pylonts gen sql init` 不传 `generateForeignKeys`）。数据完整性由 Service/DAO 层保证；如需物理约束，调用 `buildCreateTableSql(schema, { generateForeignKeys: true })`。
+
+## 生成 SQL
+
 见 [driver.md](./driver.md)。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pylonts/dsl",
-  "version": "1.1.4",
+  "version": "1.1.5",
   "description": "Schema definition DSL with drivers: MySQL DDL, TS enum, TypeBox schema codegen.",
   "type": "module",
   "main": "src/index.ts",

package/src/action.ts

@@ -1,11 +1,11 @@
-import { SchemaBase } from './dsl.js';
-
-/** An action a user can perform on a page (e.g. submit, approve, reject).
- *  Subclasses use `type` as the discriminator. */
-export interface ActionSchema extends SchemaBase {
-  type: string;
-}
-
-export function defineAction(name: string, description?: string): ActionSchema {
-  return { name, description, type: 'gesture' };
+import { SchemaBase } from './dsl.js';
+
+/** An action a user can perform on a page (e.g. submit, approve, reject).
+ *  Subclasses use `type` as the discriminator. */
+export interface ActionSchema extends SchemaBase {
+  type: string;
+}
+
+export function defineAction(name: string, description?: string): ActionSchema {
+  return { name, description, type: 'gesture' };
 }

package/src/asset.ts

@@ -1,63 +1,63 @@
-/**
- * defineAsset — registry for reusable project assets (utils, components, flows, pages, hooks).
- *
- * Each asset declares its name, category, import path, tags, and optional usage example.
- * CLI scans all asset declarations, supports query (by tag/category) and generate (import links).
- *
- *   // assets/utils.assets.ts
- *   import { defineAsset } from '@pylonts/dsl';
- *   export const formatAmt = defineAsset({
- *     name: 'formatAmt',
- *     category: 'util',
- *     tags: ['amount', 'format'],
- *     import: { name: 'formatAmt', from: '@/utils/amount' },
- *     example: 'formatAmt(12345) => "12,345.00"',
- *   });
- *
- *   // CLI:
- *   // pylonts gen asset list --tag form       → all form-related assets
- *   // pylonts gen asset import formatAmt      → import { formatAmt } from '@/utils/amount';
- */
-
-export type AssetCategory = 'util' | 'component' | 'flow' | 'page' | 'hook';
-
-export interface AssetImport {
-  /** Named export, e.g. 'formatAmt' */
-  name: string;
-  /** Module path, e.g. '@/utils/amount' */
-  from: string;
-}
-
-export interface AssetConfig {
-  name: string;
-  category: AssetCategory;
-  tags: string[];
-  import: AssetImport;
-  description?: string;
-  /** One-liner usage example */
-  example?: string;
-  /** Link to detailed docs */
-  see?: string;
-}
-
-export interface AssetDef {
-  name: string;
-  category: AssetCategory;
-  tags: string[];
-  import: AssetImport;
-  description?: string;
-  example?: string;
-  see?: string;
-}
-
-export function defineAsset(config: AssetConfig): AssetDef {
-  return {
-    name: config.name,
-    category: config.category,
-    tags: config.tags,
-    import: config.import,
-    description: config.description,
-    example: config.example,
-    see: config.see,
-  };
+/**
+ * defineAsset — registry for reusable project assets (utils, components, flows, pages, hooks).
+ *
+ * Each asset declares its name, category, import path, tags, and optional usage example.
+ * CLI scans all asset declarations, supports query (by tag/category) and generate (import links).
+ *
+ *   // assets/utils.assets.ts
+ *   import { defineAsset } from '@pylonts/dsl';
+ *   export const formatAmt = defineAsset({
+ *     name: 'formatAmt',
+ *     category: 'util',
+ *     tags: ['amount', 'format'],
+ *     import: { name: 'formatAmt', from: '@/utils/amount' },
+ *     example: 'formatAmt(12345) => "12,345.00"',
+ *   });
+ *
+ *   // CLI:
+ *   // pylonts gen asset list --tag form       → all form-related assets
+ *   // pylonts gen asset import formatAmt      → import { formatAmt } from '@/utils/amount';
+ */
+
+export type AssetCategory = 'util' | 'component' | 'flow' | 'page' | 'hook';
+
+export interface AssetImport {
+  /** Named export, e.g. 'formatAmt' */
+  name: string;
+  /** Module path, e.g. '@/utils/amount' */
+  from: string;
+}
+
+export interface AssetConfig {
+  name: string;
+  category: AssetCategory;
+  tags: string[];
+  import: AssetImport;
+  description?: string;
+  /** One-liner usage example */
+  example?: string;
+  /** Link to detailed docs */
+  see?: string;
+}
+
+export interface AssetDef {
+  name: string;
+  category: AssetCategory;
+  tags: string[];
+  import: AssetImport;
+  description?: string;
+  example?: string;
+  see?: string;
+}
+
+export function defineAsset(config: AssetConfig): AssetDef {
+  return {
+    name: config.name,
+    category: config.category,
+    tags: config.tags,
+    import: config.import,
+    description: config.description,
+    example: config.example,
+    see: config.see,
+  };
 }

package/src/bases.ts

@@ -1,30 +1,30 @@
-import type { DtoMessage, ImportBase, ImportRef } from './dto.js';
-
-// Named base-schema references for common protocol DTOs.
-//
-// These are ImportRef metadata (not re-exports of the actual TypeBox schemas):
-// the DSL stores { from, name } so the generator can emit the import line and
-// the identifier — the runtime schema object itself is never loaded by the DSL.
-//
-// `import { PageRequest } from '@pylonts/dsl'` therefore gives .include() an
-// already-resolved reference — no static analysis or name lookup needed.
-
-/** Paginated query request base — renders `import { PageRequest } from '@pylonts/core'` + Intersect */
-export const PageRequest: ImportBase = { from: '@pylonts/core', name: 'PageRequest' };
-
-/** Paginated list response base — renders `import { PageResult } from '@pylonts/core'` + `PageResult(<row>)` */
-export const PageResult = (row: DtoMessage): ImportRef => ({
-  from: '@pylonts/core',
-  name: 'PageResult',
-  args: [row],
-});
-
-/** Paged rows type base without generic args — renders `import type { PagedRows } from '@pylonts/core'` */
-export const PagedRows: ImportBase = { from: '@pylonts/core', name: 'PagedRows', type: true };
-
-/** Paged rows type base — renders `import { PagedRows } from '@pylonts/core'` + `PagedRows(<row>)` */
-export const PageRows = (row: DtoMessage): ImportRef => ({
-  from: '@pylonts/core',
-  name: 'PagedRows',
-  args: [row],
+import type { DtoMessage, ImportBase, ImportRef } from './dto.js';
+
+// Named base-schema references for common protocol DTOs.
+//
+// These are ImportRef metadata (not re-exports of the actual TypeBox schemas):
+// the DSL stores { from, name } so the generator can emit the import line and
+// the identifier — the runtime schema object itself is never loaded by the DSL.
+//
+// `import { PageRequest } from '@pylonts/dsl'` therefore gives .include() an
+// already-resolved reference — no static analysis or name lookup needed.
+
+/** Paginated query request base — renders `import { PageRequest } from '@pylonts/core'` + Intersect */
+export const PageRequest: ImportBase = { from: '@pylonts/core', name: 'PageRequest' };
+
+/** Paginated list response base — renders `import { PageResult } from '@pylonts/core'` + `PageResult(<row>)` */
+export const PageResult = (row: DtoMessage): ImportRef => ({
+  from: '@pylonts/core',
+  name: 'PageResult',
+  args: [row],
+});
+
+/** Paged rows type base without generic args — renders `import type { PagedRows } from '@pylonts/core'` */
+export const PagedRows: ImportBase = { from: '@pylonts/core', name: 'PagedRows', type: true };
+
+/** Paged rows type base — renders `import { PagedRows } from '@pylonts/core'` + `PagedRows(<row>)` */
+export const PageRows = (row: DtoMessage): ImportRef => ({
+  from: '@pylonts/core',
+  name: 'PagedRows',
+  args: [row],
 });

package/src/component.ts

@@ -1,22 +1,22 @@
-import type { SchemaBase } from './dsl.js';
-import type { RefSchema } from './ref.js';
-import type { ActionSchema } from './action.js';
-import type { EventDataSchema } from './event.js';
-
-/** A component event trigger declaration. */
-export interface TriggerSchema extends SchemaBase {
-  /** Data the event carries (e.g. e.detail). */
-  eventData?: EventDataSchema;
-  /** Actions that fire when the event occurs. */
-  actions?: ActionSchema[];
-}
-
-/** A UI component declaration — a virtual schema that describes props and
- *  event triggers, not a real renderable component.
- *
- *  properties: data bindings via RefSchema (or literal values).
- *  triggers: event name → TriggerSchema bindings. */
-export interface ComponentSchema extends SchemaBase {
-  properties: Record<string, RefSchema | string | number | boolean>;
-  triggers: Record<string, TriggerSchema>;
+import type { SchemaBase } from './dsl.js';
+import type { RefSchema } from './ref.js';
+import type { ActionSchema } from './action.js';
+import type { EventDataSchema } from './event.js';
+
+/** A component event trigger declaration. */
+export interface TriggerSchema extends SchemaBase {
+  /** Data the event carries (e.g. e.detail). */
+  eventData?: EventDataSchema;
+  /** Actions that fire when the event occurs. */
+  actions?: ActionSchema[];
+}
+
+/** A UI component declaration — a virtual schema that describes props and
+ *  event triggers, not a real renderable component.
+ *
+ *  properties: data bindings via RefSchema (or literal values).
+ *  triggers: event name → TriggerSchema bindings. */
+export interface ComponentSchema extends SchemaBase {
+  properties: Record<string, RefSchema | string | number | boolean>;
+  triggers: Record<string, TriggerSchema>;
 }

package/src/convert.ts

@@ -1,16 +1,16 @@
-import type { SchemaBase } from './dsl.js';
-import type { FrontAppSchema } from './project.js';
-
-/** Declares post-call result → page data field mapping.
- *  Driver generates per-item transform (e.g. .map()) before setData. */
-export interface ConvertSchema extends SchemaBase {
-  type: 'convert';
-  /** The frontend app this convert belongs to (shared instance from project.config). */
-  app: FrontAppSchema;
-  /** { targetField: sourceField } — renames or copies fields from call result. */
-  fields: Record<string, string>;
-}
-
-export function defineConvert(name: string, app: FrontAppSchema, fields: Record<string, string>): ConvertSchema {
-  return { name, type: 'convert', app, fields };
+import type { SchemaBase } from './dsl.js';
+import type { FrontAppSchema } from './project.js';
+
+/** Declares post-call result → page data field mapping.
+ *  Driver generates per-item transform (e.g. .map()) before setData. */
+export interface ConvertSchema extends SchemaBase {
+  type: 'convert';
+  /** The frontend app this convert belongs to (shared instance from project.config). */
+  app: FrontAppSchema;
+  /** { targetField: sourceField } — renames or copies fields from call result. */
+  fields: Record<string, string>;
+}
+
+export function defineConvert(name: string, app: FrontAppSchema, fields: Record<string, string>): ConvertSchema {
+  return { name, type: 'convert', app, fields };
 }