@ingenioz-it/caits 0.6.0 → 0.8.0

package/src/testing/backend/presentationScenario.ts

@@ -1,19 +1,39 @@
 import { expect } from "vitest";
+import type { TimerController } from "../../messaging/TimerController.js";
 import type { startPresentationApplication } from "./presentationApplication.js";
 
 type PresentationApplication = ReturnType<typeof startPresentationApplication>;
 
+/** The body of a request, and its type: a form, a text as it is, or JSON. */
+function bodyOf(body: unknown): RequestInit {
+  if (body === undefined) return {};
+  // A form, which fetch sends with its type: multipart/form-data for a FormData, application/x-www-form-urlencoded for URLSearchParams.
+  if (body instanceof FormData || body instanceof URLSearchParams) return { body };
+  return { body: typeof body === "string" ? body : JSON.stringify(body), headers: { "content-type": "application/json" } };
+}
+
 export class PresentationScenario {
   private request: Request | undefined;
+  /** The client of the request: it leaves when the test has read the start of a stream. */
+  private readonly client = new AbortController();
+  private timer: (abstract new (...args: never[]) => TimerController<object>) | undefined;
 
   constructor(private readonly app: PresentationApplication) {}
 
-  /** A request with a body sends it as JSON: a string is the text of the body as it is (`"{not json"`), any other value its JSON. */
-  givenTheRequest(method: string, path: string, body?: unknown): this {
-    this.request = new Request(`http://localhost${path}`, {
-      method,
-      ...(body === undefined ? {} : { body: typeof body === "string" ? body : JSON.stringify(body), headers: { "content-type": "application/json" } })
-    });
+  /**
+   * A request with a body sends it as JSON: a string is the text of the body as it is (`"{not json"`), any other value its JSON. A
+   * FormData is sent as a form, multipart/form-data, with its files, and URLSearchParams as a form of URL encoding. The headers go with
+   * it, over the type that its body gives.
+   */
+  givenTheRequest(method: string, path: string, body?: unknown, headers: Readonly<Record<string, string>> = {}): this {
+    const sent = bodyOf(body);
+    this.request = new Request(`http://localhost${path}`, { method, signal: this.client.signal, ...sent, headers: { ...sent.headers as Record<string, string> | undefined, ...headers } });
+    return this;
+  }
+
+  /** The timer controller whose turn the test runs, instead of a request. */
+  givenTheTimer(timer: abstract new (...args: never[]) => TimerController<object>): this {
+    this.timer = timer;
     return this;
   }
 
@@ -27,12 +47,69 @@ export class PresentationScenario {
     return this;
   }
 
+  /** The events that the application publishes when it receives the last message, before it answers: a stream writes them. */
+  givenTheApplicationPublishes(...events: object[]): this {
+    this.app.messageBus.publishTheLast(events);
+    return this;
+  }
+
+  /** The application never answers the last message: its handler keeps running, while a stream writes what it published. */
+  givenTheApplicationKeepsRunning(): this {
+    this.app.messageBus.keepTheLastRunning();
+    return this;
+  }
+
   givenTheApplicationFails(error: Error): this {
     this.app.messageBus.failTheLast(error);
     return this;
   }
 
-  async expectTheResponseToBe(status: number, body?: unknown, headers: Record<string, string> = {}): Promise<void> {
+  /** Runs one turn of the timer: it runs every `every` milliseconds, sends what the test expects, and reports no error. */
+  async expectTheTurnToRunEvery(every: number): Promise<void> {
+    if (this.timer === undefined) throw new Error("PresentationScenario: call givenTheTimer(...) before expectTheTurnToRunEvery(...).");
+    expect(await this.app.tick(this.timer)).toBe(every);
+    expect(this.app.reportedErrors).toEqual([]);
+    this.app.messageBus.verify();
+  }
+
+  /** Reads the whole stream of the response: its status, its headers (null for a header that it does not have), and its text. */
+  async expectTheStreamToBe(status: number, text: string, headers: Record<string, string | null> = {}): Promise<void> {
+    const response = await this.stream(status, headers);
+    expect(await response.text()).toBe(text);
+    this.app.messageBus.verify();
+  }
+
+  /**
+   * Reads the start of the stream of the response, as long as the text, then the client leaves: the test of a feed, or of a client that
+   * leaves. The signal that went with each DTO aborts then: the handler sees the client leave.
+   */
+  async expectTheStreamToStartWith(status: number, text: string, headers: Record<string, string | null> = {}): Promise<void> {
+    const reader = (await this.stream(status, headers)).body!.getReader();
+    const decoder = new TextDecoder();
+    let read = "";
+    while (read.length < text.length) {
+      const chunk = await reader.read();
+      if (chunk.done) break;
+      read += decoder.decode(chunk.value, { stream: true });
+    }
+    expect(read.slice(0, text.length)).toBe(text);
+    this.client.abort();
+    await reader.cancel();
+    await new Promise(resolve => { setTimeout(resolve, 0); });
+    this.app.messageBus.verify();
+    this.app.messageBus.verifyLeft();
+  }
+
+  private async stream(status: number, headers: Record<string, string | null>): Promise<Response> {
+    if (this.request === undefined) throw new Error("PresentationScenario: call givenTheRequest(...) before reading its stream.");
+    const response = await this.app.fetch(this.request);
+    expect(response.status).toBe(status);
+    for (const [name, value] of Object.entries(headers)) expect(response.headers.get(name), `header ${name}`).toBe(value);
+    return response;
+  }
+
+  /** Reads the response: its status, its body, and its headers, null for a header that it does not have. */
+  async expectTheResponseToBe(status: number, body?: unknown, headers: Record<string, string | null> = {}): Promise<void> {
     if (this.request === undefined) throw new Error("PresentationScenario: call givenTheRequest(...) before expectTheResponseToBe(...).");
     const response = await this.app.fetch(this.request);
 

package/src/testing/frontend/applicationScenario.ts

@@ -1,5 +1,4 @@
 import { expect } from "vitest";
-import type { Input } from "../../messaging/Input.js";
 import type { TestApplication } from "./applications.js";
 
 /**
@@ -10,7 +9,7 @@ import type { TestApplication } from "./applications.js";
 export class ApplicationScenario implements PromiseLike<void> {
   private readonly expected: object[] = [];
 
-  constructor(private readonly app: TestApplication, private readonly dto: Input<void>) {}
+  constructor(private readonly app: TestApplication, private readonly dto: object) {}
 
   expectItToPublish(event: object): this {
     this.expected.push(event);
@@ -32,5 +31,5 @@ export class ApplicationScenario implements PromiseLike<void> {
 }
 
 export const applicationScenario = (app: TestApplication) => ({
-  givenTheDto: (dto: Input<void>) => new ApplicationScenario(app, dto)
+  givenTheDto: (dto: object) => new ApplicationScenario(app, dto)
 });

package/src/testing/frontend/applications.ts

@@ -4,7 +4,7 @@ import type { Binding } from "../../di/Container.js";
 import { createFrontendWithBus } from "../../di/createFrontend.js";
 import { discoveredFrontends } from "../../di/discoveredFrontends.js";
 import type { Fetcher } from "../../di/Fetcher.js";
-import type { Input } from "../../messaging/Input.js";
+import { UnknownInputError } from "../../messaging/InProcessMessageBus.js";
 import type { Token } from "../../Token.js";
 
 /** The test.di.ts of each context that has one: the bindings that replace, in tests, those that reach outside the browser. */
@@ -37,7 +37,7 @@ export function createTestApplication() {
 
   const ownerOf = (input: object): string => {
     const name = Object.keys(discoveredFrontends).find(context => discoveredFrontends[context].useCases.some(({ input: type }) => type === input.constructor));
-    if (name === undefined) throw new Error(`No context handles ${input.constructor.name}`);
+    if (name === undefined) throw new UnknownInputError(input.constructor.name);
     return name;
   };
 
@@ -50,7 +50,7 @@ export function createTestApplication() {
 
   return {
     /** Sends an input DTO to the message bus of the context that handles it. */
-    send: <Output>(input: Input<Output>): Promise<Output> => frontend(ownerOf(input)).bus.send(input),
+    send: (input: object): Promise<unknown> => frontend(ownerOf(input)).bus.send(input),
     /** The dependency with this token, built now if no handler needed it before. */
     get: <T>(token: Token<T>): T => {
       const found = holders(token);

package/src/testing/frontend/frontends.ts

@@ -1,5 +1,4 @@
 import { FrontendEventBus } from "../../messaging/FrontendEventBus.js";
-import type { Input } from "../../messaging/Input.js";
 import { createStore, type StoreDefinition } from "../../state/createStore.js";
 import type { EventPublisher } from "../../messaging/EventPublisher.js";
 import { discoveredFrontends } from "../../di/discoveredFrontends.js";
@@ -9,7 +8,7 @@ type EventOf<F> = F extends { events: EventPublisher<infer E> } ? E : never;
 type StoreOf<F> = F extends { store: infer S } ? S : undefined;
 
 /** The presentation of a context in a test: its frontend, the DTOs that its store sent, and the events that it published. */
-export type TestPresentation<F> = { events: EventPublisher<EventOf<F>>; store: StoreOf<F>; sent: Input<unknown>[]; published: EventOf<F>[] };
+export type TestPresentation<F> = { events: EventPublisher<EventOf<F>>; store: StoreOf<F>; sent: object[]; published: EventOf<F>[] };
 
 /**
  * The presentation of a context, as its views and its components get it: its EventPublisher and its store (none, for a context
@@ -19,11 +18,11 @@ export type TestPresentation<F> = { events: EventPublisher<EventOf<F>>; store: S
  */
 export function testPresentation<Name extends keyof Frontends>(name: Name): TestPresentation<Frontends[Name]> {
   const events = new FrontendEventBus<EventOf<Frontends[Name]>>();
-  const sent: Input<unknown>[] = [];
+  const sent: object[] = [];
   const published: EventOf<Frontends[Name]>[] = [];
   events.subscribe(event => { published.push(event); });
   const definition = discoveredFrontends[name].store as StoreDefinition<unknown, EventOf<Frontends[Name]>> | undefined;
-  const store = definition && createStore(definition, { events, bus: { send: <Output>(input: Input<Output>) => { sent.push(input); return Promise.resolve(undefined as Output); } } });
+  const store = definition && createStore(definition, { events, bus: { send: (input: object) => { sent.push(input); return Promise.resolve(undefined); } } });
   return { events, store, sent, published } as unknown as TestPresentation<Frontends[Name]>;
 }
 

package/src/testing/shared/FakeMessageBus.ts

@@ -1,10 +1,15 @@
-import type { MessageBus } from "../../messaging/MessageBus.js";
+import type { MessageBus, Sending } from "../../messaging/MessageBus.js";
 
-type Outcome = { reply: unknown } | { error: Error };
-type Expectation = { message: object; outcome: Outcome | undefined; received: boolean };
+type Outcome = { reply: unknown } | { error: Error } | { pending: true };
+/** A message that the test expects: what the application answers, whether it came, what it publishes, and the signal that went with it. */
+type Expectation = { message: object; outcome: Outcome | undefined; received: boolean; publishes: readonly object[]; signal?: AbortSignal };
+
+/** A matcher of Vitest, as `expect.any(String)` gives it: a field of an expected message that the test cannot know, an id drawn by chance. */
+const isMatcher = (value: object): value is { asymmetricMatch(other: unknown): boolean } => typeof (value as { asymmetricMatch?: unknown }).asymmetricMatch === "function";
 
 function same(left: unknown, right: unknown): boolean {
   if (Object.is(left, right)) return true;
+  if (typeof left === "object" && left !== null && isMatcher(left)) return left.asymmetricMatch(right);
   if (typeof left !== "object" || typeof right !== "object" || left === null || right === null) return false;
   if (Object.getPrototypeOf(left) !== Object.getPrototypeOf(right)) return false;
   if (left instanceof Date) return left.getTime() === (right as Date).getTime();
@@ -17,8 +22,21 @@ export class FakeMessageBus implements MessageBus {
   private expectations: Expectation[] = [];
   private unexpected: object[] = [];
 
+  /** What the application publishes when it receives a message: a test of a controller that streams gives where the events go. */
+  constructor(private readonly publish: (event: object) => void = () => {}) {}
+
   expect(message: object): void {
-    this.expectations.push({ message, outcome: undefined, received: false });
+    this.expectations.push({ message, outcome: undefined, received: false, publishes: [] });
+  }
+
+  /** The events that the application publishes when it receives the last message, before it answers. */
+  publishTheLast(events: readonly object[]): void {
+    this.last("publishes").publishes = events;
+  }
+
+  /** The application never answers the last message: its handler keeps running. */
+  keepTheLastRunning(): void {
+    this.last("keeps running").outcome = { pending: true };
   }
 
   replyToTheLast(output: unknown): void {
@@ -29,7 +47,7 @@ export class FakeMessageBus implements MessageBus {
     this.last("fails").outcome = { error };
   }
 
-  send(message: object): Promise<never> {
+  send(message: object, sending: Sending = {}): Promise<never> {
     const expected = this.expectations.find(candidate => !candidate.received && same(candidate.message, message));
     if (!expected) {
       this.unexpected.push(message);
@@ -37,7 +55,10 @@ export class FakeMessageBus implements MessageBus {
       return Promise.reject(new Error(`The application sent a message nobody expected: ${message.constructor.name} ${JSON.stringify(message)} (still expected: ${pending})`));
     }
     expected.received = true;
+    expected.signal = sending.signal;
+    for (const event of expected.publishes) this.publish(event);
     if (!expected.outcome) return Promise.reject(new Error(`Nothing is prepared for the application to be answered: ${message.constructor.name}`));
+    if ("pending" in expected.outcome) return new Promise(() => {});
     return "error" in expected.outcome ? Promise.reject(expected.outcome.error) : Promise.resolve(expected.outcome.reply as never);
   }
 
@@ -50,6 +71,19 @@ export class FakeMessageBus implements MessageBus {
     if (problems.length) throw new Error(problems.join("\n"));
   }
 
+  /**
+   * Once the client left: each message came with the signal of its request, which aborted. Without it, the handler would not see the
+   * client leave.
+   */
+  verifyLeft(): void {
+    const problems = this.expectations.filter(({ received }) => received).flatMap(({ message, signal }) => {
+      const name = `${message.constructor.name} ${JSON.stringify(message)}`;
+      if (!signal) return [`the application sent ${name} without the signal of its request: its handler cannot see the client leave`];
+      return signal.aborted ? [] : [`the signal that went with ${name} did not abort when the client left`];
+    });
+    if (problems.length) throw new Error(problems.join("\n"));
+  }
+
   private last(step: string): Expectation {
     const last = this.expectations.at(-1);
     if (!last) throw new Error(`Say which message is expected before saying how the application ${step}.`);

package/src/virtual-modules.d.ts

@@ -4,7 +4,6 @@ declare module "virtual:kernel/backend" {
   import type { Translation } from "@ingenioz-it/caits/messaging/ContextMap";
   type Modules = Record<string, Record<string, unknown>>;
   export const bindings: Record<string, readonly Binding[]>;
-  export const dtos: Modules;
   export const handlers: Modules;
   export const controllers: Modules;
   export const maps: Record<string, Translation[]>;
@@ -21,7 +20,6 @@ declare module "virtual:kernel/frontend" {
   import type { StoreDefinition } from "@ingenioz-it/caits/state/createStore";
   type Modules = Record<string, Record<string, unknown>>;
   export const bindings: Record<string, readonly Binding[]>;
-  export const dtos: Modules;
   export const handlers: Modules;
   export const stores: Record<string, StoreDefinition<unknown, unknown>>;
   export const maps: Record<string, readonly Line[]>;

package/src/vite.js

@@ -5,6 +5,8 @@ import MagicString from "magic-string";
 import { normalizePath, parseSync } from "vite";
 import { declareDependencies } from "./di/declareDependencies.js";
 
+export { adapter } from "./adapter.js";
+
 /** @import { Plugin } from "vite" */
 /** @import { KernelOptions } from "./vite.types.js" */
 
@@ -58,7 +60,6 @@ function dependencies(source) {
 const CONTEXT_MODULES = {
   "virtual:kernel/backend": [
     ["bindings", "backend/*/di.ts", true],
-    ["dtos", "backend/*/{command,query}/*/*.dto.ts"],
     ["handlers", "backend/*/{command,query}/*/*.handler.ts"],
     ["controllers", "backend/*/{command,query}/*/*.controller.ts"],
     ["maps", "backend/*/context-map.ts", true]
@@ -66,7 +67,6 @@ const CONTEXT_MODULES = {
   "virtual:kernel/backend-test": [["bindings", "backend/*/test.di.ts", true]],
   "virtual:kernel/frontend": [
     ["bindings", "frontend/*/di.ts", true],
-    ["dtos", "frontend/*/{command,query}/*/*.dto.ts"],
     ["handlers", "frontend/*/{command,query}/*/*.handler.ts"],
     ["stores", "frontend/*/presentation/store/*Store.ts", true],
     ["maps", "frontend/*/context-map.ts", true]

package/src/vite.types.d.ts

@@ -1,3 +1,4 @@
+import type { Adapter } from "@marko/run/vite";
 import type { Plugin } from "vite";
 
 /** The types of vite.js, for the projects: TypeScript reads no types from the JavaScript of a package. Keep them the same as vite.js. */
@@ -12,3 +13,9 @@ export declare function kernel(options?: KernelOptions): Plugin[];
 
 /** Makes @marko/run write the types of the routes whole: `caits check` runs the checks at once, and some of them read these types. */
 export declare function wholeRouteTypes(): Plugin;
+
+/**
+ * The adapter of @marko/run for a CAITS app: the server of `npm start` (the entry that it gives to `npm run build`) and that of `caits dev`
+ * boot the backend, start its timers, and stop it on SIGTERM or SIGINT; `caits dev` boots it again when its code changes.
+ */
+export declare function adapter(): Adapter;