typed-assert

library1.0.9jsnpmunverified

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.

type-stubs serialization

npm install typed-assert

github ↗package ↗

INSTALL

IMPORT

SIG · TYPED-ASSERT

typed-assert

type-stubsjavascriptv1.0.9

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

✓ import * as t from 'typed-assert';

✗ const t = require('typed-assert');

The primary usage pattern for accessing all assertion functions.

isString

✓ import { isString } from 'typed-assert';

✗ import * as t from 'typed-assert'; const { isString } = t;

Individual assertion functions can be imported directly for tree-shaking benefits.

safeJsonParse

✓ import { safeJsonParse } from 'typed-assert';

✗ import * as t from 'typed-assert'; const myParse = t.safeJsonParse;

A utility function exported directly to facilitate parsing untrusted JSON into `unknown`.

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' }

Debug

Known issues

breakingThis 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.

affects: <3.7

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.

affects: >=1.0.0

Errors

Common errors & fixes

TS2571: Object is of type 'unknown'.

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.

Upgrade

Version history

1.0.9latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

29 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/elierotenberg/typed-assert ↗

packagehttps://www.npmjs.com/package/typed-assert ↗