Module P-3·23 min read

tsconfig.json, typing Express handlers and middleware, interfaces vs types, generics, ts-node for dev, tsc for prod — and migrating a JavaScript project incrementally.

JJS

Written by Jatin Jain Saraf · Senior Software Engineer

Module P-3 — TypeScript in Node.js

Q: When migrating a Node.js project to TypeScript, which compiler option allows TypeScript and JavaScript files to coexist without strictly type-checking the JS files?

`"allowJs": true` — Setting `"allowJs": true` enables the TypeScript compiler to process `.js` files alongside `.ts` files without throwing errors for missing types. This is the foundation of incrementally migrating a project to TypeScript.

Q: What is the primary practical difference between `interface` and `type` in TypeScript?

`interface` can be extended and merged (declaration merging), while `type` is more flexible and can represent unions and intersections. — Interfaces are specifically designed for object shapes and can automatically merge if declared multiple times (useful for augmenting Express `Request`). Types are more versatile and are required when defining unions (e.g., `string | number`) or complex mapped types.

Q: Which TypeScript utility type would you use to create a new type representing a User model without the `passwordHash` field?

`Omit ` — `Omit` constructs a type by picking all properties from a type and then removing the specified keys. `Pick` does the exact opposite, and `Exclude` is used for removing members from union types, not object properties.

What this module covers: TypeScript catches an entire class of bugs at compile time that JavaScript silently ships to production. This module covers setting up TypeScript for a Node.js API, the tsconfig.json settings that actually matter, typing Express handlers and middleware correctly, the type utilities you will use daily, and how to migrate an existing JavaScript project incrementally without stopping all other work.

Why TypeScript on the Backend

TypeScript's value is not just "autocomplete". It is a documentation system that the compiler enforces. Consider:

javascript

// JavaScript — what does this function expect?
async function createOrder({ userId, items, couponCode }) {
  // ...
}

// TypeScript — the contract is explicit and verified
interface CreateOrderInput {
  userId: number;
  items: Array<{ productId: number; quantity: number }>;
  couponCode?: string; // optional — the ? makes it clear
}

async function createOrder(input: CreateOrderInput): Promise<Order> {
  // ...
}

The TypeScript version:

Documents what the function accepts — no need to read the implementation
Errors at compile time if you pass userId as a string
Errors at the call site if you forget items
Autocompletes input. to show all available fields

At scale — hundreds of functions, dozens of developers, months of development — this prevents entire categories of bugs: wrong property names, missing required fields, null dereferences, wrong return type assumptions.

Installation and Setup

bash

npm install -D typescript ts-node @types/node
npx tsc --init  # generates tsconfig.json

Install type definitions for your libraries:

bash

npm install -D @types/express @types/bcrypt @types/jsonwebtoken
# Prisma generates its own types — no @types needed

tsconfig.json: The Settings That Matter

json

{
  "compilerOptions": {
    // ── Output ─────────────────────────────────────────────
    "target": "ES2022",          // JavaScript version to output
    "module": "NodeNext",        // Use Node's native ESM resolution
    "moduleResolution": "NodeNext",
    "outDir": "./dist",          // compiled JS goes here
    "rootDir": "./src",          // TypeScript source lives here

    // ── Type Safety ────────────────────────────────────────
    "strict": true,              // enables all strict checks — always use this
    "noUncheckedIndexedAccess": true,  // arr[0] is T | undefined, not T
    "noImplicitReturns": true,   // all code paths must return a value
    "noFallthroughCasesInSwitch": true,

    // ── Interop ────────────────────────────────────────────
    "esModuleInterop": true,     // allows: import express from 'express'
    "allowSyntheticDefaultImports": true,
    "resolveJsonModule": true,   // import config from './config.json'

    // ── Dev Experience ─────────────────────────────────────
    "sourceMap": true,           // source maps for debugger and stack traces
    "declaration": true,         // generate .d.ts files (needed for libraries)
    "skipLibCheck": true         // skip type checking node_modules (faster builds)
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules", "dist"]
}

The single most important setting is "strict": true. It enables:

strictNullChecks — null and undefined are not assignable to other types
noImplicitAny — variables must have explicit types when they can't be inferred
strictFunctionTypes — function parameter types are checked contravariantly
Several others

Without strict, TypeScript is considerably less useful. Always start with it on.

TypeScript Project Structure

text

blog-api/
├── src/
│   ├── types/              # shared interfaces and types
│   │   ├── express.d.ts    # augment Express Request type
│   │   └── models.ts       # domain model types
│   ├── routes/
│   ├── controllers/
│   ├── services/
│   ├── repositories/
│   └── index.ts
├── dist/                   # compiled output (git-ignored)
├── tsconfig.json
└── package.json

Update package.json scripts:

json

{
  "scripts": {
    "build": "tsc",
    "start": "node dist/index.js",
    "dev": "ts-node --esm src/index.ts",
    "typecheck": "tsc --noEmit"
  }
}

tsc --noEmit type-checks without producing output — fast, use in CI.

A note on dev: ts-node --esm works, but tsx has become the de facto standard for running TypeScript directly, largely displacing ts-node in new projects — it's esbuild-based (much faster), and handles ESM/CJS interop without a --esm flag or loader configuration. Many teams now write "dev": "tsx watch src/index.ts" instead. This course keeps ts-node --esm in the sample scripts since it's the reference implementation, but reach for tsx if you want less configuration.

Typing Your Domain Models

Define your core types once and import them everywhere:

typescript

// src/types/models.ts

export interface User {
  id: number;
  name: string;
  email: string;
  passwordHash: string;
  role: 'user' | 'admin' | 'moderator';
  status: 'active' | 'banned';
  createdAt: Date;
}

// The shape returned to clients — never expose passwordHash
export type PublicUser = Omit<User, 'passwordHash'>;

export interface Post {
  id: number;
  title: string;
  content: string;
  published: boolean;
  authorId: number;
  author?: PublicUser;
  createdAt: Date;
  updatedAt: Date;
}

export interface Order {
  id: number;
  userId: number;
  total: number;
  status: 'pending' | 'confirmed' | 'shipped' | 'delivered' | 'cancelled';
  items: OrderItem[];
  createdAt: Date;
}

export interface OrderItem {
  id: number;
  orderId: number;
  productId: number;
  quantity: number;
  price: number;
}

Typing Express Handlers

Express's built-in types are usable but loose. Here is the correct pattern:

typescript

import { Request, Response, NextFunction, RequestHandler } from 'express';
import { PublicUser } from '../types/models.js';

// Typed route handler — explicit req body, params, query, response body
type CreateUserBody = { name: string; email: string; password: string };
type CreateUserResponse = PublicUser;

export const createUser: RequestHandler<
  {},                   // req.params shape
  CreateUserResponse,   // res.json() shape
  CreateUserBody,       // req.body shape
  {}                    // req.query shape
> = async (req, res, next) => {
  try {
    const { name, email, password } = req.body; // fully typed
    const user = await usersService.create({ name, email, password });
    res.status(201).json(user);
  } catch (err) {
    next(err);
  }
};

// Simpler — type just what you need
export const getUserById = async (
  req: Request<{ id: string }>,
  res: Response<PublicUser | { error: string }>,
  next: NextFunction,
) => {
  try {
    const user = await usersService.findById(parseInt(req.params.id));
    if (!user) return res.status(404).json({ error: 'Not found' });
    res.json(user);
  } catch (err) {
    next(err);
  }
};

Augmenting the Express Request Type

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

typescript

// 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:

typescript

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:

typescript

// 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:

typescript

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:

typescript

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

typescript

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:

typescript

// 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:

typescript

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:

typescript

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:

typescript

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

typescript

// 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 },
  });
}

typescript

// 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

json

// 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:

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

Step 3: Tighten the config progressively

json

// 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:

typescript

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:

json

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

typescript

// 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:

bash

npm install -D tsc-alias

json

// 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.

Knowledge Check

When migrating a Node.js project to TypeScript, which compiler option allows TypeScript and JavaScript files to coexist without strictly type-checking the JS files?

What is the primary practical difference between interface and type in TypeScript?

Which TypeScript utility type would you use to create a new type representing a User model without the passwordHash field?

Test your knowledge with more question sets

Sign in to keep reading

The rest of this module is free — sign in with Google to unlock it and track your progress.

PreviousModule P-2: Authentication and Authorization Next Module P-4: Input Validation, Error Handling, and Middleware Pipelines

Discussion

Join the discussion

Loading comments...