Modules and Declaration Files

1
2
3
4
5
6
7
8
9
10
11
12
13export interface User {
  id: number;
  name: string;
}

export type Role = 'admin' | 'editor' | 'viewer';

// A value and a type can be exported side by side.
export const ROLES: readonly Role[] = ['admin', 'editor', 'viewer'];

export function isRole(value: unknown): value is Role {
  return typeof value === 'string' && (ROLES as readonly string[]).includes(value);
}

1
2
3
4
5
6
7
8
9
10
11import { type User, type Role, ROLES, isRole } from './types.js';

function describe(user: User, role: Role): string {
  return `${user.name} is ${role}`;
}

const user: User = { id: 1, name: 'Ada' };

console.log(describe(user, 'admin'));
console.log(ROLES.join(', '));
console.log(isRole('editor'), isRole('nonsense'));

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16// 1. An inline type modifier. Clear at a glance which names are types, and
//    those names are guaranteed to be erased.
import { type User, ROLES } from './types.js';

// 2. A type-only import statement. The whole statement disappears.
import type { Role } from './types.js';

// 3. A plain import. Works, but the compiler has to decide what to erase, and
//    a reader cannot tell which of these are types.
import { isRole } from './types.js';

function describe(user: User, role: Role): string {
  return isRole(role) ? `${user.name}: ${role}` : `${user.name}: unknown`;
}

console.log(describe({ id: 1, name: 'Ada' }, 'admin'), ROLES.length);

1
2
3
4
5
6
7
8
9
10
11// user.ts
import type { Order } from './order.js';

export interface User {
  id: number;
  orders: Order[];
}

export function orderCount(user: User): number {
  return user.orders.length;
}

1
2
3
4
5
6
7
8
9
10import type { User } from './user.js';

export interface Order {
  id: string;
  placedBy: User;
}

export function ownerName(order: Order): number {
  return order.placedBy.id;
}

1
2
3export function internalParse(input: string): number {
  return Number.parseInt(input, 10);
}

1
2
3
4
5
6
7
8
9
10
11
12// Re-export selected names.
export { type User, ROLES } from './types.js';

// Re-export everything a module has.
export * from './parse.js';

// Re-export with a rename, which is how you present a tidier public API than
// your internal file layout.
export { internalParse as parse } from './parse.js';

// Type-only re-export, for the same erasure reasons as before.
export type { Role } from './types.js';

1
2
3
4
5
6
7
8
9
10
11
12
13
14// `declare` says: this exists somewhere, here is its type, do not emit
// anything for it.
declare function add(a: number, b: number): number;

declare const VERSION: string;

declare class Calculator {
  constructor(precision: number);
  add(value: number): this;
  result(): number;
}

// In a .d.ts these still need exporting to be importable.
export { add, VERSION, Calculator };

1
2
3
4// If a package has no types at all, the compiler errors on the import. This
// silences it and gives you `any`, which is the fastest possible fix and
// leaves you with no checking.
declare module 'legacy-charts';

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17// You do not have to describe the whole library. Ten minutes describing the
// three functions you call gives you real checking on the part you touch.
declare module 'legacy-charts' {
  export interface ChartOptions {
    width: number;
    height: number;
    title?: string;
  }

  export class Chart {
    constructor(element: HTMLElement, options: ChartOptions);
    render(data: readonly number[]): void;
    destroy(): void;
  }

  export function version(): string;
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15// A global injected by a build tool or a script tag.
declare global {
  const BUILD_VERSION: string;

  interface Window {
    analytics?: {
      track(event: string, payload?: Record<string, unknown>): void;
    };
  }
}

// A file containing top-level import or export is a module, and `declare
// global` inside a module needs this to work. In a file with no imports or
// exports, the declarations are already global and this is unnecessary.
export {};

1
2
3
4
5
6
7
8function report(event: string): string {
  // Optional, so it must be checked — which is right, because a script may
  // not have loaded.
  window.analytics?.track(event, { version: BUILD_VERSION });
  return `reported ${event} on build ${BUILD_VERSION}`;
}

console.log(typeof report);

1
2
3
4
5
6
7
8
9
10
11
12// The canonical case: middleware attaches `user` to every request, and you
// want the rest of your code to know about it.
declare module 'express-serve-static-core' {
  interface Request {
    user?: {
      id: number;
      roles: readonly string[];
    };
  }
}

export {};

1
2
3
4
5
6
7
8
9
10
11
12
13// Without this, `import styles from './button.module.css'` is an error,
// because the compiler has no idea what a CSS file is.
declare module '*.module.css' {
  const classes: Record<string, string>;
  export default classes;
}

declare module '*.svg' {
  const url: string;
  export default url;
}

export {};

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18// This course compiles with lib: ["es2023", "dom"], so all of these resolve.

// es2015 and later.
console.log('Map:', new Map([['a', 1]]).get('a'));

// es2019.
console.log('flat:', [1, [2, [3]]].flat(2));

// es2022.
console.log('at:', [1, 2, 3].at(-1));
console.log('hasOwn:', Object.hasOwn({ a: 1 }, 'a'));

// es2023.
console.log('findLast:', [1, 2, 3, 4].findLast((n) => n % 2 === 1));
console.log('toSorted:', [3, 1, 2].toSorted((a, b) => a - b));

// From dom.
console.log('URL is available:', typeof URL);

1
2
3
4
5
6
7
8
9
10
11
12
13namespace Geometry {
  export interface Point {
    x: number;
    y: number;
  }

  export function distance(a: Point, b: Point): number {
    return Math.hypot(a.x - b.x, a.y - b.y);
  }
}

const corner: Geometry.Point = { x: 0, y: 0 };
console.log(Geometry.distance(corner, { x: 3, y: 4 }));