easy-stack

Common errors

• ReferenceError: require is not defined

  cause Attempting to use `require()` in a plain browser environment without a CommonJS bundler like Webpack or Browserify.
  fix For browser usage, include `es5.js` via a `<script>` tag (e.g., `<script src='./node_modules/easy-stack/es5.js'></script>`) to make `Stack` globally available.

• TypeError: Cannot read properties of undefined (reading 'next')

  cause This typically occurs when a function added to the stack (`stack.add(myFunction)`) loses its `this` context, preventing access to `this.next()`. This can happen with arrow functions or improperly bound functions.
  fix Ensure functions passed to `stack.add` are regular functions or are explicitly bound to the stack instance if `this` context is critical (though `easy-stack` usually handles this correctly internally for regular functions).

• TypeError: stack.stop is not a function

  cause Incorrectly attempting to call the `stop` property as a method, when it is a boolean property.
  fix To stop or resume the stack, assign a boolean value directly: `stack.stop = true;` (to stop) or `stack.stop = false;` (to resume).

Warnings

• breaking The license for easy-stack changed from the DBAD Public License to the MIT License. While not a code-breaking change, this alters the legal terms of use and distribution.
  Fix: Review the new MIT license terms if your project's compliance depends on the previous DBAD license.
• gotcha The `stop` property is a boolean flag (`stack.stop = true;`) to halt execution, not a method (`stack.stop();`). Attempting to call it as a function will result in a TypeError.
  Fix: Assign a boolean value directly to `stack.stop` (e.g., `stack.stop = true;`) to control stack execution.
• gotcha easy-stack is fundamentally a CommonJS module. Direct use of ES Modules `import` syntax (`import Stack from 'easy-stack';`) will fail in Node.js environments without a build step or explicit configuration for CJS-ESM interop.
  Fix: Always use `const Stack = require('easy-stack');` for Node.js and bundler environments. For browser, use a script tag or a bundler.
• gotcha The package targets Node.js version 6.0.0 and above. This is an older Node.js version, which means the package may not fully leverage or be tested against modern JavaScript features or security practices available in newer Node.js releases.
  Fix: Consider potential compatibility or security implications when using in highly modern Node.js environments. While functional, it might not integrate seamlessly with very recent ecosystem changes.
• gotcha Functions added to the stack (`stack.add(myFunction)`) must call `this.next()` internally to proceed to the next item in the stack. Failure to do so will halt stack execution prematurely, especially for asynchronous operations.
  Fix: Ensure that every function passed to `stack.add` explicitly calls `this.next()` after its work is done, particularly after any asynchronous tasks, to maintain the execution flow.

Install

• npm install easy-stack npm
• yarn add easy-stack yarn
• pnpm add easy-stack pnpm

Imports

• Stack
  wrong:

  import { Stack } from 'easy-stack';
  import Stack from 'easy-stack';

  correct:

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

  The primary module export for `easy-stack` is the Stack constructor directly, designed for CommonJS. ESM `import` syntax is not natively supported without a bundler configured for CJS interop.
• Stack (ES5)

  const Stack = require('easy-stack/es5.js');

  Use this specific path for environments requiring ES5 compatibility, such as older Node.js versions or direct browser usage without modern transpilation.
• Global Stack (Browser)
  wrong:

  require('easy-stack'); // Fails in browser without a CommonJS bundler

  correct:

  <script src="./node_modules/easy-stack/es5.js"></script>
  <script>
    // Stack is now available globally
    const stack = new Stack();
  </script>

  For direct browser usage without a CommonJS bundler, include the `es5.js` file via a script tag, which exposes `Stack` globally.

Quickstart

Demonstrates initializing a new easy-stack instance, adding functions to it, and the LIFO execution flow with `this.next()` for sequence control, including dynamic additions.

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

// Create a new Stack instance
const stack = new Stack();

let requestCount = 0;

// Add multiple functions to the stack
for (let i = 0; i < 3; i++) {
    stack.add(function makeRequest() {
        requestCount++;
        // Simulate an asynchronous operation
        console.log(`Processing request ${requestCount} from the stack...`);
        setTimeout(() => {
            console.log(`Request ${requestCount} completed.`);
            // Crucially, call this.next() to advance the stack.
            // This ensures the next item is processed, especially if autoRun is false or after an async step.
            this.next();
        }, 50);
    });
}

// Dynamically add a high-priority task later. It will run automatically if `autoRun` is true and the stack is not stopped.
stack.add(function dynamicTask() {
    console.log('A new high-priority task dynamically added to the stack!');
    this.next();
});

console.log('Stack initialized. Items will process in LIFO order (Last-In, First-Out).');