@pylonts/dsl 1.1.4 → 1.1.6

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pylonts/dsl",
-  "version": "1.1.4",
+  "version": "1.1.6",
   "description": "Schema definition DSL with drivers: MySQL DDL, TS enum, TypeBox schema codegen.",
   "type": "module",
   "main": "src/index.ts",
@@ -24,6 +24,9 @@
   ],
   "author": "",
   "license": "MIT",
+  "dependencies": {
+    "@pylonts/core": "file:../pylon"
+  },
   "devDependencies": {
     "typescript": "^7.0.2",
     "vitest": "^4.1.10"

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/controller.ts

@@ -0,0 +1,40 @@
+import { SchemaBase } from './dsl.js';
+import { FrontAppSchema } from './project.js';
+import type { EndpointSchema } from './endpoint.js';
+
+/** A backend RPC controller. Strong constraints:
+ *  - a backend module maps 1:1 to a frontend app (they are peers);
+ *  - a controller serves exactly one frontend app — no cross-module calls. */
+export interface ControllerSchema extends SchemaBase {
+  type: 'controller';
+  /** The frontend app this controller serves (shared instance from project.config). */
+  app: FrontAppSchema;
+  /** RPC methods exposed by this controller. */
+  methods: ControllerMethodSchema[];
+}
+
+export function defineController(options: {
+  name: string;
+  app: FrontAppSchema;
+  /** Method declarations: type/schema are injected by this builder. */
+  methods: Array<Omit<ControllerMethodSchema, 'type' | 'schema'>>;
+  description?: string;
+}): ControllerSchema {
+  const schema: ControllerSchema = {
+    type: 'controller',
+    name: options.name,
+    description: options.description,
+    app: options.app,
+    methods: [],
+  };
+  schema.methods = options.methods.map((method) => ({ type: 'method', schema, ...method }));
+  return schema;
+}
+
+/** An RPC method exposed by a controller. */
+export interface ControllerMethodSchema extends SchemaBase {
+  type: 'method';
+  schema: ControllerSchema;
+  /** Shared API signature — same instance the page-side provider references. */
+  signature: EndpointSchema;
+}

package/src/convert.ts

@@ -1,16 +1,43 @@
 import type { SchemaBase } from './dsl.js';
+import type { DtoMessage } from './dto.js';
+import type { TableSchema } from './db.js';
+import type { ThirdMethodSchema } from './third-service.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. */
+// Schema-collection integration: multiple source collections combine into
+// one target collection (e.g. two entity tables into one dto, or entity
+// columns plus a dto into one third-party wire message).
+
+/** A source/target collection of a convert — dto, entity or third-party message. */
+export type ConvertSourceSchema = DtoMessage | TableSchema | ThirdMethodSchema;
+
+/** Declares a multi-source → single-target schema integration. */
 export interface ConvertSchema extends SchemaBase {
   type: 'convert';
-  /** The frontend app this convert belongs to (shared instance from project.config). */
+  /** The app (module) this convert belongs to — its artifact lands in modules/{app}/convert/. */
   app: FrontAppSchema;
-  /** { targetField: sourceField } — renames or copies fields from call result. */
-  fields: Record<string, string>;
+  /** Source schemas — one or more, mixed dimensions. */
+  sources: ConvertSourceSchema[];
+  /** Target schema — the single integrated collection. */
+  target: ConvertSourceSchema;
 }
 
-export function defineConvert(name: string, app: FrontAppSchema, fields: Record<string, string>): ConvertSchema {
-  return { name, type: 'convert', app, fields };
+export function defineConvert(options: {
+  name: string;
+  app: FrontAppSchema;
+  sources: ConvertSourceSchema[];
+  target: ConvertSourceSchema;
+  description?: string;
+}): ConvertSchema {
+  if (options.sources.length === 0) {
+    throw new Error(`convert '${options.name}': sources must not be empty`);
+  }
+  return {
+    type: 'convert',
+    name: options.name,
+    description: options.description,
+    app: options.app,
+    sources: options.sources,
+    target: options.target,
+  };
 }

package/src/curd.ts

@@ -2,6 +2,7 @@ import { SchemaBase, Field, Operator } from './dsl.js';
 import { TableSchema } from './db.js';
 import { FrontAppSchema } from './project.js';
 import { ActionSchema } from './action.js';
+import { toKebabCase } from '@pylonts/core';
 
 // Admin-only CRUD page standard: binds one entity table to a frontend admin
 // app, describing everything needed to generate the list page plus optional
@@ -15,8 +16,6 @@ export type ActionPageMode = 'modal' | 'route';
 /** One CRUD action page (add / update / detail). */
 export interface ActionPage {
   mode: ActionPageMode;
-  /** For add/update: when true, render as modal on list page; when false/undefined, render as standalone route page. */
-  modal?: boolean;
   /** Fields rendered on this page. Required, non-empty — every field the
    *  frontend shows must be listed explicitly. */
   columns: Field[];
@@ -81,6 +80,12 @@ export function defineCurd(name: string, schema: Omit<CurdSchema, 'name'>): Curd
   if (curd.app.type !== 'admin') {
     throw new Error(`curd ${name}: app ${curd.app.name} must be type 'admin' (got '${curd.app.type}')`);
   }
+  // The name is the admin route path — it must be the kebab-case table name
+  // so paths cannot drift from the table they serve.
+  const expectedName = toKebabCase(curd.table.name);
+  if (name !== expectedName) {
+    throw new Error(`curd name must be '${expectedName}' (kebab-case of table '${curd.table.name}'); got '${name}'`);
+  }
   if (!curd.section) {
     throw new Error(`curd ${name}: section is required (sidebar menu group, e.g. '商户管理')`);
   }

package/src/dao.ts

@@ -1,13 +1,172 @@
-import { SchemaBase } from './dsl.js';
+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>;
 }
 
-export function defineDao(name: string, app: FrontAppSchema, description?: string): DaoSchema {
-  return { name, type: 'dao', app, description };
+/** 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

@@ -118,6 +118,11 @@ export function defineTable<
         `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;

package/src/dsl.ts

@@ -71,6 +71,24 @@ interface DecimalField extends BaseField {
   // Value is transported as string to avoid binary float error.
 }
 
+type RateUnit = 'pct' | 'pm' | 'bp';
+
+export function rateScale(unit: RateUnit): number {
+  switch (unit) {
+    case 'pct': return 2;
+    case 'pm':  return 3;
+    case 'bp':  return 4;
+  }
+}
+
+interface RateField extends BaseField {
+  type: 'rate';
+  jsType: 'string';
+  unit: RateUnit;
+  // Precision/scale are derived from unit at DDL/TypeBox render time,
+  // not stored on the field.
+}
+
 interface BooleanField extends BaseField {
   type: 'boolean';
   jsType: 'boolean';
@@ -125,18 +143,36 @@ 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
   | IntField
   | BigintField
   | DecimalField
+  | RateField
   | BooleanField
   | DateField
   | 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).
@@ -163,6 +199,10 @@ export function decimalField(extra: FieldExtras<DecimalField>): DecimalField {
   return { name: '', type: 'decimal', jsType: 'string', ...extra };
 }
 
+export function rateField(unit: RateUnit, extra: Omit<FieldExtras<RateField>, 'unit'> = {}): RateField {
+  return { name: '', type: 'rate', jsType: 'string', unit, ...extra };
+}
+
 export function booleanField(extra: FieldExtras<BooleanField> = {}): BooleanField {
   return { name: '', type: 'boolean', jsType: 'boolean', ...extra };
 }
@@ -183,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 };