@itmetsam/samurai-framework 0.21.4 → 0.22.0

package/dist/runner/fixture-defs.js

@@ -0,0 +1,104 @@
+import { requestedBy } from "./fixture-args.js";
+/** The fixtures the runner builds for every test: a custom fixture of the same name overrides it */
+export const BUILT_IN_FIXTURES = new Set([
+    "page",
+    "browser",
+    "browserName",
+    "workerIndex",
+    "env",
+    "secrets",
+    "inputs",
+    "outputs",
+    "context",
+    "baseURL",
+    "request",
+    "testInfo",
+    "isMobile",
+    "hasTouch",
+]);
+const OPTION_KEYS = new Set(["auto", "scope"]);
+function isPlainObject(value) {
+    if (typeof value !== "object" || value === null)
+        return false;
+    const proto = Object.getPrototypeOf(value);
+    return proto === Object.prototype || proto === null;
+}
+/** `[fixture, options]` is always a pair with options; an array value goes in a function */
+function checkedOptions(name, options) {
+    for (const key of Object.keys(options))
+        if (!OPTION_KEYS.has(key))
+            throw new Error(`extend(): fixture "${name}" has an unknown option "${key}"`);
+    if (options.auto !== undefined && typeof options.auto !== "boolean")
+        throw new Error(`extend(): fixture "${name}": auto must be true or false`);
+    if (options.scope === "worker")
+        throw new Error(`extend(): fixture "${name}" has scope "worker", which is not supported; fixtures live as long as one test ({ scope: "test" })`);
+    if (options.scope !== undefined && options.scope !== "test")
+        throw new Error(`extend(): fixture "${name}": scope must be "test"`);
+    return { auto: options.auto === true };
+}
+function definitionOf(name, raw) {
+    const [fixture, options] = Array.isArray(raw) && raw.length === 2 && isPlainObject(raw[1])
+        ? [raw[0], checkedOptions(name, raw[1])]
+        : [raw, { auto: false }];
+    if (typeof fixture !== "function")
+        return { name, auto: options.auto, deps: [], value: fixture };
+    const requested = requestedBy(fixture);
+    if (requested.kind === "opaque" || requested.rest)
+        throw new Error(`extend(): fixture "${name}" must destructure the fixtures it uses in its first argument, as ({ page }, use) or ({}, use)`);
+    return {
+        name,
+        auto: options.auto,
+        deps: requested.names,
+        setup: fixture,
+    };
+}
+/** Where a dependency of `name` (at definition `level`) comes from: another definition, or the built-in fixture */
+export function dependencyOf(layers, name, level, dep) {
+    if (dep === name)
+        return level > 0
+            ? { name, level: level - 1 }
+            : BUILT_IN_FIXTURES.has(dep)
+                ? "built-in"
+                : undefined;
+    const defs = layers.get(dep);
+    if (defs)
+        return { name: dep, level: defs.length - 1 };
+    return BUILT_IN_FIXTURES.has(dep) ? "built-in" : undefined;
+}
+/** Throws for a dependency nobody defines and for a cycle (`a` needs `b` needs `a`) */
+function validate(layers) {
+    const done = new Set();
+    const walk = (name, level, path) => {
+        const key = `${name}#${level}`;
+        if (done.has(key))
+            return;
+        if (path.includes(key)) {
+            const loop = [...path.slice(path.indexOf(key)), key];
+            throw new Error(`extend(): fixtures depend on each other in a circle: ${loop.map((k) => k.split("#")[0]).join(" -> ")}`);
+        }
+        const def = layers.get(name)?.[level];
+        if (!def)
+            return;
+        for (const dep of def.deps) {
+            const target = dependencyOf(layers, name, level, dep);
+            if (target === undefined)
+                throw new Error(`extend(): fixture "${name}" depends on unknown fixture "${dep}"`);
+            if (target !== "built-in")
+                walk(target.name, target.level, [...path, key]);
+        }
+        done.add(key);
+    };
+    for (const [name, defs] of layers)
+        for (let level = 0; level < defs.length; level++)
+            walk(name, level, []);
+}
+/** The fixtures after `test.extend(definitions)` on a test that has `base`; throws `extend(): ...` for a definition that cannot work */
+export function extendLayers(base, definitions) {
+    if (!isPlainObject(definitions))
+        throw new Error("extend(): needs an object of fixtures");
+    const layers = new Map(base);
+    for (const [name, raw] of Object.entries(definitions))
+        layers.set(name, [...(layers.get(name) ?? []), definitionOf(name, raw)]);
+    validate(layers);
+    return layers;
+}

package/dist/runner/fixture-scope.d.ts

@@ -0,0 +1,33 @@
+import type { TestFixtures } from "../types/test.js";
+import { type FixtureLayers } from "./fixture-defs.js";
+/** A custom fixture whose setup threw or never called `use` */
+export declare class FixtureSetupError extends Error {
+    constructor(name: string, cause: unknown);
+}
+/**
+ * The custom fixtures of one test run. Fixtures are set up when a test or hook asks for them (by destructuring
+ * them), their dependencies first, and torn down in the opposite order. The hooks and the body of a test share
+ * one scope, so they see the same instances.
+ */
+export declare class FixtureScope {
+    private readonly layers;
+    private readonly base;
+    /** The built-in fixtures, with each custom fixture added (replacing a built-in of that name) once it is set up */
+    readonly fixtures: TestFixtures;
+    private readonly values;
+    private readonly pending;
+    private readonly started;
+    private closed;
+    constructor(layers: FixtureLayers, base: TestFixtures);
+    /** Sets up the fixtures marked `auto` */
+    prepareAuto(): Promise<void>;
+    /** Sets up the custom fixtures `fn` destructures from its first parameter */
+    prepare(fn: (...args: never[]) => unknown): Promise<void>;
+    /**
+     * Finishes the fixtures that were set up, last first, each within `limitMs`. Returns the first error (a
+     * fixture's cleanup threw or ran out of time); the others still run.
+     */
+    teardown(limitMs: number): Promise<Error | undefined>;
+    private ensure;
+    private setUp;
+}

package/dist/runner/fixture-scope.js

@@ -0,0 +1,156 @@
+import { requestedBy } from "./fixture-args.js";
+import { BUILT_IN_FIXTURES, dependencyOf, } from "./fixture-defs.js";
+/** A custom fixture whose setup threw or never called `use` */
+export class FixtureSetupError extends Error {
+    constructor(name, cause) {
+        super(`fixture "${name}" setup failed: ${messageOf(cause)}`);
+        this.name = "FixtureSetupError";
+        if (cause instanceof Error && cause.stack)
+            this.stack = cause.stack;
+    }
+}
+const messageOf = (err) => err instanceof Error ? err.message : String(err);
+/** Runs `setup` until it calls `use`; resolves with the value and the means to finish it */
+function startSetup(def, args) {
+    return new Promise((resolve, reject) => {
+        let release = () => { };
+        const released = new Promise((r) => (release = r));
+        let used = false;
+        let running;
+        const done = () => running ?? Promise.resolve();
+        const use = async (value) => {
+            if (used)
+                throw new Error("use() was called twice");
+            used = true;
+            resolve({ value, release, done });
+            await released;
+        };
+        running = (async () => def.setup?.(args, use))();
+        running.then(() => {
+            if (!used)
+                reject(new Error("the setup never called use()"));
+        }, (err) => {
+            if (!used)
+                reject(err);
+        });
+        // A failure after use() is read by teardown; this keeps it from being reported as unhandled meanwhile
+        running.catch(() => { });
+    });
+}
+/**
+ * The custom fixtures of one test run. Fixtures are set up when a test or hook asks for them (by destructuring
+ * them), their dependencies first, and torn down in the opposite order. The hooks and the body of a test share
+ * one scope, so they see the same instances.
+ */
+export class FixtureScope {
+    constructor(layers, base) {
+        this.layers = layers;
+        this.base = base;
+        this.values = new Map();
+        this.pending = new Map();
+        this.started = [];
+        this.closed = false;
+        const own = Object.getOwnPropertyDescriptors(base);
+        for (const descriptor of Object.values(own))
+            descriptor.configurable = true;
+        this.fixtures = Object.defineProperties({}, own);
+    }
+    /** Sets up the fixtures marked `auto` */
+    async prepareAuto() {
+        for (const [name, defs] of this.layers)
+            if (defs[defs.length - 1]?.auto)
+                await this.ensure(name, defs.length - 1);
+    }
+    /** Sets up the custom fixtures `fn` destructures from its first parameter */
+    async prepare(fn) {
+        const requested = requestedBy(fn);
+        if (requested.kind === "opaque")
+            return;
+        const names = requested.rest ? [...this.layers.keys()] : requested.names;
+        for (const name of names) {
+            const defs = this.layers.get(name);
+            if (defs)
+                await this.ensure(name, defs.length - 1);
+            else if (!BUILT_IN_FIXTURES.has(name))
+                throw new Error(`extend(): unknown fixture "${name}"`);
+        }
+    }
+    /**
+     * Finishes the fixtures that were set up, last first, each within `limitMs`. Returns the first error (a
+     * fixture's cleanup threw or ran out of time); the others still run.
+     */
+    async teardown(limitMs) {
+        this.closed = true;
+        let first;
+        for (let one = this.started.pop(); one; one = this.started.pop()) {
+            one.release();
+            let timer;
+            try {
+                await Promise.race([
+                    one.done(),
+                    new Promise((_, reject) => {
+                        timer = setTimeout(() => reject(new Error(`timed out after ${limitMs / 1000} seconds`)), limitMs);
+                    }),
+                ]);
+            }
+            catch (err) {
+                first ??= new Error(`fixture "${one.name}" teardown failed: ${messageOf(err)}`);
+                if (err instanceof Error && err.stack)
+                    first.stack = err.stack;
+            }
+            finally {
+                clearTimeout(timer);
+            }
+        }
+        return first;
+    }
+    ensure(name, level) {
+        const key = `${name}#${level}`;
+        let promise = this.pending.get(key);
+        if (!promise) {
+            promise = this.setUp(name, level);
+            this.pending.set(key, promise);
+        }
+        return promise;
+    }
+    async setUp(name, level) {
+        const def = this.layers.get(name)?.[level];
+        if (!def)
+            throw new Error(`extend(): unknown fixture "${name}"`);
+        try {
+            const args = {};
+            for (const dep of def.deps) {
+                const target = dependencyOf(this.layers, name, level, dep);
+                if (target === "built-in" || target === undefined)
+                    args[dep] = this.base[dep];
+                else {
+                    await this.ensure(target.name, target.level);
+                    args[dep] = this.values.get(`${target.name}#${target.level}`);
+                }
+            }
+            let value = def.value;
+            if (def.setup) {
+                const started = await startSetup(def, args);
+                if (this.closed) {
+                    started.release();
+                    throw new Error("the test is already over");
+                }
+                value = started.value;
+                this.started.push({ name, ...started });
+            }
+            this.values.set(`${name}#${level}`, value);
+            if (level === (this.layers.get(name)?.length ?? 0) - 1)
+                Object.defineProperty(this.fixtures, name, {
+                    value,
+                    enumerable: true,
+                    configurable: true,
+                    writable: true,
+                });
+        }
+        catch (err) {
+            throw err instanceof FixtureSetupError
+                ? err
+                : new FixtureSetupError(name, err);
+        }
+    }
+}

package/dist/runner/fixtures.d.ts

@@ -0,0 +1,37 @@
+import type { Browser } from "../browser/browser.js";
+import type Page from "../browser/page.js";
+import type { SupportedBrowser } from "../types/browser.js";
+import type { AllHookFixtures, RegisteredTestCase, TestFixtures, TestInfo } from "../types/test.js";
+import type { RequestFixture } from "./request-fixture.js";
+import type { RunnerOptions } from "./options.js";
+import type { PreparedRun } from "./prepare-run.js";
+import type { OutputSink } from "../wait/output-sink.js";
+/** What `beforeAll` and `afterAll` hooks get: no page, only what a run knows */
+export declare function allHookFixtures(run: PreparedRun, browserName: SupportedBrowser, workerIndex?: number): AllHookFixtures;
+/** What one run of a test builds its fixtures from */
+export interface FixtureSources {
+    launched: {
+        page: Page;
+        browser: Browser;
+    };
+    browserName: SupportedBrowser;
+    workerIndex: number;
+    run: PreparedRun;
+    test: RegisteredTestCase;
+    options: RunnerOptions;
+    sink: OutputSink;
+    info: TestInfo;
+    /** The test's `request` fixture, made on first use */
+    request: RequestFixture;
+    /** What the `use` options came to in this browser */
+    device: {
+        isMobile: boolean;
+        hasTouch: boolean;
+    };
+}
+/**
+ * The fixtures a test body and its each-hooks receive. `context`, `baseURL`, `request` and `testInfo` are getters: nothing
+ * is looked up until a test reads one (and `page.context()` throws for a page without one, which only a test
+ * that asks for it should see).
+ */
+export declare function buildTestFixtures(from: FixtureSources): TestFixtures;

package/dist/runner/fixtures.js

@@ -0,0 +1,40 @@
+import { createSecretsFixture } from "../config/secrets.js";
+import { createEnvFixture } from "../config/variables.js";
+import { createInputsFixture, createOutputsFixture } from "./test-io.js";
+/** What `beforeAll` and `afterAll` hooks get: no page, only what a run knows */
+export function allHookFixtures(run, browserName, workerIndex = 0) {
+    const { settings, secrets } = run;
+    return {
+        browserName,
+        workerIndex,
+        env: createEnvFixture(settings.environment, settings.variables),
+        secrets: createSecretsFixture(settings.environment, secrets),
+    };
+}
+/**
+ * The fixtures a test body and its each-hooks receive. `context`, `baseURL`, `request` and `testInfo` are getters: nothing
+ * is looked up until a test reads one (and `page.context()` throws for a page without one, which only a test
+ * that asks for it should see).
+ */
+export function buildTestFixtures(from) {
+    const { launched, browserName, workerIndex, run, test, options, sink, info, device, request, } = from;
+    const { settings, secrets } = run;
+    const fixtures = {
+        page: launched.page,
+        browser: launched.browser,
+        browserName,
+        workerIndex,
+        env: createEnvFixture(settings.environment, settings.variables),
+        secrets: createSecretsFixture(settings.environment, secrets),
+        inputs: createInputsFixture(test.inputs, options.inputs),
+        outputs: createOutputsFixture(sink),
+        isMobile: device.isMobile,
+        hasTouch: device.hasTouch,
+    };
+    return Object.defineProperties(fixtures, {
+        context: { enumerable: true, get: () => launched.page.context() },
+        baseURL: { enumerable: true, get: () => settings.baseURL },
+        request: { enumerable: true, get: () => request.get() },
+        testInfo: { enumerable: true, get: () => info },
+    });
+}

package/dist/runner/global-hooks.d.ts

@@ -0,0 +1,13 @@
+import type { GlobalHookConfig, SamuraiTestConfig } from "../types/config.js";
+/** The run-level hooks of a config: `setup` before the tests, `teardown` after them */
+export interface GlobalHooks {
+    /** Runs `globalSetup`. A throw is `globalSetup(): message` */
+    setup(): Promise<void>;
+    /**
+     * Runs what the setup returned, then `globalTeardown`; both even when the setup failed half way. Resolves with the
+     * first error as `globalTeardown(): message`, else undefined
+     */
+    teardown(): Promise<Error | undefined>;
+}
+/** Binds the config's `globalSetup` / `globalTeardown` to the config they receive and the project folder they load from */
+export declare function globalHooks(config: SamuraiTestConfig, hookConfig: GlobalHookConfig, projectDir: string): GlobalHooks;

package/dist/runner/global-hooks.js

@@ -0,0 +1,66 @@
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+const messageOf = (error) => error instanceof Error ? error.message : String(error);
+/** The function a hook names: given directly, or the default export of the module at `projectDir`/`hook` */
+async function loadHook(name, hook, projectDir) {
+    if (typeof hook === "function")
+        return hook;
+    const file = path.resolve(projectDir, hook);
+    let module;
+    try {
+        module = (await import(pathToFileURL(file).href));
+    }
+    catch (error) {
+        throw new Error(`${name}(): cannot load ${hook}: ${messageOf(error)}`);
+    }
+    if (typeof module.default !== "function")
+        throw new Error(`${name}(): ${hook} must export a function as default`);
+    return module.default;
+}
+/** Binds the config's `globalSetup` / `globalTeardown` to the config they receive and the project folder they load from */
+export function globalHooks(config, hookConfig, projectDir) {
+    const returned = [];
+    return {
+        async setup() {
+            if (config.globalSetup === undefined)
+                return;
+            try {
+                const setup = (await loadHook("globalSetup", config.globalSetup, projectDir));
+                const teardown = await setup(hookConfig);
+                if (typeof teardown === "function")
+                    returned.push(teardown);
+            }
+            catch (error) {
+                const message = messageOf(error);
+                throw new Error(message.startsWith("globalSetup(): ")
+                    ? message
+                    : `globalSetup(): ${message}`);
+            }
+        },
+        async teardown() {
+            let first;
+            const record = (error) => {
+                const message = messageOf(error);
+                first ??= new Error(message.startsWith("globalTeardown(): ")
+                    ? message
+                    : `globalTeardown(): ${message}`);
+            };
+            for (const teardown of returned.splice(0).reverse())
+                try {
+                    await teardown();
+                }
+                catch (error) {
+                    record(error);
+                }
+            if (config.globalTeardown !== undefined)
+                try {
+                    const teardown = (await loadHook("globalTeardown", config.globalTeardown, projectDir));
+                    await teardown(hookConfig);
+                }
+                catch (error) {
+                    record(error);
+                }
+            return first;
+        },
+    };
+}

package/dist/runner/hooks.d.ts

@@ -1,4 +1,5 @@
 import type { Suite, TestFixtures } from "../types/test.js";
+import type { FixtureScope } from "./fixture-scope.js";
 import { type HookKind } from "./suite.js";
 /** A hook threw or ran out of time: the message names the hook (`beforeEach hook failed: <message>`) */
 export declare class HookError extends Error {
@@ -21,4 +22,8 @@ export declare function runHook<F>(kind: HookKind, hook: (fixtures: F) => Promis
  * - What it throws: the `beforeEach` failure, else the body's error, else the first `afterEach` failure. A skip is
  *   overruled by a failing `afterEach`.
  */
-export declare function runWithEachHooks(suite: Suite, fixtures: TestFixtures, signal: AbortSignal, body: () => Promise<void>): Promise<void>;
+export declare function runWithEachHooks(suite: Suite, fixtures: TestFixtures, signal: AbortSignal, body: () => Promise<void>, 
+/** Called once the body (or a `beforeEach` hook) is over, before the `afterEach` hooks, with what it threw */
+onBodyDone?: (error: unknown) => void, 
+/** The custom fixtures: the `auto` ones are set up first, and a hook gets the ones it destructures */
+custom?: FixtureScope): Promise<void>;

package/dist/runner/hooks.js

@@ -46,24 +46,36 @@ export async function runHook(kind, hook, fixtures, limitMs) {
  * - What it throws: the `beforeEach` failure, else the body's error, else the first `afterEach` failure. A skip is
  *   overruled by a failing `afterEach`.
  */
-export async function runWithEachHooks(suite, fixtures, signal, body) {
+export async function runWithEachHooks(suite, fixtures, signal, body, 
+/** Called once the body (or a `beforeEach` hook) is over, before the `afterEach` hooks, with what it threw */
+onBodyDone, 
+/** The custom fixtures: the `auto` ones are set up first, and a hook gets the ones it destructures */
+custom) {
+    const withFixtures = (hook) => custom
+        ? async (given) => {
+            await custom.prepare(hook);
+            return hook(given);
+        }
+        : hook;
     let primary;
     let failed = false;
     try {
+        await custom?.prepareAuto();
         for (const hook of beforeEachOf(suite))
-            await runHook("beforeEach", hook, fixtures);
+            await runHook("beforeEach", withFixtures(hook), fixtures);
         await body();
     }
     catch (error) {
         primary = error;
         failed = true;
     }
+    onBodyDone?.(failed ? primary : undefined);
     let afterError;
     let afterFailed = false;
     if (!signal.aborted) {
         for (const hook of afterEachOf(suite)) {
             try {
-                await runHook("afterEach", hook, fixtures);
+                await runHook("afterEach", withFixtures(hook), fixtures);
             }
             catch (error) {
                 if (!afterFailed)

package/dist/runner/options.d.ts

@@ -1,5 +1,6 @@
 import type { SupportedBrowser } from "../types/browser.js";
 import type { RunEvent } from "./reporter.js";
+import type { Shard } from "./shard.js";
 /** What decides which tests of the found files run, and how the browser starts */
 export interface RunnerOptions {
     /** Spec files to run, absolute or relative to the project folder. Default: every `*.spec.ts` under `srcDir` */
@@ -8,8 +9,12 @@ export interface RunnerOptions {
     grep?: string | RegExp;
     /** Only tests with exactly one of these full names (`describe` titles joined with " > ") */
     testNames?: string[];
-    /** Only the tests of this group of the config's `groups` (unknown name: an error). Combines with the other filters */
-    group?: string;
+    /**
+     * Only the tests of this group of the config's `groups`, or of any of these (unknown name: an error). Combines with
+     * the other filters. The run applies the group's `use` and `browsers`; a test in two selected groups runs once per
+     * group, and its results name the group.
+     */
+    group?: string | string[];
     /** The browsers to run in, instead of the group's or the project's `browsers` (the command line's `--browser`) */
     browsers?: SupportedBrowser[];
     /**
@@ -24,6 +29,12 @@ export interface RunnerOptions {
      * @default the config's `retries`, else 0
      */
     retries?: number | string;
+    /**
+     * Runs only one slice of the selected tests, to split a run over several machines (the command line's
+     * `--shard=current/total`). Whole files, and serial blocks, go to one shard; the shards are disjoint and together
+     * hold every test. The report names the shard. A shard without tests succeeds.
+     */
+    shard?: Shard;
     /**
      * Values for the inputs the tests declare, by name: every test of the run reads the names it declares from
      * here, and its own default for a name missing here

package/dist/runner/output-tail.d.ts

@@ -0,0 +1,14 @@
+/** The last few lines a child process printed, kept for the error message when it fails */
+export declare class OutputTail {
+    private readonly max;
+    /** Values to hide besides the registered secrets (the child's own `env` values) */
+    private readonly hidden;
+    private lines;
+    private partial;
+    constructor(max?: number, 
+    /** Values to hide besides the registered secrets (the child's own `env` values) */
+    hidden?: readonly string[]);
+    add(chunk: Buffer | string): void;
+    /** The kept lines, masked, one per line; empty when the child printed nothing */
+    text(): string;
+}

package/dist/runner/output-tail.js

@@ -0,0 +1,30 @@
+import { MASK, maskText } from "../config/mask.js";
+/** The last few lines a child process printed, kept for the error message when it fails */
+export class OutputTail {
+    constructor(max = 20, 
+    /** Values to hide besides the registered secrets (the child's own `env` values) */
+    hidden = []) {
+        this.max = max;
+        this.hidden = hidden;
+        this.lines = [];
+        this.partial = "";
+    }
+    add(chunk) {
+        const text = this.partial + chunk.toString();
+        const parts = text.split(/\r?\n/);
+        this.partial = parts.pop() ?? "";
+        this.lines.push(...parts);
+        if (this.lines.length > this.max)
+            this.lines.splice(0, this.lines.length - this.max);
+    }
+    /** The kept lines, masked, one per line; empty when the child printed nothing */
+    text() {
+        let text = [...this.lines, this.partial]
+            .filter((line) => line !== "")
+            .join("\n");
+        for (const value of this.hidden)
+            if (value.length >= 4)
+                text = text.split(value).join(MASK);
+        return maskText(text);
+    }
+}

package/dist/runner/pool-schedule.d.ts

@@ -0,0 +1,22 @@
+import type { WorkItem } from "./worker-protocol.js";
+/** What scheduling needs to know of a queued item and of a worker */
+interface Queued {
+    item: WorkItem;
+}
+export interface Worker {
+    /** The unit this worker is running; it keeps the unit's items to itself until none is left */
+    unit?: string | undefined;
+    /** The serial key of the unit, held while the worker keeps the unit */
+    unitKey?: string | undefined;
+    busy?: {
+        entry: Queued;
+    } | undefined;
+}
+/**
+ * The queue position of the next item for `worker`: one of the unit it is running, else the first whose serial
+ * key is not running and whose unit is not held by a worker. -1 when there is none.
+ */
+export declare function nextEligible(queue: Queued[], workers: Worker[], worker: Worker): number;
+/** How many queued items could run at the same time right now: the items of a unit count one */
+export declare function eligibleCount(queue: Queued[], workers: Worker[]): number;
+export {};

package/dist/runner/pool-schedule.js

@@ -0,0 +1,55 @@
+/** The serial keys that are running, or kept by a worker between the items of its unit */
+function busyKeys(workers) {
+    const keys = new Set();
+    for (const { busy, unitKey } of workers) {
+        const key = busy?.entry.item.serialKey ?? unitKey;
+        if (key)
+            keys.add(key);
+    }
+    return keys;
+}
+/** The units workers are running: no other worker may take their items */
+function heldUnits(workers) {
+    const units = new Set();
+    for (const { unit } of workers)
+        if (unit)
+            units.add(unit);
+    return units;
+}
+/**
+ * The queue position of the next item for `worker`: one of the unit it is running, else the first whose serial
+ * key is not running and whose unit is not held by a worker. -1 when there is none.
+ */
+export function nextEligible(queue, workers, worker) {
+    if (worker.unit) {
+        const unit = worker.unit;
+        const at = queue.findIndex(({ item }) => item.unit === unit);
+        if (at >= 0)
+            return at;
+        worker.unit = worker.unitKey = undefined;
+    }
+    const busy = busyKeys(workers);
+    const units = heldUnits(workers);
+    return queue.findIndex(({ item }) => (!item.serialKey || !busy.has(item.serialKey)) &&
+        (!item.unit || !units.has(item.unit)));
+}
+/** How many queued items could run at the same time right now: the items of a unit count one */
+export function eligibleCount(queue, workers) {
+    const taken = busyKeys(workers);
+    const units = heldUnits(workers);
+    let count = 0;
+    for (const { item } of queue) {
+        if (item.unit) {
+            if (units.has(item.unit))
+                continue;
+            units.add(item.unit);
+        }
+        if (item.serialKey) {
+            if (taken.has(item.serialKey))
+                continue;
+            taken.add(item.serialKey);
+        }
+        count++;
+    }
+    return count;
+}