@yaro.page/nano-queue

🚀 Nano-Queue

A lightweight, cross-platform task manager inspired by Celery for JavaScript environments. Nano-Queue provides asynchronous task execution, worker management, and queue processing for both Node.js and browser environments.

✨ Features

• 🔄 Asynchronous Task Execution - Execute tasks in the background
• 👷 Worker Management - Multiple workers processing different queues
• 🔁 Retry Logic - Automatic retry on task failure
• ⏱️ Delayed Execution - Schedule tasks with countdown delays
• 📊 Queue Monitoring - Track queue status and task results
• 🌐 Cross-Platform - Works in Node.js and browsers
• 📝 Comprehensive Logging - Built-in logger with configurable levels
• 🎯 TypeScript-Ready - Full JSDoc documentation for type hints

📦 Installation

npm install nano-queue

🚀 Quick Start

Basic Usage

import Queue from 'nano-queue'

// Create a Queue instance
const queue = new Queue()

// Define a task
const addTask = queue.task('add')((x, y) => x + y)

// Start workers
await queue.startWorkers(2)

// Execute task
const result = addTask.delay(5, 3)

// Wait for result
setTimeout(() => {
    if (result.ready()) {
        console.log('Result:', result.get()) // Output: 8
    }
}, 1000)

Advanced Usage

import Queue from 'nano-queue'

// Create queue with custom logger level
const queue = new Queue({ logLevel: 'debug' })

// Define async task with options
const processDataTask = queue.task('process_data', {
    retry: 3,
    countdown: 2
})(async (data) => {
    // Simulate processing
    await new Promise(resolve => setTimeout(resolve, 1000))
    return `Processed: ${data}`
});

// Start workers for specific queues
await queue.startWorkers(3, ['data_processing', 'default'])

// Send task to specific queue with options
const result = queue.sendTask('process_data', ['important_data'], {}, {
    queue: 'data_processing',
    countdown: 5,
    retry: true
})

// Monitor queue status
console.log(queue.getQueueStatus())

📚 API Reference

Queue

Main class for managing tasks and workers.

Constructor

new Queue(options)

• options.logLevel - Logging level ('debug', 'info', 'warn', 'error')

Methods

• task(name, options) - Create a task decorator
• sendTask(taskName, args, kwargs, options) - Send task to queue
• startWorkers(count, queues) - Start worker processes
• stopAllWorkers() - Stop all workers
• getQueueStatus() - Get queue status information
• getResult(taskId) - Get task result by ID

Task

Represents an executable task.

Methods

• delay(...args) - Execute task with arguments
• applyAsync(args, kwargs, options) - Execute with detailed options
• execute(args, kwargs) - Direct task execution

TaskResult

Represents the result of task execution.

Methods

• ready() - Check if task is completed
• successful() - Check if task succeeded
• failed() - Check if task failed
• get() - Get task result (throws if failed/not ready)

Worker

Processes tasks from queues.

Methods

• start() - Start processing tasks
• stop() - Stop the worker
• processTask(taskMessage) - Process a single task

🔧 Configuration

Task Options

const task = queue.task('my_task', {
    retry: 3,           // Number of retry attempts
    countdown: 5,       // Delay before execution (seconds)
    expires: 3600       // Task expiration time
});

Execution Options

const result = queue.sendTask('task_name', [arg1, arg2], {}, {
    queue: 'priority',  // Target queue
    countdown: 10,      // Execution delay
    retry: true,        // Enable retries
    maxRetries: 5       // Maximum retry attempts
});

🌐 Browser Usage

Via Bundler

import Queue from 'nano-queue'
// or
import { Queue } from 'nano-queue'
// Works with Webpack, Rollup, Vite, etc.

📊 Examples

Retry Logic

const unstableTask = queue.task('unstable', { retry: 3 })(() => {
    if (Math.random() < 0.7) {
        throw new Error('Random failure')
    }
    return 'Success!'
})

const result = unstableTask.delay()

Multiple Queues

// High priority queue
const urgentTask = queue.task('urgent_task')((data) => {
    return `Urgent: ${data}`
})

// Normal priority queue
const normalTask = queue.task('normal_task')((data) => {
    return `Normal: ${data}`
})

// Start specialized workers
await queue.startWorkers(2, ['urgent'])     // 2 workers for urgent queue
await queue.startWorkers(1, ['normal'])     // 1 worker for normal queue

// Send tasks to different queues
queue.sendTask('urgent_task', ['critical_data'], {}, { queue: 'urgent' })
queue.sendTask('normal_task', ['regular_data'], {}, { queue: 'normal' })

Delayed Execution???

const scheduledTask = queue.task('scheduled')((message) => {
    console.log(`Executed at: ${new Date()}`)
    return message
})

// Execute after 30 seconds
const result = scheduledTask.applyAsync(['Hello World'], {}, { countdown: 30 })

🧪 Testing

npm test                # Run tests
npm run test:watch      # Watch mode
npm run test:coverage   # With coverage report

🔍 Debugging

Enable debug logging:

const queue = new Queue({ logLevel: 'debug' })

// Or change level later
queue.setLogLevel('debug')

🤝 Contributing

• Fork the repository
• Create your feature branch (git checkout -b feature/amazing-feature)
• Commit your changes (git commit -m 'Add amazing feature')
• Push to the branch (git push origin feature/amazing-feature)
• Open a Pull Request

📄 License

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

🙏 Acknowledgments

• Inspired by Celery for Python
• Built for modern JavaScript environments
• Designed for simplicity and performance

📈 Roadmap

• Persistent storage adapters (nano-db/{fs,redis,mongodb})
• Task scheduling with cron expressions
• Web UI for monitoring
• Task dependencies and workflows
• Distributed worker support
• Performance metrics and monitoring

Made with ❤️