TypeScript Interface Runtime Validator

Common errors

• Error: value.size is missing

  cause An object being checked against an interface is missing a required property.
  fix Ensure the object being validated includes all non-optional properties defined in the TypeScript interface. For example, `Square.check({ size: 1 });` instead of `Square.check({ color: 'green' });` for an interface requiring `size`.

• Error: value.color is not a string

  cause A property in the object being checked has an incorrect type according to the interface definition.
  fix Verify that all properties in the validated object conform to their specified TypeScript types. For example, `Square.check({ size: 4, color: 'blue' });` instead of `Square.check({ size: 4, color: 5 });`.

• Error: value.name is not a string

  cause When validating method arguments, a parameter has an incorrect type.
  fix Ensure arguments passed to `methodArgs().check()` match the types defined for the method's parameters in the interface. For example, `Greeter.methodArgs("greet").check(["Bob"]);` instead of `Greeter.methodArgs("greet").check([17]);`.

• Error: value.name is missing

  cause When validating method arguments, a required parameter is missing from the argument list.
  fix Provide all required arguments when calling `methodArgs().check()`. For example, `Greeter.methodArgs("greet").check(["Alice"]);` instead of `Greeter.methodArgs("greet").check([]);`.

• Error: value is not a string

  cause When validating a method's return value, the value does not match the specified return type.
  fix Ensure the return value passed to `methodResult().check()` matches the method's return type. For example, `Greeter.methodResult("greet").check("hello");` instead of `Greeter.methodResult("greet").check(null);`.

Warnings

• gotcha The `ts-interface-checker` package is a runtime dependency, but it requires definitions generated by `ts-interface-builder` at build-time. Users must install both, with `ts-interface-builder` as a dev dependency.
  Fix: Ensure `npm install --save-dev ts-interface-builder` and `npm install --save ts-interface-checker` are executed, and run `npx ts-interface-builder <your-ts-files>` as part of your build process before runtime checks are performed.
• gotcha Using `strictCheck()` can lead to backward compatibility issues. If new optional properties are added to an interface, older code with `strictCheck()` will fail when validating data containing these new properties.
  Fix: Avoid `strictCheck()` for interfaces that are part of public APIs or stable data contracts to allow for graceful schema evolution. Use standard `check()` unless strict enforcement of known properties is absolutely required.
• gotcha The library does not currently support TypeScript generics (except for Promises, which are unwrapped). Interfaces with complex generic types will not be correctly processed by `ts-interface-builder`.
  Fix: Refactor interfaces to avoid complex generics or manually implement runtime checks for parts of the schema that rely on unsupported generic constructs. Refer to `ts-interface-builder` limitations for details.

Install

• npm install ts-interface-checker npm
• yarn add ts-interface-checker yarn
• pnpm add ts-interface-checker pnpm

Imports

• createCheckers
  wrong:

  const { createCheckers } = require('ts-interface-checker');

  correct:

  import { createCheckers } from "ts-interface-checker";

  This is the primary function for initializing checkers from generated type suites. The library is primarily ESM-first, so CommonJS `require` is not directly supported without a transpilation step or appropriate `esModuleInterop` configuration.
• Checker

  import type { Checker } from "ts-interface-checker";

  Use this type to explicitly type the individual checker objects returned by `createCheckers` for enhanced type safety and IDE assistance.
• Generated Type Suites (e.g., fooTI)
  wrong:

  import * as fooTI from "./foo-ti";

  correct:

  import fooTI from "./foo-ti";

  Files generated by `ts-interface-builder` typically export a default object containing the type suite. Prefer default imports for these modules.

Quickstart

Demonstrates the full workflow of defining a TypeScript interface, conceptually generating runtime checkers using `ts-interface-builder`, and then utilizing `ts-interface-checker` to validate JavaScript objects against the interface's structure at runtime, including expected error scenarios.

// 1. Define your TypeScript interface (e.g., in `foo.ts`)
// interface Square {
//   size: number;
//   color?: string;
// }

// 2. Generate runtime checker code using ts-interface-builder (build step)
//    npx ts-interface-builder foo.ts
//    This creates `foo-ti.js` or `foo-ti.ts`.
//    The content of `foo-ti.js` would look something like:
/*
// foo-ti.js
import * as t from "ts-interface-checker";
export const Square = t.iface([], {
  "size": "number",
  "color": t.opt("string"),
});
const exportedTypeSuite = { Square };
export default exportedTypeSuite;
*/

// 3. At runtime, import the generated type suite and create checkers.
// For a self-contained example, we'll mock the `foo-ti` module content directly:

// A minimal mock of what `foo-ti.js`'s default export would look like to `createCheckers`
// In a real application, you would `import fooTI from './foo-ti';`
const mockFooTI = {
  Square: { // This structure would be generated by ts-interface-builder
    name: "Square",
    check: (value: any) => {
      if (typeof value !== 'object' || value === null) throw new Error('value is not an object');
      if (typeof value.size !== 'number') throw new Error('value.size is not a number');
      if ('color' in value && typeof value.color !== 'string') throw new Error('value.color is not a string');
    }
  }
};

// Import createCheckers from the library
import { createCheckers } from "ts-interface-checker";

const { Square } = createCheckers(mockFooTI); // Pass in the generated type suite

console.log("Checking valid objects:");
Square.check({ size: 1 });                  // OK
Square.check({ size: 1, color: "green" });  // OK
console.log("Valid objects checked successfully.");

try {
  console.log("\nChecking invalid object (missing property):");
  Square.check({ color: "green" });
} catch (e: any) {
  console.error(`Error: ${e.message}`); // Expected: Error: value.size is not a number
}

try {
  console.log("\nChecking invalid object (wrong property type):");
  Square.check({ size: 4, color: 5 });
} catch (e: any) {
  console.error(`Error: ${e.message}`); // Expected: Error: value.color is not a string
}