@sincpro/client-framework 1.0.0 → 1.1.0

package/dist/circuit_breaker/domain/circuit.d.ts

@@ -0,0 +1,29 @@
+import type { FailureKind } from "@sincpro/criteria";
+/**
+ * Where a circuit stands — for a health screen or a test; a call never needs it.
+ *
+ * - `closed`: calls go through.
+ * - `open`: calls fail at once (`CircuitOpen`) until its time passes.
+ * - `half_open`: its time passed; one call goes through to try, the others still fail at once.
+ */
+export type CircuitState = "closed" | "open" | "half_open";
+/**
+ * The kinds a circuit counts by default — the backend's `COUNTED`: the dependency did not answer,
+ * may not have, asked to be left alone, or failed in a way nobody declared. Every other kind is
+ * an answer: a refusal is the dependency working.
+ */
+export declare const COUNTED_KINDS: ReadonlySet<FailureKind>;
+/** Whether a failure says the dependency is not answering — not what it answered. */
+export declare function countedByDefault(error: unknown): boolean;
+/**
+ * The dependency a circuit guards failed too often: the call was not made. It declares itself
+ * `unavailable` with its wait, so a retry, a stored queue and a screen already know what to do.
+ */
+export declare class CircuitOpen extends Error {
+    readonly circuit: string;
+    static readonly failureKind = "unavailable";
+    readonly reason = "CIRCUIT_OPEN";
+    /** Seconds to wait before trying again — one at least. */
+    readonly retryAfter: number;
+    constructor(circuit: string, retryAfterSeconds: number);
+}

package/dist/circuit_breaker/domain/circuit.js

@@ -0,0 +1,37 @@
+import { failureOf } from "../../common/failures.js";
+/**
+ * The kinds a circuit counts by default — the backend's `COUNTED`: the dependency did not answer,
+ * may not have, asked to be left alone, or failed in a way nobody declared. Every other kind is
+ * an answer: a refusal is the dependency working.
+ */
+export const COUNTED_KINDS = new Set([
+    "unavailable",
+    "unknown_outcome",
+    "exhausted",
+    "internal",
+]);
+/** Whether a failure says the dependency is not answering — not what it answered. */
+export function countedByDefault(error) {
+    const failure = failureOf(error);
+    return !failure.aborted && COUNTED_KINDS.has(failure.kind);
+}
+/** The least wait a refused call is told: a clock that rounds to nothing never says «now». */
+const LEAST_RETRY_AFTER = 1;
+/**
+ * The dependency a circuit guards failed too often: the call was not made. It declares itself
+ * `unavailable` with its wait, so a retry, a stored queue and a screen already know what to do.
+ */
+export class CircuitOpen extends Error {
+    circuit;
+    static failureKind = "unavailable";
+    reason = "CIRCUIT_OPEN";
+    /** Seconds to wait before trying again — one at least. */
+    retryAfter;
+    constructor(circuit, retryAfterSeconds) {
+        const retryAfter = Math.max(LEAST_RETRY_AFTER, Math.ceil(retryAfterSeconds));
+        super(`circuit ${circuit} is open — the call was not made; try again in ${retryAfter}s`);
+        this.circuit = circuit;
+        this.name = "CircuitOpen";
+        this.retryAfter = retryAfter;
+    }
+}

package/dist/circuit_breaker/entrypoint/circuit-breaker.d.ts

@@ -0,0 +1,56 @@
+import { type CircuitState } from "../domain/circuit.js";
+export type CircuitBreakerOptions = {
+    /** Consecutive counted failures that open it (5). */
+    readonly failures?: number;
+    /** How long it stays open before it lets one call try, in ms (30 s). */
+    readonly openFor?: number;
+    /** What counts as the dependency not answering (`countedByDefault`). */
+    readonly counts?: (error: unknown) => boolean;
+    /** Milliseconds since the epoch — what a test moves by hand (`Date.now`). */
+    readonly clock?: () => number;
+};
+/**
+ * Stops calling a dependency that fails repeatedly, and tries it again once it may be back — the
+ * backend's `CircuitBreaker`, in this process's memory.
+ *
+ *     const odoo = new CircuitBreaker("odoo", { failures: 3, openFor: 60_000 });
+ *     await odoo.call(() => client.callModel("sale.order", "create", values));
+ *     const send = odoo.wrap(sendInvoice);                 // the same, as a function
+ *     const transport = guardedTransport(restTransport({ base }), odoo);
+ *
+ * Context: a phone without coverage or a backend that is down answers every call slowly with the
+ * same failure; trying it again at once only spends battery and blocks what waits. After
+ * `failures` counted failures in a row it opens: calls fail at once with `CircuitOpen` —
+ * `unavailable`, with the time left as its `retryAfter` —, which `failureOf`, a stored queue and a
+ * screen already handle. Once `openFor` passed, one call tries (half-open): an answer closes it,
+ * a counted failure opens it again. A refusal (`domain`, `not_found`…) is an answer and never
+ * counts. Each process keeps its own circuit: a tab, the app.
+ */
+export declare class CircuitBreaker {
+    readonly name: string;
+    private readonly failures;
+    private readonly openFor;
+    private readonly counts;
+    private readonly clock;
+    private streak;
+    private openedAt;
+    private probing;
+    constructor(name: string, options?: CircuitBreakerOptions);
+    /** Where it stands now. */
+    state(): CircuitState;
+    /** Closed again, as if it never failed — what an operator or a test does. */
+    reset(): void;
+    /**
+     * `work` run through the circuit.
+     *
+     * 1. Open: refused at once (`CircuitOpen`, the time left as its wait); half-open with a call
+     *    already trying: refused, a second's wait.
+     * 2. Run. An answer — or a failure that does not count — closes it.
+     * 3. A counted failure: half-open, it opens again; closed, one more in the streak, and at
+     *    `failures` it opens.
+     * Final: what `work` answered, or what it failed with.
+     */
+    call<T>(work: () => T | Promise<T>): Promise<T>;
+    /** `fn`, every call of it through the circuit. */
+    wrap<A extends unknown[], T>(fn: (...args: A) => T | Promise<T>): (...args: A) => Promise<T>;
+}

package/dist/circuit_breaker/entrypoint/circuit-breaker.js

@@ -0,0 +1,94 @@
+import { CircuitOpen, countedByDefault, } from "../domain/circuit.js";
+/**
+ * Stops calling a dependency that fails repeatedly, and tries it again once it may be back — the
+ * backend's `CircuitBreaker`, in this process's memory.
+ *
+ *     const odoo = new CircuitBreaker("odoo", { failures: 3, openFor: 60_000 });
+ *     await odoo.call(() => client.callModel("sale.order", "create", values));
+ *     const send = odoo.wrap(sendInvoice);                 // the same, as a function
+ *     const transport = guardedTransport(restTransport({ base }), odoo);
+ *
+ * Context: a phone without coverage or a backend that is down answers every call slowly with the
+ * same failure; trying it again at once only spends battery and blocks what waits. After
+ * `failures` counted failures in a row it opens: calls fail at once with `CircuitOpen` —
+ * `unavailable`, with the time left as its `retryAfter` —, which `failureOf`, a stored queue and a
+ * screen already handle. Once `openFor` passed, one call tries (half-open): an answer closes it,
+ * a counted failure opens it again. A refusal (`domain`, `not_found`…) is an answer and never
+ * counts. Each process keeps its own circuit: a tab, the app.
+ */
+export class CircuitBreaker {
+    name;
+    failures;
+    openFor;
+    counts;
+    clock;
+    streak = 0;
+    openedAt;
+    probing = false;
+    constructor(name, options = {}) {
+        this.name = name;
+        this.failures = options.failures ?? 5;
+        this.openFor = options.openFor ?? 30_000;
+        this.counts = options.counts ?? countedByDefault;
+        this.clock = options.clock ?? Date.now;
+        if (!Number.isInteger(this.failures) || this.failures < 1) {
+            throw new TypeError(`circuit ${name}: failures must be 1 or more`);
+        }
+        if (!(this.openFor > 0))
+            throw new TypeError(`circuit ${name}: openFor must be some time`);
+    }
+    /** Where it stands now. */
+    state() {
+        if (this.openedAt === undefined)
+            return "closed";
+        return this.clock() < this.openedAt + this.openFor ? "open" : "half_open";
+    }
+    /** Closed again, as if it never failed — what an operator or a test does. */
+    reset() {
+        this.streak = 0;
+        this.openedAt = undefined;
+        this.probing = false;
+    }
+    /**
+     * `work` run through the circuit.
+     *
+     * 1. Open: refused at once (`CircuitOpen`, the time left as its wait); half-open with a call
+     *    already trying: refused, a second's wait.
+     * 2. Run. An answer — or a failure that does not count — closes it.
+     * 3. A counted failure: half-open, it opens again; closed, one more in the streak, and at
+     *    `failures` it opens.
+     * Final: what `work` answered, or what it failed with.
+     */
+    async call(work) {
+        const state = this.state();
+        if (state === "open") {
+            throw new CircuitOpen(this.name, ((this.openedAt ?? 0) + this.openFor - this.clock()) / 1000);
+        }
+        const probe = state === "half_open";
+        if (probe && this.probing)
+            throw new CircuitOpen(this.name, 1);
+        if (probe)
+            this.probing = true;
+        try {
+            const answer = await work();
+            this.reset();
+            return answer;
+        }
+        catch (error) {
+            if (!this.counts(error)) {
+                if (probe)
+                    this.reset();
+                throw error;
+            }
+            this.probing = false;
+            this.streak += 1;
+            if (probe || this.streak >= this.failures)
+                this.openedAt = this.clock();
+            throw error;
+        }
+    }
+    /** `fn`, every call of it through the circuit. */
+    wrap(fn) {
+        return (...args) => this.call(() => fn(...args));
+    }
+}

package/dist/circuit_breaker/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Circuit breaker: stop calling a dependency that fails repeatedly, and try it again once it may
+ * be back — as sincpro_framework's `circuit_breaker`.
+ *
+ *   domain/      CircuitState, CircuitOpen, what counts as the dependency not answering
+ *   entrypoint/  CircuitBreaker
+ */
+export { CircuitOpen, type CircuitState, COUNTED_KINDS, countedByDefault, } from "./domain/circuit.js";
+export { CircuitBreaker, type CircuitBreakerOptions, } from "./entrypoint/circuit-breaker.js";

package/dist/circuit_breaker/index.js

@@ -0,0 +1,9 @@
+/**
+ * Circuit breaker: stop calling a dependency that fails repeatedly, and try it again once it may
+ * be back — as sincpro_framework's `circuit_breaker`.
+ *
+ *   domain/      CircuitState, CircuitOpen, what counts as the dependency not answering
+ *   entrypoint/  CircuitBreaker
+ */
+export { CircuitOpen, COUNTED_KINDS, countedByDefault, } from "./domain/circuit.js";
+export { CircuitBreaker, } from "./entrypoint/circuit-breaker.js";

package/dist/client/adapters/json-rpc.d.ts

@@ -0,0 +1,40 @@
+import { type OperationTransport } from "../domain/operation.js";
+import { type FailureKind, type Problem } from "@sincpro/criteria";
+export type JsonRpcOptions = {
+    /** Where the gateway answers: `"/rpc"`, `"https://forge.sincpro.com.bo/rpc"`. */
+    endpoint: string;
+    /** Sent with every request. A function is called fresh each time — a token that rotates. */
+    headers?: Record<string, string> | (() => Record<string, string>);
+    /** Defaults to the global `fetch`. Inject one for tests, or a platform's. */
+    fetch?: typeof fetch;
+};
+/**
+ * A JSON-RPC call that failed: the error the gateway answered — its `code` and, when it sent
+ * one, its `Problem` — or a request nobody answered (`code: null`). `failureOf` reads its
+ * `Problem`; without one, the kind its code stands for (`kindOfJsonRpcCode`).
+ */
+export declare class JsonRpcError extends Error {
+    readonly method: string;
+    readonly code: number | null;
+    readonly problem: Problem | null;
+    /** Declared only when the gateway sent no `Problem` — the `Problem` says more when it did. */
+    readonly failureKind: FailureKind | undefined;
+    constructor(method: string, code: number | null, problem: Problem | null, message?: string);
+}
+/**
+ * Operations over JSON-RPC 2.0, as sincpro_framework's RPC gateway publishes them: one `POST` to
+ * its endpoint, the operation's method (`operation.rpc.method`) with its input as named params.
+ *
+ *     const operations = jsonRpcOperations({ endpoint: "/rpc", headers: () => session() });
+ *     const forge = clientOf(operations);
+ *
+ * 1. The operation's JSON-RPC binding; none: `OperationNotPublished`.
+ * 2. The request — `{jsonrpc: "2.0", id, method, params}` — with the call's headers (the run's
+ *    trace and context) and the gesture's `Idempotency-Key`, cancelled with its signal.
+ * 3. An answer with `error`: a `JsonRpcError` with its code and the `Problem` its `data` carries
+ *    (its `message` the detail when the problem has none).
+ * 4. No answer (the network, an `AbortError` aside): a `JsonRpcError` nobody answered — it may
+ *    have run.
+ * Final: the `result`, the operation's answer as the contract describes it.
+ */
+export declare function jsonRpcOperations(options: JsonRpcOptions): OperationTransport;

package/dist/client/adapters/json-rpc.js

@@ -0,0 +1,97 @@
+import { OperationNotPublished, } from "../domain/operation.js";
+import { kindOfJsonRpcCode } from "../../common/failures.js";
+import { readProblem } from "@sincpro/criteria";
+/**
+ * A JSON-RPC call that failed: the error the gateway answered — its `code` and, when it sent
+ * one, its `Problem` — or a request nobody answered (`code: null`). `failureOf` reads its
+ * `Problem`; without one, the kind its code stands for (`kindOfJsonRpcCode`).
+ */
+export class JsonRpcError extends Error {
+    method;
+    code;
+    problem;
+    /** Declared only when the gateway sent no `Problem` — the `Problem` says more when it did. */
+    failureKind;
+    constructor(method, code, problem, message) {
+        super(message ??
+            problem?.detail ??
+            problem?.title ??
+            `${method} failed (${code ?? "no answer"})`);
+        this.method = method;
+        this.code = code;
+        this.problem = problem;
+        this.name = "JsonRpcError";
+        this.failureKind =
+            problem !== null
+                ? undefined
+                : code === null
+                    ? "unknown_outcome"
+                    : kindOfJsonRpcCode(code);
+    }
+}
+let next = 0;
+/**
+ * Operations over JSON-RPC 2.0, as sincpro_framework's RPC gateway publishes them: one `POST` to
+ * its endpoint, the operation's method (`operation.rpc.method`) with its input as named params.
+ *
+ *     const operations = jsonRpcOperations({ endpoint: "/rpc", headers: () => session() });
+ *     const forge = clientOf(operations);
+ *
+ * 1. The operation's JSON-RPC binding; none: `OperationNotPublished`.
+ * 2. The request — `{jsonrpc: "2.0", id, method, params}` — with the call's headers (the run's
+ *    trace and context) and the gesture's `Idempotency-Key`, cancelled with its signal.
+ * 3. An answer with `error`: a `JsonRpcError` with its code and the `Problem` its `data` carries
+ *    (its `message` the detail when the problem has none).
+ * 4. No answer (the network, an `AbortError` aside): a `JsonRpcError` nobody answered — it may
+ *    have run.
+ * Final: the `result`, the operation's answer as the contract describes it.
+ */
+export function jsonRpcOperations(options) {
+    const send = options.fetch ?? ((...args) => fetch(...args));
+    const own = () => typeof options.headers === "function" ? options.headers() : options.headers;
+    return {
+        async call(operation, input, call = {}) {
+            const method = operation.rpc?.method;
+            if (method === undefined)
+                throw new OperationNotPublished(operation.identity, "JSON-RPC");
+            const id = ++next;
+            let response;
+            try {
+                response = await send(options.endpoint, {
+                    method: "POST",
+                    headers: {
+                        "Content-Type": "application/json",
+                        Accept: "application/json",
+                        ...own(),
+                        ...call.headers,
+                        ...(call.idempotencyKey ? { "Idempotency-Key": call.idempotencyKey } : {}),
+                    },
+                    body: JSON.stringify({ jsonrpc: "2.0", id, method, params: input ?? {} }),
+                    ...(call.signal ? { signal: call.signal } : {}),
+                });
+            }
+            catch (error) {
+                if (error?.name === "AbortError")
+                    throw error;
+                throw new JsonRpcError(method, null, null, `${method} got no answer`);
+            }
+            const text = await response.text();
+            let answer;
+            try {
+                answer = JSON.parse(text);
+            }
+            catch {
+                throw new JsonRpcError(method, null, readProblem(text), `${method} answered no JSON-RPC`);
+            }
+            if (answer.error !== undefined) {
+                const { code, message, data } = answer.error;
+                const said = typeof message === "string" ? message : undefined;
+                const problem = readProblem(data);
+                throw new JsonRpcError(method, typeof code === "number" ? code : null, problem && problem.detail === undefined && said
+                    ? { ...problem, detail: said }
+                    : problem, said);
+            }
+            return answer.result;
+        },
+    };
+}

package/dist/client/adapters/rest-operations.d.ts

@@ -0,0 +1,19 @@
+import { type OperationTransport } from "../domain/operation.js";
+import { type Transport } from "../domain/transport.js";
+/**
+ * Operations over REST, as sincpro_framework's REST gateway publishes them — on a `Transport`
+ * (`restTransport`, `memoryTransport`, a platform's):
+ *
+ *     const operations = restOperations(restTransport({ base: "/v1", headers: session }));
+ *     const forge = clientOf(operations);
+ *
+ * 1. The operation's REST binding (`operation.rest`); none: `OperationNotPublished`.
+ * 2. Each `{field}` of its path taken from the input.
+ * 3. A `GET` — a Query — sends every other field as its query (text as it is, `criteria` and any
+ *    other value as JSON) and reads the answer as it came; one that answers bytes (`streamed`,
+ *    an export) is downloaded.
+ * 4. Anything else — a Command — sends the input as its body, with the gesture's
+ *    `Idempotency-Key`.
+ * Final: the operation's answer, as the contract describes it.
+ */
+export declare function restOperations(transport: Transport): OperationTransport;

package/dist/client/adapters/rest-operations.js

@@ -0,0 +1,66 @@
+import { OperationNotPublished, } from "../domain/operation.js";
+import { downloadRoute, readRoute, } from "../domain/transport.js";
+const PATH_KEY = /\{([A-Za-z_][A-Za-z0-9_]*)\}/g;
+/** What a value is in a query string: text as it is, anything else as JSON (`criteria`). */
+function queryValue(value) {
+    return typeof value === "string" ? value : JSON.stringify(value);
+}
+/** The path with each `{field}` taken from the input, and the input's fields it did not take. */
+function placed(operation, path, input) {
+    const rest = { ...input };
+    const route = path.replace(PATH_KEY, (_whole, name) => {
+        const value = input[name];
+        if (value === undefined || value === null || value === "")
+            throw new TypeError(`${operation.identity} needs "${name}" for ${path}`);
+        delete rest[name];
+        return encodeURIComponent(String(value));
+    });
+    return { route, rest };
+}
+/** The route with every other field of a GET as its query. */
+function withQuery(route, fields) {
+    const query = new URLSearchParams(Object.entries(fields)
+        .filter(([, value]) => value !== undefined && value !== null && value !== "")
+        .map(([name, value]) => [name, queryValue(value)])).toString();
+    return query === "" ? route : `${route}${route.includes("?") ? "&" : "?"}${query}`;
+}
+/**
+ * Operations over REST, as sincpro_framework's REST gateway publishes them — on a `Transport`
+ * (`restTransport`, `memoryTransport`, a platform's):
+ *
+ *     const operations = restOperations(restTransport({ base: "/v1", headers: session }));
+ *     const forge = clientOf(operations);
+ *
+ * 1. The operation's REST binding (`operation.rest`); none: `OperationNotPublished`.
+ * 2. Each `{field}` of its path taken from the input.
+ * 3. A `GET` — a Query — sends every other field as its query (text as it is, `criteria` and any
+ *    other value as JSON) and reads the answer as it came; one that answers bytes (`streamed`,
+ *    an export) is downloaded.
+ * 4. Anything else — a Command — sends the input as its body, with the gesture's
+ *    `Idempotency-Key`.
+ * Final: the operation's answer, as the contract describes it.
+ */
+export function restOperations(transport) {
+    return {
+        call(operation, input, options = {}) {
+            const rest = operation.rest;
+            if (rest === undefined)
+                return Promise.reject(new OperationNotPublished(operation.identity, "REST"));
+            const { signal, ...call } = options;
+            const fields = (input ?? {});
+            try {
+                const { route, rest: others } = placed(operation, rest.path, fields);
+                if (rest.method === "GET") {
+                    const asked = withQuery(route, others);
+                    return operation.streamed
+                        ? downloadRoute(transport, asked, signal, call)
+                        : readRoute(transport, asked, signal, call);
+                }
+                return transport.send(rest.method, route, fields, signal, call);
+            }
+            catch (error) {
+                return Promise.reject(error);
+            }
+        },
+    };
+}

package/dist/client/domain/operation.d.ts

@@ -0,0 +1,73 @@
+import type { SendOptions } from "./transport.js";
+/**
+ * One operation of a remote service, as its client contract names it: who it is, what it does
+ * for its entities, and how each wire reaches it. What a generated client's `operations` holds,
+ * one entry per Command or Query the backend publishes.
+ *
+ *     {
+ *       identity: "sincpro-forge-project.CommandSendIssue",
+ *       role: "command", query: false, entities: ["Issue"], targets: { Issue: "issue_id" },
+ *       rest: { method: "POST", path: "/issues/{issue_id}/messages" },
+ *       rpc: { method: "project.send_issue" },
+ *     }
+ */
+export type RemoteOperation = {
+    /** `<bounded context>.<Command>`: the same on every wire. */
+    readonly identity: string;
+    /** What it is for its entity: `search`, `get`, `edit`, `export`, `command`… */
+    readonly role: string;
+    /** It writes nothing: retrying or caching it is safe. */
+    readonly query: boolean;
+    readonly entities: readonly string[];
+    readonly targets: Readonly<Record<string, string>>;
+    /** It answers bytes as they are produced (an export), not JSON. */
+    readonly streamed?: boolean;
+    readonly rest?: {
+        readonly method: string;
+        readonly path: string;
+    };
+    readonly rpc?: {
+        readonly method: string;
+    };
+    readonly grpc?: {
+        readonly method: string;
+    };
+    readonly mcp?: {
+        readonly tool: string;
+    };
+};
+/**
+ * What one call carries besides its input: its headers (the run's trace and context), what
+ * cancels it, and — for a write — the gesture's idempotency key.
+ */
+export type OperationOptions = SendOptions & {
+    signal?: AbortSignal;
+};
+/**
+ * Calls an operation of a remote service by who it is — the port every wire implements, and
+ * what a generated client is made over:
+ *
+ *     clientOf(restOperations(restTransport({ base: "/v1" })));    // REST
+ *     clientOf(jsonRpcOperations({ endpoint: "/rpc" }));          // JSON-RPC
+ *     clientOf(grpcOperations(channel));                          // gRPC — a platform's adapter
+ *
+ * Context: the contract publishes each operation once, with how every wire reaches it; the
+ * generated client names only the operation and its input, never a route, a verb or a method.
+ * Which wire it travels on is the adapter an application injects — the backend's, another
+ * backend's, a platform's —, so the same client and the same Features run over any of them. An
+ * adapter answers the operation's answer as the contract describes it, and fails with errors
+ * `failureOf` reads (a `Problem`, or a declared `failureKind`).
+ */
+export interface OperationTransport {
+    call<T>(operation: RemoteOperation, input: unknown, options?: OperationOptions): Promise<T>;
+}
+/** An operation the wire an adapter speaks does not publish: a client asked for what is not there. */
+export declare class OperationNotPublished extends Error {
+    readonly operation: string;
+    readonly wire: string;
+    static readonly failureKind = "not_found";
+    readonly reason = "OPERATION_NOT_PUBLISHED";
+    constructor(operation: string, wire: string);
+}
+/** Whether a value is an `OperationTransport`: what a run binds to itself even without `BIND`. */
+export declare function isOperationTransport(value: unknown): value is OperationTransport;

package/dist/client/domain/operation.js

@@ -0,0 +1,19 @@
+/** An operation the wire an adapter speaks does not publish: a client asked for what is not there. */
+export class OperationNotPublished extends Error {
+    operation;
+    wire;
+    static failureKind = "not_found";
+    reason = "OPERATION_NOT_PUBLISHED";
+    constructor(operation, wire) {
+        super(`${operation} is not published over ${wire}: its contract has no ${wire} binding`);
+        this.operation = operation;
+        this.wire = wire;
+        this.name = "OperationNotPublished";
+    }
+}
+/** Whether a value is an `OperationTransport`: what a run binds to itself even without `BIND`. */
+export function isOperationTransport(value) {
+    return (value !== null &&
+        typeof value === "object" &&
+        typeof value.call === "function");
+}

package/dist/client/index.d.ts

@@ -7,10 +7,14 @@
  *   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 { bindable, bindTransport, headersOf, } from "./services/propagation.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

@@ -7,10 +7,14 @@
  *   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 { bindable, bindTransport, headersOf, } from "./services/propagation.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;
+}