Registry / web-framework / zalgo-promise

zalgo-promise

library1.0.48jsnpmunverified

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.

web-framework

npm install zalgo-promise

github ↗package ↗

INSTALL

IMPORT

SIG · ZALGO-PROMISE

zalgo-promise

web-frameworkjavascriptv1.0.48

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

ZalgoPromise

✓ import { ZalgoPromise } from 'zalgo-promise';

✗ import ZalgoPromise from 'zalgo-promise'; // Or for CommonJS in ESM context: const ZalgoPromise = require('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.

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.');

Debug

Known issues

breakingZalgoPromise 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.

affects: >=1.0.0

gotchaMixing `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.

affects: >=1.0.0

gotchaWhile 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.

affects: >=1.0.0

gotchaThe 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.

affects: >=1.0.0

Errors

Common errors & fixes

ReferenceError: ZalgoPromise is not defined

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.

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.

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.

Upgrade

Version history

1.0.48latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

22 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/krakenjs/zalgo-promise ↗

packagehttps://www.npmjs.com/package/zalgo-promise ↗