API reference › @evolu/nodejs › TestJSDoc › testJSDocExamples

function testJSDocExamples(
  __namedParameters: TestJSDocExamplesOptions,
): Promise<void>;

Defined in: packages/nodejs/src/TestJSDoc.ts:159

Lints, compiles, and executes every TypeScript example in the included JSDoc comments and Markdown files.

Examples are compiled together as isolated TypeScript modules. Examples without compilation errors are then imported in source order by one Node.js process. Lint, compilation, and execution failures are reported together. Examples are linted with @evolu/oxlint-config. Evolu's required polyfills are installed before each example and the modules it imports run, without declaring anything an example could collide with.

TypeScript examples use ts fences, or tsx fences for JSX. Other spellings of them, such as typescript or TS, fail instead of leaving the example unchecked. TSX fences use the automatic React JSX runtime. Vite transforms them to JavaScript before they run, because Node.js cannot strip JSX. Only the examples are transformed, so the modules they import must not be TSX.

Install @evolu/oxlint-config, @evolu/typescript-config, oxlint, oxlint-tsgolint, and TypeScript as development dependencies in the project that calls this helper, and vite, react, and @types/react for TSX examples.

Write every TypeScript fence as a standalone, deterministic example and explicitly import its dependencies and assertions. Use assertType to prove static contracts, assertEqual for Data comparisons, assert with a descriptive message for invariants and narrowing, and assertOk or assertErr for Results. Prefix intentionally unused declarations with _; an underscore-prefixed declaration must remain unused. Package aliases are useful for examples documenting an entry point that is not exported yet. Package subpaths can be aliased independently. Each alias target must be an absolute TypeScript module path exposing the named exports used by the example.

Example

import { testJSDocExamples } from "@evolu/nodejs/TestJSDoc";
import { mkdtemp, rm, writeFile } from "node:fs/promises";
import { tmpdir } from "node:os";
import { join } from "node:path";

const fence = "`".repeat(3);
const directory = await mkdtemp(join(tmpdir(), "evolu-jsdoc-example-"));
try {
  const sourcePath = join(directory, "README.md");
  await writeFile(
    sourcePath,
    [
      `${fence}ts`,
      'import assert from "node:assert/strict";',
      "",
      "assert.equal(1 + 1, 2);",
      fence,
    ].join("\n"),
  );
  await testJSDocExamples({
    cwd: process.cwd(),
    include: sourcePath,
  });
} finally {
  await rm(directory, { force: true, recursive: true });
}