Registry / serialization / typescript-is

typescript-is

library0.20.0jsnpmunverified

typescript-is is a TypeScript compiler transformer that generates runtime type-check functions directly from static TypeScript types. It automates the process of creating type predicates for `any` or `unknown` data, which is common when working with external data sources like API responses or user-uploaded files. The library inspects type definitions at compile time and emits JavaScript functions that meticulously validate incoming objects against those definitions. Currently at version 0.20.0, the project is officially deprecated and will not be updated for TypeScript versions 4.8 and above. Users are strongly advised to migrate to `typia` for newer TypeScript environments. Before its deprecation, the project aimed for regular, feature-driven releases. Its core differentiator lies in leveraging the TypeScript compiler API to avoid manual type predicate writing, aiming for comprehensive type-safety at runtime for serializable JavaScript objects.

serialization web-framework

npm install typescript-is

github ↗package ↗

INSTALL

IMPORT

SIG · TYPESCRIPT-IS

typescript-is

serializationjavascriptv0.20.0

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 { is } from 'typescript-is';

✗ const { is } = require('typescript-is');

This function call is a placeholder transformed at compile-time by the `typescript-is` plugin. Without the plugin configured via `ttypescript`, it will not perform runtime checks and often resolve to `any`.

assertEquals

✓ import { assertEquals } from 'typescript-is';

✗ assertEquals<Type>(value); // Used without ttypescript configured

Throws a `TypeError` if the value does not conform to the specified type. Like `is`, this call is transformed by the compiler plugin; it requires `ttypescript` to function correctly at runtime.

Transformer Configuration

✓ { "transform": "typescript-is/lib/transform-inline/transformer" }

✗ { "transform": "typescript-is/transformer" }

This is not a direct import into source code but an entry in the `compilerOptions.plugins` array within `tsconfig.json`, used by `ttypescript` to inject the compiler transformer.

This quickstart demonstrates how to configure `typescript-is` with `ttypescript` in `tsconfig.json` and use `assertEquals` to perform runtime type validation on an `unknown` input, ensuring type safety for `User` objects. It shows both valid and invalid data scenarios.

{ "compilerOptions": { "target": "es2018", "module": "commonjs", "strict": true, "esModuleInterop": true, "plugins": [ { "transform": "typescript-is/lib/transform-inline/transformer" } ] }, "include": ["src/**/*.ts"] } // package.json (excerpt) // ... // "scripts": { // "build": "ttsc", // "start": "node dist/index.js" // } // ... // src/index.ts import { assertEquals } from 'typescript-is'; interface User { id: number; name: string; email?: string; } function processUserData(data: unknown) { try { // This call is transformed by typescript-is to perform runtime checks assertEquals<User>(data); console.log("User data is valid:", data); // At this point, 'data' is safely typed as User console.log(`Processing user ${data.name} (ID: ${data.id})`); } catch (error: any) { console.error("Invalid user data:", error.message); } } // Example valid data processUserData({ id: 1, name: "Alice", email: "alice@example.com" }); processUserData({ id: 2, name: "Bob" }); // Example invalid data processUserData({ id: "3", name: "Charlie" }); // ID is string, expected number processUserData({ id: 4 }); // Missing name processUserData({ id: 5, name: "David", age: 30 }); // Extra property (strict)

Debug

Known issues

breaking`typescript-is` is officially deprecated and will not receive updates or support for TypeScript versions 4.8 and higher. Continuing to use it with newer TypeScript versions may lead to build failures or unexpected behavior.

fix

Migrate to the recommended alternative, `typia` (https://github.com/samchon/typia), or another actively maintained runtime type-checking library for TypeScript.

affects: >=4.8.0-ts

gotchaWhen using bundlers or loaders like `ts-loader` with the `transpileOnly` flag set to `true`, TypeScript transformers are bypassed. This means `typescript-is` will not apply its type transformations, leading to no runtime checks.

fix

Ensure `transpileOnly` is set to `false` or use `ttypescript` as the compiler in your build setup, which explicitly supports transformers.

affects: >=0.17.0

gotcha`typescript-is` relies on a TypeScript compiler transformer, which is not natively supported by `tsc`. It requires `ttypescript` or programmatic configuration of the TypeScript API to inject the transformer into your build process.

fix

Install `ttypescript` (`npm install --save-dev ttypescript`), configure your `tsconfig.json` with the transformer plugin, and run your build using `ttsc` instead of `tsc`.

affects: >=0.1.0

gotchaThe library is designed to generate type predicates for *serializable* JavaScript objects. It will not work for types that involve non-serializable constructs like functions, classes (unless configured with decorators and `reflect-metadata`), or complex symbols, without specific configuration or limitations.

fix

Review the types you are attempting to validate. For types involving functions, use the `functionBehavior` option in `tsconfig.json` to either ignore or perform a simple `typeof` check. Avoid using `typescript-is` for deeply complex, non-serializable type structures.

affects: >=0.1.0

Errors

Common errors & fixes

Error: No transformer was applied. Did you forget to configure 'ttypescript' or your bundler?

The `typescript-is` transformer was not successfully integrated into the build process, or `ttypescript` was not used/configured correctly.

fix

Ensure `ttypescript` is installed, `tsconfig.json` correctly points to the transformer (`"transform": "typescript-is/lib/transform-inline/transformer"`), and the build command uses `ttsc` instead of `tsc`.

Validation failed at $: expected 'foo' in object, found: {}

The runtime data provided to `assertEquals` or `is` did not conform to the expected TypeScript type definition, specifically missing the 'foo' property.

fix

Inspect the input data and the target type definition (e.g., `interface Foo { foo: string; }`) to identify the mismatch. Adjust the data to fit the type or refine the type definition.

TypeError: Function calls are not supported at runtime by `typescript-is`. Consider using `functionBehavior`.

Attempted to validate a TypeScript type that includes a function signature (e.g., `type MyType = { handler: () => void }`) without explicit handling.

fix

Configure the `functionBehavior` option in your `tsconfig.json` plugin settings. Options include `ignoreFunctions` (to skip function validation) or `typeof` (to perform a basic `typeof 'function'` check).

Upgrade

Version history

0.20.0latest on npm

Audit

Dependencies

typescriptrequiredPeer dependency required for the TypeScript compiler transformer to operate.

reflect-metadataoptionalRequired for using decorator-based type assertions (`ValidateClass`, `AssertType`).

Agent activity

7 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/woutervh-/typescript-is ↗

packagehttps://www.npmjs.com/package/typescript-is ↗