Understanding TypeScript’s Type System: Safe Any Interoperability and Top‑Level Types

Proofs are programs, and conclusions are program types – the Curry‑Howard correspondence.

Background

Every day we use TypeScript’s type system; this article aims to introduce its principles and practical usage so readers can write type‑safe and concise code.

The intended audience has a basic understanding of TypeScript.

CodeShare – Safe any Interoperability

It is well known that any disables all type checking, but in real browser code we cannot completely avoid any entering the type system, affecting type inference. Examples include JSON.parse(), Reflect.get(), and Response.json().

The best practice is to first convert any to the top‑level type unknown , which forces developers to perform explicit type conversions before using the value elsewhere.

The following snippet attempts to retrieve a globally mounted method from window , safely cast it if it exists, otherwise fall back with a warning:

export type I18NMethod = (key: string, options: unknown, fallbackText: string) => string;

function isI18nFunction(input: unknown): input is I18NMethod {
  return typeof input === 'function';
}

function makeI18nMethod(): I18NMethod {
  let hasWarnShown = false;

  return function (key: string, options: unknown, fallbackText: string) {
    if (Reflect.has(window, '$i18n')) {
      const globalI18n: unknown = Reflect.get(window, '$i18n');
      if (isI18nFunction(globalI18n)) {
        return globalI18n(key, options, fallbackText);
      }
    }
    showWarnOnce();
    return fallbackText;
  };

  function showWarnOnce() {
    if (hasWarnShown === false) {
      hasWarnShown = true;
      console.warn('Cannot Fetch i18n Text: window.$18n is not a valid function');
    }
  }
}

export const $i18n = makeI18nMethod();

// usecase
$i18n("hello-text-key", {}, "你好");

Line 13 obtains an any object and first converts it to unknown . If line 14 omitted the isI18nFunction check and returned globalI18n directly, TypeScript would error: "Type 'unknown' is not assignable to type 'string'", forcing developers to write an explicit conversion.

The article recommends using the is syntax for runtime type guards, then performing safe type casts.

Fundamental Type System Principles

Four questions are addressed: why any is unsafe, what top‑level types are, why they are safe, and why unknown is a top‑level type.

Understanding subtyping is essential: a subtype can be used wherever its supertype is expected.

TypeScript employs a structural subtype system: if type A has all the structure of type B, A is a subtype of B.

Examples illustrate basic subtype inference using classes, showing implicit safe conversions and explicit unsafe casts.

any Type

any is a special TypeScript type that is both a supertype and a subtype of all types, effectively turning off type checking.

let aAny: any = 1;
let aNumber: number = 1;

aAny = aNumber; // OK
aNumber = aAny; // OK

Top‑Level Types

A top‑level type is a supertype of all possible types. In TypeScript, unknown serves this role because any type can be assigned to it, but not vice‑versa without an explicit cast.

let aUnknown: unknown = 1;
let aNumber: number = 1;

aUnknown = aNumber; // OK
aNumber = aUnknown; // Error

Type Conversion

Only parent‑child type conversions are allowed. Converting via unknown acts as a safe intermediate step.

// Advertiser -> unknown -> Employee
getSalary(new Advertiser() as unknown as Employee)

Up‑casting (subtype to supertype) is safe and implicit; down‑casting requires explicit assertion.

Writing Type‑Safe Code

Enabling strictNullChecks and strictFunctionTypes in TypeScript improves safety.

Basic Type Obsession

Using primitive types like number , string , and boolean can hide intent. The article demonstrates wrapping such primitives in domain‑specific classes (e.g., Milliseconds ) to improve readability and enforce constraints.

declare function debounce
(wait: number, fn: (...args: Args) => Output): (...args: Args) => Output;

const debouncedLog = debounce(500, (input: string) => console.log(input));

By defining a Milliseconds class with runtime validation, the intent becomes clear and invalid values are caught early.

class Milliseconds {
  constructor(public readonly value: number) {
    if (this.value < 0) {
      throw new Error('Milliseconds value cannot be smaller than 0');
    }
  }
}

Further refinements use unique symbols to simulate nominal subtyping and literal type checks to enforce positivity at compile time.

Deep Dive into Type System

The article explores variance, product vs. sum types, intersection types, and the distinction between nominal and structural typing, providing code examples in both TypeScript and Java.

Variance

Functions are covariant in return types and contravariant in parameter types; arrays and generic containers follow the same subtype relationships as their element types.

Nominal vs. Structural Typing

Nominal typing requires explicit declarations of subtype relationships (e.g., Java), while structural typing (e.g., TypeScript) infers subtyping based on shape, allowing more flexible code reuse.

Special Types

Bottom types ( never ) and unit types ( void , null , undefined ) are discussed, with examples of their usage in functions that never return or only return a single value.

Type Composition Complexity

Sum (union) types, product (tuple/object) types, and intersection types are explained with algebraic analogies and TypeScript syntax.

References are listed at the end of the article.