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

easy-stack works with bundlers and without a bundler. Bundlers resolve the bare easy-stack import normally. Native browser ESM resolves that same bare import through an import map, with no build or transpilation step:

<script type="importmap">
{
    "imports": {
        "easy-stack": "./node_modules/easy-stack/stack.js"
    }
}
</script>
<script type="module">
    import Stack from 'easy-stack';

    const stack = new Stack();
</script>

Import-map URLs are relative to the HTML document. Serve the page over HTTP(S), and configure the server to expose the mapped node_modules files; file:// is not a supported path. easy-stack currently has zero runtime dependencies, so the complete normal-layout map needs only the package entry and no scoped nested-dependency map.

Alternatively, use stack-vanilla.js as a modern classic script or es5.js for legacy syntax:

<script src="https://unpkg.com/[email protected]/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 94 uniquely identified Unit, Functional, Behavioral, Integration, and Regression cases, all registered through [email protected]. The same shared JavaScript inventory imports easy-stack by package name in Node and real Chrome; Chrome resolves it through the configured native import map. CI proves the exact Node 22.13 floor and Node 24 across Linux, macOS, and Windows; it also verifies composite consumer outcomes, five rendered Playground journeys in real Chrome, same-constructor ESM/CommonJS interop, browser globals, the packed npm artifact, documentation and deployment contracts, 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:behavioral
npm run test:behavioral:chrome
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