@afora/core 0.0.9 → 0.0.12

package/dist/core/output/output.js

@@ -0,0 +1,192 @@
+import { isCommand } from "../command/command.js";
+import { Kind } from "../symbols/kind.js";
+import { accessGuardOf } from "./access.js";
+import { DuplicateOperation, InvalidOutputStage } from "./exceptions.js";
+import { isStage } from "./stage.js";
+function isApplicationLike(value) {
+  return typeof value === "object" && value !== null && value[Kind] === "application";
+}
+function invalid(source, reason) {
+  throw new InvalidOutputStage({ source, details: { reason } });
+}
+const PATCHABLE = ["meta", "tags", "description", "deprecated", "invoke"];
+export function operationOf(operation, patch) {
+  const source = operation?.id ?? "operationOf";
+  if (operation?.kind !== "operation" || operation.version !== 1) {
+    invalid(source, "Expected an operation descriptor.");
+  }
+  if (typeof patch !== "object" || patch === null || Array.isArray(patch)) {
+    invalid(source, "Expected the patch to be an object.");
+  }
+  for (const key of Reflect.ownKeys(patch)) {
+    if (typeof key !== "string" || !PATCHABLE.includes(key)) {
+      invalid(source, `"${String(key)}" cannot be patched; only ${PATCHABLE.join(", ")} can.`);
+    }
+  }
+  const { meta, tags, description, deprecated, invoke } = patch;
+  if ("meta" in patch && (typeof meta !== "object" || meta === null || Array.isArray(meta))) {
+    invalid(source, "Expected meta to be an object.");
+  }
+  if ("tags" in patch && (!Array.isArray(tags) || tags.some((tag) => typeof tag !== "string"))) {
+    invalid(source, "Expected tags to be a list of strings.");
+  }
+  if ("description" in patch && description !== undefined && typeof description !== "string") {
+    invalid(source, "Expected description to be a string.");
+  }
+  if ("deprecated" in patch && typeof deprecated !== "boolean") {
+    invalid(source, "Expected deprecated to be a boolean.");
+  }
+  if ("invoke" in patch && typeof invoke !== "function") {
+    invalid(source, "Expected invoke to be a function.");
+  }
+  return Object.freeze({
+    ...operation,
+    ..."meta" in patch ? { meta: Object.freeze({ ...meta }) } : {},
+    ..."tags" in patch ? { tags: Object.freeze([...tags ?? []]) } : {},
+    ..."description" in patch ? { description } : {},
+    ..."deprecated" in patch ? { deprecated } : {},
+    ..."invoke" in patch ? { invoke } : {}
+  });
+}
+function operationsOfCommand(command) {
+  return command.operations.map((name) => {
+    const UseCase = command.useCases[name];
+    const context = command.context ?? UseCase.context;
+    const description = UseCase.description ?? command.description;
+    const id = `${command.commandName}.${name}`;
+    const run = command.run;
+    const guard = UseCase.access === undefined ? undefined : accessGuardOf(id, UseCase.access, context);
+    return Object.freeze({
+      kind: "operation",
+      version: 1,
+      id,
+      command: command.commandName,
+      name,
+      useCase: UseCase.useCaseName,
+      ...description === undefined ? {} : { description },
+      tags: Object.freeze([
+        ...new Set([...command.tags, ...UseCase.tags])
+      ]),
+      deprecated: UseCase.deprecated,
+      input: UseCase.blueprint,
+      response: UseCase.response,
+      ...context ? { context } : {},
+      errors: UseCase.errors,
+      ...UseCase.route === undefined ? {} : { route: UseCase.route },
+      ...UseCase.access === undefined ? {} : { access: UseCase.access },
+      meta: Object.freeze({}),
+      invoke: guard ? async (input, options) => run(name, input, guard(input, options)) : (input, options) => run(name, input, options && "principal" in options ? { context: options.context } : options)
+    });
+  });
+}
+function statusesOf(name, statuses) {
+  if (statuses === undefined)
+    return Object.freeze({});
+  if (typeof statuses !== "object" || statuses === null || Array.isArray(statuses)) {
+    invalid(name, "Expected statuses to be a map of exception names to statuses.");
+  }
+  for (const [exception, status] of Object.entries(statuses)) {
+    if (!exception || typeof status !== "number" || !Number.isInteger(status) || status < 400 || status > 599) {
+      invalid(name, `Expected the status of "${exception}" to be an integer between 400 and 599.`);
+    }
+  }
+  return Object.freeze({ ...statuses });
+}
+function checkPipe(name, pipe) {
+  if (!Array.isArray(pipe))
+    invalid(name, "Expected pipe to be a list of stages.");
+  const stages = pipe;
+  stages.forEach((stage, index) => {
+    if (!isStage(stage)) {
+      invalid(name, `Expected pipe[${index}] to be a transform or sink stage.`);
+    }
+    if (stage.kind === "sink" && index !== stages.length - 1) {
+      invalid(name, `The sink at pipe[${index}] must be the last stage.`);
+    }
+  });
+  return Object.freeze([...stages]);
+}
+function transformed(name, operations, transforms, context) {
+  let current = operations;
+  for (const stage of transforms) {
+    if (stage.kind !== "transform")
+      continue;
+    const next = [];
+    for (const operation of current) {
+      const result = stage.apply(operation, context);
+      if (result === null)
+        continue;
+      if (typeof result !== "object" || result?.kind !== "operation" || result.id !== operation.id) {
+        invalid(name, `A transform must return the operation "${operation.id}" or null.`);
+      }
+      next.push(result);
+    }
+    current = next;
+  }
+  return Object.freeze([...current]);
+}
+function make(name, commands, operations, stages, statuses) {
+  const context = Object.freeze({
+    output: Object.freeze({ name, statuses })
+  });
+  let built;
+  const output = {
+    [Kind]: "output",
+    outputName: name,
+    commands,
+    operations,
+    stages,
+    statuses,
+    build() {
+      if (built)
+        return built.value;
+      const sink = stages.at(-1);
+      if (sink?.kind !== "sink") {
+        invalid(name || "output", "The pipe has no sink to build.");
+      }
+      built = { value: sink.build(operations, context) };
+      return built.value;
+    },
+    pipe(...more) {
+      const next = checkPipe(name || "output", more);
+      const last = next.at(-1);
+      if (stages.at(-1)?.kind === "sink") {
+        invalid(name || "output", "Cannot add stages after the sink.");
+      }
+      const ops = transformed(name, operations, next, context);
+      if (last?.kind === "sink") {
+        return last.build(ops, context);
+      }
+      return make("", commands, ops, Object.freeze([...stages, ...next]), statuses);
+    }
+  };
+  return Object.freeze(output);
+}
+export function outputOf(settings) {
+  const { name, commands } = settings ?? {};
+  if (typeof name !== "string" || !name.trim()) {
+    invalid("outputOf", "Expected name to be a non-empty string.");
+  }
+  const sources = Array.isArray(commands) ? commands : [commands];
+  if (!Array.isArray(commands) && isCommand(commands) || sources.some((entry) => !isCommand(entry) && !isApplicationLike(entry))) {
+    invalid(name, "Expected commands to be a list of commands made by commandOf or applications.");
+  }
+  const flat = [
+    ...new Set(sources.flatMap((entry) => isCommand(entry) ? [entry] : Object.values(entry.commands)))
+  ];
+  const statuses = statusesOf(name, settings.statuses);
+  const stages = checkPipe(name, settings.pipe ?? []);
+  const all = flat.flatMap(operationsOfCommand);
+  const ids = new Set;
+  for (const { id } of all) {
+    if (ids.has(id))
+      throw new DuplicateOperation({ source: name, details: { id } });
+    ids.add(id);
+  }
+  const context = { output: { name, statuses } };
+  const operations = transformed(name, all, stages, context);
+  return make(name, Object.freeze(flat), operations, stages, statuses);
+}
+export function isOutput(value) {
+  return typeof value === "object" && value !== null && value[Kind] === "output";
+}

package/dist/core/output/problem.js

@@ -0,0 +1,30 @@
+import { Exception } from "../exception/exception.js";
+import { raisedOf } from "./status.js";
+export const PROBLEM_MEDIA_TYPE = "application/problem+json";
+const INTERNAL = "Internal error.";
+export function problemOf(error, options) {
+  const { status, debug = false } = options;
+  const exception = error instanceof Exception ? error : undefined;
+  const title = exception?.name ?? "UnexpectedError";
+  const message = exception?.message ?? (error instanceof Error ? error.message : String(error));
+  const raised = exception && raisedOf(exception);
+  const rawIssues = raised?.details?.issues;
+  const issues = status === 400 && Array.isArray(rawIssues) ? rawIssues.map((issue) => ({
+    path: [...issue.path],
+    code: issue.code,
+    message: issue.message
+  })) : undefined;
+  return {
+    type: `urn:afora:exception:${title}`,
+    title,
+    status,
+    detail: status >= 500 && !debug ? INTERNAL : message,
+    ...raised ? { layer: raised.layer } : {},
+    ...issues ? { issues } : {},
+    ...debug ? { trace: exception ? exception.toString() : String(error) } : {}
+  };
+}
+export function outputValueOf(value) {
+  const text = JSON.stringify(value);
+  return text === undefined ? undefined : JSON.parse(text);
+}

package/dist/core/output/select.js

@@ -0,0 +1,28 @@
+import { transformOf } from "./stage.js";
+const LISTS = ["tags", "operations", "exclude"];
+export const select = transformOf({
+  name: "select",
+  validate: (options) => {
+    for (const key of Object.keys(options)) {
+      if (!LISTS.includes(key)) {
+        return `select has no option "${key}".`;
+      }
+    }
+    for (const key of LISTS) {
+      const list = options[key];
+      if (list !== undefined && (!Array.isArray(list) || list.some((item) => typeof item !== "string"))) {
+        return `Expected select.${key} to be a list of strings.`;
+      }
+    }
+    return;
+  },
+  apply: (operation, { tags, operations, exclude }) => {
+    if (tags && !tags.some((tag) => operation.tags.includes(tag)))
+      return null;
+    if (operations && !operations.includes(operation.id))
+      return null;
+    if (exclude?.includes(operation.id))
+      return null;
+    return operation;
+  }
+});

package/dist/core/output/stage.js

@@ -0,0 +1,111 @@
+import { frozenJson } from "../json.js";
+import { Kind } from "../symbols/kind.js";
+import { InvalidOutputStage } from "./exceptions.js";
+const descriptions = new WeakMap;
+const factories = new WeakMap;
+const opaque = Object.freeze({ kind: "opaque" });
+function invalid(source, reason) {
+  throw new InvalidOutputStage({ source, details: { reason } });
+}
+function optionsOf(name, given, validate) {
+  const options = frozenJson(given ?? {}, "Stage options", (reason) => invalid(name, reason));
+  if (options === null || typeof options !== "object" || Array.isArray(options)) {
+    invalid(name, "Stage options must be an object.");
+  }
+  const reason = validate?.(options);
+  if (reason !== undefined)
+    invalid(name, reason);
+  return options;
+}
+function checkName(source, name) {
+  if (typeof name !== "string" || !name.trim()) {
+    invalid(source, "Expected the stage name to be a non-empty string.");
+  }
+}
+export function transformOf(settings) {
+  checkName("transformOf", settings?.name);
+  if (typeof settings.apply !== "function") {
+    invalid(settings.name, "Expected apply to be a function.");
+  }
+  const { name, apply, validate } = settings;
+  const factory = (given) => {
+    const options = optionsOf(name, given, validate);
+    const stage = Object.freeze({
+      kind: "transform",
+      name,
+      options,
+      apply: (operation, context) => apply(operation, options, context)
+    });
+    descriptions.set(stage, Object.freeze({
+      kind: "transform",
+      name,
+      options
+    }));
+    return stage;
+  };
+  factories.set(factory, { kind: "transform", name });
+  return factory;
+}
+export function sinkOf(settings) {
+  checkName("sinkOf", settings?.name);
+  if (typeof settings.build !== "function") {
+    invalid(settings.name, "Expected build to be a function.");
+  }
+  const { name, build, validate } = settings;
+  const factory = (given, hooks) => {
+    const options = optionsOf(name, given, validate);
+    if (hooks !== undefined && (typeof hooks !== "object" || hooks === null || Array.isArray(hooks))) {
+      invalid(name, "Stage hooks must be an object.");
+    }
+    const stage = Object.freeze({
+      kind: "sink",
+      name,
+      options,
+      build: (operations, context) => build(operations, options, context, hooks)
+    });
+    descriptions.set(stage, Object.freeze({
+      kind: "sink",
+      name,
+      options
+    }));
+    return stage;
+  };
+  factories.set(factory, { kind: "sink", name });
+  return factory;
+}
+export function stageDescriptionOf(stage) {
+  return descriptions.get(stage) ?? opaque;
+}
+export function stageKindOf(factory) {
+  return factories.get(factory)?.kind;
+}
+export function isStage(value) {
+  if (typeof value !== "object" || value === null)
+    return false;
+  const { kind, apply, build } = value;
+  return kind === "transform" && typeof apply === "function" || kind === "sink" && typeof build === "function";
+}
+export function stageCatalogOf(...stages) {
+  const byName = {};
+  for (const factory of stages) {
+    const known = factories.get(factory);
+    if (!known) {
+      invalid("catalog", "A catalog takes factories made by `transformOf` or `sinkOf`.");
+    }
+    if (Object.hasOwn(byName, known.name)) {
+      invalid(known.name, "The catalog has another stage with its name.");
+    }
+    byName[known.name] = factory;
+  }
+  return Object.freeze({
+    [Kind]: "stage-catalog",
+    stages: Object.freeze(byName),
+    list: Object.freeze([...stages]),
+    resolve(name, options) {
+      const factory = Object.hasOwn(byName, name) ? byName[name] : undefined;
+      if (!factory)
+        invalid("catalog", `Unknown stage "${name}".`);
+      return factory(options);
+    }
+  });
+}

package/dist/core/output/status.js

@@ -0,0 +1,52 @@
+import { Exception } from "../exception/exception.js";
+const INVALID_INPUT = new Set([
+  "InvalidUseCaseInput",
+  "InvalidUseCaseContext",
+  "InvalidCommandContext"
+]);
+const CONFIGURATION = new Set(["InvalidCommandEnvironment"]);
+const NOT_FOUND = new Set([
+  "RepositoryEntityNotFound",
+  "UnknownCommandOperation",
+  "UseCaseEntityNotFound"
+]);
+const CONFLICT = new Set([
+  "RepositoryUniqueViolation",
+  "RepositoryConcurrencyConflict",
+  "UseCaseEntityConflict"
+]);
+export function raisedOf(error) {
+  let raised = error;
+  for (let current = error.cause;current instanceof Exception; current = current.cause) {
+    if (current.name === error.name)
+      raised = current;
+  }
+  return raised;
+}
+export function statusOf(error, operation, statuses) {
+  if (!(error instanceof Exception))
+    return 500;
+  const { name } = error;
+  if (statuses && Object.hasOwn(statuses, name))
+    return statuses[name];
+  if (INVALID_INPUT.has(name))
+    return 400;
+  if (CONFIGURATION.has(name))
+    return 500;
+  if (Array.isArray(raisedOf(error).details?.issues)) {
+    return 400;
+  }
+  if (NOT_FOUND.has(name))
+    return 404;
+  if (CONFLICT.has(name))
+    return 409;
+  if (name === "UseCaseInvalidCredentials" || name === "Unauthenticated") {
+    return 401;
+  }
+  if (name === "Forbidden")
+    return 403;
+  if (operation?.errors.some((Declared) => error.is(Declared) || Declared.name === name)) {
+    return 422;
+  }
+  return 500;
+}

package/dist/core/output/types/http.interface.d.ts

@@ -15,7 +15,11 @@ export interface HttpOptions extends RouteOptions {
         readonly info: OpenAPISinkOptions["info"];
         readonly servers?: OpenAPISinkOptions["servers"];
     };
-    /** Adds the `trace` to problems and the real `detail` to 5xx ones. Off by default. */
+    /**
+     * Adds the `trace` to problems and the real `detail` to 5xx ones.
+     *
+     * @default false
+     */
     readonly debug?: boolean;
     /**
      * The context of an operation, by context key: from request headers

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

@@ -100,6 +100,11 @@ export type StageDescription = {
 } | {
     readonly kind: "opaque";
 };
+/**
+ * What `transformOf` takes: the `name` of the stage, the `apply` function that
+ * changes each operation (or removes it) and an optional `validate` of its
+ * options.
+ */
 export interface TransformSettings<Options extends object> {
     readonly name: string;
     /** Returns the operation, a changed copy, or `null` to remove it. */
@@ -107,6 +112,11 @@ export interface TransformSettings<Options extends object> {
     /** Why `options` cannot be used, or `undefined`. Checked when the stage is made. */
     readonly validate?: (options: Options) => string | undefined;
 }
+/**
+ * What `sinkOf` takes: the `name` of the stage, the `build` function that turns
+ * the operations into the result of the output (a server, a document...) and an
+ * optional `validate` of its options.
+ */
 export interface SinkSettings<Result, Options extends object, Hooks = never> {
     readonly name: string;
     /**
@@ -120,6 +130,11 @@ export interface SinkSettings<Result, Options extends object, Hooks = never> {
 }
 /** Makes a stage from JSON options. */
 export type TransformFactory<Options extends object = StageOptions> = (options?: Options) => TransformStage<Options>;
+/**
+ * Makes a sink stage from JSON `options` and, second, `hooks`: what cannot be
+ * JSON (functions, an instance of a server), which the description of the stage
+ * leaves out. What `sinkOf` returns.
+ */
 export type SinkFactory<Result = unknown, Options extends object = StageOptions, Hooks = never> = (options?: Options, hooks?: Hooks) => SinkStage<Result, Options>;
 /** Any stage factory. */
 export type StageFactory = TransformFactory<any> | SinkFactory<any, any>;
@@ -143,6 +158,11 @@ export interface OutputApplication {
 }
 /** What an output takes its commands from. */
 export type OutputSource = AnyCommand | OutputApplication;
+/**
+ * What `outputOf` takes: the `name` of the output, the `commands` it exposes
+ * (commands, applications or a mix), the `statuses` by exception name and the
+ * `pipe` of stages that transform its operations and end in a sink.
+ */
 export interface OutputSettings<Pipe extends readonly Stage[]> {
     readonly name: string;
     /** The commands the output exposes: commands, applications (all their commands) or a mix. */
@@ -184,6 +204,10 @@ export interface Problem {
     /** Only with `debug`. */
     readonly trace?: string;
 }
+/**
+ * What `problemOf` takes: the HTTP `status` of the problem and `debug`, which
+ * adds the `trace` and the real `detail` of a 5xx.
+ */
 export interface ProblemOptions {
     readonly status: number;
     readonly debug?: boolean;

package/dist/core/parse/issue.js

@@ -0,0 +1,31 @@
+export const REJECTED = Symbol("rejected");
+
+export class LazyIssue {
+  message;
+  path;
+  code;
+  source;
+  #origin;
+  constructor(message, path, code, source, origin) {
+    this.message = message;
+    this.path = path;
+    this.code = code;
+    this.source = source;
+    this.#origin = origin;
+  }
+  get cause() {
+    return this.#origin.exception();
+  }
+  at(path) {
+    return new LazyIssue(this.message, path, this.code, this.source, this.#origin);
+  }
+}
+export function movedIssue(issue, path) {
+  if (issue instanceof LazyIssue)
+    return issue.at(path);
+  const moved = { ...issue, path };
+  const cause = Object.getOwnPropertyDescriptor(issue, "cause");
+  if (cause && !cause.enumerable)
+    Object.defineProperty(moved, "cause", cause);
+  return moved;
+}

package/dist/core/parse/parse.d.ts

@@ -18,6 +18,13 @@ export declare function isPlainObject(value: unknown): value is Record<string, u
  * is parsing it, e.g. a record name.
  */
 export declare function parseCollection(properties: IBlueprintCollection, value: unknown, path: Path, source: string): ParseResult<Readonly<Record<string, unknown>>>;
+/**
+ * Makes, once the rest of a collection is known to be valid, the values the
+ * caller left out for it (`undefined` in `handled`); it returns the keys it
+ * made that still have to be checked.
+ * @internal
+ */
+export type Complete = (handled: Record<string, unknown>) => readonly string[] | undefined;
 /**
  * `parseCollection` at the root, as a function of the value alone: what it
  * needs of `properties` is looked up on the first value and kept, instead of
@@ -26,7 +33,7 @@ export declare function parseCollection(properties: IBlueprintCollection, value:
  * unchecked: for what the caller made itself and knows to be valid.
  * @internal
  */
-export declare function collectionParserOf(properties: IBlueprintCollection, source: string): (value: unknown, vouched?: readonly string[]) => ParseResult<Readonly<Record<string, unknown>>>;
+export declare function collectionParserOf(properties: IBlueprintCollection, source: string): (value: unknown, vouched?: readonly string[], complete?: Complete) => ParseResult<Readonly<Record<string, unknown>>>;
 /**
  * `value` handled by `field`, or every issue found: a property runs its
  * handlers, a blueprint each of its fields, a list each of its items, and a