@afora/core 0.0.9 → 0.0.11

package/dist/core/event-policy/publish.js

@@ -0,0 +1,98 @@
+import { CommandEventFailed } from "../command/exceptions.js";
+import { logFailure } from "../logger/logger.js";
+import { eventPolicyOf } from "./event-policy.js";
+const KEYS = ["publisher", "topic", "events", "handle", "onPublishError"];
+const IDENTIFIER = /^[A-Za-z_$][\w$]*$/;
+const PLACEHOLDER = /\{(event|command|operation|id)\}/g;
+function validate(options) {
+  const given = options;
+  for (const key of Object.keys(given)) {
+    if (!KEYS.includes(key))
+      return `publishEvents has no option "${key}".`;
+  }
+  const { publisher, topic, events, handle, onPublishError } = given;
+  if (typeof publisher !== "string" || !IDENTIFIER.test(publisher)) {
+    return "Expected publishEvents.publisher to be the key of a publisher of the application.";
+  }
+  if (typeof topic !== "string" || topic === "") {
+    return 'Expected publishEvents.topic to be a non-empty string, such as "posts/{id}".';
+  }
+  const unknown = topic.replaceAll(PLACEHOLDER, "").match(/\{[^}]*\}/);
+  if (unknown) {
+    return `publishEvents.topic has an unknown placeholder ${unknown[0]}: use {event}, {command}, {operation} or {id}.`;
+  }
+  if (events !== undefined && (!Array.isArray(events) || events.some((name) => typeof name !== "string" || name === ""))) {
+    return "Expected publishEvents.events to be a list of event names.";
+  }
+  if (handle !== undefined && typeof handle !== "boolean") {
+    return "Expected publishEvents.handle to be a boolean.";
+  }
+  if (onPublishError !== undefined && onPublishError !== "log" && onPublishError !== "throw") {
+    return 'Expected publishEvents.onPublishError to be "log" or "throw".';
+  }
+  return;
+}
+function entityJson(event) {
+  const text = JSON.stringify(event.entity);
+  return text === undefined ? null : JSON.parse(text);
+}
+export const publishEvents = eventPolicyOf({
+  name: "publishEvents",
+  validate,
+  publishers: (options) => [options.publisher],
+  handle: async (events, info, options) => {
+    const { command, operation, logger } = info;
+    const commandName = command.commandName;
+    const source = `${commandName}.${operation}`;
+    const only = options.events ? new Set(options.events) : undefined;
+    const failed = (cause, event, index) => new CommandEventFailed({
+      source,
+      cause,
+      details: {
+        operation,
+        event: event.name,
+        handled: index,
+        remaining: events.length - index - 1
+      }
+    });
+    for (const [index, event] of events.entries()) {
+      if (options.handle !== false) {
+        try {
+          await event.handle({ logger });
+        } catch (cause) {
+          throw failed(cause, event, index);
+        }
+      }
+      if (only && !only.has(event.name))
+        continue;
+      let publisher;
+      try {
+        publisher = info.publisher(options.publisher);
+      } catch (cause) {
+        throw failed(cause, event, index);
+      }
+      const entity = entityJson(event);
+      const id = entity?.id;
+      const topic = options.topic.replaceAll(PLACEHOLDER, (_, key) => key === "event" ? event.name : key === "command" ? commandName : key === "operation" ? operation : id === undefined ? "" : String(id));
+      const published = Object.freeze({
+        name: event.name,
+        command: commandName,
+        operation,
+        entity
+      });
+      try {
+        await publisher.publish(topic, published);
+      } catch (cause) {
+        if (options.onPublishError === "throw")
+          throw failed(cause, event, index);
+        logFailure(logger, "event-publish-failed", {
+          command: commandName,
+          operation,
+          event: event.name,
+          publisher: options.publisher,
+          topic
+        }, cause);
+      }
+    }
+  }
+});

package/dist/core/event-policy/publishers.js

@@ -0,0 +1,18 @@
+import { startedApplication } from "../application/registry.js";
+import { PublisherNotBound } from "./exceptions.js";
+export const ApplicationPublishersKey = Symbol("afora.application.publishers");
+const boundPublishers = new WeakMap;
+export function bindPublishers(command, publishers) {
+  boundPublishers.set(command, publishers);
+}
+export function isEventPublisher(value) {
+  return typeof value === "object" && value !== null && typeof value.publish === "function";
+}
+export function resolvePublisher(command, name, source) {
+  const publishers = boundPublishers.get(command) ?? startedApplication()?.[ApplicationPublishersKey];
+  const publisher = publishers && Object.hasOwn(publishers, name) ? publishers[name] : undefined;
+  if (!publisher) {
+    throw new PublisherNotBound({ source, details: { publisher: name } });
+  }
+  return publisher;
+}

package/dist/core/event-policy/types/event-policy.interface.d.ts

@@ -61,12 +61,18 @@ export interface PublishEventsOptions {
     readonly topic: string;
     /** The names of the events to publish; all of them by default. */
     readonly events?: readonly string[];
-    /** Whether each event runs its own handler first, as `"after-commit"` does. `true` by default. */
+    /**
+     * Whether each event runs its own handler first, as `"after-commit"` does.
+     *
+     * @default true
+     */
     readonly handle?: boolean;
     /**
-     * What a failed publish does: `"log"` (default) writes an error to the
+     * What a failed publish does: `"log"` writes an error to the
      * logger and goes on, since the call already committed; `"throw"` makes
      * the call fail with `CommandEventFailed`.
+     *
+     * @default "log"
      */
     readonly onPublishError?: "log" | "throw";
 }

package/dist/core/exception/enums/exception-layers.js

@@ -0,0 +1,15 @@
+export var ExceptionLayers;
+((ExceptionLayers) => {
+  ExceptionLayers["Schema"] = "schema";
+  ExceptionLayers["Property"] = "property";
+  ExceptionLayers["Blueprint"] = "blueprint";
+  ExceptionLayers["Record"] = "record";
+  ExceptionLayers["Entity"] = "entity";
+  ExceptionLayers["UseCase"] = "use-case";
+  ExceptionLayers["Repository"] = "repository";
+  ExceptionLayers["Environment"] = "environment";
+  ExceptionLayers["Event"] = "event";
+  ExceptionLayers["Command"] = "command";
+  ExceptionLayers["Application"] = "application";
+  ExceptionLayers["Output"] = "output";
+})(ExceptionLayers ||= {});

package/dist/core/exception/exception.d.ts

@@ -64,5 +64,20 @@ export declare function declaredMessageOf(Declared: DeclaredExceptionClass<never
  * Declares an exception of `layer`, e.g.
  * `throw new PropertyRequired({ source: "email" })`. Its `details` are typed
  * by the parameter of `message`, when it is a function.
+ *
+ * @example
+ * ```ts
+ * import { ExceptionLayers, exceptionOf } from "@afora/core";
+ *
+ * const UserNotFound = exceptionOf({
+ * 	layer: ExceptionLayers.UseCase,
+ * 	name: "UserNotFound",
+ * 	message: ({ id }: { id: string }) => `There is no user ${id}.`,
+ * });
+ *
+ * const error = new UserNotFound({ source: "FindUser", details: { id: "42" } });
+ * error.message; // "There is no user 42."
+ * error.layer; // ExceptionLayers.UseCase
+ * ```
  */
 export declare function exceptionOf<Details = undefined>({ layer, name, message, }: ExceptionDeclaration<Details>): DeclaredExceptionClass<Details>;

package/dist/core/exception/exception.js

@@ -0,0 +1,128 @@
+export const UNEXPECTED_ERROR = "UnexpectedError";
+
+export class Exception extends Error {
+  name;
+  layer;
+  source;
+  details;
+  cause;
+  constructor({
+    layer,
+    name,
+    source,
+    message,
+    details,
+    cause
+  }) {
+    super(message, cause === undefined ? undefined : { cause });
+    this.name = name;
+    this.layer = layer;
+    this.source = source;
+    this.details = details;
+    this.cause = cause;
+  }
+  static from(error, scope) {
+    if (error instanceof Exception)
+      return error;
+    return new Exception({
+      ...scope,
+      name: UNEXPECTED_ERROR,
+      message: error instanceof Error ? error.message : String(error),
+      cause: error
+    });
+  }
+  get frame() {
+    const { layer, name, source, message, details } = this;
+    return { layer, name, source, message, details };
+  }
+  get trace() {
+    return this.chain().map((exception) => exception.frame).reverse();
+  }
+  get origin() {
+    return this.chain().at(-1);
+  }
+  find(target) {
+    return this.chain().find((exception) => typeof target === "string" ? exception.name === target : exception instanceof target);
+  }
+  is(target) {
+    return this.find(target) !== undefined;
+  }
+  passedThrough(layer) {
+    return this.chain().some((exception) => exception.layer === layer);
+  }
+  propagate({
+    layer,
+    source,
+    name = this.name,
+    message = this.message,
+    details
+  }) {
+    const keepsClass = name === this.name && details === undefined && isDeclaredInstance(this);
+    const init = {
+      layer,
+      source,
+      name,
+      message,
+      details: keepsClass ? this.details : details,
+      cause: this
+    };
+    return keepsClass ? Reflect.construct(Exception, [init], this.constructor) : new Exception(init);
+  }
+  toJSON() {
+    return { ...this.frame, trace: this.trace };
+  }
+  toString() {
+    return this.chain().map((exception, index) => `${index === 0 ? "" : "  <- "}${exception.name} [${exception.layer} @ ${exception.source}]: ${exception.message}`).join(`
+`);
+  }
+  chain() {
+    const chain = [];
+    for (let current = this;current instanceof Exception; current = current.cause) {
+      chain.push(current);
+    }
+    return chain;
+  }
+}
+const declarations = new WeakMap;
+function isDeclaredInstance(exception) {
+  for (let current = exception.constructor;typeof current === "function"; current = Object.getPrototypeOf(current)) {
+    if (declarations.has(current))
+      return true;
+  }
+  return false;
+}
+export function isDeclaredException(value) {
+  return typeof value === "function" && declarations.has(value);
+}
+export function declaredMessageOf(Declared) {
+  const { message } = declarations.get(Declared) ?? {};
+  return typeof message === "string" ? message : undefined;
+}
+export function exceptionOf({
+  layer,
+  name,
+  message
+}) {
+
+  class DeclaredException extends Exception {
+    static layer = layer;
+    constructor({
+      source,
+      details,
+      cause,
+      message: custom
+    }) {
+      super({
+        layer,
+        name,
+        source,
+        details,
+        cause,
+        message: custom ?? (typeof message === "function" ? message(details, source) : message)
+      });
+    }
+  }
+  Object.defineProperty(DeclaredException, "name", { value: name });
+  declarations.set(DeclaredException, { message });
+  return DeclaredException;
+}

package/dist/core/exception/exported.js

@@ -0,0 +1,49 @@
+import * as Application from "../application/exceptions.js";
+import * as Blueprint from "../blueprint/exceptions.js";
+import * as Command from "../command/exceptions.js";
+import * as Entity from "../entity/exceptions.js";
+import * as Environment from "../environment/environment.js";
+import * as EventPolicy from "../event-policy/exceptions.js";
+import * as Log from "../logger/exceptions.js";
+import * as OpenAPI from "../openapi/exceptions.js";
+import * as Output from "../output/exceptions.js";
+import * as Property from "../property/exceptions.js";
+import * as RecordKeys from "../record/exceptions.js";
+import * as Repository from "../repository/exceptions.js";
+import * as Tracing from "../tracing/exceptions.js";
+import * as UseCaseSteps from "../use-case/exceptions.js";
+import * as UseCase from "../use-case/use-case.js";
+import { isDeclaredException } from "./exception.js";
+const exported = new WeakSet;
+let collected = false;
+export function markExported(...classes) {
+  for (const Declared of classes) {
+    if (isDeclaredException(Declared))
+      exported.add(Declared);
+  }
+}
+export function isExportedException(Declared) {
+  if (!collected) {
+    collected = true;
+    for (const module of [
+      Application,
+      Blueprint,
+      Command,
+      Entity,
+      Environment,
+      EventPolicy,
+      Log,
+      OpenAPI,
+      Output,
+      Property,
+      RecordKeys,
+      Repository,
+      Tracing,
+      UseCase,
+      UseCaseSteps
+    ]) {
+      markExported(...Object.values(module));
+    }
+  }
+  return typeof Declared === "function" && exported.has(Declared);
+}

package/dist/core/exception/guard.d.ts

@@ -1,8 +1,27 @@
 import { Exception } from "./exception.js";
 import type { ExceptionScope } from "./types/exception.interface.js";
 /**
- * Handles what `run` throws, or rejects with, in `scope`. Without `resolve`,
+ * Handles what `run` throws, or rejects with, in `scope` (see {@link ExceptionScope}). Without `resolve`,
  * or when it calls `pass`, the exception goes up to the next layer with its
  * trace; otherwise `resolve` returns the value to use instead.
+ *
+ * @throws {@link Exception} what `run` throws or rejects with, in `scope` and with its trace, unless `resolve` gives a value instead.
+ *
+ * @example
+ * ```ts
+ * import { ExceptionLayers, guard } from "@afora/core";
+ *
+ * const scope = { layer: ExceptionLayers.UseCase, source: "LoadConfig" };
+ *
+ * // Without `resolve`, what `run` throws goes up to the next layer with its trace
+ * guard(scope, () => JSON.parse('{"port":3000}'));
+ *
+ * // With `resolve`, it can give a value instead, or call `pass` to go up
+ * const config = guard(
+ * 	scope,
+ * 	() => JSON.parse("{") as { port: number },
+ * 	() => ({ port: 8080 }),
+ * );
+ * ```
  */
 export declare function guard<Result>(scope: ExceptionScope, run: () => Result, resolve?: (exception: Exception, pass: () => never) => Result | Awaited<Result>): Result;

package/dist/core/exception/guard.js

@@ -0,0 +1,16 @@
+import { Exception } from "./exception.js";
+export function guard(scope, run, resolve) {
+  const handle = (error) => {
+    const exception = Exception.from(error, scope);
+    const pass = () => {
+      throw exception === error ? exception.propagate(scope) : exception;
+    };
+    return resolve ? resolve(exception, pass) : pass();
+  };
+  try {
+    const result = run();
+    return result instanceof Promise ? result.catch(handle) : result;
+  } catch (error) {
+    return handle(error);
+  }
+}

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

@@ -11,6 +11,10 @@ export interface ExceptionFrame<Details = unknown> extends ExceptionScope {
     readonly message: string;
     readonly details: Details;
 }
+/**
+ * What the {@link Exception} constructor takes: the scope (`layer` and
+ * `source`), the `name` and `message`, optional `details` and the `cause`.
+ */
 export interface ExceptionInit<Details = unknown> extends ExceptionScope {
     readonly name: string;
     readonly message: string;
@@ -26,7 +30,16 @@ export interface ExceptionPropagation<Details = unknown> extends ExceptionScope
 }
 /** An exception class, abstract or declared with `exceptionOf`. */
 export type ExceptionClass<Instance = any> = abstract new (...args: never[]) => Instance;
+/**
+ * The `message` of an exception declared with {@link exceptionOf}: a string, or
+ * a function of the `details` and the `source` that gives it.
+ */
 export type ExceptionMessage<Details> = string | ((details: Details, source: string) => string);
+/**
+ * What {@link exceptionOf} takes: the `layer` of the exception, its `name` and
+ * its `message`. `Details` is the type of the `details` it carries, taken from
+ * the parameter of `message` when that is a function.
+ */
 export interface ExceptionDeclaration<Details> {
     readonly layer: ExceptionLayers;
     readonly name: string;

package/dist/core/json.js

@@ -0,0 +1,19 @@
+export function frozenJson(value, subject, fail, seen = new Set) {
+  if (value === null || typeof value === "string" || typeof value === "boolean")
+    return value;
+  if (typeof value === "number" && Number.isFinite(value))
+    return value;
+  if (typeof value !== "object" || value === null || seen.has(value))
+    return fail(`${subject} must be finite, acyclic JSON values.`);
+  if (!Array.isArray(value) && Object.getPrototypeOf(value) !== Object.prototype && Object.getPrototypeOf(value) !== null)
+    return fail(`${subject} must contain only plain objects and arrays.`);
+  if (Object.getOwnPropertySymbols(value).length > 0)
+    return fail(`${subject} cannot contain symbol keys.`);
+  seen.add(value);
+  const result = Array.isArray(value) ? value.map((item) => frozenJson(item, subject, fail, seen)) : Object.fromEntries(Object.entries(value).map(([key, item]) => [
+    key,
+    frozenJson(item, subject, fail, seen)
+  ]));
+  seen.delete(value);
+  return Object.freeze(result);
+}

package/dist/core/logger/exceptions.js

@@ -0,0 +1,7 @@
+import { ExceptionLayers } from "../exception/enums/exception-layers.js";
+import { exceptionOf } from "../exception/exception.js";
+export const InvalidLogDeclaration = exceptionOf({
+  layer: ExceptionLayers.Application,
+  name: "InvalidLogDeclaration",
+  message: ({ reason }) => reason
+});

package/dist/core/logger/logger.d.ts

@@ -1,7 +1,11 @@
 import { Kind } from "../symbols/kind.js";
 /** What a log line carries besides its event. */
 export type LogFields = Readonly<Record<string, unknown>>;
+/** The severity of a log line, from the least to the most severe. */
 export type LogLevel = "debug" | "info" | "warn" | "error";
+/**
+ * The {@link LogLevel}s in order of severity, from `"debug"` to `"error"`.
+ */
 export declare const LogLevels: readonly LogLevel[];
 /** What logs: an application, a use case through its `Logger` dependency, your code. */
 export interface ILogger {
@@ -31,7 +35,11 @@ export interface ILogProvider {
 }
 /** The `log` of an application. */
 export interface LogSettings {
-    /** Lines below it are dropped. `"info"` by default. */
+    /**
+     * Lines below it are dropped.
+     *
+     * @default "info"
+     */
     readonly level?: LogLevel;
     readonly providers: readonly ILogProvider[];
 }
@@ -79,6 +87,11 @@ export declare function applicationLogger(application: string): {
 export interface LoggerDeclaration {
     readonly [Kind]: "logger";
 }
+/**
+ * The dependency that gives a use case the logger of its application:
+ * `dependencies: { logger: Logger }` makes `this.dependencies.logger` an {@link
+ * ILogger}.
+ */
 export declare const Logger: LoggerDeclaration;
 export declare function isLoggerDeclaration(value: unknown): value is LoggerDeclaration;
 /** Whether `value` can stand for a logger (an override in `execute`). */

package/dist/core/logger/logger.js

@@ -0,0 +1,178 @@
+import { startedApplication } from "../application/registry.js";
+import { Exception, UNEXPECTED_ERROR } from "../exception/exception.js";
+import { Kind } from "../symbols/kind.js";
+import { InvalidLogDeclaration } from "./exceptions.js";
+export const LogLevels = Object.freeze([
+  "debug",
+  "info",
+  "warn",
+  "error"
+]);
+const names = new WeakMap;
+const invalid = (reason) => {
+  throw new InvalidLogDeclaration({ source: "log", details: { reason } });
+};
+export function logProviderOf(settings) {
+  if (!settings || typeof settings.write !== "function") {
+    invalid("Expected a log provider with a write function.");
+  }
+  if (settings.flush !== undefined && typeof settings.flush !== "function") {
+    invalid("Expected flush to be a function.");
+  }
+  if (settings.name !== undefined && (typeof settings.name !== "string" || settings.name.trim() === "")) {
+    invalid("Expected the name of a log provider to be a non-empty string.");
+  }
+  const provider = Object.freeze({
+    write: settings.write,
+    ...settings.flush ? { flush: settings.flush } : {}
+  });
+  if (settings.name)
+    names.set(provider, settings.name);
+  return provider;
+}
+export function logProviderNameOf(provider) {
+  return names.get(provider);
+}
+const fieldsText = (fields) => Object.keys(fields).length > 0 ? ` ${JSON.stringify(fields)}` : "";
+export function consoleLogProvider() {
+  return logProviderOf({
+    name: "console",
+    write: ({ at, level, event, fields, application }) => {
+      const line = `${at} ${level.toUpperCase()} [${application}] ${event}${fieldsText(fields)}`;
+      (level === "debug" ? console.debug : level === "info" ? console.info : level === "warn" ? console.warn : console.error)(line);
+    }
+  });
+}
+export function jsonLogProvider() {
+  return logProviderOf({
+    name: "json",
+    write: (entry) => {
+      console.log(JSON.stringify({
+        at: entry.at,
+        level: entry.level,
+        application: entry.application,
+        event: entry.event,
+        ...entry.fields
+      }));
+    }
+  });
+}
+export function memoryLogProvider() {
+  const entries = [];
+  const provider = Object.freeze({
+    write: (entry) => {
+      entries.push(entry);
+    },
+    entries,
+    clear: () => {
+      entries.length = 0;
+    }
+  });
+  names.set(provider, "memory");
+  return provider;
+}
+export function checkLogSettings(settings) {
+  if (typeof settings !== "object" || settings === null) {
+    return invalid("Expected `log` to be { level?, providers }.");
+  }
+  const { level = "info", providers } = settings;
+  if (!LogLevels.includes(level)) {
+    invalid(`Expected the log level to be one of ${LogLevels.join(", ")}.`);
+  }
+  if (!Array.isArray(providers) || providers.some((provider) => typeof provider !== "object" || provider === null || typeof provider.write !== "function")) {
+    invalid("Expected `log.providers` to be a list of log providers.");
+  }
+  return Object.freeze({ level, providers: Object.freeze([...providers]) });
+}
+export const silentLogger = Object.freeze({
+  debug: () => {},
+  info: () => {},
+  warn: () => {},
+  error: () => {}
+});
+const rank = (level) => LogLevels.indexOf(level);
+export function applicationLogger(application) {
+  let current;
+  const write = (level) => (event, fields = {}) => {
+    if (!current || rank(level) < rank(current.level))
+      return;
+    const entry = Object.freeze({
+      at: new Date().toISOString(),
+      level,
+      event,
+      fields,
+      application
+    });
+    for (const provider of current.providers) {
+      try {
+        const written = provider.write(entry);
+        if (written && typeof written.catch === "function") {
+          written.catch(() => {});
+        }
+      } catch {}
+    }
+  };
+  const logger = Object.freeze({
+    debug: write("debug"),
+    info: write("info"),
+    warn: write("warn"),
+    error: write("error")
+  });
+  return {
+    logger,
+    get settings() {
+      return current;
+    },
+    set(settings) {
+      current = settings;
+    },
+    async flush() {
+      await Promise.all((current?.providers ?? []).map((provider) => Promise.resolve().then(() => provider.flush?.()).catch(() => {})));
+    }
+  };
+}
+export const Logger = Object.freeze({
+  [Kind]: "logger"
+});
+export function isLoggerDeclaration(value) {
+  return value === Logger;
+}
+export function isLogger(value) {
+  return typeof value === "object" && value !== null && ["debug", "info", "warn", "error"].every((level) => typeof value[level] === "function");
+}
+export const ApplicationLoggerKey = Symbol("afora.application.logger");
+export function resolveLogger(scoped, owner) {
+  return scoped ?? owner?.[ApplicationLoggerKey] ?? startedApplication()?.[ApplicationLoggerKey];
+}
+export function clock() {
+  return globalThis.performance?.now() ?? Date.now();
+}
+export function elapsed(since) {
+  return Math.round(clock() - since);
+}
+const logged = new WeakSet;
+export function logFailure(logger, event, fields, error) {
+  if (!logger)
+    return;
+  const exception = error instanceof Exception ? error : undefined;
+  const key = exception?.origin ?? error;
+  if (typeof key === "object" && key !== null) {
+    if (logged.has(key))
+      return;
+    logged.add(key);
+  }
+  const unexpected = !exception || exception.origin.name === UNEXPECTED_ERROR;
+  try {
+    logger[unexpected ? "error" : "warn"](event, {
+      ...fields,
+      exception: exception ? exception.toJSON() : { message: error instanceof Error ? error.message : String(error) }
+    });
+  } catch {}
+}
+export function writeLog(logger, level, event, fields) {
+  if (!logger)
+    return;
+  try {
+    logger[level](event, fields);
+  } catch {}
+}

package/dist/core/openapi/exceptions.js

@@ -0,0 +1,7 @@
+import { ExceptionLayers } from "../exception/enums/exception-layers.js";
+import { exceptionOf } from "../exception/exception.js";
+export const InvalidOpenAPIModel = exceptionOf({
+  layer: ExceptionLayers.Output,
+  name: "InvalidOpenAPIModel",
+  message: ({ name }) => `"${name}" is not a property, blueprint, list, record or entity.`
+});