easy-stack

easy-stack

Zero-dependency cooperative LIFO execution for Node.js and browsers.

Overview · Why easy-stack · Guide · API · Patterns · Browser · Examples · Playground · Stack vs queue · Benchmarks · Migration · Testing

Quick start

npm install easy-stack

import Stack from 'easy-stack';

const stack = new Stack();
const order = [];

stack.autoRun = false;
stack.add(
    function first() {
        order.push('first');
        this.next();
    },
    function newest() {
        order.push('newest');
        this.next();
    }
);
stack.next();

console.log(order); // ['newest', 'first']

CommonJS remains supported:

const Stack = require('easy-stack');

Both loaders resolve the same synchronous stack.js implementation on Node 22.13 and newer.

Each task receives the stack as this and explicitly continues the flow with this.next(). Execution begins synchronously when autoRun is truthy; set it to false while assembling a batch.

Contract at a glance

API	Result
new Stack()	Creates an isolated stack with autoRun = true and stop = false.
add(...tasks)	Validates and appends functions, starts eligible work, and returns the stack.
next()	Runs the newest pending task and returns undefined.
clear()	Removes pending work and returns the new empty live array.
contents()	Returns the live pending array.
contents(tasks)	Replaces pending work after validating the complete array.
stack	Gets or replaces the live pending array.
size	Reports the pending task count.
running	Reports whether a task has started and not yet yielded or drained.

The runner is intentionally cooperative. A task that does not call this.next() keeps the stack active until another part of the program calls next(). New tasks added while active take priority over older pending work.

Why choose it

Choose easy-stack when the newest pending intent should run first and the active task should control the hand-off. It has zero runtime dependencies, exposes pending work for inspection, works in Node and browsers, and keeps its behavior small enough to verify exhaustively. Use a FIFO queue, concurrency pool, or durable job broker when those are the actual requirements.

Read the focused selection guide and version benchmarks.

Captured microbenchmarks compare the exact 2.0.0 WeakMap runtime with 2.1.0 private fields. See the linked page for the complete method, exact timings, machine data, and reproduction command.

Browser entry points

Use stack.js as a native module, stack-vanilla.js as a modern classic script, or es5.js for legacy syntax:

<script src="https://unpkg.com/easy-stack@2.1.0/stack-vanilla.js"></script>
<script>
    const stack = new Stack();
</script>

See the focused browser guide for module and classic-script examples.

Verification

The non-duplicated catalog contains 86 uniquely identified Unit, Functional, Integration, and Regression cases, all registered through vanilla-test@2.1.1. CI proves the exact Node 22.13 floor and Node 24 across Linux, macOS, and Windows; it also verifies same-constructor ESM/CommonJS interop, browser globals, the packed npm artifact, documentation links, the opaque Playground Worker, and 100% statement, branch, function, and line coverage.

npm test
npm run test:unit
npm run test:functional
npm run test:integration
npm run test:regression
npm run test:regression:chrome
npm run coverage
npm run benchmark

Read the testing evidence or the v2 migration guide.

License

MIT © Brandon Nozaki Miller