Enterprise TypeScript Architecture: Branded Types, Discriminated Unions & the Satisfies Operator

// Problem: Both are raw strings!
function transferFunds(senderId: string, recipientId: string, amount: number) {
  // If someone accidentally calls transferFunds(recipientId, senderId, 500),
  // TypeScript will NOT throw an error!
}

declare const Brand: unique symbol;

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

// Domain Primitives
export type UserId = Branded<string, "UserId">;
export type OrderId = Branded<string, "OrderId">;
export type USDAmount = Branded<number, "USDAmount">;

// Constructor validators
export function createUserId(id: string): UserId {
  if (!id.startsWith("usr_")) throw new Error("Invalid User ID format");
  return id as UserId;
}

export function createUSDAmount(n: number): USDAmount {
  if (n <= 0) throw new Error("Amount must be positive");
  return n as USDAmount;
}

// Function signature with strict nominal types
function executeOrder(userId: UserId, orderId: OrderId, amount: USDAmount) {
  console.log(`User ${userId} executed order ${orderId} for $${amount}`);
}

const user = createUserId("usr_987");
const order = "ord_123" as OrderId;
const payment = createUSDAmount(150);

executeOrder(user, order, payment); // ✅ Compiles perfectly!

// executeOrder(order, user, payment);
// ❌ Error: Type 'OrderId' is not assignable to type 'UserId'

type PaymentState =
  | { status: "idle" }
  | { status: "processing"; startedAt: number }
  | { status: "succeeded"; transactionId: string; amount: number }
  | { status: "failed"; errorCode: string; retryable: boolean };

function assertNever(x: never): never {
  throw new Error(`Unexpected object received: ${JSON.stringify(x)}`);
}

function renderPaymentStatus(state: PaymentState): string {
  switch (state.status) {
    case "idle":
      return "Ready to pay.";
    case "processing":
      return `Processing since ${new Date(state.startedAt).toLocaleTimeString()}...`;
    case "succeeded":
      return `Payment successful! Ref: ${state.transactionId}`;
    case "failed":
      return `Payment failed (${state.errorCode}).`;
    default:
      // If any variant is unhandled, TypeScript fails compilation right here!
      return assertNever(state);
  }
}

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

// APPROACH A: Standard Type Annotation (Type is widened to Color)
const paletteA: Record<string, Color> = {
  primary: "red",
  accent: [0, 242, 254],
};
// paletteA.primary.toUpperCase(); 
// ❌ Error: Property 'toUpperCase' does not exist on type '[number, number, number]'

// APPROACH B: The satisfies Operator (Validates type AND preserves exact literals!)
const paletteB = {
  primary: "red",
  accent: [0, 242, 254],
} satisfies Record<string, Color>;

// ✅ TypeScript knows primary is strictly 'red', so toUpperCase() works!
console.log(paletteB.primary.toUpperCase()); 
// ✅ TypeScript knows accent is strictly a 3-number tuple!
console.log(paletteB.accent[0].toFixed(2));

// The 'const' modifier instructs TypeScript to infer the narrowest literal type
function defineRoutes<const TRoutes extends readonly string[]>(routes: TRoutes): TRoutes {
  return routes;
}

// Inferred as readonly ["/dashboard", "/settings", "/billing"] (NOT string[])!
const appRoutes = defineRoutes(["/dashboard", "/settings", "/billing"]);

export type Result<TData, TError = Error> =
  | { success: true; data: TData }
  | { success: false; error: TError };

export function Ok<T>(data: T): Result<T, never> {
  return { success: true, data };
}

export function Err<E>(error: E): Result<never, E> {
  return { success: false, error };
}

// Usage in API handler
async function fetchUserAccount(id: string): Promise<Result<{ name: string }, "NOT_FOUND" | "DB_ERROR">> {
  try {
    const user = await findUserInDatabase(id);
    if (!user) return Err("NOT_FOUND");
    return Ok({ name: user.name });
  } catch {
    return Err("DB_ERROR");
  }
}

// Consumer code is forced to handle both success and error branches safely!
const res = await fetchUserAccount("usr_123");
if (res.success) {
  console.log("Welcome:", res.data.name);
} else {
  console.error("Fetch failed with reason:", res.error);
}