easy-stack

easy-stack

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

Overview · Guide · API · Patterns · Browser · Examples · Stack vs queue · 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');

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.

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.0.0/stack-vanilla.js"></script>
<script>
    const stack = new Stack();
</script>

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

Verification

The shared behavior suite runs through vanilla-test@2.1.1 in Node and headless Chrome. A dependency-free fallback proves the shipped runtime on the declared Node 12.22 floor. CI also verifies both module systems, browser globals, the packed npm artifact, documentation links, and 100% statement, branch, function, and line coverage.

npm test
npm run coverage

Read the testing evidence or the v2 migration guide.

License

MIT © Brandon Nozaki Miller