Runtime Interface Validation in TypeScript: Compile-Time Type System and Runtime Solutions

In TypeScript development, interfaces serve as essential tools for defining object structures, providing compile-time type checking that helps developers catch potential type errors. However, a common misconception is expecting these interface definitions to automatically validate data at runtime. In reality, TypeScript's type system is completely erased during compilation, with the generated JavaScript code containing no type information. This means that when loading data from external sources, such as JSON configuration files, one cannot directly use interface definitions to verify the structural correctness of the data.

The Nature of TypeScript's Type System

TypeScript's design philosophy emphasizes static type checking rather than runtime validation. During compilation, type annotations and interface definitions are used to check code consistency but do not generate corresponding runtime code. For example, consider the following interface definition:

interface EngineConfig {
    pathplanner?: PathPlannerConfig;
    debug?: DebugConfig;
}

In the compiled JavaScript, this interface definition completely disappears, leaving only the actual object manipulation code. Therefore, when loading configuration from a JSON file:

const config = JSON.parse(fs.readFileSync('config.json', 'utf8'));

One cannot directly use the EngineConfig interface to verify whether the config object conforms to the expected structure, nor detect the presence of undefined additional properties.

User-Defined Type Guards

Although TypeScript does not provide built-in runtime validation mechanisms, developers can implement validation logic manually through user-defined type guards. A type guard is a special function with a return type of arg is Type, used to determine at runtime whether an object satisfies a specific interface. For example:

interface Test {
    prop: number;
}

function isTest(arg: any): arg is Test {
    return arg && arg.prop && typeof arg.prop === 'number';
}

let obj: any = { prop: 5, extra: 'unexpected' };
if (isTest(obj)) {
    console.log(obj.prop); // Type-safe, TypeScript knows obj is of type Test
    // However, the isTest function does not check the extra property, potentially missing validation
}

The advantage of this approach is complete control over validation logic, and it can be integrated with testing frameworks. However, it requires manual writing and maintenance of validation code, which can become verbose and error-prone for complex interfaces.

Third-Party Library Solutions

To simplify runtime validation, the community has developed various tool libraries. Among them, ts-interface-builder and ts-interface-checker provide a systematic approach. First, use build-time tools to generate interface descriptors:

// Generate descriptors at build time
// Command line: ts-interface-builder foo.ts -o foo-ti.ts

Then use these descriptors for validation at runtime:

import { createCheckers } from 'ts-interface-checker';
import fooDesc from './foo-ti';

const checkers = createCheckers(fooDesc);
const config = loadConfig();

try {
    checkers.EngineConfig.strictCheck(config); // Strict check, rejects unknown properties
    console.log('Configuration validation passed');
} catch (error) {
    console.error('Configuration error:', error.message);
}

This method offers high automation and accurately reflects interface definitions but adds build steps and runtime dependencies.

JSON Schema Conversion and Validation

Another popular approach involves converting TypeScript interfaces to JSON Schema and then using standard JSON validators. First, generate the Schema using the typescript-json-schema tool:

// Command line: typescript-json-schema --required --noExtraProps -o schema.json source.ts EngineConfig

Then use a validator like ajv at runtime:

const Ajv = require('ajv');
const schema = require('./schema.json');
const ajv = new Ajv({ allErrors: true });
const validate = ajv.compile(schema);

const config = loadConfig();
if (!validate(config)) {
    console.log('Validation errors:', validate.errors);
} else {
    console.log('Configuration is valid');
}

The advantage of this method lies in leveraging the mature JSON Schema ecosystem, supporting complex validation rules, though the conversion process may not fully preserve all TypeScript type features.

Comparative Analysis and Best Practices

Each solution has its appropriate use cases. User-defined type guards are suitable for simple interfaces and situations requiring highly customized validation logic. Third-party libraries like ts-interface-checker provide type-safe automated validation, ideal for large projects. The JSON Schema approach is more advantageous when interacting with external systems or requiring standardized validation.

In practice, it is recommended to choose the appropriate method based on project requirements. For critical configurations, multiple techniques can be combined: using JSON Schema for initial validation, followed by type guards for business logic checks. Always remember that TypeScript's core value lies in compile-time type safety, with runtime validation serving as a supplement rather than a replacement.

The TypeScript team has a long-standing discussion on GitHub (issue #3628) about whether to support runtime type information at the language level. Although not yet implemented, various community tools already provide practical solutions, helping developers ensure runtime data integrity while enjoying the benefits of TypeScript's static typing.