@noverax/courier-build 0.0.0-stage → 0.5.0

package/lib/esbuild/index.js

@@ -0,0 +1,191 @@
+import { t as RoutesReadError } from "../routes-read-error-DQhKIE2F.js";
+import { n as routesModuleCode } from "../routes-module-code-DYtP7uj1.js";
+import { t as configInPageMessage } from "../config-in-page-message-DLd3f0Jd.js";
+import { w as CONFIG_BASENAMES } from "../load-config-barNPfXN.js";
+import { t as sharedEngine } from "../shared-engine-D0j7uXg8.js";
+import { t as configFileOf } from "../config-file-of-Clf_dWUQ.js";
+import { n as ROUTES_PATTERN, r as ROUTES_SPECIFIER } from "../routes-module-id-CnUjQjYF.js";
+import { t as routesFile } from "../routes-file-DRoqUZ0S.js";
+import { basename, extname } from "node:path";
+// src/esbuild/config-in-page.ts
+const RESOLVING = "@noverax/courier-build:resolving-config";
+/**
+* Fail a page's bundle where it imports the project's config: it would ship
+* the server's settings and every API's definition to the browser. The
+* import is caught as it resolves, not as the module loads: another plugin
+* may load the file first, as Angular's compiler loads every TypeScript
+* module. esbuild hands the plugin only imports that name a config's file,
+* with or without its extension; each resolves as it would, and the one that
+* reaches the config — found anew, as it may appear or move while a context
+* watches — fails.
+*
+* @param build - The build the plugin is set up for
+* @param root - The project's root, where the config is found from
+* @param named - The config, from the root or absolute, when it is not the one found
+* @example
+* ```ts
+* if (build.initialOptions.platform !== "node") refuseConfigInPage(build, root, options.config);
+* ```
+*/
+function refuseConfigInPage(build, root, named) {
+	const names = named === void 0 ? CONFIG_BASENAMES : [basename(named)];
+	const stems = [...new Set(names.map((name) => name.slice(0, -extname(name).length)))];
+	const filter = new RegExp(`(^|[\\\\/])(${stems.map(escaped).join("|")})(\\.[cm]?[jt]s)?$`);
+	build.onResolve({ filter }, async (args) => {
+		if (args.pluginData === RESOLVING) return void 0;
+		const resolved = await build.resolve(args.path, {
+			kind: args.kind,
+			importer: args.importer,
+			resolveDir: args.resolveDir,
+			pluginData: RESOLVING
+		});
+		const configFile = configFileOf(root, named);
+		if (resolved.errors.length > 0 || configFile === void 0) return void 0;
+		if (withSlashes(resolved.path) !== withSlashes(configFile)) return void 0;
+		return { errors: [{ text: configInPageMessage(configFile) }] };
+	});
+}
+function escaped(name) {
+	return name.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+function withSlashes(path) {
+	return path.split("\\").join("/");
+}
+// src/esbuild/load-routes.ts
+/**
+* The routes module, as esbuild loads it: the routes read from the config,
+* with every path they came from watched, so a context that watches builds
+* them again when one changes — a file that is not there yet included, and
+* each folder whose entries the reading listed.
+*
+* When they cannot be read, what the failed reading read is watched instead,
+* so mending the config brings the routes back. A first build fails with
+* why; a later one keeps the routes read last, and warns.
+*
+* @param engine - The engine that reads the project's routes
+* @param again - Whether a build has run before in this context
+* @returns What esbuild loads
+* @example
+* ```ts
+* build.onLoad({ filter: ANY_PATH, namespace }, () => loadRoutes(engine, builds > 1));
+* ```
+*/
+async function loadRoutes(engine, again) {
+	try {
+		const snapshot = await engine.read();
+		return {
+			contents: routesModuleCode(snapshot),
+			loader: "js",
+			...watched(snapshot)
+		};
+	} catch (error) {
+		const failure = error instanceof Error ? error : new Error(String(error));
+		const followed = (failure instanceof RoutesReadError ? failure.inputs : void 0) ?? engine.last;
+		const watch = followed === void 0 ? {} : watched(followed);
+		const why = [{ text: `[courier] ${failure.message}` }];
+		const last = engine.last;
+		if (!again || last === void 0) return {
+			errors: why,
+			...watch
+		};
+		return {
+			contents: routesModuleCode(last),
+			loader: "js",
+			warnings: why,
+			...watch
+		};
+	}
+}
+function watched(inputs) {
+	return {
+		watchFiles: [...inputs.files],
+		watchDirs: [...inputs.listed ?? []]
+	};
+}
+// src/esbuild/courier-routes.ts
+const NAMESPACE = "courier-routes";
+const ANY_PATH = /.*/;
+/**
+* The esbuild plugin that builds the routes a page's proxy client may call
+* from `courier.config.ts`, in place of the module `@noverax/courier/routes`
+* ships. No routes file is written, and the routes carry no address, path or
+* middleware. A page's bundle — any `platform` but `node` — that takes the
+* config itself fails.
+*
+* A build that cannot read the config fails with why. A context that builds
+* again, under `watch()` or `serve()`, follows every file the routes came
+* from; when they cannot be read on a later build, it keeps the routes it
+* read last and warns why.
+*
+* @param options - Where the config is, when it is not found from `absWorkingDir`
+* @returns The plugin
+* @example
+* ```ts
+* import { build } from "esbuild";
+* import { courierRoutes } from "@noverax/courier-build/esbuild";
+*
+* await build({ entryPoints: ["src/main.ts"], bundle: true, plugins: [courierRoutes()] });
+* ```
+*/
+function courierRoutes(options = {}) {
+	return {
+		name: "courier-routes",
+		setup(build) {
+			const root = build.initialOptions.absWorkingDir ?? process.cwd();
+			const engine = sharedEngine({
+				root,
+				config: options.config,
+				envFiles: []
+			});
+			let builds = 0;
+			build.onStart(() => {
+				builds += 1;
+			});
+			build.onResolve({ filter: ROUTES_PATTERN }, () => ({
+				path: ROUTES_SPECIFIER,
+				namespace: NAMESPACE
+			}));
+			build.onLoad({
+				filter: ANY_PATH,
+				namespace: NAMESPACE
+			}, () => loadRoutes(engine, builds > 1));
+			if (build.initialOptions.platform !== "node") refuseConfigInPage(build, root, options.config);
+		}
+	};
+}
+// src/esbuild/written-routes-plugin.ts
+/**
+* The esbuild plugin for a host that follows only the files its build read
+* from disk, as Angular's builders do, not those a plugin names: the
+* routes are written to a module there, which `@noverax/courier/routes`
+* resolves to, and watchers of what they came from rewrite it on a change,
+* so the host builds it again. A page's bundle — any `platform` but `node` —
+* that takes the config itself fails.
+*
+* A build fails while the routes cannot be read, with why; a host that
+* watches keeps the routes read last, and with none read yet the module
+* fails where it is imported, saying why.
+*
+* @param options - Where the project, its config and the module are, and whether the host watches
+* @returns The plugin, once the routes are written
+* @throws RoutesReadError `ROUTES_NOT_WRITTEN` when the module cannot be written
+* @example
+* ```ts
+* const plugin = await writtenRoutesPlugin({ root, file: join(dir, "routes.js"), watch: false, elsewhere: "TMPDIR" });
+* ```
+*/
+async function writtenRoutesPlugin(options) {
+	const routes = await routesFile(options.root, options.config, options.file, options.elsewhere);
+	return {
+		name: "courier-routes",
+		setup(build) {
+			build.onResolve({ filter: ROUTES_PATTERN }, () => {
+				const failure = routes.failure;
+				if (!options.watch && failure !== void 0) return { errors: [{ text: `[courier] ${failure.message}` }] };
+				return { path: routes.file };
+			});
+			if (build.initialOptions.platform !== "node") refuseConfigInPage(build, options.root, options.config);
+		}
+	};
+}
+export { courierRoutes, writtenRoutesPlugin };

package/lib/index-_VUU5N5v.d.ts

@@ -0,0 +1,134 @@
+import { t as CourierRoutesOptions } from "./courier-routes-options-BYF7Sfdf.js";
+/** What the routes rules of a project are made from. */
+interface RoutesProject {
+  /** The project's root, absolute. */
+  readonly root: string;
+  /** The config file the options name, absolute; none when it is the one found from the root. */
+  readonly config?: string | undefined;
+  /**
+   * The module `@noverax/courier/routes` resolves to from the root, by its
+   * real path, as a bundler names it: the module the routes are built in
+   * place of.
+   */
+  readonly stubFile: string;
+  /** The config's real path, when there is one to read: a page's bundle must not take it. */
+  readonly configFile?: string | undefined;
+}
+/**
+ * The project a bundler builds, as its routes rules need it.
+ *
+ * @param root - The project's root, where the bundler resolves its packages from
+ * @param options - The plugin's options
+ * @returns The project
+ * @throws RoutesReadError `CORE_NOT_FOUND` when `@noverax/courier` does not resolve from the root
+ * @example
+ * ```ts
+ * routesProject("/app"); // { root: "/app", stubFile: "/app/node_modules/@noverax/courier/lib/routes/index.js", configFile: "/app/courier.config.ts" }
+ * ```
+ */
+declare function routesProject(root: string, options?: CourierRoutesOptions): RoutesProject;
+/**
+ * What a rule hands the routes loader. Plain data alone, as Turbopack takes
+ * a loader's options only as JSON.
+ */
+interface RoutesLoaderOptions {
+  /** The project's root, absolute: the config is looked for there and above it. */
+  readonly root: string;
+  /** The config file, absolute, when it is not the one found from the root. */
+  readonly config?: string | undefined;
+  /**
+   * `"config-in-page"` on the rule that matches the config itself in a
+   * page's bundle, which the loader refuses; none on the routes module's.
+   */
+  readonly refuse?: "config-in-page" | undefined;
+}
+/** A module rule of webpack and Rspack that runs the routes loader on one module. */
+interface RoutesLoaderRule {
+  /** The module the rule matches, by its real path: webpack and Rspack match a path from its start. */
+  test: string;
+  /** Before every other loader, which would read the module the package ships. */
+  enforce?: "pre";
+  /** The routes loader, and what it is told. */
+  use: Array<{
+    loader: string;
+    options: RoutesLoaderOptions;
+  }>;
+}
+/**
+ * The rule that builds the routes in place of the module
+ * `@noverax/courier/routes` ships, for every bundle the bundler builds: a
+ * page's and a server's alike.
+ *
+ * @param project - The project, as `routesProject()` gives it
+ * @returns The rule, for the bundler's `module.rules`
+ * @example
+ * ```ts
+ * config.module.rules.push(routesRule(routesProject(config.context)));
+ * ```
+ */
+declare function routesRule(project: RoutesProject): RoutesLoaderRule;
+/**
+ * The rule that fails a page's bundle where it takes the project's config
+ * as a module: it would ship the server's settings and every API's
+ * definition to the browser. Only for the bundles a browser runs; a server's
+ * may import the config.
+ *
+ * @param project - The project, as `routesProject()` gives it
+ * @returns The rule, for the `module.rules` of a page's bundle; none when the project has no config yet
+ * @example
+ * ```ts
+ * const rule = configInPageRule(project);
+ * if (rule && !isServer) config.module.rules.push(rule);
+ * ```
+ */
+declare function configInPageRule(project: RoutesProject): RoutesLoaderRule | undefined;
+/** What of a webpack or Rspack compiler the plugin reads, and adds its rules to. */
+interface RoutesCompiler {
+  /** The folder the compiler resolves from: the project's root. */
+  readonly context: string;
+  readonly options: {
+    readonly target?: unknown;
+    readonly module: {
+      rules?: unknown[];
+    };
+  };
+}
+/**
+ * The webpack and Rspack plugin that builds the routes a page's proxy
+ * client may call from `courier.config.ts`, in place of the module
+ * `@noverax/courier/routes` ships, for every bundle the compiler builds. No
+ * routes file is written, and the routes carry no address, path or
+ * middleware. A page's bundle that takes the config itself fails.
+ *
+ * @example
+ * ```ts
+ * // webpack.config.js
+ * import { CourierRoutesPlugin } from "@noverax/courier-build/webpack";
+ *
+ * export default { plugins: [new CourierRoutesPlugin()] };
+ * ```
+ */
+declare class CourierRoutesPlugin {
+  #private;
+  /**
+   * @param options - Where the config is, when it is not found from the compiler's context
+   */
+  constructor(options?: CourierRoutesOptions);
+  /**
+   * @param compiler - The compiler the plugin is given
+   */
+  apply(compiler: RoutesCompiler): void;
+}
+/**
+ * The loader this package ships, as webpack, Rspack and Turbopack load it:
+ * a CommonJS module, by its absolute path.
+ *
+ * @returns The loader file
+ * @throws Error when the package's own folder cannot be found
+ * @example
+ * ```ts
+ * routesLoaderFile(); // "/app/node_modules/@noverax/courier-build/lib/webpack/loader.cjs"
+ * ```
+ */
+declare function routesLoaderFile(): string;
+export { RoutesLoaderRule as a, RoutesProject as c, configInPageRule as i, routesProject as l, CourierRoutesPlugin as n, routesRule as o, RoutesCompiler as r, RoutesLoaderOptions as s, routesLoaderFile as t };

package/lib/index.d.ts

@@ -0,0 +1,101 @@
+import { a as RoutesInputs, i as createRoutesEngine, n as RoutesEngineOptions, o as RoutesRequest, r as RoutesEvaluator, s as RoutesSnapshot, t as RoutesEngine } from "./routes-engine-BfwrCuNL.js";
+import { CourierError } from "@noverax/courier";
+/**
+ * The module a page's bundle takes in place of `@noverax/courier/routes`:
+ * the routes of every source of the config, as data alone, written as an
+ * object literal that keeps every name its own — `__proto__` too, which a
+ * literal would otherwise take for the object's prototype.
+ *
+ * @param snapshot - The routes as the config gave them
+ * @returns The module's code
+ * @example
+ * ```ts
+ * routesModuleCode(snapshot); // 'export const routes = {"shop":{"source":"shop","endpoints":{…}}};\n'
+ * ```
+ */
+export declare function routesModuleCode(snapshot: RoutesSnapshot): string;
+/**
+ * The same module, as CommonJS, for a host that requires it and transforms
+ * nothing it takes: Jest, outside its ES module mode. It exports `routes`
+ * as an ES module would, so an import compiled to a `require` takes it by
+ * name.
+ *
+ * @param snapshot - The routes as the config gave them
+ * @returns The module's code
+ * @example
+ * ```ts
+ * routesCommonJsCode(snapshot); // '"use strict";\nObject.defineProperty(exports, "__esModule", …);\nexports.routes = {…};\n'
+ * ```
+ */
+export declare function routesCommonJsCode(snapshot: RoutesSnapshot): string;
+/**
+ * The module a page's bundle takes when the routes were never read: one
+ * that fails where it is imported, saying why, as a build fails with it.
+ * It still exports `routes`, so a module that imports it links, and the
+ * reason is the error the page shows.
+ *
+ * @param message - Why the routes were not read
+ * @returns The module's code
+ * @example
+ * ```ts
+ * unreadRoutesModuleCode("courier.config.ts did not load: …");
+ * ```
+ */
+export declare function unreadRoutesModuleCode(message: string): string;
+/** Why a project's routes were not read. */
+type RoutesReadErrorCode = "CONFIG_NOT_FOUND" | "CONFIG_NOT_TRUSTED" | "CONFIG_NOT_LOADED" | "ROUTES_NOT_READ" | "CORE_NOT_FOUND" | "ROUTES_NOT_WRITTEN";
+/** Where a reading of the routes failed. */
+interface RoutesReadErrorContext extends Record<string, unknown> {
+  /** The project's root the config was looked for from. */
+  root: string;
+  /** The config file, once one was found. */
+  configFile?: string | undefined;
+}
+/** What a failed reading leaves besides its reason. */
+interface RoutesReadErrorDetails {
+  /** The stack of the error the config's own code threw, when it threw one. */
+  stack?: string | undefined;
+  /**
+   * What the reading had read when it failed: a change to any of it may mend
+   * the config, and a watcher follows them. None when the reading never
+   * answered.
+   */
+  inputs?: RoutesInputs | undefined;
+}
+/**
+ * A project's routes could not be read from its config. A build fails with
+ * it; a dev server keeps the routes it read last and reports it.
+ *
+ * @example
+ * ```ts
+ * throw new RoutesReadError("CONFIG_NOT_FOUND", "No courier.config.* in /app or above it", { root: "/app" });
+ * ```
+ */
+export declare class RoutesReadError extends CourierError<RoutesReadErrorCode> {
+  readonly context: RoutesReadErrorContext;
+  /** What the reading had read when it failed, when it answered at all. */
+  readonly inputs: RoutesInputs | undefined;
+  /**
+   * @param code - Why the routes were not read
+   * @param message - What went wrong, and what to do about it
+   * @param context - The project's root, and the config file once found
+   * @param details - The stack of what the config threw, and what the reading had read
+   */
+  constructor(code: RoutesReadErrorCode, message: string, context: RoutesReadErrorContext, { stack, inputs }?: RoutesReadErrorDetails);
+}
+/**
+ * Why the project's config cannot be a module of a page, and what to write
+ * instead. It holds the server's settings and the definition of every API —
+ * their addresses, their middleware, what reads their secrets — and imported
+ * as a value it ships all of them to the browser. A page needs its type
+ * alone, which an `import type` gives without a byte of it.
+ *
+ * @param configFile - The project's config
+ * @returns The message a build fails with
+ * @example
+ * ```ts
+ * configInPageMessage("/app/courier.config.ts"); // "[courier] courier.config.ts is imported into a page as a value, …"
+ * ```
+ */
+export declare function configInPageMessage(configFile: string): string;
+export { type RoutesEngine, type RoutesEngineOptions, type RoutesEvaluator, type RoutesInputs, type RoutesReadErrorCode, type RoutesReadErrorContext, type RoutesReadErrorDetails, type RoutesRequest, type RoutesSnapshot, createRoutesEngine };

package/lib/index.js

@@ -0,0 +1,4 @@
+import { t as RoutesReadError } from "./routes-read-error-DQhKIE2F.js";
+import { i as createRoutesEngine, n as routesModuleCode, r as unreadRoutesModuleCode, t as routesCommonJsCode } from "./routes-module-code-DYtP7uj1.js";
+import { t as configInPageMessage } from "./config-in-page-message-DLd3f0Jd.js";
+export { RoutesReadError, configInPageMessage, createRoutesEngine, routesCommonJsCode, routesModuleCode, unreadRoutesModuleCode };

package/lib/jest/routes-thread.d.ts

@@ -0,0 +1 @@
+export {}

package/lib/jest/routes-thread.js

@@ -0,0 +1,46 @@
+import { n as routesModuleCode, t as routesCommonJsCode } from "../routes-module-code-DYtP7uj1.js";
+import { n as isRecord } from "../errno-code-CNx_E80R.js";
+import { t as sharedEngine } from "../shared-engine-D0j7uXg8.js";
+import { parentPort } from "node:worker_threads";
+// src/jest/routes-thread.ts
+parentPort?.on("message", (message) => {
+	if (!isRecord(message) || !isRecord(message.request)) return;
+	const { port, signal } = message;
+	if (!(signal instanceof Int32Array) || !isPort(port)) return;
+	answer(requestOf(message.request)).then((reply) => {
+		port.postMessage(reply);
+		port.close();
+		Atomics.store(signal, 0, 1);
+		Atomics.notify(signal, 0);
+	});
+});
+async function answer(request) {
+	try {
+		const snapshot = await sharedEngine({
+			root: request.root,
+			config: request.config,
+			envFiles: []
+		}).read();
+		return {
+			ok: true,
+			module: routesModuleCode(snapshot),
+			commonJs: routesCommonJsCode(snapshot)
+		};
+	} catch (error) {
+		return {
+			ok: false,
+			message: error instanceof Error ? error.message : String(error)
+		};
+	}
+}
+function requestOf(request) {
+	const root = typeof request.root === "string" ? request.root : process.cwd();
+	return typeof request.config === "string" ? {
+		root,
+		config: request.config
+	} : { root };
+}
+function isPort(value) {
+	return isRecord(value) && typeof value.postMessage === "function";
+}
+export {};

package/lib/jest/transformer.cjs

@@ -0,0 +1,121 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+let node_path = require("node:path");
+let node_crypto = require("node:crypto");
+let node_worker_threads = require("node:worker_threads");
+// src/util/is-record.ts
+/**
+* Whether a value is an object read by its keys: not null, not an array.
+*
+* @param value - The value to check
+* @returns Whether it can be read as a record of fields
+*
+* @example
+* ```ts
+* isRecord({ sources: {} }); // true
+* isRecord(["shop"]); // false
+* ```
+*/
+function isRecord(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+// src/jest/routes-thread-messages.ts
+/**
+* Whether a message is the thread's answer.
+*
+* @param message - What came over the channel
+* @returns Whether it is an answer
+* @example
+* ```ts
+* if (isRoutesThreadReply(message)) settle(message);
+* ```
+*/
+function isRoutesThreadReply(message) {
+	if (!isRecord(message)) return false;
+	if (message.ok === true) return typeof message.module === "string" && typeof message.commonJs === "string";
+	return message.ok === false && typeof message.message === "string";
+}
+// src/jest/read-routes-sync.ts
+/** How long a reading may take: the engine's own limit, and time to start the thread. */
+const WAIT_MS = 75e3;
+let thread;
+/**
+* Read the routes of a project as Jest asks a transformer for them: at once.
+* The engine runs on a thread of its own, which reads the config in a
+* process of its own as every bundler's plugin does; this one waits for its
+* answer. The thread keeps the routes it read, so a later call, made while
+* nothing they came from has changed, is answered without reading again.
+*
+* @param request - Where the project is
+* @returns The routes module, or why there is none
+* @example
+* ```ts
+* const reply = readRoutesSync({ root: options.config.rootDir });
+* ```
+*/
+function readRoutesSync(request) {
+	const signal = new Int32Array(new SharedArrayBuffer(4));
+	const { port1, port2 } = new node_worker_threads.MessageChannel();
+	routesThread().postMessage({
+		request,
+		port: port2,
+		signal
+	}, [port2]);
+	const waited = Atomics.wait(signal, 0, 0, WAIT_MS);
+	const reply = (0, node_worker_threads.receiveMessageOnPort)(port1)?.message;
+	port1.close();
+	if (isRoutesThreadReply(reply)) return reply;
+	return {
+		ok: false,
+		message: `The routes were not read: the thread that reads them gave ${waited === "timed-out" ? `no answer in ${WAIT_MS / 1e3} s` : "no answer"}`
+	};
+}
+function routesThread() {
+	if (thread !== void 0) return thread;
+	const started = new node_worker_threads.Worker((0, node_path.join)(__dirname, "routes-thread.js"));
+	started.unref();
+	started.once("exit", () => {
+		if (thread === started) thread = void 0;
+	});
+	thread = started;
+	return started;
+}
+// src/jest/routes-transformer.ts
+/**
+* The Jest transformer that builds the routes a proxy client may call from
+* `courier.config.ts`, in place of the module `@noverax/courier/routes`
+* ships, as CommonJS or as an ES module, as the test runs. The config is
+* read in a process of its own, as every bundler's plugin reads it, from
+* Jest's `rootDir`, once in each worker while nothing it read changes; the
+* cache key is the module itself, so a run after an edit, or under another
+* value of a variable the config read, never takes the routes of the last.
+*
+* @param options - Where the config is, when it is not found from `rootDir`
+* @returns The transformer
+* @throws Error from each method when the routes cannot be read, with why
+* @example
+* ```js
+* // jest.config.js
+* export default {
+*   transform: { "/node_modules/@noverax/courier/lib/routes/index\\.js$": "@noverax/courier-build/jest" },
+*   transformIgnorePatterns: ["/node_modules/(?!@noverax/courier/)"],
+* };
+* ```
+*/
+function createTransformer(options = {}) {
+	const moduleFor = (transformOptions) => {
+		return codeOf(readRoutesSync({
+			root: transformOptions.config.rootDir,
+			config: options.config
+		}), transformOptions.supportsStaticESM);
+	};
+	return {
+		canInstrument: false,
+		getCacheKey: (_source, _path, transformOptions) => (0, node_crypto.createHash)("sha256").update(moduleFor(transformOptions)).digest("hex"),
+		process: (_source, _path, transformOptions) => ({ code: moduleFor(transformOptions) })
+	};
+}
+function codeOf(reply, esm) {
+	if (!reply.ok) throw new Error(`[courier] ${reply.message}`);
+	return esm ? reply.module : reply.commonJs;
+}
+exports.createTransformer = createTransformer;

package/lib/jest/transformer.d.cts

@@ -0,0 +1,39 @@
+import { t as CourierRoutesOptions } from "../courier-routes-options-BYF7Sfdf.cjs";
+/** What Jest hands a transformer of a module: the part the routes transformer reads. */
+export interface RoutesTransformOptions {
+  readonly config: {
+    readonly rootDir: string;
+  };
+  /** Whether the test runs as an ES module, under `--experimental-vm-modules`. */
+  readonly supportsStaticESM: boolean;
+}
+/** The transformer Jest runs on the module `@noverax/courier/routes` ships. */
+export interface RoutesTransformer {
+  readonly canInstrument: false;
+  getCacheKey(source: string, path: string, options: RoutesTransformOptions): string;
+  process(source: string, path: string, options: RoutesTransformOptions): {
+    code: string;
+  };
+}
+/**
+ * The Jest transformer that builds the routes a proxy client may call from
+ * `courier.config.ts`, in place of the module `@noverax/courier/routes`
+ * ships, as CommonJS or as an ES module, as the test runs. The config is
+ * read in a process of its own, as every bundler's plugin reads it, from
+ * Jest's `rootDir`, once in each worker while nothing it read changes; the
+ * cache key is the module itself, so a run after an edit, or under another
+ * value of a variable the config read, never takes the routes of the last.
+ *
+ * @param options - Where the config is, when it is not found from `rootDir`
+ * @returns The transformer
+ * @throws Error from each method when the routes cannot be read, with why
+ * @example
+ * ```js
+ * // jest.config.js
+ * export default {
+ *   transform: { "/node_modules/@noverax/courier/lib/routes/index\\.js$": "@noverax/courier-build/jest" },
+ *   transformIgnorePatterns: ["/node_modules/(?!@noverax/courier/)"],
+ * };
+ * ```
+ */
+export declare function createTransformer(options?: CourierRoutesOptions): RoutesTransformer;