@sincpro/client-framework 0.6.0 → 1.1.0

package/dist/core/domain/dto.js

@@ -0,0 +1,43 @@
+/**
+ * The DTOs of the application layer, as sincpro_framework's `DataTransferObject`: a Command asks
+ * for work and names, by its type, the Response it answers.
+ *
+ *     class CommandCancelIssue extends Command<ResponseCancelIssue> {
+ *       constructor(readonly issue_id: string) { super(); }
+ *     }
+ *     const answer = await project.execute(new CommandCancelIssue("x"));   // ResponseCancelIssue
+ *
+ * Context: the backend asks `bus(dto, ResponseType)` for the type; here the Command carries it, so
+ * `execute` infers it with no second argument. The association is type-only: absent from a
+ * serialized DTO, not a runtime validator. A generated DTO is a remote contract (a type), not one
+ * of these: a local Command may implement it.
+ */
+export class DataTransferObject {
+}
+export class Response extends DataTransferObject {
+}
+export class Command extends DataTransferObject {
+}
+/**
+ * A fact that already happened, as sincpro_framework's `DomainEvent`: executed like a Command, by
+ * the Feature or ApplicationService registered for its class — its subscriber in this bounded
+ * context —, through the same pipeline. Delivering it (a queue, an outbox) is the platform's.
+ *
+ *     class OrderPaid extends DomainEvent {
+ *       static readonly eventName = "shop.order.v1.paid";
+ *       constructor(readonly order_id: string) { super(); }
+ *     }
+ *     project.feature(OrderPaid)(NotifyCustomer);
+ *     await project.execute(new OrderPaid("o-1"));
+ *
+ * Context: the backend names an event on the wire by `name`, `<context>.<aggregate>.vN.<fact>`,
+ * and defaults it to the class's name; a client is minified, so the name is declared, as
+ * `serviceName` is. `name` is reserved, as the backend reserves it: every event reads its class's
+ * `eventName` there, and a subclass cannot make it a field.
+ */
+export class DomainEvent extends DataTransferObject {
+    /** Its wire name: its class's `eventName`. */
+    get name() {
+        return this.constructor.eventName ?? "";
+    }
+}

package/dist/core/domain/errors.d.ts

@@ -0,0 +1,18 @@
+/**
+ * What answers a use case's failure instead of raising it — sincpro_framework's error handlers.
+ *
+ *     project.addFeatureErrorHandler((error) => {
+ *       if (error instanceof IssueNotFound) return new ResponseEmpty();   // the answer
+ *       throw error;                                                     // the next handler
+ *     });
+ *
+ * Context: three chains per bounded context — global (around `project.execute`), feature and
+ * application service —, each run first-registered-first. A handler that throws hands what it
+ * threw to the next; the last one's throw reaches the caller. The failure was already recorded
+ * where it happened (its span, its log line and, when unexpected, its report): a handler decides
+ * the answer, not whether it is observed. A handler that only watches must end with `throw`:
+ * what it returns is the answer.
+ */
+export type ErrorHandler = (error: unknown) => unknown;
+/** An error's class, as `expectErrors` names it. */
+export type ErrorClass = abstract new (...args: never[]) => unknown;

package/dist/core/domain/errors.js

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

package/dist/core/domain/pipeline.d.ts

@@ -0,0 +1,89 @@
+import type { Execution } from "../../context/domain/execution.js";
+import type { Executable } from "./dto.js";
+import type { LayerLogger } from "../../observability/domain/logging.js";
+import type { Outcome } from "../../observability/domain/tracing.js";
+/**
+ * Where the execution pipeline is extended — as sincpro_framework's `bus_pipeline`, in two kinds:
+ *
+ *     control       interceptors   wrap the service: look, veto, adjust or answer
+ *     observation   listeners      a run started, answered, or a failure escaped: heard, never changed
+ *
+ *     project.interceptor(CommandPay)(async (command, next, run) => {
+ *       if (!credit.allows(command.customer_id)) throw new NoCredit();   // veto
+ *       return next(command);                                             // the next, or the service
+ *     });
+ *     project.onCompletion((done) => activity.succeeded(done.execution.useCase));
+ *
+ * Context: the core owns the flow — context, span, log lines, outcome, report, handlers — and
+ * these are the places an application changes it from outside, without touching a service. An
+ * interceptor runs inside the run: its veto is the use case's failure, observed and answered by
+ * the error handlers like any other. A listener that fails is ignored: hearing never changes
+ * the answer.
+ */
+export type PipelineLayer = "feature" | "application_service";
+/** What caused a run from outside: an event delivered with its envelope continues its chain. */
+export type Cause = {
+    /** The id of what caused it — a delivered event's. */
+    readonly id: string;
+    /** The chain it continues. */
+    readonly correlationId: string;
+};
+/**
+ * How a Command or an event is executed: what cancels it, and — for a delivered event — what
+ * caused it.
+ *
+ *     await sales.execute(new CommandQuote(3), { signal: screen.signal });
+ *
+ * Context: a screen that closes, a navigation that leaves, a user who gives up stop waiting; the
+ * run ends `aborted` (not reported), its Features inherit the signal, and the requests its
+ * transport sends are cancelled with it.
+ */
+export type ExecuteOptions = {
+    readonly signal?: AbortSignal;
+    readonly cause?: Cause;
+};
+/** The run an interceptor wraps: who runs, inside which execution, writing where. */
+export type InterceptedRun = {
+    readonly boundedContext: string;
+    /** `<bounded context>.<serviceName>`. */
+    readonly useCase: string;
+    readonly layer: PipelineLayer;
+    /** Its id, span, context and chain. */
+    readonly execution: Execution;
+    /** The run's logger, bound to it. */
+    readonly logger: LayerLogger;
+};
+/** The rest of the chain: the next interceptor, or the service. */
+export type CallNext<T extends Executable> = (executable: T) => Promise<unknown>;
+/**
+ * Runs around the service of a Command or an event. It passes on what it received — or another
+ * of the same class: the bus routes by class, so another class would be another use case — and
+ * returns what the next answered, or an answer of its own; it throws to veto.
+ */
+export type Interceptor<T extends Executable = Executable> = (executable: T, next: CallNext<T>, run: InterceptedRun) => unknown;
+/** A run began. */
+export type ExecutionStarted = {
+    readonly executable: Executable;
+    readonly execution: Execution;
+    readonly layer: PipelineLayer;
+};
+/** A run's service answered. */
+export type ExecutionCompleted = ExecutionStarted & {
+    readonly answer: unknown;
+    readonly durationMs: number;
+};
+/**
+ * A failure escaped a call — after every handler —, said once, where it first failed. No
+ * execution when it reached none: nothing is registered for the class.
+ */
+export type ExecutionFailed = {
+    readonly executable: Executable;
+    readonly execution: Execution | undefined;
+    readonly layer: PipelineLayer | undefined;
+    readonly error: unknown;
+    readonly outcome: Outcome;
+};
+/** Who hears a moment of the pipeline. */
+export type Listener<E> = (heard: E) => void;
+/** A component wired into a bounded context: its interceptors, listeners, services. */
+export type Extension<B> = (context: B) => void;

package/dist/core/domain/pipeline.js

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

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

@@ -0,0 +1,47 @@
+import type { Execution } from "../../context/domain/execution.js";
+import type { ContextValues } from "../../context/domain/store.js";
+import type { FeatureBus } from "./bus.js";
+import type { Command, DomainEvent } from "./dto.js";
+import type { LayerLogger } from "../../observability/domain/logging.js";
+import type { Span } from "../../observability/domain/tracing.js";
+/**
+ * The services of the application layer, as sincpro_framework's: a Feature executes one
+ * registered Command — or domain event, as its subscriber —; an ApplicationService composes its
+ * context's Features.
+ *
+ *     @project.feature(CommandCancelIssue)
+ *     class CancelIssue extends Feature<CommandCancelIssue, ResponseCancelIssue> {
+ *       static readonly serviceName = "CancelIssue";
+ *       async execute(command: CommandCancelIssue) {
+ *         this.logger.info("Cancelling");                 // bound to this run
+ *         return new ResponseCancelIssue(await this.client.cancelIssue(command));
+ *       }
+ *     }
+ *
+ * Context: while a method runs, `this.context`, `this.span`, `this.logger`, `this.featureBus` and
+ * every dependency are that run's (`executeService`). `serviceName` is stable metadata, never
+ * `constructor.name`, which a minifier renames.
+ */
+export declare abstract class Feature<C extends Command<R> | DomainEvent, R, Context extends object = ContextValues> {
+    /** What this run reads: the process's context, its bounded context's, its scope's. */
+    readonly context: Readonly<Partial<Context>>;
+    /** This run's span: `this.span.set({...})` says more about the use case. */
+    readonly span: Span;
+    /** This run's logger: every line carries its use case, execution and trace. */
+    readonly logger: LayerLogger;
+    /** What cancels this run, when it was executed with one: check it in a long loop. */
+    readonly signal: AbortSignal | undefined;
+    /**
+     * This run: its id, use case, flow (`correlationId`) and cause. A subscriber of a delivered
+     * event finds the envelope's id as `causationId` — the key that makes executing it twice
+     * harmless.
+     */
+    readonly execution: Execution;
+    abstract execute(command: C): R | Promise<R>;
+}
+export declare abstract class ApplicationService<C extends Command<R> | DomainEvent, R, Context extends object = ContextValues> extends Feature<C, R, Context> {
+    /** The context's Features, run as children of this execution. */
+    protected readonly featureBus: FeatureBus;
+}
+/** @internal — what a run finds on `this` that no dependency may take. */
+export declare const RESERVED_MEMBERS: ReadonlySet<string>;

package/dist/core/domain/services.js

@@ -0,0 +1,31 @@
+/**
+ * The services of the application layer, as sincpro_framework's: a Feature executes one
+ * registered Command — or domain event, as its subscriber —; an ApplicationService composes its
+ * context's Features.
+ *
+ *     @project.feature(CommandCancelIssue)
+ *     class CancelIssue extends Feature<CommandCancelIssue, ResponseCancelIssue> {
+ *       static readonly serviceName = "CancelIssue";
+ *       async execute(command: CommandCancelIssue) {
+ *         this.logger.info("Cancelling");                 // bound to this run
+ *         return new ResponseCancelIssue(await this.client.cancelIssue(command));
+ *       }
+ *     }
+ *
+ * Context: while a method runs, `this.context`, `this.span`, `this.logger`, `this.featureBus` and
+ * every dependency are that run's (`executeService`). `serviceName` is stable metadata, never
+ * `constructor.name`, which a minifier renames.
+ */
+export class Feature {
+}
+export class ApplicationService extends Feature {
+}
+/** @internal — what a run finds on `this` that no dependency may take. */
+export const RESERVED_MEMBERS = new Set([
+    "featureBus",
+    "context",
+    "span",
+    "logger",
+    "signal",
+    "execution",
+]);

package/dist/core/entrypoint/bounded-context.d.ts

@@ -0,0 +1,139 @@
+import type { ContextValues } from "../../context/domain/store.js";
+import { type Context } from "../../context/entrypoint/context.js";
+import { type CommandBus } from "../domain/bus.js";
+import { type Answer, type AnyCommand, Command, type CommandClass, DomainEvent, type EventClass, type Executable, type ResponseClass } from "../domain/dto.js";
+import type { ErrorClass, ErrorHandler } from "../domain/errors.js";
+import type { Cause, ExecuteOptions, ExecutionCompleted, ExecutionFailed, ExecutionStarted, Extension, Interceptor, Listener } from "../domain/pipeline.js";
+import { type ExecutableClass } from "../services/listening.js";
+import type { LayerLogger } from "../../observability/domain/logging.js";
+interface Executor<C extends Executable, R> {
+    execute(executable: C): R | Promise<R>;
+}
+type ServiceClass<C extends Executable, R> = {
+    new (): Executor<C, R>;
+    readonly serviceName: string;
+};
+/** What a service is registered for: a Command's class or a domain event's. */
+type DtoClass = ExecutableClass;
+/** The service a registration takes the place of, as the backend's `replaces=`. */
+export type RegistrationOptions = {
+    replaces?: abstract new (...args: never[]) => object;
+};
+/** What `feature(...)` and `appService(...)` answer: the function that registers the service. */
+export type Registrar<T extends Executable> = <S extends ServiceClass<NoInfer<T>, Answer<NoInfer<T>>>>(Service: S, decorator?: ClassDecoratorContext<S>) => S;
+/**
+ * A bounded context: the bus of its Commands and domain events, as sincpro_framework's
+ * `UseFramework`.
+ *
+ *     const project = new BoundedContext<ProjectDependencies>("project");
+ *     project.addDependency("client", clientOf(transport));
+ *     project.feature(CommandCancelIssue)(CancelIssue);          // or @project.feature(...)
+ *     project.feature(IssueClosed)(NotifyWatchers);              // a subscriber of an event
+ *     project.feature(CommandCancelIssue, { replaces: CancelIssue })(CancelAndArchive);
+ *     project.addFeatureErrorHandler(toEmptyWhenMissing);
+ *     project.expectErrors(IssueLocked);                         // refused, never reported
+ *     await project.execute(new CommandCancelIssue("x"));        // ResponseCancelIssue
+ *     await project.execute(new IssueClosed("x"));               // what its subscriber returns
+ *     project.logger.info("Catalog preloaded");
+ *
+ * Context: registrations, dependencies, handlers and expected errors are snapshotted per
+ * generation; a call keeps the generation it started with, and what is added later answers from
+ * the next call — as the backend's `build_root_bus`. A domain event is executed as a Command is:
+ * one subscriber per bounded context, through the same pipeline; carrying it to every bounded
+ * context that hears it (a queue, an outbox) is the platform's.
+ */
+export declare class BoundedContext<D extends object = Record<never, never>, C extends object = ContextValues> {
+    readonly name: string;
+    /** Its level of the context: what every use case of it runs with, under the process's. */
+    readonly context: Context<C>;
+    /** Its own logger, named after it: for what it does outside a use case. */
+    readonly logger: LayerLogger;
+    private readonly registrations;
+    private readonly dependencyValues;
+    private readonly handlers;
+    private readonly expected;
+    private readonly interceptors;
+    private readonly listeners;
+    private revision;
+    private builtRevision;
+    private built;
+    constructor(name: string);
+    get deps(): Readonly<D>;
+    addDependency<K extends keyof D & string>(name: K, dependency: D[K], options?: {
+        replaces: D[K];
+    }): this;
+    /**
+     * Registers the Feature that executes a Command — or that subscribes to a domain event. With
+     * `replaces`, it takes the place of the service registered now for it.
+     */
+    feature<T extends AnyCommand>(command: CommandClass<T>, options?: RegistrationOptions): Registrar<T>;
+    feature<E extends DomainEvent>(event: EventClass<E>, options?: RegistrationOptions): Registrar<E>;
+    /** Registers the ApplicationService of a Command or a domain event; `replaces` as `feature`. */
+    appService<T extends AnyCommand>(command: CommandClass<T>, options?: RegistrationOptions): Registrar<T>;
+    appService<E extends DomainEvent>(event: EventClass<E>, options?: RegistrationOptions): Registrar<E>;
+    /** The service registered now for a Command or an event class — what a `replaces` names. */
+    handlerOf(dto: DtoClass): (abstract new (...args: never[]) => object) | undefined;
+    /**
+     * The event class registered here under a wire name, or `undefined` when nothing here hears it
+     * — what a platform's queue rebuilds a stored event as, as the backend's `event_type(name)`.
+     */
+    eventTypeOf(name: string): EventClass<DomainEvent> | undefined;
+    /**
+     * Runs `interceptor` around every execution of these classes — of every one when none is
+     * named —, outermost first in the order registered. It may look, veto (throw), adjust what it
+     * passes on (of the same class) or answer by itself. Registered after a call, it wraps from
+     * the next one.
+     */
+    interceptor<T extends Executable = Executable>(...dtos: (abstract new (...args: never[]) => T)[]): <F extends Interceptor<T>>(interceptor: F) => F;
+    /** Stops `interceptor` wherever it was registered; from the next call. */
+    withoutInterceptor(interceptor: (...args: never[]) => unknown): this;
+    /** Hears every run of these classes (every one when none is named) begin. Answers how to stop. */
+    onStart(listener: Listener<ExecutionStarted>, ...dtos: DtoClass[]): () => void;
+    /** Hears every run of these classes whose service answered — not an answer a handler gave. */
+    onCompletion(listener: Listener<ExecutionCompleted>, ...dtos: DtoClass[]): () => void;
+    /** Hears every failure that escapes a call — after every handler —, once, where it failed. */
+    onFailure(listener: Listener<ExecutionFailed>, ...dtos: DtoClass[]): () => void;
+    /**
+     * Wires a component into this bounded context — its dependencies, services, interceptors,
+     * listeners, handlers — in one place: a module of an application, a plugin. `fresh()` copies
+     * all it registered.
+     */
+    extend(extension: Extension<this>): this;
+    /** Answers a failure that reaches `execute` (or a scope's): after every layer's handlers. */
+    addGlobalErrorHandler(handler: ErrorHandler): this;
+    /** Answers a Feature's failure, wherever it was executed from. */
+    addFeatureErrorHandler(handler: ErrorHandler): this;
+    /** Answers an ApplicationService's failure. */
+    addAppServiceErrorHandler(handler: ErrorHandler): this;
+    /**
+     * Errors of these classes are the business answering, not a fault: the run ends `refused`,
+     * its span is no error and nothing is reported. They are still thrown — or handled.
+     */
+    expectErrors(...types: ErrorClass[]): this;
+    /**
+     * Executes a Command — its Response, inferred —, or a domain event — its subscriber's answer.
+     * `{ signal }` cancels the run (it ends `aborted`); a delivered event's envelope continues its
+     * flow (`execute(event, envelope)`).
+     */
+    execute<R>(command: Command<R>, returnType?: ResponseClass<NoInfer<R>>): Promise<R>;
+    execute<R>(command: Command<R>, options: ExecuteOptions): Promise<R>;
+    execute(event: DomainEvent, options?: ExecuteOptions | Cause): Promise<unknown>;
+    scoped(context: Partial<C>): CommandBus;
+    buildRootBus(): void;
+    fresh(): BoundedContext<D, C>;
+    /** What escaped a call, told once, from where it first failed. */
+    private escaped;
+    private addErrorHandler;
+    private registrar;
+    /**
+     * 1. The service is of the layer it is registered in, for a Command or a domain event class.
+     * 2. The class has no service yet — or, with `replaces`, the one it has is that one.
+     * 3. Its `serviceName` is given and no other service has it; an event's `eventName` is given
+     *    and no other event class here has it — the name means one event.
+     * Final: registered, said on its spans when it replaced another; the next call answers with it.
+     */
+    private registerService;
+    private generation;
+    private buildGeneration;
+}
+export {};