lukemorales
Exhaustive
Exhaustiveness checking in TypeScript
Tiny bundle footprint for typesafe exhaustiveness checks with helpful type inference
to ensure you haven’t forgotten any case.
📦 Install
exhaustive is available as a package on NPM. Install it with your favorite package manager:
npm install exhaustive⚡ Quick start
import { exhaustive } from "exhaustive";
enum Role {
ADMIN = 'ADMIN',
DEFAULT = 'DEFAULT',
VIEWER = 'VIEWER',
}
enum Permission {
DELETE = 'DELETE',
EDIT = 'EDIT',
VIEW = 'VIEW',
}
const getUserPermissions = (role: Role) =>
exhaustive(role, {
ADMIN: () => [Permission.DELETE, Permission.EDIT, Permission.VIEW],
DEFAULT: () => [Permission.EDIT, Permission.VIEW],
VIEWER: () => [Permission.VIEW],
});📝 Features
Tagged Unions
When working with Tagged Unions (or Discriminated Unions), use exhaustive.tag to inform what property to discriminate between union members:
interface Square {
kind: 'square';
size: number;
}
interface Rectangle {
kind: 'rectangle';
width: number;
height: number;
}
interface Circle {
kind: 'circle';
radius: number;
}
type Shape = Square | Rectangle | Circle;
const area = (s: Shape) => {
return exhaustive.tag(s, 'kind', {
square: (shape) => shape.size ** 2,
rectangle: (shape) => shape.width * shape.height,
circle: (shape) => Math.PI * shape.radius ** 2,
});
};An overload is also available in the core exhaustive function: by adding a third parameter to the function, Typescript will fallback to the Tagged Union overload.
exhaustive(s, 'kind', {
square: (shape) => shape.size ** 2,
rectangle: (shape) => shape.width * shape.height,
circle: (shape) => Math.PI * shape.radius ** 2,
});PS: Note that TypeScript has a limitation inferring the Tagged Union overload via argument types because they are generic values. This means autocomplete for the Tagged Union keys will not exist until you declare an empty object as the third argument:
exhaustive(s, 'kind', {});
// ^ this will trigger the Tagged Union overloadThis overload exists so you can use it at your own convenience, but if you prefer the better DX of inferred types from the start, calling exhaustive.tag is still preferrable.
Type Narrowing
For every case checked, exhaustive will narrow the type of input:
const getRoleLabel = (r: Role) =>
exhaustive(r, {
ADMIN: (role) => capitalize(role), // Admin
// ^? role is ADMIN
DEFAULT: (role) => capitalize(role), // Default
// ^? role is DEFAULT
VIEWER: (role) => capitalize(role), // Viewer
// ^? role is VIEWER
});
const area = (s: Shape) => {
return exhaustive.tag(s, 'kind', {
square: (shape) => shape.size ** 2,
// ^? shape is Square
rectangle: (shape) => shape.width * shape.height,
// ^? shape is Rectangle
circle: (shape) => Math.PI * shape.radius ** 2,
// ^? shape is Circle
});
};Default Fallback
If any corrupt values make to the exhaustive checker, it will throw a TypeError at runtime. If you don't want exhaustive to throw, you can provide a default fallback:
enum Food {
BANANA = 'BANANA',
SALAD = 'SALAD',
}
const getFoodType = (food: Food) => {
return exhaustive(food, {
BANANA: () => 'Fruit',
SALAD: () => 'Leaves',
_: () => 'Unknown',
});
};Exhaustive Switch Statements
Sometimes it's easier to work with switch statements, especially if you have a lot of cases that are falling-through to a common handler.
To enforce exhaustiveness checking inside switch statements, use the corrupt helper as your default value, which will make TypeScript complain of unhandled cases, and throw at runtime if the default case is reached:
import { corrupt } from "exhaustive";
type Day =
| 'Sunday'
| 'Monday'
| 'Tuesday'
| 'Wednesday'
| 'Thursday'
| 'Friday'
| 'Saturday';
const getLabelForDayOfWeek = (day: Day) => {
switch (day) {
case 'Monday':
case 'Tuesday':
case 'Wednesday':
case 'Thursday':
case 'Friday':
return 'Weekday';
case 'Saturday':
// case 'Sunday':
return 'Weekend';
default:
corrupt(day);
// ^? Argument of type 'string' is not assignable to parameter of type 'never'
}
};