
Building financial systems at Pangea requires type safety that goes beyond basic TypeScript. We've developed advanced type patterns that prevent entire classes of bugs and make our codebase more maintainable. Here are the patterns that have proven most valuable.

#### Discriminated Unions for Payment States

```typescript
type PaymentState =
  | { status: 'pending'; initiatedAt: Date }
  | { status: 'processing'; processorId: string; startedAt: Date }
  | { status: 'completed'; completedAt: Date; transactionId: string }
  | { status: 'failed'; failedAt: Date; errorCode: string; errorMessage: string }
  | { status: 'refunded'; refundedAt: Date; refundId: string; originalTransactionId: string };

function handlePaymentState(state: PaymentState): void {
  switch (state.status) {
    case 'pending':
      // TypeScript knows state.initiatedAt exists
      console.log(`Initiated at ${state.initiatedAt}`);
      break;
    case 'processing':
      // TypeScript knows state.processorId exists
      console.log(`Processing with ${state.processorId}`);
      break;
    case 'completed':
      // TypeScript knows state.transactionId exists
      console.log(`Completed: ${state.transactionId}`);
      break;
    case 'failed':
      // TypeScript knows error details exist
      console.error(`Failed: ${state.errorCode} - ${state.errorMessage}`);
      break;
    case 'refunded':
      // TypeScript knows refund details exist
      console.log(`Refunded: ${state.refundId}`);
      break;
  }
}
```

#### Branded Types for Financial Values

```typescript
// Prevent mixing different types of money
type Money = number & { readonly __brand: 'Money' };
type USD = Money & { readonly __currency: 'USD' };
type EUR = Money & { readonly __currency: 'EUR' };

function createUSD(amount: number): USD {
  return amount as USD;
}

function createEUR(amount: number): EUR {
  return amount as EUR;
}

// This will cause a compile error:
// const usd: USD = createEUR(100); // Error!

// Type-safe currency conversion
function convertCurrency(amount: USD, rate: number): EUR {
  return (amount * rate) as EUR;
}
```

#### Const Assertions and Template Literal Types

```typescript
const CURRENCY_CODES = ['USD', 'EUR', 'GBP', 'JPY'] as const;
type CurrencyCode = typeof CURRENCY_CODES[number]; // 'USD' | 'EUR' | 'GBP' | 'JPY'

type PaymentEvent = 
  | `payment.${CurrencyCode}.created`
  | `payment.${CurrencyCode}.completed`
  | `payment.${CurrencyCode}.failed`;

// Type-safe event handling
function handlePaymentEvent(event: PaymentEvent): void {
  if (event.startsWith('payment.USD.')) {
    // Handle USD payment events
  }
}
```

#### Mapped Types for API Contracts

```typescript
type ApiResponse<T> = {
  data: T;
  status: 'success' | 'error';
  timestamp: Date;
  requestId: string;
};

type ApiError = {
  code: string;
  message: string;
  details?: Record<string, unknown>;
};

type PaymentApiResponse = ApiResponse<Payment> | ApiResponse<ApiError>;

// Type guard
function isSuccessResponse<T>(
  response: ApiResponse<T | ApiError>
): response is ApiResponse<T> {
  return response.status === 'success' && !('code' in response.data);
}
```

#### Conditional Types for Flexible APIs

```typescript
type ApiMethod = 'GET' | 'POST' | 'PUT' | 'DELETE';

type ApiRequest<T extends ApiMethod> = 
  T extends 'GET' 
    ? { method: T; params: Record<string, string> }
    : { method: T; body: unknown; params?: Record<string, string> };

function makeRequest<T extends ApiMethod>(
  request: ApiRequest<T>
): Promise<unknown> {
  // Implementation
}

// Usage - TypeScript enforces correct structure
makeRequest({ method: 'GET', params: { id: '123' } });
makeRequest({ method: 'POST', body: { amount: 100 }, params: { id: '123' } });
```

#### Utility Types for Transformations

```typescript
// Make all properties optional except required ones
type PartialExcept<T, K extends keyof T> = Partial<T> & Pick<T, K>;

interface Payment {
  id: string;
  amount: number;
  currency: string;
  userId: string;
  status: string;
}

// Update payment - only id required, rest optional
type PaymentUpdate = PartialExcept<Payment, 'id'>;

function updatePayment(id: string, updates: PaymentUpdate): void {
  // Implementation
}
```

#### Recursive Types for Complex Structures

```typescript
type JsonValue = 
  | string
  | number
  | boolean
  | null
  | JsonObject
  | JsonArray;

interface JsonObject {
  [key: string]: JsonValue;
}

interface JsonArray extends Array<JsonValue> {}

// Type-safe JSON parsing
function parseJson<T extends JsonValue>(json: string): T {
  return JSON.parse(json) as T;
}
```

#### Type-Level Programming

```typescript
// Extract return type of async function
type Awaited<T> = T extends Promise<infer U> ? U : T;

async function fetchPayment(id: string): Promise<Payment> {
  // Implementation
}

type PaymentResult = Awaited<ReturnType<typeof fetchPayment>>; // Payment

// Extract function parameters
type PaymentParams = Parameters<typeof updatePayment>; // [string, PaymentUpdate]
```

> "Advanced TypeScript types catch bugs at compile time that would otherwise cause runtime errors in production. In financial systems, this is invaluable."

#### Best Practices

1. Use discriminated unions for state machines
2. Brand types to prevent mixing incompatible values
3. Leverage template literal types for type-safe strings
4. Use conditional types for flexible APIs
5. Create utility types for common transformations
6. Document complex types with JSDoc
7. Test type definitions, not just implementations



Advanced TypeScript type patterns for financial systems


At Pangea, we built an event-driven architecture for our FX trading platform. TypeScript's type system enabled us to create type-safe event handlers that catch errors at compile time. Here's how we structured it.

#### Event Type Definitions

```typescript
// Base event structure
interface BaseEvent {
  eventId: string;
  timestamp: Date;
  version: string;
}

// Specific event types
interface PaymentCreatedEvent extends BaseEvent {
  type: 'payment.created';
  payload: {
    paymentId: string;
    amount: Decimal;
    currency: CurrencyCode;
    userId: string;
  };
}

interface PaymentFailedEvent extends BaseEvent {
  type: 'payment.failed';
  payload: {
    paymentId: string;
    reason: string;
    errorCode: string;
  };
}

interface FXRateUpdatedEvent extends BaseEvent {
  type: 'fx.rate.updated';
  payload: {
    pair: CurrencyPair;
    rate: Decimal;
    source: 'market' | 'manual';
  };
}

// Union type for all events
type PaymentEvent = PaymentCreatedEvent | PaymentFailedEvent;
type FXEvent = FXRateUpdatedEvent;
type SystemEvent = PaymentEvent | FXEvent;
```

#### Type-Safe Event Handlers

```typescript
type EventHandler<T extends SystemEvent> = (event: T) => Promise<void>;

class EventDispatcher {
  private handlers: Map<string, EventHandler<any>[]> = new Map();
  
  on<T extends SystemEvent>(
    eventType: T['type'],
    handler: EventHandler<T>
  ): void {
    if (!this.handlers.has(eventType)) {
      this.handlers.set(eventType, []);
    }
    this.handlers.get(eventType)!.push(handler);
  }
  
  async emit<T extends SystemEvent>(event: T): Promise<void> {
    const handlers = this.handlers.get(event.type) || [];
    await Promise.all(handlers.map(handler => handler(event)));
  }
}

// Usage - fully type-safe
const dispatcher = new EventDispatcher();

dispatcher.on('payment.created', async (event) => {
  // TypeScript knows event.payload has paymentId, amount, currency, userId
  console.log(`Payment ${event.payload.paymentId} created`);
});

dispatcher.on('payment.failed', async (event) => {
  // TypeScript knows event.payload has paymentId, reason, errorCode
  console.error(`Payment ${event.payload.paymentId} failed: ${event.payload.reason}`);
});
```

#### Event Schema Validation

```typescript
import { z } from 'zod';

const PaymentCreatedSchema = z.object({
  type: z.literal('payment.created'),
  eventId: z.string().uuid(),
  timestamp: z.date(),
  version: z.string(),
  payload: z.object({
    paymentId: z.string().uuid(),
    amount: z.string().regex(/^\d+\.\d{2}$/),
    currency: z.enum(['USD', 'EUR', 'GBP']),
    userId: z.string().uuid(),
  }),
});

type ValidatedPaymentCreatedEvent = z.infer<typeof PaymentCreatedSchema>;

function validateEvent(event: unknown): ValidatedPaymentCreatedEvent {
  return PaymentCreatedSchema.parse(event);
}
```

#### Pattern Matching with Exhaustiveness Checking

```typescript
function processEvent(event: SystemEvent): void {
  switch (event.type) {
    case 'payment.created':
      handlePaymentCreated(event); // TypeScript narrows type
      break;
    case 'payment.failed':
      handlePaymentFailed(event); // TypeScript narrows type
      break;
    case 'fx.rate.updated':
      handleRateUpdate(event); // TypeScript narrows type
      break;
    default:
      // Exhaustiveness check - TypeScript error if we miss a case
      const _exhaustive: never = event;
      throw new Error(`Unknown event type: ${_exhaustive}`);
  }
}
```

> "Type-safe event handling prevents entire classes of bugs in distributed systems."

#### Advanced Patterns

**Event Versioning:**
```typescript
type EventV1 = { version: '1'; data: OldFormat };
type EventV2 = { version: '2'; data: NewFormat };
type VersionedEvent = EventV1 | EventV2;

function handleVersionedEvent(event: VersionedEvent): void {
  if (event.version === '1') {
    // Handle v1 format
  } else {
    // Handle v2 format
  }
}
```

**Event Transformation:**
```typescript
type EventTransformer<T extends SystemEvent, U extends SystemEvent> = (
  event: T
) => U;

function transformPaymentEvent(
  event: PaymentCreatedEvent
): PaymentCreatedEvent {
  return {
    ...event,
    payload: {
      ...event.payload,
      amount: event.payload.amount.mul(100), // Convert to cents
    },
  };
}
```



Type-safe event handling with TypeScript


At Pangea, we built REST APIs that are fully type-safe from client to server. This prevents entire classes of bugs and makes refactoring safer. Here's how we achieved end-to-end type safety.

#### Shared Type Definitions

```typescript
// shared/types.ts
export interface CreatePaymentRequest {
  amount: Decimal;
  currency: CurrencyCode;
  recipientId: string;
  description: string;
  metadata?: Record<string, unknown>;
}

export interface PaymentResponse {
  id: string;
  amount: Decimal;
  currency: CurrencyCode;
  status: PaymentStatus;
  createdAt: Date;
  updatedAt: Date;
}

export interface ApiError {
  code: string;
  message: string;
  details?: Record<string, unknown>;
}
```

#### Type-Safe API Client

```typescript
// client/api.ts
class ApiClient {
  async createPayment(
    request: CreatePaymentRequest
  ): Promise<PaymentResponse> {
    const response = await fetch('/api/payments', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify(request),
    });
    
    if (!response.ok) {
      const error: ApiError = await response.json();
      throw new ApiError(error.code, error.message, error.details);
    }
    
    return response.json() as Promise<PaymentResponse>;
  }
  
  async getPayment(id: string): Promise<PaymentResponse> {
    const response = await fetch(`/api/payments/${id}`);
    
    if (!response.ok) {
      const error: ApiError = await response.json();
      throw new ApiError(error.code, error.message, error.details);
    }
    
    return response.json() as Promise<PaymentResponse>;
  }
}
```

#### Type-Safe Server Handlers

```typescript
// server/handlers.ts
import type { CreatePaymentRequest, PaymentResponse } from '@shared/types';

class PaymentHandler {
  async createPayment(
    request: CreatePaymentRequest
  ): Promise<PaymentResponse> {
    // TypeScript ensures request matches CreatePaymentRequest
    const payment = await this.paymentService.create({
      amount: request.amount,
      currency: request.currency,
      recipientId: request.recipientId,
      description: request.description,
      metadata: request.metadata,
    });
    
    return {
      id: payment.id,
      amount: payment.amount,
      currency: payment.currency,
      status: payment.status,
      createdAt: payment.createdAt,
      updatedAt: payment.updatedAt,
    };
  }
}
```

#### Runtime Validation with Zod

```typescript
import { z } from 'zod';

const CreatePaymentSchema = z.object({
  amount: z.string().regex(/^\d+\.\d{2}$/),
  currency: z.enum(['USD', 'EUR', 'GBP']),
  recipientId: z.string().uuid(),
  description: z.string().min(1).max(500),
  metadata: z.record(z.unknown()).optional(),
});

// Infer TypeScript type from Zod schema
type ValidatedCreatePaymentRequest = z.infer<typeof CreatePaymentSchema>;

function validateRequest(
  body: unknown
): ValidatedCreatePaymentRequest {
  return CreatePaymentSchema.parse(body);
}
```

#### Type-Safe Route Handlers

```typescript
// Using Next.js API routes
import type { NextApiRequest, NextApiResponse } from 'next';
import type { CreatePaymentRequest, PaymentResponse, ApiError } from '@shared/types';

export default async function handler(
  req: NextApiRequest,
  res: NextApiResponse<PaymentResponse | ApiError>
) {
  if (req.method !== 'POST') {
    return res.status(405).json({
      code: 'METHOD_NOT_ALLOWED',
      message: 'Only POST method is allowed',
    });
  }
  
  try {
    const request = validateRequest(req.body);
    const payment = await paymentHandler.createPayment(request);
    return res.status(201).json(payment);
  } catch (error) {
    if (error instanceof z.ZodError) {
      return res.status(400).json({
        code: 'VALIDATION_ERROR',
        message: 'Invalid request body',
        details: error.errors,
      });
    }
    
    return res.status(500).json({
      code: 'INTERNAL_ERROR',
      message: 'An unexpected error occurred',
    });
  }
}
```

#### OpenAPI Type Generation

```typescript
// Generate types from OpenAPI spec
// openapi-typescript openapi.yaml --output types/api.ts

import type { paths } from './types/api';

type CreatePaymentPath = paths['/api/payments']['post'];
type CreatePaymentRequest = CreatePaymentPath['requestBody']['content']['application/json'];
type CreatePaymentResponse = CreatePaymentPath['responses']['201']['content']['application/json'];
```

> "Type-safe APIs catch integration bugs before they reach production. The investment in shared types pays dividends."

#### Benefits

- Compile-time error detection
- Automatic refactoring safety
- Better IDE autocomplete
- Self-documenting APIs
- Reduced integration bugs



Building type-safe APIs with TypeScript


At Pangea, we use TypeScript with Prisma to create type-safe database queries. This prevents SQL injection, ensures data consistency, and makes refactoring safer. Here's our approach.

#### Prisma Schema Definition

```prisma
model Payment {
  id        String   @id @default(uuid())
  amount    Decimal  @db.Decimal(10, 2)
  currency  String
  status    PaymentStatus
  userId    String
  createdAt DateTime @default(now())
  updatedAt DateTime @updatedAt
  
  user      User     @relation(fields: [userId], references: [id])
  
  @@index([userId])
  @@index([status, createdAt])
}

enum PaymentStatus {
  PENDING
  PROCESSING
  COMPLETED
  FAILED
  REFUNDED
}
```

#### Type-Safe Queries

```typescript
import { PrismaClient, Prisma } from '@prisma/client';

const prisma = new PrismaClient();

// Type-safe find
async function getPayment(id: string): Promise<Payment | null> {
  return prisma.payment.findUnique({
    where: { id },
    include: { user: true },
  });
}

// Type-safe create with validation
async function createPayment(
  data: Prisma.PaymentCreateInput
): Promise<Payment> {
  // TypeScript ensures all required fields are present
  return prisma.payment.create({
    data: {
      amount: data.amount,
      currency: data.currency,
      status: 'PENDING',
      user: {
        connect: { id: data.user.connect.id },
      },
    },
  });
}

// Type-safe updates
async function updatePaymentStatus(
  id: string,
  status: PaymentStatus
): Promise<Payment> {
  return prisma.payment.update({
    where: { id },
    data: { status },
  });
}
```

#### Complex Queries with Type Safety

```typescript
// Type-safe aggregations
async function getPaymentStats(
  userId: string,
  startDate: Date,
  endDate: Date
): Promise<{
  totalAmount: Decimal;
  count: number;
  byStatus: Record<PaymentStatus, number>;
}> {
  const payments = await prisma.payment.findMany({
    where: {
      userId,
      createdAt: {
        gte: startDate,
        lte: endDate,
      },
    },
  });
  
  const totalAmount = payments.reduce(
    (sum, p) => sum.plus(p.amount),
    new Decimal(0)
  );
  
  const byStatus = payments.reduce((acc, p) => {
    acc[p.status] = (acc[p.status] || 0) + 1;
    return acc;
  }, {} as Record<PaymentStatus, number>);
  
  return {
    totalAmount,
    count: payments.length,
    byStatus,
  };
}
```

#### Transaction Safety

```typescript
async function transferFunds(
  fromAccountId: string,
  toAccountId: string,
  amount: Decimal
): Promise<void> {
  await prisma.$transaction(async (tx) => {
    // Type-safe transaction context
    const fromAccount = await tx.account.findUnique({
      where: { id: fromAccountId },
    });
    
    if (!fromAccount || fromAccount.balance.lt(amount)) {
      throw new Error('Insufficient funds');
    }
    
    await tx.account.update({
      where: { id: fromAccountId },
      data: { balance: { decrement: amount } },
    });
    
    await tx.account.update({
      where: { id: toAccountId },
      data: { balance: { increment: amount } },
    });
    
    await tx.transaction.create({
      data: {
        fromAccountId,
        toAccountId,
        amount,
        type: 'TRANSFER',
      },
    });
  });
}
```

#### Type-Safe Raw Queries

```typescript
// Even raw queries can be type-safe
async function getPaymentTotalsByCurrency(): Promise<
  Array<{ currency: string; total: Decimal }>
> {
  const results = await prisma.$queryRaw<
    Array<{ currency: string; total: Decimal }>
  >`
    SELECT 
      currency,
      SUM(amount) as total
    FROM Payment
    WHERE status = 'COMPLETED'
    GROUP BY currency
  `;
  
  return results;
}
```

> "Type-safe database queries prevent entire classes of bugs and make refactoring safer."

#### Best Practices

1. Use Prisma for type-safe ORM
2. Define schemas carefully - they become your types
3. Use transactions for multi-step operations
4. Validate inputs before database operations
5. Use raw queries sparingly, but type them when needed
6. Index frequently queried fields
7. Use enums for constrained values



Type-safe database queries with TypeScript


Working with financial data requires precision. TypeScript's utility types help us create robust abstractions that prevent errors. Here are the patterns we use at Pangea.

#### Deep Partial and Required

```typescript
// Make nested properties optional
type DeepPartial<T> = {
  [P in keyof T]?: T[P] extends object ? DeepPartial<T[P]> : T[P];
};

// Make nested properties required
type DeepRequired<T> = {
  [P in keyof T]-?: T[P] extends object ? DeepRequired<T[P]> : T[P];
};

interface Payment {
  id: string;
  amount: Decimal;
  metadata?: {
    source?: string;
    reference?: string;
  };
}

type PartialPayment = DeepPartial<Payment>;
// All properties optional, including nested ones

type RequiredPayment = DeepRequired<Payment>;
// All properties required, including nested ones
```

#### Readonly Deep

```typescript
type DeepReadonly<T> = {
  readonly [P in keyof T]: T[P] extends object ? DeepReadonly<T[P]> : T[P];
};

const payment: DeepReadonly<Payment> = {
  id: '123',
  amount: new Decimal('100.00'),
  metadata: {
    source: 'api',
  },
};

// payment.metadata.source = 'web'; // Error: Cannot assign to readonly property
```

#### NonNullable for Financial Calculations

```typescript
type NonNullable<T> = T extends null | undefined ? never : T;

function calculateTotal(
  payments: Array<Payment | null | undefined>
): Decimal {
  return payments
    .filter((p): p is NonNullable<typeof p> => p != null)
    .reduce((sum, p) => sum.plus(p.amount), new Decimal(0));
}
```

#### Extract and Exclude for Filtering

```typescript
type PaymentStatus = 'pending' | 'processing' | 'completed' | 'failed';
type ActiveStatus = Exclude<PaymentStatus, 'failed'>; // 'pending' | 'processing' | 'completed'
type FinalStatus = Extract<PaymentStatus, 'completed' | 'failed'>; // 'completed' | 'failed'

function handleActivePayment(status: ActiveStatus): void {
  // TypeScript knows status cannot be 'failed'
}
```

#### Record Types for Mappings

```typescript
type CurrencyCode = 'USD' | 'EUR' | 'GBP';
type ExchangeRates = Record<CurrencyCode, Decimal>;

const rates: ExchangeRates = {
  USD: new Decimal('1.00'),
  EUR: new Decimal('0.85'),
  GBP: new Decimal('0.73'),
};

// TypeScript ensures all currencies are present
```

#### Pick and Omit for Transformations

```typescript
// Create public API response (omit internal fields)
type PublicPayment = Omit<Payment, 'internalId' | 'deletedAt'>;

// Create update payload (pick only updatable fields)
type PaymentUpdate = Pick<Payment, 'status' | 'metadata'>;
```

#### Conditional Types for Smart Defaults

```typescript
type DefaultValue<T> = T extends string
  ? string
  : T extends number
  ? number
  : T extends boolean
  ? boolean
  : never;

function getConfigValue<T>(
  key: string,
  defaultValue: DefaultValue<T>
): T {
  // Implementation
}

// Usage
const timeout = getConfigValue<number>('timeout', 5000); // Type-safe
```

> "Utility types make TypeScript code more maintainable and prevent entire classes of bugs."

#### Practical Applications

**Type-Safe Configuration:**
```typescript
type Config = {
  apiUrl: string;
  timeout: number;
  retries: number;
  features: {
    payments: boolean;
    fx: boolean;
  };
};

type PartialConfig = DeepPartial<Config>;

function mergeConfig(
  base: Config,
  overrides: PartialConfig
): Config {
  // Type-safe merge
}
```



Advanced TypeScript utility types for financial data


At Pangea, we use dependency injection with full type safety. This makes testing easier, improves maintainability, and prevents runtime errors. Here's our approach.

#### Service Interfaces

```typescript
interface IPaymentService {
  createPayment(request: CreatePaymentRequest): Promise<Payment>;
  getPayment(id: string): Promise<Payment | null>;
  updatePaymentStatus(id: string, status: PaymentStatus): Promise<Payment>;
}

interface IEmailService {
  sendEmail(to: string, subject: string, body: string): Promise<void>;
}

interface IAuditService {
  logEvent(event: AuditEvent): Promise<void>;
}
```

#### Service Implementation

```typescript
class PaymentService implements IPaymentService {
  constructor(
    private db: IDatabase,
    private emailService: IEmailService,
    private auditService: IAuditService
  ) {}
  
  async createPayment(request: CreatePaymentRequest): Promise<Payment> {
    const payment = await this.db.payments.create({
      amount: request.amount,
      currency: request.currency,
      status: 'PENDING',
    });
    
    await this.emailService.sendEmail(
      request.userEmail,
      'Payment Created',
      `Your payment of ${request.amount} ${request.currency} has been created.`
    );
    
    await this.auditService.logEvent({
      type: 'payment.created',
      paymentId: payment.id,
      userId: request.userId,
    });
    
    return payment;
  }
  
  // Other methods...
}
```

#### Dependency Container

```typescript
class Container {
  private services = new Map<string, any>();
  
  register<T>(key: string, factory: () => T): void {
    this.services.set(key, factory);
  }
  
  resolve<T>(key: string): T {
    const factory = this.services.get(key);
    if (!factory) {
      throw new Error(`Service ${key} not found`);
    }
    return factory();
  }
}

// Setup
const container = new Container();

container.register<IDatabase>('database', () => new Database());
container.register<IEmailService>('email', () => new EmailService());
container.register<IAuditService>('audit', () => new AuditService());

container.register<IPaymentService>('payment', () => {
  return new PaymentService(
    container.resolve<IDatabase>('database'),
    container.resolve<IEmailService>('email'),
    container.resolve<IAuditService>('audit')
  );
});
```

#### Type-Safe Factory Pattern

```typescript
type ServiceFactory<T> = (container: Container) => T;

class TypedContainer {
  private factories = new Map<string, ServiceFactory<any>>();
  
  register<T>(key: string, factory: ServiceFactory<T>): void {
    this.factories.set(key, factory);
  }
  
  resolve<T>(key: string): T {
    const factory = this.factories.get(key);
    if (!factory) {
      throw new Error(`Service ${key} not found`);
    }
    return factory(this) as T;
  }
}

// Usage with type inference
const container = new TypedContainer();

container.register<IPaymentService>('payment', (c) => {
  return new PaymentService(
    c.resolve<IDatabase>('database'),
    c.resolve<IEmailService>('email'),
    c.resolve<IAuditService>('audit')
  );
});

const paymentService = container.resolve<IPaymentService>('payment');
// Fully type-safe!
```

#### Testing with Mocks

```typescript
// Mock implementations for testing
class MockEmailService implements IEmailService {
  private sentEmails: Array<{ to: string; subject: string; body: string }> = [];
  
  async sendEmail(to: string, subject: string, body: string): Promise<void> {
    this.sentEmails.push({ to, subject, body });
  }
  
  getSentEmails(): Array<{ to: string; subject: string; body: string }> {
    return this.sentEmails;
  }
}

// Test setup
const mockEmailService = new MockEmailService();
const paymentService = new PaymentService(
  mockDatabase,
  mockEmailService,
  mockAuditService
);

// Test
await paymentService.createPayment(request);
expect(mockEmailService.getSentEmails()).toHaveLength(1);
```

> "Type-safe dependency injection makes code more testable and maintainable."

#### Benefits

- Easy testing with mock implementations
- Loose coupling between components
- Centralized service management
- Type safety throughout
- Better IDE support



Type-safe dependency injection with TypeScript


Form validation is critical in financial applications. At Pangea, we use TypeScript with Zod to create type-safe forms that validate at runtime and provide excellent developer experience.

#### Schema Definition

```typescript
import { z } from 'zod';

const PaymentFormSchema = z.object({
  amount: z.string()
    .regex(/^\d+\.\d{2}$/, 'Amount must be in format 0.00')
    .refine((val) => parseFloat(val) > 0, 'Amount must be greater than 0'),
  currency: z.enum(['USD', 'EUR', 'GBP'], {
    errorMap: () => ({ message: 'Invalid currency' }),
  }),
  recipientId: z.string().uuid('Invalid recipient ID'),
  description: z.string().min(1).max(500),
  metadata: z.record(z.unknown()).optional(),
});

// Infer TypeScript type from schema
type PaymentFormData = z.infer<typeof PaymentFormSchema>;
```

#### Type-Safe Form Component

```typescript
import { useForm } from 'react-hook-form';
import { zodResolver } from '@hookform/resolvers/zod';

function PaymentForm() {
  const {
    register,
    handleSubmit,
    formState: { errors },
  } = useForm<PaymentFormData>({
    resolver: zodResolver(PaymentFormSchema),
  });
  
  const onSubmit = async (data: PaymentFormData) => {
    // data is fully typed and validated
    await createPayment({
      amount: new Decimal(data.amount),
      currency: data.currency,
      recipientId: data.recipientId,
      description: data.description,
      metadata: data.metadata,
    });
  };
  
  return (
    <form onSubmit={handleSubmit(onSubmit)}>
      <input {...register('amount')} />
      {errors.amount && <span>{errors.amount.message}</span>}
      
      <select {...register('currency')}>
        <option value="USD">USD</option>
        <option value="EUR">EUR</option>
        <option value="GBP">GBP</option>
      </select>
      {errors.currency && <span>{errors.currency.message}</span>}
      
      <input {...register('recipientId')} />
      {errors.recipientId && <span>{errors.recipientId.message}</span>}
      
      <textarea {...register('description')} />
      {errors.description && <span>{errors.description.message}</span>}
      
      <button type="submit">Submit</button>
    </form>
  );
}
```

#### Server-Side Validation

```typescript
// API route handler
export default async function handler(
  req: NextApiRequest,
  res: NextApiResponse
) {
  try {
    // Validate request body
    const validatedData = PaymentFormSchema.parse(req.body);
    
    // Process payment with validated data
    const payment = await createPayment(validatedData);
    
    return res.status(201).json(payment);
  } catch (error) {
    if (error instanceof z.ZodError) {
      return res.status(400).json({
        errors: error.errors,
      });
    }
    
    return res.status(500).json({
      error: 'Internal server error',
    });
  }
}
```

#### Custom Validators

```typescript
const PaymentFormSchema = z.object({
  amount: z.string().refine(
    (val) => {
      const amount = parseFloat(val);
      return amount > 0 && amount <= 1000000;
    },
    { message: 'Amount must be between 0 and 1,000,000' }
  ),
  currency: z.enum(['USD', 'EUR', 'GBP']),
  recipientId: z.string().uuid(),
}).refine(
  (data) => {
    // Cross-field validation
    if (data.currency === 'USD' && parseFloat(data.amount) > 10000) {
      return false;
    }
    return true;
  },
  {
    message: 'USD payments over $10,000 require additional verification',
    path: ['amount'],
  }
);
```

> "Type-safe validation prevents bugs and improves developer experience."

#### Advanced Patterns

**Async Validation:**
```typescript
const PaymentFormSchema = z.object({
  recipientId: z.string().uuid().refine(
    async (id) => {
      const recipient = await checkRecipientExists(id);
      return recipient !== null;
    },
    { message: 'Recipient not found' }
  ),
});
```

**Conditional Validation:**
```typescript
const PaymentFormSchema = z.discriminatedUnion('type', [
  z.object({
    type: z.literal('domestic'),
    routingNumber: z.string().length(9),
  }),
  z.object({
    type: z.literal('international'),
    swiftCode: z.string().regex(/^[A-Z]{4}[A-Z]{2}[A-Z0-9]{2}[A-Z0-9]{3}$/),
  }),
]);
```



Type-safe form validation with TypeScript and Zod


After years of experience in engineering leadership and fintech, I've learned that typescript type patterns requires careful attention to both technical excellence and human factors.

#### The Challenge

TypeScript type patterns is something I've encountered throughout my career at companies like Mercury, Heard, Ness, and now Pangea. The key is understanding both the technical and human aspects.

#### Key Insights

1. **Technical Excellence**: Whether it's Python, TypeScript, or infrastructure, solid technical foundations matter.

2. **People First**: Engineering is ultimately about people-building systems that serve users and teams that thrive.

3. **Balance**: Finding the right balance between technical depth and practical application.

#### Lessons Learned

- Start with understanding the problem deeply
- Build iteratively and get feedback early
- Invest in both technical skills and soft skills
- Take care of your mental and physical health

> "The best engineering solutions come from understanding both the code and the people who use it."

#### Next Steps

Consider how typescript type patterns applies to your own work. What can you learn? What can you improve? How can you help others?



TypeScript type patterns


At Pangea, we're using an Nx monorepo to manage our FX and payments platform. The monorepo approach has been transformative for code sharing, type safety, and developer experience.

#### Why Monorepo for Fintech?

Financial services require tight integration between services. A monorepo allows us to:
- Share types across services (critical for API contracts)
- Enforce consistent patterns
- Make refactoring safer across service boundaries
- Improve developer experience with shared tooling

#### The Nx Advantage

Nx provides:
- Dependency graph visualization
- Affected project detection
- Caching for faster builds
- Code generation for consistency

#### Type Safety Across Services

```typescript
// Shared types package
export interface PaymentRequest {
  amount: Decimal;
  currency: CurrencyCode;
  recipientId: string;
}

// Used in both API and worker services
import { PaymentRequest } from '@pangea/shared-types';
```

This ensures that changes to payment types are caught at compile time across all services.

#### Challenges

- Build times can grow
- Need discipline around dependencies
- CI/CD complexity increases
- Requires team buy-in

#### Best Practices

1. Keep shared code in dedicated packages
2. Use strict dependency rules
3. Invest in CI/CD optimization
4. Document the monorepo structure
5. Regular dependency audits

The monorepo has been a game-changer for maintaining consistency and type safety across our platform.



TypeScript monorepos in fintech


After years of experience in engineering leadership and fintech, I've learned that typescript monorepo best practices requires careful attention to both technical excellence and human factors.

#### The Challenge

TypeScript monorepo best practices is something I've encountered throughout my career at companies like Mercury, Heard, Ness, and now Pangea. The key is understanding both the technical and human aspects.

#### Key Insights

1. **Technical Excellence**: Whether it's Python, TypeScript, or infrastructure, solid technical foundations matter.

2. **People First**: Engineering is ultimately about people-building systems that serve users and teams that thrive.

3. **Balance**: Finding the right balance between technical depth and practical application.

#### Lessons Learned

- Start with understanding the problem deeply
- Build iteratively and get feedback early
- Invest in both technical skills and soft skills
- Take care of your mental and physical health

> "The best engineering solutions come from understanding both the code and the people who use it."

#### Next Steps

Consider how typescript monorepo best practices applies to your own work. What can you learn? What can you improve? How can you help others?



TypeScript monorepo best practices


Building international transfer systems at Mercury required precision in financial calculations. JavaScript's floating-point arithmetic is notoriously problematic for money, but TypeScript gives us the type safety we need while working with proper decimal libraries.

#### The Problem with JavaScript Numbers

```typescript
0.1 + 0.2 === 0.3 // false!
```

This classic JavaScript gotcha becomes catastrophic when dealing with currency. We needed a solution that caught these errors at compile time.

#### Our Approach

We used TypeScript with `decimal.js` for all monetary calculations. The type system ensures we never accidentally use native JavaScript numbers for money:

```typescript
import Decimal from 'decimal.js';

type Money = Decimal;

function calculateInterest(principal: Money, rate: Money): Money {
  return principal.mul(rate);
}
```

#### Type Safety Benefits

TypeScript's type system caught dozens of potential bugs during development. When you're dealing with thousands of transactions daily, catching a bug at compile time versus production can save millions.

#### Lessons from Production

After launching international transfers through Wise, we learned that type safety alone isn't enough. You also need:
- Comprehensive test coverage
- Monitoring and alerting
- Clear error handling
- Audit trails for every calculation



TypeScript for financial calculations


At Pangea, we built an event-driven architecture for our FX and payments platform. TypeScript's type system made it possible to build reliable, type-safe event handlers across multiple services.

#### Why Event-Driven?

Event-driven architecture provides:
- Loose coupling between services
- Scalability (services scale independently)
- Resilience (failures are isolated)
- Flexibility (easy to add new consumers)

#### The Architecture

We use:
- **Pub/Sub** (Google Cloud Pub/Sub) for messaging
- **TypeScript** for type safety
- **Event schemas** defined in shared packages
- **Dead letter queues** for failed events

#### Event Schema

```typescript
// Shared event types
export interface PaymentCreatedEvent {
  type: 'payment.created';
  paymentId: string;
  amount: Decimal;
  currency: CurrencyCode;
  timestamp: Date;
  metadata: Record<string, unknown>;
}

export interface PaymentFailedEvent {
  type: 'payment.failed';
  paymentId: string;
  reason: string;
  timestamp: Date;
}

export type PaymentEvent = PaymentCreatedEvent | PaymentFailedEvent;
```

#### Event Publisher

```typescript
import { PubSub } from '@google-cloud/pubsub';

class EventPublisher {
  private pubsub: PubSub;
  private topic: Topic;
  
  constructor(topicName: string) {
    this.pubsub = new PubSub();
    this.topic = this.pubsub.topic(topicName);
  }
  
  async publish<T extends PaymentEvent>(event: T): Promise<void> {
    const messageId = await this.topic.publishMessage({
      json: event,
    });
    console.log(`Published ${event.type} with ID ${messageId}`);
  }
}
```

#### Event Consumer

```typescript
class PaymentEventHandler {
  private subscription: Subscription;
  
  constructor(subscriptionName: string) {
    const pubsub = new PubSub();
    this.subscription = pubsub.subscription(subscriptionName);
  }
  
  async start(): Promise<void> {
    this.subscription.on('message', (message) => {
      const event = message.json as PaymentEvent;
      this.handleEvent(event);
      message.ack();
    });
  }
  
  private async handleEvent(event: PaymentEvent): Promise<void> {
    switch (event.type) {
      case 'payment.created':
        await this.handlePaymentCreated(event);
        break;
      case 'payment.failed':
        await this.handlePaymentFailed(event);
        break;
      default:
        console.warn(`Unknown event type: ${(event as any).type}`);
    }
  }
  
  private async handlePaymentCreated(event: PaymentCreatedEvent): Promise<void> {
    // Process payment created event
  }
  
  private async handlePaymentFailed(event: PaymentFailedEvent): Promise<void> {
    // Handle payment failure
  }
}
```

#### Benefits

- Type safety catches errors at compile time
- Easy to add new event types
- Clear contracts between services
- Better IDE support and autocomplete

#### Challenges

- Event ordering (use partitioning keys)
- Idempotency (handle duplicate events)
- Error handling (dead letter queues)
- Testing (mock event publishers)

#### Best Practices

1. Version your event schemas
2. Make events idempotent
3. Use dead letter queues
4. Monitor event processing
5. Document event contracts

> "Events are the contracts between services. Make them explicit and type-safe."



Event-driven architecture with TypeScript


Error handling in TypeScript can be tricky. After building payment systems where errors can cost money, I've learned that good error handling is about more than try/catch-it's about creating a robust error handling strategy.

#### The Problem

JavaScript's error handling is limited:
- No discriminated unions for errors
- Easy to forget error cases
- No type safety for error types
- Inconsistent error patterns

#### Pattern 1: Result Type

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

function processPayment(amount: number): Result<Payment, PaymentError> {
  if (amount <= 0) {
    return { success: false, error: new PaymentError('Invalid amount') };
  }
  // Process payment...
  return { success: true, data: payment };
}

// Usage
const result = processPayment(100);
if (result.success) {
  console.log(result.data); // TypeScript knows this is Payment
} else {
  console.error(result.error); // TypeScript knows this is PaymentError
}
```

#### Pattern 2: Custom Error Classes

```typescript
class PaymentError extends Error {
  constructor(
    message: string,
    public code: string,
    public statusCode: number = 400
  ) {
    super(message);
    this.name = 'PaymentError';
  }
}

class InsufficientFundsError extends PaymentError {
  constructor(public balance: number, public requested: number) {
    super(
      `Insufficient funds: ${balance} < ${requested}`,
      'INSUFFICIENT_FUNDS',
      402
    );
  }
}
```

#### Pattern 3: Error Handling Middleware

```typescript
async function errorHandler(
  error: unknown,
  req: Request,
  res: Response,
  next: NextFunction
) {
  if (error instanceof PaymentError) {
    return res.status(error.statusCode).json({
      error: {
        code: error.code,
        message: error.message,
      },
    });
  }
  
  // Log unexpected errors
  console.error('Unexpected error:', error);
  return res.status(500).json({
    error: {
      code: 'INTERNAL_ERROR',
      message: 'An unexpected error occurred',
    },
  });
}
```

#### Pattern 4: Async Error Wrapper

```typescript
function asyncHandler<T extends RequestHandler>(
  fn: T
): RequestHandler {
  return (req, res, next) => {
    Promise.resolve(fn(req, res, next)).catch(next);
  };
}

// Usage
app.post('/payments', asyncHandler(async (req, res) => {
  const payment = await processPayment(req.body);
  res.json(payment);
}));
```

#### Best Practices

1. Use specific error types
2. Include context in errors
3. Log errors appropriately
4. Don't expose internals to users
5. Handle errors at the right level
6. Use type guards for error checking

> "Good error handling makes debugging easier and improves user experience."



TypeScript error handling patterns


At Elevate Security, we launched real-time analytics (RDRs - Real-time Data Reports) that provided instant insights into security events. The system processed thousands of events per second and displayed results in a React dashboard.

#### The Challenge

Security events happen in real-time, and delayed insights mean delayed responses. We needed:
- Sub-second latency
- High throughput (thousands of events/second)
- Real-time visualization
- Historical context
- Alerting capabilities

#### Architecture

We built:
- **Event ingestion**: Kafka for event streaming
- **Processing**: Real-time aggregation with Apache Flink
- **Storage**: Time-series database (InfluxDB)
- **API**: FastAPI for data access
- **Frontend**: React with real-time updates

#### Event Processing

```typescript
interface SecurityEvent {
  timestamp: Date;
  eventType: string;
  userId: string;
  ipAddress: string;
  severity: 'low' | 'medium' | 'high' | 'critical';
  metadata: Record<string, unknown>;
}

class RealTimeAnalytics {
  private eventStream: EventStream;
  private aggregator: EventAggregator;
  
  async processEvent(event: SecurityEvent): Promise<void> {
    // Update real-time counters
    await this.aggregator.incrementCounter(
      `events.${event.eventType}`,
      event.timestamp
    );
    
    // Update user activity
    await this.aggregator.updateUserActivity(
      event.userId,
      event.timestamp
    );
    
    // Check for anomalies
    if (await this.detectAnomaly(event)) {
      await this.triggerAlert(event);
    }
    
    // Update dashboard
    await this.broadcastUpdate(event);
  }
}
```

#### Real-Time Dashboard

```typescript
import { useEffect, useState } from 'react';
import useWebSocket from 'react-use-websocket';

function RealTimeDashboard() {
  const [metrics, setMetrics] = useState<Metrics>({});
  const { lastMessage } = useWebSocket('ws://api/events/stream');
  
  useEffect(() => {
    if (lastMessage) {
      const update = JSON.parse(lastMessage.data);
      setMetrics(prev => ({
        ...prev,
        ...update,
      }));
    }
  }, [lastMessage]);
  
  return (
    <div>
      <MetricCard label="Events/sec" value={metrics.eventsPerSecond} />
      <MetricCard label="Active Users" value={metrics.activeUsers} />
      <EventTimeline events={metrics.recentEvents} />
    </div>
  );
}
```

#### Aggregation Logic

```typescript
class EventAggregator {
  private counters: Map<string, number> = new Map();
  private timeWindows: Map<string, TimeWindow> = new Map();
  
  incrementCounter(key: string, timestamp: Date): void {
    const windowKey = this.getTimeWindow(timestamp);
    const current = this.counters.get(windowKey) || 0;
    this.counters.set(windowKey, current + 1);
  }
  
  getMetrics(timeRange: TimeRange): Metrics {
    const relevantWindows = this.getWindowsInRange(timeRange);
    
    return {
      totalEvents: relevantWindows.reduce((sum, w) => sum + w.count, 0),
      eventsPerSecond: this.calculateRate(relevantWindows),
      topEventTypes: this.getTopEventTypes(relevantWindows),
    };
  }
}
```

#### Performance Optimization

- Use time-windowed aggregation
- Cache frequently accessed metrics
- Batch database writes
- Use WebSockets for real-time updates
- Optimize queries with indexes

#### Results

- Sub-second latency for metrics
- Real-time visualization
- Better security incident response
- Improved user experience
- Scalable to millions of events

> "Real-time analytics enable faster decision-making."

#### Lessons Learned

1. Choose the right time-series database
2. Optimize aggregation queries
3. Use WebSockets for real-time updates
4. Handle backpressure gracefully
5. Monitor system performance



Building real-time analytics with RDRs


At Ness, we integrated Plaid to streamline onboarding for our consumer credit card platform. The integration reduced onboarding time by 50%, but getting it right required careful attention to TypeScript types and error handling.

#### Why Plaid?

Plaid provides a unified API for connecting to thousands of financial institutions. Instead of building integrations with each bank, we use Plaid's API to access account data, transaction history, and identity verification.

#### The TypeScript Advantage

Plaid's TypeScript SDK provides excellent type safety:

```typescript
import { PlaidApi, PlaidEnvironments, AccountsGetRequest } from 'plaid';

const client = new PlaidApi({
  basePath: PlaidEnvironments.sandbox,
  baseOptions: {
    headers: {
      'PLAID-CLIENT-ID': process.env.PLAID_CLIENT_ID,
      'PLAID-SECRET': process.env.PLAID_SECRET,
    },
  },
});

async function getAccounts(accessToken: string) {
  const request: AccountsGetRequest = {
    access_token: accessToken,
  };
  
  const response = await client.accountsGet(request);
  return response.data.accounts;
}
```

#### Error Handling

Plaid uses specific error codes that we need to handle:

```typescript
try {
  const accounts = await getAccounts(accessToken);
} catch (error) {
  if (error.response?.data?.error_code === 'ITEM_LOGIN_REQUIRED') {
    // Re-authenticate the user
    return redirectToPlaidLink();
  }
  // Handle other errors
}
```

#### Security Considerations

- Never store Plaid access tokens in plain text
- Use environment variables for credentials
- Implement proper token rotation
- Log access but don't log sensitive data
- Follow PCI compliance guidelines

#### The User Experience

The Plaid Link flow is straightforward:
1. User clicks "Connect Bank"
2. Plaid Link modal opens
3. User selects their bank and logs in
4. We receive an access token
5. We can now fetch account data

#### Results

- 50% reduction in onboarding time
- Higher conversion rates
- Better user experience
- Reduced support tickets

#### Lessons Learned

1. Test thoroughly in sandbox before production
2. Handle all error cases gracefully
3. Provide clear user messaging
4. Monitor API usage and costs
5. Keep SDK updated

Plaid integration was a game-changer for our onboarding flow.



Integrating Plaid with TypeScript


At Elevate Security, we built a no-code workflow builder that allowed users to create security automation workflows without writing code. Built with React and Tailwind, it provided a visual interface for connecting actions and triggers.

#### The Vision

Enable non-technical users to:
- Create workflows visually
- Connect triggers to actions
- Test workflows before deployment
- Monitor workflow execution
- Debug workflow issues

#### Architecture

- **Frontend**: React with drag-and-drop
- **Backend**: Node.js/Express API
- **Execution Engine**: Workflow runner service
- **Storage**: PostgreSQL for workflow definitions
- **Monitoring**: Real-time execution logs

#### React Components

```typescript
import React, { useState } from 'react';
import { ReactFlow, Node, Edge } from 'reactflow';

interface WorkflowNode {
  id: string;
  type: 'trigger' | 'action' | 'condition';
  data: {
    label: string;
    config: Record<string, unknown>;
  };
  position: { x: number; y: number };
}

function WorkflowBuilder() {
  const [nodes, setNodes] = useState<Node[]>([]);
  const [edges, setEdges] = useState<Edge[]>([]);
  
  const onNodesChange = (changes: NodeChange[]) => {
    setNodes(applyNodeChanges(changes, nodes));
  };
  
  const onEdgesChange = (changes: EdgeChange[]) => {
    setEdges(applyEdgeChanges(changes, edges));
  };
  
  const onConnect = (connection: Connection) => {
    setEdges(prev => addEdge(connection, prev));
  };
  
  return (
    <div className="h-screen w-full">
      <ReactFlow
        nodes={nodes}
        edges={edges}
        onNodesChange={onNodesChange}
        onEdgesChange={onEdgesChange}
        onConnect={onConnect}
      >
        <Controls />
        <MiniMap />
        <Background />
      </ReactFlow>
    </div>
  );
}
```

#### Node Types

```typescript
const nodeTypes = {
  trigger: TriggerNode,
  action: ActionNode,
  condition: ConditionNode,
};

function TriggerNode({ data }: { data: NodeData }) {
  return (
    <div className="px-4 py-2 bg-blue-500 text-white rounded">
      <div className="font-bold">{data.label}</div>
      <div className="text-sm">{data.description}</div>
    </div>
  );
}

function ActionNode({ data }: { data: NodeData }) {
  return (
    <div className="px-4 py-2 bg-green-500 text-white rounded">
      <div className="font-bold">{data.label}</div>
      <div className="text-sm">{data.description}</div>
    </div>
  );
}
```

#### Workflow Execution

```typescript
class WorkflowExecutor {
  async executeWorkflow(workflowId: string, context: ExecutionContext): Promise<ExecutionResult> {
    const workflow = await this.loadWorkflow(workflowId);
    const execution = await this.createExecution(workflowId);
    
    try {
      // Execute trigger
      const triggerResult = await this.executeTrigger(workflow.trigger, context);
      
      // Execute actions
      for (const action of workflow.actions) {
        if (await this.evaluateConditions(action.conditions, triggerResult)) {
          await this.executeAction(action, triggerResult);
        }
      }
      
      await this.markExecutionComplete(execution.id);
      return { success: true, executionId: execution.id };
    } catch (error) {
      await this.markExecutionFailed(execution.id, error);
      throw error;
    }
  }
}
```

#### Testing Workflows

```typescript
function WorkflowTester({ workflowId }: { workflowId: string }) {
  const [testResult, setTestResult] = useState<TestResult | null>(null);
  
  const runTest = async () => {
    const result = await fetch(`/api/workflows/${workflowId}/test`, {
      method: 'POST',
      body: JSON.stringify({ testData: {} }),
    }).then(r => r.json());
    
    setTestResult(result);
  };
  
  return (
    <div>
      <button onClick={runTest}>Run Test</button>
      {testResult && (
        <TestResultViewer result={testResult} />
      )}
    </div>
  );
}
```

#### Results

- Non-technical users created workflows
- Faster automation setup
- Visual debugging
- Better user experience
- Reduced support requests

> "No-code tools democratize automation."

#### Lessons Learned

1. Make the UI intuitive
2. Provide good error messages
3. Allow testing before deployment
4. Show execution logs
5. Support workflow versioning



Building a no-code workflow builder with React


Building financial dashboards requires real-time data, complex visualizations, and excellent user experience. Next.js provides the perfect foundation for these applications, combining React's component model with server-side rendering and API routes.

#### Why Next.js?

Next.js offers:
- Server-side rendering for fast initial loads
- API routes for backend logic
- TypeScript support out of the box
- Excellent developer experience
- Great performance optimizations

#### Architecture

We use:
- **Next.js** for the framework
- **TypeScript** for type safety
- **Tailwind CSS** for styling
- **Recharts** or **Chart.js** for visualizations
- **SWR** or **React Query** for data fetching

#### Example: Dashboard Page

```typescript
import { GetServerSideProps } from 'next';
import { useState } from 'react';
import useSWR from 'swr';

interface DashboardProps {
  initialData: FinancialData;
}

export default function Dashboard({ initialData }: DashboardProps) {
  const { data, error } = useSWR('/api/financial-data', {
    fallbackData: initialData,
    refreshInterval: 5000, // Refresh every 5 seconds
  });

  if (error) return <div>Error loading data</div>;
  if (!data) return <div>Loading...</div>;

  return (
    <div className="grid grid-cols-3 gap-4">
      <BalanceCard balance={data.balance} />
      <TransactionList transactions={data.transactions} />
      <Chart data={data.chartData} />
    </div>
  );
}

export const getServerSideProps: GetServerSideProps = async () => {
  const data = await fetchFinancialData();
  return { props: { initialData: data } };
};
```

#### Real-Time Updates

```typescript
function useRealtimeFinancialData() {
  const { data, mutate } = useSWR('/api/financial-data');
  
  useEffect(() => {
    const eventSource = new EventSource('/api/stream');
    eventSource.onmessage = (event) => {
      const newData = JSON.parse(event.data);
      mutate(newData, false); // Update without revalidation
    };
    return () => eventSource.close();
  }, [mutate]);
  
  return data;
}
```

#### Security Considerations

- Authenticate all API routes
- Validate all user inputs
- Use HTTPS in production
- Implement rate limiting
- Sanitize data before display

#### Performance

- Use static generation when possible
- Implement proper caching
- Optimize images
- Code split large components
- Monitor performance metrics

> "Financial dashboards need to be fast, accurate, and secure."

#### Best Practices

1. Type everything with TypeScript
2. Handle loading and error states
3. Implement proper authentication
4. Optimize for performance
5. Test thoroughly



Next.js for financial dashboards


At Skillshare, we migrated our payments backend to Nest.js and our frontend to React. The migration improved developer experience, type safety, and maintainability.

#### Why Migrate?

Our legacy stack had issues:
- Tight coupling between components
- Limited type safety
- Difficult to test
- Poor developer experience
- Hard to scale

#### Backend: Nest.js Migration

Nest.js provides:
- TypeScript-first architecture
- Dependency injection
- Modular structure
- Built-in testing support
- Excellent documentation

#### Service Structure

```typescript
// payment.service.ts
@Injectable()
export class PaymentService {
  constructor(
    private paymentRepository: PaymentRepository,
    private notificationService: NotificationService,
  ) {}
  
  async processPayment(dto: CreatePaymentDto): Promise<Payment> {
    const payment = await this.paymentRepository.create(dto);
    await this.notificationService.sendConfirmation(payment);
    return payment;
  }
}

// payment.controller.ts
@Controller('payments')
export class PaymentController {
  constructor(private paymentService: PaymentService) {}
  
  @Post()
  async create(@Body() dto: CreatePaymentDto): Promise<Payment> {
    return this.paymentService.processPayment(dto);
  }
}
```

#### Module Organization

```typescript
@Module({
  imports: [TypeOrmModule.forFeature([Payment])],
  controllers: [PaymentController],
  providers: [PaymentService, PaymentRepository],
  exports: [PaymentService],
})
export class PaymentModule {}
```

#### Frontend: React Migration

React provides:
- Component-based architecture
- Strong ecosystem
- TypeScript support
- Great developer tools
- Performance optimizations

#### Component Structure

```typescript
interface PaymentFormProps {
  onSubmit: (payment: PaymentData) => void;
}

function PaymentForm({ onSubmit }: PaymentFormProps) {
  const [paymentData, setPaymentData] = useState<PaymentData>({
    amount: 0,
    currency: 'USD',
  });
  
  const handleSubmit = (e: React.FormEvent) => {
    e.preventDefault();
    onSubmit(paymentData);
  };
  
  return (
    <form onSubmit={handleSubmit}>
      <input
        type="number"
        value={paymentData.amount}
        onChange={(e) => setPaymentData({
          ...paymentData,
          amount: parseFloat(e.target.value),
        })}
      />
      <button type="submit">Pay</button>
    </form>
  );
}
```

#### Migration Strategy

1. **Parallel Run**: Run old and new systems side-by-side
2. **Feature Flags**: Gradually enable new system
3. **Incremental Migration**: Move features one at a time
4. **Testing**: Comprehensive testing at each step
5. **Rollback Plan**: Ability to revert if needed

#### Testing

```typescript
// Backend tests
describe('PaymentService', () => {
  let service: PaymentService;
  
  beforeEach(async () => {
    const module = await Test.createTestingModule({
      providers: [PaymentService, PaymentRepository],
    }).compile();
    
    service = module.get<PaymentService>(PaymentService);
  });
  
  it('should process payment', async () => {
    const result = await service.processPayment({
      amount: 100,
      currency: 'USD',
    });
    
    expect(result).toBeDefined();
  });
});

// Frontend tests
describe('PaymentForm', () => {
  it('should submit payment data', () => {
    const onSubmit = jest.fn();
    render(<PaymentForm onSubmit={onSubmit} />);
    
    fireEvent.change(screen.getByLabelText('Amount'), {
      target: { value: '100' },
    });
    fireEvent.click(screen.getByText('Pay'));
    
    expect(onSubmit).toHaveBeenCalledWith({
      amount: 100,
      currency: 'USD',
    });
  });
});
```

#### Results

- Better type safety
- Improved developer experience
- Easier testing
- More maintainable code
- Faster feature development

> "Modern frameworks improve productivity and code quality."

#### Lessons Learned

1. Plan migration carefully
2. Test thoroughly
3. Migrate incrementally
4. Train team on new stack
5. Monitor performance



Migrating to Nest.js and React


At Pangea, we integrated multiple third-party services: Jiko for banking, Plaid for account connectivity, Clerk for authentication, and Xata for data storage. Each integration required careful design and error handling.

#### Integration Architecture

```typescript
// Authentication with Clerk
import { Clerk } from '@clerk/clerk-sdk-node';

class AuthService {
  private clerk: Clerk;
  
  async authenticateUser(token: string): Promise<User> {
    const user = await this.clerk.verifyToken(token);
    return this.mapClerkUserToUser(user);
  }
}

// Account connectivity with Plaid
import { PlaidApi } from 'plaid';

class AccountService {
  private plaid: PlaidApi;
  
  async linkAccount(userId: string): Promise<LinkToken> {
    const response = await this.plaid.linkTokenCreate({
      user: { client_user_id: userId },
      client_name: 'Pangea',
      products: ['transactions', 'auth'],
      country_codes: ['US'],
    });
    
    return response.data.link_token;
  }
}

// Banking with Jiko
class BankingService {
  async createAccount(userId: string, accountData: AccountData): Promise<Account> {
    const response = await fetch('https://api.jiko.com/accounts', {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${process.env.JIKO_API_KEY}`,
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({
        user_id: userId,
        ...accountData,
      }),
    });
    
    return response.json();
  }
}

// Data storage with Xata
import { XataClient } from '@xata.io/client';

class DataService {
  private xata: XataClient;
  
  async storeTransaction(transaction: Transaction): Promise<void> {
    await this.xata.db.transactions.create(transaction);
  }
}
```

#### Unified Service Layer

```typescript
class PangeaService {
  constructor(
    private auth: AuthService,
    private accounts: AccountService,
    private banking: BankingService,
    private data: DataService,
  ) {}
  
  async onboardUser(authToken: string, accountData: AccountData): Promise<OnboardingResult> {
    // Authenticate user
    const user = await this.auth.authenticateUser(authToken);
    
    // Create bank account
    const bankAccount = await this.banking.createAccount(user.id, accountData);
    
    // Link Plaid account
    const linkToken = await this.accounts.linkAccount(user.id);
    
    // Store in Xata
    await this.data.storeTransaction({
      userId: user.id,
      accountId: bankAccount.id,
      type: 'onboarding',
    });
    
    return {
      userId: user.id,
      bankAccountId: bankAccount.id,
      linkToken,
    };
  }
}
```

#### Error Handling

```typescript
class IntegrationError extends Error {
  constructor(
    message: string,
    public service: string,
    public code: string,
  ) {
    super(message);
  }
}

async function handleIntegrationError(error: unknown, service: string): Promise<never> {
  if (error instanceof IntegrationError) {
    // Log and handle service-specific errors
    logger.error(`Integration error in ${service}`, error);
    throw error;
  }
  
  // Handle unexpected errors
  logger.error(`Unexpected error in ${service}`, error);
  throw new IntegrationError('Unexpected error', service, 'UNKNOWN');
}
```

#### Testing Integrations

```typescript
describe('PangeaService', () => {
  it('should onboard user successfully', async () => {
    // Mock integrations
    jest.spyOn(authService, 'authenticateUser').mockResolvedValue(mockUser);
    jest.spyOn(bankingService, 'createAccount').mockResolvedValue(mockAccount);
    
    const result = await pangeaService.onboardUser('token', accountData);
    
    expect(result.userId).toBeDefined();
    expect(result.bankAccountId).toBeDefined();
  });
});
```

#### Best Practices

- Use SDKs when available
- Handle errors gracefully
- Implement retries with backoff
- Monitor integration health
- Cache when appropriate
- Document integration contracts

> "Third-party integrations require careful design and error handling."

#### Lessons Learned

1. Use official SDKs
2. Handle all error cases
3. Implement proper retries
4. Monitor integration health
5. Test with sandbox environments

