@casko/queues

Small, focused queue and stack utilities for TypeScript. Use them when you need to keep work, messages, jobs, or values in a predictable order without pulling in a larger data-structure library.

Install

npm install @casko/queues

Implemented Algorithms

Queue

A first-in, first-out line. The first thing added is the first thing removed.

Real-world example: a customer support inbox where the oldest ticket should be answered first.

import { Queue } from "@casko/queues";

const queue = new Queue<string>();

queue.enqueue("first ticket");
queue.enqueue("second ticket");

console.log(queue.dequeue()); // "first ticket"

Deque

A double-ended queue. Add or remove items from either the front or the back.

Real-world example: a browser history list where you can move backward and forward through recently visited pages.

import { Deque } from "@casko/queues";

const pages = new Deque<string>();

pages.pushBack("/home");
pages.pushBack("/settings");
pages.pushFront("/welcome");

console.log(pages.popFront()); // "/welcome"
console.log(pages.popBack()); // "/settings"

PriorityQueue

A queue where the most important item comes out first. By default, lower priority numbers are handled before higher numbers.

Real-world example: a print queue where urgent documents should be printed before routine jobs.

import { PriorityQueue } from "@casko/queues";

const printJobs = new PriorityQueue<string>();

printJobs.enqueue("weekly report", 10);
printJobs.enqueue("boarding pass", 1);

console.log(printJobs.dequeue()); // "boarding pass"

StablePriorityQueue

A priority queue that keeps the original order when two items have the same priority.

Real-world example: hospital triage where patients with the same urgency level should be seen in arrival order.

import { StablePriorityQueue } from "@casko/queues";

const patients = new StablePriorityQueue<string>();

patients.enqueue("Avery", 2);
patients.enqueue("Blake", 2);
patients.enqueue("Casey", 1);

console.log(patients.dequeue()); // "Casey"
console.log(patients.dequeue()); // "Avery"

DelayQueue

A queue where items only become available after a delay or at a specific time.

Real-world example: retrying a failed email delivery after waiting a few minutes.

import { DelayQueue } from "@casko/queues";

const retries = new DelayQueue<string>();
const now = Date.now();

retries.enqueueAt("send welcome email again", now + 5_000);

console.log(retries.dequeue(now)); // undefined
console.log(retries.dequeue(now + 5_000)); // "send welcome email again"

RingBuffer

A fixed-size rolling buffer. When full, new items replace the oldest items.

Real-world example: keeping only the most recent sensor readings on a dashboard.

import { RingBuffer } from "@casko/queues";

const readings = new RingBuffer<number>(3);

readings.push(18);
readings.push(19);
readings.push(20);
readings.push(21);

console.log(readings.toArray()); // [19, 20, 21]

WorkQueue

A queue that runs work with a maximum number of jobs active at the same time.

Real-world example: resizing uploaded images without letting too many CPU-heavy tasks run at once.

import { WorkQueue } from "@casko/queues";

const uploads = new WorkQueue<string>({
  concurrency: 2,
  worker: async (fileName) => {
    await resizeImage(fileName);
  },
});

await Promise.all([
  uploads.enqueue("hero.jpg"),
  uploads.enqueue("avatar.png"),
  uploads.enqueue("gallery.jpg"),
]);

MultiQueue

Several named queues managed together. Each key has its own first-in, first-out line.

Real-world example: processing notifications per user so one user's messages stay in order without blocking everyone else.

import { MultiQueue } from "@casko/queues";

const notifications = new MultiQueue<string, string>();

notifications.enqueue("user-1", "Welcome");
notifications.enqueue("user-2", "Password changed");
notifications.enqueue("user-1", "Trial ends tomorrow");

console.log(notifications.dequeue("user-1")); // "Welcome"

Rotation

A repeating queue that cycles through the same items again and again.

Real-world example: assigning leads to sales representatives in round-robin order.

import { Rotation } from "@casko/queues";

const reps = new Rotation<string>();

reps.enqueue("Nora");
reps.enqueue("Omar");

console.log(reps.dequeue()); // "Nora"
console.log(reps.dequeue()); // "Omar"
console.log(reps.dequeue()); // "Nora"

AsyncQueue

A queue that can be awaited. Consumers can wait for the next item before it exists.

Real-world example: a background service waiting for new messages from a live feed.

import { AsyncQueue } from "@casko/queues";

const messages = new AsyncQueue<string>();

const nextMessage = messages.dequeue();
messages.enqueue("payment received");

console.log(await nextMessage); // "payment received"

BoundedQueue

A queue with a fixed maximum size and a chosen overflow behavior.

Real-world example: buffering log messages while deciding whether to reject new logs or drop older ones when memory is tight.

import { BoundedQueue } from "@casko/queues";

const logs = new BoundedQueue<string>(2, "drop-oldest");

logs.enqueue("started");
logs.enqueue("connected");
logs.enqueue("ready");

console.log(logs.dequeue()); // "connected"

Stack

A last-in, first-out pile. The most recently added item is the first thing removed.

Real-world example: an undo history where the latest action should be undone first.

import { Stack } from "@casko/queues";

const undo = new Stack<string>();

undo.push("type title");
undo.push("change color");

console.log(undo.pop()); // "change color"

Package Contents

The package publishes the compiled dist files, this README.md, and the LICENSE file.