Рецепт: типизированный API-клиент на fetch

npm init -y
npm pkg set type=module
npm install zod@4
npm install -D typescript @types/node@24 vitest

{
  "compilerOptions": {
    "noEmit": true,
    "target": "esnext",
    "module": "nodenext",
    "allowImportingTsExtensions": true,
    "verbatimModuleSyntax": true,
    "erasableSyntaxOnly": true,
    "strict": true,
    "skipLibCheck": true,
    "types": ["node"]
  },
  "include": ["src", "test"]
}

import { z } from "zod";

// RFC 9457: a member of the wrong type is ignored, unknown members are extensions
const ProblemDetailsSchema = z.looseObject({
  type: z.string().catch("about:blank").default("about:blank"),
  title: z.string().optional().catch(undefined),
  status: z.number().int().optional().catch(undefined),
  detail: z.string().optional().catch(undefined),
  instance: z.string().optional().catch(undefined),
});
export type ProblemDetails = z.output<typeof ProblemDetailsSchema>;

export type ApiErrorKind = "http" | "timeout" | "network" | "invalid-response";

// One error class for everything that can go wrong with a call.
// Cancellation by the caller is not an ApiError: the AbortError is rethrown as is.
export class ApiError extends Error {
  readonly kind: ApiErrorKind;
  readonly method: string;
  readonly url: string;
  readonly status: number | undefined;
  readonly problem: ProblemDetails | undefined;

  constructor(
    message: string,
    details: { kind: ApiErrorKind; method: string; url: string; status?: number; problem?: ProblemDetails; cause?: unknown },
  ) {
    super(message, { cause: details.cause });
    this.name = "ApiError";
    this.kind = details.kind;
    this.method = details.method;
    this.url = details.url;
    this.status = details.status;
    this.problem = details.problem;
  }
}

type HeadersProvider = HeadersInit | (() => HeadersInit | Promise<HeadersInit>);
type Query = Record<string, string | number | boolean | undefined>;

export type ApiClientOptions = {
  baseUrl: string; // "https://api.example.com/v1"
  headers?: HeadersProvider; // a function is called before every attempt: fresh token
  timeoutMs?: number; // per attempt
  retries?: number; // extra attempts, only for idempotent requests
  retryDelayMs?: number;
  fetch?: typeof fetch;
};

export type RequestOptions<S extends z.ZodType> = {
  schema: S; // checks the response body and gives it a type
  query?: Query;
  body?: unknown; // sent as JSON
  headers?: HeadersInit;
  signal?: AbortSignal; // cancellation by the caller
  timeoutMs?: number;
  idempotencyKey?: string; // makes POST and PATCH retryable if the API supports it
};

const IDEMPOTENT_METHODS = new Set(["GET", "HEAD", "OPTIONS", "PUT", "DELETE"]);
const RETRYABLE_STATUS = new Set([408, 429, 500, 502, 503, 504]);

function buildUrl(baseUrl: string, path: string, query: Query = {}): URL {
  // new URL("users", "https://x/v1") drops "/v1": keep the base path with a trailing slash
  const url = new URL(path.replace(/^\/+/, ""), baseUrl.endsWith("/") ? baseUrl : `${baseUrl}/`);
  for (const [key, value] of Object.entries(query)) {
    if (value !== undefined) url.searchParams.set(key, String(value));
  }
  return url;
}

async function readProblem(res: Response): Promise<ProblemDetails | undefined> {
  if (!res.headers.get("content-type")?.includes("application/problem+json")) {
    await res.body?.cancel();
    return undefined;
  }
  const parsed = ProblemDetailsSchema.safeParse(await res.json().catch(() => null));
  return parsed.success ? parsed.data : undefined;
}

function sleep(ms: number, signal: AbortSignal | undefined): Promise<void> {
  return new Promise((resolve, reject) => {
    if (signal?.aborted) return reject(signal.reason);
    const timer = setTimeout(done, ms);
    function done() {
      signal?.removeEventListener("abort", onAbort);
      resolve();
    }
    function onAbort() {
      clearTimeout(timer);
      reject(signal?.reason);
    }
    signal?.addEventListener("abort", onAbort, { once: true });
  });
}

export function createApiClient(options: ApiClientOptions) {
  const { baseUrl, timeoutMs = 10_000, retries = 2, retryDelayMs = 200, fetch: doFetch = fetch } = options;

  async function attempt<S extends z.ZodType>(method: string, url: URL, opts: RequestOptions<S>): Promise<z.output<S>> {
    const shared = typeof options.headers === "function" ? await options.headers() : options.headers;
    const headers = new Headers(shared);
    new Headers(opts.headers).forEach((value, key) => headers.set(key, value));
    headers.set("Accept", "application/json, application/problem+json");
    if (opts.idempotencyKey) headers.set("Idempotency-Key", opts.idempotencyKey);
    if (opts.body !== undefined) headers.set("Content-Type", "application/json");

    const timeout = AbortSignal.timeout(opts.timeoutMs ?? timeoutMs);
    const signal = opts.signal ? AbortSignal.any([opts.signal, timeout]) : timeout;
    const where = { method, url: url.toString() };

    try {
      const res = await doFetch(url, {
        method,
        headers,
        body: opts.body === undefined ? undefined : JSON.stringify(opts.body),
        signal,
      });
      if (!res.ok) {
        const problem = await readProblem(res);
        const reason = problem?.title ?? res.statusText;
        throw new ApiError(`${method} ${url.pathname} answered ${res.status}${reason ? `: ${reason}` : ""}`, {
          kind: "http", status: res.status, problem, ...where,
        });
      }
      const data: unknown = res.status === 204 ? undefined : await res.json();
      const parsed = opts.schema.safeParse(data);
      if (!parsed.success) {
        throw new ApiError(`${method} ${url.pathname}: unexpected response\n${z.prettifyError(parsed.error)}`, {
          kind: "invalid-response", status: res.status, cause: parsed.error, ...where,
        });
      }
      return parsed.data;
    } catch (error) {
      if (error instanceof ApiError) throw error;
      if (opts.signal?.aborted) throw opts.signal.reason; // the caller cancelled: not our failure
      if (timeout.aborted) {
        throw new ApiError(`${method} ${url.pathname}: no response in ${opts.timeoutMs ?? timeoutMs} ms`, {
          kind: "timeout", cause: error, ...where,
        });
      }
      if (error instanceof SyntaxError) {
        throw new ApiError(`${method} ${url.pathname}: response is not JSON`, { kind: "invalid-response", cause: error, ...where });
      }
      throw new ApiError(`${method} ${url.pathname}: network error`, { kind: "network", cause: error, ...where });
    }
  }

  async function request<S extends z.ZodType>(method: string, path: string, opts: RequestOptions<S>): Promise<z.output<S>> {
    const url = buildUrl(baseUrl, path, opts.query);
    // RFC 9110: repeat automatically only idempotent requests (or ones with an idempotency key)
    const maxAttempts = IDEMPOTENT_METHODS.has(method) || opts.idempotencyKey ? retries + 1 : 1;

    for (let n = 1; ; n++) {
      try {
        return await attempt(method, url, opts);
      } catch (error) {
        const transient =
          error instanceof ApiError &&
          (error.kind === "network" || error.kind === "timeout" || RETRYABLE_STATUS.has(error.status ?? 0));
        if (!transient || n >= maxAttempts) throw error;
        // Simplified pause; Retry-After, jitter and an overall deadline are in the external API lesson
        await sleep(retryDelayMs * 2 ** (n - 1), opts.signal);
      }
    }
  }

  return {
    get: <S extends z.ZodType>(path: string, opts: RequestOptions<S>) => request("GET", path, opts),
    post: <S extends z.ZodType>(path: string, opts: RequestOptions<S>) => request("POST", path, opts),
    put: <S extends z.ZodType>(path: string, opts: RequestOptions<S>) => request("PUT", path, opts),
    patch: <S extends z.ZodType>(path: string, opts: RequestOptions<S>) => request("PATCH", path, opts),
    delete: <S extends z.ZodType>(path: string, opts: RequestOptions<S>) => request("DELETE", path, opts),
  };
}

export type ApiClient = ReturnType<typeof createApiClient>;

import { z } from "zod";
import type { ApiClient } from "./api-client.ts";

// The schema is both the runtime check and the TypeScript type
export const User = z.object({
  id: z.string(),
  name: z.string(),
  email: z.email(),
  createdAt: z.iso.datetime().transform((value) => new Date(value)),
});
export type User = z.output<typeof User>;

const UserPage = z.object({
  items: z.array(User),
  nextCursor: z.string().nullable(),
});

export function makeUsersApi(api: ApiClient) {
  return {
    get: (id: string, signal?: AbortSignal) =>
      api.get(`users/${encodeURIComponent(id)}`, { schema: User, signal }),
    list: (cursor?: string) =>
      api.get("users", { schema: UserPage, query: { cursor, limit: 20 } }),
    // One key per operation: a retry of the same POST does not create a second user
    create: (input: { name: string; email: string }) =>
      api.post("users", { schema: User, body: input, idempotencyKey: crypto.randomUUID() }),
    remove: (id: string) =>
      api.delete(`users/${encodeURIComponent(id)}`, { schema: z.undefined() }), // 204 No Content
  };
}

import { createApiClient } from "./api-client.ts";
import { makeUsersApi } from "./users.ts";

// Composition point: one client per API, typed modules on top of it.
// Where the token comes from (session, refresh flow) is the app's decision.
export function createApi(baseUrl: string, getToken: () => Promise<string | null>) {
  const client = createApiClient({
    baseUrl,
    timeoutMs: 8_000,
    headers: async (): Promise<HeadersInit> => {
      const token = await getToken();
      return token ? { Authorization: `Bearer ${token}` } : {};
    },
  });
  return { users: makeUsersApi(client) };
}

import type { ApiError } from "./api-client.ts";

// User texts come from your own translations, keyed by kind, status and the problem "type" URI.
// "detail" is for logs and debugging: do not parse it and do not show it as is.
export function errorMessage(error: ApiError): string {
  if (error.kind === "timeout" || error.kind === "network") {
    return "The server is not responding. Check the connection and try again.";
  }
  if (error.kind === "invalid-response" || (error.status ?? 500) >= 500) {
    return "Something went wrong on our side. We are already looking into it.";
  }
  if (error.status === 401) return "Your session has expired. Please sign in again.";
  if (error.problem?.type === "https://api.example.com/problems/email-taken") {
    return "This email is already registered.";
  }
  return "The request could not be completed.";
}

import { createServer, type IncomingHttpHeaders, type IncomingMessage, type ServerResponse } from "node:http";
import type { AddressInfo } from "node:net";

export type Handler = (req: IncomingMessage, res: ServerResponse, n: number) => void;
export type Recorded = { method: string; url: string; headers: IncomingHttpHeaders; body: string };

// A real HTTP server on a random local port: the client goes through the network stack
export async function startServer() {
  let handler: Handler = (_req, res) => void res.writeHead(404).end();
  const requests: Recorded[] = [];
  const server = createServer(async (req, res) => {
    let body = "";
    for await (const chunk of req) body += chunk;
    requests.push({ method: req.method ?? "", url: req.url ?? "", headers: req.headers, body });
    handler(req, res, requests.length);
  });
  await new Promise<void>((resolve) => server.listen(0, "127.0.0.1", resolve));
  const { port } = server.address() as AddressInfo;

  return {
    baseUrl: `http://127.0.0.1:${port}/v1`,
    requests,
    handle(next: Handler) {
      handler = next;
      requests.length = 0;
    },
    close: () =>
      new Promise<void>((resolve) => {
        server.closeAllConnections();
        server.close(() => resolve());
      }),
  };
}

export function send(res: ServerResponse, status: number, data: unknown, type = "application/json") {
  if (res.destroyed) return; // the client has already given up
  res.writeHead(status, { "Content-Type": type }).end(typeof data === "string" ? data : JSON.stringify(data));
}

import { createServer } from "node:http";
import type { AddressInfo } from "node:net";
import { afterAll, beforeAll, describe, expect, it } from "vitest";
import { z } from "zod";
import { ApiError, createApiClient } from "../src/api-client.ts";
import { createApi } from "../src/api.ts";
import { errorMessage } from "../src/error-message.ts";
import { send, startServer } from "./server.ts";

let server: Awaited<ReturnType<typeof startServer>>;
beforeAll(async () => {
  server = await startServer();
});
afterAll(() => server.close());

const anna = { id: "u1", name: "Anna", email: "anna@example.com", createdAt: "2026-10-12T09:00:00Z" };
const api = () => createApi(server.baseUrl, async () => "test-token");
const fail = (promise: Promise<unknown>) => promise.then(() => expect.fail("should reject"), (error: unknown) => error);

describe("typed API client", () => {
  it("joins the base URL, sends headers and returns typed data", async () => {
    server.handle((_req, res) => send(res, 200, anna));
    const user = await api().users.get("u1");
    expect(user.createdAt).toBeInstanceOf(Date);
    expect(user.name).toBe("Anna");
    expect(server.requests[0]).toMatchObject({ method: "GET", url: "/v1/users/u1" });
    expect(server.requests[0]!.headers.authorization).toBe("Bearer test-token");
    expect(server.requests[0]!.headers.accept).toBe("application/json, application/problem+json");
  });

  it("puts query parameters into the URL and skips undefined ones", async () => {
    server.handle((_req, res) => send(res, 200, { items: [anna], nextCursor: null }));
    const page = await api().users.list();
    expect(page.items[0]!.email).toBe("anna@example.com");
    expect(server.requests[0]!.url).toBe("/v1/users?limit=20");
  });

  it("rejects a body that does not match the schema and does not retry it", async () => {
    server.handle((_req, res) => send(res, 200, { ...anna, email: "not-an-email" }));
    const error = await fail(api().users.get("u1"));
    expect(error).toBeInstanceOf(ApiError);
    expect(error).toMatchObject({ kind: "invalid-response", status: 200 });
    expect(server.requests).toHaveLength(1);
  });

  it("turns application/problem+json into ApiError and keeps extensions", async () => {
    const problem = {
      type: "https://example.com/probs/out-of-credit",
      title: "You do not have enough credit.",
      detail: "Your current balance is 30, but that costs 50.",
      instance: "/account/12345/msgs/abc",
      balance: 30,
      accounts: ["/account/12345", "/account/67890"],
    };
    server.handle((_req, res) => send(res, 403, problem, "application/problem+json"));
    const client = createApiClient({ baseUrl: server.baseUrl });
    const error = await fail(client.post("purchase", { schema: z.object({}), body: { item: 123456, quantity: 2 } }));
    expect(error).toBeInstanceOf(ApiError);
    expect(error).toMatchObject({ kind: "http", status: 403, problem });
    expect((error as ApiError).message).toBe("POST /v1/purchase answered 403: You do not have enough credit.");
    expect(server.requests[0]!.headers["content-type"]).toBe("application/json");
    expect(JSON.parse(server.requests[0]!.body)).toEqual({ item: 123456, quantity: 2 });
  });

  it("ignores problem members of the wrong type (RFC 9457, section 3.1)", async () => {
    server.handle((_req, res) => send(res, 404, { title: 42, status: "404", detail: "No user u9" }, "application/problem+json"));
    const error = (await fail(api().users.get("u9"))) as ApiError;
    expect(error.problem).toEqual({ type: "about:blank", detail: "No user u9" });
    expect(error.message).toBe("GET /v1/users/u9 answered 404: Not Found");
  });

  it("retries an idempotent GET after 503", async () => {
    server.handle((_req, res, n) => (n === 1 ? send(res, 503, "busy", "text/plain") : send(res, 200, anna)));
    expect((await api().users.get("u1")).id).toBe("u1");
    expect(server.requests).toHaveLength(2);
  });

  it("does not retry POST without an idempotency key", async () => {
    server.handle((_req, res) => send(res, 503, "busy", "text/plain"));
    const client = createApiClient({ baseUrl: server.baseUrl, retryDelayMs: 1 });
    const error = await fail(client.post("orders", { schema: z.object({}), body: {} }));
    expect(error).toMatchObject({ kind: "http", status: 503, problem: undefined });
    expect(server.requests).toHaveLength(1);
  });

  it("retries POST with an idempotency key and sends the same key every time", async () => {
    server.handle((_req, res, n) => (n === 1 ? send(res, 503, "busy", "text/plain") : send(res, 201, anna)));
    const user = await api().users.create({ name: "Anna", email: "anna@example.com" });
    expect(user.id).toBe("u1");
    const keys = server.requests.map((r) => r.headers["idempotency-key"]);
    expect(keys).toHaveLength(2);
    expect(keys[0]).toBeTruthy();
    expect(keys[1]).toBe(keys[0]);
  });

  it("returns undefined for 204 No Content", async () => {
    server.handle((_req, res) => void res.writeHead(204).end());
    await expect(api().users.remove("u1")).resolves.toBeUndefined();
  });

  it("gives up after timeoutMs with kind timeout", async () => {
    server.handle((_req, res) => setTimeout(() => send(res, 200, anna), 300));
    const client = createApiClient({ baseUrl: server.baseUrl, timeoutMs: 50, retries: 0 });
    const error = await fail(client.get("users/u1", { schema: z.unknown() }));
    expect(error).toMatchObject({ kind: "timeout" });
  });

  it("passes the caller's cancellation through as AbortError, without retries", async () => {
    server.handle((_req, res) => setTimeout(() => send(res, 200, anna), 300));
    for (const retries of [0, 2]) {
      const client = createApiClient({ baseUrl: server.baseUrl, retries });
      const controller = new AbortController();
      setTimeout(() => controller.abort(), 30);
      const error = await fail(client.get("users/u1", { schema: z.unknown(), signal: controller.signal }));
      expect(error).not.toBeInstanceOf(ApiError);
      expect((error as Error).name).toBe("AbortError");
    }
    expect(server.requests).toHaveLength(2); // one request per call
  });

  it("reports a non-JSON success body as invalid-response", async () => {
    server.handle((_req, res) => send(res, 200, "<html>maintenance</html>", "text/html"));
    const error = await fail(api().users.get("u1"));
    expect(error).toMatchObject({ kind: "invalid-response" });
  });

  it("maps a problem type to a user message", async () => {
    server.handle((_req, res) =>
      send(res, 409, { type: "https://api.example.com/problems/email-taken", title: "Email taken" }, "application/problem+json"),
    );
    const error = (await fail(api().users.create({ name: "Anna", email: "anna@example.com" }))) as ApiError;
    expect(errorMessage(error)).toBe("This email is already registered.");
  });

  it("reports a refused connection as a network error", async () => {
    const probe = createServer();
    await new Promise<void>((resolve) => probe.listen(0, "127.0.0.1", resolve));
    const { port } = probe.address() as AddressInfo;
    await new Promise<void>((resolve) => probe.close(() => resolve()));
    const client = createApiClient({ baseUrl: `http://127.0.0.1:${port}`, retries: 1, retryDelayMs: 1 });
    const error = await fail(client.get("health", { schema: z.unknown() }));
    expect(error).toMatchObject({ kind: "network" });
  });
});

$ npx tsc -p .
$ npx vitest run --reporter=verbose

RUN  v5.0.3 …

 ✓ test/api-client.test.ts > typed API client > joins the base URL, sends headers and returns typed data 18ms
 ✓ test/api-client.test.ts > typed API client > puts query parameters into the URL and skips undefined ones 3ms
 ✓ test/api-client.test.ts > typed API client > rejects a body that does not match the schema and does not retry it 3ms
 ✓ test/api-client.test.ts > typed API client > turns application/problem+json into ApiError and keeps extensions 5ms
 ✓ test/api-client.test.ts > typed API client > ignores problem members of the wrong type (RFC 9457, section 3.1) 17ms
 ✓ test/api-client.test.ts > typed API client > retries an idempotent GET after 503 231ms
 ✓ test/api-client.test.ts > typed API client > does not retry POST without an idempotency key 16ms
 ✓ test/api-client.test.ts > typed API client > retries POST with an idempotency key and sends the same key every time 246ms
 ✓ test/api-client.test.ts > typed API client > returns undefined for 204 No Content 2ms
 ✓ test/api-client.test.ts > typed API client > gives up after timeoutMs with kind timeout 62ms
 ✓ test/api-client.test.ts > typed API client > passes the caller's cancellation through as AbortError, without retries 76ms
 ✓ test/api-client.test.ts > typed API client > reports a non-JSON success body as invalid-response 2ms
 ✓ test/api-client.test.ts > typed API client > maps a problem type to a user message 2ms
 ✓ test/api-client.test.ts > typed API client > reports a refused connection as a network error 13ms

 Test Files  1 passed (1)
      Tests  14 passed (14)