tools.md

🛠️ Tools Utilities

Advanced utility classes to help manage asynchronous workflows, task queues, and other generalized tools for building robust applications.

---

Access the tools utility

import atomix from '@nasriya/atomix';

const tools = atomix.tools;

OR

import * as tools from '@nasriya/atomix/tools';

---

Available Tools

Tool	Description	API Reference
TasksQueue	A prioritized task queue manager for async workflows	API Details
AdaptiveTaskQueue	A task queue with dynamic concurrency adjustment	API Details
EventEmitter	A simple event emitter for event-driven applications	API Details

---

Core APIs

These utilities are available as classes under the tools namespace.

🗂️ TasksQueue

A prioritized task queue manager that helps you run async tasks with priorities and control.

const taskQueue = new atomix.tools.TasksQueue();

taskQueue.addTask({
    id: 'task1',
    priority: 2,
    action: async () => {
        console.log('Running task 1');
    }
});

await taskQueue.untilComplete();

:: See full API reference & examples → ::

⚙️ AdaptiveTaskQueue

An extension of TasksQueue that dynamically adjusts its concurrency limit based on the rate of task additions (RPS). Useful for adaptive workload scaling in real-time.

const adaptiveQueue = new atomix.tools.AdaptiveTaskQueue({
    autoRun: true,
    windowDurationMs: 500,
    recalcDebounce: 100,
});

adaptiveQueue.onConcurrencyUpdate(newLimit => {
    console.log(`Concurrency limit updated to ${newLimit}`);
});

adaptiveQueue.addTask({
    type: 'work',
    action: async () => {
        // your async task here
    }
});

await adaptiveQueue.untilComplete();

:: See full API reference & examples → ::

🔔 EventEmitter

A simple yet structured event system with support for lifecycle hooks and one-time handlers.

const emitter = new atomix.tools.EventEmitter();

// Add a regular handler
emitter.on('message', (text) => {
    console.log('Message received:', text);
});

// Add a one-time handler
emitter.on('message', () => {
    console.log('This runs only once');
}, { once: true });

// Add a beforeAll handler
emitter.on('message', () => {
    console.log('Preparing to emit "message" event');
}, { type: 'beforeAll' });

await emitter.emit('message', 'Hello');
await emitter.emit('message', 'World');

:: See full API reference & examples → ::