@unsplash/sum-types

Safe, ergonomic, non-generic sum types in TypeScript.

Documentation: unsplash.github.io/sum-types

import * as Sum from "@unsplash/sum-types"

type Weather = Sum.Member<"Sun"> | Sum.Member<"Rain", number>
const Weather = Sum.create<Weather>()

const getRainfall = Weather.match({
  Rain: n => `${n}mm`,
  Sun: () => "none",
})

const todayWeather = Weather.mk.Rain(5)

getRainfall(todayWeather) // '5mm'

Installation

The library is available on the npm registry: @unsplash/sum-types

Note that due to usage of Proxy and Symbol this library only supports ES2015+.

The following bindings are also available:

• @unsplash/sum-types-fp-ts
• @unsplash/sum-types-io-ts
• @unsplash/sum-types-fast-check

Motivation

The library solves a number of problems we've experienced at Unsplash with alternative libraries in this space. Specifically:

• Convenient member constructor functions are provided, unlike ts-adt.
• The API is small, simple, and boilerplate-free, unlike tagged-ts.
• Pattern matching is curried for use in pipeline application and function composition, unlike @practical-fp/union-types.
• Types are not inlined in compiler output, improving readability and performance at scale, unlike unionize.

The compromise we've made to achieve this is to not support generic sum types.

Changelog

This project adheres to semantic versioning.

0.4.1 (2023-10-04)

Fixes pattern matching branches which return undefined in matchX and matchXW.

0.4.0 (2023-05-16)

Adds supports for convenient "strict" pattern matching without access to member values, denoted by an "X" suffix.

Adds a first-class, low-level is primitive for refining foreign data to a known sum member.

Fixes reference equality of deserialized nullary sums.

0.3.2 (2023-03-23)

Fixes nullary equality checks in Jest and others that compare the reference equality of functions.

0.3.1 (2022-09-13)

Exports the types Match and MatchW to workaround type errors that appear when compiling with the declaration compiler option enabled.

0.3.0 (2022-09-05)

Nullary constructors are no longer function calls, fixing an edge case unsafety. Where you previously called mk.Member(), now simply refer to mk.Member.

0.2.2 (2022-02-22)

Add ESM support.

0.2.1 (2022-01-12)

Fix runtime representation of nullary constructors.

0.2.0 (2022-01-12)

Exhaustive checking in pattern matching now reports on missing members. Previously it would report on a missing wildcard.

The internal representation of nullary constructors has been changed to use null instead of undefined for easier JSON interop post-serialisation.

0.1.1 (2021-12-08)

Expose the Serialized type for easier usage of the serialization functions.

0.1.0 (2021-09-17)

The initial release of @unsplash/sum-types with support for non-generic sum types, pattern matching with or without wildcards, and (de)serialization.