@sincpro/client-framework 0.5.0 → 1.0.0

package/dist/context/index.js

@@ -0,0 +1,15 @@
+/**
+ * The context: the levels a call sees (the process, its bounded context, a scope), where they
+ * live (`ContextStore`, a port each platform implements), what travels with a request, and the
+ * execution a run carries.
+ *
+ *   domain/          the ports and rules: `ContextStore`, `ContextCodec`, what travels, `Execution`
+ *   adapters/        the implementations this package gives: memory, the plain codec
+ *   entrypoint/      `Context`: one door over a level
+ *   infrastructure/  the process's store and its level (`processContext`)
+ */
+export { memoryContexts } from "./adapters/memory.js";
+export { plainCodec } from "./adapters/plain-codec.js";
+export { CONTEXT_HEADER, travelling, travels, } from "./domain/codec.js";
+export { BIND, } from "./domain/execution.js";
+export { processContext } from "./infrastructure/process.js";

package/dist/context/infrastructure/process.d.ts

@@ -0,0 +1,13 @@
+import type { ContextStore } from "../domain/store.js";
+import { type Context, type StoreSource } from "../entrypoint/context.js";
+/** @internal — `configureProcess` is the way in. */
+export declare function replaceProcessStore(store: ContextStore): void;
+/** The process's store as every level of the context reads it — the process's and each bounded context's. */
+export declare const processStore: StoreSource;
+/**
+ * The process's level of the context: what every use case of every bounded context runs with —
+ * the tenant, the company, the language.
+ *
+ *     processContext.set({ tenant_id: "acme" });
+ */
+export declare const processContext: Context;

package/dist/context/infrastructure/process.js

@@ -0,0 +1,35 @@
+import { memoryContexts } from "../adapters/memory.js";
+import { contextAt, } from "../entrypoint/context.js";
+/**
+ * Where this process keeps its context: the store `configureProcess` chose (`memoryContexts()`
+ * until it chooses), read on every call, never at import.
+ *
+ * Context: a level made before `main` configures the process (`project` is defined when its
+ * module loads) still reads the store chosen later; whoever listens moves to the new store and
+ * hears the change.
+ */
+let current = memoryContexts();
+const replacing = new Set();
+/** @internal — `configureProcess` is the way in. */
+export function replaceProcessStore(store) {
+    const before = current;
+    current = store;
+    if (current !== before)
+        for (const listener of [...replacing])
+            listener();
+}
+/** The process's store as every level of the context reads it — the process's and each bounded context's. */
+export const processStore = {
+    current: () => current,
+    replaced(listener) {
+        replacing.add(listener);
+        return () => void replacing.delete(listener);
+    },
+};
+/**
+ * The process's level of the context: what every use case of every bounded context runs with —
+ * the tenant, the company, the language.
+ *
+ *     processContext.set({ tenant_id: "acme" });
+ */
+export const processContext = contextAt("process", processStore);

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

@@ -0,0 +1,18 @@
+import type { AnyCommand, Command, ResponseClass } from "./dto.js";
+/** What executes a Command: the bounded context, a scope of it, an ApplicationService's features. */
+export interface CommandBus {
+    execute<R>(command: Command<R>, returnType?: ResponseClass<NoInfer<R>>): Promise<R>;
+}
+/** @internal — how a bus hands a Command to its generation. */
+export type Dispatch = (command: AnyCommand) => Promise<unknown>;
+/** @internal — the heterogeneous registry erases the type; registration checks the association. */
+export declare function executeTyped<R>(dispatch: Dispatch, command: Command<R>): Promise<R>;
+/**
+ * What an ApplicationService composes its context's Features through (`this.featureBus`): the
+ * same pipeline, as a child of the running execution, and Features only.
+ */
+export declare class FeatureBus implements CommandBus {
+    private readonly dispatch;
+    constructor(dispatch: Dispatch);
+    execute<R>(command: Command<R>, _returnType?: ResponseClass<NoInfer<R>>): Promise<R>;
+}

package/dist/core/domain/bus.js

@@ -0,0 +1,18 @@
+/** @internal — the heterogeneous registry erases the type; registration checks the association. */
+export async function executeTyped(dispatch, command) {
+    // As with Python's return_type, this does not validate the returned data at runtime.
+    return (await dispatch(command));
+}
+/**
+ * What an ApplicationService composes its context's Features through (`this.featureBus`): the
+ * same pipeline, as a child of the running execution, and Features only.
+ */
+export class FeatureBus {
+    dispatch;
+    constructor(dispatch) {
+        this.dispatch = dispatch;
+    }
+    execute(command, _returnType) {
+        return executeTyped(this.dispatch, command);
+    }
+}

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

@@ -0,0 +1,32 @@
+/**
+ * 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 declare abstract class DataTransferObject {
+    protected readonly dtoBrand: void;
+}
+export declare abstract class Response extends DataTransferObject {
+}
+declare const responseType: unique symbol;
+export declare abstract class Command<R> extends DataTransferObject {
+    /** Type-only association: absent from serialized DTOs and not a runtime validator. */
+    readonly [responseType]: R;
+}
+export type AnyCommand = Command<unknown>;
+/** What a Command answers. */
+export type Answer<C extends AnyCommand> = C[typeof responseType];
+/** A Command's class: what a service is registered for, by exact constructor identity. */
+export type CommandClass<C extends AnyCommand> = abstract new (...args: never[]) => C;
+/** A Response's class: the backend's `return_type`, accepted for the same reading. */
+export type ResponseClass<R> = abstract new (...args: never[]) => R;
+export {};

package/dist/core/domain/dto.js

@@ -0,0 +1,20 @@
+/**
+ * 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 {
+}

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/services.d.ts

@@ -0,0 +1,37 @@
+import type { ContextValues } from "../../context/domain/store.js";
+import type { FeatureBus } from "./bus.js";
+import type { Command } 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; 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>, 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;
+    abstract execute(command: C): R | Promise<R>;
+}
+export declare abstract class ApplicationService<C extends Command<R>, 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,28 @@
+/**
+ * The services of the application layer, as sincpro_framework's: a Feature executes one
+ * registered Command; 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",
+]);

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

@@ -0,0 +1,70 @@
+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, AnyCommand, Command, CommandClass, ResponseClass } from "../domain/dto.js";
+import type { ErrorClass, ErrorHandler } from "../domain/errors.js";
+import type { LayerLogger } from "../../observability/domain/logging.js";
+interface Executor<C extends AnyCommand, R> {
+    execute(command: C): R | Promise<R>;
+}
+type ServiceClass<C extends AnyCommand, R> = {
+    new (): Executor<C, R>;
+    readonly serviceName: string;
+};
+/**
+ * A bounded context: the bus of its Commands, as sincpro_framework's `UseFramework`.
+ *
+ *     const project = new BoundedContext<ProjectDependencies>("project");
+ *     project.addDependency("client", clientOf(transport));
+ *     project.feature(CommandCancelIssue)(CancelIssue);          // or @project.feature(...)
+ *     project.addFeatureErrorHandler(toEmptyWhenMissing);
+ *     project.expectErrors(IssueClosed);                         // refused, never reported
+ *     await project.execute(new CommandCancelIssue("x"));        // ResponseCancelIssue
+ *     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`.
+ */
+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 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;
+    feature<T extends AnyCommand>(command: CommandClass<T>): <S extends ServiceClass<NoInfer<T>, Answer<NoInfer<T>>>>(Service: S, decorator?: ClassDecoratorContext<S> | undefined) => S;
+    appService<T extends AnyCommand>(command: CommandClass<T>): <S extends ServiceClass<NoInfer<T>, Answer<NoInfer<T>>>>(Service: S, decorator?: ClassDecoratorContext<S> | undefined) => S;
+    /** 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;
+    execute<R>(command: Command<R>, _returnType?: ResponseClass<NoInfer<R>>): Promise<R>;
+    scoped(context: Partial<C>): CommandBus;
+    buildRootBus(): void;
+    fresh(): BoundedContext<D, C>;
+    private addErrorHandler;
+    private registrar;
+    private registerService;
+    private generation;
+    private buildGeneration;
+}
+export {};

package/dist/core/entrypoint/bounded-context.js

@@ -0,0 +1,252 @@
+import { contextAt, } from "../../context/entrypoint/context.js";
+import { processContext, processStore, } from "../../context/infrastructure/process.js";
+import { executeTyped, FeatureBus, } from "../domain/bus.js";
+import { ApplicationService, Feature, RESERVED_MEMBERS, } from "../domain/services.js";
+import { handled } from "../services/error-handlers.js";
+import { executeService } from "../services/execution.js";
+import { boundedContextLogger, logHandled, } from "../../observability/services/logging.js";
+function isExecutor(value) {
+    return (typeof value === "object" &&
+        value !== null &&
+        "execute" in value &&
+        typeof value.execute === "function");
+}
+/**
+ * A bounded context: the bus of its Commands, as sincpro_framework's `UseFramework`.
+ *
+ *     const project = new BoundedContext<ProjectDependencies>("project");
+ *     project.addDependency("client", clientOf(transport));
+ *     project.feature(CommandCancelIssue)(CancelIssue);          // or @project.feature(...)
+ *     project.addFeatureErrorHandler(toEmptyWhenMissing);
+ *     project.expectErrors(IssueClosed);                         // refused, never reported
+ *     await project.execute(new CommandCancelIssue("x"));        // ResponseCancelIssue
+ *     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`.
+ */
+export class BoundedContext {
+    name;
+    /** Its level of the context: what every use case of it runs with, under the process's. */
+    context;
+    /** Its own logger, named after it: for what it does outside a use case. */
+    logger;
+    registrations = new Map();
+    dependencyValues = new Map();
+    handlers = {
+        global: [],
+        feature: [],
+        application_service: [],
+    };
+    expected = [];
+    revision = 0;
+    builtRevision = -1;
+    built;
+    constructor(name) {
+        this.name = name;
+        if (name.trim() === "" || name.includes("/")) {
+            throw new TypeError("A bounded context needs a nonempty name without '/'");
+        }
+        this.context = contextAt(`bounded_context:${name}`, processStore);
+        this.logger = boundedContextLogger(name);
+    }
+    get deps() {
+        // The dependency interface is erased; the locator checks real registrations.
+        return new Proxy({}, {
+            get: (_target, key) => {
+                if (typeof key !== "string" || !this.dependencyValues.has(key)) {
+                    throw new Error(`Dependency is not registered: ${String(key)}`);
+                }
+                return this.dependencyValues.get(key);
+            },
+            set: () => {
+                throw new Error("Dependencies are read-only; use addDependency");
+            },
+            deleteProperty: () => {
+                throw new Error("Dependencies cannot be deleted");
+            },
+            defineProperty: () => {
+                throw new Error("Dependencies are read-only");
+            },
+            setPrototypeOf: () => {
+                throw new Error("Dependencies are read-only");
+            },
+        });
+    }
+    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);
+        this.revision++;
+        return this;
+    }
+    feature(command) {
+        return this.registrar(command, "feature");
+    }
+    appService(command) {
+        return this.registrar(command, "application_service");
+    }
+    /** Answers a failure that reaches `execute` (or a scope's): after every layer's handlers. */
+    addGlobalErrorHandler(handler) {
+        return this.addErrorHandler("global", handler);
+    }
+    /** Answers a Feature's failure, wherever it was executed from. */
+    addFeatureErrorHandler(handler) {
+        return this.addErrorHandler("feature", handler);
+    }
+    /** Answers an ApplicationService's failure. */
+    addAppServiceErrorHandler(handler) {
+        return this.addErrorHandler("application_service", handler);
+    }
+    /**
+     * 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) {
+        for (const type of types) {
+            if (typeof type !== "function")
+                throw new TypeError("An expected error is a class");
+            if (!this.expected.includes(type))
+                this.expected.push(type);
+        }
+        this.revision++;
+        return this;
+    }
+    execute(command, _returnType) {
+        return executeTyped((one) => this.generation().root(one, {}), command);
+    }
+    scoped(context) {
+        const scope = { ...context };
+        return new FeatureBus((command) => this.generation().root(command, scope));
+    }
+    buildRootBus() {
+        this.generation();
+    }
+    fresh() {
+        const fresh = new BoundedContext(this.name);
+        for (const [command, registration] of this.registrations) {
+            fresh.registrations.set(command, registration);
+        }
+        for (const [name, dependency] of this.dependencyValues) {
+            fresh.dependencyValues.set(name, dependency);
+        }
+        for (const where of ["global", "feature", "application_service"]) {
+            fresh.handlers[where].push(...this.handlers[where]);
+        }
+        fresh.expected.push(...this.expected);
+        fresh.revision = this.revision;
+        return fresh;
+    }
+    addErrorHandler(where, handler) {
+        if (typeof handler !== "function")
+            throw new TypeError("An error handler is a function");
+        this.handlers[where].push(handler);
+        this.revision++;
+        return this;
+    }
+    registrar(command, layer) {
+        return (Service, decorator) => {
+            const register = () => this.registerService(command, Service, layer);
+            // Standard decorators run before static fields have initialized.
+            if (decorator)
+                decorator.addInitializer(register);
+            else
+                register();
+            return Service;
+        };
+    }
+    registerService(command, Service, layer) {
+        const Base = layer === "feature" ? Feature : ApplicationService;
+        if (!(Service.prototype instanceof Base) ||
+            (layer === "feature" && Service.prototype instanceof ApplicationService)) {
+            throw new TypeError(`The service is not an ${layer}`);
+        }
+        if (this.registrations.has(command)) {
+            throw new Error("Command already registered: one executor across both layers");
+        }
+        const name = Service.serviceName;
+        if (typeof name !== "string" || name.trim() === "") {
+            throw new Error("A service needs a nonempty registered name");
+        }
+        if ([...this.registrations.values()].some((registration) => registration.name === name)) {
+            throw new Error(`Service name already registered: ${name}`);
+        }
+        this.registrations.set(command, { name, layer, Service });
+        this.revision++;
+    }
+    generation() {
+        if (this.built && this.builtRevision === this.revision)
+            return this.built;
+        const revision = this.revision;
+        const built = this.buildGeneration();
+        this.built = built;
+        this.builtRevision = revision;
+        return built;
+    }
+    buildGeneration() {
+        const registrations = new Map(this.registrations);
+        const dependencies = new Map(this.dependencyValues);
+        const handlers = {
+            global: [...this.handlers.global],
+            feature: [...this.handlers.feature],
+            application_service: [...this.handlers.application_service],
+        };
+        const expectedTypes = [...this.expected];
+        const expected = (error) => expectedTypes.some((type) => error instanceof type);
+        const instances = new Map();
+        for (const registration of registrations.values()) {
+            const instance = new registration.Service();
+            if (!isExecutor(instance)) {
+                throw new Error(`Registered service is unavailable: ${registration.name}`);
+            }
+            instances.set(registration, instance);
+        }
+        const dispatch = async (command, parent, featureOnly = false, scope = {}) => {
+            // Exact constructor identity: a subclass of a registered Command is another Command.
+            const target = registrations.get(Object.getPrototypeOf(command)?.constructor);
+            if (!target)
+                throw new Error("No executor registered for this command class");
+            if (featureOnly && target.layer !== "feature") {
+                throw new Error("An ApplicationService may compose only Features");
+            }
+            const service = instances.get(target);
+            if (!service) {
+                throw new Error(`Registered service is unavailable: ${target.name}`);
+            }
+            return executeService(service, command, {
+                boundedContext: this.name,
+                name: target.name,
+                layer: target.layer,
+                dependencies,
+                context: () => ({ ...processContext.values, ...this.context.values, ...scope }),
+                ...(parent ? { parent } : {}),
+                featureBus: (execution) => new FeatureBus((child) => dispatch(child, execution, true)),
+                expected,
+                handlers: handlers[target.layer],
+            });
+        };
+        return {
+            root: async (command, scope) => {
+                try {
+                    return await dispatch(command, undefined, false, scope);
+                }
+                catch (error) {
+                    if (handlers.global.length === 0)
+                        throw error;
+                    const answer = await handled(handlers.global, error);
+                    logHandled("bounded_context", { boundedContext: this.name });
+                    return answer;
+                }
+            },
+        };
+    }
+}

package/dist/core/entrypoint/screens.d.ts

@@ -0,0 +1,6 @@
+import type { Transport } from "../../client/domain/transport.js";
+/**
+ * Screen requests enter the same command pipeline as application services. A generated
+ * client injected into a Feature uses its raw transport instead, continuing that execution.
+ */
+export declare function screensTransport(transport: Transport, name?: string): Transport;