
TypeScript infers types from the values you assign - you rarely need to annotate every variable. But inference has rules, and knowing when it widens a type vs narrows it prevents subtle bugs.

<ExamplePair>
<ExampleProse>

`const` infers a narrow literal type. `let` infers a wide primitive type because the value can change.

</ExampleProse>
<ExampleCode>

```ts
const lang = "typescript";  // type: "typescript" (string literal)
let lang2 = "typescript";   // type: string (widened)

const count = 42;            // type: 42 (numeric literal)
let count2 = 42;             // type: number (widened)
```

</ExampleCode>
</ExamplePair>

<ExamplePair>
<ExampleProse>

Object and array literals inferred with `const` still get wide types for their properties - the object reference is const, but the properties are mutable. Use `as const` to lock everything down to literal types.

</ExampleProse>
<ExampleCode>

```ts
const config = { env: "production", port: 3000 };
// config.env: string (NOT "production")
// config.port: number (NOT 3000)

const config2 = { env: "production", port: 3000 } as const;
// config2.env: "production"
// config2.port: 3000
// All properties are readonly - config2.env = "staging" is a type error
```

</ExampleCode>
</ExamplePair>

<ExamplePair>
<ExampleProse>

TypeScript infers function return types automatically. Annotating the return type explicitly is optional but documents intent and catches mistakes when the function body changes.

</ExampleProse>
<ExampleCode>

```ts
// inferred return type: number
function add(a: number, b: number) {
  return a + b;
}

// explicit return type - documents intent, errors if the body returns something else
function greet(name: string): string {
  return `Hello, ${name}!`;
}

// explicit return type: Promise<number>
async function fetchCount(): Promise<number> {
  return 42;
}
```

</ExampleCode>
</ExamplePair>

<InProduction>
The widening of object literals is one of the most common TypeScript footguns in configuration code. `const config = { env: 'production' }` gives `config.env` the type `string`, not `'production'`. When this config object is passed to a function expecting `{ env: 'production' | 'staging' }`, TypeScript rejects it with a confusing error. Fix it at the source with `as const` or an explicit type annotation. This pattern appears constantly in feature flags, environment configs, and route definitions - getting it right once prevents a class of "works at runtime but fails type checking" surprises.
</InProduction>


How TypeScript infers types from assignments - const vs let narrowing, as const, and return type inference.

Type Inference


Interfaces describe the shape of an object. TypeScript uses structural typing - any object that has the required fields satisfies the interface, regardless of what class or constructor created it.

<ExamplePair>
<ExampleProse>

An interface declares a set of required properties and their types. Optional properties use `?`; readonly properties use `readonly` and cannot be reassigned after creation.

</ExampleProse>
<ExampleCode>

```ts
interface User {
  id: string;
  name: string;
  email?: string;         // optional
  readonly createdAt: Date; // cannot be changed after assignment
}

const user: User = {
  id: "u_1",
  name: "Alice",
  createdAt: new Date(),
};

user.name = "Bob";          // ok - name is mutable
// user.createdAt = new Date(); // error - readonly
```

</ExampleCode>
</ExamplePair>

<ExamplePair>
<ExampleProse>

Interfaces can extend other interfaces to compose shapes without repeating fields. A class can implement an interface to guarantee it satisfies the contract.

</ExampleProse>
<ExampleCode>

```ts
interface Entity {
  id: string;
  createdAt: Date;
  updatedAt: Date;
}

interface Product extends Entity {
  name: string;
  priceInCents: number;
  sku: string;
}

// Any object with all required fields satisfies Product - no class needed
const widget: Product = {
  id: "p_1",
  name: "Widget",
  priceInCents: 999,
  sku: "WGT-001",
  createdAt: new Date(),
  updatedAt: new Date(),
};
```

</ExampleCode>
</ExamplePair>

<ExamplePair>
<ExampleProse>

Declaration merging: declaring the same interface twice merges the two declarations into one. This is how library authors augment global types without modifying the original source.

</ExampleProse>
<ExampleCode>

```ts
interface Config {
  port: number;
}

interface Config {
  host: string; // merged - both declarations combine
}

// Config now requires: { port: number; host: string }
const config: Config = { port: 3000, host: "localhost" };
```

</ExampleCode>
</ExamplePair>

<InProduction>
Interfaces are open by design - declaration merging is how libraries like Express augment `Request` to add `req.user` without forking the types. That power cuts both ways: if you accidentally re-declare an interface you own, TypeScript silently merges the declarations rather than erroring, which can add unexpected properties to an otherwise closed contract. For shapes you own and don't want extended by consumers or test utilities, prefer type aliases - they're closed and don't merge.
</InProduction>


Declaring interfaces - optional and readonly properties, extending interfaces, and declaration merging.

Interfaces


TypeScript adds static types on top of JavaScript's runtime types. Most annotations are optional - the compiler infers types from assignments - but knowing the full type vocabulary lets you annotate precisely when inference isn't enough.

<ExamplePair>
<ExampleProse>

The primitive types mirror JavaScript's built-in values. Type annotations appear after the variable name with a colon.

</ExampleProse>
<ExampleCode>

```ts
const name: string = "Alice";
const age: number = 30;
const active: boolean = true;
const nothing: null = null;
const missing: undefined = undefined;
const id: symbol = Symbol("id");
const big: bigint = 9007199254740993n;
```

</ExampleCode>
</ExamplePair>

<ExamplePair>
<ExampleProse>

`any` opts a value out of type checking entirely - the compiler stops tracking it. `unknown` is the safer alternative: values are type-checked, but you must narrow the type before using them.

</ExampleProse>
<ExampleCode>

```ts
// any: no type checking - avoid in new code
let loose: any = "hello";
loose = 42;          // no error
loose.toFixed(2);    // no error - even if loose is a string

// unknown: must narrow before use
let raw: unknown = JSON.parse('{"x": 1}');
// raw.x  ← error: Object is of type 'unknown'

if (typeof raw === "object" && raw !== null && "x" in raw) {
  console.log((raw as { x: number }).x); // safe
}
```

</ExampleCode>
</ExamplePair>

<ExamplePair>
<ExampleProse>

`never` is TypeScript's bottom type - a type with no values. It appears in two situations: functions that never return (they always throw or loop forever), and union branches that TypeScript has fully exhausted during narrowing.

The `assertUnreachable` helper is what makes `never` useful in practice. Its parameter type is `never`, so if TypeScript believes any value could reach that call, you get a compile error - not a runtime crash.

</ExampleProse>
<ExampleCode>

```ts
// A function that never returns has return type `never`
function fail(message: string): never {
  throw new Error(message);
}

// x: never means "this branch is impossible - the compiler guarantees it"
function assertUnreachable(x: never): never {
  return fail(`Unhandled case: ${JSON.stringify(x)}`);
}

type Direction = "north" | "south" | "east" | "west";

function move(dir: Direction): string {
  switch (dir) {
    case "north": return "moving north";
    case "south": return "moving south";
    case "east":  return "moving east";
    case "west":  return "moving west";
    default: return assertUnreachable(dir);
    // ↑ dir is `never` here because all cases are handled.
    // Add "northeast" to Direction and this line immediately errors.
  }
}
```

</ExampleCode>
</ExamplePair>

<ExamplePair>
<ExampleProse>

The real payoff shows up on a team. When you add a new variant to a shared union - a new event type, a new API status, a new feature flag - TypeScript errors at every unhandled `switch` across the entire codebase. You can't ship until every callsite is updated. `never` turns a runtime oversight into a compile-time requirement.

<ProdNote>
Add `assertUnreachable` to `utils/types.ts` and import it in every switch. When a teammate adds a new union variant, every unhandled switch fails to compile - the bug is caught in CI, not in production.
</ProdNote>

</ExampleProse>
<ExampleCode>

```ts
type ApiEvent =
  | { type: "success"; data: { id: string; name: string } }
  | { type: "error"; code: number; message: string }
  | { type: "loading" };

function handleEvent(event: ApiEvent): void {
  switch (event.type) {
    case "success":
      renderUser(event.data);
      break;
    case "error":
      showError(event.code, event.message);
      break;
    case "loading":
      showSpinner();
      break;
    default:
      assertUnreachable(event);
  }
}

// A teammate adds `{ type: "cancelled" }` to ApiEvent.
// The default branch above errors immediately:
//   Argument of type '{ type: "cancelled" }' is not
//   assignable to parameter of type 'never'.
// No runtime bug. No forgotten branch. Caught at CI.
```

</ExampleCode>
</ExamplePair>

<InProduction>
Ban `any` with `@typescript-eslint/no-explicit-any` from day one. Use `unknown` at every boundary where you don't control the shape - JSON.parse, API responses, message queues - and narrow before you use it. `any` lets bugs through silently; `unknown` makes the compiler ask you to prove it's safe first.
</InProduction>


TypeScript's built-in scalar types - string, number, boolean, null, undefined, symbol, bigint, any, unknown, never.