{"id":12700,"library":"zalgo-promise","title":"Zalgo Promise","description":"The `zalgo-promise` library (current stable version 1.0.48) is a specialized JavaScript promise implementation designed to deviate from the standard asynchronous-by-default behavior of native `Promise` objects. It resolves synchronously unless an explicit asynchronous operation (e.g., `setTimeout`, network request) is introduced within the promise chain. This unique characteristic makes it particularly useful for mitigating specific performance bottlenecks in browser environments, such as issues with `setTimeout` deprioritization in unfocused popup windows, or when polyfilling Promises in older browsers where shims might rely on inefficient asynchronous mechanisms. `zalgo-promise` provides a more direct control over execution flow compared to standard promises, making it a niche but valuable tool for developers facing these particular challenges. While it doesn't have a rapid release cadence, it is actively maintained for its specific use case.","status":"active","version":"1.0.48","language":"javascript","source_language":"en","source_url":"git://github.com/krakenjs/zalgo-promise","tags":["javascript","template"],"install":[{"cmd":"npm install zalgo-promise","lang":"bash","label":"npm"},{"cmd":"yarn add zalgo-promise","lang":"bash","label":"yarn"},{"cmd":"pnpm add zalgo-promise","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"For ES6 modules, `ZalgoPromise` is a named export. Ensure you destructure it correctly.","wrong":"import ZalgoPromise from 'zalgo-promise';\n// Or for CommonJS in ESM context:\nconst ZalgoPromise = require('zalgo-promise');","symbol":"ZalgoPromise","correct":"import { ZalgoPromise } from 'zalgo-promise';"},{"note":"Standard CommonJS import pattern for Node.js environments or bundled applications.","symbol":"ZalgoPromise (CommonJS)","correct":"const ZalgoPromise = require('zalgo-promise');"},{"note":"When included directly via a script tag in the browser, `ZalgoPromise` becomes available as a global variable.","symbol":"ZalgoPromise (Global)","correct":"<script src=\"zalgo-promise.js\"></script>\n<script>\n    new ZalgoPromise( ... );\n</script>"}],"quickstart":{"code":"import { ZalgoPromise } from 'zalgo-promise';\n\n// Demonstrates synchronous resolution by default\nconst syncPromise = new ZalgoPromise(function(resolve) {\n    console.log('Creating synchronous promise...');\n    resolve('Synchronous result');\n});\n\nsyncPromise.then(function(result) {\n    console.log(`Handler 1: ${result}`); // This logs synchronously\n});\n\nconsole.log('Code after synchronous promise handler.');\n\n// Demonstrates asynchronous resolution when an async operation is involved\nconst asyncPromise = new ZalgoPromise(function(resolve) {\n    console.log('Creating asynchronous promise...');\n    setTimeout(() => {\n        resolve('Asynchronous result');\n    }, 10);\n});\n\nasyncPromise.then(function(result) {\n    console.log(`Handler 2: ${result}`); // This logs asynchronously after ~10ms\n});\n\nconsole.log('Code after asynchronous promise creation.');","lang":"javascript","description":"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."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":">=1.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Thoroughly understand the library's rationale and behavior before integrating, especially the implications of synchronous vs. asynchronous execution flow.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"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.","cause":"The `ZalgoPromise` symbol was not correctly imported or made available in the current scope.","error":"ReferenceError: ZalgoPromise is not defined"},{"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.","cause":"This is the intended behavior of `zalgo-promise` for synchronously resolvable values. It bypasses the microtask queue that native Promises use.","error":"My promise chain executes immediately, blocking the UI, unlike native Promises."},{"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.","cause":"The synchronous-by-default nature of `ZalgoPromise` conflicts with the always-asynchronous nature of native Promises (even `Promise.resolve()` is async via microtasks).","error":"I'm seeing different execution orders when mixing ZalgoPromise with native Promises."}],"ecosystem":"npm"}