ts-box
v0.3.0
Published
Put exceptions into boxes
Downloads
8
Readme
📦 ts-box
Put exceptions into boxes.
In JavaScript and therefor in TypeScript any function can throw anything at any time. This makes exception handling hard. ts-box is a workaround which puts function return values into boxes (like a maybe monad) and forces users to check for the error at the type level before the actual value can be accessed.
Install
npm install ts-box
Usage
Use boxify()
to boxify existing functions
import {boxify} from "ts-box";
// Make a version of fetch that never throws exceptions
const boxedFetch = boxify(fetch);
async function main() {
const box = await boxedFetch("/api");
if (!box.ok) {
console.log("Fetch failed", box.error);
return;
}
// The value can be accessed only when the error is handled
console.log("Fetch ok!", box.value.status);
}
Use runBox()
to immediately execute a function with boxing
import {runBox} from "ts-box";
const jsonBox = runBox(() => box.value.json());
if (jsonBox.ok) {
// jsonBox.value...
}
Use boxifyObject()
to boxify object of functions
import {boxifyObject} from "ts-box";
import Axiox from "axios";
const BoxifiedAxios = boxifyObject(Axios);
The return type
The return type of a boxified function is always a discriminated union
ResultBox
with a common ok
singleton property as the discriminant which
can be used to narrow the type to the value or error.
type ResultBox<T> = {ok: true; value: T} | {ok: false; error: any};
Read more about the TypeScript discriminated unions here:
https://www.typescriptlang.org/docs/handbook/advanced-types.html#discriminated-unions