@halsystems/red-bacnet 1.4.6 → 2.0.0-alpha.0

package/CHANGELOG.md

@@ -1,6 +1,10 @@
 # Changelog
 
-## [1.4.6]
+## [2.0.0-alpha.0]
+### Changed
+- Replaced independent node `CoalescedJobQueue` with global queue with priority
+
+## [1.4.7]
 ### Added
 - Added CICD workflow
 

package/ROOT

@@ -0,0 +1 @@
+ROOT

package/common/core/constant.js

@@ -27,6 +27,7 @@ module.exports = {
     ERR_WRITE_POINT_INVALID_PRIORITY: 'Write point invalid priority',
     ERR_EMPTY_DATA: 'Empty data',
     ERR_WRITING_POINT: 'Error writing point',
+    ERR_GLOBAL_QUEUE_WORKER_ERROR: 'Global queue worker error',
 
     // job error
     ERR_CONSTRUCT_ABSTRACT_JOB: 'Cannot construct abstract Job class',

package/common/job/core.js

@@ -7,86 +7,221 @@ const {
     ERR_ONSTOP_NOT_IMPLEMENTED, ERR_EXECUTE_NOT_IMPLEMENTED
 } = require('@root/common/core/constant.js')
 
-// ---------------------------------- export ----------------------------------
-module.exports = {
-    BaseJob: class {
-        constructor() {
-            if (new.target === module.exports.BaseJob) {
-                throw new TypeError(ERR_CONSTRUCT_ABSTRACT_JOB);
-            }
+/**
+ * Abstract base class for job implementations.
+ *
+ * This is an abstract class that cannot be instantiated directly. Subclasses must implement
+ * the lifecycle methods: onStart(), execute(), and onStop().
+ *
+ * @abstract
+ * @class BaseJob
+ * @example
+ * class MyJob extends BaseJob {
+ *     async onStart() {
+ *         // Initialize job resources
+ *     }
+ *
+ *     async execute() {
+ *         // Perform the job's main work
+ *     }
+ *
+ *     async onStop() {
+ *         // Clean up job resources
+ *     }
+ * }
+ */
+class BaseJob {
+    /**
+     * Creates a new BaseJob instance.
+     *
+     * @constructor
+     * @throws {TypeError} If attempting to instantiate BaseJob directly (must subclass it).
+     */
+    constructor() {
+        if (new.target === BaseJob) {
+            throw new TypeError(ERR_CONSTRUCT_ABSTRACT_JOB);
         }
+    }
 
-        async onStart() {
-            throw new Error(ERR_ONSTART_NOT_IMPLEMENTED);
-        }
+    /**
+     * Lifecycle method called when the job starts.
+     *
+     * Subclasses should override this method to perform initialization tasks such as
+     * setting up resources, connections, or state.
+     *
+     * @async
+     * @returns {Promise<void>}
+     * @throws {Error} If not implemented by subclass.
+     */
+    async onStart() {
+        throw new Error(ERR_ONSTART_NOT_IMPLEMENTED);
+    }
 
-        async execute() {
-            throw new Error(ERR_EXECUTE_NOT_IMPLEMENTED);
-        }
+    /**
+     * Main execution method for the job.
+     *
+     * Subclasses must override this method to implement the core job logic.
+     * This method is called by the job queue to execute the job's work.
+     *
+     * @async
+     * @returns {Promise<void>}
+     * @throws {Error} If not implemented by subclass.
+     */
+    async execute() {
+        throw new Error(ERR_EXECUTE_NOT_IMPLEMENTED);
+    }
 
-        async onStop() {
-            throw new Error(ERR_ONSTOP_NOT_IMPLEMENTED);
-        }
-    },
+    /**
+     * Lifecycle method called when the job stops.
+     *
+     * Subclasses should override this method to perform cleanup tasks such as
+     * closing connections, releasing resources, or saving state.
+     *
+     * @async
+     * @returns {Promise<void>}
+     * @throws {Error} If not implemented by subclass.
+     */
+    async onStop() {
+        throw new Error(ERR_ONSTOP_NOT_IMPLEMENTED);
+    }
+}
 
-    CoalescedJobQueue: class {
-        isRunning = false
+/**
+ * A priority-based job queue that coalesces duplicate jobs.
+ *
+ * This class manages a queue of jobs that are executed asynchronously with support for:
+ * - Priority-based execution (lower priority number = higher execution priority)
+ * - Job coalescing (duplicate job IDs are not added to the queue)
+ * - FIFO ordering for jobs with equal priority
+ * - Configurable delay between job processing cycles
+ *
+ * @class CoalescedJobQueue
+ * @example
+ * const queue = new CoalescedJobQueue(1000, true, 5);
+ * queue.addJob({ id: 'job1', task: myJobInstance, priority: 2 });
+ * queue.addJob({ id: 'job2', task: anotherJobInstance, priority: 5 });
+ * await queue.run(); // Starts processing jobs indefinitely
+ */
+class CoalescedJobQueue {
+    /**
+     * Whether the job queue is currently running.
+     * @type {boolean}
+     */
+    isRunning = false
 
-        /**
-         * Create a new CoalescedJob.
-         * @param {number} [delay=1000] - Delay in milliseconds between coalesced job runs.
-         * @param {boolean} [showLog=true] - Whether to log coalesced jobs.
-         */
-        constructor(delay = 1000, showLog = true,) {
-            this.queue = [];
-            this.delay = delay;
-            this.showLog = showLog;
-        }
+    /**
+     * Creates a new CoalescedJobQueue instance.
+     *
+     * @constructor
+     * @param {number} [delay=100] - Delay in milliseconds between job processing cycles.
+     * @param {boolean} [showLog=true] - Whether to log when jobs are coalesced (duplicate IDs).
+     * @param {number} [defaultPriority=10] - Default priority for jobs when not specified (0-10, lower = higher priority).
+     */
+    constructor(delay = 100, showLog = true, defaultPriority = 10) {
+        this.queue = [];
+        this.delay = delay;
+        this.showLog = showLog;
+        this.defaultPriority = defaultPriority;
+    }
 
-        /**
-         * Start indefinitely running the first job in the queue.
-         * If there are no jobs in the queue, wait for the delay before checking again.
-         * @async
-         */
-        async run() {
-            this.isRunning = true;
-            while (this.isRunning) {
-                if (this.queue.length > 0) {
-                    const job = this.queue.shift();
-                    try {
-                        await job.task.execute();
-                    } catch (error) {
-                        console.error(`Error executing job ${job.id}:`, error);
+    /**
+     * Starts indefinitely running jobs from the queue.
+     *
+     * Continuously processes jobs in the queue until stop() is called. Jobs are executed
+     * in priority order (lower priority number = higher execution priority). If multiple
+     * jobs have the same priority, they are executed in FIFO order (earliest first).
+     * If the queue is empty, waits for the configured delay before checking again.
+     *
+     * @async
+     * @returns {Promise<void>}
+     * @example
+     * const queue = new CoalescedJobQueue();
+     * // Start the queue in the background
+     * queue.run().catch(err => console.error('Queue error:', err));
+     * // Add jobs...
+     * // Later, stop the queue
+     * queue.stop();
+     */
+    async run() {
+        this.isRunning = true;
+        while (this.isRunning) {
+            if (this.queue.length > 0) {
+                // Get the job with the lowest priority number (highest priority)
+                // If priorities are equal, use FIFO (earliest timestamp first)
+                const jobIndex = this.queue.reduce((minIndex, job, index) => {
+                    const minJob = this.queue[minIndex];
+                    if (job.priority < minJob.priority) {
+                        return index;
+                    } else if (job.priority === minJob.priority && job.timestamp < minJob.timestamp) {
+                        return index;
                     }
+                    return minIndex;
+                }, 0);
+
+                const job = this.queue.splice(jobIndex, 1)[0];
+                try {
+                    await job.task.execute();
+                } catch (error) {
+                    console.error(`Error executing job ${job.id}:`, error);
                 }
-                await new Promise(resolve => setTimeout(resolve, this.delay));
             }
+            await new Promise(resolve => setTimeout(resolve, this.delay));
         }
+    }
 
-        /**
-         * Add a job to the queue.
-         * If the job with the same id is already in the queue, do not add it.
-         * If showLog is true, log a message when a job is coalesced.
-         * @param {Object} job - { id: string, task: BaseJob }
-         */
-        addJob(job) {
-            if (this.queue.map(item => item.id).includes(job.id)) {
-                if (this.showLog)
-                    print(`Coalesced job: ${job.id}`, true)
-                return
-            }
-
-            this.queue.push({
-                id: job.id,
-                task: job.task
-            })
+    /**
+     * Adds a job to the queue with optional priority.
+     *
+     * If a job with the same ID already exists in the queue, it will not be added again
+     * (job coalescing). If showLog is enabled, a message will be logged when a job is coalesced.
+     *
+     * @param {Object} job - The job object to add to the queue.
+     * @param {string} job.id - Unique identifier for the job. Duplicate IDs will be coalesced.
+     * @param {Object} job.task - The job task instance (must be a subclass of BaseJob).
+     * @param {number} [job.priority] - Priority level for execution (0-10, lower = higher priority).
+     *                                   If not specified, uses this.defaultPriority.
+     * @returns {void}
+     * @example
+     * queue.addJob({
+     *     id: 'discover-points',
+     *     task: new DiscoverPointsJob(),
+     *     priority: 3
+     * });
+     */
+    addJob(job) {
+        if (this.queue.map(item => item.id).includes(job.id)) {
+            if (this.showLog)
+                print(`Coalesced job: ${job.id}`, true)
+            return
         }
 
-        /**
-         * Stops the job queue process.
-         */
-        stop() {
-            this.isRunning = false;
-        }
+        const priority = typeof job.priority === 'number' ? job.priority : this.defaultPriority;
+
+        this.queue.push({
+            id: job.id,
+            task: job.task,
+            priority: priority,
+            timestamp: Date.now()
+        })
     }
-}
+
+    /**
+     * Stops the job queue process.
+     *
+     * Sets isRunning to false, which will cause the run() loop to exit after the current
+     * job completes and the next delay cycle finishes.
+     *
+     * @returns {void}
+     * @example
+     * queue.stop();
+     */
+    stop() {
+        this.isRunning = false;
+    }
+}
+
+// ---------------------------------- export ----------------------------------
+module.exports = {
+    BaseJob,
+    CoalescedJobQueue
+};

package/common/job/global_queue_manager.js

@@ -0,0 +1,112 @@
+'use strict';
+
+require('./_alias.js');
+
+const { CoalescedJobQueue } = require('@root/common/job/core.js');
+const { ERR_GLOBAL_QUEUE_WORKER_ERROR } = require('@root/common/core/constant.js');
+
+// ---------------------------------- Singleton State ----------------------------------
+let globalQueue = null;
+let workerPromise = null;
+let workerRunning = false;
+let stopping = false;
+
+// ---------------------------------- Worker Control ----------------------------------
+function startWorker() {
+    if (!globalQueue || stopping || workerRunning) return;
+
+    workerRunning = true;
+
+    const loop = async () => {
+        try {
+            await globalQueue.run();
+        } catch (error) {
+            console.error(`${ERR_GLOBAL_QUEUE_WORKER_ERROR}:`, error);
+        } finally {
+            workerRunning = false;
+            workerPromise = null;
+        }
+
+        // Self-healing: restart after short delay if still active
+        if (globalQueue && !stopping) {
+            await new Promise((resolve) => setTimeout(resolve, 1000));
+            startWorker();
+        }
+    };
+
+    workerPromise = loop();
+}
+
+// ---------------------------------- Teardown Helper ----------------------------------
+/**
+ * Shared teardown logic used by both shutdown() and reset().
+ * Returns a promise that resolves once any in-flight worker has finished.
+ */
+async function teardown() {
+    stopping = true;
+
+    if (globalQueue) {
+        globalQueue.stop();
+        globalQueue = null;
+    }
+
+    // Await in-flight work rather than abandoning it
+    if (workerPromise) {
+        try {
+            await workerPromise;
+        } catch {
+            // Worker errors are already logged inside loop(); swallow here
+        }
+    }
+
+    workerPromise = null;
+    workerRunning = false;
+}
+
+// ---------------------------------- Module Exports ----------------------------------
+module.exports = {
+    /**
+     * Get or create the global queue singleton.
+     * Safe to call multiple times; starts the worker if not already running.
+     */
+    getQueue() {
+        if (!globalQueue) {
+            stopping = false;
+            globalQueue = new CoalescedJobQueue(100, true, 5);
+        }
+
+        if (!globalQueue.isRunning && !stopping) {
+            startWorker();
+        }
+
+        return globalQueue;
+    },
+
+    /**
+     * Initialize queue (Node-RED startup hook).
+     */
+    async initialize() {
+        this.getQueue();
+    },
+
+    /**
+     * Graceful shutdown. Stops the queue and awaits any in-flight worker.
+     * After this, the module is inert until getQueue() is called again.
+     *
+     * @returns {Promise<void>}
+     */
+    async shutdown() {
+        await teardown();
+    },
+
+    /**
+     * Full cycle reset (testing utility).
+     * Tears down the current queue and immediately initialises a fresh one.
+     *
+     * @returns {Promise<void>}
+     */
+    async reset() {
+        await teardown();
+        this.getQueue();
+    },
+};

package/jsconfig.json

@@ -2,7 +2,6 @@
     "compilerOptions": {
         "module": "commonjs",
         "target": "ES2022",
-        "baseUrl": ".",
         "paths": {
             "@root/*": ["./*"],
             "@tests/*": ["./tests/*"]

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@halsystems/red-bacnet",
-  "version": "1.4.6",
+  "version": "2.0.0-alpha.0",
   "publishConfig": {
     "registry": "https://registry.npmjs.org/",
     "access": "public"

package/red-bacnet/discover_device.html

@@ -82,6 +82,12 @@
 
             <dt class="optional">msg.highLimit <span class="property-type">number</span></dt>
             <dd>Default config will be used if not configured.</dd>
+
+            <dt class="optional">msg.id <span class="property-type">string | number</span></dt>
+            <dd> Job ID. Default to <code>discoverDevices</code> if not provided.</dd>
+
+            <dt class="optional">msg.priority <span class="property-type">number</span></dt>
+            <dd> Job priority in queue. Default to <code>5</code> if not provided.</dd>
         </dl>
 
     <h3>Outputs</h3>

package/red-bacnet/discover_device.js

@@ -6,7 +6,7 @@ const EventEmitter = require('events');
 const { print } = require('@root/common/core/util.js')
 const { nowFormatted } = require('@root/common/core/util.js')
 const { DiscoverDeviceJob } = require('@root/common/job/discover_device.js')
-const { CoalescedJobQueue } = require('@root/common/job/core.js')
+const { getQueue } = require('@root/common/job/global_queue_manager.js')
 const {
     EVENT_UPDATE_STATUS, EVENT_ERROR, EVENT_INPUT, EVENT_OUTPUT, EVENT_CLOSE
 } = require('@root/common/core/constant.js')
@@ -32,9 +32,8 @@ module.exports = function (RED) {
             // events
             this.#subscribeListeners();
 
-            // configure job queue
-            this.job = new CoalescedJobQueue();
-            this.job.run();
+            // configure job queue - use global queue
+            this.job = getQueue();
 
             // init task
             this.task = new DiscoverDeviceJob(
@@ -59,9 +58,12 @@ module.exports = function (RED) {
                 as a result, workaround is introduce before strategy to reuse discoverDeviceJob instead
                 of creating new one every time onInput is triggered
                 */
-                if (this.job.queue.length > 0) {
-                    print('Coalesced job: discoverDevices', true)
-                    return
+                const jobId = (typeof msg.id === 'string' || typeof msg.id === 'number') ? msg.id : 'discoverDevices';
+
+                if (this.job.queue.map(item => item.id).includes(jobId)) {
+                    // @ts-ignore
+                    print(`Coalesced job: ${jobId}`, true)
+                    return;
                 }
 
                 this.task.network = (msg.network === undefined) ? this.network : msg.network;
@@ -69,9 +71,12 @@ module.exports = function (RED) {
                 this.task.highLimit = (msg.highLimit === undefined) ? this.highLimit : msg.highLimit;
 
                 this.job.addJob({
-                    id: (typeof msg.id === 'string' || typeof msg.id === 'number') ? msg.id : 'task',
-                    task: this.task
+                    id: jobId,
+                    task: this.task,
+                    priority: Number.isFinite(msg.priority) ? msg.priority : 5,
                 });
+                // @ts-ignore
+                this.status({ fill: 'yellow', shape: 'dot', text: `in queue` });
             });
 
             // @ts-ignore

package/red-bacnet/discover_point.html

@@ -101,7 +101,9 @@
             <dt>msg.devices <span class="property-type">array</span></dt>
                 <dd> A list of devices generated from discover device node (modify values if required)</dd>
             <dt class="optional">msg.id <span class="property-type">string | number</span></dt>
-                <dd> Job ID. Default to <code>task</code> if not provided.</dd>
+                <dd> Job ID. Default to <code>discoverPoints</code> if not provided.</dd>
+            <dt class="optional">msg.priority <span class="property-type">number</span></dt>
+                <dd> Job priority in queue. Default to <code>5</code> if not provided.</dd>
         </dl>
 
     <h3>Outputs</h3>

package/red-bacnet/discover_point.js

@@ -3,9 +3,10 @@ require('./_alias.js');
 
 const EventEmitter = require('events');
 
+const { print } = require('@root/common/core/util.js')
 const { nowFormatted } = require('@root/common/core/util.js')
 const { DiscoverPointJob } = require('@root/common/job/discover_point.js')
-const { CoalescedJobQueue } = require('@root/common/job/core.js')
+const { getQueue } = require('@root/common/job/global_queue_manager.js')
 const {
     EVENT_UPDATE_STATUS, EVENT_ERROR, EVENT_INPUT, EVENT_OUTPUT
 } = require('@root/common/core/constant.js')
@@ -30,9 +31,8 @@ module.exports = function (RED) {
             // events
             this.#subscribeListeners();
 
-            // configure job queue
-            this.job = new CoalescedJobQueue();
-            this.job.run();
+            // configure job queue - use global queue
+            this.job = getQueue();
         }
 
         #subscribeListeners() {
@@ -41,6 +41,14 @@ module.exports = function (RED) {
             */
             // @ts-ignore
             this.on(EVENT_INPUT, async function (msg) {
+                const jobId = (typeof msg.id === 'string' || typeof msg.id === 'number') ? msg.id : 'discoverPoints';
+
+                if (this.job.queue.map(item => item.id).includes(jobId)) {
+                    // @ts-ignore
+                    print(`Coalesced job: ${jobId}`, true)
+                    return;
+                }
+
                 const task = new DiscoverPointJob(
                     this.client, this.#eventEmitter, msg?.devices, this.discoverMode, this.readMethod,
                     this.groupExportDeviceCount, this.maxConcurrentDeviceRead,
@@ -48,9 +56,12 @@ module.exports = function (RED) {
                 );
 
                 this.job.addJob({
-                    id: (typeof msg.id === 'string' || typeof msg.id === 'number') ? msg.id : 'task',
-                    task: task
+                    id: jobId,
+                    task: task,
+                    priority: Number.isFinite(msg.priority) ? msg.priority : 5,
                 });
+                // @ts-ignore
+                this.status({ fill: 'yellow', shape: 'dot', text: `in queue` });
             });
 
             this.#eventEmitter.on(EVENT_OUTPUT, (data) => {

package/red-bacnet/read_point.html

@@ -88,7 +88,10 @@
             <dd> A list of points generated from discover point node (modify values if required)</dd>
 
             <dt class="optional">msg.id <span class="property-type">string | number</span></dt>
-            <dd> Job ID. Default to <code>task</code> if not provided.</dd>
+            <dd> Job ID. Default to <code>readPoints</code> if not provided.</dd>
+
+            <dt class="optional">msg.priority <span class="property-type">number</span></dt>
+            <dd> Job priority in queue. Default to <code>2</code> if not provided.</dd>
         </dl>
 
     <h3>Outputs</h3>

package/red-bacnet/read_point.js

@@ -3,9 +3,10 @@ require('./_alias.js');
 
 const EventEmitter = require('events');
 
+const { print } = require('@root/common/core/util.js')
 const { nowFormatted } = require('@root/common/core/util.js')
 const { ReadPointJob } = require('@root/common/job/read_point.js')
-const { CoalescedJobQueue } = require('@root/common/job/core.js')
+const { getQueue } = require('@root/common/job/global_queue_manager.js')
 const {
     EVENT_UPDATE_STATUS, EVENT_ERROR, EVENT_INPUT, EVENT_OUTPUT
 } = require('@root/common/core/constant.js')
@@ -29,9 +30,8 @@ module.exports = function (RED) {
             // events
             this.#subscribeListeners();
 
-            // configure job queue
-            this.job = new CoalescedJobQueue();
-            this.job.run();
+            // configure job queue - use global queue
+            this.job = getQueue();
         }
 
         #subscribeListeners() {
@@ -51,10 +51,21 @@ module.exports = function (RED) {
                     this.concurrentTaskDelay
                 );
 
+                const jobId = (typeof msg.id === 'string' || typeof msg.id === 'number') ? msg.id : 'readPoints';
+
+                if (this.job.queue.map(item => item.id).includes(jobId)) {
+                    // @ts-ignore
+                    print(`Coalesced job: ${jobId}`, true)
+                    return;
+                }
+
                 this.job.addJob({
-                    id: (typeof msg.id === 'string' || typeof msg.id === 'number') ? msg.id : 'task',
-                    task: task
+                    id: jobId,
+                    task: task,
+                    priority: Number.isFinite(msg.priority) ? msg.priority : 2,
                 });
+                // @ts-ignore
+                this.status({ fill: 'yellow', shape: 'dot', text: `in queue` });
             });
 
             this.#eventEmitter.on(EVENT_OUTPUT, (data) => {

package/red-bacnet/write_point.html

@@ -76,7 +76,10 @@
             <dd> Eg: {'VAV_1.ZoneTemp_SP': 21.5, ...}</dd>
 
             <dt class="optional">msg.id <span class="property-type">string | number</span></dt>
-            <dd> Job ID. Default to <code>task</code> if not provided.</dd>
+            <dd> Job ID. Default to <code>writePoints</code> if not provided.</dd>
+
+            <dt class="optional">msg.priority <span class="property-type">number</span></dt>
+            <dd> Job priority in queue. Default to <code>2</code> if not provided.</dd>
         </dl>
 
     <h3>Details</h3>

package/red-bacnet/write_point.js

@@ -3,9 +3,10 @@ require('./_alias.js');
 
 const EventEmitter = require('events');
 
+const { print } = require('@root/common/core/util.js')
 const { nowFormatted } = require('@root/common/core/util.js')
 const { WritePointJob } = require('@root/common/job/write_point.js')
-const { CoalescedJobQueue } = require('@root/common/job/core.js')
+const { getQueue } = require('@root/common/job/global_queue_manager.js')
 const {
     EVENT_UPDATE_STATUS, EVENT_ERROR, EVENT_INPUT, EVENT_OUTPUT
 } = require('@root/common/core/constant.js')
@@ -28,9 +29,8 @@ module.exports = function (RED) {
             // events
             this.#subscribeListeners();
 
-            // configure job queue
-            this.job = new CoalescedJobQueue();
-            this.job.run();
+            // configure job queue - use global queue
+            this.job = getQueue();
         }
 
         #subscribeListeners() {
@@ -49,11 +49,21 @@ module.exports = function (RED) {
                     this.maxConcurrentPointWrite,
                     this.concurrentTaskDelay
                 );
+                const jobId = (typeof msg.id === 'string' || typeof msg.id === 'number') ? msg.id : 'writePoints';
+
+                if (this.job.queue.map(item => item.id).includes(jobId)) {
+                    // @ts-ignore
+                    print(`Coalesced job: ${jobId}`, true)
+                    return;
+                }
 
                 this.job.addJob({
-                    id: (typeof msg.id === 'string' || typeof msg.id === 'number') ? msg.id : 'task',
-                    task: task
+                    id: jobId,
+                    task: task,
+                    priority: Number.isFinite(msg.priority) ? msg.priority : 2,
                 });
+                // @ts-ignore
+                this.status({ fill: 'yellow', shape: 'dot', text: `in queue` });
             });
 
             this.#eventEmitter.on(EVENT_OUTPUT, (data) => {