@afora/core 0.0.6 → 0.0.7

package/README.md

@@ -11,6 +11,7 @@ afora is not a general-purpose validator. It is for code that models a domain, a
 - **Exceptions that know their layer.** Each error carries a layer (`Property`, `Record`, `UseCase`, `Output`...) and a `trace` that grows as it goes up.
 - **Standard Schema V1 on every field.** Properties, blueprints, lists and record classes work as is in Hono, tRPC and TanStack Form, and `safeParse` never throws for an invalid value.
 - **Commands and outputs.** `commandOf` groups use cases behind one execution boundary (context, transactions, event policies); `outputOf` turns commands into operations and pipes them to a sink: an HTTP API with `@afora/hono`, an OpenAPI 3.1 document, or MCP tools, with problem+json errors and masked responses.
+- **Standard use cases.** `commandOf({ useCases: (ctx) => ({ create: ctx.create(Posts), publish: ctx.publish(Posts) }) })` picks ready-made use cases that follow the repository and its entity: the actions it declares, its record plugins and the properties of its keys ([docs](docs/std-use-cases.md)).
 - **The whole application in JSON.** An `afora.json` generates the code (`@afora/codegen`), use cases included, as data (steps), and `extractSpec(app)` gives back the `afora.json` of an application written by hand.
 - **Repositories on any store.** A provider contract with typed queries, soft deletion and transactions, a runner-agnostic kit to test one (`@afora/core/testing`), in memory by default and on Drizzle ORM with `@afora/drizzle`.
 
@@ -304,7 +305,7 @@ Every field (a property, blueprint, list or record class) implements Standard Sc
 
 ## Example
 
-`examples/blog` is a blog (users with the `authenticatable` plugin, posts with soft deletion, use cases written as steps, a Hono API on Drizzle and SQLite) whose whole `src/domain` is generated from one `afora.json` by `@afora/codegen`. Only the database, the schema, the provider (made from a `Database` environment with `providerFrom` when the server calls `App.start()`), a password hashing function and the server are hand-written. Its tests check that the committed code is what the spec generates, drive the API end to end and extract the spec back from the application: `bun run test:blog`.
+`examples/blog` is a blog (users with the `authenticatable` plugin, posts with soft deletion, every use case a [standard one](docs/std-use-cases.md), a Hono API on Drizzle and SQLite) whose whole `src/domain` is generated from one `afora.json` by `@afora/codegen`. Only the database, the schema, the provider (made from a `Database` environment with `providerFrom` when the server calls `App.start()`, and named `database` in the `providers` of the spec) and the server are hand-written. Its tests check that the committed code is what the spec generates, drive the API end to end and extract the spec back from the application: `bun run test:blog`.
 
 ## Performance
 

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

@@ -340,6 +340,17 @@ export interface UseCaseDescription {
     } | {
         readonly kind: "opaque";
     };
+    /**
+     * The use case plugin that made it, the registered repository it was made
+     * for and the options given, with classes by name as in the steps; absent
+     * for a use case declared by hand.
+     */
+    readonly generic?: {
+        readonly name: string;
+        readonly version: string;
+        readonly repository: string;
+        readonly options: Readonly<Record<string, unknown>>;
+    };
 }
 /** A command: its metadata, context, operations and policies. */
 export interface CommandDescription {

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

@@ -1,7 +1,6 @@
-import type { IBlueprintCollection } from "../blueprint/types/blueprint.interface.js";
-import { type EnvironmentDependencies } from "../environment/environment.js";
 import type { IRepositoryProvider } from "../repository/types/repository.interface.js";
-import type { AnyCommand, CommandOf, CommandSettings, CommandUseCases } from "./types/command.interface.js";
+import type { IUseCaseCatalog, UseCasePluginContext } from "../use-case/types/plugin.interface.js";
+import type { AnyCommand, CommandBuilder } from "./types/command.interface.js";
 /**
  * Checks now that the repositories of `command` share a provider that has
  * `transaction`, as its first call would; an application calls it when it
@@ -15,11 +14,19 @@ export declare function verifyCommand(command: object): void;
  * @internal
  */
 export declare function commandTransactionProvider(command: object): IRepositoryProvider | undefined;
+/**
+ * A `commandOf` whose `useCases` may be a function of the use case plugins
+ * of `catalogs`, by name, a later catalog winning a name:
+ * `useCases: (ctx) => ({ create: ctx.create(Posts), custom: MyUseCase })`.
+ * Throws `InvalidCommandDeclaration` for what is not a catalog made by
+ * `useCaseCatalogOf`.
+ */
+export declare function commandBuilderOf<const Catalogs extends readonly IUseCaseCatalog[] = []>(...catalogs: Catalogs): CommandBuilder<UseCasePluginContext<Catalogs>>;
 /**
  * Groups use cases under operation names and is the boundary of a call: the
  * context is validated once, a transaction can wrap the use case, and the
  * events it raised are handled by a policy once it succeeded.
  */
-export declare function commandOf<const UseCases extends CommandUseCases, Context extends IBlueprintCollection | undefined = undefined, Environment extends EnvironmentDependencies | undefined = undefined>(settings: CommandSettings<UseCases, Context, Environment>): CommandOf<UseCases, Context, Environment>;
+export declare const commandOf: CommandBuilder<Record<never, never>>;
 /** Whether `value` is a command made by `commandOf`. */
 export declare function isCommand(value: unknown): value is AnyCommand;

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

@@ -48,6 +48,25 @@ export interface CommandSettings<UseCases extends CommandUseCases, Context exten
     readonly events?: CommandEvents;
     readonly onEventError?: CommandEventErrorHandler;
 }
+/**
+ * The `useCases` of a command made by a builder: the object, or a function
+ * of the use case plugins of its catalogs that gives it.
+ */
+export type CommandUseCasesOption<UseCases extends CommandUseCases, Generics> = UseCases | ((ctx: Generics) => UseCases);
+/** `CommandSettings` with `useCases` as a builder takes it. */
+export interface CommandBuilderSettings<UseCases extends CommandUseCases, Context extends IBlueprintCollection | undefined, Environment extends EnvironmentDependencies | undefined, Generics> extends Omit<CommandSettings<UseCases, Context, Environment>, "useCases"> {
+    /**
+     * The use cases, by operation name; or a function that gets the use
+     * case plugins of the builder's catalogs, each called with a repository,
+     * and gives them: `(ctx) => ({ create: ctx.create(Posts) })`.
+     */
+    readonly useCases: CommandUseCasesOption<UseCases, Generics>;
+}
+/**
+ * What `commandBuilderOf` gives: `commandOf`, with the use case plugins
+ * `Generics` to pick from.
+ */
+export type CommandBuilder<Generics> = <const UseCases extends CommandUseCases, Context extends IBlueprintCollection | undefined = undefined, Environment extends EnvironmentDependencies | undefined = undefined>(settings: CommandBuilderSettings<UseCases, Context, Environment, Generics>) => CommandOf<UseCases, Context, Environment>;
 /** The names of the operations of a command. */
 export type CommandOperation<Command extends {
     readonly useCases: object;

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

@@ -10,7 +10,8 @@ export declare function raisedOf(error: Exception): Exception;
  * The HTTP-style status of an error, in this order: `statuses` by exception
  * name; 400 for invalid input or context (and any exception whose
  * `details.issues` is a list, except `InvalidCommandEnvironment`, a 500); 404 for a missing entity or operation; 409 for
- * a unique violation; 422 for a class in `operation.errors`; 500 for the
+ * a unique violation or an entity that already exists; 401 for
+ * `UseCaseInvalidCredentials`; 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/property/input.d.ts

@@ -0,0 +1,20 @@
+import type { AnyPropertyConstructor } from "./types/property-collection.type.js";
+/**
+ * The static of a property class whose callers give another form of its
+ * value than the one it stores: a password is given plain and stored as a
+ * hash. Classes extending or refining the property keep it.
+ */
+export declare const PropertyInput: unique symbol;
+/** What a property class holds under `PropertyInput`. */
+export interface IPropertyInput<Value = unknown> {
+    /** The property that validates what a caller gives, of the same value type. */
+    readonly accepts: AnyPropertyConstructor;
+    /** Turns what a caller gave into the value the property stores. */
+    convert(value: Value): Value | Promise<Value>;
+}
+/**
+ * What `field` declares under `PropertyInput`; `undefined` for a property
+ * that takes its value as it stores it, and for a field that is not a
+ * property.
+ */
+export declare function propertyInputOf(field: unknown): IPropertyInput | undefined;

package/dist/core/record/plugin.d.ts

@@ -9,8 +9,12 @@ export declare const RecordPlugins: unique symbol;
 export declare const IdentifiedRecord: unique symbol;
 /** Whether `version` is a semantic version. */
 export declare function isVersion(version: unknown): version is string;
-/** The major, minor and patch of a semantic version. */
-export declare function versionParts(version: string): readonly [number, number, number];
+/**
+ * Whether a plugin of version `available` satisfies a reference to
+ * `requested`: the same major version (the same minor below `1.0.0`), and
+ * not older.
+ */
+export declare function satisfies(available: string, requested: string): boolean;
 /** The `onSet` and `onSetAll` a plugin runs, for changes to its `keys`. */
 interface RecordPluginHook {
     readonly plugin: AnyRecordPlugin;

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

@@ -51,7 +51,7 @@ export declare abstract class AbstractRepository<Entity extends AnyRepositoryEnt
  * A repository of `entity` with the methods of `actions`: `findBy<Key>` for a
  * unique key (`id`, `options.unique`, a `unique` property), giving the entity
  * or `undefined`; `findManyBy<Key>` for any other key, giving a list;
- * `create`, `update`, `delete`, `count`, and the queries `findMany`,
+ * `create`, `update`, `delete`, `restore` (soft deletion only), `count`, and the queries `findMany`,
  * `exists`, `findPage` and `findCursor`. Every method is async and reads and writes through `provider`
  * (a new `inMemoryProvider()` by default), which gets the variables of
  * `environmentDependencies` as `context.env`. The repository can be a

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

@@ -37,6 +37,15 @@ export interface RepositoryInspection {
 }
 /** The declaration of `repository`; `undefined` when it is not one. */
 export declare function inspectRepository(repository: unknown): RepositoryInspection | undefined;
+/** Keeps `repository` as the one `repositoryOf` made for `state`. */
+export declare function declareRepository(state: RepositoryState, repository: object): void;
+/**
+ * The repository `repositoryOf` made for the entity class `Entity` that the
+ * entities of `repository` hold; `undefined` when it has no such relation.
+ *
+ * @internal
+ */
+export declare function relatedRepositoryOf(repository: object, Entity: object): object | undefined;
 /**
  * A repository sharing the declaration of `repository` that reads and writes
  * through `provider`, unless it declared a provider of its own; a declared

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

@@ -42,6 +42,13 @@ export interface RepositoryUpdate<Entity> {
 export interface RepositoryDelete<Entity> {
     delete(entity: EntityInstanceOf<Entity> | string): Promise<EntityInstanceOf<Entity>>;
 }
+/**
+ * `restore`: brings back a soft-deleted entity (or the one of the id) and
+ * gives it, alive; only for a repository with `deletion: "soft"`.
+ */
+export interface RepositoryRestore<Entity> {
+    restore(entity: EntityInstanceOf<Entity> | string): Promise<EntityInstanceOf<Entity>>;
+}
 /** `count`: how many entities it holds. */
 export interface RepositoryCount<Entity = unknown> {
     count(query?: RepositoryQuery<Entity>): Promise<number>;
@@ -67,9 +74,9 @@ export type RepositoryFindManyBy<Entity, Actions extends string = string> = {
  * so that a class extending a repository can override them.
  * @internal
  */
-export type RepositoryMethods<Entity, Actions extends string = string> = RepositoryFindBy<Entity, Actions> & RepositoryFindManyBy<Entity, Actions> & ("create" extends Actions ? RepositoryCreate<Entity> : unknown) & ("update" extends Actions ? RepositoryUpdate<Entity> : unknown) & ("delete" extends Actions ? RepositoryDelete<Entity> : unknown) & ("count" extends Actions ? RepositoryCount<Entity> : unknown) & ("findMany" extends Actions ? RepositoryFindMany<Entity> : unknown) & ("exists" extends Actions ? RepositoryExists<Entity> : unknown) & ("findPage" extends Actions ? RepositoryFindPage<Entity> : unknown) & ("findCursor" extends Actions ? RepositoryFindCursor<Entity> : unknown);
+export type RepositoryMethods<Entity, Actions extends string = string> = RepositoryFindBy<Entity, Actions> & RepositoryFindManyBy<Entity, Actions> & ("create" extends Actions ? RepositoryCreate<Entity> : unknown) & ("update" extends Actions ? RepositoryUpdate<Entity> : unknown) & ("delete" extends Actions ? RepositoryDelete<Entity> : unknown) & ("restore" extends Actions ? RepositoryRestore<Entity> : unknown) & ("count" extends Actions ? RepositoryCount<Entity> : unknown) & ("findMany" extends Actions ? RepositoryFindMany<Entity> : unknown) & ("exists" extends Actions ? RepositoryExists<Entity> : unknown) & ("findPage" extends Actions ? RepositoryFindPage<Entity> : unknown) & ("findCursor" extends Actions ? RepositoryFindCursor<Entity> : unknown);
 /** A method a repository of `Entity` can have, e.g. `"findByEmail"`. */
-export type RepositoryAction<Entity> = keyof RepositoryFindBy<Entity> | keyof RepositoryFindManyBy<Entity> | "create" | "update" | "delete" | "count" | "findMany" | "exists" | "findPage" | "findCursor";
+export type RepositoryAction<Entity> = keyof RepositoryFindBy<Entity> | keyof RepositoryFindManyBy<Entity> | "create" | "update" | "delete" | "restore" | "count" | "findMany" | "exists" | "findPage" | "findCursor";
 /**
  * A repository of `Entity` with the methods of `Actions`, whose provider gets
  * `Environment` as `context.env`, e.g.

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

@@ -8,3 +8,39 @@ export declare const InvalidUseCaseStep: import("../../index.js").DeclaredExcept
     readonly reason: string;
     readonly code?: string;
 }>;
+/**
+ * `useCasePluginOf` or `useCaseCatalogOf` was given what cannot be a plugin
+ * or a catalog: an invalid name or version, no `compile`, two plugins with
+ * one name; or a plugin was called with something that is not a repository
+ * or with options that are not a plain object. `source` is the plugin name.
+ */
+export declare const InvalidUseCasePlugin: import("../../index.js").DeclaredExceptionClass<{
+    readonly reason: string;
+}>;
+/** A catalog has no use case plugin of that name; `source` is `catalog`. */
+export declare const UnknownUseCasePlugin: import("../../index.js").DeclaredExceptionClass<{
+    readonly name: string;
+}>;
+/** The use case plugin of a catalog does not satisfy the version asked for; `source` is the plugin name. */
+export declare const IncompatibleUseCasePlugin: import("../../index.js").DeclaredExceptionClass<{
+    readonly reason: string;
+}>;
+/**
+ * A use case plugin cannot make its use case for a repository: the
+ * repository lacks an action, the entity lacks a record plugin, or an option
+ * names what the entity does not have. `source` is the plugin name.
+ */
+export declare const UseCaseUnavailable: import("../../index.js").DeclaredExceptionClass<{
+    readonly repository: string;
+    readonly reason: string;
+    readonly missing?: {
+        readonly actions: readonly string[];
+        readonly plugins: readonly string[];
+    };
+}>;
+/** What a use case made by a plugin throws for an entity it did not find, unless given another error. */
+export declare const UseCaseEntityNotFound: import("../../index.js").DeclaredExceptionClass<undefined>;
+/** What a use case made by a plugin throws for an entity that already exists, unless given another error. */
+export declare const UseCaseEntityConflict: import("../../index.js").DeclaredExceptionClass<undefined>;
+/** What a use case made by a plugin throws for credentials that do not match, unless given another error. */
+export declare const UseCaseInvalidCredentials: import("../../index.js").DeclaredExceptionClass<undefined>;

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

@@ -0,0 +1,11 @@
+import type { AnyUseCasePlugin, IUseCaseCatalog, UseCasePluginsByName } from "./types/plugin.interface.js";
+/** Whether `value` is a catalog made by `useCaseCatalogOf`. */
+export declare function isUseCaseCatalog(value: unknown): value is IUseCaseCatalog;
+/**
+ * A catalog of use case `plugins`, by name: what `commandBuilderOf` gives
+ * the `useCases` of a command to pick from, as
+ * `(ctx) => ({ create: ctx.create(Posts) })`; `catalog.context` is that
+ * `ctx`, for use outside a command. Throws `InvalidUseCasePlugin` for what
+ * is not a plugin and for two plugins with the same name.
+ */
+export declare function useCaseCatalogOf<const Plugins extends readonly AnyUseCasePlugin[]>(...plugins: Plugins): IUseCaseCatalog<UseCasePluginsByName<Plugins>>;

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

@@ -0,0 +1,25 @@
+import type { AnyUseCasePlugin, IUseCasePlugin, UseCaseMaker, UseCaseOriginInfo, UseCasePluginSettings } from "./types/plugin.interface.js";
+/** Whether `value` is a plugin made by `useCasePluginOf`. */
+export declare function isUseCasePlugin(value: unknown): value is AnyUseCasePlugin;
+/**
+ * The plugin, the repository and the options a use case class was made
+ * from, by a plugin's `make`; `undefined` for a class declared by hand. A
+ * class extending one keeps its origin.
+ */
+export declare function useCaseOriginOf(UseCase: unknown): UseCaseOriginInfo | undefined;
+/**
+ * A use case that is made for a repository. `settings.compile` gets what is
+ * known of the repository and its entity (`UseCaseTargetInfo`) and the
+ * options of the call, and gives the settings of `useCaseOf` with `steps`;
+ * `settings.requires` lists the actions and record plugins it cannot do
+ * without. The plugin's `make(repository, options)` gives the class, the
+ * same for the same repository and equal options.
+ *
+ * `Make` types that call: give it to say which repositories are accepted
+ * (`UseCaseTarget`) and what the use case takes and returns. Without it any
+ * repository is accepted and the class is `AnyUseCaseClass`.
+ *
+ * Throws `InvalidUseCasePlugin` for a name that is not an identifier, a
+ * version that is not semantic or a `compile` that is not a function.
+ */
+export declare function useCasePluginOf<const Name extends string, Make extends UseCaseMaker = UseCaseMaker>(name: Name, settings: UseCasePluginSettings): IUseCasePlugin<Name, Make>;

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

@@ -10,6 +10,11 @@ export type StepReference = `$${string}`;
 export type StepValue = StepReference | string | number | boolean | null | readonly StepValue[] | {
     readonly [key: string]: StepValue;
 };
+/**
+ * The arguments of a `find`, `invoke` or `run`: a list of values, or one
+ * reference to a list, which is spread (`args: "$input.tags"`).
+ */
+export type StepArgs = readonly StepValue[] | StepReference;
 /** The actions of a repository that only read. */
 export type StepReadAction = `findBy${string}` | `findManyBy${string}` | "findMany" | "exists" | "findPage" | "findCursor" | "count";
 type RepositoryKeys<Dependencies> = {
@@ -40,7 +45,7 @@ export type StepEnsureKind = "exists" | "absent" | "equals" | "notEquals" | "tru
 export type UseCaseStep<Dependencies extends UseCaseCollection = UseCaseCollection> = {
     /** `"<repository>.<read action>"`. */
     readonly find: StepFindTarget<Dependencies>;
-    readonly args?: readonly StepValue[];
+    readonly args?: StepArgs;
     readonly as?: string;
 } | {
     readonly ensure: "exists" | "absent" | "true" | "false";
@@ -64,12 +69,14 @@ export type UseCaseStep<Dependencies extends UseCaseCollection = UseCaseCollecti
     readonly change: StepReference;
     readonly key: string;
     readonly value: StepValue;
+    /** Skips the step when `value` resolves to `undefined`: a partial update. */
+    readonly ifPresent?: boolean;
     readonly as?: string;
 } | {
     /** A reference to a record or entity. */
     readonly invoke: StepReference;
     readonly method: string;
-    readonly args?: readonly StepValue[];
+    readonly args?: StepArgs;
     readonly as?: string;
 } | {
     readonly create: StepRepositoryWith<Dependencies, "create">;
@@ -83,6 +90,11 @@ export type UseCaseStep<Dependencies extends UseCaseCollection = UseCaseCollecti
     readonly delete: StepRepositoryWith<Dependencies, "delete">;
     readonly value: StepValue;
     readonly as?: string;
+} | {
+    /** A soft-deleted entity or its id; the repository gives it back alive. */
+    readonly restore: StepRepositoryWith<Dependencies, "restore">;
+    readonly value: StepValue;
+    readonly as?: string;
 } | {
     readonly call: UseCaseKeys<Dependencies>;
     readonly input: StepValue;
@@ -90,7 +102,7 @@ export type UseCaseStep<Dependencies extends UseCaseCollection = UseCaseCollecti
 } | {
     readonly run: string;
     readonly fn: (...args: any[]) => unknown;
-    readonly args?: readonly StepValue[];
+    readonly args?: StepArgs;
     readonly as?: string;
 } | {
     readonly return: StepValue;
@@ -102,7 +114,7 @@ export type StepErrorDescription = string | {
 /** A `UseCaseStep` as `describe()` gives it: classes by name, functions as `opaque`. */
 export type UseCaseStepDescription = {
     readonly find: string;
-    readonly args?: readonly StepValue[];
+    readonly args?: StepArgs;
     readonly as?: string;
 } | {
     readonly ensure: StepEnsureKind;
@@ -118,11 +130,12 @@ export type UseCaseStepDescription = {
     readonly change: string;
     readonly key: string;
     readonly value: StepValue;
+    readonly ifPresent?: boolean;
     readonly as?: string;
 } | {
     readonly invoke: string;
     readonly method: string;
-    readonly args?: readonly StepValue[];
+    readonly args?: StepArgs;
     readonly as?: string;
 } | {
     readonly create: string;
@@ -136,6 +149,10 @@ export type UseCaseStepDescription = {
     readonly delete: string;
     readonly value: StepValue;
     readonly as?: string;
+} | {
+    readonly restore: string;
+    readonly value: StepValue;
+    readonly as?: string;
 } | {
     readonly call: string;
     readonly input: StepValue;
@@ -145,7 +162,7 @@ export type UseCaseStepDescription = {
     readonly fn: {
         readonly kind: "opaque";
     };
-    readonly args?: readonly StepValue[];
+    readonly args?: StepArgs;
     readonly as?: string;
 } | {
     readonly return: StepValue;

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

@@ -0,0 +1,9 @@
+import type { AnyRepository } from "../repository/types/repository.interface.js";
+import type { UseCaseTargetInfo } from "./types/plugin.interface.js";
+/**
+ * What a use case plugin reads of `repository`: its entity, its actions and
+ * a plan of every key, to derive blueprints and steps from. `source` names
+ * who asks, in the `UseCaseUnavailable` it throws. Throws a `TypeError` when
+ * `repository` was not made by `repositoryOf`.
+ */
+export declare function useCaseTargetOf(repository: AnyRepository, source?: string): UseCaseTargetInfo;

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

@@ -0,0 +1,185 @@
+import type { BlueprintField } from "../../blueprint/types/blueprint.interface.js";
+import type { AnyRepository, AnyRepositoryEntity, EntityInstanceOf } from "../../repository/types/repository.interface.js";
+import type { Kind } from "../../symbols/kind.js";
+import type { AnyUseCaseClass, UseCaseStepsSettings } from "../use-case.js";
+/** What a use case plugin needs of the repository it is made for. */
+export interface UseCasePluginRequirements {
+    /** The actions the repository must declare, e.g. `["findById", "update"]`. */
+    readonly actions?: readonly string[];
+    /** The record plugins the entity must have, by name. */
+    readonly plugins?: readonly string[];
+}
+/** What a key of the entity is, for a use case that reads or writes it. */
+export interface UseCaseFieldPlan {
+    readonly key: string;
+    readonly field: BlueprintField;
+    /** One of the identity keys: `id`, `createdAt`, `updatedAt`, `deletedAt`. */
+    readonly identity: boolean;
+    /** The record plugin that adds the key, by name. */
+    readonly plugin: string | undefined;
+    readonly sensitive: boolean;
+    readonly unique: boolean;
+    readonly optional: boolean;
+    /** Whether the entity has `change.<key>`. */
+    readonly change: boolean;
+    readonly kind: "property" | "blueprint" | "list" | "record" | "entity" | "entity-list";
+    /** The entity class the key holds, for `entity` and `entity-list`. */
+    readonly related: AnyRepositoryEntity | undefined;
+    /**
+     * What an input takes for the key: `<key>Id` and the `id` field of the
+     * entity it holds, for an entity; the property a `PropertyInput`
+     * accepts, for a property that declares one; else the key and the field.
+     */
+    readonly input: {
+        readonly key: string;
+        readonly field: BlueprintField;
+    };
+    /**
+     * Turns what the input gave into what the entity stores, for a property
+     * that declares a `PropertyInput` (a plain password into its hash); gives
+     * `undefined` for `undefined`.
+     */
+    readonly convert: ((value: unknown) => unknown) | undefined;
+}
+/** What `compile` gets of the repository a use case is made for. */
+export interface UseCaseTargetInfo {
+    readonly repository: AnyRepository;
+    /** The name `repositoryOf` gave it. */
+    readonly repositoryName: string;
+    readonly entity: AnyRepositoryEntity;
+    /** The declared name of the entity, else the name of its class. */
+    readonly entityName: string;
+    readonly actions: readonly string[];
+    readonly deletion: "hard" | "soft";
+    /** Every key of the entity, in the order of its blueprint. */
+    readonly fields: readonly UseCaseFieldPlan[];
+    readonly changeKeys: readonly string[];
+    readonly uniqueKeys: readonly string[];
+    /** The field plan of `key`; throws `UseCaseUnavailable` when the entity has no such key. */
+    field(key: string): UseCaseFieldPlan;
+    /**
+     * The repository of the entity the key holds, with the `actions` it must
+     * declare; throws `UseCaseUnavailable` when the repository has no such
+     * relation or the related one lacks an action.
+     */
+    relation(key: string, actions?: readonly string[]): AnyRepository;
+    /** Throws `UseCaseUnavailable` for this target, with `reason`. */
+    unavailable(reason: string): never;
+}
+/**
+ * The declaration a plugin compiles: what `useCaseOf` takes, with `steps`.
+ * The steps are data here, checked by `useCaseOf` when the class is made.
+ */
+export interface UseCaseCompilation extends Omit<UseCaseStepsSettings<any, any, any, any>, "steps"> {
+    readonly steps: readonly Readonly<Record<string, unknown>>[];
+}
+/**
+ * The call signature of a plugin without one of its own: any repository,
+ * any options.
+ */
+export type UseCaseMaker = (repository: any, options?: any) => AnyUseCaseClass;
+/** What `useCasePluginOf` takes, after the name. */
+export interface UseCasePluginSettings {
+    /** A semantic version, e.g. `1.2.0`; `1.0.0` when left out. */
+    readonly version?: string;
+    /** What the use case does, for catalogs and tools. */
+    readonly description?: string;
+    readonly requires?: UseCasePluginRequirements;
+    /**
+     * The use case for `target` and `options`, as the settings of
+     * `useCaseOf` with `steps`. The options are the plain object the caller
+     * gave, `{}` when none.
+     */
+    compile(target: UseCaseTargetInfo, options: Readonly<Record<string, unknown>>): UseCaseCompilation;
+}
+/** The plain, JSON form of a use case plugin, as `plugin.toJSON()` gives it. */
+export interface UseCasePluginDescriptor {
+    readonly kind: "use-case-plugin";
+    readonly name: string;
+    readonly version: string;
+    readonly description?: string;
+    readonly requires: Required<UseCasePluginRequirements>;
+}
+/**
+ * A use case that is made for a repository: its blueprints, dependencies and
+ * steps follow the entity, the actions and the plugins. Made by
+ * `useCasePluginOf`.
+ */
+export interface IUseCasePlugin<Name extends string = string, Make extends UseCaseMaker = UseCaseMaker> {
+    readonly [Kind]: "use-case-plugin";
+    readonly name: Name;
+    readonly version: string;
+    readonly description?: string;
+    readonly requires: Required<UseCasePluginRequirements>;
+    /**
+     * The use case class for a repository and options: the same class for
+     * the same repository and equal options. Throws `UseCaseUnavailable`
+     * when the repository or its entity lacks what the plugin requires.
+     */
+    readonly make: Make;
+    toJSON(): UseCasePluginDescriptor;
+}
+/** Any use case plugin. */
+export type AnyUseCasePlugin = IUseCasePlugin<string, any>;
+/** Where a use case class made by a plugin comes from, as `useCaseOriginOf` gives it. */
+export interface UseCaseOriginInfo {
+    readonly plugin: AnyUseCasePlugin;
+    readonly repository: AnyRepository;
+    readonly options: Readonly<Record<string, unknown>>;
+}
+/** @internal */
+export type UseCasePluginsByName<Plugins extends readonly AnyUseCasePlugin[]> = {
+    readonly [Plugin in Plugins[number] as Plugin["name"]]: Plugin;
+};
+/** @internal The `make` of each plugin, by name. */
+export type UseCaseContextOf<Plugins> = {
+    readonly [Name in keyof Plugins]: Plugins[Name] extends {
+        readonly make: infer Make;
+    } ? Make : never;
+};
+/**
+ * Use case plugins by name: what `commandBuilderOf` gives `useCases` to pick
+ * from, as `(ctx) => ({ create: ctx.create(Posts) })`. Made by
+ * `useCaseCatalogOf`.
+ */
+export interface IUseCaseCatalog<Plugins extends Readonly<Record<string, AnyUseCasePlugin>> = Readonly<Record<string, AnyUseCasePlugin>>> {
+    readonly [Kind]: "use-case-catalog";
+    readonly plugins: Plugins;
+    readonly list: readonly AnyUseCasePlugin[];
+    /** The `make` of each plugin, by name. */
+    readonly context: UseCaseContextOf<Plugins>;
+    /** The plugin of a name, or of a name and a version (`create@1.0.0`). */
+    resolve(reference: string): AnyUseCasePlugin;
+}
+/**
+ * @internal The context of a list of catalogs: the `make` of every plugin,
+ * a later catalog winning a name.
+ */
+export type UseCasePluginContext<Catalogs extends readonly IUseCaseCatalog[]> = Catalogs extends readonly [
+    infer Head extends IUseCaseCatalog,
+    ...infer Tail extends readonly IUseCaseCatalog[]
+] ? Omit<Head["context"], keyof UseCasePluginContext<Tail>> & UseCasePluginContext<Tail> : Record<never, never>;
+type ActionsOf<Repository> = Repository extends {
+    readonly actions: readonly (infer Action)[];
+} ? Action : never;
+/** The entity class of a repository. */
+export type EntityOfRepository<Repository> = Repository extends {
+    readonly entity: infer Entity;
+} ? Entity : never;
+/** What the type of an argument shows when the repository lacks an action. */
+export interface MissingRepositoryAction<Action extends string> {
+    readonly "this use case needs the repository to declare the action": Action;
+}
+/** What the type of an argument shows when the entity lacks a record plugin. */
+export interface MissingRecordPlugin<Plugin extends string> {
+    readonly "this use case needs the entity to have the plugin": Plugin;
+}
+/**
+ * The precondition of a use case plugin, in the type of its repository
+ * argument, written `repository: Repository & UseCaseTarget<Repository, ...>`:
+ * nothing when `Repository` declares every `Action` and its entities have
+ * the `Members` of the record plugin `Plugin`; else the type that names what
+ * is missing.
+ */
+export type UseCaseTarget<Repository, Action extends string, Members = unknown, Plugin extends string = never> = [Action] extends [ActionsOf<Repository>] ? EntityInstanceOf<EntityOfRepository<Repository>> extends Members ? unknown : MissingRecordPlugin<Plugin> : MissingRepositoryAction<Exclude<Action, ActionsOf<Repository>>>;
+export {};

package/dist/experimental.js

@@ -7,10 +7,10 @@ import {
   isBlueprintList2,
   AbstractRecord2,
   declareRecord,
-  UndeclaredBlueprintProperty2,
   optionalOf2,
+  UndeclaredBlueprintProperty2,
   blueprintFromProperties
-} from "./index-3nd9bjnc.js";
+} from "./index-r78dsvtc.js";
 
 // src/core/blueprint/slice.ts
 function propertiesOfField(field) {