Neighbourhood Party Manager

    @nozzlegear/railway
    TypeScript icon, indicating that this package has built-in type declarations

    2.0.0 • Public • Published

    @nozzlegear/railway

    This is a collection of functional helpers and monads, heavily inspired by F#, to help facilitate "railway-oriented" programming in TypeScript.

    Installation

    yarn install @nozzlegear/railway
    import { compute, pipe, Result, Async } from "@nozzlegear/railway";

    Usage

    compute

    The compute function is an incredibly simple wrapper whose purpose is to group up temporary variables into a "computation block" (think a let binding in F#), preventing them from polluting your function scope. It also encourages immutability (but does not require it).

    const order = await compute(async () => {
        const displayId = await database.getDisplayIdAsync();
        const order = {
            ...baseOrder,
            user_id: req.user_id,
            display_id: displayId
        }
        const result = await database.createAsync(order);
     
        return {
            ...order,
            _id: result.id,
            _rev: result.rev
        }
    })

    In this example, order is only declared once, and the temporary variables that only it uses (displayId, result) are wrapped up neatly in the computation. Here's the same example without wrapping in a computation:

    const displayId = await database.getDisplayIdAsync();
    let order = {
        ...baseOrder,
        user_id: req.user_id,
        display_id: displayId
    }
    const result = await database.createAsync(order);
    order = {
        ...order,
        _id: result.id,
        _rev: result.rev
    }

    In this example, order is mutable by default (because its value needs to be reassigned after getting the result), and the temporary variables that only it uses are polluting the scope of the rest of the function.

    pipe

    The pipe function is a simple function chain that pipes the result of the last function to the next function. Since custom operators are impossible, the pipe function instead uses .chain and .value.

    Note that the functions are executed as they're chained, not when the value is retrieved.

    function getName() {
        return "joshua"
    }
     
    function capitalize(str: string) {
        const first = str[0];
        const rest = str.slice(1);
     
        return first.toUpperCase() + rest.toLowerCase();
    }
     
    function formatMessage(name: string) {
        return `Hello, ${name}!`
    }
     
    // Pipe the functions together to create the message
    const message = pipe(getName())
        .chain(capitalize)
        .chain(formatMessage)
        .value();
     
    console.log(message) // "Hello, Joshua!"

    Result<T>

    The Result monad encourages railway-oriented programming by wrapping values in either an "Ok" value or an "Error" value. You can safely operate on the monad without worrying about whether the value is an error or not, as the functions will only operate on "Ok" values.

    const result = Result.ofValue<string>("5")
        .map(str => parseInt(str));
     
    if (result.isOk()) {
        console.log(result.getValue()) // 5
    } else {
        console.error(result.getError())
    }

    When the value is an error, none of the functions will run:

    const result = Result.ofError<string>(new Error("Test error"))
        .map(str => parseInt(str));
     
    if (result.isOk()) {
        console.log(result.getValue()) // will not be called
    } else {
        console.error(result.getError()) // Error with message "Test error"
    }

    Always check that a Result has a value before getting the value, and check that a Result has an error before getting the error. Attemping to do either of these operations without first checking can throw an error and break your program:

    const firstResult = Result.ofError(new Error("Test error"));
     
    firstResult.getValue() // This WILL throw an error
     
    const secondResult = Result.ofValue(5)
     
    secondResult.getError() // This WILL throw an error

    You can set a default value for the Result, which will be used if the value is an error:

    const value = Result.ofError<string>(new Error("Test error"))
        .map(str => parseInt(str))
        .defaultValue(10)
     
    console.log(value) // 10

    The Result monad's functions can also be curried, which is ideal for working with the pipe function:

    function getName() {
        return "joshua"
    }
     
    function capitalize(str: string) {
        const first = str[0];
        const rest = str.slice(1);
     
        return first.toUpperCase() + rest.toLowerCase();
    }
     
    function formatMessage(name: string) {
        return `Hello, ${name}!`
    }
     
    // Pipe the functions together to create the message, using the Result monad's currying
    const message = pipe(getName())
        .chain(Result.ofValue)
        .chain(Result.map(capitalize))
        .chain(Result.map(formatMessage))
        .chain(Result.defaultValue("Hello, Newman..."))
        .value();
     
    console.log(message) // "Hello, Joshua!"

    You can wrap functions and promises in a Result, which will internally wrap them in a try/catch (or add a .catch to the promise chain):

    const fnResult = Result.ofFunction(() => {
        return somethingUndefined / 0
    })
     
    console.log(fnResult.isError()) // true
     
    if (fnResult.isError()) {
        console.error(fnResult.getError()) // ReferenceError: somethingUndefined is not defined at ....
    }
     
    // Be sure to await the result
    const promResult = await Result.ofPromise(async () => {
        return 5
    })
     
    console.log(promResult.isOk()) // true
     
    if (promResult.isOk()) {
        console.log(promResult.getValue()) // 5
    }

    Async<T>

    The Async monad wraps a promise and adds a couple of functions that make it easier to work with the value of the promise. The biggest change is that Async.map takes the value of the promise and returns the exact value you return, where the native Promise.map would return an array of the value you return.

    async function getSomethingAsync() {
        return "5";
    }
     
    const value = await Async.ofPromise(getSomethingAsync())
        .map(parseInt)
        .get() // Must call .get() to get the final promise so you can await it
     
    console.log(value) // 5
     
    // Doing the same thing with a promise would return an array:
    const secondValue = await getSomethingAsync().map(parseInt)
     
    console.log(secondValue) // [5]

    You can also bind promises, merging the promise returned by the function into the value of the Async's promise:

    async function getSomethingAsync() {
        return "5"
    }
     
    async function parseIntAsync(str: string) {
        return parseInt(str);
    }
     
    // This is bad, it returns a Promise<int> even after being awaited
    const mappedValue: Promise<number> = await Async.ofPromise(getSomethingAsync())
        .map(parseIntAsync)
        .get()
     
    // This is good, it binds the promise returned from `parseIntAsync`
    const value: number = await Async.ofPromise(getSomethingAsync())
        .bind(parseIntAsync) 
        .get()
     
    console.log(value) // 5

    Just like the Result monad, Async also has curried functions:

    async function getName() {
        return "joshua"
    }
     
    function capitalize(str: string) {
        const first = str[0];
        const rest = str.slice(1);
     
        return first.toUpperCase() + rest.toLowerCase();
    }
     
    async function formatMessage(name: string) {
        return `Hello, ${name}!`
    }
     
    // Pipe the functions together to create the message, using the Async monad's currying
    const message = await pipe(getName())
        .chain(Async.ofPromise)
        .chain(Async.map(capitalize))
        .chain(Async.bind(formatMessage))
        .chain(Async.get)
        .value();
     
    console.log(message) // "Hello, Joshua!"

    Keywords

    none

    Install

    npm i @nozzlegear/railway

    DownloadsWeekly Downloads

    27

    Version

    2.0.0

    License

    MIT

    Unpacked Size

    67.1 kB

    Total Files

    24

    Last publish

    Collaborators

    • nozzlegear