https://github.com/jiangjie/tiny-future
A zero-dependency Future/Promise wrapper to resolve or reject a Promise outside its executor.
https://github.com/jiangjie/tiny-future
async await defer deferred future promise taskcompletionsource tiny withresolvers zero-dependency
Last synced: 5 months ago
JSON representation
A zero-dependency Future/Promise wrapper to resolve or reject a Promise outside its executor.
- Host: GitHub
- URL: https://github.com/jiangjie/tiny-future
- Owner: JiangJie
- License: mit
- Created: 2024-08-02T12:16:48.000Z (almost 2 years ago)
- Default Branch: main
- Last Pushed: 2026-01-17T15:34:10.000Z (5 months ago)
- Last Synced: 2026-01-18T01:14:29.122Z (5 months ago)
- Topics: async, await, defer, deferred, future, promise, taskcompletionsource, tiny, withresolvers, zero-dependency
- Language: TypeScript
- Homepage:
- Size: 160 KB
- Stars: 5
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
# tiny-future
[](LICENSE)
[](https://github.com/jiangjie/tiny-future/actions/workflows/test.yml)
[](https://codecov.io/gh/JiangJie/tiny-future)
[](https://npmjs.org/package/tiny-future)
[](https://npmjs.org/package/tiny-future)
[](https://jsr.io/@happy-js/tiny-future)
[](https://jsr.io/@happy-js/tiny-future/score)
A zero-dependency Future/Promise wrapper to resolve or reject a Promise outside its executor.
Inspired by C# `TaskCompletionSource`.
## Features
- Zero dependencies
- TypeScript first with full type support
- Works with `Promise.withResolvers` (ES2024) with automatic fallback
- Supports ESM, CommonJS, and Deno/JSR
## Installation
```sh
# npm
npm install tiny-future
# pnpm
pnpm add tiny-future
# yarn
yarn add tiny-future
# JSR (Deno)
deno add @happy-js/tiny-future
# JSR (other runtimes)
npx jsr add @happy-js/tiny-future
```
## Usage
```ts
import { Future } from 'tiny-future';
function sleep(ms: number): Promise {
const future = new Future();
setTimeout(() => {
// resolve/reject from anywhere, not just inside the executor
future.resolve(ms);
}, ms);
return future.promise;
}
await sleep(1000);
```
### Comparison with standard Promise
With `Future`, you can resolve or reject from anywhere:
```ts
// Using Future
const future = new Future();
someAsyncOperation((result) => {
future.resolve(result);
});
return future.promise;
```
With standard `Promise`, resolve/reject must be inside the executor:
```ts
// Using Promise
return new Promise((resolve) => {
someAsyncOperation((result) => {
resolve(result);
});
});
```
### Error handling
```ts
const future = new Future();
future.promise.catch((err) => {
console.error('Error:', err.message);
});
future.reject(new Error('something went wrong'));
```
## API
### `Future`
| Property | Type | Description |
|----------|------|-------------|
| `promise` | `Promise` | The underlying Promise instance |
| `resolve` | `(value: T \| PromiseLike) => void` | Resolves the Promise |
| `reject` | `(reason?: unknown) => void` | Rejects the Promise |
## Documentation
[API Documentation](https://jiangjie.github.io/tiny-future/)
## License
MIT