TypeScript-is

Common errors

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

  cause 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: {}

  cause 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`.

  cause 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).

Warnings

• 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.
• gotcha When 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.
• 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`.
• gotcha The 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.

Install

• npm install typescript-is npm
• yarn add typescript-is yarn
• pnpm add typescript-is pnpm

Imports

• is
  wrong:

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

  correct:

  import { is } from '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
  wrong:

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

  correct:

  import { assertEquals } from 'typescript-is';

  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
  wrong:

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

  correct:

  { "transform": "typescript-is/lib/transform-inline/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.

Quickstart

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)