Advanced TypeScript Patterns for Enterprise Applications

// THE DANGEROUS DEFAULT: Primitive Obsession
function transferFunds(senderId: string, recipientId: string, amountCents: number) {
  // Logic...
}

const customerId = "cust_123";
const vendorId = "vend_456";

// ACCIDENTAL BUG: Parameters swapped! TypeScript compiles with ZERO errors:
transferFunds(vendorId, customerId, 5000);

// types/branded.ts
declare const __brand: unique symbol;

export type Brand<T, B> = T & { readonly [__brand]: B };

// Domain Types
export type UserId = Brand<string, 'UserId'>;
export type OrderId = Brand<string, 'OrderId'>;
export type Cents = Brand<number, 'Cents'>;

// Validated Constructors / Type Guards
export function parseUserId(raw: string): UserId {
  if (!raw.startsWith('usr_')) {
    throw new Error(`Invalid UserId format: ${raw}`);
  }
  return raw as UserId;
}

export function toCents(dollars: number): Cents {
  if (dollars < 0) throw new Error('Amount cannot be negative');
  return Math.round(dollars * 100) as Cents;
}

function chargeCustomer(user: UserId, amount: Cents) {
  // ...
}

const rawId = "usr_987";
// chargeCustomer(rawId, 1000); 
// ❌ ERROR: Argument of type 'string' is not assignable to parameter of type 'UserId'.

const validUser = parseUserId(rawId);
const validAmount = toCents(10.00);

chargeCustomer(validUser, validAmount); // ✅ COMPILES SAFELY

interface AuditRecord {
  timestamp: number;
  actor: string;
}

interface BaseCustomer {
  id: string;
  name: string;
}

interface CustomerWithAudit extends BaseCustomer {
  auditLog: AuditRecord[];
}

interface FetchOptions {
  includeAudit?: boolean;
}

// Dynamic Return Type Calculation
export type CustomerResponse<T extends FetchOptions> = 
  T extends { includeAudit: true } ? CustomerWithAudit : BaseCustomer;

export async function getCustomer<T extends FetchOptions>(
  id: string,
  options?: T
): Promise<CustomerResponse<T>> {
  const res = await fetch(`/api/customers/${id}?audit=${options?.includeAudit ?? false}`);
  return res.json();
}

// USAGE:
async function run() {
  // TypeScript infers return type as BaseCustomer:
  const simple = await getCustomer('cust_1', { includeAudit: false });
  // simple.auditLog; // ❌ Property 'auditLog' does not exist on type 'BaseCustomer'.

  // TypeScript infers return type as CustomerWithAudit:
  const detailed = await getCustomer('cust_2', { includeAudit: true });
  console.log(detailed.auditLog.length); // ✅ Fully typed!
}

// Recursive Path Parameter Extractor
type ExtractParams<Path extends string> =
  Path extends `${string}:${infer Param}/${infer Rest}`
    ? { [K in Param | keyof ExtractParams<`/${Rest}`>]: string }
    : Path extends `${string}:${infer Param}`
    ? { [K in Param]: string }
    : Record<string, never>;

// Type Verification Tests:
type RouteA = ExtractParams<"/dashboard">; 
// Result: Record<string, never> (Empty object)

type RouteB = ExtractParams<"/orgs/:orgId/members/:memberId">;
// Result: { orgId: string; memberId: string; }

// Implementation of Type-Safe API Client:
function createRoute<P extends string>(path: P) {
  return {
    buildUrl(params: ExtractParams<P>): string {
      let url: string = path;
      for (const [key, value] of Object.entries(params)) {
        url = url.replace(`:${key}`, encodeURIComponent(value as string));
      }
      return url;
    }
  };
}

const userOrderRoute = createRoute("/api/users/:userId/orders/:orderId");

// userOrderRoute.buildUrl({ userId: "10" });
// ❌ ERROR: Property 'orderId' is missing in type '{ userId: string; }'.

const url = userOrderRoute.buildUrl({ userId: "10", orderId: "ord_99" });
// ✅ Output: "/api/users/10/orders/ord_99"

type Color = 'red' | 'green' | 'blue' | [number, number, number];

type ThemeConfig = Record<'primary' | 'secondary', Color>;

// PROBLEM WITH ANNOTATION (: ThemeConfig):
// Widens the types to 'Color', so we lose exact string literal knowledge!
const themeAnnotated: ThemeConfig = {
  primary: 'red',
  secondary: [0, 255, 0]
};
// themeAnnotated.primary.toUpperCase(); // ❌ ERROR: Property 'toUpperCase' does not exist on type '[number, number, number]'.

// THE WINNER: `satisfies`
const themeWithSatisfies = {
  primary: 'red',
  secondary: [0, 255, 0]
} satisfies ThemeConfig;

// 1. Catches invalid keys at compile time:
// { accent: 'purple' } satisfies ThemeConfig; // ❌ ERROR: Object literal may only specify known properties.

// 2. Preserves exact inferred types:
console.log(themeWithSatisfies.primary.toUpperCase()); // ✅ Valid! Inferred as string literal 'red'.
console.log(themeWithSatisfies.secondary.map(v => v * 2)); // ✅ Valid! Inferred as tuple [number, number, number].

type PaymentState = 
  | { status: 'PENDING'; expiresAt: number }
  | { status: 'SUCCESS'; transactionId: string }
  | { status: 'FAILED'; reason: string }
  | { status: 'REFUNDED'; refundId: string }; // Newly added state!

function handlePayment(event: PaymentState): string {
  switch (event.status) {
    case 'PENDING':
      return `Waiting for payment until ${event.expiresAt}`;
    case 'SUCCESS':
      return `Processed transaction: ${event.transactionId}`;
    case 'FAILED':
      return `Payment failed: ${event.reason}`;
    case 'REFUNDED':
      return `Refund issued: ${event.refundId}`;
    default: {
      // EXHAUSTIVE CHECK:
      // If any union variant is unhandled, `event` is NOT `never`, and this line fails compilation!
      const _unreachable: never = event;
      throw new Error(`Unhandled payment state: ${JSON.stringify(_unreachable)}`);
    }
  }
}