@veloxts/queue 0.6.56 → 0.6.58

package/README.md

@@ -1,34 +1,8 @@
 # @veloxts/queue
 
-> **Early Preview** - APIs may change before v1.0.
+> **Early Preview (v0.6.x)** - APIs are stabilizing but may still change. Use with caution in production.
 
-Background job processing with type-safe job definitions and multiple drivers.
-
-## Installation
-
-```bash
-npm install @veloxts/queue
-```
-
-## Quick Start
-
-```typescript
-import { queuePlugin, defineJob } from '@veloxts/queue';
-
-app.use(queuePlugin({ driver: 'sync' }));
-
-const sendEmail = defineJob({
-  name: 'email.send',
-  handler: async ({ data }) => {
-    await mailer.send(data.to, data.subject, data.body);
-  },
-});
-
-// Dispatch a job
-await ctx.queue.dispatch(sendEmail, { to: 'user@example.com', subject: 'Hello' });
-```
-
-See [GUIDE.md](./GUIDE.md) for detailed documentation.
+Background job processing for VeloxTS Framework - provides sync and BullMQ drivers with type-safe job definitions and reliable execution. Learn more at [@veloxts/velox](https://www.npmjs.com/package/@veloxts/velox).
 
 ## License
 

package/dist/index.d.ts

@@ -53,3 +53,30 @@ export { createQueueManager, createWorkerManager, type QueueManager, queue, type
 export { closeQueue, getQueue, getQueueFromInstance, initQueue, queuePlugin, } from './plugin.js';
 export type { BackoffOptions, BullMQConfig, Delay, DispatchOptions, DurationString, FailedJob, JobContext, JobDefinition, JobDefinitionConfig, JobHandler, JobOptions, QueueConfig, QueueDriver, QueuePluginOptions, QueueStats, QueueStore, SyncConfig, WorkerStore, } from './types.js';
 export { formatDuration, isDurationString, parseDelay, validateJobName } from './utils.js';
+/**
+ * DI tokens and providers for @veloxts/queue
+ *
+ * Use these to integrate queue services with the @veloxts/core DI container.
+ *
+ * @example
+ * ```typescript
+ * import { Container } from '@veloxts/core';
+ * import { registerQueueProviders, QUEUE_MANAGER, WORKER_MANAGER } from '@veloxts/queue';
+ *
+ * const container = new Container();
+ * await registerQueueProviders(container, {
+ *   driver: 'sync',
+ *   includeWorker: true,
+ * });
+ *
+ * const queue = container.resolve(QUEUE_MANAGER);
+ * await queue.dispatch(myJob, { data: 'value' });
+ *
+ * const worker = container.resolve(WORKER_MANAGER);
+ * worker.register(myJob);
+ * await worker.start();
+ * ```
+ */
+export type { RegisterQueueProvidersOptions } from './providers.js';
+export { registerQueueProviders } from './providers.js';
+export { QUEUE_CONFIG, QUEUE_MANAGER, QUEUE_STORE, WORKER_MANAGER, WORKER_STORE, } from './tokens.js';

package/dist/index.js

@@ -57,3 +57,6 @@ export { createQueueManager, createWorkerManager, queue, } from './manager.js';
 export { closeQueue, getQueue, getQueueFromInstance, initQueue, queuePlugin, } from './plugin.js';
 // Utilities
 export { formatDuration, isDurationString, parseDelay, validateJobName } from './utils.js';
+export { registerQueueProviders } from './providers.js';
+// Token exports - unique identifiers for DI resolution
+export { QUEUE_CONFIG, QUEUE_MANAGER, QUEUE_STORE, WORKER_MANAGER, WORKER_STORE, } from './tokens.js';

package/dist/providers.d.ts

@@ -0,0 +1,69 @@
+/**
+ * DI Providers for @veloxts/queue
+ *
+ * Factory provider functions for registering queue services with the DI container.
+ * These providers allow services to be managed by the container for testability and flexibility.
+ *
+ * @module queue/providers
+ *
+ * @example
+ * ```typescript
+ * import { Container } from '@veloxts/core';
+ * import { registerQueueProviders, QUEUE_MANAGER } from '@veloxts/queue';
+ *
+ * const container = new Container();
+ * await registerQueueProviders(container, { driver: 'sync' });
+ *
+ * const queue = container.resolve(QUEUE_MANAGER);
+ * await queue.dispatch(myJob, { data: 'value' });
+ * ```
+ */
+import type { Container } from '@veloxts/core';
+import type { QueuePluginOptions } from './types.js';
+/**
+ * Options for registering queue providers
+ */
+export type RegisterQueueProvidersOptions = QueuePluginOptions & {
+    /**
+     * Whether to also register a worker manager.
+     * @default false
+     */
+    includeWorker?: boolean;
+};
+/**
+ * Registers queue providers with a container
+ *
+ * This handles async initialization of the queue manager and optionally
+ * the worker manager, registering the resolved instances directly for
+ * synchronous resolution.
+ *
+ * @param container - The DI container to register providers with
+ * @param config - Queue plugin options (driver, prefix, etc.)
+ *
+ * @example
+ * ```typescript
+ * import { Container } from '@veloxts/core';
+ * import { registerQueueProviders, QUEUE_MANAGER, WORKER_MANAGER } from '@veloxts/queue';
+ *
+ * const container = new Container();
+ *
+ * // Sync driver (development/testing)
+ * await registerQueueProviders(container, { driver: 'sync' });
+ *
+ * // BullMQ driver (production) with worker
+ * await registerQueueProviders(container, {
+ *   driver: 'bullmq',
+ *   config: { url: process.env.REDIS_URL },
+ *   includeWorker: true,
+ * });
+ *
+ * const queue = container.resolve(QUEUE_MANAGER);
+ * await queue.dispatch(myJob, { userId: '123' });
+ *
+ * // If includeWorker was true:
+ * const worker = container.resolve(WORKER_MANAGER);
+ * worker.register(myJob);
+ * await worker.start();
+ * ```
+ */
+export declare function registerQueueProviders(container: Container, config?: RegisterQueueProvidersOptions): Promise<void>;

package/dist/providers.js

@@ -0,0 +1,82 @@
+/**
+ * DI Providers for @veloxts/queue
+ *
+ * Factory provider functions for registering queue services with the DI container.
+ * These providers allow services to be managed by the container for testability and flexibility.
+ *
+ * @module queue/providers
+ *
+ * @example
+ * ```typescript
+ * import { Container } from '@veloxts/core';
+ * import { registerQueueProviders, QUEUE_MANAGER } from '@veloxts/queue';
+ *
+ * const container = new Container();
+ * await registerQueueProviders(container, { driver: 'sync' });
+ *
+ * const queue = container.resolve(QUEUE_MANAGER);
+ * await queue.dispatch(myJob, { data: 'value' });
+ * ```
+ */
+import { createQueueManager, createWorkerManager } from './manager.js';
+import { QUEUE_CONFIG, QUEUE_MANAGER, WORKER_MANAGER } from './tokens.js';
+/**
+ * Registers queue providers with a container
+ *
+ * This handles async initialization of the queue manager and optionally
+ * the worker manager, registering the resolved instances directly for
+ * synchronous resolution.
+ *
+ * @param container - The DI container to register providers with
+ * @param config - Queue plugin options (driver, prefix, etc.)
+ *
+ * @example
+ * ```typescript
+ * import { Container } from '@veloxts/core';
+ * import { registerQueueProviders, QUEUE_MANAGER, WORKER_MANAGER } from '@veloxts/queue';
+ *
+ * const container = new Container();
+ *
+ * // Sync driver (development/testing)
+ * await registerQueueProviders(container, { driver: 'sync' });
+ *
+ * // BullMQ driver (production) with worker
+ * await registerQueueProviders(container, {
+ *   driver: 'bullmq',
+ *   config: { url: process.env.REDIS_URL },
+ *   includeWorker: true,
+ * });
+ *
+ * const queue = container.resolve(QUEUE_MANAGER);
+ * await queue.dispatch(myJob, { userId: '123' });
+ *
+ * // If includeWorker was true:
+ * const worker = container.resolve(WORKER_MANAGER);
+ * worker.register(myJob);
+ * await worker.start();
+ * ```
+ */
+export async function registerQueueProviders(container, config = {}) {
+    const { includeWorker, ...queueConfig } = config;
+    // Register config
+    container.register({
+        provide: QUEUE_CONFIG,
+        useValue: queueConfig,
+    });
+    // Create queue manager (async operation)
+    const queueManager = await createQueueManager(queueConfig);
+    // Register the resolved queue manager instance directly
+    // This allows synchronous resolution from the container
+    container.register({
+        provide: QUEUE_MANAGER,
+        useValue: queueManager,
+    });
+    // Optionally create and register worker manager
+    if (includeWorker) {
+        const workerManager = await createWorkerManager(queueConfig);
+        container.register({
+            provide: WORKER_MANAGER,
+            useValue: workerManager,
+        });
+    }
+}

package/dist/tokens.d.ts

@@ -0,0 +1,85 @@
+/**
+ * DI Tokens for @veloxts/queue
+ *
+ * Symbol-based tokens for type-safe dependency injection.
+ * These tokens allow queue services to be registered, resolved, and mocked via the DI container.
+ *
+ * @module queue/tokens
+ *
+ * @example
+ * ```typescript
+ * import { Container } from '@veloxts/core';
+ * import { QUEUE_MANAGER, registerQueueProviders } from '@veloxts/queue';
+ *
+ * const container = new Container();
+ * await registerQueueProviders(container, { driver: 'sync' });
+ *
+ * const queue = container.resolve(QUEUE_MANAGER);
+ * await queue.dispatch(myJob, { data: 'value' });
+ * ```
+ */
+import type { QueueManager, WorkerManager } from './manager.js';
+import type { QueuePluginOptions, QueueStore, WorkerStore } from './types.js';
+/**
+ * Queue manager token
+ *
+ * The main queue manager instance for dispatching and managing jobs.
+ *
+ * @example
+ * ```typescript
+ * const queue = container.resolve(QUEUE_MANAGER);
+ * await queue.dispatch(sendWelcomeEmail, { userId: '123' });
+ * await queue.getStats();
+ * ```
+ */
+export declare const QUEUE_MANAGER: import("@veloxts/core").SymbolToken<QueueManager>;
+/**
+ * Worker manager token
+ *
+ * The worker manager for processing jobs.
+ *
+ * @example
+ * ```typescript
+ * const worker = container.resolve(WORKER_MANAGER);
+ * worker.register(sendWelcomeEmail);
+ * await worker.start();
+ * ```
+ */
+export declare const WORKER_MANAGER: import("@veloxts/core").SymbolToken<WorkerManager>;
+/**
+ * Queue store token
+ *
+ * The underlying queue store driver (BullMQ or Sync).
+ * Use QUEUE_MANAGER for high-level operations; use this for direct store access.
+ *
+ * @example
+ * ```typescript
+ * const store = container.resolve(QUEUE_STORE);
+ * await store.add('job-name', data, { queue: 'default' });
+ * ```
+ */
+export declare const QUEUE_STORE: import("@veloxts/core").SymbolToken<QueueStore>;
+/**
+ * Worker store token
+ *
+ * The underlying worker store driver for job processing.
+ *
+ * @example
+ * ```typescript
+ * const store = container.resolve(WORKER_STORE);
+ * store.registerHandler('job-name', handler, { queue: 'default' });
+ * ```
+ */
+export declare const WORKER_STORE: import("@veloxts/core").SymbolToken<WorkerStore>;
+/**
+ * Queue configuration token
+ *
+ * Contains queue plugin options including driver and driver-specific config.
+ *
+ * @example
+ * ```typescript
+ * const config = container.resolve(QUEUE_CONFIG);
+ * console.log(config.driver); // 'bullmq' or 'sync'
+ * ```
+ */
+export declare const QUEUE_CONFIG: import("@veloxts/core").SymbolToken<QueuePluginOptions>;

package/dist/tokens.js

@@ -0,0 +1,90 @@
+/**
+ * DI Tokens for @veloxts/queue
+ *
+ * Symbol-based tokens for type-safe dependency injection.
+ * These tokens allow queue services to be registered, resolved, and mocked via the DI container.
+ *
+ * @module queue/tokens
+ *
+ * @example
+ * ```typescript
+ * import { Container } from '@veloxts/core';
+ * import { QUEUE_MANAGER, registerQueueProviders } from '@veloxts/queue';
+ *
+ * const container = new Container();
+ * await registerQueueProviders(container, { driver: 'sync' });
+ *
+ * const queue = container.resolve(QUEUE_MANAGER);
+ * await queue.dispatch(myJob, { data: 'value' });
+ * ```
+ */
+import { token } from '@veloxts/core';
+// ============================================================================
+// Core Queue Tokens
+// ============================================================================
+/**
+ * Queue manager token
+ *
+ * The main queue manager instance for dispatching and managing jobs.
+ *
+ * @example
+ * ```typescript
+ * const queue = container.resolve(QUEUE_MANAGER);
+ * await queue.dispatch(sendWelcomeEmail, { userId: '123' });
+ * await queue.getStats();
+ * ```
+ */
+export const QUEUE_MANAGER = token.symbol('QUEUE_MANAGER');
+/**
+ * Worker manager token
+ *
+ * The worker manager for processing jobs.
+ *
+ * @example
+ * ```typescript
+ * const worker = container.resolve(WORKER_MANAGER);
+ * worker.register(sendWelcomeEmail);
+ * await worker.start();
+ * ```
+ */
+export const WORKER_MANAGER = token.symbol('WORKER_MANAGER');
+/**
+ * Queue store token
+ *
+ * The underlying queue store driver (BullMQ or Sync).
+ * Use QUEUE_MANAGER for high-level operations; use this for direct store access.
+ *
+ * @example
+ * ```typescript
+ * const store = container.resolve(QUEUE_STORE);
+ * await store.add('job-name', data, { queue: 'default' });
+ * ```
+ */
+export const QUEUE_STORE = token.symbol('QUEUE_STORE');
+/**
+ * Worker store token
+ *
+ * The underlying worker store driver for job processing.
+ *
+ * @example
+ * ```typescript
+ * const store = container.resolve(WORKER_STORE);
+ * store.registerHandler('job-name', handler, { queue: 'default' });
+ * ```
+ */
+export const WORKER_STORE = token.symbol('WORKER_STORE');
+// ============================================================================
+// Configuration Tokens
+// ============================================================================
+/**
+ * Queue configuration token
+ *
+ * Contains queue plugin options including driver and driver-specific config.
+ *
+ * @example
+ * ```typescript
+ * const config = container.resolve(QUEUE_CONFIG);
+ * console.log(config.driver); // 'bullmq' or 'sync'
+ * ```
+ */
+export const QUEUE_CONFIG = token.symbol('QUEUE_CONFIG');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@veloxts/queue",
-  "version": "0.6.56",
+  "version": "0.6.58",
   "description": "Background job processing for VeloxTS framework",
   "type": "module",
   "main": "./dist/index.js",
@@ -23,7 +23,7 @@
     "ioredis": "5.6.1",
     "superjson": "2.2.2",
     "zod": "3.24.4",
-    "@veloxts/core": "0.6.56"
+    "@veloxts/core": "0.6.58"
   },
   "devDependencies": {
     "@biomejs/biome": "2.0.0",
@@ -32,7 +32,7 @@
     "fastify": "5.6.2",
     "typescript": "5.8.3",
     "vitest": "4.0.16",
-    "@veloxts/testing": "0.6.56"
+    "@veloxts/testing": "0.6.58"
   },
   "peerDependencies": {
     "fastify": "^5.0.0"