Giter Club home page Giter Club logo

ts-results-es's Introduction

ts-results-es

A typescript implementation of Rust's Result and Option objects.

Brings compile-time error checking and optional values to typescript.

Relationship with ts-results

This package is a friendly fork of the excellent https://github.com/vultix/ts-results/ created due to time constraints on our (Lune's) side – we needed a package available with some fixes.

Notable changes compared to the original package:

  • Added ESM compatibility
  • Option gained extra methods: mapOr(), mapOrElse(), or(), orElse()
  • Result also gained extra methods: mapOr(), mapOrElse(), expectErr(), or(), orElse()
  • Ok and Err no longer have the val property – it's Ok.value and Err.error now
  • There is Some.value which replaced Some.val
  • Boolean flags were replaced with methods:
    • Option.some -> Option.isSome()
    • Option.none -> Option.isNone()
    • Result.ok -> Result.isOk()
    • Result.err -> Result.isErr()

We'll try to get the changes merged into the upstream package so that this fork can become obsolete.

Contents

Installation

$ npm install ts-results-es

or

$ yarn add ts-results-es

Example

Result Example

Convert this:

import { existsSync, readFileSync } from 'fs';

function readFile(path: string): string {
    if (existsSync(path)) {
        return readFileSync(path);
    } else {
        // Callers of readFile have no way of knowing the function can fail
        throw new Error('invalid path');
    }
}

// This line may fail unexpectedly without warnings from typescript
const text = readFile('test.txt');

To this:

import { existsSync, readFileSync } from 'fs';
import { Ok, Err, Result } from 'ts-results-es';

function readFile(path: string): Result<string, 'invalid path'> {
    if (existsSync(path)) {
        return new Ok(readFileSync(path)); // new is optional here
    } else {
        return new Err('invalid path'); // new is optional here
    }
}

// Typescript now forces you to check whether you have a valid result at compile time.
const result = readFile('test.txt');
if (result.isOk()) {
    // text contains the file's content
    const text = result.value;
} else {
    // err equals 'invalid path'
    const err = result.error;
}

Option Example

Convert this:

declare function getLoggedInUsername(): string | undefined;

declare function getImageURLForUsername(username: string): string | undefined;

function getLoggedInImageURL(): string | undefined {
    const username = getLoggedInUsername();
    if (!username) {
        return undefined;
    }

    return getImageURLForUsername(username);
}

const stringUrl = getLoggedInImageURL();
const optionalUrl = stringUrl ? new URL(stringUrl) : undefined;
console.log(optionalUrl);

To this:

import { Option, Some, None } from 'ts-results-es';

declare function getLoggedInUsername(): Option<string>;

declare function getImageForUsername(username: string): Option<string>;

function getLoggedInImage(): Option<string> {
    return getLoggedInUsername().andThen(getImageForUsername);
}

const optionalUrl = getLoggedInImage().map((url) => new URL(stringUrl));
console.log(optionalUrl); // Some(URL('...'))

// To extract the value, do this:
if (optionalUrl.some) {
    const url: URL = optionalUrl.value;
}

Usage

See https://ts-results-es.readthedocs.io/en/latest/reference/api/index.html to see the API reference.

Publishing the package

The package is published manually right now.

Steps to publish:

  1. Bump the version in package.json and src/package.json as needed
  2. Update the CHANGELOG
  3. Commit to Git in a single commit and add a tag: git tag -a vX.X.X (the tag description can be anything)
  4. npm run build && npm publish
  5. Push both the master branch and the new tag to GitHub

ts-results-es's People

Contributors

jstasiak avatar vultix avatar dependabot[bot] avatar jack-works avatar petehunt avatar tgfisher4 avatar jacoobes avatar kevinsimper avatar kyle-johnson avatar kaznovac avatar msftenhanceprovenance avatar paulrouget avatar

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. 📊📈🎉

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google ❤️ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.