Production-Grade Typescript & Architecture

When an endpoint path changes, do you want failures to show up at compile time or at runtime? This section defines a strongly typed TypeScript API client wrapper that enforces endpoint-specific request/response typing using Advanced TypeScript (production-grade) Generics & Utility Types, Type Narrowing & Guards (discriminated unions, `never`, exhaustive checks), and Error Handling with a `Result` pattern.

Quick Reference

Example Prep Question: “Design a strongly typed API client wrapper in TypeScript that ensures compile-time safety for endpoints.”

Parameters

Typed contract fields (within `TEndpoints`):

Code Example

// Strongly typed API client wrapper with compile-time endpoint safety.
// Uses Advanced TypeScript (production-grade) Generics & Utility Types,
// Type Narrowing & Guards (discriminated unions + exhaustive checks),
// and Error Handling with Result.

type Result =
  | { ok: true; value: T }
  | { ok: false; error: E };

type ApiError = {
  status: number;
  code: "VALIDATION_ERROR" | "NOT_FOUND" | "UPSTREAM_ERROR";
  message: string;
};

// Endpoint contract matrix
type Endpoints = {
  getProperty: {
    method: "GET";
    path: "/v1/properties/{propertyId}";
    request: { params: { propertyId: string } };
    response: { id: string; name: string; price: number };
    error: ApiError;
  };
  createProperty: {
    method: "POST";
    path: "/v1/properties";
    request: { body: { name: string; price: number } };
    response: { id: string };
    error: ApiError;
  };
};

type EndpointKey = keyof Endpoints;

type ExtractParams =
  Endpoints[EK]["request"] extends { params: infer P } ? P : never;

type ExtractBody =
  Endpoints[EK]["request"] extends { body: infer B } ? B : never;

type ExtractResponse = Endpoints[EK]["response"];
type ExtractError = Endpoints[EK]["error"];
type ExtractMethod = Endpoints[EK]["method"];
type ExtractPath = Endpoints[EK]["path"];

type ExhaustiveCheck = T;

function assertNever(x: never): never {
  throw new Error(`Unhandled case: ${String(x)}`);
}

export class TypedApiClient> {
  constructor(
    private readonly baseUrl: string,
    private readonly endpoints: T,
    private readonly requestInit: RequestInit = {},
    private readonly timeoutMs: number = 10_000,
    private readonly headers: Record = {},
    private readonly resultMode: "result" | "throw" = "result"
  ) {}

  private async fetchJson(input: RequestInfo, init: RequestInit): Promise {
    const res = await fetch(input, init);
    const text = await res.text();
    const data = text ? JSON.parse(text) : undefined;
    if (!res.ok) throw { status: res.status, data };
    return data as TResponse;
  }

  async call(
    key: EK,
    ...args: ExtractParams extends never
      ? [undefined?]
      : [ExtractParams]
  ): Promise, ExtractError>> {
    const endpoint = this.endpoints[key] as Endpoints[EK];
    const method = endpoint.method as ExtractMethod;
    const path = endpoint.path as ExtractPath;

    // Discriminated union narrowing for request building
    const controller = new AbortController();
    const timeout = setTimeout(() => controller.abort(), this.timeoutMs);

    try {
      let url = this.baseUrl + path;
      let body: any =

const params = (args?.[0] ?? {}) as ExtractParams;
			// Simple path templating: "/v1/properties/{propertyId}"
			url = url.replace("{propertyId}", encodeURIComponent((params as any).propertyId));
...