@afora/core 0.0.8 → 0.0.11

package/dist/core/use-case/route.js

@@ -0,0 +1,200 @@
+import { toOpenAPI } from "../openapi/openapi.js";
+import { isProperty } from "../property/is-property.js";
+const ROUTE_METHODS = [
+  "get",
+  "post",
+  "put",
+  "patch",
+  "delete"
+];
+const ROUTE_SUCCESS_STATUSES = [
+  200,
+  201,
+  202,
+  204
+];
+const PARAMETER = /^\{([A-Za-z_][A-Za-z0-9_]*)\}$/;
+export const HEADER_NAME = /^[A-Za-z0-9!#$%&'*+.^_`|~-]+$/;
+export function isRoutePath(value, parameters = true) {
+  if (typeof value !== "string" || !value.startsWith("/"))
+    return false;
+  return value.split("/").every((segment) => parameters && PARAMETER.test(segment) || !/[{}?#\s:*]/.test(segment));
+}
+export function parametersOfPath(path) {
+  const names = [];
+  for (const segment of path.split("/")) {
+    const name = PARAMETER.exec(segment)?.[1];
+    if (name)
+      names.push(name);
+  }
+  return names;
+}
+export function isScalarSchema(schema) {
+  const types = [schema.type ?? []].flat();
+  return !types.some((type) => type === "object" || type === "array");
+}
+export function isScalarKey(blueprint, name) {
+  if (!Object.hasOwn(blueprint.properties, name))
+    return false;
+  const field = blueprint.properties[name];
+  return isProperty(field) && isScalarSchema(toOpenAPI(field));
+}
+function isObject(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+const ROUTE_KEYS = [
+  "method",
+  "path",
+  "status",
+  "query",
+  "headers",
+  "cookie",
+  "setCookie"
+];
+const COOKIE_KEYS = [
+  "name",
+  "httpOnly",
+  "secure",
+  "sameSite",
+  "path",
+  "domain",
+  "maxAge"
+];
+function cookieIssue(cookie, where) {
+  if (!isObject(cookie) || typeof cookie.name !== "string") {
+    return `Expected ${where} to be { name, httpOnly?, secure?, sameSite?, path?, domain?, maxAge? }.`;
+  }
+  for (const key of Object.keys(cookie)) {
+    if (!COOKIE_KEYS.includes(key))
+      return `${where} has no option "${key}".`;
+  }
+  if (!HEADER_NAME.test(cookie.name)) {
+    return `Expected ${where}.name to be the name of a cookie.`;
+  }
+  for (const key of ["httpOnly", "secure"]) {
+    if (cookie[key] !== undefined && typeof cookie[key] !== "boolean") {
+      return `Expected ${where}.${key} to be a boolean.`;
+    }
+  }
+  if (cookie.sameSite !== undefined && !["strict", "lax", "none"].includes(cookie.sameSite)) {
+    return `Expected ${where}.sameSite to be "strict", "lax" or "none".`;
+  }
+  if (cookie.sameSite === "none" && cookie.secure === false) {
+    return `${where}.sameSite "none" needs a secure cookie.`;
+  }
+  for (const key of ["path", "domain"]) {
+    const value = cookie[key];
+    if (value !== undefined && (typeof value !== "string" || value === "" || /[;\s]/.test(value))) {
+      return `Expected ${where}.${key} to be text without ";" or spaces.`;
+    }
+  }
+  if (cookie.maxAge !== undefined && (!Number.isInteger(cookie.maxAge) || cookie.maxAge < 0)) {
+    return `Expected ${where}.maxAge to be a whole number of seconds, 0 or more.`;
+  }
+  return;
+}
+export function routeDeclarationOf(route, blueprint, response) {
+  if (!isObject(route)) {
+    return "Expected route to be { method, path?, status?, query?, headers?, cookie?, setCookie? }.";
+  }
+  for (const key of Object.keys(route)) {
+    if (!ROUTE_KEYS.includes(key))
+      return `route has no option "${key}".`;
+  }
+  const method = typeof route.method === "string" ? route.method.toLowerCase() : undefined;
+  if (!ROUTE_METHODS.includes(method)) {
+    return `Expected route.method to be one of ${ROUTE_METHODS.join(", ")}.`;
+  }
+  const { path, status, query, headers, cookie, setCookie } = route;
+  const places = new Map;
+  const place = (key, where) => {
+    const taken = places.get(key);
+    if (taken !== undefined) {
+      return `route reads the input key "${key}" from two places: ${taken} and ${where}.`;
+    }
+    if (!isScalarKey(blueprint, key)) {
+      return `route reads "${key}" from ${where}, but it is not a scalar key of the input.`;
+    }
+    places.set(key, where);
+    return;
+  };
+  if (path !== undefined) {
+    if (!isRoutePath(path)) {
+      return 'Expected route.path to start with "/", with parameters only as whole "{name}" segments and no query.';
+    }
+    for (const name of parametersOfPath(path)) {
+      const bad = place(name, "the path");
+      if (bad)
+        return bad;
+    }
+  }
+  if (status !== undefined && !ROUTE_SUCCESS_STATUSES.includes(status)) {
+    return `Expected route.status to be one of ${ROUTE_SUCCESS_STATUSES.join(", ")}.`;
+  }
+  if (query !== undefined) {
+    if (!Array.isArray(query) || query.some((key) => typeof key !== "string")) {
+      return "Expected route.query to be a list of input keys.";
+    }
+    for (const key of query) {
+      const bad = place(key, "the query");
+      if (bad)
+        return bad;
+    }
+  }
+  for (const [option, value, where] of [
+    ["headers", headers, "a header"],
+    ["cookie", cookie, "a cookie"]
+  ]) {
+    if (value === undefined)
+      continue;
+    if (!isObject(value)) {
+      return `Expected route.${option} to map input keys to names.`;
+    }
+    const names = new Set;
+    for (const [key, name] of Object.entries(value)) {
+      if (typeof name !== "string" || !HEADER_NAME.test(name)) {
+        return `Expected route.${option}["${key}"] to be the name of ${where}.`;
+      }
+      const bad = place(key, where);
+      if (bad)
+        return bad;
+      const folded = option === "headers" ? name.toLowerCase() : name;
+      if (names.has(folded)) {
+        return `route.${option} reads "${name}" into two input keys.`;
+      }
+      names.add(folded);
+    }
+  }
+  if (setCookie !== undefined) {
+    if (!isObject(setCookie)) {
+      return "Expected route.setCookie to map response keys to cookies.";
+    }
+    const names = new Set;
+    for (const [key, settings] of Object.entries(setCookie)) {
+      if (!isScalarKey(response, key)) {
+        return `route.setCookie sends "${key}", which is not a scalar key of the response.`;
+      }
+      const bad = cookieIssue(settings, `route.setCookie["${key}"]`);
+      if (bad)
+        return bad;
+      const { name } = settings;
+      if (names.has(name)) {
+        return `route.setCookie sets the cookie "${name}" from two response keys.`;
+      }
+      names.add(name);
+    }
+  }
+  return Object.freeze({
+    method,
+    ...path === undefined ? {} : { path },
+    ...status === undefined ? {} : { status },
+    ...query === undefined ? {} : { query: Object.freeze([...query]) },
+    ...headers === undefined ? {} : {
+      headers: Object.freeze(Object.fromEntries(Object.entries(headers).map(([key, name]) => [key, name.toLowerCase()])))
+    },
+    ...cookie === undefined ? {} : { cookie: Object.freeze({ ...cookie }) },
+    ...setCookie === undefined ? {} : {
+      setCookie: Object.freeze(Object.fromEntries(Object.entries(setCookie).map(([key, settings]) => [key, Object.freeze({ ...settings })])))
+    }
+  });
+}

package/dist/core/use-case/scope.d.ts

@@ -1,5 +1,6 @@
 import type { ILogger } from "../logger/logger.js";
 import type { IRepositoryProvider } from "../repository/types/repository.interface.js";
+import type { ITracer, ITraceSpan } from "../tracing/tracing.js";
 /**
  * What a call carries to its repositories, internal: the providers that
  * replace the ones the repositories declared (e.g. one inside a transaction).
@@ -14,6 +15,10 @@ export interface ExecutionScope {
     readonly environments?: ReadonlyMap<object, Readonly<Record<string, unknown>>>;
     /** The logger of the application running the call, given by its command. */
     readonly logger?: ILogger;
+    /** The tracer of the application running the call, given by its command. */
+    readonly tracer?: ITracer;
+    /** The span of the caller (a command, a use case): the parent of the next. */
+    readonly span?: ITraceSpan;
 }
 /**
  * Key of the constructor options (and of the repository view) that carries

package/dist/core/use-case/scope.js

@@ -0,0 +1,4 @@
+export const ScopeKey = Symbol("afora.use-case.scope");
+export function scopedProvider(scope, provider) {
+  return scope?.providers.get(provider) ?? provider;
+}

package/dist/core/use-case/steps/describe.d.ts

@@ -1,3 +1,4 @@
+import type { FieldsDescription } from "../../application/types/application.interface.js";
 import type { StepErrorDescription, UseCaseStepDescription } from "./types/steps.interface.js";
 /** How a class of a step is named in the descriptor. */
 export interface StepNames {
@@ -5,9 +6,12 @@ export interface StepNames {
     readonly record: (Class: unknown) => string;
     /** The registered name of an exception, or `{ core }` for one the package exports. */
     readonly error: (Class: unknown) => StepErrorDescription;
+    /** The fields of the `params` blueprint of a `run`. */
+    readonly params: (blueprint: unknown) => FieldsDescription;
 }
 /**
  * The steps as `describe()` gives them: the same data, with the classes of
- * `build` and `ensure.error` by name and the function of `run` as `opaque`.
+ * `build` and `ensure.error` by name, the function of `run` as `opaque` and
+ * its `params` by their fields.
  */
 export declare function describeSteps(steps: readonly Readonly<Record<string, unknown>>[], names: StepNames): UseCaseStepDescription[];

package/dist/core/use-case/steps/describe.js

@@ -0,0 +1,24 @@
+import { isPlain } from "./references.js";
+function cloneData(value) {
+  if (Array.isArray(value))
+    return value.map(cloneData);
+  if (isPlain(value)) {
+    return Object.fromEntries(Object.entries(value).map(([key, item]) => [key, cloneData(item)]));
+  }
+  return value;
+}
+export function describeSteps(steps, names) {
+  return steps.map((step) => {
+    const copy = cloneData({ ...step });
+    if (Object.hasOwn(step, "build"))
+      copy.build = names.record(step.build);
+    if (Object.hasOwn(step, "ensure"))
+      copy.error = names.error(step.error);
+    if (Object.hasOwn(step, "run")) {
+      copy.fn = { kind: "opaque" };
+      if (step.params !== undefined)
+        copy.params = names.params(step.params);
+    }
+    return copy;
+  });
+}

package/dist/core/use-case/steps/references.js

@@ -0,0 +1,105 @@
+export const RESERVED_NAMES = [
+  "input",
+  "context",
+  "env",
+  "literal"
+];
+const IDENTIFIER = /^[A-Za-z_][A-Za-z0-9_]*$/;
+const SEGMENT = /^(?:[A-Za-z_][A-Za-z0-9_]*|0|[1-9][0-9]*)$/;
+const BLOCKED = new Set(["__proto__", "constructor", "prototype"]);
+export function isStepName(value) {
+  return typeof value === "string" && IDENTIFIER.test(value);
+}
+const parsed = new Map;
+export function parseReference(text) {
+  const cached = parsed.get(text);
+  if (cached !== undefined)
+    return cached ?? undefined;
+  let result = null;
+  if (text.startsWith("$")) {
+    const [root, ...path] = text.slice(1).split(".");
+    if (root !== undefined && IDENTIFIER.test(root) && path.every((segment) => SEGMENT.test(segment))) {
+      result = Object.freeze({ root, path: Object.freeze(path) });
+    }
+  }
+  if (parsed.size < 4096)
+    parsed.set(text, result);
+  return result ?? undefined;
+}
+export function isPlain(value) {
+  if (typeof value !== "object" || value === null)
+    return false;
+  const prototype = Object.getPrototypeOf(value);
+  return prototype === Object.prototype || prototype === null;
+}
+function isLiteralEscape(value) {
+  return isPlain(value) && Object.keys(value).length === 1 && Object.hasOwn(value, "literal");
+}
+export function walkValue(value, onReference, onIssue) {
+  if (typeof value === "string") {
+    if (!value.startsWith("$"))
+      return;
+    const reference = parseReference(value);
+    if (!reference)
+      onIssue("invalid_reference", value);
+    else
+      onReference(reference, value);
+    return;
+  }
+  if (value === null || typeof value === "number" || typeof value === "boolean") {
+    return;
+  }
+  if (isLiteralEscape(value)) {
+    return;
+  }
+  if (Array.isArray(value)) {
+    for (const item of value)
+      walkValue(item, onReference, onIssue);
+    return;
+  }
+  if (isPlain(value)) {
+    for (const item of Object.values(value)) {
+      walkValue(item, onReference, onIssue);
+    }
+    return;
+  }
+  onIssue("invalid_value", String(value));
+}
+export function followPath(from, path) {
+  let current = from;
+  for (const segment of path) {
+    if (typeof current !== "object" && typeof current !== "function" || current === null || BLOCKED.has(segment)) {
+      return;
+    }
+    current = current[segment];
+  }
+  return current;
+}
+export function resolveValue(value, lookup) {
+  if (typeof value === "string") {
+    if (!value.startsWith("$"))
+      return value;
+    const reference = parseReference(value);
+    return reference ? lookup(reference) : undefined;
+  }
+  if (isLiteralEscape(value))
+    return value.literal;
+  if (Array.isArray(value))
+    return value.map((item) => resolveValue(item, lookup));
+  if (isPlain(value)) {
+    return Object.fromEntries(Object.entries(value).map(([key, item]) => [
+      key,
+      resolveValue(item, lookup)
+    ]));
+  }
+  return value;
+}
+export function freezeData(value) {
+  if (Array.isArray(value)) {
+    return Object.freeze(value.map(freezeData));
+  }
+  if (isPlain(value)) {
+    return Object.freeze(Object.fromEntries(Object.entries(value).map(([key, item]) => [key, freezeData(item)])));
+  }
+  return value;
+}

package/dist/core/use-case/steps/run.js

@@ -0,0 +1,139 @@
+import { isRecordClass } from "../../blueprint/record-field.js";
+import { sameValue } from "../../repository/query.js";
+import { InvalidUseCaseStep } from "../exceptions.js";
+import { followPath, resolveValue } from "./references.js";
+const FORBIDDEN_METHODS = new Set([
+  "set",
+  "emit",
+  "constructor",
+  "__proto__",
+  "hasOwnProperty",
+  "isPrototypeOf",
+  "propertyIsEnumerable",
+  "toLocaleString",
+  "valueOf",
+  "__defineGetter__",
+  "__defineSetter__",
+  "__lookupGetter__",
+  "__lookupSetter__"
+]);
+function isRecordInstance(value) {
+  return typeof value === "object" && value !== null && isRecordClass(value.constructor);
+}
+function parsedArgs(params, args, invalid) {
+  const keys = Object.keys(params.properties);
+  if (args.length !== keys.length) {
+    invalid(`run.params declares ${keys.length} parameter(s), args gave ${args.length}.`, "invalid_args");
+  }
+  const result = params.safeParse(Object.fromEntries(keys.map((key, at) => [key, args[at]])));
+  if (result.issues) {
+    const [first] = result.issues;
+    const more = result.issues.length > 1 ? ` (and ${result.issues.length - 1} more)` : "";
+    return invalid(`the argument "${first?.path.join(".")}" ${first?.message}${more}.`, "invalid_args", result.issues);
+  }
+  const value = result.value;
+  return keys.map((key) => value[key]);
+}
+export async function executeSteps(dependencies = {}) {
+  const { useCaseName, steps = [] } = this.constructor;
+  const named = new Map;
+  const lookup = ({ root, path }) => {
+    if (root === "input")
+      return followPath(this.input, path);
+    if (root === "context")
+      return followPath(this.context, path);
+    if (root === "env")
+      return followPath(dependencies[path[0]], path.slice(1));
+    return followPath(named.get(root), path);
+  };
+  const value = (raw) => resolveValue(raw, lookup);
+  for (const [index, step] of steps.entries()) {
+    const invalid = (reason, code = "invalid_target", issues) => {
+      throw new InvalidUseCaseStep({
+        source: useCaseName,
+        details: { index, reason, code, ...issues ? { issues } : {} }
+      });
+    };
+    const list = (raw) => {
+      if (raw === undefined)
+        return [];
+      const resolved = value(raw);
+      if (!Array.isArray(resolved))
+        invalid("args must resolve to a list.");
+      return resolved;
+    };
+    const bind = (result) => {
+      if (typeof step.as === "string")
+        named.set(step.as, result);
+    };
+    const target = (field) => {
+      const resolved = value(step[field]);
+      if (!isRecordInstance(resolved)) {
+        invalid(`${field} must reference a record or entity.`);
+      }
+      return resolved;
+    };
+    if (Object.hasOwn(step, "return"))
+      return value(step.return);
+    if (Object.hasOwn(step, "find")) {
+      const [repository, action] = step.find.split(".");
+      const methods = dependencies[repository];
+      bind(await methods[action].call(methods, ...list(step.args)));
+    } else if (Object.hasOwn(step, "ensure")) {
+      const subject = value(step.value);
+      const passed = {
+        exists: subject !== undefined && subject !== null,
+        absent: subject === undefined || subject === null,
+        equals: sameValue(subject, value(step.other)),
+        notEquals: !sameValue(subject, value(step.other)),
+        true: subject === true,
+        false: subject === false
+      }[step.ensure];
+      if (!passed) {
+        const Thrown = step.error;
+        throw new Thrown({
+          source: useCaseName,
+          ...step.details === undefined ? {} : { details: value(step.details) }
+        });
+      }
+    } else if (Object.hasOwn(step, "build")) {
+      const Built = step.build;
+      bind(new Built(value(step.values)));
+    } else if (Object.hasOwn(step, "change")) {
+      const record = target("change");
+      const namespace = record.change;
+      const key = step.key;
+      if (typeof namespace !== "object" || namespace === null || typeof namespace[key] !== "function") {
+        invalid(`"${key}" is not a change key of the record.`);
+      }
+      const changed = value(step.value);
+      if (step.ifPresent !== true || changed !== undefined) {
+        await namespace[key]?.(changed);
+      }
+      bind(record);
+    } else if (Object.hasOwn(step, "invoke")) {
+      const record = target("invoke");
+      const method = step.method;
+      if (FORBIDDEN_METHODS.has(method) || typeof record[method] !== "function") {
+        invalid(`"${method}" is not a public method of the record.`);
+      }
+      bind(await record[method].apply(record, list(step.args)));
+    } else if (Object.hasOwn(step, "call")) {
+      const child = dependencies[step.call];
+      bind(await child(value(step.input)));
+    } else if (Object.hasOwn(step, "run")) {
+      const fn = step.fn;
+      const args = list(step.args);
+      bind(await fn(...step.params === undefined ? args : parsedArgs(step.params, args, invalid), { context: this.context, dependencies }));
+    } else {
+      const action = ["create", "update", "delete", "restore"].find((kind) => Object.hasOwn(step, kind));
+      const methods = dependencies[step[action]];
+      bind(await methods[action].call(methods, value(step.value)));
+    }
+  }
+  return;
+}
+export function interpretedStepsOf(UseCase) {
+  const Declared = UseCase;
+  return Declared.prototype.execute === executeSteps ? Declared.steps : undefined;
+}