factory-factory 0.4.0 → 0.4.2

package/dist/src/backend/services/job-runner.service.js

@@ -0,0 +1,168 @@
+import { toError } from '../../backend/lib/error-utils.js';
+import { createLogger } from './logger.service.js';
+const logger = createLogger('job-runner');
+export class JobRunner {
+    jobs = new Map();
+    register(definition) {
+        const existing = this.jobs.get(definition.name);
+        if (existing?.loop != null || existing?.starting) {
+            throw new Error(`Job already running, cannot redefine: ${definition.name}`);
+        }
+        this.jobs.set(definition.name, {
+            definition,
+            loop: null,
+            starting: false,
+            stopping: false,
+            restartRequested: false,
+            stopPending: null,
+            abortController: new AbortController(),
+            currentRun: null,
+            cancelSleep: null,
+        });
+    }
+    isRunning(name) {
+        return this.get(name).loop !== null;
+    }
+    start(name) {
+        const state = this.get(name);
+        if (state.stopPending !== null) {
+            state.restartRequested = true;
+            return;
+        }
+        if (state.loop !== null || state.starting) {
+            return;
+        }
+        state.stopping = false;
+        state.abortController = new AbortController();
+        state.starting = true;
+        try {
+            const loop = this.runLoop(state)
+                .catch((error) => {
+                logger.error(`Job loop terminated unexpectedly: ${name}`, toError(error));
+            })
+                .finally(() => {
+                if (state.loop === loop) {
+                    state.loop = null;
+                }
+            });
+            state.loop = loop;
+        }
+        finally {
+            state.starting = false;
+        }
+        logger.info('Job started', { job: name, intervalMs: state.definition.intervalMs });
+    }
+    startAll() {
+        for (const name of this.jobs.keys()) {
+            this.start(name);
+        }
+    }
+    waitForCurrentRun(name) {
+        return this.get(name).currentRun ?? Promise.resolve();
+    }
+    async stop(name) {
+        const state = this.get(name);
+        state.restartRequested = false;
+        if (state.stopPending !== null) {
+            await state.stopPending;
+            return;
+        }
+        state.stopping = true;
+        const pending = (async () => {
+            const { loop, currentRun } = state;
+            if (loop !== null) {
+                await loop;
+            }
+            else if (currentRun !== null) {
+                await currentRun;
+            }
+        })();
+        state.stopPending = pending;
+        state.abortController.abort();
+        state.cancelSleep?.();
+        try {
+            await pending;
+        }
+        finally {
+            state.stopPending = null;
+        }
+        logger.info('Job stopped', { job: name });
+        if (state.restartRequested) {
+            state.restartRequested = false;
+            this.start(name);
+        }
+    }
+    async stopAll() {
+        await Promise.all([...this.jobs.keys()].map((name) => this.stop(name)));
+    }
+    reset() {
+        this.jobs.clear();
+    }
+    get(name) {
+        const state = this.jobs.get(name);
+        if (!state) {
+            throw new Error(`Job not registered: ${name}`);
+        }
+        return state;
+    }
+    async runLoop(state) {
+        if (!state.definition.runImmediately) {
+            await this.sleep(state);
+        }
+        while (!state.stopping) {
+            await this.runOnce(state);
+            if (state.stopping) {
+                break;
+            }
+            await this.sleep(state);
+        }
+    }
+    async runOnce(state) {
+        const { signal } = state.abortController;
+        let settle;
+        const run = new Promise((resolve) => {
+            settle = resolve;
+        });
+        state.currentRun = run;
+        try {
+            await state.definition.run(signal);
+        }
+        catch (error) {
+            logger.error(`Job run failed: ${state.definition.name}`, toError(error));
+        }
+        finally {
+            if (state.currentRun === run) {
+                state.currentRun = null;
+            }
+            settle();
+        }
+    }
+    sleep(state) {
+        if (state.stopping) {
+            return Promise.resolve();
+        }
+        const { intervalMs, computeDelay } = state.definition;
+        const delayMs = computeDelay ? computeDelay(intervalMs) : intervalMs;
+        return new Promise((resolve) => {
+            let settled = false;
+            let timer;
+            const finish = () => {
+                if (settled) {
+                    return;
+                }
+                settled = true;
+                if (timer !== undefined) {
+                    clearTimeout(timer);
+                }
+                if (state.cancelSleep === finish) {
+                    state.cancelSleep = null;
+                }
+                resolve();
+            };
+            state.cancelSleep = finish;
+            timer = setTimeout(finish, delayMs);
+        });
+    }
+}
+export const jobRunner = new JobRunner();
+//# sourceMappingURL=job-runner.service.js.map

package/dist/src/backend/services/job-runner.service.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"job-runner.service.js","sourceRoot":"","sources":["../../../../src/backend/services/job-runner.service.ts"],"names":[],"mappings":"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"}

package/dist/src/backend/services/job-runner.service.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=job-runner.service.test.d.ts.map

package/dist/src/backend/services/job-runner.service.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"job-runner.service.test.d.ts","sourceRoot":"","sources":["../../../../src/backend/services/job-runner.service.test.ts"],"names":[],"mappings":""}

package/dist/src/backend/services/job-runner.service.test.js

@@ -0,0 +1,498 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+const mockLogger = vi.hoisted(() => ({
+    debug: vi.fn(),
+    info: vi.fn(),
+    warn: vi.fn(),
+    error: vi.fn(),
+}));
+vi.mock('./logger.service', () => ({
+    createLogger: () => mockLogger,
+}));
+import { jobRunner } from './job-runner.service.js';
+function controllableRun() {
+    let starts = 0;
+    let release = null;
+    return {
+        get starts() {
+            return starts;
+        },
+        run: () => {
+            starts += 1;
+            return new Promise((resolve) => {
+                release = resolve;
+            });
+        },
+        finish() {
+            const resolve = release;
+            release = null;
+            resolve?.();
+        },
+    };
+}
+describe('jobRunner', () => {
+    beforeEach(() => {
+        vi.useFakeTimers();
+        vi.clearAllMocks();
+        jobRunner.reset();
+    });
+    afterEach(async () => {
+        await jobRunner.stopAll();
+        jobRunner.reset();
+        vi.useRealTimers();
+    });
+    describe('registration', () => {
+        it('does not start a job just because it was registered', async () => {
+            const run = vi.fn().mockResolvedValue(undefined);
+            jobRunner.register({ name: 'first', intervalMs: 1000, run });
+            jobRunner.register({ name: 'second', intervalMs: 1000, run });
+            expect(jobRunner.isRunning('first')).toBe(false);
+            expect(jobRunner.isRunning('second')).toBe(false);
+            await vi.advanceTimersByTimeAsync(10_000);
+            expect(run).not.toHaveBeenCalled();
+        });
+        it('replaces the definition when the job is idle', async () => {
+            const first = vi.fn().mockResolvedValue(undefined);
+            const second = vi.fn().mockResolvedValue(undefined);
+            jobRunner.register({ name: 'dup', intervalMs: 1000, run: first });
+            jobRunner.register({ name: 'dup', intervalMs: 1000, run: second });
+            jobRunner.start('dup');
+            await vi.advanceTimersByTimeAsync(1000);
+            expect(first).not.toHaveBeenCalled();
+            expect(second).toHaveBeenCalledTimes(1);
+        });
+        it('refuses to redefine a job that is already running', () => {
+            const run = vi.fn().mockResolvedValue(undefined);
+            jobRunner.register({ name: 'live', intervalMs: 1000, run });
+            jobRunner.start('live');
+            expect(() => jobRunner.register({ name: 'live', intervalMs: 1000, run })).toThrow('Job already running, cannot redefine: live');
+        });
+        it('names the job when addressed by a name nothing registered', async () => {
+            expect(() => jobRunner.start('typo')).toThrow('Job not registered: typo');
+            expect(() => jobRunner.isRunning('typo')).toThrow('Job not registered: typo');
+            expect(() => jobRunner.waitForCurrentRun('typo')).toThrow('Job not registered: typo');
+            await expect(jobRunner.stop('typo')).rejects.toThrow('Job not registered: typo');
+        });
+    });
+    describe('pacing', () => {
+        it('waits out the first delay before the first run by default', async () => {
+            const run = vi.fn().mockResolvedValue(undefined);
+            jobRunner.register({ name: 'delayed', intervalMs: 1000, run });
+            jobRunner.start('delayed');
+            await vi.advanceTimersByTimeAsync(999);
+            expect(run).not.toHaveBeenCalled();
+            await vi.advanceTimersByTimeAsync(1);
+            expect(run).toHaveBeenCalledTimes(1);
+        });
+        it('runs at once when the job asks to, then falls into the interval', async () => {
+            const run = vi.fn().mockResolvedValue(undefined);
+            jobRunner.register({ name: 'eager', intervalMs: 1000, run, runImmediately: true });
+            jobRunner.start('eager');
+            await vi.advanceTimersByTimeAsync(0);
+            expect(run).toHaveBeenCalledTimes(1);
+            await vi.advanceTimersByTimeAsync(1000);
+            expect(run).toHaveBeenCalledTimes(2);
+        });
+        it('measures the delay from the end of a run, not its start', async () => {
+            const job = controllableRun();
+            jobRunner.register({ name: 'slow', intervalMs: 1000, run: job.run });
+            jobRunner.start('slow');
+            await vi.advanceTimersByTimeAsync(1000);
+            expect(job.starts).toBe(1);
+            await vi.advanceTimersByTimeAsync(5000);
+            expect(job.starts).toBe(1);
+            job.finish();
+            await vi.advanceTimersByTimeAsync(999);
+            expect(job.starts).toBe(1);
+            await vi.advanceTimersByTimeAsync(1);
+            expect(job.starts).toBe(2);
+            job.finish();
+        });
+        it('lets the job stretch its own delay', async () => {
+            const run = vi.fn().mockResolvedValue(undefined);
+            const computeDelay = vi.fn((base) => base * 3);
+            jobRunner.register({ name: 'backed-off', intervalMs: 1000, run, computeDelay });
+            jobRunner.start('backed-off');
+            await vi.advanceTimersByTimeAsync(2999);
+            expect(run).not.toHaveBeenCalled();
+            await vi.advanceTimersByTimeAsync(1);
+            expect(run).toHaveBeenCalledTimes(1);
+            expect(computeDelay).toHaveBeenCalledWith(1000);
+        });
+        it('re-reads the computed delay every cycle, so backoff can change', async () => {
+            let multiplier = 1;
+            const run = vi.fn(() => {
+                multiplier = 4;
+                return Promise.resolve();
+            });
+            jobRunner.register({
+                name: 'variable',
+                intervalMs: 1000,
+                run,
+                computeDelay: (base) => base * multiplier,
+            });
+            jobRunner.start('variable');
+            await vi.advanceTimersByTimeAsync(1000);
+            expect(run).toHaveBeenCalledTimes(1);
+            await vi.advanceTimersByTimeAsync(3999);
+            expect(run).toHaveBeenCalledTimes(1);
+            await vi.advanceTimersByTimeAsync(1);
+            expect(run).toHaveBeenCalledTimes(2);
+        });
+    });
+    describe('failure handling', () => {
+        it('logs a rejected run and keeps the loop alive', async () => {
+            const run = vi.fn().mockRejectedValueOnce(new Error('boom')).mockResolvedValue(undefined);
+            jobRunner.register({ name: 'flaky', intervalMs: 1000, run });
+            jobRunner.start('flaky');
+            await vi.advanceTimersByTimeAsync(1000);
+            expect(run).toHaveBeenCalledTimes(1);
+            expect(mockLogger.error).toHaveBeenCalledWith('Job run failed: flaky', expect.objectContaining({ message: 'boom' }));
+            await vi.advanceTimersByTimeAsync(1000);
+            expect(run).toHaveBeenCalledTimes(2);
+        });
+    });
+    describe('waitForCurrentRun', () => {
+        it('resolves immediately when the job is between runs', async () => {
+            const run = vi.fn().mockResolvedValue(undefined);
+            jobRunner.register({ name: 'idle', intervalMs: 1000, run });
+            jobRunner.start('idle');
+            let resolved = false;
+            void jobRunner.waitForCurrentRun('idle').then(() => {
+                resolved = true;
+            });
+            await vi.advanceTimersByTimeAsync(0);
+            expect(resolved).toBe(true);
+            expect(run).not.toHaveBeenCalled();
+        });
+        it('resolves when the run in flight finishes, and does not wait for the next one', async () => {
+            const job = controllableRun();
+            jobRunner.register({
+                name: 'inflight',
+                intervalMs: 1000,
+                run: job.run,
+                runImmediately: true,
+            });
+            jobRunner.start('inflight');
+            await vi.advanceTimersByTimeAsync(0);
+            let resolved = false;
+            void jobRunner.waitForCurrentRun('inflight').then(() => {
+                resolved = true;
+            });
+            await vi.advanceTimersByTimeAsync(0);
+            expect(resolved).toBe(false);
+            job.finish();
+            await vi.advanceTimersByTimeAsync(0);
+            expect(resolved).toBe(true);
+            expect(job.starts).toBe(1);
+        });
+        it('resolves immediately for a job that was never started', async () => {
+            jobRunner.register({ name: 'unstarted', intervalMs: 1000, run: vi.fn() });
+            await expect(jobRunner.waitForCurrentRun('unstarted')).resolves.toBeUndefined();
+        });
+    });
+    describe('stop', () => {
+        it('cancels a pending delay instead of waiting it out', async () => {
+            const run = vi.fn().mockResolvedValue(undefined);
+            jobRunner.register({ name: 'sleeping', intervalMs: 120_000, run });
+            jobRunner.start('sleeping');
+            await jobRunner.stop('sleeping');
+            expect(run).not.toHaveBeenCalled();
+            expect(jobRunner.isRunning('sleeping')).toBe(false);
+        });
+        it('waits for a run that is in flight', async () => {
+            const job = controllableRun();
+            jobRunner.register({ name: 'busy', intervalMs: 1000, run: job.run, runImmediately: true });
+            jobRunner.start('busy');
+            await vi.advanceTimersByTimeAsync(0);
+            let stopped = false;
+            const stopping = jobRunner.stop('busy').then(() => {
+                stopped = true;
+            });
+            await vi.advanceTimersByTimeAsync(0);
+            expect(stopped).toBe(false);
+            job.finish();
+            await stopping;
+            expect(stopped).toBe(true);
+            expect(job.starts).toBe(1);
+        });
+        it('does not start another cycle after the in-flight run completes', async () => {
+            const job = controllableRun();
+            jobRunner.register({
+                name: 'last-cycle',
+                intervalMs: 1000,
+                run: job.run,
+                runImmediately: true,
+            });
+            jobRunner.start('last-cycle');
+            await vi.advanceTimersByTimeAsync(0);
+            const stopping = jobRunner.stop('last-cycle');
+            job.finish();
+            await stopping;
+            await vi.advanceTimersByTimeAsync(10_000);
+            expect(job.starts).toBe(1);
+        });
+        it('is safe to call on a job that is not running', async () => {
+            jobRunner.register({ name: 'never-started', intervalMs: 1000, run: vi.fn() });
+            await expect(jobRunner.stop('never-started')).resolves.toBeUndefined();
+        });
+        it('allows a stopped job to be started again', async () => {
+            const run = vi.fn().mockResolvedValue(undefined);
+            jobRunner.register({ name: 'restartable', intervalMs: 1000, run });
+            jobRunner.start('restartable');
+            await jobRunner.stop('restartable');
+            jobRunner.start('restartable');
+            await vi.advanceTimersByTimeAsync(1000);
+            expect(run).toHaveBeenCalledTimes(1);
+            expect(jobRunner.isRunning('restartable')).toBe(true);
+        });
+    });
+    describe('abort signal', () => {
+        it('aborts the in-flight run when the job is stopped', async () => {
+            let observed;
+            const job = controllableRun();
+            jobRunner.register({
+                name: 'abortable',
+                intervalMs: 1000,
+                runImmediately: true,
+                run: (signal) => {
+                    observed = signal;
+                    return job.run();
+                },
+            });
+            jobRunner.start('abortable');
+            await vi.advanceTimersByTimeAsync(0);
+            expect(observed?.aborted).toBe(false);
+            const stopping = jobRunner.stop('abortable');
+            expect(observed?.aborted).toBe(true);
+            job.finish();
+            await stopping;
+        });
+        it('hands a restarted job a signal that is not already aborted', async () => {
+            const signals = [];
+            jobRunner.register({
+                name: 'restarted',
+                intervalMs: 1000,
+                runImmediately: true,
+                run: (signal) => {
+                    signals.push(signal);
+                    return Promise.resolve();
+                },
+            });
+            jobRunner.start('restarted');
+            await vi.advanceTimersByTimeAsync(0);
+            await jobRunner.stop('restarted');
+            expect(signals[0]?.aborted).toBe(true);
+            jobRunner.start('restarted');
+            await vi.advanceTimersByTimeAsync(0);
+            expect(signals).toHaveLength(2);
+            expect(signals[1]?.aborted).toBe(false);
+        });
+    });
+    describe('start', () => {
+        it('is idempotent, so a second call does not create a second loop', async () => {
+            const run = vi.fn().mockResolvedValue(undefined);
+            jobRunner.register({ name: 'once', intervalMs: 1000, run });
+            jobRunner.start('once');
+            jobRunner.start('once');
+            await vi.advanceTimersByTimeAsync(1000);
+            expect(run).toHaveBeenCalledTimes(1);
+        });
+    });
+    describe('restart safety', () => {
+        it('refuses to build a second loop while a stop is still waiting on a run', async () => {
+            const job = controllableRun();
+            jobRunner.register({
+                name: 'winding-down',
+                intervalMs: 1000,
+                runImmediately: true,
+                run: job.run,
+            });
+            jobRunner.start('winding-down');
+            await vi.advanceTimersByTimeAsync(0);
+            expect(job.starts).toBe(1);
+            const stopping = jobRunner.stop('winding-down');
+            jobRunner.start('winding-down');
+            await vi.advanceTimersByTimeAsync(0);
+            expect(job.starts).toBe(1);
+            job.finish();
+            await stopping;
+            expect(jobRunner.isRunning('winding-down')).toBe(true);
+            expect(job.starts).toBe(2);
+            job.finish();
+            await vi.advanceTimersByTimeAsync(1000);
+            expect(job.starts).toBe(3);
+            job.finish();
+        });
+        it('queues a restart requested from an abort listener', async () => {
+            const job = controllableRun();
+            jobRunner.register({
+                name: 'listener-restart',
+                intervalMs: 1000,
+                runImmediately: true,
+                run: (signal) => {
+                    signal.addEventListener('abort', () => jobRunner.start('listener-restart'));
+                    return job.run();
+                },
+            });
+            jobRunner.start('listener-restart');
+            await vi.advanceTimersByTimeAsync(0);
+            const stopping = jobRunner.stop('listener-restart');
+            job.finish();
+            await stopping;
+            expect(jobRunner.isRunning('listener-restart')).toBe(true);
+            job.finish();
+        });
+        it('drops a pending restart when a second stop supersedes it', async () => {
+            const run = vi.fn().mockResolvedValue(undefined);
+            const job = controllableRun();
+            jobRunner.register({
+                name: 'superseded',
+                intervalMs: 1000,
+                runImmediately: true,
+                run: () => {
+                    run();
+                    return job.run();
+                },
+            });
+            jobRunner.start('superseded');
+            await vi.advanceTimersByTimeAsync(0);
+            const first = jobRunner.stop('superseded');
+            jobRunner.start('superseded');
+            const second = jobRunner.stop('superseded');
+            job.finish();
+            await Promise.all([first, second]);
+            expect(jobRunner.isRunning('superseded')).toBe(false);
+            expect(run).toHaveBeenCalledTimes(1);
+        });
+        it('honours a stop issued synchronously from inside the first run', async () => {
+            let starts = 0;
+            let stopPromise = null;
+            let runFinished = false;
+            jobRunner.register({
+                name: 'self-stopping',
+                intervalMs: 1000,
+                runImmediately: true,
+                run: async () => {
+                    starts += 1;
+                    if (starts === 1) {
+                        stopPromise = jobRunner.stop('self-stopping');
+                    }
+                    await Promise.resolve();
+                    runFinished = true;
+                },
+            });
+            jobRunner.start('self-stopping');
+            await vi.advanceTimersByTimeAsync(0);
+            expect(stopPromise).not.toBeNull();
+            await stopPromise;
+            expect(runFinished).toBe(true);
+            await vi.advanceTimersByTimeAsync(5000);
+            expect(starts).toBe(1);
+            expect(jobRunner.isRunning('self-stopping')).toBe(false);
+        });
+        it('makes a second stop wait for the same run as the first', async () => {
+            const job = controllableRun();
+            jobRunner.register({ name: 'twice', intervalMs: 1000, runImmediately: true, run: job.run });
+            jobRunner.start('twice');
+            await vi.advanceTimersByTimeAsync(0);
+            let secondResolved = false;
+            const first = jobRunner.stop('twice');
+            const second = jobRunner.stop('twice').then(() => {
+                secondResolved = true;
+            });
+            await vi.advanceTimersByTimeAsync(0);
+            expect(secondResolved).toBe(false);
+            job.finish();
+            await Promise.all([first, second]);
+            expect(secondResolved).toBe(true);
+        });
+        it('frees the slot when the loop dies outside a run, so the job can restart', async () => {
+            let explode = true;
+            const run = vi.fn().mockResolvedValue(undefined);
+            jobRunner.register({
+                name: 'exploding',
+                intervalMs: 1000,
+                runImmediately: true,
+                run,
+                computeDelay: (base) => {
+                    if (explode) {
+                        throw new Error('backoff blew up');
+                    }
+                    return base;
+                },
+            });
+            jobRunner.start('exploding');
+            await vi.advanceTimersByTimeAsync(0);
+            expect(run).toHaveBeenCalledTimes(1);
+            expect(mockLogger.error).toHaveBeenCalledWith('Job loop terminated unexpectedly: exploding', expect.objectContaining({ message: 'backoff blew up' }));
+            expect(jobRunner.isRunning('exploding')).toBe(false);
+            explode = false;
+            jobRunner.start('exploding');
+            await vi.advanceTimersByTimeAsync(0);
+            expect(run).toHaveBeenCalledTimes(2);
+        });
+        it('has the first run observable the moment start() returns', async () => {
+            const job = controllableRun();
+            jobRunner.register({
+                name: 'sync-first',
+                intervalMs: 1000,
+                runImmediately: true,
+                run: job.run,
+            });
+            jobRunner.start('sync-first');
+            expect(job.starts).toBe(1);
+            let resolved = false;
+            void jobRunner.waitForCurrentRun('sync-first').then(() => {
+                resolved = true;
+            });
+            await vi.advanceTimersByTimeAsync(0);
+            expect(resolved).toBe(false);
+            job.finish();
+            await vi.advanceTimersByTimeAsync(0);
+            expect(resolved).toBe(true);
+        });
+        it('holds the idempotence guard even when the first run re-enters start()', async () => {
+            const run = vi.fn(() => {
+                jobRunner.start('reentrant');
+                return Promise.resolve();
+            });
+            jobRunner.register({ name: 'reentrant', intervalMs: 1000, runImmediately: true, run });
+            jobRunner.start('reentrant');
+            await vi.advanceTimersByTimeAsync(0);
+            expect(run).toHaveBeenCalledTimes(1);
+        });
+    });
+    describe('startAll / stopAll', () => {
+        it('starts every registered job', async () => {
+            const first = vi.fn().mockResolvedValue(undefined);
+            const second = vi.fn().mockResolvedValue(undefined);
+            jobRunner.register({ name: 'a', intervalMs: 1000, run: first });
+            jobRunner.register({ name: 'b', intervalMs: 2000, run: second });
+            jobRunner.startAll();
+            await vi.advanceTimersByTimeAsync(2000);
+            expect(first).toHaveBeenCalledTimes(2);
+            expect(second).toHaveBeenCalledTimes(1);
+        });
+        it('stops jobs concurrently, so shutdown costs the slowest run and not their sum', async () => {
+            const slow = controllableRun();
+            const alsoSlow = controllableRun();
+            jobRunner.register({ name: 'x', intervalMs: 1000, run: slow.run, runImmediately: true });
+            jobRunner.register({ name: 'y', intervalMs: 1000, run: alsoSlow.run, runImmediately: true });
+            jobRunner.startAll();
+            await vi.advanceTimersByTimeAsync(0);
+            let stopped = false;
+            const stopping = jobRunner.stopAll().then(() => {
+                stopped = true;
+            });
+            await vi.advanceTimersByTimeAsync(0);
+            expect(stopped).toBe(false);
+            slow.finish();
+            alsoSlow.finish();
+            await stopping;
+            expect(stopped).toBe(true);
+            expect(jobRunner.isRunning('x')).toBe(false);
+            expect(jobRunner.isRunning('y')).toBe(false);
+        });
+    });
+});
+//# sourceMappingURL=job-runner.service.test.js.map