{"id":15247,"library":"typed-assert","title":"Type-Safe Assertion Library for TypeScript","description":"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.","status":"active","version":"1.0.9","language":"javascript","source_language":"en","source_url":"https://github.com/elierotenberg/typed-assert","tags":["javascript","assert","typescript"],"install":[{"cmd":"npm install typed-assert","lang":"bash","label":"npm"},{"cmd":"yarn add typed-assert","lang":"bash","label":"yarn"},{"cmd":"pnpm add typed-assert","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"The primary usage pattern for accessing all assertion functions.","wrong":"const t = require('typed-assert');","symbol":"t","correct":"import * as t from 'typed-assert';"},{"note":"Individual assertion functions can be imported directly for tree-shaking benefits.","wrong":"import * as t from 'typed-assert'; const { isString } = t;","symbol":"isString","correct":"import { isString } from 'typed-assert';"},{"note":"A utility function exported directly to facilitate parsing untrusted JSON into `unknown`.","wrong":"import * as t from 'typed-assert'; const myParse = t.safeJsonParse;","symbol":"safeJsonParse","correct":"import { safeJsonParse } from 'typed-assert';"}],"quickstart":{"code":"import * as t from 'typed-assert';\n\ninterface Config { \n  readonly a: { \n    readonly b: 'c';\n    readonly d: string; \n  };\n  readonly f?: number;\n}\n\n// Custom assertion function for a complex type\nfunction assertConfig(input: unknown): asserts input is Config {\n  t.isRecordWithKeys(input, ['a']); // 'f' is optional, so not required here\n  t.isRecordWithKeys(input.a, ['b', 'd']);\n  t.isExactly(input.a.b, 'c');\n  t.isString(input.a.d);\n  t.isOption(input.f, t.isNumber); // Handles optional numeric property\n}\n\n// Example usage with untrusted input\nconst untrustedInput1: unknown = {\n  a: { b: 'c', d: 'hello' },\n  f: 123\n};\n\nassertConfig(untrustedInput1);\n// At this point, untrustedInput1 is narrowed to Config\nconsole.log(untrustedInput1.a.d); // 'hello'\n\nconst untrustedInput2: unknown = {\n  a: { b: 'c', d: 456 } // 'd' should be string\n};\n\ntry {\n  assertConfig(untrustedInput2);\n} catch (error: any) {\n  console.error(`Assertion failed: ${error.message}`); \n  // Expected: 'Value must be a string: 456'\n}","lang":"typescript","description":"Demonstrates defining a custom type assertion for a complex interface and its application to untrusted `unknown` input, showcasing compile-time type narrowing."},"warnings":[{"fix":"Upgrade your project's TypeScript version to 3.7 or newer. Ensure your `tsconfig.json` targets an appropriate ES version.","message":"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.","severity":"breaking","affected_versions":"<3.7"},{"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.","message":"`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.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"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.","cause":"Attempting to access properties on an `unknown` type without prior assertion or type narrowing.","error":"TS2571: Object is of type 'unknown'."}],"ecosystem":"npm"}