@afora/core 0.0.9 → 0.0.11

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

@@ -1,5 +1,6 @@
 import type { ILogger } from "../logger/logger.js";
 import type { IRepositoryProvider } from "../repository/types/repository.interface.js";
+import type { ITracer, ITraceSpan } from "../tracing/tracing.js";
 /**
  * What a call carries to its repositories, internal: the providers that
  * replace the ones the repositories declared (e.g. one inside a transaction).
@@ -14,6 +15,10 @@ export interface ExecutionScope {
     readonly environments?: ReadonlyMap<object, Readonly<Record<string, unknown>>>;
     /** The logger of the application running the call, given by its command. */
     readonly logger?: ILogger;
+    /** The tracer of the application running the call, given by its command. */
+    readonly tracer?: ITracer;
+    /** The span of the caller (a command, a use case): the parent of the next. */
+    readonly span?: ITraceSpan;
 }
 /**
  * Key of the constructor options (and of the repository view) that carries

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

@@ -0,0 +1,4 @@
+export const ScopeKey = Symbol("afora.use-case.scope");
+export function scopedProvider(scope, provider) {
+  return scope?.providers.get(provider) ?? provider;
+}

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

@@ -1,3 +1,4 @@
+import type { FieldsDescription } from "../../application/types/application.interface.js";
 import type { StepErrorDescription, UseCaseStepDescription } from "./types/steps.interface.js";
 /** How a class of a step is named in the descriptor. */
 export interface StepNames {
@@ -5,9 +6,12 @@ export interface StepNames {
     readonly record: (Class: unknown) => string;
     /** The registered name of an exception, or `{ core }` for one the package exports. */
     readonly error: (Class: unknown) => StepErrorDescription;
+    /** The fields of the `params` blueprint of a `run`. */
+    readonly params: (blueprint: unknown) => FieldsDescription;
 }
 /**
  * The steps as `describe()` gives them: the same data, with the classes of
- * `build` and `ensure.error` by name and the function of `run` as `opaque`.
+ * `build` and `ensure.error` by name, the function of `run` as `opaque` and
+ * its `params` by their fields.
  */
 export declare function describeSteps(steps: readonly Readonly<Record<string, unknown>>[], names: StepNames): UseCaseStepDescription[];

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

@@ -0,0 +1,24 @@
+import { isPlain } from "./references.js";
+function cloneData(value) {
+  if (Array.isArray(value))
+    return value.map(cloneData);
+  if (isPlain(value)) {
+    return Object.fromEntries(Object.entries(value).map(([key, item]) => [key, cloneData(item)]));
+  }
+  return value;
+}
+export function describeSteps(steps, names) {
+  return steps.map((step) => {
+    const copy = cloneData({ ...step });
+    if (Object.hasOwn(step, "build"))
+      copy.build = names.record(step.build);
+    if (Object.hasOwn(step, "ensure"))
+      copy.error = names.error(step.error);
+    if (Object.hasOwn(step, "run")) {
+      copy.fn = { kind: "opaque" };
+      if (step.params !== undefined)
+        copy.params = names.params(step.params);
+    }
+    return copy;
+  });
+}

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

@@ -0,0 +1,105 @@
+export const RESERVED_NAMES = [
+  "input",
+  "context",
+  "env",
+  "literal"
+];
+const IDENTIFIER = /^[A-Za-z_][A-Za-z0-9_]*$/;
+const SEGMENT = /^(?:[A-Za-z_][A-Za-z0-9_]*|0|[1-9][0-9]*)$/;
+const BLOCKED = new Set(["__proto__", "constructor", "prototype"]);
+export function isStepName(value) {
+  return typeof value === "string" && IDENTIFIER.test(value);
+}
+const parsed = new Map;
+export function parseReference(text) {
+  const cached = parsed.get(text);
+  if (cached !== undefined)
+    return cached ?? undefined;
+  let result = null;
+  if (text.startsWith("$")) {
+    const [root, ...path] = text.slice(1).split(".");
+    if (root !== undefined && IDENTIFIER.test(root) && path.every((segment) => SEGMENT.test(segment))) {
+      result = Object.freeze({ root, path: Object.freeze(path) });
+    }
+  }
+  if (parsed.size < 4096)
+    parsed.set(text, result);
+  return result ?? undefined;
+}
+export function isPlain(value) {
+  if (typeof value !== "object" || value === null)
+    return false;
+  const prototype = Object.getPrototypeOf(value);
+  return prototype === Object.prototype || prototype === null;
+}
+function isLiteralEscape(value) {
+  return isPlain(value) && Object.keys(value).length === 1 && Object.hasOwn(value, "literal");
+}
+export function walkValue(value, onReference, onIssue) {
+  if (typeof value === "string") {
+    if (!value.startsWith("$"))
+      return;
+    const reference = parseReference(value);
+    if (!reference)
+      onIssue("invalid_reference", value);
+    else
+      onReference(reference, value);
+    return;
+  }
+  if (value === null || typeof value === "number" || typeof value === "boolean") {
+    return;
+  }
+  if (isLiteralEscape(value)) {
+    return;
+  }
+  if (Array.isArray(value)) {
+    for (const item of value)
+      walkValue(item, onReference, onIssue);
+    return;
+  }
+  if (isPlain(value)) {
+    for (const item of Object.values(value)) {
+      walkValue(item, onReference, onIssue);
+    }
+    return;
+  }
+  onIssue("invalid_value", String(value));
+}
+export function followPath(from, path) {
+  let current = from;
+  for (const segment of path) {
+    if (typeof current !== "object" && typeof current !== "function" || current === null || BLOCKED.has(segment)) {
+      return;
+    }
+    current = current[segment];
+  }
+  return current;
+}
+export function resolveValue(value, lookup) {
+  if (typeof value === "string") {
+    if (!value.startsWith("$"))
+      return value;
+    const reference = parseReference(value);
+    return reference ? lookup(reference) : undefined;
+  }
+  if (isLiteralEscape(value))
+    return value.literal;
+  if (Array.isArray(value))
+    return value.map((item) => resolveValue(item, lookup));
+  if (isPlain(value)) {
+    return Object.fromEntries(Object.entries(value).map(([key, item]) => [
+      key,
+      resolveValue(item, lookup)
+    ]));
+  }
+  return value;
+}
+export function freezeData(value) {
+  if (Array.isArray(value)) {
+    return Object.freeze(value.map(freezeData));
+  }
+  if (isPlain(value)) {
+    return Object.freeze(Object.fromEntries(Object.entries(value).map(([key, item]) => [key, freezeData(item)])));
+  }
+  return value;
+}

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

@@ -0,0 +1,139 @@
+import { isRecordClass } from "../../blueprint/record-field.js";
+import { sameValue } from "../../repository/query.js";
+import { InvalidUseCaseStep } from "../exceptions.js";
+import { followPath, resolveValue } from "./references.js";
+const FORBIDDEN_METHODS = new Set([
+  "set",
+  "emit",
+  "constructor",
+  "__proto__",
+  "hasOwnProperty",
+  "isPrototypeOf",
+  "propertyIsEnumerable",
+  "toLocaleString",
+  "valueOf",
+  "__defineGetter__",
+  "__defineSetter__",
+  "__lookupGetter__",
+  "__lookupSetter__"
+]);
+function isRecordInstance(value) {
+  return typeof value === "object" && value !== null && isRecordClass(value.constructor);
+}
+function parsedArgs(params, args, invalid) {
+  const keys = Object.keys(params.properties);
+  if (args.length !== keys.length) {
+    invalid(`run.params declares ${keys.length} parameter(s), args gave ${args.length}.`, "invalid_args");
+  }
+  const result = params.safeParse(Object.fromEntries(keys.map((key, at) => [key, args[at]])));
+  if (result.issues) {
+    const [first] = result.issues;
+    const more = result.issues.length > 1 ? ` (and ${result.issues.length - 1} more)` : "";
+    return invalid(`the argument "${first?.path.join(".")}" ${first?.message}${more}.`, "invalid_args", result.issues);
+  }
+  const value = result.value;
+  return keys.map((key) => value[key]);
+}
+export async function executeSteps(dependencies = {}) {
+  const { useCaseName, steps = [] } = this.constructor;
+  const named = new Map;
+  const lookup = ({ root, path }) => {
+    if (root === "input")
+      return followPath(this.input, path);
+    if (root === "context")
+      return followPath(this.context, path);
+    if (root === "env")
+      return followPath(dependencies[path[0]], path.slice(1));
+    return followPath(named.get(root), path);
+  };
+  const value = (raw) => resolveValue(raw, lookup);
+  for (const [index, step] of steps.entries()) {
+    const invalid = (reason, code = "invalid_target", issues) => {
+      throw new InvalidUseCaseStep({
+        source: useCaseName,
+        details: { index, reason, code, ...issues ? { issues } : {} }
+      });
+    };
+    const list = (raw) => {
+      if (raw === undefined)
+        return [];
+      const resolved = value(raw);
+      if (!Array.isArray(resolved))
+        invalid("args must resolve to a list.");
+      return resolved;
+    };
+    const bind = (result) => {
+      if (typeof step.as === "string")
+        named.set(step.as, result);
+    };
+    const target = (field) => {
+      const resolved = value(step[field]);
+      if (!isRecordInstance(resolved)) {
+        invalid(`${field} must reference a record or entity.`);
+      }
+      return resolved;
+    };
+    if (Object.hasOwn(step, "return"))
+      return value(step.return);
+    if (Object.hasOwn(step, "find")) {
+      const [repository, action] = step.find.split(".");
+      const methods = dependencies[repository];
+      bind(await methods[action].call(methods, ...list(step.args)));
+    } else if (Object.hasOwn(step, "ensure")) {
+      const subject = value(step.value);
+      const passed = {
+        exists: subject !== undefined && subject !== null,
+        absent: subject === undefined || subject === null,
+        equals: sameValue(subject, value(step.other)),
+        notEquals: !sameValue(subject, value(step.other)),
+        true: subject === true,
+        false: subject === false
+      }[step.ensure];
+      if (!passed) {
+        const Thrown = step.error;
+        throw new Thrown({
+          source: useCaseName,
+          ...step.details === undefined ? {} : { details: value(step.details) }
+        });
+      }
+    } else if (Object.hasOwn(step, "build")) {
+      const Built = step.build;
+      bind(new Built(value(step.values)));
+    } else if (Object.hasOwn(step, "change")) {
+      const record = target("change");
+      const namespace = record.change;
+      const key = step.key;
+      if (typeof namespace !== "object" || namespace === null || typeof namespace[key] !== "function") {
+        invalid(`"${key}" is not a change key of the record.`);
+      }
+      const changed = value(step.value);
+      if (step.ifPresent !== true || changed !== undefined) {
+        await namespace[key]?.(changed);
+      }
+      bind(record);
+    } else if (Object.hasOwn(step, "invoke")) {
+      const record = target("invoke");
+      const method = step.method;
+      if (FORBIDDEN_METHODS.has(method) || typeof record[method] !== "function") {
+        invalid(`"${method}" is not a public method of the record.`);
+      }
+      bind(await record[method].apply(record, list(step.args)));
+    } else if (Object.hasOwn(step, "call")) {
+      const child = dependencies[step.call];
+      bind(await child(value(step.input)));
+    } else if (Object.hasOwn(step, "run")) {
+      const fn = step.fn;
+      const args = list(step.args);
+      bind(await fn(...step.params === undefined ? args : parsedArgs(step.params, args, invalid), { context: this.context, dependencies }));
+    } else {
+      const action = ["create", "update", "delete", "restore"].find((kind) => Object.hasOwn(step, kind));
+      const methods = dependencies[step[action]];
+      bind(await methods[action].call(methods, value(step.value)));
+    }
+  }
+  return;
+}
+export function interpretedStepsOf(UseCase) {
+  const Declared = UseCase;
+  return Declared.prototype.execute === executeSteps ? Declared.steps : undefined;
+}

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

@@ -13,7 +13,7 @@
  * the steps are not distributive (`[Step] extends [...]`): TypeScript then
  * never evaluates them with the constraint of the steps while it infers them.
  */
-import type { BlueprintValue, IBlueprint, IBlueprintCollection } from "../../../blueprint/types/blueprint.interface.js";
+import type { BlueprintInput, BlueprintValue, IBlueprint, IBlueprintCollection } from "../../../blueprint/types/blueprint.interface.js";
 import type { AnyEnvironment, EnvironmentValue } from "../../../environment/environment.js";
 import type { Meta } from "../../../symbols/meta.js";
 import type { AnyUseCaseClass, UseCaseInput, UseCaseResponse } from "../../use-case.js";
@@ -64,10 +64,21 @@ type PathsFrom<Value, Path extends string, Expected, Depth extends unknown[]> =
 export type StepReferencesOf<Scope, Expected = unknown> = Scope extends unknown ? {
     [Root in keyof Scope & string]-?: Root extends "env" ? Below<Scope[Root], `$${Root}`, Expected, [0]> : PathsFrom<Scope[Root], `$${Root}`, Expected, []>;
 }[keyof Scope & string] : never;
-/** `Reference` when it names a value of `Scope` that fits `Expected`; else the references that would. */
+/**
+ * The references of `Scope` that fit `Expected`, or `Expected` itself when
+ * none does, so that the error names the type that is taken rather than `never`.
+ */
+type Suggested<Expected, Scope> = [StepReferencesOf<Scope, Expected>] extends [
+    infer References
+] ? [References] extends [never] ? Expected : References : never;
+/**
+ * `Reference` when it names a value of `Scope` that fits `Expected`; else the
+ * references that would, and, when it only fails because it may be
+ * `undefined`, a hint to ensure it exists first.
+ */
 type CheckReference<Reference, Expected, Scope> = [
     StepReferenceType<Scope, Reference>
-] extends [infer Type] ? [Type] extends [never] ? StepReferencesOf<Scope, Expected> : [Type] extends [Expected] ? Reference : StepReferencesOf<Scope, Expected> : never;
+] extends [infer Type] ? [Type] extends [never] ? Suggested<Expected, Scope> : [Type] extends [Expected] ? Reference : [NonNullable<Type>] extends [Expected] ? Suggested<Expected, Scope> | `${Reference & string} may be undefined: ensure it exists first` : Suggested<Expected, Scope> : never;
 type Primitive = string | number | boolean | null;
 /** The type of the key `Key` in what `Expected` takes, over each object of it. */
 type ExpectedAt<Expected, Key> = Expected extends object ? Key extends keyof Expected ? Expected[Key] : never : never;
@@ -158,7 +169,7 @@ type ChangeStep<Step, Record, Scope> = [Record] extends [never] ? ValueStep<Step
     Record
 ] : [Step, Record];
 /** `[what Step must be, what it gives to its as]`, read against `Scope`. */
-type CheckStep<Step, Dependencies, Scope> = [Step] extends [
+type CheckStep<Step, Dependencies, Scope, Response> = [Step] extends [
     {
         readonly find: infer Target;
     }
@@ -183,7 +194,11 @@ type CheckStep<Step, Dependencies, Scope> = [Step] extends [
     readonly delete: infer Repository;
 }] ? WriteStep<Step, MemberOf<Dependencies, Repository, "delete">, Scope> : [Step] extends [{
     readonly restore: infer Repository;
-}] ? WriteStep<Step, MemberOf<Dependencies, Repository, "restore">, Scope> : ValueStep<Step, "value" | "other" | "details" | "return", unknown, unknown, Scope>;
+}] ? WriteStep<Step, MemberOf<Dependencies, Repository, "restore">, Scope> : [Step] extends [{
+    readonly return: unknown;
+}] ? ValueStep<Step, "return", ResponseInput<Response>, unknown, Scope> : ValueStep<Step, "value" | "other" | "details", unknown, unknown, Scope>;
+/** What the response blueprint `Response` takes, or anything when it is not known. */
+type ResponseInput<Response> = [Response] extends [IBlueprintCollection] ? BlueprintInput<Response> : unknown;
 type WriteStep<Step, Method, Scope> = ValueStep<Step, "value", FirstParameter<Method>, ResultOf<Method>, Scope>;
 /** The scope after `Step`: its result bound to its `as`, or a value it ensures exists. */
 type ScopeAfter<Step, Result, Scope> = [Step] extends [
@@ -201,14 +216,18 @@ type ScopeAfter<Step, Result, Scope> = [Step] extends [
     readonly [Key in Name]: NonNullable<Scope[Name]>;
 } : Scope : Scope;
 /** The steps folded in order, each checked against the scope the earlier ones built. */
-type CheckSteps<Steps extends readonly unknown[], Dependencies, Scope, Checked extends readonly unknown[] = []> = [Steps] extends [readonly [infer Step, ...infer Rest]] ? CheckStep<Step, Dependencies, Scope> extends [infer Current, infer Result] ? CheckSteps<Rest, Dependencies, ScopeAfter<Step, Result, Scope>, [
+type CheckSteps<Steps extends readonly unknown[], Dependencies, Scope, Response, Checked extends readonly unknown[] = []> = [Steps] extends [readonly [infer Step, ...infer Rest]] ? CheckStep<Step, Dependencies, Scope, Response> extends [
+    infer Current,
+    infer Result
+] ? CheckSteps<Rest, Dependencies, ScopeAfter<Step, Result, Scope>, Response, [
     ...Checked,
     Current
 ]> : never : readonly [...Checked];
 /**
  * What `useCaseOf` takes as `steps`: the steps, inferred as a tuple, each
- * checked against the values in scope. Steps that are not a tuple (built at
+ * checked against the values in scope, and the `return` against what the
+ * response blueprint (the collection `Response`) takes. Steps that are not a tuple (built at
  * run time) are checked only when the use case is declared.
  */
-export type CheckedSteps<Steps, Input extends IBlueprintCollection, Context extends IBlueprintCollection | undefined, Dependencies> = [Steps] extends [readonly [unknown, ...unknown[]]] ? CheckSteps<Steps, Dependencies, StepsInitialScope<Input, Context, Dependencies>> : Steps;
+export type CheckedSteps<Steps, Input extends IBlueprintCollection, Context extends IBlueprintCollection | undefined, Dependencies, Response extends IBlueprintCollection | undefined = undefined> = [Steps] extends [readonly [unknown, ...unknown[]]] ? CheckSteps<Steps, Dependencies, StepsInitialScope<Input, Context, Dependencies>, Response> : Steps;
 export {};

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

@@ -1,4 +1,5 @@
-import type { AnyRecordClass } from "../../../blueprint/types/blueprint.interface.js";
+import type { FieldsDescription } from "../../../application/types/application.interface.js";
+import type { AnyBlueprint, AnyRecordClass } from "../../../blueprint/types/blueprint.interface.js";
 import type { AnyRepository } from "../../../repository/types/repository.interface.js";
 import type { AnyExceptionClass, AnyUseCaseClass, UseCaseCollection } from "../../use-case.js";
 /** A reference to a value: `$input.email`, `$context.userId`, `$env.mail`, `$saved.tags.0`. */
@@ -103,6 +104,11 @@ export type UseCaseStep<Dependencies extends UseCaseCollection = UseCaseCollecti
     readonly run: string;
     readonly fn: (...args: any[]) => unknown;
     readonly args?: StepArgs;
+    /**
+     * Checks the `args` at execution: each against the key of the blueprint
+     * at its position; `fn` gets the values as the keys handled them.
+     */
+    readonly params?: AnyBlueprint;
     readonly as?: string;
 } | {
     readonly return: StepValue;
@@ -163,6 +169,7 @@ export type UseCaseStepDescription = {
         readonly kind: "opaque";
     };
     readonly args?: StepArgs;
+    readonly params?: FieldsDescription;
     readonly as?: string;
 } | {
     readonly return: StepValue;