@afora/core 0.0.5 → 0.0.7

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

@@ -1,10 +1,10 @@
-import type { AnyBlueprint, BlueprintData, BlueprintInput, BlueprintValue, IBlueprint, IBlueprintCollection, RecordAccepts } from "../../blueprint/types/blueprint.interface.js";
+import type { AnyBlueprint, AnyRecordClass, BlueprintData, BlueprintInput, BlueprintValue, IBlueprint, IBlueprintCollection, RecordAccepts } from "../../blueprint/types/blueprint.interface.js";
 import type { ParseResult } from "../../parse/types/parse.interface.js";
 import type { StandardSchemaV1 } from "../../standard/standard-schema.js";
 import type { Kind } from "../../symbols/kind.js";
 import type { Meta } from "../../symbols/meta.js";
 import type { AbstractRecord } from "../abstract-record.js";
-import type { AnyRecordPlugin, RecordPluginsOption, RecordUniqueKeys } from "./plugin.interface.js";
+import type { AnyRecordPlugin, RecordPluginsOption, RecordSensitiveKeys, RecordUniqueKeys } from "./plugin.interface.js";
 /** The value of a record, read from its blueprint. */
 export type RecordValue<Record extends AnyRecordShape> = Record extends {
     readonly [Meta]: {
@@ -41,13 +41,21 @@ export type RecordChange<Record extends AnyRecordShape> = {
 /** A key of the blueprint of a record. */
 export type RecordKey<Properties extends IBlueprintCollection> = keyof Properties & string;
 /** What `recordOf` takes, after the blueprint, to describe its keys. */
-export interface RecordOptions<Properties extends IBlueprintCollection, Change extends readonly RecordKey<Properties>[] = readonly RecordKey<Properties>[], Unique extends readonly RecordKey<Properties>[] = readonly RecordKey<Properties>[], Plugins extends readonly AnyRecordPlugin[] = readonly AnyRecordPlugin[], Context = unknown> {
+export interface RecordOptions<Properties extends IBlueprintCollection, Change extends readonly RecordKey<Properties>[] = readonly RecordKey<Properties>[], Unique extends readonly RecordKey<Properties>[] = readonly RecordKey<Properties>[], Plugins extends readonly AnyRecordPlugin[] = readonly AnyRecordPlugin[], Context = unknown, Sensitive extends readonly RecordKey<Properties>[] = readonly RecordKey<Properties>[]> {
+    /**
+     * The name of the record, read with `recordNameOf(Class)` (or
+     * `Class.recordName`): an identifier that stays the same when a bundler
+     * renames the class. It names the record in exceptions, in the context a
+     * repository gives its provider (`context.name` is `<name>Repository`) and
+     * in OpenAPI. Without it, the name of the class is used.
+     */
+    readonly name?: string;
     /**
      * Keys whose values `toJSON` masks, every leaf as `MASK`, at any depth. A
      * key holding a property declared `sensitive` (as `Password`), or a list of
      * them, is always sensitive, and such a property is masked at any depth.
      */
-    readonly sensitive?: readonly RecordKey<Properties>[];
+    readonly sensitive?: Sensitive;
     /**
      * Keys whose value no two records may share. Records only list them in
      * `options.unique`: repositories (or the database) enforce it. A key
@@ -91,45 +99,98 @@ interface RecordChangeNamespace<Properties extends IBlueprintCollection, Change
 type RecordChangeMethods<Self, Properties extends IBlueprintCollection, Key extends string> = {
     readonly [K in Key]: (value: K extends keyof BlueprintValue<Properties> ? BlueprintValue<Properties>[K] : never) => Self;
 };
-export interface IRecord<Properties extends IBlueprintCollection> {
+/**
+ * A sensitive value as `toJSON` gives it: each leaf (string, number, boolean,
+ * bigint) is the string `MASK`; lists and objects keep their shape, and
+ * `null` and `undefined` stay.
+ */
+export type Masked<Value> = Value extends null | undefined ? Value : Value extends readonly (infer Item)[] ? Masked<Item>[] : Value extends object ? {
+    readonly [Key in keyof Value]: Masked<Value[Key]>;
+} : string;
+/** What `toJSON` gives for `Field`, whose plain value is `Data`. */
+type JsonField<Field, Data> = Field extends {
+    readonly type: {
+        readonly sensitive: true;
+    };
+} ? Masked<Data> : Field extends {
+    readonly type: unknown;
+} ? Data : Field extends AnyRecordClass ? JsonOfRecord<Field, Data> : Field extends {
+    readonly record: infer Class extends AnyRecordClass;
+} ? JsonOfRecord<Class, Data> : Field extends {
+    readonly properties: infer Properties extends IBlueprintCollection;
+} ? Data extends object ? JsonKeys<Properties, Data, never> : Data : Field extends {
+    readonly item: infer Item;
+} ? Data extends readonly (infer ItemData)[] ? JsonField<Item, ItemData>[] : Data : Data;
+/** What the `toJSON` of the records of `Class` gives, in place of their plain value. */
+type JsonOfRecord<Class extends AnyRecordClass, Data> = InstanceType<Class> extends {
+    toJSON(): infer Json;
+} ? Data extends object ? Json : Data : Data;
+/**
+ * `Data`, the plain value of `Properties`, key by key as `toJSON` gives it.
+ * `Result` is a parameter so that no alias names the object.
+ */
+type JsonKeys<Properties, Data, Sensitive, Result = {
+    readonly [Key in keyof Data]: Key extends Sensitive ? Masked<Data[Key]> : Key extends keyof Properties ? JsonField<Properties[Key], Data[Key]> : Data[Key];
+}> = Result;
+/**
+ * What `toJSON` of a record of `Properties` gives: every key of its plain
+ * value, with the keys of `Sensitive` and every property declared
+ * `sensitive`, at any depth, as `Masked`. `Result` is a parameter so that no
+ * alias names the object.
+ */
+type JsonValue<Properties extends IBlueprintCollection, Sensitive, Result = 0 extends 1 & Properties ? Readonly<Record<string, unknown>> : string extends keyof Properties ? Readonly<Record<string, unknown>> : JsonKeys<Properties, BlueprintData<Properties>, Sensitive>> = Result;
+/**
+ * The type of `toJSON()` of a record of `Properties` whose `options.sensitive`
+ * lists `Sensitive`: the plain value, no key left out, sensitive values masked.
+ */
+export type RecordJson<Properties extends IBlueprintCollection, Sensitive extends string = never> = JsonValue<Properties, Sensitive>;
+export interface IRecord<Properties extends IBlueprintCollection, Sensitive extends string = never> {
     /** Declaration metadata, separate from domain keys. */
     readonly [Meta]: {
         readonly blueprint: IBlueprint<Properties>;
         readonly options: RecordSettings<Properties>;
     };
     /** The value with the sensitive keys, and every `sensitive` property, masked. */
-    toJSON(): Readonly<Partial<BlueprintData<Properties>>>;
+    toJSON(): RecordJson<Properties, Sensitive>;
 }
 /**
  * The records of the class `recordOf` returns, with what its plugins add,
  * `Members`.
  */
-export type DeclaredRecordInstance<Properties extends IBlueprintCollection, Change extends readonly string[], Members = unknown> = AbstractRecord<Properties> & Readonly<BlueprintValue<Properties>> & RecordChanges<Properties, Change> & Members;
+export type DeclaredRecordInstance<Properties extends IBlueprintCollection, Change extends readonly string[], Members = unknown, Sensitive extends string = never> = AbstractRecord<Properties, Sensitive> & Readonly<BlueprintValue<Properties>> & RecordChanges<Properties, Change> & Members;
 /**
  * What `recordOf` returns: a class built from the value of the blueprint;
  * `Unique` are the keys of `options.unique`, and `Members` what its plugins
  * add to its records.
  */
-export type RecordConstructor<Properties extends IBlueprintCollection, Change extends readonly string[], Unique extends string = never, Members = unknown, Accepts = never> = {
-    new (value: BlueprintInput<Properties>): DeclaredRecordInstance<Properties, Change, Members>;
+export type RecordConstructor<Properties extends IBlueprintCollection, Change extends readonly string[], Unique extends string = never, Members = unknown, Accepts = never, Sensitive extends string = never> = {
+    new (value: BlueprintInput<Properties>): DeclaredRecordInstance<Properties, Change, Members, Sensitive>;
     /**
      * The Standard Schema of the class: `validate` gives an instance of it, or
      * the issues that reject the value. Typed with the instance of the class
      * `recordOf` returns, not of a subclass.
      */
-    readonly "~standard": StandardSchemaV1.Props<BlueprintInput<Properties>, DeclaredRecordInstance<Properties, Change, Members>>;
+    readonly "~standard": StandardSchemaV1.Props<BlueprintInput<Properties>, DeclaredRecordInstance<Properties, Change, Members, Sensitive>>;
     /**
      * An instance of the class (a subclass included) for `value`, or every
      * issue that rejects it; never throws for an invalid value.
      */
     safeParse<Self extends new (value: never) => object>(this: Self, value: unknown): ParseResult<InstanceType<Self>>;
     readonly [Kind]: "record";
+    /**
+     * The name of the class as declared: the `name` option, which a bundler
+     * does not rename, or the name of the class without one. A subclass may
+     * give its own with `static override readonly recordName = "..."`.
+     */
+    readonly recordName: string;
     readonly blueprint: IBlueprint<Properties>;
     readonly options: RecordSettings<Properties>;
     /** Its plugins, those they require included, each once. */
     readonly plugins: readonly AnyRecordPlugin[];
     /** The keys of `options.unique`, for the type of a plugin of the class. */
     readonly [RecordUniqueKeys]?: Unique;
+    /** The keys of `options.sensitive`, for the type of a plugin of the class. */
+    readonly [RecordSensitiveKeys]?: Sensitive;
     /** More values a field of this class takes, as a sliced record takes the original's records. */
     readonly [RecordAccepts]?: Accepts;
 };

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

@@ -0,0 +1,13 @@
+import type { RepositoryOrder } from "./types/query.interface.js";
+import type { RepositoryData } from "./types/repository.interface.js";
+/**
+ * The cursor of `row` in `orders`: an opaque text holding the values of its
+ * order keys. It is not encrypted or signed: whoever has it can read those
+ * values, and changing it only moves the position inside the same query.
+ */
+export declare function encodeCursor(orders: readonly RepositoryOrder[], row: RepositoryData): string;
+/**
+ * The values a cursor holds, one for each of `orders`; throws
+ * `InvalidRepositoryCursor` when it is not a cursor or was made for another order.
+ */
+export declare function decodeCursor(source: string, orders: readonly RepositoryOrder[], cursor: unknown): readonly unknown[];

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

@@ -1,7 +1,17 @@
+import type { Issue } from "../parse/types/parse.interface.js";
 /** A query contains unsupported keys, ordering or pagination. */
 export declare const InvalidRepositoryQuery: import("../../index.js").DeclaredExceptionClass<{
     readonly reason: string;
 }>;
+/**
+ * `findCursor` got an `after` that is not a cursor it gave, or one made for
+ * another `orderBy`; `source` is the repository name. Its `issues` name the
+ * `after` of the query, so an output answers it as invalid input.
+ */
+export declare const InvalidRepositoryCursor: import("../../index.js").DeclaredExceptionClass<{
+    readonly reason: string;
+    readonly issues: readonly Issue[];
+}>;
 /** `repositoryOf` got something other than an entity, actions and a provider. */
 export declare const InvalidRepositoryDeclaration: import("../../index.js").DeclaredExceptionClass<{
     readonly reason: string;

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

@@ -1,9 +1,9 @@
-import type { RepositoryQuery } from "./types/query.interface.js";
+import type { ProviderQuery, RepositoryQuery } from "./types/query.interface.js";
 import type { RepositoryContext, RepositoryData } from "./types/repository.interface.js";
 /** Validates query structure and optionally normalizes domain values for storage. */
-export declare function prepareQuery(context: RepositoryContext, input?: unknown, map?: (key: string, value: unknown) => unknown): RepositoryQuery;
+export declare function prepareQuery(context: RepositoryContext, input?: unknown, map?: (key: string, value: unknown) => unknown, options?: readonly string[]): RepositoryQuery;
 /** Structural JSON/data equality without depending on object key insertion order. */
 export declare function sameValue(a: unknown, b: unknown): boolean;
 export declare function matchesQuery(data: RepositoryData, query: RepositoryQuery): boolean;
-/** The rows of `query` after ordering, offset and limit. */
-export declare function selectRows(rows: Iterable<RepositoryData>, query: RepositoryQuery): RepositoryData[];
+/** The rows of `query` after ordering, `after`, offset and limit. */
+export declare function selectRows(rows: Iterable<RepositoryData>, query: ProviderQuery): RepositoryData[];

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

@@ -51,8 +51,8 @@ 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`,
- * `exists` and `findPage`. Every method is async and reads and writes through `provider`
+ * `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
  * dependency of a use case, and `RepositoryOf` extends it with a class.

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/query.interface.d.ts

@@ -30,6 +30,41 @@ export interface RepositoryPage<Entity> {
     readonly limit: number;
     readonly offset: number;
 }
+/**
+ * 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.
+ */
+export interface RepositoryCursorQuery<Entity = unknown> extends Omit<RepositoryQuery<Entity>, "offset" | "limit"> {
+    /** Positive integer; 20 when left out. */
+    readonly limit?: number;
+    /** The `next` of the page before; the first page when left out. */
+    readonly after?: string;
+}
+/** A page read by position: its items and, when there are more, the cursor of the next. */
+export interface RepositoryCursorPage<Entity> {
+    readonly items: readonly EntityInstanceOf<Entity>[];
+    readonly limit: number;
+    /** What to give as `after` for the next page; `undefined` on the last one. */
+    readonly next: string | undefined;
+}
+/**
+ * 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.
+ */
+export interface ProviderQuery extends RepositoryQuery {
+    readonly after?: readonly unknown[];
+}
+export interface RepositoryFindCursor<Entity> {
+    /**
+     * A page of `limit` items (20 by default) after the cursor `after`. Unlike
+     * `findPage` it reads one page with one query, does not count, and stays
+     * correct when rows are added or removed between pages.
+     */
+    findCursor(query?: RepositoryCursorQuery<Entity>): Promise<RepositoryCursorPage<Entity>>;
+}
 export interface RepositoryFindMany<Entity> {
     findMany(query?: RepositoryQuery<Entity>): Promise<EntityInstanceOf<Entity>[]>;
 }
@@ -57,6 +92,8 @@ export type ProviderDescription = {
 export interface ProviderCapabilities {
     readonly operators?: readonly string[];
     readonly transactions?: boolean;
+    /** Whether `findMany` honors `after` (`ProviderQuery`), which `findCursor` needs. */
+    readonly keyset?: 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, RepositoryExists, RepositoryFindMany, RepositoryFindPage, RepositoryQuery } from "./query.interface.js";
+import type { ProviderCapabilities, ProviderQuery, RepositoryExists, RepositoryFindCursor, RepositoryFindMany, RepositoryFindPage, 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[];
@@ -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);
+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";
+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.
@@ -82,9 +89,12 @@ export type AnyRepository = AbstractRepository<any, any, any>;
 export type RepositoryData = Readonly<Record<string, unknown>>;
 /** What a provider gets with every call: whose entities, and the environment. */
 export interface RepositoryContext<Environment = unknown> {
-    /** The entity class, e.g. to name a table after it. */
+    /** The entity class; name a table after `recordNameOf(entity)`, not `entity.name`. */
     readonly entity: AnyRepositoryEntity;
-    /** The name of the repository, for the source of its exceptions. */
+    /**
+     * The name of the repository, `<entity name>Repository`, for the source of
+     * its exceptions; stable under minification when the entity declares a `name`.
+     */
     readonly name: string;
     /** The keys no two entities may share, `id` first. */
     readonly unique: readonly string[];
@@ -99,7 +109,8 @@ export interface RepositoryContext<Environment = unknown> {
  */
 export interface IRepositoryProvider<Environment = unknown> {
     findOne(context: RepositoryContext<Environment>, query?: RepositoryQuery): Promise<RepositoryData | undefined>;
-    findMany(context: RepositoryContext<Environment>, query?: RepositoryQuery): Promise<readonly RepositoryData[]>;
+    /** `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>;
     remove(context: RepositoryContext<Environment>, id: string): Promise<void>;

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,8 +10,13 @@ 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" | "count";
+export type StepReadAction = `findBy${string}` | `findManyBy${string}` | "findMany" | "exists" | "findPage" | "findCursor" | "count";
 type RepositoryKeys<Dependencies> = {
     [Key in keyof Dependencies & string]: Dependencies[Key] extends AnyRepository ? Key : never;
 }[keyof Dependencies & string];
@@ -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;