API reference › @evolu/nodejs › TestJSDoc › testJSDocExamples

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

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

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 runs.

Install @evolu/oxlint-config, @evolu/typescript-config, oxlint, oxlint-tsgolint, and TypeScript as development dependencies in the project that calls this helper.

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 directory = await mkdtemp(join(tmpdir(), "evolu-jsdoc-example-"));
try {
  const sourcePath = join(directory, "Example.ts");
  await writeFile(
    sourcePath,
    [
      "/**",
      " * ``" + "`ts",
      ' * import { assertEqual } from "@evolu/common";',
      " *",
      " * assertEqual(1 + 1, 2);",
      " * ``" + "`",
      " *" + "/",
      "export {};",
    ].join("\n"),
  );
  await testJSDocExamples({
    cwd: process.cwd(),
    include: sourcePath,
  });
} finally {
  await rm(directory, { force: true, recursive: true });
}