@pylonts/dsl 1.1.6 → 1.1.12

package/src/service.ts

@@ -1,10 +1,17 @@
-import { SchemaBase } from './dsl.js';
-import { FrontAppSchema } from './project.js';
+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. */
@@ -16,28 +23,86 @@ export type ServiceMethodDef = Omit<ServiceMethodSchema, 'type' | 'schema' | 'na
 
 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] as ServiceMethodDef;
+    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;
 }

package/src/third-service.ts

@@ -1,4 +1,5 @@
 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';
 
@@ -29,6 +30,8 @@ export interface ThirdServiceMethodSchema extends SchemaBase {
   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.
@@ -150,6 +153,8 @@ export interface ThirdServiceMethodDef {
   args: ThirdMethodDef;
   /** Output message. */
   results: ThirdMethodDef;
+  /** Exceptions this method may throw (e.g. IOException, CodeException). */
+  throws?: ExceptionSchema[];
   description?: string;
 }
 
@@ -175,6 +180,7 @@ export function defineThirdService(options: {
       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);

package/src/typebox-driver.ts

@@ -79,6 +79,10 @@ function renderBasic(
       }
       return `Type.Enum(${ref.name})`;
     }
+    case 'aggregate':
+      // Aggregate query outputs: count/sum(int) are numbers, everything else
+      // arrives as a precision string.
+      return field.jsType === 'number' ? 'Type.Number()' : 'Type.String()';
     case 'array':
       return `Type.Array(${renderFieldValue(field.items, indent, resolver)})`;
     case 'object':

package/src/utils.ts

@@ -1,5 +1,5 @@
 import type { Field, SchemaBase } from './dsl.js';
-import type { FrontAppSchema } from './project.js';
+import type { FrontAppSchema, ProjectApiSchema } from './project.js';
 
 // Base utility modules — business-agnostic helpers with full method
 // signatures (e.g. DateTimeUtils.format). Called at the service layer;
@@ -22,7 +22,13 @@ export type UtilsMethodDef = Omit<UtilsMethodSchema, 'type' | 'schema' | 'name'>
 /** A base utility module (e.g. DateTimeUtils). */
 export interface UtilsSchema extends SchemaBase {
   type: 'utils';
-  /** Optional binding — empty means a shared public module. */
+  /** Backend binding — the api module this utils belongs to (shared instance
+   *  from project.config.ts apis). With `app` it serves that frontend
+   *  ({api}/{app}/utils/); alone it is the api's public module
+   *  ({api}/common/utils/). Unset = not backend-side. */
+  api?: ProjectApiSchema;
+  /** Optional binding — the frontend app this utils serves (shared instance
+   *  from project.config.ts apps). Empty means a shared public module. */
   app?: FrontAppSchema;
   /** Methods keyed by name — the map key is written back as the method name. */
   methods: Record<string, UtilsMethodSchema>;
@@ -30,14 +36,19 @@ export interface UtilsSchema extends SchemaBase {
 
 export function defineUtils(options: {
   name: string;
+  api?: ProjectApiSchema;
   app?: FrontAppSchema;
   methods: Record<string, UtilsMethodDef>;
   description?: string;
 }): UtilsSchema {
+  if (options.api !== undefined && options.app !== undefined && !options.api.apps.includes(options.app)) {
+    throw new Error(`utils ${options.name}: api '${options.api.name}' does not serve app '${options.app.name}'`);
+  }
   const schema: UtilsSchema = {
     type: 'utils',
     name: options.name,
     description: options.description,
+    api: options.api,
     app: options.app,
     methods: {},
   };

package/src/endpoint.ts

@@ -1,18 +0,0 @@
-import { SchemaBase } from './dsl.js';
-import type { DtoMessage } from './dto.js';
-
-/** Shared API call signature: one request DTO in, one response shape out.
- *  Referenced by both backend controller methods and frontend page providers —
- *  both sides must use the exact same instance, so drift is impossible. */
-export interface EndpointSchema extends SchemaBase {
-  type: 'endpoint';
-  args: DtoMessage;
-  results: DtoMessage | number | boolean | string;
-}
-
-export function defineEndpoint(
-  name: string,
-  options: { args: DtoMessage; results: DtoMessage | number | boolean | string; description?: string },
-): EndpointSchema {
-  return { type: 'endpoint', name, args: options.args, results: options.results, description: options.description };
-}

package/src/provider.ts

@@ -1,68 +0,0 @@
-import type { ImportBase } from './import-base.js';
-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 { EndpointSchema } from './endpoint.js';
-
-// ProviderSchema: an API function signature (args DTO + results DTO).
-
-/** Parameter data source for a call argument. */
-export type DataRef =
-  | { type: 'route'; key: string }
-  | { type: 'data';  key: string }
-  | { type: 'value'; value: unknown };
-
-/** Create a route-parameter reference. */
-export function route(key: string): DataRef {
-  return { type: 'route', key };
-}
-
-/** Create a page-data reference. */
-export function data(key: string): DataRef {
-  return { type: 'data', key };
-}
-
-export interface CallAction extends ActionSchema {
-  type: 'call';
-  func: ProviderSchema;
-  args?: Record<string, DtoField | DtoMessage | DtoArrayField | DtoObjectField | RefSchema | string>;
-}
-
-
-export function call(func: ProviderSchema, args?: Record<string, DtoField | DtoMessage | DtoArrayField | DtoObjectField | RefSchema | string>): CallAction {
-  return { name: func.name, type: 'call', func, args };
-}
-
-/** Provider function signature. The generated API client exposes one function
- *  per endpoint; ProviderSchema gives that function a name and a shared signature. */
-export interface ProviderSchema extends ImportableSchemaBase {
-  isAsync: boolean;
-  /** Shared API signature — same instance the backend controller method references. */
-  signature: EndpointSchema;
-}
-
-/** Define a provider function. */
-export function defineProvider(
-  name: string,
-  schema: {
-    isAsync: boolean;
-    signature: EndpointSchema;
-    description?: string;
-    importRef?: ImportBase;
-  },
-): ProviderSchema {
-  return { name, ...schema };
-}
-
-/** Assign a call's result to a page data field.
- *  React: setState({ [field]: await ... }). Mini-program: this.setData({ [field]: ... }). */
-export interface SetDataAction extends ActionSchema {
-  type: 'setData';
-  call: CallAction;
-  field: DtoField;
-}
-
-export function setData(call: CallAction, field: DtoField): SetDataAction {
-  return { name: 'setData', type: 'setData', call, field };
-}