PowerQ - Take control of your async world 🚀

Effortless, prioritized async scheduling for JavaScript and TypeScript.

---

✨ Features

• Priority task queue with binary or dynamic task promotion/demotion
• Configurable concurrency (run many tasks in parallel)
• Customizable queue selection logic
• Cancel queued or running tasks
• Cross-platform: Node.js, React, React Native
• Zero dependencies, ultra-lightweight

---

📦 Installation

npm install powerq
# or
yarn add powerq

---

🚀 Usage

import { PowerQ } from "powerq";

// Create scheduler with concurrency of 3
const scheduler = new PowerQ({ concurrency: 3 });

// Add a normal (default) task
const handle1 = scheduler.add(() => fetch("/api/slow-job"));

// Add a priority task
const handle2 = scheduler.add(() => fetch("/api/vip-job"), { priority: true });

// Await the result (does NOT block the JS thread)
handle1.result.then(console.log).catch(console.error);

// Promote/demote as needed
scheduler.promoteToPriority(handle1.id);
scheduler.demoteToNormal(handle2.id);

// Cancel if needed
handle2.cancel();

// Change concurrency at runtime
scheduler.setConcurrency(5);

// Custom queue selection: favor "aged" normal tasks if they've waited >5s
scheduler.setQueueSelector((priorityQ, normalQ) => {
  if (normalQ.length && Date.now() - normalQ[0].addedAt > 5000) return "normal";
  return "priority";
});

---

🛠 API

new PowerQ(options?)

Create a new scheduler.

• concurrency (number): Max concurrent tasks (default: 1)
• queueSelector (function): Custom selection logic for which queue to draw from

---

.add(taskFn, options?)

Add a task (default: normal queue).

const handle = scheduler.add(() => someAsyncJob(), { priority: true });

Returns a TaskHandle with:

• id: string
• result: Promise<T> — resolves/rejects with task’s outcome
• cancel(): void — cancels this task

---

.promoteToPriority(taskId: string)

Move a normal task to the priority queue.

---

.demoteToNormal(taskId: string)

Move a priority task back to the normal queue.

---

.cancel(taskId: string)

Cancel a queued or running task.

---

.setConcurrency(number)

Change the maximum number of concurrent tasks.

---

.setQueueSelector(fn)

Replace the queue selection strategy at runtime.

---

🧪 Example with Concurrency

const scheduler = new PowerQ({ concurrency: 2 });

const slowTask = (id: number, ms: number) => () =>
  new Promise((res) => setTimeout(() => res(`Task ${id} done`), ms));

const h1 = scheduler.add(slowTask(1, 1000));
const h2 = scheduler.add(slowTask(2, 500));
const h3 = scheduler.add(slowTask(3, 200), { priority: true });

Promise.all([h1.result, h2.result, h3.result]).then(console.log);

---

The package is developed and maintained by S25Digital.