Zalgo Promise

Common errors

• ReferenceError: ZalgoPromise is not defined

  cause The `ZalgoPromise` symbol was not correctly imported or made available in the current scope.
  fix For ES modules, use `import { ZalgoPromise } from 'zalgo-promise';`. For CommonJS, `const ZalgoPromise = require('zalgo-promise');`. If using a global script tag, ensure `zalgo-promise.js` is loaded before your code executes.

• My promise chain executes immediately, blocking the UI, unlike native Promises.

  cause This is the intended behavior of `zalgo-promise` for synchronously resolvable values. It bypasses the microtask queue that native Promises use.
  fix If you need asynchronous, non-blocking behavior (similar to native Promises), you must explicitly introduce an asynchronous operation within your `ZalgoPromise` chain, such as `setTimeout` or a network request.

• I'm seeing different execution orders when mixing ZalgoPromise with native Promises.

  cause The synchronous-by-default nature of `ZalgoPromise` conflicts with the always-asynchronous nature of native Promises (even `Promise.resolve()` is async via microtasks).
  fix Ensure clear boundaries between code sections using `ZalgoPromise` and those using native Promises. Avoid implicitly relying on resolution order when intermixing them. Convert `ZalgoPromise` to a native Promise (e.g., `Promise.resolve(new ZalgoPromise(...))`) if consistency with native behavior is required.

Warnings

• breaking ZalgoPromise fundamentally changes the expected asynchronous behavior of standard JavaScript Promises. Operations that would be asynchronous (via microtask queue) with native `Promise.resolve().then()` will execute synchronously with `ZalgoPromise` unless an explicit asynchronous action is involved.
  Fix: Always assume synchronous execution unless you explicitly introduce an asynchronous operation (e.g., `setTimeout`, network request). If standard async behavior is desired, explicitly use `setTimeout` or native Promises.
• gotcha Mixing `zalgo-promise` with native Promises or other promise polyfills can lead to unpredictable execution order due to their differing resolution models. Operations might complete in an order unexpected by developers accustomed to standard Promise behavior.
  Fix: Be consistent. If `zalgo-promise` is used, try to use it throughout the relevant sections of your codebase. If interacting with native Promises, explicitly convert or understand the timing differences.
• gotcha While designed to prevent hangs in certain browser scenarios, over-reliance on synchronous promise resolution for CPU-intensive tasks can block the main thread, leading to a frozen UI. The benefits of asynchronicity for non-blocking operations are bypassed.
  Fix: Only use `zalgo-promise`'s synchronous behavior where it specifically addresses a `setTimeout` deprioritization or similar browser-specific issue. For general long-running tasks, consider web workers or ensure operations are still explicitly asynchronous.
• gotcha The name 'Zalgo' references an internet meme for 'creepy text' or 'coming from beyond the screen,' implying uncontrolled or unexpected behavior. While humorous, it's a reminder that this library intentionally breaks standard Promise expectations, which can be a footgun if not fully understood.
  Fix: Thoroughly understand the library's rationale and behavior before integrating, especially the implications of synchronous vs. asynchronous execution flow.

Install

• npm install zalgo-promise npm
• yarn add zalgo-promise yarn
• pnpm add zalgo-promise pnpm

Imports

• ZalgoPromise
  wrong:

  import ZalgoPromise from 'zalgo-promise';
  // Or for CommonJS in ESM context:
  const ZalgoPromise = require('zalgo-promise');

  correct:

  import { ZalgoPromise } from 'zalgo-promise';

  For ES6 modules, `ZalgoPromise` is a named export. Ensure you destructure it correctly.
• ZalgoPromise (CommonJS)

  const ZalgoPromise = require('zalgo-promise');

  Standard CommonJS import pattern for Node.js environments or bundled applications.
• ZalgoPromise (Global)

  <script src="zalgo-promise.js"></script>
  <script>
      new ZalgoPromise( ... );
  </script>

  When included directly via a script tag in the browser, `ZalgoPromise` becomes available as a global variable.

Quickstart

This example showcases `zalgo-promise`'s core behavior: synchronous resolution for immediate values and asynchronous resolution when a `setTimeout` (or similar async operation) is introduced.

import { ZalgoPromise } from 'zalgo-promise';

// Demonstrates synchronous resolution by default
const syncPromise = new ZalgoPromise(function(resolve) {
    console.log('Creating synchronous promise...');
    resolve('Synchronous result');
});

syncPromise.then(function(result) {
    console.log(`Handler 1: ${result}`); // This logs synchronously
});

console.log('Code after synchronous promise handler.');

// Demonstrates asynchronous resolution when an async operation is involved
const asyncPromise = new ZalgoPromise(function(resolve) {
    console.log('Creating asynchronous promise...');
    setTimeout(() => {
        resolve('Asynchronous result');
    }, 10);
});

asyncPromise.then(function(result) {
    console.log(`Handler 2: ${result}`); // This logs asynchronously after ~10ms
});

console.log('Code after asynchronous promise creation.');