@afora/core 0.0.9 → 0.0.12

package/dist/core/use-case/steps/validate.js

@@ -0,0 +1,368 @@
+import { isBlueprint } from "../../blueprint/is-blueprint.js";
+import { isBlueprintList } from "../../blueprint/list.js";
+import { isRecordClass, recordFieldOf } from "../../blueprint/record-field.js";
+import {
+  blueprintOfVariant,
+  isBlueprintVariant
+} from "../../blueprint/variant.js";
+import { isEnvironment } from "../../environment/environment.js";
+import { isDeclaredException } from "../../exception/exception.js";
+import { isRepository } from "../../repository/repository.js";
+import { Kind } from "../../symbols/kind.js";
+import { InvalidUseCaseStep } from "../exceptions.js";
+import {
+  isPlain,
+  isStepName,
+  parseReference,
+  RESERVED_NAMES,
+  walkValue
+} from "./references.js";
+const SHAPES = {
+  find: { required: ["find"], optional: ["args", "as"] },
+  ensure: {
+    required: ["ensure", "value", "error"],
+    optional: ["other", "details"]
+  },
+  build: { required: ["build", "values", "as"], optional: [] },
+  change: {
+    required: ["change", "key", "value"],
+    optional: ["ifPresent", "as"]
+  },
+  invoke: { required: ["invoke", "method"], optional: ["args", "as"] },
+  create: { required: ["create", "value"], optional: ["as"] },
+  update: { required: ["update", "value"], optional: ["as"] },
+  delete: { required: ["delete", "value"], optional: ["as"] },
+  restore: { required: ["restore", "value"], optional: ["as"] },
+  call: { required: ["call", "input"], optional: ["as"] },
+  run: { required: ["run", "fn"], optional: ["args", "params", "as"] },
+  return: { required: ["return"], optional: [] }
+};
+const KINDS = Object.keys(SHAPES);
+const ENSURE_KINDS = new Set([
+  "exists",
+  "absent",
+  "equals",
+  "notEquals",
+  "true",
+  "false"
+]);
+const READ_ACTION = /^(?:findBy.+|findManyBy.+|findMany|exists|findPage|findCursor|count)$/;
+const WRITE_ACTIONS = new Set([
+  "create",
+  "update",
+  "delete",
+  "restore",
+  "increment"
+]);
+const INDEX = /^(?:0|[1-9][0-9]*)$/;
+const LENGTH = Symbol("length");
+const PRIMITIVE_SCHEMA_TYPES = new Set([
+  "string",
+  "number",
+  "integer",
+  "boolean",
+  "null"
+]);
+function isPrimitiveProperty(field) {
+  const schema = field?.type?.schema;
+  if (typeof field !== "function" || schema === undefined)
+    return false;
+  try {
+    const type = JSON.parse(schema.toString()).type;
+    return typeof type === "string" && PRIMITIVE_SCHEMA_TYPES.has(type);
+  } catch {
+    return false;
+  }
+}
+function missingSegment(field, path) {
+  let current = field;
+  for (const segment of path) {
+    if (current === LENGTH)
+      return segment;
+    if (isBlueprint(current)) {
+      if (!Object.hasOwn(current.properties, segment))
+        return segment;
+      current = current.properties[segment];
+      continue;
+    }
+    if (isBlueprintList(current)) {
+      if (segment === "length") {
+        current = LENGTH;
+        continue;
+      }
+      if (!INDEX.test(segment))
+        return segment;
+      current = current.item;
+      continue;
+    }
+    if (isBlueprintVariant(current)) {
+      if (segment === current.key)
+        return;
+      const variants = current.variants;
+      const holder = Object.values(variants).map(blueprintOfVariant).find((variant) => Object.hasOwn(variant.properties, segment));
+      if (!holder)
+        return segment;
+      current = holder.properties[segment];
+      continue;
+    }
+    const record = recordFieldOf(current)?.record;
+    if (record) {
+      const { properties } = record.blueprint;
+      if (Object.hasOwn(properties, segment)) {
+        current = properties[segment];
+        continue;
+      }
+      return segment in record.prototype ? undefined : segment;
+    }
+    return isPrimitiveProperty(current) ? segment : undefined;
+  }
+  return;
+}
+export function validateSteps(declaration, steps) {
+  const { name } = declaration;
+  const fail = (index, code, reason) => {
+    throw new InvalidUseCaseStep({
+      source: name,
+      details: { index, reason, code }
+    });
+  };
+  if (!Array.isArray(steps) || steps.length === 0) {
+    fail(0, "missing_return", "Expected steps to be a list ending in return.");
+  }
+  const list = steps;
+  const bound = new Map;
+  const runs = new Set;
+  let returned = false;
+  const useCaseDependency = (key) => typeof key === "string" && Object.hasOwn(declaration.dependencies, key) ? declaration.dependencies[key] : undefined;
+  const checkReference = (index, text) => {
+    const reference = parseReference(text);
+    if (!reference) {
+      fail(index, "invalid_reference", `"${text}" is not a valid reference.`);
+      return;
+    }
+    const { root, path } = reference;
+    const firstKey = path[0];
+    if (root === "input" || root === "context") {
+      const blueprint = root === "input" ? declaration.blueprint : declaration.context;
+      if (blueprint === undefined) {
+        fail(index, "invalid_reference", `"${text}" uses $context, but the use case declares no context.`);
+        return;
+      }
+      const missing = missingSegment(blueprint, path);
+      if (missing !== undefined) {
+        fail(index, "unknown_key", `"${text}" names "${missing}", which the ${root} does not declare.`);
+      }
+      return;
+    }
+    if (root === "env") {
+      if (firstKey === undefined || !isEnvironment(useCaseDependency(firstKey))) {
+        fail(index, "unknown_dependency", `"${text}" must name an environment dependency.`);
+      }
+      return;
+    }
+    if (RESERVED_NAMES.includes(root)) {
+      fail(index, "invalid_reference", `"${root}" is reserved.`);
+      return;
+    }
+    if (!bound.has(root)) {
+      fail(index, "unbound_reference", `"${text}" uses "${root}", which no earlier step binds.`);
+    }
+  };
+  const checkValue = (index, value, field) => {
+    walkValue(value, (_reference, text) => checkReference(index, text), (issue, text) => fail(index, issue, issue === "invalid_reference" ? `"${text}" is not a valid reference.` : `${field} must hold only JSON values and references.`));
+  };
+  const checkArgs = (index, args) => {
+    if (args === undefined)
+      return;
+    if (typeof args === "string" && args.startsWith("$")) {
+      checkReference(index, args);
+      return;
+    }
+    if (!Array.isArray(args)) {
+      fail(index, "invalid_step", "args must be a list of values or a reference to one.");
+    }
+    checkValue(index, args, "args");
+  };
+  const checkTarget = (index, target, kind) => {
+    if (typeof target !== "string" || !target.startsWith("$")) {
+      fail(index, "invalid_reference", `${kind} must be a reference.`);
+      return;
+    }
+    checkReference(index, target);
+  };
+  const repositoryOf = (index, key, action) => {
+    const dependency = useCaseDependency(key);
+    if (!isRepository(dependency)) {
+      return fail(index, "unknown_dependency", `"${String(key)}" is not a repository dependency.`);
+    }
+    const actions = dependency.actions;
+    if (!actions.includes(action)) {
+      fail(index, "unknown_action", `The repository "${String(key)}" has no "${action}" action.`);
+    }
+    return { actions };
+  };
+  for (const [index, step] of list.entries()) {
+    if (!isPlain(step) || Array.isArray(step)) {
+      fail(index, "unknown_step", "A step must be an object.");
+    }
+    const record = step;
+    const kinds = KINDS.filter((kind) => Object.hasOwn(record, kind));
+    if (kinds.length !== 1) {
+      fail(index, "unknown_step", kinds.length === 0 ? `Unknown step; expected one of ${KINDS.join(", ")}.` : `A step has one kind, found ${kinds.join(" and ")}.`);
+    }
+    const kind = kinds[0];
+    const shape = SHAPES[kind];
+    for (const key of shape.required) {
+      if (!Object.hasOwn(record, key) || record[key] === undefined) {
+        fail(index, "invalid_step", `A ${kind} step needs "${key}".`);
+      }
+    }
+    for (const key of Object.keys(record)) {
+      if (!shape.required.includes(key) && !shape.optional.includes(key)) {
+        fail(index, "invalid_step", `A ${kind} step has no "${key}".`);
+      }
+    }
+    const as = record.as;
+    if (as !== undefined) {
+      if (!isStepName(as) || RESERVED_NAMES.includes(as) || bound.has(as)) {
+        fail(index, "invalid_step_name", `"${String(as)}" must be an identifier, not reserved, bound once.`);
+      }
+    }
+    let knownRecord;
+    switch (kind) {
+      case "find": {
+        const target = record.find;
+        const parts = typeof target === "string" ? target.split(".") : [];
+        const [repository, action] = parts;
+        if (parts.length !== 2 || !repository || !action) {
+          fail(index, "invalid_step", 'find must be "<repository>.<action>".');
+        }
+        if (WRITE_ACTIONS.has(action)) {
+          fail(index, "write_in_find", `find cannot call "${action}".`);
+        }
+        if (action === "forEachPage") {
+          fail(index, "unknown_action", '"forEachPage" runs a function on each page and cannot be a step; call it from a use case written in TypeScript.');
+        }
+        if (!READ_ACTION.test(action)) {
+          fail(index, "unknown_action", `"${action}" is not a read action.`);
+        }
+        repositoryOf(index, repository, action);
+        checkArgs(index, record.args);
+        break;
+      }
+      case "ensure": {
+        if (!ENSURE_KINDS.has(record.ensure)) {
+          fail(index, "invalid_step", `ensure must be one of ${[...ENSURE_KINDS].join(", ")}.`);
+        }
+        const compares = record.ensure === "equals" || record.ensure === "notEquals";
+        if (compares && record.other === undefined) {
+          fail(index, "invalid_step", `ensure "${record.ensure}" needs other.`);
+        }
+        if (!compares && record.other !== undefined) {
+          fail(index, "invalid_step", `ensure "${String(record.ensure)}" has no other.`);
+        }
+        if (!isDeclaredException(record.error) || !declaration.errors.includes(record.error)) {
+          fail(index, "undeclared_error", "ensure.error must be a class made by exceptionOf, listed in errors.");
+        }
+        checkValue(index, record.value, "value");
+        if (record.other !== undefined)
+          checkValue(index, record.other, "other");
+        if (record.details !== undefined) {
+          checkValue(index, record.details, "details");
+        }
+        break;
+      }
+      case "build": {
+        if (!isRecordClass(record.build)) {
+          fail(index, "invalid_class", "build must be a record or entity class.");
+        }
+        const values = record.values;
+        if (!(typeof values === "string" && values.startsWith("$")) && !isPlain(values)) {
+          fail(index, "invalid_step", "build.values must be a mapping or a reference.");
+        }
+        checkValue(index, values, "values");
+        knownRecord = record.build;
+        break;
+      }
+      case "change": {
+        checkTarget(index, record.change, "change");
+        if (typeof record.key !== "string" || record.key === "") {
+          fail(index, "invalid_step", "change.key must be a string.");
+        }
+        if (record.ifPresent !== undefined && typeof record.ifPresent !== "boolean") {
+          fail(index, "invalid_step", "change.ifPresent must be a boolean.");
+        }
+        const reference = parseReference(record.change);
+        const known = reference && reference.path.length === 0 ? bound.get(reference.root)?.record : undefined;
+        if (known) {
+          const keys = known.options?.change ?? [];
+          if (!keys.includes(record.key)) {
+            fail(index, "invalid_change_key", `"${String(record.key)}" is not a change key of ${known.name}.`);
+          }
+        }
+        checkValue(index, record.value, "value");
+        knownRecord = known;
+        break;
+      }
+      case "invoke": {
+        checkTarget(index, record.invoke, "invoke");
+        if (typeof record.method !== "string" || record.method === "") {
+          fail(index, "invalid_step", "invoke.method must be a string.");
+        }
+        checkArgs(index, record.args);
+        break;
+      }
+      case "create":
+      case "update":
+      case "delete":
+      case "restore": {
+        repositoryOf(index, record[kind], kind);
+        checkValue(index, record.value, "value");
+        break;
+      }
+      case "call": {
+        const dependency = useCaseDependency(record.call);
+        if (typeof dependency !== "function" || dependency[Kind] !== "use-case") {
+          fail(index, "unknown_dependency", `"${String(record.call)}" is not a use case dependency.`);
+        }
+        checkValue(index, record.input, "input");
+        break;
+      }
+      case "run": {
+        const runName = record.run;
+        if (!isStepName(runName) || runs.has(runName)) {
+          fail(index, "invalid_step_name", `run "${String(runName)}" must be an identifier, unique in the use case.`);
+        }
+        if (typeof record.fn !== "function") {
+          fail(index, "invalid_step", "run.fn must be a function.");
+        }
+        runs.add(runName);
+        checkArgs(index, record.args);
+        if (record.params !== undefined) {
+          if (!isBlueprint(record.params)) {
+            fail(index, "invalid_step", "run.params must be a blueprint.");
+          }
+          const declared = Object.keys(record.params.properties).length;
+          const given = record.args === undefined ? 0 : Array.isArray(record.args) ? record.args.length : undefined;
+          if (given !== undefined && given !== declared) {
+            fail(index, "invalid_args", `run.params declares ${declared} parameter(s), args gives ${given}.`);
+          }
+        }
+        break;
+      }
+      case "return": {
+        checkValue(index, record.return, "return");
+        returned = true;
+        if (index !== list.length - 1) {
+          fail(index, "misplaced_return", "return must be the last step, exactly once.");
+        }
+        break;
+      }
+    }
+    if (typeof as === "string")
+      bound.set(as, { record: knownRecord });
+  }
+  if (!returned) {
+    fail(list.length, "missing_return", "The steps must end with return.");
+  }
+}

package/dist/core/use-case/target.js

@@ -0,0 +1,100 @@
+import { fieldOf } from "../blueprint/callable.js";
+import { isBlueprint } from "../blueprint/is-blueprint.js";
+import { isBlueprintList } from "../blueprint/list.js";
+import { optionalOf } from "../blueprint/optional.js";
+import { recordFieldOf } from "../blueprint/record-field.js";
+import { isBlueprintVariant } from "../blueprint/variant.js";
+import { identityKeysOf } from "../entity/abstract-entity.js";
+import { isEntityClass } from "../entity/entity.js";
+import { propertyInputOf } from "../property/input.js";
+import { isProperty } from "../property/is-property.js";
+import { recordNameOf } from "../record/name.js";
+import { pluginsOf } from "../record/plugin.js";
+import { findState, relatedRepositoryOf } from "../repository/state.js";
+import { UseCaseUnavailable } from "./exceptions.js";
+function isOptionalField(field) {
+  if (isProperty(field))
+    return field.type.optional === true;
+  const record = recordFieldOf(field);
+  if (record)
+    return record.optional;
+  return field.optional === true;
+}
+function planOf(entity, key, owners) {
+  const field = fieldOf(entity.blueprint.properties[key]);
+  const optional = isOptionalField(field);
+  const record = recordFieldOf(field);
+  const item = isBlueprintList(field) ? recordFieldOf(field.item) : undefined;
+  const related = [record?.record, item?.record].find(isEntityClass);
+  const kind = record ? related ? "entity" : "record" : isBlueprintList(field) ? related ? "entity-list" : "list" : isBlueprint(field) || isBlueprintVariant(field) ? "blueprint" : "property";
+  let input = { key, field };
+  if (kind === "entity" && related) {
+    const id = related.blueprint.properties.id;
+    input = { key: `${key}Id`, field: optional ? optionalOf(id) : id };
+  }
+  const declared = kind === "property" ? propertyInputOf(field) : undefined;
+  if (declared) {
+    input = {
+      key,
+      field: optional ? optionalOf(declared.accepts) : declared.accepts
+    };
+  }
+  return Object.freeze({
+    key,
+    field,
+    identity: identityKeysOf(entity).includes(key),
+    plugin: owners.get(key),
+    sensitive: entity.options.sensitive.includes(key),
+    unique: entity.options.unique.includes(key),
+    optional,
+    change: entity.options.change.includes(key),
+    kind,
+    related,
+    input: Object.freeze(input),
+    convert: declared ? (value) => value === undefined ? undefined : declared.convert(value) : undefined
+  });
+}
+export function useCaseTargetOf(repository, source = "useCaseTargetOf") {
+  const state = findState(repository);
+  if (!state)
+    throw new TypeError("Expected a repository made by repositoryOf");
+  const { entity } = state;
+  const unavailable = (reason) => {
+    throw new UseCaseUnavailable({
+      source,
+      details: { repository: state.name, reason }
+    });
+  };
+  const owners = new Map;
+  for (const plugin of pluginsOf(entity)) {
+    for (const key of plugin.keys)
+      owners.set(key, plugin.name);
+  }
+  const fields = Object.freeze(Object.keys(entity.blueprint.properties).map((key) => planOf(entity, key, owners)));
+  const field = (key) => fields.find((plan) => plan.key === key) ?? unavailable(`the entity has no key "${key}"`);
+  return Object.freeze({
+    repository,
+    repositoryName: state.name,
+    entity,
+    entityName: recordNameOf(entity),
+    actions: state.actions,
+    deletion: state.deletion,
+    fields,
+    changeKeys: entity.options.change,
+    uniqueKeys: entity.options.unique,
+    field,
+    relation(key, actions = []) {
+      const { related } = field(key);
+      const found = related ? relatedRepositoryOf(repository, related) : undefined;
+      if (!found) {
+        return unavailable(`the repository has no relation for the entity of "${key}"`);
+      }
+      const missing = actions.filter((action) => !found.actions.includes(action));
+      if (missing.length > 0) {
+        unavailable(`the repository of "${key}" lacks the action ${missing.map((action) => `"${action}"`).join(", ")}`);
+      }
+      return found;
+    },
+    unavailable
+  });
+}

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

@@ -6,13 +6,29 @@ export type RouteSuccessStatus = 200 | 201 | 202 | 204;
 export interface RouteCookie {
     /** The name of the cookie. */
     readonly name: string;
-    /** Not readable by scripts of the page. `true` by default. */
+    /**
+     * Not readable by scripts of the page.
+     *
+     * @default true
+     */
     readonly httpOnly?: boolean;
-    /** Sent over HTTPS only. `true` by default. */
+    /**
+     * Sent over HTTPS only.
+     *
+     * @default true
+     */
     readonly secure?: boolean;
-    /** `"lax"` by default. */
+    /**
+     * The `SameSite` attribute of the cookie.
+     *
+     * @default "lax"
+     */
     readonly sameSite?: "strict" | "lax" | "none";
-    /** `"/"` by default. */
+    /**
+     * The `Path` attribute of the cookie.
+     *
+     * @default "/"
+     */
     readonly path?: string;
     readonly domain?: string;
     /** The seconds the cookie lives; without it, until the browser closes. */
@@ -32,7 +48,11 @@ export interface RouteDeclaration {
      * is the default of the sink: `/{kebab(command)}/{kebab(operation)}`.
      */
     readonly path?: string;
-    /** `200` by default. */
+    /**
+     * The status of a successful response.
+     *
+     * @default 200
+     */
     readonly status?: RouteSuccessStatus;
     /**
      * Scalar input keys read from the query string. A `get` or `delete` route

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

@@ -37,14 +37,31 @@ export type AnyExceptionClass = DeclaredExceptionClass<any>;
  * `repositoryOf`, an environment made by `environmentOf`, or `Logger`.
  */
 export type UseCaseDependency = AnyUseCaseClass | AnyRepository | AnyEnvironment | LoggerDeclaration;
+/**
+ * The `dependencies` of a use case, by name: use case classes, repositories,
+ * environments or the {@link Logger}.
+ */
 export type UseCaseCollection = Readonly<Record<string, UseCaseDependency>>;
 type Declaration = {
     readonly blueprint: AnyBlueprint;
     readonly response: AnyBlueprint;
     readonly dependencies: UseCaseCollection;
 };
+/**
+ * The input of a use case class, as its constructor takes it: the input of its
+ * `blueprint`.
+ */
 export type UseCaseInput<Class extends Declaration> = BlueprintInput<Class["blueprint"]["properties"]>;
+/**
+ * The value `execute` of a use case class resolves with: the value of its
+ * `response` blueprint.
+ */
 export type UseCaseResponse<Class extends Declaration> = BlueprintValue<Class["response"]["properties"]>;
+/**
+ * The dependencies of a use case class as `this.dependencies` gives them: a
+ * function for a use case, the repository itself, the variables of an
+ * environment or an {@link ILogger} (see {@link DependencyOf}).
+ */
 export type UseCaseDependencies<Class extends Declaration> = DependencyFunctions<Class["dependencies"]>;
 /** The context of a use case class, as `this.context` gives it; `undefined` without one. */
 export type UseCaseContext<Class extends {
@@ -66,6 +83,10 @@ type OptionsArgs<Context extends IBlueprintCollection | undefined> = Context ext
  * repository itself, the variables of an environment, or an `ILogger`.
  */
 export type DependencyOf<Dependency> = Dependency extends AnyUseCaseClass ? (input: UseCaseInput<Dependency>) => Promise<UseCaseResponse<Dependency>> : Dependency extends AnyEnvironment ? EnvironmentValue<Dependency> : Dependency extends LoggerDeclaration ? ILogger : Dependency;
+/**
+ * A collection of dependencies as a use case receives them: each one as {@link
+ * DependencyOf} gives it.
+ */
 export type DependencyFunctions<Dependencies extends UseCaseCollection> = {
     readonly [Key in keyof Dependencies]: DependencyOf<Dependencies[Key]>;
 };
@@ -76,6 +97,12 @@ export type DependencyFunctions<Dependencies extends UseCaseCollection> = {
 export type DependencyOverrides<Dependencies extends UseCaseCollection> = {
     readonly [Key in keyof Dependencies]?: Dependencies[Key] extends AnyRepository ? Partial<Dependencies[Key]> : DependencyOf<Dependencies[Key]>;
 };
+/**
+ * What {@link useCaseOf} takes: the `name`, the `blueprint` of the input, the
+ * `response` blueprint, the `dependencies` and the `context`, with the
+ * documentation of the operation (`description`, `tags`, `deprecated`,
+ * `errors`) and where it is served and who may call it (`route`, `access`).
+ */
 export interface UseCaseSettings<Input extends IBlueprintCollection, Output extends IBlueprintCollection, Dependencies extends UseCaseCollection, Context extends IBlueprintCollection | undefined = undefined> {
     readonly name: string;
     readonly blueprint: IBlueprint<Input>;
@@ -125,9 +152,10 @@ export interface UseCaseDeclaration<Input extends IBlueprintCollection, Output e
      * class concrete: validated here, interpreted by its `execute`, and
      * described by `describe()`. TypeScript checks the kinds of the steps and
      * the names of dependencies and actions; with `strictSteps`, also their
-     * references and values (see `CheckedSteps`).
+     * references and values, and the `return` against the response (see
+     * `CheckedSteps`).
      */
-    readonly steps?: [Strict] extends [true] ? CheckedSteps<Steps, NoInfer<Input>, NoInfer<Context>, NoInfer<Dependencies>> : Steps;
+    readonly steps?: [Strict] extends [true] ? CheckedSteps<Steps, NoInfer<Input>, NoInfer<Context>, NoInfer<Dependencies>, NoInfer<Output>> : Steps;
     /**
      * `true` checks the steps, written inline, at compile time: each reference
      * must name a value in scope (the input, the context, an environment or the
@@ -137,10 +165,20 @@ export interface UseCaseDeclaration<Input extends IBlueprintCollection, Output e
      */
     readonly strictSteps?: Strict;
 }
+/**
+ * A use case, or a decorator of one, is declared with what it cannot use;
+ * `reason` says what.
+ */
 export declare const InvalidUseCaseDeclaration: DeclaredExceptionClass<{
     reason: string;
 }>;
+/** `execute` was called twice on one instance of a use case, which runs only once. */
 export declare const UseCaseAlreadyExecuted: DeclaredExceptionClass<undefined>;
+/**
+ * The overrides given to `execute` name a dependency the use case does not
+ * declare, or give the wrong kind of value for one; or a dependency was called
+ * after `execute` ended.
+ */
 export declare const InvalidUseCaseDependencies: DeclaredExceptionClass<undefined>;
 /** An operation with validated input, dependency functions and a drainable event queue. */
 export declare abstract class AbstractUseCase<Input extends IBlueprintCollection, Output extends IBlueprintCollection, Dependencies extends UseCaseCollection> {
@@ -148,6 +186,14 @@ export declare abstract class AbstractUseCase<Input extends IBlueprintCollection
     constructor(input: BlueprintInput<Input>, ...args: unknown[]);
     /** Default parameter for implementations: `execute(deps = this.dependencies)`. */
     get dependencies(): DependencyFunctions<Dependencies>;
+    /**
+     * Runs the operation and gives its response. `dependencies` replace the
+     * declared ones for this call: a function for a use case, some methods of a
+     * repository, the variables of an environment.
+     *
+     * @throws {@link UseCaseAlreadyExecuted} when this instance already executed.
+     * @throws {@link InvalidUseCaseDependencies} when an override names an undeclared dependency or is of the wrong kind.
+     */
     abstract execute(dependencies?: DependencyOverrides<Dependencies>): Promise<BlueprintValue<Output>>;
     /** Immediately drains collected events; never executes their handlers. */
     pullEvents(): EntityEvent[];
@@ -176,6 +222,11 @@ type UseCaseInstanceContext<Context extends IBlueprintCollection | undefined> =
     /** What the caller supplied with the call, parsed and frozen; `undefined` without a declared context. */
     readonly context: Context extends IBlueprintCollection ? Readonly<BlueprintValue<Context>> : undefined;
 };
+/**
+ * What {@link useCaseOf} gives without `steps`: an abstract class to extend,
+ * implementing an async `execute`. Its constructor takes the input and, when
+ * the use case declares a context, `{ context }`.
+ */
 export type UseCaseConstructor<Input extends IBlueprintCollection, Output extends IBlueprintCollection, Dependencies extends UseCaseCollection, Context extends IBlueprintCollection | undefined = undefined> = (abstract new (input: BlueprintInput<Input>, ...options: OptionsArgs<Context>) => AbstractUseCase<Input, Output, Dependencies> & UseCaseInstanceContext<Context>) & UseCaseStatics<Input, Output, Dependencies, Context>;
 /**
  * What `useCaseOf` gives with `steps`: concrete, its `execute` interprets the
@@ -188,8 +239,32 @@ export type StepsUseCaseConstructor<Input extends IBlueprintCollection, Output e
  * Declares an operation. With `steps` the class is concrete: its `execute`
  * interprets them. Without, it is abstract: extend it and implement an async
  * execute method.
+ *
+ * @throws {@link InvalidUseCaseDeclaration} when the name, the blueprints or the dependencies are missing or of the wrong kind, or a setting is not valid.
+ *
+ * @example
+ * ```ts
+ * import { blueprintOf, useCaseOf } from "@afora/core";
+ *
+ * class Greet extends useCaseOf({
+ * 	name: "Greet",
+ * 	blueprint: blueprintOf((ctx) => ({ name: ctx.text })),
+ * 	response: blueprintOf((ctx) => ({ message: ctx.string })),
+ * }) {
+ * 	override async execute() {
+ * 		return { message: `Hello, ${this.input.name}!` };
+ * 	}
+ * }
+ *
+ * const { message } = await new Greet({ name: "Ana" }).execute();
+ * ```
  */
 export declare function useCaseOf<Input extends IBlueprintCollection, Output extends IBlueprintCollection, const Dependencies extends UseCaseCollection = Record<never, never>, Context extends IBlueprintCollection | undefined = undefined, const Steps extends readonly UseCaseStep<NoInfer<Dependencies>>[] | undefined = undefined, Strict extends boolean = false>(settings: UseCaseDeclaration<Input, Output, Dependencies, Context, Steps, Strict>): [Steps] extends [undefined] ? UseCaseConstructor<Input, Output, Dependencies, Context> : StepsUseCaseConstructor<Input, Output, Dependencies, Context>;
+/**
+ * Whether `value` is a use case class made by {@link useCaseOf}, abstract or
+ * concrete, or a subclass of one.
+ */
 export declare function isUseCaseClass(value: unknown): value is AnyUseCaseClass;
+/** Whether `value` is an instance of a use case class. */
 export declare function isUseCase(value: unknown): value is AbstractUseCase<IBlueprintCollection, IBlueprintCollection, UseCaseCollection>;
 export {};