@afora/core 0.0.8 → 0.0.11

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

@@ -0,0 +1,39 @@
+import type { JsonValue } from "../../json.js";
+/**
+ * Who is calling: what an authenticator made of the credentials of a request.
+ * `subject` identifies the caller (a user id), `scopes` is what it may do.
+ */
+export interface Principal {
+    readonly subject: string;
+    readonly scopes: readonly string[];
+    /** Anything else the credentials say (a tenant, a role). */
+    readonly claims?: Readonly<Record<string, JsonValue>>;
+}
+/** A value of the principal: its subject, its scopes or one of its claims. */
+type PrincipalValue = "subject" | "scopes" | `claims.${string}`;
+/**
+ * Who may call a use case, as data: declared with the `access` setting of
+ * `useCaseOf` or with `@Access`, and enforced by every output before the use
+ * case runs. `{ public: true }` lets anyone in. Any other declaration needs
+ * an authenticated caller (`{}` asks for nothing more), and may add:
+ *
+ * - `scopes`: the caller has all of them;
+ * - `owner`: the input key `input` equals the subject of the caller, or its
+ *   claim `claim`;
+ * - `context`: keys of the context of the call filled from the caller, over
+ *   whatever the request sent.
+ */
+export type AccessDeclaration = {
+    readonly public: true;
+} | {
+    readonly public?: false;
+    readonly scopes?: readonly string[];
+    readonly owner?: {
+        readonly input: string;
+        readonly claim?: string;
+    };
+    readonly context?: {
+        readonly [contextKey: string]: PrincipalValue;
+    };
+};
+export {};

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

@@ -0,0 +1,86 @@
+/** An HTTP method an operation can be routed to. */
+export type RouteMethod = "get" | "post" | "put" | "patch" | "delete";
+/** The status of a successful call of a route; `204` has no body. */
+export type RouteSuccessStatus = 200 | 201 | 202 | 204;
+/** How a cookie a route sets is sent. The defaults are the safe ones for a session. */
+export interface RouteCookie {
+    /** The name of the cookie. */
+    readonly name: string;
+    /**
+     * Not readable by scripts of the page.
+     *
+     * @default true
+     */
+    readonly httpOnly?: boolean;
+    /**
+     * Sent over HTTPS only.
+     *
+     * @default true
+     */
+    readonly secure?: boolean;
+    /**
+     * The `SameSite` attribute of the cookie.
+     *
+     * @default "lax"
+     */
+    readonly sameSite?: "strict" | "lax" | "none";
+    /**
+     * The `Path` attribute of the cookie.
+     *
+     * @default "/"
+     */
+    readonly path?: string;
+    readonly domain?: string;
+    /** The seconds the cookie lives; without it, until the browser closes. */
+    readonly maxAge?: number;
+}
+/**
+ * Where a use case is served over HTTP, as data: declared with the `route`
+ * setting of `useCaseOf` or with `@Route`, and read by the sinks that serve
+ * or document HTTP. The blueprint of the use case stays the only description
+ * of its input: a route only says where each key comes from.
+ */
+export interface RouteDeclaration {
+    readonly method: RouteMethod;
+    /**
+     * The path, after the `basePath` of the sink, e.g. `"/posts/{slug}"`. A
+     * `{name}` segment fills the scalar input key `name`. Without it, the path
+     * is the default of the sink: `/{kebab(command)}/{kebab(operation)}`.
+     */
+    readonly path?: string;
+    /**
+     * The status of a successful response.
+     *
+     * @default 200
+     */
+    readonly status?: RouteSuccessStatus;
+    /**
+     * Scalar input keys read from the query string. A `get` or `delete` route
+     * reads from the query every key that has no other place, so this is for
+     * the routes with a body.
+     */
+    readonly query?: readonly string[];
+    /** Scalar input keys read from request headers: `{ locale: "accept-language" }`. */
+    readonly headers?: {
+        readonly [inputKey: string]: string;
+    };
+    /** Scalar input keys read from cookies: `{ session: "sid" }`. */
+    readonly cookie?: {
+        readonly [inputKey: string]: string;
+    };
+    /**
+     * Scalar keys of the response sent as cookies instead of in the body:
+     * `{ token: { name: "sid" } }`. An empty text removes the cookie, and an
+     * absent value sets none.
+     */
+    readonly setCookie?: {
+        readonly [responseKey: string]: RouteCookie;
+    };
+}
+/**
+ * What the `route` setting and `@Route` take: a {@link RouteDeclaration}
+ * whose method may be written in upper case.
+ */
+export interface RouteSettings extends Omit<RouteDeclaration, "method"> {
+    readonly method: RouteMethod | Uppercase<RouteMethod>;
+}

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

@@ -5,7 +5,10 @@ import { type DeclaredExceptionClass } from "../exception/exception.js";
 import { type ILogger, type LoggerDeclaration } from "../logger/logger.js";
 import type { AnyRepository } from "../repository/types/repository.interface.js";
 import { Kind } from "../symbols/kind.js";
+import type { CheckedSteps } from "./steps/types/check.interface.js";
 import type { UseCaseStep } from "./steps/types/steps.interface.js";
+import type { AccessDeclaration } from "./types/access.interface.js";
+import type { RouteDeclaration, RouteSettings } from "./types/route.interface.js";
 /** A concrete UseCase declaration, usable as a dependency. */
 export interface AnyUseCaseClass {
     readonly [Kind]: "use-case";
@@ -18,6 +21,10 @@ export interface AnyUseCaseClass {
     readonly tags: readonly string[];
     readonly deprecated: boolean;
     readonly errors: readonly AnyExceptionClass[];
+    /** Where it is served over HTTP, if it says so (see `RouteDeclaration`). */
+    readonly route: RouteDeclaration | undefined;
+    /** Who may call it, if it says so (see `AccessDeclaration`). */
+    readonly access: AccessDeclaration | undefined;
     new (input: any, ...options: any[]): {
         execute(): Promise<unknown>;
         pullEvents(): EntityEvent[];
@@ -30,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 {
@@ -59,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]>;
 };
@@ -69,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>;
@@ -81,6 +115,22 @@ export interface UseCaseSettings<Input extends IBlueprintCollection, Output exte
     readonly deprecated?: boolean;
     /** The exceptions (made by `exceptionOf`) a caller should expect; documentation only. */
     readonly errors?: readonly AnyExceptionClass[];
+    /**
+     * Where the use case is served over HTTP: method, path and where each
+     * input key is read from (see `RouteDeclaration`). A decorated class says
+     * the same with `@Route`. Read by the sinks that serve or document HTTP;
+     * the `route` option of a sink overrides the method, path and status.
+     */
+    readonly route?: RouteSettings;
+    /**
+     * Who may call the use case through an output: anyone (`{ public: true }`),
+     * or an authenticated caller with these `scopes`, that is the `owner`
+     * named by an input key, and whose values fill the `context` (see
+     * `AccessDeclaration`). A decorated class says the same with `@Access`.
+     * Enforced before the use case runs; a call made in process, with
+     * `execute` or `command.run`, is trusted and not checked.
+     */
+    readonly access?: AccessDeclaration;
 }
 /** `UseCaseSettings` with the `steps` that are its `execute`. */
 export interface UseCaseStepsSettings<Input extends IBlueprintCollection, Output extends IBlueprintCollection, Dependencies extends UseCaseCollection, Context extends IBlueprintCollection | undefined = undefined> extends UseCaseSettings<Input, Output, Dependencies, Context> {
@@ -89,11 +139,46 @@ export interface UseCaseStepsSettings<Input extends IBlueprintCollection, Output
      * interpreted by its `execute`, and described by `describe()`.
      */
     readonly steps: readonly UseCaseStep<NoInfer<Dependencies>>[];
+    /** Checks the references and values of the steps at compile time (see `CheckedSteps`). */
+    readonly strictSteps?: boolean;
 }
+/**
+ * What `useCaseOf` takes: `UseCaseSettings`, and the `steps` that make the
+ * class concrete, if any.
+ */
+export interface UseCaseDeclaration<Input extends IBlueprintCollection, Output extends IBlueprintCollection, Dependencies extends UseCaseCollection, Context extends IBlueprintCollection | undefined = undefined, Steps extends readonly UseCaseStep<Dependencies>[] | undefined = undefined, Strict extends boolean = false> extends UseCaseSettings<Input, Output, Dependencies, Context> {
+    /**
+     * What the use case does, as data (see `UseCaseStep`), which makes the
+     * class concrete: validated here, interpreted by its `execute`, and
+     * described by `describe()`. TypeScript checks the kinds of the steps and
+     * the names of dependencies and actions; with `strictSteps`, also their
+     * references and values, and the `return` against the response (see
+     * `CheckedSteps`).
+     */
+    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
+     * result of an earlier step, at any depth), and the `args`, `values`,
+     * `value` and `input` of a step must fit what it calls or builds. It costs
+     * the editor more than the default checks. Without effect at run time.
+     */
+    readonly strictSteps?: Strict;
+}
+/**
+ * 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> {
@@ -101,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[];
@@ -119,12 +212,21 @@ type UseCaseStatics<Input extends IBlueprintCollection, Output extends IBlueprin
     readonly deprecated: boolean;
     /** The exceptions a caller should expect. */
     readonly errors: readonly AnyExceptionClass[];
+    /** Where it is served over HTTP, from the `route` setting or `@Route`. */
+    readonly route: RouteDeclaration | undefined;
+    /** Who may call it, from the `access` setting or `@Access`. */
+    readonly access: AccessDeclaration | undefined;
 };
 /** What a use case instance carries beyond `AbstractUseCase`. */
 type UseCaseInstanceContext<Context extends IBlueprintCollection | undefined> = {
     /** 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
@@ -137,9 +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 useCaseOf<Input extends IBlueprintCollection, Output extends IBlueprintCollection, const Dependencies extends UseCaseCollection = Record<never, never>, Context extends IBlueprintCollection | undefined = undefined>(settings: UseCaseStepsSettings<Input, Output, Dependencies, Context>): StepsUseCaseConstructor<Input, Output, Dependencies, Context>;
-export declare function useCaseOf<Input extends IBlueprintCollection, Output extends IBlueprintCollection, const Dependencies extends UseCaseCollection = Record<never, never>, Context extends IBlueprintCollection | undefined = undefined>(settings: UseCaseSettings<Input, Output, Dependencies, Context>): UseCaseConstructor<Input, Output, Dependencies, Context>;
 export declare function 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 {};