@ingenioz-it/caits 0.0.0-stage → 0.5.0

package/src/testing/frontend/applications.ts

@@ -0,0 +1,70 @@
+/// <reference path="../../virtual-modules.d.ts" />
+import { bindings as testDi } from "virtual:kernel/frontend-test";
+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 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. */
+const testBindings: Record<string, readonly Binding[] | undefined> = Object.fromEntries(
+  Object.entries(testDi)
+    .map(([path, bindings]) => [/frontend\/([^/]+)\//.exec(path)![1], bindings])
+);
+
+const offline: Fetcher = input => Promise.reject(new Error(`A test frontend has no network: replace the dependency that asked for ${input}`));
+
+type TestFrontend = ReturnType<typeof createFrontendWithBus>;
+
+/**
+ * Every context, built from its di.ts with its test.di.ts over it, each one alone, and only when a test needs it. A test sends input
+ * DTOs, as the stores do, and reads the events that the handlers published.
+ */
+export function createTestApplication() {
+  const published: object[] = [];
+  const built = new Map<string, TestFrontend>();
+
+  const frontend = (name: string): TestFrontend => {
+    let found = built.get(name);
+    if (!found) {
+      found = createFrontendWithBus(discoveredFrontends[name], offline, testBindings[name]);
+      found.events.subscribe(event => { published.push(event as object); });
+      built.set(name, found);
+    }
+    return found;
+  };
+
+  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}`);
+    return name;
+  };
+
+  /** The contexts that bind this token. */
+  const holders = (token: Token<unknown>): string[] => {
+    const found = Object.keys(discoveredFrontends).filter(name => [...discoveredFrontends[name].bindings, ...testBindings[name] ?? []].some(binding => binding.key === token));
+    if (found.length === 0) throw new Error(`No context binds ${token.name}`);
+    return found;
+  };
+
+  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),
+    /** The dependency with this token, built now if no handler needed it before. */
+    get: <T>(token: Token<T>): T => {
+      const found = holders(token);
+      if (found.length > 1) throw new Error(`The contexts ${found.join(", ")} each build their own ${token.name}`);
+      return frontend(found[0]).get(token);
+    },
+    /** Gives the dependency that the app uses from now on: a test builds its own Fake, and keeps it to arrange and check it. */
+    use: <T, Given extends T>(token: Token<T>, value: Given): Given => {
+      for (const name of holders(token)) frontend(name).use(token, value);
+      return value;
+    },
+    /** Every event the handlers published, in the order they published them. */
+    published
+  };
+}
+
+export type TestApplication = ReturnType<typeof createTestApplication>;

package/src/testing/frontend/frontends.ts

@@ -0,0 +1,28 @@
+import { FrontendEventBus } from "../../messaging/FrontendEventBus.js";
+import type { Input } from "../../messaging/Input.js";
+import { createStore, type StoreDefinition } from "../../state/createStore.js";
+import type { Frontend } from "../../state/request.js";
+import { discoveredFrontends } from "../../di/discoveredFrontends.js";
+import { frontendsOn, type Frontends } from "../../di/frontend.js";
+
+type StateOf<F> = F extends Frontend<infer S, unknown> ? S : never;
+type EventOf<F> = F extends Frontend<unknown, infer E> ? E : never;
+
+/**
+ * The presentation of a context, as its views get it: its EventPublisher and its store. The message bus of the store is a Fake: it
+ * records the DTOs it receives, and answers nothing. A test publishes the events of the handlers itself.
+ */
+export function testPresentation<Name extends keyof Frontends>(name: Name): Frontend<StateOf<Frontends[Name]>, EventOf<Frontends[Name]>> & { sent: Input<unknown>[] } {
+  const events = new FrontendEventBus<EventOf<Frontends[Name]>>();
+  const sent: Input<unknown>[] = [];
+  const definition = discoveredFrontends[name].store as StoreDefinition<StateOf<Frontends[Name]>, EventOf<Frontends[Name]>>;
+  const store = createStore(definition, { events, bus: { send: <Output>(input: Input<Output>) => { sent.push(input); return Promise.resolve(undefined as Output); } } });
+  return { events, store, sent };
+}
+
+/** A $global as Marko gives it to the views: the address of the page, and frontends already built. */
+export function globalWith(frontends: Partial<Frontends>, url = "http://localhost/"): object {
+  const $global = { url: new URL(url) };
+  for (const [name, frontend] of Object.entries(frontends)) frontendsOn($global).set(name, frontend);
+  return $global;
+}

package/src/testing/frontend/infra.ts

@@ -0,0 +1,2 @@
+/** Everything an infra test of the frontend imports: the contract of a port, and the test of each implementation that runs it. */
+export { afterAll, afterEach, beforeAll, beforeEach, describe, expect, test, vi } from "vitest";

package/src/testing/frontend/marko.ts

@@ -0,0 +1,12 @@
+type Mountable = { mount(input: unknown, container: Element): { update(input: unknown): void; destroy(): void } };
+
+export async function mountTemplate(template: unknown, input: unknown = {}) {
+  const container = document.createElement("div");
+  document.body.append(container);
+  const instance = (template as Mountable).mount(input, container);
+  await settle();
+  return { container, instance, async update(next: unknown) { instance.update(next); await settle(); }, async destroy() { instance.destroy(); await settle(); container.remove(); } };
+}
+
+export const settle = () => new Promise(resolve => setTimeout(resolve, 20));
+export const press = async (element: Element | null | undefined) => { (element as HTMLElement).click(); await settle(); };

package/src/testing/frontend/presentation.ts

@@ -0,0 +1,7 @@
+/**
+ * Everything a presentation test of the frontend imports: the test of a View. The file starts with `// @vitest-environment happy-dom`.
+ * `testPresentation` gives the real FrontendEventBus and Store of a context, with a Fake MessageBus that records the DTOs in `sent`.
+ */
+export { afterAll, afterEach, beforeAll, beforeEach, describe, expect, test, vi } from "vitest";
+export { globalWith, testPresentation } from "./frontends.js";
+export { mountTemplate, press, settle } from "./marko.js";

package/src/testing/shared/FakeMessageBus.ts

@@ -0,0 +1,58 @@
+import type { MessageBus } from "../../messaging/MessageBus.js";
+
+type Outcome = { reply: unknown } | { error: Error };
+type Expectation = { message: object; outcome: Outcome | undefined; received: boolean };
+
+function same(left: unknown, right: unknown): boolean {
+  if (Object.is(left, right)) return true;
+  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();
+  const keys = Object.keys(left);
+  return keys.length === Object.keys(right).length && keys.every(key => Object.hasOwn(right, key) && same((left as Record<string, unknown>)[key], (right as Record<string, unknown>)[key]));
+}
+
+/** A message bus that only records: a test says which messages it expects, and what the application answers to each one. */
+export class FakeMessageBus implements MessageBus {
+  private expectations: Expectation[] = [];
+  private unexpected: object[] = [];
+
+  expect(message: object): void {
+    this.expectations.push({ message, outcome: undefined, received: false });
+  }
+
+  replyToTheLast(output: unknown): void {
+    this.last("replies").outcome = { reply: output };
+  }
+
+  failTheLast(error: Error): void {
+    this.last("fails").outcome = { error };
+  }
+
+  send(message: object): Promise<never> {
+    const expected = this.expectations.find(candidate => !candidate.received && same(candidate.message, message));
+    if (!expected) {
+      this.unexpected.push(message);
+      const pending = this.expectations.filter(candidate => !candidate.received).map(candidate => JSON.stringify(candidate.message)).join(", ") || "none";
+      return Promise.reject(new Error(`The application sent a message nobody expected: ${message.constructor.name} ${JSON.stringify(message)} (still expected: ${pending})`));
+    }
+    expected.received = true;
+    if (!expected.outcome) return Promise.reject(new Error(`Nothing is prepared for the application to be answered: ${message.constructor.name}`));
+    return "error" in expected.outcome ? Promise.reject(expected.outcome.error) : Promise.resolve(expected.outcome.reply as never);
+  }
+
+  verify(): void {
+    const missing = this.expectations.filter(expectation => !expectation.received).map(expectation => expectation.message);
+    const problems = [
+      ...(this.unexpected.length ? [`messages the application sent although nobody expected them: ${JSON.stringify(this.unexpected)}`] : []),
+      ...(missing.length ? [`messages the application was expected to send: ${JSON.stringify(missing)}`] : [])
+    ];
+    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}.`);
+    return last;
+  }
+}

package/src/testing/shared/tempDirectories.ts

@@ -0,0 +1,15 @@
+import { mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterAll } from "vitest";
+
+/** Gives a new empty folder at each call, and removes them all after the tests of the file. */
+export function useTempDirectories() {
+  const directories: string[] = [];
+  afterAll(async () => { await Promise.all(directories.map(directory => rm(directory, { recursive: true, force: true }))); });
+  return async (): Promise<string> => {
+    const directory = await mkdtemp(join(tmpdir(), "contract-"));
+    directories.push(directory);
+    return directory;
+  };
+}

package/src/virtual-modules.d.ts

@@ -0,0 +1,33 @@
+/** The modules of the kernel's Vite plugin (vite.js): the files of the contexts, by their path from the root of the project. */
+declare module "virtual:kernel/backend" {
+  import type { Binding } from "@ingenioz-it/caits/di/Container";
+  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 map: Record<string, Translation[]>;
+}
+
+declare module "virtual:kernel/backend-test" {
+  import type { Binding } from "@ingenioz-it/caits/di/Container";
+  export const bindings: Record<string, readonly Binding[]>;
+}
+
+declare module "virtual:kernel/frontend" {
+  import type { Binding } from "@ingenioz-it/caits/di/Container";
+  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>>;
+}
+
+declare module "virtual:kernel/frontend-test" {
+  import type { Binding } from "@ingenioz-it/caits/di/Container";
+  export const bindings: Record<string, readonly Binding[]>;
+}
+
+declare module "virtual:marko-run/__marko-run__router.js";

package/src/vite.js

@@ -0,0 +1,162 @@
+// JavaScript, not TypeScript: Node loads this file itself when Vite loads its configuration, and Node strips no types in node_modules,
+// where a project installs the kernel. TypeScript checks the types of the comments; vite.types.d.ts gives them to the projects.
+import { promises as files } from "node:fs";
+import MagicString from "magic-string";
+import { normalizePath, parseSync } from "vite";
+import { declareDependencies } from "./di/declareDependencies.js";
+
+/** @import { Plugin } from "vite" */
+/** @import { KernelOptions } from "./vite.types.js" */
+
+/** The name of this package: the app imports the tokens of the kernel (EventPublisher, DataDirectory, Fetcher…) with it. */
+const KERNEL = "@ingenioz-it/caits";
+
+/** The folder of the kernel: its classes and its tokens need the same code (a Controller gets its MessageBus, a token its name). */
+const OWN_FOLDER = `${normalizePath(import.meta.dirname)}/`;
+
+/**
+ * The plugins of the kernel, for Vite and Vitest:
+ * - the dependencies of the classes, for the containers (see declareDependencies);
+ * - the contexts, found by convention in {source}/backend and {source}/frontend (see discovered.ts and discoveredFrontends.ts).
+ * @param {KernelOptions} [options]
+ * @returns {Plugin[]}
+ */
+export function kernel({ source = "src" } = {}) {
+  const folder = `/${source.replace(/^\/+|\/+$/g, "")}`;
+  return [dependencies(folder), contexts(folder)];
+}
+
+/**
+ * Writes, after the code of each module, the dependencies of its classes and the names of its tokens: in the modules whose classes the
+ * containers build, those of the project and those of the kernel. They are written before the minifier renames the code.
+ * @param {string} source
+ * @returns {Plugin}
+ */
+function dependencies(source) {
+  /** @type {string[]} */
+  let folders = [];
+  return {
+    name: "kernel-dependencies",
+    enforce: "pre",
+    configResolved: config => { folders = [`${config.root}${source}/`, OWN_FOLDER]; },
+    transform(code, id) {
+      if (!id.endsWith(".ts") || !folders.some(folder => id.startsWith(folder))) return undefined;
+      const declarations = declareDependencies(code, id, parseSync, [KERNEL]);
+      if (declarations === undefined) return undefined;
+      // The written code maps to no line of the module: the stack traces and the coverage show only the code of the module.
+      const module = new MagicString(code).append(`\n${declarations}`);
+      return { code: module.toString(), map: module.generateMap({ hires: true, source: id }) };
+    }
+  };
+}
+
+/**
+ * The modules that find the contexts: each export of a module is a pattern of files, from the source folder, and whether it takes only
+ * the default export of each file. The test.di.ts files have modules of their own: the production code never reads them.
+ * @type {Record<string, [name: string, pattern: string, onlyDefault?: boolean][]>}
+ */
+const CONTEXT_MODULES = {
+  "virtual:kernel/backend": [
+    ["bindings", "backend/*/di.ts", true],
+    ["dtos", "backend/*/application/*/*/*.dto.ts"],
+    ["handlers", "backend/*/application/*/*/*.handler.ts"],
+    ["controllers", "backend/*/presentation/*/*.controller.ts"],
+    ["map", "backend/context-map.ts", true]
+  ],
+  "virtual:kernel/backend-test": [["bindings", "backend/*/test.di.ts", true]],
+  "virtual:kernel/frontend": [
+    ["bindings", "frontend/*/di.ts", true],
+    ["dtos", "frontend/*/application/*/*/*.dto.ts"],
+    ["handlers", "frontend/*/application/*/*/*.handler.ts"],
+    ["stores", "frontend/*/presentation/store/*Store.ts", true]
+  ],
+  "virtual:kernel/frontend-test": [["bindings", "frontend/*/test.di.ts", true]]
+};
+
+/**
+ * The modules that find the contexts. Vite reads the patterns when it builds: they must be literal, and they start at the root of the
+ * project, because a virtual module has no folder.
+ * Vite and Vitest follow the files that a module loaded, but not the new files that its patterns find: when a file of a pattern comes
+ * or goes, the plugin makes the environments load the module again. It also tells the watcher that the files that import the module
+ * changed: Vitest, in watch mode, then runs again the tests that use them (a new handler is found without a restart of Vitest).
+ * @param {string} source
+ * @returns {Plugin}
+ */
+function contexts(source) {
+  /** @type {(pattern: string, onlyDefault?: boolean) => string} */
+  const glob = (pattern, onlyDefault = false) =>
+    `import.meta.glob(${JSON.stringify(`${source}/${pattern}`)}, { eager: true${onlyDefault ? `, import: "default"` : ""} })`;
+  /** A pattern as a regular expression: `*` is a part of a name, without "/". */
+  const matcherOf = (/** @type {string} */ pattern) =>
+    new RegExp(`^${`${source}/${pattern}`.replace(/[.+?^${}()|[\]\\]/g, "\\$&").replaceAll("*", "[^/]*")}$`);
+  const modules = Object.entries(CONTEXT_MODULES).map(([id, exports]) => ({
+    id,
+    code: exports.map(([name, pattern, onlyDefault]) => `export const ${name} = ${glob(pattern, onlyDefault)};`).join("\n"),
+    matchers: exports.map(([, pattern]) => matcherOf(pattern))
+  }));
+  const moduleOf = (/** @type {string} */ id) => modules.find(module => module.id === id);
+  let root = "";
+  return {
+    name: "kernel-contexts",
+    config: () => ({
+      // Vite processes the package as the code of the project, also when it is installed: it holds TypeScript and imports these modules.
+      ssr: { noExternal: [KERNEL] },
+      optimizeDeps: { exclude: [KERNEL] },
+      // The shortcut #shared leads to the backend context shared from every file (the tsconfig.json of the project says it to TypeScript).
+      // Vite reads an alias before the "imports" of the package.json of a context (#context), which cannot lead out of the context.
+      resolve: { alias: [{ find: /^#shared\//, replacement: `${source}/backend/shared/` }] }
+    }),
+    configResolved: config => { root = config.root; },
+    configureServer: server => {
+      /** @param {string} file */
+      const reload = file => {
+        const path = normalizePath(file);
+        if (!path.startsWith(`${root}/`)) return;
+        const fromRoot = path.slice(root.length);
+        for (const { id } of modules.filter(({ matchers }) => matchers.some(matcher => matcher.test(fromRoot)))) {
+          /** @type {Set<string>} */
+          const importers = new Set();
+          for (const { moduleGraph } of Object.values(server.environments)) {
+            const loaded = moduleGraph.getModuleById(`\0${id}`);
+            if (!loaded) continue;
+            moduleGraph.invalidateModule(loaded);
+            for (const { file: importer } of loaded.importers) if (importer) importers.add(importer);
+          }
+          for (const importer of importers) server.watcher.emit("change", importer);
+        }
+      };
+      server.watcher.on("add", reload);
+      server.watcher.on("unlink", reload);
+    },
+    resolveId: id => moduleOf(id) ? `\0${id}` : undefined,
+    load: id => id.startsWith("\0") ? moduleOf(id.slice(1))?.code : undefined
+  };
+}
+
+/** The file of the types of the routes, which @marko/run writes in the folder .marko-run of the project. */
+const ROUTE_TYPES = /[\\/]\.marko-run[\\/]routes\.d\.ts$/;
+let routeTypesWrittenWhole = false;
+
+/**
+ * Makes @marko/run write the types of the routes (.marko-run/routes.d.ts) whole. It writes the file in place each time it reads the
+ * routes (a build, a start of Vitest or of the development server): while it writes, the file is empty. `caits check` runs the checks
+ * at once, and the lint and the type check read this file: they saw it empty when another check started. Now the text goes in a file of
+ * its own, which then takes the name of the file. @marko/run gives no other way: the plugin replaces the writeFile of node:fs, for this
+ * file only, as soon as the configuration of Vite makes the plugin, before the plugins write anything.
+ * @returns {Plugin}
+ */
+export function wholeRouteTypes() {
+  if (!routeTypesWrittenWhole) {
+    routeTypesWrittenWhole = true;
+    const { writeFile, rename } = files;
+    /** @type {typeof files.writeFile} */
+    const writeWhole = async (file, data, options) => {
+      if (typeof file !== "string" || !ROUTE_TYPES.test(file)) return writeFile(file, data, options);
+      const draft = `${file}.${process.pid}.tmp`;
+      await writeFile(draft, data, options);
+      await rename(draft, file);
+    };
+    files.writeFile = writeWhole;
+  }
+  return { name: "caits-whole-route-types" };
+}

package/src/vite.types.d.ts

@@ -0,0 +1,14 @@
+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. */
+
+export type KernelOptions = {
+  /** The folder that holds backend/ and frontend/, from the root of the project. */
+  source?: string;
+};
+
+/** The plugins of the kernel, for Vite and Vitest: the dependencies of the classes, and the contexts of the project. */
+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;