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

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

This article explores common frustrations with TypeScript, demonstrates how to design a robust `pick` API using generics, keyof, and advanced type tricks, and offers practical guidelines for creating type‑safe, developer‑friendly code.

MaGe Linux Operations
MaGe Linux Operations
MaGe Linux Operations

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.

Original Source

Signed-in readers can open the original source through BestHub's protected redirect.

Sign in to view source
Republication Notice

This article has been distilled and summarized from source material, then republished for learning and reference. If you believe it infringes your rights, please contactadmin@besthub.devand we will review it promptly.

TypeScriptprogrammingGenericsAPI Designtype safety
Reader feedback

How this landed with the community

Sign in to like

Rate this article

Was this worth your time?

Sign in to rate
Discussion

0 Comments

Thoughtful readers leave field notes, pushback, and hard-won operational detail here.