Why TypeScript Isn’t Just “Type Gym”: A Practical Guide to Safer API Design

Preface

Many developers complain about "type gymnastics" and struggle to learn TypeScript, often forgetting what they learned shortly after.

Introduction

We examine a simple API design scenario: creating a function that extracts specified keys from an object and returns a new object.

Bad TypeScript

A developer writes a loosely typed function:

declare function pick(target: any, ...keys: any): any

Calling it with incorrect arguments leads to runtime errors.

Just Learning TypeScript

Improving the signature with basic types reduces errors:

declare function pick(target: Record<string, unknown>, ...keys: string[]): unknown

However, issues remain when object keys are long or complex.

Not Just TypeScript

Using generics and keyof solves the key‑validation problem:

declare function pick<T extends Record<string, unknown>>(target: T, ...keys: (keyof T)[]): unknown

Yet the return type still lacks precision.

Calculating Types

We can compute a new type that maps selected keys to their values:

declare function pick<T extends Record<string, unknown>, Keys extends keyof T>(target: T, ...keys: Keys[]): { [K in Keys]: T[K] }

This handles duplicate keys and provides accurate typings.

Perfect TypeScript

Advanced type utilities like L2T enable handling of repeated keys and more complex scenarios:

export type L2T<L, LAlias = L, LAlias2 = L> = [L] extends [never]
  ? []
  : L extends infer LItem
    ? [LItem?, ...L2T<Exclude<LAlias2, LItem>, LAlias>]
    : never;

declare function pick<T extends Record<string, unknown>, Keys extends L2T<keyof T>>(target: T, ...keys: Keys): Pick<T, Keys[number]> & keyof T;

const x0 = pick({ a: '1', b: '2' }, 'a');
// @ts-expect-error
console.log(x0.b);

const x1 = pick({ a: '1', b: '2' }, 'a', 'a');
// TS2345 error because duplicate keys are not assignable

A relatively perfect pick function is thus achieved.

Conclusion

People adopt TypeScript for several reasons: following trends, contributing to mature projects, or because their company’s stack requires it. The underlying motive is often to solve type‑checking problems, which can lead to resistance.

Ensuring thorough type checking

Providing friendly type hints

Maintaining strict type safety

Ensuring extensibility

Designing APIs with these goals lets developers write code easily without constantly consulting documentation.

Hopefully this sharing deepens your understanding of TypeScript and encourages you to contribute to its ecosystem.