@noverax/courier-build 0.0.0-stage → 0.5.0

package/lib/metro/index.cjs

@@ -0,0 +1,25 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+let node_path = require("node:path");
+let node_url = require("node:url");
+// src/metro/require-entry.ts
+/**
+* `withCourier()` for a `metro.config.js` that `require()`s it, as most do:
+* built as CommonJS, it hands the work to the package's ES module beside it,
+* which every Node the package runs on imports, `require(esm)` or not.
+*
+* @param config - The Metro config, or a promise of it
+* @param options - Where the config is, and where the module is written
+* @returns The config, with the resolver that answers the routes
+* @example
+* ```js
+* const { withCourier } = require("@noverax/courier-build/metro");
+* module.exports = withCourier(getDefaultConfig(__dirname));
+* ```
+*/
+async function withCourier(config, options = {}) {
+	const loaded = await import((0, node_url.pathToFileURL)((0, node_path.join)(__dirname, "index.js")).href);
+	const run = typeof loaded === "object" && loaded !== null ? Reflect.get(loaded, "withCourier") : void 0;
+	if (typeof run !== "function") throw new Error("[courier] @noverax/courier-build is installed incompletely: install it again.");
+	return await Reflect.apply(run, void 0, [config, options]);
+}
+exports.withCourier = withCourier;

package/lib/metro/index.d.cts

@@ -0,0 +1,55 @@
+import { t as CourierRoutesOptions } from "../courier-routes-options-BYF7Sfdf.cjs";
+/** Where Metro found a module: the part the routes resolver reads. */
+interface MetroResolution {
+  readonly type: string;
+  readonly filePath?: string | undefined;
+}
+/** What Metro hands a resolver: the part the routes resolver reads. */
+interface MetroResolutionContext {
+  /** Whether the bundle is a development one: a build's fails where the routes were not read. */
+  readonly dev: boolean;
+  /** The module that imports the one resolved. */
+  readonly originModulePath: string;
+  /** Expo names a server's bundle here: `node`, or `react-server`. */
+  readonly customResolverOptions?: {
+    readonly environment?: unknown;
+  } | undefined;
+  /** The resolver the chain goes on with: Metro's own, or the one Expo wraps it in. */
+  readonly resolveRequest: MetroResolver;
+}
+/** A Metro resolver, as `resolver.resolveRequest` takes one. */
+type MetroResolver = (context: MetroResolutionContext, moduleName: string, platform: string | null) => MetroResolution;
+/** What of a Metro config the plugin reads and extends: Expo's `getDefaultConfig()` gives one. */
+interface MetroConfigShape {
+  readonly projectRoot?: string | undefined;
+  readonly watchFolders?: readonly string[] | undefined;
+  readonly resolver?: {
+    readonly resolveRequest?: MetroResolver | null | undefined;
+  } | undefined;
+}
+/** Options of the routes plugin of Metro and Expo. */
+interface MetroRoutesOptions extends CourierRoutesOptions {
+  /**
+   * The folder the routes module Metro bundles is written to, from the
+   * project's root or absolute: `node_modules/.cache/@noverax/courier` by
+   * default. Name another where `node_modules` cannot be written; one outside
+   * the project and its watched folders is watched too.
+   */
+  outDir?: string | undefined;
+}
+/**
+ * `withCourier()` for a `metro.config.js` that `require()`s it, as most do:
+ * built as CommonJS, it hands the work to the package's ES module beside it,
+ * which every Node the package runs on imports, `require(esm)` or not.
+ *
+ * @param config - The Metro config, or a promise of it
+ * @param options - Where the config is, and where the module is written
+ * @returns The config, with the resolver that answers the routes
+ * @example
+ * ```js
+ * const { withCourier } = require("@noverax/courier-build/metro");
+ * module.exports = withCourier(getDefaultConfig(__dirname));
+ * ```
+ */
+export declare function withCourier<TConfig extends MetroConfigShape>(config: TConfig | Promise<TConfig>, options?: MetroRoutesOptions): Promise<TConfig & MetroConfigShape>;
+export {};

package/lib/metro/index.d.ts

@@ -0,0 +1,67 @@
+import { t as CourierRoutesOptions } from "../courier-routes-options-BYF7Sfdf.js";
+/** Where Metro found a module: the part the routes resolver reads. */
+interface MetroResolution {
+  readonly type: string;
+  readonly filePath?: string | undefined;
+}
+/** What Metro hands a resolver: the part the routes resolver reads. */
+interface MetroResolutionContext {
+  /** Whether the bundle is a development one: a build's fails where the routes were not read. */
+  readonly dev: boolean;
+  /** The module that imports the one resolved. */
+  readonly originModulePath: string;
+  /** Expo names a server's bundle here: `node`, or `react-server`. */
+  readonly customResolverOptions?: {
+    readonly environment?: unknown;
+  } | undefined;
+  /** The resolver the chain goes on with: Metro's own, or the one Expo wraps it in. */
+  readonly resolveRequest: MetroResolver;
+}
+/** A Metro resolver, as `resolver.resolveRequest` takes one. */
+type MetroResolver = (context: MetroResolutionContext, moduleName: string, platform: string | null) => MetroResolution;
+/** What of a Metro config the plugin reads and extends: Expo's `getDefaultConfig()` gives one. */
+interface MetroConfigShape {
+  readonly projectRoot?: string | undefined;
+  readonly watchFolders?: readonly string[] | undefined;
+  readonly resolver?: {
+    readonly resolveRequest?: MetroResolver | null | undefined;
+  } | undefined;
+}
+/** Options of the routes plugin of Metro and Expo. */
+interface MetroRoutesOptions extends CourierRoutesOptions {
+  /**
+   * The folder the routes module Metro bundles is written to, from the
+   * project's root or absolute: `node_modules/.cache/@noverax/courier` by
+   * default. Name another where `node_modules` cannot be written; one outside
+   * the project and its watched folders is watched too.
+   */
+  outDir?: string | undefined;
+}
+/**
+ * Have Metro — under Expo or React Native's CLI — bundle the routes a
+ * proxy client may call from `courier.config.ts`, in place of the module
+ * `@noverax/courier/routes` ships. The routes are read before Metro starts
+ * and written to a module of the app's own, which a dev server keeps
+ * current: a change to anything they came from reads them again, and Metro
+ * bundles the module anew. The routes carry no address, path or
+ * middleware. A bundle of the app that takes the config itself fails.
+ *
+ * A build fails while the routes cannot be read, with why; a development
+ * bundle keeps the routes read last, and with none read yet, the module
+ * fails where it is imported, saying why.
+ *
+ * @param config - The Metro config, as `getDefaultConfig()` gives it, or a promise of it
+ * @param options - Where the config is, and where the module is written
+ * @returns The config, with the resolver that answers the routes
+ * @throws RoutesReadError `ROUTES_NOT_WRITTEN` when the module's folder cannot be written
+ * @example
+ * ```js
+ * // metro.config.js
+ * const { getDefaultConfig } = require("expo/metro-config");
+ * const { withCourier } = require("@noverax/courier-build/metro");
+ *
+ * module.exports = withCourier(getDefaultConfig(__dirname));
+ * ```
+ */
+export declare function withCourier<TConfig extends MetroConfigShape>(config: TConfig | Promise<TConfig>, options?: MetroRoutesOptions): Promise<TConfig & MetroConfigShape>;
+export type { MetroConfigShape, MetroResolution, MetroResolutionContext, MetroResolver, MetroRoutesOptions };

package/lib/metro/index.js

@@ -0,0 +1,105 @@
+import "../routes-module-id-CnUjQjYF.js";
+import { t as routesFile } from "../routes-file-DRoqUZ0S.js";
+import { basename, isAbsolute, join, relative, resolve } from "node:path";
+import { realpathSync } from "node:fs";
+// src/metro/routes-resolver.ts
+const SERVER_ENVIRONMENTS = /* @__PURE__ */ new Set(["node", "react-server"]);
+/**
+* The resolver Metro runs first: `@noverax/courier/routes` resolves to the
+* module the routes are written in, and every other module as the app's own
+* resolver, or Metro's, resolves it. A build fails there while the routes
+* cannot be read, with why; a development bundle takes the module, which
+* says why where it is imported. A module of the app's bundle that resolves
+* to the config fails it, as the config would ship the server's settings
+* and every API's definition in the app; a server's bundle may take it.
+*
+* @param routes - The project's routes
+* @param own - The resolver the config had, if any
+* @returns The resolver
+* @example
+* ```ts
+* const resolver = { ...config.resolver, resolveRequest: routesResolver(routes, config.resolver?.resolveRequest) };
+* ```
+*/
+function routesResolver(routes, own) {
+	return (context, moduleName, platform) => {
+		if (moduleName === "@noverax/courier/routes") {
+			if (!context.dev && routes.failure !== void 0) throw routes.failure;
+			return {
+				type: "sourceFile",
+				filePath: routes.file
+			};
+		}
+		const resolution = (own ?? context.resolveRequest)(context, moduleName, platform);
+		refuseConfigInApp(routes, context, resolution);
+		return resolution;
+	};
+}
+function refuseConfigInApp(routes, context, resolution) {
+	const configFile = routes.configFile;
+	const filePath = resolution.filePath;
+	if (configFile === void 0 || filePath === void 0 || isServer(context)) return;
+	if (basename(filePath) !== basename(configFile) || realOf(filePath) !== configFile) return;
+	throw new Error(`[courier] ${basename(configFile)} is imported into the app's bundle as a value, by ${context.originModulePath}: it would ship the server's settings and every API's definition in the app. Import its type alone: write \`import type config from\` where the module writes \`import config from\`.`);
+}
+function isServer(context) {
+	const environment = context.customResolverOptions?.environment;
+	return typeof environment === "string" && SERVER_ENVIRONMENTS.has(environment);
+}
+function realOf(path) {
+	try {
+		return realpathSync(path);
+	} catch {
+		return path;
+	}
+}
+// src/metro/with-courier.ts
+const OUT_DIR = join("node_modules", ".cache", "@noverax", "courier");
+const ELSEWHERE = "withCourier(config, { outDir })";
+/**
+* Have Metro — under Expo or React Native's CLI — bundle the routes a
+* proxy client may call from `courier.config.ts`, in place of the module
+* `@noverax/courier/routes` ships. The routes are read before Metro starts
+* and written to a module of the app's own, which a dev server keeps
+* current: a change to anything they came from reads them again, and Metro
+* bundles the module anew. The routes carry no address, path or
+* middleware. A bundle of the app that takes the config itself fails.
+*
+* A build fails while the routes cannot be read, with why; a development
+* bundle keeps the routes read last, and with none read yet, the module
+* fails where it is imported, saying why.
+*
+* @param config - The Metro config, as `getDefaultConfig()` gives it, or a promise of it
+* @param options - Where the config is, and where the module is written
+* @returns The config, with the resolver that answers the routes
+* @throws RoutesReadError `ROUTES_NOT_WRITTEN` when the module's folder cannot be written
+* @example
+* ```js
+* // metro.config.js
+* const { getDefaultConfig } = require("expo/metro-config");
+* const { withCourier } = require("@noverax/courier-build/metro");
+*
+* module.exports = withCourier(getDefaultConfig(__dirname));
+* ```
+*/
+async function withCourier(config, options = {}) {
+	const resolved = await config;
+	const root = resolved.projectRoot ?? process.cwd();
+	const folder = resolve(root, options.outDir ?? OUT_DIR);
+	const routes = await routesFile(root, options.config, join(folder, "routes.js"), ELSEWHERE);
+	const watchFolders = resolved.watchFolders ?? [];
+	const watched = [root, ...watchFolders].some((parent) => isWithin(parent, folder));
+	return {
+		...resolved,
+		watchFolders: watched ? watchFolders : [...watchFolders, folder],
+		resolver: {
+			...resolved.resolver,
+			resolveRequest: routesResolver(routes, resolved.resolver?.resolveRequest)
+		}
+	};
+}
+function isWithin(parent, path) {
+	const from = relative(resolve(parent), path);
+	return from === "" || !from.startsWith("..") && !isAbsolute(from);
+}
+export { withCourier };

package/lib/package-file-CVAKY_Nu.js

@@ -0,0 +1,39 @@
+import { dirname, join } from "node:path";
+import { existsSync, readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+// src/util/package-file.ts
+/** The package this module ships in, by the name its manifest gives. */
+const PACKAGE_NAME = "@noverax/courier-build";
+let root;
+/**
+* A file this package ships, by its path from the package's root: the
+* folder above this module that holds the manifest with the package's
+* name, wherever this module was bundled into.
+*
+* @param path - The file, from the package's root
+* @returns The file, absolute; none when no folder above holds the manifest
+* @example
+* ```ts
+* packageFile("lib/engine/worker.js"); // "/app/node_modules/@noverax/courier-build/lib/engine/worker.js"
+* ```
+*/
+function packageFile(path) {
+	root ??= packageRoot() ?? null;
+	return root === null ? void 0 : join(root, path);
+}
+function packageRoot() {
+	let dir = dirname(fileURLToPath(import.meta.url));
+	while (!isPackageRoot(dir)) {
+		const parent = dirname(dir);
+		if (parent === dir) return void 0;
+		dir = parent;
+	}
+	return dir;
+}
+function isPackageRoot(dir) {
+	const manifest = join(dir, "package.json");
+	if (!existsSync(manifest)) return false;
+	const parsed = JSON.parse(readFileSync(manifest, "utf8"));
+	return typeof parsed === "object" && parsed !== null && Reflect.get(parsed, "name") === PACKAGE_NAME;
+}
+export { packageFile as t };

package/lib/read-limits-DUuUaEQM.js

@@ -0,0 +1,41 @@
+// src/config/definitions-phase.ts
+/**
+* The signal a project's code reads to tell that Courier is reading its
+* definitions rather than serving requests: `COURIER_PHASE` holds
+* `definitions` in every process Courier starts to read them — the
+* `courier-cli routes` command, `courier-mcp --list`, Studio, the process a
+* bundler plugin reads the routes in — after the fashion of `NEXT_PHASE`.
+* Code that checks the environment as it is imported can skip the check
+* then, as `@t3-oss/env-core` does with `skipValidation`; Courier guesses
+* nothing for it. Where the application runs — `courier-server`,
+* `courier-mcp` serving an agent, `attachRuntime()`, the app itself — the
+* variable is not set.
+*/
+/** The variable a project's code reads the phase from. */
+const COURIER_PHASE = "COURIER_PHASE";
+/** Its value while Courier reads the project's definitions. */
+const DEFINITIONS_PHASE = "definitions";
+/**
+* Mark the process as one that reads the project's definitions, before the
+* project's code runs in it.
+*
+* @param env - The environment to mark (default: the process's)
+* @example
+* ```ts
+* enterDefinitionsPhase();
+* process.env.COURIER_PHASE; // "definitions"
+* ```
+*/
+function enterDefinitionsPhase(env = process.env) {
+	env[COURIER_PHASE] = DEFINITIONS_PHASE;
+}
+// src/config/read-limits.ts
+/**
+* How long one reading of a project's config may take before it is given
+* up, in milliseconds: a config that waits on the network, or on a timer,
+* never ends. The routes plugin's process and `courier-cli routes` hold to
+* it; Studio, which keeps running what it loaded last, has its own,
+* `COURIER_CONFIG_LOAD_TIMEOUT_MS`.
+*/
+const CONFIG_READ_LIMIT_MS = 6e4;
+export { enterDefinitionsPhase as i, COURIER_PHASE as n, DEFINITIONS_PHASE as r, CONFIG_READ_LIMIT_MS as t };

package/lib/rollup/index.d.ts

@@ -0,0 +1,51 @@
+import { t as CourierRoutesOptions } from "../courier-routes-options-BYF7Sfdf.js";
+import "../routes-engine-BfwrCuNL.js";
+/** What of Rollup's and Rolldown's plugin context the routes module is loaded with. */
+interface RoutesPluginContext {
+  readonly meta: {
+    readonly watchMode: boolean;
+  };
+  addWatchFile(id: string): void;
+  warn(message: string): void;
+  error(message: string): never;
+}
+/** Options of the routes plugin of Rollup and Rolldown. */
+interface RollupRoutesOptions extends CourierRoutesOptions {
+  /**
+   * The bundle is a server's, which may take the config itself: none is
+   * refused. A page's by default, which must not.
+   */
+  server?: boolean | undefined;
+}
+/** The plugin, as Rollup and Rolldown both take it. */
+interface RoutesRollupPlugin {
+  readonly name: string;
+  buildStart(): void;
+  resolveId(source: string): string | null;
+  load(this: RoutesPluginContext, id: string): Promise<string> | null;
+  transform(this: RoutesPluginContext, code: string, id: string): null;
+}
+/**
+ * The Rollup and Rolldown 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. The bundle is taken for a page's,
+ * which fails where it takes the config itself; a server's says so with
+ * `server: true`.
+ *
+ * A build that cannot read the config fails with why. Under `watch`, every
+ * file the routes came from is watched; when they cannot be read on a
+ * rebuild, the routes read last stay, with a warning.
+ *
+ * @param options - Where the config is, when it is not found from the folder the bundler runs in, and whether the bundle is a server's
+ * @returns The plugin
+ * @example
+ * ```ts
+ * // rollup.config.js
+ * import { courierRoutes } from "@noverax/courier-build/rollup";
+ *
+ * export default { input: "src/main.js", plugins: [courierRoutes()] };
+ * ```
+ */
+export declare function courierRoutes(options?: RollupRoutesOptions): RoutesRollupPlugin;
+export type { RollupRoutesOptions, RoutesPluginContext, RoutesRollupPlugin };

package/lib/rollup/index.js

@@ -0,0 +1,95 @@
+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 { t as sharedEngine } from "../shared-engine-D0j7uXg8.js";
+import { t as configFileOf } from "../config-file-of-Clf_dWUQ.js";
+import { t as ROUTES_MODULE_ID } from "../routes-module-id-CnUjQjYF.js";
+// src/rollup/load-routes-module.ts
+/**
+* The routes module: the routes read from the config, with every path they
+* came from watched — a file that is not there yet, and each folder whose
+* entries the reading listed, too — so a watching build builds it again
+* once one changes.
+*
+* When they cannot be read, what the failed reading read is watched instead,
+* so mending the config brings the routes back. A build fails with why;
+* under watch, the routes read last stay, with a warning, and with none
+* read yet the build fails.
+*
+* @param context - The plugin's context
+* @param engine - The engine that reads the project's routes
+* @returns The module's code
+* @example
+* ```ts
+* load(id) { return id === ROUTES_MODULE_ID ? loadRoutesModule(this, engine) : null; }
+* ```
+*/
+async function loadRoutesModule(context, engine) {
+	try {
+		const snapshot = await engine.read();
+		follow(context, snapshot);
+		return routesModuleCode(snapshot);
+	} catch (error) {
+		const failure = error instanceof Error ? error : new Error(String(error));
+		const followed = (failure instanceof RoutesReadError ? failure.inputs : void 0) ?? engine.last;
+		if (followed !== void 0) follow(context, followed);
+		const why = `[courier] ${failure.message}`;
+		const last = engine.last;
+		if (!context.meta.watchMode || last === void 0) return context.error(why);
+		context.warn(why);
+		return routesModuleCode(last);
+	}
+}
+function follow(context, inputs) {
+	for (const path of [...inputs.files, ...inputs.listed ?? []]) context.addWatchFile(path);
+}
+// src/rollup/courier-routes.ts
+/**
+* The Rollup and Rolldown 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. The bundle is taken for a page's,
+* which fails where it takes the config itself; a server's says so with
+* `server: true`.
+*
+* A build that cannot read the config fails with why. Under `watch`, every
+* file the routes came from is watched; when they cannot be read on a
+* rebuild, the routes read last stay, with a warning.
+*
+* @param options - Where the config is, when it is not found from the folder the bundler runs in, and whether the bundle is a server's
+* @returns The plugin
+* @example
+* ```ts
+* // rollup.config.js
+* import { courierRoutes } from "@noverax/courier-build/rollup";
+*
+* export default { input: "src/main.js", plugins: [courierRoutes()] };
+* ```
+*/
+function courierRoutes(options = {}) {
+	const root = process.cwd();
+	const engine = sharedEngine({
+		root,
+		config: options.config,
+		envFiles: []
+	});
+	let configFile;
+	return {
+		name: "courier-routes",
+		buildStart() {
+			configFile = options.server === true ? void 0 : configFileOf(root, options.config);
+		},
+		resolveId: (source) => source === "@noverax/courier/routes" || source === "\0@noverax/courier/routes" ? ROUTES_MODULE_ID : null,
+		load(id) {
+			return id === "\0@noverax/courier/routes" ? loadRoutesModule(this, engine) : null;
+		},
+		transform(_code, id) {
+			if (configFile !== void 0 && withSlashes(id.split("?")[0] ?? id) === withSlashes(configFile)) this.error(configInPageMessage(configFile));
+			return null;
+		}
+	};
+}
+function withSlashes(path) {
+	return path.split("\\").join("/");
+}
+export { courierRoutes };

package/lib/routes-engine-BfwrCuNL.d.ts

@@ -0,0 +1,117 @@
+import { CourierRoutes } from "@noverax/courier/define";
+/**
+ * What one reading of a project's routes depended on: a change to any of it
+ * may change what the next reading gives.
+ */
+interface RoutesInputs {
+  /** The config file read, absolute, once one was found. */
+  readonly configFile?: string | undefined;
+  /**
+   * Every path the reading depended on, absolute and sorted: the config, the
+   * modules it reached, the env files that were or may be read, the files
+   * it read and the paths it looked at. A file counts by its contents; a
+   * path that is not there or is a folder, by whether it is there and what
+   * it is.
+   */
+  readonly files: readonly string[];
+  /**
+   * The folders whose entries the reading listed, absolute and sorted: an
+   * entry added or removed may change what it gives. None when omitted.
+   */
+  readonly listed?: readonly string[] | undefined;
+  /**
+   * The environment variables the reading looked at, sorted, or `"*"` when it
+   * went through all of them.
+   */
+  readonly env: readonly string[] | "*";
+}
+/**
+ * The routes of a project's config, as one reading of it gave them, and
+ * what that reading depended on.
+ */
+interface RoutesSnapshot extends RoutesInputs {
+  /** The config file the routes were read from, absolute. */
+  readonly configFile: string;
+  /**
+   * Each source's routes, by its name in the config's `sources`: every
+   * source, one that opens nothing to a page with no endpoints.
+   */
+  readonly routes: Readonly<Record<string, CourierRoutes>>;
+}
+/** What reading a project's routes is told: where the project is, and how it reads its variables. */
+interface RoutesRequest {
+  /** The project's root, absolute: the config is looked for there and in the folders above it. */
+  readonly root: string;
+  /** The config file, absolute, when it is not the one found from the root. */
+  readonly configFile?: string | undefined;
+  /**
+   * The env files read before the config, absolute, the first to set a
+   * variable winning; a variable the process was started with wins over all.
+   */
+  readonly envFiles: readonly string[];
+  /**
+   * The variables those files give, as the bundler reads them — with its own
+   * expansion of `${VAR}` — in place of reading them here. A variable the
+   * process was started with still wins.
+   */
+  readonly env?: Readonly<Record<string, string>> | undefined;
+}
+/** Where a project is, for the engine that reads its routes. */
+interface RoutesEngineOptions {
+  /** The project's root: the config is looked for there and in the folders above it. */
+  root: string;
+  /** The config file, absolute or from the root, when it is not the one found from the root. */
+  config?: string | undefined;
+  /**
+   * The env files read before the config, absolute or from the root, the
+   * first to set a variable winning; a variable the process was started with
+   * wins over all. None by default.
+   */
+  envFiles?: readonly string[] | undefined;
+  /**
+   * The variables those files give, as the bundler reads them, asked anew
+   * for every reading: the config then sees the values the app does, `${VAR}`
+   * expanded as the bundler expands it. Without it the files are read as
+   * they are.
+   */
+  envValues?: (() => Readonly<Record<string, string>>) | undefined;
+}
+/** Reads a project's routes, again only when what they depend on changed. */
+interface RoutesEngine {
+  /**
+   * The routes as the config gives them now. Read in a process of its own
+   * the first time, and again only once a path the last reading depended
+   * on, or a variable it looked at, has changed. Calls made while a reading
+   * runs share it, unless something it read changed meanwhile: a call made
+   * after it began then waits for the next reading, which begins after the
+   * change. A failure is not kept: the next call reads again.
+   *
+   * @throws RoutesReadError when the config cannot be found or read
+   */
+  read(): Promise<RoutesSnapshot>;
+  /** The routes the last successful reading gave, if one has. */
+  readonly last: RoutesSnapshot | undefined;
+  /**
+   * A digest of what the latest successful reading depended on, as it is
+   * now: equal digests mean the same routes. `undefined` before the first,
+   * and while that reading may have missed a change made as it ran, until
+   * `read()` reads again.
+   */
+  fingerprint(): string | undefined;
+}
+/** How a reading of the routes runs: in a process of its own, unless a test says otherwise. */
+type RoutesEvaluator = (request: RoutesRequest) => Promise<RoutesSnapshot>;
+/**
+ * Create the engine that reads a project's routes for a bundler plugin.
+ *
+ * @param options - Where the project and its config are
+ * @param evaluate - How one reading runs: in a process of its own
+ * @returns The engine
+ * @example
+ * ```ts
+ * const engine = createRoutesEngine({ root: process.cwd(), envFiles: [".env.local", ".env"] });
+ * const { routes } = await engine.read();
+ * ```
+ */
+declare function createRoutesEngine(options: RoutesEngineOptions, evaluate?: RoutesEvaluator): RoutesEngine;
+export { RoutesInputs as a, createRoutesEngine as i, RoutesEngineOptions as n, RoutesRequest as o, RoutesEvaluator as r, RoutesSnapshot as s, RoutesEngine as t };