# @trenskow/custom-promise

> A extendable class for making custom promises.

Latest version **0.13.31** (published 2026-10-05) · BSD-2-Clause license · 0 weekly downloads

## Install

```sh
npm install @trenskow/custom-promise
pnpm add @trenskow/custom-promise
yarn add @trenskow/custom-promise
bun add @trenskow/custom-promise
```

## Health

**Score 60/100 (C)** — status: active.

Positive: esm support; no vulnerabilities; recently updated; high maintenance score.

Warnings: low downloads; no types; pre 1.0.

## Facts

| | |
|---|---|
| Version | 0.13.31 |
| Published | 2026-10-05 |
| First published | 2020-07-16 |
| Weekly downloads | 0 |
| License | BSD-2-Clause |
| TypeScript types | none |
| Module format | ESM + CommonJS |
| Dependencies | 0 |
| Unpacked size | 6.8 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 2 |
| Author | Kristian Trenskow |
| Maintainers | trenskow |
| Keywords | promise, custom |

## Links

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

## Alternatives

- [promise-throttle](https://npm.io/package/promise-throttle.md) — 44.2K weekly downloads
- [@commercetools/sync-actions](https://npm.io/package/@commercetools/sync-actions.md) — 25.1K weekly downloads
- [cwait](https://npm.io/package/cwait.md) — 21.4K weekly downloads
- [@ledgerhq/hw-app-cosmos](https://npm.io/package/@ledgerhq/hw-app-cosmos.md) — 4.2K weekly downloads
- [@financial-times/o-loading](https://npm.io/package/@financial-times/o-loading.md) — 2.8K weekly downloads

## Recent versions

- 0.13.31 (latest) — 2026-10-05
- 0.13.30 — 2026-09-21
- 0.13.29 — 2026-09-16
- 0.13.28 — 2026-09-16
- 0.13.27 — 2026-08-03
- 0.13.26 — 2026-07-27
- 0.13.25 — 2026-07-13
- 0.13.24 — 2026-07-02
- 0.13.23 — 2026-06-25
- 0.13.22 — 2026-06-08
- 0.13.21 — 2026-05-19
- 0.13.20 — 2026-05-04
- 0.13.19 — 2026-03-28
- 0.13.18 — 2026-02-14
- 0.13.17 — 2026-02-01
- … 25 more at https://npm.io/package/@trenskow/custom-promise/versions

## README

custom-promise
----

A small JavaScript library for creating custom promises.

# Reason

The promise specifications in JavaScript makes it hard to subclass `Promise` as the specifications does not allow for constructors that takes anything else but a function as a callback.

> [See the ECMA specifications for promises here](https://tc39.es/ecma262/#sec-newpromisecapability)

# Solution

I've created this small class that follows the specifications for what *is* a promise. All promises needs to have a `then` method that takes two parameters – `catch` is syntactic sugar added by the JavaScript engine.

# How to Use

It's dead simple!

You subclass `CustomPromise` and then you call either `this._resolve(value)` or `this._reject(error)` when the promise is done.

State and callback handling is handled under the hood.

The constructor for `CustomPromise` takes no parameters, so you can customize your subclasses to whatever needs, you might have. You do, though, need to call `super()` doing construction.

# Example

````javascript
import CustomPromise from '@trenskow/custom-promise';
import readline from 'readline';

class AskQuestion extends CustomPromise {

	constructor(question) {

		super()

		this._rl = readline.createInterface({
			input: process.stdin,
			terminal: true
		});

		this._rl.question(question, (answer) => {
			if (answer === '!') this._reject(new Error('User refused to answer!'))
			else this._resolve(answer);
		});

	}

}
````

Now you can use it like this.

````javascript
await new AskQuestion('What is your name?');
````

# Another example

The above use case for this might be a little impractical, as you might as well just implement it using regular promises or an asynchronous function.

But a useful use case is when you want to provide promise capability on daisy chained APIs.

````javascript
import CustomPromise from '@trenskow/custom-promise';

class DoIt extends CustomPromise {

	constructor () {

		super()

		setImmediate(() => {
			this._exec();
		});

	}

	take() { return this; }

	your() { return this; }

	mama() { return this; }

	out() { return this; }

	all() { return this; }

	night() { return this; }
	
	_exec() {
		this._resolve('Baby, you\'re a full grown man!');
	}

}
````

This can be used like this.

````javascript

await new DoIt()
	.take()
	.your()
	.mama()
	.out()
	.all()
	.night(); // Returns 'Baby, you\'re a full grown man!'

````

This is not really possible with promises as they are implemented in ECMAScript, and therefore you cannot really create APIs like this – but with `CustomPromise` you can..! 😉

# License

See LICENSE.

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