assert_skill

Overview

This skill provides a small TypeScript assertion function for runtime type narrowing with clear, descriptive error messages. It is designed as a drop-in lightweight helper inspired by tiny-invariant, optimized for clarity and predictable runtime behavior. Use it to enforce invariants and narrow types at runtime in production web and AI apps. The implementation is minimal, with a focus on developer ergonomics and readable failure output.

How this skill works

At runtime the function checks a boolean condition and throws a descriptive Error when the condition is falsy. When used in TypeScript code, the signature acts as an assertion function, allowing the compiler to narrow types after a successful check. The message parameter accepts a string or a function that returns a string for lazily computed messages, reducing overhead when assertions pass.

When to use it

• Validate assumptions about external data before using it to avoid downstream runtime errors.
• Narrow union or unknown types to concrete types in conditional code paths.
• Replace noisy if-throw blocks with a concise, centralized assertion call.
• Enforce invariants in business logic where failure should halt execution with a clear message.
• Document intent in code by making preconditions explicit and self-documenting.

Best practices

• Write concise, actionable error messages that include contextual values when helpful.
• Prefer lazy message functions for assertions inside hot paths to avoid unnecessary formatting work.
• Use assertions for programmer and data invariants, not for normal control flow or validation UI.
• Keep assertions focused and specific so stack traces and messages point directly at the violated assumption.
• Combine with type guards and exhaustive switch checks to get both runtime safety and compile-time guarantees.

Example use cases

• Assert that API response fields exist before mapping them to typed objects, reducing null checks later.
• Narrow unknown payloads received from postMessage or worker messages to concrete types.
• Guard expensive operations that assume a certain state, making failures fail fast with a clear reason.
• Use in switch statements to assert never for exhaustive pattern matching on discriminated unions.
• Ensure configuration values are present at startup and fail loudly with a helpful message if not.