@ts-std/enum
    TypeScript icon, indicating that this package has built-in type declarations

    0.1.2 • Public • Published

    @ts-std/enum

    A library that brings ergonomic, matchable, tagged unions to typescript.

    Tagged unions are an extremely convenient way to handle types that may be in one of many "states" or variants. While typescript already has a version of this with discriminated unions, they leave a certain amount to be desired:

    • They're fairly verbose to define and to instantiate.
    • You only get exhaustiveness checks if there's some ambient quality of the code that requires it. For example if you perform a switch in a void function then you have to add your own exhaustiveness check with some never typed function or variable.

    The Enum function and type remove both of these problems:

    import { Enum, empty, variant } from '@ts-std/enum'
    
    // defining the shape/types of the enum...
    const WebEvent = Enum({
      PageLoad: empty(),
      PageUnload: empty(),
      KeyPress: variant<number>(),
      Paste: variant<string>(),
      Click: variant<{ x: number, y: number }>(),
    })
    // ... makes it convenient to define the type
    type WebEvent = Enum<typeof WebEvent>
    
    let event = WebEvent.PageLoad() as WebEvent
    
    event = WebEvent.PageLoad()
    event = WebEvent.PageUnload()
    event = WebEvent.KeyPress(7)
    event = WebEvent.Paste('stuff')
    event = WebEvent.Click({ x: 1, y: 2 })
    
    // won't compile!! yay!!
    event = 7
    
    let keypress_count = 0
    
    // even though these are all void functions,
    // we still get exhaustiveness checks
    event.match({
      PageUnload: () => { keypress_count = 0 },
      KeyPress: _code => { keypress_count += 1 },
      // use _ as the default case
      // if you remove this case, this function call won't compile!
      _: () => {}
    })
    
    // there's also the `matches` method when you only care to check one case
    if (event.matches('Paste')) {
      // `matches` is a guard, so you can safely access the `content` of the variant
      console.log(event.content.toLowerCase())
    }
    
    // and of course, invalid key names aren't accepted
    // so this won't compile
    event.match({
      Invalid: () => 1,
      _: () => 0,
    })
    // nor will this
    event.matches('Invalid')

    API

    Enum(variant_manifest: VariantManifest, [initial_key?: keyof variant_manifest, initial_variant: content])

    The function to create an Enum. It has two overloads.

    The first, and likely more common one, simply defines a map of variant names to their type descriptors.

    function Enum(
      variant_manifest: VariantManifest,
    ): RequiredEnum { ... }
    
    const State = Enum({
      Loading: empty(),
      Done: variant<number>(),
    })

    The second, that may be convenient in some cases, gives a "default" key and content that can be used to initialize a variable of the Enum's type.

    function Enum(
      variant_manifest: VariantManifest,
      initial_key: keyof variant_manifest,
      initial_variant: contentof initial_key,
    ): DefaultableEnum { ... }
    
    // here `State` now has a `default` method that will return a `Loading` variant
    // since `Loading` is `empty`, no content has to be provided
    const State = Enum({
      Loading: empty(),
      Done: variant<number>(),
    }, 'Loading')
    
    let state = State.default()
    state.matches('Loading') === true
    
    // if you provide a non-empty default variant, you have to provide initial content
    const State = Enum({
      Loading: empty(),
      Done: variant<number>(),
    }, 'Done', 0)
    
    let state = State.default()
    state.matches('Done') === true
    state.content === 0

    type Enum<E extends RequiredEnum>

    The helper type that extracts the union of all variants from an Enum.

    const State = Enum({
      Loading: empty(),
      Done: variant<number>(),
    })
    // State === Variant<'Loading', []> | Variant<'Done', [number]>
    type State = Enum<typeof State>
    // now that type can be used
    // this union type is automatically the return of `default` for `DefaultableEnum`s
    let state = State.Loading() as State
    state = State.Done()

    variant<T>(): VariantDescriptor<[T]> {

    Creates a non-empty variant.

    empty(): VariantDescriptor<[]>

    Creates an empty variant.

    type Match<T, M extends VariantManifest> =

    The input type to match. It requires that either all keys of the Enum are covered, or that there is a _ case for the default.

    It also is generic over T the return type of all the case functions.

    Known Issues and Future Work

    At this point, it isn't possible to create an Enum that contains generic variants.

    Keywords

    none

    Install

    npm i @ts-std/enum

    DownloadsWeekly Downloads

    2

    Version

    0.1.2

    License

    MIT

    Unpacked Size

    9.95 kB

    Total Files

    5

    Last publish

    Collaborators

    • blainehansen