GuardX helps you validate values at runtime while preserving TypeScript's type narrowing. Use assertion functions when invalid data should stop execution, type guards when you want to handle it yourself, or result objects when you want to avoid repetitive try/catch blocks.

• Type-safe assertions narrow values after a runtime check.
• Composable type guards fit naturally into conditionals and filters.
• Result-based error handling keeps success and failure paths explicit.
• ESM and CommonJS support lets you use the same API in either module system.
• Focused imports keep call sites clear: guardx/assert, guardx/check, guardx/run, and guardx/util.

npm install guardx

pnpm add guardx

yarn add guardx

Assertions throw at runtime and narrow the value for all code that follows.

import * as assert from 'guardx/assert';

type User = {
  id: number;
  emailAddress: string;
};

declare function findUserById(userId: number): User | undefined;

const user = findUserById(123);

assert.isDefined(user, 'User not found');

// TypeScript now knows that user is a User.
user.emailAddress = 'new-email@example.com';

You can pass either an error message or an Error instance:

assert.isDefined(user, new Error('User not found'));

Checks return booleans and leave the response to your application.

import * as check from 'guardx/check';

declare const value: string | null | undefined;

if (check.isNullOrUndefined(value)) {
  console.log('No value was provided');
} else {
  // value is narrowed to string.
  console.log(value.toUpperCase());
}

safe and safeAsync return a discriminated union, so checking success narrows the result to either its output or error.

import * as run from 'guardx/run';

const result = run.safe(() => JSON.parse('{"ready":true}'));

if (result.success) {
  console.log(result.output);
} else {
  console.error(result.error);
}

For promises, use safeAsync:

const result = await run.safeAsync(() => fetch('/api/users/123'));

if (!result.success) {
  console.error('Request failed', result.error);
}

You can import every module from the package root:

import { assert, check, run, util } from 'guardx';

Or import only the module you need:

import * as assert from 'guardx/assert';
import * as check from 'guardx/check';
import * as run from 'guardx/run';
import * as util from 'guardx/util';

See the generated documentation for additional API details.

GuardX uses pnpm, Nx, and Vitest. Node.js 20 is used in CI.

pnpm install
pnpm exec nx test guardx
pnpm exec nx lint guardx
pnpm exec nx build guardx

To generate the API documentation locally:

pnpm exec nx docs guardx

Bug reports and pull requests are welcome. Before opening a pull request, please run the test, lint, and build commands above.

• Report a bug or request a feature
• View the changelog

GuardX is available under the MIT License.