@afora/core 0.0.9 → 0.0.11

package/dist/core/schema/schema.js

@@ -0,0 +1,542 @@
+import Compile from "typebox/compile";
+import { Locale, Settings } from "typebox/system";
+const KEPT_KEYWORDS = new Set([
+  "type",
+  "required",
+  "$ref",
+  "$id",
+  "$anchor",
+  "$dynamicRef",
+  "$dynamicAnchor"
+]);
+const SCHEMA_KEYWORDS = new Set([
+  "additionalProperties",
+  "items",
+  "additionalItems",
+  "prefixItems",
+  "anyOf",
+  "oneOf",
+  "allOf",
+  "contains",
+  "propertyNames"
+]);
+const SCHEMA_MAP_KEYWORDS = new Set([
+  "properties",
+  "patternProperties",
+  "dependentSchemas",
+  "$defs",
+  "definitions"
+]);
+const JSON_TYPES = new Set([
+  "null",
+  "array",
+  "string",
+  "number",
+  "boolean",
+  "object"
+]);
+function typeOfValue(value) {
+  const type = value === null ? "null" : Array.isArray(value) ? "array" : typeof value;
+  return JSON_TYPES.has(type) ? type : undefined;
+}
+function shapeOf(schema) {
+  if (Array.isArray(schema))
+    return schema.map(shapeOf);
+  if (typeof schema !== "object" || schema === null)
+    return schema;
+  const shape = {};
+  for (const [key, value] of Object.entries(schema)) {
+    if (KEPT_KEYWORDS.has(key))
+      shape[key] = value;
+    else if (SCHEMA_KEYWORDS.has(key))
+      shape[key] = shapeOf(value);
+    else if (SCHEMA_MAP_KEYWORDS.has(key)) {
+      shape[key] = Object.fromEntries(Object.entries(value).map(([name, item]) => [
+        name,
+        shapeOf(item)
+      ]));
+    }
+  }
+  if (!("type" in shape)) {
+    const values = "const" in schema ? [schema.const] : schema.enum;
+    if (Array.isArray(values)) {
+      const types = values.map(typeOfValue);
+      if (types.every((type) => type !== undefined)) {
+        shape.type = [...new Set(types)];
+      }
+    }
+  }
+  return shape;
+}
+export function describeError(error) {
+  return `${error.instancePath || "/"}: ${error.message}`;
+}
+const INERT_KEYWORDS = new Set([
+  "~kind",
+  "~optional",
+  "~readonly",
+  "~unsafe",
+  "title",
+  "description",
+  "default",
+  "examples",
+  "deprecated",
+  "readOnly",
+  "writeOnly",
+  "$comment"
+]);
+const isNumeric = (value) => typeof value === "number" || typeof value === "bigint";
+const LEAF_KEYWORDS = [
+  [
+    "type",
+    (value) => typeof value === "string" || Array.isArray(value) && value.every((item) => typeof item === "string"),
+    (type) => ({ type })
+  ],
+  ["minLength", (value) => typeof value === "number", (limit) => ({ limit })],
+  ["maxLength", (value) => typeof value === "number", (limit) => ({ limit })],
+  ["format", (value) => typeof value === "string", (format) => ({ format })],
+  ["pattern", (value) => typeof value === "string", (pattern) => ({ pattern })],
+  ["exclusiveMinimum", isNumeric, (limit) => ({ comparison: ">", limit })],
+  ["exclusiveMaximum", isNumeric, (limit) => ({ comparison: "<", limit })],
+  ["minimum", isNumeric, (limit) => ({ comparison: ">=", limit })],
+  ["maximum", isNumeric, (limit) => ({ comparison: "<=", limit })],
+  ["multipleOf", isNumeric, (multipleOf) => ({ multipleOf })],
+  ["const", () => true, (allowedValue) => ({ allowedValue })],
+  ["enum", Array.isArray, (allowedValues) => ({ allowedValues })]
+];
+const LEAF_KEYWORD_NAMES = new Set(LEAF_KEYWORDS.map(([keyword]) => keyword));
+function leafChecksOf(schema) {
+  if (typeof schema !== "object" || schema === null)
+    return;
+  for (const key of Reflect.ownKeys(schema)) {
+    if (!LEAF_KEYWORD_NAMES.has(key) && !INERT_KEYWORDS.has(key)) {
+      return;
+    }
+  }
+  const checks = [];
+  for (const [keyword, reads, params] of LEAF_KEYWORDS) {
+    if (!Object.hasOwn(schema, keyword))
+      continue;
+    const value = schema[keyword];
+    if (!reads(value))
+      return;
+    const validator = Compile({ [keyword]: value });
+    checks.push({
+      keyword,
+      params: params(value),
+      check: (candidate) => validator.Check(candidate)
+    });
+  }
+  return checks;
+}
+const leafChecks = new WeakMap;
+function addError(sink, keyword, schemaPath, instancePath, params) {
+  if (sink.errors.length < sink.max) {
+    const error = { keyword, schemaPath, instancePath, params };
+    sink.errors.push({ ...error, message: sink.locale(error) });
+  }
+  return false;
+}
+const segmentOf = (key) => key.replaceAll("~", "~0").replaceAll("/", "~1");
+const hasKey = (value, key) => key === "__proto__" || key === "constructor" || key === "prototype" ? Object.hasOwn(value, key) : (key in value);
+const STRUCTURE_KEYWORDS = new Set([
+  "required",
+  "properties",
+  "additionalProperties",
+  "items",
+  "minItems",
+  "maxItems",
+  "anyOf"
+]);
+function explainerOf(schema) {
+  if (!isRecord(schema))
+    return;
+  for (const key of Reflect.ownKeys(schema)) {
+    if (!LEAF_KEYWORD_NAMES.has(key) && !INERT_KEYWORDS.has(key) && !STRUCTURE_KEYWORDS.has(key)) {
+      return;
+    }
+  }
+  let type;
+  const leaves = [];
+  for (const [keyword, reads, params] of LEAF_KEYWORDS) {
+    if (!Object.hasOwn(schema, keyword))
+      continue;
+    const value = schema[keyword];
+    if (!reads(value))
+      return;
+    const validator = Compile({ [keyword]: value });
+    const leaf = {
+      keyword,
+      params: params(value),
+      check: (candidate) => validator.Check(candidate)
+    };
+    if (keyword === "type")
+      type = leaf;
+    else
+      leaves.push(leaf);
+  }
+  let required;
+  if (Object.hasOwn(schema, "required")) {
+    const value = schema.required;
+    if (!Array.isArray(value))
+      return;
+    if (!value.every((key) => typeof key === "string"))
+      return;
+    required = value;
+  }
+  let properties;
+  if (Object.hasOwn(schema, "properties")) {
+    if (!isRecord(schema.properties))
+      return;
+    const list = [];
+    for (const [key, property] of Object.entries(schema.properties)) {
+      const explain = explainerOf(property);
+      if (!explain)
+        return;
+      list.push({
+        key,
+        segment: segmentOf(key),
+        required: required?.includes(key) ?? false,
+        explain
+      });
+    }
+    properties = list;
+  }
+  let declared;
+  if (Object.hasOwn(schema, "additionalProperties")) {
+    if (schema.additionalProperties !== false)
+      return;
+    declared = new Set(properties?.map(({ key }) => key));
+  }
+  let items;
+  if (Object.hasOwn(schema, "items")) {
+    items = explainerOf(schema.items);
+    if (!items)
+      return;
+  }
+  const limits = [];
+  for (const keyword of ["minItems", "maxItems"]) {
+    if (!Object.hasOwn(schema, keyword))
+      continue;
+    const limit = schema[keyword];
+    if (typeof limit !== "number")
+      return;
+    const validator = Compile({ [keyword]: limit });
+    limits.push({
+      keyword,
+      params: { limit },
+      check: (candidate) => validator.Check(candidate)
+    });
+  }
+  let anyOf;
+  if (Object.hasOwn(schema, "anyOf")) {
+    if (!Array.isArray(schema.anyOf))
+      return;
+    const list = [];
+    for (const option of schema.anyOf) {
+      const explain = explainerOf(option);
+      if (!explain)
+        return;
+      list.push(explain);
+    }
+    anyOf = list;
+  }
+  return (value, schemaPath, instancePath, sink) => {
+    if (sink.errors.length >= sink.max)
+      return false;
+    let accepted = true;
+    if (type && !type.check(value)) {
+      accepted = addError(sink, "type", schemaPath, instancePath, type.params);
+    }
+    if (isRecord(value)) {
+      if (required) {
+        const missing = required.filter((key) => !hasKey(value, key));
+        if (missing.length > 0) {
+          accepted = addError(sink, "required", schemaPath, instancePath, {
+            requiredProperties: missing
+          });
+        }
+      }
+      if (declared) {
+        const undeclared = [];
+        for (const key of Object.getOwnPropertyNames(value)) {
+          if (declared.has(key))
+            continue;
+          undeclared.push(key);
+          addError(sink, "boolean", `${schemaPath}/additionalProperties`, `${instancePath}/${segmentOf(key)}`, {});
+        }
+        if (undeclared.length > 0) {
+          accepted = addError(sink, "additionalProperties", schemaPath, instancePath, { additionalProperties: undeclared });
+        }
+      }
+      if (properties) {
+        for (const property of properties) {
+          const { key } = property;
+          if (!property.required && !sink.exact && value[key] === undefined) {
+            continue;
+          }
+          if (!hasKey(value, key))
+            continue;
+          const explained = property.explain(value[key], `${schemaPath}/properties/${property.segment}`, `${instancePath}/${property.segment}`, sink);
+          if (!explained)
+            accepted = false;
+        }
+      }
+    }
+    if (Array.isArray(value)) {
+      if (items) {
+        const explain = items;
+        value.forEach((item, index) => {
+          const explained = explain(item, `${schemaPath}/items`, `${instancePath}/${index}`, sink);
+          if (!explained)
+            accepted = false;
+        });
+      }
+      for (const limit of limits) {
+        if (limit.check(value))
+          continue;
+        accepted = addError(sink, limit.keyword, schemaPath, instancePath, limit.params);
+      }
+    }
+    for (const leaf of leaves) {
+      if (leaf.check(value))
+        continue;
+      accepted = addError(sink, leaf.keyword, schemaPath, instancePath, leaf.params);
+    }
+    if (anyOf) {
+      const failed = [];
+      let matched = false;
+      for (const [index, explain] of anyOf.entries()) {
+        const own = { ...sink, errors: [] };
+        const explained = explain(value, `${schemaPath}/anyOf/${index}`, instancePath, own);
+        if (explained)
+          matched = true;
+        else
+          failed.push(own.errors);
+      }
+      if (!matched) {
+        for (const errors of failed) {
+          for (const error of errors) {
+            if (sink.errors.length < sink.max)
+              sink.errors.push(error);
+          }
+        }
+        accepted = addError(sink, "anyOf", schemaPath, instancePath, {});
+      }
+    }
+    return accepted;
+  };
+}
+const explainers = new WeakMap;
+function sinkOf() {
+  const settings = Settings.Get();
+  const locale = Locale.Get();
+  if (typeof settings?.maxErrors !== "number" || typeof locale !== "function") {
+    return;
+  }
+  return {
+    errors: [],
+    max: settings.maxErrors,
+    locale,
+    exact: settings.exactOptionalPropertyTypes === true
+  };
+}
+const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+function literalOf(variant, key) {
+  if (!isRecord(variant) || variant.type !== "object")
+    return;
+  const { properties, required } = variant;
+  if (!isRecord(properties) || !Array.isArray(required))
+    return;
+  if (!required.includes(key) || !Object.hasOwn(properties, key)) {
+    return;
+  }
+  const property = properties[key];
+  if (!isRecord(property) || !Object.hasOwn(property, "const"))
+    return;
+  const value = property.const;
+  return typeof value === "string" || typeof value === "number" || typeof value === "boolean" ? { value } : undefined;
+}
+function discriminatedUnionOf(schema) {
+  if (!isRecord(schema) || !Array.isArray(schema.anyOf))
+    return;
+  for (const key of Reflect.ownKeys(schema)) {
+    if (key !== "anyOf" && !INERT_KEYWORDS.has(key))
+      return;
+  }
+  const options = schema.anyOf;
+  const [first] = options;
+  if (options.length < 2 || !isRecord(first) || !isRecord(first.properties)) {
+    return;
+  }
+  for (const key of Object.keys(first.properties)) {
+    const variants = new Map;
+    for (const [index, option] of options.entries()) {
+      const literal = literalOf(option, key);
+      if (!literal || variants.has(literal.value))
+        break;
+      let validator;
+      variants.set(literal.value, {
+        index,
+        explain: explainerOf(option),
+        Errors: (value) => {
+          validator ??= Compile(option);
+          return validator.Errors(value);
+        }
+      });
+    }
+    if (variants.size !== options.length)
+      continue;
+    return {
+      key,
+      segment: segmentOf(key),
+      allowedValues: [...variants.keys()],
+      variants
+    };
+  }
+  return;
+}
+const discriminatedUnions = new WeakMap;
+function errorsOfVariant(union, value) {
+  const variant = union.variants.get(value[union.key]);
+  if (variant) {
+    const at = `#/anyOf/${variant.index}`;
+    const sink = variant.explain && sinkOf();
+    if (variant.explain && sink) {
+      variant.explain(value, at, "", sink);
+      return sink.errors.length > 0 ? sink.errors : undefined;
+    }
+    const errors = variant.Errors(value);
+    if (errors.length === 0)
+      return;
+    return errors.map((error) => ({
+      ...error,
+      schemaPath: at + error.schemaPath.slice(1)
+    }));
+  }
+  const maxErrors = Settings.Get().maxErrors;
+  const locale = Locale.Get();
+  if (typeof maxErrors !== "number" || typeof locale !== "function") {
+    return;
+  }
+  if (maxErrors < 1)
+    return [];
+  const error = {
+    keyword: "enum",
+    schemaPath: "#/anyOf",
+    instancePath: `/${union.segment}`,
+    params: { allowedValues: union.allowedValues }
+  };
+  return [{ ...error, message: locale(error) }];
+}
+export function errorsOfSchema(schema, value) {
+  let checks = leafChecks.get(schema);
+  if (checks === undefined) {
+    checks = leafChecksOf(rawTypeOf(schema)) ?? null;
+    leafChecks.set(schema, checks);
+  }
+  const maxErrors = Settings.Get().maxErrors;
+  const locale = Locale.Get();
+  if (checks !== null && typeof maxErrors === "number" && typeof locale === "function") {
+    const errors = [];
+    for (const { keyword, params, check } of checks) {
+      if (errors.length >= maxErrors)
+        break;
+      if (check(value))
+        continue;
+      const error = { keyword, schemaPath: "#", instancePath: "", params };
+      errors.push({ ...error, message: locale(error) });
+    }
+    if (errors.length > 0)
+      return errors;
+  }
+  if (checks === null && isRecord(value)) {
+    let union = discriminatedUnions.get(schema);
+    if (union === undefined) {
+      union = discriminatedUnionOf(rawTypeOf(schema)) ?? null;
+      discriminatedUnions.set(schema, union);
+    }
+    const errors = union && errorsOfVariant(union, value);
+    if (errors)
+      return errors;
+  }
+  if (checks === null) {
+    let explain = explainers.get(schema);
+    if (explain === undefined) {
+      explain = explainerOf(rawTypeOf(schema)) ?? null;
+      explainers.set(schema, explain);
+    }
+    const sink = explain && sinkOf();
+    if (explain && sink) {
+      explain(value, "#", "", sink);
+      if (sink.errors.length > 0)
+        return sink.errors;
+    }
+  }
+  return schema.type.Errors(value);
+}
+
+class AbstractSchema {
+  _type;
+  validator;
+  shapeValidator;
+  constructor(_type) {
+    this._type = _type;
+  }
+  match(value) {
+    return this.type.Check(value);
+  }
+  matchShape(value) {
+    this.shapeValidator ??= Compile(shapeOf(this._type));
+    return this.shapeValidator.Check(value);
+  }
+  checks() {
+    const validator = this.type;
+    const shape = shapeOf(this._type);
+    if (shape.type === "string" && Object.keys(shape).length === 1) {
+      return {
+        match: (value) => validator.Check(value),
+        matchShape: (value) => typeof value === "string"
+      };
+    }
+    return {
+      match: (value) => validator.Check(value),
+      matchShape: (value) => this.matchShape(value)
+    };
+  }
+  errors(value) {
+    return this.type.Errors(value).map(describeError);
+  }
+  toString() {
+    return JSON.stringify(this._type);
+  }
+  get type() {
+    this.validator ??= Compile(this._type);
+    return this.validator;
+  }
+}
+export function checksOfSchema(schema) {
+  return schema instanceof AbstractSchema ? schema.checks() : {
+    match: (value) => schema.match(value),
+    matchShape: (value) => schema.matchShape(value)
+  };
+}
+export function rawTypeOf(schema) {
+  return schema instanceof AbstractSchema ? schema._type : schema.type.Type();
+}
+export function schemaOf(name, schema) {
+
+  class Schema extends AbstractSchema {
+    constructor(type = schema) {
+      super(type);
+    }
+    static fromString(value) {
+      return new Schema(JSON.parse(value));
+    }
+  }
+  Object.defineProperty(Schema, "name", { value: name });
+  Object.defineProperty(Schema, Symbol.for("nodejs.util.inspect.custom"), {
+    value: () => `@afora::schema:${name}`
+  });
+  return Schema;
+}

package/dist/core/standard/standard-schema.js

@@ -0,0 +1 @@
+export const STANDARD_VENDOR = "afora";

package/dist/core/standard/standard.js

@@ -0,0 +1,23 @@
+import { STANDARD_VENDOR } from "./standard-schema.js";
+function standardOf(parse) {
+  return Object.freeze({
+    version: 1,
+    vendor: STANDARD_VENDOR,
+    validate: parse
+  });
+}
+export function withStandard(target, parse) {
+  return Object.defineProperty(target, "~standard", {
+    value: standardOf(parse),
+    enumerable: false
+  });
+}
+const cache = new WeakMap;
+export function standardOfClass(Class) {
+  let standard = cache.get(Class);
+  if (!standard) {
+    standard = standardOf((value) => Class.safeParse(value));
+    cache.set(Class, standard);
+  }
+  return standard;
+}

package/dist/core/symbols/demo.d.ts

@@ -1 +1,5 @@
+/**
+ * Given to the constructor of a property in place of a value, it builds the
+ * instance from the `default` of the property, as `demo()` does.
+ */
 export declare const Demo: unique symbol;

package/dist/core/symbols/demo.js

@@ -0,0 +1 @@
+export const Demo = Symbol("demo");

package/dist/core/symbols/kind.js

@@ -0,0 +1 @@
+export const Kind = Symbol("kind");

package/dist/core/symbols/meta.js

@@ -0,0 +1 @@
+export const Meta = Symbol("meta");

package/dist/core/symbols/state.d.ts

@@ -1 +1,6 @@
+/**
+ * The key under which a property instance reports where it is in its pipeline,
+ * a `PropertyStates` value: declared, pre-handling, handling, after-handling,
+ * done.
+ */
 export declare const State: unique symbol;

package/dist/core/symbols/state.js

@@ -0,0 +1 @@
+export const State = Symbol("state");

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

@@ -0,0 +1,4 @@
+/** The `trace` of an application is not a tracer (`ITracer`). */
+export declare const InvalidTraceDeclaration: import("../../index.js").DeclaredExceptionClass<{
+    readonly reason: string;
+}>;

package/dist/core/tracing/exceptions.js

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

package/dist/core/tracing/tracing.d.ts

@@ -0,0 +1,72 @@
+import type { ExceptionLayers } from "../exception/enums/exception-layers.js";
+/**
+ * What a span carries: names and outcomes only, never an input, an argument,
+ * a response or any value of a record.
+ */
+export type TraceAttributes = Readonly<Record<string, string | number | boolean>>;
+/** How a span ended. */
+export type TraceStatus = "ok" | "error";
+/** A span afora started; it ends it once, with the attributes of the outcome. */
+export interface ITraceSpan {
+    end(status: TraceStatus, attributes: TraceAttributes): void;
+}
+/**
+ * What traces an application: a span per command operation, use case and
+ * repository call made through a use case. `@afora/otel` adapts an
+ * OpenTelemetry `Tracer` to it; `memoryTracer()` keeps the spans for tests.
+ */
+export interface ITracer {
+    /**
+     * Starts a span. `parent` is the span of the call that made this one (the
+     * command of a use case, the use case of a repository call), `undefined`
+     * for a call that starts a trace.
+     */
+    startSpan(name: string, attributes: TraceAttributes, parent: ITraceSpan | undefined): ITraceSpan;
+    /**
+     * Runs `run` with `span` as the current span, when the tracer has a notion
+     * of one (an OpenTelemetry context): what your code and the instrumented
+     * drivers start inside the call is nested in its span.
+     */
+    withSpan?<Result>(span: ITraceSpan, run: () => Result): Result;
+}
+/** Throws unless `value` can trace an application. */
+export declare function checkTracer(value: unknown): ITracer;
+/**
+ * Carries the tracer of an application, when it has a `trace`: on the
+ * application and on the use case classes it binds.
+ */
+export declare const ApplicationTracerKey: unique symbol;
+/**
+ * The tracer of a call: the one its scope carries, else the one of the
+ * application its class was bound by, else the started application's.
+ */
+export declare function resolveTracer(scoped: ITracer | undefined, owner: unknown): ITracer | undefined;
+/** Starts a span; a tracer that throws never breaks the call it traces. */
+export declare function startSpan(tracer: ITracer, name: string, attributes: TraceAttributes, parent: ITraceSpan | undefined): ITraceSpan | undefined;
+/** Runs `run` inside `span`, if the tracer can make it current. */
+export declare function runInSpan<Result>(tracer: ITracer, span: ITraceSpan, run: () => Result): Result;
+/** Ends a span that succeeded. */
+export declare function endSpan(span: ITraceSpan | undefined): void;
+/**
+ * Ends a span that failed, with the layer and name of the exception where it
+ * was first raised (`layer` and `UnexpectedError` for anything else thrown).
+ * Never its message, details or cause: they can hold values.
+ */
+export declare function failSpan(span: ITraceSpan | undefined, error: unknown, layer: ExceptionLayers): void;
+/** A span as `memoryTracer` keeps it. */
+export interface MemorySpan {
+    readonly name: string;
+    /** Those it started with, then those it ended with. */
+    readonly attributes: TraceAttributes;
+    readonly parent: MemorySpan | undefined;
+    /** `undefined` until it ends. */
+    readonly status: TraceStatus | undefined;
+}
+/** A tracer that keeps the spans, for tests. */
+export interface MemoryTracer extends ITracer {
+    /** Every span, in the order they started. */
+    readonly spans: readonly MemorySpan[];
+    clear(): void;
+}
+/** Keeps every span in `spans`, with its parent, for tests. */
+export declare function memoryTracer(): MemoryTracer;