playbooks

home / skills / andrelandgraf / fullstackrecipes / assert

assert skill

/.agents/skills/assert

This skill provides a TypeScript assertion helper for runtime type narrowing with descriptive errors, aiding robust input validation and early failure

npx playbooks add skill andrelandgraf/fullstackrecipes --skill assert

Review the files below or copy the command above to add this skill to your agents.

Files (1)
SKILL.md
462 B
---
name: assert
description: TypeScript assertion function for runtime type narrowing with descriptive error messages. Based on tiny-invariant.
---

# Assertion Helper

To set up Assertion Helper, refer to the fullstackrecipes MCP server resource:

**Resource URI:** `recipe://fullstackrecipes.com/assert`

If the MCP server is not configured, fetch the recipe directly:

```bash
curl -H "Accept: text/plain" https://fullstackrecipes.com/api/recipes/assert
```

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.

FAQ

Does this throw a specific error type?

It throws a standard Error with the provided descriptive message so typical error handling and reporting works out of the box.

Will message strings be evaluated when assertions pass?

If you provide a function that returns a string, it is evaluated lazily only when the assertion fails; plain strings are always created before the call.