Module P-3 — TypeScript in Node.js

The authenticate middleware from P-2 adds req.user — but TypeScript does not know that. Fix it with module augmentation:

// src/types/express.d.ts
import { Request } from 'express';
 
declare global {
  namespace Express {
    interface Request {
      user?: {
        id: number;
        role: 'user' | 'admin' | 'moderator';
      };
      requestId?: string;
    }
  }
}

After this, req.user is fully typed in every handler — no casting needed:

export const getProfile = async (req: Request, res: Response, next: NextFunction) => {
  // req.user is typed as { id: number; role: string } | undefined
  if (!req.user) return res.status(401).json({ error: 'Unauthorized' });
 
  const user = await usersService.findById(req.user.id); // req.user.id is number
  res.json(user);
};

---

Interfaces vs Types

TypeScript checks that your data has the right shape, not that it wears the right name tag — like a bouncer who only checks you're holding a valid ticket stub, not which box office printed it. An interface Dog and a type Dog describing identical fields are interchangeable to the type checker; it never asks which keyword built the shape.

Both define object shapes. The differences that matter in practice:

// interface — can be extended and merged (declaration merging)
interface Animal {
  name: string;
}
 
interface Dog extends Animal {
  breed: string;
}
 
// Multiple declarations of the same interface merge
interface Request { user?: User; }
interface Request { requestId?: string; }
// Result: Request has both user and requestId
 
// type alias — more flexible, can represent unions and intersections
type ID = number | string;
type Status = 'active' | 'banned';
type AdminUser = User & { permissions: string[] };  // intersection
type ApiResponse<T> = { data: T; error: null } | { data: null; error: string };

Practical rule: use interface for object shapes (models, DTOs, service inputs). Use type for unions, intersections, and computed types (Omit, Pick, Partial).

---

unknown vs any: A Deliberate Safety Choice

Both types accept any value, but only one keeps the compiler on your side:

function process(input: any) {
  input.toUpperCase(); // compiles — even though this can crash at runtime
}
 
function processSafe(input: unknown) {
  input.toUpperCase(); // Error: Object is of type 'unknown'
  if (typeof input === 'string') {
    input.toUpperCase(); // fine — narrowed to string first
  }
}

any opts a value out of type checking entirely — it's a trapdoor, not a type. unknown says "this could be anything, so prove what it is before you use it." The compiler forces a narrowing check (typeof, instanceof, a type guard) before it lets you call a method or access a property.

The most common place this shows up in an Express codebase is catch (err: unknown), which you'll use throughout P-4's error handling:

try {
  await usersService.create(input);
} catch (err: unknown) {
  // err.message would be a compile error here — err isn't known to have one
  if (err instanceof AppError) {
    // narrowed — err.message, err.statusCode are safe
  }
}

With catch (err: any) (the old default), err.message compiles even though err could be a string, a PrismaClientKnownRequestError, or anything else something throws. With err: unknown, TypeScript forces you to check what you actually caught before touching it — which is exactly what the error handler in P-4 does, branching on instanceof ZodError, instanceof AppError, instanceof Prisma.PrismaClientKnownRequestError, and so on.

---

Utility Types You Use Daily

interface User {
  id: number;
  name: string;
  email: string;
  passwordHash: string;
  role: 'user' | 'admin';
  createdAt: Date;
}
 
// Omit — remove fields
type PublicUser = Omit<User, 'passwordHash'>;
 
// Pick — keep only specific fields
type UserSummary = Pick<User, 'id' | 'name'>;
 
// Partial — all fields optional (for update DTOs)
type UpdateUserInput = Partial<Pick<User, 'name' | 'email' | 'role'>>;
 
// Required — all fields required
type CompleteUser = Required<User>;
 
// Readonly — prevent mutation
type ImmutableUser = Readonly<User>;
 
// Record — dictionary type
type RolePermissions = Record<User['role'], string[]>;
// { user: string[]; admin: string[] }
 
// ReturnType — infer the return type of a function
async function findUser(id: number): Promise<User | null> { /* ... */ }
type FindUserResult = Awaited<ReturnType<typeof findUser>>;
// → User | null
 
// Parameters — infer function parameters
type FindUserParams = Parameters<typeof findUser>;
// → [id: number]
 
// NonNullable — remove null and undefined
type DefiniteUser = NonNullable<User | null | undefined>;
// → User

---

Generics: Writing Flexible Typed Code

Generics let you write functions and types that work with any type while preserving type information:

// Generic repository interface
interface Repository<T, ID = number> {
  findById(id: ID): Promise<T | null>;
  findAll(): Promise<T[]>;
  create(data: Omit<T, 'id' | 'createdAt'>): Promise<T>;
  update(id: ID, data: Partial<T>): Promise<T | null>;
  delete(id: ID): Promise<boolean>;
}
 
// Typed API response wrapper
type ApiResponse<T> =
  | { success: true; data: T }
  | { success: false; error: string; code: number };
 
function ok<T>(data: T): ApiResponse<T> {
  return { success: true, data };
}
 
function fail(error: string, code = 500): ApiResponse<never> {
  return { success: false, error, code };
}
 
// Paginated result
interface Paginated<T> {
  data: T[];
  total: number;
  page: number;
  limit: number;
  hasMore: boolean;
}
 
async function paginateQuery<T>(
  query: () => Promise<T[]>,
  countQuery: () => Promise<number>,
  page: number,
  limit: number,
): Promise<Paginated<T>> {
  const [data, total] = await Promise.all([query(), countQuery()]);
  return { data, total, page, limit, hasMore: page * limit < total };
}

---

Discriminated Unions: Narrowing by a Common Tag

The ApiResponse<T> type defined above is a discriminated union — a union where every member shares a literal-valued field (here, success) that TypeScript can use to figure out which branch you're in:

function handle<T>(response: ApiResponse<T>) {
  if (response.success) {
    console.log(response.data); // narrowed: this branch only has `data`
  } else {
    console.log(response.error, response.code); // narrowed: this branch only has `error`/`code`
  }
}

Once you check response.success, TypeScript eliminates the other branch from the type entirely inside that block — response.error is not even a valid property access in the if branch, and response.data is not valid in the else. This is the same pattern you'll lean on constantly with Zod's safeParse result, which is itself a discriminated union tagged on success:

const result = createUserSchema.safeParse(req.body);
if (result.success) {
  result.data;   // narrowed — safe to use, fully typed
} else {
  result.error;  // narrowed — the other branch, a ZodError
}

Naming this pattern matters because it's easy to write the less safe version instead — checking a boolean and then reaching for a property that isn't guaranteed on both branches (e.g. an optional data?: T alongside an optional error?: string on the same type, rather than two variants of a union). A discriminated union makes invalid states like "both data and error are set" unrepresentable, not just unlikely.

---

The satisfies Operator (TS 4.9+)

satisfies checks that a value conforms to a type — without widening the value's inferred type the way a : annotation does. It's now the idiomatic way to type a config or environment object where you still want the literal values, not the general type, to flow through:

type Env = 'development' | 'staging' | 'production';
 
const config = {
  port: 3000,
  env: 'production',
  logLevel: 'info',
} satisfies { port: number; env: Env; logLevel: string };
 
config.env; // inferred as the literal 'production', not the wider `Env`

Compare the three options for the same object:

• No annotation at all: config.env is inferred as string and a typo like 'produciton' compiles fine — nothing checks it against Env.
• : { port: number; env: Env; logLevel: string }: catches the typo, but now config.env's type is the full Env union everywhere it's used — you lose the fact that this config object is specifically 'production'.
• satisfies { ... }: catches the same typo, and config.env keeps its literal type ('production'), because satisfies only validates the shape — it doesn't change what TypeScript infers the variable's type to be.

This is exactly the shape of problem the env config object built in P-6 solves: you want process.env.NODE_ENV validated against a known set of values and you want the resulting config's fields to stay as narrow and specific as what was actually parsed, not widened into their general types. satisfies gets you both at once, which is why it's replaced the : Type annotation for this use case in most codebases written after TS 4.9.

---

Typing Service and Repository Layers

// src/repositories/users.repository.ts
import prisma from '../db/prisma.js';
import { User, PublicUser } from '../types/models.js';
 
export async function findById(id: number): Promise<PublicUser | null> {
  return prisma.user.findUnique({
    where: { id },
    select: { id: true, name: true, email: true, role: true, createdAt: true },
  });
}
 
export async function findByEmail(email: string): Promise<User | null> {
  return prisma.user.findUnique({ where: { email } });
}
 
export async function create(data: {
  name: string;
  email: string;
  passwordHash: string;
}): Promise<PublicUser> {
  return prisma.user.create({
    data,
    select: { id: true, name: true, email: true, role: true, createdAt: true },
  });
}

// src/services/users.service.ts
import * as usersRepo from '../repositories/users.repository.js';
import { AppError } from '../errors/AppError.js';
import { PublicUser } from '../types/models.js';
 
export async function findById(id: number): Promise<PublicUser> {
  const user = await usersRepo.findById(id);
  if (!user) throw new AppError('User not found', 404);
  return user; // TypeScript knows this is PublicUser, not null
}

The type information flows from repository → service → controller. TypeScript catches mismatches at every boundary.

---

Incrementally Migrating JavaScript to TypeScript

You do not need to convert everything at once. The incremental approach:

Step 1: Add TypeScript without breaking anything

// tsconfig.json — start permissive
{
  "compilerOptions": {
    "allowJs": true,          // allow .js files
    "checkJs": false,         // don't type-check .js files yet
    "strict": false,          // start loose, tighten later
    "outDir": "./dist"
  }
}

Step 2: Convert files one by one

Rename .js to .ts. Fix errors. Commit. Move to the next file.

Start with:

1. types/models.ts — define your domain types first
2. repositories/ — add return types to DB functions
3. services/ — add input/output types
4. controllers/ — type req, res, next
5. Last: index.ts, middleware, routes

Step 3: Tighten the config progressively

// After most files converted
{
  "compilerOptions": {
    "strict": true,
    "checkJs": false,       // still allow JS where needed
    "allowJs": false        // once all files are .ts
  }
}

Step 4: Enable noUncheckedIndexedAccess

This is the last setting to add — it causes the most friction but catches real bugs:

const arr = [1, 2, 3];
const first = arr[0]; // With noUncheckedIndexedAccess: number | undefined
if (first !== undefined) {
  console.log(first * 2); // TypeScript is sure it's a number here
}

Production story: A payments settlement service was migrated to TypeScript file by file, following exactly the order this section describes — types, then repositories, then services. The team turned on strict immediately but left noUncheckedIndexedAccess for "later," since it's the noisiest setting to enable and floods a large codebase with new errors on day one. Months later, when someone finally flipped it on, the compiler flagged a line that had been shipping for two years: const amount = transactions[0].amount;, written on the assumption that a merchant's settlement window always contained at least one transaction. It usually did — until a quiet merchant had a day with zero transactions. transactions[0] was undefined, .amount on it was also undefined, and undefined * exchangeRate silently evaluated to NaN, which got written straight into that day's reconciliation report with no exception ever thrown. noUncheckedIndexedAccess retypes transactions[0] as Transaction | undefined, forcing every call site to prove the array isn't empty before touching .amount — precisely the check that had been missing for two years.

---

Path Aliases

Avoid ../../../repositories/users.repository with path aliases:

// tsconfig.json
{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@/*": ["src/*"],
      "@types/*": ["src/types/*"],
      "@services/*": ["src/services/*"],
      "@repositories/*": ["src/repositories/*"]
    }
  }
}

// Before
import * as usersRepo from '../../../repositories/users.repository.js';
 
// After
import * as usersRepo from '@repositories/users.repository.js';

tsconfig-paths/register is the common answer for resolving these — but it only patches Node's CommonJS Module._resolveFilename, and this project's tsconfig.json is set to NodeNext/--esm, which uses Node's native ESM resolver instead. Under native ESM, tsconfig-paths/register silently does nothing and path aliases won't resolve. For a NodeNext project like this one, resolve aliases at build time instead:

npm install -D tsc-alias

// package.json
{
  "scripts": {
    "build": "tsc && tsc-alias"
  }
}

tsc-alias runs after tsc and rewrites the @repositories/...-style imports in the compiled .js output back into real relative paths, which Node's ESM resolver can then load without any extra loader flags. (If you're on a CommonJS project instead of NodeNext, tsconfig-paths/register is the right tool — just not here.)

---

Summary

• "strict": true is non-negotiable. It enables the checks that make TypeScript worth using.
• module: "NodeNext" with moduleResolution: "NodeNext" for correct ESM + CJS interop in Node.js.
• Type your domain models in src/types/models.ts and import them everywhere — single source of truth.
• Augment Express.Request in src/types/express.d.ts to type req.user, req.requestId, and any other middleware-added properties.
• Use interface for object shapes, type for unions and computed types. Both are fine — consistency matters more than which you pick.
• Utility types (Omit, Pick, Partial, Readonly, ReturnType) reduce duplication and keep types in sync with their source.
• Migrate incrementally — allowJs: true lets TypeScript and JavaScript coexist. Convert file by file starting with the types and data access layers.

Next: input validation and error handling — replacing manual if (!name) checks with Zod schemas and building the error pipeline that makes every handler clean.

---