@afora/core 0.0.8 → 0.0.11

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

@@ -2,6 +2,8 @@ import type { AnyBlueprint } from "../../blueprint/types/blueprint.interface.js"
 import type { AnyCommand } from "../../command/types/command.interface.js";
 import type { JsonValue } from "../../json.js";
 import type { Kind } from "../../symbols/kind.js";
+import type { AccessDeclaration, Principal } from "../../use-case/types/access.interface.js";
+import type { RouteDeclaration } from "../../use-case/types/route.interface.js";
 import type { AnyExceptionClass } from "../../use-case/use-case.js";
 /** The options of a stage: a JSON object. */
 export type StageOptions = {
@@ -9,9 +11,15 @@ export type StageOptions = {
 };
 /** An HTTP-style status by exception name. */
 export type OutputStatuses = Readonly<Record<string, number>>;
-/** The call of an operation: `context` is what the command (or use case) declares. */
+/**
+ * The call of an operation: `context` is what the command (or use case)
+ * declares, and `principal` is who calls, as the sink authenticated it
+ * (`null` or absent for an anonymous caller). An operation with an `access`
+ * checks the principal before it runs.
+ */
 export interface OperationCallOptions {
     readonly context?: unknown;
+    readonly principal?: Principal | null;
 }
 /**
  * One operation of a command, as an output sees it. Frozen; transforms change
@@ -39,9 +47,16 @@ export interface OperationDescriptor {
     readonly context?: AnyBlueprint;
     /** The `errors` of the use case. */
     readonly errors: readonly AnyExceptionClass[];
+    /** The route the use case declares (`route` or `@Route`), if any. */
+    readonly route?: RouteDeclaration;
+    /** Who may call it, as the use case declares (`access` or `@Access`), if it does. */
+    readonly access?: AccessDeclaration;
     /** Set by transforms; `{}` initially. */
     readonly meta: Readonly<Record<string, unknown>>;
-    /** `command.run(name, input, options)`. */
+    /**
+     * `command.run(name, input, { context })`, after the check of `access`:
+     * it rejects with `Unauthenticated` or `Forbidden` before anything runs.
+     */
     invoke(input: unknown, options?: OperationCallOptions): Promise<unknown>;
 }
 /** What `operationOf` can change. */
@@ -85,6 +100,11 @@ export type StageDescription = {
 } | {
     readonly kind: "opaque";
 };
+/**
+ * What `transformOf` takes: the `name` of the stage, the `apply` function that
+ * changes each operation (or removes it) and an optional `validate` of its
+ * options.
+ */
 export interface TransformSettings<Options extends object> {
     readonly name: string;
     /** Returns the operation, a changed copy, or `null` to remove it. */
@@ -92,15 +112,30 @@ export interface TransformSettings<Options extends object> {
     /** Why `options` cannot be used, or `undefined`. Checked when the stage is made. */
     readonly validate?: (options: Options) => string | undefined;
 }
-export interface SinkSettings<Result, Options extends object> {
+/**
+ * What `sinkOf` takes: the `name` of the stage, the `build` function that turns
+ * the operations into the result of the output (a server, a document...) and an
+ * optional `validate` of its options.
+ */
+export interface SinkSettings<Result, Options extends object, Hooks = never> {
     readonly name: string;
-    readonly build: (operations: readonly OperationDescriptor[], options: Options, context: StageContext) => Result;
+    /**
+     * `hooks` is the second argument the stage was made with: what cannot be
+     * JSON (functions, an instance of a server). It is not part of the
+     * description of the stage.
+     */
+    readonly build: (operations: readonly OperationDescriptor[], options: Options, context: StageContext, hooks: Hooks | undefined) => Result;
     /** Why `options` cannot be used, or `undefined`. Checked when the stage is made. */
     readonly validate?: (options: Options) => string | undefined;
 }
 /** Makes a stage from JSON options. */
 export type TransformFactory<Options extends object = StageOptions> = (options?: Options) => TransformStage<Options>;
-export type SinkFactory<Result = unknown, Options extends object = StageOptions> = (options?: Options) => SinkStage<Result, Options>;
+/**
+ * Makes a sink stage from JSON `options` and, second, `hooks`: what cannot be
+ * JSON (functions, an instance of a server), which the description of the stage
+ * leaves out. What `sinkOf` returns.
+ */
+export type SinkFactory<Result = unknown, Options extends object = StageOptions, Hooks = never> = (options?: Options, hooks?: Hooks) => SinkStage<Result, Options>;
 /** Any stage factory. */
 export type StageFactory = TransformFactory<any> | SinkFactory<any, any>;
 /** Stage factories by name. */
@@ -123,6 +158,11 @@ export interface OutputApplication {
 }
 /** What an output takes its commands from. */
 export type OutputSource = AnyCommand | OutputApplication;
+/**
+ * What `outputOf` takes: the `name` of the output, the `commands` it exposes
+ * (commands, applications or a mix), the `statuses` by exception name and the
+ * `pipe` of stages that transform its operations and end in a sink.
+ */
 export interface OutputSettings<Pipe extends readonly Stage[]> {
     readonly name: string;
     /** The commands the output exposes: commands, applications (all their commands) or a mix. */
@@ -164,6 +204,10 @@ export interface Problem {
     /** Only with `debug`. */
     readonly trace?: string;
 }
+/**
+ * What `problemOf` takes: the HTTP `status` of the problem and `debug`, which
+ * adds the `trace` and the real `detail` of a 5xx.
+ */
 export interface ProblemOptions {
     readonly status: number;
     readonly debug?: boolean;

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

@@ -1,6 +1,31 @@
 import type { Exception } from "../exception/exception.js";
-import type { Issue } from "./types/parse.interface.js";
-/** `issue` with a `cause` that is built the first time it is read, and kept. */
-export declare function withLazyCause(issue: Issue, build: () => Exception): Issue;
+import type { Issue, IssueCode } from "./types/parse.interface.js";
+/**
+ * What a step gives back, in place of a value, for a value it rejects; the
+ * issues are then found where the step says, so a valid value costs no result
+ * object.
+ * @internal
+ */
+export declare const REJECTED: unique symbol;
+/** Who knows the exception an issue stands for, and builds it only when asked. */
+export interface IssueOrigin {
+    exception(): Exception;
+}
+/**
+ * An issue whose `cause` is built the first time it is read, by its origin,
+ * which keeps it: every issue of one origin has the same cause. Its own keys
+ * are those of any issue, `cause` is not one of them.
+ */
+export declare class LazyIssue implements Issue {
+    #private;
+    readonly message: string;
+    readonly path: readonly (string | number)[];
+    readonly code: IssueCode;
+    readonly source: string;
+    constructor(message: string, path: readonly (string | number)[], code: IssueCode, source: string, origin: IssueOrigin);
+    get cause(): Exception;
+    /** A copy of the issue at `path`, with the same cause. */
+    at(path: readonly (string | number)[]): LazyIssue;
+}
 /** A copy of `issue` at `path`, with the same `cause`, built lazily or not. */
 export declare function movedIssue(issue: Issue, path: readonly (string | number)[]): Issue;

package/dist/core/parse/issue.js

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

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

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

package/dist/core/parse/parse.js

@@ -0,0 +1,323 @@
+import { isBlueprint } from "../blueprint/is-blueprint.js";
+import { isBlueprintList } from "../blueprint/list.js";
+import { recordFieldOf } from "../blueprint/record-field.js";
+import { isBlueprintVariant } from "../blueprint/variant.js";
+import {
+  AbstractProperty,
+  parsingDefinitionOf
+} from "../property/abstract-property.js";
+import { parserOf, takeRejectionIssues } from "../property/define-property.js";
+import { isProperty } from "../property/is-property.js";
+import { recordNameOf } from "../record/name.js";
+import { movedIssue, REJECTED } from "./issue.js";
+const entriesOf = new WeakMap;
+export function fieldsOf(properties) {
+  let entries = entriesOf.get(properties);
+  if (!entries) {
+    entries = Object.entries(properties);
+    entriesOf.set(properties, entries);
+  }
+  return entries;
+}
+export function isPlainObject(value) {
+  if (typeof value !== "object" || value === null)
+    return false;
+  const prototype = Object.getPrototypeOf(value);
+  return prototype === Object.prototype || prototype === null;
+}
+const PROPERTY = 0;
+const LIST = 1;
+const BLUEPRINT = 2;
+const RECORD = 3;
+const UNDECLARED_FIELD = 4;
+const VARIANT = 5;
+function stepOf(field) {
+  const record = recordFieldOf(field);
+  const kind = isBlueprintList(field) ? LIST : isBlueprint(field) ? BLUEPRINT : isBlueprintVariant(field) ? VARIANT : record ? RECORD : isProperty(field) ? PROPERTY : UNDECLARED_FIELD;
+  return {
+    kind,
+    property: kind === PROPERTY ? field : undefined,
+    parser: undefined,
+    list: kind === LIST ? field : undefined,
+    item: undefined,
+    blueprint: kind === BLUEPRINT ? field : undefined,
+    collection: undefined,
+    record: kind === RECORD ? record?.record : undefined,
+    optionalRecord: kind === RECORD && record?.optional === true,
+    variant: kind === VARIANT ? field : undefined,
+    variants: undefined
+  };
+}
+const UNDECLARED = {
+  kind: UNDECLARED_FIELD,
+  property: undefined,
+  parser: undefined,
+  list: undefined,
+  item: undefined,
+  blueprint: undefined,
+  collection: undefined,
+  record: undefined,
+  optionalRecord: false,
+  variant: undefined,
+  variants: undefined
+};
+const steps = new WeakMap;
+function keptStepOf(field) {
+  if (typeof field !== "object" && typeof field !== "function" || field === null) {
+    return UNDECLARED;
+  }
+  let step = steps.get(field);
+  if (!step) {
+    step = stepOf(field);
+    steps.set(field, step);
+  }
+  return step;
+}
+const collections = new WeakMap;
+function collectionOf(properties) {
+  let collection = collections.get(properties);
+  if (!collection) {
+    const fields = fieldsOf(properties);
+    collection = {
+      properties,
+      names: fields.map(([name]) => name),
+      steps: fields.map(([, field]) => keptStepOf(field))
+    };
+    collections.set(properties, collection);
+  }
+  return collection;
+}
+function runOf(base, source) {
+  return { source, base, keys: [], issues: undefined };
+}
+function pathOf(run, depth) {
+  const { base, keys } = run;
+  const path = base.length === 0 ? [] : [...base];
+  for (let index = 0;index < depth; index++) {
+    path.push(keys[index]);
+  }
+  return path;
+}
+function reject(run, code, message, path) {
+  run.issues ??= [];
+  run.issues.push({ code, message, path, source: run.source });
+  return REJECTED;
+}
+function resultOf(run, handled) {
+  return handled === REJECTED ? { issues: run.issues ?? [] } : { value: handled };
+}
+export function parseCollection(properties, value, path, source) {
+  const run = runOf(path, source);
+  return resultOf(run, collectionAt(collectionOf(properties), value, run, 0));
+}
+const ROOT = Object.freeze([]);
+export function collectionParserOf(properties, source) {
+  let collection;
+  return (value, vouched, complete) => {
+    collection ??= collectionOf(properties);
+    const run = runOf(ROOT, source);
+    return resultOf(run, collectionAt(collection, value, run, 0, vouched, undefined, complete));
+  };
+}
+function collectionAt(collection, value, run, depth, vouched, tag, complete) {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    return reject(run, "invalid_type", "must be an object", pathOf(run, depth));
+  }
+  const { properties, names, steps } = collection;
+  let rejected = false;
+  const keys = Object.keys(value);
+  for (let index = 0;index < keys.length; index++) {
+    const name = keys[index];
+    if (name === names[index] || name === tag || Object.hasOwn(properties, name)) {
+      continue;
+    }
+    rejected = true;
+    reject(run, "undeclared_key", "is not declared", [
+      ...pathOf(run, depth),
+      name
+    ]);
+  }
+  const handled = tag === undefined ? {} : { [tag]: value[tag] };
+  const first = vouched?.[0];
+  const second = vouched?.[1];
+  const third = vouched?.[2];
+  for (let index = 0;index < names.length; index++) {
+    const name = names[index];
+    if (vouched !== undefined && (name === first || name === second || name === third || vouched.length > 3 && vouched.includes(name))) {
+      handled[name] = value[name];
+      continue;
+    }
+    run.keys[depth] = name;
+    const item = fieldAt(steps[index], value[name], run, depth + 1);
+    if (item === REJECTED)
+      rejected = true;
+    else if (item !== undefined)
+      handled[name] = item;
+  }
+  if (!rejected && complete !== undefined) {
+    for (const name of complete(handled) ?? []) {
+      run.keys[depth] = name;
+      const item = fieldAt(steps[names.indexOf(name)], handled[name], run, depth + 1);
+      if (item === REJECTED)
+        rejected = true;
+      else if (item !== undefined)
+        handled[name] = item;
+    }
+  }
+  return rejected ? REJECTED : Object.freeze(handled);
+}
+export function parseField(field, value, path, source) {
+  const run = runOf(path, source);
+  return resultOf(run, fieldAt(keptStepOf(field), value, run, 0));
+}
+const DECLARED_SAFE_PARSE = AbstractProperty.safeParse;
+function fieldAt(step, value, run, depth) {
+  switch (step.kind) {
+    case PROPERTY:
+      return propertyAt(step, value, run, depth);
+    case LIST: {
+      const list = step.list;
+      if (value === undefined) {
+        return list.optional ? value : required(run, depth);
+      }
+      if (!Array.isArray(value)) {
+        return reject(run, "invalid_type", "must be an array", pathOf(run, depth));
+      }
+      const { minItems, maxItems } = list;
+      let rejected = false;
+      if (minItems !== undefined && value.length < minItems || maxItems !== undefined && value.length > maxItems) {
+        rejected = true;
+        const path = pathOf(run, depth);
+        if (minItems !== undefined && value.length < minItems) {
+          reject(run, "too_few_items", `must have at least ${minItems} items`, path);
+        }
+        if (maxItems !== undefined && value.length > maxItems) {
+          reject(run, "too_many_items", `must have at most ${maxItems} items`, path);
+        }
+      }
+      step.item ??= keptStepOf(list.item);
+      const { item } = step;
+      const items = [];
+      for (let index = 0;index < value.length; index++) {
+        run.keys[depth] = index;
+        const handled = fieldAt(item, value[index], run, depth + 1);
+        if (handled === REJECTED)
+          rejected = true;
+        else
+          items.push(handled);
+      }
+      return rejected ? REJECTED : Object.freeze(items);
+    }
+    case BLUEPRINT: {
+      const blueprint = step.blueprint;
+      if (value === undefined) {
+        return blueprint.optional ? value : required(run, depth);
+      }
+      step.collection ??= collectionOf(blueprint.properties);
+      return collectionAt(step.collection, value, run, depth);
+    }
+    case VARIANT: {
+      const variant = step.variant;
+      if (value === undefined) {
+        return variant.optional ? value : required(run, depth);
+      }
+      if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        return reject(run, "invalid_type", "must be an object", pathOf(run, depth));
+      }
+      let { variants } = step;
+      if (variants === undefined) {
+        variants = new Map;
+        const declared = variant.variants;
+        for (const tag of Object.keys(declared)) {
+          const one = declared[tag];
+          variants.set(tag, isBlueprint(one) ? collectionOf(one.properties) : one);
+        }
+        step.variants = variants;
+      }
+      if (!isPlainObject(value)) {
+        for (const one of variants.values()) {
+          if (typeof one === "function" && value instanceof one)
+            return value;
+        }
+      }
+      const { key } = variant;
+      const tag = value[key];
+      const named = typeof tag === "string" ? variants.get(tag) : undefined;
+      if (named === undefined) {
+        return reject(run, "invalid_value", "must be equal to one of the allowed values", [...pathOf(run, depth), key]);
+      }
+      if (typeof named !== "function") {
+        return collectionAt(named, value, run, depth, undefined, key);
+      }
+      const { [key]: _name, ...input } = value;
+      const result = named.safeParse(input);
+      if (!result.issues)
+        return result.value;
+      const path = pathOf(run, depth);
+      run.issues ??= [];
+      for (const issue of result.issues) {
+        run.issues.push(movedIssue(issue, [...path, ...issue.path]));
+      }
+      return REJECTED;
+    }
+    case RECORD: {
+      const Record = step.record;
+      if (value === undefined) {
+        return step.optionalRecord ? value : required(run, depth);
+      }
+      if (value instanceof Record)
+        return value;
+      if (!isPlainObject(value)) {
+        return reject(run, "not_record", `must be an instance of record "${recordNameOf(Record)}"`, pathOf(run, depth));
+      }
+      const result = Record.safeParse(value);
+      if (!result.issues)
+        return result.value;
+      const path = pathOf(run, depth);
+      run.issues ??= [];
+      for (const issue of result.issues) {
+        run.issues.push(movedIssue(issue, [...path, ...issue.path]));
+      }
+      return REJECTED;
+    }
+    default:
+      return reject(run, "undeclared_key", "is not declared", pathOf(run, depth));
+  }
+}
+function required(run, depth) {
+  return reject(run, "required", "is required", pathOf(run, depth));
+}
+function propertyAt(step, value, run, depth) {
+  const property = step.property;
+  if (property.safeParse === DECLARED_SAFE_PARSE) {
+    let { parser } = step;
+    if (parser === undefined) {
+      parser = parserOf(parsingDefinitionOf(property)) ?? null;
+      step.parser = parser;
+    }
+    if (parser !== null) {
+      const handled = parser(value);
+      if (handled !== REJECTED)
+        return handled;
+      run.issues ??= [];
+      takeRejectionIssues(pathOf(run, depth), run.issues);
+      return REJECTED;
+    }
+  }
+  const result = property.safeParse(value);
+  if (!result.issues)
+    return result.value;
+  const path = pathOf(run, depth);
+  run.issues ??= [];
+  if (result.issues.some((issue) => Object.isFrozen(issue))) {
+    for (const issue of result.issues) {
+      run.issues.push(movedIssue(issue, [...path, ...issue.path]));
+    }
+  } else {
+    for (const issue of result.issues) {
+      issue.path = [...path, ...issue.path];
+      run.issues.push(issue);
+    }
+  }
+  return REJECTED;
+}

package/dist/core/parse/strip.js

@@ -0,0 +1,48 @@
+import { isBlueprint } from "../blueprint/is-blueprint.js";
+import { isBlueprintList } from "../blueprint/list.js";
+import { recordFieldOf } from "../blueprint/record-field.js";
+import { isBlueprintVariant, variantOfValue } from "../blueprint/variant.js";
+import { fieldsOf, isPlainObject } from "./parse.js";
+function collectionOf(properties, value) {
+  if (!isPlainObject(value))
+    return value;
+  const kept = {};
+  for (const [name, field] of fieldsOf(properties)) {
+    if (!Object.hasOwn(value, name))
+      continue;
+    const item = fieldOf(field, value[name]);
+    if (item === undefined)
+      continue;
+    Object.defineProperty(kept, name, {
+      value: item,
+      enumerable: true,
+      writable: true,
+      configurable: true
+    });
+  }
+  return kept;
+}
+function fieldOf(field, value) {
+  if (isBlueprintList(field)) {
+    return Array.isArray(value) ? value.map((item) => fieldOf(field.item, item)) : value;
+  }
+  if (isBlueprint(field))
+    return collectionOf(field.properties, value);
+  if (isBlueprintVariant(field)) {
+    const variant = variantOfValue(field, value);
+    if (!variant || !isPlainObject(value))
+      return value;
+    return {
+      [field.key]: value[field.key],
+      ...collectionOf(variant.properties, value)
+    };
+  }
+  const record = recordFieldOf(field);
+  if (record) {
+    return collectionOf(record.record.blueprint.properties, value);
+  }
+  return value;
+}
+export function stripUndeclared(shape, value) {
+  return fieldOf(shape, value);
+}

package/dist/core/property/abstract-property.d.ts

@@ -9,6 +9,15 @@ import type { AnyPropertyConstructor } from "./types/property-collection.type.js
 import type { PropertyValue } from "./types/property-constructor.type.js";
 import type { PropertyOptions } from "./types/property-options.interface.js";
 import type { IPropertyType } from "./types/property-type.interface.js";
+/**
+ * The definition `Class` parses with. It does not depend on any member the
+ * constructor sets, and `parse` leaves nothing on it that the next one reads,
+ * so every `safeParse` shares one.
+ * @internal
+ */
+export declare function parsingDefinitionOf(Class: {
+    prototype: object;
+}): AbstractDefineProperty<TSchema>;
 /** A property instance; `Value` is the value of its schema, as in `ISchema`. */
 export declare abstract class AbstractProperty<SchemaType extends TSchema, Value = Static<SchemaType>> implements IProperty<SchemaType, Value> {
     get [State](): PropertyStates;

package/dist/core/property/abstract-property.js

@@ -0,0 +1,37 @@
+import { standardOfClass } from "../standard/standard.js";
+import { Demo } from "../symbols/demo.js";
+import { State } from "../symbols/state.js";
+import { refinePropertyOf } from "./refine.js";
+const parsingDefinitions = new WeakMap;
+export function parsingDefinitionOf(Class) {
+  let definition = parsingDefinitions.get(Class);
+  if (!definition) {
+    definition = Object.create(Class.prototype).createDefinition();
+    parsingDefinitions.set(Class, definition);
+  }
+  return definition;
+}
+
+export class AbstractProperty {
+  get [State]() {
+    return this.definition[State];
+  }
+  definition;
+  value;
+  constructor(value) {
+    this.definition = this.createDefinition();
+    this.value = this.definition.make(value === Demo ? this.definition.type[Demo] : value);
+  }
+  static demo() {
+    return new this(Demo);
+  }
+  static safeParse(value) {
+    return parsingDefinitionOf(this).parse(value);
+  }
+  static with(options) {
+    return refinePropertyOf(this, options);
+  }
+  static get "~standard"() {
+    return standardOfClass(this);
+  }
+}