@afora/core 0.0.8 → 0.0.11

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.`
+});

package/dist/core/openapi/openapi.js

@@ -0,0 +1,132 @@
+import { isBlueprint } from "../blueprint/is-blueprint.js";
+import { isBlueprintList } from "../blueprint/list.js";
+import { isRecordClass, 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 { isProperty } from "../property/is-property.js";
+import { rawTypeOf } from "../schema/schema.js";
+import { InvalidOpenAPIModel } from "./exceptions.js";
+const NO_MARKS = { writeOnly: [], readOnly: [] };
+function isField(value) {
+  return isProperty(value) || isBlueprint(value) || isBlueprintList(value) || isBlueprintVariant(value) || recordFieldOf(value) !== undefined;
+}
+function isOptional(field) {
+  if (isProperty(field))
+    return field.type.optional === true;
+  if (isBlueprint(field) || isBlueprintList(field) || isBlueprintVariant(field)) {
+    return field.optional;
+  }
+  return recordFieldOf(field)?.optional ?? false;
+}
+export function plainOf(value, nested = false) {
+  if (Array.isArray(value))
+    return value.map((item) => plainOf(item, true));
+  if (typeof value !== "object" || value === null)
+    return value;
+  const id = value.$id;
+  if (nested && typeof id === "string")
+    return { $ref: id };
+  const plain = {};
+  for (const [key, item] of Object.entries(value)) {
+    if (!key.startsWith("~"))
+      plain[key] = plainOf(item, true);
+  }
+  return plain;
+}
+function objectOf(properties, scope, marks) {
+  const shape = {};
+  const required = [];
+  for (const [key, field] of Object.entries(properties)) {
+    const schema = schemaOf(field, scope);
+    if (marks.readOnly.includes(key))
+      schema.readOnly = true;
+    if (marks.writeOnly.includes(key))
+      schema.writeOnly = true;
+    shape[key] = schema;
+    if (!isOptional(field))
+      required.push(key);
+  }
+  return {
+    type: "object",
+    properties: shape,
+    ...required.length > 0 ? { required } : {},
+    additionalProperties: false
+  };
+}
+function recordSchemaOf(record, scope) {
+  const { sensitive = [] } = record.options ?? {};
+  return objectOf(record.blueprint.properties, scope, {
+    writeOnly: sensitive,
+    readOnly: isEntityClass(record) ? identityKeysOf(record) : []
+  });
+}
+function schemaOf(field, scope) {
+  if (isBlueprintList(field)) {
+    const { item, minItems, maxItems } = field;
+    return {
+      type: "array",
+      items: schemaOf(item, scope),
+      ...minItems === undefined ? {} : { minItems },
+      ...maxItems === undefined ? {} : { maxItems }
+    };
+  }
+  if (isBlueprint(field))
+    return objectOf(field.properties, scope, NO_MARKS);
+  if (isBlueprintVariant(field)) {
+    const variants = field.variants;
+    return {
+      oneOf: Object.entries(variants).map(([tag, variant]) => {
+        const object = isRecordClass(variant) ? recordSchemaOf(variant, scope) : objectOf(variant.properties, scope, NO_MARKS);
+        return {
+          ...object,
+          properties: { [field.key]: { const: tag }, ...object.properties },
+          required: [field.key, ...object.required ?? []]
+        };
+      }),
+      discriminator: { propertyName: field.key }
+    };
+  }
+  const record = recordFieldOf(field);
+  if (record) {
+    const name = scope.names.get(record.record);
+    return name === undefined ? recordSchemaOf(record.record, scope) : { $ref: `${scope.prefix}${name}` };
+  }
+  if (!isProperty(field)) {
+    throw new InvalidOpenAPIModel({
+      source: "openapi",
+      details: { name: String(field) }
+    });
+  }
+  const schema = plainOf(rawTypeOf(field.type.schema));
+  if (field.type.sensitive)
+    schema.writeOnly = true;
+  return schema;
+}
+export function toOpenAPI(modelOrModels, { refPrefix = "#/components/schemas/" } = {}) {
+  if (isField(modelOrModels)) {
+    return schemaOf(modelOrModels, { names: new Map, prefix: refPrefix });
+  }
+  if (typeof modelOrModels !== "object" || modelOrModels === null) {
+    throw new InvalidOpenAPIModel({
+      source: "openapi",
+      details: { name: String(modelOrModels) }
+    });
+  }
+  const names = new Map;
+  for (const [name, model] of Object.entries(modelOrModels)) {
+    if (!isField(model)) {
+      throw new InvalidOpenAPIModel({ source: "openapi", details: { name } });
+    }
+    const record = recordFieldOf(model);
+    if (record && !names.has(record.record))
+      names.set(record.record, name);
+  }
+  const scope = { names, prefix: refPrefix };
+  const schemas = {};
+  for (const [name, model] of Object.entries(modelOrModels)) {
+    const record = recordFieldOf(model);
+    schemas[name] = record && names.get(record.record) === name ? recordSchemaOf(record.record, scope) : schemaOf(model, scope);
+  }
+  return { schemas };
+}

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

@@ -28,10 +28,16 @@ export interface OpenAPIComponents<Name extends PropertyKey = string> {
         readonly [Key in Name]: OpenAPISchema;
     };
 }
+/**
+ * What `toOpenAPI` takes after the models: how a record named among them is
+ * referenced.
+ */
 export interface OpenAPIOptions {
     /**
      * Where a record named among the models is referenced from: `$ref` is this
-     * prefix and its name. `"#/components/schemas/"` by default.
+     * prefix and its name.
+     *
+     * @default "#/components/schemas/"
      */
     readonly refPrefix?: string;
 }

package/dist/core/output/access.d.ts

@@ -0,0 +1,16 @@
+import type { AnyBlueprint } from "../blueprint/types/blueprint.interface.js";
+import type { AccessDeclaration } from "../use-case/types/access.interface.js";
+import type { OperationCallOptions } from "./types/output.interface.js";
+/** What `command.run` takes: the call options without the caller. */
+type RunOptions = {
+    readonly context?: unknown;
+} | undefined;
+/**
+ * The check of `access` for the operation `id`, made once: given the input
+ * and the options of a call, it throws `Unauthenticated` or `Forbidden`, or
+ * gives the options to run the command with (the context filled from the
+ * caller). Throws `InvalidOutputStage` when `access.context` names a key the
+ * `context` of the operation does not have.
+ */
+export declare function accessGuardOf(id: string, access: AccessDeclaration, context: AnyBlueprint | undefined): (input: unknown, options: OperationCallOptions | undefined) => RunOptions;
+export {};

package/dist/core/output/access.js

@@ -0,0 +1,66 @@
+import { isPublicAccess } from "../use-case/access.js";
+import { Forbidden, InvalidOutputStage, Unauthenticated } from "./exceptions.js";
+function readerOf(path) {
+  if (path === "subject")
+    return (principal) => principal.subject;
+  if (path === "scopes")
+    return (principal) => [...principal.scopes];
+  const claim = path.slice("claims.".length);
+  return (principal) => principal.claims && Object.hasOwn(principal.claims, claim) ? principal.claims[claim] : undefined;
+}
+export function accessGuardOf(id, access, context) {
+  if (isPublicAccess(access)) {
+    return (_input, options) => options === undefined ? undefined : { context: options.context };
+  }
+  const scopes = access.scopes ?? [];
+  const owner = access.owner;
+  const ownerOf = owner ? readerOf(owner.claim === undefined ? "subject" : `claims.${owner.claim}`) : undefined;
+  const fills = Object.entries(access.context ?? {}).map(([key, path]) => [key, readerOf(path)]);
+  for (const [key] of fills) {
+    if (!context || !Object.hasOwn(context.properties, key)) {
+      throw new InvalidOutputStage({
+        source: id,
+        details: {
+          reason: `The access of ${id} fills the context key "${key}", which the context of the operation does not declare.`
+        }
+      });
+    }
+  }
+  return (input, options) => {
+    const principal = options?.principal;
+    if (principal === undefined || principal === null || typeof principal.subject !== "string" || !Array.isArray(principal.scopes)) {
+      throw new Unauthenticated({ source: id });
+    }
+    if (scopes.length > 0) {
+      const missing = scopes.filter((scope) => !principal.scopes.includes(scope));
+      if (missing.length > 0) {
+        throw new Forbidden({
+          source: id,
+          details: { reason: "scope", scopes: missing }
+        });
+      }
+    }
+    if (owner && ownerOf) {
+      const expected = ownerOf(principal);
+      const given = typeof input === "object" && input !== null ? input[owner.input] : undefined;
+      if (given === undefined || given === null || expected === undefined || expected === null || String(given) !== String(expected)) {
+        throw new Forbidden({ source: id, details: { reason: "owner" } });
+      }
+    }
+    if (fills.length === 0) {
+      return options?.context === undefined ? undefined : { context: options.context };
+    }
+    const given = options?.context;
+    const filled = {
+      ...typeof given === "object" && given !== null ? given : {}
+    };
+    for (const [key, read] of fills) {
+      const value = read(principal);
+      if (value === undefined)
+        delete filled[key];
+      else
+        filled[key] = value;
+    }
+    return { context: filled };
+  };
+}

package/dist/core/output/coerce.js

@@ -0,0 +1,38 @@
+import { toOpenAPI } from "../openapi/openapi.js";
+const scalarTypes = new WeakMap;
+function scalarTypesOf(blueprint) {
+  let types = scalarTypes.get(blueprint);
+  if (!types) {
+    const schema = toOpenAPI(blueprint);
+    const found = {};
+    for (const [key, property] of Object.entries(schema.properties ?? {})) {
+      found[key] = [property.type ?? []].flat();
+    }
+    types = Object.freeze(found);
+    scalarTypes.set(blueprint, types);
+  }
+  return types;
+}
+function coerce(text, types) {
+  if (!types || types.includes("string"))
+    return text;
+  const trimmed = text.trim();
+  if (types.includes("boolean") && (trimmed === "true" || trimmed === "false")) {
+    return trimmed === "true";
+  }
+  if (types.includes("integer") || types.includes("number")) {
+    const number = trimmed === "" ? Number.NaN : Number(trimmed);
+    if (Number.isFinite(number))
+      return number;
+  }
+  return text;
+}
+export function coerceTextValues(blueprint, texts) {
+  const types = scalarTypesOf(blueprint);
+  const out = {};
+  for (const [key, value] of Object.entries(texts)) {
+    if (value !== undefined)
+      out[key] = coerce(value, types[key]);
+  }
+  return out;
+}

package/dist/core/output/exceptions.d.ts

@@ -6,3 +6,19 @@ export declare const InvalidOutputStage: import("../../index.js").DeclaredExcept
 export declare const DuplicateOperation: import("../../index.js").DeclaredExceptionClass<{
     readonly id: string;
 }>;
+/**
+ * An operation that declares its `access` was called without an
+ * authenticated caller: no credentials, or ones that were not accepted. A
+ * 401.
+ */
+export declare const Unauthenticated: import("../../index.js").DeclaredExceptionClass<undefined>;
+/**
+ * The caller is authenticated but may not call the operation: it lacks a
+ * scope the `access` of the operation asks for (`details.reason` is
+ * `"scope"`, with the missing `scopes`), or is not the owner (`"owner"`). A
+ * 403.
+ */
+export declare const Forbidden: import("../../index.js").DeclaredExceptionClass<{
+    readonly reason: "scope" | "owner";
+    readonly scopes?: readonly string[];
+}>;

package/dist/core/output/exceptions.js

@@ -0,0 +1,22 @@
+import { ExceptionLayers } from "../exception/enums/exception-layers.js";
+import { exceptionOf } from "../exception/exception.js";
+export const InvalidOutputStage = exceptionOf({
+  layer: ExceptionLayers.Output,
+  name: "InvalidOutputStage",
+  message: ({ reason }) => reason
+});
+export const DuplicateOperation = exceptionOf({
+  layer: ExceptionLayers.Output,
+  name: "DuplicateOperation",
+  message: ({ id }) => `The operation "${id}" is declared twice.`
+});
+export const Unauthenticated = exceptionOf({
+  layer: ExceptionLayers.Output,
+  name: "Unauthenticated",
+  message: "Authentication is required."
+});
+export const Forbidden = exceptionOf({
+  layer: ExceptionLayers.Output,
+  name: "Forbidden",
+  message: (_details) => "The caller may not do this."
+});

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

@@ -0,0 +1,36 @@
+import type { CompileRoutesSettings, HttpOptions, RouteTable } from "./types/http.interface.js";
+import type { OperationDescriptor, StageContext } from "./types/output.interface.js";
+/** The option names of {@link HttpOptions}, for sinks that list their options. */
+export declare const HTTP_OPTION_KEYS: readonly ["basePath", "route", "responses", "requestId", "security", "docs", "debug", "context", "auth"];
+/**
+ * Why the {@link HttpOptions} are not valid, naming them `where.<option>`;
+ * `undefined` when they are. Other keys of `options` are not looked at.
+ */
+export declare function httpOptionsIssue(options: HttpOptions, where: string): string | undefined;
+/**
+ * The routes of `operations`, compiled once, for a sink that serves HTTP on
+ * any server: the sink routes each `method` and `path` to `handle` and sends
+ * the result as is. Everything a request needs is decided here, so a call
+ * only reads, coerces and runs:
+ *
+ * - The input is the JSON body of a `post`, `put` or `patch` and the query
+ *   of a `get` or `delete`, with the keys the route reads elsewhere over it:
+ *   `{name}` segments of the path, and the query keys, headers and cookies
+ *   the use case route declares. Text is coerced to the numbers and booleans
+ *   the input takes; the operation validates it (a 400 problem with `issues`).
+ * - The context comes from `context.headers` (coerced) and
+ *   `context.variables` (as is); a missing one leaves the key out.
+ * - An operation with an `access` other than `public` asks
+ *   `settings.authenticator` who calls; without one, or without credentials,
+ *   it is a 401.
+ * - Success is the route status with the response as JSON (sensitive values
+ *   masked by `toJSON`), or no body for `204`, plus the `responses` headers.
+ *   Errors are `application/problem+json`, with the status of `statusOf`
+ *   (the output `statuses` first). `requestId` puts the request id on every
+ *   result, `notFound` and `failure` included.
+ * - `docs.path` serves the `openapi` document of the same operations.
+ *
+ * Throws `InvalidOutputStage` (source `settings.source`) as `operationRoutes`
+ * does, and when `docs.path` is taken by a `get` route.
+ */
+export declare function compileRoutes(operations: readonly OperationDescriptor[], options: HttpOptions, context: StageContext, settings: CompileRoutesSettings): RouteTable;