@afora/core 0.0.6 → 0.0.8

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

@@ -1,4 +1,6 @@
 import { type EnvironmentDependencies } from "../environment/environment.js";
+import type { ILogger } from "../logger/logger.js";
+import type { RepositoryIndex, RepositoryScans } from "./types/query.interface.js";
 import type { AnyRepositoryEntity, IRepositoryProvider, RepositoryContext } from "./types/repository.interface.js";
 /** What a repository class holds, shared by the classes extending it. */
 export interface RepositoryState {
@@ -12,6 +14,12 @@ export interface RepositoryState {
     readonly environment: EnvironmentDependencies | undefined;
     /** The repository of each entity class its entities hold, at any depth. */
     readonly relations: ReadonlyMap<object, RepositoryState>;
+    /** Its declared indexes, normalized and frozen. */
+    readonly indexes: Readonly<Record<string, RepositoryIndex>>;
+    /** What it does with a query only a scan serves. */
+    readonly scans: RepositoryScans;
+    /** The logger of the application that bound it, for `scans: "warn"`. */
+    readonly logger?: ILogger;
     context?: RepositoryContext;
 }
 export declare const states: WeakMap<object, RepositoryState>;
@@ -26,6 +34,8 @@ export interface RepositoryInspection {
     readonly entity: AnyRepositoryEntity;
     readonly actions: readonly string[];
     readonly deletion: "hard" | "soft";
+    readonly indexes: Readonly<Record<string, RepositoryIndex>>;
+    readonly scans: RepositoryScans;
     readonly explicitProvider: boolean;
     /** The provider, only when the repository declared it. */
     readonly provider: IRepositoryProvider | undefined;
@@ -37,9 +47,36 @@ 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;
+/**
+ * Throws `RepositoryUsedOutsideApplication` when `state` is a declaration an
+ * application bound to its provider: its calls would read another store.
+ */
+export declare function assertUnbound(state: RepositoryState): void;
+/** Where the application binding a repository comes from. */
+export interface RepositoryBinding {
+    /** The name of the application. */
+    readonly application: string;
+    /** The key of the repository in the application. */
+    readonly key: string;
+    /** The logger of the application, for `scans: "warn"`. */
+    readonly logger?: ILogger;
+}
 /**
  * A repository sharing the declaration of `repository` that reads and writes
  * through `provider`, unless it declared a provider of its own; a declared
- * provider found in `instances` is replaced by its value.
+ * provider found in `instances` is replaced by its value. With `binding`,
+ * the declaration (made by `repositoryOf`) throws
+ * `RepositoryUsedOutsideApplication` from then on.
  */
-export declare function bindRepository<Repository extends object>(repository: Repository, provider: IRepositoryProvider | undefined, instances?: ReadonlyMap<object, IRepositoryProvider>): Repository;
+export declare function bindRepository<Repository extends object>(repository: Repository, provider: IRepositoryProvider | undefined, instances?: ReadonlyMap<object, IRepositoryProvider>, binding?: RepositoryBinding): Repository;
+/** The provider `repository` reads and writes through. @internal */
+export declare function providerOfRepository(repository: unknown): IRepositoryProvider | undefined;

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

@@ -22,6 +22,11 @@ export interface RepositoryQuery<Entity = unknown> {
     readonly offset?: number;
     /** Include destroyed rows; repository defaults depend on its deletion policy. */
     readonly withDeleted?: boolean;
+    /**
+     * Include expired rows, of an entity declared with `expires`; `false` by
+     * default.
+     */
+    readonly withExpired?: boolean;
 }
 /** A page and the unpaginated number of matching live (or explicitly included) rows. */
 export interface RepositoryPage<Entity> {
@@ -32,8 +37,8 @@ export interface RepositoryPage<Entity> {
 }
 /**
  * The query of `findCursor`: as `RepositoryQuery`, with the `next` of the
- * previous page as `after` in place of `offset`. `where`, `orderBy` and
- * `withDeleted` must stay the same from one page to the next.
+ * previous page as `after` in place of `offset`. `where`, `orderBy`,
+ * `withDeleted` and `withExpired` must stay the same from one page to the next.
  */
 export interface RepositoryCursorQuery<Entity = unknown> extends Omit<RepositoryQuery<Entity>, "offset" | "limit"> {
     /** Positive integer; 20 when left out. */
@@ -49,13 +54,56 @@ export interface RepositoryCursorPage<Entity> {
     readonly next: string | undefined;
 }
 /**
- * What a provider gets from `findCursor` on `findMany`: `after` holds one
+ * What a provider gets. From `findCursor` on `findMany`, `after` holds one
  * value for each order of `orderBy`, those of the last row already read, and
- * the provider gives the rows strictly after it in that order. Only a
- * provider with `capabilities.keyset` is given it.
+ * the provider gives the rows strictly after it in that order; only a
+ * provider with `capabilities.keyset` is given it. For an entity that expires
+ * (`context.expiry`), `now` is the current date and time as an ISO 8601
+ * string, from the clock of the entity: unless `withExpired`, the provider
+ * leaves out the rows whose `context.expiry.key` is at or before it.
  */
 export interface ProviderQuery extends RepositoryQuery {
     readonly after?: readonly unknown[];
+    /**
+     * The name of the declared index (`context.indexes`) that serves the
+     * query, when one does; a provider without `capabilities.indexes` can
+     * ignore it, and the rows must be the same either way.
+     */
+    readonly index?: string;
+    /** The current date and time (ISO 8601), given for entities that expire. */
+    readonly now?: string;
+}
+/**
+ * An access pattern a repository declares: queries whose `where` holds every
+ * key of `where` by equality, and whose first order (if any) is `orderBy`.
+ */
+export interface RepositoryIndex<Key extends string = string> {
+    /** The keys the query matches by equality, at least one. */
+    readonly where: readonly Key[];
+    /** The scalar key the rows are read in order of. */
+    readonly orderBy?: Key;
+}
+/**
+ * How a query reaches its rows: by `id`, by another unique key, through a
+ * declared index (named by `index`), or by reading every row (`scan`).
+ */
+export interface RepositoryPlan {
+    readonly access: "id" | "unique" | "index" | "scan";
+    /** The declared index that serves the query, when `access` is `"index"`. */
+    readonly index?: string;
+}
+/**
+ * What a repository does with a query that only a scan serves: run it
+ * (`"allow"`, the default), log `repository-scan` and run it (`"warn"`), or
+ * throw `InvalidRepositoryQuery` before the provider is called (`"reject"`).
+ */
+export type RepositoryScans = "allow" | "warn" | "reject";
+export interface RepositoryExplain<Entity> {
+    /**
+     * How the query would be read (`{ access, index? }`), without reading
+     * anything; takes the query of `findMany` or of `findCursor`.
+     */
+    explain(query?: RepositoryQuery<Entity> | RepositoryCursorQuery<Entity>): Promise<RepositoryPlan>;
 }
 export interface RepositoryFindCursor<Entity> {
     /**
@@ -65,6 +113,48 @@ export interface RepositoryFindCursor<Entity> {
      */
     findCursor(query?: RepositoryCursorQuery<Entity>): Promise<RepositoryCursorPage<Entity>>;
 }
+/** Where `forEachPage` is in its walk, given with each page. */
+export interface RepositoryWalkPage {
+    /** The position of the page in this call, from 0. */
+    readonly index: number;
+    /**
+     * The cursor after this page, `undefined` on the last: save it once the
+     * page is done to resume from the next one.
+     */
+    readonly next?: string;
+}
+/** When `forEachPage` stops before the end. */
+export interface RepositoryWalkOptions {
+    /**
+     * A deadline (a `Date` or epoch milliseconds) or a function that says when
+     * to stop; checked before each page, never while one runs.
+     */
+    readonly until?: Date | number | (() => boolean);
+}
+/** What `forEachPage` did. */
+export interface RepositoryWalkResult {
+    /** Whether it walked to the last page; `false` when `until` stopped it. */
+    readonly done: boolean;
+    /**
+     * When it stopped early, the `after` to resume from: the `next` of the
+     * last page it ran, or the `after` it was given if it ran none.
+     */
+    readonly next?: string;
+    /** The pages it ran `fn` on. */
+    readonly pages: number;
+    /** The items of those pages. */
+    readonly items: number;
+}
+export interface RepositoryForEachPage<Entity> {
+    /**
+     * Reads the pages of `query` by cursor, as `findCursor` does, and runs
+     * `fn` on each, one after the other, until the last or until `until`
+     * says to stop (checked between pages). Rows added or removed between
+     * pages, by `fn` too, are neither repeated nor skipped. An error of `fn`
+     * stops the walk and rejects; resume from the last `next` saved.
+     */
+    forEachPage(query: RepositoryCursorQuery<Entity>, fn: (items: EntityInstanceOf<Entity>[], page: RepositoryWalkPage) => unknown, options?: RepositoryWalkOptions): Promise<RepositoryWalkResult>;
+}
 export interface RepositoryFindMany<Entity> {
     findMany(query?: RepositoryQuery<Entity>): Promise<EntityInstanceOf<Entity>[]>;
 }
@@ -94,6 +184,17 @@ export interface ProviderCapabilities {
     readonly transactions?: boolean;
     /** Whether `findMany` honors `after` (`ProviderQuery`), which `findCursor` needs. */
     readonly keyset?: boolean;
+    /**
+     * Whether the provider serves the indexes a repository declares
+     * (`context.indexes`) from storage, reading `ProviderQuery.index`.
+     */
+    readonly indexes?: boolean;
+    /** Whether `update` honors an expected `version` (versioned entities, #44). */
+    readonly versioning?: boolean;
+    /** Whether the provider has an atomic `increment` (#34). */
+    readonly atomic?: boolean;
+    /** Whether reads leave out expired records (entities with `expires`, #35). */
+    readonly expiry?: boolean;
 }
 /** Declaration input for a named provider, implemented by providerOf in T10. */
 export interface ProviderSettings<Options extends ProviderOptions = ProviderOptions, Provider extends IRepositoryProvider = IRepositoryProvider> {

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

@@ -3,7 +3,7 @@ import type { AbstractEntity, EntityUniqueKeys } from "../../entity/abstract-ent
 import type { AnyEntityClass } from "../../entity/event.js";
 import type { RecordSettings } from "../../record/types/record.interface.js";
 import type { AbstractRepository } from "../repository.js";
-import type { ProviderCapabilities, ProviderQuery, RepositoryExists, RepositoryFindCursor, RepositoryFindMany, RepositoryFindPage, RepositoryQuery } from "./query.interface.js";
+import type { ProviderCapabilities, ProviderQuery, RepositoryExists, RepositoryExplain, RepositoryFindCursor, RepositoryFindMany, RepositoryFindPage, RepositoryForEachPage, RepositoryIndex, RepositoryQuery } from "./query.interface.js";
 /** Any class made by `entityOf`, or extending one, that a repository holds. */
 export type AnyRepositoryEntity = AnyRecordClass & AnyEntityClass & {
     readonly [EntityUniqueKeys]: readonly string[];
@@ -38,10 +38,49 @@ export interface RepositoryCreate<Entity> {
 export interface RepositoryUpdate<Entity> {
     update(entity: EntityInstanceOf<Entity>): Promise<EntityInstanceOf<Entity>>;
 }
+type ChangeKeyOf<Entity> = EntityInstanceOf<Entity> extends {
+    readonly change: infer Change;
+} ? keyof Change & string : never;
+/**
+ * The keys `increment` takes for `Entity`: those of its `change` list that
+ * hold a number.
+ */
+export type EntityIncrementKeyOf<Entity> = {
+    [Key in ChangeKeyOf<Entity>]: NonNullable<ValueAt<Entity, Key>> extends number ? Key : never;
+}[ChangeKeyOf<Entity>];
+/** What `increment` adds to each key, e.g. `{ views: 1 }`. */
+export type RepositoryIncrementDeltas<Entity> = {
+    readonly [Key in EntityIncrementKeyOf<Entity>]?: number;
+};
+/** The options of `increment`. */
+export interface RepositoryIncrementOptions<Entity> {
+    /**
+     * The input of the entity to create when the id holds none, without its
+     * `id` (the one given) and with the keys of the deltas optional (0 when
+     * left out); the deltas are added to it.
+     */
+    readonly create?: Omit<Entity extends new (value: infer Input) => unknown ? Input : never, "id" | EntityIncrementKeyOf<Entity>> & {
+        readonly [Key in EntityIncrementKeyOf<Entity>]?: number;
+    };
+}
+/**
+ * `increment`: adds the deltas to the numeric keys of the entity of the id
+ * (or the one given) in one atomic write, and gives the entity as stored.
+ */
+export interface RepositoryIncrement<Entity> {
+    increment(entity: EntityInstanceOf<Entity> | string, deltas: RepositoryIncrementDeltas<Entity>, options?: RepositoryIncrementOptions<Entity>): Promise<EntityInstanceOf<Entity>>;
+}
 /** `delete`: destroys the entity (or the one of the id), removes it and gives it. */
 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,19 +106,54 @@ 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) & ("increment" extends Actions ? RepositoryIncrement<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) & ("explain" extends Actions ? RepositoryExplain<Entity> : unknown) & ("forEachPage" extends Actions ? RepositoryForEachPage<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" | "increment" | "count" | "findMany" | "exists" | "findPage" | "findCursor" | "explain" | "forEachPage";
+/**
+ * Whether a repository given `Provider` keeps `findCursor`: `false` when the
+ * type of its `capabilities.keyset` cannot be `true` (left out of the
+ * capabilities, or `false`), `true` for `true`, for a wide `boolean`, and
+ * with no provider (the default in-memory one reads by cursor). `repositoryOf`
+ * infers only the `capabilities` of a provider: one without them keeps
+ * `findCursor` in the type and is rejected at declaration.
+ */
+export type ProviderKeyset<Provider> = undefined extends Provider ? true : Provider extends {
+    readonly capabilities?: infer Capabilities;
+} ? [NonNullable<Capabilities>] extends [{
+    readonly keyset?: infer Keyset;
+}] ? true extends Keyset ? true : false : false : false;
 /**
  * A repository of `Entity` with the methods of `Actions`, whose provider gets
  * `Environment` as `context.env`, e.g.
  * `RepositoryOf<typeof User, ["findById", "create"]>`.
  */
-export type RepositoryOf<Entity extends AnyRepositoryEntity, Actions extends readonly RepositoryAction<Entity>[], Environment = Readonly<Record<never, never>>> = AbstractRepository<Entity, Actions, Environment> & RepositoryMethods<Entity, Actions[number]>;
+export type RepositoryOf<Entity extends AnyRepositoryEntity, Actions extends readonly RepositoryAction<Entity>[], Environment = Readonly<Record<never, never>>, Keyset extends boolean = true> = AbstractRepository<Entity, Actions, Environment> & RepositoryMethods<Entity, Keyset extends true ? Actions[number] : Exclude<Actions[number], "findCursor">>;
 /** Any repository, whatever its entity, actions and environment. */
 export type AnyRepository = AbstractRepository<any, any, any>;
 /** A value of an entity as a provider stores it: plain, unmasked. */
 export type RepositoryData = Readonly<Record<string, unknown>>;
+/** What `update` of a provider gets after the data. */
+export interface ProviderUpdateOptions {
+    /** The `version` the stored row must hold for the write to happen. */
+    readonly expectedVersion?: number;
+}
+/** What `increment` of a provider gets after the deltas. */
+export interface ProviderIncrementOptions {
+    /** Values stored as they are by the same write, e.g. `updatedAt`. */
+    readonly set?: RepositoryData;
+    /**
+     * The row to insert when the id holds none, or holds one that expired
+     * (which it replaces).
+     */
+    readonly create?: RepositoryData;
+    /**
+     * For an entity that expires (`context.expiry`), the current date and
+     * time (ISO 8601) by the clock of the entity: a row whose expiry is at or
+     * before it counts as absent. A provider called without it uses the
+     * current time.
+     */
+    readonly now?: string;
+}
 /** What a provider gets with every call: whose entities, and the environment. */
 export interface RepositoryContext<Environment = unknown> {
     /** The entity class; name a table after `recordNameOf(entity)`, not `entity.name`. */
@@ -91,6 +165,21 @@ export interface RepositoryContext<Environment = unknown> {
     readonly name: string;
     /** The keys no two entities may share, `id` first. */
     readonly unique: readonly string[];
+    /**
+     * The indexes the repository declares, by name, for a provider to build
+     * (a GSI, an SQL index); a repository always gives it, empty when it
+     * declares none (optional for contexts built by hand).
+     */
+    readonly indexes?: Readonly<Record<string, RepositoryIndex>>;
+    /**
+     * For an entity declared with `expires`, the key holding the date at which
+     * a record expires (`expiresAt`, or the key of `at`): reads leave out the
+     * records whose date is at or before `query.now`, unless
+     * `query.withExpired`. A record without a date never expires.
+     */
+    readonly expiry?: {
+        readonly key: string;
+    };
     /** The variables of the `environmentDependencies` of the repository. */
     readonly env: Environment;
 }
@@ -101,13 +190,30 @@ export interface RepositoryContext<Environment = unknown> {
  * `RepositoryEntityNotFound` for an unknown id.
  */
 export interface IRepositoryProvider<Environment = unknown> {
-    findOne(context: RepositoryContext<Environment>, query?: RepositoryQuery): Promise<RepositoryData | undefined>;
+    findOne(context: RepositoryContext<Environment>, query?: ProviderQuery): Promise<RepositoryData | undefined>;
     /** `query.after` is only given to a provider with `capabilities.keyset`. */
     findMany(context: RepositoryContext<Environment>, query?: ProviderQuery): Promise<readonly RepositoryData[]>;
     insert(context: RepositoryContext<Environment>, data: RepositoryData): Promise<void>;
-    update(context: RepositoryContext<Environment>, data: RepositoryData): Promise<void>;
+    /**
+     * With `options.expectedVersion`, writes only when the stored `version` is
+     * that one, and throws `RepositoryConcurrencyConflict` otherwise; only a
+     * provider with `capabilities.versioning` is given it.
+     */
+    update(context: RepositoryContext<Environment>, data: RepositoryData, options?: ProviderUpdateOptions): Promise<void>;
     remove(context: RepositoryContext<Environment>, id: string): Promise<void>;
-    count(context: RepositoryContext<Environment>, query?: RepositoryQuery): Promise<number>;
+    /**
+     * Adds each of `deltas` to the stored number of its key (a missing one
+     * counts as 0) and stores `options.set` in the same atomic write, then
+     * gives the row as stored. Only rows that are not soft-deleted, nor expired
+     * (`context.expiry`, at `options.now`), match. When the id holds none (or
+     * an expired one), inserts `options.create` as it is, replacing the expired
+     * row, and gives it, or throws `RepositoryEntityNotFound` without it; a
+     * concurrent insert of the same id still gets the deltas added. A
+     * soft-deleted row with `create` is a `RepositoryUniqueViolation` on `id`.
+     * Advertised by `capabilities.atomic`.
+     */
+    increment?(context: RepositoryContext<Environment>, id: string, deltas: Readonly<Record<string, number>>, options?: ProviderIncrementOptions): Promise<RepositoryData>;
+    count(context: RepositoryContext<Environment>, query?: ProviderQuery): Promise<number>;
     readonly capabilities?: ProviderCapabilities;
     transaction?<Result>(run: (provider: IRepositoryProvider<Environment>) => Promise<Result>): Promise<Result>;
     /** Releases what the provider holds (connections, files); `app.stop()` calls it. */

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;