promisary
Version:
A growing collection of utilities to make working with Promises easier and cleaner.
134 lines (91 loc) • 3.25 kB
Markdown
# `promisary`
[](https://www.npmjs.com/package/promisary)
[](LICENSE)
[](https://github.com/RobbieTheWagner/promisary/actions)
> A growing collection of utilities to make working with Promises easier and cleaner.
## ✨ What is it?
`promisary` is a growing collection of promise utilities to make async JavaScript easier and cleaner.
The first utilities available are `hash` and `hashSettled`, which help you work with objects of promises.
- `hash`: Like `Promise.all`, but for objects. Rejects if any promise rejects.
- `hashSettled`: Like `Promise.allSettled`, but for objects. Always resolves with a fulfilled or rejected state.
**More utilities are planned for future releases!**
## 📦 Installation
```bash
pnpm add promisary
# or
npm install promisary
# or
yarn add promisary
```
## 🔥 Usage
### `hash`
```typescript
import { hash } from 'promisary';
async function loadData() {
const result = await hash({
user: fetchUser(),
posts: fetchPosts(),
});
console.log(result.user); // Resolved user
console.log(result.posts); // Resolved posts
}
```
You can mix promises and plain values too:
```typescript
const result = await hash({
a: 1,
b: Promise.resolve(2),
c: asyncOperation(),
});
console.log(result); // { a: 1, b: 2, c: <resolved value of asyncOperation> }
```
If any promise rejects, the whole `hash` will reject immediately:
```typescript
await hash({
a: Promise.reject(new Error('fail')),
b: Promise.resolve(2),
});
// -> throws Error: fail
```
### `hashSettled`
```typescript
import { hashSettled } from 'promisary';
async function loadDataSettled() {
const result = await hashSettled({
user: fetchUser(),
posts: fetchPosts(),
});
console.log(result.user); // { state: 'fulfilled', value: ... }
console.log(result.posts); // { state: 'fulfilled', value: ... } or { state: 'rejected', reason: ... }
}
```
You can safely inspect each result without worrying about rejected promises throwing errors.
## 🛠 Why use this?
- **Drop-in replacement for `RSVP.hash` and `RSVP.hashSettled`**.
- **No extra dependencies** besides native Promises.
- **Tiny and tree-shakable** (~300 bytes minified).
- **TypeScript ready** and fully tested.
Perfect for cleaning up older Ember.js apps or anywhere you want better Promise ergonomics.
## ✅ Features
- Supports plain values and promises.
- Rejects early (with `hash`) or always resolves (with `hashSettled`).
- Fully typed with TypeScript.
- Lightweight and fast.
- More Promise utilities coming soon!
## 📅 Roadmap
Here are some utilities planned for future releases:
- **`timeout`** — Add a timeout to any promise, rejecting if it takes too long.
- **`raceObject`** — Like `Promise.race`, but for an object of promises.
- **`delay`** — Create a promise that resolves after a specified delay.
- **More to come!**
Have ideas? [Open an issue](https://github.com/RobbieTheWagner/promisary/issues) or send a PR!
## 📜 License
MIT