@afora/core 0.0.2 → 0.0.4

package/dist/core/command/command.d.ts

@@ -0,0 +1,25 @@
+import type { IBlueprintCollection } from "../blueprint/types/blueprint.interface.js";
+import { type EnvironmentDependencies } from "../environment/environment.js";
+import type { IRepositoryProvider } from "../repository/types/repository.interface.js";
+import type { AnyCommand, CommandOf, CommandSettings, CommandUseCases } from "./types/command.interface.js";
+/**
+ * Checks now that the repositories of `command` share a provider that has
+ * `transaction`, as its first call would; an application calls it when it
+ * binds the command to its provider.
+ * @internal
+ */
+export declare function verifyCommand(command: object): void;
+/**
+ * The provider whose transaction runs the calls of `command`, or `undefined`
+ * without a transaction or a repository.
+ * @internal
+ */
+export declare function commandTransactionProvider(command: object): IRepositoryProvider | undefined;
+/**
+ * Groups use cases under operation names and is the boundary of a call: the
+ * context is validated once, a transaction can wrap the use case, and the
+ * events it raised are handled by a policy once it succeeded.
+ */
+export declare function commandOf<const UseCases extends CommandUseCases, Context extends IBlueprintCollection | undefined = undefined, Environment extends EnvironmentDependencies | undefined = undefined>(settings: CommandSettings<UseCases, Context, Environment>): CommandOf<UseCases, Context, Environment>;
+/** Whether `value` is a command made by `commandOf`. */
+export declare function isCommand(value: unknown): value is AnyCommand;

package/dist/core/command/exceptions.d.ts

@@ -0,0 +1,33 @@
+import type { Issue } from "../parse/types/parse.interface.js";
+/** `commandOf` got a setting it cannot use; `details.reason` says which. */
+export declare const InvalidCommandDeclaration: import("../../index.js").DeclaredExceptionClass<{
+    readonly reason: string;
+}>;
+/** A command was asked for an operation it does not declare. */
+export declare const UnknownCommandOperation: import("../../index.js").DeclaredExceptionClass<{
+    readonly operation: string;
+}>;
+/** The context of a call does not fit the context blueprint of the command. */
+export declare const InvalidCommandContext: import("../../index.js").DeclaredExceptionClass<{
+    readonly issues: readonly Issue[];
+}>;
+/**
+ * The `env` of a call holds a key no environment of the command declares, or
+ * a value its blueprint rejects. It is configuration, not input.
+ */
+export declare const InvalidCommandEnvironment: import("../../index.js").DeclaredExceptionClass<{
+    readonly keys: readonly string[];
+    readonly issues: readonly Issue[];
+}>;
+/**
+ * An event handler failed after the call succeeded (and, with a
+ * transaction, committed). `handled` events ran before the failure and
+ * `remaining` events after it were not handled.
+ */
+export declare const CommandEventFailed: import("../../index.js").DeclaredExceptionClass<{
+    readonly operation: string;
+    /** The failed event; absent when a handler policy failed. */
+    readonly event?: string;
+    readonly handled: number;
+    readonly remaining: number;
+}>;

package/dist/core/command/types/command.interface.d.ts

@@ -0,0 +1,108 @@
+import type { BlueprintInput, IBlueprint, IBlueprintCollection } from "../../blueprint/types/blueprint.interface.js";
+import type { EntityEvent } from "../../entity/event.js";
+import type { AnyEnvironment, EnvironmentDependencies, MergedEnvironment } from "../../environment/environment.js";
+import type { ILogger } from "../../logger/logger.js";
+import type { Kind } from "../../symbols/kind.js";
+import type { AnyUseCaseClass, UseCaseInput, UseCaseOptions, UseCaseResponse } from "../../use-case/use-case.js";
+/** The use cases of a command, by operation name. */
+export type CommandUseCases = Readonly<Record<string, AnyUseCaseClass>>;
+/** What a handler policy gets next to the events. */
+export interface CommandEventInfo {
+    readonly command: AnyCommand;
+    readonly operation: string;
+    /** The context of the call, validated by the command's blueprint if it has one. */
+    readonly context: unknown;
+    /** The variables of the command's environments, with the `env` of the call over them. */
+    readonly env: Readonly<Record<string, unknown>>;
+    /**
+     * The logger of the application that bound the command, else the started
+     * application's; a logger that writes nothing without either.
+     */
+    readonly logger: ILogger;
+}
+/** Handles all the events of a call, once it succeeded. */
+export type CommandEventHandler = (events: readonly EntityEvent[], info: CommandEventInfo) => void | Promise<void>;
+/**
+ * What the command does with the events of a call, after it commits:
+ * `"after-commit"` awaits `event.handle()` in order, `"manual"` leaves them
+ * to `execute`, a function receives them all.
+ */
+export type CommandEvents = "after-commit" | "manual" | CommandEventHandler;
+/** Called when an event fails with the `"after-commit"` policy; the next event still runs. */
+export type CommandEventErrorHandler = (error: unknown, event: EntityEvent, info: CommandEventInfo) => void | Promise<void>;
+export interface CommandSettings<UseCases extends CommandUseCases, Context extends IBlueprintCollection | undefined = undefined, Environment extends EnvironmentDependencies | undefined = undefined> {
+    readonly name: string;
+    readonly description?: string;
+    readonly tags?: readonly string[];
+    /** What the caller supplies with each call; validated once by this blueprint. */
+    readonly context?: IBlueprint<Exclude<Context, undefined>>;
+    readonly useCases: UseCases;
+    /** Runs every call in a transaction of the provider of the repositories. Default `false`. */
+    readonly transaction?: boolean;
+    /**
+     * One environment, or a list merged in order: read on first use as
+     * `command.env`, given to the event handlers, and to the use cases that
+     * declare the same environment, with the `env` of a call over them.
+     */
+    readonly environmentDependencies?: Environment;
+    readonly events?: CommandEvents;
+    readonly onEventError?: CommandEventErrorHandler;
+}
+/** The names of the operations of a command. */
+export type CommandOperation<Command extends {
+    readonly useCases: object;
+}> = keyof Command["useCases"] & string;
+/** The input of an operation. */
+export type CommandInput<Command extends {
+    readonly useCases: CommandUseCases;
+}, Op extends CommandOperation<Command>> = UseCaseInput<Command["useCases"][Op]>;
+/** The response of an operation. */
+export type CommandResponse<Command extends {
+    readonly useCases: CommandUseCases;
+}, Op extends CommandOperation<Command>> = UseCaseResponse<Command["useCases"][Op]>;
+/**
+ * The options of a call: `{ context }` of the command when it declares one,
+ * otherwise those of the use case.
+ */
+export type CommandOptions<Class extends AnyUseCaseClass, Context extends IBlueprintCollection | undefined, Environment extends EnvironmentDependencies | undefined = undefined> = Context extends IBlueprintCollection ? [
+    options: {
+        readonly context: BlueprintInput<Context>;
+    } & CommandEnvOption<Environment>
+] : Class["context"] extends IBlueprint<infer Properties> ? [options: UseCaseOptions<Properties> & CommandEnvOption<Environment>] : Environment extends undefined ? [] : [options?: CommandEnvOption<Environment>];
+/**
+ * The `env` a call can give, when the command declares environments: some of
+ * their variables, in place of the loaded ones for this call.
+ */
+export type CommandEnvOption<Environment extends EnvironmentDependencies | undefined> = Environment extends undefined ? {
+    readonly env?: undefined;
+} : {
+    readonly env?: Partial<MergedEnvironment<Environment>>;
+};
+/** What `execute` gives: the response and the events, with no policy applied. */
+export interface CommandExecution<Value> {
+    readonly value: Value;
+    readonly events: EntityEvent[];
+}
+/** A command made by `commandOf`. */
+export interface CommandOf<UseCases extends CommandUseCases, Context extends IBlueprintCollection | undefined = undefined, in out Environment extends EnvironmentDependencies | undefined = undefined> {
+    readonly [Kind]: "command";
+    readonly commandName: string;
+    readonly description: string | undefined;
+    readonly tags: readonly string[];
+    readonly context: Context extends IBlueprintCollection ? IBlueprint<Context> : undefined;
+    readonly useCases: Readonly<UseCases>;
+    readonly transaction: boolean;
+    /** The environments of `environmentDependencies`, as a list. */
+    readonly environments: readonly AnyEnvironment[];
+    /** Their variables, merged; read and validated on first use (`InvalidEnvironment`). */
+    readonly env: MergedEnvironment<Environment>;
+    readonly events: CommandEvents;
+    readonly onEventError: CommandEventErrorHandler | undefined;
+    readonly operations: readonly (keyof UseCases & string)[];
+    /** Runs `op` and applies the event policy; gives its response. */
+    run<Op extends keyof UseCases & string>(op: Op, input: UseCaseInput<UseCases[Op]>, ...options: CommandOptions<UseCases[Op], Context, Environment>): Promise<UseCaseResponse<UseCases[Op]>>;
+    /** Runs `op` and gives the response and the events, without applying the policy. */
+    execute<Op extends keyof UseCases & string>(op: Op, input: UseCaseInput<UseCases[Op]>, ...options: CommandOptions<UseCases[Op], Context, Environment>): Promise<CommandExecution<UseCaseResponse<UseCases[Op]>>>;
+}
+/** Any command. */
+export type AnyCommand = CommandOf<any, any, any>;

package/dist/core/entity/event.d.ts

@@ -1,3 +1,4 @@
+import { type ILogger } from "../logger/logger.js";
 /** A class made by `entityOf`, including subclasses. */
 export declare const EntityClassBrand: unique symbol;
 export type AnyEntityClass = (abstract new (value: never) => object) & {
@@ -9,11 +10,20 @@ export interface EventDefinition {
     readonly name: string;
     readonly [EventBrand]: true;
 }
+/** What the handler of an event gets next to the entity. */
+export interface EventHandlerContext {
+    /**
+     * The logger of the application whose command raised the event; else the
+     * started application's; a logger that writes nothing without either.
+     */
+    readonly logger: ILogger;
+}
 /** One queued occurrence, referencing the original entity rather than a snapshot. */
 export interface EntityEvent<Entity = object> {
     readonly name: string;
     readonly entity: Entity;
-    handle(): Promise<void>;
+    /** Runs the handler; `logger` replaces the one it would get. */
+    handle(context?: Partial<EventHandlerContext>): Promise<void>;
 }
 export type EntityEventReference = EventDefinition | readonly EventDefinition[] | (() => EventDefinition | readonly EventDefinition[]);
 export interface EntityEvents {
@@ -23,7 +33,7 @@ export interface EntityEvents {
 }
 export declare const EntityEventSettings: unique symbol;
 /** Defines an event without executing its handler. */
-export declare function eventOf<Class extends AnyEntityClass>(name: string, entityClass: Class, handler: (entity: InstanceType<Class>) => Promise<void>): EventDefinition;
+export declare function eventOf<Class extends AnyEntityClass>(name: string, entityClass: Class, handler: (entity: InstanceType<Class>, context: EventHandlerContext) => Promise<void>): EventDefinition;
 export declare function enqueueEvent(entity: object, event: EventDefinition): void;
 export declare function pullEntityEvents<Entity extends object>(entity: Entity): EntityEvent<Entity>[];
 export declare function enqueueLifecycle(entity: object, cycle: keyof EntityEvents): void;

package/dist/core/environment/environment.d.ts

@@ -24,7 +24,10 @@ export type AnyEnvironment = IEnvironment<any>;
 export type EnvironmentValue<Environment extends AnyEnvironment> = ReturnType<Environment["load"]>;
 /** One environment, or a list of them, whose variables are merged in order. */
 export type EnvironmentDependencies = AnyEnvironment | readonly AnyEnvironment[];
-/** The variables of every environment of `Dependencies`, merged. */
+/**
+ * The variables of every environment of `Dependencies`, merged.
+ * @internal
+ */
 export type MergedEnvironment<Dependencies extends EnvironmentDependencies | undefined> = Dependencies extends AnyEnvironment ? EnvironmentValue<Dependencies> : Dependencies extends readonly AnyEnvironment[] ? UnionToIntersection<EnvironmentValue<Dependencies[number]>> & Readonly<Record<never, never>> : Readonly<Record<never, never>>;
 type UnionToIntersection<Union> = (Union extends unknown ? (value: Union) => void : never) extends (value: infer Intersection) => void ? Intersection : never;
 /** A variable of the environment is missing or rejected by its blueprint. */

package/dist/core/exception/exception.d.ts

@@ -47,6 +47,10 @@ export interface DeclaredExceptionClass<Details = undefined> {
     readonly layer: ExceptionLayers;
     from: typeof Exception.from;
 }
+/** Whether `value` is a class made by `exceptionOf`. */
+export declare function isDeclaredException(value: unknown): value is DeclaredExceptionClass<never>;
+/** The message `exceptionOf` got, when it was a string; `undefined` otherwise. */
+export declare function declaredMessageOf(Declared: DeclaredExceptionClass<never>): string | undefined;
 /**
  * Declares an exception of `layer`, e.g.
  * `throw new PropertyRequired({ source: "email" })`. Its `details` are typed

package/dist/core/exception/exported.d.ts

@@ -0,0 +1,4 @@
+/** Counts `Exception` classes the package exports from a module the core cannot import. */
+export declare function markExported(...classes: readonly unknown[]): void;
+/** Whether `Declared` is an exception class exported by the package. */
+export declare function isExportedException(Declared: unknown): boolean;

package/dist/core/json.d.ts

@@ -0,0 +1,10 @@
+/** A JSON value. */
+export type JsonValue = null | boolean | number | string | readonly JsonValue[] | {
+    readonly [key: string]: JsonValue;
+};
+/**
+ * A deep, frozen copy of `value`, which must be finite, acyclic JSON made of
+ * plain objects and arrays. `subject` names it in the messages (e.g.
+ * "Provider options") and `fail` raises the error of the caller.
+ */
+export declare function frozenJson(value: unknown, subject: string, fail: (reason: string) => never, seen?: Set<object>): JsonValue;

package/dist/core/logger/exceptions.d.ts

@@ -0,0 +1,4 @@
+/** `logProviderOf`, `logFrom` or the `log` of an application got something it cannot use. */
+export declare const InvalidLogDeclaration: import("../../index.js").DeclaredExceptionClass<{
+    readonly reason: string;
+}>;

package/dist/core/logger/logger.d.ts

@@ -0,0 +1,106 @@
+import { Kind } from "../symbols/kind.js";
+/** What a log line carries besides its event. */
+export type LogFields = Readonly<Record<string, unknown>>;
+export type LogLevel = "debug" | "info" | "warn" | "error";
+export declare const LogLevels: readonly LogLevel[];
+/** What logs: an application, a use case through its `Logger` dependency, your code. */
+export interface ILogger {
+    debug(event: string, fields?: LogFields): void;
+    info(event: string, fields?: LogFields): void;
+    warn(event: string, fields?: LogFields): void;
+    error(event: string, fields?: LogFields): void;
+}
+/** One line, as a log provider gets it. */
+export interface LogEntry {
+    /** ISO 8601. */
+    readonly at: string;
+    readonly level: LogLevel;
+    readonly event: string;
+    readonly fields: LogFields;
+    /** The name of the application that logged it. */
+    readonly application: string;
+}
+/**
+ * Where lines go: the console, JSON on stdout, a log service, memory. An
+ * application writes each line to every provider of its `log`.
+ */
+export interface ILogProvider {
+    write(entry: LogEntry): void | Promise<void>;
+    /** Called on `app.stop()`, to send what is still buffered. */
+    flush?(): Promise<void>;
+}
+/** The `log` of an application. */
+export interface LogSettings {
+    /** Lines below it are dropped. `"info"` by default. */
+    readonly level?: LogLevel;
+    readonly providers: readonly ILogProvider[];
+}
+/** What `logProviderOf` takes. */
+export interface LogProviderSettings<Provider extends ILogProvider> {
+    /** Shown by `app.describe()`; anonymous providers are opaque. */
+    readonly name?: string;
+    readonly write: Provider["write"];
+    readonly flush?: Provider["flush"];
+}
+/** A log provider, checked, and named for `describe()` when `name` is given. */
+export declare function logProviderOf(settings: LogProviderSettings<ILogProvider>): ILogProvider;
+/** The name `logProviderOf` gave a provider, if any. */
+export declare function logProviderNameOf(provider: ILogProvider): string | undefined;
+/** A readable line on the console, by level: for local development. */
+export declare function consoleLogProvider(): ILogProvider;
+/** One JSON object per line on stdout: for Lambda, containers, CloudWatch. */
+export declare function jsonLogProvider(): ILogProvider;
+/** A provider that keeps the lines, for tests. */
+export interface MemoryLogProvider extends ILogProvider {
+    readonly entries: readonly LogEntry[];
+    clear(): void;
+}
+/** Keeps every line in `entries`, for tests. */
+export declare function memoryLogProvider(): MemoryLogProvider;
+/** Throws unless `settings` is a usable `log`; gives it with the default level. */
+export declare function checkLogSettings(settings: unknown): Required<LogSettings>;
+/** A logger that writes nothing. */
+export declare const silentLogger: ILogger;
+/**
+ * The logger of an application: drops what is below `level`, writes the rest
+ * to every provider, and never lets a provider break the call or the others.
+ * `settings` can be set later (a `log` made on start) and unset on stop.
+ */
+export declare function applicationLogger(application: string): {
+    logger: ILogger;
+    readonly settings: Required<LogSettings> | undefined;
+    set(settings: Required<LogSettings> | undefined): void;
+    flush(): Promise<void>;
+};
+/**
+ * The `Logger` dependency of a use case: `dependencies: { logger: Logger }`
+ * gives an `ILogger`, the one of the application it runs in.
+ */
+export interface LoggerDeclaration {
+    readonly [Kind]: "logger";
+}
+export declare const Logger: LoggerDeclaration;
+export declare function isLoggerDeclaration(value: unknown): value is LoggerDeclaration;
+/** Whether `value` can stand for a logger (an override in `execute`). */
+export declare function isLogger(value: unknown): value is ILogger;
+/**
+ * Carries the logger of an application, when it has a `log`: on the
+ * application and on the use case classes it binds.
+ */
+export declare const ApplicationLoggerKey: unique symbol;
+/**
+ * The logger a call writes to: the one its scope carries, else the one of
+ * the application its class was bound by, else the started application's.
+ */
+export declare function resolveLogger(scoped: ILogger | undefined, owner: unknown): ILogger | undefined;
+/** Milliseconds, for timing; `Date.now` where there is no `performance`. */
+export declare function clock(): number;
+export declare function elapsed(since: number): number;
+/**
+ * Logs a failure once: the same exception passes through every use case and
+ * command up the call, each wrapping it. `warn` for a declared exception,
+ * `error` for an unexpected one, with its trace.
+ */
+export declare function logFailure(logger: ILogger | undefined, event: string, fields: LogFields, error: unknown): void;
+/** Writes one line; a logger that throws never breaks the call it logs. */
+export declare function writeLog(logger: ILogger | undefined, level: LogLevel, event: string, fields: LogFields): void;

package/dist/core/output/exceptions.d.ts

@@ -0,0 +1,8 @@
+/** `outputOf`, an operation patch or a stage got something it cannot use; `details.reason` says what. */
+export declare const InvalidOutputStage: import("../../index.js").DeclaredExceptionClass<{
+    readonly reason: string;
+}>;
+/** Two operations of an output share an id. */
+export declare const DuplicateOperation: import("../../index.js").DeclaredExceptionClass<{
+    readonly id: string;
+}>;

package/dist/core/output/openapi-sink.d.ts

@@ -0,0 +1,83 @@
+import type { OpenAPISchema } from "../openapi/types/openapi.interface.js";
+import type { OperationDescriptor } from "./types/output.interface.js";
+declare const METHODS: readonly ["get", "post", "put", "patch", "delete"];
+/** An HTTP method an operation can be routed to. */
+export type OpenAPIMethod = (typeof METHODS)[number];
+/** The options of the `openapi` sink. */
+export interface OpenAPISinkOptions {
+    readonly info: {
+        readonly title: string;
+        readonly version: string;
+        readonly description?: string;
+    };
+    readonly servers?: readonly {
+        readonly url: string;
+        readonly description?: string;
+    }[];
+    /** Prefix of every path, e.g. `"/api"`. Empty by default. */
+    readonly basePath?: string;
+    /** Method and path by operation id, e.g. `{ "Users.login": { path: "/session" } }`. */
+    readonly route?: {
+        readonly [operationId: string]: {
+            readonly method?: OpenAPIMethod;
+            readonly path?: string;
+        };
+    };
+}
+/** An OpenAPI 3.1 document. */
+export interface OpenAPIDocument {
+    readonly openapi: "3.1.0";
+    readonly info: OpenAPISinkOptions["info"];
+    readonly servers?: OpenAPISinkOptions["servers"];
+    readonly paths: {
+        readonly [path: string]: Record<string, unknown>;
+    };
+    readonly components: {
+        readonly schemas: {
+            readonly [name: string]: OpenAPISchema;
+        };
+    };
+}
+/** The options that route operations: shared by the sinks that serve HTTP. */
+export interface RouteOptions {
+    readonly basePath?: string;
+    readonly route?: OpenAPISinkOptions["route"];
+}
+/** Where an operation is served. */
+export interface OperationRoute {
+    readonly method: OpenAPIMethod;
+    /** `basePath` included. */
+    readonly path: string;
+}
+/**
+ * Why `basePath` and `route` are not valid routing options, naming them
+ * `where.basePath` and `where.route`; `undefined` when they are.
+ */
+export declare function routeOptionsIssue(options: RouteOptions, where: string): string | undefined;
+/**
+ * The route of every operation, by id: `POST {basePath}/{kebab(command)}/{kebab(operation)}`,
+ * changed per operation id with `route`. Throws `InvalidOutputStage` (with
+ * `source`) when `route` names an unknown operation or two operations share a
+ * method and path. The routing of the `openapi` sink and of the sinks that
+ * serve HTTP.
+ */
+export declare function operationRoutes(operations: readonly OperationDescriptor[], options: RouteOptions, source?: string): ReadonlyMap<string, OperationRoute>;
+/**
+ * Builds an OpenAPI 3.1 document from the operations.
+ *
+ * Routes: `POST {basePath}/{kebab(command)}/{kebab(operation)}`, changed per
+ * operation id with `route`; two operations on one method and path throw
+ * `InvalidOutputStage`. The `operationId` is the id with its dot as an
+ * underscore (`Users.register` -> `Users_register`), unique or the build
+ * throws. `get` and `delete` send the input as query parameters, which needs
+ * every input field to be a scalar property. Responses: `200` with the
+ * response schema, `400` and `500` always, and the status of each declared
+ * error (`statusOf`: `statuses` of the output, else 422). Operations carry no
+ * repository dependencies, so `404` and `409` appear only when an error that
+ * maps to them is declared. Records and entities reachable from inputs and
+ * responses are named by class name in `components.schemas`, beside `Problem`
+ * (RFC 9457). The `context` of an operation is transport-specific and not
+ * part of the document; sinks that serve HTTP map it (headers, middleware).
+ */
+export declare const openapi: import("./types/output.interface.js").SinkFactory<OpenAPIDocument, OpenAPISinkOptions>;
+export {};

package/dist/core/output/output.d.ts

@@ -0,0 +1,19 @@
+import type { AnyOutput, OperationDescriptor, OperationPatch, OutputOf, OutputSettings, PipeResult, Stage } from "./types/output.interface.js";
+/**
+ * A modified copy of `operation`. Only `meta` (replaced), `tags`,
+ * `description`, `deprecated` and `invoke` can change; `kind`, `version`,
+ * `id`, `command`, `name`, `useCase`, `input`, `response`, `context` and
+ * `errors` cannot, and a patch naming them throws `InvalidOutputStage`.
+ */
+export declare function operationOf(operation: OperationDescriptor, patch: OperationPatch): OperationDescriptor;
+/**
+ * An output turns commands into operations and runs them through a pipe of
+ * stages: transforms change them, and a last sink builds something concrete
+ * (an OpenAPI document, an HTTP app, ...). The operations are computed once,
+ * at declaration; `build()` runs the sink the first time it is called.
+ * Throws `InvalidOutputStage` (or `DuplicateOperation`) for a bad declaration.
+ * `commands` takes commands, applications (all their commands) or a mix.
+ */
+export declare function outputOf<const Pipe extends readonly Stage[] = readonly []>(settings: OutputSettings<Pipe>): OutputOf<PipeResult<Pipe>>;
+/** Whether `value` is an output made by `outputOf`. */
+export declare function isOutput(value: unknown): value is AnyOutput;

package/dist/core/output/problem.d.ts

@@ -0,0 +1,15 @@
+import type { Problem, ProblemOptions } from "./types/output.interface.js";
+/** The media type of a problem response. */
+export declare const PROBLEM_MEDIA_TYPE = "application/problem+json";
+/**
+ * An RFC 9457 problem for `error`. `issues` (`path`, `code`, `message`; no
+ * values or causes) is present only for a 400, `trace` only with `debug`,
+ * and the `detail` of a 5xx is `"Internal error."` unless `debug` is set, so
+ * internal messages do not leak.
+ */
+export declare function problemOf(error: unknown, options: ProblemOptions): Problem;
+/**
+ * The JSON a sink sends: `JSON.parse(JSON.stringify(value))`. Every record
+ * goes through its `toJSON`, so sensitive values are always masked.
+ */
+export declare function outputValueOf(value: unknown): unknown;

package/dist/core/output/select.d.ts

@@ -0,0 +1,14 @@
+/** The options of `select`. */
+export interface SelectOptions {
+    /** Keep operations that have any of these tags. */
+    tags?: string[];
+    /** Keep only these operation ids, e.g. `"Users.register"`. */
+    operations?: string[];
+    /** Drop these operation ids. */
+    exclude?: string[];
+}
+/**
+ * Keeps the operations that match every given option: `tags` (any of),
+ * `operations` (ids to keep) and `exclude` (ids to drop).
+ */
+export declare const select: import("./types/output.interface.js").TransformFactory<SelectOptions>;

package/dist/core/output/stage.d.ts

@@ -0,0 +1,24 @@
+import type { IStageCatalog, SinkFactory, SinkSettings, Stage, StageDescription, StageFactory, StageOptions, TransformFactory, TransformSettings } from "./types/output.interface.js";
+/** A factory of transform stages: `select({ tags: ["public"] })`. */
+export declare function transformOf<Options extends object = StageOptions>(settings: TransformSettings<Options>): TransformFactory<Options>;
+/** A factory of sink stages: `openapi({ info })`. */
+export declare function sinkOf<Result, Options extends object = StageOptions>(settings: SinkSettings<Result, Options>): SinkFactory<Result, Options>;
+/**
+ * What a stage is: its kind, name and JSON options when it came from a
+ * factory, `{ kind: "opaque" }` otherwise (a hand-written stage needs an
+ * import mapping to be extracted).
+ */
+export declare function stageDescriptionOf(stage: Stage): StageDescription;
+/**
+ * Whether a factory made by `transformOf` or `sinkOf` builds transforms or
+ * sinks, without calling it; `undefined` for any other function.
+ */
+export declare function stageKindOf(factory: StageFactory): "transform" | "sink" | undefined;
+/** Whether `value` is shaped as a stage (made by a factory or written by hand). */
+export declare function isStage(value: unknown): value is Stage;
+/**
+ * A catalog of stage `factories`, by name: what resolves the name and
+ * options of a JSON pipe back to a stage. Throws `InvalidOutputStage` for a
+ * function that is not a factory or for two with the same name.
+ */
+export declare function stageCatalogOf<const Factories extends readonly StageFactory[]>(...stages: Factories): IStageCatalog;

package/dist/core/output/status.d.ts

@@ -0,0 +1,17 @@
+import { Exception } from "../exception/exception.js";
+import type { OperationDescriptor, OutputStatuses } from "./types/output.interface.js";
+/**
+ * The exception that raised `error` under its name: a use case or a command
+ * passes an exception up as a copy with the same name, no details and the
+ * original as its cause, so the original is the deepest one with that name.
+ */
+export declare function raisedOf(error: Exception): Exception;
+/**
+ * The HTTP-style status of an error, in this order: `statuses` by exception
+ * name; 400 for invalid input or context (and any exception whose
+ * `details.issues` is a list, except `InvalidCommandEnvironment`, a 500); 404 for a missing entity or operation; 409 for
+ * a unique violation; 422 for a class in `operation.errors`; 500 for the
+ * rest, errors that are not exceptions included. Exceptions match by name,
+ * or by class for `operation.errors`.
+ */
+export declare function statusOf(error: unknown, operation?: Pick<OperationDescriptor, "errors">, statuses?: OutputStatuses): number;