# zalgo-promise

> Javascript module template.

Latest version **1.0.48** (published 2021-09-24) · 0 weekly downloads

## Install

```sh
npm install zalgo-promise
pnpm add zalgo-promise
yarn add zalgo-promise
bun add zalgo-promise
```

## Health

**Score 33/100 (F)** — status: abandoned.

Positive: has types package; no vulnerabilities; high quality score.

Warnings: low downloads; no esm support.

Negative: abandoned.

## Facts

| | |
|---|---|
| Version | 1.0.48 |
| Published | 2021-09-24 |
| First published | 2017-06-14 |
| Weekly downloads | 0 |
| TypeScript types | separate (@types/zalgo-promise) |
| Module format | CommonJS |
| Dependencies | 0 |
| Unpacked size | 116.2 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 57 |
| Maintainers | bluepnume |
| Keywords | template |

## Links

- npm: https://www.npmjs.com/package/zalgo-promise
- Repository: https://github.com/krakenjs/zalgo-promise
- Homepage: https://github.com/krakenjs/zalgo-promise#readme
- Issues: https://github.com/krakenjs/zalgo-promise/issues
- npm.io page: https://npm.io/package/zalgo-promise

## Recent versions

- 1.0.48 (latest) — 2021-09-24
- 1.0.47 — 2021-07-15
- 1.0.46 — 2020-10-02
- 1.0.45 — 2020-08-04
- 1.0.44 — 2019-09-22
- 1.0.43 — 2019-09-22
- 1.0.42 — 2019-09-16
- 1.0.41 — 2019-06-11
- 1.0.40 — 2019-06-02
- 1.0.39 — 2019-06-02
- 1.0.38 — 2019-02-02
- 1.0.37 — 2019-01-28
- 1.0.36 — 2019-01-09
- 1.0.35 — 2019-01-06
- 1.0.34 — 2018-09-07
- … 33 more at https://npm.io/package/zalgo-promise/versions

## README

zalgo-promise
-------------

[![build status][build-badge]][build]
[![code coverage][coverage-badge]][coverage]
[![npm version][version-badge]][package]

[build-badge]: https://img.shields.io/github/workflow/status/krakenjs/zalgo-promise/build?logo=github&style=flat-square
[build]: https://github.com/krakenjs/zalgo-promise/actions?query=workflow%3Abuild
[coverage-badge]: https://img.shields.io/codecov/c/github/krakenjs/zalgo-promise.svg?style=flat-square
[coverage]: https://codecov.io/github/krakenjs/zalgo-promise/
[version-badge]: https://img.shields.io/npm/v/zalgo-promise.svg?style=flat-square
[package]: https://www.npmjs.com/package/zalgo-promise

A promise library that does not automatically resolve promises asynchronously, unless you do so manually.

https://medium.com/@bluepnume/intentionally-unleashing-zalgo-with-promises-ab3f63ead2fd

### Quick Start

`npm install --save zalgo-promise`

#### Global

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

#### CommonJS

```javascript
var ZalgoPromise = require('zalgo-promise');

new ZalgoPromise( ... );
```

#### ES6

```javascript
import { ZalgoPromise } from 'zalgo-promise';

new ZalgoPromise( ... );
```

### Rationale

Promises are asynchronous by default. This means that:

```javascript
Promise.resolve('foo').then(function(result) {
    console.log(result);
});

console.log('bar');
```

Will log:

```javascript
bar
foo
```

Even if we don't do anything explicitly asynchronous in the promise, it becomes asynchronous by default.

This is, generally speaking, a good thing™

However, this is a problem when:

- You're using a browser which doesn't have native Promise support
- You're using a Promise shim, which has to use `setTimeout()` to guarantee promises are resolved asynchronously
- You need to deal with cases where the browser deprioritizes `setTimeout()`, for instance, you're in a popup window but still want to communicate with the parent window

In this case, any promises you run in the unfocused window will try to run `setTimeout()`, the browser will deprioritize those calls, and your code will hang.

ZalgoPromise attempts to resolve this problem by introducing promises which are not asynchronous by default, only if you explicitly do something asynchronous like an ajax call, a post-message, a setTimeout or something else.

```javascript
var promise = new ZalgoPromise(function(resolve) {
    resolve();
});

promise.then(function() {
    // This function will be called *synchronously*
});
```

```javascript
var promise = new ZalgoPromise(function(resolve) {
    setTimeout(resolve, 100);
});

promise.then(function() {
    // This function will be called *asynchronously*
});
```

---
_Source: https://npm.io/package/zalgo-promise · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._