@sincpro/client-framework 1.1.0 → 1.2.0

package/dist/event_driven/entrypoint/subscriber.js

@@ -1,16 +1,27 @@
 /**
- * Hands an event to every bounded context that hears it — the backend's `Subscriber(buses)`:
+ * The door of a queue: hands an event to everyone who hears it — the backend's
+ * `Subscriber(buses)`:
  *
- *     const subscriber = new Subscriber(shop, mail, stock);
+ *     const subscriber = new Subscriber(shopBoundedContext, mailBoundedContext, ticketsSubscriptions);
  *     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.
+ * Context: who hears an event is a bounded context with a use case of it (a Feature or an
+ * ApplicationService registered for its class) or `Subscriptions` with an `EventSubscriber` of
+ * it — the entrypoint that calls use cases. Several hearing one event is several executions, one
+ * each, in the order named; one that fails does not stop the others: each answer, or failure, is
+ * said under its name — which a stored queue keeps, so a redelivery never runs again one that
+ * already heard it. Two of them never share a name.
  */
 export class Subscriber {
     contexts;
     constructor(...contexts) {
+        const names = new Set();
+        for (const context of contexts) {
+            if (names.has(context.name)) {
+                throw new Error(`Two of those who hear events are named ${context.name}: the queue keeps who heard an event by its name`);
+            }
+            names.add(context.name);
+        }
         this.contexts = contexts;
     }
     eventTypeOf(name) {

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

@@ -0,0 +1,110 @@
+import type { Execution } from "../../context/domain/execution.js";
+import type { ContextValues } from "../../context/domain/store.js";
+import { DomainEvent, type EventClass } from "../../core/domain/dto.js";
+import type { Cause, ExecuteOptions } from "../../core/domain/pipeline.js";
+import type { LayerLogger } from "../../observability/domain/logging.js";
+import type { Span } from "../../observability/domain/tracing.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 declare abstract class EventSubscriber<E extends DomainEvent, Context extends object = ContextValues> {
+    /** What this delivery runs with: the process's context. */
+    readonly context: Readonly<Partial<Context>>;
+    /** This delivery's span: the Commands it executes are its children. */
+    readonly span: Span;
+    /** This delivery's logger: every line carries its flow and trace. */
+    readonly logger: LayerLogger;
+    /** What cancels this delivery, when it was executed with one. */
+    readonly signal: AbortSignal | undefined;
+    /**
+     * This delivery: its id, flow (`correlationId`) and cause — the envelope's id, the key that
+     * makes hearing an event twice harmless.
+     */
+    readonly execution: Execution;
+    abstract handle(event: E): unknown;
+}
+type SubscriberClass<E extends DomainEvent> = {
+    new (): EventSubscriber<E>;
+    readonly subscriberName: string;
+};
+/** What a subscription takes the place of: the subscriber registered now for the event. */
+export type SubscriptionOptions = {
+    replaces?: abstract new (...args: never[]) => object;
+};
+/** What `subscribe(...)` answers: the function that registers the subscriber. */
+export type Subscribing<E extends DomainEvent> = <S extends SubscriberClass<NoInfer<E>>>(Subscriber: S, decorator?: ClassDecoratorContext<S>) => S;
+/**
+ * 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 declare class Subscriptions<D extends object = Record<never, never>> {
+    readonly name: string;
+    private readonly registrations;
+    private readonly dependencyValues;
+    constructor(name: string);
+    /** A dependency its subscribers find on `this`, bound to each delivery; `replaces` as a bounded context's. */
+    addDependency<K extends keyof D & string>(name: K, dependency: D[K], options?: {
+        replaces: D[K];
+    }): this;
+    /**
+     * Registers the subscriber that hears `event` here. With `replaces`, it takes the place of the
+     * one registered now.
+     */
+    subscribe<E extends DomainEvent>(event: EventClass<E>, options?: SubscriptionOptions): Subscribing<E>;
+    /** The subscriber registered now for an event class — what a `replaces` names. */
+    handlerOf(event: abstract new (...args: never[]) => DomainEvent): (abstract new (...args: never[]) => object) | undefined;
+    /** The event class registered here under a wire name, or `undefined` when nobody here hears it. */
+    eventTypeOf(name: string): EventClass<DomainEvent> | 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: DomainEvent, options?: ExecuteOptions | Cause): Promise<unknown>;
+    /**
+     * 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.
+     */
+    private register;
+}
+export {};

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

@@ -7,7 +7,9 @@
  *   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)
+ *   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";
@@ -17,3 +19,4 @@ 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

@@ -7,7 +7,9 @@
  *   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)
+ *   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";
@@ -15,3 +17,4 @@ 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/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;

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

@@ -51,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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sincpro/client-framework",
-  "version": "1.1.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",