Over the past two weeks, I've been working on [crabrave](https://crabrave.vercel.app), a <500B (when bundled) library that brings Rust-style Enums, Options, and Results into TypeScript. This is an introduction to what I call packed enums, which are essentially the same as Rust enums, in that they can hold arbitrary information alongside the thing they represent. But first, A lot of people have talked at length about the technical problems of TypeScript enums; their runtime cost, inconsistent behaviour, etc. etc. {% embed https://www.youtube.com/watch?v=jjMbPt_H3RQ %} These are all very bad problems, and this implementation fixes those as well (at least the ones I know of), but I think the bigger issue is that TypeScript enums just aren't very useful. Let me demonstrate: ## The problem with vanilla TS enums The following is a standard TypeScript enum: ```ts enum ColorEnum { Red, Green, Blue } ``` We can use it like this: ```ts const red = ColorEnum.Red const green = ColorEnum.Green const blue = ColorEnum.Blue red === ColorEnum.Red // true red === ColorEnum.Green // false ``` Pretty simple, right? But what if we wanted to store the intensity of that color as well? Well, we could maybe make a type: ```ts type Color = { color: ColorEnum, value: number } const red: Color = { color: ColorEnum.Red, value: 128 } ``` Let's also make a function that takes a `Color` and makes it into an `[R, G, B]` tuple. ```ts function toRGB(color: Color) { switch (color.color) { case ColorEnum.Red: return [color.value, 0, 0] case ColorEnum.Green: return [0, color.value, 0] case ColorEnum.Blue: return [0, 0, color.value] } } console.log(toRGB(red)) // [ 128, 0, 0 ] ``` And that looks fine at first, but what if our client comes to us and kindly informs us of the following: > MAKE IT SO I CAN USE RGB VALUES OR YOU'RE FIRED! Well, ok, can't be too hard. Let's just add Rgb to our enum... ```ts enum ColorEnum = { Red, Green, Blue, Rgb } ``` And update our type: ```ts type Color = { color: ColorEnum, value: ??? } ``` *Wait, what should our type be?* - `number[]`? *I guess it would work if I change all the code that's written to handle `number`s.* - `number | [number, number, number]`? *A bit nicer, but what if someone tries to set a single number for an RGB value?* - `class Color` with conversion functions? *Bloat much?* - `any`? *Yeah, no.* And even if you do all the changes to handle RGB today, what are you going to do tomorrow when they ask you for hexadecimal and HSL and HSV and alpha channels and who knows what else? **Packed Enums**, that's how! Let's work through the same example with one. ## How Packed Enums fix everything Import the library like this: ```ts import { type Enum, match, pack } from '@oofdere/crabrave' ``` Let's start by initializing the enum again: ```ts type Colors = { Red: number; Blue: number; Green: number; }; ``` Some things to take note of: 1. As you can see, this is just a standard type. 2. The keys of the enum are the types they store. 3. It's very similar to Rust's enums. We can use it like this: ```ts const red = pack("Red", 128) //=> const red: Enum const green = pack("Blue", 128) //=> const green: Enum const blue = pack("Green", 128) //=> const blue: Enum ``` `pack(k, v)` takes in our enum definition (the `Colors` type we created earlier) and packs it into an object based on the `key` and `value` of that specific enum entry. This means you get autocomplete in your IDE for both `key` and `value`. Not as clean as the default TS enum syntax, but note that we passed the intensity into `pack()`, which means we don't have to define `type Color` like we did before. Now let's make that toRGB function again: ```ts function toRGB(color: Enum) { // returns number[] return match(color, { Red: (x) => [x, 0, 0], //=> Red: (x: number) => number[] Green: (x) => [0, x, 0], //=> Green: (x: number) => number[] Blue: (x) => [0, 0, x], //=> Blue: (x: number) => number[] }); } console.log(toRGB(blue)); // [ 0, 0, 128 ] ``` Great! We have all the functionality of the original again! Now let's start implementing RGB colors by updating our Color enum: ```ts type Colors = { Red: number; Blue: number; Green: number; Rgb: [number, number, number]; }; ``` TypeScript will start screaming at us as soon as we do this: ```bash colors.ts:16:22 - error TS2345: Argument of type '{ Red: (x: number) => number[]; Green: (x: number) => number[]; Blue: (x: number) => number[]; }' is not assignable to parameter of type 'Functionify'. Property 'Rgb' is missing in type '{ Red: (x: number) => number[]; Green: (x: number) => number[]; Blue: (x: number) => number[]; }' but required in type 'Functionify'. ``` This might look intimidating at first, but if we look at the start of the indented line, we'll see that TypeScript is actually warning us that our `match()` call doesn't handle the `Rgb` case we just added to our enum. The same thing will happen if we try to pack an invalid value into `Rgb`: ```ts const rgb = pack("Rgb", 128) //=> const rgb: Enum ``` The TypeScript compiler will tell us what we did wrong in three different ways: ```bash Argument of type '["Rgb", 128]' is not assignable to parameter of type 'EnumUnion'. Type '["Rgb", 128]' is not assignable to type '["Rgb", [number, number, number]]'. Type at position 1 in source is not compatible with type at position 1 in target. Type 'number' is not assignable to type '[number, number, number]'.ts(2345) ``` Valid values obviously work: ```ts const rgb = pack("Rgb", [128, 128, 128]) //=> const rgb: Enum ``` Let's update our `toRGB()` function now: ```ts function toRGB(color: Enum) { return match(color, { Red: (x) => [x, 0, 0], //=> Red: (x: number) => number[] Green: (x) => [0, x, 0], //=> Green: (x: number) => number[] Blue: (x) => [0, 0, x], //=> Blue: (x: number) => number[] + Rgb: (x) => x //=> Rgb: (x: [number, number, number]) => [number, number, number] }); } ``` This works, but the return type is now `number[] | [number, number, number]`, which isn't ideal. We can work around this with the `as` keyword: ```ts function toRGB(color: Enum) { return match(color, { // ... Rgb: (x) => x //=> Rgb: (x: [number, number, number]) => [number, number, number] }) as [number, number, number]; } ``` Another option is to return `Enum`, which is useful if you want to keep using the functions built to handle the enum: ```ts function toRGB(color: Enum) { // returns Enum return match(color, { Red: (x) => pack("Rgb", [x, 0, 0]), //=> Red: (x: number) => Enum Green: (x) => pack("Rgb", [0, x, 0]), //=> Green: (x: number) => Enum Blue: (x) => pack("Rgb", [0, 0, x]), //=> Blue: (x: number) => Enum Rgb: (x) => pack("Rgb", x) //=> Rgb: (x: number) => Enum }); } console.log(toRGB(blue).v); ``` Both are fine, do whichever makes more sense for your project. And of course, fearlessly add new features, knowing the compiler will tell you exactly where your code needs to be updated to handle them: ```ts type Colors = { Red: number; Blue: number; Green: number; Rgb: [number, number, number]; Rgba: [number, number, number, number]; Hsl: { hue: number, saturation: number, lightness: number }, Css: string, None: null }; ``` ```bash colors.ts:26:22 - error TS2345: Argument of type '{ Red: (x: number) => Enum; Green: (x: number) => Enum; Blue: (x: number) => Enum; Rgb: (x: [number, number, number]) => Enum<...>; }' is not assignable to parameter of type 'Functionify'. Type '{ Red: (x: number) => Enum; Green: (x: number) => Enum; Blue: (x: number) => Enum; Rgb: (x: [number, number, number]) => Enum<...>; }' is missing the following properties from type 'Functionify': Rgba, Hsl, Css, None ``` ## (Almost) Zero-cost This is how TypeScript compiles the vanilla enum we built earlier: ```ts "use strict"; var ColorEnum; (function (ColorEnum) { ColorEnum[ColorEnum["Red"] = 0] = "Red"; ColorEnum[ColorEnum["Green"] = 1] = "Green"; ColorEnum[ColorEnum["Blue"] = 2] = "Blue"; })(ColorEnum || (ColorEnum = {})); ``` And this is how it compiles a crabrave enum: ```ts // this space intentionally left empty ``` And in fact, the entirety of the enum logic bundles down to just this: ```ts // src/enum.ts var pack = (...entry) => entry; var match = (pattern, arms) => arms[pattern[0]](pattern[1]); var matchPartial = (pattern, arms, fallback) => (arms[pattern[0]] || fallback)(pattern[1]); export { pack, matchPartial, match }; ``` Or, after minification: `var o=(...i)=>i,w=(i,u)=>u[i[0]](i[1]),x=(i,u,d)=>(u[i[0]]||d)(i[1]);export{o as pack,x as matchPartial,w as match};` (116 bytes) This is a cost you pay once across your whole entire project, and then you can make and use as many enums as you'd like without any additional penalty.

The magic is in the type system, and that's what vanilla TS enums miss. Next time, I'll be posting a guide on `Result`, a gentler way of handling errors. In the meantime, check out [the docs](https://crabrave.vercel.app) (very much under construction) and [the code](https://github.com/oofdere/crabrave) Feedback and contributions welcomed!

oofdere

Making TypeScript enums not suck in 500 bytes or less.

Join Our Newsletter. No Spam, Only the good stuff.