@flightdev/queue 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024-2026 Flight Contributors
+
+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,372 @@
+# @flight-framework/queue
+
+Background job processing for Flight Framework. Run tasks asynchronously with retries, scheduling, and multiple adapters.
+
+## Table of Contents
+
+- [Features](#features)
+- [Installation](#installation)
+- [Quick Start](#quick-start)
+- [Adapters](#adapters)
+- [Defining Jobs](#defining-jobs)
+- [Enqueueing Jobs](#enqueueing-jobs)
+- [Processing Jobs](#processing-jobs)
+- [Scheduling](#scheduling)
+- [Error Handling](#error-handling)
+- [API Reference](#api-reference)
+- [License](#license)
+
+---
+
+## Features
+
+- Multiple storage adapters (Redis, Memory, IndexedDB)
+- Automatic retries with exponential backoff
+- Job scheduling (delayed and recurring)
+- Priority queues
+- Concurrency control
+- Dead letter queue for failed jobs
+- Job batching
+- Progress tracking
+- Type-safe job definitions
+
+---
+
+## Installation
+
+```bash
+npm install @flight-framework/queue
+
+# For Redis adapter
+npm install ioredis
+```
+
+---
+
+## Quick Start
+
+```typescript
+import { createQueue } from '@flight-framework/queue';
+import { redis } from '@flight-framework/queue/redis';
+
+const queue = createQueue(redis({
+    url: process.env.REDIS_URL,
+}));
+
+// Define a job handler
+queue.define('sendEmail', async (job) => {
+    await sendEmail(job.data.to, job.data.subject, job.data.body);
+    console.log(`Email sent to ${job.data.to}`);
+});
+
+// Enqueue a job
+await queue.enqueue('sendEmail', {
+    to: 'user@example.com',
+    subject: 'Welcome!',
+    body: 'Thanks for signing up.',
+});
+
+// Start processing
+queue.process();
+```
+
+---
+
+## Adapters
+
+### Redis (Production)
+
+Persistent, distributed queue using Redis.
+
+```typescript
+import { redis } from '@flight-framework/queue/redis';
+
+const adapter = redis({
+    url: process.env.REDIS_URL,
+    prefix: 'myapp:queue:',  // Key prefix
+    maxRetries: 3,
+});
+```
+
+### Memory (Development)
+
+In-memory queue for development and testing.
+
+```typescript
+import { memory } from '@flight-framework/queue/memory';
+
+const adapter = memory();
+```
+
+### IndexedDB (Client-Side)
+
+Browser-based queue for offline-capable apps.
+
+```typescript
+import { indexeddb } from '@flight-framework/queue-indexeddb';
+
+const adapter = indexeddb({
+    dbName: 'myapp-queue',
+});
+```
+
+---
+
+## Defining Jobs
+
+### Basic Definition
+
+```typescript
+queue.define('processImage', async (job) => {
+    const { imageUrl, size } = job.data;
+    const result = await resizeImage(imageUrl, size);
+    return result;
+});
+```
+
+### With Options
+
+```typescript
+queue.define('sendNotification', async (job) => {
+    await sendPushNotification(job.data);
+}, {
+    retries: 5,
+    backoff: 'exponential',
+    timeout: 30000,  // 30 seconds
+    priority: 'high',
+});
+```
+
+### Type-Safe Jobs
+
+```typescript
+interface EmailJob {
+    to: string;
+    subject: string;
+    body: string;
+    attachments?: string[];
+}
+
+queue.define<EmailJob>('sendEmail', async (job) => {
+    // job.data is typed as EmailJob
+    await sendEmail(job.data.to, job.data.subject, job.data.body);
+});
+```
+
+---
+
+## Enqueueing Jobs
+
+### Basic Enqueue
+
+```typescript
+await queue.enqueue('sendEmail', {
+    to: 'user@example.com',
+    subject: 'Hello',
+    body: 'World',
+});
+```
+
+### With Options
+
+```typescript
+await queue.enqueue('sendEmail', data, {
+    delay: 60000,           // Delay 1 minute
+    priority: 'high',       // high, normal, low
+    attempts: 5,            // Max retry attempts
+    backoff: 'exponential', // Retry strategy
+    jobId: 'unique-id',     // Dedupe by ID
+});
+```
+
+### Delayed Jobs
+
+```typescript
+// Run in 5 minutes
+await queue.enqueue('reminder', data, {
+    delay: 5 * 60 * 1000,
+});
+
+// Run at specific time
+await queue.enqueue('reminder', data, {
+    runAt: new Date('2026-01-15T10:00:00Z'),
+});
+```
+
+### Batch Enqueue
+
+```typescript
+await queue.enqueueMany('sendEmail', [
+    { to: 'user1@example.com', subject: 'Hello' },
+    { to: 'user2@example.com', subject: 'Hello' },
+    { to: 'user3@example.com', subject: 'Hello' },
+]);
+```
+
+---
+
+## Processing Jobs
+
+### Start Processing
+
+```typescript
+// Process all queues
+queue.process();
+
+// Process specific queues with concurrency
+queue.process({
+    queues: ['sendEmail', 'processImage'],
+    concurrency: 5,
+});
+```
+
+### Graceful Shutdown
+
+```typescript
+process.on('SIGTERM', async () => {
+    await queue.shutdown({ timeout: 30000 });
+    process.exit(0);
+});
+```
+
+### Progress Updates
+
+```typescript
+queue.define('processVideo', async (job) => {
+    for (let i = 0; i <= 100; i += 10) {
+        await processChunk(job.data, i);
+        await job.updateProgress(i);
+    }
+});
+
+// Listen to progress
+queue.on('progress', (jobId, progress) => {
+    console.log(`Job ${jobId}: ${progress}%`);
+});
+```
+
+---
+
+## Scheduling
+
+### Recurring Jobs
+
+```typescript
+import { schedule } from '@flight-framework/queue';
+
+// Run every hour
+schedule(queue, 'cleanup', {}, {
+    pattern: '0 * * * *',  // Cron pattern
+});
+
+// Run every 5 minutes
+schedule(queue, 'healthCheck', {}, {
+    every: 5 * 60 * 1000,
+});
+```
+
+### Cron Patterns
+
+| Pattern | Description |
+|---------|-------------|
+| `0 * * * *` | Every hour |
+| `0 0 * * *` | Every day at midnight |
+| `0 0 * * 0` | Every Sunday |
+| `*/5 * * * *` | Every 5 minutes |
+| `0 9 * * 1-5` | 9am on weekdays |
+
+---
+
+## Error Handling
+
+### Retry Strategy
+
+```typescript
+queue.define('unreliableTask', handler, {
+    retries: 3,
+    backoff: 'exponential',  // 1s, 2s, 4s, 8s...
+    // or: 'linear'          // 1s, 2s, 3s, 4s...
+    // or: 'fixed'           // 1s, 1s, 1s, 1s...
+});
+```
+
+### Dead Letter Queue
+
+Jobs that exceed max retries go to the dead letter queue:
+
+```typescript
+// Get failed jobs
+const failed = await queue.getDeadJobs();
+
+// Retry a dead job
+await queue.retryDead(jobId);
+
+// Clear dead jobs
+await queue.clearDead();
+```
+
+### Event Listeners
+
+```typescript
+queue.on('completed', (job) => {
+    console.log(`Job ${job.id} completed`);
+});
+
+queue.on('failed', (job, error) => {
+    console.error(`Job ${job.id} failed:`, error);
+});
+
+queue.on('stalled', (job) => {
+    console.warn(`Job ${job.id} stalled`);
+});
+```
+
+---
+
+## API Reference
+
+### createQueue Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `concurrency` | `number` | `1` | Max concurrent jobs |
+| `prefix` | `string` | `'queue:'` | Key prefix |
+| `defaultRetries` | `number` | `3` | Default retry count |
+
+### queue.define Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `retries` | `number` | `3` | Max retries |
+| `backoff` | `string` | `'exponential'` | Retry strategy |
+| `timeout` | `number` | `30000` | Job timeout (ms) |
+| `priority` | `string` | `'normal'` | Queue priority |
+
+### queue.enqueue Options
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `delay` | `number` | Delay in ms |
+| `runAt` | `Date` | Specific run time |
+| `priority` | `string` | Job priority |
+| `attempts` | `number` | Max attempts |
+| `jobId` | `string` | Unique job ID |
+
+### Queue Methods
+
+| Method | Description |
+|--------|-------------|
+| `define(name, handler, opts?)` | Define job handler |
+| `enqueue(name, data, opts?)` | Add job to queue |
+| `enqueueMany(name, items)` | Batch enqueue |
+| `process(opts?)` | Start processing |
+| `shutdown(opts?)` | Graceful shutdown |
+| `getJob(id)` | Get job by ID |
+| `getDeadJobs()` | Get failed jobs |
+| `retryDead(id)` | Retry failed job |
+
+---
+
+## License
+
+MIT

package/dist/adapters/bullmq.d.ts

@@ -0,0 +1,62 @@
+import * as _bullmq from 'bullmq';
+import { QueueAdapter } from '../index.js';
+
+interface BullMQConfig {
+    /** Redis connection options */
+    connection: {
+        host?: string;
+        port?: number;
+        password?: string;
+        db?: number;
+        url?: string;
+    };
+    /** Queue name (default: 'flight-jobs') */
+    queueName?: string;
+    /** Default job options */
+    defaultJobOptions?: {
+        attempts?: number;
+        backoff?: {
+            type: 'exponential' | 'fixed';
+            delay: number;
+        };
+        removeOnComplete?: boolean | number;
+        removeOnFail?: boolean | number;
+    };
+}
+/**
+ * Create a BullMQ adapter for the queue service.
+ *
+ * @param config - BullMQ configuration
+ * @returns Queue adapter
+ */
+declare function bullmq(config: BullMQConfig): QueueAdapter;
+/**
+ * Create a BullMQ worker for processing jobs.
+ *
+ * This is an advanced API for when you need more control over the worker.
+ * For most cases, use queue.process() instead.
+ *
+ * @example
+ * ```typescript
+ * import { createBullMQWorker } from '@flightdev/queue/bullmq';
+ *
+ * const worker = await createBullMQWorker({
+ *     connection: { host: 'localhost' },
+ *     queueName: 'my-jobs',
+ *     processor: async (job) => {
+ *         console.log('Processing:', job.name);
+ *         // ... job logic
+ *     },
+ *     concurrency: 10,
+ * });
+ *
+ * // Graceful shutdown
+ * process.on('SIGTERM', () => worker.close());
+ * ```
+ */
+declare function createBullMQWorker(config: BullMQConfig & {
+    processor: (job: any) => Promise<void>;
+    concurrency?: number;
+}): Promise<_bullmq.Worker<any, void, string>>;
+
+export { type BullMQConfig, bullmq, createBullMQWorker };

package/dist/adapters/bullmq.js

@@ -0,0 +1,141 @@
+// src/adapters/bullmq.ts
+function bullmq(config) {
+  const queueName = config.queueName ?? "flight-jobs";
+  let Queue;
+  let Worker;
+  let queueInstance;
+  let workerInstance;
+  async function getQueue() {
+    if (!queueInstance) {
+      const bullmqModule = await import("bullmq");
+      Queue = bullmqModule.Queue;
+      queueInstance = new Queue(queueName, {
+        connection: config.connection,
+        defaultJobOptions: {
+          attempts: config.defaultJobOptions?.attempts ?? 3,
+          backoff: config.defaultJobOptions?.backoff ?? {
+            type: "exponential",
+            delay: 1e3
+          },
+          removeOnComplete: config.defaultJobOptions?.removeOnComplete ?? 100,
+          removeOnFail: config.defaultJobOptions?.removeOnFail ?? 1e3
+        }
+      });
+    }
+    return queueInstance;
+  }
+  function mapStatus(bullmqState) {
+    const statusMap = {
+      waiting: "pending",
+      delayed: "pending",
+      active: "processing",
+      completed: "completed",
+      failed: "failed"
+    };
+    return statusMap[bullmqState] ?? "pending";
+  }
+  function toJob(bullmqJob) {
+    return {
+      id: bullmqJob.id,
+      name: bullmqJob.name,
+      data: bullmqJob.data,
+      status: mapStatus(bullmqJob.getState?.() ?? "waiting"),
+      attempts: bullmqJob.attemptsMade ?? 0,
+      maxAttempts: bullmqJob.opts?.attempts ?? 3,
+      createdAt: new Date(bullmqJob.timestamp),
+      scheduledAt: bullmqJob.delay ? new Date(bullmqJob.timestamp + bullmqJob.delay) : void 0,
+      startedAt: bullmqJob.processedOn ? new Date(bullmqJob.processedOn) : void 0,
+      completedAt: bullmqJob.finishedOn ? new Date(bullmqJob.finishedOn) : void 0,
+      error: bullmqJob.failedReason
+    };
+  }
+  return {
+    name: "bullmq",
+    async enqueue(name, data, options) {
+      const queue = await getQueue();
+      const bullmqOptions = {};
+      if (options?.delay) {
+        bullmqOptions.delay = options.delay;
+      }
+      if (options?.maxAttempts) {
+        bullmqOptions.attempts = options.maxAttempts;
+      }
+      if (options?.priority) {
+        bullmqOptions.priority = options.priority;
+      }
+      if (options?.scheduledAt) {
+        bullmqOptions.delay = options.scheduledAt.getTime() - Date.now();
+      }
+      const job = await queue.add(name, data, bullmqOptions);
+      return toJob(job);
+    },
+    async dequeue(_name) {
+      const queue = await getQueue();
+      const jobs = await queue.getWaiting(0, 0);
+      if (jobs.length > 0) {
+        return toJob(jobs[0]);
+      }
+      return null;
+    },
+    async complete(jobId) {
+      const queue = await getQueue();
+      const job = await queue.getJob(jobId);
+      if (job) {
+        await job.moveToCompleted("done", true);
+      }
+    },
+    async fail(jobId, error) {
+      const queue = await getQueue();
+      const job = await queue.getJob(jobId);
+      if (job) {
+        await job.moveToFailed(new Error(error), true);
+      }
+    },
+    async retry(jobId) {
+      const queue = await getQueue();
+      const job = await queue.getJob(jobId);
+      if (job) {
+        await job.retry();
+      }
+    },
+    async getJob(jobId) {
+      const queue = await getQueue();
+      const job = await queue.getJob(jobId);
+      if (!job) return null;
+      return toJob(job);
+    },
+    async getStats() {
+      const queue = await getQueue();
+      const counts = await queue.getJobCounts();
+      return {
+        pending: (counts.waiting ?? 0) + (counts.delayed ?? 0),
+        processing: counts.active ?? 0,
+        completed: counts.completed ?? 0,
+        failed: counts.failed ?? 0
+      };
+    }
+  };
+}
+async function createBullMQWorker(config) {
+  const { Worker } = await import("bullmq");
+  const queueName = config.queueName ?? "flight-jobs";
+  const worker = new Worker(
+    queueName,
+    config.processor,
+    {
+      connection: config.connection,
+      concurrency: config.concurrency ?? 1
+    }
+  );
+  worker.on("completed", (job) => {
+    console.log(`[BullMQ] Job ${job.id} completed`);
+  });
+  worker.on("failed", (job, err) => {
+    console.error(`[BullMQ] Job ${job?.id} failed:`, err.message);
+  });
+  return worker;
+}
+export {
+  bullmq,
+  createBullMQWorker
+};

package/dist/adapters/memory.d.ts

@@ -0,0 +1,9 @@
+import { QueueAdapterFactory } from '../index.js';
+
+/**
+ * In-Memory Queue Adapter (for development/testing)
+ */
+
+declare const memory: QueueAdapterFactory<void>;
+
+export { memory as default, memory };

package/dist/adapters/memory.js

@@ -0,0 +1,74 @@
+// src/adapters/memory.ts
+var memory = () => {
+  const jobs = /* @__PURE__ */ new Map();
+  const queue = [];
+  let idCounter = 0;
+  const adapter = {
+    name: "memory",
+    async enqueue(name, data, options) {
+      const job = {
+        id: `job_${++idCounter}`,
+        name,
+        data,
+        status: "pending",
+        attempts: 0,
+        maxAttempts: options?.maxAttempts ?? 3,
+        createdAt: /* @__PURE__ */ new Date(),
+        scheduledAt: options?.scheduledAt
+      };
+      jobs.set(job.id, job);
+      queue.push(job.id);
+      return job;
+    },
+    async dequeue() {
+      const jobId = queue.shift();
+      if (!jobId) return null;
+      const job = jobs.get(jobId);
+      if (!job || job.status !== "pending") return null;
+      job.status = "processing";
+      job.startedAt = /* @__PURE__ */ new Date();
+      job.attempts++;
+      return job;
+    },
+    async complete(jobId) {
+      const job = jobs.get(jobId);
+      if (job) {
+        job.status = "completed";
+        job.completedAt = /* @__PURE__ */ new Date();
+      }
+    },
+    async fail(jobId, error) {
+      const job = jobs.get(jobId);
+      if (job) {
+        job.status = "failed";
+        job.error = error;
+      }
+    },
+    async retry(jobId) {
+      const job = jobs.get(jobId);
+      if (job) {
+        job.status = "pending";
+        queue.push(jobId);
+      }
+    },
+    async getJob(jobId) {
+      return jobs.get(jobId) ?? null;
+    },
+    async getStats() {
+      let pending = 0, processing = 0, completed = 0, failed = 0;
+      for (const job of jobs.values()) {
+        if (job.status === "pending") pending++;
+        else if (job.status === "processing") processing++;
+        else if (job.status === "completed") completed++;
+        else if (job.status === "failed") failed++;
+      }
+      return { pending, processing, completed, failed };
+    }
+  };
+  return adapter;
+};
+var memory_default = memory;
+export {
+  memory_default as default,
+  memory
+};

package/dist/adapters/redis.d.ts

@@ -0,0 +1,13 @@
+import { QueueAdapterFactory } from '../index.js';
+
+/**
+ * Redis Queue Adapter
+ */
+
+interface RedisConfig {
+    url?: string;
+    prefix?: string;
+}
+declare const redis: QueueAdapterFactory<RedisConfig>;
+
+export { type RedisConfig, redis as default, redis };

package/dist/adapters/redis.js

@@ -0,0 +1,98 @@
+// src/adapters/redis.ts
+var redis = (config = {}) => {
+  const { url = "redis://localhost:6379", prefix = "flight:queue:" } = config;
+  let client = null;
+  async function getClient() {
+    if (!client) {
+      try {
+        const Redis = (await import("ioredis")).default;
+        client = new Redis(url);
+      } catch {
+        throw new Error("@flightdev/queue: ioredis not installed. Run: npm install ioredis");
+      }
+    }
+    return client;
+  }
+  const adapter = {
+    name: "redis",
+    async enqueue(name, data, options) {
+      const redis2 = await getClient();
+      const job = {
+        id: `job_${Date.now()}_${Math.random().toString(36).slice(2)}`,
+        name,
+        data,
+        status: "pending",
+        attempts: 0,
+        maxAttempts: options?.maxAttempts ?? 3,
+        createdAt: /* @__PURE__ */ new Date()
+      };
+      await redis2.lpush(`${prefix}pending`, JSON.stringify(job));
+      await redis2.hset(`${prefix}jobs`, job.id, JSON.stringify(job));
+      return job;
+    },
+    async dequeue() {
+      const redis2 = await getClient();
+      const data = await redis2.rpop(`${prefix}pending`);
+      if (!data) return null;
+      const job = JSON.parse(data);
+      job.status = "processing";
+      job.attempts++;
+      await redis2.hset(`${prefix}jobs`, job.id, JSON.stringify(job));
+      return job;
+    },
+    async complete(jobId) {
+      const redis2 = await getClient();
+      const data = await redis2.hget(`${prefix}jobs`, jobId);
+      if (data) {
+        const job = JSON.parse(data);
+        job.status = "completed";
+        job.completedAt = /* @__PURE__ */ new Date();
+        await redis2.hset(`${prefix}jobs`, jobId, JSON.stringify(job));
+      }
+    },
+    async fail(jobId, error) {
+      const redis2 = await getClient();
+      const data = await redis2.hget(`${prefix}jobs`, jobId);
+      if (data) {
+        const job = JSON.parse(data);
+        job.status = "failed";
+        job.error = error;
+        await redis2.hset(`${prefix}jobs`, jobId, JSON.stringify(job));
+      }
+    },
+    async retry(jobId) {
+      const redis2 = await getClient();
+      const data = await redis2.hget(`${prefix}jobs`, jobId);
+      if (data) {
+        const job = JSON.parse(data);
+        job.status = "pending";
+        await redis2.lpush(`${prefix}pending`, JSON.stringify(job));
+        await redis2.hset(`${prefix}jobs`, jobId, JSON.stringify(job));
+      }
+    },
+    async getJob(jobId) {
+      const redis2 = await getClient();
+      const data = await redis2.hget(`${prefix}jobs`, jobId);
+      return data ? JSON.parse(data) : null;
+    },
+    async getStats() {
+      const redis2 = await getClient();
+      const all = await redis2.hgetall(`${prefix}jobs`);
+      let pending = 0, processing = 0, completed = 0, failed = 0;
+      for (const val of Object.values(all)) {
+        const job = JSON.parse(val);
+        if (job.status === "pending") pending++;
+        else if (job.status === "processing") processing++;
+        else if (job.status === "completed") completed++;
+        else if (job.status === "failed") failed++;
+      }
+      return { pending, processing, completed, failed };
+    }
+  };
+  return adapter;
+};
+var redis_default = redis;
+export {
+  redis_default as default,
+  redis
+};

package/dist/index.d.ts

@@ -0,0 +1,80 @@
+/**
+ * @flightdev/queue - Agnostic Background Job Queue
+ *
+ * @example
+ * ```typescript
+ * import { createQueue } from '@flightdev/queue';
+ * import { redis } from '@flightdev/queue/redis';
+ *
+ * const queue = createQueue(redis({ url: process.env.REDIS_URL }));
+ *
+ * // Define a job
+ * queue.define('sendEmail', async (job) => {
+ *   await sendEmail(job.data.to, job.data.subject, job.data.body);
+ * });
+ *
+ * // Enqueue a job
+ * await queue.enqueue('sendEmail', { to: 'user@example.com', subject: 'Welcome!' });
+ *
+ * // Start processing
+ * queue.process();
+ * ```
+ */
+type JobStatus = 'pending' | 'processing' | 'completed' | 'failed' | 'retrying';
+interface Job<T = unknown> {
+    id: string;
+    name: string;
+    data: T;
+    status: JobStatus;
+    attempts: number;
+    maxAttempts: number;
+    createdAt: Date;
+    scheduledAt?: Date;
+    startedAt?: Date;
+    completedAt?: Date;
+    error?: string;
+}
+interface JobOptions {
+    delay?: number;
+    maxAttempts?: number;
+    priority?: number;
+    scheduledAt?: Date;
+}
+type JobHandler<T = unknown> = (job: Job<T>) => Promise<void>;
+interface QueueAdapter {
+    readonly name: string;
+    enqueue<T>(name: string, data: T, options?: JobOptions): Promise<Job<T>>;
+    dequeue(name?: string): Promise<Job | null>;
+    complete(jobId: string): Promise<void>;
+    fail(jobId: string, error: string): Promise<void>;
+    retry(jobId: string): Promise<void>;
+    getJob(jobId: string): Promise<Job | null>;
+    getStats(): Promise<{
+        pending: number;
+        processing: number;
+        completed: number;
+        failed: number;
+    }>;
+}
+type QueueAdapterFactory<TConfig = unknown> = (config?: TConfig) => QueueAdapter;
+interface QueueService {
+    readonly adapter: QueueAdapter;
+    define<T>(name: string, handler: JobHandler<T>): void;
+    enqueue<T>(name: string, data: T, options?: JobOptions): Promise<Job<T>>;
+    dequeue(name?: string): Promise<Job | null>;
+    complete(jobId: string): Promise<void>;
+    fail(jobId: string, error: string): Promise<void>;
+    retry(jobId: string): Promise<void>;
+    getJob(jobId: string): Promise<Job | null>;
+    process(concurrency?: number): void;
+    stop(): void;
+    getStats(): Promise<{
+        pending: number;
+        processing: number;
+        completed: number;
+        failed: number;
+    }>;
+}
+declare function createQueue(adapter: QueueAdapter): QueueService;
+
+export { type Job, type JobHandler, type JobOptions, type JobStatus, type QueueAdapter, type QueueAdapterFactory, type QueueService, createQueue };

package/dist/index.js

@@ -0,0 +1,71 @@
+// src/index.ts
+function createQueue(adapter) {
+  const handlers = /* @__PURE__ */ new Map();
+  let processing = false;
+  let intervalId = null;
+  async function processJob() {
+    const job = await adapter.dequeue();
+    if (!job) return;
+    const handler = handlers.get(job.name);
+    if (!handler) {
+      await adapter.fail(job.id, `No handler for job: ${job.name}`);
+      return;
+    }
+    try {
+      await handler(job);
+      await adapter.complete(job.id);
+    } catch (error) {
+      const errorMsg = error instanceof Error ? error.message : "Unknown error";
+      if (job.attempts < job.maxAttempts) {
+        await adapter.retry(job.id);
+      } else {
+        await adapter.fail(job.id, errorMsg);
+      }
+    }
+  }
+  return {
+    adapter,
+    define(name, handler) {
+      handlers.set(name, handler);
+    },
+    enqueue(name, data, options) {
+      return adapter.enqueue(name, data, options);
+    },
+    dequeue(name) {
+      return adapter.dequeue(name);
+    },
+    complete(jobId) {
+      return adapter.complete(jobId);
+    },
+    fail(jobId, error) {
+      return adapter.fail(jobId, error);
+    },
+    retry(jobId) {
+      return adapter.retry(jobId);
+    },
+    getJob(jobId) {
+      return adapter.getJob(jobId);
+    },
+    process(concurrency = 1) {
+      if (processing) return;
+      processing = true;
+      intervalId = setInterval(async () => {
+        const promises = Array.from({ length: concurrency }, () => processJob());
+        await Promise.all(promises);
+      }, 100);
+    },
+    stop() {
+      processing = false;
+      if (intervalId) {
+        clearInterval(intervalId);
+        intervalId = null;
+      }
+    },
+    getStats() {
+      return adapter.getStats();
+    }
+  };
+}
+export {
+  createQueue
+};

package/dist/jobs.d.ts

@@ -0,0 +1,212 @@
+import { Job, JobOptions, QueueService } from './index.js';
+
+/**
+ * Declarative Job Definition API
+ *
+ * A more declarative way to define jobs with configuration,
+ * validation, and type safety.
+ *
+ * @example
+ * ```typescript
+ * import { defineJob, createJobRunner } from '@flightdev/queue/jobs';
+ * import { z } from 'zod';
+ *
+ * // Define a job with schema validation
+ * const sendEmailJob = defineJob({
+ *     name: 'sendEmail',
+ *     schema: z.object({
+ *         to: z.string().email(),
+ *         subject: z.string(),
+ *         body: z.string(),
+ *     }),
+ *     handler: async ({ data, log }) => {
+ *         log.info(`Sending email to ${data.to}`);
+ *         await emailService.send(data);
+ *         return { sent: true };
+ *     },
+ *     options: {
+ *         maxAttempts: 3,
+ *         backoff: 'exponential',
+ *     },
+ * });
+ *
+ * // Enqueue with type safety
+ * await sendEmailJob.enqueue({ to: 'user@example.com', subject: 'Hi!' });
+ * ```
+ */
+
+/**
+ * Logger interface for job execution.
+ */
+interface JobLogger {
+    info: (message: string, data?: Record<string, unknown>) => void;
+    warn: (message: string, data?: Record<string, unknown>) => void;
+    error: (message: string, data?: Record<string, unknown>) => void;
+    debug: (message: string, data?: Record<string, unknown>) => void;
+}
+/**
+ * Context passed to job handlers.
+ */
+interface JobContext<TData> {
+    /** The job data */
+    data: TData;
+    /** Job metadata */
+    job: Job<TData>;
+    /** Logger scoped to this job */
+    log: JobLogger;
+    /** Report progress (0-100) */
+    progress: (percent: number) => Promise<void>;
+    /** Abort signal for cancellation */
+    signal: AbortSignal;
+}
+/**
+ * Result from a job handler.
+ */
+type JobResult = void | unknown;
+/**
+ * Job handler function with context.
+ */
+type JobHandlerFn<TData, TResult = JobResult> = (context: JobContext<TData>) => Promise<TResult>;
+/**
+ * Backoff strategy for retries.
+ */
+type BackoffStrategy = 'linear' | 'exponential' | 'fixed' | number[];
+/**
+ * Job definition options.
+ */
+interface JobDefinitionOptions {
+    /** Maximum retry attempts (default: 3) */
+    maxAttempts?: number;
+    /** Backoff strategy for retries */
+    backoff?: BackoffStrategy;
+    /** Base delay for backoff in ms (default: 1000) */
+    backoffDelay?: number;
+    /** Default priority (higher = processed first) */
+    priority?: number;
+    /** Timeout in ms */
+    timeout?: number;
+    /** Only allow one instance of this job to run at a time */
+    unique?: boolean;
+    /** Rate limit: max jobs per interval */
+    rateLimit?: {
+        max: number;
+        interval: number;
+    };
+}
+/**
+ * Job definition configuration.
+ */
+interface JobDefinition<TData = unknown, TResult = JobResult> {
+    /** Unique job name */
+    name: string;
+    /** Zod-like schema for validation (optional) */
+    schema?: {
+        parse: (data: unknown) => TData;
+    };
+    /** Job handler function */
+    handler: JobHandlerFn<TData, TResult>;
+    /** Job options */
+    options?: JobDefinitionOptions;
+    /** Hook called before job runs */
+    onStart?: (job: Job<TData>) => void | Promise<void>;
+    /** Hook called after job completes */
+    onComplete?: (job: Job<TData>, result: TResult) => void | Promise<void>;
+    /** Hook called when job fails */
+    onError?: (job: Job<TData>, error: Error) => void | Promise<void>;
+}
+/**
+ * Defined job with enqueue methods.
+ */
+interface DefinedJob<TData, TResult = JobResult> {
+    /** Job name */
+    readonly name: string;
+    /** Definition config */
+    readonly definition: JobDefinition<TData, TResult>;
+    /** Enqueue a job */
+    enqueue: (data: TData, options?: Partial<JobOptions>) => Promise<Job<TData>>;
+    /** Schedule a job to run at a specific time */
+    schedule: (data: TData, at: Date) => Promise<Job<TData>>;
+    /** Schedule recurring job */
+    recurring: (data: TData, cron: string) => Promise<void>;
+    /** Register with a queue service */
+    register: (queue: QueueService) => void;
+}
+/**
+ * Set the global queue service for all defined jobs.
+ */
+declare function setGlobalQueue(queue: QueueService): void;
+/**
+ * Get the global queue service.
+ */
+declare function getGlobalQueue(): QueueService | null;
+/**
+ * Define a job with declarative configuration.
+ *
+ * @param definition - Job definition config
+ * @returns Defined job with enqueue methods
+ *
+ * @example
+ * ```typescript
+ * const processOrderJob = defineJob({
+ *     name: 'processOrder',
+ *     schema: OrderSchema,
+ *     handler: async ({ data, log, progress }) => {
+ *         log.info('Processing order', { orderId: data.id });
+ *
+ *         await validateInventory(data);
+ *         await progress(25);
+ *
+ *         await chargePayment(data);
+ *         await progress(50);
+ *
+ *         await shipOrder(data);
+ *         await progress(100);
+ *
+ *         return { shipped: true };
+ *     },
+ *     options: {
+ *         maxAttempts: 3,
+ *         backoff: 'exponential',
+ *         timeout: 60000,
+ *     },
+ *     onComplete: (job, result) => {
+ *         console.log(`Order ${job.data.id} processed:`, result);
+ *     },
+ * });
+ * ```
+ */
+declare function defineJob<TData = unknown, TResult = JobResult>(definition: JobDefinition<TData, TResult>): DefinedJob<TData, TResult>;
+/**
+ * Create a job runner that processes defined jobs.
+ *
+ * @example
+ * ```typescript
+ * const runner = createJobRunner({
+ *     queue,
+ *     jobs: [sendEmailJob, processOrderJob],
+ *     concurrency: 5,
+ * });
+ *
+ * await runner.start();
+ * ```
+ */
+declare function createJobRunner(options: {
+    queue: QueueService;
+    jobs: DefinedJob<any, any>[];
+    concurrency?: number;
+}): {
+    start(): void;
+    stop(): void;
+    stats(): Promise<{
+        pending: number;
+        processing: number;
+        completed: number;
+        failed: number;
+    }>;
+};
+/**
+ * Calculate backoff delay based on strategy.
+ */
+declare function calculateBackoff(attempt: number, strategy: BackoffStrategy, baseDelay?: number): number;
+
+export { type BackoffStrategy, type DefinedJob, type JobContext, type JobDefinition, type JobDefinitionOptions, type JobHandlerFn, type JobLogger, type JobResult, calculateBackoff, createJobRunner, defineJob, getGlobalQueue, setGlobalQueue };

package/dist/jobs.js

@@ -0,0 +1,134 @@
+// src/jobs.ts
+var globalQueue = null;
+function setGlobalQueue(queue) {
+  globalQueue = queue;
+}
+function getGlobalQueue() {
+  return globalQueue;
+}
+function defineJob(definition) {
+  let registeredQueue = null;
+  function createLogger(jobId) {
+    const prefix = `[Job:${definition.name}:${jobId}]`;
+    return {
+      info: (msg, data) => console.log(`${prefix} ${msg}`, data ?? ""),
+      warn: (msg, data) => console.warn(`${prefix} ${msg}`, data ?? ""),
+      error: (msg, data) => console.error(`${prefix} ${msg}`, data ?? ""),
+      debug: (msg, data) => console.debug(`${prefix} ${msg}`, data ?? "")
+    };
+  }
+  function createHandler() {
+    return async (job) => {
+      const controller = new AbortController();
+      const log = createLogger(job.id);
+      let timeoutId;
+      if (definition.options?.timeout) {
+        timeoutId = setTimeout(() => {
+          controller.abort();
+        }, definition.options.timeout);
+      }
+      const context = {
+        data: job.data,
+        job,
+        log,
+        signal: controller.signal,
+        progress: async (_percent) => {
+        }
+      };
+      try {
+        if (definition.schema) {
+          context.data = definition.schema.parse(job.data);
+        }
+        if (definition.onStart) {
+          await definition.onStart(job);
+        }
+        const result = await definition.handler(context);
+        if (definition.onComplete) {
+          await definition.onComplete(job, result);
+        }
+      } catch (error) {
+        if (definition.onError) {
+          await definition.onError(job, error);
+        }
+        throw error;
+      } finally {
+        if (timeoutId) {
+          clearTimeout(timeoutId);
+        }
+      }
+    };
+  }
+  function getQueue() {
+    const queue = registeredQueue ?? globalQueue;
+    if (!queue) {
+      throw new Error(
+        `No queue registered for job "${definition.name}". Call job.register(queue) or setGlobalQueue(queue) first.`
+      );
+    }
+    return queue;
+  }
+  return {
+    name: definition.name,
+    definition,
+    async enqueue(data, options) {
+      const queue = getQueue();
+      return queue.enqueue(definition.name, data, {
+        maxAttempts: definition.options?.maxAttempts ?? 3,
+        priority: definition.options?.priority,
+        ...options
+      });
+    },
+    async schedule(data, at) {
+      const queue = getQueue();
+      return queue.enqueue(definition.name, data, {
+        maxAttempts: definition.options?.maxAttempts ?? 3,
+        scheduledAt: at
+      });
+    },
+    async recurring(_data, _cron) {
+      throw new Error("Recurring jobs require an adapter with cron support");
+    },
+    register(queue) {
+      registeredQueue = queue;
+      queue.define(definition.name, createHandler());
+    }
+  };
+}
+function createJobRunner(options) {
+  const { queue, jobs, concurrency = 1 } = options;
+  for (const job of jobs) {
+    job.register(queue);
+  }
+  return {
+    start() {
+      queue.process(concurrency);
+    },
+    stop() {
+      queue.stop();
+    },
+    async stats() {
+      return queue.getStats();
+    }
+  };
+}
+function calculateBackoff(attempt, strategy, baseDelay = 1e3) {
+  if (Array.isArray(strategy)) {
+    return strategy[Math.min(attempt, strategy.length - 1)] ?? baseDelay;
+  }
+  switch (strategy) {
+    case "linear":
+      return baseDelay * attempt;
+    case "exponential":
+      return baseDelay * Math.pow(2, attempt - 1);
+    case "fixed":
+    default:
+      return baseDelay;
+  }
+}
+export {
+  calculateBackoff,
+  createJobRunner,
+  defineJob,
+  getGlobalQueue,
+  setGlobalQueue
+};

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "@flightdev/queue",
+  "version": "0.2.0",
+  "description": "Agnostic background job queue for Flight Framework. Choose your backend: Redis, BullMQ, SQLite, Postgres, SQS.",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./jobs": {
+      "types": "./dist/jobs.d.ts",
+      "import": "./dist/jobs.js"
+    },
+    "./memory": {
+      "types": "./dist/adapters/memory.d.ts",
+      "import": "./dist/adapters/memory.js"
+    },
+    "./redis": {
+      "types": "./dist/adapters/redis.d.ts",
+      "import": "./dist/adapters/redis.js"
+    },
+    "./bullmq": {
+      "types": "./dist/adapters/bullmq.d.ts",
+      "import": "./dist/adapters/bullmq.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "peerDependencies": {
+    "ioredis": ">=5.0.0",
+    "bullmq": ">=5.0.0"
+  },
+  "peerDependenciesMeta": {
+    "ioredis": {
+      "optional": true
+    },
+    "bullmq": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "tsup": "^8.0.0",
+    "typescript": "^5.7.0",
+    "vitest": "^2.0.0"
+  },
+  "license": "MIT",
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
+  }
+}