Type-Safe Assertion Library for TypeScript

1.0.9 · active · verified Tue Apr 21

typed-assert is a lightweight, zero-dependency assertion library designed specifically for TypeScript 3.7+ environments. It leverages TypeScript's assertion functions feature to perform runtime checks that simultaneously narrow types at compile-time, promoting the use of `unknown` for untrusted input instead of `any`. The library provides a suite of common assertion functions (`isString`, `isNumber`, `isRecord`, etc.) and combinators (`isArrayOf`, `isOneOf`, `isOption`), allowing developers to build robust type guards and custom composite assertions. As of version 1.0.9, it's a stable release with no explicit major release cadence, but it's actively maintained. A key differentiator is its compile-time type narrowing alongside runtime validation, contrasting with traditional assertion libraries like Chai or Jest's `expect` which primarily offer runtime validation without type inference benefits. For more complex schema validation needs, the documentation explicitly recommends considering `zod` as an alternative due to `typed-assert`'s simpler scope.

Common errors

```
TS2571: Object is of type 'unknown'.
```
cause Attempting to access properties on an `unknown` type without prior assertion or type narrowing.

fix Apply an appropriate `typed-assert` function (e.g., `t.isRecord`, `t.isString`, `t.isArrayOf`) before accessing properties on an `unknown` variable to narrow its type.

Warnings

breaking This library relies on TypeScript's 'assertion functions' feature, introduced in TypeScript 3.7. Projects using older TypeScript versions will not be able to utilize this package effectively and will encounter compilation errors related to unsupported syntax.
Fix: Upgrade your project's TypeScript version to 3.7 or newer. Ensure your `tsconfig.json` targets an appropriate ES version.
gotcha `typed-assert` is designed for focused type-safe assertions and type narrowing. For highly complex data validation schemas, especially those involving recursive types, transformations, or extensive error reporting, it explicitly recommends considering a more comprehensive validation library like Zod.
Fix: Evaluate the complexity of your data validation needs. If simple type narrowing is sufficient, `typed-assert` is appropriate. For intricate schemas, investigate libraries like Zod, Yup, or Joi.

Install

npm install typed-assert npm
yarn add typed-assert yarn
pnpm add typed-assert pnpm

Imports

t
wrong:
```
const t = require('typed-assert');
```
correct:
```
import * as t from 'typed-assert';
```
The primary usage pattern for accessing all assertion functions.
isString
wrong:
```
import * as t from 'typed-assert'; const { isString } = t;
```
correct:
```
import { isString } from 'typed-assert';
```
Individual assertion functions can be imported directly for tree-shaking benefits.
safeJsonParse
wrong:
```
import * as t from 'typed-assert'; const myParse = t.safeJsonParse;
```
correct:
```
import { safeJsonParse } from 'typed-assert';
```
A utility function exported directly to facilitate parsing untrusted JSON into `unknown`.

Quickstart

Demonstrates defining a custom type assertion for a complex interface and its application to untrusted `unknown` input, showcasing compile-time type narrowing.

import * as t from 'typed-assert';

interface Config { 
  readonly a: { 
    readonly b: 'c';
    readonly d: string; 
  };
  readonly f?: number;
}

// Custom assertion function for a complex type
function assertConfig(input: unknown): asserts input is Config {
  t.isRecordWithKeys(input, ['a']); // 'f' is optional, so not required here
  t.isRecordWithKeys(input.a, ['b', 'd']);
  t.isExactly(input.a.b, 'c');
  t.isString(input.a.d);
  t.isOption(input.f, t.isNumber); // Handles optional numeric property
}

// Example usage with untrusted input
const untrustedInput1: unknown = {
  a: { b: 'c', d: 'hello' },
  f: 123
};

assertConfig(untrustedInput1);
// At this point, untrustedInput1 is narrowed to Config
console.log(untrustedInput1.a.d); // 'hello'

const untrustedInput2: unknown = {
  a: { b: 'c', d: 456 } // 'd' should be string
};

try {
  assertConfig(untrustedInput2);
} catch (error: any) {
  console.error(`Assertion failed: ${error.message}`); 
  // Expected: 'Value must be a string: 456'
}

view raw JSON →