@afora/core 0.0.8 → 0.0.9

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";

package/dist/experimental.js

@@ -1,47 +1,63 @@
 import {
-  isBlueprint2,
-  isRecordClass2,
-  recordFieldOf2,
+  propertyLineageOf2,
+  isBlueprint,
+  isRecordClass,
+  recordFieldOf,
+  InvalidBlueprintVariant2,
+  UndeclaredBlueprintProperty2,
+  isBlueprintVariant,
   recordNameOf2,
   listOf2,
-  isBlueprintList2,
-  AbstractRecord2,
-  UndeclaredBlueprintProperty2,
+  isBlueprintList,
+  AbstractRecord,
   optionalOf2,
   blueprintFromProperties,
-  declareRecord
-} from "./index-qxfkyd6k.js";
-
+  declareRecord,
+  stageDescriptionOf2,
+  InvalidJwtOptions2,
+  jwtOf2
+} from "./index-xegv6a1p.js";
+import {
+  providerDescriptionOf2,
+  prepareQuery2,
+  sameValue2,
+  matchesQuery2,
+  selectRows2,
+  useCaseTargetOf2,
+  useCaseOriginOf2,
+  eventPolicyDescriptionOf2,
+  eventPolicyCatalogOf2
+} from "./index-3aae5jfq.js";
 // src/core/blueprint/slice.ts
 function propertiesOfField(field) {
   if (field === undefined)
     return;
-  if (isBlueprintList2(field))
+  if (isBlueprintList(field))
     return propertiesOfField(field.item);
-  const record = recordFieldOf2(field);
+  const record = recordFieldOf(field);
   if (record)
     return record.record.blueprint.properties;
-  return isBlueprint2(field) ? field.properties : undefined;
+  return isBlueprint(field) ? field.properties : undefined;
 }
 function maskOf(selector, against) {
-  if (isRecordClass2(selector))
+  if (isRecordClass(selector))
     return maskOf(selector.blueprint, against);
-  if (isBlueprint2(selector)) {
+  if (isBlueprint(selector)) {
     return Object.fromEntries(Object.entries(selector.properties).map(([key, field]) => [key, fieldMaskOf(field, against?.[key])]));
   }
   return selector;
 }
 function fieldMaskOf(field, other) {
-  if (isBlueprintList2(field)) {
-    return fieldMaskOf(field.item, isBlueprintList2(other) ? other.item : other);
+  if (isBlueprintList(field)) {
+    return fieldMaskOf(field.item, isBlueprintList(other) ? other.item : other);
   }
-  const record = recordFieldOf2(field);
+  const record = recordFieldOf(field);
   if (record) {
-    if (record.record === recordFieldOf2(other)?.record)
+    if (record.record === recordFieldOf(other)?.record)
       return true;
     return maskOf(record.record, propertiesOfField(other));
   }
-  if (isBlueprint2(field)) {
+  if (isBlueprint(field)) {
     return field === other ? true : maskOf(field, propertiesOfField(other));
   }
   return true;
@@ -66,7 +82,7 @@ function slicedRecordOf(Original, mask, path) {
   const blueprint = blueprintFromProperties(source.plugins, sliceCollection(source.properties, mask, `${path}.`));
   const kept = (keys) => keys.filter((key) => Object.hasOwn(blueprint.properties, key));
   const { sensitive, unique, change } = Original.options;
-  const Sliced = declareRecord(AbstractRecord2, blueprint, {
+  const Sliced = declareRecord(AbstractRecord, blueprint, {
     sensitive: kept(sensitive),
     unique: kept(unique),
     change: kept(change)
@@ -81,22 +97,31 @@ function slicedRecordOf(Original, mask, path) {
 function sliceField(field, selected, path) {
   if (selected === true)
     return field;
-  if (isBlueprintList2(field)) {
+  if (isBlueprintList(field)) {
     const list = listOf2(sliceField(field.item, selected, path), {
       minItems: field.minItems,
       maxItems: field.maxItems
     });
     return field.optional ? optionalOf2(list) : list;
   }
-  const record = recordFieldOf2(field);
+  const record = recordFieldOf(field);
   if (record) {
     const sliced = slicedRecordOf(record.record, selected, path);
     return record.optional ? optionalOf2(sliced) : sliced;
   }
-  if (isBlueprint2(field)) {
+  if (isBlueprint(field)) {
     const sliced = blueprintFromProperties(field.plugins, sliceCollection(field.properties, selected, `${path}.`));
     return field.optional ? optionalOf2(sliced) : sliced;
   }
+  if (isBlueprintVariant(field)) {
+    throw new InvalidBlueprintVariant2({
+      source: "blueprint",
+      details: {
+        key: field.key,
+        reason: `"${path}" cannot be sliced by its keys yet, only picked whole`
+      }
+    });
+  }
   throw new UndeclaredBlueprintProperty2({
     source: "blueprint",
     details: { key: `${path}.${Object.keys(selected)[0] ?? ""}` }
@@ -109,7 +134,7 @@ function pick(value, mask) {
     return value.map((item) => pick(item, mask));
   if (typeof value !== "object" || value === null)
     return value;
-  const source = isRecordClass2(value.constructor) ? value.toJSON() : value;
+  const source = isRecordClass(value.constructor) ? value.toJSON() : value;
   const picked = {};
   for (const [key, selected] of Object.entries(mask)) {
     if (!selected || !Object.hasOwn(source, key))
@@ -119,6 +144,19 @@ function pick(value, mask) {
   return picked;
 }
 export {
+  InvalidJwtOptions2 as InvalidJwtOptions,
+  eventPolicyCatalogOf2 as eventPolicyCatalogOf,
+  eventPolicyDescriptionOf2 as eventPolicyDescriptionOf,
+  jwtOf2 as jwtOf,
+  matchesQuery2 as matchesQuery,
+  prepareQuery2 as prepareQuery,
+  propertyLineageOf2 as propertyLineageOf,
+  providerDescriptionOf2 as providerDescriptionOf,
+  sameValue2 as sameValue,
+  selectRows2 as selectRows,
   sliceOf,
-  sliceValue
+  sliceValue,
+  stageDescriptionOf2 as stageDescriptionOf,
+  useCaseOriginOf2 as useCaseOriginOf,
+  useCaseTargetOf2 as useCaseTargetOf
 };