@sidequest/engine 1.15.1 → 1.16.0

package/dist/workers/worker-runtime.cjs

@@ -0,0 +1,88 @@
+'use strict';
+
+var core = require('@sidequest/core');
+var nodeCron = require('node-cron');
+var dispatcher = require('../execution/dispatcher.cjs');
+var executorManager = require('../execution/executor-manager.cjs');
+var queueManager = require('../execution/queue-manager.cjs');
+var cleanupFinishedJob = require('../routines/cleanup-finished-job.cjs');
+var releaseStaleJobs = require('../routines/release-stale-jobs.cjs');
+
+/**
+ * Owns the runtime side of the engine: the dispatcher loop plus the stale-job and finished-job
+ * cron routines.
+ *
+ * It runs either inside the forked worker process (driven by {@link MainWorker}) or directly in the
+ * host process when the engine is started with `fork: false`. It does NOT own the backend
+ * lifecycle: closing the backend remains the responsibility of the {@link Engine} that created it.
+ */
+class WorkerRuntime {
+    backend;
+    config;
+    dispatcher;
+    cronTasks = [];
+    /**
+     * Creates a new WorkerRuntime.
+     * @param backend The backend instance.
+     * @param config The non-nullable engine configuration.
+     */
+    constructor(backend, config) {
+        this.backend = backend;
+        this.config = config;
+        this.dispatcher = new dispatcher.Dispatcher(backend, new queueManager.QueueManager(backend, config.queues, config.queueDefaults), new executorManager.ExecutorManager(backend, config), config.jobPollingInterval);
+    }
+    /**
+     * Starts the dispatcher loop and the cron routines.
+     */
+    async start() {
+        this.dispatcher.start();
+        await this.startCron();
+    }
+    /**
+     * Stops the cron routines and drains the dispatcher. Unlike the forked worker (which relies on
+     * process exit), the in-process runtime must explicitly stop its cron tasks to avoid leaks.
+     */
+    async shutdown() {
+        core.logger("WorkerRuntime").debug("Stopping cron routines");
+        // ScheduledTask.stop() returns `void | Promise<void>`; normalize before aggregating.
+        await Promise.all(this.cronTasks.map((task) => Promise.resolve(task.stop())));
+        this.cronTasks = [];
+        core.logger("WorkerRuntime").debug("Stopping dispatcher");
+        await this.dispatcher.stop();
+    }
+    /**
+     * Schedules the stale-job and finished-job cron routines according to the config and runs each
+     * once immediately. Either routine can be disabled with a `false` interval.
+     */
+    async startCron() {
+        const promises = [];
+        if (this.config.releaseStaleJobsIntervalMin !== false) {
+            promises.push(this.scheduleAndRun(this.config.releaseStaleJobsIntervalMin, "ReleaseStaleJob", () => releaseStaleJobs.releaseStaleJobs(this.backend, this.config.releaseStaleJobsMaxStaleMs, this.config.releaseStaleJobsMaxClaimedMs)));
+        }
+        if (this.config.cleanupFinishedJobsIntervalMin !== false) {
+            promises.push(this.scheduleAndRun(this.config.cleanupFinishedJobsIntervalMin, "CleanupJob", () => cleanupFinishedJob.cleanupFinishedJobs(this.backend, this.config.cleanupFinishedJobsOlderThan)));
+        }
+        await Promise.all(promises).catch((error) => core.logger("WorkerRuntime").error(error));
+    }
+    /**
+     * Schedules a recurring task at the given minute interval, tracks it for shutdown, and triggers
+     * an immediate run.
+     */
+    scheduleAndRun(intervalMin, name, task) {
+        core.logger("WorkerRuntime").debug(`Starting ${name} cron with interval: ${intervalMin} minutes`);
+        const scheduled = nodeCron.schedule(`*/${intervalMin} * * * *`, async () => {
+            try {
+                core.logger("WorkerRuntime").debug(`Running ${name} task`);
+                await task();
+            }
+            catch (error) {
+                core.logger("WorkerRuntime").error(`Error on running ${name}!`, error);
+            }
+        });
+        this.cronTasks.push(scheduled);
+        return scheduled.execute();
+    }
+}
+
+exports.WorkerRuntime = WorkerRuntime;
+//# sourceMappingURL=worker-runtime.cjs.map

package/dist/workers/worker-runtime.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"worker-runtime.cjs","sources":["../../src/workers/worker-runtime.ts"],"sourcesContent":[null],"names":["Dispatcher","QueueManager","ExecutorManager","logger","releaseStaleJobs","cleanupFinishedJobs","cron"],"mappings":"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"}

package/dist/workers/worker-runtime.d.ts

@@ -0,0 +1,44 @@
+import { Backend } from '@sidequest/backend';
+import { NonNullableEngineConfig } from '../engine.js';
+
+/**
+ * Owns the runtime side of the engine: the dispatcher loop plus the stale-job and finished-job
+ * cron routines.
+ *
+ * It runs either inside the forked worker process (driven by {@link MainWorker}) or directly in the
+ * host process when the engine is started with `fork: false`. It does NOT own the backend
+ * lifecycle: closing the backend remains the responsibility of the {@link Engine} that created it.
+ */
+declare class WorkerRuntime {
+    private backend;
+    private config;
+    private dispatcher;
+    private cronTasks;
+    /**
+     * Creates a new WorkerRuntime.
+     * @param backend The backend instance.
+     * @param config The non-nullable engine configuration.
+     */
+    constructor(backend: Backend, config: NonNullableEngineConfig);
+    /**
+     * Starts the dispatcher loop and the cron routines.
+     */
+    start(): Promise<void>;
+    /**
+     * Stops the cron routines and drains the dispatcher. Unlike the forked worker (which relies on
+     * process exit), the in-process runtime must explicitly stop its cron tasks to avoid leaks.
+     */
+    shutdown(): Promise<void>;
+    /**
+     * Schedules the stale-job and finished-job cron routines according to the config and runs each
+     * once immediately. Either routine can be disabled with a `false` interval.
+     */
+    startCron(): Promise<void>;
+    /**
+     * Schedules a recurring task at the given minute interval, tracks it for shutdown, and triggers
+     * an immediate run.
+     */
+    private scheduleAndRun;
+}
+
+export { WorkerRuntime };

package/dist/workers/worker-runtime.js

@@ -0,0 +1,86 @@
+import { logger } from '@sidequest/core';
+import nodeCron from 'node-cron';
+import { Dispatcher } from '../execution/dispatcher.js';
+import { ExecutorManager } from '../execution/executor-manager.js';
+import { QueueManager } from '../execution/queue-manager.js';
+import { cleanupFinishedJobs } from '../routines/cleanup-finished-job.js';
+import { releaseStaleJobs } from '../routines/release-stale-jobs.js';
+
+/**
+ * Owns the runtime side of the engine: the dispatcher loop plus the stale-job and finished-job
+ * cron routines.
+ *
+ * It runs either inside the forked worker process (driven by {@link MainWorker}) or directly in the
+ * host process when the engine is started with `fork: false`. It does NOT own the backend
+ * lifecycle: closing the backend remains the responsibility of the {@link Engine} that created it.
+ */
+class WorkerRuntime {
+    backend;
+    config;
+    dispatcher;
+    cronTasks = [];
+    /**
+     * Creates a new WorkerRuntime.
+     * @param backend The backend instance.
+     * @param config The non-nullable engine configuration.
+     */
+    constructor(backend, config) {
+        this.backend = backend;
+        this.config = config;
+        this.dispatcher = new Dispatcher(backend, new QueueManager(backend, config.queues, config.queueDefaults), new ExecutorManager(backend, config), config.jobPollingInterval);
+    }
+    /**
+     * Starts the dispatcher loop and the cron routines.
+     */
+    async start() {
+        this.dispatcher.start();
+        await this.startCron();
+    }
+    /**
+     * Stops the cron routines and drains the dispatcher. Unlike the forked worker (which relies on
+     * process exit), the in-process runtime must explicitly stop its cron tasks to avoid leaks.
+     */
+    async shutdown() {
+        logger("WorkerRuntime").debug("Stopping cron routines");
+        // ScheduledTask.stop() returns `void | Promise<void>`; normalize before aggregating.
+        await Promise.all(this.cronTasks.map((task) => Promise.resolve(task.stop())));
+        this.cronTasks = [];
+        logger("WorkerRuntime").debug("Stopping dispatcher");
+        await this.dispatcher.stop();
+    }
+    /**
+     * Schedules the stale-job and finished-job cron routines according to the config and runs each
+     * once immediately. Either routine can be disabled with a `false` interval.
+     */
+    async startCron() {
+        const promises = [];
+        if (this.config.releaseStaleJobsIntervalMin !== false) {
+            promises.push(this.scheduleAndRun(this.config.releaseStaleJobsIntervalMin, "ReleaseStaleJob", () => releaseStaleJobs(this.backend, this.config.releaseStaleJobsMaxStaleMs, this.config.releaseStaleJobsMaxClaimedMs)));
+        }
+        if (this.config.cleanupFinishedJobsIntervalMin !== false) {
+            promises.push(this.scheduleAndRun(this.config.cleanupFinishedJobsIntervalMin, "CleanupJob", () => cleanupFinishedJobs(this.backend, this.config.cleanupFinishedJobsOlderThan)));
+        }
+        await Promise.all(promises).catch((error) => logger("WorkerRuntime").error(error));
+    }
+    /**
+     * Schedules a recurring task at the given minute interval, tracks it for shutdown, and triggers
+     * an immediate run.
+     */
+    scheduleAndRun(intervalMin, name, task) {
+        logger("WorkerRuntime").debug(`Starting ${name} cron with interval: ${intervalMin} minutes`);
+        const scheduled = nodeCron.schedule(`*/${intervalMin} * * * *`, async () => {
+            try {
+                logger("WorkerRuntime").debug(`Running ${name} task`);
+                await task();
+            }
+            catch (error) {
+                logger("WorkerRuntime").error(`Error on running ${name}!`, error);
+            }
+        });
+        this.cronTasks.push(scheduled);
+        return scheduled.execute();
+    }
+}
+
+export { WorkerRuntime };
+//# sourceMappingURL=worker-runtime.js.map

package/dist/workers/worker-runtime.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"worker-runtime.js","sources":["../../src/workers/worker-runtime.ts"],"sourcesContent":[null],"names":["cron"],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sidequest/engine",
-  "version": "1.15.1",
+  "version": "1.16.0",
   "description": "@sidequest/engine is the core engine of SideQuest, a distributed background job processing system for Node.js and TypeScript.",
   "keywords": [
     "nodejs",
@@ -42,12 +42,12 @@
   },
   "license": "LGPL-3.0-or-later",
   "dependencies": {
-    "@sidequest/backend": "1.15.1",
-    "@sidequest/core": "1.15.1",
+    "@sidequest/backend": "1.16.0",
+    "@sidequest/core": "1.16.0",
     "node-cron": "^4.2.1",
     "piscina": "^5.1.4"
   },
   "peerDependencies": {
-    "sidequest": "1.15.1"
+    "sidequest": "1.16.0"
   }
 }