@sincpro/client-framework 1.0.0 → 1.1.0

package/dist/event_driven/domain/envelope.d.ts

@@ -0,0 +1,28 @@
+import type { DomainEvent } from "../../core/domain/dto.js";
+import type { Cause } from "../../core/domain/pipeline.js";
+/**
+ * What travels beside a published event: who it is, which flow it belongs to and what caused it
+ * — the backend's `Envelope` and the chain of its `DomainEvent` (`correlation_id`,
+ * `causation_id`), kept beside the event rather than in it, so an event class carries only what
+ * happened.
+ *
+ *     { name: "shop.order.v1.paid", id: "0193…", correlationId: "0193…", causationId: "0192…",
+ *       publishedAt: "2026-11-10T23:31:53.000Z" }
+ *
+ * Context: a queue stores it with the event and hands it back on delivery
+ * (`context.execute(event, envelope)`): the run that executes the event continues the flow —
+ * the same `correlationId`, caused by this event's `id` —, three services and two devices later.
+ */
+export type Envelope = Cause & {
+    /** The event's wire name (`eventName`). */
+    readonly name: string;
+    /** What directly caused it: the run that published it; `null` for the head of a flow. */
+    readonly causationId: string | null;
+    /** When it was published, ISO. */
+    readonly publishedAt: string;
+};
+/**
+ * The envelope of `event`, published by the run `cause` names — or the head of its own flow when
+ * nothing caused it (its `correlationId` is its own `id`).
+ */
+export declare function envelopeOf(event: DomainEvent, cause?: Cause): Envelope;

package/dist/event_driven/domain/envelope.js

@@ -0,0 +1,19 @@
+import { newEntityId } from "../../common/ids.js";
+/**
+ * The envelope of `event`, published by the run `cause` names — or the head of its own flow when
+ * nothing caused it (its `correlationId` is its own `id`).
+ */
+export function envelopeOf(event, cause) {
+    const name = event.name;
+    if (name.trim() === "") {
+        throw new Error(`${event.constructor.name} has no eventName: an event is published by its wire name`);
+    }
+    const id = newEntityId();
+    return {
+        name,
+        id,
+        correlationId: cause?.correlationId ?? id,
+        causationId: cause?.id ?? null,
+        publishedAt: new Date().toISOString(),
+    };
+}

package/dist/event_driven/domain/queue.d.ts

@@ -0,0 +1,40 @@
+import type { DomainEvent, EventClass } from "../../core/domain/dto.js";
+import type { Envelope } from "./envelope.js";
+/**
+ * What carries a published event to whoever hears it — the port each platform implements with
+ * its own technology, as the backend's `Queue`:
+ *
+ * - `syncQueue(subscriber)` — this package's: in the call, in memory (the web's default, tests).
+ * - a phone: SQLite, so an event outlives a restart, with retries, a dead-letter queue and the
+ *   connectivity it waits for.
+ * - a browser: IndexedDB to work offline, `BroadcastChannel` to tell the other tabs.
+ * - a server's broker, through the backend.
+ *
+ * Context: delivery is the platform's — when, how often, how durably —; what it delivers and to
+ * whom is the same everywhere: an event, its envelope, and a `Subscribes` that executes it in
+ * every bounded context that hears it.
+ */
+export interface EventQueue {
+    put(event: DomainEvent, envelope: Envelope): void | Promise<void>;
+}
+/** What one bounded context answered, or failed with, for a delivered event. */
+export type Handled = {
+    readonly boundedContext: string;
+    readonly answer: unknown;
+} | {
+    readonly boundedContext: string;
+    readonly error: unknown;
+};
+/**
+ * What a queue hands an event to — the backend's `Subscribes`: which class a stored name is
+ * rebuilt as, and the event executed by every subscriber.
+ */
+export interface Subscribes {
+    /** The class an event of that wire name is rebuilt as, or `undefined` when nobody hears it. */
+    eventTypeOf(name: string): EventClass<DomainEvent> | undefined;
+    /**
+     * The event executed in every bounded context that hears it — but those `skip` names, which
+     * already have it — and what each answered.
+     */
+    handle(event: DomainEvent, envelope?: Envelope, skip?: readonly string[]): Promise<Handled[]>;
+}

package/dist/event_driven/domain/queue.js

@@ -0,0 +1 @@
+export {};

package/dist/event_driven/domain/store.d.ts

@@ -0,0 +1,56 @@
+import type { JsonValue } from "../../common/serialization.js";
+import type { Envelope } from "./envelope.js";
+import type { FailureKind } from "@sincpro/criteria";
+/**
+ * Where a stored queue keeps what it was handed until every bounded context that hears it has
+ * executed it — the port each platform implements with its own technology:
+ *
+ * - `memoryEventStore()` — this package's: the process's memory (a browser tab, a test).
+ * - a phone: a SQLite table, so an event outlives a restart; the set-aside ones are its
+ *   dead-letter queue.
+ * - a browser: IndexedDB, to work offline.
+ *
+ * Context: storing is the platform's, deciding what to do with what is stored is not — when to
+ * try again, what to set aside, which contexts already have it (`storedQueue`). So the port only
+ * keeps records, in the order they came, and finds the next one waiting.
+ */
+export interface EventStore {
+    /** Keeps a published event, waiting. */
+    add(stored: StoredEvent): void | Promise<void>;
+    /**
+     * The oldest event still waiting (`pending`), in the order added — but those `skip` names by
+     * envelope id: not ready yet (no connection, no session), they wait while the rest go on.
+     */
+    next(skip: ReadonlySet<string>): StoredEvent | undefined | Promise<StoredEvent | undefined>;
+    /** What changed of a stored event — found by its envelope's id. */
+    save(stored: StoredEvent): void | Promise<void>;
+}
+/**
+ * - `pending`: waiting to be delivered — again, after `retryAt`, when it failed in a way a retry
+ *   may fix.
+ * - `delivered`: every bounded context that hears it executed it.
+ * - `set_aside`: a context failed in a way every attempt would repeat (`PERMANENT_KINDS`) — the
+ *   dead-letter queue; it never holds back what comes after.
+ */
+export type StoredState = "pending" | "delivered" | "set_aside";
+/** Why a bounded context did not execute it. */
+export type DeliveryFailure = {
+    readonly boundedContext: string;
+    readonly kind: FailureKind;
+    readonly reason: string;
+    readonly message: string;
+};
+/** A published event as a store keeps it: its envelope, its values and how its delivery goes. */
+export type StoredEvent = {
+    readonly envelope: Envelope;
+    /** The event's values (`valuesOf`): rebuilt as its class on delivery. */
+    readonly payload: JsonValue;
+    readonly state: StoredState;
+    readonly attempts: number;
+    /** When it may be tried again, ISO; `null` when it need not wait. */
+    readonly retryAt: string | null;
+    /** The bounded contexts done with it — executed, or set aside —: a retry never runs them again. */
+    readonly reached: readonly string[];
+    /** Why the last attempt did not reach every context. */
+    readonly failures: readonly DeliveryFailure[];
+};

package/dist/event_driven/domain/store.js

@@ -0,0 +1 @@
+export {};

package/dist/event_driven/entrypoint/publisher.d.ts

@@ -0,0 +1,26 @@
+import { BIND, type Execution } from "../../context/domain/execution.js";
+import type { DomainEvent } from "../../core/domain/dto.js";
+import type { Cause } from "../../core/domain/pipeline.js";
+import { type Envelope } from "../domain/envelope.js";
+import type { EventQueue } from "../domain/queue.js";
+/**
+ * Puts events into a queue — what a Feature holds to tell whoever listens, as the backend's
+ * `Publisher`:
+ *
+ *     shop.addDependency("publisher", new Publisher(queue));
+ *     // in a Feature:
+ *     await this.publisher.publish(new OrderPaid(order.id));   // its Envelope
+ *
+ * Context: a dependency of a bounded context is bound to each run (`BIND`), so what a Feature
+ * publishes joins that run's flow — the same `correlationId`, caused by the run — with nothing
+ * passed by hand. Outside a run, an event is the head of its own flow.
+ */
+export declare class Publisher {
+    private readonly queue;
+    private readonly cause?;
+    constructor(queue: EventQueue, cause?: Cause | undefined);
+    /** `event` into the queue, with its envelope; answers the envelope once the queue took it. */
+    publish(event: DomainEvent): Promise<Envelope>;
+    /** The same publisher, publishing as `execution`: its events join that run's flow. */
+    [BIND](execution: Execution): Publisher;
+}

package/dist/event_driven/entrypoint/publisher.js

@@ -0,0 +1,35 @@
+import { BIND } from "../../context/domain/execution.js";
+import { envelopeOf, } from "../domain/envelope.js";
+/**
+ * Puts events into a queue — what a Feature holds to tell whoever listens, as the backend's
+ * `Publisher`:
+ *
+ *     shop.addDependency("publisher", new Publisher(queue));
+ *     // in a Feature:
+ *     await this.publisher.publish(new OrderPaid(order.id));   // its Envelope
+ *
+ * Context: a dependency of a bounded context is bound to each run (`BIND`), so what a Feature
+ * publishes joins that run's flow — the same `correlationId`, caused by the run — with nothing
+ * passed by hand. Outside a run, an event is the head of its own flow.
+ */
+export class Publisher {
+    queue;
+    cause;
+    constructor(queue, cause) {
+        this.queue = queue;
+        this.cause = cause;
+    }
+    /** `event` into the queue, with its envelope; answers the envelope once the queue took it. */
+    async publish(event) {
+        const envelope = envelopeOf(event, this.cause);
+        await this.queue.put(event, envelope);
+        return envelope;
+    }
+    /** The same publisher, publishing as `execution`: its events join that run's flow. */
+    [BIND](execution) {
+        return new Publisher(this.queue, {
+            id: execution.id,
+            correlationId: execution.correlationId,
+        });
+    }
+}

package/dist/event_driven/entrypoint/subscriber.d.ts

@@ -0,0 +1,34 @@
+import type { DomainEvent, EventClass } from "../../core/domain/dto.js";
+import type { Cause } from "../../core/domain/pipeline.js";
+import type { Envelope } from "../domain/envelope.js";
+import type { Handled, Subscribes } from "../domain/queue.js";
+/** What the subscriber needs of a bounded context: whether it hears an event, and running it. */
+export type HearingContext = {
+    readonly name: string;
+    handlerOf(dto: abstract new (...args: never[]) => DomainEvent): unknown;
+    eventTypeOf(name: string): EventClass<DomainEvent> | undefined;
+    execute(event: DomainEvent, cause?: Cause): Promise<unknown>;
+};
+/**
+ * Hands an event to every bounded context that hears it — the backend's `Subscriber(buses)`:
+ *
+ *     const subscriber = new Subscriber(shop, mail, stock);
+ *     const queue = syncQueue(subscriber);              // or a platform's durable queue
+ *
+ * Context: one subscriber per bounded context (its Feature or ApplicationService registered for
+ * the event class); several contexts hearing one event is several executions, one each, in the
+ * order named. A context that fails does not stop the others: each answer, or failure, is said.
+ */
+export declare class Subscriber implements Subscribes {
+    private readonly contexts;
+    constructor(...contexts: HearingContext[]);
+    eventTypeOf(name: string): EventClass<DomainEvent> | undefined;
+    /**
+     * 1. Every bounded context registered for the event's class, in the order named — but those
+     *    `skip` names, which already have it.
+     * 2. Each executes it — continuing the envelope's flow when there is one —, and its answer or
+     *    failure is kept; a failure does not stop the next.
+     * Final: what each answered, or failed with.
+     */
+    handle(event: DomainEvent, envelope?: Envelope, skip?: readonly string[]): Promise<Handled[]>;
+}

package/dist/event_driven/entrypoint/subscriber.js

@@ -0,0 +1,51 @@
+/**
+ * Hands an event to every bounded context that hears it — the backend's `Subscriber(buses)`:
+ *
+ *     const subscriber = new Subscriber(shop, mail, stock);
+ *     const queue = syncQueue(subscriber);              // or a platform's durable queue
+ *
+ * Context: one subscriber per bounded context (its Feature or ApplicationService registered for
+ * the event class); several contexts hearing one event is several executions, one each, in the
+ * order named. A context that fails does not stop the others: each answer, or failure, is said.
+ */
+export class Subscriber {
+    contexts;
+    constructor(...contexts) {
+        this.contexts = contexts;
+    }
+    eventTypeOf(name) {
+        for (const context of this.contexts) {
+            const found = context.eventTypeOf(name);
+            if (found)
+                return found;
+        }
+        return undefined;
+    }
+    /**
+     * 1. Every bounded context registered for the event's class, in the order named — but those
+     *    `skip` names, which already have it.
+     * 2. Each executes it — continuing the envelope's flow when there is one —, and its answer or
+     *    failure is kept; a failure does not stop the next.
+     * Final: what each answered, or failed with.
+     */
+    async handle(event, envelope, skip = []) {
+        const type = Object.getPrototypeOf(event)?.constructor;
+        const handled = [];
+        for (const context of this.contexts) {
+            if (type === undefined || context.handlerOf(type) === undefined)
+                continue;
+            if (skip.includes(context.name))
+                continue;
+            try {
+                handled.push({
+                    boundedContext: context.name,
+                    answer: await context.execute(event, envelope),
+                });
+            }
+            catch (error) {
+                handled.push({ boundedContext: context.name, error });
+            }
+        }
+        return handled;
+    }
+}

package/dist/event_driven/index.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Event-driven: the ports and the in-memory pieces that let every platform publish domain events
+ * and subscribe to them the same way — as sincpro_framework's `event_driven`. Delivering them
+ * durably (SQLite on a phone, IndexedDB in a browser, a broker) is each platform's, behind
+ * `EventQueue`.
+ *
+ *   domain/      the envelope and the ports: EventQueue, Subscribes, EventStore
+ *   adapters/    syncQueue (in the call), storedQueue (store, then deliver, retry, set aside),
+ *                memoryEventStore
+ *   entrypoint/  Publisher (what a Feature holds), Subscriber (every bounded context that hears)
+ */
+export { type MemoryEventStore, memoryEventStore, } from "./adapters/memory-event-store.js";
+export { type StoredQueue, storedQueue, type StoredQueueOptions, } from "./adapters/stored-queue.js";
+export { syncQueue } from "./adapters/sync-queue.js";
+export { type Envelope, envelopeOf, } from "./domain/envelope.js";
+export type { EventQueue, Handled, Subscribes, } from "./domain/queue.js";
+export type { DeliveryFailure, EventStore, StoredEvent, StoredState, } from "./domain/store.js";
+export { Publisher } from "./entrypoint/publisher.js";
+export { type HearingContext, Subscriber, } from "./entrypoint/subscriber.js";

package/dist/event_driven/index.js

@@ -0,0 +1,17 @@
+/**
+ * Event-driven: the ports and the in-memory pieces that let every platform publish domain events
+ * and subscribe to them the same way — as sincpro_framework's `event_driven`. Delivering them
+ * durably (SQLite on a phone, IndexedDB in a browser, a broker) is each platform's, behind
+ * `EventQueue`.
+ *
+ *   domain/      the envelope and the ports: EventQueue, Subscribes, EventStore
+ *   adapters/    syncQueue (in the call), storedQueue (store, then deliver, retry, set aside),
+ *                memoryEventStore
+ *   entrypoint/  Publisher (what a Feature holds), Subscriber (every bounded context that hears)
+ */
+export { memoryEventStore, } from "./adapters/memory-event-store.js";
+export { storedQueue, } from "./adapters/stored-queue.js";
+export { syncQueue } from "./adapters/sync-queue.js";
+export { envelopeOf, } from "./domain/envelope.js";
+export { Publisher } from "./entrypoint/publisher.js";
+export { Subscriber, } from "./entrypoint/subscriber.js";

package/dist/index.d.ts

@@ -7,19 +7,24 @@
  * as sincpro_framework's are — `domain/` (ports and rules), `adapters/` (their implementations),
  * `services/`, `infrastructure/`, `entrypoint/` — and says what it offers in its own `index.ts`:
  *
- *   common/         the values of the wire, as the backend writes them
+ *   common/         the values of the wire, as the backend writes them; what a failure is
+ *   circuit_breaker/  stop calling what keeps failing; try it again once it may be back
  *   context/        the context's levels, where they live, what travels, the execution
  *   observability/  tracing, error reporting and logging: ports, console, loggers
  *   client/         the seam with a server: transports, entities, the client contract
  *   model/          model definitions
- *   core/           Commands, Features, ApplicationServices, BoundedContext, the process
+ *   core/           Commands, events, Features, ApplicationServices, BoundedContext, the
+ *                   pipeline's extension points, the process
+ *   event_driven/   publishing and subscribing to domain events: ports, Publisher, Subscriber
  *
  * The generator is `@sincpro/client-framework/codegen`, and the in-memory observability
  * `@sincpro/client-framework/testing`: neither is part of what an application runs.
  */
+export * from "./circuit_breaker/index.js";
 export * from "./client/index.js";
 export * from "./common/index.js";
 export * from "./context/index.js";
 export * from "./core/index.js";
+export * from "./event_driven/index.js";
 export * from "./model/index.js";
 export * from "./observability/index.js";

package/dist/index.js

@@ -7,19 +7,24 @@
  * as sincpro_framework's are — `domain/` (ports and rules), `adapters/` (their implementations),
  * `services/`, `infrastructure/`, `entrypoint/` — and says what it offers in its own `index.ts`:
  *
- *   common/         the values of the wire, as the backend writes them
+ *   common/         the values of the wire, as the backend writes them; what a failure is
+ *   circuit_breaker/  stop calling what keeps failing; try it again once it may be back
  *   context/        the context's levels, where they live, what travels, the execution
  *   observability/  tracing, error reporting and logging: ports, console, loggers
  *   client/         the seam with a server: transports, entities, the client contract
  *   model/          model definitions
- *   core/           Commands, Features, ApplicationServices, BoundedContext, the process
+ *   core/           Commands, events, Features, ApplicationServices, BoundedContext, the
+ *                   pipeline's extension points, the process
+ *   event_driven/   publishing and subscribing to domain events: ports, Publisher, Subscriber
  *
  * The generator is `@sincpro/client-framework/codegen`, and the in-memory observability
  * `@sincpro/client-framework/testing`: neither is part of what an application runs.
  */
+export * from "./circuit_breaker/index.js";
 export * from "./client/index.js";
 export * from "./common/index.js";
 export * from "./context/index.js";
 export * from "./core/index.js";
+export * from "./event_driven/index.js";
 export * from "./model/index.js";
 export * from "./observability/index.js";

package/dist/observability/domain/logging.d.ts

@@ -24,6 +24,8 @@ export type LogRecord = {
     readonly boundedContext?: string;
     readonly useCase?: string;
     readonly executionId?: string;
+    /** The chain the run belongs to: every run and event of one flow share it. */
+    readonly correlationId?: string;
     readonly traceId?: string;
     readonly spanId?: string;
     readonly outcome?: Outcome;

package/dist/observability/services/logging.js

@@ -19,6 +19,7 @@ function correlationOf(execution) {
         boundedContext: execution.boundedContext,
         useCase: execution.useCase,
         executionId: execution.id,
+        correlationId: execution.correlationId,
         ...(execution.span.traceId ? { traceId: execution.span.traceId } : {}),
         ...(execution.span.spanId ? { spanId: execution.span.spanId } : {}),
     };

package/dist/observability/services/outcome.d.ts

@@ -1,12 +1,12 @@
 import type { Outcome } from "../domain/tracing.js";
 /**
- * How an error ended a use case, by default.
+ * How an error ended a use case, by default — read off the failure it is (`failureOf`).
  *
  * Context: the backend reports what nobody expected and only that — a refusal it explained is
- * the business answering, not a fault. Here the same: a `TransportError` the server answered
- * with a 4xx is `refused`; a request the caller stopped waiting for is `aborted`; everything
- * else — a bug, a 5xx, a server nobody could reach — is `failed`, and reported. A bounded
- * context adds its own expected errors (`expectErrors`); a process replaces this whole
- * (`configureProcess({ outcomeOf })`).
+ * the business answering, not a fault. Here the same: a failure that is the caller's answer (a
+ * 4xx, an error that declares a kind such as `domain` or `not_found`) is `refused`; a request
+ * the caller stopped waiting for is `aborted`; a fault — a bug, a 5xx, a server nobody could
+ * reach — is `failed`, and reported. A bounded context adds its own expected errors
+ * (`expectErrors`); a process replaces this whole (`configureProcess({ outcomeOf })`).
  */
 export declare function outcomeOf(error: unknown): Outcome;

package/dist/observability/services/outcome.js

@@ -1,20 +1,17 @@
-import { TransportError } from "../../client/domain/transport.js";
+import { failureOf } from "../../common/failures.js";
 /**
- * How an error ended a use case, by default.
+ * How an error ended a use case, by default — read off the failure it is (`failureOf`).
  *
  * Context: the backend reports what nobody expected and only that — a refusal it explained is
- * the business answering, not a fault. Here the same: a `TransportError` the server answered
- * with a 4xx is `refused`; a request the caller stopped waiting for is `aborted`; everything
- * else — a bug, a 5xx, a server nobody could reach — is `failed`, and reported. A bounded
- * context adds its own expected errors (`expectErrors`); a process replaces this whole
- * (`configureProcess({ outcomeOf })`).
+ * the business answering, not a fault. Here the same: a failure that is the caller's answer (a
+ * 4xx, an error that declares a kind such as `domain` or `not_found`) is `refused`; a request
+ * the caller stopped waiting for is `aborted`; a fault — a bug, a 5xx, a server nobody could
+ * reach — is `failed`, and reported. A bounded context adds its own expected errors
+ * (`expectErrors`); a process replaces this whole (`configureProcess({ outcomeOf })`).
  */
 export function outcomeOf(error) {
-    if (error instanceof TransportError && error.status !== null)
-        return error.status >= 400 && error.status < 500 ? "refused" : "failed";
-    if (error !== null &&
-        typeof error === "object" &&
-        error.name === "AbortError")
+    const failure = failureOf(error);
+    if (failure.aborted)
         return "aborted";
-    return "failed";
+    return failure.fault ? "failed" : "refused";
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sincpro/client-framework",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "The client side of sincpro_framework, for every platform: Feature and ApplicationService traced and reported by default, applications made of domains, and the typed client generated from a service's contract. No React, no DOM.",
   "type": "module",
   "main": "./dist/index.js",