@evolu/vitest 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2023 Evolu
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,8 @@
+# Evolu Vitest
+
+Vitest assertions and test utilities for Evolu.
+
+## Documentation
+
+For detailed information and usage examples, please visit
+[evolu.dev](https://www.evolu.dev).

package/dist/src/TestJSDoc.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Vitest utilities for testing TypeScript examples embedded in JSDoc and
+ * Markdown.
+ *
+ * These utilities use the dedicated `@evolu/vitest/TestJSDoc` entry point so
+ * normal `@evolu/vitest` imports do not evaluate Node.js test tooling.
+ *
+ * @module
+ */
+import { type ReadonlyRecord } from "@evolu/common";
+/** Options for compiling and executing TypeScript documentation examples. */
+export interface TestJSDocExamplesOptions {
+    /** Source files or glob patterns resolved from `cwd`. */
+    readonly include: string | ReadonlyArray<string>;
+    /** Package imports redirected to absolute TypeScript entry paths. */
+    readonly aliases?: ReadonlyRecord<string, string>;
+    /** Directory used for globbing and package resolution. */
+    readonly cwd?: string;
+    /** TypeScript compiler package. Defaults to `"typescript"`. */
+    readonly typescriptPackage?: string;
+}
+/**
+ * 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 run concurrently, bounded by the CPU
+ * parallelism available to the process. Compilation and execution failures are
+ * reported together. Vitest's `assert`, `expect`, and `expectTypeOf`, along
+ * with Evolu's `expectOk` and `expectErr`, are injected into each module.
+ *
+ * Write every TypeScript fence as a standalone, deterministic example and
+ * import its dependencies. Use `expectTypeOf` to prove static contracts and an
+ * appropriate runtime assertion such as `expect`, `expectOk`, or `expectErr`
+ * instead of describing expected behavior only in comments.
+ *
+ * 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
+ *
+ * ```ts
+ * import { testJSDocExamples } from "@evolu/vitest/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",
+ *       " * expect(1 + 1).toBe(2);",
+ *       " * ``" + "`",
+ *       " *" + "/",
+ *       "export {};",
+ *     ].join("\n"),
+ *   );
+ *   await testJSDocExamples({
+ *     cwd: process.cwd(),
+ *     include: sourcePath,
+ *     typescriptPackage: "@typescript/native",
+ *   });
+ * } finally {
+ *   await rm(directory, { force: true, recursive: true });
+ * }
+ * ```
+ */
+export declare const testJSDocExamples: ({ include, aliases, cwd, typescriptPackage, }: TestJSDocExamplesOptions) => Promise<void>;
+//# sourceMappingURL=TestJSDoc.d.ts.map

package/dist/src/TestJSDoc.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"TestJSDoc.d.ts","sourceRoot":"","sources":["../../src/TestJSDoc.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAOL,KAAK,cAAc,EAGpB,MAAM,eAAe,CAAC;AAkBvB,6EAA6E;AAC7E,MAAM,WAAW,wBAAwB;IACvC,yDAAyD;IACzD,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,aAAa,CAAC,MAAM,CAAC,CAAC;IACjD,qEAAqE;IACrE,QAAQ,CAAC,OAAO,CAAC,EAAE,cAAc,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAClD,0DAA0D;IAC1D,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IACtB,+DAA+D;IAC/D,QAAQ,CAAC,iBAAiB,CAAC,EAAE,MAAM,CAAC;CACrC;AA8BD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmDG;AACH,eAAO,MAAM,iBAAiB,kDAK3B,wBAAwB,KAAG,OAAO,CAAC,IAAI,CAsIzC,CAAC"}

package/dist/src/TestJSDoc.js

@@ -0,0 +1,376 @@
+/**
+ * Vitest utilities for testing TypeScript examples embedded in JSDoc and
+ * Markdown.
+ *
+ * These utilities use the dedicated `@evolu/vitest/TestJSDoc` entry point so
+ * normal `@evolu/vitest` imports do not evaluate Node.js test tooling.
+ *
+ * @module
+ */
+var __addDisposableResource = (this && this.__addDisposableResource) || function (env, value, async) {
+    if (value !== null && value !== void 0) {
+        if (typeof value !== "object" && typeof value !== "function") throw new TypeError("Object expected.");
+        var dispose, inner;
+        if (async) {
+            if (!Symbol.asyncDispose) throw new TypeError("Symbol.asyncDispose is not defined.");
+            dispose = value[Symbol.asyncDispose];
+        }
+        if (dispose === void 0) {
+            if (!Symbol.dispose) throw new TypeError("Symbol.dispose is not defined.");
+            dispose = value[Symbol.dispose];
+            if (async) inner = dispose;
+        }
+        if (typeof dispose !== "function") throw new TypeError("Object not disposable.");
+        if (inner) dispose = function() { try { inner.call(this); } catch (e) { return Promise.reject(e); } };
+        env.stack.push({ value: value, dispose: dispose, async: async });
+    }
+    else if (async) {
+        env.stack.push({ async: true });
+    }
+    return value;
+};
+var __disposeResources = (this && this.__disposeResources) || (function (SuppressedError) {
+    return function (env) {
+        function fail(e) {
+            env.error = env.hasError ? new SuppressedError(e, env.error, "An error was suppressed during disposal.") : e;
+            env.hasError = true;
+        }
+        var r, s = 0;
+        function next() {
+            while (r = env.stack.pop()) {
+                try {
+                    if (!r.async && s === 1) return s = 0, env.stack.push(r), Promise.resolve().then(next);
+                    if (r.dispose) {
+                        var result = r.dispose.call(r.value);
+                        if (r.async) return s |= 2, Promise.resolve(result).then(next, function(e) { fail(e); return next(); });
+                    }
+                    else s |= 1;
+                }
+                catch (e) {
+                    fail(e);
+                }
+            }
+            if (s === 1) return env.hasError ? Promise.reject(env.error) : Promise.resolve();
+            if (env.hasError) throw env.error;
+        }
+        return next();
+    };
+})(typeof SuppressedError === "function" ? SuppressedError : function (error, suppressed, message) {
+    var e = new Error(message);
+    return e.name = "SuppressedError", e.error = error, e.suppressed = suppressed, e;
+});
+import { allSettled, createRun, filterArray, isErr, mapArray, PositiveInt, safelyStringifyUnknownValue, tryAsync, } from "@evolu/common";
+import assert from "node:assert/strict";
+import { spawn } from "node:child_process";
+import { globSync, mkdirSync, mkdtempSync, readFileSync, realpathSync, rmSync, writeFileSync, } from "node:fs";
+import { findPackageJSON } from "node:module";
+import { availableParallelism } from "node:os";
+import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { stripVTControlCharacters } from "node:util";
+const jsdocPattern = /\/\*\*[\s\S]*?\*\//g;
+const fencePattern = /(?:```|~~~)([^\n]*)\n([\s\S]*?)(?:(```|~~~)|$)/g;
+const markdownFilePattern = /\.mdx?$/i;
+const packageNamePattern = /^(?:@[a-z\d][a-z\d._~-]*\/)?[a-z\d][a-z\d._~-]*$/i;
+const packageSubpathSegmentPattern = /^[a-z\d][a-z\d._~-]*$/i;
+const polyfillsPath = fileURLToPath(import.meta.resolve("@evolu/common/polyfills"));
+/**
+ * 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 run concurrently, bounded by the CPU
+ * parallelism available to the process. Compilation and execution failures are
+ * reported together. Vitest's `assert`, `expect`, and `expectTypeOf`, along
+ * with Evolu's `expectOk` and `expectErr`, are injected into each module.
+ *
+ * Write every TypeScript fence as a standalone, deterministic example and
+ * import its dependencies. Use `expectTypeOf` to prove static contracts and an
+ * appropriate runtime assertion such as `expect`, `expectOk`, or `expectErr`
+ * instead of describing expected behavior only in comments.
+ *
+ * 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
+ *
+ * ```ts
+ * import { testJSDocExamples } from "@evolu/vitest/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",
+ *       " * expect(1 + 1).toBe(2);",
+ *       " * ``" + "`",
+ *       " *" + "/",
+ *       "export {};",
+ *     ].join("\n"),
+ *   );
+ *   await testJSDocExamples({
+ *     cwd: process.cwd(),
+ *     include: sourcePath,
+ *     typescriptPackage: "@typescript/native",
+ *   });
+ * } finally {
+ *   await rm(directory, { force: true, recursive: true });
+ * }
+ * ```
+ */
+export const testJSDocExamples = async ({ include, aliases = {}, cwd = process.cwd(), typescriptPackage = "typescript", }) => {
+    const workingDirectory = realpathSync(resolve(cwd));
+    const patterns = typeof include === "string" ? [include] : include;
+    assert(patterns.length > 0, "Documentation example tests require included files.");
+    const filePaths = Array.from(new Set(globSync(patterns, { cwd: workingDirectory }).map((filePath) => resolve(workingDirectory, filePath)))).sort();
+    assert(filePaths.length > 0, "No files matched the documentation example patterns.");
+    const examples = filePaths.flatMap((filePath) => extractDocumentationExamples(readFileSync(filePath, "utf8"), filePath));
+    assert(examples.length > 0, "No TypeScript documentation examples were found.");
+    const compilerPath = resolveTypeScriptCompiler(workingDirectory, typescriptPackage);
+    const temporaryRoot = join(workingDirectory, "tmp");
+    mkdirSync(temporaryRoot, { recursive: true });
+    const temporaryDirectory = mkdtempSync(join(temporaryRoot, "evolu-jsdoc-"));
+    try {
+        writeFileSync(join(temporaryDirectory, "package.json"), JSON.stringify({ type: "module" }));
+        createPackageAliases(temporaryDirectory, aliases);
+        const generatedExamples = examples.map((example, index) => {
+            const generatedPath = join(temporaryDirectory, `example-${index}.ts`);
+            writeFileSync(generatedPath, transformJSDocExample(example, generatedPath));
+            return { ...example, generatedPath };
+        });
+        // TODO: Lint generated examples with Oxc after the repository migration.
+        // Treat top-level declarations as example output and ignore `using`
+        // bindings whose disposal is their purpose.
+        const compilerConfigPath = join(temporaryDirectory, "tsconfig.json");
+        writeFileSync(compilerConfigPath, JSON.stringify({
+            compilerOptions: {
+                allowImportingTsExtensions: true,
+                erasableSyntaxOnly: true,
+                esModuleInterop: true,
+                exactOptionalPropertyTypes: true,
+                lib: ["DOM", "ESNext"],
+                module: "NodeNext",
+                moduleResolution: "NodeNext",
+                noEmit: true,
+                skipLibCheck: true,
+                strict: true,
+                target: "ES2022",
+                types: ["node"],
+                verbatimModuleSyntax: true,
+            },
+            files: generatedExamples.map(({ generatedPath }) => generatedPath),
+        }));
+        let compilationError;
+        try {
+            await runProcess(process.execPath, [compilerPath, "--project", compilerConfigPath], workingDirectory, "Documentation example TypeScript compilation", [
+                "Generated example sources:",
+                ...generatedExamples.map(({ filePath, generatedPath, line }) => `- ${relative(temporaryDirectory, generatedPath)}: ${relative(workingDirectory, filePath)}:${line}`),
+            ].join("\n"));
+        }
+        catch (error) {
+            compilationError =
+                error instanceof Error
+                    ? error
+                    : new Error(safelyStringifyUnknownValue(error));
+        }
+        const runnableExamples = compilationError === undefined
+            ? generatedExamples
+            : getExamplesWithoutCompilationErrors(generatedExamples, compilationError, workingDirectory);
+        let executionError;
+        try {
+            await runJSDocExamples(runnableExamples, workingDirectory);
+        }
+        catch (error) {
+            executionError =
+                error instanceof Error
+                    ? error
+                    : new Error(safelyStringifyUnknownValue(error));
+        }
+        if (compilationError !== undefined && executionError !== undefined) {
+            const executionErrors = executionError instanceof AggregateError
+                ? executionError.errors
+                : [executionError];
+            throw new AggregateError([compilationError, ...executionErrors], `${compilationError.message}\n${executionError.message}`);
+        }
+        if (compilationError !== undefined)
+            throw compilationError;
+        if (executionError !== undefined)
+            throw executionError;
+    }
+    finally {
+        rmSync(temporaryDirectory, { force: true, recursive: true });
+    }
+};
+const getExamplesWithoutCompilationErrors = (examples, compilationError, workingDirectory) => {
+    const compilationErrorMessage = stripVTControlCharacters(compilationError.message);
+    const examplesWithErrors = examples.filter(({ generatedPath }) => [generatedPath, relative(workingDirectory, generatedPath)].some((path) => [`${path}(`, `${path}:`].some((segment) => compilationErrorMessage.includes(segment))));
+    if (examplesWithErrors.length === 0)
+        return [];
+    return examples.filter((example) => !examplesWithErrors.includes(example));
+};
+const extractDocumentationExamples = (source, filePath) => {
+    if (markdownFilePattern.test(filePath)) {
+        return extractFencedExamples(source, source, filePath, 0, false);
+    }
+    const examples = [];
+    for (const jsdoc of source.matchAll(jsdocPattern)) {
+        examples.push(...extractFencedExamples(source, jsdoc[0], filePath, jsdoc.index, true));
+    }
+    return examples;
+};
+const extractFencedExamples = (source, fencedSource, filePath, offset, stripJSDocPrefixes) => {
+    const examples = [];
+    for (const fence of fencedSource.matchAll(fencePattern)) {
+        const metadata = fence[1].trim().toLowerCase().split(/\s+/);
+        if (!["ts", "typescript"].includes(metadata[0])) {
+            continue;
+        }
+        const line = getLineNumber(source, offset + fence.index);
+        const closingFence = fence[3];
+        assert(closingFence !== undefined, `${filePath}:${line} has an unclosed TypeScript example fence.`);
+        const exampleSource = (stripJSDocPrefixes ? fence[2].replace(/^[ \t]*\* ?/gm, "") : fence[2]).trim();
+        assert(exampleSource.length > 0, `${filePath}:${line} has an empty TypeScript example.`);
+        examples.push({ filePath, line, source: exampleSource });
+    }
+    return examples;
+};
+const getLineNumber = (source, offset) => {
+    let line = 1;
+    for (let index = 0; index < offset; index++) {
+        if (source.charCodeAt(index) === 10)
+            line++;
+    }
+    return line;
+};
+const transformJSDocExample = (example, generatedPath) => [
+    `import { installPolyfills } from ${JSON.stringify(pathToImportSpecifier(generatedPath, polyfillsPath))};`,
+    'import { expectErr, expectOk } from "@evolu/vitest";',
+    'import { assert, expect, expectTypeOf } from "vitest";',
+    "installPolyfills();",
+    example.source,
+].join("\n\n");
+const resolveTypeScriptCompiler = (workingDirectory, typescriptPackage) => {
+    const packagePath = findPackageJSON(typescriptPackage, pathToFileURL(join(workingDirectory, "package.json")));
+    assert(packagePath !== undefined, `Cannot resolve ${typescriptPackage} from ${workingDirectory}.`);
+    const packageJson = JSON.parse(readFileSync(packagePath, "utf8"));
+    const compiler = typeof packageJson.bin === "string" ? packageJson.bin : packageJson.bin.tsc;
+    assert(compiler !== undefined, `${typescriptPackage} does not expose a tsc executable.`);
+    return resolve(dirname(packagePath), compiler);
+};
+const runJSDocExamples = async (examples, workingDirectory) => {
+    const env_1 = { stack: [], error: void 0, hasError: false };
+    try {
+        const run = __addDisposableResource(env_1, createRun(), true);
+        const results = await run.ok(allSettled(examples, (example) => async (run) => tryAsync(() => runProcess(process.execPath, [example.generatedPath], workingDirectory, "Node.js execution"), (error) => {
+            run.signal.throwIfAborted();
+            return { error, example };
+        }), { concurrency: PositiveInt.orThrow(availableParallelism()) }));
+        const failures = filterArray(results, isErr);
+        if (failures.length === 0)
+            return;
+        const errors = mapArray(failures, ({ error: { error, example: { filePath, line }, }, }) => {
+            const message = error instanceof Error
+                ? error.message
+                : safelyStringifyUnknownValue(error);
+            return new Error(`${relative(workingDirectory, filePath)}:${line}: ${message}`, { cause: error });
+        });
+        throw new AggregateError(errors, [
+            "JSDoc example execution failed.",
+            ...mapArray(errors, (error) => `- ${error.message}`),
+        ].join("\n"));
+    }
+    catch (e_1) {
+        env_1.error = e_1;
+        env_1.hasError = true;
+    }
+    finally {
+        const result_1 = __disposeResources(env_1);
+        if (result_1)
+            await result_1;
+    }
+};
+const createPackageAliases = (temporaryDirectory, aliases) => {
+    const aliasesByPackageName = new Map();
+    for (const [name, target] of Object.entries(aliases)) {
+        assert(isAbsolute(target), `Package alias ${name} must be absolute.`);
+        const segments = name.split("/");
+        const packageSegmentCount = name.startsWith("@") ? 2 : 1;
+        const packageName = segments.slice(0, packageSegmentCount).join("/");
+        const subpathSegments = segments.slice(packageSegmentCount);
+        assert(packageNamePattern.test(packageName) &&
+            subpathSegments.every((segment) => packageSubpathSegmentPattern.test(segment)), `Invalid package alias: ${name}.`);
+        const subpath = subpathSegments.join("/");
+        const packageAliases = aliasesByPackageName.get(packageName) ?? [];
+        packageAliases.push({ subpath, targetPath: realpathSync(target) });
+        aliasesByPackageName.set(packageName, packageAliases);
+    }
+    for (const [packageName, packageAliases] of aliasesByPackageName) {
+        const packageSegments = packageName.split("/");
+        const packageDirectory = join(temporaryDirectory, "node_modules", ...packageSegments);
+        mkdirSync(packageDirectory, { recursive: true });
+        const exportsBySubpath = {};
+        for (const { subpath, targetPath } of packageAliases) {
+            const entryPathWithoutExtension = subpath || "index";
+            const exportName = subpath ? `./${subpath}` : ".";
+            exportsBySubpath[exportName] = {
+                types: `./${entryPathWithoutExtension}.ts`,
+                default: `./${entryPathWithoutExtension}.js`,
+            };
+            for (const extension of ["ts", "js"]) {
+                const entryPath = join(packageDirectory, `${entryPathWithoutExtension}.${extension}`);
+                mkdirSync(dirname(entryPath), { recursive: true });
+                writeFileSync(entryPath, `export * from ${JSON.stringify(pathToImportSpecifier(entryPath, targetPath))};\n`);
+            }
+        }
+        writeFileSync(join(packageDirectory, "package.json"), JSON.stringify({
+            name: packageName,
+            type: "module",
+            exports: exportsBySubpath,
+        }));
+    }
+};
+const pathToImportSpecifier = (from, to) => {
+    const path = relative(dirname(from), to).split(sep).join("/");
+    return path.startsWith(".") ? path : `./${path}`;
+};
+const runProcess = (command, args, cwd, operation, details) => new Promise((resolve, reject) => {
+    const child = spawn(command, args, {
+        cwd,
+        stdio: ["ignore", "pipe", "pipe"],
+    });
+    const stdout = [];
+    const stderr = [];
+    child.stdout.on("data", (chunk) => {
+        stdout.push(chunk);
+    });
+    child.stderr.on("data", (chunk) => {
+        stderr.push(chunk);
+    });
+    child.once("error", (error) => {
+        reject(new Error([`${operation} failed.`, details].filter(Boolean).join("\n"), {
+            cause: error,
+        }));
+    });
+    child.once("close", (code, signal) => {
+        if (code === 0) {
+            resolve();
+            return;
+        }
+        reject(new Error([
+            `${operation} failed${signal === null ? ` with exit code ${String(code)}` : ` from signal ${signal}`}.`,
+            details,
+            Buffer.concat(stdout).toString("utf8"),
+            Buffer.concat(stderr).toString("utf8"),
+        ]
+            .filter(Boolean)
+            .join("\n")));
+    });
+});

package/dist/src/index.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Vitest assertions for Evolu.
+ *
+ * @module
+ */
+import type { Err, Ok, Result } from "@evolu/common";
+/**
+ * Expects an {@link Ok} Result whose value matches the expected value using
+ * Vitest's `toEqual`, and narrows the Result.
+ *
+ * Use `toBe` on the narrowed value when reference identity also matters.
+ */
+export declare const expectOk: <R extends Result<unknown, unknown>>(result: R, expectedValue: unknown) => asserts result is Extract<R, Ok<unknown>>;
+/**
+ * Expects an {@link Err} Result whose error matches the expected error using
+ * Vitest's `toEqual`, and narrows the Result.
+ *
+ * Use `toBe` on the narrowed error when reference identity also matters.
+ */
+export declare const expectErr: <R extends Result<unknown, unknown>>(result: R, expectedError: unknown) => asserts result is Extract<R, Err<unknown>>;
+//# sourceMappingURL=index.d.ts.map

package/dist/src/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,GAAG,EAAE,EAAE,EAAE,MAAM,EAAE,MAAM,eAAe,CAAC;AAGrD;;;;;GAKG;AACH,eAAO,MAAM,QAAQ,EAAE,CAAC,CAAC,SAAS,MAAM,CAAC,OAAO,EAAE,OAAO,CAAC,EACxD,MAAM,EAAE,CAAC,EACT,aAAa,EAAE,OAAO,KACnB,OAAO,CAAC,MAAM,IAAI,OAAO,CAAC,CAAC,EAAE,EAAE,CAAC,OAAO,CAAC,CAE5C,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,SAAS,EAAE,CAAC,CAAC,SAAS,MAAM,CAAC,OAAO,EAAE,OAAO,CAAC,EACzD,MAAM,EAAE,CAAC,EACT,aAAa,EAAE,OAAO,KACnB,OAAO,CAAC,MAAM,IAAI,OAAO,CAAC,CAAC,EAAE,GAAG,CAAC,OAAO,CAAC,CAE7C,CAAC"}

package/dist/src/index.js

@@ -0,0 +1,24 @@
+/**
+ * Vitest assertions for Evolu.
+ *
+ * @module
+ */
+import { expect } from "vitest";
+/**
+ * Expects an {@link Ok} Result whose value matches the expected value using
+ * Vitest's `toEqual`, and narrows the Result.
+ *
+ * Use `toBe` on the narrowed value when reference identity also matters.
+ */
+export const expectOk = (result, expectedValue) => {
+    expect(result).toEqual({ ok: true, value: expectedValue });
+};
+/**
+ * Expects an {@link Err} Result whose error matches the expected error using
+ * Vitest's `toEqual`, and narrows the Result.
+ *
+ * Use `toBe` on the narrowed error when reference identity also matters.
+ */
+export const expectErr = (result, expectedError) => {
+    expect(result).toEqual({ ok: false, error: expectedError });
+};

package/package.json

@@ -0,0 +1,64 @@
+{
+  "name": "@evolu/vitest",
+  "version": "1.0.0",
+  "description": "Vitest assertions and test utilities for Evolu",
+  "keywords": [
+    "evolu",
+    "vitest"
+  ],
+  "author": "Daniel Steigerwald <daniel@steigerwald.cz>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/evoluhq/evolu.git"
+  },
+  "bugs": {
+    "url": "https://github.com/evoluhq/evolu/issues"
+  },
+  "homepage": "https://evolu.dev",
+  "type": "module",
+  "types": "./dist/src/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/src/index.d.ts",
+      "import": "./dist/src/index.js"
+    },
+    "./TestJSDoc": {
+      "types": "./dist/src/TestJSDoc.d.ts",
+      "import": "./dist/src/TestJSDoc.js"
+    }
+  },
+  "typesVersions": {
+    "*": {
+      "TestJSDoc": [
+        "./dist/src/TestJSDoc.d.ts"
+      ]
+    }
+  },
+  "files": [
+    "dist/src/**",
+    "src/**",
+    "README.md"
+  ],
+  "devDependencies": {
+    "@typescript/native": "npm:typescript@^7.0.2",
+    "vitest": "^4.1.2",
+    "@evolu/common": "8.0.0",
+    "@evolu/typescript-config": "0.0.2"
+  },
+  "peerDependencies": {
+    "@evolu/common": "^8.0.0-next.0",
+    "vitest": "^4.1.2"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=24.0.0"
+  },
+  "sideEffects": false,
+  "scripts": {
+    "build": "tsc --build tsconfig.build.json",
+    "format": "prettier --write \"src/*.{ts,md}\""
+  }
+}

package/src/TestJSDoc.ts

@@ -0,0 +1,574 @@
+/**
+ * Vitest utilities for testing TypeScript examples embedded in JSDoc and
+ * Markdown.
+ *
+ * These utilities use the dedicated `@evolu/vitest/TestJSDoc` entry point so
+ * normal `@evolu/vitest` imports do not evaluate Node.js test tooling.
+ *
+ * @module
+ */
+
+import {
+  allSettled,
+  createRun,
+  filterArray,
+  isErr,
+  mapArray,
+  PositiveInt,
+  type ReadonlyRecord,
+  safelyStringifyUnknownValue,
+  tryAsync,
+} from "@evolu/common";
+import assert from "node:assert/strict";
+import { spawn } from "node:child_process";
+import {
+  globSync,
+  mkdirSync,
+  mkdtempSync,
+  readFileSync,
+  realpathSync,
+  rmSync,
+  writeFileSync,
+} from "node:fs";
+import { findPackageJSON } from "node:module";
+import { availableParallelism } from "node:os";
+import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { stripVTControlCharacters } from "node:util";
+
+/** Options for compiling and executing TypeScript documentation examples. */
+export interface TestJSDocExamplesOptions {
+  /** Source files or glob patterns resolved from `cwd`. */
+  readonly include: string | ReadonlyArray<string>;
+  /** Package imports redirected to absolute TypeScript entry paths. */
+  readonly aliases?: ReadonlyRecord<string, string>;
+  /** Directory used for globbing and package resolution. */
+  readonly cwd?: string;
+  /** TypeScript compiler package. Defaults to `"typescript"`. */
+  readonly typescriptPackage?: string;
+}
+
+interface JSDocExample {
+  readonly filePath: string;
+  readonly line: number;
+  readonly source: string;
+}
+
+interface GeneratedJSDocExample extends JSDocExample {
+  readonly generatedPath: string;
+}
+
+interface JSDocExampleFailure {
+  readonly error: unknown;
+  readonly example: GeneratedJSDocExample;
+}
+
+interface TypeScriptPackage {
+  readonly bin: string | { readonly tsc?: string };
+}
+
+const jsdocPattern = /\/\*\*[\s\S]*?\*\//g;
+const fencePattern = /(?:```|~~~)([^\n]*)\n([\s\S]*?)(?:(```|~~~)|$)/g;
+const markdownFilePattern = /\.mdx?$/i;
+const packageNamePattern = /^(?:@[a-z\d][a-z\d._~-]*\/)?[a-z\d][a-z\d._~-]*$/i;
+const packageSubpathSegmentPattern = /^[a-z\d][a-z\d._~-]*$/i;
+const polyfillsPath = fileURLToPath(
+  import.meta.resolve("@evolu/common/polyfills"),
+);
+
+/**
+ * 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 run concurrently, bounded by the CPU
+ * parallelism available to the process. Compilation and execution failures are
+ * reported together. Vitest's `assert`, `expect`, and `expectTypeOf`, along
+ * with Evolu's `expectOk` and `expectErr`, are injected into each module.
+ *
+ * Write every TypeScript fence as a standalone, deterministic example and
+ * import its dependencies. Use `expectTypeOf` to prove static contracts and an
+ * appropriate runtime assertion such as `expect`, `expectOk`, or `expectErr`
+ * instead of describing expected behavior only in comments.
+ *
+ * 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
+ *
+ * ```ts
+ * import { testJSDocExamples } from "@evolu/vitest/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",
+ *       " * expect(1 + 1).toBe(2);",
+ *       " * ``" + "`",
+ *       " *" + "/",
+ *       "export {};",
+ *     ].join("\n"),
+ *   );
+ *   await testJSDocExamples({
+ *     cwd: process.cwd(),
+ *     include: sourcePath,
+ *     typescriptPackage: "@typescript/native",
+ *   });
+ * } finally {
+ *   await rm(directory, { force: true, recursive: true });
+ * }
+ * ```
+ */
+export const testJSDocExamples = async ({
+  include,
+  aliases = {},
+  cwd = process.cwd(),
+  typescriptPackage = "typescript",
+}: TestJSDocExamplesOptions): Promise<void> => {
+  const workingDirectory = realpathSync(resolve(cwd));
+  const patterns = typeof include === "string" ? [include] : include;
+  assert(
+    patterns.length > 0,
+    "Documentation example tests require included files.",
+  );
+
+  const filePaths = Array.from(
+    new Set(
+      globSync(patterns, { cwd: workingDirectory }).map((filePath) =>
+        resolve(workingDirectory, filePath),
+      ),
+    ),
+  ).sort();
+  assert(
+    filePaths.length > 0,
+    "No files matched the documentation example patterns.",
+  );
+
+  const examples = filePaths.flatMap((filePath) =>
+    extractDocumentationExamples(readFileSync(filePath, "utf8"), filePath),
+  );
+  assert(
+    examples.length > 0,
+    "No TypeScript documentation examples were found.",
+  );
+
+  const compilerPath = resolveTypeScriptCompiler(
+    workingDirectory,
+    typescriptPackage,
+  );
+  const temporaryRoot = join(workingDirectory, "tmp");
+  mkdirSync(temporaryRoot, { recursive: true });
+
+  const temporaryDirectory = mkdtempSync(join(temporaryRoot, "evolu-jsdoc-"));
+
+  try {
+    writeFileSync(
+      join(temporaryDirectory, "package.json"),
+      JSON.stringify({ type: "module" }),
+    );
+    createPackageAliases(temporaryDirectory, aliases);
+
+    const generatedExamples = examples.map((example, index) => {
+      const generatedPath = join(temporaryDirectory, `example-${index}.ts`);
+      writeFileSync(
+        generatedPath,
+        transformJSDocExample(example, generatedPath),
+      );
+      return { ...example, generatedPath } satisfies GeneratedJSDocExample;
+    });
+    // TODO: Lint generated examples with Oxc after the repository migration.
+    // Treat top-level declarations as example output and ignore `using`
+    // bindings whose disposal is their purpose.
+    const compilerConfigPath = join(temporaryDirectory, "tsconfig.json");
+    writeFileSync(
+      compilerConfigPath,
+      JSON.stringify({
+        compilerOptions: {
+          allowImportingTsExtensions: true,
+          erasableSyntaxOnly: true,
+          esModuleInterop: true,
+          exactOptionalPropertyTypes: true,
+          lib: ["DOM", "ESNext"],
+          module: "NodeNext",
+          moduleResolution: "NodeNext",
+          noEmit: true,
+          skipLibCheck: true,
+          strict: true,
+          target: "ES2022",
+          types: ["node"],
+          verbatimModuleSyntax: true,
+        },
+        files: generatedExamples.map(({ generatedPath }) => generatedPath),
+      }),
+    );
+
+    let compilationError: Error | undefined;
+    try {
+      await runProcess(
+        process.execPath,
+        [compilerPath, "--project", compilerConfigPath],
+        workingDirectory,
+        "Documentation example TypeScript compilation",
+        [
+          "Generated example sources:",
+          ...generatedExamples.map(
+            ({ filePath, generatedPath, line }) =>
+              `- ${relative(temporaryDirectory, generatedPath)}: ${relative(workingDirectory, filePath)}:${line}`,
+          ),
+        ].join("\n"),
+      );
+    } catch (error) {
+      compilationError =
+        error instanceof Error
+          ? error
+          : new Error(safelyStringifyUnknownValue(error));
+    }
+
+    const runnableExamples =
+      compilationError === undefined
+        ? generatedExamples
+        : getExamplesWithoutCompilationErrors(
+            generatedExamples,
+            compilationError,
+            workingDirectory,
+          );
+
+    let executionError: Error | undefined;
+    try {
+      await runJSDocExamples(runnableExamples, workingDirectory);
+    } catch (error) {
+      executionError =
+        error instanceof Error
+          ? error
+          : new Error(safelyStringifyUnknownValue(error));
+    }
+
+    if (compilationError !== undefined && executionError !== undefined) {
+      const executionErrors: ReadonlyArray<unknown> =
+        executionError instanceof AggregateError
+          ? (executionError.errors as ReadonlyArray<unknown>)
+          : [executionError];
+      throw new AggregateError(
+        [compilationError, ...executionErrors],
+        `${compilationError.message}\n${executionError.message}`,
+      );
+    }
+    if (compilationError !== undefined) throw compilationError;
+    if (executionError !== undefined) throw executionError;
+  } finally {
+    rmSync(temporaryDirectory, { force: true, recursive: true });
+  }
+};
+
+const getExamplesWithoutCompilationErrors = (
+  examples: ReadonlyArray<GeneratedJSDocExample>,
+  compilationError: Error,
+  workingDirectory: string,
+): ReadonlyArray<GeneratedJSDocExample> => {
+  const compilationErrorMessage = stripVTControlCharacters(
+    compilationError.message,
+  );
+  const examplesWithErrors = examples.filter(({ generatedPath }) =>
+    [generatedPath, relative(workingDirectory, generatedPath)].some((path) =>
+      [`${path}(`, `${path}:`].some((segment) =>
+        compilationErrorMessage.includes(segment),
+      ),
+    ),
+  );
+
+  if (examplesWithErrors.length === 0) return [];
+
+  return examples.filter((example) => !examplesWithErrors.includes(example));
+};
+
+const extractDocumentationExamples = (
+  source: string,
+  filePath: string,
+): ReadonlyArray<JSDocExample> => {
+  if (markdownFilePattern.test(filePath)) {
+    return extractFencedExamples(source, source, filePath, 0, false);
+  }
+
+  const examples: Array<JSDocExample> = [];
+  for (const jsdoc of source.matchAll(jsdocPattern)) {
+    examples.push(
+      ...extractFencedExamples(source, jsdoc[0], filePath, jsdoc.index, true),
+    );
+  }
+
+  return examples;
+};
+
+const extractFencedExamples = (
+  source: string,
+  fencedSource: string,
+  filePath: string,
+  offset: number,
+  stripJSDocPrefixes: boolean,
+): ReadonlyArray<JSDocExample> => {
+  const examples: Array<JSDocExample> = [];
+
+  for (const fence of fencedSource.matchAll(fencePattern)) {
+    const metadata = fence[1].trim().toLowerCase().split(/\s+/);
+    if (!["ts", "typescript"].includes(metadata[0])) {
+      continue;
+    }
+
+    const line = getLineNumber(source, offset + fence.index);
+    const closingFence = fence[3] as string | undefined;
+    assert(
+      closingFence !== undefined,
+      `${filePath}:${line} has an unclosed TypeScript example fence.`,
+    );
+    const exampleSource = (
+      stripJSDocPrefixes ? fence[2].replace(/^[ \t]*\* ?/gm, "") : fence[2]
+    ).trim();
+    assert(
+      exampleSource.length > 0,
+      `${filePath}:${line} has an empty TypeScript example.`,
+    );
+    examples.push({ filePath, line, source: exampleSource });
+  }
+
+  return examples;
+};
+
+const getLineNumber = (source: string, offset: number): number => {
+  let line = 1;
+  for (let index = 0; index < offset; index++) {
+    if (source.charCodeAt(index) === 10) line++;
+  }
+  return line;
+};
+
+const transformJSDocExample = (
+  example: JSDocExample,
+  generatedPath: string,
+): string =>
+  [
+    `import { installPolyfills } from ${JSON.stringify(pathToImportSpecifier(generatedPath, polyfillsPath))};`,
+    'import { expectErr, expectOk } from "@evolu/vitest";',
+    'import { assert, expect, expectTypeOf } from "vitest";',
+    "installPolyfills();",
+    example.source,
+  ].join("\n\n");
+
+const resolveTypeScriptCompiler = (
+  workingDirectory: string,
+  typescriptPackage: string,
+): string => {
+  const packagePath = findPackageJSON(
+    typescriptPackage,
+    pathToFileURL(join(workingDirectory, "package.json")),
+  );
+  assert(
+    packagePath !== undefined,
+    `Cannot resolve ${typescriptPackage} from ${workingDirectory}.`,
+  );
+  const packageJson = JSON.parse(
+    readFileSync(packagePath, "utf8"),
+  ) as TypeScriptPackage;
+  const compiler =
+    typeof packageJson.bin === "string" ? packageJson.bin : packageJson.bin.tsc;
+  assert(
+    compiler !== undefined,
+    `${typescriptPackage} does not expose a tsc executable.`,
+  );
+  return resolve(dirname(packagePath), compiler);
+};
+
+const runJSDocExamples = async (
+  examples: ReadonlyArray<GeneratedJSDocExample>,
+  workingDirectory: string,
+): Promise<void> => {
+  await using run = createRun();
+  const results = await run.ok(
+    allSettled(
+      examples,
+      (example) => async (run) =>
+        tryAsync(
+          () =>
+            runProcess(
+              process.execPath,
+              [example.generatedPath],
+              workingDirectory,
+              "Node.js execution",
+            ),
+          (error) => {
+            run.signal.throwIfAborted();
+            return { error, example } satisfies JSDocExampleFailure;
+          },
+        ),
+      { concurrency: PositiveInt.orThrow(availableParallelism()) },
+    ),
+  );
+
+  const failures = filterArray(results, isErr);
+  if (failures.length === 0) return;
+
+  const errors = mapArray(
+    failures,
+    ({
+      error: {
+        error,
+        example: { filePath, line },
+      },
+    }) => {
+      const message =
+        error instanceof Error
+          ? error.message
+          : safelyStringifyUnknownValue(error);
+      return new Error(
+        `${relative(workingDirectory, filePath)}:${line}: ${message}`,
+        { cause: error },
+      );
+    },
+  );
+  throw new AggregateError(
+    errors,
+    [
+      "JSDoc example execution failed.",
+      ...mapArray(errors, (error) => `- ${error.message}`),
+    ].join("\n"),
+  );
+};
+
+const createPackageAliases = (
+  temporaryDirectory: string,
+  aliases: ReadonlyRecord<string, string>,
+): void => {
+  const aliasesByPackageName = new Map<
+    string,
+    Array<{
+      readonly subpath: string;
+      readonly targetPath: string;
+    }>
+  >();
+
+  for (const [name, target] of Object.entries(aliases)) {
+    assert(isAbsolute(target), `Package alias ${name} must be absolute.`);
+    const segments = name.split("/");
+    const packageSegmentCount = name.startsWith("@") ? 2 : 1;
+    const packageName = segments.slice(0, packageSegmentCount).join("/");
+    const subpathSegments = segments.slice(packageSegmentCount);
+    assert(
+      packageNamePattern.test(packageName) &&
+        subpathSegments.every((segment) =>
+          packageSubpathSegmentPattern.test(segment),
+        ),
+      `Invalid package alias: ${name}.`,
+    );
+    const subpath = subpathSegments.join("/");
+    const packageAliases = aliasesByPackageName.get(packageName) ?? [];
+    packageAliases.push({ subpath, targetPath: realpathSync(target) });
+    aliasesByPackageName.set(packageName, packageAliases);
+  }
+
+  for (const [packageName, packageAliases] of aliasesByPackageName) {
+    const packageSegments = packageName.split("/");
+    const packageDirectory = join(
+      temporaryDirectory,
+      "node_modules",
+      ...packageSegments,
+    );
+    mkdirSync(packageDirectory, { recursive: true });
+    const exportsBySubpath: Record<
+      string,
+      { readonly types: string; readonly default: string }
+    > = {};
+
+    for (const { subpath, targetPath } of packageAliases) {
+      const entryPathWithoutExtension = subpath || "index";
+      const exportName = subpath ? `./${subpath}` : ".";
+      exportsBySubpath[exportName] = {
+        types: `./${entryPathWithoutExtension}.ts`,
+        default: `./${entryPathWithoutExtension}.js`,
+      };
+
+      for (const extension of ["ts", "js"]) {
+        const entryPath = join(
+          packageDirectory,
+          `${entryPathWithoutExtension}.${extension}`,
+        );
+        mkdirSync(dirname(entryPath), { recursive: true });
+        writeFileSync(
+          entryPath,
+          `export * from ${JSON.stringify(pathToImportSpecifier(entryPath, targetPath))};\n`,
+        );
+      }
+    }
+
+    writeFileSync(
+      join(packageDirectory, "package.json"),
+      JSON.stringify({
+        name: packageName,
+        type: "module",
+        exports: exportsBySubpath,
+      }),
+    );
+  }
+};
+
+const pathToImportSpecifier = (from: string, to: string): string => {
+  const path = relative(dirname(from), to).split(sep).join("/");
+  return path.startsWith(".") ? path : `./${path}`;
+};
+
+const runProcess = (
+  command: string,
+  args: ReadonlyArray<string>,
+  cwd: string,
+  operation: string,
+  details?: string,
+): Promise<void> =>
+  new Promise((resolve, reject) => {
+    const child = spawn(command, args, {
+      cwd,
+      stdio: ["ignore", "pipe", "pipe"],
+    });
+    const stdout: Array<Buffer> = [];
+    const stderr: Array<Buffer> = [];
+    child.stdout.on("data", (chunk: Buffer) => {
+      stdout.push(chunk);
+    });
+    child.stderr.on("data", (chunk: Buffer) => {
+      stderr.push(chunk);
+    });
+    child.once("error", (error) => {
+      reject(
+        new Error(
+          [`${operation} failed.`, details].filter(Boolean).join("\n"),
+          {
+            cause: error,
+          },
+        ),
+      );
+    });
+    child.once("close", (code, signal) => {
+      if (code === 0) {
+        resolve();
+        return;
+      }
+      reject(
+        new Error(
+          [
+            `${operation} failed${signal === null ? ` with exit code ${String(code)}` : ` from signal ${signal}`}.`,
+            details,
+            Buffer.concat(stdout).toString("utf8"),
+            Buffer.concat(stderr).toString("utf8"),
+          ]
+            .filter(Boolean)
+            .join("\n"),
+        ),
+      );
+    });
+  });

package/src/index.ts

@@ -0,0 +1,34 @@
+/**
+ * Vitest assertions for Evolu.
+ *
+ * @module
+ */
+
+import type { Err, Ok, Result } from "@evolu/common";
+import { expect } from "vitest";
+
+/**
+ * Expects an {@link Ok} Result whose value matches the expected value using
+ * Vitest's `toEqual`, and narrows the Result.
+ *
+ * Use `toBe` on the narrowed value when reference identity also matters.
+ */
+export const expectOk: <R extends Result<unknown, unknown>>(
+  result: R,
+  expectedValue: unknown,
+) => asserts result is Extract<R, Ok<unknown>> = (result, expectedValue) => {
+  expect(result).toEqual({ ok: true, value: expectedValue });
+};
+
+/**
+ * Expects an {@link Err} Result whose error matches the expected error using
+ * Vitest's `toEqual`, and narrows the Result.
+ *
+ * Use `toBe` on the narrowed error when reference identity also matters.
+ */
+export const expectErr: <R extends Result<unknown, unknown>>(
+  result: R,
+  expectedError: unknown,
+) => asserts result is Extract<R, Err<unknown>> = (result, expectedError) => {
+  expect(result).toEqual({ ok: false, error: expectedError });
+};