home > research > effective-typescript (2026-04-19)

Mastering TypeScript: Strategies and Best Practices

Mastering TypeScript: Strategies and Best Practices

Table of Contents

Effective TypeScript

TypeScript and JavaScript

Options

Code Generation

Structural Typing

any

Type System

Editors

Sets of Values

Type Space vs. Value Space

Type Declarations

Avoid Object Wrapper Types

Excessive Property Checking

Function Expressions

Type vs. Interface

Operations and Generics

Index Signatures

Arrays, Tuples, and ArrayLike

readonly

Mapped Types

Type Inference

Variables

Type Widening

Type Narrowing

Create Objects All at Once

Aliases

async vs Callbacks

Context

Functional Constructs

Type Design

Valid States

Liberal in Accept, Strict in Produce

Documentation

Null Values to Perimeter

Unions of Interfaces

Precise Alternatives to Strings

Incomplete vs. Inaccurate

Generate Types from APIs

Problem Domain

Brands

Working with any

Narrowest Possible Scope

More Precise Variants

Hide Unsafe

Evolving any

Use unknown

Monkey Patching

Track Type Coverage

Types Declarations and @types

devDependencies

Three Versions

Exports

TSDoc

this in Callbacks

Conditional Types

Mirror Types

Testing Types

Writing and Running Code

Iteration

DOM

Private

Source Maps

Migration

Modern JavaScript

@ts-checking

allowJs

Module Conversion

noImplicitAny

2026 Review

TypeScript 5.7 and 5.8 (late 2025 through 2026)

TypeScript 5.7 (November 2025) and 5.8 (early 2026) continued the pattern of incremental precision: --isolatedDeclarations stabilization for parallel d.ts emit, import attributes GA, --noUncheckedSideEffectImports, and --erasableSyntaxOnly (prerequisite for native TS execution). The 5.8 cycle hardened const type parameters and graduated NoInfer from experimental to stable.

Notable changes across the two releases:

  • satisfies operator fully adopted across major libraries and frameworks
  • const type parameters allow callers to pin literal types without assertions
  • NoInfer<T> prevents type inference from flowing through a specific site
  • --isolatedDeclarations enables build tools to parallelize .d.ts generation
  • --erasableSyntaxOnly rejects enums and namespaces that survive erasure, enabling drop-in compatibility with Node.js native strip-types mode

The Go Rewrite of tsc (announced March 2025)

In March 2025 Microsoft announced a port of the TypeScript compiler to Go, targeting a 10x throughput improvement. The key design decisions:

  • Structural equivalence to the JS compiler: same AST shapes, same type algorithm, same error messages
  • Native concurrency in the Go runtime replaces single-threaded JS semantics
  • Language server (tsserver) rewritten alongside the compiler, preserving the LSP surface
  • Opt-in via --newTsc flag; expected to become the default in a 7.x release

The port does not change the language itself — only the implementation. Existing code, tsconfig options, and d.ts files are unaffected.

TypeScript in Node.js (–experimental-strip-types, Node 23+)

Node.js 22.6 introduced --experimental-strip-types, promoted to unflagged in Node.js 23. The mechanism:

  • The loader invokes a lightweight transform (based on @swc/wasm-typescript) that erases type annotations without re-ordering code
  • Only erasable syntax is allowed: type annotations, interfaces, type aliases, generic parameters. Enums and namespaces require --experimental-transform-types
  • No tsconfig lookup at runtime; type-checking remains a separate build step
  • Compatible with ESM and CJS module resolution

The result is that node --experimental-strip-types app.ts works without a build step in Node 23, making TypeScript a first-class scripting language on the platform.

Deno 2.x and Bun — TypeScript-first runtimes

Deno 2.0 (October 2024) and its subsequent 2.x releases stabilized the transition from Deno 1.x's opinionated stdlib to npm/Node compatibility:

  • Full npm package resolution and node_modules support
  • deno compile produces self-contained binaries from TypeScript entry points
  • Built-in formatter (deno fmt), linter (deno lint), and test runner understand TypeScript natively
  • JSR (JavaScript Registry) as the preferred module registry, with mandatory type declarations

Bun continues to support TypeScript by default via its built-in transpiler (Zig + JavaScriptCore), with sub-millisecond startup times for most scripts. Bun added a native lockfile format in 1.x and stabilized its macros API.

Type System Advances

satisfies operator maturity

satisfies (introduced in 4.9) reached ubiquity in 2026: it validates an expression against a type without widening the inferred type. This is the idiomatic replacement for many as-cast patterns. 

type Palette = Record<string, [number, number, number] | string>;

const colors = {
  red: [255, 0, 0],
  green: "#00ff00",
  blue: [0, 0, 255],
} satisfies Palette;

// Narrowed to string (not string | [number,number,number]) because satisfies
// validates without widening the inferred type.
const hexGreen: string = colors.green;
const redChannel: number = colors.red[0];

const type parameters

A const modifier on a generic parameter tells the compiler to infer the narrowest possible (literal / tuple / readonly) type for the argument. 

// Without `const`, T widens to string[] and Page becomes string.
function route<const T extends readonly string[]>(paths: T): T {
  return paths;
}

const pages = route(["home", "about", "contact"]);
type Page = (typeof pages)[number]; // "home" | "about" | "contact"

NoInfer utility type

NoInfer<T> blocks type inference from flowing through the wrapped position. Useful when a function should infer a type from one argument and then validate (not widen) other arguments against it. 

// NoInfer blocks T from being widened by the reducer's return type.
// Without it, a reducer that returns a supertype would silently change T.
function createStore<T>(
  initial: T,
  reducer: (state: NoInfer<T>, action: string) => NoInfer<T>,
): { state: T } {
  return { state: reducer(initial, "init") };
}

const store = createStore(
  { count: 0 },
  (state, _action) => ({ count: state.count + 1 }),
);

TypeScript in the Agent Era

The Anthropic SDK, Vercel AI SDK, and MCP TypeScript SDK define the current idioms for TypeScript in agent systems.

The Anthropic SDK (@anthropic-ai/sdk) ships full TypeScript declarations for all message types, tool call schemas, and streaming events. The Vercel AI SDK (ai package) provides a unified interface across providers with generateText, streamText, and generateObject (which takes a Zod schema and returns a validated typed object). The MCP TypeScript SDK (@modelcontextprotocol/sdk) defines the transport and message types for the Model Context Protocol.

Common patterns emerging in this space:

  • Zod-first tool schemas: tool parameters defined once in Zod, then inferred as TypeScript types and serialized to JSON Schema at runtime
  • Discriminated unions for agent message types (user / assistant / toolresult)
  • satisfies for provider configuration objects to preserve string literals while validating against a broader config type
  • const type parameters for typed prompt template functions
  • Streaming with typed AsyncIterable<T> return types

Compilation Targets Diagram

// TypeScript compilation targets — 2026
digraph ts_targets {
    rankdir=LR;
    graph [bgcolor="white", fontname="Helvetica", fontsize=11,
           pad="0.4", nodesep="0.35", ranksep="0.6"];
    node  [shape=box, style="rounded,filled", fontname="Helvetica",
           fontsize=10, fillcolor="#f5f5f5", color="#888"];
    edge  [color="#aaa"];

    ts_source [label="TypeScript\nSource (.ts)", fillcolor="#e8f4fd", color="#3178c6"];

    subgraph cluster_compilers {
        label="Compilers / Transpilers"; style="rounded"; color="#555"; fontcolor="#555";
        tsc     [label="tsc\n(JS + Go port)", fillcolor="#dff0d8", color="#3c763d"];
        swc     [label="swc (Rust)",          fillcolor="#dff0d8", color="#3c763d"];
        esbuild [label="esbuild (Go)",        fillcolor="#dff0d8", color="#3c763d"];
        strip   [label="Node strip-types\n(erasure only)", fillcolor="#dff0d8", color="#3c763d"];
    }

    js_out [label="JavaScript (.js)", fillcolor="#fdf5e8", color="#c67b00"];

    subgraph cluster_runtimes {
        label="Runtimes"; style="rounded"; color="#3178c6"; fontcolor="#3178c6";
        node_rt   [label="Node.js 23+",  fillcolor="#e8f4fd", color="#3178c6"];
        deno_rt   [label="Deno 2.x",     fillcolor="#e8f4fd", color="#3178c6"];
        bun_rt    [label="Bun",          fillcolor="#e8f4fd", color="#3178c6"];
        browser   [label="Browser",      fillcolor="#e8f4fd", color="#3178c6"];
    }

    ts_source -> tsc;
    ts_source -> swc;
    ts_source -> esbuild;
    ts_source -> strip;

    tsc     -> js_out;
    swc     -> js_out;
    esbuild -> js_out;
    strip   -> js_out [style=dashed, label="in-process"];

    js_out -> node_rt;
    js_out -> deno_rt;
    js_out -> bun_rt;
    js_out -> browser;

    // Direct native TS execution paths (no separate JS artifact)
    ts_source -> deno_rt [style=dashed, color="#aaa", label="native"];
    ts_source -> bun_rt  [style=dashed, color="#aaa", label="native"];
    ts_source -> node_rt [style=dashed, color="#aaa", label="strip-types\n(Node 23+)"];
}

diagram-ts-targets.png

Author: Jason Walsh

j@wal.sh

Last Updated: 2026-04-19 08:30:00

build: 2026-04-20 23:43 | sha: d110973