@ryuzaki13/react-foundation-api 1.1.16 → 1.1.18

package/src/http/README.mdx

@@ -0,0 +1,570 @@
+import { Meta } from "@storybook/addon-docs/blocks";
+
+<Meta title="Foundation API/Transport/HTTP" />
+
+# Обычный HTTP через `@ryuzaki13/react-foundation-api/http`
+
+Модуль выполняет нейтральные HTTP/REST запросы и создаёт функции, совместимые с TanStack Query. Внешний payload остаётся `unknown`, пока consumer явно не проверит его через `parse`.
+
+## Содержание
+
+- [Когда использовать](#когда-использовать)
+- [Импорт](#импорт)
+- [`httpFetch`](#httpfetch)
+- [`httpFetchPayload`](#httpfetchpayload)
+- [`httpJsonQueryFn`](#httpjsonqueryfn)
+- [`httpJsonMutationFn`](#httpjsonmutationfn)
+- [`RouteError`](#routeerror)
+- [Ошибки, runtime и безопасность](#ошибки-runtime-и-безопасность)
+- [Полный API](#полный-api)
+
+## Когда использовать
+
+```text
+обычный REST/HTTP ──► /http
+SAP Gateway/OData ──► /odata
+```
+
+`http` не добавляет SAP headers, `credentials: include`, X-CSRF token, SSO recovery, OData V2 headers и не снимает envelope `{ d: { results } }`. Для SAP/OData используйте [`/odata`](../odata/README.mdx).
+
+Модуль намеренно остаётся небольшим. Он не пытается быть REST framework: выполняет request, проверяет HTTP status, разбирает базовый payload и требует от consumer-а runtime parser.
+
+## Импорт
+
+```ts
+import {
+	httpFetch,
+	httpFetchPayload,
+	httpJsonMutationFn,
+	httpJsonQueryFn,
+	RouteError
+} from "@ryuzaki13/react-foundation-api/http";
+
+import type {
+	HttpMutationFnOptions,
+	HttpQueryFnOptions,
+	HttpRequestOptions
+} from "@ryuzaki13/react-foundation-api/http";
+```
+
+Нужны глобальные Web Fetch API: `fetch`, `Request`, `Response`, `Headers`, `URL`.
+
+## `httpFetch`
+
+```ts
+const response = await httpFetch("/health", {
+	baseUrl: "https://api.example.com",
+	init: {
+		method: "GET",
+		headers: { Accept: "text/plain" }
+	}
+});
+
+console.log(await response.text());
+```
+
+Функция возвращает исходный `Response`, если `response.ok === true`. Body ещё не прочитан.
+
+Для string input URL строится простой конкатенацией:
+
+```text
+baseUrl + input
+```
+
+Helper не исправляет slash:
+
+```ts
+// Правильно.
+{ baseUrl: "https://api.example.com", input: "/users" }
+
+// Получится https://api.example.comusers — неверно.
+{ baseUrl: "https://api.example.com", input: "users" }
+```
+
+Если input является `Request` или `URL`, `baseUrl` игнорируется. Это не proxy/url resolver.
+
+### Полные request options
+
+```ts
+type HttpRequestOptions = {
+	readonly baseUrl?: string;
+	readonly init?: RequestInit;
+};
+```
+
+Caller самостоятельно задаёт method, headers, cookies и signal:
+
+```ts
+const controller = new AbortController();
+
+const request = httpFetch("/profile", {
+	baseUrl: "/api",
+	init: {
+		method: "GET",
+		headers: {
+			Accept: "application/json",
+			Authorization: `Bearer ${token}`
+		},
+		credentials: "include",
+		signal: controller.signal
+	}
+});
+
+controller.abort();
+await request;
+```
+
+Отмена пробрасывается как native fetch error. Модуль не превращает её в специальный класс.
+
+### Зачем возвращать `Response`
+
+Используйте `httpFetch`, а не `httpFetchPayload`, когда нужны headers, Blob, stream или custom parser:
+
+```ts
+const response = await httpFetch("/reports/export.xlsx", {
+	baseUrl: "/api"
+});
+
+const file = await response.blob();
+const disposition = response.headers.get("Content-Disposition");
+```
+
+Response body читается один раз. После `blob()` нельзя повторно вызвать `json()` без предварительного `response.clone()`.
+
+## `httpFetchPayload`
+
+```ts
+const payload: unknown = await httpFetchPayload("/api/profile");
+```
+
+Правила parser-а:
+
+| Response | Результат |
+| --- | --- |
+| status `204` или `205` | `null` |
+| `Content-Type` содержит `application/json` | `response.json()` |
+| любой другой content type | `response.text()` |
+
+Результат намеренно `unknown`. Generic type не может проверить данные, пришедшие по сети:
+
+```ts
+function parseProfile(value: unknown): Profile {
+	if (!isProfile(value)) throw new Error("Некорректный Profile payload");
+	return value;
+}
+
+const profile = parseProfile(await httpFetchPayload("/api/profile"));
+```
+
+Если сервер отдаёт JSON без корректного `Content-Type`, модуль вернёт JSON как string. Исправьте backend или разберите string на своей boundary.
+
+Content-Type приводится к lowercase, но распознаётся только media type, содержащий literal `application/json`. Например, `application/problem+json` будет прочитан как text. Для такого endpoint используйте `httpFetch` с custom parsing либо расширьте общий package contract.
+
+Invalid JSON с header `application/json` приводит к native parsing error. Он не заменяется на `null` или text.
+
+## `httpJsonQueryFn`
+
+Factory возвращает async-функцию с формой TanStack Query `queryFn`:
+
+```ts
+const loadProfile = httpJsonQueryFn("/api/profile", {
+	baseUrl: "https://api.example.com",
+	parse: parseProfile,
+	swCache: "ttl=10m;name=profile"
+});
+
+const profile = await loadProfile({ signal });
+```
+
+С React Query:
+
+```tsx
+const profileQuery = useQuery({
+	queryKey: ["profile", userId],
+	queryFn: httpJsonQueryFn(`/api/users/${userId}`, {
+		parse: parseProfile
+	})
+});
+```
+
+Factory:
+
+- использует `init.signal`, если он задан явно;
+- иначе подставляет signal, переданный TanStack Query;
+- добавляет `x-sw-cache`, только если `swCache` truthy;
+- вызывает обязательный `parse(payload)` после успешного запроса.
+
+Header `x-sw-cache` — только protocol с Service Worker. Без соответствующего SW он не создаёт cache.
+
+`parse` может вернуть преобразованную domain model, но обычно лучше ограничиться runtime validation и вынести бизнес-mapping владельцу entity.
+
+### Почему `parse` обязателен
+
+TypeScript generic исчезает из runtime:
+
+```ts
+// Аннотация User не проверяет network.
+const unsafe = httpJsonQueryFn<User>("/api/user", {
+	parse: (payload) => payload as User
+});
+```
+
+Минимальный parser:
+
+```ts
+function parseUser(payload: unknown): User {
+	if (!payload || typeof payload !== "object") {
+		throw new Error("User response должен быть object");
+	}
+
+	const record = payload as Record<string, unknown>;
+	if (typeof record.id !== "string" || typeof record.name !== "string") {
+		throw new Error("User response содержит неверные поля");
+	}
+
+	return { id: record.id, name: record.name };
+}
+```
+
+Для сложной формы используйте project-approved runtime schema validator.
+
+### Stable query options
+
+```ts
+import { queryOptions } from "@tanstack/react-query";
+
+const userKeys = {
+	all: ["users"] as const,
+	detail: (id: string) => [...userKeys.all, "detail", id] as const
+};
+
+export const userQueryOptions = (id: string) =>
+	queryOptions({
+		queryKey: userKeys.detail(id),
+		queryFn: httpJsonQueryFn(
+			`/api/users/${encodeURIComponent(id)}`,
+			{
+				parse: parseUser,
+				swCache: "off"
+			}
+		),
+		enabled: id.length > 0
+	});
+```
+
+Все inputs, меняющие response, должны быть в query key. URL encoding остаётся обязанностью caller-а.
+
+### AbortSignal priority
+
+Если `options.init.signal` отсутствует, factory подставляет signal TanStack Query. Если explicit signal уже задан, он имеет приоритет и QueryClient cancellation его не заменит.
+
+### Service Worker header
+
+Factory создаёт новый `Headers` object и выставляет `x-sw-cache`, когда `swCache` truthy. Если такой header уже был в `init.headers`, option `swCache` перезапишет его.
+
+Сам header ничего не кэширует без Service Worker, который реализует protocol. Для auth-sensitive responses используйте `off`, пока isolation users/sessions явно не доказана.
+
+## `httpJsonMutationFn`
+
+```ts
+type CreateUserInput = { name: string };
+
+const createUser = httpJsonMutationFn<CreateUserInput, User>("/api/users", {
+	method: "POST",
+	mapBody: (input) => ({ displayName: input.name }),
+	parse: parseUser
+});
+
+const user = await createUser({ name: "Анна" });
+```
+
+С `useMutation`:
+
+```tsx
+const mutation = useMutation({ mutationFn: createUser });
+mutation.mutate({ name: "Анна" });
+```
+
+Поведение:
+
+1. Вычисляет body через `mapBody(input)` или использует input.
+2. Сериализует body через `JSON.stringify`.
+3. Использует method `POST` по умолчанию; поддерживаются `POST`, `PUT`, `PATCH`, `DELETE`.
+4. Добавляет `Content-Type: application/json`, только если header ещё не задан.
+5. Выполняет запрос и передаёт payload в обязательный `parse`.
+
+Сигнатура mutation function также допускает второй `AbortSignal` при ручном вызове. Стандартный `useMutation` TanStack Query не передаёт signal автоматически. Если `options.init.signal` уже задан, второй signal не заменит его.
+
+`JSON.stringify` может бросить ошибку для `BigInt`/циклического объекта. `undefined` body сериализуется в `undefined`; убедитесь, что это соответствует endpoint.
+
+### Полные mutation options
+
+```ts
+type HttpMutationFnOptions<TInput, TResult> = HttpRequestOptions & {
+	readonly method?: "POST" | "PUT" | "PATCH" | "DELETE";
+	readonly mapBody?: (input: TInput) => unknown;
+	readonly parse: (data: unknown) => TResult;
+};
+```
+
+### Mapping input в body
+
+```ts
+type UpdateProfileInput = {
+	userId: string;
+	draft: {
+		name: string;
+		email: string;
+	};
+};
+
+const updateProfile = httpJsonMutationFn<UpdateProfileInput, User>(
+	"/api/profile",
+	{
+		method: "PATCH",
+		mapBody: ({ draft }) => ({
+			displayName: draft.name,
+			emailAddress: draft.email
+		}),
+		parse: parseUser
+	}
+);
+```
+
+URL factory фиксирован при создании. Если path зависит от input, создайте feature wrapper, который внутри строит подходящий mutation function или вызывает `httpFetchPayload`.
+
+### Особенность nullish body mapper
+
+Implementation выбирает body так:
+
+```ts
+const body = options.mapBody?.(input) ?? input;
+```
+
+Если `mapBody` вернул `null` или `undefined`, будет сериализован исходный input. Mapper не может этим способом создать body `null` или пустой body.
+
+Для endpoint, которому действительно нужен `null`, передайте `null` как input без mapper-а. Для запроса без body используйте `httpFetchPayload`.
+
+### Content-Type
+
+`application/json` добавляется только при отсутствии header. Custom media type сохраняется:
+
+```ts
+const patchResource = httpJsonMutationFn("/api/resource", {
+	method: "PATCH",
+	init: {
+		headers: {
+			"Content-Type": "application/merge-patch+json"
+		}
+	},
+	parse: parseResource
+});
+```
+
+### Cache после mutation
+
+Factory не знает query keys и ничего не инвалидирует:
+
+```tsx
+const queryClient = useQueryClient();
+
+const mutation = useMutation({
+	mutationFn: updateProfile,
+	onSuccess: (updated) => {
+		queryClient.setQueryData(userKeys.detail(updated.id), updated);
+		void queryClient.invalidateQueries({ queryKey: userKeys.all });
+	}
+});
+```
+
+Query cache хранит server snapshot. Не используйте object из cache как mutable form draft.
+
+### Manual abort mutation
+
+```ts
+const controller = new AbortController();
+const promise = updateProfile(input, controller.signal);
+controller.abort();
+await promise;
+```
+
+`useMutation` сам не передаёт AbortSignal. Не переиспользуйте уже aborted controller.
+
+## HTTP errors
+
+Для `response.ok === false` обе низкоуровневые функции бросают обычный `Error`:
+
+```text
+HTTP error: <message>
+```
+
+Если error body — непустой text, он становится message. Для JSON error object поля `message`, `error` и `details` не извлекаются; fallback — `<status> <statusText>`.
+
+Network error/CORS/abort от глобального `fetch` пробрасывается без обёртки.
+
+При non-2xx transport читает error body, чтобы построить message. Consumer уже не получает этот Response.
+
+Для JSON error object поля не анализируются:
+
+```json
+{
+	"message": "Нет доступа"
+}
+```
+
+При status `403` message будет fallback `HTTP error: 403 Forbidden`, потому что parsed payload является object, а не string.
+
+Модуль не повторяет request. Retry policy принадлежит TanStack Query или caller. Обычный `Error` из `httpFetch` не содержит числовой status, поэтому status-aware retry требует отдельного project error contract.
+
+## `RouteError`
+
+```ts
+throw new RouteError(404);
+```
+
+Это маленький `Error` с числовым полем `status` и пустым message. `httpFetch` сам его не создаёт. Класс нужен для routing/error-boundary policy приложения, если оно договорилось понимать такой error.
+
+```ts
+async function profileLoader() {
+	const profile = await loadProfile();
+	if (!profile) throw new RouteError(404);
+	return profile;
+}
+```
+
+`Object.setPrototypeOf` внутри class обеспечивает надёжный `instanceof RouteError`. Класс не содержит response body, headers или `cause` и не заменяет полноценную structured transport error.
+
+## Тестирование
+
+```ts
+import { afterEach, expect, it, vi } from "vitest";
+import {
+	httpFetchPayload,
+	httpJsonQueryFn
+} from "@ryuzaki13/react-foundation-api/http";
+
+afterEach(() => vi.unstubAllGlobals());
+
+it("разбирает JSON payload", async () => {
+	vi.stubGlobal(
+		"fetch",
+		vi.fn().mockResolvedValue(
+			new Response(JSON.stringify({ id: "u-1", name: "Анна" }), {
+				status: 200,
+				headers: { "Content-Type": "application/json" }
+			})
+		)
+	);
+
+	await expect(httpFetchPayload("/api/user")).resolves.toEqual({
+		id: "u-1",
+		name: "Анна"
+	});
+});
+
+it("отклоняет неверный runtime shape", async () => {
+	vi.stubGlobal(
+		"fetch",
+		vi.fn().mockResolvedValue(
+			new Response(JSON.stringify({ id: 10 }), {
+				status: 200,
+				headers: { "Content-Type": "application/json" }
+			})
+		)
+	);
+
+	const queryFn = httpJsonQueryFn("/api/user", { parse: parseUser });
+	await expect(queryFn()).rejects.toThrow(
+		"User response содержит неверные поля"
+	);
+});
+```
+
+Проверяйте минимум:
+
+- string `baseUrl + path`;
+- Request/URL input игнорирует baseUrl;
+- 204/205 возвращает `null`;
+- JSON и text parsing;
+- invalid JSON;
+- non-2xx error message;
+- explicit signal priority;
+- `x-sw-cache` header;
+- `mapBody` и JSON serialization;
+- custom Content-Type;
+- feature cache strategy после mutation.
+
+## Частые ошибки
+
+### Generic вместо runtime parser
+
+`payload as User` только заставляет TypeScript поверить разработчику.
+
+### Неверные slashes
+
+URL соединяется простой конкатенацией. Придерживайтесь одной convention.
+
+### Ожидать SAP side effects
+
+`/http` не добавляет CSRF, SSO, SAP client или OData envelope parser.
+
+### Вернуть `null` из `mapBody`
+
+Из-за `?? input` будет отправлен исходный input.
+
+### Ожидать automatic invalidation
+
+Mutation factory не знает query keys. Стратегию cache задаёт owner ресурса.
+
+### Отправлять FormData через JSON factory
+
+`httpJsonMutationFn` всегда вызывает `JSON.stringify`. Для FormData используйте `httpFetch`.
+
+## Ошибки, runtime и безопасность
+
+- TypeScript generic не валидирует сеть; используйте `parse`/schema guard.
+- `baseUrl` и path не нормализуются и не кодируются.
+- Authorization, cookies, CORS и retry задаёт consumer через `init` или внешний слой.
+- Модуль не делает timeout. Для него используйте `AbortController`.
+- Не помещайте token/secret в query string и cache key.
+- `x-sw-cache` для персональных данных требует изолированной cache policy.
+- На SSR абсолютный/относительный URL и cookies должны быть настроены server runtime-ом.
+
+## FAQ
+
+### Чем `httpFetchPayload` отличается от `fetch(...).json()`?
+
+Он проверяет `response.ok`, понимает 204/205 и выбирает JSON/text по Content-Type.
+
+### Можно ли скачать Blob?
+
+Да: `httpFetch`, затем `response.blob()`.
+
+### Можно ли отправить FormData?
+
+Да через `httpFetch`. JSON mutation factory для этого не подходит.
+
+### Как задать timeout?
+
+Передайте signal от `AbortSignal.timeout(...)` в поддерживаемой среде или используйте `AbortController`.
+
+### Почему JSON query может получить text/null?
+
+Low-level parser допускает эти shapes, а обязательный `parse` определяет валидный result endpoint-а.
+
+### Где хранить query keys?
+
+Рядом с public API entity/feature либо в `/resource`, если нужен generic descriptor.
+
+## Полный API
+
+| Export | Результат |
+| --- | --- |
+| `httpFetch` | Успешный `Response` |
+| `httpFetchPayload` | JSON/text/`null` как `unknown` |
+| `httpJsonQueryFn` | Query-compatible async function |
+| `httpJsonMutationFn` | Mutation-compatible async function |
+| `RouteError` | Error с `status` |
+| `HttpRequestOptions` | `baseUrl` и `init` |
+| `HttpQueryFnOptions` | Request options + `swCache` + `parse` |
+| `HttpMutationFnOptions` | Request options + method/body mapper/parse |