Soit (French for: either) is like an enhanced Set() function which simplifies type narrowing and aims to replace TypeScript enums.

Motivation

The enum feature of TypeScript is not ideal. It does not provide type guards and is not iterable.

I wanted a simple lib which provides a way to narrow type to a given set of values and can be iterated.

Inspired from the enum feature of zod.

Declaration

A Soit instance can be created by passing literals (string, number or boolean) in an array to the Soit function.

const isWarmColor = Soit(["red", "orange"]);

You can infer the corresponding union using the Infer "helper" provided by the lib.

type WarmColor = Infer<typeof isWarmColor>; // infers "red" | "orange"

You can pass any string, number or boolean you want.

const isColdColor = Soit(["one", 1, true]);

Soit instances are iterable and can be used to create new definitions.

const isColor = Soit([...isWarmColor, "green", "blue"]);

type Color = Infer<typeof isColor>; // infers "red" | "orange" | "green" | "blue"

Guard

A Soit instance is intended to be used as a type guard:

function handleColor(color: Color) {
    if(isWarmColor(color)) {
        // color can be "red" | "orange"
    }
    // color can be "blue" | "green"
}

Array utils

Because the Soit instance is iterable, you can access the corresponding array:

const colors = Array.from(isColor);

You may prefer this syntax:

const colors = [...isColor];

map and forEach can be used without Array.from().

isColor.forEach((color) => console.log(color));

const uppercaseColors = isColor.map(color => color.toUpperCase());

Set utils

.subset([])

You can create subsets using the subset method.

const isWarmColor = isColor.subset(["red", "orange"]);

This checks on build time that "red" and "orange" do exist in the isColor instance.

.extend([])

You can extend an existing Soit instance using the extend method.

const isColor = isWarmColor.extend(["blue", "green"]);

.difference([])

You can create a new instance without the specified values using the difference method.

const isColdColor = isColor.difference(["red", "orange", "yellow"]);

The given array don't need to be a subset and can contain values that don't exist in the initial instance.

Troubleshoot

Type 'string' is not assignable to type 'never'. ts(2345)

You are maybe trying to create a new Soit instance using a named array.

const warmColors = ["red", "orange"];
const isWarmColor = Soit(warmColors); // error ts(2345)

Soit throw this error to prevent passing an unknown set of value (i.e. string[]). The solution here is to use the as const declaration in order to freeze the values and allow a proper type inference.

const warmColors = ["red", "orange"] as const;
const isWarmColor = Soit(warmColors);