@ryuzaki13/react-foundation-ui 1.8.12 → 1.8.14

package/storybook-static/assets/README-BUwRENpH.js

@@ -0,0 +1,448 @@
+import{n as e}from"./rolldown-runtime-DkW27tQK.js";import{n as t}from"./iframe--RU38UHO.js";import{i as n,r}from"./react-Bl2r1tuC.js";import{l as i,m as a}from"./blocks-DcVVTXzf.js";function o(e){let t={a:`a`,code:`code`,h1:`h1`,h2:`h2`,h3:`h3`,li:`li`,p:`p`,pre:`pre`,table:`table`,tbody:`tbody`,td:`td`,th:`th`,thead:`thead`,tr:`tr`,ul:`ul`,...n(),...e.components};return(0,c.jsxs)(c.Fragment,{children:[(0,c.jsx)(i,{title:`Foundation API/Adapters/Server Function`}),`
+`,(0,c.jsxs)(t.h1,{id:`server-function-adapters-через-ryuzaki13react-foundation-apiserver-fn`,children:[`Server-function adapters через `,(0,c.jsx)(t.code,{children:`@ryuzaki13/react-foundation-api/server-fn`})]}),`
+`,(0,c.jsxs)(t.p,{children:[`Модуль адаптирует функцию с публичной формой `,(0,c.jsx)(t.code,{children:`serverFn({ data })`}),` к query/mutation operation из `,(0,c.jsx)(t.a,{href:`../resource/README.mdx`,children:(0,c.jsx)(t.code,{children:`/resource`})}),`. Сам пакет не импортирует TanStack Start и не запускает сервер.`]}),`
+`,(0,c.jsx)(t.h2,{id:`модель`,children:`Модель`}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-text`,children:`scope + args/input
+        │ buildData
+        ▼
+     { data }
+        │ serverFn или custom executor
+        ▼
+     response
+        │ optional transform
+        ▼
+ resource operation result
+`})}),`
+`,(0,c.jsx)(t.p,{children:`Подходит любая async-функция такого контракта:`}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`type ServerFnTransport<TData, TResponse> = (
+	request: { data: TData }
+) => Promise<TResponse>;
+`})}),`
+`,(0,c.jsxs)(t.p,{children:[`Название `,(0,c.jsx)(t.code,{children:`server-fn`}),` описывает типичный источник функции. Оно не гарантирует server-only выполнение и не создаёт security boundary.`]}),`
+`,(0,c.jsx)(t.p,{children:`Для начинающего разработчика:`}),`
+`,(0,c.jsxs)(t.ul,{children:[`
+`,(0,c.jsxs)(t.li,{children:[(0,c.jsx)(t.code,{children:`serverFn`}),` — transport function framework-а;`]}),`
+`,(0,c.jsxs)(t.li,{children:[(0,c.jsx)(t.code,{children:`buildData`}),` — явный mapper application inputs в transport DTO;`]}),`
+`,(0,c.jsxs)(t.li,{children:[(0,c.jsx)(t.code,{children:`transform`}),` — mapper transport response в application result;`]}),`
+`,(0,c.jsxs)(t.li,{children:[`resource operation — описание того, как generic `,(0,c.jsx)(t.code,{children:`/resource`}),` должен выполнить query/mutation.`]}),`
+`]}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-text`,children:`React component
+    │ useResourceQuery/useResourceMutation
+    ▼
+resource descriptor
+    │ execute context
+    ▼
+server-fn adapter
+    │ { data }
+    ▼
+framework server function stub
+    │ network/server boundary framework-а
+    ▼
+server handler
+`})}),`
+`,(0,c.jsxs)(t.p,{children:[`Этот package адаптирует только участок `,(0,c.jsx)(t.code,{children:`execute context → { data }`}),`. Он не реализует network protocol framework-а.`]}),`
+`,(0,c.jsx)(t.h2,{id:`импорт`,children:`Импорт`}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`import {
+	createServerFnMutationOperation,
+	createServerFnQueryOperation
+} from "@ryuzaki13/react-foundation-api/server-fn";
+
+import type {
+	ServerFnTransport,
+	ServerFnTransportExecutor,
+	ServerFnTransportExecutorContext,
+	ServerFnTransportRequest
+} from "@ryuzaki13/react-foundation-api/server-fn";
+`})}),`
+`,(0,c.jsxs)(t.p,{children:[`Нужен `,(0,c.jsx)(t.code,{children:`@tanstack/react-query`}),`; созданные operations обычно подключаются через `,(0,c.jsx)(t.code,{children:`/resource`}),` или `,(0,c.jsx)(t.code,{children:`/persisted`}),` descriptor.`]}),`
+`,(0,c.jsx)(t.p,{children:`Пакет не имеет root import. Не импортируйте внутренний файл:`}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`// Правильно.
+import { createServerFnQueryOperation } from "@ryuzaki13/react-foundation-api/server-fn";
+
+// Неправильно.
+import { createServerFnQueryOperation } from "@ryuzaki13/react-foundation-api/src/server-fn/serverFn";
+`})}),`
+`,(0,c.jsx)(t.h2,{id:`query-operation`,children:`Query operation`}),`
+`,(0,c.jsx)(t.p,{children:`Предположим, сгенерированная framework-функция принимает:`}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`type LoadOrdersData = {
+	companyId: string;
+	search: string;
+};
+
+declare const loadOrdersServerFn: ServerFnTransport<
+	LoadOrdersData,
+	{ items: OrderDto[] }
+>;
+`})}),`
+`,(0,c.jsx)(t.p,{children:`Adapter:`}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`const searchOrdersOperation = createServerFnQueryOperation({
+	serverFn: loadOrdersServerFn,
+	buildData: (companyId: string, args: { search: string }) => ({
+		companyId,
+		search: args.search
+	}),
+	transform: (response) => response.items.map(mapOrderDto),
+	staleTime: 60_000,
+	gcTime: 5 * 60_000,
+	isEnabled: (companyId, args) => Boolean(companyId && args.search.trim())
+});
+`})}),`
+`,(0,c.jsxs)(t.p,{children:[(0,c.jsx)(t.code,{children:`buildData`}),` получает валидный scope и query args. `,(0,c.jsx)(t.code,{children:`transform`}),` получает response и `,(0,c.jsx)(t.code,{children:`{ scope, args }`}),`; без transform result равен response.`]}),`
+`,(0,c.jsxs)(t.p,{children:[`Созданный объект соответствует `,(0,c.jsx)(t.code,{children:`ResourceQueryOperation`}),`:`]}),`
+`,(0,c.jsxs)(t.ul,{children:[`
+`,(0,c.jsxs)(t.li,{children:[(0,c.jsx)(t.code,{children:`execute({ scope, args, client, signal })`}),`;`]}),`
+`,(0,c.jsxs)(t.li,{children:[`optional `,(0,c.jsx)(t.code,{children:`isEnabled`}),`;`]}),`
+`,(0,c.jsxs)(t.li,{children:[`optional `,(0,c.jsx)(t.code,{children:`staleTime`}),`;`]}),`
+`,(0,c.jsxs)(t.li,{children:[`optional `,(0,c.jsx)(t.code,{children:`gcTime`}),`.`]}),`
+`]}),`
+`,(0,c.jsx)(t.h3,{id:`полный-query-lifecycle`,children:`Полный query lifecycle`}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-text`,children:`Resource проверяет scope/isEnabled
+          │
+          ▼
+operation.execute({ scope, args, client, signal })
+          │
+          ▼
+buildData(scope, args)
+          │
+          ▼
+executor(serverFn, { data }, { client, signal })
+          │
+          ▼
+server response
+          │
+          ├─ transform задан ──► transform(response, { scope, args })
+          └─ transform нет ────► response
+`})}),`
+`,(0,c.jsxs)(t.p,{children:[(0,c.jsx)(t.code,{children:`buildData`}),` вызывается на каждом фактическом execute, а не при создании descriptor-а.`]}),`
+`,(0,c.jsx)(t.h3,{id:`scope-args-и-data--разные-вещи`,children:`Scope, args и data — разные вещи`}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`type Scope = string; // companyId
+type Args = { search: string; page: number };
+type Data = {
+	company: string;
+	query: string;
+	offset: number;
+};
+`})}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`buildData: (companyId, args) => ({
+	company: companyId,
+	query: args.search.trim(),
+	offset: args.page * 50
+})
+`})}),`
+`,(0,c.jsx)(t.p,{children:`Не передавайте args как data автоматически: имена/форматы transport DTO могут отличаться, а scope часто должен попасть внутрь request.`}),`
+`,(0,c.jsx)(t.h3,{id:`isenabled`,children:(0,c.jsx)(t.code,{children:`isEnabled`})}),`
+`,(0,c.jsx)(t.p,{children:`Callback получает nullable scope, потому что hook может быть вызван до готовности route/form state:`}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`isEnabled: (companyId, args) =>
+	Boolean(companyId && args.search.trim().length >= 2)
+`})}),`
+`,(0,c.jsxs)(t.p,{children:[`Сам adapter просто сохраняет callback в operation. Проверку выполняет `,(0,c.jsx)(t.code,{children:`/resource`}),` при построении query options. Не вызывайте `,(0,c.jsx)(t.code,{children:`operation.execute`}),` вручную с invalid scope и не ожидайте, что `,(0,c.jsx)(t.code,{children:`isEnabled`}),` внутри остановит его.`]}),`
+`,(0,c.jsxs)(t.h3,{id:`staletime-и-gctime`,children:[(0,c.jsx)(t.code,{children:`staleTime`}),` и `,(0,c.jsx)(t.code,{children:`gcTime`})]}),`
+`,(0,c.jsx)(t.p,{children:`Это hints TanStack Query lifecycle, а не transport timeout:`}),`
+`,(0,c.jsxs)(t.ul,{children:[`
+`,(0,c.jsxs)(t.li,{children:[(0,c.jsx)(t.code,{children:`staleTime`}),` — сколько snapshot считается fresh;`]}),`
+`,(0,c.jsxs)(t.li,{children:[(0,c.jsx)(t.code,{children:`gcTime`}),` — когда неактивный snapshot можно удалить;`]}),`
+`,(0,c.jsx)(t.li,{children:`они не прерывают network request;`}),`
+`,(0,c.jsx)(t.li,{children:`они не определяют server cache.`}),`
+`]}),`
+`,(0,c.jsx)(t.h3,{id:`transform-и-runtime-validation`,children:`Transform и runtime validation`}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`transform: (response, { scope, args }) => {
+	if (!response || !Array.isArray(response.items)) {
+		throw new Error("ServerFn response не содержит items");
+	}
+
+	return response.items.map((item) => mapOrderDto(item, scope, args));
+}
+`})}),`
+`,(0,c.jsx)(t.p,{children:`TypeScript generic не проверяет response framework-а. Если server/client могут иметь разные versions или endpoint получает внешние данные, выполняйте runtime validation.`}),`
+`,(0,c.jsxs)(t.p,{children:[`Ошибка `,(0,c.jsx)(t.code,{children:`buildData`}),`, executor или transform становится query error.`]}),`
+`,(0,c.jsx)(t.h2,{id:`mutation-operation`,children:`Mutation operation`}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`declare const saveOrderServerFn: ServerFnTransport<
+	{ companyId: string; order: SaveOrderDto },
+	{ order: OrderDto }
+>;
+
+const saveOrderOperation = createServerFnMutationOperation({
+	serverFn: saveOrderServerFn,
+	buildData: (companyId: string, input: SaveOrderInput) => ({
+		companyId,
+		order: mapSaveOrder(input)
+	}),
+	transform: (response) => mapOrderDto(response.order),
+	cacheStrategy: createInvalidateResourceScopeCacheStrategy()
+});
+`})}),`
+`,(0,c.jsxs)(t.p,{children:[(0,c.jsx)(t.code,{children:`transform`}),` получает `,(0,c.jsx)(t.code,{children:`{ scope, input }`}),`. `,(0,c.jsx)(t.code,{children:`cacheStrategy`}),` прикрепляется к operation и выполняется владельцем resource mutation после успешного ответа.`]}),`
+`,(0,c.jsxs)(t.p,{children:[`Mutation operation не имеет `,(0,c.jsx)(t.code,{children:`AbortSignal`}),` в generic resource contract. Custom executor получает `,(0,c.jsx)(t.code,{children:`{ client }`}),` без signal.`]}),`
+`,(0,c.jsx)(t.h3,{id:`полный-mutation-lifecycle`,children:`Полный mutation lifecycle`}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-text`,children:`useResourceMutation(...).mutate(input)
+          │
+          ▼
+operation.execute({ scope, input, client })
+          │
+          ▼
+buildData(scope, input)
+          │
+          ▼
+executor(serverFn, { data }, { client })
+          │
+          ▼
+optional transform(response, { scope, input })
+          │
+          ▼
+resource применяет cacheStrategy
+`})}),`
+`,(0,c.jsxs)(t.p,{children:[`Cache strategy выполняется только после успешного `,(0,c.jsx)(t.code,{children:`execute`}),`. Если `,(0,c.jsx)(t.code,{children:`transform`}),` бросил error, mutation считается failed и strategy не должна применяться.`]}),`
+`,(0,c.jsx)(t.h3,{id:`body-mapping-без-mutation-input-leakage`,children:`Body mapping без mutation input leakage`}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`type SaveOrderInput = {
+	localDraftId: string;
+	name: string;
+	amount: number;
+};
+
+buildData: (companyId, input) => ({
+	companyId,
+	order: {
+		name: input.name.trim(),
+		amount: input.amount
+	}
+})
+`})}),`
+`,(0,c.jsxs)(t.p,{children:[(0,c.jsx)(t.code,{children:`localDraftId`}),` не уходит на server, если он не является частью transport contract.`]}),`
+`,(0,c.jsx)(t.h3,{id:`cache-strategy-выбирается-явно`,children:`Cache strategy выбирается явно`}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`cacheStrategy: createInvalidateResourceScopeCacheStrategy()
+`})}),`
+`,(0,c.jsxs)(t.p,{children:[`или точечный `,(0,c.jsx)(t.code,{children:`setQueryData`}),` strategy из `,(0,c.jsx)(t.code,{children:`/resource`}),`. Adapter только прикрепляет strategy к operation; выполняет её resource mutation layer.`]}),`
+`,(0,c.jsx)(t.p,{children:`Без strategy server mutation может успешно завершиться, но cached lists/details останутся stale.`}),`
+`,(0,c.jsx)(t.h2,{id:`подключение-к-resource-descriptor`,children:`Подключение к resource descriptor`}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`const ordersResource = createResourceDescriptor({
+	namespace: "sales",
+	resource: "orders",
+	operations: {
+		queries: { search: searchOrdersOperation },
+		mutations: { save: saveOrderOperation }
+	}
+});
+
+const query = useResourceQuery(
+	ordersResource,
+	"search",
+	companyId,
+	{ search }
+);
+`})}),`
+`,(0,c.jsxs)(t.p,{children:[(0,c.jsx)(t.code,{children:`server-fn`}),` не экспортирует resource hooks повторно. Импортируйте их из `,(0,c.jsx)(t.code,{children:`@ryuzaki13/react-foundation-api/resource`}),`.`]}),`
+`,(0,c.jsx)(t.h3,{id:`полный-descriptor-example`,children:`Полный descriptor example`}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`import {
+	createResourceDescriptor,
+	useResourceMutation,
+	useResourceQuery
+} from "@ryuzaki13/react-foundation-api/resource";
+import {
+	createServerFnMutationOperation,
+	createServerFnQueryOperation
+} from "@ryuzaki13/react-foundation-api/server-fn";
+
+const ordersResource = createResourceDescriptor({
+	namespace: "sales",
+	resource: "orders",
+	operations: {
+		queries: {
+			search: createServerFnQueryOperation({
+				serverFn: loadOrdersServerFn,
+				buildData: (companyId: string, args: { search: string }) => ({
+					companyId,
+					search: args.search
+				}),
+				transform: (response) => response.items.map(mapOrderDto),
+				isEnabled: (scope, args) => Boolean(scope && args.search.trim())
+			})
+		},
+		mutations: {
+			save: createServerFnMutationOperation({
+				serverFn: saveOrderServerFn,
+				buildData: (companyId: string, input: SaveOrderInput) => ({
+					companyId,
+					order: mapSaveOrder(input)
+				}),
+				transform: (response) => mapOrderDto(response.order),
+				cacheStrategy: createInvalidateResourceScopeCacheStrategy()
+			})
+		}
+	}
+});
+
+function Orders({ companyId, search }: { companyId: string; search: string }) {
+	const orders = useResourceQuery(
+		ordersResource,
+		"search",
+		companyId,
+		{ search }
+	);
+
+	const save = useResourceMutation(
+		ordersResource,
+		"save",
+		companyId
+	);
+
+	// render loading/error/data and invoke save.mutate(input)
+}
+`})}),`
+`,(0,c.jsx)(t.h2,{id:`custom-executor`,children:`Custom executor`}),`
+`,(0,c.jsx)(t.p,{children:`По умолчанию adapter вызывает только:`}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`serverFn({ data })
+`})}),`
+`,(0,c.jsxs)(t.p,{children:[(0,c.jsx)(t.code,{children:`QueryClient`}),` и `,(0,c.jsx)(t.code,{children:`AbortSignal`}),` не передаются внутрь `,(0,c.jsx)(t.code,{children:`serverFn`}),`. Если transport/framework умеет использовать дополнительный context, задайте executor:`]}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`const executor: ServerFnTransportExecutor<Input, Output> = async (
+	serverFn,
+	request,
+	{ signal }
+) => {
+	if (signal?.aborted) throw signal.reason;
+	return serverFn(request);
+};
+
+const operation = createServerFnQueryOperation({
+	serverFn,
+	buildData,
+	executor
+});
+`})}),`
+`,(0,c.jsxs)(t.p,{children:[`Executor получает саму функцию, нормализованный request `,(0,c.jsx)(t.code,{children:`{ data }`}),` и `,(0,c.jsx)(t.code,{children:`{ client, signal? }`}),`. Он полезен для tracing, тестов и framework adapter-а. Не используйте его для бизнес-логики конкретной entity.`]}),`
+`,(0,c.jsx)(t.h3,{id:`default-executor`,children:`Default executor`}),`
+`,(0,c.jsxs)(t.p,{children:[`Без option `,(0,c.jsx)(t.code,{children:`executor`}),` фактически выполняется:`]}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`await serverFn({ data });
+`})}),`
+`,(0,c.jsxs)(t.p,{children:[(0,c.jsx)(t.code,{children:`client`}),` и `,(0,c.jsx)(t.code,{children:`signal`}),` доступны adapter layer, но не добавляются в transport data.`]}),`
+`,(0,c.jsx)(t.h3,{id:`tracing-executor`,children:`Tracing executor`}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`const tracingExecutor: ServerFnTransportExecutor<Input, Output> = async (
+	serverFn,
+	request,
+	context
+) => {
+	const startedAt = performance.now();
+
+	try {
+		if (context.signal?.aborted) {
+			throw context.signal.reason;
+		}
+
+		return await serverFn(request);
+	} finally {
+		console.debug("serverFn duration", performance.now() - startedAt);
+	}
+};
+`})}),`
+`,(0,c.jsxs)(t.p,{children:[`Не логируйте `,(0,c.jsx)(t.code,{children:`request.data`}),` целиком: он может содержать personal/auth-sensitive fields.`]}),`
+`,(0,c.jsx)(t.h3,{id:`test-executor`,children:`Test executor`}),`
+`,(0,c.jsx)(t.p,{children:`Custom executor позволяет проверить request без real framework runtime:`}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`const executor = vi.fn(async (_serverFn, request) => ({
+	items: [{ id: request.data.companyId }]
+}));
+
+const operation = createServerFnQueryOperation({
+	serverFn: vi.fn(),
+	buildData: (scope: string, args: { search: string }) => ({
+		companyId: scope,
+		search: args.search
+	}),
+	executor
+});
+`})}),`
+`,(0,c.jsx)(t.h2,{id:`security-boundary`,children:`Security boundary`}),`
+`,(0,c.jsxs)(t.p,{children:[`Public client type `,(0,c.jsx)(t.code,{children:`{ data }`}),` не означает, что data доверена. Server handler обязан повторно выполнить:`]}),`
+`,(0,c.jsxs)(t.ul,{children:[`
+`,(0,c.jsx)(t.li,{children:`authentication;`}),`
+`,(0,c.jsx)(t.li,{children:`authorization на scope/entity/action;`}),`
+`,(0,c.jsx)(t.li,{children:`runtime schema validation;`}),`
+`,(0,c.jsx)(t.li,{children:`ограничения размера/частоты;`}),`
+`,(0,c.jsx)(t.li,{children:`sanitization перед DB/HTML/logs;`}),`
+`,(0,c.jsx)(t.li,{children:`безопасную обработку errors.`}),`
+`]}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-text`,children:`TypeScript type на client ≠ проверенный server input
+`})}),`
+`,(0,c.jsxs)(t.p,{children:[`Не передавайте secrets server-а в `,(0,c.jsx)(t.code,{children:`buildData`}),`: этот mapper выполняется на client side operation boundary.`]}),`
+`,(0,c.jsx)(t.h2,{id:`query-cache-и-server-cache`,children:`Query cache и server cache`}),`
+`,(0,c.jsx)(t.p,{children:`Resource query key владеет identity client snapshot. ServerFn/framework может дополнительно кэшировать server response, но это другой слой.`}),`
+`,(0,c.jsx)(t.p,{children:`После mutation:`}),`
+`,(0,c.jsxs)(t.ul,{children:[`
+`,(0,c.jsx)(t.li,{children:`resource cache strategy синхронизирует QueryClient;`}),`
+`,(0,c.jsx)(t.li,{children:`server-side invalidation управляется framework/backend;`}),`
+`,(0,c.jsx)(t.li,{children:`одно не заменяет другое.`}),`
+`]}),`
+`,(0,c.jsx)(t.h2,{id:`тестирование`,children:`Тестирование`}),`
+`,(0,c.jsx)(t.h3,{id:`query-operation-1`,children:`Query operation`}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`it("строит { data } и преобразует response", async () => {
+	const serverFn = vi.fn(async ({ data }) => ({
+		items: [{ id: data.companyId }]
+	}));
+
+	const operation = createServerFnQueryOperation({
+		serverFn,
+		buildData: (scope: string, args: { search: string }) => ({
+			companyId: scope,
+			search: args.search
+		}),
+		transform: (response) => response.items
+	});
+
+	const result = await operation.execute({
+		scope: "1000",
+		args: { search: "test" },
+		client: queryClient,
+		signal: new AbortController().signal
+	});
+
+	expect(serverFn).toHaveBeenCalledWith({
+		data: { companyId: "1000", search: "test" }
+	});
+	expect(result).toEqual([{ id: "1000" }]);
+});
+`})}),`
+`,(0,c.jsx)(t.p,{children:`Проверяйте:`}),`
+`,(0,c.jsxs)(t.ul,{children:[`
+`,(0,c.jsx)(t.li,{children:`buildData получает scope и args/input;`}),`
+`,(0,c.jsxs)(t.li,{children:[`serverFn получает ровно `,(0,c.jsx)(t.code,{children:`{ data }`}),`;`]}),`
+`,(0,c.jsx)(t.li,{children:`transform context правильный;`}),`
+`,(0,c.jsx)(t.li,{children:`без transform response возвращается как есть;`}),`
+`,(0,c.jsx)(t.li,{children:`query executor видит signal;`}),`
+`,(0,c.jsx)(t.li,{children:`mutation executor не получает signal;`}),`
+`,(0,c.jsx)(t.li,{children:`errors mapper/executor/transform пробрасываются;`}),`
+`,(0,c.jsx)(t.li,{children:`cache strategy прикреплена к mutation operation;`}),`
+`,(0,c.jsxs)(t.li,{children:[(0,c.jsx)(t.code,{children:`isEnabled`}),`, `,(0,c.jsx)(t.code,{children:`staleTime`}),`, `,(0,c.jsx)(t.code,{children:`gcTime`}),` сохранены в query operation.`]}),`
+`]}),`
+`,(0,c.jsx)(t.h2,{id:`частые-ошибки`,children:`Частые ошибки`}),`
+`,(0,c.jsx)(t.h3,{id:`выполнять-serverfn-при-создании-operation`,children:`Выполнять serverFn при создании operation`}),`
+`,(0,c.jsx)(t.p,{children:`Factory должна получить функцию, а не Promise/result.`}),`
+`,(0,c.jsx)(t.h3,{id:`смешивать-transport-dto-и-domain-model`,children:`Смешивать transport DTO и domain model`}),`
+`,(0,c.jsxs)(t.p,{children:[`Используйте `,(0,c.jsx)(t.code,{children:`buildData`}),` и `,(0,c.jsx)(t.code,{children:`transform`}),` как явные boundaries.`]}),`
+`,(0,c.jsx)(t.h3,{id:`хранить-бизнес-логику-в-generic-executor`,children:`Хранить бизнес-логику в generic executor`}),`
+`,(0,c.jsx)(t.p,{children:`Executor — infrastructure wrapper. Entity mapping принадлежит operation/owner entity.`}),`
+`,(0,c.jsx)(t.h3,{id:`ожидать-cache-update-без-strategy`,children:`Ожидать cache update без strategy`}),`
+`,(0,c.jsx)(t.p,{children:`Mutation operation сама не угадывает затронутые queries.`}),`
+`,(0,c.jsxs)(t.h3,{id:`передавать-signal-внутрь--data-`,children:[`Передавать signal внутрь `,(0,c.jsx)(t.code,{children:`{ data }`})]}),`
+`,(0,c.jsx)(t.p,{children:`AbortSignal не сериализуемый business payload. Используйте executor/framework capability.`}),`
+`,(0,c.jsx)(t.h2,{id:`типичные-ошибки`,children:`Типичные ошибки`}),`
+`,(0,c.jsx)(t.h3,{id:`передавать-args-напрямую`,children:`Передавать args напрямую`}),`
+`,(0,c.jsxs)(t.p,{children:[`Неверно предполагать, что query args автоматически становятся data. Их явно преобразует `,(0,c.jsx)(t.code,{children:`buildData`}),`, потому что scope/args и transport DTO — разные контракты.`]}),`
+`,(0,c.jsx)(t.h3,{id:`ожидать-автоматическую-отмену`,children:`Ожидать автоматическую отмену`}),`
+`,(0,c.jsxs)(t.p,{children:[`Default executor не передаёт signal в функцию, поскольку её публичный contract содержит только `,(0,c.jsx)(t.code,{children:`{ data }`}),`. Отмена TanStack Query остановит дальнейшее использование результата на уровне query, но transport должен поддерживать abort отдельно.`]}),`
+`,(0,c.jsx)(t.h3,{id:`считать-функцию-доверенной`,children:`Считать функцию доверенной`}),`
+`,(0,c.jsx)(t.p,{children:`Если функция вызывается из browser bundle, её input контролирует пользователь. Backend обязан повторно проверить authentication, authorization и payload schema.`}),`
+`,(0,c.jsx)(t.h3,{id:`использовать-без-descriptor-а`,children:`Использовать без descriptor-а`}),`
+`,(0,c.jsxs)(t.p,{children:[`Factory возвращает operation, а не готовый React hook. Подключите её к resource/persisted descriptor или вызовите `,(0,c.jsx)(t.code,{children:`execute`}),` через корректный orchestration layer.`]}),`
+`,(0,c.jsx)(t.h2,{id:`faq`,children:`FAQ`}),`
+`,(0,c.jsx)(t.h3,{id:`обязательно-ли-использовать-tanstack-start`,children:`Обязательно ли использовать TanStack Start?`}),`
+`,(0,c.jsxs)(t.p,{children:[`Нет. Подходит любая async function с contract `,(0,c.jsx)(t.code,{children:`({ data }) => Promise<response>`}),`.`]}),`
+`,(0,c.jsxs)(t.h3,{id:`где-выполняется-builddata`,children:[`Где выполняется `,(0,c.jsx)(t.code,{children:`buildData`}),`?`]}),`
+`,(0,c.jsx)(t.p,{children:`На стороне, где выполняется resource operation, обычно в client bundle.`}),`
+`,(0,c.jsx)(t.h3,{id:`передаётся-ли-queryclient-в-serverfn`,children:`Передаётся ли QueryClient в serverFn?`}),`
+`,(0,c.jsx)(t.p,{children:`Нет. Только custom executor получает QueryClient как infrastructure context.`}),`
+`,(0,c.jsx)(t.h3,{id:`работает-ли-query-cancellation`,children:`Работает ли query cancellation?`}),`
+`,(0,c.jsx)(t.p,{children:`Signal доходит до executor. Default serverFn contract его не использует; реальный abort зависит от framework/custom executor.`}),`
+`,(0,c.jsx)(t.h3,{id:`почему-mutation-не-получает-signal`,children:`Почему mutation не получает signal?`}),`
+`,(0,c.jsxs)(t.p,{children:[`Таков generic `,(0,c.jsx)(t.code,{children:`ResourceMutationOperation`}),` contract. Если нужен abort, проектируйте отдельный controlled transport boundary.`]}),`
+`,(0,c.jsx)(t.h3,{id:`можно-ли-вернуть-domain-model-из-transform`,children:`Можно ли вернуть domain model из transform?`}),`
+`,(0,c.jsx)(t.p,{children:`Да. Generic result type будет выведен из transform.`}),`
+`,(0,c.jsx)(t.h2,{id:`полный-api`,children:`Полный API`}),`
+`,(0,c.jsxs)(t.table,{children:[(0,c.jsx)(t.thead,{children:(0,c.jsxs)(t.tr,{children:[(0,c.jsx)(t.th,{children:`Export`}),(0,c.jsx)(t.th,{children:`Назначение`})]})}),(0,c.jsxs)(t.tbody,{children:[(0,c.jsxs)(t.tr,{children:[(0,c.jsx)(t.td,{children:(0,c.jsx)(t.code,{children:`createServerFnQueryOperation`})}),(0,c.jsx)(t.td,{children:`Создаёт read operation, optional transform/lifetime/isEnabled`})]}),(0,c.jsxs)(t.tr,{children:[(0,c.jsx)(t.td,{children:(0,c.jsx)(t.code,{children:`createServerFnMutationOperation`})}),(0,c.jsx)(t.td,{children:`Создаёт write operation, optional transform/cache strategy`})]}),(0,c.jsxs)(t.tr,{children:[(0,c.jsx)(t.td,{children:(0,c.jsx)(t.code,{children:`ServerFnTransport`})}),(0,c.jsxs)(t.td,{children:[`Контракт функции `,(0,c.jsx)(t.code,{children:`(request) => Promise`})]})]}),(0,c.jsxs)(t.tr,{children:[(0,c.jsx)(t.td,{children:(0,c.jsx)(t.code,{children:`ServerFnTransportRequest`})}),(0,c.jsxs)(t.td,{children:[`Обёртка `,(0,c.jsx)(t.code,{children:`{ data }`})]})]}),(0,c.jsxs)(t.tr,{children:[(0,c.jsx)(t.td,{children:(0,c.jsx)(t.code,{children:`ServerFnTransportExecutor`})}),(0,c.jsx)(t.td,{children:`Контракт custom execution`})]}),(0,c.jsxs)(t.tr,{children:[(0,c.jsx)(t.td,{children:(0,c.jsx)(t.code,{children:`ServerFnTransportExecutorContext`})}),(0,c.jsxs)(t.td,{children:[(0,c.jsx)(t.code,{children:`QueryClient`}),` и optional signal`]})]})]})]})]})}function s(e={}){let{wrapper:t}={...n(),...e.components};return t?(0,c.jsx)(t,{...e,children:(0,c.jsx)(o,{...e})}):o(e)}var c;function l(){return(l=e((()=>{c=t(),r(),a()})))()}l();export{s as default};