@sincpro/client-framework 0.6.0 → 1.1.0

package/dist/client/index.d.ts

@@ -0,0 +1,20 @@
+/**
+ * The seam with a server: the `Transport` port and its implementations, entities with typed
+ * commands, the service's client contract, and how a run's trace and context reach the wire.
+ *
+ *   domain/    the port and the server's words: `Transport`, `TransportError`, `entity()`, the
+ *              client contract
+ *   adapters/  REST, memory, and Parquet (optional entry `./parquet`)
+ *   services/  discovery, retry keys, propagation (`traceparent`, `sincpro-context`)
+ */
+export { JsonRpcError, jsonRpcOperations, type JsonRpcOptions, } from "./adapters/json-rpc.js";
+export { type MemoryOptions, type MemoryTable, memoryTransport, } from "./adapters/memory.js";
+export { type RestOptions, restTransport, urlOf, type VersionDrift, } from "./adapters/rest.js";
+export { restOperations } from "./adapters/rest-operations.js";
+export { type ClientContract, entityKeyOf, kindOf, metasOf, versionsOf, } from "./domain/contract.js";
+export { bodyFor, type CommandAnswers, type CommandBodies, type CommandRoute, type Entity, entity, type EntityRef, type EntityRoutes, type ExportFormat, exportRoute, listRoute, NEW_PARAM, pathFor, PICK_PARAM, QUERY_PARAM, SCOPE_PARAM, scopeOfRef, startingValuesOf, type SummaryFields, type SummaryPart, TRAIL_PARAM, WITH_PARAM, type WriteRoute, writeRoute, } from "./domain/entity.js";
+export { OperationNotPublished, type OperationOptions, type OperationTransport, type RemoteOperation, } from "./domain/operation.js";
+export { type CallOptions, type Decoder, type Download, downloadRoute, type Draft, type Method, type One, readRoute, type SendOptions, type Transport, TransportError, } from "./domain/transport.js";
+export { guardedTransport } from "./services/guarded.js";
+export { bindable, bindOperations, bindTransport, headersOf, } from "./services/propagation.js";
+export { type RetryKeys, retryKeys, unanswered, } from "./services/retry.js";

package/dist/client/index.js

@@ -0,0 +1,20 @@
+/**
+ * The seam with a server: the `Transport` port and its implementations, entities with typed
+ * commands, the service's client contract, and how a run's trace and context reach the wire.
+ *
+ *   domain/    the port and the server's words: `Transport`, `TransportError`, `entity()`, the
+ *              client contract
+ *   adapters/  REST, memory, and Parquet (optional entry `./parquet`)
+ *   services/  discovery, retry keys, propagation (`traceparent`, `sincpro-context`)
+ */
+export { JsonRpcError, jsonRpcOperations, } from "./adapters/json-rpc.js";
+export { memoryTransport, } from "./adapters/memory.js";
+export { restTransport, urlOf, } from "./adapters/rest.js";
+export { restOperations } from "./adapters/rest-operations.js";
+export { entityKeyOf, kindOf, metasOf, versionsOf, } from "./domain/contract.js";
+export { bodyFor, entity, exportRoute, listRoute, NEW_PARAM, pathFor, PICK_PARAM, QUERY_PARAM, SCOPE_PARAM, scopeOfRef, startingValuesOf, TRAIL_PARAM, WITH_PARAM, writeRoute, } from "./domain/entity.js";
+export { OperationNotPublished, } from "./domain/operation.js";
+export { downloadRoute, readRoute, TransportError, } from "./domain/transport.js";
+export { guardedTransport } from "./services/guarded.js";
+export { bindable, bindOperations, bindTransport, headersOf, } from "./services/propagation.js";
+export { retryKeys, unanswered, } from "./services/retry.js";

package/dist/client/services/guarded.d.ts

@@ -0,0 +1,17 @@
+import type { CircuitBreaker } from "../../circuit_breaker/entrypoint/circuit-breaker.js";
+import { type OperationTransport } from "../domain/operation.js";
+import type { Transport } from "../domain/transport.js";
+/**
+ * `transport`, every call through `breaker` — an `OperationTransport` of any wire, or REST's
+ * `Transport`:
+ *
+ *     const operations = guardedTransport(jsonRpcOperations({ endpoint }), new CircuitBreaker("forge"));
+ *     project.addDependency("client", clientOf(operations));
+ *
+ * Context: the circuit belongs where the dependency is — the transport —, not in each Feature. A
+ * run binds it as it binds any transport, so the trace and the context still travel; an open
+ * circuit fails at once with `CircuitOpen` (`unavailable`, with its wait), which the outcome, a
+ * stored queue and a screen already read.
+ */
+export declare function guardedTransport(transport: OperationTransport, breaker: CircuitBreaker): OperationTransport;
+export declare function guardedTransport(transport: Transport, breaker: CircuitBreaker): Transport;

package/dist/client/services/guarded.js

@@ -0,0 +1,19 @@
+import { isOperationTransport, } from "../domain/operation.js";
+export function guardedTransport(transport, breaker) {
+    if (isOperationTransport(transport))
+        return {
+            call: (operation, input, options) => breaker.call(() => transport.call(operation, input, options)),
+        };
+    const guarded = {
+        list: (route, criteria, signal, options) => breaker.call(() => transport.list(route, criteria, signal, options)),
+        one: (route, signal, options) => breaker.call(() => transport.one(route, signal, options)),
+        send: (method, route, body, signal, options) => breaker.call(() => transport.send(method, route, body, signal, options)),
+    };
+    const read = transport.read;
+    if (read !== undefined)
+        guarded.read = (route, signal, options) => breaker.call(() => read.call(transport, route, signal, options));
+    const download = transport.download;
+    if (download !== undefined)
+        guarded.download = (route, signal, options) => breaker.call(() => download.call(transport, route, signal, options));
+    return guarded;
+}

package/dist/client/services/propagation.d.ts

@@ -0,0 +1,45 @@
+import type { OperationTransport } from "../domain/operation.js";
+import type { Transport } from "../domain/transport.js";
+import { type Execution } from "../../context/domain/execution.js";
+/** Whether a value is a `Transport`: what a run binds to itself even without `BIND`. */
+export declare function isTransport(value: unknown): value is Transport;
+/**
+ * What every request of an execution carries: its trace (`traceparent`, W3C) and its context
+ * (`sincpro-context`, the header sincpro_framework's entrances read, written with `plainCodec`).
+ * Nothing when there is no trace and no context that travels.
+ */
+export declare function headersOf(execution: Execution): Record<string, string>;
+/**
+ * The transport, writing the execution's headers on every call — the caller's own headers of a
+ * call still win.
+ *
+ * Context: the transport's own headers (`restTransport({ headers })`) are the session's — the
+ * token, the tenant — the same for every call; these are the use case's, different for two use
+ * cases running at once, so they travel per call (`CallOptions`). A call that gives no signal of
+ * its own is cancelled with the run.
+ */
+export declare function bindTransport(transport: Transport, execution: Execution): Transport;
+/**
+ * The operation transport, calling as `execution`: every call carries the run's trace and
+ * context as headers and is cancelled with the run — the caller's own headers and signal still
+ * win.
+ */
+export declare function bindOperations(transport: OperationTransport, execution: Execution): OperationTransport;
+/** A transport of either kind, bound to `execution`. */
+export declare function bound<W extends Transport | OperationTransport>(wire: W, execution: Execution): W;
+/**
+ * A client made over a transport, made again over the transport bound to each execution it is
+ * used in. What a generated `clientOf(operations)` answers, so a Feature that calls
+ * `this.client.sendIssue(…)` sends that request with its own trace, context and signal.
+ *
+ *     export function clientOf(operations: OperationTransport) {
+ *       return bindable(operations, (operations) => ({
+ *         sendIssue: (input) => operations.call(operations_.CommandSendIssue, input),
+ *       }));
+ *     }
+ *
+ * Context: it takes the function that makes the client, not the client — rebuilding through
+ * `clientOf` itself would make TypeScript infer `clientOf` from its own return. A REST
+ * `Transport` binds the same way, for a client written over it by hand.
+ */
+export declare function bindable<W extends Transport | OperationTransport, T extends object>(wire: W, make: (wire: W) => T): T;

package/dist/{services/execution.js → client/services/propagation.js}

@@ -1,16 +1,8 @@
-import { CONTEXT_HEADER, plainCodec, travels } from "../context/codec.js";
-/**
- * A dependency that has something to say about the execution it is used in: given that
- * execution, it answers itself bound to it. The transport and every generated client are;
- * any other dependency of a bounded context is handed as it is.
- */
-export const BIND = Symbol.for("sincpro.client-framework.bind");
-function isBindable(value) {
-    return (value !== null &&
-        (typeof value === "object" || typeof value === "function") &&
-        typeof value[BIND] === "function");
-}
-function isTransport(value) {
+import { plainCodec } from "../../context/adapters/plain-codec.js";
+import { CONTEXT_HEADER, travels } from "../../context/domain/codec.js";
+import { BIND } from "../../context/domain/execution.js";
+/** Whether a value is a `Transport`: what a run binds to itself even without `BIND`. */
+export function isTransport(value) {
     if (value === null || typeof value !== "object")
         return false;
     const one = value;
@@ -43,51 +35,72 @@ export function headersOf(execution) {
  *
  * Context: the transport's own headers (`restTransport({ headers })`) are the session's — the
  * token, the tenant — the same for every call; these are the use case's, different for two use
- * cases running at once, so they travel per call (`CallOptions`).
+ * cases running at once, so they travel per call (`CallOptions`). A call that gives no signal of
+ * its own is cancelled with the run.
  */
 export function bindTransport(transport, execution) {
     const own = headersOf(execution);
-    if (Object.keys(own).length === 0)
+    const cancels = execution.signal;
+    if (Object.keys(own).length === 0 && cancels === undefined)
         return transport;
     const call = (options) => ({ ...options, headers: { ...own, ...options?.headers } });
     const bound = {
-        list: (route, criteria, signal, options) => transport.list(route, criteria, signal, call(options)),
-        one: (route, signal, options) => transport.one(route, signal, call(options)),
-        send: (method, route, body, signal, options) => transport.send(method, route, body, signal, call(options)),
+        list: (route, criteria, signal, options) => transport.list(route, criteria, signal ?? cancels, call(options)),
+        one: (route, signal, options) => transport.one(route, signal ?? cancels, call(options)),
+        send: (method, route, body, signal, options) => transport.send(method, route, body, signal ?? cancels, call(options)),
     };
     const read = transport.read;
     if (read !== undefined)
-        bound.read = (route, signal, options) => read.call(transport, route, signal, call(options));
+        bound.read = (route, signal, options) => read.call(transport, route, signal ?? cancels, call(options));
     const download = transport.download;
     if (download !== undefined)
-        bound.download = (route, signal, options) => download.call(transport, route, signal, call(options));
+        bound.download = (route, signal, options) => download.call(transport, route, signal ?? cancels, call(options));
     return bound;
 }
+/**
+ * The operation transport, calling as `execution`: every call carries the run's trace and
+ * context as headers and is cancelled with the run — the caller's own headers and signal still
+ * win.
+ */
+export function bindOperations(transport, execution) {
+    const own = headersOf(execution);
+    const cancels = execution.signal;
+    if (Object.keys(own).length === 0 && cancels === undefined)
+        return transport;
+    return {
+        call: (operation, input, options) => transport.call(operation, input, {
+            ...options,
+            headers: { ...own, ...options?.headers },
+            ...((options?.signal ?? cancels) ? { signal: options?.signal ?? cancels } : {}),
+        }),
+    };
+}
+/** A transport of either kind, bound to `execution`. */
+export function bound(wire, execution) {
+    return (isTransport(wire)
+        ? bindTransport(wire, execution)
+        : bindOperations(wire, execution));
+}
 /**
  * A client made over a transport, made again over the transport bound to each execution it is
- * used in. What a generated `clientOf(transport)` answers, so a Feature that calls
- * `this.client.sendIssue(…)` sends that request with its own trace.
+ * used in. What a generated `clientOf(operations)` answers, so a Feature that calls
+ * `this.client.sendIssue(…)` sends that request with its own trace, context and signal.
  *
- *     export function clientOf(transport: Transport) {
- *       return bindable(transport, (transport) => ({ sendIssue: (body) => transport.send(…) }));
+ *     export function clientOf(operations: OperationTransport) {
+ *       return bindable(operations, (operations) => ({
+ *         sendIssue: (input) => operations.call(operations_.CommandSendIssue, input),
+ *       }));
  *     }
  *
  * Context: it takes the function that makes the client, not the client — rebuilding through
- * `clientOf` itself would make TypeScript infer `clientOf` from its own return.
+ * `clientOf` itself would make TypeScript infer `clientOf` from its own return. A REST
+ * `Transport` binds the same way, for a client written over it by hand.
  */
-export function bindable(transport, make) {
-    const client = make(transport);
+export function bindable(wire, make) {
+    const client = make(wire);
     Object.defineProperty(client, BIND, {
-        value: (execution) => bindable(bindTransport(transport, execution), make),
+        value: (execution) => bindable(bound(wire, execution), make),
         enumerable: false,
     });
     return client;
 }
-/** A dependency as the execution should see it: bound when it can be, as it is otherwise. */
-export function bindDependency(value, execution) {
-    if (isBindable(value))
-        return value[BIND](execution);
-    if (isTransport(value))
-        return bindTransport(value, execution);
-    return value;
-}

package/dist/client/{retry.js → services/retry.js}

@@ -1,4 +1,4 @@
-import { TransportError } from "./transport.js";
+import { TransportError } from "../domain/transport.js";
 /** Whether a failure leaves it unknown if the Command ran — so a retry must reuse its key. */
 export function unanswered(error) {
     if (!(error instanceof TransportError))

package/dist/codegen/{metamodel.d.ts → domain/metamodel.d.ts}

@@ -53,6 +53,21 @@ export type Operation = {
     /** The operation that replaces it, by identity. */
     replacement?: string | null;
 };
+/**
+ * A domain event of the bounded context — in a contract exported with its events
+ * (`export-client-contract --events`), keyed by its wire name (`DomainEvent.name`).
+ */
+export type EventDescription = {
+    /** Its class's name on the server: the type it is written as. */
+    title: string;
+    description?: string | null;
+    /** One of the bounded context's own events: its aggregates record it. */
+    recorded: boolean;
+    /** A Feature of the bounded context is registered for it: it subscribes. */
+    handled: boolean;
+    /** Every field it carries — the envelope and what happened —, `name` a constant. */
+    schema: Schema;
+};
 /** How REST reaches an operation: its method and its whole path, `{field}` where a field goes. */
 export type RestBinding = {
     method: string;
@@ -80,14 +95,14 @@ export type Metamodel = {
     /** The name the gateways publish it under (`FastApiGateway({"project": …})`): what a client
      *  names the context by. */
     alias?: string;
-    /** The bounded context's name, as sincpro_framework 3.32 wrote it before `bounded_context`. */
-    context?: string;
     version: string;
     /** Every shape the contract names: an entity (it has an `identity`) or a value it holds. */
     models: Readonly<Record<string, Schema>>;
     /** By the Command's identity, `"<bounded_context>.<Class>"`. */
     operations: Readonly<Record<string, Operation>>;
     $defs?: Readonly<Record<string, Schema>>;
+    /** Its domain events, by wire name — only when the contract was exported with them. */
+    events?: Readonly<Record<string, EventDescription>>;
     /** By wire, then by the Command's identity. */
     bindings?: Bindings;
 };

package/dist/codegen/{names.d.ts → domain/names.d.ts}

@@ -13,7 +13,7 @@ export declare function keyOf(name: string): string;
 export declare function sorted<V>(record: Readonly<Record<string, V>>): [string, V][];
 /** `{ Issue: "issue_id" }`: a record of texts as TypeScript writes it, keys sorted. */
 export declare function recordLiteral(record: Readonly<Record<string, string>>): string;
-/** The bounded context's own name: `bounded_context`, or `context` in a 3.32 contract. */
+/** The bounded context's own name: what every operation's identity starts with. */
 export declare function contextOf(metamodel: Metamodel): string;
 /** What a client names the context by: its `alias`, else its own name. */
 export declare function aliasOf(metamodel: Metamodel): string;
@@ -30,7 +30,7 @@ export declare function localOf(metamodel: Metamodel, identity: string): string;
  *
  * Context: the ubiquitous language. The backend writes `CommandCancelIssue` → `ResponseCancelIssue`,
  * and a client that calls it `CommandCancelIssueAnswer` makes a person learn two words for one
- * thing. The `<Name>Answer` it used to write stays as a deprecated alias of the backend's name.
+ * thing.
  */
 export declare function answerOf(metamodel: Metamodel, identity: string): string;
 /** The method an operation is called by: `CommandSendIssue` → `sendIssue`. */

package/dist/codegen/{names.js → domain/names.js}

@@ -32,9 +32,9 @@ export function recordLiteral(record) {
     const entries = sorted(record).map(([key, value]) => `${keyOf(key)}: ${JSON.stringify(value)}`);
     return entries.length === 0 ? "{}" : `{ ${entries.join(", ")} }`;
 }
-/** The bounded context's own name: `bounded_context`, or `context` in a 3.32 contract. */
+/** The bounded context's own name: what every operation's identity starts with. */
 export function contextOf(metamodel) {
-    const name = metamodel.bounded_context ?? metamodel.context;
+    const name = metamodel.bounded_context;
     if (name === undefined)
         throw new Error("the contract names no bounded context");
     return name;
@@ -100,7 +100,7 @@ function answersOf(metamodel) {
  *
  * Context: the ubiquitous language. The backend writes `CommandCancelIssue` → `ResponseCancelIssue`,
  * and a client that calls it `CommandCancelIssueAnswer` makes a person learn two words for one
- * thing. The `<Name>Answer` it used to write stays as a deprecated alias of the backend's name.
+ * thing.
  */
 export function answerOf(metamodel, identity) {
     let known = ANSWERS.get(metamodel);

package/dist/codegen/{cli.js → entrypoint/cli.js}

@@ -1,19 +1,20 @@
 #!/usr/bin/env node
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
-import { CheckError, checkImports } from "./check.js";
-import { clientFileOf } from "./client.js";
-import { domainFileOf } from "./domain.js";
-import { entitiesFileOf } from "./entities.js";
-import { aliasOf } from "./names.js";
-import { scaffoldFilesOf } from "./scaffold.js";
+import { aliasOf } from "../domain/names.js";
+import { CheckError, checkImports } from "../services/check.js";
+import { clientFileOf } from "../services/client.js";
+import { domainFileOf } from "../services/domain.js";
+import { entitiesFileOf } from "../services/entities.js";
+import { scaffoldFilesOf } from "../services/scaffold.js";
 /**
  * `sincpro-client generate <contract.json> --out <dir> [--domain <name>] [--base <path>]` — what an
  * application's `make client` runs, once per bounded context, over the client contract
  * sincpro_framework exported (`export-client-contract`):
  *
- * - `domain.ts`: the DTOs, only types;
- * - `client.ts`: every operation as data, and `clientOf(transport)`;
+ * - `domain.ts`: the DTOs, only types — and the domain events with `DomainEvent`, their union,
+ *   when the contract was exported with them (`export-client-contract --events`);
+ * - `client.ts`: every operation (and event) as data, and `clientOf(operations)` over any wire;
  * - `entities.ts`: an `entity<T, C>()` per model a screen can list;
  * - `contract.json`: the snapshot they were written from, for `metasOf`.
  *
@@ -25,7 +26,7 @@ import { scaffoldFilesOf } from "./scaffold.js";
  */
 const USAGE = [
     "usage: sincpro-client generate <contract.json> --out <dir> [--domain <name>] [--base <path>]",
-    "       sincpro-client scaffold <contract.json> --out <dir> [--transport <module>]",
+    "       sincpro-client scaffold <contract.json> --out <dir> [--operations <module>]",
     "       sincpro-client check [--root src] [--tsconfig tsconfig.json]",
 ].join("\n");
 /** JSON with every key sorted: the snapshot reads the same however the server ordered it. */
@@ -52,7 +53,7 @@ function parsed(args) {
         flags.set(flag, value);
     }
     const out = flags.get("--out");
-    const known = new Set(command === "generate" ? ["--out", "--domain", "--base"] : ["--out", "--transport"]);
+    const known = new Set(command === "generate" ? ["--out", "--domain", "--base"] : ["--out", "--operations"]);
     if (out === undefined || [...flags.keys()].some((one) => !known.has(one)))
         return undefined;
     const domain = flags.get("--domain");
@@ -65,12 +66,12 @@ function parsed(args) {
             ...(domain === undefined ? {} : { domain }),
             ...(base === undefined ? {} : { base }),
         },
-        transport: flags.get("--transport"),
+        operations: flags.get("--operations"),
     };
 }
 /** The skeleton, each file only when it is not there: what is there is the application's. */
-function scaffold(metamodel, out, transport) {
-    const files = scaffoldFilesOf(metamodel, transport === undefined ? {} : { transport });
+function scaffold(metamodel, out, operations) {
+    const files = scaffoldFilesOf(metamodel, operations === undefined ? {} : { operations });
     const written = [];
     const kept = [];
     for (const [name, source] of Object.entries(files)) {
@@ -127,7 +128,7 @@ function main(args) {
     }
     const metamodel = JSON.parse(readFileSync(asked.source, "utf8"));
     if (asked.command === "scaffold")
-        return scaffold(metamodel, asked.out, asked.transport);
+        return scaffold(metamodel, asked.out, asked.operations);
     const files = { "domain.ts": domainFileOf(metamodel) };
     if (metamodel.bindings !== undefined) {
         files["client.ts"] = clientFileOf(metamodel, asked.options);

package/dist/codegen/index.d.ts

@@ -3,10 +3,10 @@
  * sincpro_framework exports (PRD_01 phase B). A build step that runs in Node — nothing in
  * the runtime imports it (`make doctor`), and the package's root entry does not re-export it. `sincpro-client generate` (`cli.ts`) is the same, from a terminal.
  */
-export { CheckError, checkImports, type Place, placeOf, type Violation, violationOf, } from "./check.js";
-export { clientFileOf } from "./client.js";
-export { domainFileOf } from "./domain.js";
-export { entitiesFileOf } from "./entities.js";
-export type { Bindings, Metamodel, Operation, RestBinding, Schema, } from "./metamodel.js";
-export type { GenerateOptions } from "./rest.js";
-export { scaffoldFilesOf, type ScaffoldOptions, } from "./scaffold.js";
+export type { Bindings, Metamodel, Operation, RestBinding, Schema, } from "./domain/metamodel.js";
+export { CheckError, checkImports, type Place, placeOf, type Violation, violationOf, } from "./services/check.js";
+export { clientFileOf } from "./services/client.js";
+export { domainFileOf } from "./services/domain.js";
+export { entitiesFileOf } from "./services/entities.js";
+export type { GenerateOptions } from "./services/rest.js";
+export { scaffoldFilesOf, type ScaffoldOptions, } from "./services/scaffold.js";

package/dist/codegen/index.js

@@ -1,10 +1,5 @@
-/**
- * The generator: a bounded context's DTOs, client and entities out of the client contract
- * sincpro_framework exports (PRD_01 phase B). A build step that runs in Node — nothing in
- * the runtime imports it (`make doctor`), and the package's root entry does not re-export it. `sincpro-client generate` (`cli.ts`) is the same, from a terminal.
- */
-export { CheckError, checkImports, placeOf, violationOf, } from "./check.js";
-export { clientFileOf } from "./client.js";
-export { domainFileOf } from "./domain.js";
-export { entitiesFileOf } from "./entities.js";
-export { scaffoldFilesOf, } from "./scaffold.js";
+export { CheckError, checkImports, placeOf, violationOf, } from "./services/check.js";
+export { clientFileOf } from "./services/client.js";
+export { domainFileOf } from "./services/domain.js";
+export { entitiesFileOf } from "./services/entities.js";
+export { scaffoldFilesOf, } from "./services/scaffold.js";

package/dist/codegen/services/client.d.ts

@@ -0,0 +1,15 @@
+import type { Metamodel } from "../domain/metamodel.js";
+import { type GenerateOptions } from "./rest.js";
+/**
+ * The TypeScript of the client of `metamodel`, as the text of one file next to its `domain.ts`.
+ *
+ * 1. Every operation, by its local name, as data: identity, role, `query`, entities, targets,
+ *    whether it answers bytes, and the binding of each wire that publishes it.
+ * 2. A method per operation, named by `methodOf`: its input — optional when nothing in it is
+ *    required — and the call's options (headers, signal, idempotency key), answering its answer.
+ * 3. When the contract carries them, every domain event as data, by its type's name: its wire
+ *    name, and whether the bounded context records it or handles it.
+ * Final: `clientOf(transport)` over an `OperationTransport`, bound to each run that uses it; two
+ *    methods with one name are refused, naming both.
+ */
+export declare function clientFileOf(metamodel: Metamodel, options?: GenerateOptions): string;

package/dist/codegen/services/client.js

@@ -0,0 +1,111 @@
+import { aliasOf, answerOf, claimed, deprecationOf, docOf, DOMAIN_MODULE, FRAMEWORK, headerOf, identifierOf, localOf, methodOf, recordLiteral, sorted, } from "../domain/names.js";
+import { restOf, } from "./rest.js";
+/**
+ * The client of a bounded context as TypeScript: every operation as data, and a method for each
+ * one, called by who it is through an `OperationTransport` — so a script, a test, a Feature or a
+ * hook calls the service typed, over whatever wire the application injects.
+ *
+ * Context: the generated client names an operation and its input, never a route, a verb or an
+ * RPC method: those are the contract's bindings, in `operations`, and the adapter reads the one of
+ * its wire (`restOperations`, `jsonRpcOperations`, a platform's gRPC). So the same client, and the
+ * Features that use it, run over REST today and JSON-RPC or gRPC tomorrow without regenerating.
+ * Each method takes the operation's input and answers its answer, as the contract types them
+ * (`domain.ts`).
+ */
+const WIRES = [
+    ["rest", "REST"],
+    ["rpc", "JSON-RPC"],
+    ["grpc", "gRPC"],
+    ["mcp", "MCP"],
+];
+/** The wires that publish an operation, by name. */
+function wiresOf(metamodel, identity) {
+    return WIRES.filter(([wire]) => metamodel.bindings?.[wire]?.[identity] !== undefined).map(([, name]) => name);
+}
+/** Whether an operation answers bytes as they are produced — an export —, not JSON. */
+function isStreamed(operation) {
+    return (operation.output !== null &&
+        operation.output["x-sincpro-streamed"] !== undefined);
+}
+/** The data of one operation: what it is, and how each wire reaches it. */
+function dataOf(metamodel, identity, operation, rest) {
+    const lines = [
+        `    identity: ${JSON.stringify(identity)},`,
+        `    role: ${JSON.stringify(operation.role)},`,
+        `    query: ${operation.query},`,
+        `    entities: ${JSON.stringify(operation.entities)},`,
+        `    targets: ${recordLiteral(operation.targets)},`,
+    ];
+    if (isStreamed(operation))
+        lines.push("    streamed: true,");
+    if (rest !== undefined)
+        lines.push(`    rest: { method: ${JSON.stringify(rest.method)}, path: ${JSON.stringify(rest.path)} },`);
+    const rpc = metamodel.bindings?.rpc?.[identity];
+    if (rpc !== undefined)
+        lines.push(`    rpc: { method: ${JSON.stringify(rpc.method)} },`);
+    const grpc = metamodel.bindings?.grpc?.[identity];
+    if (grpc !== undefined)
+        lines.push(`    grpc: { method: ${JSON.stringify(grpc.method)} },`);
+    const mcp = metamodel.bindings?.mcp?.[identity];
+    if (mcp !== undefined)
+        lines.push(`    mcp: { tool: ${JSON.stringify(mcp.tool)} },`);
+    return `  ${localOf(metamodel, identity)}: {\n${lines.join("\n")}\n  },`;
+}
+/**
+ * The TypeScript of the client of `metamodel`, as the text of one file next to its `domain.ts`.
+ *
+ * 1. Every operation, by its local name, as data: identity, role, `query`, entities, targets,
+ *    whether it answers bytes, and the binding of each wire that publishes it.
+ * 2. A method per operation, named by `methodOf`: its input — optional when nothing in it is
+ *    required — and the call's options (headers, signal, idempotency key), answering its answer.
+ * 3. When the contract carries them, every domain event as data, by its type's name: its wire
+ *    name, and whether the bounded context records it or handles it.
+ * Final: `clientOf(transport)` over an `OperationTransport`, bound to each run that uses it; two
+ *    methods with one name are refused, naming both.
+ */
+export function clientFileOf(metamodel, options = {}) {
+    const claim = claimed();
+    const data = [];
+    const methods = [];
+    for (const [identity, operation] of sorted(metamodel.operations)) {
+        const local = localOf(metamodel, identity);
+        data.push(dataOf(metamodel, identity, operation, restOf(metamodel, identity, options)));
+        const method = methodOf(local);
+        claim(method, `operation ${identity}`);
+        const wires = wiresOf(metamodel, identity);
+        const doc = docOf([
+            operation.description,
+            deprecationOf(metamodel, operation),
+            wires.length === 0 ? undefined : `Published over ${wires.join(", ")}.`,
+        ], "    ");
+        const optional = (operation.input.required ?? []).length === 0;
+        methods.push([
+            `${doc}    ${method}: (input${optional ? "?" : ""}: dto.${local}, options?: OperationOptions) =>`,
+            `      transport.call<dto.${answerOf(metamodel, identity)}>(operations.${local}, input${optional ? " ?? {}" : ""}, options),`,
+        ].join("\n"));
+    }
+    const events = sorted(metamodel.events ?? {}).map(([name, event]) => `  ${identifierOf(event.title)}: { name: ${JSON.stringify(name)}, recorded: ${event.recorded}, handled: ${event.handled} },`);
+    const imports = [
+        `import { bindable, type OperationOptions, type OperationTransport } from "${FRAMEWORK}";`,
+        "",
+        `import type * as dto from "${DOMAIN_MODULE}";`,
+    ].join("\n");
+    const client = [
+        "/**",
+        ` * «${aliasOf(metamodel)}» over any wire: a method per operation, called by who it is. The transport`,
+        " * decides how it travels — `restOperations(restTransport(…))`, `jsonRpcOperations(…)`, a",
+        " * platform's —; used by a Feature, each call carries the run's trace, context and signal.",
+        " */",
+    ].join("\n");
+    return `${[
+        headerOf("The client", metamodel),
+        imports,
+        `/** Every operation of «${aliasOf(metamodel)}», as data: what it is, and how each wire reaches it. */\nexport const operations = {\n${data.join("\n")}\n} as const;`,
+        ...(events.length === 0
+            ? []
+            : [
+                `/** Every domain event of «${aliasOf(metamodel)}» in the contract, as data: its wire name, and whether it records or handles it. */\nexport const events = {\n${events.join("\n")}\n} as const;`,
+            ]),
+        `${client}\nexport function clientOf(transport: OperationTransport) {\n  return bindable(transport, (transport) => ({\n${methods.join("\n")}\n  }));\n}`,
+    ].join("\n\n")}\n`;
+}

package/dist/codegen/services/domain.d.ts

@@ -0,0 +1,20 @@
+import type { Metamodel } from "../domain/metamodel.js";
+/**
+ * The TypeScript of every DTO of `metamodel`, as the text of one file.
+ *
+ * 1. The models, by name: an entity's contract, a related model by its own name.
+ * 2. Each operation, by its local name (its identity without `<context>.`): its input as
+ *    `<Name>` and its answer by the backend's own name for it (`answerOf`: `ResponseX`) — or as
+ *    `<Name>Answer` when it has no name.
+ * 3. A model an input carries — and the ones it carries, until none is new — as `<Name>Input`:
+ *    what a caller sends follows the contract's `required`; the server fills the rest.
+ * 4. Each domain event, when the contract carries them, by its class's name (`title`): a record
+ *    as it is received — every field present, `name` its wire name as a literal —, and
+ *    `DomainEvent`, the union of them all, which a `switch` on `name` narrows.
+ * 5. The shared definitions those reach — and the ones those reach, until none is new —, but
+ *    never one a package of the stack already types (`Criteria`).
+ * Final: a header that says where it came from and not to edit it, the imports, then models,
+ *    definitions, operations and events, each sorted by name; two of them with one TypeScript
+ *    name are refused, naming both.
+ */
+export declare function domainFileOf(metamodel: Metamodel): string;