Alwaysly

There are things that should never happen. Rather than adding meaningless conditions just to satisfy TypeScript, you can use always. It also comes with a parameterless version never.

Unlike assert, it's runtime-agnostic and so simple that you probably should just copy-paste needed functions into your project.

export function always(condition: unknown): asserts condition {
  if (!condition) throw new Error("Entered unreachable code");
}

export function ensure(value: unknown): asserts value is {} {
  if (value == null) throw new Error("Entered unreachable code");
}

export function never(_value?: never): never {
  always(false);
}

export function todo(
  note: "This code path is unimplemented" & { [brand]: 0 },
): never {
  throw new Error(`Not implemented yet${note ? `: ${note}` : ""}`);
}

declare const brand: unique symbol;

If you like me and don't want to bother with dragging it around, you can install it from npm:

npm install alwaysly

It's tiny and has no dependencies (duh!).

It also is well-documented and covered with tests. Who would've thought that one could push such a simple code that far!

FAQ

Why not just use if statements?

You definitely can, but an assertion communicates impossible code paths more clearly. The presence of a condition not only clutters the code but also implies that branching is possible.

If the latter is the case, then you should use if.

Why not just use assert?

asserts is a runtime feature. Node.js (and compatible runtimes) ships with the node:assert module. Browser runtimes have console.assert.

However, using those in universal code is impossible without bundler shenanigans or wrapper functions. alwaysly is exactly that wrapper.

Why is it named always instead of assert?

The editor (e.g., VS Code) auto-import feature always reaches for the node:assert module, so to make the developer experience better, I named it always.

It also rhymes with never and indicates that it is not a standard assert.

What does "alwaysly" mean?

I once met a company of Brits in Bangkok that loved saying "alwaysly" instead of saying "for sure" or "definitely".

It stuck with me, and some decade later, I had a chance to share it with the world.

Why can't I pass a message to always/never?

It is not a good idea, as it bloats the build size and distracts from the main point of the assertion to communicate that a certain code path is impossible.

Is it an is-even kind of thing?

No. Yes. Kind of. It is an example of how useful a nano-library can be.

Changelog

See the changelog.

License

MIT © Sasha Koss