@afora/core 0.0.8 → 0.0.11

package/dist/core/command/command.js

@@ -0,0 +1,428 @@
+import { isBlueprint } from "../blueprint/is-blueprint.js";
+import {
+  isEnvironment,
+  loadEnvironments
+} from "../environment/environment.js";
+import { resolvePublisher } from "../event-policy/publishers.js";
+import { ExceptionLayers } from "../exception/enums/exception-layers.js";
+import { Exception } from "../exception/exception.js";
+import { guard } from "../exception/guard.js";
+import {
+  clock,
+  elapsed,
+  logFailure,
+  resolveLogger,
+  silentLogger,
+  writeLog
+} from "../logger/logger.js";
+import { isRepository } from "../repository/repository.js";
+import { findState } from "../repository/state.js";
+import { Kind } from "../symbols/kind.js";
+import {
+  endSpan,
+  failSpan,
+  resolveTracer,
+  runInSpan,
+  startSpan
+} from "../tracing/tracing.js";
+import { isUseCaseCatalog } from "../use-case/plugin-catalog.js";
+import { ScopeKey } from "../use-case/scope.js";
+import { isUseCaseClass } from "../use-case/use-case.js";
+import {
+  CommandEventFailed,
+  InvalidCommandContext,
+  InvalidCommandDeclaration,
+  InvalidCommandEnvironment,
+  UnknownCommandOperation
+} from "./exceptions.js";
+const verifiers = new WeakMap;
+export function verifyCommand(command) {
+  verifiers.get(command)?.();
+}
+export function commandTransactionProvider(command) {
+  return verifiers.get(command)?.();
+}
+const IDENTIFIER = /^[A-Za-z_$][A-Za-z0-9_$]*$/;
+function repositoryProvidersOf(useCases, declared) {
+  const providers = new Map;
+  const seen = new Set;
+  const add = (state) => {
+    if (declared && !state.explicitProvider)
+      return;
+    const { provider, name } = state;
+    const names = providers.get(provider) ?? [];
+    if (!names.includes(name))
+      names.push(name);
+    providers.set(provider, names);
+  };
+  const visit = (UseCase) => {
+    if (seen.has(UseCase))
+      return;
+    seen.add(UseCase);
+    for (const dependency of Object.values(UseCase.dependencies)) {
+      if (isUseCaseClass(dependency)) {
+        visit(dependency);
+      } else if (isRepository(dependency)) {
+        const state = findState(dependency);
+        if (!state)
+          continue;
+        add(state);
+        for (const related of state.relations.values())
+          add(related);
+      }
+    }
+  };
+  for (const UseCase of Object.values(useCases))
+    visit(UseCase);
+  return providers;
+}
+function transactionProviderOf(name, useCases, declared = false) {
+  const providers = repositoryProvidersOf(useCases, declared);
+  const invalid = (reason, repositories) => {
+    throw new InvalidCommandDeclaration({
+      source: name,
+      details: { reason, repositories }
+    });
+  };
+  if (providers.size > 1) {
+    const repositories = [...providers.values()].flat();
+    invalid(`A transaction needs every repository to share one provider; found ${providers.size} (${repositories.join(", ")}).`, repositories);
+  }
+  const [entry] = providers;
+  if (!entry)
+    return;
+  const [provider, repositories] = entry;
+  if (typeof provider.transaction !== "function" || provider.capabilities?.transactions === false) {
+    invalid(`The provider of ${repositories.join(", ")} does not support transactions.`, repositories);
+  }
+  return provider;
+}
+function narrowed(UseCase, context) {
+  if (!UseCase.context || typeof context !== "object" || context === null) {
+    return;
+  }
+  const picked = {};
+  for (const key of Object.keys(UseCase.context.properties)) {
+    if (Object.hasOwn(context, key)) {
+      picked[key] = context[key];
+    }
+  }
+  return picked;
+}
+function callEnvironment(source, environments, given) {
+  if (typeof given !== "object" || given === null || Array.isArray(given)) {
+    throw new InvalidCommandEnvironment({
+      source,
+      details: { keys: [], issues: [] }
+    });
+  }
+  const values = given;
+  const unknownKeys = Object.keys(values).filter((key) => !environments.some((environment) => Object.hasOwn(environment.blueprint.properties, key)));
+  if (unknownKeys.length > 0) {
+    throw new InvalidCommandEnvironment({
+      source,
+      details: { keys: unknownKeys, issues: [] }
+    });
+  }
+  const byEnvironment = new Map;
+  const merged = {};
+  for (const environment of environments) {
+    const keys = Object.keys(environment.blueprint.properties);
+    const picked = {};
+    for (const key of keys) {
+      if (Object.hasOwn(values, key))
+        picked[key] = values[key];
+    }
+    const complete = keys.every((key) => Object.hasOwn(picked, key));
+    const base = Object.keys(picked).length === 0 || !complete ? environment.load() : {};
+    if (Object.keys(picked).length === 0) {
+      Object.assign(merged, base);
+      continue;
+    }
+    const parsed = environment.blueprint.safeParse({ ...base, ...picked });
+    if (parsed.issues) {
+      throw new InvalidCommandEnvironment({
+        source,
+        details: {
+          keys: [
+            ...new Set(parsed.issues.map((issue) => String(issue.path[0] ?? "")))
+          ],
+          issues: parsed.issues
+        },
+        cause: parsed.issues.find((issue) => issue.cause)?.cause
+      });
+    }
+    const value = Object.freeze(parsed.value);
+    byEnvironment.set(environment, value);
+    Object.assign(merged, value);
+  }
+  return { byEnvironment, merged: Object.freeze(merged) };
+}
+function declareCommand(given, generics) {
+  const { name, description, context, onEventError } = given;
+  const source = typeof name === "string" ? name : "commandOf";
+  const picked = given.useCases;
+  const useCases = typeof picked === "function" && !isUseCaseClass(picked) ? guard({ layer: ExceptionLayers.Command, source }, () => picked(generics)) : picked;
+  const settings = given;
+  const invalid = (reason) => {
+    throw new InvalidCommandDeclaration({ source, details: { reason } });
+  };
+  if (typeof name !== "string" || !name.trim()) {
+    invalid("Expected name to be a non-empty string.");
+  }
+  if (description !== undefined && typeof description !== "string") {
+    invalid("Expected description to be a string.");
+  }
+  const tags = settings.tags === undefined ? [] : settings.tags;
+  if (!Array.isArray(tags) || tags.some((tag) => typeof tag !== "string") || new Set(tags).size !== tags.length) {
+    invalid("Expected tags to be distinct strings.");
+  }
+  if (context !== undefined && (!isBlueprint(context) || context.optional)) {
+    invalid("Expected context to be a non-optional blueprint.");
+  }
+  if (typeof useCases !== "object" || useCases === null || Array.isArray(useCases) || Reflect.ownKeys(useCases).length === 0) {
+    invalid("Expected useCases to be a non-empty object of use case classes, or a function returning one.");
+  }
+  for (const key of Reflect.ownKeys(useCases)) {
+    if (typeof key !== "string" || !IDENTIFIER.test(key) || !isUseCaseClass(useCases[key])) {
+      invalid("Expected the operations to be identifiers holding use case classes.");
+    }
+  }
+  const transaction = settings.transaction === undefined ? false : settings.transaction;
+  if (typeof transaction !== "boolean") {
+    invalid("Expected transaction to be a boolean.");
+  }
+  const declaredEnvironments = settings.environmentDependencies;
+  const environments = Object.freeze(declaredEnvironments === undefined ? [] : isEnvironment(declaredEnvironments) ? [declaredEnvironments] : Array.isArray(declaredEnvironments) ? [...declaredEnvironments] : [null]);
+  if (!environments.every(isEnvironment) || new Set(environments).size !== environments.length) {
+    invalid("Expected environmentDependencies to be distinct environments made by environmentOf.");
+  }
+  const events = settings.events === undefined ? "after-commit" : settings.events;
+  if (events !== "after-commit" && events !== "manual" && typeof events !== "function") {
+    invalid('Expected events to be "after-commit", "manual" or a function.');
+  }
+  if (onEventError !== undefined) {
+    if (typeof onEventError !== "function") {
+      invalid("Expected onEventError to be a function.");
+    }
+    if (events !== "after-commit") {
+      invalid('onEventError only applies to the "after-commit" policy.');
+    }
+  }
+  if (transaction)
+    transactionProviderOf(source, useCases, true);
+  let resolved;
+  const providerOfCall = () => {
+    if (!transaction)
+      return;
+    resolved ??= { provider: transactionProviderOf(source, useCases) };
+    return resolved.provider;
+  };
+  const operations = Object.freeze(Object.keys(useCases));
+  const frozenUseCases = Object.freeze({ ...useCases });
+  const perform = async (op, input, options, keepSpan) => {
+    if (typeof op !== "string" || !Object.hasOwn(frozenUseCases, op)) {
+      throw new UnknownCommandOperation({
+        source,
+        details: { operation: String(op) }
+      });
+    }
+    const where = `${source}.${op}`;
+    const UseCase = frozenUseCases[op];
+    const tracer = resolveTracer(undefined, UseCase);
+    const span = tracer === undefined ? undefined : startSpan(tracer, `command ${where}`, { "afora.command": where, "afora.operation": op }, undefined);
+    let callContext = options?.context;
+    let given = callContext;
+    let overrides;
+    try {
+      if (context) {
+        const checked = context.safeParse(callContext);
+        if (checked.issues) {
+          throw new InvalidCommandContext({
+            source: where,
+            details: { issues: checked.issues },
+            cause: checked.issues.find((issue) => issue.cause)?.cause
+          });
+        }
+        callContext = checked.value;
+        given = narrowed(UseCase, callContext);
+      }
+      overrides = options?.env === undefined ? undefined : callEnvironment(where, environments, options.env);
+    } catch (error) {
+      failSpan(span, error, ExceptionLayers.Command);
+      throw error;
+    }
+    const logger = resolveLogger(undefined, UseCase);
+    const withEnvironments = (scope) => {
+      const environmentsOfCall = overrides === undefined || overrides.byEnvironment.size === 0 ? scope?.environments : overrides.byEnvironment;
+      if (!environmentsOfCall && !logger && !tracer)
+        return scope;
+      return {
+        ...scope,
+        providers: scope?.providers ?? new Map,
+        ...environmentsOfCall ? { environments: environmentsOfCall } : {},
+        ...logger ? { logger } : {},
+        ...tracer ? { tracer, ...span ? { span } : {} } : {}
+      };
+    };
+    const run = async (declared) => {
+      const scope = withEnvironments(declared);
+      const useCase = new UseCase(input, { context: given, [ScopeKey]: scope });
+      const value = await useCase.execute();
+      return { value, events: useCase.pullEvents() };
+    };
+    const provider = providerOfCall();
+    const started = clock();
+    const outcome = await guard({ layer: ExceptionLayers.Command, source: where }, span === undefined || tracer === undefined ? () => provider?.transaction ? provider.transaction((scoped) => run({ providers: new Map([[provider, scoped]]) })) : run(undefined) : () => runInSpan(tracer, span, () => provider?.transaction ? provider.transaction((scoped) => run({ providers: new Map([[provider, scoped]]) })) : run(undefined))).catch((error) => {
+      logFailure(logger, "command-failed", { command: where, ms: elapsed(started) }, error);
+      failSpan(span, error, ExceptionLayers.Command);
+      throw error;
+    });
+    writeLog(logger, "debug", "command", {
+      command: where,
+      ms: elapsed(started)
+    });
+    if (!keepSpan)
+      endSpan(span);
+    return {
+      ...outcome,
+      context: callContext,
+      env: () => overrides?.merged ?? loadEnvironments(environments),
+      logger: logger ?? silentLogger,
+      tracer,
+      span
+    };
+  };
+  const command = {
+    [Kind]: "command",
+    commandName: name,
+    description,
+    tags: Object.freeze([...tags]),
+    context,
+    useCases: frozenUseCases,
+    transaction,
+    environments,
+    get env() {
+      return loadEnvironments(environments);
+    },
+    events,
+    onEventError,
+    operations,
+    async execute(op, input, options) {
+      const { value, events } = await perform(op, input, options, false);
+      return { value, events };
+    },
+    async run(op, input, options) {
+      const {
+        value,
+        events: raised,
+        context: callContext,
+        env,
+        logger,
+        tracer,
+        span
+      } = await perform(op, input, options, true);
+      const call = {
+        operation: op,
+        raised,
+        context: callContext,
+        env,
+        logger
+      };
+      if (span === undefined || tracer === undefined) {
+        await applyPolicy(command, events, onEventError, call);
+        return value;
+      }
+      try {
+        await runInSpan(tracer, span, () => applyPolicy(command, events, onEventError, call));
+      } catch (error) {
+        failSpan(span, error, ExceptionLayers.Command);
+        throw error;
+      }
+      endSpan(span);
+      return value;
+    }
+  };
+  Object.freeze(command);
+  verifiers.set(command, providerOfCall);
+  return command;
+}
+export function commandBuilderOf(...catalogs) {
+  if (!catalogs.every(isUseCaseCatalog)) {
+    throw new InvalidCommandDeclaration({
+      source: "commandBuilderOf",
+      details: {
+        reason: "Expected catalogs made by useCaseCatalogOf."
+      }
+    });
+  }
+  const generics = Object.freeze(Object.assign({}, ...catalogs.map((catalog) => catalog.context)));
+  return (settings) => declareCommand(settings, generics);
+}
+export const commandOf = commandBuilderOf();
+async function applyPolicy(command, policy, onEventError, call) {
+  const { operation, raised } = call;
+  const source = `${command.commandName}.${operation}`;
+  if (policy === "manual")
+    return;
+  const info = {
+    command,
+    operation,
+    context: call.context,
+    get env() {
+      return call.env();
+    },
+    logger: call.logger,
+    publisher: (name) => resolvePublisher(command, name, source)
+  };
+  if (typeof policy === "function") {
+    try {
+      await policy(raised, info);
+    } catch (cause) {
+      if (cause instanceof Exception && cause.name === "CommandEventFailed") {
+        throw cause;
+      }
+      throw new CommandEventFailed({
+        source,
+        cause,
+        details: { operation, handled: 0, remaining: raised.length }
+      });
+    }
+    return;
+  }
+  for (const [index, event] of raised.entries()) {
+    try {
+      await event.handle({ logger: call.logger });
+    } catch (cause) {
+      if (!onEventError) {
+        throw new CommandEventFailed({
+          source,
+          cause,
+          details: {
+            operation,
+            event: event.name,
+            handled: index,
+            remaining: raised.length - index - 1
+          }
+        });
+      }
+      try {
+        await onEventError(cause, event, info);
+      } catch (failure) {
+        throw new CommandEventFailed({
+          source,
+          cause: failure,
+          details: {
+            operation,
+            event: event.name,
+            handled: index,
+            remaining: raised.length - index - 1
+          }
+        });
+      }
+    }
+  }
+}
+export function isCommand(value) {
+  return typeof value === "object" && value !== null && value[Kind] === "command";
+}

package/dist/core/command/exceptions.js

@@ -0,0 +1,30 @@
+import { ExceptionLayers } from "../exception/enums/exception-layers.js";
+import { exceptionOf } from "../exception/exception.js";
+export const InvalidCommandDeclaration = exceptionOf({
+  layer: ExceptionLayers.Command,
+  name: "InvalidCommandDeclaration",
+  message: ({ reason }) => reason
+});
+export const UnknownCommandOperation = exceptionOf({
+  layer: ExceptionLayers.Command,
+  name: "UnknownCommandOperation",
+  message: ({ operation }) => `Unknown command operation "${operation}".`
+});
+export const InvalidCommandContext = exceptionOf({
+  layer: ExceptionLayers.Command,
+  name: "InvalidCommandContext",
+  message: (_details) => "Invalid Command context."
+});
+export const InvalidCommandEnvironment = exceptionOf({
+  layer: ExceptionLayers.Command,
+  name: "InvalidCommandEnvironment",
+  message: (_details) => "Invalid Command environment."
+});
+export const CommandEventFailed = exceptionOf({
+  layer: ExceptionLayers.Command,
+  name: "CommandEventFailed",
+  message: ({
+    operation,
+    event
+  }) => event === undefined ? `The event handler of "${operation}" failed after the call succeeded.` : `The event "${event}" of "${operation}" failed after the call succeeded.`
+});

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

@@ -37,6 +37,11 @@ export type CommandEventHandler = (events: readonly EntityEvent[], info: Command
 export type CommandEvents = "after-commit" | "manual" | CommandEventHandler;
 /** Called when an event fails with the `"after-commit"` policy; the next event still runs. */
 export type CommandEventErrorHandler = (error: unknown, event: EntityEvent, info: CommandEventInfo) => void | Promise<void>;
+/**
+ * What {@link commandOf} takes: the `name` and the `useCases` of the command,
+ * the `context` a call supplies, and how a call runs (`transaction`,
+ * `environmentDependencies`, `events` and `onEventError`).
+ */
 export interface CommandSettings<UseCases extends CommandUseCases, Context extends IBlueprintCollection | undefined = undefined, Environment extends EnvironmentDependencies | undefined = undefined> {
     readonly name: string;
     readonly description?: string;
@@ -44,7 +49,11 @@ export interface CommandSettings<UseCases extends CommandUseCases, Context exten
     /** What the caller supplies with each call; validated once by this blueprint. */
     readonly context?: IBlueprint<Exclude<Context, undefined>>;
     readonly useCases: UseCases;
-    /** Runs every call in a transaction of the provider of the repositories. Default `false`. */
+    /**
+     * Runs every call in a transaction of the provider of the repositories.
+     *
+     * @default false
+     */
     readonly transaction?: boolean;
     /**
      * One environment, or a list merged in order: read on first use as

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

@@ -1,4 +1,5 @@
 import type { BlueprintInput, BlueprintValue, IBlueprintCollection } from "../blueprint/types/blueprint.interface.js";
+import type { Complete } from "../parse/parse.js";
 import { AbstractRecord } from "../record/abstract-record.js";
 import { type EntityEvent, type EventDefinition } from "./event.js";
 import type { EntityIdentityKey } from "./types/entity.interface.js";
@@ -25,6 +26,11 @@ export declare const EntityLifetime: unique symbol;
 export declare const EXPIRES_AT = "expiresAt";
 /** The key a versioned entity adds to its identity. */
 export declare const ENTITY_VERSION_KEY = "version";
+/**
+ * The key of each stored row holding its schema version, for entities
+ * declared with `schemaVersion`; it is never a key of the entity.
+ */
+export declare const SCHEMA_VERSION_KEY = "$v";
 /** Whether `entityClass` was declared with `versioned: true`. */
 export declare function isVersionedEntityClass(entityClass: unknown): boolean;
 /**
@@ -38,6 +44,24 @@ export declare function identityKeysOf(entityClass: unknown): readonly string[];
  * a write succeeded. @internal
  */
 export declare function storeEntityVersion(entity: object, version: number): void;
+/**
+ * Under this key, a class made by `entityOf` holds what makes its id, its
+ * `createdAt` and its `expiresAt` once its value is known to be valid.
+ *
+ * @internal
+ */
+export declare const EntityComplete: unique symbol;
+/**
+ * What an entity class does with the values its builder vouched for and left
+ * out, after the rest of its value is known to be valid: `createdAt` first,
+ * then `id`, as they were made before; and, for a class that expires, an
+ * `expiresAt` `lifetime` milliseconds after `createdAt`, which is still
+ * checked.
+ */
+export declare function completeOf(clock: {
+    readonly generateId: () => string;
+    readonly now: () => string;
+}, lifetime: number | undefined): Complete;
 /**
  * A record with identity: an `id` and a `createdAt`, made when it is built
  * and never changed after, an `updatedAt` set by each change, and a