typescript-strict

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
typ

---

*Content truncated.*