Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/metaory/pcall.js
✱ Minimal Result/Monad like tuples for JS ── zero-dependency
https://github.com/metaory/pcall.js
async await bundleless cjs es2025 esm hybrid lua mediator middleware minimal npm-package pcall promise protected safecall unbuild wrapper zero-dependencies zero-dependency
Last synced: about 1 month ago
JSON representation
✱ Minimal Result/Monad like tuples for JS ── zero-dependency
- Host: GitHub
- URL: https://github.com/metaory/pcall.js
- Owner: metaory
- License: mit
- Created: 2024-04-18T06:22:41.000Z (5 months ago)
- Default Branch: master
- Last Pushed: 2024-06-24T08:29:24.000Z (3 months ago)
- Last Synced: 2024-07-25T19:25:03.142Z (about 2 months ago)
- Topics: async, await, bundleless, cjs, es2025, esm, hybrid, lua, mediator, middleware, minimal, npm-package, pcall, promise, protected, safecall, unbuild, wrapper, zero-dependencies, zero-dependency
- Language: JavaScript
- Homepage: https://npmjs.com/package/pcall.js
- Size: 10.5 MB
- Stars: 2
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
Ƥ𝖢𐤠LL.ᴊꜱ
Result/Monad like tuples for JS
unwrap promises safely with minimum footprint
── ╶╴╶╴╶╴╶╴╶╴╶╴╶╴ ──
📦 Extremely Small
🧬 Lifecycle Hooks
🎯 Concise Signature
💠 Group Side Effects
⛔ try/catch HELL 👹
🌟 Better Visibility and Control
🌐 Works in ESM & CJS
✱ Minimal Obsessive Disorder
---
---
Inspiration
-----------
`pcall.js` is heavily inspired by
🔹 Lua `pcall` `status, res`
🔹 Elixir/Erlang Result Monad `{:ok/:error, reason/value}`
🔹 Rust `Result`
🔹 Go `[]error`
**with superpowers** 🦄!
---
SYNOPSIS
--------
`pcall({f}, {arg1}, {...})`
`[err, res]`
`pcall()` Calls function `{f}` with the given arguments in **protected mode**.
This means that any error inside `{f}` is not propagated;
Instead, `pcall` catches the error and returns a tuple.
Its first element is the `err` object,
Which is `null` if the call succeeds without errors.
And all results from the call, on second element; `[null, {res}]`
---
Usage
-----
```sh
# install
npm install pcall.js
```
```js
// ESM
import Pcall from 'pcall.js'
// CJS
const Pcall = require('pcall.js')
```
```js
const [err, res] = await Pcall(asyncFn, a, b, c, /* ··· */)
```
```js
const pcall = new Pcall({
onSuccess: console.log,
onFailure: console.error,
onFinally: console.info,
timeout: 30_000,
transformOnSuccess: (res) => res,
transformOnFailure: (err) => err,
noTrace: false
})
const [err, res] = await pcall(asyncFn, a, b, c, /* ··· */)
```
:Fulfill [null, res]
:Reject [err, null]
Convert
-------
```js
import { readFile } from 'node:fs/promises'
// 🔻 BEFORE
try {
const res = await readFile('./package.json', { encoding: 'utf8' })
} catch(error) {
console.error(error, '🔥')
}
// ─────────────────
// 🔹AFTER
import Pcall from 'pcall.js'
const [err, res] = await Pcall(readFile, './package.json', { encoding: 'utf8' })
// 🔸THROW
err && throw new Error("XYZZY", { cause: err });
// ─────────────────
// 🔸 MOCK
// const readJson = new Pcall({
// fn: readFile,
// args: [{ encoding: 'utf8' }],
// transformOnSuccess: (res) => JSON.parse(res),
// transformOnFailure: (err) => err.message,
// })
// const path = 'test/sample-good.json'
//
// const res = await readJson(path)
// log(res.hogo) // fuga
```
Options
-------
```js
import { readFile } from 'node:fs/promises'
import Pcall from 'pcall.js'
const pcall = new Pcall({
onSuccess: console.log,
onFailure: console.error,
onFinally: (args, func, span) => { /* 💣 💣 💥 */ },
transformOnSuccess: (res) => res,
transformOnFailure: (err) => err,
timeout: 30_000,
noTrace: false,
})
const path = './package.json'
const opts = { encoding: 'utf8' }
const [err, res] = await pcall(readFile, path, opts)
```
---
#### 💡 Check [test/](test/) files for more examples
---
Development
-----------
```bash
# run test playground in watch mode
npm run dev
# build production
npm run build
# build stub
npm run build:stub
```
---
TODO
----
- [x] 🌀 Lifecycle Hooks
- [.] 🔌 Serializer
- [.] 🧬 Parser
- [.] 📜 JSDoc
- [.] 🔧 ESLint
- [o] 📖 Docs
- [o] ⚠️ Tests
- [o] 💡 Examples
---
License
-------
[MIT](LICENSE)
