npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

lambda-res

v1.0.24

Published

Type-safe error handling without exception

Downloads

3

Readme

Type-safe error handling without exceptions

Flexible and explicit error handling with a small flavor of functional languages.

TypeScript Test Coverage Status

Result type allows you go from this:

const user = getUser(email);

if (!user) {
  throw new Error("Can't get user"); 
  // but what happens, why email is invalid?
  // and who will catch this error?
}

to this:

const userResult = getUser(email);

if (userResult.isErr()) {
  const err = userResult.err();

  switch (err.type) {
    case 'InvalidEmail':
      console.log('User email is invalid');
      break;
    case 'UserNotExists':
      console.log("Can't find the user");
      break;
    case 'UserBannded':
      console.log(`User was bannded: ${err.ban}`);
      break;
  }
}

Usage:

Creating result

There are two main function for creating results ok and fail.

import { Err, Result, ok, fail } from 'lambda-res';

const success = ok('good'); // inferred as Success<string>

const error = fail<Err>('bad'); // inferred as Failure<string>

const result: Result<string, Err> = Math.random() ? success : error;

The Err and Errs type

Err used for creating errors of given type.

import { Failure, Err, fail, nope } from 'lambda-res';

// same as: { type: 'AppDatabaseError' } & Err
type DatabaseError = Err<'AppDatabaseError'>; 
type ConnectionError = Err<'AppConnectionError'>;

type AppErrors = DatabaseError | ConnectionError; // | Err<'NotHandled'>;

const check = (err: AppErrors): string => {
  if (err.type === 'AppDatabaseError') {
    return 'Database error';
  }

  if (err.type === 'AppConnectionError') {
    return 'Connection error';
  }

  // try unncoment NotHandled error and typescript will show a problem here!
  // that ensures that all error types are checked exhaustively
  nope(err);
};

// must match the types or Typescript will show an error
const failure: Failure<AppErrors> = fail<DatabaseError>('AppDatabaseError');

check(failure.err()); // get en error from failure

Errs type can be used to create multiple errors of a given kind, which may be useful in order not to pollute your exports with multiple individual errors (like: DatabaseError, ConnectionError).

import { Failure, Errs, fail } from 'lambda-res';

// only AppError needs to be exported
type AppError = Errs<{
  name: 'App';
  DatabaseError: string;
  ConnectionError: string;
}>;

// note an Errs here (inside Failure): 
// it transform AppError into Err<'AppDatabaseError'> | Err<'AppConnectionError'>
const failure: Failure<Errs<AppError>> = fail<AppError['DatabaseError']>('AppDatabaseError');

Using result

Once you created result it have a bunch of useful methods:

isOk, isErr, ok, err

import { Err, Result, ok, fail } from 'lambda-res';

const result: Result<string, Err> = Math.random() ? ok('ok') : fail<Err<'Error1'>>('Error1');

// isOk method allows to narrow result type to Success<string>
if (result.isOk()) {
  // once type is narrowed you can safely access the data
  console.log(result.ok()); // will outputs 'ok'
}

// isErr method allows to narrow result type to Failure<Err<'Error1'>>
if (result.isErr()) {
  console.log(result.err().type);
}

// result.err();
// ^
// this will throw an exception because result is not a Failure
// that is why isErr check used first

Mapping result with onOk and onErr (onFail)

import { Response, Errs, ok, fail, nope } from 'lambda-res';

type GetUserEmailError = Errs<{
  name: 'GetUserEmail';
  NotFound: string;
  Deleted: string;
}>;

const getUserName = async (id: string): Response<string, Errs<GetUserEmailError>> => {
  if (id === 'id1') {
    return ok('[email protected]');
  } else if (id === 'id2') {
    return fail('GetUserEmailDeleted');
  }
  return fail('GetUserEmailNotFound');
};

type SendEmailError = Errs<{
  name: 'SendEmail';
  DeliveryError: string;
}>;

const sendEmail = async (email: string): Response<{ sentCount: number }, Errs<SendEmailError>> => {
  if (email === '[email protected]') {
    return ok({ sentCount: 3 })
  }
  return fail('SendEmailDeliveryError')
}

const sendEmailToUser = async () /*: Response<{ sentCount: number }, Err<'DeliveryError'> | Err<'LoadingUserError'>> */ => {
  const userNameRes = await getUserName('id1');

  return userNameRes.onOk(async (email) => {
    const sendRes = await sendEmail(email); 

    return sendRes;
  }).onErr((err) => {
    if (err.type === 'SendEmailDeliveryError') {
      return { type: 'DeliveryError' }
    } else if (err.type === 'GetUserEmailDeleted' || err.type === 'GetUserEmailNotFound') {
      return { type: 'LoadingUserError'  }
    }
    nope(err);
  }).res();
}

Result<Data, Fail>.onOk

On success return new Data2 and collects all errors. Used to sequentially run multiple functions which returns result. In the end onErr can map errors to desired error type.

Params:

  • cb: callback which receives

    • data: Data
    • res: Result<Data, never>
  • name (optional) : common error name, it will prepend all errors types

Returns:

  • Result<Data2, Fail | Fail2> or Response<Data2, Fail | Fail2> (for async functions)

Result<Data, Fail>.onErr, Result<Data, Fail>.onFail

Doesn't change Data and returns new Fail2 — used to map one type of errors to another.

Params:

  • cb: callback which receives
    • err: Fail
    • res: Result<never, Fail>

Returns:

  • onErr: string, { type: string } or Promise<string>, Promise<{ type: string }>
  • onFail: Result<never, Fail2> or Response<never, Fail2>