@useblacksmith/vitest 0.0.0-stage → 0.2.1

package/dist/affected.js

@@ -0,0 +1,570 @@
+import { createHash } from 'node:crypto';
+import { existsSync } from 'node:fs';
+import { mkdir, mkdtemp, readFile, rename, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+import picomatch from 'picomatch';
+import { BloomFilter } from './bloom.js';
+import { cacheKey, ENV_CACHE_URL, restoreBundle, saveBundle } from './cache.js';
+import { anchorTree, diffTrees, headSha, knownPaths, lockfilePaths, repoRoot, } from './git.js';
+import { shardOwner } from './sequencer.js';
+export const SNAPSHOT_FILE = 'blacksmith.json';
+// Bumped whenever the snapshot's shape changes or the records an anchor
+// vouches for gain a kind of dependency, so an older snapshot is not trusted.
+const SNAPSHOT_VERSION = 4;
+export function compileDependencies(dependencies) {
+    return Object.entries(dependencies ?? {}).map(([tests, deps]) => ({
+        tests: picomatch(tests, { dot: true }),
+        deps: picomatch(typeof deps === 'string' ? deps : [...deps], { dot: true }),
+    }));
+}
+/** `file` relative to the config root with `/` separators, the form the `dependencies` globs match. */
+function rootRelative(root, file) {
+    return path.relative(root, file).split(path.sep).join('/');
+}
+/** `file` relative to the repository with `/` separators (git's form, whatever path.sep is); `tree` and `tests` are keyed by it. */
+function repoRelative(repo, file) {
+    return path.relative(repo, file).split(path.sep).join('/');
+}
+const LOCKFILES = new Set([
+    'package-lock.json',
+    'pnpm-lock.yaml',
+    'yarn.lock',
+    'bun.lock',
+    'bun.lockb',
+]);
+function projectNames(vitest) {
+    return vitest.projects.map((project) => project.name).sort();
+}
+/**
+ * `blacksmith.json`, or `blacksmith.<hash>.json` when `--project` narrowed the
+ * run: invocations covering different project sets keep separate anchors.
+ */
+export function snapshotPath(vitest, dir) {
+    const filtered = vitest.config.project.length > 0;
+    const name = filtered
+        ? SNAPSHOT_FILE.replace('.json', `.${createHash('sha1').update(projectNames(vitest).join('\n')).digest('hex').slice(0, 12)}.json`)
+        : SNAPSHOT_FILE;
+    return path.join(dir, name);
+}
+/** Vitest's `dependencies.json`, or `null` before the first recorded run. */
+async function readRecords(vitest, dir) {
+    const file = path.join(dir, 'dependencies.json');
+    try {
+        return JSON.parse(await readFile(file, 'utf8'));
+    }
+    catch {
+        return null;
+    }
+}
+/** Recorded test file → the files it was seen importing, both absolute; empty when vitest has no records yet. */
+async function recordedDependencies(vitest, dir) {
+    const records = await readRecords(vitest, dir);
+    if (!records)
+        return new Map();
+    const result = new Map();
+    for (const project of Object.values(records.projects ?? {})) {
+        // Vitest records every project's paths relative to the root config's root.
+        const root = vitest.config.root;
+        for (const [test, record] of Object.entries(project.files)) {
+            // A test file two projects share keeps the dependencies of both.
+            const file = path.resolve(root, test);
+            const deps = result.get(file) ?? new Set();
+            for (const index of record.deps) {
+                deps.add(path.resolve(root, project.modules[index] ?? ''));
+            }
+            result.set(file, deps);
+        }
+    }
+    return result;
+}
+/**
+ * Repo-relative paths the anchor covers: every module vitest's records name
+ * (imports, fs reads, config and globalSetup files), every recorded test
+ * file, lockfiles, and every file a `dependencies` rule names (nothing reads
+ * those, so the anchor is the only way a change to them is seen).
+ */
+async function anchoredPaths(vitest, repo, dir, rules) {
+    const paths = new Set(await lockfilePaths(repo, LOCKFILES));
+    if (rules.length > 0) {
+        for (const file of await knownPaths(repo)) {
+            const fromRoot = rootRelative(vitest.config.root, path.join(repo, file));
+            if (rules.some((rule) => rule.deps(fromRoot)))
+                paths.add(file);
+        }
+    }
+    const records = await readRecords(vitest, dir);
+    for (const project of Object.values(records?.projects ?? {})) {
+        // Vitest records every project's paths relative to the root config's root.
+        const root = vitest.config.root;
+        for (const module of project.modules) {
+            paths.add(repoRelative(repo, path.resolve(root, module)));
+        }
+        for (const test of Object.keys(project.files)) {
+            paths.add(repoRelative(repo, path.resolve(root, test)));
+        }
+    }
+    return [...paths];
+}
+function sameShard(a, b) {
+    if (a === null)
+        return b === undefined;
+    return b !== undefined && a.index === b.index && a.count === b.count;
+}
+function describeShard(shard) {
+    return shard ? `shard ${shard.index}/${shard.count}` : 'unsharded run';
+}
+function isShard(value) {
+    if (value === null)
+        return true;
+    if (typeof value !== 'object')
+        return false;
+    const { index, count } = value;
+    return typeof index === 'number' && typeof count === 'number';
+}
+function isTree(value) {
+    return (typeof value === 'object' &&
+        value !== null &&
+        Object.values(value).every((sha) => typeof sha === 'string'));
+}
+/** `null` for a missing, truncated or otherwise unusable file, which callers treat as "run everything". */
+async function readSnapshot(file) {
+    let parsed;
+    try {
+        parsed = JSON.parse(await readFile(file, 'utf8'));
+    }
+    catch {
+        return null;
+    }
+    if (typeof parsed !== 'object' || parsed === null)
+        return null;
+    const { version, head, shard, projects, tree, tests } = parsed;
+    const covered = BloomFilter.parse(tests);
+    if (version !== SNAPSHOT_VERSION ||
+        typeof head !== 'string' ||
+        !isShard(shard) ||
+        !Array.isArray(projects) ||
+        !projects.every((name) => typeof name === 'string') ||
+        !isTree(tree) ||
+        covered === null) {
+        return null;
+    }
+    return {
+        version: SNAPSHOT_VERSION,
+        head,
+        shard,
+        projects: projects,
+        tree,
+        tests: covered,
+    };
+}
+/**
+ * Decides which files changed since the snapshot was written by diffing the
+ * stored anchor against the recorded paths as they are now. Falls back
+ * to "everything" whenever the snapshot cannot vouch for this shard.
+ */
+const PROVIDER_BRAND = Symbol.for('blacksmith.treeSnapshotProvider');
+/** True for a `TreeSnapshotProvider` from any copy of this module (a project with its own root re-evaluates the config file, so it gets its own copy). */
+export function isTreeSnapshotProvider(value) {
+    return typeof value === 'object' && value !== null && PROVIDER_BRAND in value;
+}
+/** The provider vitest loaded: the root config's `experimental.vcsProvider`, when it is ours. */
+export function configuredProvider(vitest) {
+    const configured = vitest.config.experimental.vcsProvider;
+    return isTreeSnapshotProvider(configured) ? configured : null;
+}
+export class TreeSnapshotProvider {
+    [PROVIDER_BRAND] = true;
+    vitest;
+    /**
+     * Recorded test files none of whose recorded imports changed: the provider
+     * vouches that they need not run, whatever filters the run also applies.
+     */
+    deselected = new Set();
+    /** The plugin's `dependencies` option, compiled. */
+    dependencies = [];
+    async findChangedFiles(options) {
+        this.deselected = new Set();
+        const dependencies = await options.resolver.getDependencies();
+        const cacheDir = this.vitest.vite.config.cacheDir;
+        const selected = await this.select(options, dependencies, cacheDir, (message) => this.vitest.logger.log(`[blacksmith] ${message}`));
+        if (selected === null) {
+            return dependencies.map((dependency) => dependency.file);
+        }
+        const changed = new Set(selected);
+        for (const [test, deps] of await recordedDependencies(this.vitest, cacheDir)) {
+            if (changed.has(test))
+                continue;
+            if ([...deps].some((dep) => changed.has(dep)))
+                continue;
+            this.deselected.add(test);
+        }
+        return selected;
+    }
+    /**
+     * Changed files to hand vitest, or `null` when every test of the shard has
+     * to run; `dir` is where the record and anchor live (vitest's `cacheDir`,
+     * or a shadow run's copy of it).
+     */
+    async select({ root }, dependencies, dir, log) {
+        const shard = this.vitest.config.shard;
+        const snapshot = await readSnapshot(snapshotPath(this.vitest, dir));
+        if (!snapshot) {
+            log(`no dependency snapshot, running every test of the ${describeShard(shard)}`);
+            return null;
+        }
+        if (!sameShard(snapshot.shard, shard)) {
+            log(`dependency snapshot is for ${describeShard(snapshot.shard)}, running every test of the ${describeShard(shard)}`);
+            return null;
+        }
+        const projects = projectNames(this.vitest);
+        if (snapshot.projects.join('\n') !== projects.join('\n')) {
+            log(`dependency snapshot covers projects [${snapshot.projects.join(', ')}], this run covers [${projects.join(', ')}], running every test of the ${describeShard(shard)}`);
+            return null;
+        }
+        const repo = await repoRoot(root);
+        const tree = await anchorTree(repo, await anchoredPaths(this.vitest, repo, dir, this.dependencies));
+        const changedPaths = diffTrees(snapshot.tree, tree);
+        const owns = await shardOwner(this.vitest);
+        // Entries without a record are test files vitest has never seen; a test
+        // the snapshot does not vouch for has no trustworthy record either,
+        // whatever vitest's dependencies.json holds about it.
+        const uncovered = new Set(dependencies
+            .filter((dependency) => dependency.recordedAt === undefined && owns(dependency.file))
+            .map((dependency) => dependency.file));
+        for (const specification of await this.vitest.globTestSpecifications()) {
+            const file = specification.moduleId;
+            if (owns(file) && !snapshot.tests.has(repoRelative(repo, file))) {
+                uncovered.add(file);
+            }
+        }
+        const changed = new Set(uncovered);
+        for (const relative of changedPaths) {
+            if (LOCKFILES.has(path.basename(relative))) {
+                log(`${relative} changed, running every test of the ${describeShard(shard)}`);
+                return null;
+            }
+            changed.add(path.join(repo, relative));
+        }
+        const triggered = this.dependencies.filter((rule) => changedPaths.some((relative) => rule.deps(rootRelative(root, path.join(repo, relative)))));
+        let mapped = 0;
+        if (triggered.length > 0) {
+            for (const dependency of dependencies) {
+                if (changed.has(dependency.file))
+                    continue;
+                if (!owns(dependency.file))
+                    continue;
+                const fromRoot = rootRelative(root, dependency.file);
+                if (triggered.some((rule) => rule.tests(fromRoot))) {
+                    changed.add(dependency.file);
+                    mapped++;
+                }
+            }
+        }
+        log(`${changedPaths.length} files changed since ${snapshot.head.slice(0, 12)}, ${uncovered.size} test files not covered by it${mapped > 0 ? `, ${mapped} test files via dependencies` : ''}`);
+        return [...changed];
+    }
+}
+function isPartialSpecification(specification) {
+    return (specification.testLines !== undefined ||
+        specification.testIds !== undefined ||
+        specification.testNames !== undefined ||
+        specification.testNamePattern !== undefined ||
+        specification.testTagsFilter !== undefined);
+}
+/**
+ * Shadow mode: fetches the shard's last record and anchor into a temporary
+ * directory while the full run executes, and works out what the affected
+ * selection would have run, without touching vitest's `cacheDir` or the run.
+ */
+export class ShadowAnalysis {
+    vitest;
+    dependencies;
+    result;
+    constructor(vitest, dependencies) {
+        this.vitest = vitest;
+        this.dependencies = dependencies;
+        this.result = this.run().catch((error) => ({
+            wouldRun: null,
+            changed: 0,
+            head: null,
+            key: null,
+            reason: error instanceof Error ? error.message : String(error),
+        }));
+    }
+    async run() {
+        const none = (reason) => ({
+            wouldRun: null,
+            changed: 0,
+            head: null,
+            key: null,
+            reason,
+        });
+        const base = process.env[ENV_CACHE_URL];
+        if (!base)
+            return none(`${ENV_CACHE_URL} is not set`);
+        const vitest = this.vitest;
+        const repo = await repoRoot(vitest.config.root);
+        const key = cacheKey({
+            snapshotVersion: SNAPSHOT_VERSION,
+            projects: projectNames(vitest),
+            shard: vitest.config.shard ?? null,
+            head: process.env.GITHUB_SHA || (await headSha(repo)),
+        });
+        const dir = await mkdtemp(path.join(tmpdir(), 'blacksmith-shadow-'));
+        const outcome = await restoreBundle(base, dir, key);
+        if (!outcome.restored)
+            return none(outcome.reason);
+        const snapshot = await readSnapshot(snapshotPath(vitest, dir));
+        const recorded = await recordedDependencies(vitest, dir);
+        const records = await readRecords(vitest, dir);
+        const { root } = vitest.config;
+        const owns = await shardOwner(vitest);
+        const specifications = (await vitest.globTestSpecifications()).filter((specification) => owns(specification.moduleId));
+        const owned = [
+            ...new Set(specifications.map((specification) => specification.moduleId)),
+        ];
+        const provider = new TreeSnapshotProvider();
+        provider.vitest = vitest;
+        provider.dependencies = this.dependencies;
+        let changed = 0;
+        let lastMessage = '';
+        const selected = await provider.select({ root }, owned.map((file) => ({
+            file,
+            recordedAt: recorded.has(file) ? 1 : undefined,
+        })), dir, (message) => {
+            lastMessage = message;
+            const match = /^(\d+) files changed/.exec(message);
+            if (match)
+                changed = Number(match[1]);
+        });
+        const head = snapshot?.head ?? null;
+        const all = (reason) => ({
+            wouldRun: 'all',
+            changed,
+            head,
+            key: outcome.key,
+            reason,
+        });
+        if (selected === null)
+            return all(lastMessage);
+        const changedFiles = new Set(selected);
+        const dependsOnChange = (files) => files?.some((file) => changedFiles.has(file)) ?? false;
+        // What vitest does with the changed files: `forceRerunTriggers` and the
+        // root config rerun everything; a project's config, env files, missing
+        // record or globalSetup rerun the project; otherwise a test reruns when
+        // it has no record or one of its recorded dependencies changed.
+        const triggers = vitest.config.forceRerunTriggers;
+        if (selected.some((file) => picomatch.isMatch(file, triggers, { dot: true }))) {
+            return all('a changed file matches forceRerunTriggers');
+        }
+        if (dependsOnChange(vitest.vite.config.configFileDependencies)) {
+            return all('a dependency of the config changed');
+        }
+        const wouldRun = new Set();
+        for (const project of vitest.projects) {
+            const specs = specifications.filter((specification) => specification.project === project);
+            if (specs.length === 0)
+                continue;
+            const record = records?.projects[project.name];
+            // Record paths are relative to the root config's root, whatever the project's.
+            const projectRoot = vitest.config.root;
+            const modules = (indexes) => indexes?.map((index) => path.resolve(projectRoot, record?.modules[index] ?? ''));
+            if (!record ||
+                dependsOnChange(project.vite.config.configFileDependencies) ||
+                dependsOnChange(envFiles(project)) ||
+                (project.config.globalSetup.length > 0 &&
+                    (!record.globalSetup ||
+                        dependsOnChange(modules(record.globalSetup.deps))))) {
+                for (const spec of specs)
+                    wouldRun.add(spec.moduleId);
+                continue;
+            }
+            for (const spec of specs) {
+                const test = record.files[path.relative(projectRoot, spec.moduleId).split(path.sep).join('/')];
+                if (!test ||
+                    changedFiles.has(spec.moduleId) ||
+                    dependsOnChange(modules(test.deps))) {
+                    wouldRun.add(spec.moduleId);
+                }
+            }
+        }
+        return { wouldRun, changed, head, key: outcome.key, reason: null };
+    }
+}
+/** The env files vitest reloads a project for, as `getEnvFiles` lists them. */
+function envFiles(project) {
+    const { envDir, mode } = project.vite.config;
+    if (typeof envDir !== 'string')
+        return [];
+    return ['.env', '.env.local', `.env.${mode}`, `.env.${mode}.local`].map((file) => path.resolve(envDir, file));
+}
+/**
+ * Writes the snapshot once a passing run has covered every test the shard owns,
+ * so the next `--changed` run can trust the dependency records for all of them.
+ */
+const RECORDER_BRAND = Symbol.for('blacksmith.snapshotRecorder');
+/** True for a `SnapshotRecorder` from any copy of this module (a project's config bundles its own). */
+export function isSnapshotRecorder(reporter) {
+    return (typeof reporter === 'object' &&
+        reporter !== null &&
+        RECORDER_BRAND in reporter);
+}
+export class SnapshotRecorder {
+    provider;
+    options;
+    [RECORDER_BRAND] = true;
+    vitest;
+    started = new Set();
+    partial = false;
+    constructor(provider, options = {}) {
+        this.provider = provider;
+        this.options = options;
+    }
+    /** Shadow mode's verdict for this run, logged once the run has finished. */
+    async reportShadow(modules) {
+        const shadow = this.options.shadow;
+        if (!shadow)
+            return;
+        const log = (message) => this.vitest.logger.log(`[blacksmith] shadow: ${message}`);
+        const result = await shadow.result;
+        if (result.wouldRun === null) {
+            log(`nothing to compare against (${result.reason ?? 'unknown'})`);
+            return;
+        }
+        const ran = this.started;
+        const would = result.wouldRun === 'all'
+            ? ran
+            : new Set([...result.wouldRun].filter((file) => ran.has(file)));
+        const since = result.head ? ` since ${result.head.slice(0, 12)}` : '';
+        const why = result.wouldRun === 'all'
+            ? `everything: ${result.reason}`
+            : `${result.changed} files changed${since}`;
+        log(`would have run ${would.size} of ${ran.size} test files (${why}, from ${result.key ?? 'the cache'})`);
+        const failed = modules
+            .filter((module) => module.state() === 'failed' || module.errors().length > 0)
+            .map((module) => module.moduleId);
+        if (failed.length === 0)
+            return;
+        const outside = failed.filter((file) => !would.has(file));
+        if (outside.length === 0) {
+            log(`all ${failed.length} failed test files were in the selection`);
+            return;
+        }
+        const root = this.vitest.config.root;
+        log(`${outside.length} failed test files outside the selection: ${outside
+            .map((file) => path.relative(root, file))
+            .join(', ')}`);
+    }
+    /** The provider vitest is using: the root config's, which may come from another copy of this module. */
+    activeProvider() {
+        return configuredProvider(this.vitest) ?? this.provider;
+    }
+    onInit(vitest) {
+        this.vitest = vitest;
+    }
+    onTestRunStart(specifications) {
+        this.started = new Set(specifications.map((specification) => specification.moduleId));
+        this.partial = specifications.some(isPartialSpecification);
+    }
+    async onTestRunEnd(modules, _errors, reason) {
+        await this.reportShadow(modules);
+        if (reason !== 'passed')
+            return;
+        const covered = await this.coveredTests();
+        if (covered === null)
+            return;
+        const cacheDir = this.vitest.vite.config.cacheDir;
+        const { root, shard } = this.vitest.config;
+        const repo = await repoRoot(root);
+        const snapshot = {
+            version: SNAPSHOT_VERSION,
+            head: await headSha(repo),
+            shard: shard ?? null,
+            projects: projectNames(this.vitest),
+            tree: await anchorTree(repo, await anchoredPaths(this.vitest, repo, cacheDir, this.provider.dependencies)),
+            tests: BloomFilter.from(covered.map((file) => repoRelative(repo, file))),
+        };
+        const file = snapshotPath(this.vitest, cacheDir);
+        await mkdir(path.dirname(file), { recursive: true });
+        const tmp = `${file}.${process.pid}.${Date.now()}.tmp`;
+        await writeFile(tmp, JSON.stringify(snapshot));
+        await rename(tmp, file);
+        await this.publish(snapshot);
+    }
+    /** Puts the record and this anchor in the Actions cache when a run can reach it. */
+    async publish(snapshot) {
+        const base = process.env[ENV_CACHE_URL];
+        if (!base)
+            return;
+        const key = cacheKey({
+            snapshotVersion: snapshot.version,
+            projects: snapshot.projects,
+            shard: snapshot.shard,
+            head: snapshot.head,
+        });
+        try {
+            const outcome = await saveBundle(base, this.vitest.vite.config.cacheDir, key);
+            this.vitest.logger.log(outcome.saved
+                ? `[blacksmith] saved dependency cache ${key.key} (${outcome.bytes} bytes)`
+                : `[blacksmith] dependency cache not saved: ${outcome.reason}`);
+        }
+        catch (error) {
+            this.vitest.logger.log(`[blacksmith] dependency cache not saved: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    /** The tests this shard owns, when every one of them ran or was deselected by our own provider; `null` when the run covered less. */
+    async coveredTests() {
+        if (this.partial || this.vitest.getGlobalTestNamePattern() !== undefined) {
+            return null;
+        }
+        const owns = await shardOwner(this.vitest);
+        const { deselected } = this.activeProvider();
+        const owned = [
+            ...new Set((await this.vitest.globTestSpecifications())
+                .map((specification) => specification.moduleId)
+                .filter(owns)),
+        ];
+        return owned.every((file) => this.started.has(file) || deselected.has(file))
+            ? owned
+            : null;
+    }
+}
+/**
+ * Before selection: when the Actions cache is reachable and Vitest's cache
+ * directory (`cacheDir`, wherever the config puts it) holds no record yet,
+ * pulls the newest record for this shard and project set into it. The
+ * directory itself may exist: every `vitest run` on one config shares it
+ * (its hash is the root `test.name`, not the `--project` filter).
+ */
+export async function restoreDependencyCache(vitest) {
+    const base = process.env[ENV_CACHE_URL];
+    if (!base) {
+        if (process.env.TURBO_HASH)
+            vitest.logger.warn(`[blacksmith] running under turbo, which hides ${ENV_CACHE_URL} in strict env mode; add it to passThroughEnv to use the dependency cache`);
+        return;
+    }
+    // Only this run's own anchor blocks a restore: every `vitest run` on one config
+    // shares `cacheDir`, so another project set's anchor may already be there.
+    const anchor = snapshotPath(vitest, vitest.vite.config.cacheDir);
+    if (existsSync(anchor)) {
+        vitest.logger.warn(`[blacksmith] ${path.relative(vitest.config.root, anchor)} already exists, not restoring the dependency cache over it`);
+        return;
+    }
+    const repo = await repoRoot(vitest.config.root);
+    const key = cacheKey({
+        snapshotVersion: SNAPSHOT_VERSION,
+        projects: projectNames(vitest),
+        shard: vitest.config.shard ?? null,
+        head: process.env.GITHUB_SHA || (await headSha(repo)),
+    });
+    try {
+        const outcome = await restoreBundle(base, vitest.vite.config.cacheDir, key);
+        vitest.logger.log(outcome.restored
+            ? `[blacksmith] restored dependency cache ${outcome.key}`
+            : `[blacksmith] no dependency cache: ${outcome.reason}`);
+    }
+    catch (error) {
+        vitest.logger.log(`[blacksmith] dependency cache not restored: ${error instanceof Error ? error.message : String(error)}`);
+    }
+}

package/dist/bloom.d.ts

@@ -0,0 +1,23 @@
+/** Serialized form stored in the snapshot: `m` bits, `k` hashes, bits base64-encoded. */
+export interface BloomJSON {
+    m: number;
+    k: number;
+    bits: string;
+}
+/**
+ * Set membership for the test files a snapshot vouches for. A false positive
+ * would skip a test the shard never covered, so the default sizing keeps the
+ * rate at one in a billion: ~43 bits per entry.
+ */
+export declare class BloomFilter {
+    readonly m: number;
+    readonly k: number;
+    private readonly bits;
+    private constructor();
+    static from(keys: Iterable<string>, falsePositiveRate?: number): BloomFilter;
+    static parse(value: unknown): BloomFilter | null;
+    has(key: string): boolean;
+    toJSON(): BloomJSON;
+    /** Kirsch–Mitzenmacher double hashing over the two 64-bit halves of sha256. */
+    private indexes;
+}

package/dist/bloom.js

@@ -0,0 +1,70 @@
+import { createHash } from 'node:crypto';
+/**
+ * Set membership for the test files a snapshot vouches for. A false positive
+ * would skip a test the shard never covered, so the default sizing keeps the
+ * rate at one in a billion: ~43 bits per entry.
+ */
+export class BloomFilter {
+    m;
+    k;
+    bits;
+    constructor(m, k, bits) {
+        this.m = m;
+        this.k = k;
+        this.bits = bits;
+    }
+    static from(keys, falsePositiveRate = 1e-9) {
+        const entries = [...keys];
+        const n = Math.max(entries.length, 1);
+        const m = Math.ceil((-n * Math.log(falsePositiveRate)) / Math.LN2 ** 2);
+        const k = Math.max(1, Math.round((m / n) * Math.LN2));
+        const filter = new BloomFilter(m, k, new Uint8Array(Math.ceil(m / 8)));
+        for (const key of entries) {
+            for (const index of filter.indexes(key)) {
+                const byte = index >> 3;
+                filter.bits[byte] = (filter.bits[byte] ?? 0) | (1 << (index & 7));
+            }
+        }
+        return filter;
+    }
+    static parse(value) {
+        if (typeof value !== 'object' || value === null)
+            return null;
+        const { m, k, bits } = value;
+        if (!Number.isInteger(m) ||
+            !Number.isInteger(k) ||
+            m < 1 ||
+            k < 1 ||
+            typeof bits !== 'string') {
+            return null;
+        }
+        const bytes = Buffer.from(bits, 'base64');
+        if (bytes.length !== Math.ceil(m / 8))
+            return null;
+        return new BloomFilter(m, k, new Uint8Array(bytes));
+    }
+    has(key) {
+        for (const index of this.indexes(key)) {
+            if (((this.bits[index >> 3] ?? 0) & (1 << (index & 7))) === 0)
+                return false;
+        }
+        return true;
+    }
+    toJSON() {
+        return {
+            m: this.m,
+            k: this.k,
+            bits: Buffer.from(this.bits).toString('base64'),
+        };
+    }
+    /** Kirsch–Mitzenmacher double hashing over the two 64-bit halves of sha256. */
+    *indexes(key) {
+        const digest = createHash('sha256').update(key).digest();
+        const h1 = digest.readBigUInt64BE(0);
+        const h2 = digest.readBigUInt64BE(8) | 1n;
+        const m = BigInt(this.m);
+        for (let i = 0n; i < BigInt(this.k); i++) {
+            yield Number((h1 + i * h2) % m);
+        }
+    }
+}