guarden: Zero-Dependency TypeScript Runtime Safety (Type Guards, Result/Option Monads)

#typescript #opensourcenpmwebdev

The Problem with TypeScript Runtime Safety

TypeScript gives you compile-time type checking, but at runtime you have zero protection. API responses come back as unknown, JSON.parse() returns any, and one wrong assumption crashes production.

const data = JSON.parse(rawInput); // any - no safety
const user = data.user; // could be anything
user.name.toUpperCase(); // TypeError: Cannot read property 'toUpperCase' of undefined

Introducing guarden

guarden is a zero-dependency TypeScript-first runtime safety toolkit that closes the gap between compile-time and runtime type safety.

GitHub: https://github.com/Avinashvelu03/guarden
npm: npm install guarden

Key Features

1. 60+ Type Guards with Auto-Narrowing

import { isString, isValidEmail, isUUID, isNonEmptyArray, isISO8601Date } from 'guarden';

if (isString(value)) {
  // TypeScript narrows: value is string here
  console.log(value.toUpperCase()); // safe!
}

const emails = data.filter(isValidEmail);
// TypeScript infers: emails is string[]

2. Result and Option Monads

No more try/catch spaghetti. Handle errors as values:

import { Result, Option } from 'guarden';

const result = Result.try(() => JSON.parse(rawInput));

result
  .map(data => data.users)
  .filter(isNonEmptyArray)
  .match({
    ok: (users) => renderUsers(users),
    err: (error) => showError(error.message),
  });

3. Composable Pipelines

import { pipe } from 'guarden';

const processUser = pipe(
  (input: unknown) => Result.try(() => JSON.parse(input as string)),
  (r) => r.map(d => d.user),
  (r) => r.flatMap(u => isString(u.name) ? Result.ok(u) : Result.err('Invalid user'))
);

4. Assertions and Invariants

import { assert, invariant } from 'guarden';

assert(isString(name), 'Name must be a string');
invariant(age >= 0 && age <= 150, `Invalid age: ${age}`);