@pylonts/dsl 1.1.4 → 1.1.6

package/src/popup.ts

@@ -1,25 +1,25 @@
-import type { ActionSchema } from './action.js';
-import type { RefSchema } from './ref.js';
-
-/** Display a toast notification. React: toast/message UI. Mini-program: wx.showToast. */
-export interface ToastAction extends ActionSchema {
-  type: 'toast';
-  message: string | RefSchema;
-  icon?: 'success' | 'error' | 'loading' | 'none';
-}
-
-/** Display an alert dialog. React: modal. Mini-program: wx.showModal. */
-export interface AlertAction extends ActionSchema {
-  type: 'alert';
-  title: string | RefSchema;
-  content: string | RefSchema;
-}
-
-export const popup = {
-  toast(message: string | RefSchema, icon?: 'success' | 'error' | 'loading' | 'none'): ToastAction {
-    return { name: 'toast', type: 'toast', message, icon };
-  },
-  alert(title: string | RefSchema, content: string | RefSchema): AlertAction {
-    return { name: 'alert', type: 'alert', title, content };
-  },
-};
+import type { ActionSchema } from './action.js';
+import type { RefSchema } from './ref.js';
+
+/** Display a toast notification. React: toast/message UI. Mini-program: wx.showToast. */
+export interface ToastAction extends ActionSchema {
+  type: 'toast';
+  message: string | RefSchema;
+  icon?: 'success' | 'error' | 'loading' | 'none';
+}
+
+/** Display an alert dialog. React: modal. Mini-program: wx.showModal. */
+export interface AlertAction extends ActionSchema {
+  type: 'alert';
+  title: string | RefSchema;
+  content: string | RefSchema;
+}
+
+export const popup = {
+  toast(message: string | RefSchema, icon?: 'success' | 'error' | 'loading' | 'none'): ToastAction {
+    return { name: 'toast', type: 'toast', message, icon };
+  },
+  alert(title: string | RefSchema, content: string | RefSchema): AlertAction {
+    return { name: 'alert', type: 'alert', title, content };
+  },
+};

package/src/project.ts

@@ -1,98 +1,98 @@
-import { SchemaBase } from './dsl.js';
-import type { TableSchema } from './db.js';
-
-// Project topology definitions: describe the applications (frontends) and
-// backend APIs of a repository, and which frontends each API serves.
-
-/** Frontend form factor. Closed enum, extend when new form factors appear. */
-export type FrontType = 'admin' | 'wxmini';
-
-/** A frontend application (e.g. admin console, wechat mini program). */
-export interface FrontAppSchema extends SchemaBase {
-  type: FrontType;
-  /** Source directory relative to project root, e.g. 'web-admin/'. */
-  dir: string;
-  /**
-   * Tenant table for this app. When set, all tables with a foreign key
-   * pointing to this table get automatic tenant scoping: the tenant PK
-   * value is injected from `user.id` into all curd operations.
-   */
-  tenant?: TableSchema;
-}
-
-/** A backend API service. apps references shared FrontAppSchema instances. */
-export interface ProjectApiSchema extends SchemaBase {
-  /** Source directory relative to project root, e.g. 'api/'. */
-  dir: string;
-  /** Frontends this API serves. Direct instance references (see defineProject). */
-  apps: FrontAppSchema[];
-  /** API base URL prefix shared by all apps it serves, e.g. '/mall'. '' = no prefix. */
-  contextPath?: string;
-  /** API service base URL for node clients, e.g. 'http://127.0.0.1:3000'. */
-  baseUrl?: string;
-}
-
-/** A third-party system (e.g. wechat pay, unionpay). Owns its own
- *  implementation dir and contract (controller_types), just like an API,
- *  but is not part of this repo's served surface. */
-export interface ThirdApiSchema extends SchemaBase {
-  /** Source directory relative to project root, e.g. 'wechat/'. */
-  dir: string;
-}
-
-export interface ProjectSchema extends SchemaBase {
-  apps: FrontAppSchema[];
-  apis: ProjectApiSchema[];
-  thirdApis: ThirdApiSchema[];
-}
-
-/**
- * Defines the project topology. FrontAppSchema instances are shared value objects:
- * api.apps references the same instances from project.apps, so an app served
- * by multiple APIs is defined once and referenced many times.
- *
- * Runtime-validates app type whitelist, unique names and api.apps reference
- * integrity (same style as defineTable/defineCurd).
- */
-export function defineProject(
-  name: string,
-  schema: {
-    description?: string;
-    apps: FrontAppSchema[];
-    apis: ProjectApiSchema[];
-    thirdApis?: ThirdApiSchema[];
-  },
-): ProjectSchema {
-  const project: ProjectSchema = { name, ...schema, thirdApis: schema.thirdApis ?? [] };
-
-  const appNames = new Set<string>();
-  for (const app of project.apps) {
-    if (!app.name) throw new Error(`project ${name}: app name is required`);
-    if (appNames.has(app.name)) throw new Error(`project ${name}: duplicate app name '${app.name}'`);
-    appNames.add(app.name);
-    if (app.type !== 'admin' && app.type !== 'wxmini') {
-      throw new Error(`project ${name}: app '${app.name}' must be type 'admin' or 'wxmini' (got '${app.type}')`);
-    }
-    if (!app.dir) throw new Error(`project ${name}: app '${app.name}' dir is required`);
-  }
-
-  const apiNames = new Set<string>();
-  for (const api of project.apis) {
-    if (!api.name) throw new Error(`project ${name}: api name is required`);
-    if (apiNames.has(api.name)) throw new Error(`project ${name}: duplicate api name '${api.name}'`);
-    apiNames.add(api.name);
-    if (!api.dir) throw new Error(`project ${name}: api '${api.name}' dir is required`);
-    for (const ref of api.apps) {
-      if (!project.apps.includes(ref)) {
-        throw new Error(`project ${name}: api '${api.name}' references app '${ref.name}' that is not a shared instance in project.apps (define once and reference it)`);
-      }
-    }
-  }
-
-  for (const third of project.thirdApis) {
-    if (!third.name) throw new Error(`project ${name}: thirdApi name is required`);
-    if (!third.dir) throw new Error(`project ${name}: thirdApi '${third.name}' dir is required`);
-  }
-
-  return project;
+import { SchemaBase } from './dsl.js';
+import type { TableSchema } from './db.js';
+
+// Project topology definitions: describe the applications (frontends) and
+// backend APIs of a repository, and which frontends each API serves.
+
+/** Frontend form factor. Closed enum, extend when new form factors appear. */
+export type FrontType = 'admin' | 'wxmini';
+
+/** A frontend application (e.g. admin console, wechat mini program). */
+export interface FrontAppSchema extends SchemaBase {
+  type: FrontType;
+  /** Source directory relative to project root, e.g. 'web-admin/'. */
+  dir: string;
+  /**
+   * Tenant table for this app. When set, all tables with a foreign key
+   * pointing to this table get automatic tenant scoping: the tenant PK
+   * value is injected from `user.id` into all curd operations.
+   */
+  tenant?: TableSchema;
+}
+
+/** A backend API service. apps references shared FrontAppSchema instances. */
+export interface ProjectApiSchema extends SchemaBase {
+  /** Source directory relative to project root, e.g. 'api/'. */
+  dir: string;
+  /** Frontends this API serves. Direct instance references (see defineProject). */
+  apps: FrontAppSchema[];
+  /** API base URL prefix shared by all apps it serves, e.g. '/mall'. '' = no prefix. */
+  contextPath?: string;
+  /** API service base URL for node clients, e.g. 'http://127.0.0.1:3000'. */
+  baseUrl?: string;
+}
+
+/** A third-party system (e.g. wechat pay, unionpay). Owns its own
+ *  implementation dir and contract (controller_types), just like an API,
+ *  but is not part of this repo's served surface. */
+export interface ThirdApiSchema extends SchemaBase {
+  /** Source directory relative to project root, e.g. 'wechat/'. */
+  dir: string;
+}
+
+export interface ProjectSchema extends SchemaBase {
+  apps: FrontAppSchema[];
+  apis: ProjectApiSchema[];
+  thirdApis: ThirdApiSchema[];
+}
+
+/**
+ * Defines the project topology. FrontAppSchema instances are shared value objects:
+ * api.apps references the same instances from project.apps, so an app served
+ * by multiple APIs is defined once and referenced many times.
+ *
+ * Runtime-validates app type whitelist, unique names and api.apps reference
+ * integrity (same style as defineTable/defineCurd).
+ */
+export function defineProject(
+  name: string,
+  schema: {
+    description?: string;
+    apps: FrontAppSchema[];
+    apis: ProjectApiSchema[];
+    thirdApis?: ThirdApiSchema[];
+  },
+): ProjectSchema {
+  const project: ProjectSchema = { name, ...schema, thirdApis: schema.thirdApis ?? [] };
+
+  const appNames = new Set<string>();
+  for (const app of project.apps) {
+    if (!app.name) throw new Error(`project ${name}: app name is required`);
+    if (appNames.has(app.name)) throw new Error(`project ${name}: duplicate app name '${app.name}'`);
+    appNames.add(app.name);
+    if (app.type !== 'admin' && app.type !== 'wxmini') {
+      throw new Error(`project ${name}: app '${app.name}' must be type 'admin' or 'wxmini' (got '${app.type}')`);
+    }
+    if (!app.dir) throw new Error(`project ${name}: app '${app.name}' dir is required`);
+  }
+
+  const apiNames = new Set<string>();
+  for (const api of project.apis) {
+    if (!api.name) throw new Error(`project ${name}: api name is required`);
+    if (apiNames.has(api.name)) throw new Error(`project ${name}: duplicate api name '${api.name}'`);
+    apiNames.add(api.name);
+    if (!api.dir) throw new Error(`project ${name}: api '${api.name}' dir is required`);
+    for (const ref of api.apps) {
+      if (!project.apps.includes(ref)) {
+        throw new Error(`project ${name}: api '${api.name}' references app '${ref.name}' that is not a shared instance in project.apps (define once and reference it)`);
+      }
+    }
+  }
+
+  for (const third of project.thirdApis) {
+    if (!third.name) throw new Error(`project ${name}: thirdApi name is required`);
+    if (!third.dir) throw new Error(`project ${name}: thirdApi '${third.name}' dir is required`);
+  }
+
+  return project;
 }

package/src/provider.ts

@@ -3,7 +3,7 @@ import type { ImportableSchemaBase } from './dsl.js';
 import type { DtoField, DtoMessage, DtoArrayField, DtoObjectField } from './dto.js';
 import type { ActionSchema } from './action.js';
 import type { RefSchema } from './ref.js';
-import type { ConvertSchema } from './convert.js';
+import type { EndpointSchema } from './endpoint.js';
 
 // ProviderSchema: an API function signature (args DTO + results DTO).
 
@@ -35,13 +35,11 @@ export function call(func: ProviderSchema, args?: Record<string, DtoField | DtoM
 }
 
 /** Provider function signature. The generated API client exposes one function
- *  per endpoint; ProviderSchema gives that function a name and types. */
+ *  per endpoint; ProviderSchema gives that function a name and a shared signature. */
 export interface ProviderSchema extends ImportableSchemaBase {
   isAsync: boolean;
-  /** Input DTO (buildInput / buildQuery / buildPk result). */
-  args: DtoMessage;
-  /** Output DTO (buildOutput result) or primitive. */
-  results: DtoMessage | number | boolean | string;
+  /** Shared API signature — same instance the backend controller method references. */
+  signature: EndpointSchema;
 }
 
 /** Define a provider function. */
@@ -49,8 +47,7 @@ export function defineProvider(
   name: string,
   schema: {
     isAsync: boolean;
-    args: DtoMessage;
-    results: DtoMessage | number | boolean | string;
+    signature: EndpointSchema;
     description?: string;
     importRef?: ImportBase;
   },
@@ -64,10 +61,8 @@ export interface SetDataAction extends ActionSchema {
   type: 'setData';
   call: CallAction;
   field: DtoField;
-  /** Optional field-level transform before assignment. */
-  convert?: ConvertSchema;
 }
 
-export function setData(call: CallAction, field: DtoField, convert?: ConvertSchema): SetDataAction {
-  return { name: 'setData', type: 'setData', call, field, convert };
+export function setData(call: CallAction, field: DtoField): SetDataAction {
+  return { name: 'setData', type: 'setData', call, field };
 }

package/src/ref.ts

@@ -1,19 +1,19 @@
-import type { CollectionSchemaBase } from './dsl.js';
-import type { DtoField } from './dto.js';
-
-/** A reference to a field within another schema. Carries a .schema back-reference
- *  so the driver knows where the data comes from (route params, page data, etc.). */
-export interface RefSchema {
-  name: string;
-  /** Schema back-reference — tells driver the data source. */
-  schema: CollectionSchemaBase;
-  /** The referenced field instance. */
-  field: DtoField;
-}
-
-/** Create a reference to a field in a source schema.
- *  Writes back field.schema to the source so the driver can trace origin. */
-export function defineRef(source: CollectionSchemaBase, field: DtoField): RefSchema {
-  field.schema = source;
-  return { name: field.name, schema: source, field };
+import type { CollectionSchemaBase } from './dsl.js';
+import type { DtoField } from './dto.js';
+
+/** A reference to a field within another schema. Carries a .schema back-reference
+ *  so the driver knows where the data comes from (route params, page data, etc.). */
+export interface RefSchema {
+  name: string;
+  /** Schema back-reference — tells driver the data source. */
+  schema: CollectionSchemaBase;
+  /** The referenced field instance. */
+  field: DtoField;
+}
+
+/** Create a reference to a field in a source schema.
+ *  Writes back field.schema to the source so the driver can trace origin. */
+export function defineRef(source: CollectionSchemaBase, field: DtoField): RefSchema {
+  field.schema = source;
+  return { name: field.name, schema: source, field };
 }

package/src/route.ts

@@ -1,12 +1,12 @@
-import type { CollectionSchemaBase } from './dsl.js';
-import type { DtoField } from './dto.js';
-
-/** Route params: data that arrives from the navigation URL / route. */
-export interface RouteDataSchema extends CollectionSchemaBase {
-  type: 'route';
-  fields: Record<string, DtoField>;
-}
-
-export function defineRouteData(name: string, fields: RouteDataSchema['fields']): RouteDataSchema {
-  return { name, type: 'route', fields };
+import type { CollectionSchemaBase } from './dsl.js';
+import type { DtoField } from './dto.js';
+
+/** Route params: data that arrives from the navigation URL / route. */
+export interface RouteDataSchema extends CollectionSchemaBase {
+  type: 'route';
+  fields: Record<string, DtoField>;
+}
+
+export function defineRouteData(name: string, fields: RouteDataSchema['fields']): RouteDataSchema {
+  return { name, type: 'route', fields };
 }

package/src/service.ts

@@ -2,20 +2,42 @@ import { SchemaBase } from './dsl.js';
 import { FrontAppSchema } from './project.js';
 import type { DtoArrayField, DtoField, DtoMessage, DtoObjectField } from './dto.js';
 
-/** A frontend service bound to exactly one frontend app. */
+/** A backend service serving exactly one frontend app (1:1 module). */
 export interface ServiceSchema extends SchemaBase {
   type: 'service';
-  /** The frontend app this service belongs to (shared instance from project.config). */
+  /** The frontend app this service serves (shared instance from project.config). */
   app: FrontAppSchema;
+  /** Methods keyed by name — the map key is written back as the method name. */
+  methods: Record<string, ServiceMethodSchema>;
 }
 
-export function defineService(name: string, app: FrontAppSchema, description?: string): ServiceSchema {
-  return { name, type: 'service', app, description };
+/** Method input for defineService: type/schema/name are set by the builder. */
+export type ServiceMethodDef = Omit<ServiceMethodSchema, 'type' | 'schema' | 'name'>;
+
+export function defineService(options: {
+  name: string;
+  app: FrontAppSchema;
+  methods: Record<string, ServiceMethodDef>;
+  description?: string;
+}): ServiceSchema {
+  const schema: ServiceSchema = {
+    type: 'service',
+    name: options.name,
+    description: options.description,
+    app: options.app,
+    methods: {},
+  };
+  for (const key of Object.keys(options.methods)) {
+    const method = options.methods[key] as ServiceMethodDef;
+    schema.methods[key] = { type: 'method', schema, ...method, name: key };
+  }
+  return schema;
 }
 
 /** A method exposed by a service. */
 export interface ServiceMethodSchema extends SchemaBase {
   type: 'method';
-  name: string;
-  fields: Record<string, DtoField | DtoMessage | DtoArrayField | DtoObjectField>;
+  schema : ServiceSchema;
+  args: DtoMessage,
+  results : DtoMessage
 }

package/src/third-service.ts

@@ -0,0 +1,186 @@
+import { CollectionSchemaBase, Field, SchemaBase } from './dsl.js';
+import type { FieldRuleEnd, FieldRuleSchema } from './field-rule.js';
+import type { ThirdApiSchema } from './project.js';
+
+// Third-party integration services.
+// A ThirdMethodSchema is the Field-collection counterpart of a DtoMessage —
+// like TableSchema.columns but for wire-format fields instead of DB columns.
+// DTOs project from it via from(thirdMethod), and its fields may either share
+// a local entity column instance (same fact, same type) or declare their own
+// wire type plus a refs link (same fact, different type/format).
+
+/** A third-party integration service (e.g. tenpay wechat pay).
+ *  Distinct from ServiceSchema (backend service bound to an app) and
+ *  ThirdApiSchema (project topology: the dir the integration lives in).
+ *  Describes the adapter class contract: constructor config + methods. */
+export interface ThirdServiceSchema extends SchemaBase {
+  type: 'thirdService';
+  /** The third-party system this service integrates (topology reference). */
+  schema: ThirdApiSchema;
+  /** Methods keyed by name — the map key is written back as the method name. */
+  methods: Record<string, ThirdServiceMethodSchema>;
+}
+
+/** A method exposed by a third-party service. */
+export interface ThirdServiceMethodSchema extends SchemaBase {
+  type: 'method';
+  schema: ThirdServiceSchema;
+  /** Input message — the Field-collection counterpart of a DtoMessage. */
+  args: ThirdMethodSchema;
+  /** Output message. */
+  results: ThirdMethodSchema;
+}
+
+/** Field binding to a rule: which end the local wire field stands on.
+ *  The ref always stands on the other end — from/to carry no extra information. */
+export interface ConvertFieldSchema {
+  /** The rule binding field and ref (rule = name + two ends). */
+  rule: FieldRuleSchema;
+  /** The end instance the local wire field stands on. */
+  end: FieldRuleEnd;
+}
+
+/** Same-fact variant link: a wire field carrying the same fact as a local
+ *  entity column under a different type/format (e.g. total_fee in fen vs amount in yuan). */
+export interface ThirdFieldRef {
+  /** Wire field defined in this message (local definition). */
+  field: Field;
+  /** Field in another schema (table column or another message). */
+  ref: Field;
+  /** Optional rule binding — omitted when the fact is merely linked, not converted. */
+  convert?: ConvertFieldSchema;
+}
+
+/** A directional message of a third-party method: a Field collection mirroring
+ *  TableSchema.columns, but fields hold wire-format names/types. A field may be
+ *  a shared instance of a local entity column (same fact, same type) — its
+ *  name/schema keep pointing at the table and the DTO projection inherits
+ *  type/semantics from the entity, exactly like from(table). */
+export interface ThirdMethodSchema extends CollectionSchemaBase {
+  type: 'thirdMethod';
+  /** The method this message belongs to (direction implied by args/results slot). */
+  schema: ThirdServiceMethodSchema;
+  /** Wire-format fields. */
+  fields: Record<string, Field>;
+  /** Same-fact variant links: wire field -> local entity column. */
+  refs?: ThirdFieldRef[];
+}
+
+/** Message input for defineThirdMethod: type/schema are set by the builder. */
+export type ThirdMethodDef = Omit<ThirdMethodSchema, 'type' | 'schema'>;
+
+/** Build a third-party method message. Writes back name/schema on own fields
+ *  (top-level and nested); shared entity columns keep their table identity and
+ *  must be keyed by their column name. */
+export function defineThirdMethod(def: ThirdMethodDef): ThirdMethodSchema {
+  const message: ThirdMethodSchema = {
+    type: 'thirdMethod',
+    name: def.name,
+    description: def.description,
+    // Filled by defineThirdService.
+    schema: undefined as unknown as ThirdServiceMethodSchema,
+    fields: def.fields,
+    refs: def.refs,
+  };
+  for (const key of Object.keys(message.fields)) {
+    const field = message.fields[key] as Field;
+    if (field.schema === undefined) {
+      field.name = key;
+      field.schema = message;
+    } else if (field.schema.type === 'table') {
+      // Shared entity column: from() names the projection after field.name, so
+      // a mismatched key would silently rename the wire field. Same-fact fields
+      // with different names go through refs instead.
+      if (field.name !== key) {
+        throw new Error(
+          `thirdMethod '${message.name}': shared column key '${key}' must match the column name '${field.name}' — ` +
+          `same-fact fields with different names go through refs instead`,
+        );
+      }
+    } else if (field.schema !== message) {
+      throw new Error(
+        `thirdMethod '${message.name}': field '${key}' already belongs to ${field.schema.type} '${field.schema.name}', cannot reuse`,
+      );
+    }
+    writeBackNested(message, field);
+  }
+  if (message.refs !== undefined) {
+    const ownFields = Object.values(message.fields);
+    for (const link of message.refs) {
+      if (!ownFields.includes(link.field)) {
+        throw new Error(`thirdMethod '${message.name}': ref field must be one of its fields`);
+      }
+      if (link.ref.schema === undefined || link.ref.schema === message) {
+        throw new Error(`thirdMethod '${message.name}': ref target '${link.ref.name}' must be defined in another schema`);
+      }
+      if (link.convert !== undefined) {
+        const ends = Object.values(link.convert.rule.ends);
+        if (!ends.includes(link.convert.end)) {
+          throw new Error(
+            `thirdMethod '${message.name}': convert end '${link.convert.end.name}' must be one of rule '${link.convert.rule.name}' ends`,
+          );
+        }
+      }
+    }
+  }
+  return message;
+}
+
+/** Write back name/schema on nested wire fields (array items, object properties);
+ *  shared entity columns keep their table identity. */
+function writeBackNested(message: ThirdMethodSchema, field: Field): void {
+  if (field.type === 'array') {
+    writeBackNested(message, field.items);
+    return;
+  }
+  if (field.type !== 'object') return;
+  for (const key of Object.keys(field.properties)) {
+    const child = field.properties[key] as Field;
+    if (child.schema === undefined) {
+      child.name = key;
+      child.schema = message;
+    }
+    writeBackNested(message, child);
+  }
+}
+
+/** Method input for defineThirdService: name is written back from the methods map key. */
+export interface ThirdServiceMethodDef {
+  /** Input message. */
+  args: ThirdMethodDef;
+  /** Output message. */
+  results: ThirdMethodDef;
+  description?: string;
+}
+
+export function defineThirdService(options: {
+  schema: ThirdApiSchema;
+  name: string;
+  methods: Record<string, ThirdServiceMethodDef>;
+  description?: string;
+}): ThirdServiceSchema {
+  const schema: ThirdServiceSchema = {
+    type: 'thirdService',
+    name: options.name,
+    description: options.description,
+    schema: options.schema,
+    methods: {},
+  };
+  for (const key of Object.keys(options.methods)) {
+    const method = options.methods[key] as ThirdServiceMethodDef;
+    const methodSchema: ThirdServiceMethodSchema = {
+      type: 'method',
+      name: key,
+      description: method.description,
+      schema,
+      args: undefined as unknown as ThirdMethodSchema,
+      results: undefined as unknown as ThirdMethodSchema,
+    };
+    methodSchema.args = defineThirdMethod(method.args);
+    methodSchema.results = defineThirdMethod(method.results);
+    methodSchema.args.schema = methodSchema;
+    methodSchema.results.schema = methodSchema;
+    schema.methods[key] = methodSchema;
+  }
+  return schema;
+}