TypeScript Strict Mode

Core Rules

1. No any - ever. Use unknown if type is truly unknown
2. No type assertions (as Type) without justification
3. Prefer type over interface for data structures
4. Reserve interface for behavior contracts only

Schema Organization

Organize Schemas by Usage

Common patterns: - Centralized: src/schemas/ for shared schemas - Co-located: Near the modules that use them - Layered: Separate by architectural layer (if using layered/hexagonal architecture)

Key principle: Avoid duplicating the same validation logic across multiple files.

Gotcha: Schema Duplication

Common anti-pattern:

Defining the same schema in multiple places: - Validation logic duplicated across endpoints - Same business rules defined in multiple adapters - Type definitions not shared

Why This Is Wrong: - ❌ Duplication creates multiple sources of truth - ❌ Changes require updating multiple files - ❌ Breaks DRY principle at the knowledge level - ❌ Domain logic leaks into infrastructure code

Solution:

// ✅ CORRECT - Define schema once, import everywhere
// src/schemas/user-requests.ts
import { z } from 'zod';

export const CreateUserRequestSchema = z.object({
  email: z.string().email(),
  name: z.string().min(1),
});

export type CreateUserRequest = z.infer<typeof CreateUserRequestSchema>;

// Use in multiple places
import { CreateUserRequestSchema } from '../schemas/user-requests.js';

// Express endpoint
app.post('/users', (req, res) => {
  const result = CreateUserRequestSchema.safeParse(req.body);
  if (!result.success) {
    return res.status(400).json({ error: result.error });
  }
  // Use result.data (validated)
});

// GraphQL resolver
const createUser = (input: unknown) => {
  const validated = CreateUserRequestSchema.parse(input);
  return userService.create(validated);
};

Key Benefits: - ✅ Single source of truth for validation - ✅ Schema changes propagate everywhere automatically - ✅ Type safety maintained across codebase - ✅ DRY principle at knowledge level

Remember: If validation logic is duplicated, extract it into a shared schema.

Dependency Injection Pattern

Inject Dependencies, Don't Create Them

The Rule: - Dependencies are always injected via parameters - Never use new to create dependencies inside functions - Factory functions accept dependencies as parameters

Why This Matters

Without dependency injection: - ❌ Only one implementation possible - ❌ Can't test with mocks (poor testability) - ❌ Tight coupling to specific implementations - ❌ Violates dependency inversion principle - ❌ Can't swap implementations

With dependency injection: - ✅ Any implementation works (in-memory, database, remote API) - ✅ Fully testable (inject mocks for testing) - ✅ Loose coupling - ✅ Follows dependency inversion principle - ✅ Runtime flexibility (configure implementation)

Example: Order Processor

❌ WRONG - Creating implementation internally

export const createOrderProcessor = ({
  paymentGateway,
}: {
  paymentGateway: PaymentGateway;
}): OrderProcessor => {
  // ❌ Hardcoded implementation!
  const orderRepository = new InMemoryOrderRepository();

  return {
    processOrder(order) {
      const payment = paymentGateway.charge(order.total);
      if (!payment.success) {
        return { success: false, error: payment.error };
      }

      orderRepository.save(order); // Using hardcoded repository
      return { success: true, data: order };
    },
  };
};

Why this is WRONG: - Only ONE repository implementation possible (in-memory) - Can't test with mock repository - Can't swap to database repository or remote API - Tight coupling to specific implementation

✅ CORRECT - Injecting all dependencies

export const createOrderProcessor = ({
  paymentGateway,  // ✅ Injected
  orderRepository, // ✅ Injected
}: {
  paymentGateway: PaymentGateway;
  orderRepository: OrderRepository;
}): OrderProcessor => {
  return {
    processOrder(order) {
      const payment = paymentGateway.charge(order.total);
      if (!payment.success) {
        return { success: false, error: payment.error };
      }

      orderRepository.save(order); // Delegate to injected dependency
      return { success: true, data: order };
    },
  };
};

Why this is CORRECT: - ✅ Any OrderRepository implementation works (in-memory, PostgreSQL, MongoDB) - ✅ Any PaymentGateway implementation works (Stripe, mock, testing) - ✅ Easy to test (inject mocks) - ✅ Loose coupling (depends on interfaces, not implementations) - ✅ Runtime flexibility (choose implementation at startup)

Type vs Interface - Understanding WHY

The choice between type and interface is architectural, not stylistic.

Behavior Contracts → Use interface

When to use: Interfaces define contracts that must be implemented.

Examples: UserRepository, PaymentGateway, EmailService, CacheProvider

Why interface for behavior contracts?

1. Signals implementation contracts clearly - Interface communicates "this must be implemented elsewhere" - Type communicates "this is a data structure"

2. Better TypeScript errors when implementing - class X implements UserRepository gives clear errors - Types don't have implements keyword

3. Conventional for dependency injection - Standard pattern for dependency inversion - Clear separation between contract and implementation

4. Class-friendly for implementations - Many libraries use classes for services - Classes naturally implement interfaces

Example:

// Behavior contract
export interface UserRepository {
  findById(id: string): Promise<User | undefined>;
  save(user: User): Promise<void>;
  delete(id: string): Promise<void>;
}

// Concrete implementation
export class PostgresUserRepository implements UserRepository {
  async findById(id: string): Promise<User | undefined> {
    // Implementation
  }
  // ... other methods
}

Data Structures → Use type

When to use: Types define immutable data structures.

Examples: User, Order, Config, ApiResponse

Why type for data?

1. Emphasizes immutability - Types with readonly signal "don't mutate this" - Functional programming alignment

2. Better for unions, intersections, mapped types - type Result<T, E> = Success<T> | Failure<E> - type Partial<T> = { [P in keyof T]?: T[P] }

3. Prevents accidental mutations - readonly properties enforce immutability at type level - Compiler catches mutation attempts

4. More flexible composition - Easier to compose with utility types - Better inference in complex scenarios

Example:

// Data structure
export type User = {
  readonly id: string;
  readonly email: string;
  readonly name: string;
  readonly roles: ReadonlyArray<string>;
};

export type Order = {
  readonly id: string;
  readonly userId: string;
  readonly items: ReadonlyArray<OrderItem>;
  readonly total: number;
};

Architectural Pattern

This pattern supports clean architecture:

• Behavior contracts (interface) = Boundaries between layers
• Data structures (type) = Data flowing through the system
• Business logic depends on interfaces, not implementations
• Data is immutable (types with readonly)

Strict Mode Configuration

tsconfig.json Settings

{
  "compilerOptions": {
    "strict": true,
    "noImplicitAny": true,
    "strictNullChecks": true,
    "noUnusedLocals": true,
    "noUnusedParameters": true,
    "noImplicitReturns": true,
    "noFallthroughCasesInSwitch": true,
    "noUncheckedIndexedAccess": true,
    "exactOptionalPropertyTypes": true,
    "noPropertyAccessFromIndexSignature": true,
    "forceConsistentCasingInFileNames": true,
    "allowUnusedLabels": false
  }
}

What Each Setting Does

Core strict flags: - strict: true - Enables all strict type checking options - noImplicitAny - Error on expressions/declarations with implied any type - strictNullChecks - null and undefined have their own types (not assignable to everything) - noUnusedLocals - Error on unused local variables - noUnusedParameters - Error on unused function parameters - noImplicitReturns - Error when not all code paths return a value - noFallthroughCasesInSwitch - Error on fallthrough cases in switch statements

Additional safety flags (CRITICAL): - noUncheckedIndexedAccess - Array/object access returns T | undefined (prevents runtime errors from assuming elements exist) - exactOptionalPropertyTypes - Distinguishes property?: T from property: T | undefined (more precise types) - noPropertyAccessFromIndexSignature - Requires bracket notation for index signature properties (forces awareness of dynamic access) - forceConsistentCasingInFileNames - Prevents case sensitivity issues across operating systems - allowUnusedLabels - Error on unused labels (catches accidental labels that do nothing)

Additional Rules

• No @ts-ignore without explicit comments explaining why
• These rules apply to test code as well as production code

Architectural Insight: noUnusedParameters Catches Design Issues

The noUnusedParameters rule can reveal architectural problems:

Example: A function with an unused parameter often indicates the parameter belongs in a different layer. Strict mode catches these design issues early.

Immutability Patterns

Use readonly on All Data Structures

// ✅ CORRECT - Immutable data structure
type ApiRequest = {
  readonly method: 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH';
  readonly url: string;
  readonly headers?: {
    readonly [key: string]: string;
  };
  readonly body?: unknown;
};

// ❌ WRONG - Mutable data structure
type ApiRequest = {
  method: 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH';
  url: string;
  headers?: {
    [key: string]: string;
  };
  body?: unknown;
};

ReadonlyArray vs Array

// ✅ CORRECT - Immutable array
type ShoppingCart = {
  readonly id: string;
  readonly items: ReadonlyArray<CartItem>;
};

// ❌ WRONG - Mutable array
type ShoppingCart = {
  readonly id: string;
  readonly items: CartItem[];
};

Result Type Pattern for Error Handling

Prefer Result<T, E> types over exceptions for expected errors:

export type Result<T, E = Error> =
  | { readonly success: true; readonly data: T }
  | { readonly success: false; readonly error: E };

// Usage
export const findUser = (
  userId: string,
): Result<User> => {
  const user = database.findById(userId);
  if (!user) {
    return { success: false, error: new Error('User not found') };
  }

  return { success: true, data: user };
};

Why result types? - Explicit error handling (type system enforces checking) - No hidden control flow (unlike exceptions) - Functional programming alignment - Easier to test (no try/catch needed)

Factory Pattern for Object Creation

Use Factory Functions (Not Classes)

// ✅ CORRECT - Factory function
export const createOrderService = (
  orderRepository: OrderRepository,
  paymentGateway: PaymentGateway,
): OrderService => {
  return {
    async createOrder(order) {
      const validation = validateOrder(order);
      if (!validation.success) {
        return validation;
      }
      await orderRepository.save(order);
      return { success: true, data: order };
    },
    async processPayment(orderId, paymentInfo) {
      const order = await orderRepository.findById(orderId);
      if (!order) {
        return { success: false, error: new Error('Order not found') };
      }
      return paymentGateway.charge(order.total, paymentInfo);
    },
  };
};

// ❌ WRONG - Class-based creation
export class OrderService {
  constructor(
    private orderRepository: OrderRepository,
    private paymentGateway: PaymentGateway,
  ) {}

  async createOrder(order: Order) {
    // Implementation with `this`
  }
}

Why factory functions? - Functional programming alignment - No this context issues - Easier to compose - Natural dependency injection - Simpler testing (no new keyword)

Location Guidance

Suggested File Organization

These are common patterns, not strict rules. Adapt to your project's needs.

Interfaces (Behavior Contracts) - Common locations: src/interfaces/, src/contracts/, src/ports/ - Examples: UserRepository, PaymentGateway, EmailService - Why: Behavior contracts that define boundaries between layers

Types (Data Structures) - Common locations: src/types/, src/models/, co-located with features - Examples: User, Order, Config - Why: Immutable data structures used throughout the system

Schemas (Validation) - Common locations: src/schemas/, src/validation/, co-located with features - Examples: UserSchema, OrderSchema, ConfigSchema - Why: Validation rules (consider avoiding duplication)

Business Logic - Common locations: src/services/, src/domain/, src/use-cases/ - Examples: createUserService, processOrder, validatePayment - Why: Core business logic (prefer framework-agnostic when possible)

Implementation Details - Common locations: src/adapters/, src/infrastructure/, src/repositories/ - Examples: PostgresUserRepository, StripePaymentGateway, RedisCache - Why: Framework-specific code, external integrations

Note: These are suggestions based on common patterns. Your project may use different conventions. The key principles are: - Clear separation of concerns - Minimal duplication of validation logic - Dependencies point inward (toward business logic)

Schema-First at Trust Boundaries

When Schemas ARE Required

• Data crosses trust boundary (external → internal)
• Type has validation rules (format, constraints)
• Shared data contract between systems
• Used in test factories (validate test data completeness)

// API responses, user input, external data
const UserSchema = z.object({
  id: z.string().uuid(),
  email: z.string().email(),
});
type User = z.infer<typeof UserSchema>;

// Validate at boundary
const user = UserSchema.parse(apiResponse);

When Schemas AREN'T Required

• Pure internal types (utilities, state)
• Result/Option types (no validation needed)
• TypeScript utility types (Partial<T>, Pick<T>, etc.)
• Behavior contracts (interfaces - structural, not validated)
• Component props (unless from URL/API)

// ✅ CORRECT - No schema needed
type Result<T, E> =
  | { success: true; data: T }
  | { success: false; error: E };

// ✅ CORRECT - Interface, no validation
interface UserService {
  createUser(user: User): void;
}

Functional Programming Principles

These principles support immutability and type safety:

Pure Functions

• No side effects (don't mutate external state)
• Deterministic (same input → same output)
• Easier to reason about, test, and compose

// ✅ CORRECT - Pure function
const addItem = (
  items: ReadonlyArray<Item>,
  newItem: Item,
): ReadonlyArray<Item> => {
  return [...items, newItem]; // Returns new array
};

// ❌ WRONG - Impure function (mutates)
const addItem = (items: Item[], newItem: Item): void => {
  items.push(newItem); // Mutates input!
};

No Data Mutation

• Use spread operators for immutable updates
• Return new objects/arrays instead of modifying
• Let TypeScript's readonly enforce this

// ✅ CORRECT - Immutable update
const updateUser = (
  user: User,
  updates: Partial<User>,
): User => {
  return { ...user, ...updates }; // New object
};

// ❌ WRONG - Mutation
const updateUser = (user: User, updates: Partial<User>): void => {
  Object.assign(user, updates); // Mutates!
};

Composition Over Complex Logic

• Compose small functions into larger ones
• Each function does one thing well
• Easier to understand, test, and reuse

// ✅ CORRECT - Composed functions
const validate = (input: unknown) => UserSchema.parse(input);
const saveToDatabase = (user: User) => database.save(user);
const createUser = (input: unknown) => saveToDatabase(validate(input));

// ❌ WRONG - Complex monolithic function
const createUser = (input: unknown) => {
  if (typeof input !== 'object' || !input) throw new Error('Invalid');
  if (!('email' in input)) throw new Error('Missing email');
  // ... 50 more lines of validation and registration
};

Use Array Methods Over Loops

• Prefer map, filter, reduce for transformations
• Declarative (what, not how)
• Natural immutability (return new arrays)

// ✅ CORRECT - Functional array methods
const activeUsers = users.filter(u => u.active);
const userEmails = users.map(u => u.email);

// ❌ WRONG - Imperative loops
const activeUsers = [];
for (const u of users) {
  if (u.active) {
    activeUsers.push(u);
  }
}

Branded Types

For type-safe primitives:

type UserId = string & { readonly brand: unique symbol };
type PaymentAmount = number & { readonly brand: unique symbol };

// Type-safe at compile time
const processPayment = (userId: UserId, amount: PaymentAmount) => {
  // Implementation
};

// ❌ Can't pass raw string/number
processPayment('user-123', 100); // Error

// ✅ Must use branded type
const userId = 'user-123' as UserId;
const amount = 100 as PaymentAmount;
processPayment(userId, amount); // OK

Summary Checklist

When writing TypeScript code, verify:

• [ ] No any types - using unknown where type is truly unknown
• [ ] No type assertions without justification
• [ ] Using type for data structures with readonly
• [ ] Using interface for behavior contracts (ports)
• [ ] Schemas defined in core, not duplicated in adapters
• [ ] Ports injected via parameters, never created internally
• [ ] Factory functions for object creation (not classes)
• [ ] readonly on all data structure properties
• [ ] Pure functions wherever possible (no mutations)
• [ ] Result types for expected errors (not exceptions)
• [ ] Strict mode enabled with all checks passing
• [ ] Artifacts in correct locations (ports/, types/, schemas/, domain/)