@hellaweb3/wiremock-testcontainers-nodejs 0.1.2 → 0.2.0

package/package.json

@@ -2,7 +2,10 @@
   "name": "@hellaweb3/wiremock-testcontainers-nodejs",
   "description": "A Node.js library for using WireMock with Testcontainers, providing a fluent API for easy setup and integration testing.",
   "homepage": "https://github.com/hella-web3/wiremock-testcontainers-nodejs#readme",
-  "repository": "https://github.com/hella-web3/wiremock-testcontainers-nodejs",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/hella-web3/wiremock-testcontainers-nodejs.git"
+  },
   "bugs": "https://github.com/hella-web3/wiremock-testcontainers-nodejs/issues",
   "keywords": [
     "testcontainers",
@@ -11,7 +14,7 @@
     "mock",
     "api"
   ],
-  "version": "0.1.2",
+  "version": "0.2.0",
   "publishConfig": {
     "access": "public"
   },
@@ -19,11 +22,13 @@
   "author": "Chris Anatalio",
   "files": [
     "dist",
+    "!dist/*.js.map",
     "src",
     "README.md",
     "LICENSE"
   ],
   "type": "module",
+  "sideEffects": false,
   "main": "./dist/index.cjs",
   "module": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -41,50 +46,30 @@
     "./package.json": "./package.json"
   },
   "dependencies": {
-    "testcontainers": "^11.11.0"
+    "testcontainers": "^12.2.0"
   },
   "devDependencies": {
-    "@types/jest": "^30.0.0",
-    "@types/node": "^25.0.10",
-    "bunchee": "^6.9.4",
-    "jest": "^30.2.0",
-    "ts-jest": "^29.4.6",
-    "tsdx": "^2.0.0",
-    "typescript": "^5.9.3",
-    "vitest": "^4.0.18"
-  },
-  "jest": {
-    "collectCoverageFrom": [
-      "**/*.(t|j)s"
-    ],
-    "coverageDirectory": "../coverage",
-    "coveragePathIgnorePatterns": [
-      "app.module.ts",
-      "main.ts",
-      ".*\\.module\\.ts",
-      ".*\\.dto\\.ts"
-    ],
-    "moduleFileExtensions": [
-      "js",
-      "json",
-      "ts"
-    ],
-    "rootDir": ".",
-    "testEnvironment": "node",
-    "testRegex": "test/.*\\.test\\.ts$",
-    "transform": {
-      "^.+\\.(t|j)s$": "ts-jest"
-    }
+    "@arethetypeswrong/core": "^0.18.5",
+    "@types/node": "^24.19.2",
+    "@vitest/coverage-v8": "^5.1.0",
+    "oxlint": "^1.87.0",
+    "publint": "^0.3.24",
+    "tsdown": "^0.23.0",
+    "typescript": "^6.0.3",
+    "vitest": "^5.1.0"
   },
   "engines": {
-    "node": ">=22"
+    "node": ">=22.22"
   },
   "scripts": {
-    "dev": "tsdx dev",
-    "build": "tsdx build",
-    "test": "jest --colors --injectGlobals",
-    "lint": "tsdx lint",
+    "dev": "tsdown --watch",
+    "build": "tsdown",
+    "test": "vitest run",
+    "test:unit": "vitest run test/unit",
+    "test:e2e": "vitest run test/index.test.ts",
+    "test:coverage": "vitest run --coverage",
+    "lint": "oxlint --deny-warnings",
     "typecheck": "tsc --noEmit",
-    "check": "pnpm build && pnpm typecheck && pnpm lint && pnpm test"
+    "check": "pnpm build && pnpm typecheck && pnpm lint && pnpm test:coverage"
   }
 }

package/src/index.ts

@@ -1,12 +1,49 @@
+import { existsSync, readFileSync, statSync } from "node:fs";
+import { basename, join, posix, resolve } from "node:path";
 import {
   AbstractStartedContainer,
   GenericContainer,
-  StartedTestContainer,
+  type StartedTestContainer,
   Wait,
 } from "testcontainers";
+import {
+  containerName,
+  fail,
+  inlineJson,
+  isRecord,
+  listFiles,
+  resolveFile,
+  stubIds,
+  stubIdsOf,
+  within,
+  type WiremockMappingSource,
+  type WiremockStaticFile,
+} from "./sources";
+
+export type {
+  WiremockFileSource,
+  WiremockMappingSource,
+  WiremockPath,
+  WiremockStaticFile,
+  WiremockStubMapping,
+} from "./sources";
+
+const MAPPINGS = "/home/wiremock/mappings";
+const FILES = "/home/wiremock/__files";
+const INLINE = "inline JSON";
+
+/** A file a registration places in the container. */
+interface Claim {
+  readonly target: string;
+  /** The absolute source path, or {@link INLINE}. */
+  readonly origin: string;
+  readonly ids?: readonly string[];
+}
 
 /**
- * A Testcontainer for Wiremock.
+ * A Testcontainer for Wiremock. Stubs are registered with {@link withMappings} (a directory),
+ * {@link withMapping} (one named stub) and {@link withFiles} (response bodies), in any
+ * combination. Registrations are validated immediately and may not overwrite one another.
  *
  * @example
  * ```typescript
@@ -14,6 +51,11 @@ import {
  * ```
  */
 export class WiremockContainer extends GenericContainer {
+  /** Container path → origin of every registered file. */
+  #origins = new Map<string, string>();
+  /** Stub id → container path declaring it: WireMock refuses to start with duplicates. */
+  #stubIds = new Map<string, string>();
+
   /**
    * Creates a new WiremockContainer.
    * @example
@@ -36,18 +78,74 @@ export class WiremockContainer extends GenericContainer {
    *   .withMappings("./test/__mocks__/wiremock")
    *   .start();
    * ```
-   * @param directory The directory containing the mappings and __files.
+   * @param directory The directory containing `mappings/` and, optionally, `__files/`.
+   * @throws If `mappings/` is not a directory in `directory`, or a file would overwrite an earlier registration.
    */
-  public withMappings(directory: string) {
-    this.withCopyDirectoriesToContainer([{
-      source: `${directory}/__files`,
-      target: "/home/wiremock/__files",
-    }]);
-    this.withCopyDirectoriesToContainer([{
-      source: `${directory}/mappings`,
-      target: "/home/wiremock/mappings",
-    }]);
+  public withMappings(directory: string): this {
+    within("WiremockContainer.withMappings", () => {
+      const mappings = join(directory, "mappings");
+      if (!existsSync(mappings)) fail(`"${mappings}" does not exist`);
+      if (!statSync(mappings).isDirectory()) fail(`"${mappings}" is not a directory`);
+      // `__files/` is optional: mappings may define their response bodies inline.
+      const files = join(directory, "__files");
+      const dirs = [{ source: mappings, target: MAPPINGS }, ...(existsSync(files) ? [{ source: files, target: FILES }] : [])];
+      this.#claim(
+        dirs.flatMap(({ source, target }) =>
+          listFiles(source).map((name) => ({
+            target: posix.join(target, name),
+            origin: resolve(source, name),
+            ids: target === MAPPINGS ? stubIdsOf(join(source, name)) : [],
+          })),
+        ),
+      );
+      this.withCopyDirectoriesToContainer(dirs);
+    });
+    return this;
+  }
 
+  /**
+   * Registers one stub at `mappings/<name>.json`, validated and copied byte-for-byte.
+   * @example
+   * ```typescript
+   * new WiremockContainer()
+   *   .withMapping("cards", "./test/fixtures/cards.json")
+   *   .withMapping("user", { package: "@acme/fixtures", file: "wiremock/user.json" })
+   *   .withMapping("balance", { module: import.meta.url, file: "./balance.json" })
+   *   .withMapping("ping", { json: { request: { url: "/ping" }, response: { status: 200 } } });
+   * ```
+   * @param name File name below `mappings/`, may contain `/`; `.json` is appended unless present.
+   * @throws If the name or source is invalid, the source is not a WireMock mapping, or it would overwrite an earlier registration.
+   */
+  public withMapping(name: string, source: WiremockMappingSource): this {
+    within(`WiremockContainer.withMapping("${name}")`, () => {
+      const file = containerName(name);
+      const target = posix.join(MAPPINGS, file.endsWith(".json") ? file : `${file}.json`);
+      const inline = isRecord(source) && "json" in source;
+      const origin = inline ? INLINE : resolveFile(source);
+      const content = inline ? inlineJson(source.json) : readFileSync(origin);
+      const ids = within(origin, () => stubIds(content.toString()));
+      this.withCopyContentToContainer(this.#claim([{ target, origin, ids }]).map(() => ({ content, target })));
+    });
+    return this;
+  }
+
+  /**
+   * Registers response bodies at `__files/<name>` (default: the base name), copied as-is.
+   * @example
+   * ```typescript
+   * new WiremockContainer().withFiles("./test/fixtures/body.json", { file: "./logo.png", name: "img/logo.png" });
+   * ```
+   * @throws If a source or name is invalid, or a file would overwrite an earlier registration; nothing is registered then.
+   */
+  public withFiles(...files: WiremockStaticFile[]): this {
+    within("WiremockContainer.withFiles", () => {
+      const claims = files.map((file) => {
+        const origin = resolveFile(file);
+        const name = isRecord(file) && file.name !== undefined ? containerName(file.name) : basename(origin);
+        return { target: posix.join(FILES, name), origin };
+      });
+      this.withCopyFilesToContainer(this.#claim(claims).map(({ origin, target }) => ({ source: origin, target })));
+    });
     return this;
   }
 
@@ -62,13 +160,36 @@ export class WiremockContainer extends GenericContainer {
       `http://${startedContainer.getHost()}:${startedContainer.getMappedPort(8080)}`,
     );
   }
+
+  /**
+   * Records `claims` – all or nothing – unless one would overwrite a file from another origin or
+   * reuse a stub id. Returns the claims not already registered from the same file.
+   */
+  #claim<T extends Claim>(claims: readonly T[]): T[] {
+    const origins = new Map(this.#origins);
+    const owners = new Map(this.#stubIds);
+    const fresh = claims.filter(({ target, origin, ids = [] }) => {
+      const existing = origins.get(target);
+      if (existing === origin && origin !== INLINE) return false;
+      if (existing) fail(`"${target}" is already registered from ${existing}; registering ${origin} would overwrite it`);
+      for (const id of ids) {
+        const owner = owners.get(id);
+        if (owner) fail(`stub id "${id}" in ${origin} is already used by "${owner}"; WireMock refuses to start with duplicate stub ids`);
+        owners.set(id, target);
+      }
+      origins.set(target, origin);
+      return true;
+    });
+    [this.#origins, this.#stubIds] = [origins, owners];
+    return fresh;
+  }
 }
 
 /**
  * A started Wiremock container with helper methods for interacting with the node.
  */
 export class StartedWiremockContainer extends AbstractStartedContainer {
-  private readonly _rpcUrl;
+  readonly #rpcUrl: string;
 
   /**
    * Creates a new StartedWiremockContainer.
@@ -77,13 +198,13 @@ export class StartedWiremockContainer extends AbstractStartedContainer {
    */
   constructor(startedTestContainer: StartedTestContainer, url: string) {
     super(startedTestContainer);
-    this._rpcUrl = url;
+    this.#rpcUrl = url;
   }
 
   /**
    * Gets the URL of the Wiremock node.
    */
-  get rpcUrl() {
-    return this._rpcUrl;
+  get rpcUrl(): string {
+    return this.#rpcUrl;
   }
 }

package/src/sources.ts

@@ -0,0 +1,143 @@
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+import { createRequire } from "node:module";
+import { dirname, join, relative, resolve, sep } from "node:path";
+import { fileURLToPath } from "node:url";
+
+/** A path (relative to the working directory) or a `file:` URL. */
+export type WiremockPath = string | URL;
+
+/**
+ * A fixture file: a local path or `file:` URL, `{ file }`, a file inside an installed npm
+ * package `{ package, file }` (its `exports` are ignored), or a file next to a module
+ * `{ module: import.meta.url | __filename | __dirname, file }`.
+ */
+export type WiremockFileSource =
+  | WiremockPath
+  | { readonly file: WiremockPath }
+  | { readonly package: string; readonly file: string }
+  | { readonly module: WiremockPath; readonly file: string };
+
+/** A WireMock stub; fields besides `request` and `response` are passed through. */
+export interface WiremockStubMapping {
+  readonly request: object;
+  readonly response: object;
+  readonly [field: string]: unknown;
+}
+
+/** A file source, or inline JSON: a string, a stub or `{ mappings: [...] }`. */
+export type WiremockMappingSource =
+  | WiremockFileSource
+  | { readonly json: string | WiremockStubMapping | { readonly mappings: readonly WiremockStubMapping[] } };
+
+/** A file source; object forms may set `name`, the path below `__files/` (default: the base name). */
+export type WiremockStaticFile = WiremockPath | (Exclude<WiremockFileSource, WiremockPath> & { readonly name?: string });
+
+const PACKAGE_NAME = /^(?:@[a-z0-9-~][a-z0-9-._~]*\/)?[a-z0-9-~][a-z0-9-._~]*$/u;
+
+export function fail(message: string): never {
+  throw new Error(message);
+}
+
+/** Runs `fn`, prefixing the message of any error it throws with `context`. */
+export function within<T>(context: string, fn: () => T): T {
+  try {
+    return fn();
+  } catch (error) {
+    throw new Error(`${context}: ${(error as Error).message}`, { cause: error });
+  }
+}
+
+export const isRecord = (value: unknown): value is Record<string, unknown> =>
+  typeof value === "object" && value !== null && !Array.isArray(value);
+
+const show = (value: unknown): string => (value instanceof URL ? value.href : (JSON.stringify(value) ?? String(value)));
+
+const text = (value: unknown, field: string): string =>
+  typeof value === "string" && value.trim() !== "" ? value : fail(`"${field}" must be a non-empty string, got ${show(value)}`);
+
+const toPath = (value: unknown, field: string): string => {
+  if (!(value instanceof URL) && !text(value, field).startsWith("file:")) return resolve(value as string);
+  try {
+    return fileURLToPath(value as WiremockPath);
+  } catch {
+    return fail(`"${field}" must be a path or a file: URL, got ${show(value)}`);
+  }
+};
+
+const existingFile = (path: string): string => {
+  const stats = statSync(path, { throwIfNoEntry: false });
+  return stats?.isFile() ? path : fail(`"${path}" ${stats ? "is not a file" : "does not exist"}`);
+};
+
+/** Finds an installed package the way `require()` would from the working directory. */
+const packageRoot = (name: string): string => {
+  if (!PACKAGE_NAME.test(name)) fail(`"${name}" is not a valid npm package name`);
+  const searchPaths = createRequire(join(process.cwd(), "noop.js")).resolve.paths(name) ?? [];
+  const root = searchPaths.map((dir) => join(dir, name)).find((dir) => existsSync(join(dir, "package.json")));
+  return root ?? fail(`package "${name}" is not installed (searched from "${process.cwd()}")`);
+};
+
+/** Resolves a {@link WiremockFileSource} to the absolute path of an existing file. */
+export function resolveFile(source: unknown): string {
+  if (typeof source === "string" || source instanceof URL) return existingFile(toPath(source, "source"));
+  if (!isRecord(source)) return fail(`unsupported source ${show(source)}; expected a path, a file: URL, { file }, { package, file } or { module, file }`);
+  const { file, package: pkg, module } = source;
+  if (pkg !== undefined && module !== undefined) fail('a source may set "package" or "module", not both');
+  if (pkg !== undefined) {
+    const root = packageRoot(text(pkg, "package"));
+    const path = resolve(root, text(file, "file"));
+    return relative(root, path).split(sep)[0] === ".." ? fail(`"${String(file)}" must point to a file inside package "${pkg}"`) : existingFile(path);
+  }
+  if (module === undefined) return existingFile(toPath(file, "file"));
+  const anchor = toPath(module, "module");
+  return existingFile(resolve(statSync(anchor, { throwIfNoEntry: false })?.isDirectory() ? anchor : dirname(anchor), text(file, "file")));
+}
+
+/** Validates a `/`-separated relative container name (no empty, `.` or `..` segments). */
+export const containerName = (name: unknown): string => {
+  const value = text(name, "name");
+  const invalid = value.split("/").some((part) => ["", ".", ".."].includes(part) || /[\\\0]/u.test(part));
+  return invalid ? fail(`name "${value}" must be a relative path using "/" separators, without empty, "." or ".." segments`) : value;
+};
+
+/** Inline mapping JSON: strings verbatim, anything else pretty-printed. */
+export const inlineJson = (json: unknown): string =>
+  typeof json === "string" ? json : (JSON.stringify(json, null, 2) ?? fail('"json" must be a JSON string or an object'));
+
+const parseJson = (json: string): unknown => {
+  try {
+    return JSON.parse(json);
+  } catch (error) {
+    return fail(`invalid JSON (${(error as Error).message})`);
+  }
+};
+
+/** Validates a mapping file – one stub or `{ mappings: [...] }` – and returns its stub ids. */
+export function stubIds(json: string): string[] {
+  const value = parseJson(json);
+  const many = isRecord(value) && "mappings" in value;
+  const stubs = many ? value.mappings : [value];
+  if (!Array.isArray(stubs) || stubs.length === 0) fail('"mappings" must be a non-empty array of stub mappings');
+  return stubs.flatMap((stub: unknown, index) => {
+    if (!isRecord(stub) || !isRecord(stub.request) || !isRecord(stub.response)) {
+      fail(`${many ? `mappings[${index}]` : "the mapping"} is not a WireMock stub mapping ("request" and "response" objects are required)`);
+    }
+    const id = stub.id ?? stub.uuid;
+    return typeof id === "string" ? [id] : [];
+  });
+}
+
+/** {@link stubIds} of a file in a mounted directory; malformed files are left for WireMock to report. */
+export const stubIdsOf = (path: string): string[] => {
+  try {
+    return path.endsWith(".json") ? stubIds(readFileSync(path, "utf8")) : [];
+  } catch {
+    return [];
+  }
+};
+
+/** Files below `dir`, as `/`-separated relative paths. */
+export const listFiles = (dir: string): string[] =>
+  readdirSync(dir, { recursive: true, withFileTypes: true })
+    .filter((entry) => !entry.isDirectory())
+    .map((entry) => relative(dir, join(entry.parentPath, entry.name)).split(sep).join("/"));