@philiprehberger/ts-invariant

Tiny runtime assertion with TypeScript narrowing

Installation

npm install @philiprehberger/ts-invariant

Usage

import { invariant, assertNever, unreachable } from '@philiprehberger/ts-invariant';

const user = getUser(id);
invariant(user, 'User %s not found', id);
user.name; // narrowed to User

// Lazy message
invariant(data, () => `Expected data, got ${typeof data}`);

// Exhaustiveness checking
type Shape = 'circle' | 'square';
switch (shape) {
  case 'circle': return handleCircle();
  case 'square': return handleSquare();
  default: assertNever(shape);
}

Defined / Typed Assertions

import { assertDefined, assertType } from '@philiprehberger/invariant-ts';

function findUser(id: string): User | undefined { /* ... */ }

const user: User | undefined = findUser(id);
assertDefined(user, 'User must exist');
user.name; // narrowed to User

const isUser = (v: unknown): v is User =>
  !!v && typeof v === 'object' && 'id' in v;

assertType(payload, isUser, 'Invalid user payload');
payload.name; // narrowed to User

Custom Error Classes

import { invariantAs } from '@philiprehberger/ts-invariant';

class NotFoundError extends Error {
  constructor(message?: string) {
    super(message);
    this.name = 'NotFoundError';
  }
}

invariantAs(NotFoundError, user, 'User not found');

API

Function	Description
invariant(condition, message?, ...args)	Assert condition is truthy, narrows type
invariantAs(ErrorClass, condition, message?)	Assert with custom error type
assertDefined(value, message?)	Narrow T | null | undefined to T
assertType(value, guard, message?)	Narrow via a custom type guard
assertNever(value)	Exhaustiveness checking for switch/if chains
unreachable(message?)	Mark unreachable code paths
InvariantError	Error class thrown by invariant()

Development

npm install
npm run build
npm test

Support

If you find this project useful:

⭐ Star the repo

🐛 Report issues

💡 Suggest features

❤️ Sponsor development

🌐 All Open Source Projects

💻 GitHub Profile

🔗 LinkedIn Profile

License

MIT