@xacos/queue 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 XAOCS Team
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,17 @@
+# @xacos/queue
+
+> Part of the [XAOCS Framework](https://xaocs.dev) — full-stack TypeScript, built for AI-native development.
+
+## Install
+
+```bash
+bun add @xacos/queue
+```
+
+## Docs
+
+Full documentation at [xaocs.dev/docs/queue](https://xaocs.dev/docs/queue).
+
+## License
+
+MIT © XAOCS Team

package/dist/QueueManager.d.ts

@@ -0,0 +1,8 @@
+export interface QueueDriver {
+    push(job: import('./XJob').XJob): Promise<void> | void;
+}
+export declare function resolveQueueDriver(): QueueDriver;
+export declare class QueueManager {
+    static resolve(): QueueDriver;
+}
+//# sourceMappingURL=QueueManager.d.ts.map

package/dist/QueueManager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"QueueManager.d.ts","sourceRoot":"","sources":["../src/QueueManager.ts"],"names":[],"mappings":"AAEA,MAAM,WAAW,WAAW;IAC1B,IAAI,CAAC,GAAG,EAAE,OAAO,QAAQ,EAAE,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;CACxD;AAID,wBAAgB,kBAAkB,IAAI,WAAW,CAsBhD;AAED,qBAAa,YAAY;IACvB,MAAM,CAAC,OAAO,IAAI,WAAW;CAG9B"}

package/dist/QueueManager.js

@@ -0,0 +1,29 @@
+import { MemoryQueue } from './drivers/MemoryQueue';
+let _instance = null;
+export function resolveQueueDriver() {
+    if (_instance)
+        return _instance;
+    const driver = process.env['QUEUE_DRIVER'] ?? 'memory';
+    switch (driver) {
+        case 'redis': {
+            const { BullMQQueue } = require('./drivers/BullMQQueue');
+            _instance = new BullMQQueue({
+                host: process.env['REDIS_HOST'] ?? 'localhost',
+                port: Number(process.env['REDIS_PORT'] ?? 6379),
+                password: process.env['REDIS_PASSWORD'],
+            });
+            break;
+        }
+        case 'memory':
+        default:
+            _instance = new MemoryQueue();
+            break;
+    }
+    return _instance;
+}
+export class QueueManager {
+    static resolve() {
+        return resolveQueueDriver();
+    }
+}
+//# sourceMappingURL=QueueManager.js.map

package/dist/QueueManager.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"QueueManager.js","sourceRoot":"","sources":["../src/QueueManager.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC;AAMpD,IAAI,SAAS,GAAuB,IAAI,CAAC;AAEzC,MAAM,UAAU,kBAAkB;IAChC,IAAI,SAAS;QAAE,OAAO,SAAS,CAAC;IAEhC,MAAM,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,cAAc,CAAC,IAAI,QAAQ,CAAC;IAEvD,QAAQ,MAAM,EAAE,CAAC;QACf,KAAK,OAAO,CAAC,CAAC,CAAC;YACb,MAAM,EAAE,WAAW,EAAE,GAAG,OAAO,CAAC,uBAAuB,CAA2C,CAAC;YACnG,SAAS,GAAG,IAAI,WAAW,CAAC;gBAC1B,IAAI,EAAE,OAAO,CAAC,GAAG,CAAC,YAAY,CAAC,IAAI,WAAW;gBAC9C,IAAI,EAAE,MAAM,CAAC,OAAO,CAAC,GAAG,CAAC,YAAY,CAAC,IAAI,IAAI,CAAC;gBAC/C,QAAQ,EAAE,OAAO,CAAC,GAAG,CAAC,gBAAgB,CAAC;aACxC,CAAC,CAAC;YACH,MAAM;QACR,CAAC;QACD,KAAK,QAAQ,CAAC;QACd;YACE,SAAS,GAAG,IAAI,WAAW,EAAE,CAAC;YAC9B,MAAM;IACV,CAAC;IAED,OAAO,SAAS,CAAC;AACnB,CAAC;AAED,MAAM,OAAO,YAAY;IACvB,MAAM,CAAC,OAAO;QACZ,OAAO,kBAAkB,EAAE,CAAC;IAC9B,CAAC;CACF"}

package/dist/XJob.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Base class for all XAOCS background jobs.
+ * Extend this class and implement `handle()`.
+ *
+ * @example
+ * export class SendWelcomeEmailJob extends XJob {
+ *   constructor(public userId: number) { super(); }
+ *
+ *   async handle(): Promise<void> {
+ *     const user = await User.findOrFail(this.userId);
+ *     await mail.send({ to: user.email, subject: 'Welcome!' });
+ *   }
+ * }
+ */
+export declare abstract class XJob {
+    /**
+     * The queue this job should be placed on.
+     * Defaults to 'default'.
+     */
+    static queue: string;
+    /**
+     * Number of times to retry on failure.
+     * Defaults to 3.
+     */
+    static retries: number;
+    /**
+     * Delay in milliseconds before first attempt.
+     * Defaults to 0 (immediate).
+     */
+    static delay: number;
+    /**
+     * Implement your job logic here.
+     */
+    abstract handle(): Promise<void>;
+    /**
+     * Called if all retries are exhausted.
+     * Override to implement custom failure handling.
+     */
+    failed(error: Error): Promise<void>;
+}
+//# sourceMappingURL=XJob.d.ts.map

package/dist/XJob.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"XJob.d.ts","sourceRoot":"","sources":["../src/XJob.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,8BAAsB,IAAI;IACxB;;;OAGG;IACH,MAAM,CAAC,KAAK,SAAa;IAEzB;;;OAGG;IACH,MAAM,CAAC,OAAO,SAAK;IAEnB;;;OAGG;IACH,MAAM,CAAC,KAAK,SAAK;IAEjB;;OAEG;IACH,QAAQ,CAAC,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC;IAEhC;;;OAGG;IACG,MAAM,CAAC,KAAK,EAAE,KAAK,GAAG,OAAO,CAAC,IAAI,CAAC;CAG1C"}

package/dist/XJob.js

@@ -0,0 +1,39 @@
+/**
+ * Base class for all XAOCS background jobs.
+ * Extend this class and implement `handle()`.
+ *
+ * @example
+ * export class SendWelcomeEmailJob extends XJob {
+ *   constructor(public userId: number) { super(); }
+ *
+ *   async handle(): Promise<void> {
+ *     const user = await User.findOrFail(this.userId);
+ *     await mail.send({ to: user.email, subject: 'Welcome!' });
+ *   }
+ * }
+ */
+export class XJob {
+    /**
+     * The queue this job should be placed on.
+     * Defaults to 'default'.
+     */
+    static queue = 'default';
+    /**
+     * Number of times to retry on failure.
+     * Defaults to 3.
+     */
+    static retries = 3;
+    /**
+     * Delay in milliseconds before first attempt.
+     * Defaults to 0 (immediate).
+     */
+    static delay = 0;
+    /**
+     * Called if all retries are exhausted.
+     * Override to implement custom failure handling.
+     */
+    async failed(error) {
+        console.error(`[XAOCS Queue] Job failed: ${this.constructor.name}`, error.message);
+    }
+}
+//# sourceMappingURL=XJob.js.map

package/dist/XJob.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"XJob.js","sourceRoot":"","sources":["../src/XJob.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,MAAM,OAAgB,IAAI;IACxB;;;OAGG;IACH,MAAM,CAAC,KAAK,GAAG,SAAS,CAAC;IAEzB;;;OAGG;IACH,MAAM,CAAC,OAAO,GAAG,CAAC,CAAC;IAEnB;;;OAGG;IACH,MAAM,CAAC,KAAK,GAAG,CAAC,CAAC;IAOjB;;;OAGG;IACH,KAAK,CAAC,MAAM,CAAC,KAAY;QACvB,OAAO,CAAC,KAAK,CAAC,6BAA6B,IAAI,CAAC,WAAW,CAAC,IAAI,EAAE,EAAE,KAAK,CAAC,OAAO,CAAC,CAAC;IACrF,CAAC"}

package/dist/dispatch.d.ts

@@ -0,0 +1,10 @@
+import type { XJob } from './XJob';
+/**
+ * Dispatch a job to the queue.
+ *
+ * @example
+ * import { dispatch } from '@xacos/queue';
+ * await dispatch(new SendWelcomeEmailJob(user.id));
+ */
+export declare function dispatch(job: XJob): Promise<void>;
+//# sourceMappingURL=dispatch.d.ts.map

package/dist/dispatch.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dispatch.d.ts","sourceRoot":"","sources":["../src/dispatch.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,QAAQ,CAAC;AAEnC;;;;;;GAMG;AACH,wBAAsB,QAAQ,CAAC,GAAG,EAAE,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAEvD"}

package/dist/dispatch.js

@@ -0,0 +1,12 @@
+import { QueueManager } from './QueueManager';
+/**
+ * Dispatch a job to the queue.
+ *
+ * @example
+ * import { dispatch } from '@xacos/queue';
+ * await dispatch(new SendWelcomeEmailJob(user.id));
+ */
+export async function dispatch(job) {
+    await QueueManager.resolve().push(job);
+}
+//# sourceMappingURL=dispatch.js.map

package/dist/dispatch.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"dispatch.js","sourceRoot":"","sources":["../src/dispatch.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAG9C;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,QAAQ,CAAC,GAAS;IACtC,MAAM,YAAY,CAAC,OAAO,EAAE,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AACzC,CAAC"}

package/dist/dispatch.test.d.ts

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

package/dist/dispatch.test.d.ts.map

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

package/dist/dispatch.test.js

@@ -0,0 +1,16 @@
+import { describe, it, expect } from 'bun:test';
+import { dispatch } from './dispatch';
+import { XJob } from './XJob';
+let handled = false;
+class SimpleJob extends XJob {
+    async handle() { handled = true; }
+}
+describe('dispatch', () => {
+    it('dispatches a job and executes it', async () => {
+        process.env['QUEUE_DRIVER'] = 'memory';
+        await dispatch(new SimpleJob());
+        await new Promise(r => setTimeout(r, 10));
+        expect(handled).toBe(true);
+    });
+});
+//# sourceMappingURL=dispatch.test.js.map

package/dist/dispatch.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"dispatch.test.js","sourceRoot":"","sources":["../src/dispatch.test.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,EAAE,EAAE,MAAM,EAAE,MAAM,UAAU,CAAC;AAChD,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AACtC,OAAO,EAAE,IAAI,EAAE,MAAM,QAAQ,CAAC;AAE9B,IAAI,OAAO,GAAG,KAAK,CAAC;AACpB,MAAM,SAAU,SAAQ,IAAI;IAC1B,KAAK,CAAC,MAAM,KAAK,OAAO,GAAG,IAAI,CAAC,CAAC,CAAC;CACnC;AAED,QAAQ,CAAC,UAAU,EAAE,GAAG,EAAE;IACxB,EAAE,CAAC,kCAAkC,EAAE,KAAK,IAAI,EAAE;QAChD,OAAO,CAAC,GAAG,CAAC,cAAc,CAAC,GAAG,QAAQ,CAAC;QACvC,MAAM,QAAQ,CAAC,IAAI,SAAS,EAAE,CAAC,CAAC;QAChC,MAAM,IAAI,OAAO,CAAC,CAAC,CAAC,EAAE,CAAC,UAAU,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC;QAC1C,MAAM,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAC7B,CAAC,CAAC,CAAC;AACL,CAAC,CAAC,CAAC"}

package/dist/drivers/BullMQQueue.d.ts

@@ -0,0 +1,23 @@
+import { Worker } from 'bullmq';
+import type { XJob } from '../XJob';
+export interface BullMQConfig {
+    host?: string | undefined;
+    port?: number | undefined;
+    password?: string | undefined;
+}
+export declare class BullMQQueue {
+    private queues;
+    private workers;
+    private config;
+    constructor(config?: BullMQConfig);
+    private getConnection;
+    private getOrCreateQueue;
+    push(job: XJob): Promise<void>;
+    /**
+     * Start a worker for the given queue name.
+     * Workers process jobs in separate processes in production.
+     */
+    startWorker(queueName: string, jobClasses: Array<new (...args: unknown[]) => XJob>): Worker;
+    close(): Promise<void>;
+}
+//# sourceMappingURL=BullMQQueue.d.ts.map

package/dist/drivers/BullMQQueue.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"BullMQQueue.d.ts","sourceRoot":"","sources":["../../src/drivers/BullMQQueue.ts"],"names":[],"mappings":"AAAA,OAAO,EAAS,MAAM,EAAuB,MAAM,QAAQ,CAAC;AAC5D,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,SAAS,CAAC;AAEpC,MAAM,WAAW,YAAY;IAC3B,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC1B,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC1B,QAAQ,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAC/B;AAGD,qBAAa,WAAW;IACtB,OAAO,CAAC,MAAM,CAA4B;IAC1C,OAAO,CAAC,OAAO,CAA6B;IAC5C,OAAO,CAAC,MAAM,CAAe;gBAEjB,MAAM,GAAE,YAAiB;IAIrC,OAAO,CAAC,aAAa;IAQrB,OAAO,CAAC,gBAAgB;IAalB,IAAI,CAAC,GAAG,EAAE,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;IAcpC;;;OAGG;IACH,WAAW,CAAC,SAAS,EAAE,MAAM,EAAE,UAAU,EAAE,KAAK,CAAC,KAAK,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,IAAI,CAAC,GAAG,MAAM;IAwBrF,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;CAI7B"}

package/dist/drivers/BullMQQueue.js

@@ -0,0 +1,67 @@
+import { Queue, Worker } from 'bullmq';
+export class BullMQQueue {
+    queues = new Map();
+    workers = new Map();
+    config;
+    constructor(config = {}) {
+        this.config = config;
+    }
+    getConnection() {
+        return {
+            host: this.config.host ?? 'localhost',
+            port: this.config.port ?? 6379,
+            password: this.config.password,
+        };
+    }
+    getOrCreateQueue(name) {
+        if (!this.queues.has(name)) {
+            this.queues.set(name, new Queue(name, {
+                connection: this.getConnection(),
+                defaultJobOptions: {
+                    attempts: 3,
+                    backoff: { type: 'exponential', delay: 1000 },
+                },
+            }));
+        }
+        return this.queues.get(name);
+    }
+    async push(job) {
+        const JobClass = job.constructor;
+        const queueName = JobClass.queue;
+        const queue = this.getOrCreateQueue(queueName);
+        const jobName = JobClass.name;
+        const payload = JSON.stringify(job);
+        await queue.add(jobName, { jobName, payload }, {
+            delay: JobClass.delay,
+            attempts: JobClass.retries + 1,
+        });
+    }
+    /**
+     * Start a worker for the given queue name.
+     * Workers process jobs in separate processes in production.
+     */
+    startWorker(queueName, jobClasses) {
+        // Build a registry: jobName → constructor
+        const registry = new Map();
+        for (const JobClass of jobClasses) {
+            registry.set(JobClass.name, JobClass);
+        }
+        const worker = new Worker(queueName, async (bullJob) => {
+            const { jobName, payload } = bullJob.data;
+            const JobClass = registry.get(jobName);
+            if (!JobClass)
+                throw new Error(`[XAOCS Queue] Unknown job: ${jobName}`);
+            const instance = Object.assign(new JobClass(), JSON.parse(payload));
+            await instance.handle();
+        }, { connection: this.getConnection() });
+        this.workers.set(queueName, worker);
+        return worker;
+    }
+    async close() {
+        for (const worker of this.workers.values())
+            await worker.close();
+        for (const queue of this.queues.values())
+            await queue.close();
+    }
+}
+//# sourceMappingURL=BullMQQueue.js.map

package/dist/drivers/BullMQQueue.js.map

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

package/dist/drivers/MemoryQueue.d.ts

@@ -0,0 +1,15 @@
+import type { XJob } from '../XJob';
+export declare class MemoryQueue {
+    private queues;
+    private running;
+    /**
+     * Add a job to the queue.
+     */
+    push(job: XJob): void;
+    private processNext;
+    /**
+     * Get the number of pending jobs across all queues.
+     */
+    pending(): number;
+}
+//# sourceMappingURL=MemoryQueue.d.ts.map

package/dist/drivers/MemoryQueue.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"MemoryQueue.d.ts","sourceRoot":"","sources":["../../src/drivers/MemoryQueue.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,SAAS,CAAC;AAQpC,qBAAa,WAAW;IACtB,OAAO,CAAC,MAAM,CAAkC;IAChD,OAAO,CAAC,OAAO,CAAS;IAExB;;OAEG;IACH,IAAI,CAAC,GAAG,EAAE,IAAI,GAAG,IAAI;YAgBP,WAAW;IAsBzB;;OAEG;IACH,OAAO,IAAI,MAAM;CAOlB"}

package/dist/drivers/MemoryQueue.js

@@ -0,0 +1,53 @@
+export class MemoryQueue {
+    queues = new Map();
+    running = false;
+    /**
+     * Add a job to the queue.
+     */
+    push(job) {
+        const queueName = job.constructor.queue;
+        if (!this.queues.has(queueName)) {
+            this.queues.set(queueName, []);
+        }
+        this.queues.get(queueName).push({
+            job,
+            retries: 0,
+            maxRetries: job.constructor.retries,
+        });
+        if (!this.running) {
+            void this.processNext();
+        }
+    }
+    async processNext() {
+        this.running = true;
+        for (const [, queue] of this.queues) {
+            while (queue.length > 0) {
+                const item = queue.shift();
+                try {
+                    await item.job.handle();
+                }
+                catch (error) {
+                    if (item.retries < item.maxRetries) {
+                        item.retries++;
+                        queue.push(item); // re-queue with incremented retries
+                    }
+                    else {
+                        await item.job.failed(error);
+                    }
+                }
+            }
+        }
+        this.running = false;
+    }
+    /**
+     * Get the number of pending jobs across all queues.
+     */
+    pending() {
+        let total = 0;
+        for (const queue of this.queues.values()) {
+            total += queue.length;
+        }
+        return total;
+    }
+}
+//# sourceMappingURL=MemoryQueue.js.map

package/dist/drivers/MemoryQueue.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"MemoryQueue.js","sourceRoot":"","sources":["../../src/drivers/MemoryQueue.ts"],"names":[],"mappings":"AAQA,MAAM,OAAO,WAAW;IACd,MAAM,GAAG,IAAI,GAAG,EAAuB,CAAC;IACxC,OAAO,GAAG,KAAK,CAAC;IAExB;;OAEG;IACH,IAAI,CAAC,GAAS;QACZ,MAAM,SAAS,GAAI,GAAG,CAAC,WAA2B,CAAC,KAAK,CAAC;QACzD,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,SAAS,CAAC,EAAE,CAAC;YAChC,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,SAAS,EAAE,EAAE,CAAC,CAAC;QACjC,CAAC;QACD,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,SAAS,CAAE,CAAC,IAAI,CAAC;YAC/B,GAAG;YACH,OAAO,EAAE,CAAC;YACV,UAAU,EAAG,GAAG,CAAC,WAA2B,CAAC,OAAO;SACrD,CAAC,CAAC;QAEH,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,CAAC;YAClB,KAAK,IAAI,CAAC,WAAW,EAAE,CAAC;QAC1B,CAAC;IACH,CAAC;IAEO,KAAK,CAAC,WAAW;QACvB,IAAI,CAAC,OAAO,GAAG,IAAI,CAAC;QAEpB,KAAK,MAAM,CAAC,EAAE,KAAK,CAAC,IAAI,IAAI,CAAC,MAAM,EAAE,CAAC;YACpC,OAAO,KAAK,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;gBACxB,MAAM,IAAI,GAAG,KAAK,CAAC,KAAK,EAAG,CAAC;gBAC5B,IAAI,CAAC;oBACH,MAAM,IAAI,CAAC,GAAG,CAAC,MAAM,EAAE,CAAC;gBAC1B,CAAC;gBAAC,OAAO,KAAK,EAAE,CAAC;oBACf,IAAI,IAAI,CAAC,OAAO,GAAG,IAAI,CAAC,UAAU,EAAE,CAAC;wBACnC,IAAI,CAAC,OAAO,EAAE,CAAC;wBACf,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,oCAAoC;oBACxD,CAAC;yBAAM,CAAC;wBACN,MAAM,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,KAAc,CAAC,CAAC;oBACxC,CAAC;gBACH,CAAC;YACH,CAAC;QACH,CAAC;QAED,IAAI,CAAC,OAAO,GAAG,KAAK,CAAC;IACvB,CAAC;IAED;;OAEG;IACH,OAAO;QACL,IAAI,KAAK,GAAG,CAAC,CAAC;QACd,KAAK,MAAM,KAAK,IAAI,IAAI,CAAC,MAAM,CAAC,MAAM,EAAE,EAAE,CAAC;YACzC,KAAK,IAAI,KAAK,CAAC,MAAM,CAAC;QACxB,CAAC;QACD,OAAO,KAAK,CAAC;IACf,CAAC;CACF"}

package/dist/drivers/MemoryQueue.test.d.ts

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

package/dist/drivers/MemoryQueue.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"MemoryQueue.test.d.ts","sourceRoot":"","sources":["../../src/drivers/MemoryQueue.test.ts"],"names":[],"mappings":""}

package/dist/drivers/MemoryQueue.test.js

@@ -0,0 +1,28 @@
+import { describe, it, expect } from 'bun:test';
+import { MemoryQueue } from './MemoryQueue';
+import { XJob } from '../XJob';
+class TestJob extends XJob {
+    static executed = false;
+    async handle() { TestJob.executed = true; }
+}
+class FailingJob extends XJob {
+    static retries = 0;
+    static failedCalled = false;
+    async handle() { throw new Error('intentional fail'); }
+    async failed(_err) { FailingJob.failedCalled = true; }
+}
+describe('MemoryQueue', () => {
+    it('executes a job', async () => {
+        const queue = new MemoryQueue();
+        queue.push(new TestJob());
+        await new Promise(r => setTimeout(r, 10)); // let queue process
+        expect(TestJob.executed).toBe(true);
+    });
+    it('calls failed() after exhausting retries', async () => {
+        const queue = new MemoryQueue();
+        queue.push(new FailingJob());
+        await new Promise(r => setTimeout(r, 10));
+        expect(FailingJob.failedCalled).toBe(true);
+    });
+});
+//# sourceMappingURL=MemoryQueue.test.js.map

package/dist/drivers/MemoryQueue.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"MemoryQueue.test.js","sourceRoot":"","sources":["../../src/drivers/MemoryQueue.test.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,EAAE,EAAE,MAAM,EAAE,MAAM,UAAU,CAAC;AAChD,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAC5C,OAAO,EAAE,IAAI,EAAE,MAAM,SAAS,CAAC;AAE/B,MAAM,OAAQ,SAAQ,IAAI;IACxB,MAAM,CAAC,QAAQ,GAAG,KAAK,CAAC;IACxB,KAAK,CAAC,MAAM,KAAK,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAC,CAAC,CAAC;;AAG7C,MAAM,UAAW,SAAQ,IAAI;IAC3B,MAAM,CAAC,OAAO,GAAG,CAAC,CAAC;IACnB,MAAM,CAAC,YAAY,GAAG,KAAK,CAAC;IAC5B,KAAK,CAAC,MAAM,KAAK,MAAM,IAAI,KAAK,CAAC,kBAAkB,CAAC,CAAC,CAAC,CAAC;IACvD,KAAK,CAAC,MAAM,CAAC,IAAW,IAAI,UAAU,CAAC,YAAY,GAAG,IAAI,CAAC,CAAC,CAAC;;AAG/D,QAAQ,CAAC,aAAa,EAAE,GAAG,EAAE;IAC3B,EAAE,CAAC,gBAAgB,EAAE,KAAK,IAAI,EAAE;QAC9B,MAAM,KAAK,GAAG,IAAI,WAAW,EAAE,CAAC;QAChC,KAAK,CAAC,IAAI,CAAC,IAAI,OAAO,EAAE,CAAC,CAAC;QAC1B,MAAM,IAAI,OAAO,CAAC,CAAC,CAAC,EAAE,CAAC,UAAU,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,oBAAoB;QAC/D,MAAM,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACtC,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,yCAAyC,EAAE,KAAK,IAAI,EAAE;QACvD,MAAM,KAAK,GAAG,IAAI,WAAW,EAAE,CAAC;QAChC,KAAK,CAAC,IAAI,CAAC,IAAI,UAAU,EAAE,CAAC,CAAC;QAC7B,MAAM,IAAI,OAAO,CAAC,CAAC,CAAC,EAAE,CAAC,UAAU,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC;QAC1C,MAAM,CAAC,UAAU,CAAC,YAAY,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAC7C,CAAC,CAAC,CAAC;AACL,CAAC,CAAC,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export { XJob } from './XJob';
+export { dispatch } from './dispatch';
+export { MemoryQueue } from './drivers/MemoryQueue';
+export { QueueManager, resolveQueueDriver } from './QueueManager';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,MAAM,QAAQ,CAAC;AAC9B,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AACtC,OAAO,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC;AACpD,OAAO,EAAE,YAAY,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAC"}

package/dist/index.js

@@ -0,0 +1,5 @@
+export { XJob } from './XJob';
+export { dispatch } from './dispatch';
+export { MemoryQueue } from './drivers/MemoryQueue';
+export { QueueManager, resolveQueueDriver } from './QueueManager';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,MAAM,QAAQ,CAAC;AAC9B,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AACtC,OAAO,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC;AACpD,OAAO,EAAE,YAAY,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAC"}

package/package.json

@@ -0,0 +1,68 @@
+{
+  "name": "@xacos/queue",
+  "version": "1.0.0",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "dependencies": {
+    "@xacos/config": "workspace:*",
+    "@xacos/shared": "workspace:*",
+    "bullmq": "^5.76.8"
+  },
+  "devDependencies": {
+    "typescript": "^5.x",
+    "bun-types": "^1.3.12"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "test": "bun test src",
+    "type-check": "tsc --noEmit"
+  },
+  "license": "MIT",
+  "author": "XAOCS Team",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/zoherr/xaocs.git",
+    "directory": "packages/queue"
+  },
+  "homepage": "https://xaocs.dev",
+  "bugs": {
+    "url": "https://github.com/zoherr/xaocs/issues"
+  },
+  "keywords": [
+    "xaocs",
+    "xacos",
+    "framework",
+    "typescript",
+    "fullstack",
+    "fastify",
+    "react",
+    "queue",
+    "bullmq",
+    "jobs",
+    "workers",
+    "redis"
+  ],
+  "files": [
+    "dist",
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org",
+    "provenance": false
+  },
+  "engines": {
+    "bun": ">=1.0.0",
+    "node": ">=18.0.0"
+  }
+}

package/src/QueueManager.ts

@@ -0,0 +1,38 @@
+import { MemoryQueue } from './drivers/MemoryQueue';
+
+export interface QueueDriver {
+  push(job: import('./XJob').XJob): Promise<void> | void;
+}
+
+let _instance: QueueDriver | null = null;
+
+export function resolveQueueDriver(): QueueDriver {
+  if (_instance) return _instance;
+
+  const driver = process.env['QUEUE_DRIVER'] ?? 'memory';
+
+  switch (driver) {
+    case 'redis': {
+      const { BullMQQueue } = require('./drivers/BullMQQueue') as typeof import('./drivers/BullMQQueue');
+      _instance = new BullMQQueue({
+        host: process.env['REDIS_HOST'] ?? 'localhost',
+        port: Number(process.env['REDIS_PORT'] ?? 6379),
+        password: process.env['REDIS_PASSWORD'],
+      });
+      break;
+    }
+    case 'memory':
+    default:
+      _instance = new MemoryQueue();
+      break;
+  }
+
+  return _instance;
+}
+
+export class QueueManager {
+  static resolve(): QueueDriver {
+    return resolveQueueDriver();
+  }
+}
+

package/src/XJob.ts

@@ -0,0 +1,47 @@
+/**
+ * Base class for all XAOCS background jobs.
+ * Extend this class and implement `handle()`.
+ *
+ * @example
+ * export class SendWelcomeEmailJob extends XJob {
+ *   constructor(public userId: number) { super(); }
+ *
+ *   async handle(): Promise<void> {
+ *     const user = await User.findOrFail(this.userId);
+ *     await mail.send({ to: user.email, subject: 'Welcome!' });
+ *   }
+ * }
+ */
+export abstract class XJob {
+  /**
+   * The queue this job should be placed on.
+   * Defaults to 'default'.
+   */
+  static queue = 'default';
+
+  /**
+   * Number of times to retry on failure.
+   * Defaults to 3.
+   */
+  static retries = 3;
+
+  /**
+   * Delay in milliseconds before first attempt.
+   * Defaults to 0 (immediate).
+   */
+  static delay = 0;
+
+  /**
+   * Implement your job logic here.
+   */
+  abstract handle(): Promise<void>;
+
+  /**
+   * Called if all retries are exhausted.
+   * Override to implement custom failure handling.
+   */
+  async failed(error: Error): Promise<void> {
+    console.error(`[XAOCS Queue] Job failed: ${this.constructor.name}`, error.message);
+  }
+}
+

package/src/dispatch.test.ts

@@ -0,0 +1,18 @@
+import { describe, it, expect } from 'bun:test';
+import { dispatch } from './dispatch';
+import { XJob } from './XJob';
+
+let handled = false;
+class SimpleJob extends XJob {
+  async handle() { handled = true; }
+}
+
+describe('dispatch', () => {
+  it('dispatches a job and executes it', async () => {
+    process.env['QUEUE_DRIVER'] = 'memory';
+    await dispatch(new SimpleJob());
+    await new Promise(r => setTimeout(r, 10));
+    expect(handled).toBe(true);
+  });
+});
+

package/src/dispatch.ts

@@ -0,0 +1,14 @@
+import { QueueManager } from './QueueManager';
+import type { XJob } from './XJob';
+
+/**
+ * Dispatch a job to the queue.
+ *
+ * @example
+ * import { dispatch } from '@xacos/queue';
+ * await dispatch(new SendWelcomeEmailJob(user.id));
+ */
+export async function dispatch(job: XJob): Promise<void> {
+  await QueueManager.resolve().push(job);
+}
+

package/src/drivers/BullMQQueue.ts

@@ -0,0 +1,88 @@
+import { Queue, Worker, type Job as BullJob } from 'bullmq';
+import type { XJob } from '../XJob';
+
+export interface BullMQConfig {
+  host?: string | undefined;
+  port?: number | undefined;
+  password?: string | undefined;
+}
+
+
+export class BullMQQueue {
+  private queues = new Map<string, Queue>();
+  private workers = new Map<string, Worker>();
+  private config: BullMQConfig;
+
+  constructor(config: BullMQConfig = {}) {
+    this.config = config;
+  }
+
+  private getConnection() {
+    return {
+      host: this.config.host ?? 'localhost',
+      port: this.config.port ?? 6379,
+      password: this.config.password,
+    };
+  }
+
+  private getOrCreateQueue(name: string): Queue {
+    if (!this.queues.has(name)) {
+      this.queues.set(name, new Queue(name, {
+        connection: this.getConnection(),
+        defaultJobOptions: {
+          attempts: 3,
+          backoff: { type: 'exponential', delay: 1000 },
+        },
+      }));
+    }
+    return this.queues.get(name)!;
+  }
+
+  async push(job: XJob): Promise<void> {
+    const JobClass = job.constructor as typeof XJob;
+    const queueName = JobClass.queue;
+    const queue = this.getOrCreateQueue(queueName);
+
+    const jobName = JobClass.name;
+    const payload = JSON.stringify(job);
+
+    await queue.add(jobName, { jobName, payload }, {
+      delay: JobClass.delay,
+      attempts: JobClass.retries + 1,
+    });
+  }
+
+  /**
+   * Start a worker for the given queue name.
+   * Workers process jobs in separate processes in production.
+   */
+  startWorker(queueName: string, jobClasses: Array<new (...args: unknown[]) => XJob>): Worker {
+    // Build a registry: jobName → constructor
+    const registry = new Map<string, new (...args: unknown[]) => XJob>();
+    for (const JobClass of jobClasses) {
+      registry.set(JobClass.name, JobClass);
+    }
+
+    const worker = new Worker(
+      queueName,
+      async (bullJob: BullJob) => {
+        const { jobName, payload } = bullJob.data as { jobName: string; payload: string };
+        const JobClass = registry.get(jobName);
+        if (!JobClass) throw new Error(`[XAOCS Queue] Unknown job: ${jobName}`);
+
+        const instance = Object.assign(new JobClass(), JSON.parse(payload));
+        await instance.handle();
+      },
+      { connection: this.getConnection() }
+    );
+
+    this.workers.set(queueName, worker);
+    return worker;
+  }
+
+  async close(): Promise<void> {
+    for (const worker of this.workers.values()) await worker.close();
+    for (const queue of this.queues.values()) await queue.close();
+  }
+}
+

package/src/drivers/MemoryQueue.test.ts

@@ -0,0 +1,32 @@
+import { describe, it, expect } from 'bun:test';
+import { MemoryQueue } from './MemoryQueue';
+import { XJob } from '../XJob';
+
+class TestJob extends XJob {
+  static executed = false;
+  async handle() { TestJob.executed = true; }
+}
+
+class FailingJob extends XJob {
+  static retries = 0;
+  static failedCalled = false;
+  async handle() { throw new Error('intentional fail'); }
+  async failed(_err: Error) { FailingJob.failedCalled = true; }
+}
+
+describe('MemoryQueue', () => {
+  it('executes a job', async () => {
+    const queue = new MemoryQueue();
+    queue.push(new TestJob());
+    await new Promise(r => setTimeout(r, 10)); // let queue process
+    expect(TestJob.executed).toBe(true);
+  });
+
+  it('calls failed() after exhausting retries', async () => {
+    const queue = new MemoryQueue();
+    queue.push(new FailingJob());
+    await new Promise(r => setTimeout(r, 10));
+    expect(FailingJob.failedCalled).toBe(true);
+  });
+});
+

package/src/drivers/MemoryQueue.ts

@@ -0,0 +1,65 @@
+import type { XJob } from '../XJob';
+
+interface QueuedJob {
+  job: XJob;
+  retries: number;
+  maxRetries: number;
+}
+
+export class MemoryQueue {
+  private queues = new Map<string, QueuedJob[]>();
+  private running = false;
+
+  /**
+   * Add a job to the queue.
+   */
+  push(job: XJob): void {
+    const queueName = (job.constructor as typeof XJob).queue;
+    if (!this.queues.has(queueName)) {
+      this.queues.set(queueName, []);
+    }
+    this.queues.get(queueName)!.push({
+      job,
+      retries: 0,
+      maxRetries: (job.constructor as typeof XJob).retries,
+    });
+
+    if (!this.running) {
+      void this.processNext();
+    }
+  }
+
+  private async processNext(): Promise<void> {
+    this.running = true;
+
+    for (const [, queue] of this.queues) {
+      while (queue.length > 0) {
+        const item = queue.shift()!;
+        try {
+          await item.job.handle();
+        } catch (error) {
+          if (item.retries < item.maxRetries) {
+            item.retries++;
+            queue.push(item); // re-queue with incremented retries
+          } else {
+            await item.job.failed(error as Error);
+          }
+        }
+      }
+    }
+
+    this.running = false;
+  }
+
+  /**
+   * Get the number of pending jobs across all queues.
+   */
+  pending(): number {
+    let total = 0;
+    for (const queue of this.queues.values()) {
+      total += queue.length;
+    }
+    return total;
+  }
+}
+

package/src/index.ts

@@ -0,0 +1,5 @@
+export { XJob } from './XJob';
+export { dispatch } from './dispatch';
+export { MemoryQueue } from './drivers/MemoryQueue';
+export { QueueManager, resolveQueueDriver } from './QueueManager';
+