@afora/core 0.0.8 → 0.0.9

package/dist/core/blueprint/optional.d.ts

@@ -1,6 +1,6 @@
 import type { OptionalProperty } from "../property/types/optional-property.type.js";
 import type { AnyPropertyConstructor } from "../property/types/property-collection.type.js";
-import type { AnyBlueprint, AnyBlueprintList, AnyRecordClass, BlueprintField, OptionalBlueprint, OptionalBlueprintList, OptionalRecord } from "./types/blueprint.interface.js";
+import type { AnyBlueprint, AnyBlueprintList, AnyBlueprintVariant, AnyRecordClass, BlueprintField, OptionalBlueprint, OptionalBlueprintList, OptionalBlueprintVariant, OptionalRecord } from "./types/blueprint.interface.js";
 /**
  * The version of `Property` that accepts `undefined`. Returns `Property` itself
  * when it is already optional, and the same class for the same `Property`.
@@ -13,6 +13,8 @@ export declare function optionalOf<Property extends AnyPropertyConstructor>(Prop
 export declare function optionalOf<Blueprint extends AnyBlueprint>(blueprint: Blueprint): OptionalBlueprint<Blueprint>;
 /** The version of `list` that, as a field of a blueprint, accepts `undefined`. */
 export declare function optionalOf<List extends AnyBlueprintList>(list: List): OptionalBlueprintList<List>;
+/** The version of `variant` that, as a field of a blueprint, accepts `undefined`. */
+export declare function optionalOf<Variant extends AnyBlueprintVariant>(variant: Variant): OptionalBlueprintVariant<Variant>;
 /**
  * The version of `record` that, as a field of a blueprint, accepts `undefined`
  * or an instance of `record`. Returns `record` itself when it is already optional.

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

@@ -10,9 +10,22 @@ import type { StandardSchemaV1 } from "../../standard/standard-schema.js";
 import type { Kind } from "../../symbols/kind.js";
 import type { listOf } from "../list.js";
 import type { optionalOf } from "../optional.js";
+import type { variantOf } from "../variant.js";
 import type { IBlueprintFactories, IBlueprintPlugin } from "./blueprint-plugin.interface.js";
 /** Any blueprint, whatever its properties, optional or not. */
 export type AnyBlueprint = IBlueprint<any, boolean>;
+/**
+ * Any variant field, whatever its key and its variants, optional or not.
+ * Written out, not as `IBlueprintVariant` of anything: every field of every
+ * blueprint is compared with it, and this way nothing is worked out for that.
+ */
+export interface AnyBlueprintVariant {
+    readonly [Kind]: "variant";
+    readonly key: string;
+    readonly variants: any;
+    readonly optional: boolean;
+    readonly "~standard": StandardSchemaV1.Props<any, any>;
+}
 /** Any list, whatever its item, optional or not. */
 export type AnyBlueprintList = IBlueprintList<any, boolean>;
 /**
@@ -40,9 +53,10 @@ export interface OptionalRecord<Record extends AnyRecordClass> {
 export type AnyOptionalRecord = OptionalRecord<AnyRecordClass>;
 /**
  * What a blueprint key holds: a property, a blueprint for a nested object, a
- * record, or a list of any of them.
+ * record, a list of any of them, or one of several blueprints told apart by a
+ * key.
  */
-export type BlueprintField = AnyPropertyConstructor | AnyBlueprint | AnyBlueprintList | AnyRecordClass | AnyOptionalRecord;
+export type BlueprintField = AnyPropertyConstructor | AnyBlueprint | AnyBlueprintList | AnyRecordClass | AnyOptionalRecord | AnyBlueprintVariant;
 /** Fields by key, e.g. `{ name: Name, address: Address }`. */
 export type IBlueprintCollection = Record<string, BlueprintField>;
 /** What a blueprint picks its fields from: a plugin, or another blueprint. */
@@ -66,7 +80,17 @@ type FieldSchema<Field, Mode extends FieldMode> = 0 extends 1 & Field ? TSchema
 } ? Optional extends true ? TOptional<CollectionSchema<Properties, Mode>> : CollectionSchema<Properties, Mode> : Field extends {
     readonly item: infer Item;
     readonly optional: infer Optional;
-} ? Optional extends true ? TOptional<TArray<FieldSchema<Item, Mode>>> : TArray<FieldSchema<Item, Mode>> : never;
+} ? Optional extends true ? TOptional<TArray<FieldSchema<Item, Mode>>> : TArray<FieldSchema<Item, Mode>> : VariantSchema<Field, Mode>;
+/**
+ * The schema of a variant field: its value as it is, since a union of objects
+ * is only read for whether the key is optional. Apart from `FieldSchema`, so
+ * that a field that is not a variant costs one comparison there.
+ */
+type VariantSchema<Field, Mode extends FieldMode> = Field extends {
+    readonly key: infer Key extends string;
+    readonly variants: infer Variants;
+    readonly optional: infer Optional;
+} ? Optional extends true ? TOptional<TUnsafe<VariantValue<Key, Variants, Mode>>> : TUnsafe<VariantValue<Key, Variants, Mode>> : never;
 /** Declares the records a field of a record class takes besides its own. */
 export declare const RecordAccepts: unique symbol;
 /** The values besides its instances and plain input that a field of `Record` takes. */
@@ -102,7 +126,31 @@ type FieldValue<Field, Mode extends FieldMode> = 0 extends 1 & Field ? Static<TS
     readonly properties: infer Properties extends IBlueprintCollection;
 } ? CollectionValue<Properties, Mode> : Field extends {
     readonly item: infer Item;
-} ? FieldValue<Item, Mode>[] : never;
+} ? FieldValue<Item, Mode>[] : Field extends {
+    readonly key: infer Key extends string;
+    readonly variants: infer Variants;
+} ? VariantValue<Key, Variants, Mode> : never;
+/**
+ * The value of a variant field: for each variant, its own value with `Key`
+ * set to its name, so that `value[Key]` tells which one it is. Anything for a
+ * field of any variants (as `AnyBlueprintVariant`'s).
+ */
+type VariantValue<Key extends string, Variants, Mode extends FieldMode> = 0 extends 1 & Variants ? any : {
+    [Tag in keyof Variants & string]: VariantMember<Key, Tag, Variants[Tag], Mode>;
+}[keyof Variants & string];
+/**
+ * The value of one variant named `Tag`. A blueprint gives its value with the
+ * key. A record class gives an instance, which has no key and is told apart
+ * by its class; what it takes is an instance or its plain input with the key,
+ * and its plain data has the key.
+ */
+type VariantMember<Key extends string, Tag, Variant, Mode extends FieldMode> = Variant extends AnyRecordClass ? Mode extends "value" ? InstanceType<Variant> : Mode extends "input" ? InstanceType<Variant> | Evaluate<{
+    readonly [Name in Key]: Tag;
+} & RecordInput<Variant>> : Evaluate<{
+    readonly [Name in Key]: Tag;
+} & RecordValueOf<Variant, "data">> : Evaluate<{
+    readonly [Name in Key]: Tag;
+} & FieldValue<Variant, Mode>>;
 /** The value of a record field, as `RecordSchema` describes it. */
 type RecordValueOf<Record extends AnyRecordClass, Mode extends FieldMode> = Mode extends "value" ? InstanceType<Record> : Mode extends "input" ? InstanceType<Record> | RecordInput<Record> | AcceptedBy<Record> : Record["blueprint"] extends IBlueprint<infer Properties, boolean> ? CollectionValue<Properties, "data"> : never;
 type ReadonlyOptionalKeys<Schemas> = {
@@ -196,6 +244,7 @@ export interface BlueprintHelpers {
     readonly listOf: typeof listOf;
     readonly optionalOf: typeof optionalOf;
     readonly propertyOf: typeof propertyOf;
+    readonly variantOf: typeof variantOf;
 }
 /**
  * What a blueprint's definition picks from: every source field, the field
@@ -223,7 +272,10 @@ export type CallableProperties<Fields> = {
  * @internal
  */
 export type OptionalProperties<Properties> = {
-    readonly [Key in keyof Properties]: Properties[Key] extends AnyPropertyConstructor ? OptionalProperty<Properties[Key]> : Properties[Key] extends AnyBlueprint ? OptionalBlueprint<Properties[Key]> : Properties[Key] extends AnyBlueprintList ? OptionalBlueprintList<Properties[Key]> : Properties[Key] extends AnyRecordClass ? OptionalRecord<Properties[Key]> : Properties[Key] extends AnyOptionalRecord ? Properties[Key] : never;
+    readonly [Key in keyof Properties]: Properties[Key] extends AnyPropertyConstructor ? OptionalProperty<Properties[Key]> : Properties[Key] extends AnyBlueprint ? OptionalBlueprint<Properties[Key]> : Properties[Key] extends AnyBlueprintList ? OptionalBlueprintList<Properties[Key]> : Properties[Key] extends AnyRecordClass ? OptionalRecord<Properties[Key]> : Properties[Key] extends AnyOptionalRecord ? Properties[Key] : Properties[Key] extends {
+        readonly key: infer Name extends string;
+        readonly variants: infer Variants extends BlueprintVariants;
+    } ? IBlueprintVariant<Name, Variants, true> : never;
 };
 export type BlueprintDefinition<Sources extends readonly BlueprintSource[], Properties extends IBlueprintCollection> = (ctx: BlueprintContext<Sources>) => Properties;
 export interface IBlueprint<Properties extends IBlueprintCollection, Optional extends boolean = false> {
@@ -288,6 +340,28 @@ export interface IBlueprintList<Item extends BlueprintField, Optional extends bo
     readonly "~standard": StandardSchemaV1.Props<ListShape<Item, "input", Optional>, ListShape<Item, "value", Optional>>;
 }
 type ListShape<Item, Mode extends FieldMode, Optional extends boolean> = Optional extends true ? FieldValue<Item, Mode>[] | undefined : FieldValue<Item, Mode>[];
+/** The variants of a variant field, by the value its key has for each: blueprints, or record classes. */
+export type BlueprintVariants = Readonly<Record<string, AnyBlueprint | AnyRecordClass>>;
+/**
+ * A field holding one of the objects of `Variants`, told apart by the value
+ * of `Key`, which is the name of the variant.
+ */
+export interface IBlueprintVariant<Key extends string, Variants extends BlueprintVariants, Optional extends boolean = false> {
+    readonly [Kind]: "variant";
+    /** The key that tells the variants apart; no variant declares it. */
+    readonly key: Key;
+    readonly variants: Variants;
+    /** Whether, as a field of a blueprint, it accepts `undefined`. */
+    readonly optional: Optional;
+    /**
+     * The Standard Schema of the field: `validate` gives the frozen value of
+     * the variant the key names, or the issues that reject the value.
+     */
+    readonly "~standard": StandardSchemaV1.Props<VariantShape<Key, Variants, "input", Optional>, VariantShape<Key, Variants, "value", Optional>>;
+}
+type VariantShape<Key extends string, Variants, Mode extends FieldMode, Optional extends boolean> = Optional extends true ? VariantValue<Key, Variants, Mode> | undefined : VariantValue<Key, Variants, Mode>;
+/** `Variant` as a field that accepts `undefined`. */
+export type OptionalBlueprintVariant<Variant extends AnyBlueprintVariant> = Variant extends IBlueprintVariant<infer Key, infer Variants, boolean> ? IBlueprintVariant<Key, Variants, true> : never;
 /** `List` as a field that accepts `undefined`. */
 export type OptionalBlueprintList<List extends AnyBlueprintList> = List extends IBlueprintList<infer Item, boolean> ? IBlueprintList<Item, true> : never;
 export {};

package/dist/core/blueprint/variant.d.ts

@@ -0,0 +1,32 @@
+import type { AnyBlueprint, AnyBlueprintVariant, BlueprintVariants, IBlueprintVariant } from "./types/blueprint.interface.js";
+/**
+ * A field holding one of several objects, told apart by the value of `key`:
+ * `variantOf("type", { click: Click, signup: Signup })` takes
+ * `{ type: "click", ...a Click }` or `{ type: "signup", ...a Signup }`. Each
+ * variant is a blueprint, which does not declare `key`: the field adds it,
+ * with the name of the variant for its value. A variant can also be a record
+ * class (an entity too): the value is then an instance of it, told apart by
+ * its class, and the key is only in what is given, in `toJSON` and in what is
+ * stored.
+ */
+export declare function variantOf<const Key extends string, const Variants extends BlueprintVariants>(key: Key, variants: Variants): IBlueprintVariant<Key, Variants>;
+/** `variant`, frozen, with the `~standard` that handles a value as `variant` does. */
+export declare function standardVariantOf<Variant extends object>(variant: Variant): Variant;
+type Variant = BlueprintVariants[string];
+/** The blueprint of a variant: itself, or that of the record class it is. */
+export declare function blueprintOfVariant(variant: Variant): AnyBlueprint;
+/**
+ * The variant that the plain `value` names with the key of `field`, if it
+ * names one: a blueprint or a record class.
+ */
+export declare function namedVariantOf(field: AnyBlueprintVariant, value: unknown): Variant | undefined;
+/** The blueprint of the variant that the plain `value` names with the key of `field`, if it names one. */
+export declare function variantOfValue(field: AnyBlueprintVariant, value: unknown): AnyBlueprint | undefined;
+/**
+ * The name of the variant `instance` is, a record of one of the classes of
+ * `field`; `undefined` when it is of none.
+ */
+export declare function variantNameOf(field: AnyBlueprintVariant, instance: unknown): string | undefined;
+/** Whether `value` is a field made by `variantOf`. */
+export declare function isBlueprintVariant(value: unknown): value is AnyBlueprintVariant;
+export {};

package/dist/core/entity/abstract-entity.d.ts

@@ -25,6 +25,11 @@ export declare const EntityLifetime: unique symbol;
 export declare const EXPIRES_AT = "expiresAt";
 /** The key a versioned entity adds to its identity. */
 export declare const ENTITY_VERSION_KEY = "version";
+/**
+ * The key of each stored row holding its schema version, for entities
+ * declared with `schemaVersion`; it is never a key of the entity.
+ */
+export declare const SCHEMA_VERSION_KEY = "$v";
 /** Whether `entityClass` was declared with `versioned: true`. */
 export declare function isVersionedEntityClass(entityClass: unknown): boolean;
 /**

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

@@ -9,7 +9,7 @@ import type { EntityBuilder, EntityBuilderSettings, IEntityIdentity } from "./ty
  * `options.plugins` picks from the plugins of `plugins`, catalogs made by
  * `recordPluginCatalogOf`.
  */
-export declare function entityBuilderOf<Identity extends IEntityIdentity, const Catalogs extends readonly IRecordPluginCatalog[] = []>({ identity, generateId, now, expiresAt, plugins: catalogs, }: EntityBuilderSettings<Identity, Catalogs>): EntityBuilder<Identity, RecordPluginContext<Catalogs>>;
+export declare function entityBuilderOf<Identity extends IEntityIdentity, const Catalogs extends readonly IRecordPluginCatalog[] = []>(settings: EntityBuilderSettings<Identity, Catalogs>): EntityBuilder<Identity, RecordPluginContext<Catalogs>>;
 /** Whether `value` is a class made by `entityOf`, or one extending it. */
 export declare function isEntityClass(value: unknown): value is AnyRecordClass & AnyEntityClass;
 /** Whether `value` is an entity, an instance of a class made by `entityOf`. */

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

@@ -25,3 +25,12 @@ export declare const DeletedEntity: import("../../index.js").DeclaredExceptionCl
 export declare const InvalidEntityExpiry: import("../../index.js").DeclaredExceptionClass<{
     readonly reason: string;
 }>;
+/**
+ * The schema evolution options of an entity are invalid: `schemaVersion` is
+ * not a positive integer, a step of `upgrade` is not a function or reaches a
+ * version outside `2..schemaVersion`, or `previousNames` holds something
+ * that cannot name a record, or its own name; `source` is the entity name.
+ */
+export declare const InvalidEntitySchemaVersion: import("../../index.js").DeclaredExceptionClass<{
+    readonly reason: string;
+}>;

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

@@ -0,0 +1,24 @@
+/**
+ * Under this key, the settings of an entity builder tell when what their
+ * `generateId` and `now` make is known to be valid, so that an entity does
+ * not check again the id and the date it has just made. Only for a builder
+ * that knows its own makers, as `std` does of its defaults: a generator an
+ * application configures is never vouched for.
+ * @internal
+ */
+export declare const MakesValid: unique symbol;
+/** @internal */
+export interface ValidMakers {
+    /** Whether the id `generateId` is about to make is one `id` accepts as it is. */
+    readonly id: () => boolean;
+    /** Whether the date `now` is about to make is one `createdAt` accepts as it is. */
+    readonly createdAt: () => boolean;
+}
+/**
+ * `settings` of an entity builder with `makers` vouching for its
+ * `generateId` and `now`.
+ * @internal
+ */
+export declare function vouching<const Settings extends object>(settings: Settings, makers: ValidMakers): Settings;
+/** The makers `settings` vouch for, if any. @internal */
+export declare function validMakersOf(settings: object): ValidMakers | undefined;

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

@@ -75,6 +75,30 @@ export interface EntityStorageOptions<Key extends string = string, Expires exten
      * blueprint. A record with no date never expires.
      */
     readonly expires?: Expires;
+    /**
+     * The version of the stored shape of the entity, 1 when absent. When set,
+     * every write stores it in each row under `SCHEMA_VERSION_KEY`, and reads
+     * bring older rows up to it with `upgrade` before parsing them.
+     */
+    readonly schemaVersion?: number;
+    /**
+     * The steps that bring a stored row from the version before each key up
+     * to that key: `{ 2: (data) => ({ ...data, slug: data.path }) }`. Each
+     * gets the raw stored data, without the version key.
+     */
+    readonly upgrade?: EntityUpgrades;
+    /**
+     * The names the entity had before (its `name` option), so a backfill
+     * (`app.migrate`) moves their rows to the current name, and `start()`
+     * accepts the rename.
+     */
+    readonly previousNames?: readonly string[];
+}
+/** A step of `upgrade`: the stored data of a version, as the next one. */
+export type EntityUpgrade = (data: Readonly<Record<string, unknown>>) => Record<string, unknown>;
+/** The `upgrade` steps of an entity, keyed by the version each one reaches. */
+export interface EntityUpgrades {
+    readonly [version: number]: EntityUpgrade;
 }
 /** A duration, e.g. `{ days: 400 }`. */
 export interface EntityDuration {
@@ -107,6 +131,12 @@ export type ExpiringIdentity<Identity extends IEntityIdentity, Expires> = Expire
 export interface EntityStorageSettings {
     readonly versioned: boolean;
     readonly expires?: EntityExpires;
+    /** Whether `schemaVersion` was declared, so rows carry the version key. */
+    readonly schemaVersioned: boolean;
+    /** `schemaVersion`, 1 when absent. */
+    readonly schemaVersion: number;
+    readonly upgrade: EntityUpgrades;
+    readonly previousNames: readonly string[];
 }
 /**
  * The unique keys of an entity: `id`, those listed in `options.unique`, and

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

@@ -0,0 +1,16 @@
+import type { AnyBlueprint } from "../blueprint/types/blueprint.interface.js";
+import type { AccessDeclaration } from "../use-case/types/access.interface.js";
+import type { OperationCallOptions } from "./types/output.interface.js";
+/** What `command.run` takes: the call options without the caller. */
+type RunOptions = {
+    readonly context?: unknown;
+} | undefined;
+/**
+ * The check of `access` for the operation `id`, made once: given the input
+ * and the options of a call, it throws `Unauthenticated` or `Forbidden`, or
+ * gives the options to run the command with (the context filled from the
+ * caller). Throws `InvalidOutputStage` when `access.context` names a key the
+ * `context` of the operation does not have.
+ */
+export declare function accessGuardOf(id: string, access: AccessDeclaration, context: AnyBlueprint | undefined): (input: unknown, options: OperationCallOptions | undefined) => RunOptions;
+export {};

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

@@ -6,3 +6,19 @@ export declare const InvalidOutputStage: import("../../index.js").DeclaredExcept
 export declare const DuplicateOperation: import("../../index.js").DeclaredExceptionClass<{
     readonly id: string;
 }>;
+/**
+ * An operation that declares its `access` was called without an
+ * authenticated caller: no credentials, or ones that were not accepted. A
+ * 401.
+ */
+export declare const Unauthenticated: import("../../index.js").DeclaredExceptionClass<undefined>;
+/**
+ * The caller is authenticated but may not call the operation: it lacks a
+ * scope the `access` of the operation asks for (`details.reason` is
+ * `"scope"`, with the missing `scopes`), or is not the owner (`"owner"`). A
+ * 403.
+ */
+export declare const Forbidden: import("../../index.js").DeclaredExceptionClass<{
+    readonly reason: "scope" | "owner";
+    readonly scopes?: readonly string[];
+}>;

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

@@ -0,0 +1,36 @@
+import type { CompileRoutesSettings, HttpOptions, RouteTable } from "./types/http.interface.js";
+import type { OperationDescriptor, StageContext } from "./types/output.interface.js";
+/** The option names of {@link HttpOptions}, for sinks that list their options. */
+export declare const HTTP_OPTION_KEYS: readonly ["basePath", "route", "responses", "requestId", "security", "docs", "debug", "context", "auth"];
+/**
+ * Why the {@link HttpOptions} are not valid, naming them `where.<option>`;
+ * `undefined` when they are. Other keys of `options` are not looked at.
+ */
+export declare function httpOptionsIssue(options: HttpOptions, where: string): string | undefined;
+/**
+ * The routes of `operations`, compiled once, for a sink that serves HTTP on
+ * any server: the sink routes each `method` and `path` to `handle` and sends
+ * the result as is. Everything a request needs is decided here, so a call
+ * only reads, coerces and runs:
+ *
+ * - The input is the JSON body of a `post`, `put` or `patch` and the query
+ *   of a `get` or `delete`, with the keys the route reads elsewhere over it:
+ *   `{name}` segments of the path, and the query keys, headers and cookies
+ *   the use case route declares. Text is coerced to the numbers and booleans
+ *   the input takes; the operation validates it (a 400 problem with `issues`).
+ * - The context comes from `context.headers` (coerced) and
+ *   `context.variables` (as is); a missing one leaves the key out.
+ * - An operation with an `access` other than `public` asks
+ *   `settings.authenticator` who calls; without one, or without credentials,
+ *   it is a 401.
+ * - Success is the route status with the response as JSON (sensitive values
+ *   masked by `toJSON`), or no body for `204`, plus the `responses` headers.
+ *   Errors are `application/problem+json`, with the status of `statusOf`
+ *   (the output `statuses` first). `requestId` puts the request id on every
+ *   result, `notFound` and `failure` included.
+ * - `docs.path` serves the `openapi` document of the same operations.
+ *
+ * Throws `InvalidOutputStage` (source `settings.source`) as `operationRoutes`
+ * does, and when `docs.path` is taken by a `get` route.
+ */
+export declare function compileRoutes(operations: readonly OperationDescriptor[], options: HttpOptions, context: StageContext, settings: CompileRoutesSettings): RouteTable;

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

@@ -1,4 +1,5 @@
 import type { OpenAPISchema } from "../openapi/types/openapi.interface.js";
+import type { RouteCookie } from "../use-case/types/route.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. */
@@ -146,10 +147,30 @@ export interface OperationRoute {
     readonly headers: {
         readonly [name: string]: string;
     };
+    /**
+     * Whether the input keys with no other place are a JSON body (`post`,
+     * `put`, `patch`); otherwise they are read from the query.
+     */
+    readonly body: boolean;
+    /** The input keys the use case route reads from the query, whatever the method. */
+    readonly query: readonly string[];
+    /** The input keys read from request headers, with the header of each (lower case). */
+    readonly requestHeaders: {
+        readonly [inputKey: string]: string;
+    };
+    /** The input keys read from cookies, with the cookie of each. */
+    readonly cookies: {
+        readonly [inputKey: string]: string;
+    };
+    /** The response keys sent as cookies instead of in the body, with the cookie of each. */
+    readonly setCookies: {
+        readonly [responseKey: string]: RouteCookie;
+    };
 }
 /**
  * The route of every operation, by id: `POST {basePath}/{kebab(command)}/{kebab(operation)}`
- * with `200`, changed per operation id with `route` and `responses`. Throws
+ * with `200`, changed by the route the use case declares (`operation.route`)
+ * and, over it, per operation id with `route` and `responses`. Throws
  * `InvalidOutputStage` (with `source`) when `route`, `responses` or
  * `security.operations` name an unknown operation, a path parameter is not a
  * scalar key of the input, or two operations share a method and path. The
@@ -179,5 +200,5 @@ export declare function operationRoutes(operations: readonly OperationDescriptor
  * 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 declare const openapi: import("./types/output.interface.js").SinkFactory<OpenAPIDocument, OpenAPISinkOptions, never>;
 export {};

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

@@ -1,8 +1,13 @@
 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>;
+/**
+ * A factory of sink stages: `openapi({ info })`. A sink that needs what JSON
+ * cannot hold (middlewares, an authenticator) takes it as a second argument,
+ * its `hooks`, which `build` receives and the description of the stage
+ * leaves out.
+ */
+export declare function sinkOf<Result, Options extends object = StageOptions, Hooks = never>(settings: SinkSettings<Result, Options, Hooks>): SinkFactory<Result, Options, Hooks>;
 /**
  * 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

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

@@ -11,7 +11,7 @@ export declare function raisedOf(error: Exception): 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, a concurrency conflict or an entity that already exists; 401 for
- * `UseCaseInvalidCredentials`; 422 for a class in `operation.errors`; 500 for the
+ * `UseCaseInvalidCredentials` and `Unauthenticated`; 403 for `Forbidden`; 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`.
  */

package/dist/core/output/types/http.interface.d.ts

@@ -0,0 +1,130 @@
+import type { DescribedJwtOptions } from "../../auth/types/jwt.interface.js";
+import type { Principal } from "../../use-case/types/access.interface.js";
+import type { OpenAPIMethod, OpenAPISinkOptions, RouteOptions } from "../openapi-sink.js";
+import type { OperationDescriptor } from "./output.interface.js";
+/**
+ * The options every sink that serves HTTP takes. JSON, so the stage can live
+ * in an `afora.json`. The routing options (`basePath`, `route`, `responses`,
+ * `requestId`, `security`) are those of the `openapi` sink, so the served
+ * routes and the document agree.
+ */
+export interface HttpOptions extends RouteOptions {
+    /** Serves the OpenAPI document of the same operations at `path`. */
+    readonly docs?: {
+        readonly path: string;
+        readonly info: OpenAPISinkOptions["info"];
+        readonly servers?: OpenAPISinkOptions["servers"];
+    };
+    /** Adds the `trace` to problems and the real `detail` to 5xx ones. Off by default. */
+    readonly debug?: boolean;
+    /**
+     * The context of an operation, by context key: from request headers
+     * (`{ headers: { locale: "accept-language" } }`) and from values a
+     * middleware of the server set for the request
+     * (`{ variables: { caller: "caller" } }`).
+     */
+    readonly context?: {
+        readonly headers?: {
+            readonly [contextKey: string]: string;
+        };
+        readonly variables?: {
+            readonly [contextKey: string]: string;
+        };
+    };
+    /**
+     * Who calls, from a JSON Web Token (see `jwtOf`; the secret is named by
+     * its environment variable, `{ env: "JWT_SECRET" }`): read from the
+     * `authorization` header (`Bearer <token>`; another header with `header`)
+     * and, with `cookie`, from that cookie when the header is absent. The
+     * document gets a matching security scheme unless `security` declares
+     * its own. An `authenticator` given in the hooks of the sink replaces it.
+     */
+    readonly auth?: {
+        readonly jwt: DescribedJwtOptions & {
+            readonly header?: string;
+            readonly cookie?: string;
+        };
+    };
+}
+/** A request, as the server of a sink gives it to the route table. */
+export interface HttpRequest {
+    /** The value of the `{name}` segment of the path, decoded. */
+    param(name: string): string | undefined;
+    /** The query string, the first value of each name. */
+    query(): Readonly<Record<string, string | undefined>>;
+    /** The value of a header, by its name in lower case. */
+    header(name: string): string | undefined;
+    /** The body, as text. Called at most once, and only by routes with a body. */
+    text(): string | Promise<string>;
+    /** A value a middleware of the server set for this request, by name. */
+    variable?(name: string): unknown;
+    /** The request of the server itself, for an authenticator that needs it. */
+    readonly native?: unknown;
+}
+/** The answer to a request: what the server of a sink has to send, as is. */
+export interface HttpResult {
+    readonly status: number;
+    /** `content-type` included, when there is a body. */
+    readonly headers: Readonly<Record<string, string>>;
+    /** One `set-cookie` header each. */
+    readonly cookies: readonly string[];
+    /** The body, already serialized (sensitive values masked), or `null` for none. */
+    readonly body: string | null;
+}
+/** What an authenticator reads of a request. */
+export interface AuthRequest {
+    /** The value of a header, by its name in lower case. */
+    header(name: string): string | undefined;
+    /** The value of a cookie of the request. */
+    cookie(name: string): string | undefined;
+    /** The operation being called. */
+    readonly operation: OperationDescriptor;
+    /** The request of the server itself. */
+    readonly native?: unknown;
+}
+/**
+ * Who is calling, from the credentials of a request: a `Principal`, or
+ * `null` for an anonymous caller. Called for each request to an operation
+ * with an `access` other than `public`. It may throw `Unauthenticated` to
+ * refuse credentials it does not accept.
+ */
+export type Authenticator = (request: AuthRequest) => Principal | null | Promise<Principal | null>;
+/** One operation, ready to serve: the server routes `method` and `path` to `handle`. */
+export interface CompiledRoute {
+    readonly operation: OperationDescriptor;
+    readonly method: OpenAPIMethod;
+    /** `basePath` included, parameters as `{name}`. */
+    readonly path: string;
+    /** The names of the `{name}` segments of `path`, in order. */
+    readonly parameters: readonly string[];
+    /** Never rejects: an error is a problem result. */
+    handle(request: HttpRequest): Promise<HttpResult>;
+}
+/** The routes of an output, compiled once (see `compileRoutes`). */
+export interface RouteTable {
+    readonly routes: readonly CompiledRoute[];
+    /** The route that serves the OpenAPI document, with `docs`. */
+    readonly docs?: {
+        readonly path: string;
+        handle(request?: Pick<HttpRequest, "header">): HttpResult;
+    };
+    /** The 404 problem for a request no route serves. */
+    notFound(request?: Pick<HttpRequest, "header">): HttpResult;
+    /**
+     * The problem for an error raised outside `handle`: its status is the one
+     * the output `statuses` give its name, else `status`, else `statusOf`.
+     */
+    failure(error: unknown, options?: {
+        readonly operation?: OperationDescriptor;
+        readonly status?: number;
+        readonly request?: Pick<HttpRequest, "header">;
+    }): HttpResult;
+}
+/** What `compileRoutes` takes besides the operations and the options. */
+export interface CompileRoutesSettings {
+    /** The name of the sink, for the messages of `InvalidOutputStage`. */
+    readonly source: string;
+    readonly authenticator?: Authenticator;
+    /** Changes the OpenAPI document before it is served (a sink with routes of its own kind). */
+    readonly document?: (document: unknown) => unknown;
+}

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

@@ -2,6 +2,8 @@ import type { AnyBlueprint } from "../../blueprint/types/blueprint.interface.js"
 import type { AnyCommand } from "../../command/types/command.interface.js";
 import type { JsonValue } from "../../json.js";
 import type { Kind } from "../../symbols/kind.js";
+import type { AccessDeclaration, Principal } from "../../use-case/types/access.interface.js";
+import type { RouteDeclaration } from "../../use-case/types/route.interface.js";
 import type { AnyExceptionClass } from "../../use-case/use-case.js";
 /** The options of a stage: a JSON object. */
 export type StageOptions = {
@@ -9,9 +11,15 @@ export type StageOptions = {
 };
 /** An HTTP-style status by exception name. */
 export type OutputStatuses = Readonly<Record<string, number>>;
-/** The call of an operation: `context` is what the command (or use case) declares. */
+/**
+ * The call of an operation: `context` is what the command (or use case)
+ * declares, and `principal` is who calls, as the sink authenticated it
+ * (`null` or absent for an anonymous caller). An operation with an `access`
+ * checks the principal before it runs.
+ */
 export interface OperationCallOptions {
     readonly context?: unknown;
+    readonly principal?: Principal | null;
 }
 /**
  * One operation of a command, as an output sees it. Frozen; transforms change
@@ -39,9 +47,16 @@ export interface OperationDescriptor {
     readonly context?: AnyBlueprint;
     /** The `errors` of the use case. */
     readonly errors: readonly AnyExceptionClass[];
+    /** The route the use case declares (`route` or `@Route`), if any. */
+    readonly route?: RouteDeclaration;
+    /** Who may call it, as the use case declares (`access` or `@Access`), if it does. */
+    readonly access?: AccessDeclaration;
     /** Set by transforms; `{}` initially. */
     readonly meta: Readonly<Record<string, unknown>>;
-    /** `command.run(name, input, options)`. */
+    /**
+     * `command.run(name, input, { context })`, after the check of `access`:
+     * it rejects with `Unauthenticated` or `Forbidden` before anything runs.
+     */
     invoke(input: unknown, options?: OperationCallOptions): Promise<unknown>;
 }
 /** What `operationOf` can change. */
@@ -92,15 +107,20 @@ export interface TransformSettings<Options extends object> {
     /** Why `options` cannot be used, or `undefined`. Checked when the stage is made. */
     readonly validate?: (options: Options) => string | undefined;
 }
-export interface SinkSettings<Result, Options extends object> {
+export interface SinkSettings<Result, Options extends object, Hooks = never> {
     readonly name: string;
-    readonly build: (operations: readonly OperationDescriptor[], options: Options, context: StageContext) => Result;
+    /**
+     * `hooks` is the second argument the stage was made with: what cannot be
+     * JSON (functions, an instance of a server). It is not part of the
+     * description of the stage.
+     */
+    readonly build: (operations: readonly OperationDescriptor[], options: Options, context: StageContext, hooks: Hooks | undefined) => Result;
     /** Why `options` cannot be used, or `undefined`. Checked when the stage is made. */
     readonly validate?: (options: Options) => string | undefined;
 }
 /** Makes a stage from JSON options. */
 export type TransformFactory<Options extends object = StageOptions> = (options?: Options) => TransformStage<Options>;
-export type SinkFactory<Result = unknown, Options extends object = StageOptions> = (options?: Options) => SinkStage<Result, Options>;
+export type SinkFactory<Result = unknown, Options extends object = StageOptions, Hooks = never> = (options?: Options, hooks?: Hooks) => SinkStage<Result, Options>;
 /** Any stage factory. */
 export type StageFactory = TransformFactory<any> | SinkFactory<any, any>;
 /** Stage factories by name. */