📦 @gotocva/queue

An in-memory event queue for Node.js with retry and backoff support.

🚀 Features

✅ In-memory queue (No Redis, No Database)
✅ Auto-retry failed jobs (with configurable attempts)
✅ Backoff delay before retry
✅ Process jobs sequentially
✅ Simple API, Lightweight, and Fast

📥 Installation

Install via npm:

npm install @gotocva/queue

Install via yarn:

yarn add @gotocva/queue

📌 Usage

1️⃣ Basic Example

const Queue = require('@gotocva/queue');

const jobQueue = new Queue();

// Register event listener to process jobs
jobQueue.on('process', async (job, resolve, reject) => {
  console.log(`Processing job: ${JSON.stringify(job)}`);

  // Simulate a failing job (50% failure rate)
  if (Math.random() > 0.5) {
    return reject(new Error('Random Job Failure'));
  }

  setTimeout(resolve, 1000); // Simulate async task success
});

// Add jobs with retry & backoff
jobQueue.add({ id: 1, task: 'Send Email' }, { attempts: 3, backoff: 5000 });
jobQueue.add({ id: 2, task: 'Generate Report' }, { attempts: 3, backoff: 5000 });

📖 API Reference

🏗 new Queue()

Creates a new instance of the in-memory queue.

📌 .add(job, options)

Adds a job to the queue.

Parameters

• job (Object) → Job data (e.g., { id: 1, task: 'Send Email' })
• options (Object, optional):
  • attempts (Number) → Number of times to retry on failure (default: 3)
  • backoff (Number) → Delay before retrying in ms (default: 5000)

Example

queue.add({ id: 1, task: 'Send Email' }, { attempts: 3, backoff: 5000 });

🔄 .on('process', async (job, resolve, reject) => { ... })

Registers a listener that processes jobs.

Parameters

• job (Object) → The job being processed
• resolve (Function) → Call this when the job succeeds
• reject (Function) → Call this when the job fails

Example

queue.on('process', async (job, resolve, reject) => {
  try {
    console.log(`Processing job: ${job.task}`);
    resolve(); // Mark job as complete
  } catch (error) {
    reject(error); // Retry if job fails
  }
});

⚡ Advanced Example

Simulating API Calls & Retrying on Failure

const Queue = require('@gotocva/queue');
const axios = require('axios');

const apiQueue = new Queue();

// Process jobs (making API request)
apiQueue.on('process', async (job, resolve, reject) => {
  console.log(`Calling API: ${job.url}`);

  try {
    const response = await axios.get(job.url);
    console.log(`✅ API Success: ${response.status}`);
    resolve();
  } catch (error) {
    console.error(`❌ API Failed: ${error.message}`);
    reject(error);
  }
});

// Add an API call job
apiQueue.add({ url: 'https://jsonplaceholder.typicode.com/posts/1' }, { attempts: 5, backoff: 3000 });

🛠 How It Works

| Step | Description | |----------|---------------| | 1️⃣ | Jobs are added to the queue using .add(job, options). | | 2️⃣ | The process event is triggered for each job. | | 3️⃣ | If the job succeeds, resolve() is called. | | 4️⃣ | If the job fails, reject(error) is called, and the job retries based on attempts. | | 5️⃣ | Failed jobs wait (backoff ms) before retrying. |

📌 Why Use @gotocva/queue?

✅ No Dependencies → No need for Redis or external services
✅ Simple API → Just add jobs and listen for events
✅ Fast & Lightweight → Built for high performance
✅ Supports Retries → Ensures jobs are processed reliably

⚖️ Comparison with Other Queues

| Feature | @gotocva/queue | Bull (Redis) | Kue (Redis) | |--------------------|---------------|-------------|-------------| | No Redis Required | ✅ Yes | ❌ No | ❌ No | | Retry & Backoff | ✅ Yes | ✅ Yes | ✅ Yes | | In-Memory | ✅ Yes | ❌ No | ❌ No | | Simple API | ✅ Yes | ❌ Complex | ❌ Complex | | Good for Small Apps | ✅ Yes | ❌ No | ❌ No |

📜 License

This project is licensed under the MIT License - see the LICENSE file for details.

👨‍💻 Author

gotocva - GitHub

⭐ Support

If you like this project, give it a ⭐ on GitHub! 🚀