typescript-nullable
    TypeScript icon, indicating that this package has built-in type declarations

    0.6.0 • Public • Published

    TypeScript Nullable

    npm version CircleCI codecov

    What is This?

    Glad you asked. This is a type-safe formalization of the concept of possibly absent values in TypeScript. It is perhaps even more importantly a module of type-safe utility functions that deal with possibly absent values.

    Think of it roughly like a JavaScript-friendly version of Haskell’s or Elm’s Maybe type and corresponding module of functions for dealing with Maybe. It is functional to its core, with typed and curried pure functions.

    Installation

    From the command line:

    $ npm install --save typescript-nullable
    

    In your TypeScript files:

    import { Nullable } from 'typescript-nullable'

    Nullable Type Definition

    type None = null | undefined
     
    type Nullable<T> = T | None

    Module Utility Functions

    This module also ships with a Nullable object that contains multiple useful functions for dealing with potentially absent values. Thus we have both a Nullable type and a Nullable object of utility functions.

    All utility functions are curried to the extent that their final argument is optional. If a final argument is not provided, the function will return another function that expects that final argument.

    Nullable.isNone

    Determines if a provided Nullable is None and provides a type guard.

    Type Annotation
    <T>(nullable: Nullable<T>): nullable is None
    
    Example Usage
    Nullable.isNone('noob noob') // false
    Nullable.isNone(null) // true
    Nullable.isNone(undefined) // true
     
    const possiblyNullValue: Nullable<string> = 'noob noob'
     
    if (Nullable.isNone(possiblyNullValue)) {
      // in this scope, TypeScript knows possiblyNullValue is a None
    }

    Nullable.isSome

    Determines if a provided Nullable is a concrete value and provides a type guard.

    Type Annotation
    <T>(nullable: Nullable<T>): nullable is T
    
    Example Usage
    Nullable.isNone('noob noob') // true
    Nullable.isNone(null) // false
    Nullable.isNone(undefined) // false
     
    const possiblyNullValue: Nullable<string> = 'noob noob'
     
    if (Nullable.isSome(possiblyNullValue)) {
      // in this scope, TypeScript knows possiblyNullValue is a concrete string
    }

    Nullable.map

    Applies the provided function to the provided Nullable only if it is not None. Returns null otherwise.

    Type Annotation
    <A, B>(func: (val: A) => B): (nullable: Nullable<A>) => Nullable<B>
    
    Example Usage
    const toUpper = (text: string): string => text.toUpperCase()
    Nullable.map(toUpper, 'noob noob') // NOOB NOOB
    Nullable.map(toUpper, null) // null
    Nullable.map(toUpper, undefined) // null

    Nullable.withDefault

    Provided a default value and a Nullable, will return the default value when the Nullable is None. Will return the concrete value of the Nullable if it is, in fact, concrete.

    Type Annotation
    <T>(defaultVal: T): (nullable: Nullable<T>) => T
    
    Example Usage
    Nullable.withDefault('morty')('rick') // 'rick'
    Nullable.withDefault('morty')(null) // 'morty'

    Nullable.maybe

    Provided a default value, a function, and a Nullable, will return the default value when the Nullable is None. Will return the provided function applied to the concrete value of the Nullable if it is, in fact, concrete.

    Type Annotation
    <A, B>(defaultVal: B, f: (a: A) => B): (nullable: Nullable<A>) => B
    
    Example Usage
    import { add } from 'ramda'
    Nullable.maybe(7, add(83), null)) // 7
    Nullable.maybe(7, add(83), 34)) // 117

    Nullable.andThen

    Used for chaining functions that take a raw value of type T but return a Nullable<T>. This is like Haskell's bind or >>=.

    Type Annotation
    Nullable.andThen<A, B>(func: (val: A) => Nullable<B>): (nullable: Nullable<A>) => Nullable<B>
    
    Example Usage
    import { compose, curry } from 'ramda'
     
    // Some arbitrary function that returns a Nullable:
    const safeDivide = curry((a: number, b: number): Nullable<number> => {
      return a === 0
        ? null
        : b / a
    })
     
    compose(
      Nullable.andThen(safeDivide(3)),
      Nullable.andThen(safeDivide(0)), // this line results in a None value so the rest of the composition chain passes along None without blowing up or throwing an exception
      Nullable.andThen(safeDivide(4)),
      safeDivide(2),
    )(32) // null
     
    compose(
      Nullable.andThen(safeDivide(3)),
      Nullable.andThen(safeDivide(5)),
      Nullable.andThen(safeDivide(4)),
      safeDivide(2),
    )(32) // 0.5333333333333333

    Nullable.ap

    Used for writing in the applicative style. For "lifting" functions into the Nullable context.

    Type Annotation
    Nullable.ap<A, B>(targetNullable: Nullable<A>): (applicativeNullable: Nullable<(val: A) => B>) => Nullable<B>
    
    Example Usage
    // Some arbitrary curried function that takes 3 concrete values:
    const addThreeNumbers = (a: number) => (b: number) => (c: number) => a + b + c
     
    compose(
      Nullable.ap(3),
      Nullable.ap(2),
      Nullable.ap(1),
    )(addThreeNumbers) // 6
     
    // This can be thought of as "lifting" addThreeNumbers into the context of its passed-in arguments being Nullable:
    compose(
      Nullable.ap(3),
      Nullable.ap(null as Nullable<number>), // note we have to typecast this here because TypeScript can’t be sure what kind of Nullable<T> it has at this point.
      Nullable.ap(1),
    )(addThreeNumbers) // null

    Install

    npm i typescript-nullable

    DownloadsWeekly Downloads

    840

    Version

    0.6.0

    License

    ISC

    Unpacked Size

    88.2 kB

    Total Files

    24

    Last publish

    Collaborators

    • kylecorbelli