result-interface

A tiny utility (mainly interfaces) with zero dependencies to standardize handling results that may succeed or fail, inspired by Go-style error handling.

Installation

npm i result-interface

Usage

You can define functions more declaratively when working with possible failures:

import { type Result, isError } from "result-interface";

let VALUE: number | undefined = undefined;

function getValue(): Result<number, string> {
    if (VALUE !== undefined) {
        return { value: VALUE };
    }
    return { error: "The value is undefined" };
}

const resp: Result<number, string> = getValue();

if (isError(resp)) {
    console.log(`Unable to get the value. Reason: ${resp.error}`);
    process.exit(1);
}

console.log(`The value multiplied by two is ${resp.value * 2}`);

You can use helper functions to generate IError and IResult types (the possible types of Result).

import { type Result, isError, result, error } from "result-interface";

function getValue(): Result<number, string> {
    if (VALUE !== undefined) {
        return result(VALUE);
    }
    return error("The value is undefined");
}

You can specify that a Promise will not throw:

import { isError, SafePromise, type Result } from "result-interface";

let VALUE: number | undefined = undefined;

async function getValueLater(): SafePromise<number,string> {
    return new Promise((resolve, reject) => {
        if (VALUE !== undefined) {
            resolve({
                value:VALUE
            })
        } else {
            reject("The value is undefined");
        }
    });
}

// Creates a promise that always resolves with a Result. 
// On failure, it resolves with an error instead of rejecting or throwing.
const resp: Result<number, string> = await getValueLater();

if (isError(resp)) {
    console.log(`Unable to get the value. Reason: ${resp.error}`);
    process.exit(1);
}

console.log(`The value multiplied by two is ${resp.value * 2}`);

You can specify that a promise will never fail, thus that it will always be an IResult:

import { SafePromise, type Result } from "./src/index";

let VALUE: number | undefined = undefined;

async function getValueLater(): SafePromise<number, never> {
    return new Promise((resolve, reject) => {
        if (VALUE !== undefined) {
            resolve({
                value: VALUE
            })
        } else {
            reject("The value is undefined");
        }
    });
}

// Creates a promise that always resolves with a Result. 
// On failure, it resolves with an error instead of rejecting or throwing.
const resp: Result<number, never> = await getValueLater();

console.log(`The value multiplied by two is ${resp.value * 2}`);

You can ensure that a Promise will not throw:

import { isError, safePromise, type Result } from "result-interface";

let VALUE: number | undefined = undefined;

async function getValueLaterUnsafe(): Promise<number> {
    return new Promise((resolve, reject) => {
        if (VALUE !== undefined) {
            resolve(VALUE)
        } else {
            reject("The value is undefined");
        }
    });
}

// Creates a promise that always resolves with a Result. 
// On failure, it resolves with an error instead of rejecting or throwing.
const resp: Result<number, unknown> = await safePromise(getValueLaterUnsafe());

if (isError(resp)) {
    console.log(`Unable to get the value. Reason: ${resp.error}`);
    process.exit(1);
}

console.log(`The value multiplied by two is ${resp.value * 2}`);

Test

bun test

License

This project is licensed under the MIT License. See the LICENSE file for more details.