Tiny Invariant

Tiny Invariant is a lightweight assertion library that provides a single invariant function for runtime validation with TypeScript type narrowing. It serves as a minimal alternative to the larger invariant library, offering essential assertion functionality with automatic message stripping in production builds for optimal bundle size.

Package Information

• Package Name: tiny-invariant
• Package Type: npm
• Language: TypeScript
• Installation: npm install tiny-invariant

Core Imports

import invariant from "tiny-invariant";

For CommonJS:

const invariant = require("tiny-invariant");

Basic Usage

import invariant from "tiny-invariant";

// Basic assertion
invariant(value, "Expected value to be truthy");

// Type narrowing example
const maybeUser: User | null = getUser();
invariant(maybeUser, "Expected user to exist");
// maybeUser is now typed as User (null eliminated)

// Lazy message evaluation
invariant(condition, () => getExpensiveErrorMessage());

Capabilities

Runtime Assertion

The core invariant function provides runtime assertion with TypeScript type narrowing capabilities.

/**
 * Asserts that the condition is truthy, throwing an error if falsy.
 * In TypeScript, acts as an assertion function to narrow types.
 * Messages are automatically stripped in production builds.
 * 
 * @param condition - Value to test for truthiness
 * @param message - Optional error message or lazy message function
 * @throws Error when condition is falsy
 */
function invariant(
  condition: any,
  message?: string | (() => string)
): asserts condition;

Type Narrowing Behavior:

• Input type can be a union type (e.g., T | null | undefined)
• After successful assertion, TypeScript narrows the type to exclude falsy possibilities
• Acts as a type guard for conditional logic

Error Behavior:

• Development: Throws Error("Invariant failed: <message>") or Error("Invariant failed") if no message
• Production: Always throws Error("Invariant failed") (custom messages stripped for bundle size)

Message Options:

• String message: invariant(condition, "Custom error message")
• Lazy function: invariant(condition, () => computeExpensiveMessage())
• No message: invariant(condition) (uses default "Invariant failed")

Usage Examples:

// Null checking with type narrowing
function processUser(user: User | null) {
  invariant(user, "User must be provided");
  // user is now typed as User, not User | null
  console.log(user.name); // TypeScript knows user is not null
}

// Value validation
function divide(a: number, b: number) {
  invariant(b !== 0, "Division by zero is not allowed");
  return a / b;
}

// Lazy message for expensive operations
function validateConfig(config: unknown) {
  invariant(
    isValidConfig(config),
    () => `Invalid config: ${JSON.stringify(config, null, 2)}`
  );
}

// Boolean narrowing
function handleFlag(flag: boolean) {
  invariant(flag, "Flag must be true to continue");
  // TypeScript knows flag is true here
}

// Array/object existence checking
function processItems(items: Item[] | undefined) {  
  invariant(items && items.length > 0, "Items array must not be empty");
  // items is now typed as Item[] (undefined and empty array eliminated)
  return items.map(processItem);
}

Production Optimization

Tiny Invariant is designed for production optimization:

• Message Stripping: Custom error messages are automatically removed in production builds
• Bundle Size: Optimized for minimal bundle impact (~217B minified)
• Environment Detection: Uses process.env.NODE_ENV to determine behavior
• Zero Dependencies: No runtime dependencies

Recommended Build Configuration:

For optimal production bundles, use build tools that:

1. Set process.env.NODE_ENV to "production"
2. Apply dead code elimination/tree shaking
3. Use plugins like babel-plugin-dev-expression for additional optimization

Types

The package exports a single default function with TypeScript assertion signature:

declare function invariant(
  condition: any,
  message?: string | (() => string)
): asserts condition;

export default invariant;

Key Type Features:

• asserts condition: TypeScript assertion function signature for type narrowing
• condition: any: Accepts any value for maximum flexibility
• message?: string | (() => string): Optional string or lazy function message
• Return type void with assertion signature for type narrowing side effects