@afora/core 0.0.8 → 0.0.11

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.d.ts

@@ -1,8 +1,13 @@
 import type { IStageCatalog, SinkFactory, SinkSettings, Stage, StageDescription, StageFactory, StageOptions, TransformFactory, TransformSettings } from "./types/output.interface.js";
 /** A factory of transform stages: `select({ tags: ["public"] })`. */
 export declare function transformOf<Options extends object = StageOptions>(settings: TransformSettings<Options>): TransformFactory<Options>;
-/** A factory of sink stages: `openapi({ info })`. */
-export declare function sinkOf<Result, Options extends object = StageOptions>(settings: SinkSettings<Result, Options>): SinkFactory<Result, Options>;
+/**
+ * A factory of sink stages: `openapi({ info })`. A sink that needs what JSON
+ * cannot hold (middlewares, an authenticator) takes it as a second argument,
+ * its `hooks`, which `build` receives and the description of the stage
+ * leaves out.
+ */
+export declare function sinkOf<Result, Options extends object = StageOptions, Hooks = never>(settings: SinkSettings<Result, Options, Hooks>): SinkFactory<Result, Options, Hooks>;
 /**
  * What a stage is: its kind, name and JSON options when it came from a
  * factory, `{ kind: "opaque" }` otherwise (a hand-written stage needs an

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.d.ts

@@ -11,7 +11,7 @@ export declare function raisedOf(error: Exception): Exception;
  * name; 400 for invalid input or context (and any exception whose
  * `details.issues` is a list, except `InvalidCommandEnvironment`, a 500); 404 for a missing entity or operation; 409 for
  * a unique violation, a concurrency conflict or an entity that already exists; 401 for
- * `UseCaseInvalidCredentials`; 422 for a class in `operation.errors`; 500 for the
+ * `UseCaseInvalidCredentials` and `Unauthenticated`; 403 for `Forbidden`; 422 for a class in `operation.errors`; 500 for the
  * rest, errors that are not exceptions included. Exceptions match by name,
  * or by class for `operation.errors`.
  */

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

@@ -0,0 +1,134 @@
+import type { DescribedJwtOptions } from "../../auth/types/jwt.interface.js";
+import type { Principal } from "../../use-case/types/access.interface.js";
+import type { OpenAPIMethod, OpenAPISinkOptions, RouteOptions } from "../openapi-sink.js";
+import type { OperationDescriptor } from "./output.interface.js";
+/**
+ * The options every sink that serves HTTP takes. JSON, so the stage can live
+ * in an `afora.json`. The routing options (`basePath`, `route`, `responses`,
+ * `requestId`, `security`) are those of the `openapi` sink, so the served
+ * routes and the document agree.
+ */
+export interface HttpOptions extends RouteOptions {
+    /** Serves the OpenAPI document of the same operations at `path`. */
+    readonly docs?: {
+        readonly path: string;
+        readonly info: OpenAPISinkOptions["info"];
+        readonly servers?: OpenAPISinkOptions["servers"];
+    };
+    /**
+     * 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
+     * (`{ headers: { locale: "accept-language" } }`) and from values a
+     * middleware of the server set for the request
+     * (`{ variables: { caller: "caller" } }`).
+     */
+    readonly context?: {
+        readonly headers?: {
+            readonly [contextKey: string]: string;
+        };
+        readonly variables?: {
+            readonly [contextKey: string]: string;
+        };
+    };
+    /**
+     * Who calls, from a JSON Web Token (see `jwtOf`; the secret is named by
+     * its environment variable, `{ env: "JWT_SECRET" }`): read from the
+     * `authorization` header (`Bearer <token>`; another header with `header`)
+     * and, with `cookie`, from that cookie when the header is absent. The
+     * document gets a matching security scheme unless `security` declares
+     * its own. An `authenticator` given in the hooks of the sink replaces it.
+     */
+    readonly auth?: {
+        readonly jwt: DescribedJwtOptions & {
+            readonly header?: string;
+            readonly cookie?: string;
+        };
+    };
+}
+/** A request, as the server of a sink gives it to the route table. */
+export interface HttpRequest {
+    /** The value of the `{name}` segment of the path, decoded. */
+    param(name: string): string | undefined;
+    /** The query string, the first value of each name. */
+    query(): Readonly<Record<string, string | undefined>>;
+    /** The value of a header, by its name in lower case. */
+    header(name: string): string | undefined;
+    /** The body, as text. Called at most once, and only by routes with a body. */
+    text(): string | Promise<string>;
+    /** A value a middleware of the server set for this request, by name. */
+    variable?(name: string): unknown;
+    /** The request of the server itself, for an authenticator that needs it. */
+    readonly native?: unknown;
+}
+/** The answer to a request: what the server of a sink has to send, as is. */
+export interface HttpResult {
+    readonly status: number;
+    /** `content-type` included, when there is a body. */
+    readonly headers: Readonly<Record<string, string>>;
+    /** One `set-cookie` header each. */
+    readonly cookies: readonly string[];
+    /** The body, already serialized (sensitive values masked), or `null` for none. */
+    readonly body: string | null;
+}
+/** What an authenticator reads of a request. */
+export interface AuthRequest {
+    /** The value of a header, by its name in lower case. */
+    header(name: string): string | undefined;
+    /** The value of a cookie of the request. */
+    cookie(name: string): string | undefined;
+    /** The operation being called. */
+    readonly operation: OperationDescriptor;
+    /** The request of the server itself. */
+    readonly native?: unknown;
+}
+/**
+ * Who is calling, from the credentials of a request: a `Principal`, or
+ * `null` for an anonymous caller. Called for each request to an operation
+ * with an `access` other than `public`. It may throw `Unauthenticated` to
+ * refuse credentials it does not accept.
+ */
+export type Authenticator = (request: AuthRequest) => Principal | null | Promise<Principal | null>;
+/** One operation, ready to serve: the server routes `method` and `path` to `handle`. */
+export interface CompiledRoute {
+    readonly operation: OperationDescriptor;
+    readonly method: OpenAPIMethod;
+    /** `basePath` included, parameters as `{name}`. */
+    readonly path: string;
+    /** The names of the `{name}` segments of `path`, in order. */
+    readonly parameters: readonly string[];
+    /** Never rejects: an error is a problem result. */
+    handle(request: HttpRequest): Promise<HttpResult>;
+}
+/** The routes of an output, compiled once (see `compileRoutes`). */
+export interface RouteTable {
+    readonly routes: readonly CompiledRoute[];
+    /** The route that serves the OpenAPI document, with `docs`. */
+    readonly docs?: {
+        readonly path: string;
+        handle(request?: Pick<HttpRequest, "header">): HttpResult;
+    };
+    /** The 404 problem for a request no route serves. */
+    notFound(request?: Pick<HttpRequest, "header">): HttpResult;
+    /**
+     * The problem for an error raised outside `handle`: its status is the one
+     * the output `statuses` give its name, else `status`, else `statusOf`.
+     */
+    failure(error: unknown, options?: {
+        readonly operation?: OperationDescriptor;
+        readonly status?: number;
+        readonly request?: Pick<HttpRequest, "header">;
+    }): HttpResult;
+}
+/** What `compileRoutes` takes besides the operations and the options. */
+export interface CompileRoutesSettings {
+    /** The name of the sink, for the messages of `InvalidOutputStage`. */
+    readonly source: string;
+    readonly authenticator?: Authenticator;
+    /** Changes the OpenAPI document before it is served (a sink with routes of its own kind). */
+    readonly document?: (document: unknown) => unknown;
+}