@sincpro/client-framework 1.0.0 → 1.2.0

package/dist/event_driven/entrypoint/subscriptions.js

@@ -0,0 +1,184 @@
+import { processContext } from "../../context/infrastructure/process.js";
+import { optionsOf } from "../../core/domain/bus.js";
+import { DomainEvent } from "../../core/domain/dto.js";
+import { RESERVED_MEMBERS } from "../../core/domain/services.js";
+import { executeService } from "../../core/services/execution.js";
+/**
+ * An entrypoint that hears one domain event and calls the use cases it starts — as a cron calls
+ * them on a tick, or a screen on a gesture:
+ *
+ *     class LoggedSuccessfully extends EventSubscriber<OdooLoggedIn> {
+ *       static readonly subscriberName = "LoggedSuccessfully";
+ *       declare readonly ticketsBoundedContext: BoundedContext<TicketsDependencies>;
+ *
+ *       async handle(event: OdooLoggedIn) {
+ *         await this.ticketsBoundedContext.execute(new CommandPrepareSession(event.uid));
+ *       }
+ *     }
+ *
+ * Context: a subscriber is not a use case. It reads the event, builds the Command — or the
+ * Commands — and executes them on a bounded context it was given; what to decide, and work of
+ * several steps, is a Feature or an ApplicationService it executes. While `handle` runs,
+ * `this.span`, `this.logger`, `this.signal`, `this.execution` and every dependency are that
+ * delivery's: a bounded context it was given executes as a child of it — the same flow, caused by
+ * it (`BIND`). `subscriberName` is stable metadata, never `constructor.name`. Like a service, a
+ * subscriber is one instance for every delivery: what belongs to one goes in its locals.
+ */
+export class EventSubscriber {
+}
+function isEventClass(value) {
+    return typeof value === "function" && value.prototype instanceof DomainEvent;
+}
+function nameOf(Subscriber) {
+    const named = Subscriber;
+    return String(named?.subscriberName ?? named?.name ?? Subscriber);
+}
+/**
+ * The subscribers of one part of an application — which `EventSubscriber` hears which event —,
+ * with the dependencies they call: what a queue's `Subscriber` hands an event to, beside the
+ * bounded contexts:
+ *
+ *     export const ticketsSubscriptions = new Subscriptions<TicketsEntrypoints>("tickets-subscriptions");
+ *     ticketsSubscriptions.addDependency("ticketsBoundedContext", ticketsBoundedContext);
+ *     ticketsSubscriptions.subscribe(OdooLoggedIn)(LoggedSuccessfully);
+ *
+ *     storedQueue({ store, subscriber: new Subscriber(odooBoundedContext, ticketsSubscriptions) });
+ *
+ * Context: the shape of a bounded context, and of the backend's `Crons`: a name that is its
+ * identity in spans, logs and the queue's record of who already heard an event — so it differs
+ * from every bounded context's —, dependencies by name, and a function (or a decorator) that
+ * registers. One subscriber per event here: several reactions to one event are one
+ * ApplicationService it executes, or subscribers of other registries. Each delivery is a run of
+ * its own (`<name>/<subscriberName>`, layer `entrypoint`), continuing the envelope's flow; it is
+ * not a use case, so interceptors and listeners do not see it — they see the use cases it calls.
+ */
+export class Subscriptions {
+    name;
+    registrations = new Map();
+    dependencyValues = new Map();
+    constructor(name) {
+        this.name = name;
+        if (name.trim() === "" || name.includes("/")) {
+            throw new TypeError("Subscriptions need a nonempty name without '/'");
+        }
+    }
+    /** A dependency its subscribers find on `this`, bound to each delivery; `replaces` as a bounded context's. */
+    addDependency(name, dependency, options) {
+        if (RESERVED_MEMBERS.has(name))
+            throw new Error(`Reserved dependency name: ${name}`);
+        const registered = this.dependencyValues.has(name);
+        if (registered && options === undefined) {
+            throw new Error(`Dependency already registered: ${name}`);
+        }
+        if (options && (!registered || this.dependencyValues.get(name) !== options.replaces)) {
+            throw new Error(`Dependency replacement does not match the registration: ${name}`);
+        }
+        this.dependencyValues.set(name, dependency);
+        return this;
+    }
+    /**
+     * Registers the subscriber that hears `event` here. With `replaces`, it takes the place of the
+     * one registered now.
+     */
+    subscribe(event, options = {}) {
+        return (Subscriber, decorator) => {
+            const register = () => this.register(event, Subscriber, options.replaces);
+            // Standard decorators run before static fields have initialized.
+            if (decorator)
+                decorator.addInitializer(register);
+            else
+                register();
+            return Subscriber;
+        };
+    }
+    /** The subscriber registered now for an event class — what a `replaces` names. */
+    handlerOf(event) {
+        return this.registrations.get(event)?.Subscriber;
+    }
+    /** The event class registered here under a wire name, or `undefined` when nobody here hears it. */
+    eventTypeOf(name) {
+        for (const event of this.registrations.keys()) {
+            if (event.eventName === name)
+                return event;
+        }
+        return undefined;
+    }
+    /**
+     * `event` heard by its subscriber here — continuing the envelope's flow when it is given
+     * (`execute(event, envelope)`) — and what `handle` returned.
+     *
+     * 1. The subscriber registered for the event's exact class; none: an error.
+     * 2. A run `<name>/<subscriberName>`, layer `entrypoint`: its span, log lines and — when it
+     *    fails with a fault nothing reported yet — its report; its dependencies bound to it.
+     * Final: what `handle` returned; its failure, as it is, to the queue that delivered it.
+     */
+    execute(event, options) {
+        const type = Object.getPrototypeOf(event)?.constructor;
+        const registration = this.registrations.get(type);
+        if (registration === undefined) {
+            return Promise.reject(new Error(`${this.name}: no subscriber hears ${event.name}`));
+        }
+        registration.instance ??= new registration.Subscriber();
+        const given = optionsOf(options);
+        const attributes = {
+            "sincpro.event": event.name,
+            ...(registration.replaces ? { "sincpro.replaces": registration.replaces } : {}),
+        };
+        return executeService(registration.instance, event, {
+            boundedContext: this.name,
+            name: registration.name,
+            layer: "entrypoint",
+            method: "handle",
+            attributes,
+            dependencies: new Map(this.dependencyValues),
+            context: () => ({ ...processContext.values }),
+            ...(given.cause ? { cause: given.cause } : {}),
+            ...(given.signal ? { signal: given.signal } : {}),
+            interceptors: [],
+            expected: () => false,
+            handlers: [],
+        });
+    }
+    /**
+     * 1. The subscriber is an `EventSubscriber`, for a domain event class with its `eventName`.
+     * 2. The event has no subscriber here yet — or, with `replaces`, the one it has is that one.
+     * 3. Its `subscriberName` is given and no other subscriber here has it; no other event class
+     *    here has the event's name.
+     * Final: registered, said on its spans when it replaced another; the next delivery hears it.
+     */
+    register(event, Subscriber, replaces) {
+        if (!(Subscriber.prototype instanceof EventSubscriber)) {
+            throw new TypeError("The subscriber is not an EventSubscriber");
+        }
+        if (!isEventClass(event)) {
+            throw new TypeError("A subscriber is registered for a DomainEvent class");
+        }
+        if (typeof event.eventName !== "string" || event.eventName.trim() === "") {
+            throw new Error("A domain event needs a nonempty eventName");
+        }
+        const current = this.registrations.get(event);
+        if (replaces !== undefined && current?.Subscriber !== replaces) {
+            throw new Error(`Replacement does not match the subscription: ${nameOf(replaces)}`);
+        }
+        if (replaces === undefined && current) {
+            throw new Error(`Event already subscribed in ${this.name}: one subscriber per event — several reactions are one ApplicationService`);
+        }
+        const name = Subscriber.subscriberName;
+        if (typeof name !== "string" || name.trim() === "" || name.includes("/")) {
+            throw new Error("A subscriber needs a nonempty subscriberName without '/'");
+        }
+        for (const [other, registration] of this.registrations) {
+            if (registration !== current && registration.name === name) {
+                throw new Error(`Subscriber name already registered: ${name}`);
+            }
+            if (other !== event && other.eventName === event.eventName) {
+                throw new Error(`Event name already registered: ${event.eventName}`);
+            }
+        }
+        this.registrations.set(event, {
+            name,
+            Subscriber,
+            ...(current ? { replaces: current.name } : {}),
+        });
+    }
+}

package/dist/event_driven/index.d.ts

@@ -0,0 +1,22 @@
+/**
+ * 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 (the queue's door: everyone who
+ *                hears), Subscriptions and EventSubscriber (the entrypoint that hears an event and
+ *                calls use cases)
+ */
+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";
+export { EventSubscriber, type Subscribing, type SubscriptionOptions, Subscriptions, } from "./entrypoint/subscriptions.js";

package/dist/event_driven/index.js

@@ -0,0 +1,20 @@
+/**
+ * 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 (the queue's door: everyone who
+ *                hears), Subscriptions and EventSubscriber (the entrypoint that hears an event and
+ *                calls use cases)
+ */
+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";
+export { EventSubscriber, Subscriptions, } from "./entrypoint/subscriptions.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/adapters/memory.d.ts

@@ -6,7 +6,7 @@ import type { Outcome, Tracer } from "../domain/tracing.js";
  *
  *     const tracer = memoryTracer();
  *     configureProcess({ tracer });
- *     await project.execute(new CommandCloseIssue("issue-1"));
+ *     await projectBoundedContext.execute(new CommandCloseIssue("issue-1"));
  *     tracer.spans.map((one) => one.name);   // ["project/CloseIssue", "project/Store", …]
  *
  * Context: a use case is proven in Node with nothing of a platform; these are the platform's

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

@@ -5,14 +5,18 @@ import type { Attributes, Outcome } from "./tracing.js";
  *
  * Context: a line says which layer wrote it, the way sincpro_framework's architecture names
  * them: the application layer (a bounded context and its ApplicationServices and Features,
- * through `project.logger` and `this.logger`), its adapters (`loggerAdapter`) and the
- * infrastructure around them (`logger`). A line written inside a use case carries that
+ * through `projectBoundedContext.logger` and `this.logger`), the entrypoints that call it (an
+ * `EventSubscriber`'s `this.logger`), its adapters (`loggerAdapter`) and the infrastructure
+ * around them (`logger`). A line written inside a use case carries that
  * execution's identity; nothing writes a DTO, a response, an error body or the session's
  * context on its own.
  */
 export type LogLevel = "debug" | "info" | "warn" | "error";
-/** The layer a line comes from. */
-export type LogLayer = "infrastructure" | "adapter" | "bounded_context" | "application_service" | "feature";
+/**
+ * The layer a line comes from: the infrastructure, an adapter, an entrypoint that calls use cases
+ * (an `EventSubscriber`), a bounded context, an ApplicationService, a Feature.
+ */
+export type LogLayer = "infrastructure" | "adapter" | "entrypoint" | "bounded_context" | "application_service" | "feature";
 /** Structured logging never implicitly includes a DTO, response, error body or session context. */
 export type LogRecord = {
     readonly timestamp: string;
@@ -24,6 +28,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.d.ts

@@ -5,14 +5,16 @@ import type { Outcome } from "../domain/tracing.js";
 export declare const logger: LayerLogger;
 /** The adapters' logger: what talks to a printer, a database, another system. */
 export declare const loggerAdapter: LayerLogger;
-/** @internal — a bounded context's own logger (`project.logger`). */
+/** @internal — a bounded context's own logger (`projectBoundedContext.logger`). */
 export declare function boundedContextLogger(name: string): LayerLogger;
-/** @internal — what a Feature or ApplicationService finds as `this.logger` while it runs. */
-export declare function executionLogger(layer: "feature" | "application_service", execution: Execution): LayerLogger;
+/** A run's layer: an entrypoint's (an `EventSubscriber`), a Feature's or an ApplicationService's. */
+type RunLogLayer = Extract<LogLayer, "entrypoint" | "feature" | "application_service">;
+/** @internal — what a run (a use case, an entrypoint) finds as `this.logger` while it runs. */
+export declare function executionLogger(layer: RunLogLayer, execution: Execution): LayerLogger;
 /** Each destination keeps its own policy; one failing sink does not hold back the others. */
 export declare function combineLoggers(...loggers: readonly Logger[]): Logger;
 /** @internal — lifecycle records contain correlation and outcome, never business payloads. */
-export declare function logExecution(layer: "feature" | "application_service", execution: Execution, completed?: {
+export declare function logExecution(layer: RunLogLayer, execution: Execution, completed?: {
     outcome: Outcome;
     durationMs: number;
 }): void;
@@ -25,3 +27,4 @@ export declare function logHandled(layer: LogLayer, correlation: {
 } | {
     boundedContext: string;
 }): void;
+export {};

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 } : {}),
     };
@@ -50,11 +51,11 @@ function layerLogger(layer, sink, correlation = {}) {
 export const logger = layerLogger("infrastructure", processSink);
 /** The adapters' logger: what talks to a printer, a database, another system. */
 export const loggerAdapter = layerLogger("adapter", processSink);
-/** @internal — a bounded context's own logger (`project.logger`). */
+/** @internal — a bounded context's own logger (`projectBoundedContext.logger`). */
 export function boundedContextLogger(name) {
     return layerLogger("bounded_context", processSink, { boundedContext: name });
 }
-/** @internal — what a Feature or ApplicationService finds as `this.logger` while it runs. */
+/** @internal — what a run (a use case, an entrypoint) finds as `this.logger` while it runs. */
 export function executionLogger(layer, execution) {
     return layerLogger(layer, processSink, correlationOf(execution));
 }

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.2.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",