@afora/core 0.0.7 → 0.0.9

package/dist/core/repository/upcast.d.ts

@@ -0,0 +1,64 @@
+import type { EntityUpgrades } from "../entity/types/entity.interface.js";
+import type { RepositoryState } from "./state.js";
+import type { RepositoryData } from "./types/repository.interface.js";
+/** What happens to the value of one key of a collection. */
+type FieldStep = {
+    readonly kind: "property";
+    readonly fill?: unknown;
+    readonly renamedFrom?: string;
+} | {
+    readonly kind: "collection";
+    readonly fields: CollectionSteps;
+} | {
+    readonly kind: "list";
+    readonly item: FieldStep;
+} | {
+    readonly kind: "opaque";
+};
+/** The steps of the keys of a blueprint, and whether any of them does something. */
+interface CollectionSteps {
+    readonly fields: ReadonlyMap<string, FieldStep>;
+}
+/** How the rows of an entity are brought up to its current shape. */
+export interface UpcastPlan {
+    readonly versioned: boolean;
+    readonly version: number;
+    /** Whether the entity lists `previousNames`: its moved rows may hold old keys. */
+    readonly renamed: boolean;
+    readonly upgrade: EntityUpgrades;
+    readonly fields: CollectionSteps;
+}
+/** What `upcast` did to a row, for `app.migrate`. */
+export interface UpcastReport {
+    /** The version the row was stored at (1 without the version key). */
+    from: number;
+    /** Paths of the keys moved from their `renamedFrom`. */
+    readonly renamed: string[];
+    /** Paths of the keys given their `fill`. */
+    readonly filled: string[];
+    /** Paths of the keys the blueprint no longer declares. */
+    readonly removed: string[];
+}
+/** The plan of `entity`, even when it changes nothing but the keys it no longer declares. */
+export declare function fullUpcastPlanOf(entity: object): UpcastPlan;
+/**
+ * `data`, a row of an entity of `plan` as a provider gave it, in the current
+ * shape: without the version key, through each `upgrade` step from the
+ * version after the stored one up to `schemaVersion`, then the automatic
+ * steps of the current blueprint (`renamedFrom`, `fill`, and, with `drop`,
+ * leaving out keys it no longer declares). The steps run first because each
+ * is written against the shape of the version before it, which the
+ * automatic steps would already have changed. Throws
+ * `InvalidStoredSchemaVersion` for a version that is not a positive integer
+ * or is above `schemaVersion`.
+ */
+export declare function upcast(source: string, plan: UpcastPlan, data: RepositoryData, drop?: boolean, report?: UpcastReport): RepositoryData;
+/**
+ * `rows` of `state`'s entity in its current shape (see `upcast`); `rows`
+ * itself when the entity needs nothing. Throws `InvalidRepositoryData`
+ * caused by `InvalidStoredSchemaVersion` for a row it cannot bring up.
+ */
+export declare function upcastRows(state: RepositoryState, rows: readonly RepositoryData[]): readonly RepositoryData[];
+/** `data` with the version key of `state`'s entity, when it declares `schemaVersion`. */
+export declare function withSchemaVersion(entity: object, data: RepositoryData): RepositoryData;
+export {};

package/dist/core/schema/schema.d.ts

@@ -5,6 +5,34 @@ export declare function describeError(error: {
     instancePath: string;
     message: string;
 }): string;
+/** One TypeBox error, as `Errors` gives it. */
+export interface SchemaError {
+    readonly keyword: string;
+    readonly schemaPath: string;
+    readonly instancePath: string;
+    readonly params: object;
+    readonly message: string;
+}
+/**
+ * The errors of `value`, which `schema` rejects. For every schema but one
+ * they are what `schema.type.Errors(value)` gives: same errors, same order,
+ * same messages. The one is a discriminated union given an object, told by
+ * the variant its key names (see `errorsOfVariant`). TypeBox is only asked
+ * about a schema with a keyword that has no explanation here (`explainerOf`).
+ * @internal
+ */
+export declare function errorsOfSchema(schema: ISchema<TSchema>, value: unknown): readonly SchemaError[];
+/** The two checks of a schema, as functions. */
+export interface SchemaChecks {
+    match(value: unknown): boolean;
+    matchShape(value: unknown): boolean;
+}
+/**
+ * `schema.match` and `schema.matchShape`, compiled now, for who checks many
+ * values with one schema; those of a schema not made by `schemaOf` call it.
+ * @internal
+ */
+export declare function checksOfSchema(schema: ISchema<TSchema>): SchemaChecks;
 /** A schema class declared with `schemaOf`. */
 export interface SchemaClass<SchemaType extends TSchema> {
     new (type?: SchemaType): ISchema<SchemaType>;

package/dist/core/symbols/kind.d.ts

@@ -1,2 +1,2 @@
-/** Brands blueprints, lists and records, so none is told apart by its shape. */
+/** Brands blueprints, lists, variants and records, so none is told apart by its shape. */
 export declare const Kind: unique symbol;

package/dist/core/use-case/access.d.ts

@@ -0,0 +1,12 @@
+import type { AnyBlueprint } from "../blueprint/types/blueprint.interface.js";
+import type { AccessDeclaration } from "./types/access.interface.js";
+/** Whether `access` lets anyone in. */
+export declare function isPublicAccess(access: AccessDeclaration): access is {
+    readonly public: true;
+};
+/**
+ * The frozen declaration of `access` for a use case whose input is
+ * `blueprint`, or the reason it is not valid. The keys of `context` are
+ * checked where the context is known: when the use case becomes an operation.
+ */
+export declare function accessDeclarationOf(access: unknown, blueprint: AnyBlueprint): AccessDeclaration | string;

package/dist/core/use-case/decorators.d.ts

@@ -0,0 +1,40 @@
+import type { AccessDeclaration } from "./types/access.interface.js";
+import type { RouteSettings } from "./types/route.interface.js";
+/** What a decorator of this module is given besides the class: nothing it reads. */
+type ClassContext = {
+    readonly kind: string;
+};
+/** A class decorator for use cases, in the standard form and in the legacy one of TypeScript. */
+export type UseCaseDecorator = <UseCase extends abstract new (...args: any[]) => unknown>(value: UseCase, context?: ClassContext) => void;
+/**
+ * Says where a use case is served over HTTP, on the class itself:
+ *
+ * ```ts
+ * @Route("GET", "/posts/{slug}", { query: ["page"], cookie: { session: "sid" } })
+ * class ListPosts extends useCaseOf({ name: "ListPosts", blueprint, response }) {}
+ * ```
+ *
+ * The same as the `route` setting of `useCaseOf` (see `RouteDeclaration`), so
+ * `describe()`, the sinks and `afora.json` see one declaration. It names no
+ * server: the sink of an output does. Throws `InvalidUseCaseDeclaration` on
+ * a class that is not a use case, on one that already has another route
+ * (the same one again is accepted), and for a route that does not fit the
+ * input of the use case.
+ */
+export declare function Route(method: RouteSettings["method"], path?: string, options?: Omit<RouteSettings, "method" | "path">): UseCaseDecorator;
+export declare function Route(method: RouteSettings["method"], options?: Omit<RouteSettings, "method" | "path">): UseCaseDecorator;
+/**
+ * Says who may call a use case, on the class itself:
+ *
+ * ```ts
+ * @Access({ scopes: ["posts:write"], context: { userId: "subject" } })
+ * class PublishPost extends useCaseOf({ name: "PublishPost", blueprint, response, context }) {}
+ * ```
+ *
+ * The same as the `access` setting of `useCaseOf` (see `AccessDeclaration`).
+ * Throws `InvalidUseCaseDeclaration` on a class that is not a use case, on
+ * one that already declares another access (the same one again is accepted),
+ * and for a declaration that does not fit the input of the use case.
+ */
+export declare function Access(access: AccessDeclaration): UseCaseDecorator;
+export {};

package/dist/core/use-case/route.d.ts

@@ -0,0 +1,18 @@
+import type { AnyBlueprint } from "../blueprint/types/blueprint.interface.js";
+import type { OpenAPISchema } from "../openapi/types/openapi.interface.js";
+import type { RouteDeclaration } from "./types/route.interface.js";
+/** A header name (an HTTP token), which a cookie name is too. */
+export declare const HEADER_NAME: RegExp;
+/** A path such as `/entries/{slug}`: `{name}` only as a whole segment, no `:`, `*`, query or spaces. */
+export declare function isRoutePath(value: unknown, parameters?: boolean): value is string;
+/** The names of the `{name}` segments of `path`, in order. */
+export declare function parametersOfPath(path: string): string[];
+/** Whether a JSON Schema describes a value that is neither an object nor a list. */
+export declare function isScalarSchema(schema: OpenAPISchema): boolean;
+/** Whether `name` is a key of `blueprint` that is a scalar property (no object, no list). */
+export declare function isScalarKey(blueprint: AnyBlueprint, name: string): boolean;
+/**
+ * The frozen, normalized declaration of `route` for a use case whose input is
+ * `blueprint` (the method in lower case), or the reason it is not valid.
+ */
+export declare function routeDeclarationOf(route: unknown, blueprint: AnyBlueprint, response: AnyBlueprint): RouteDeclaration | string;

package/dist/core/use-case/steps/types/check.interface.d.ts

@@ -0,0 +1,214 @@
+/**
+ * The compile-time checking of `useCaseOf({ steps })`: the steps are inferred
+ * as a tuple and folded in order. Each step sees the values in scope (the
+ * input, the context, the environments and the names bound by the earlier
+ * steps with `as`); its references must name a path of one of them, and its
+ * `args`, `values`, `value` or `input` must fit what the called function,
+ * record, repository or use case takes. A reference that does not fit is
+ * replaced by the references that would, which is the error TypeScript shows
+ * and what the editor offers inside a `"$…"` string.
+ *
+ * The list of the paths of the scope is computed only for a reference that
+ * does not fit, so that right steps cost little to check. The conditionals on
+ * the steps are not distributive (`[Step] extends [...]`): TypeScript then
+ * never evaluates them with the constraint of the steps while it infers them.
+ */
+import type { BlueprintValue, IBlueprint, IBlueprintCollection } from "../../../blueprint/types/blueprint.interface.js";
+import type { AnyEnvironment, EnvironmentValue } from "../../../environment/environment.js";
+import type { Meta } from "../../../symbols/meta.js";
+import type { AnyUseCaseClass, UseCaseInput, UseCaseResponse } from "../../use-case.js";
+/** The values the first step can reference: the input, the context (if declared) and the environments. */
+export type StepsInitialScope<Input extends IBlueprintCollection, Context extends IBlueprintCollection | undefined, Dependencies> = {
+    readonly input: BlueprintValue<Input>;
+    readonly env: {
+        readonly [Key in keyof Dependencies as Dependencies[Key] extends AnyEnvironment ? Key : never]: Dependencies[Key] extends AnyEnvironment ? EnvironmentValue<Dependencies[Key]> : never;
+    };
+} & (Context extends IBlueprintCollection ? {
+    readonly context: BlueprintValue<Context>;
+} : unknown);
+type Split<Path extends string> = Path extends `${infer Head}.${infer Tail}` ? [Head, ...Split<Tail>] : [Path];
+/** `Value[Key]` for a value that is not `null` or `undefined`: by index (or `length`) in a list; `never` when absent. */
+type GetDefined<Value, Key extends string> = Value extends readonly unknown[] ? Key extends `${number}` ? Key extends keyof Value ? Value[Key] : Value[number] : Key extends "length" ? number : never : Key extends keyof Value ? Value[Key] : never;
+/**
+ * `Value[Key]` as `followPath` reads it: `undefined` through a value that
+ * may be `undefined` or `null`, and `never` when no value of the type has
+ * the key; `unknown` stays `unknown`.
+ */
+type Get<Value, Key extends string> = unknown extends Value ? unknown : [GetDefined<NonNullable<Value>, Key>] extends [infer Found] ? [Found] extends [never] ? never : Found | (Value extends null | undefined ? undefined : never) : never;
+type Walk<Value, Path extends readonly string[]> = Path extends readonly [
+    infer Key extends string,
+    ...infer Rest extends string[]
+] ? Walk<Get<Value, Key>, Rest> : Value;
+/** The type of the value the reference `$root.a.b` stands for in `Scope`; `never` when it names nothing. */
+export type StepReferenceType<Scope, Reference> = [Reference] extends [
+    `$${infer Path}`
+] ? Split<Path> extends [
+    infer Root extends string,
+    ...infer Rest extends string[]
+] ? Root extends "env" ? Rest extends [string, ...string[]] ? Walk<Get<Scope, Root>, Rest> : never : Walk<Get<Scope, Root>, Rest> : never : never;
+/** What a path walks into: the value of a record, not its methods. */
+type DataOf<Value> = Value extends {
+    readonly [Meta]: {
+        readonly blueprint: IBlueprint<infer Properties>;
+    };
+} ? BlueprintValue<Properties> : Value;
+type Leaf = string | number | boolean | bigint | symbol | null | undefined | Date | readonly unknown[] | ((...args: any[]) => unknown);
+type Below<Value, Prefix extends string, Expected, Depth extends unknown[]> = Depth["length"] extends 3 ? never : DataOf<NonNullable<Value>> extends infer Data ? Data extends Leaf ? never : {
+    [Key in keyof Data & string]-?: PathsFrom<Data[Key] | (Value extends null | undefined ? undefined : never), `${Prefix}.${Key}`, Expected, [
+        ...Depth,
+        0
+    ]>;
+}[keyof Data & string] : never;
+type PathsFrom<Value, Path extends string, Expected, Depth extends unknown[]> = Path extends unknown ? ([Value] extends [Expected] ? Path : never) | Below<Value, Path, Expected, Depth> : never;
+/** Every reference of `Scope` whose value fits `Expected` (three keys deep at most). */
+export type StepReferencesOf<Scope, Expected = unknown> = Scope extends unknown ? {
+    [Root in keyof Scope & string]-?: Root extends "env" ? Below<Scope[Root], `$${Root}`, Expected, [0]> : PathsFrom<Scope[Root], `$${Root}`, Expected, []>;
+}[keyof Scope & string] : never;
+/** `Reference` when it names a value of `Scope` that fits `Expected`; else the references that would. */
+type CheckReference<Reference, Expected, Scope> = [
+    StepReferenceType<Scope, Reference>
+] extends [infer Type] ? [Type] extends [never] ? StepReferencesOf<Scope, Expected> : [Type] extends [Expected] ? Reference : StepReferencesOf<Scope, Expected> : never;
+type Primitive = string | number | boolean | null;
+/** The type of the key `Key` in what `Expected` takes, over each object of it. */
+type ExpectedAt<Expected, Key> = Expected extends object ? Key extends keyof Expected ? Expected[Key] : never : never;
+/** The keys `Expected` takes in a mapping. */
+type KnownKeys<Expected> = Expected extends object ? keyof Expected : never;
+/** The keys the plain objects of `Expected` require (a record instance is not built from a mapping). */
+type RequiredKeys<Expected> = Expected extends {
+    readonly [Meta]: unknown;
+} ? never : Expected extends object ? {
+    [Key in keyof Expected]-?: undefined extends Expected[Key] ? never : Key;
+}[keyof Expected] : never;
+/** The keys of `Value` that `Expected` takes, each checked; the others are excess properties. */
+type CheckKeys<Value, Expected, Scope> = Value extends unknown ? {
+    readonly [Key in keyof Value as Key extends KnownKeys<Expected> ? Key : never]: StepValueCheck<Value[Key], ExpectedAt<Expected, Key>, Scope>;
+} : never;
+type CheckMapping<Value, Expected, Scope> = unknown extends Expected ? {
+    readonly [Key in keyof Value]: StepValueCheck<Value[Key], unknown, Scope>;
+} : [Exclude<RequiredKeys<Expected>, keyof Value>] extends [never] ? CheckKeys<Value, Expected, Scope> : CheckKeys<Value, Expected, Scope> & {
+    readonly [Key in Exclude<RequiredKeys<Expected>, keyof Value>]: ExpectedAt<Expected, Key>;
+};
+type ElementAt<Expected, Index> = unknown extends Expected ? unknown : Expected extends readonly unknown[] ? Index extends keyof Expected ? Expected[Index] : Expected[number] : never;
+/**
+ * What the step value `Value` must be where `Expected` is taken: itself when
+ * it fits; else, for a reference, the references that would fit, and for a
+ * literal, `Expected`. A mapping is checked key by key, a list item by item.
+ */
+export type StepValueCheck<Value, Expected, Scope> = [Value] extends [
+    `$${string}`
+] ? CheckReference<Value, Expected, Scope> : [Value] extends [Primitive] ? [Value] extends [Expected] ? Value : Expected : [Value] extends [{
+    readonly literal: unknown;
+}] ? Value : [Value] extends [readonly unknown[]] ? {
+    readonly [Index in keyof Value]: StepValueCheck<Value[Index], ElementAt<Expected, Index>, Scope>;
+} : [Value] extends [object] ? CheckMapping<Value, Expected, Scope> : Value;
+/** The parameter `Index` of a function whose parameters are `Parameters`. */
+type ParameterAt<Parameters extends readonly unknown[], Index> = Index extends keyof Parameters ? Parameters[Index] : number extends Parameters["length"] ? Parameters[number] : undefined;
+/** What the `args` of a call must be: each against its parameter, or one reference to a list. */
+type CheckArgs<Args, Parameters extends readonly unknown[], Scope> = [
+    Args
+] extends [`$${string}`] ? CheckReference<Args, readonly unknown[], Scope> : {
+    readonly [Index in keyof Args]: StepValueCheck<Args[Index], ParameterAt<Parameters, Index>, Scope>;
+};
+type Fn = (...args: any[]) => unknown;
+type ParametersOf<Value> = [Value] extends [Fn] ? Parameters<Value> : unknown[];
+type FirstParameter<Value> = [Value] extends [never] ? unknown : [Value] extends [Fn] ? Parameters<Value>[0] : unknown;
+type ResultOf<Value> = [Value] extends [Fn] ? Awaited<ReturnType<Value>> : unknown;
+/** `Dependencies[Key][Member]`, or `unknown`. */
+type MemberOf<Dependencies, Key, Member> = Key extends keyof Dependencies ? Member extends keyof Dependencies[Key] ? Dependencies[Key][Member] : unknown : unknown;
+/** The method `"users.findByEmail"` names among `Dependencies`. */
+type FindMethod<Dependencies, Target> = Target extends `${infer Repository}.${infer Action}` ? MemberOf<Dependencies, Repository, Action> : unknown;
+/** The members of a record no `invoke` may call. */
+type ForbiddenMethod = "set" | "emit" | "constructor" | "toLocaleString" | "valueOf" | "hasOwnProperty" | "isPrototypeOf" | "propertyIsEnumerable";
+/** The public methods of the record `Record`: what `invoke.method` names. */
+type StepInvokeMethod<Record> = Record extends unknown ? {
+    [Key in keyof Record & string]-?: Record[Key] extends Fn ? Key : never;
+}[Exclude<keyof Record & string, ForbiddenMethod>] : never;
+type ChangeOf<Record> = Record extends {
+    readonly change: infer Change;
+} ? Change : never;
+type UseCaseOf<Dependencies, Key> = Key extends keyof Dependencies ? Dependencies[Key] extends AnyUseCaseClass ? Dependencies[Key] : never : never;
+/** A step that calls `Method` with its `args`: `[checked step, result]`. */
+type CallStep<Step, Method, Scope> = [
+    {
+        readonly [Key in keyof Step]: Key extends "args" ? CheckArgs<Step[Key], ParametersOf<Method>, Scope> : Step[Key];
+    },
+    ResultOf<Method>
+];
+/** A step whose `Field` is checked against `Expected`: `[checked step, result]`. */
+type ValueStep<Step, Field, Expected, Result, Scope> = [
+    {
+        readonly [Key in keyof Step]: Key extends Field ? StepValueCheck<Step[Key], Expected, Scope> : Step[Key];
+    },
+    Result
+];
+type InvokeStep<Step, Record, Scope> = [Record] extends [never] ? ValueStep<Step, "invoke", object, unknown, Scope> : [Step] extends [{
+    readonly method: infer Method;
+}] ? Method extends keyof Record ? CallStep<Step, Record[Method], Scope> : [
+    {
+        readonly [Key in keyof Step]: Key extends "method" ? StepInvokeMethod<Record> : Step[Key];
+    },
+    unknown
+] : [Step, unknown];
+type ChangeStep<Step, Record, Scope> = [Record] extends [never] ? ValueStep<Step, "change", object, unknown, Scope> : [Step] extends [{
+    readonly key: infer Name;
+}] ? Name extends keyof ChangeOf<Record> ? ValueStep<Step, "value", FirstParameter<ChangeOf<Record>[Name]>, Record, Scope> : [
+    {
+        readonly [Key in keyof Step]: Key extends "key" ? keyof ChangeOf<Record> & string : Step[Key];
+    },
+    Record
+] : [Step, Record];
+/** `[what Step must be, what it gives to its as]`, read against `Scope`. */
+type CheckStep<Step, Dependencies, Scope> = [Step] extends [
+    {
+        readonly find: infer Target;
+    }
+] ? CallStep<Step, FindMethod<Dependencies, Target>, Scope> : [Step] extends [{
+    readonly run: unknown;
+    readonly fn: infer Run;
+}] ? CallStep<Step, Run, Scope> : [Step] extends [{
+    readonly invoke: infer Reference;
+}] ? InvokeStep<Step, NonNullable<StepReferenceType<Scope, Reference>>, Scope> : [Step] extends [{
+    readonly change: infer Reference;
+}] ? ChangeStep<Step, NonNullable<StepReferenceType<Scope, Reference>>, Scope> : [Step] extends [
+    {
+        readonly build: abstract new (value: infer Input) => infer Built;
+    }
+] ? ValueStep<Step, "values", Input, Built, Scope> : [Step] extends [{
+    readonly call: infer Name;
+}] ? ValueStep<Step, "input", UseCaseInput<UseCaseOf<Dependencies, Name>>, UseCaseResponse<UseCaseOf<Dependencies, Name>>, Scope> : [Step] extends [{
+    readonly create: infer Repository;
+}] ? WriteStep<Step, MemberOf<Dependencies, Repository, "create">, Scope> : [Step] extends [{
+    readonly update: infer Repository;
+}] ? WriteStep<Step, MemberOf<Dependencies, Repository, "update">, Scope> : [Step] extends [{
+    readonly delete: infer Repository;
+}] ? WriteStep<Step, MemberOf<Dependencies, Repository, "delete">, Scope> : [Step] extends [{
+    readonly restore: infer Repository;
+}] ? WriteStep<Step, MemberOf<Dependencies, Repository, "restore">, Scope> : ValueStep<Step, "value" | "other" | "details" | "return", unknown, unknown, Scope>;
+type WriteStep<Step, Method, Scope> = ValueStep<Step, "value", FirstParameter<Method>, ResultOf<Method>, Scope>;
+/** The scope after `Step`: its result bound to its `as`, or a value it ensures exists. */
+type ScopeAfter<Step, Result, Scope> = [Step] extends [
+    {
+        readonly as: infer Name extends string;
+    }
+] ? Scope & {
+    readonly [Key in Name]: Result;
+} : [Step] extends [
+    {
+        readonly ensure: "exists";
+        readonly value: `$${infer Name}`;
+    }
+] ? Name extends keyof Scope ? Scope & {
+    readonly [Key in Name]: NonNullable<Scope[Name]>;
+} : Scope : Scope;
+/** The steps folded in order, each checked against the scope the earlier ones built. */
+type CheckSteps<Steps extends readonly unknown[], Dependencies, Scope, Checked extends readonly unknown[] = []> = [Steps] extends [readonly [infer Step, ...infer Rest]] ? CheckStep<Step, Dependencies, Scope> extends [infer Current, infer Result] ? CheckSteps<Rest, Dependencies, ScopeAfter<Step, Result, Scope>, [
+    ...Checked,
+    Current
+]> : never : readonly [...Checked];
+/**
+ * What `useCaseOf` takes as `steps`: the steps, inferred as a tuple, each
+ * checked against the values in scope. Steps that are not a tuple (built at
+ * run time) are checked only when the use case is declared.
+ */
+export type CheckedSteps<Steps, Input extends IBlueprintCollection, Context extends IBlueprintCollection | undefined, Dependencies> = [Steps] extends [readonly [unknown, ...unknown[]]] ? CheckSteps<Steps, Dependencies, StepsInitialScope<Input, Context, Dependencies>> : Steps;
+export {};

package/dist/core/use-case/types/access.interface.d.ts

@@ -0,0 +1,39 @@
+import type { JsonValue } from "../../json.js";
+/**
+ * Who is calling: what an authenticator made of the credentials of a request.
+ * `subject` identifies the caller (a user id), `scopes` is what it may do.
+ */
+export interface Principal {
+    readonly subject: string;
+    readonly scopes: readonly string[];
+    /** Anything else the credentials say (a tenant, a role). */
+    readonly claims?: Readonly<Record<string, JsonValue>>;
+}
+/** A value of the principal: its subject, its scopes or one of its claims. */
+type PrincipalValue = "subject" | "scopes" | `claims.${string}`;
+/**
+ * Who may call a use case, as data: declared with the `access` setting of
+ * `useCaseOf` or with `@Access`, and enforced by every output before the use
+ * case runs. `{ public: true }` lets anyone in. Any other declaration needs
+ * an authenticated caller (`{}` asks for nothing more), and may add:
+ *
+ * - `scopes`: the caller has all of them;
+ * - `owner`: the input key `input` equals the subject of the caller, or its
+ *   claim `claim`;
+ * - `context`: keys of the context of the call filled from the caller, over
+ *   whatever the request sent.
+ */
+export type AccessDeclaration = {
+    readonly public: true;
+} | {
+    readonly public?: false;
+    readonly scopes?: readonly string[];
+    readonly owner?: {
+        readonly input: string;
+        readonly claim?: string;
+    };
+    readonly context?: {
+        readonly [contextKey: string]: PrincipalValue;
+    };
+};
+export {};

package/dist/core/use-case/types/route.interface.d.ts

@@ -0,0 +1,66 @@
+/** An HTTP method an operation can be routed to. */
+export type RouteMethod = "get" | "post" | "put" | "patch" | "delete";
+/** The status of a successful call of a route; `204` has no body. */
+export type RouteSuccessStatus = 200 | 201 | 202 | 204;
+/** How a cookie a route sets is sent. The defaults are the safe ones for a session. */
+export interface RouteCookie {
+    /** The name of the cookie. */
+    readonly name: string;
+    /** Not readable by scripts of the page. `true` by default. */
+    readonly httpOnly?: boolean;
+    /** Sent over HTTPS only. `true` by default. */
+    readonly secure?: boolean;
+    /** `"lax"` by default. */
+    readonly sameSite?: "strict" | "lax" | "none";
+    /** `"/"` by default. */
+    readonly path?: string;
+    readonly domain?: string;
+    /** The seconds the cookie lives; without it, until the browser closes. */
+    readonly maxAge?: number;
+}
+/**
+ * Where a use case is served over HTTP, as data: declared with the `route`
+ * setting of `useCaseOf` or with `@Route`, and read by the sinks that serve
+ * or document HTTP. The blueprint of the use case stays the only description
+ * of its input: a route only says where each key comes from.
+ */
+export interface RouteDeclaration {
+    readonly method: RouteMethod;
+    /**
+     * The path, after the `basePath` of the sink, e.g. `"/posts/{slug}"`. A
+     * `{name}` segment fills the scalar input key `name`. Without it, the path
+     * is the default of the sink: `/{kebab(command)}/{kebab(operation)}`.
+     */
+    readonly path?: string;
+    /** `200` by default. */
+    readonly status?: RouteSuccessStatus;
+    /**
+     * Scalar input keys read from the query string. A `get` or `delete` route
+     * reads from the query every key that has no other place, so this is for
+     * the routes with a body.
+     */
+    readonly query?: readonly string[];
+    /** Scalar input keys read from request headers: `{ locale: "accept-language" }`. */
+    readonly headers?: {
+        readonly [inputKey: string]: string;
+    };
+    /** Scalar input keys read from cookies: `{ session: "sid" }`. */
+    readonly cookie?: {
+        readonly [inputKey: string]: string;
+    };
+    /**
+     * Scalar keys of the response sent as cookies instead of in the body:
+     * `{ token: { name: "sid" } }`. An empty text removes the cookie, and an
+     * absent value sets none.
+     */
+    readonly setCookie?: {
+        readonly [responseKey: string]: RouteCookie;
+    };
+}
+/**
+ * What the `route` setting and `@Route` take: a {@link RouteDeclaration}
+ * whose method may be written in upper case.
+ */
+export interface RouteSettings extends Omit<RouteDeclaration, "method"> {
+    readonly method: RouteMethod | Uppercase<RouteMethod>;
+}

package/dist/core/use-case/use-case.d.ts

@@ -5,7 +5,10 @@ import { type DeclaredExceptionClass } from "../exception/exception.js";
 import { type ILogger, type LoggerDeclaration } from "../logger/logger.js";
 import type { AnyRepository } from "../repository/types/repository.interface.js";
 import { Kind } from "../symbols/kind.js";
+import type { CheckedSteps } from "./steps/types/check.interface.js";
 import type { UseCaseStep } from "./steps/types/steps.interface.js";
+import type { AccessDeclaration } from "./types/access.interface.js";
+import type { RouteDeclaration, RouteSettings } from "./types/route.interface.js";
 /** A concrete UseCase declaration, usable as a dependency. */
 export interface AnyUseCaseClass {
     readonly [Kind]: "use-case";
@@ -18,6 +21,10 @@ export interface AnyUseCaseClass {
     readonly tags: readonly string[];
     readonly deprecated: boolean;
     readonly errors: readonly AnyExceptionClass[];
+    /** Where it is served over HTTP, if it says so (see `RouteDeclaration`). */
+    readonly route: RouteDeclaration | undefined;
+    /** Who may call it, if it says so (see `AccessDeclaration`). */
+    readonly access: AccessDeclaration | undefined;
     new (input: any, ...options: any[]): {
         execute(): Promise<unknown>;
         pullEvents(): EntityEvent[];
@@ -81,6 +88,22 @@ export interface UseCaseSettings<Input extends IBlueprintCollection, Output exte
     readonly deprecated?: boolean;
     /** The exceptions (made by `exceptionOf`) a caller should expect; documentation only. */
     readonly errors?: readonly AnyExceptionClass[];
+    /**
+     * Where the use case is served over HTTP: method, path and where each
+     * input key is read from (see `RouteDeclaration`). A decorated class says
+     * the same with `@Route`. Read by the sinks that serve or document HTTP;
+     * the `route` option of a sink overrides the method, path and status.
+     */
+    readonly route?: RouteSettings;
+    /**
+     * Who may call the use case through an output: anyone (`{ public: true }`),
+     * or an authenticated caller with these `scopes`, that is the `owner`
+     * named by an input key, and whose values fill the `context` (see
+     * `AccessDeclaration`). A decorated class says the same with `@Access`.
+     * Enforced before the use case runs; a call made in process, with
+     * `execute` or `command.run`, is trusted and not checked.
+     */
+    readonly access?: AccessDeclaration;
 }
 /** `UseCaseSettings` with the `steps` that are its `execute`. */
 export interface UseCaseStepsSettings<Input extends IBlueprintCollection, Output extends IBlueprintCollection, Dependencies extends UseCaseCollection, Context extends IBlueprintCollection | undefined = undefined> extends UseCaseSettings<Input, Output, Dependencies, Context> {
@@ -89,6 +112,30 @@ export interface UseCaseStepsSettings<Input extends IBlueprintCollection, Output
      * interpreted by its `execute`, and described by `describe()`.
      */
     readonly steps: readonly UseCaseStep<NoInfer<Dependencies>>[];
+    /** Checks the references and values of the steps at compile time (see `CheckedSteps`). */
+    readonly strictSteps?: boolean;
+}
+/**
+ * What `useCaseOf` takes: `UseCaseSettings`, and the `steps` that make the
+ * class concrete, if any.
+ */
+export interface UseCaseDeclaration<Input extends IBlueprintCollection, Output extends IBlueprintCollection, Dependencies extends UseCaseCollection, Context extends IBlueprintCollection | undefined = undefined, Steps extends readonly UseCaseStep<Dependencies>[] | undefined = undefined, Strict extends boolean = false> extends UseCaseSettings<Input, Output, Dependencies, Context> {
+    /**
+     * What the use case does, as data (see `UseCaseStep`), which makes the
+     * class concrete: validated here, interpreted by its `execute`, and
+     * described by `describe()`. TypeScript checks the kinds of the steps and
+     * the names of dependencies and actions; with `strictSteps`, also their
+     * references and values (see `CheckedSteps`).
+     */
+    readonly steps?: [Strict] extends [true] ? CheckedSteps<Steps, NoInfer<Input>, NoInfer<Context>, NoInfer<Dependencies>> : Steps;
+    /**
+     * `true` checks the steps, written inline, at compile time: each reference
+     * must name a value in scope (the input, the context, an environment or the
+     * result of an earlier step, at any depth), and the `args`, `values`,
+     * `value` and `input` of a step must fit what it calls or builds. It costs
+     * the editor more than the default checks. Without effect at run time.
+     */
+    readonly strictSteps?: Strict;
 }
 export declare const InvalidUseCaseDeclaration: DeclaredExceptionClass<{
     reason: string;
@@ -119,6 +166,10 @@ type UseCaseStatics<Input extends IBlueprintCollection, Output extends IBlueprin
     readonly deprecated: boolean;
     /** The exceptions a caller should expect. */
     readonly errors: readonly AnyExceptionClass[];
+    /** Where it is served over HTTP, from the `route` setting or `@Route`. */
+    readonly route: RouteDeclaration | undefined;
+    /** Who may call it, from the `access` setting or `@Access`. */
+    readonly access: AccessDeclaration | undefined;
 };
 /** What a use case instance carries beyond `AbstractUseCase`. */
 type UseCaseInstanceContext<Context extends IBlueprintCollection | undefined> = {
@@ -138,8 +189,7 @@ export type StepsUseCaseConstructor<Input extends IBlueprintCollection, Output e
  * interprets them. Without, it is abstract: extend it and implement an async
  * execute method.
  */
-export declare function useCaseOf<Input extends IBlueprintCollection, Output extends IBlueprintCollection, const Dependencies extends UseCaseCollection = Record<never, never>, Context extends IBlueprintCollection | undefined = undefined>(settings: UseCaseStepsSettings<Input, Output, Dependencies, Context>): StepsUseCaseConstructor<Input, Output, Dependencies, Context>;
-export declare function useCaseOf<Input extends IBlueprintCollection, Output extends IBlueprintCollection, const Dependencies extends UseCaseCollection = Record<never, never>, Context extends IBlueprintCollection | undefined = undefined>(settings: UseCaseSettings<Input, Output, Dependencies, Context>): UseCaseConstructor<Input, Output, Dependencies, Context>;
+export declare function useCaseOf<Input extends IBlueprintCollection, Output extends IBlueprintCollection, const Dependencies extends UseCaseCollection = Record<never, never>, Context extends IBlueprintCollection | undefined = undefined, const Steps extends readonly UseCaseStep<NoInfer<Dependencies>>[] | undefined = undefined, Strict extends boolean = false>(settings: UseCaseDeclaration<Input, Output, Dependencies, Context, Steps, Strict>): [Steps] extends [undefined] ? UseCaseConstructor<Input, Output, Dependencies, Context> : StepsUseCaseConstructor<Input, Output, Dependencies, Context>;
 export declare function isUseCaseClass(value: unknown): value is AnyUseCaseClass;
 export declare function isUseCase(value: unknown): value is AbstractUseCase<IBlueprintCollection, IBlueprintCollection, UseCaseCollection>;
 export {};

package/dist/experimental.d.ts

@@ -1,6 +1,18 @@
 /**
  * `@afora/core/experimental`: features that may change in any release. Not
- * covered by the compatibility policy in `VERSIONING.md`.
+ * covered by the compatibility policy in `VERSIONING.md`. See
+ * `docs/api-tiers.md`.
  */
+export { InvalidJwtOptions, jwtOf } from "./core/auth/jwt.js";
+export type { DescribedJwtOptions, Jwt, JwtAlgorithm, JwtOptions, JwtSubject, JwtTokenOptions, } from "./core/auth/types/jwt.interface.js";
 export { sliceOf, sliceValue } from "./core/blueprint/slice.js";
 export type { SlicedBlueprint, SlicedValue, SliceMask, ValueMask, } from "./core/blueprint/types/slice.interface.js";
+export { eventPolicyCatalogOf, eventPolicyDescriptionOf, } from "./core/event-policy/event-policy.js";
+export { stageDescriptionOf } from "./core/output/stage.js";
+export { type PropertyLineage, propertyLineageOf, } from "./core/property/lineage.js";
+export { providerDescriptionOf } from "./core/repository/provider.js";
+export { matchesQuery, prepareQuery, sameValue, selectRows, } from "./core/repository/query.js";
+export { useCaseOriginOf } from "./core/use-case/plugin.js";
+export { useCaseTargetOf } from "./core/use-case/target.js";
+export type { UseCaseOriginInfo } from "./core/use-case/types/plugin.interface.js";
+export type { StdTokenOptions } from "./std/use-cases/types.js";