@ryuzaki13/react-foundation-ui 1.8.12 → 1.8.13

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

@@ -1,273 +0,0 @@
-import{n as e}from"./rolldown-runtime-DkW27tQK.js";import{n as t}from"./iframe-FSp_AjJa.js";import{i as n,r}from"./react-Bl2r1tuC.js";import{l as i,m as a}from"./blocks-B5YBxaaS.js";function o(e){let t={a:`a`,code:`code`,h1:`h1`,h2:`h2`,h3:`h3`,li:`li`,p:`p`,pre:`pre`,strong:`strong`,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/Query/Generic Resource`}),`
-`,(0,c.jsxs)(t.h1,{id:`generic-resources-через-ryuzaki13react-foundation-apiresource`,children:[`Generic resources через `,(0,c.jsx)(t.code,{children:`@ryuzaki13/react-foundation-api/resource`})]}),`
-`,(0,c.jsx)(t.p,{children:`Модуль описывает transport-agnostic ресурс поверх TanStack Query: стабильные query keys, проверку scope, произвольные read/write operations и cache strategies после mutation.`}),`
-`,(0,c.jsx)(t.h2,{id:`для-кого-этот-документ`,children:`Для кого этот документ`}),`
-`,(0,c.jsx)(t.p,{children:`Здесь термины используются так:`}),`
-`,(0,c.jsxs)(t.ul,{children:[`
-`,(0,c.jsxs)(t.li,{children:[(0,c.jsx)(t.strong,{children:`resource`}),` — технически связанная группа данных, например `,(0,c.jsx)(t.code,{children:`orders`}),`;`]}),`
-`,(0,c.jsxs)(t.li,{children:[(0,c.jsx)(t.strong,{children:`scope`}),` — контекст, внутри которого данные уникальны, например `,(0,c.jsx)(t.code,{children:`{ companyId }`}),`;`]}),`
-`,(0,c.jsxs)(t.li,{children:[(0,c.jsx)(t.strong,{children:`query/read operation`}),` — чтение без изменения server state;`]}),`
-`,(0,c.jsxs)(t.li,{children:[(0,c.jsx)(t.strong,{children:`mutation/write operation`}),` — создание/изменение/удаление;`]}),`
-`,(0,c.jsxs)(t.li,{children:[(0,c.jsx)(t.strong,{children:`descriptor`}),` — объект, объединяющий identity, operations и правила доступности;`]}),`
-`,(0,c.jsxs)(t.li,{children:[(0,c.jsx)(t.strong,{children:`query key`}),` — сериализуемый identity записи в TanStack Query cache.`]}),`
-`]}),`
-`,(0,c.jsxs)(t.p,{children:[`Модуль не выполняет HTTP/OData сам. Transport находится внутри `,(0,c.jsx)(t.code,{children:`operation.execute`}),` или создаётся adapter-ом `,(0,c.jsx)(t.code,{children:`/server-fn`}),`.`]}),`
-`,(0,c.jsx)(t.h2,{id:`когда-использовать`,children:`Когда использовать`}),`
-`,(0,c.jsxs)(t.p,{children:[`Используйте `,(0,c.jsx)(t.code,{children:`/resource`}),`, когда названия операций произвольны: `,(0,c.jsx)(t.code,{children:`search`}),`, `,(0,c.jsx)(t.code,{children:`detail`}),`, `,(0,c.jsx)(t.code,{children:`archive`}),`, `,(0,c.jsx)(t.code,{children:`recalculate`}),`.`]}),`
-`,(0,c.jsxs)(t.p,{children:[`Для стандартной модели сохранённых записей `,(0,c.jsx)(t.code,{children:`list/latest/history/save/create/delete`}),` удобнее `,(0,c.jsx)(t.a,{href:`../persisted/README.mdx`,children:(0,c.jsx)(t.code,{children:`/persisted`})}),`.`]}),`
-`,(0,c.jsx)(t.h2,{id:`установка-и-provider`,children:`Установка и provider`}),`
-`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-bash`,children:`npm install @ryuzaki13/react-foundation-api @ryuzaki13/react-foundation-lib @tanstack/react-query react
-`})}),`
-`,(0,c.jsxs)(t.p,{children:[`React hooks работают только внутри `,(0,c.jsx)(t.code,{children:`QueryClientProvider`}),`:`]}),`
-`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-tsx`,children:`import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
-
-const queryClient = new QueryClient();
-
-export function App() {
-	return <QueryClientProvider client={queryClient}>{/* routes */}</QueryClientProvider>;
-}
-`})}),`
-`,(0,c.jsx)(t.p,{children:`Создайте client один раз, а не внутри render.`}),`
-`,(0,c.jsx)(t.h2,{id:`импорт`,children:`Импорт`}),`
-`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`import {
-	applyResourceCacheStrategy,
-	buildResourceQueryOptions,
-	composeResourceCacheStrategies,
-	createInvalidateResourceScopeCacheStrategy,
-	createResourceDescriptor,
-	createResourceKeys,
-	createResourceMutationOperation,
-	createResourceQueryOperation,
-	createSetResourceQueryDataCacheStrategy,
-	getResourceQueryData,
-	normalizeResourceKeyValue,
-	useResourceMutation,
-	useResourceQuery
-} from "@ryuzaki13/react-foundation-api/resource";
-`})}),`
-`,(0,c.jsx)(t.p,{children:`Типы экспортируются из того же subpath.`}),`
-`,(0,c.jsx)(t.h2,{id:`пошаговый-пример`,children:`Пошаговый пример`}),`
-`,(0,c.jsx)(t.h3,{id:`1-описать-scope-и-данные`,children:`1. Описать scope и данные`}),`
-`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`type OrdersScope = {
-	companyId: string;
-};
-
-type SearchOrdersArgs = {
-	search: string;
-	limit: number;
-};
-
-type Order = {
-	id: string;
-	title: string;
-};
-
-type SaveOrderInput = {
-	id: string;
-	title: string;
-};
-`})}),`
-`,(0,c.jsx)(t.h3,{id:`2-создать-operations`,children:`2. Создать operations`}),`
-`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`const searchOperation = createResourceQueryOperation<
-	OrdersScope,
-	SearchOrdersArgs,
-	Order[]
->({
-	async execute({ scope, args, signal }) {
-		const query = new URLSearchParams({
-			companyId: scope.companyId,
-			search: args.search,
-			limit: String(args.limit)
-		});
-
-		const response = await fetch(\`/api/orders?\${query}\`, { signal });
-		if (!response.ok) throw new Error(\`HTTP \${response.status}\`);
-		return response.json() as Promise<Order[]>;
-	},
-	isEnabled: (scope, args) => Boolean(scope?.companyId && args.limit > 0),
-	staleTime: 60_000,
-	gcTime: 5 * 60_000
-});
-
-const saveOperation = createResourceMutationOperation<
-	OrdersScope,
-	SaveOrderInput,
-	Order,
-	unknown
->({
-	async execute({ scope, input }) {
-		const response = await fetch(\`/api/companies/\${scope.companyId}/orders/\${input.id}\`, {
-			method: "PUT",
-			headers: { "Content-Type": "application/json" },
-			body: JSON.stringify(input)
-		});
-
-		if (!response.ok) throw new Error(\`HTTP \${response.status}\`);
-		return response.json() as Promise<Order>;
-	}
-});
-`})}),`
-`,(0,c.jsxs)(t.p,{children:[`Factories `,(0,c.jsx)(t.code,{children:`createResourceQueryOperation`}),` и `,(0,c.jsx)(t.code,{children:`createResourceMutationOperation`}),` не изменяют объект. Они помогают TypeScript сохранить generic types.`]}),`
-`,(0,c.jsx)(t.h3,{id:`3-создать-descriptor`,children:`3. Создать descriptor`}),`
-`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`const ordersResource = createResourceDescriptor({
-	namespace: "sales",
-	resource: "orders",
-	normalizeScope: (scope: OrdersScope | null | undefined) => ({
-		companyId: scope?.companyId.trim() ?? ""
-	}),
-	operations: {
-		queries: { search: searchOperation },
-		mutations: { save: saveOperation }
-	},
-	isEnabled: (scope) => Boolean(scope?.companyId),
-	getScopeError: () => "Не выбрана компания"
-});
-`})}),`
-`,(0,c.jsxs)(t.p,{children:[(0,c.jsx)(t.code,{children:`namespace + resource`}),` должны быть устойчивыми и уникальными. Не включайте локализованные labels или случайные значения.`]}),`
-`,(0,c.jsxs)(t.p,{children:[(0,c.jsx)(t.code,{children:`normalizeScope`}),` влияет только на query key. В `,(0,c.jsx)(t.code,{children:`execute`}),` приходит исходный literal scope. Например, key получит trimmed `,(0,c.jsx)(t.code,{children:`companyId`}),`, но operation увидит строку ровно в переданном object. Это позволяет нормализовать identity, не переписывая draft/input.`]}),`
-`,(0,c.jsx)(t.h3,{id:`4-использовать-query-hook`,children:`4. Использовать query hook`}),`
-`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-tsx`,children:`function OrdersList({ companyId, search }: Props) {
-	const query = useResourceQuery(
-		ordersResource,
-		"search",
-		{ companyId },
-		{ search, limit: 50 }
-	);
-
-	if (query.isPending) return <p>Загрузка…</p>;
-	if (query.isError) return <p>Ошибка загрузки</p>;
-
-	return query.data.map((order) => <div key={order.id}>{order.title}</div>);
-}
-`})}),`
-`,(0,c.jsx)(t.p,{children:`Rules of Hooks применяются полностью: hook нельзя вызывать условно или в callback.`}),`
-`,(0,c.jsx)(t.h3,{id:`5-использовать-mutation-hook`,children:`5. Использовать mutation hook`}),`
-`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-tsx`,children:`const mutation = useResourceMutation(
-	ordersResource,
-	"save",
-	{ companyId },
-	{
-		onSuccess(savedOrder) {
-			showSuccess(\`Сохранён \${savedOrder.title}\`);
-		}
-	}
-);
-
-mutation.mutate({ id: "42", title: "Новый заголовок" });
-`})}),`
-`,(0,c.jsxs)(t.p,{children:[`Mutation key содержит resource/scope/operation, но не input. Input передаётся только в `,(0,c.jsx)(t.code,{children:`mutationFn`}),`.`]}),`
-`,(0,c.jsx)(t.h2,{id:`query-lifecycle`,children:`Query lifecycle`}),`
-`,(0,c.jsxs)(t.p,{children:[(0,c.jsx)(t.code,{children:`buildResourceQueryOptions(descriptor, name, scope, args)`}),` создаёт TanStack `,(0,c.jsx)(t.code,{children:`queryOptions`}),`:`]}),`
-`,(0,c.jsxs)(t.ul,{children:[`
-`,(0,c.jsxs)(t.li,{children:[`key из `,(0,c.jsx)(t.code,{children:`descriptor.keys.operation`}),`;`]}),`
-`,(0,c.jsxs)(t.li,{children:[`query function с `,(0,c.jsx)(t.code,{children:`{ scope, args, client, signal }`}),`;`]}),`
-`,(0,c.jsxs)(t.li,{children:[(0,c.jsx)(t.code,{children:`enabled`}),` из descriptor и operation;`]}),`
-`,(0,c.jsxs)(t.li,{children:[(0,c.jsx)(t.code,{children:`staleTime`}),`/`,(0,c.jsx)(t.code,{children:`gcTime`}),` из operation.`]}),`
-`]}),`
-`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`const options = buildResourceQueryOptions(
-	ordersResource,
-	"search",
-	{ companyId: "1000" },
-	{ search: "", limit: 50 }
-);
-`})}),`
-`,(0,c.jsxs)(t.p,{children:[(0,c.jsx)(t.code,{children:`enabled`}),` сначала проверяет `,(0,c.jsx)(t.code,{children:`descriptor.isEnabled(scope)`}),`, затем `,(0,c.jsx)(t.code,{children:`operation.isEnabled(scope, args)`}),`. Если одна проверка вернула `,(0,c.jsx)(t.code,{children:`false`}),`, React query не стартует автоматически.`]}),`
-`,(0,c.jsxs)(t.p,{children:[`Перед фактическим `,(0,c.jsx)(t.code,{children:`execute`}),` scope обязан быть не `,(0,c.jsx)(t.code,{children:`null`}),`/`,(0,c.jsx)(t.code,{children:`undefined`}),` и пройти descriptor policy. Иначе выбрасывается `,(0,c.jsx)(t.code,{children:`getScopeError`}),` или стандартная ошибка.`]}),`
-`,(0,c.jsx)(t.h2,{id:`императивная-загрузка`,children:`Императивная загрузка`}),`
-`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`const orders = await getResourceQueryData(
-	ordersResource,
-	"search",
-	{ companyId: "1000" },
-	{ search: "", limit: 50 },
-	queryClient
-);
-`})}),`
-`,(0,c.jsxs)(t.p,{children:[`Функция использует `,(0,c.jsx)(t.code,{children:`queryClient.fetchQuery`}),`, поэтому переиспользует query cache. Передавайте только валидный scope: imperative `,(0,c.jsx)(t.code,{children:`fetchQuery`}),` нельзя воспринимать как disabled React observer; query function всё равно защищает scope и может бросить ошибку.`]}),`
-`,(0,c.jsx)(t.h2,{id:`query-keys`,children:`Query keys`}),`
-`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`const keys = createResourceKeys<OrdersScope, "search" | "save">({
-	namespace: "sales",
-	resource: "orders",
-	normalizeScope: (scope) => ({ companyId: scope?.companyId ?? "" })
-});
-
-keys.all;
-// ["sales", "orders"]
-
-keys.scope({ companyId: "1000" });
-// ["sales", "orders", { companyId: "1000" }]
-
-keys.operation("search", { companyId: "1000" }, { limit: 50 });
-// ["sales", "orders", { companyId: "1000" }, "search", { limit: 50 }]
-`})}),`
-`,(0,c.jsxs)(t.p,{children:[(0,c.jsx)(t.code,{children:`args === undefined`}),` не добавляется в key. `,(0,c.jsx)(t.code,{children:`args === null`}),` добавляется как `,(0,c.jsx)(t.code,{children:`null`}),`.`]}),`
-`,(0,c.jsx)(t.h3,{id:`normalizeresourcekeyvalue`,children:(0,c.jsx)(t.code,{children:`normalizeResourceKeyValue`})}),`
-`,(0,c.jsx)(t.p,{children:`Нормализация рекурсивна:`}),`
-`,(0,c.jsxs)(t.ul,{children:[`
-`,(0,c.jsxs)(t.li,{children:[(0,c.jsx)(t.code,{children:`null`}),` и `,(0,c.jsx)(t.code,{children:`undefined`}),` → `,(0,c.jsx)(t.code,{children:`null`}),`;`]}),`
-`,(0,c.jsxs)(t.li,{children:[`string → `,(0,c.jsx)(t.code,{children:`trim()`}),`;`]}),`
-`,(0,c.jsx)(t.li,{children:`number/boolean остаются без изменения;`}),`
-`,(0,c.jsx)(t.li,{children:`array нормализуется по элементам, порядок сохраняется;`}),`
-`,(0,c.jsx)(t.li,{children:`object keys сортируются, значения нормализуются;`}),`
-`,(0,c.jsxs)(t.li,{children:[`другие значения превращаются через `,(0,c.jsx)(t.code,{children:`String(value)`}),`.`]}),`
-`]}),`
-`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`normalizeResourceKeyValue({ b: " x ", a: undefined });
-// { a: null, b: "x" }
-`})}),`
-`,(0,c.jsx)(t.p,{children:`Ограничения:`}),`
-`,(0,c.jsxs)(t.ul,{children:[`
-`,(0,c.jsxs)(t.li,{children:[(0,c.jsx)(t.code,{children:`Date`}),`, `,(0,c.jsx)(t.code,{children:`Map`}),`, `,(0,c.jsx)(t.code,{children:`Set`}),` и class instances не имеют специальной сериализации; обычный `,(0,c.jsx)(t.code,{children:`Date`}),` превратится в `,(0,c.jsx)(t.code,{children:`{}`}),`;`]}),`
-`,(0,c.jsx)(t.li,{children:`cyclic object приведёт к рекурсивной ошибке;`}),`
-`,(0,c.jsxs)(t.li,{children:[(0,c.jsx)(t.code,{children:`NaN`}),`/`,(0,c.jsx)(t.code,{children:`Infinity`}),` остаются number, но их cache semantics могут быть неочевидны;`]}),`
-`,(0,c.jsx)(t.li,{children:`function/symbol/bigint превращаются в строки и могут collision-иться.`}),`
-`]}),`
-`,(0,c.jsx)(t.p,{children:`Нормализуйте специальные значения сами, например Date → ISO string. Query key не должен содержать secrets, DOM nodes или огромные payload.`}),`
-`,(0,c.jsx)(t.h2,{id:`cache-strategies-после-mutation`,children:`Cache strategies после mutation`}),`
-`,(0,c.jsx)(t.h3,{id:`инвалидация-scope`,children:`Инвалидация scope`}),`
-`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`const invalidateScope = createInvalidateResourceScopeCacheStrategy();
-`})}),`
-`,(0,c.jsxs)(t.p,{children:[`Стратегия вызывает `,(0,c.jsx)(t.code,{children:`client.invalidateQueries`}),` по `,(0,c.jsx)(t.code,{children:`descriptor.keys.scope(scope)`}),`. Все query этого resource/scope становятся stale и активные observers могут refetch.`]}),`
-`,(0,c.jsxs)(t.h3,{id:`точечный-setquerydata`,children:[`Точечный `,(0,c.jsx)(t.code,{children:`setQueryData`})]}),`
-`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`const updateDetail = createSetResourceQueryDataCacheStrategy<
-	OrdersScope,
-	SaveOrderInput,
-	Order,
-	Order[],
-	typeof ordersResource
->({
-	getQueryKey: ({ descriptor, scope }) =>
-		descriptor.keys.operation("search", scope, { search: "", limit: 50 }),
-	update: (current = [], { result }) =>
-		current.map((order) => (order.id === result.id ? result : order))
-});
-`})}),`
-`,(0,c.jsxs)(t.p,{children:[(0,c.jsx)(t.code,{children:`update`}),` получает текущее cache data или `,(0,c.jsx)(t.code,{children:`undefined`}),`, а также descriptor/scope/input/result/client. Оно должно возвращать новое значение и не мутировать старое.`]}),`
-`,(0,c.jsx)(t.h3,{id:`композиция`,children:`Композиция`}),`
-`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`const strategy = composeResourceCacheStrategies(
-	updateDetail,
-	invalidateScope
-);
-`})}),`
-`,(0,c.jsxs)(t.p,{children:[`Strategies выполняются последовательно в переданном порядке. Если одна бросила ошибку, следующие и custom `,(0,c.jsx)(t.code,{children:`onSuccess`}),` mutation hook не выполнятся; сама server mutation при этом уже могла успешно завершиться.`]}),`
-`,(0,c.jsx)(t.h3,{id:`override-в-hook`,children:`Override в hook`}),`
-`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`useResourceMutation(descriptor, "save", scope, {
-	cacheStrategy: undefined // Использовать strategy операции.
-});
-
-useResourceMutation(descriptor, "save", scope, {
-	cacheStrategy: null // Полностью отключить strategy операции.
-});
-`})}),`
-`,(0,c.jsxs)(t.p,{children:[`Переданная strategy заменяет operation strategy, а не дополняет её. Для объединения используйте `,(0,c.jsx)(t.code,{children:`composeResourceCacheStrategies`}),`.`]}),`
-`,(0,c.jsxs)(t.p,{children:[(0,c.jsx)(t.code,{children:`applyResourceCacheStrategy(strategy, context)`}),` — низкоуровневый helper для ручного применения optional strategy.`]}),`
-`,(0,c.jsx)(t.h2,{id:`ошибки-и-границы`,children:`Ошибки и границы`}),`
-`,(0,c.jsxs)(t.ul,{children:[`
-`,(0,c.jsx)(t.li,{children:`Отсутствующая operation даёт раннюю ошибку с именем resource/operation.`}),`
-`,(0,c.jsxs)(t.li,{children:[`Невалидный scope блокирует hook через `,(0,c.jsx)(t.code,{children:`enabled`}),`, но ручное выполнение бросает ошибку.`]}),`
-`,(0,c.jsx)(t.li,{children:`Error transport-а сохраняется TanStack Query без автоматического преобразования.`}),`
-`,(0,c.jsx)(t.li,{children:`Descriptor лучше создавать на уровне module, чтобы ссылка не менялась на каждом render.`}),`
-`,(0,c.jsx)(t.li,{children:`Args/scope должны быть сериализуемыми и описывать все данные, влияющие на query result.`}),`
-`,(0,c.jsx)(t.li,{children:`Не используйте query cache как authoritative persistent storage.`}),`
-`,(0,c.jsx)(t.li,{children:`Cache strategy выполняется только после успешной mutation.`}),`
-`]}),`
-`,(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:`Группа`}),(0,c.jsx)(t.th,{children:`Exports`})]})}),(0,c.jsxs)(t.tbody,{children:[(0,c.jsxs)(t.tr,{children:[(0,c.jsx)(t.td,{children:`Descriptor/operations`}),(0,c.jsxs)(t.td,{children:[(0,c.jsx)(t.code,{children:`createResourceDescriptor`}),`, `,(0,c.jsx)(t.code,{children:`createResourceQueryOperation`}),`, `,(0,c.jsx)(t.code,{children:`createResourceMutationOperation`})]})]}),(0,c.jsxs)(t.tr,{children:[(0,c.jsx)(t.td,{children:`Query/mutation`}),(0,c.jsxs)(t.td,{children:[(0,c.jsx)(t.code,{children:`buildResourceQueryOptions`}),`, `,(0,c.jsx)(t.code,{children:`useResourceQuery`}),`, `,(0,c.jsx)(t.code,{children:`getResourceQueryData`}),`, `,(0,c.jsx)(t.code,{children:`useResourceMutation`})]})]}),(0,c.jsxs)(t.tr,{children:[(0,c.jsx)(t.td,{children:`Keys`}),(0,c.jsxs)(t.td,{children:[(0,c.jsx)(t.code,{children:`normalizeResourceKeyValue`}),`, `,(0,c.jsx)(t.code,{children:`createResourceKeys`}),`, `,(0,c.jsx)(t.code,{children:`ResourceKeyValue`}),`, `,(0,c.jsx)(t.code,{children:`ResourceKeys`})]})]}),(0,c.jsxs)(t.tr,{children:[(0,c.jsx)(t.td,{children:`Cache`}),(0,c.jsxs)(t.td,{children:[(0,c.jsx)(t.code,{children:`applyResourceCacheStrategy`}),`, `,(0,c.jsx)(t.code,{children:`createInvalidateResourceScopeCacheStrategy`}),`, `,(0,c.jsx)(t.code,{children:`createSetResourceQueryDataCacheStrategy`}),`, `,(0,c.jsx)(t.code,{children:`composeResourceCacheStrategies`})]})]}),(0,c.jsxs)(t.tr,{children:[(0,c.jsx)(t.td,{children:`Contracts`}),(0,c.jsxs)(t.td,{children:[(0,c.jsx)(t.code,{children:`ResourceQueryOperationContext`}),`, `,(0,c.jsx)(t.code,{children:`ResourceMutationOperationContext`}),`, `,(0,c.jsx)(t.code,{children:`ResourceQueryOperation`}),`, `,(0,c.jsx)(t.code,{children:`ResourceMutationOperation`}),`, `,(0,c.jsx)(t.code,{children:`ResourceDescriptor`}),`, `,(0,c.jsx)(t.code,{children:`CreateResourceDescriptorOptions`}),`, `,(0,c.jsx)(t.code,{children:`ResourceCacheStrategyContext`}),`, `,(0,c.jsx)(t.code,{children:`ResourceCacheStrategy`}),`, `,(0,c.jsx)(t.code,{children:`UseResourceMutationOptions`}),`, `,(0,c.jsx)(t.code,{children:`ResourceSetQueryDataStrategyOptions`})]})]}),(0,c.jsxs)(t.tr,{children:[(0,c.jsx)(t.td,{children:`Type extraction`}),(0,c.jsxs)(t.td,{children:[(0,c.jsx)(t.code,{children:`ResourceQueryArgs`}),`, `,(0,c.jsx)(t.code,{children:`ResourceQueryResult`}),`, `,(0,c.jsx)(t.code,{children:`ResourceMutationInput`}),`, `,(0,c.jsx)(t.code,{children:`ResourceMutationResult`})]})]})]})]})]})}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};

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

@@ -1,103 +0,0 @@
-import{n as e}from"./rolldown-runtime-DkW27tQK.js";import{n as t}from"./iframe-FSp_AjJa.js";import{i as n,r}from"./react-Bl2r1tuC.js";import{l as i,m as a}from"./blocks-B5YBxaaS.js";function o(e){let t={code:`code`,h1:`h1`,h2:`h2`,li:`li`,ol:`ol`,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/Errors/Error Report Delivery`}),`
-`,(0,c.jsxs)(t.h1,{id:`доставка-error-reports-через-ryuzaki13react-foundation-apierror-report`,children:[`Доставка error reports через `,(0,c.jsx)(t.code,{children:`@ryuzaki13/react-foundation-api/error-report`})]}),`
-`,(0,c.jsxs)(t.p,{children:[`Модуль превращает сохранённый черновик отчёта из `,(0,c.jsx)(t.code,{children:`foundation-lib`}),` в delivery body, вызывает adapter приложения и обновляет статус черновика.`]}),`
-`,(0,c.jsx)(t.h2,{id:`граница-ответственности`,children:`Граница ответственности`}),`
-`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-text`,children:`foundation-lib/error-report        foundation-api/error-report       host backend adapter
-collect + sanitize + draft store ──► lifecycle + delivery body ─────► HTTP/OData/serverFn
-`})}),`
-`,(0,c.jsxs)(t.p,{children:[`Модуль не собирает browser diagnostics, не выбирает endpoint и не отправляет запрос самостоятельно. Transport явно передаёт приложение через `,(0,c.jsx)(t.code,{children:`adapter`}),`.`]}),`
-`,(0,c.jsx)(t.h2,{id:`установка-и-импорт`,children:`Установка и импорт`}),`
-`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`import {
-	createErrorReportDeliveryBody,
-	sendErrorReport
-} from "@ryuzaki13/react-foundation-api/error-report";
-
-import type {
-	ErrorReportDeliveryAdapter,
-	ErrorReportDeliveryBody,
-	ErrorReportDeliveryContext,
-	SendErrorReportOptions
-} from "@ryuzaki13/react-foundation-api/error-report";
-`})}),`
-`,(0,c.jsxs)(t.p,{children:[`Нужны `,(0,c.jsx)(t.code,{children:`@ryuzaki13/react-foundation-lib`}),` и `,(0,c.jsx)(t.code,{children:`@tanstack/react-query`}),`.`]}),`
-`,(0,c.jsx)(t.h2,{id:`полный-сценарий`,children:`Полный сценарий`}),`
-`,(0,c.jsxs)(t.p,{children:[`Сначала другой слой создаёт и сохраняет draft средствами `,(0,c.jsx)(t.code,{children:`@ryuzaki13/react-foundation-lib/error-report`}),`. Затем API-слой получает только его `,(0,c.jsx)(t.code,{children:`reportId`}),`:`]}),`
-`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`import { httpFetchPayload } from "@ryuzaki13/react-foundation-api/http";
-import { sendErrorReport } from "@ryuzaki13/react-foundation-api/error-report";
-import type { ErrorReportDeliveryAdapter } from "@ryuzaki13/react-foundation-api/error-report";
-
-const deliveryAdapter: ErrorReportDeliveryAdapter = async (body) => {
-	await httpFetchPayload("/api/error-reports", {
-		init: {
-			method: "POST",
-			headers: { "Content-Type": "application/json" },
-			body: JSON.stringify(body)
-		}
-	});
-};
-
-await sendErrorReport(reportId, {
-	adapter: deliveryAdapter,
-	queryClient
-});
-`})}),`
-`,(0,c.jsx)(t.h2,{id:`createerrorreportdeliverybody`,children:(0,c.jsx)(t.code,{children:`createErrorReportDeliveryBody`})}),`
-`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`const body = createErrorReportDeliveryBody(draft);
-`})}),`
-`,(0,c.jsx)(t.p,{children:`Результат:`}),`
-`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`type ErrorReportDeliveryBody = {
-	reportId: string;
-	sessionId: string;
-	createdUtc: string;
-	category: ErrorReportCategory;
-	errorClass: string;
-	errorMessage: string;
-	stackTrace?: string;
-	payload: string;
-};
-`})}),`
-`,(0,c.jsxs)(t.p,{children:[(0,c.jsx)(t.code,{children:`payload`}),` — JSON string всего payload черновика, а не вложенный object. Это важно для backend contract.`]}),`
-`,(0,c.jsxs)(t.p,{children:[`Если `,(0,c.jsx)(t.code,{children:`draft.payload.error.message`}),` пуст, обязательные `,(0,c.jsx)(t.code,{children:`errorMessage`}),` и message внутри сериализованного payload получают значение `,(0,c.jsx)(t.code,{children:`"Неизвестная ошибка"`}),`. Остальной draft не нормализуется.`]}),`
-`,(0,c.jsxs)(t.p,{children:[(0,c.jsx)(t.code,{children:`JSON.stringify`}),` может выбросить ошибку при циклических или неподдерживаемых данных. Draft должен соответствовать сериализуемому контракту `,(0,c.jsx)(t.code,{children:`foundation-lib`}),`.`]}),`
-`,(0,c.jsx)(t.h2,{id:`senderrorreport`,children:(0,c.jsx)(t.code,{children:`sendErrorReport`})}),`
-`,(0,c.jsx)(t.p,{children:`Lifecycle:`}),`
-`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-text`,children:`draft отсутствует ─────────► undefined
-status sent/sending ───────► текущий draft, adapter не вызывается
-остальной draft ───────────► sending
-                               │
-                    adapter success / error
-                       │              │
-                       ▼              ▼
-                     sent           failed + failedReason
-`})}),`
-`,(0,c.jsx)(t.p,{children:`Пошагово функция:`}),`
-`,(0,c.jsxs)(t.ol,{children:[`
-`,(0,c.jsxs)(t.li,{children:[`Ищет draft по `,(0,c.jsx)(t.code,{children:`reportId`}),` в store из `,(0,c.jsx)(t.code,{children:`foundation-lib`}),`.`]}),`
-`,(0,c.jsxs)(t.li,{children:[`Возвращает `,(0,c.jsx)(t.code,{children:`undefined`}),`, если draft не найден.`]}),`
-`,(0,c.jsxs)(t.li,{children:[`Не отправляет повторно draft со статусом `,(0,c.jsx)(t.code,{children:`sent`}),` или `,(0,c.jsx)(t.code,{children:`sending`}),`.`]}),`
-`,(0,c.jsxs)(t.li,{children:[`Устанавливает `,(0,c.jsx)(t.code,{children:`status: "sending"`}),` и очищает `,(0,c.jsx)(t.code,{children:`failedReason`}),`.`]}),`
-`,(0,c.jsx)(t.li,{children:`Создаёт delivery body.`}),`
-`,(0,c.jsxs)(t.li,{children:[`Вызывает `,(0,c.jsx)(t.code,{children:`adapter(body, { draft, queryClient })`}),`.`]}),`
-`,(0,c.jsxs)(t.li,{children:[`При успехе устанавливает `,(0,c.jsx)(t.code,{children:`status: "sent"`}),` и `,(0,c.jsx)(t.code,{children:`sentUtc`}),`.`]}),`
-`,(0,c.jsxs)(t.li,{children:[`При ошибке устанавливает `,(0,c.jsx)(t.code,{children:`status: "failed"`}),`, сохраняет нормализованное сообщение и повторно бросает исходную ошибку.`]}),`
-`]}),`
-`,(0,c.jsxs)(t.p,{children:[`Adapter получает исходный snapshot `,(0,c.jsx)(t.code,{children:`draft`}),`, прочитанный до перевода store в `,(0,c.jsx)(t.code,{children:`sending`}),`. Используйте `,(0,c.jsx)(t.code,{children:`body`}),` как delivery payload, а context — для query invalidation или transport, которому нужен `,(0,c.jsx)(t.code,{children:`QueryClient`}),`.`]}),`
-`,(0,c.jsx)(t.h2,{id:`adapter-с-cache-invalidation`,children:`Adapter с cache invalidation`}),`
-`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`const adapter: ErrorReportDeliveryAdapter = async (body, { queryClient }) => {
-	await postReport(body);
-	await queryClient.invalidateQueries({ queryKey: ["error-reports"] });
-};
-`})}),`
-`,(0,c.jsxs)(t.p,{children:[`Если invalidation бросит ошибку, вся доставка считается неуспешной и draft станет `,(0,c.jsx)(t.code,{children:`failed`}),`, даже если backend уже принял отчёт. Для non-critical cache update обработайте ошибку внутри adapter-а.`]}),`
-`,(0,c.jsx)(t.h2,{id:`повторная-отправка-и-concurrency`,children:`Повторная отправка и concurrency`}),`
-`,(0,c.jsxs)(t.p,{children:[`После `,(0,c.jsx)(t.code,{children:`failed`}),` функцию можно вызвать повторно. Проверка `,(0,c.jsx)(t.code,{children:`sending`}),` защищает от обычного повторного нажатия, но это не распределённая блокировка: два практически одновременных вызова могут успеть прочитать старый статус до его обновления. Backend желательно сделать идемпотентным по `,(0,c.jsx)(t.code,{children:`reportId`}),`.`]}),`
-`,(0,c.jsx)(t.h2,{id:`ошибки-и-безопасность`,children:`Ошибки и безопасность`}),`
-`,(0,c.jsxs)(t.ul,{children:[`
-`,(0,c.jsx)(t.li,{children:`Ошибка adapter-а не поглощается: вызывающий код обязан её обработать.`}),`
-`,(0,c.jsx)(t.li,{children:`Не добавляйте secrets в draft. Delivery layer не выполняет дополнительную redaction всего payload.`}),`
-`,(0,c.jsxs)(t.li,{children:[(0,c.jsx)(t.code,{children:`queryClient`}),` передаётся adapter-у, но модуль сам не инвалидирует queries.`]}),`
-`,(0,c.jsx)(t.li,{children:`Функция управляет локальным draft store; не вызывайте её в среде без подходящего storage/runtime, если draft store там недоступен.`}),`
-`,(0,c.jsxs)(t.li,{children:[`Статус `,(0,c.jsx)(t.code,{children:`sent`}),` означает успешное завершение adapter-а, а не обязательное подтверждение бизнес-обработки backend-ом.`]}),`
-`]}),`
-`,(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:`createErrorReportDeliveryBody`})}),(0,c.jsx)(t.td,{children:`Строит сериализуемый backend body`})]}),(0,c.jsxs)(t.tr,{children:[(0,c.jsx)(t.td,{children:(0,c.jsx)(t.code,{children:`sendErrorReport`})}),(0,c.jsx)(t.td,{children:`Управляет status и вызывает adapter`})]}),(0,c.jsxs)(t.tr,{children:[(0,c.jsx)(t.td,{children:(0,c.jsx)(t.code,{children:`ErrorReportDeliveryBody`})}),(0,c.jsx)(t.td,{children:`Поля delivery payload`})]}),(0,c.jsxs)(t.tr,{children:[(0,c.jsx)(t.td,{children:(0,c.jsx)(t.code,{children:`ErrorReportDeliveryContext`})}),(0,c.jsxs)(t.td,{children:[(0,c.jsx)(t.code,{children:`draft`}),` и `,(0,c.jsx)(t.code,{children:`queryClient`}),` для adapter-а`]})]}),(0,c.jsxs)(t.tr,{children:[(0,c.jsx)(t.td,{children:(0,c.jsx)(t.code,{children:`ErrorReportDeliveryAdapter`})}),(0,c.jsx)(t.td,{children:`Контракт функции доставки`})]}),(0,c.jsxs)(t.tr,{children:[(0,c.jsx)(t.td,{children:(0,c.jsx)(t.code,{children:`SendErrorReportOptions`})}),(0,c.jsxs)(t.td,{children:[(0,c.jsx)(t.code,{children:`adapter`}),` и `,(0,c.jsx)(t.code,{children:`queryClient`})]})]})]})]})]})}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};

package/storybook-static/assets/iframe-DzQq_POR.js

@@ -1 +0,0 @@
-import{t as e}from"./iframe-FSp_AjJa.js";e();