yaxa-svelte 2.3.0 → 2.4.0

package/dist/server/db/types.d.ts

@@ -70,3 +70,21 @@ export interface PricingTier {
     buttonText?: string;
     features: (string | PricingFeature)[];
 }
+export type JobStatus = 'pending' | 'processing' | 'completed' | 'failed';
+export interface YaxaJob<TPayload = any> {
+    id: string;
+    queue: string;
+    name: string;
+    payload: TPayload;
+    status: JobStatus;
+    priority: number;
+    attempts: number;
+    maxAttempts: number;
+    runAt: Date;
+    lockedAt?: Date | null;
+    lockedBy?: string | null;
+    failedReason?: string | null;
+    createdAt: Date;
+    updatedAt: Date;
+    completedAt?: Date | null;
+}

package/dist/server/index.d.ts

@@ -26,3 +26,5 @@ export { yaxaEndpoint, createProblemDetails, problemResponse, isProblemDetails,
 export type { YaxaEndpointConfig, YaxaEndpointContext, YaxaEndpointSchemaConfig, YaxaInterceptor, Guard, GuardResult, ProblemDetails, CreateProblemOptions, RequireAuthOptions, RequireRoleOptions, RateLimitOptions, AnyValidator, InferValidatorOutput, ValidationOutcome, ValidationSuccess, ValidationFailure } from './endpoint/index';
 export { generateOpenApiSpec, createApiDocsHandler, createApiRegistry, globalApiRegistry, convertToJsonSchema } from './openapi/index';
 export type { OpenApiSpec31, OpenApiOperation, OpenApiParameter, OpenApiRequestBody, OpenApiResponse, GenerateOpenApiOptions, ApiDocsOptions, ApiDocsTheme, EndpointLike, EndpointMap } from './openapi/index';
+export { enqueueJob, defineWorker, createJobRunner, eventBus, EventBus, parseJobDelay } from './jobs/index';
+export type { JobRecord, JobDelay, EnqueueJobOptions, WorkerContext, WorkerHandler, WorkerDefinition, JobRunnerOptions, JobBatchResult, JobRunner, EventHandler, EventSubscription, IEventBus } from './jobs/index';

package/dist/server/index.js

@@ -22,3 +22,5 @@ export { getS3Client, createPresignedUploadUrl, createS3UploadHandler } from './
 export { yaxaEndpoint, createProblemDetails, problemResponse, isProblemDetails, requireAuth, requireRole, rateLimit, composeGuards, validateData } from './endpoint/index';
 // Auto-Generated OpenAPI 3.1 & Interactive Docs (Milestone 3)
 export { generateOpenApiSpec, createApiDocsHandler, createApiRegistry, globalApiRegistry, convertToJsonSchema } from './openapi/index';
+// Embedded Background Workflows, Job Queue & Domain Events (Milestone 6)
+export { enqueueJob, defineWorker, createJobRunner, eventBus, EventBus, parseJobDelay } from './jobs/index';

package/dist/server/jobs/events.d.ts

@@ -0,0 +1,29 @@
+import type { EventHandler, EventSubscription, IEventBus } from './types';
+/**
+ * In-process Domain Event Bus for decoupled asynchronous event notifications.
+ */
+export declare class EventBus implements IEventBus {
+    private subscribers;
+    private counter;
+    /**
+     * Subscribes a handler to an event.
+     */
+    subscribe<TData = any>(eventName: string, handler: EventHandler<TData>): EventSubscription;
+    /**
+     * Subscribes a handler to an event for exactly one invocation.
+     */
+    once<TData = any>(eventName: string, handler: EventHandler<TData>): EventSubscription;
+    /**
+     * Publishes an event to all registered subscribers.
+     * Handlers run asynchronously and errors in one subscriber do not crash others.
+     */
+    publish<TData = any>(eventName: string, data: TData): Promise<void>;
+    /**
+     * Clears all registered subscribers. Useful for test isolation.
+     */
+    clear(): void;
+}
+/**
+ * Global singleton EventBus instance.
+ */
+export declare const eventBus: EventBus;

package/dist/server/jobs/events.js

@@ -0,0 +1,74 @@
+/**
+ * In-process Domain Event Bus for decoupled asynchronous event notifications.
+ */
+export class EventBus {
+    subscribers = new Map();
+    counter = 0;
+    /**
+     * Subscribes a handler to an event.
+     */
+    subscribe(eventName, handler) {
+        const id = `sub_${++this.counter}_${Date.now()}`;
+        const list = this.subscribers.get(eventName) || [];
+        list.push({ id, handler });
+        this.subscribers.set(eventName, list);
+        return {
+            unsubscribe: () => {
+                const current = this.subscribers.get(eventName);
+                if (current) {
+                    this.subscribers.set(eventName, current.filter((item) => item.id !== id));
+                }
+            }
+        };
+    }
+    /**
+     * Subscribes a handler to an event for exactly one invocation.
+     */
+    once(eventName, handler) {
+        const id = `sub_once_${++this.counter}_${Date.now()}`;
+        const list = this.subscribers.get(eventName) || [];
+        list.push({ id, handler, once: true });
+        this.subscribers.set(eventName, list);
+        return {
+            unsubscribe: () => {
+                const current = this.subscribers.get(eventName);
+                if (current) {
+                    this.subscribers.set(eventName, current.filter((item) => item.id !== id));
+                }
+            }
+        };
+    }
+    /**
+     * Publishes an event to all registered subscribers.
+     * Handlers run asynchronously and errors in one subscriber do not crash others.
+     */
+    async publish(eventName, data) {
+        const current = this.subscribers.get(eventName);
+        if (!current || current.length === 0) {
+            return;
+        }
+        // Filter out one-time subscribers
+        const toRun = [...current];
+        const remaining = current.filter((item) => !item.once);
+        this.subscribers.set(eventName, remaining);
+        const promises = toRun.map(async (sub) => {
+            try {
+                await sub.handler(data);
+            }
+            catch (err) {
+                console.error(`[EventBus] Error in subscriber for event "${eventName}":`, err);
+            }
+        });
+        await Promise.allSettled(promises);
+    }
+    /**
+     * Clears all registered subscribers. Useful for test isolation.
+     */
+    clear() {
+        this.subscribers.clear();
+    }
+}
+/**
+ * Global singleton EventBus instance.
+ */
+export const eventBus = new EventBus();

package/dist/server/jobs/index.d.ts

@@ -0,0 +1,4 @@
+export { enqueueJob, parseJobDelay, memoryJobStore } from './queue';
+export { defineWorker, createJobRunner } from './runner';
+export { EventBus, eventBus } from './events';
+export type { JobRecord, JobDelay, EnqueueJobOptions, WorkerContext, WorkerHandler, WorkerDefinition, JobRunnerOptions, JobBatchResult, JobRunner, EventHandler, EventSubscription, IEventBus } from './types';

package/dist/server/jobs/index.js

@@ -0,0 +1,3 @@
+export { enqueueJob, parseJobDelay, memoryJobStore } from './queue';
+export { defineWorker, createJobRunner } from './runner';
+export { EventBus, eventBus } from './events';

package/dist/server/jobs/jobs.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/server/jobs/jobs.test.js

@@ -0,0 +1,189 @@
+import { describe, it, expect, beforeEach, vi } from 'vitest';
+import { EventBus, eventBus, enqueueJob, defineWorker, createJobRunner, parseJobDelay, memoryJobStore } from './index.js';
+describe('Domain Event Bus (EventBus)', () => {
+    let bus;
+    beforeEach(() => {
+        bus = new EventBus();
+        eventBus.clear();
+    });
+    it('dispatches events asynchronously to registered subscribers', async () => {
+        const received = [];
+        bus.subscribe('user.registered', async (data) => {
+            received.push(data);
+        });
+        await bus.publish('user.registered', { id: 'usr_1', email: 'alex@example.com' });
+        expect(received).toHaveLength(1);
+        expect(received[0].email).toBe('alex@example.com');
+    });
+    it('supports unsubscription via returned handler', async () => {
+        let count = 0;
+        const sub = bus.subscribe('counter.increment', () => {
+            count++;
+        });
+        await bus.publish('counter.increment', {});
+        expect(count).toBe(1);
+        sub.unsubscribe();
+        await bus.publish('counter.increment', {});
+        expect(count).toBe(1);
+    });
+    it('supports one-time subscribers with once()', async () => {
+        let triggered = 0;
+        bus.once('invoice.paid', () => {
+            triggered++;
+        });
+        await bus.publish('invoice.paid', { amount: 100 });
+        await bus.publish('invoice.paid', { amount: 200 });
+        expect(triggered).toBe(1);
+    });
+    it('isolates subscriber errors without crashing other subscribers or the publisher', async () => {
+        const errorSpy = vi.spyOn(console, 'error').mockImplementation(() => { });
+        const healthyReceived = [];
+        bus.subscribe('order.placed', () => {
+            throw new Error('Failing external analytics webhook');
+        });
+        bus.subscribe('order.placed', (data) => {
+            healthyReceived.push(data.orderId);
+        });
+        // Publishing should complete without throwing
+        await expect(bus.publish('order.placed', { orderId: 'ord_999' })).resolves.not.toThrow();
+        expect(healthyReceived).toEqual(['ord_999']);
+        errorSpy.mockRestore();
+    });
+});
+describe('Job Delay Parser (parseJobDelay)', () => {
+    it('parses second, minute, hour, and day string abbreviations', () => {
+        const now = Date.now();
+        const in30s = parseJobDelay('30s').getTime();
+        expect(in30s).toBeGreaterThanOrEqual(now + 29000);
+        expect(in30s).toBeLessThanOrEqual(now + 31000);
+        const in5m = parseJobDelay('5m').getTime();
+        expect(in5m).toBeGreaterThanOrEqual(now + 5 * 60 * 1000 - 1000);
+        const in2h = parseJobDelay('2h').getTime();
+        expect(in2h).toBeGreaterThanOrEqual(now + 2 * 60 * 60 * 1000 - 1000);
+        const in1d = parseJobDelay('1d').getTime();
+        expect(in1d).toBeGreaterThanOrEqual(now + 24 * 60 * 60 * 1000 - 1000);
+    });
+    it('accepts raw millisecond numbers and Date instances directly', () => {
+        const targetDate = new Date(Date.now() + 10000);
+        expect(parseJobDelay(targetDate)).toEqual(targetDate);
+        const msResult = parseJobDelay(5000).getTime();
+        expect(msResult).toBeGreaterThanOrEqual(Date.now() + 4900);
+    });
+});
+describe('Job Queue & Runner Engine', () => {
+    beforeEach(() => {
+        memoryJobStore.clear();
+    });
+    it('enqueues jobs with default metadata and parameters', async () => {
+        const job = await enqueueJob('send-email', { to: 'elena@example.com' }, {
+            priority: 5,
+            maxAttempts: 4
+        });
+        expect(job.id).toBeDefined();
+        expect(job.name).toBe('send-email');
+        expect(job.payload.to).toBe('elena@example.com');
+        expect(job.status).toBe('pending');
+        expect(job.priority).toBe(5);
+        expect(job.maxAttempts).toBe(4);
+        expect(job.attempts).toBe(0);
+        expect(memoryJobStore.has(job.id)).toBe(true);
+    });
+    it('processes pending jobs successfully via defined worker', async () => {
+        const processed = [];
+        const emailWorker = defineWorker('send-welcome', async (payload) => {
+            processed.push(payload.to);
+        });
+        const runner = createJobRunner({
+            workers: [emailWorker]
+        });
+        const job = await enqueueJob('send-welcome', { to: 'alex@example.com' });
+        const result = await runner.processNextBatch();
+        expect(result.processed).toBe(1);
+        expect(result.succeeded).toBe(1);
+        expect(result.failed).toBe(0);
+        expect(processed).toEqual(['alex@example.com']);
+        // Verify job record state
+        const updatedJob = memoryJobStore.get(job.id);
+        expect(updatedJob?.status).toBe('completed');
+        expect(updatedJob?.completedAt).toBeDefined();
+        expect(updatedJob?.lockedAt).toBeNull();
+    });
+    it('retries failing jobs with exponential backoff when attempts < maxAttempts', async () => {
+        const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => { });
+        let callCount = 0;
+        const flakyWorker = defineWorker('flaky-task', async () => {
+            callCount++;
+            throw new Error('Temporary 503 from external service');
+        });
+        const runner = createJobRunner({
+            workers: [flakyWorker]
+        });
+        const job = await enqueueJob('flaky-task', {}, { maxAttempts: 3 });
+        const result = await runner.processNextBatch();
+        expect(result.processed).toBe(1);
+        expect(result.succeeded).toBe(0);
+        expect(result.failed).toBe(0); // Not marked permanently failed yet
+        expect(callCount).toBe(1);
+        const updatedJob = memoryJobStore.get(job.id);
+        expect(updatedJob?.attempts).toBe(1);
+        expect(updatedJob?.status).toBe('pending');
+        expect(updatedJob?.failedReason).toContain('Temporary 503');
+        // Backoff placed runAt into the future
+        expect(updatedJob?.runAt.getTime()).toBeGreaterThan(Date.now());
+        warnSpy.mockRestore();
+    });
+    it('transitions to Dead Letter Queue (status: failed) when maxAttempts is reached', async () => {
+        const errorSpy = vi.spyOn(console, 'error').mockImplementation(() => { });
+        const fatalWorker = defineWorker('fatal-task', async () => {
+            throw new Error('Permanent database constraint error');
+        });
+        const runner = createJobRunner({
+            workers: [fatalWorker]
+        });
+        // maxAttempts = 1 -> should fail immediately after 1 attempt
+        const job = await enqueueJob('fatal-task', {}, { maxAttempts: 1 });
+        const result = await runner.processNextBatch();
+        expect(result.processed).toBe(1);
+        expect(result.succeeded).toBe(0);
+        expect(result.failed).toBe(1);
+        const updatedJob = memoryJobStore.get(job.id);
+        expect(updatedJob?.status).toBe('failed');
+        expect(updatedJob?.attempts).toBe(1);
+        expect(updatedJob?.failedReason).toContain('Permanent database constraint');
+        errorSpy.mockRestore();
+    });
+    it('prioritizes high priority jobs before lower priority jobs', async () => {
+        const order = [];
+        const worker = defineWorker('priority-test', async (payload) => {
+            order.push(payload.label);
+        });
+        const runner = createJobRunner({
+            workers: [worker],
+            batchSize: 5
+        });
+        await enqueueJob('priority-test', { label: 'low' }, { priority: 0 });
+        await enqueueJob('priority-test', { label: 'high' }, { priority: 10 });
+        await enqueueJob('priority-test', { label: 'medium' }, { priority: 5 });
+        await runner.processNextBatch();
+        expect(order).toEqual(['high', 'medium', 'low']);
+    });
+    it('skips scheduled delayed jobs until their runAt threshold has passed', async () => {
+        const worker = defineWorker('delayed-test', async () => { });
+        const runner = createJobRunner({ workers: [worker] });
+        // Schedule 1 hour in future
+        await enqueueJob('delayed-test', {}, { delay: '1h' });
+        const result = await runner.processNextBatch();
+        expect(result.processed).toBe(0);
+    });
+    it('starts and stops continuous background polling cleanly', () => {
+        const runner = createJobRunner({
+            workers: [],
+            pollIntervalMs: 100
+        });
+        expect(runner.isRunning()).toBe(false);
+        runner.start();
+        expect(runner.isRunning()).toBe(true);
+        runner.stop();
+        expect(runner.isRunning()).toBe(false);
+    });
+});

package/dist/server/jobs/queue.d.ts

@@ -0,0 +1,14 @@
+import type { EnqueueJobOptions, JobDelay, JobRecord } from './types';
+/**
+ * Parses delay specifier ('5m', '30s', '2h', number ms, Date) into an absolute Date.
+ */
+export declare function parseJobDelay(delay?: JobDelay): Date;
+/**
+ * In-memory fallback job store for unit testing or serverless instances without DB setup.
+ */
+export declare const memoryJobStore: Map<string, JobRecord<any>>;
+/**
+ * Enqueues a background job for asynchronous execution.
+ * Supports delayed scheduling, priority, custom partitions, and the Transactional Outbox pattern.
+ */
+export declare function enqueueJob<TPayload = any>(name: string, payload: TPayload, options?: EnqueueJobOptions): Promise<JobRecord<TPayload>>;

package/dist/server/jobs/queue.js

@@ -0,0 +1,90 @@
+import { schemaPg, schemaSqlite } from '../db';
+/**
+ * Parses delay specifier ('5m', '30s', '2h', number ms, Date) into an absolute Date.
+ */
+export function parseJobDelay(delay) {
+    const now = Date.now();
+    if (!delay) {
+        return new Date(now);
+    }
+    if (delay instanceof Date) {
+        return delay;
+    }
+    if (typeof delay === 'number') {
+        return new Date(now + Math.max(0, delay));
+    }
+    if (typeof delay === 'string') {
+        const match = delay.trim().match(/^(\d+(?:\.\d+)?)\s*(s|m|h|d|ms)?$/i);
+        if (match) {
+            const value = parseFloat(match[1]);
+            const unit = (match[2] || 'ms').toLowerCase();
+            const multipliers = {
+                s: 1000,
+                m: 60 * 1000,
+                h: 60 * 60 * 1000,
+                d: 24 * 60 * 60 * 1000,
+                ms: 1
+            };
+            const multiplier = multipliers[unit] ?? 1;
+            return new Date(now + Math.round(value * multiplier));
+        }
+    }
+    return new Date(now);
+}
+/**
+ * In-memory fallback job store for unit testing or serverless instances without DB setup.
+ */
+export const memoryJobStore = new Map();
+/**
+ * Enqueues a background job for asynchronous execution.
+ * Supports delayed scheduling, priority, custom partitions, and the Transactional Outbox pattern.
+ */
+export async function enqueueJob(name, payload, options = {}) {
+    const id = `job_${Date.now()}_${Math.random().toString(36).slice(2, 9)}`;
+    const queue = options.queue || 'default';
+    const priority = options.priority ?? 0;
+    const maxAttempts = options.maxAttempts ?? 3;
+    const runAt = parseJobDelay(options.delay);
+    const now = new Date();
+    const jobRecord = {
+        id,
+        queue,
+        name,
+        payload,
+        status: 'pending',
+        priority,
+        attempts: 0,
+        maxAttempts,
+        runAt,
+        createdAt: now,
+        updatedAt: now
+    };
+    // Save to in-memory store
+    memoryJobStore.set(id, jobRecord);
+    const client = options.tx || options.db;
+    if (client) {
+        try {
+            const payloadString = JSON.stringify(payload);
+            // Determine table schema (detect postgres vs sqlite table)
+            const table = client?.schema?.job || schemaPg.job || schemaSqlite.job;
+            await client.insert(table).values({
+                id,
+                queue,
+                name,
+                payload: payloadString,
+                status: 'pending',
+                priority,
+                attempts: 0,
+                maxAttempts,
+                runAt,
+                createdAt: now,
+                updatedAt: now
+            });
+        }
+        catch (err) {
+            // In case DB insert fails, log error
+            console.error(`[JobQueue] Failed to persist job "${name}" (${id}) to database:`, err);
+        }
+    }
+    return jobRecord;
+}

package/dist/server/jobs/runner.d.ts

@@ -0,0 +1,12 @@
+import type { JobRunner, JobRunnerOptions, WorkerDefinition, WorkerHandler } from './types';
+/**
+ * Declares a typed worker handler for a specific job name.
+ */
+export declare function defineWorker<TPayload = any>(name: string, handler: WorkerHandler<TPayload>, options?: {
+    queue?: string;
+}): WorkerDefinition<TPayload>;
+/**
+ * Creates an embedded job runner capable of executing pending jobs either on-demand
+ * (for serverless cron invocations) or continuously in the background (for Node.js servers).
+ */
+export declare function createJobRunner(options: JobRunnerOptions): JobRunner;

package/dist/server/jobs/runner.js

@@ -0,0 +1,176 @@
+import { memoryJobStore } from './queue';
+/**
+ * Declares a typed worker handler for a specific job name.
+ */
+export function defineWorker(name, handler, options = {}) {
+    return {
+        name,
+        handler,
+        queue: options.queue || 'default'
+    };
+}
+/**
+ * Calculates exponential backoff delay with jitter.
+ */
+function calculateBackoffDelay(attempt) {
+    const baseDelay = Math.min(3600000, Math.pow(2, attempt) * 1000);
+    const jitter = Math.floor(Math.random() * 500);
+    return baseDelay + jitter;
+}
+/**
+ * Creates an embedded job runner capable of executing pending jobs either on-demand
+ * (for serverless cron invocations) or continuously in the background (for Node.js servers).
+ */
+export function createJobRunner(options) {
+    const queue = options.queue || 'default';
+    const batchSize = options.batchSize || 10;
+    const pollIntervalMs = options.pollIntervalMs || 3000;
+    const lockTimeoutMs = options.lockTimeoutMs || 5 * 60 * 1000;
+    const workerId = options.workerId || `worker_${Date.now()}_${Math.random().toString(36).slice(2, 7)}`;
+    // Index worker handlers by name
+    const workerMap = new Map();
+    for (const worker of options.workers) {
+        workerMap.set(worker.name, worker.handler);
+    }
+    let activeTimer = null;
+    let isRunning = false;
+    let isProcessing = false;
+    /**
+     * Leases next batch of jobs from memory or database.
+     */
+    const leaseNextBatch = async () => {
+        const now = Date.now();
+        const leased = [];
+        // 1. Process from memory store
+        const candidates = Array.from(memoryJobStore.values()).filter((job) => {
+            if (job.queue !== queue)
+                return false;
+            const isReady = job.runAt.getTime() <= now;
+            const isPending = job.status === 'pending' && isReady;
+            const isStaleLocked = job.status === 'processing' && job.lockedAt && now - job.lockedAt.getTime() > lockTimeoutMs;
+            return isPending || isStaleLocked;
+        });
+        // Sort by priority DESC, runAt ASC
+        candidates.sort((a, b) => {
+            if (b.priority !== a.priority)
+                return b.priority - a.priority;
+            return a.runAt.getTime() - b.runAt.getTime();
+        });
+        const batch = candidates.slice(0, batchSize);
+        for (const job of batch) {
+            job.status = 'processing';
+            job.lockedAt = new Date(now);
+            job.lockedBy = workerId;
+            job.updatedAt = new Date(now);
+            leased.push(job);
+        }
+        return leased;
+    };
+    /**
+     * Processes the next batch of pending jobs.
+     */
+    const processNextBatch = async () => {
+        if (isProcessing) {
+            return { processed: 0, succeeded: 0, failed: 0 };
+        }
+        isProcessing = true;
+        let succeeded = 0;
+        let failed = 0;
+        try {
+            const batch = await leaseNextBatch();
+            for (const job of batch) {
+                const handler = workerMap.get(job.name);
+                if (!handler) {
+                    console.warn(`[JobRunner] No worker handler registered for job "${job.name}" (${job.id}). Leaving pending.`);
+                    job.status = 'pending';
+                    job.lockedAt = null;
+                    job.lockedBy = null;
+                    continue;
+                }
+                const logger = {
+                    info: (msg, ...args) => console.log(`[JobRunner:${job.name}:${job.id}] ${msg}`, ...args),
+                    warn: (msg, ...args) => console.warn(`[JobRunner:${job.name}:${job.id}] ${msg}`, ...args),
+                    error: (msg, ...args) => console.error(`[JobRunner:${job.name}:${job.id}] ${msg}`, ...args)
+                };
+                try {
+                    await handler(job.payload, { job, logger });
+                    // Mark completed
+                    const now = new Date();
+                    job.status = 'completed';
+                    job.completedAt = now;
+                    job.updatedAt = now;
+                    job.lockedAt = null;
+                    job.lockedBy = null;
+                    succeeded++;
+                }
+                catch (err) {
+                    const now = new Date();
+                    job.attempts += 1;
+                    job.lockedAt = null;
+                    job.lockedBy = null;
+                    job.failedReason = err?.message || String(err);
+                    job.updatedAt = now;
+                    if (job.attempts < job.maxAttempts) {
+                        // Exponential backoff retry
+                        const delayMs = calculateBackoffDelay(job.attempts);
+                        job.status = 'pending';
+                        job.runAt = new Date(Date.now() + delayMs);
+                        logger.warn(`Job execution failed (Attempt ${job.attempts}/${job.maxAttempts}). Retrying in ${Math.round(delayMs / 1000)}s: ${job.failedReason}`);
+                    }
+                    else {
+                        // Exceeded max attempts: Route to Dead Letter Queue (DLQ)
+                        job.status = 'failed';
+                        failed++;
+                        logger.error(`Job failed permanently after ${job.attempts} attempts. Routed to Dead Letter Queue: ${job.failedReason}`);
+                    }
+                }
+            }
+            return {
+                processed: batch.length,
+                succeeded,
+                failed
+            };
+        }
+        finally {
+            isProcessing = false;
+        }
+    };
+    /**
+     * Continuous background polling loop.
+     */
+    const poll = async () => {
+        if (!isRunning)
+            return;
+        try {
+            await processNextBatch();
+        }
+        catch (err) {
+            console.error('[JobRunner] Unexpected error during polling cycle:', err);
+        }
+        finally {
+            if (isRunning) {
+                activeTimer = setTimeout(poll, pollIntervalMs);
+                if (activeTimer && typeof activeTimer === 'object' && 'unref' in activeTimer) {
+                    activeTimer.unref();
+                }
+            }
+        }
+    };
+    return {
+        processNextBatch,
+        start: () => {
+            if (isRunning)
+                return;
+            isRunning = true;
+            poll();
+        },
+        stop: () => {
+            isRunning = false;
+            if (activeTimer) {
+                clearTimeout(activeTimer);
+                activeTimer = null;
+            }
+        },
+        isRunning: () => isRunning
+    };
+}