@ingenioz-it/caits 0.6.0 → 0.8.0

package/src/adapter.js

@@ -0,0 +1,94 @@
+// The adapter of @marko/run for a CAITS app: quality/caits/vite.ts gives it to the plugin of @marko/run. JavaScript, not TypeScript: Node
+// loads it with the configuration of Vite, and strips no types in node_modules, where a project installs the kernel.
+// - `npm run build` builds the server of `npm start` from server/entry.ts: it boots the backend, and stops it on SIGTERM or SIGINT.
+// - `caits dev` serves the app with the dev server of @marko/run, in a server of its own (server/serve.js): it boots the backend through
+//   Vite, boots it again when a module that the backend imports changes, and stops it when it closes.
+import { fileURLToPath } from "node:url";
+import baseAdapter, { createDevServer } from "@marko/run/adapter";
+import { serve } from "./server/serve.js";
+
+/** @import { Adapter } from "@marko/run/vite" */
+/** @import { ModuleNode, ViteDevServer } from "vite" */
+
+const ENTRY = fileURLToPath(new URL("./server/entry.ts", import.meta.url));
+const KERNEL = fileURLToPath(new URL("./server/kernel.ts", import.meta.url));
+
+/**
+ * The adapter of @marko/run that serves a CAITS app: that of Node, whose server boots the backend and stops it.
+ * @returns {Adapter}
+ */
+export function adapter() {
+  return {
+    ...baseAdapter(),
+    name: "caits",
+    getEntryFile: () => ENTRY,
+    startDev: async ({ config, options }) => {
+      const vite = await createDevServer(config);
+      /** @type {Awaited<ReturnType<typeof serve>>} */
+      let served;
+      try {
+        served = await serve({
+          handle: vite.middlewares,
+          port: options.port ?? 3000,
+          boot: async () => /** @type {typeof import("./server/kernel.js")} */ (await vite.ssrLoadModule(KERNEL)).boot()
+        });
+      } catch (error) {
+        // A first boot that fails, or a port in use: the server of Vite and its watcher would keep the command alive, and nothing would
+        // answer. The command ends, with the error.
+        await vite.close();
+        throw error;
+      }
+      vite.watcher.on("change", file => {
+        if (!imports(vite, KERNEL, file)) return;
+        forget(vite, file);
+        void served.reboot();
+      });
+      // The words of the server of @marko/run: who waits for the server reads them.
+      console.log(`\n  Server listening at\n  http://localhost:${served.port}\n`);
+      return {
+        port: served.port,
+        close: async () => {
+          await served.close();
+          await vite.close();
+        }
+      };
+    }
+  };
+}
+
+/**
+ * Whether a module that Vite loaded imports a file, itself or through the modules that it imports.
+ * @param {ViteDevServer} vite
+ * @param {string} id
+ * @param {string} file
+ */
+function imports(vite, id, file) {
+  /** @type {Set<ModuleNode>} */
+  const seen = new Set();
+  /** @type {(module: ModuleNode | undefined) => boolean} */
+  const visit = module => {
+    if (!module || seen.has(module)) return false;
+    seen.add(module);
+    return module.file === file || [...module.importedModules].some(visit);
+  };
+  return visit(vite.moduleGraph.getModuleById(id));
+}
+
+/**
+ * Makes Vite forget a file that changed, and the modules that import it: the backend that boots again loads their new code. Vite would
+ * forget them itself, but after the watchers of the project see the change.
+ * @param {ViteDevServer} vite
+ * @param {string} file
+ */
+function forget(vite, file) {
+  /** @type {Set<ModuleNode>} */
+  const seen = new Set();
+  /** @type {(module: ModuleNode) => void} */
+  const visit = module => {
+    if (seen.has(module)) return;
+    seen.add(module);
+    vite.moduleGraph.invalidateModule(module);
+    for (const importer of module.importers) visit(importer);
+  };
+  for (const module of vite.moduleGraph.getModulesByFile(file) ?? []) visit(module);
+}

package/src/di/Container.ts

@@ -40,6 +40,13 @@ export function bind<T>(key: Key<T>) {
 }
 
 const describe = (route: readonly Key[]) => route.map(key => key.name).join(" → ");
+
+/** Releases an instance that holds a resource: with Symbol.asyncDispose, else Symbol.dispose. Another instance holds none. */
+async function release(instance: unknown): Promise<void> {
+  const { [Symbol.asyncDispose]: asyncDispose, [Symbol.dispose]: dispose } = Object(instance) as Partial<AsyncDisposable & Disposable>;
+  if (typeof asyncDispose === "function") await asyncDispose.call(instance);
+  else if (typeof dispose === "function") dispose.call(instance);
+}
 const isKey = (value: unknown): value is Key => value instanceof Token || typeof value === "function";
 
 /**
@@ -90,6 +97,26 @@ export class Container {
     return value;
   }
 
+  /**
+   * Releases what this container built, the last built first, so a dependency outlives what needs it: each instance with
+   * Symbol.asyncDispose or Symbol.dispose. A value that a binding gives belongs to whoever made it, and what the parent built to the
+   * parent. Every instance is released, even when another fails: the errors come together, after. What it released, it builds again if
+   * something needs it.
+   */
+  async dispose(): Promise<void> {
+    const instances = [...this.built.values()].reverse();
+    this.built.clear();
+    const errors: unknown[] = [];
+    for (const instance of instances) {
+      try {
+        await release(instance);
+      } catch (error) {
+        errors.push(error);
+      }
+    }
+    if (errors.length > 0) throw new AggregateError(errors, `${errors.length} instance${errors.length === 1 ? "" : "s"} failed to release`);
+  }
+
   private resolve(key: Key, path: readonly Key[], make: boolean): unknown {
     const binding = this.bindings.get(key);
     if (!binding && this.parent?.has(key)) return this.parent.resolve(key, path, make);

package/src/di/RequestContext.ts

@@ -1,6 +1,12 @@
 import { Token } from "../Token.js";
 
-/** What the backend knows of the request that a handler or a controller serves. */
-export type RequestContext = { readonly correlationId: string };
+/**
+ * What the backend knows of the request that a handler or a controller serves: its correlation id, and its signal, which aborts when its
+ * client leaves. A handler gives the signal to the ports whose work the client waits for: a call to a model, to a service, to a database.
+ * A request without a client sees the backend stop: the signal of a turn of a timer aborts as soon as the server stops, that of a reaction
+ * to an event once the grace of the server ends. A DTO that the backend sends without a signal, as a test does, gets one that does not
+ * abort.
+ */
+export type RequestContext = { readonly correlationId: string; readonly signal: AbortSignal };
 
 export const RequestContext = new Token<RequestContext>();

package/src/di/backend.ts

@@ -8,6 +8,18 @@ export function startBackend(options: BackendOptions = {}): Backend {
   return current = createBackend(discovered, options);
 }
 
+/**
+ * Stops the backend that serves the requests, if one started, then forgets it: its feeds, its timers, the turns that run, the requests
+ * that the server still serves (the promise that it gives), the reactions, until the grace ends (the signal), then what its containers
+ * built. The next use starts a new one. A request that comes
+ * while it stops gets it: a new backend would outlive the server, since nothing would stop it.
+ */
+export async function stopBackend(requestsDone?: Promise<unknown>, graceOver?: AbortSignal): Promise<void> {
+  const stopping = current;
+  await stopping?.stop(requestsDone, graceOver);
+  if (current === stopping) current = undefined;
+}
+
 /** The backend that serves the requests, started with the production bindings on first use. */
 export function backend(): Backend {
   return current ?? startBackend();

package/src/di/createBackend.ts

@@ -1,12 +1,15 @@
 import type { DomainEvent } from "../DomainEvent.js";
 import type { Token } from "../Token.js";
 import { BackendEventBus, type Published } from "../messaging/BackendEventBus.js";
+import { ContextEvents } from "../messaging/ContextEvents.js";
 import { ContextMap, type Envelope, type Translation } from "../messaging/ContextMap.js";
 import { EventPublisher } from "../messaging/EventPublisher.js";
-import { InProcessMessageBus } from "../messaging/InProcessMessageBus.js";
-import type { Input } from "../messaging/Input.js";
+import { InProcessMessageBus, UnknownInputError } from "../messaging/InProcessMessageBus.js";
+import type { EventSubscriber } from "../messaging/EventSubscriber.js";
 import { MessageBus } from "../messaging/MessageBus.js";
 import { ReportError, reportToConsole } from "../messaging/ReportError.js";
+import { RequestEvents } from "../messaging/RequestEvents.js";
+import { TimerController } from "../messaging/TimerController.js";
 import { bind, Container, type Binding, type Concrete } from "./Container.js";
 import type { BackendModules, Class, UseCase } from "./discover.js";
 import { RequestContext } from "./RequestContext.js";
@@ -16,20 +19,69 @@ export type BackendOptions = {
   replace?: Partial<Record<string, readonly Binding[]>>;
   reportError?: ReportError;
   nextEventId?: () => string;
+  /** The clock of the timer controllers: setInterval when not given. */
+  schedule?: Schedule;
 };
 
-/** A context, and the events of shared that an event of its handlers gives. */
-type Context = { readonly container: Container; readonly useCases: readonly UseCase[]; readonly shares: (event: DomainEvent) => DomainEvent[] };
+/** Runs a turn every `every` milliseconds, until the function that it gives is called. */
+export type Schedule = (every: number, turn: () => void) => () => void;
 
-const SYSTEM: RequestContext = { correlationId: "system" };
+/** The longest delay of setInterval, about 24 days: Node runs a timer with a longer one every millisecond. */
+const MAX_EVERY = 2 ** 31 - 1;
+
+/** How long the turns and the reactions that still run get, once the grace ends and their signal aborted, in milliseconds. */
+const LAST_WAIT_MS = 1000;
+
+/** Waits until the work ends, or the signal aborts. */
+const untilEndOrAbort = (work: Promise<unknown>, signal: AbortSignal) => new Promise<void>(resolve => {
+  signal.addEventListener("abort", () => { resolve(); });
+  if (signal.aborted) resolve();
+  void work.then(() => { resolve(); });
+});
+
+
+const everyInterval: Schedule = (every, turn) => {
+  const timer = setInterval(turn, every);
+  return () => { clearInterval(timer); };
+};
+
+const isTimer = (type: Class): type is Concrete<TimerController<object>> => type.prototype instanceof TimerController;
+
+type Listener = (event: DomainEvent) => void;
+
+/**
+ * A context, its timer controllers, the events of shared that an event of its handlers gives, and who listens to the events of its
+ * handlers.
+ */
+type Context = {
+  readonly container: Container;
+  readonly useCases: readonly UseCase[];
+  readonly timers: readonly Concrete<TimerController<object>>[];
+  readonly shares: (event: DomainEvent) => DomainEvent[];
+  readonly listeners: Set<Listener>;
+};
+
+/** What subscribes to the events that come to these listeners. */
+const subscriberOf = (listeners: Set<Listener>): EventSubscriber<DomainEvent> => ({
+  subscribe: listener => {
+    listeners.add(listener);
+    return () => { listeners.delete(listener); };
+  }
+});
+
+/** Where a request of the backend comes from: its correlation id. */
+type Correlation = Pick<RequestContext, "correlationId">;
+
+const SYSTEM: Correlation = { correlationId: "system" };
 
 /** The context whose events are those of shared: its handlers publish them on the shared bus. */
 const SHARED = "shared";
 
 /**
  * Builds every context in a container of its own, child of the container of shared: the dependencies of a context are private to it,
- * those of shared are built once for all. Each request gets a child of its context, with its correlation id, the publisher of its events
- * and its message bus: its handlers and its controllers are built there. The backend event bus is the shared bus: the context map of a
+ * those of shared are built once for all. Each request gets a child of its context, with its correlation id, its signal, the publisher of
+ * its events and its message bus: its handlers and its controllers are built there. Its signal aborts when the signal that goes with its
+ * DTO aborts: a controller gives the signal of its request, so its handler sees its client leave. The backend event bus is the shared bus: the context map of a
  * context shares there the events of shared that the events of its handlers give, and the context map of each context turns the events
  * of shared that it hears into inputs of the context. The handlers of the context shared publish its events there.
  */
@@ -38,35 +90,76 @@ export function createBackend(modules: BackendModules, options: BackendOptions =
   const shared = new Container([bind(ReportError).toValue(reportError), ...modules.shared, ...(options.replace?.shared ?? [])]);
   const contexts = new Map<string, Context>();
   const owners = new Map<unknown, Context>();
-  const listeners = new Set<(event: DomainEvent) => void>();
+  const listeners = new Set<Listener>();
+  /** Aborts when the backend stops: the events of the contexts end. */
+  const stopping = new AbortController();
+  /** The requests without a client see the backend stop: the turns of the timers at once, the reactions to the events once the grace ends. */
+  const turnsEnd = new AbortController();
+  const reactionsEnd = new AbortController();
 
-  const ownerOf = (owned: Class): Context => {
+  /** The context of an input DTO, or of a controller: the error of an input is that of the message bus, which names the fix. */
+  const ownerOf = (owned: Class, refusal: () => Error): Context => {
     const context = owners.get(owned);
-    if (!context) throw new Error(`No context owns ${owned.name}`);
+    if (!context) throw refusal();
     return context;
   };
+  const ownerOfInput = (input: object): Context => ownerOf(input.constructor as Class, () => new UnknownInputError(input.constructor.name));
 
-  /** The container of a request, and its message bus: each input DTO gets a new handler. */
-  const requestOf = ({ container, useCases, shares }: Context, request: RequestContext) => {
+  /**
+   * The container of a request, and its message bus: each input DTO gets a new handler. A request without a client follows `ends`: its
+   * signal aborts when the backend stops it.
+   */
+  const requestOf = (context: Context, { correlationId }: Correlation, ends?: AbortSignal) => {
+    const { container, useCases } = context;
     const bus = new InProcessMessageBus();
+    const left = new AbortController();
+    const request: RequestContext = { correlationId, signal: ends === undefined ? left.signal : AbortSignal.any([left.signal, ends]) };
+    /** The signal of the request follows the one that goes with a DTO: it aborts with it, or at once if it came aborted. */
+    const follow = (signal: AbortSignal | undefined) => {
+      if (signal?.aborted) left.abort(signal.reason);
+      else signal?.addEventListener("abort", () => { left.abort(signal.reason); });
+    };
+    // Who listens to the events that the handlers of this request publish: a controller that streams them.
+    const heard = new Set<Listener>();
     const scope = container.child([
       bind(RequestContext).toValue(request),
-      bind(EventPublisher).toValue({ publish: (event: DomainEvent) => { tell(shares, event, request); } }),
-      ...(container.has(MessageBus) ? [] : [bind(MessageBus).toValue(bus)])
+      bind(EventPublisher).toValue({ publish: (event: DomainEvent) => {
+        for (const listener of [...heard]) listener(event);
+        tell(context, event, request);
+      } }),
+      ...(container.has(MessageBus) ? [] : [bind(MessageBus).toValue(bus)]),
+      ...(container.has(RequestEvents) ? [] : [bind(RequestEvents).toValue(subscriberOf(heard))])
     ]);
-    for (const { input, handler } of useCases) bus.subscribe(input as never, received => scope.create(handler as Concrete<{ execute(input: unknown): unknown }>).execute(received) as never);
+    for (const { input, handler } of useCases) {
+      bus.subscribe(input as never, (received, { signal }) => {
+        follow(signal);
+        return scope.create(handler as Concrete<{ execute(input: unknown): unknown }>).execute(received);
+      });
+    }
     return { scope, bus };
   };
 
-  const send = async <Output>(input: Input<Output>, request: RequestContext = SYSTEM): Promise<Output> =>
-    requestOf(ownerOf(input.constructor as Class), request).bus.send(input);
+  /** Sends an input DTO in a request of its own: with a correlation id, "system" by default, and the signal of its client, if it has one. */
+  const send = async (input: object, { correlationId = SYSTEM.correlationId, signal }: Partial<Correlation> & { readonly signal?: AbortSignal } = {}): Promise<unknown> =>
+    requestOf(ownerOfInput(input), { correlationId }).bus.send(input, { signal });
+
+  /** The reactions to the events that run, and the name of their input: the stop reports those that outlive it. */
+  const reactions = new Map<Promise<unknown>, string>();
+  /** Sends the input that an event gives, in a request of its own, which ends when the backend stops the reactions. */
+  const react = (input: object, correlationId: string): Promise<unknown> => {
+    const reaction = (async () => requestOf(ownerOfInput(input), { correlationId }, reactionsEnd.signal).bus.send(input))();
+    reactions.set(reaction, input.constructor.name);
+    const forget = () => { reactions.delete(reaction); };
+    void reaction.then(forget, forget);
+    return reaction;
+  };
 
   /**
    * An event that a handler publishes, in its context: the events of shared that the lines of its map that share give go to the shared
    * bus, in the request of the handler. A line that fails is reported: the handler never waits for the other contexts, nor fails for them.
    */
-  const tell = (shares: Context["shares"], event: DomainEvent, request: RequestContext) => {
-    for (const listener of [...listeners]) listener(event);
+  const tell = ({ shares, listeners: contextListeners }: Context, event: DomainEvent, request: Correlation) => {
+    for (const listener of [...listeners, ...contextListeners]) listener(event);
     let told: DomainEvent[];
     try {
       told = shares(event);
@@ -83,14 +176,14 @@ export function createBackend(modules: BackendModules, options: BackendOptions =
     event: line.event,
     inputs: (event: never, envelope: Envelope) => {
       const inputs = line.inputs(event, envelope);
-      const foreign = inputs.find(input => ownerOf(input.constructor as Class) !== contexts.get(name));
+      const foreign = inputs.find(input => ownerOfInput(input) !== contexts.get(name));
       if (foreign) throw new Error(`the context map of ${name} gives ${foreign.constructor.name}, an input of another context: a context map gives the inputs of its own context`);
       return inputs;
     }
   }]));
   const eventBus = new BackendEventBus({
     map: new ContextMap(lines),
-    send: (input, envelope) => send(input, { correlationId: envelope.correlationId }),
+    send: (input, envelope) => react(input, envelope.correlationId),
     nextEventId: options.nextEventId ?? (() => crypto.randomUUID()),
     reportError
   });
@@ -98,7 +191,8 @@ export function createBackend(modules: BackendModules, options: BackendOptions =
   for (const [name, { bindings, useCases, controllers, map }] of Object.entries(modules.contexts)) {
     const contextMap = new ContextMap(map);
     const shares = name === SHARED ? (event: DomainEvent) => [event] : (event: DomainEvent) => contextMap.eventsFor(event);
-    const context = { container: shared.child([...bindings, ...(options.replace?.[name] ?? [])]), useCases, shares };
+    const context = { container: shared.child([...bindings, ...(options.replace?.[name] ?? [])]), useCases, timers: controllers.filter(isTimer), shares, listeners: new Set<Listener>() };
+    if (!context.container.has(ContextEvents)) context.container.use(ContextEvents, { ...subscriberOf(context.listeners), signal: stopping.signal });
     for (const { input } of useCases) owners.set(input, context);
     for (const controller of controllers) owners.set(controller, context);
     contexts.set(name, context);
@@ -114,14 +208,92 @@ export function createBackend(modules: BackendModules, options: BackendOptions =
     return found;
   };
 
+  const schedule = options.schedule ?? everyInterval;
+  const cancels: (() => void)[] = [];
+  /** The turns that run, and the name of their timer controller. */
+  const turns = new Map<Promise<void>, string>();
+
+  /** The rhythm of a timer controller of a context, in milliseconds: one that Node cannot keep is refused. */
+  const rhythmOf = (context: Context, timer: Concrete<TimerController<object>>) => {
+    const { every } = requestOf(context, SYSTEM).scope.create(timer);
+    if (!(every > 0 && every <= MAX_EVERY)) throw new Error(`${timer.name} runs every ${every} ms, but its every is a number of milliseconds above 0, up to ${MAX_EVERY} (24 days): Node runs a longer one every millisecond`);
+    return every;
+  };
+
+  /** Runs a timer controller of a context every `every` milliseconds, each turn in a request of its own, and never two turns at once. */
+  const run = (context: Context, timer: Concrete<TimerController<object>>, every: number) => {
+    let running = false;
+    cancels.push(schedule(every, () => {
+      if (running) return;
+      running = true;
+      const turn = (async () => {
+        try {
+          await requestOf(context, { correlationId: crypto.randomUUID() }, turnsEnd.signal).scope.create(timer).tick();
+        } catch (error) {
+          reportError(error);
+        }
+      })().finally(() => {
+        running = false;
+        turns.delete(turn);
+      });
+      turns.set(turn, timer.name);
+    }));
+  };
+
   return {
+    /**
+     * Starts the timer controllers of the contexts: the server calls it once it serves. A second call starts nothing more. Each rhythm is
+     * checked before any timer runs: a timer that is refused leaves none running.
+     */
+    start: () => {
+      if (cancels.length > 0) return;
+      const timers = [...contexts.values()].flatMap(context => context.timers.map(timer => ({ context, timer, every: rhythmOf(context, timer) })));
+      for (const { context, timer, every } of timers) run(context, timer, every);
+    },
+    /**
+     * Stops what start started, and releases what the containers built: the server calls it when it stops. It ends the events of the
+     * contexts first: a feed has no end, and would hold the requests that the server waits for. Then it cancels the timers, and aborts
+     * the signal of the turns that run: a work in the background stops with the server. It waits for the turns, for the requests that the
+     * server still serves (`requestsDone`), and for the reactions to the events, until the grace ends (`graceOver`, no limit without it).
+     * Then the signal of the reactions aborts, and the turns and the reactions that still run get one more second, after which the backend
+     * reports them. Last, it releases what each context built, then what shared built. A failure to release is reported.
+     */
+    stop: async (requestsDone?: Promise<unknown>, graceOver?: AbortSignal) => {
+      stopping.abort();
+      for (const cancel of cancels.splice(0)) cancel();
+      turnsEnd.abort();
+      const done = (async () => {
+        while (turns.size > 0) await Promise.all([...turns.keys()]);
+        await requestsDone;
+        await eventBus.settled();
+      })();
+      if (graceOver === undefined) await done;
+      else {
+        await untilEndOrAbort(done, graceOver);
+        reactionsEnd.abort();
+        const late = new AbortController();
+        const timer = setTimeout(() => { late.abort(); }, LAST_WAIT_MS);
+        await untilEndOrAbort(done, late.signal);
+        clearTimeout(timer);
+        const running = [...[...turns.values()].map(name => `a turn of ${name}`), ...[...reactions.values()].map(name => `a reaction with ${name}`)];
+        if (running.length > 0) reportError(new Error(`The backend stopped before these ended: ${running.join(", ")}`));
+      }
+      for (const container of [...[...contexts.values()].map(({ container }) => container), shared]) {
+        try {
+          await container.dispose();
+        } catch (error) {
+          reportError(error);
+        }
+      }
+    },
     /** Sends an input DTO to the context that handles it, in a request of its own. */
     send,
     /** The controller of a context, built for a request. */
-    controller: <C>(controller: abstract new (...args: never[]) => C, request: RequestContext = SYSTEM): C =>
-      requestOf(ownerOf(controller), request).scope.create(controller as unknown as Concrete<C>),
+    controller: <C>(controller: abstract new (...args: never[]) => C, request: Correlation = SYSTEM): C =>
+      requestOf(ownerOf(controller, () => new Error(`No context has the controller ${controller.name}: write it in the folder of its use case, as <use-case>.<name>.controller.ts`)), request)
+        .scope.create(controller as unknown as Concrete<C>),
     /** Publishes an event of shared on the shared bus. */
-    publish: (event: DomainEvent, request: RequestContext = SYSTEM) => { eventBus.publish(event, request); },
+    publish: (event: DomainEvent, request: Correlation = SYSTEM) => { eventBus.publish(event, request); },
     redeliver: (published: Published) => { eventBus.redeliver(published.event, published.envelope); },
     /** Watches every event on the shared bus, in its envelope. */
     subscribe: (listener: (published: Published) => void) => eventBus.subscribe(listener),

package/src/di/declareDependencies.js

@@ -9,12 +9,14 @@
  */
 
 /**
- * The code that a module needs after its own, for the containers:
+ * The code that a module needs after its own, for the containers and the message buses:
  * - after each class that has a constructor, the dependencies of the constructor (DEPENDENCIES in Container.ts): the name of each
  *   parameter, if it is optional, and the token of its type when the type has a value of the same name, declared in the module or
  *   imported from a relative path, from a shortcut of the project (#…, which a package.json or a tsconfig.json maps to a folder) or from
  *   one of the packages given (a port and its token, or a class: the kernel gives EventPublisher, DataDirectory…). The token is read only
  *   when the container needs it, thus a cycle between modules does no harm. The name of the type goes with its token, for the errors;
+ * - after each class that has an execute method, the value of the type of its first parameter, found the same way (INPUT in
+ *   discover.ts): the input DTO of a handler, which the message bus gives it;
  * - the name of each token declared without one: the name of its constant.
  * The names are text: the minifier can rename the code.
  * @param {string} code
@@ -31,6 +33,8 @@ export function declareDependencies(code, filename, parse, packages) {
   const values = new Set();
   /** @type {{ name: string; parameters: readonly ESTree.ParamPattern[] }[]} */
   const classes = [];
+  /** @type {{ name: string; input: ESTree.ParamPattern }[]} */
+  const executes = [];
   /** @type {string[]} */
   const tokens = [];
 
@@ -57,9 +61,12 @@ export function declareDependencies(code, filename, parse, packages) {
       values.add(declaration.id.name);
       const constructor = declaration.body.body.find(member => member.type === "MethodDefinition" && member.kind === "constructor");
       if (constructor?.type === "MethodDefinition") classes.push({ name: declaration.id.name, parameters: constructor.value.params });
+      const execute = declaration.body.body.find(member => member.type === "MethodDefinition" && member.kind === "method" && !member.static && !member.computed
+        && member.key.type === "Identifier" && member.key.name === "execute");
+      const input = execute?.type === "MethodDefinition" ? execute.value.params[0] : undefined;
+      if (input) executes.push({ name: declaration.id.name, input });
     }
   }
-  if (classes.length === 0 && tokens.length === 0) return undefined;
 
   /** @type {Map<string, string>} */
   const namespaces = new Map();
@@ -75,8 +82,7 @@ export function declareDependencies(code, filename, parse, packages) {
   };
   /** @type {(parameter: ESTree.ParamPattern, index: number) => string} */
   const dependencyOf = (parameter, index) => {
-    const inner = parameter.type === "TSParameterProperty" ? parameter.parameter : parameter;
-    const pattern = inner.type === "AssignmentPattern" ? inner.left : inner;
+    const { inner, pattern } = partsOf(parameter);
     const name = pattern.type === "Identifier" ? pattern.name : `#${index}`;
     const typed = tokenOf(pattern.typeAnnotation?.typeAnnotation);
     const optional = inner.type === "AssignmentPattern" || pattern.optional === true;
@@ -84,9 +90,23 @@ export function declareDependencies(code, filename, parse, packages) {
   };
 
   const declarations = classes.map(({ name, parameters }) => `${name}[Symbol.for("kernel.dependencies")] = [${parameters.map(dependencyOf).join(", ")}];`);
+  const inputs = executes.flatMap(({ name, input }) => {
+    const typed = tokenOf(partsOf(input).pattern.typeAnnotation?.typeAnnotation);
+    return typed ? [`${name}[Symbol.for("kernel.input")] = () => ${typed.token};`] : [];
+  });
   const imports = [...namespaces].map(([source, alias]) => `import * as ${alias} from ${JSON.stringify(source)};`);
   const names = tokens.map(name => `${name}.name = ${JSON.stringify(name)};`);
-  return [...imports, ...declarations, ...names].join("\n");
+  const lines = [...imports, ...declarations, ...inputs, ...names];
+  return lines.length > 0 ? lines.join("\n") : undefined;
+}
+
+/**
+ * A parameter, without what TypeScript adds around it (`private readonly`), and its pattern, without its default value.
+ * @param {ESTree.ParamPattern} parameter
+ */
+function partsOf(parameter) {
+  const inner = parameter.type === "TSParameterProperty" ? parameter.parameter : parameter;
+  return { inner, pattern: inner.type === "AssignmentPattern" ? inner.left : inner };
 }
 
 /** @type {(name: ESTree.ModuleExportName) => string} */

package/src/di/discover.ts

@@ -1,5 +1,4 @@
 import type { Translation } from "../messaging/ContextMap.js";
-import { Input } from "../messaging/Input.js";
 import type { Binding } from "./Container.js";
 
 export type Class = abstract new (...args: never[]) => unknown;
@@ -21,6 +20,22 @@ export function single<T>(found: T[], what: string): T {
   return found[0];
 }
 
+/** Where the plugin of the kernel writes the input DTO of a handler (see declareDependencies.js). */
+export const INPUT = Symbol.for("kernel.input");
+
+/**
+ * The use case of a handler: the handler, and the input DTO that its execute takes. The plugin of the kernel reads the class from the
+ * type of the parameter, as it reads the ports from the types of the constructor.
+ */
+export function useCaseOf(path: string, module: Record<string, unknown>): UseCase {
+  const handler = single(classesOf(module), `${path} declares one handler`);
+  const input = (handler as { [INPUT]?: () => unknown })[INPUT]?.();
+  if (typeof input !== "function") {
+    throw new Error(`${path}: ${handler.name}.execute names no input DTO. Give its parameter the type of the input DTO, the class that the use case receives.`);
+  }
+  return { input: input as Class, handler };
+}
+
 /**
  * The lines of a context map, as its file gives them: the kernel refuses, when it starts, a map that is not a list of lines, rather than
  * lose what it holds without a word. `isLine` tells a line of the side.
@@ -40,10 +55,10 @@ const isTranslation = ({ shares, event, inputs, events }: Partial<Record<string,
 
 /**
  * Turns the modules found in the backend folder (src/backend by default) into the contexts of the backend: a handler serves the input
- * DTO of its use-case folder, and the context map of a context gives the events of shared that it hears and those of its own that it
+ * DTO that its execute takes, and the context map of a context gives the events of shared that it hears and those of its own that it
  * shares.
  */
-export function discover(found: { bindings: Record<string, readonly Binding[]>; dtos: Modules; handlers: Modules; controllers: Modules; maps: Record<string, Translation[]> }): BackendModules {
+export function discover(found: { bindings: Record<string, readonly Binding[]>; handlers: Modules; controllers: Modules; maps: Record<string, Translation[]> }): BackendModules {
   const contexts: Record<string, ContextModules> = {};
   const context = (path: string) => contexts[contextOf(path)] ??= { bindings: [], useCases: [], controllers: [], map: [] };
   let shared: readonly Binding[] = [];
@@ -52,12 +67,7 @@ export function discover(found: { bindings: Record<string, readonly Binding[]>;
     if (contextOf(path) === "shared") shared = bindings;
     else context(path).bindings = bindings;
   }
-  for (const [path, module] of Object.entries(found.handlers)) {
-    const dto = path.replace(".handler.ts", ".dto.ts");
-    const input = single(classesOf(found.dtos[dto] ?? {}).filter(type => type.prototype instanceof Input), `${dto} declares one input DTO`);
-    const handler = single(classesOf(module), `${path} declares one handler`);
-    context(path).useCases.push({ input, handler });
-  }
+  for (const [path, module] of Object.entries(found.handlers)) context(path).useCases.push(useCaseOf(path, module));
   for (const [path, module] of Object.entries(found.controllers)) context(path).controllers.push(...classesOf(module));
   for (const [path, map] of Object.entries(found.maps)) {
     if (contextOf(path) === "shared") throw new Error(`the backend context shared hears no other context: it has no context map (${path})`);

package/src/di/discoverFrontends.ts

@@ -1,8 +1,7 @@
-import { Input } from "../messaging/Input.js";
 import type { Line } from "../messaging/FrontendContextMap.js";
 import type { StoreDefinition } from "../state/createStore.js";
 import type { Binding } from "./Container.js";
-import { classesOf, linesIn, single, type UseCase } from "./discover.js";
+import { linesIn, useCaseOf, type UseCase } from "./discover.js";
 
 /**
  * A context of the frontend: its bindings, its use cases, its store (none for a context without a use case: its views and its
@@ -20,12 +19,11 @@ const isLine = ({ shares, event, events }: Partial<Record<string, unknown>>) =>
 
 /**
  * Turns the modules found in the frontend folder (src/frontend by default) into the contexts of the frontend: a context has a di.ts,
- * a store at most, and its context map if it hears the context shared or shares events with it; a handler serves the input DTO of its
- * use-case folder.
+ * a store at most, and its context map if it hears the context shared or shares events with it; a handler serves the input DTO that
+ * its execute takes.
  */
 export function discoverFrontends(found: {
   bindings: Record<string, readonly Binding[]>;
-  dtos: Modules;
   handlers: Modules;
   stores: Record<string, StoreDefinition<unknown, unknown>>;
   maps: Record<string, readonly Line[]>;
@@ -46,9 +44,7 @@ export function discoverFrontends(found: {
   for (const [path, module] of Object.entries(found.handlers)) {
     const context = contexts[contextOf(path)];
     if (!context) throw new Error(`${path} belongs to a frontend without a di.ts`);
-    const dto = path.replace(".handler.ts", ".dto.ts");
-    const input = single(classesOf(found.dtos[dto] ?? {}).filter(type => type.prototype instanceof Input), `${dto} declares one input DTO`);
-    context.useCases.push({ input, handler: single(classesOf(module), `${path} declares one handler`) });
+    context.useCases.push(useCaseOf(path, module));
   }
   for (const [name, context] of Object.entries(contexts)) {
     if (context.useCases.length > 0 && !context.store) {