@pylonts/dsl 1.1.12 → 1.1.13

package/src/service.ts

@@ -1,108 +1,113 @@
-import type { SchemaBase } from './dsl.js';
-import type { FrontAppSchema, ProjectApiSchema } from './project.js';
-import type { DtoArrayField, DtoField, DtoMessage, DtoObjectField } from './dto.js';
-import type { ExceptionSchema } from './exception.js';
-import type { FlowSchema } from './flow.js';
-import { exceptionEndNames } from './flow.js';
-
-/** A backend service serving exactly one frontend app (1:1 module). */
-export interface ServiceSchema extends SchemaBase {
-  type: 'service';
-  /** The backend api module this service belongs to (shared instance from
-   *  project.config.ts apis). Services are always backend-side, so storage is
-   *  service_schema/{api.name}/{app.name}/service/. */
-  api: ProjectApiSchema;
-  /** 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>;
-}
-
-/** 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;
-  api: ProjectApiSchema;
-  app: FrontAppSchema;
-  methods: Record<string, ServiceMethodDef>;
-  description?: string;
-}): ServiceSchema {
-  if (!options.api.apps.includes(options.app)) {
-    throw new Error(`service ${options.name}: api '${options.api.name}' does not serve app '${options.app.name}'`);
-  }
-  const schema: ServiceSchema = {
-    type: 'service',
-    name: options.name,
-    description: options.description,
-    api: options.api,
-    app: options.app,
-    methods: {},
-  };
-  for (const key of Object.keys(options.methods)) {
-    const method = options.methods[key];
-    schema.methods[key] = { type: 'method', schema, ...method, name: key };
-  }
-  validateFlowBindings(schema);
-  return schema;
-}
-
-// A method bound to a flow: the flow's escape set (its exception ends) must
-// equal the method's declared throws, the flow's own args/results (when
-// present) must be the same objects as the method's, and one flow may serve
-// only one method.
-//
-// Notes: (1) the unique-binding check is per defineService call — a flow
-// shared across two service schemas is not detected; (2) escape-set equality
-// means exceptions swallowed by an internal catch (or routed through a
-// catch-all end) disappear from the contract, so the method must not declare
-// them.
-function validateFlowBindings(schema: ServiceSchema): void {
-  const seenFlows = new Set<FlowSchema>();
-  for (const key of Object.keys(schema.methods)) {
-    const m = schema.methods[key];
-    if (!m.flow) continue;
-    if (seenFlows.has(m.flow)) {
-      throw new Error(`service ${schema.name}: flow "${m.flow.name}" is bound to more than one method`);
-    }
-    seenFlows.add(m.flow);
-    if (m.flow.args !== undefined && m.flow.args !== m.args) {
-      throw new Error(
-        `service ${schema.name}: method "${key}" args and its flow "${m.flow.name}" args must be the same object`,
-      );
-    }
-    if (m.flow.results !== undefined && m.flow.results !== m.results) {
-      throw new Error(
-        `service ${schema.name}: method "${key}" results and its flow "${m.flow.name}" results must be the same object`,
-      );
-    }
-    const escaped = exceptionEndNames(m.flow);
-    const declared = new Set((m.throws ?? []).map((t) => t.name));
-    for (const e of escaped) {
-      if (!declared.has(e)) {
-        throw new Error(`service ${schema.name}: method "${key}" flow escapes ${e} but the method does not declare it`);
-      }
-    }
-    for (const d of declared) {
-      if (!escaped.has(d)) {
-        throw new Error(`service ${schema.name}: method "${key}" declares throw ${d} but its flow never escapes it`);
-      }
-    }
-    if (m.flow.name !== key) {
-      console.warn(`service ${schema.name}: method "${key}" flow name "${m.flow.name}" differs from the method key`);
-    }
-  }
-}
-
-/** A method exposed by a service. */
-export interface ServiceMethodSchema extends SchemaBase {
-  type: 'method';
-  schema : ServiceSchema;
-  args: DtoMessage,
-  results : DtoMessage
-  /** Exceptions this method may throw (e.g. IOException, CodeException). */
-  throws?: ExceptionSchema[];
-  /** Implementation flow — the method's logic graph. The method carries the
-   *  contract (args/results/throws), the flow carries the structure. */
-  flow?: FlowSchema;
+import type { CollectionSchemaBase, SchemaBase } from './dsl.js';
+import type { FrontAppSchema, ProjectApiSchema } from './project.js';
+import type { DtoArrayField, DtoField, DtoMessage, DtoObjectField } from './dto.js';
+import type { ExceptionSchema } from './exception.js';
+import type { FlowSchema } from './flow.js';
+import { exceptionEndNames } from './flow.js';
+
+/** A backend service serving one frontend app (1:1 module), or a
+ *  platform-shared domain service (app unset — shared across modules). */
+export interface ServiceSchema extends CollectionSchemaBase {
+  type: 'service';
+  /** The backend api module this service belongs to (shared instance from
+   *  project.config.ts apis). Services are always backend-side, so storage is
+   *  service_schema/{api.name}/{app.name}/service/ — app unset = the api-level
+   *  common domain layer, stored at service_schema/{api.name}/common/service/. */
+  api: ProjectApiSchema;
+  /** The frontend app this service serves (shared instance from project.config).
+   *  Unset = api-level common domain service shared by all modules of the api. */
+  app?: FrontAppSchema;
+  /** Methods keyed by name — the map key is written back as the method name. */
+  methods: Record<string, ServiceMethodSchema>;
+}
+
+/** 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;
+  api: ProjectApiSchema;
+  app?: FrontAppSchema;
+  methods: Record<string, ServiceMethodDef>;
+  description?: string;
+}): ServiceSchema {
+  if (options.app && !options.api.apps.includes(options.app)) {
+    throw new Error(`service ${options.name}: api '${options.api.name}' does not serve app '${options.app.name}'`);
+  }
+  const schema: ServiceSchema = {
+    type: 'service',
+    name: options.name,
+    description: options.description,
+    api: options.api,
+    app: options.app,
+    methods: {},
+  };
+  for (const key of Object.keys(options.methods)) {
+    const method = options.methods[key];
+    schema.methods[key] = { type: 'method', schema, ...method, name: key };
+  }
+  validateFlowBindings(schema);
+  return schema;
+}
+
+// A method bound to a flow: the flow's escape set (its exception ends) must
+// equal the method's declared throws, the flow's own args/results (when
+// present) must be the same objects as the method's, and one flow may serve
+// only one method.
+//
+// Notes: (1) the unique-binding check is per defineService call — a flow
+// shared across two service schemas is not detected; (2) escape-set equality
+// means exceptions swallowed by an internal catch (or routed through a
+// catch-all end) disappear from the contract, so the method must not declare
+// them.
+function validateFlowBindings(schema: ServiceSchema): void {
+  const seenFlows = new Set<FlowSchema>();
+  for (const key of Object.keys(schema.methods)) {
+    const m = schema.methods[key];
+    if (!m.flow) continue;
+    if (seenFlows.has(m.flow)) {
+      throw new Error(`service ${schema.name}: flow "${m.flow.name}" is bound to more than one method`);
+    }
+    seenFlows.add(m.flow);
+    if (m.flow.args !== undefined && m.flow.args !== m.args) {
+      throw new Error(
+        `service ${schema.name}: method "${key}" args and its flow "${m.flow.name}" args must be the same object`,
+      );
+    }
+    if (m.flow.results !== undefined && m.flow.results !== m.results) {
+      throw new Error(
+        `service ${schema.name}: method "${key}" results and its flow "${m.flow.name}" results must be the same object`,
+      );
+    }
+    const escaped = exceptionEndNames(m.flow);
+    const declared = new Set((m.throws ?? []).map((t) => t.name));
+    for (const e of escaped) {
+      if (!declared.has(e)) {
+        throw new Error(`service ${schema.name}: method "${key}" flow escapes ${e} but the method does not declare it`);
+      }
+    }
+    for (const d of declared) {
+      if (!escaped.has(d)) {
+        throw new Error(`service ${schema.name}: method "${key}" declares throw ${d} but its flow never escapes it`);
+      }
+    }
+    if (m.flow.name !== key) {
+      console.warn(`service ${schema.name}: method "${key}" flow name "${m.flow.name}" differs from the method key`);
+    }
+  }
+}
+
+/** A method exposed by a business service — the contract with the calling
+ *  frontend. Third-party integration methods are a separate contract
+ *  (ThirdServiceMethodSchema): they can never bind a flow. */
+export interface ServiceMethodSchema extends SchemaBase {
+  type: 'method';
+  schema: ServiceSchema;
+  args: DtoMessage,
+  results : DtoMessage
+  /** Exceptions this method may throw (e.g. IOException, CodeException). */
+  throws?: ExceptionSchema[];
+  /** Implementation flow — the method's logic graph. The method carries the
+   *  contract (args/results/throws), the flow carries the structure. */
+  flow?: FlowSchema;
 }

package/src/third-service.ts

@@ -1,192 +1,69 @@
-import { CollectionSchemaBase, Field, SchemaBase } from './dsl.js';
-import type { ExceptionSchema } from './exception.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;
-  /** Exceptions this method may throw (e.g. IOException, CodeException). */
-  throws?: ExceptionSchema[];
-}
-
-/** 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;
-  /** Exceptions this method may throw (e.g. IOException, CodeException). */
-  throws?: ExceptionSchema[];
-  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,
-      throws: method.throws,
-    };
-    methodSchema.args = defineThirdMethod(method.args);
-    methodSchema.results = defineThirdMethod(method.results);
-    methodSchema.args.schema = methodSchema;
-    methodSchema.results.schema = methodSchema;
-    schema.methods[key] = methodSchema;
-  }
-  return schema;
+import type { SchemaBase } from './dsl.js';
+import type { DtoMessage } from './dto.js';
+import type { ExceptionSchema } from './exception.js';
+import type { ThirdApiSchema } from './project.js';
+
+// Third-party integration services.
+// A third-party method's args/results are plain DtoMessages — the same POJO
+// aggregate as any business DTO. Fields reference each other across messages
+// by sharing the Field instance (dtoField(sharedField)): a wire field may be
+// the same object as a local entity column (same fact, same type) or a field
+// of another DtoMessage (same fact, possibly different protocol name).
+
+/** 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 of a third-party integration service. Same contract shape as
+ *  ServiceMethodSchema minus flow — the implementation lives in the external
+ *  system, there is nothing to model. Kept separate so a third method can
+ *  never bind a flow. */
+export interface ThirdServiceMethodSchema extends SchemaBase {
+  type: 'method';
+  schema: ThirdServiceSchema;
+  /** Input message. */
+  args: DtoMessage;
+  /** Output message. */
+  results: DtoMessage;
+  /** Exceptions this method may throw (e.g. IOException, CodeException). */
+  throws?: ExceptionSchema[];
+}
+
+/** Method input for defineThirdService: name/schema are set by the builder. */
+export type ThirdServiceMethodDef = Omit<ThirdServiceMethodSchema, 'type' | 'schema' | 'name'>;
+
+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];
+    schema.methods[key] = {
+      type: 'method',
+      name: key,
+      description: method.description,
+      schema,
+      args: method.args,
+      results: method.results,
+      throws: method.throws,
+    };
+  }
+  return schema;
 }