@ryuzaki13/react-foundation-ui 1.8.12 → 1.8.14

package/storybook-static/assets/{README-CWfPiPIB.js → README-BLliGbp2.js}

@@ -1,4 +1,4 @@
-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`,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 Lib/API/Formatters/Strings`}),`
+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`,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 Lib/API/Formatters/Strings`}),`
 `,(0,c.jsx)(t.h1,{id:`строковые-форматтеры`,children:`Строковые форматтеры`}),`
 `,(0,c.jsx)(t.p,{children:`Модуль содержит небольшие предсказуемые функции для подготовки пользовательского текста: обрезки пробелов, безопасного преобразования в строку, удаления ведущих нулей, сокращения длинного текста и выбора русской формы слова.`}),`
 `,(0,c.jsx)(t.p,{children:`Все функции экспортируются через один публичный entrypoint:`}),`

package/storybook-static/assets/{README-DV4fCpqN.js → README-BRAIrWZ5.js}

@@ -1,4 +1,4 @@
-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`,blockquote:`blockquote`,code:`code`,h1:`h1`,h2:`h2`,h3:`h3`,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 Lib/API/Utils`}),`
+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`,blockquote:`blockquote`,code:`code`,h1:`h1`,h2:`h2`,h3:`h3`,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 Lib/API/Utils`}),`
 `,(0,c.jsxs)(t.h1,{id:`общие-утилиты-ryuzaki13react-foundation-libutils`,children:[`Общие утилиты `,(0,c.jsx)(t.code,{children:`@ryuzaki13/react-foundation-lib/utils`})]}),`
 `,(0,c.jsxs)(t.p,{children:[`Модуль `,(0,c.jsx)(t.code,{children:`utils`}),` объединяет небольшие технические функции, которые нужны в разных частях React- и TypeScript-приложения:`]}),`
 `,(0,c.jsxs)(t.ul,{children:[`

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

@@ -0,0 +1,441 @@
+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={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/Orchestration/Async Tasks`}),`
+`,(0,c.jsxs)(t.h1,{id:`асинхронные-задачи-через-ryuzaki13react-foundation-apiasync`,children:[`Асинхронные задачи через `,(0,c.jsx)(t.code,{children:`@ryuzaki13/react-foundation-api/async`})]}),`
+`,(0,c.jsx)(t.p,{children:`Модуль запускает независимые Promise-задачи, сохраняет связь результата с исходным элементом и формирует удобную сводку для UI/логов.`}),`
+`,(0,c.jsx)(t.h2,{id:`какой-runner-выбрать`,children:`Какой runner выбрать`}),`
+`,(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:`Функция`})]})}),(0,c.jsxs)(t.tbody,{children:[(0,c.jsxs)(t.tr,{children:[(0,c.jsx)(t.td,{children:`Задач немного, можно начать все одновременно, любая ошибка должна завершить batch исключением`}),(0,c.jsx)(t.td,{children:(0,c.jsx)(t.code,{children:`runAsyncTasks`})})]}),(0,c.jsxs)(t.tr,{children:[(0,c.jsx)(t.td,{children:`Нужно ограничить число одновременных запросов, показать progress или поддержать abort`}),(0,c.jsx)(t.td,{children:(0,c.jsx)(t.code,{children:`runConcurrentTasks`})})]})]})]}),`
+`,(0,c.jsx)(t.p,{children:`Обе функции выполняют задачи параллельно. Они не создают web workers и не ускоряют CPU-bound JavaScript: Promise-concurrency полезна прежде всего для I/O — HTTP, чтения storage и других async операций.`}),`
+`,(0,c.jsx)(t.h3,{id:`ментальная-модель-concurrency`,children:`Ментальная модель concurrency`}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-text`,children:`Параллельно в Promise-смысле:
+request A ───────────────►
+request B ─────────►
+request C ─────────────────────►
+
+JavaScript thread при этом остаётся один.
+`})}),`
+`,(0,c.jsx)(t.p,{children:`Пока request ждёт сеть, event loop может продолжить другую задачу. Но три тяжёлых синхронных вычисления всё равно блокируют один thread по очереди.`}),`
+`,(0,c.jsx)(t.h2,{id:`импорт`,children:`Импорт`}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`import {
+	AsyncTasksError,
+	ConcurrencyPartialError,
+	runAsyncTasks,
+	runConcurrentTasks
+} from "@ryuzaki13/react-foundation-api/async";
+
+import type {
+	AsyncTask,
+	RunAsyncTasksResult,
+	RunConcurrentTasksOptions,
+	RunConcurrentTasksResult
+} from "@ryuzaki13/react-foundation-api/async";
+`})}),`
+`,(0,c.jsx)(t.p,{children:`Модуль не требует React или TanStack Query.`}),`
+`,(0,c.jsxs)(t.h2,{id:`база-async-promise-и-await`,children:[`База: `,(0,c.jsx)(t.code,{children:`async`}),`, `,(0,c.jsx)(t.code,{children:`Promise`}),` и `,(0,c.jsx)(t.code,{children:`await`})]}),`
+`,(0,c.jsxs)(t.p,{children:[(0,c.jsx)(t.code,{children:`async`}),`-функция всегда возвращает `,(0,c.jsx)(t.code,{children:`Promise`}),`. `,(0,c.jsx)(t.code,{children:`await`}),` приостанавливает только текущую async-функцию, а не весь browser thread:`]}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`async function loadName() {
+	const response = await fetch("/api/me");
+	return response.text();
+}
+
+const namePromise = loadName(); // Promise<string>.
+const name = await namePromise; // string.
+`})}),`
+`,(0,c.jsxs)(t.p,{children:[`Ошибку Promise обрабатывают через `,(0,c.jsx)(t.code,{children:`try/catch`}),` вокруг `,(0,c.jsx)(t.code,{children:`await`}),`.`]}),`
+`,(0,c.jsx)(t.h2,{id:`runasynctasks`,children:(0,c.jsx)(t.code,{children:`runAsyncTasks`})}),`
+`,(0,c.jsx)(t.h3,{id:`быстрый-старт`,children:`Быстрый старт`}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`const result = await runAsyncTasks([
+	{ name: "profile", run: () => fetchProfile() },
+	{ name: "settings", run: () => fetchSettings() }
+]);
+
+console.log(result.summary);
+// { total: 2, succeeded: 2, failed: 0 }
+`})}),`
+`,(0,c.jsxs)(t.p,{children:[`Все `,(0,c.jsx)(t.code,{children:`run`}),` запускаются сразу через `,(0,c.jsx)(t.code,{children:`Promise.all`}),`. Важное отличие от обычного `,(0,c.jsx)(t.code,{children:`Promise.all`}),`: ошибка одной задачи перехватывается внутри runner-а, поэтому остальные задачи успевают завершиться. После завершения всего batch функция либо возвращает полный результат, либо бросает `,(0,c.jsx)(t.code,{children:`AsyncTasksError`}),` с тем же полным результатом.`]}),`
+`,(0,c.jsx)(t.h3,{id:`обработка-частичного-успеха`,children:`Обработка частичного успеха`}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`try {
+	const result = await runAsyncTasks(tasks, {
+		errorMessage: "Не все стартовые данные загрузились"
+	});
+	useData(result.successes);
+} catch (error) {
+	if (error instanceof AsyncTasksError) {
+		usePartialData(error.result.successes);
+		showErrors(error.result.errors);
+		return;
+	}
+
+	throw error;
+}
+`})}),`
+`,(0,c.jsxs)(t.p,{children:[(0,c.jsx)(t.code,{children:`AsyncTasksError.result`}),` содержит:`]}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`type RunAsyncTasksResult<TResult> = {
+	settled: readonly AsyncTaskSettled<TResult>[];
+	successes: readonly AsyncTaskSuccess<TResult>[];
+	errors: readonly AsyncTaskFailure[];
+	summary: {
+		total: number;
+		succeeded: number;
+		failed: number;
+	};
+};
+`})}),`
+`,(0,c.jsxs)(t.p,{children:[`Элементы `,(0,c.jsx)(t.code,{children:`settled`}),`, `,(0,c.jsx)(t.code,{children:`successes`}),` и `,(0,c.jsx)(t.code,{children:`errors`}),` сохраняют порядок исходного массива. Каждый элемент содержит `,(0,c.jsx)(t.code,{children:`index`}),` и `,(0,c.jsx)(t.code,{children:`name`}),`.`]}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`if (item.status === "fulfilled") {
+	console.log(item.data);
+} else {
+	console.error(item.error);
+}
+`})}),`
+`,(0,c.jsxs)(t.p,{children:[`TypeScript сужает union по `,(0,c.jsx)(t.code,{children:`status`}),`.`]}),`
+`,(0,c.jsxs)(t.p,{children:[`Пустой список возвращает успешный пустой результат. `,(0,c.jsx)(t.code,{children:`runAsyncTasks`}),` не имеет встроенного concurrency limit и AbortSignal.`]}),`
+`,(0,c.jsx)(t.h3,{id:`полные-типы-taskresult`,children:`Полные типы task/result`}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`type AsyncTask<TResult = unknown> = {
+	readonly name: string;
+	readonly run: () => Promise<TResult>;
+};
+
+type AsyncTaskSuccess<TResult> = {
+	readonly status: "fulfilled";
+	readonly index: number;
+	readonly name: string;
+	readonly data: TResult;
+};
+
+type AsyncTaskFailure = {
+	readonly status: "rejected";
+	readonly index: number;
+	readonly name: string;
+	readonly error: unknown;
+};
+`})}),`
+`,(0,c.jsxs)(t.p,{children:[`Имена не обязаны быть уникальными. Для надёжной identity используйте `,(0,c.jsx)(t.code,{children:`index`}),`, если caller допускает повторяющиеся names.`]}),`
+`,(0,c.jsxs)(t.h3,{id:`синхронный-throw-внутри-run`,children:[`Синхронный throw внутри `,(0,c.jsx)(t.code,{children:`run`})]}),`
+`,(0,c.jsx)(t.p,{children:`Хотя тип обещает Promise, runtime callback может бросить сразу:`}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`{
+	name: "invalid",
+	run: () => {
+		throw new Error("Ошибка до Promise");
+	}
+}
+`})}),`
+`,(0,c.jsxs)(t.p,{children:[`Runner ловит такой throw так же, как rejected Promise, и помещает его в `,(0,c.jsx)(t.code,{children:`AsyncTasksError.result.errors`}),`.`]}),`
+`,(0,c.jsx)(t.h3,{id:`все-задачи-действительно-стартуют-сразу`,children:`Все задачи действительно стартуют сразу`}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`await runAsyncTasks(tenThousandRequests);
+`})}),`
+`,(0,c.jsxs)(t.p,{children:[`создаст попытку запуска всех 10 000 operations. Это может перегрузить browser, backend или connection pool. Для большого массива используйте `,(0,c.jsx)(t.code,{children:`runConcurrentTasks`}),`.`]}),`
+`,(0,c.jsx)(t.h3,{id:`homogeneous-result-type`,children:`Homogeneous result type`}),`
+`,(0,c.jsxs)(t.p,{children:[`Один вызов использует общий `,(0,c.jsx)(t.code,{children:`TResult`}),`. Если задачи возвращают принципиально разные shapes, создайте union/discriminated result либо выполняйте независимые batches:`]}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`type StartupResult =
+	| { kind: "profile"; value: Profile }
+	| { kind: "settings"; value: Settings };
+`})}),`
+`,(0,c.jsx)(t.h3,{id:`default-error-message`,children:`Default error message`}),`
+`,(0,c.jsxs)(t.p,{children:[`Если `,(0,c.jsx)(t.code,{children:`options.errorMessage`}),` отсутствует:`]}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-text`,children:`Не удалось выполнить все асинхронные задачи.
+`})}),`
+`,(0,c.jsxs)(t.p,{children:[(0,c.jsx)(t.code,{children:`AsyncTasksError.name`}),` равен `,(0,c.jsx)(t.code,{children:`"AsyncTasksError"`}),`, а `,(0,c.jsx)(t.code,{children:`result`}),` содержит полный batch snapshot.`]}),`
+`,(0,c.jsx)(t.h2,{id:`runconcurrenttasks`,children:(0,c.jsx)(t.code,{children:`runConcurrentTasks`})}),`
+`,(0,c.jsx)(t.h3,{id:`ограничение-одновременных-запросов`,children:`Ограничение одновременных запросов`}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`const result = await runConcurrentTasks(
+	userIds,
+	async (userId, { signal }) => {
+		const response = await fetch(\`/api/users/\${userId}\`, { signal });
+		if (!response.ok) throw new Error(\`HTTP \${response.status}\`);
+		return response.json();
+	},
+	{ concurrency: 4 }
+);
+`})}),`
+`,(0,c.jsxs)(t.p,{children:[`Не более четырёх задач будут находиться в работе одновременно. Значение по умолчанию — `,(0,c.jsx)(t.code,{children:`4`}),`. Если элементов меньше, workers создаются только по числу элементов.`]}),`
+`,(0,c.jsxs)(t.p,{children:[(0,c.jsx)(t.code,{children:`concurrency`}),` обязан быть целым числом не меньше `,(0,c.jsx)(t.code,{children:`1`}),`:`]}),`
+`,(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:`Результат`})]})}),(0,c.jsxs)(t.tbody,{children:[(0,c.jsxs)(t.tr,{children:[(0,c.jsx)(t.td,{children:(0,c.jsx)(t.code,{children:`4`})}),(0,c.jsx)(t.td,{children:`Работает`})]}),(0,c.jsxs)(t.tr,{children:[(0,c.jsx)(t.td,{children:(0,c.jsx)(t.code,{children:`1`})}),(0,c.jsx)(t.td,{children:`Последовательное выполнение`})]}),(0,c.jsxs)(t.tr,{children:[(0,c.jsxs)(t.td,{children:[(0,c.jsx)(t.code,{children:`0`}),`, `,(0,c.jsx)(t.code,{children:`-1`})]}),(0,c.jsx)(t.td,{children:(0,c.jsx)(t.code,{children:`RangeError`})})]}),(0,c.jsxs)(t.tr,{children:[(0,c.jsxs)(t.td,{children:[(0,c.jsx)(t.code,{children:`1.5`}),`, `,(0,c.jsx)(t.code,{children:`NaN`})]}),(0,c.jsx)(t.td,{children:(0,c.jsx)(t.code,{children:`TypeError`})})]})]})]}),`
+`,(0,c.jsx)(t.h3,{id:`ошибки-отдельных-элементов`,children:`Ошибки отдельных элементов`}),`
+`,(0,c.jsxs)(t.p,{children:[`Runner не бросает ошибки отдельных задач. Он помещает их в `,(0,c.jsx)(t.code,{children:`result.errors`}),` и продолжает обработку:`]}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`const result = await runConcurrentTasks(inputs, task);
+
+if (result.errors.length > 0) {
+	for (const failure of result.errors) {
+		console.error(failure.index, failure.input, failure.error);
+	}
+}
+`})}),`
+`,(0,c.jsxs)(t.p,{children:[`Исключение самой функции возможно при невалидном `,(0,c.jsx)(t.code,{children:`concurrency`}),` или если callback `,(0,c.jsx)(t.code,{children:`onProgress`}),`/`,(0,c.jsx)(t.code,{children:`onItemSuccess`}),`/`,(0,c.jsx)(t.code,{children:`onItemError`}),` сам бросил ошибку. Callbacks должны быть безопасными и быстрыми.`]}),`
+`,(0,c.jsx)(t.h3,{id:`progress`,children:`Progress`}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`await runConcurrentTasks(files, uploadFile, {
+	concurrency: 3,
+	onProgress(progress) {
+		setProgress(progress.percentage);
+	},
+	onItemSuccess(item) {
+		console.log("Загружен", item.input.name);
+	},
+	onItemError(item) {
+		console.error("Ошибка", item.input.name, item.error);
+	}
+});
+`})}),`
+`,(0,c.jsxs)(t.p,{children:[(0,c.jsx)(t.code,{children:`onProgress`}),` вызывается после каждой завершённой задачи. В первом вызове процент уже больше нуля; отдельного начального события `,(0,c.jsx)(t.code,{children:`0%`}),` нет.`]}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`type ConcurrentTaskProgress<TInput, TResult> = {
+	total: number;
+	completed: number;
+	succeeded: number;
+	failed: number;
+	running: number;
+	pending: number;
+	percentage: number;
+	aborted: boolean;
+	lastSettled?: ConcurrentTaskSettled<TInput, TResult>;
+};
+`})}),`
+`,(0,c.jsxs)(t.p,{children:[(0,c.jsx)(t.code,{children:`percentage`}),` округляется через `,(0,c.jsx)(t.code,{children:`Math.round`}),`.`]}),`
+`,(0,c.jsx)(t.h3,{id:`точная-последовательность-callbacks`,children:`Точная последовательность callbacks`}),`
+`,(0,c.jsx)(t.p,{children:`Для успешной task:`}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-text`,children:`task resolved
+  → сохранить fulfilled item
+  → увеличить succeeded
+  → onItemSuccess(item)
+  → уменьшить running
+  → увеличить completed
+  → onProgress(progress)
+`})}),`
+`,(0,c.jsxs)(t.p,{children:[`Для rejected task аналогично вызывается `,(0,c.jsx)(t.code,{children:`onItemError`}),`, затем `,(0,c.jsx)(t.code,{children:`onProgress`}),`.`]}),`
+`,(0,c.jsxs)(t.p,{children:[`Callbacks синхронные: runner не `,(0,c.jsx)(t.code,{children:`await`}),`-ит Promise, который callback мог случайно вернуть. Делайте их быстрыми state/logging callbacks.`]}),`
+`,(0,c.jsxs)(t.p,{children:[`Критически важно не бросать из callbacks. Если `,(0,c.jsx)(t.code,{children:`onItemSuccess`}),` бросит, worker попадёт в `,(0,c.jsx)(t.code,{children:`catch`}),`, перезапишет item как rejected и вызовет `,(0,c.jsx)(t.code,{children:`onItemError`}),`. Если затем бросит `,(0,c.jsx)(t.code,{children:`onItemError`}),` или `,(0,c.jsx)(t.code,{children:`onProgress`}),`, весь runner может reject. Кроме того, промежуточные progress counters могут стать нелогичными. Оборачивайте необязательную telemetry:`]}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`onItemSuccess(item) {
+	try {
+		analytics.track("uploaded", { index: item.index });
+	} catch (error) {
+		console.warn("Telemetry недоступна", error);
+	}
+}
+`})}),`
+`,(0,c.jsx)(t.h3,{id:`abort`,children:`Abort`}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`const controller = new AbortController();
+
+const promise = runConcurrentTasks(urls, async (url, { signal }) => {
+	const response = await fetch(url, { signal });
+	return response.text();
+}, {
+	concurrency: 2,
+	signal: controller.signal
+});
+
+controller.abort();
+const result = await promise;
+`})}),`
+`,(0,c.jsxs)(t.p,{children:[`После abort новые задачи не стартуют. Уже начатая операция прервётся только если сама использует переданный `,(0,c.jsx)(t.code,{children:`signal`}),`. Runner ждёт завершения начатых tasks и возвращает:`]}),`
+`,(0,c.jsxs)(t.ul,{children:[`
+`,(0,c.jsxs)(t.li,{children:[(0,c.jsx)(t.code,{children:`aborted: true`}),`;`]}),`
+`,(0,c.jsxs)(t.li,{children:[`обработанные элементы в `,(0,c.jsx)(t.code,{children:`settled`}),`;`]}),`
+`,(0,c.jsxs)(t.li,{children:[`не начатые элементы в `,(0,c.jsx)(t.code,{children:`unprocessed`}),`.`]}),`
+`]}),`
+`,(0,c.jsxs)(t.p,{children:[`Abort не является ошибкой runner-а и сам по себе не приводит к `,(0,c.jsx)(t.code,{children:`throw`}),`.`]}),`
+`,(0,c.jsx)(t.h3,{id:`signal-уже-aborted-до-запуска`,children:`Signal уже aborted до запуска`}),`
+`,(0,c.jsx)(t.p,{children:`Для непустого input ни одна task не стартует:`}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`const controller = new AbortController();
+controller.abort();
+
+const result = await runConcurrentTasks([1, 2, 3], task, {
+	signal: controller.signal
+});
+`})}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`result.aborted; // true
+result.settled; // []
+result.unprocessed; // все три input с индексами
+`})}),`
+`,(0,c.jsxs)(t.p,{children:[`Initial progress event `,(0,c.jsx)(t.code,{children:`0%`}),` не генерируется.`]}),`
+`,(0,c.jsx)(t.h3,{id:`abort-уже-начатых-tasks`,children:`Abort уже начатых tasks`}),`
+`,(0,c.jsx)(t.p,{children:`Runner только прекращает выдавать новые inputs workers. Реальная отмена зависит от task:`}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`// Signal используется — fetch может прерваться.
+async (url, { signal }) => fetch(url, { signal })
+`})}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`// Signal игнорируется — task завершится несмотря на abort batch-а.
+async (url) => fetch(url)
+`})}),`
+`,(0,c.jsxs)(t.p,{children:[`Если task с signal отклоняется AbortError, она попадёт в `,(0,c.jsx)(t.code,{children:`errors`}),`, а ещё не стартовавшие inputs — в `,(0,c.jsx)(t.code,{children:`unprocessed`}),`.`]}),`
+`,(0,c.jsx)(t.h3,{id:`порядок-результата`,children:`Порядок результата`}),`
+`,(0,c.jsxs)(t.p,{children:[`Tasks могут завершаться в любом порядке, callbacks идут в порядке фактического завершения. Итоговые `,(0,c.jsx)(t.code,{children:`settled`}),`, `,(0,c.jsx)(t.code,{children:`successes`}),`, `,(0,c.jsx)(t.code,{children:`errors`}),` и `,(0,c.jsx)(t.code,{children:`unprocessed`}),` собираются по исходным индексам, поэтому результат детерминирован относительно input.`]}),`
+`,(0,c.jsx)(t.h3,{id:`полный-result`,children:`Полный result`}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`type RunConcurrentTasksResult<TInput, TResult> = {
+	settled: ConcurrentTaskSettled<TInput, TResult>[];
+	successes: ConcurrentTaskSuccess<TInput, TResult>[];
+	errors: ConcurrentTaskError<TInput>[];
+	unprocessed: ConcurrentTaskUnprocessed<TInput>[];
+	aborted: boolean;
+	summary: {
+		total: number;
+		completed: number;
+		succeeded: number;
+		failed: number;
+		unprocessed: number;
+	};
+};
+`})}),`
+`,(0,c.jsx)(t.p,{children:`Invariant после нормального завершения:`}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-text`,children:`summary.total = summary.completed + summary.unprocessed
+summary.completed = summary.succeeded + summary.failed
+`})}),`
+`,(0,c.jsx)(t.h3,{id:`пустой-input`,children:`Пустой input`}),`
+`,(0,c.jsxs)(t.p,{children:[`Возвращается empty result. Если signal уже aborted, `,(0,c.jsx)(t.code,{children:`aborted`}),` будет `,(0,c.jsx)(t.code,{children:`true`}),`; иначе `,(0,c.jsx)(t.code,{children:`false`}),`. `,(0,c.jsx)(t.code,{children:`percentage`}),` отсутствует в final summary, а progress callback не вызывается.`]}),`
+`,(0,c.jsx)(t.h2,{id:`практический-пример-upload-batch`,children:`Практический пример: upload batch`}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`type UploadInput = {
+	id: string;
+	file: File;
+};
+
+const result = await runConcurrentTasks(
+	files,
+	async ({ id, file }, { signal }) => {
+		const body = new FormData();
+		body.set("file", file);
+
+		const response = await fetch(\`/api/files/\${encodeURIComponent(id)}\`, {
+			method: "PUT",
+			body,
+			signal
+		});
+
+		if (!response.ok) {
+			throw new Error(\`HTTP \${response.status}\`);
+		}
+
+		return { id, uploaded: true };
+	},
+	{
+		concurrency: 3,
+		signal: controller.signal,
+		onProgress: ({ completed, total, percentage }) => {
+			console.log(\`\${completed}/\${total}: \${percentage}%\`);
+		}
+	}
+);
+`})}),`
+`,(0,c.jsx)(t.h3,{id:`retry-только-failures`,children:`Retry только failures`}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`const retryInputs = result.errors.map((item) => item.input);
+
+const retryResult = await runConcurrentTasks(retryInputs, uploadTask, {
+	concurrency: 2
+});
+`})}),`
+`,(0,c.jsx)(t.p,{children:`У write operations retry безопасен только при idempotent server contract. Потерянный response не доказывает, что первая запись не произошла.`}),`
+`,(0,c.jsx)(t.h3,{id:`продолжить-unprocessed-после-abort`,children:`Продолжить unprocessed после abort`}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`const remainingInputs = result.unprocessed.map((item) => item.input);
+`})}),`
+`,(0,c.jsxs)(t.p,{children:[`Не добавляйте автоматически `,(0,c.jsx)(t.code,{children:`errors`}),` к `,(0,c.jsx)(t.code,{children:`unprocessed`}),`: rejected task уже запускалась и могла частично изменить backend.`]}),`
+`,(0,c.jsx)(t.h2,{id:`concurrencypartialerror`,children:(0,c.jsx)(t.code,{children:`ConcurrencyPartialError`})}),`
+`,(0,c.jsxs)(t.p,{children:[(0,c.jsx)(t.code,{children:`runConcurrentTasks`}),` сам не создаёт этот error. Класс нужен, если слой приложения хочет преобразовать частичный результат в исключение:`]}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`const result = await runConcurrentTasks(inputs, task);
+
+if (result.errors.length > 0 || result.aborted) {
+	throw new ConcurrencyPartialError("Batch выполнен частично", result);
+}
+`})}),`
+`,(0,c.jsxs)(t.p,{children:[`Не путайте его с `,(0,c.jsx)(t.code,{children:`AsyncTasksError`}),`: первый создаёт consumer по своей policy, второй автоматически бросает `,(0,c.jsx)(t.code,{children:`runAsyncTasks`}),`.`]}),`
+`,(0,c.jsxs)(t.p,{children:[(0,c.jsx)(t.code,{children:`ConcurrencyPartialError.name`}),` равен `,(0,c.jsx)(t.code,{children:`"ConcurrencyPartialError"`}),`, field `,(0,c.jsx)(t.code,{children:`result`}),` сохраняет переданный snapshot без преобразований.`]}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`try {
+	const result = await runConcurrentTasks(inputs, task);
+
+	if (result.errors.length || result.aborted) {
+		throw new ConcurrencyPartialError(
+			"Не все файлы обработаны",
+			result
+		);
+	}
+} catch (error) {
+	if (error instanceof ConcurrencyPartialError) {
+		showPartialResult(error.result);
+		return;
+	}
+
+	throw error;
+}
+`})}),`
+`,(0,c.jsxs)(t.h2,{id:`выбор-concurrency`,children:[`Выбор `,(0,c.jsx)(t.code,{children:`concurrency`})]}),`
+`,(0,c.jsx)(t.p,{children:`Нет универсального максимума:`}),`
+`,(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:`Стартовая оценка`})]})}),(0,c.jsxs)(t.tbody,{children:[(0,c.jsxs)(t.tr,{children:[(0,c.jsx)(t.td,{children:`Тяжёлые SAP write requests`}),(0,c.jsx)(t.td,{children:`2–4`})]}),(0,c.jsxs)(t.tr,{children:[(0,c.jsx)(t.td,{children:`Небольшие independent reads`}),(0,c.jsx)(t.td,{children:`4–8`})]}),(0,c.jsxs)(t.tr,{children:[(0,c.jsx)(t.td,{children:`Local async storage`}),(0,c.jsx)(t.td,{children:`зависит от adapter-а`})]}),(0,c.jsxs)(t.tr,{children:[(0,c.jsx)(t.td,{children:`CPU-bound parsing`}),(0,c.jsx)(t.td,{children:`runner не решает задачу`})]})]})]}),`
+`,(0,c.jsx)(t.p,{children:`Начните с малого значения, измерьте latency/error rate и согласуйте лимит с backend.`}),`
+`,(0,c.jsxs)(t.p,{children:[(0,c.jsx)(t.code,{children:`concurrency: 1`}),` полезен для последовательной обработки независимых элементов с единым result contract. Но если шаг B зависит от output A, обычный последовательный workflow будет понятнее.`]}),`
+`,(0,c.jsx)(t.h2,{id:`тестирование`,children:`Тестирование`}),`
+`,(0,c.jsx)(t.h3,{id:`runasynctasks-1`,children:(0,c.jsx)(t.code,{children:`runAsyncTasks`})}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`it("сохраняет partial result в AsyncTasksError", async () => {
+	const promise = runAsyncTasks([
+		{ name: "ok", run: async () => 1 },
+		{ name: "failed", run: async () => { throw new Error("boom"); } }
+	]);
+
+	await expect(promise).rejects.toMatchObject({
+		name: "AsyncTasksError",
+		result: {
+			summary: { total: 2, succeeded: 1, failed: 1 }
+		}
+	});
+});
+`})}),`
+`,(0,c.jsx)(t.h3,{id:`проверка-лимита-concurrency`,children:`Проверка лимита concurrency`}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`it("не запускает больше двух tasks одновременно", async () => {
+	let running = 0;
+	let maximum = 0;
+
+	await runConcurrentTasks(
+		[1, 2, 3, 4],
+		async () => {
+			running += 1;
+			maximum = Math.max(maximum, running);
+			await Promise.resolve();
+			running -= 1;
+			return true;
+		},
+		{ concurrency: 2 }
+	);
+
+	expect(maximum).toBe(2);
+});
+`})}),`
+`,(0,c.jsx)(t.p,{children:`Покройте:`}),`
+`,(0,c.jsxs)(t.ul,{children:[`
+`,(0,c.jsx)(t.li,{children:`empty input;`}),`
+`,(0,c.jsxs)(t.li,{children:[`validation `,(0,c.jsx)(t.code,{children:`concurrency`}),`;`]}),`
+`,(0,c.jsx)(t.li,{children:`sync throw и rejected Promise;`}),`
+`,(0,c.jsx)(t.li,{children:`input order result-а;`}),`
+`,(0,c.jsx)(t.li,{children:`completion order callbacks;`}),`
+`,(0,c.jsx)(t.li,{children:`abort до старта;`}),`
+`,(0,c.jsx)(t.li,{children:`abort во время работы;`}),`
+`,(0,c.jsx)(t.li,{children:`task, игнорирующую signal;`}),`
+`,(0,c.jsx)(t.li,{children:`unprocessed indices;`}),`
+`,(0,c.jsx)(t.li,{children:`custom partial-error policy.`}),`
+`]}),`
+`,(0,c.jsx)(t.h2,{id:`частые-ошибки`,children:`Частые ошибки`}),`
+`,(0,c.jsxs)(t.h3,{id:`использовать-runasynctasks-для-тысяч-requests`,children:[`Использовать `,(0,c.jsx)(t.code,{children:`runAsyncTasks`}),` для тысяч requests`]}),`
+`,(0,c.jsx)(t.p,{children:`Он стартует всё сразу. Нужен bounded runner.`}),`
+`,(0,c.jsx)(t.h3,{id:`считать-abort-мгновенной-отменой`,children:`Считать abort мгновенной отменой`}),`
+`,(0,c.jsx)(t.p,{children:`Task обязана использовать signal.`}),`
+`,(0,c.jsx)(t.h3,{id:`бросать-из-progress-callback`,children:`Бросать из progress callback`}),`
+`,(0,c.jsx)(t.p,{children:`Callbacks являются частью worker execution и могут сломать batch.`}),`
+`,(0,c.jsx)(t.h3,{id:`считать-individual-errors-исключением-bounded-runner-а`,children:`Считать individual errors исключением bounded runner-а`}),`
+`,(0,c.jsxs)(t.p,{children:[`Читайте `,(0,c.jsx)(t.code,{children:`result.errors`}),`. Сам runner их не бросает.`]}),`
+`,(0,c.jsx)(t.h3,{id:`мутировать-input`,children:`Мутировать input`}),`
+`,(0,c.jsx)(t.p,{children:`Result сохраняет ссылку на исходный input. Mutation может неожиданно изменить UI/result history.`}),`
+`,(0,c.jsx)(t.h3,{id:`использовать-batch-как-query-cache`,children:`Использовать batch как Query cache`}),`
+`,(0,c.jsx)(t.p,{children:`Runner orchestrates promises, но не заменяет query identity, stale policy и cache ownership.`}),`
+`,(0,c.jsx)(t.h2,{id:`практические-рекомендации`,children:`Практические рекомендации`}),`
+`,(0,c.jsxs)(t.ul,{children:[`
+`,(0,c.jsx)(t.li,{children:`Не ставьте слишком большой concurrency: browser, proxy и backend имеют свои лимиты.`}),`
+`,(0,c.jsx)(t.li,{children:`Для write-операций продумайте идемпотентность: retry может повторить уже выполненное действие.`}),`
+`,(0,c.jsx)(t.li,{children:`Не меняйте input objects внутри task, если те же значения использует UI.`}),`
+`,(0,c.jsxs)(t.li,{children:[`Обрабатывайте `,(0,c.jsx)(t.code,{children:`unknown`}),` error через безопасный normalizer.`]}),`
+`,(0,c.jsx)(t.li,{children:`Не используйте runner вместо TanStack Query cache для одного и того же resource.`}),`
+`,(0,c.jsx)(t.li,{children:`Если задача зависит от результата предыдущей, это не независимый batch: выполните зависимые шаги последовательно.`}),`
+`]}),`
+`,(0,c.jsx)(t.h2,{id:`faq`,children:`FAQ`}),`
+`,(0,c.jsx)(t.h3,{id:`сохраняется-ли-порядок`,children:`Сохраняется ли порядок?`}),`
+`,(0,c.jsx)(t.p,{children:`В final arrays — да, по input index. В callbacks — нет, они идут по завершению.`}),`
+`,(0,c.jsx)(t.h3,{id:`останавливается-ли-batch-на-первой-task-error`,children:`Останавливается ли batch на первой task error?`}),`
+`,(0,c.jsxs)(t.p,{children:[`Нет. Оба runner-а дают уже запущенным tasks завершиться. `,(0,c.jsx)(t.code,{children:`runAsyncTasks`}),` бросает aggregated error после всего batch, bounded runner возвращает errors.`]}),`
+`,(0,c.jsx)(t.h3,{id:`можно-ли-менять-concurrency-во-время-запуска`,children:`Можно ли менять concurrency во время запуска?`}),`
+`,(0,c.jsx)(t.p,{children:`Нет. Значение фиксируется при старте.`}),`
+`,(0,c.jsx)(t.h3,{id:`есть-ли-automatic-retry`,children:`Есть ли automatic retry?`}),`
+`,(0,c.jsx)(t.p,{children:`Нет. Он должен быть явным и безопасным для operation.`}),`
+`,(0,c.jsxs)(t.h3,{id:`почему-error-имеет-type-unknown`,children:[`Почему `,(0,c.jsx)(t.code,{children:`error`}),` имеет type `,(0,c.jsx)(t.code,{children:`unknown`}),`?`]}),`
+`,(0,c.jsx)(t.p,{children:`Promise может reject любым JS value. Сужайте/нормализуйте его перед UI/logging.`}),`
+`,(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:`All-at-once`}),(0,c.jsxs)(t.td,{children:[(0,c.jsx)(t.code,{children:`runAsyncTasks`}),`, `,(0,c.jsx)(t.code,{children:`AsyncTasksError`}),`, `,(0,c.jsx)(t.code,{children:`AsyncTask`}),`, `,(0,c.jsx)(t.code,{children:`AsyncTaskSuccess`}),`, `,(0,c.jsx)(t.code,{children:`AsyncTaskFailure`}),`, `,(0,c.jsx)(t.code,{children:`AsyncTaskSettled`}),`, `,(0,c.jsx)(t.code,{children:`RunAsyncTasksResult`}),`, `,(0,c.jsx)(t.code,{children:`RunAsyncTasksOptions`})]})]}),(0,c.jsxs)(t.tr,{children:[(0,c.jsx)(t.td,{children:`Bounded concurrency`}),(0,c.jsxs)(t.td,{children:[(0,c.jsx)(t.code,{children:`runConcurrentTasks`}),`, `,(0,c.jsx)(t.code,{children:`ConcurrencyPartialError`}),`, `,(0,c.jsx)(t.code,{children:`ConcurrentTaskContext`}),`, `,(0,c.jsx)(t.code,{children:`ConcurrentTaskFn`}),`, `,(0,c.jsx)(t.code,{children:`ConcurrentTaskSuccess`}),`, `,(0,c.jsx)(t.code,{children:`ConcurrentTaskError`}),`, `,(0,c.jsx)(t.code,{children:`ConcurrentTaskSettled`}),`, `,(0,c.jsx)(t.code,{children:`ConcurrentTaskUnprocessed`}),`, `,(0,c.jsx)(t.code,{children:`ConcurrentTaskProgress`}),`, `,(0,c.jsx)(t.code,{children:`RunConcurrentTasksOptions`}),`, `,(0,c.jsx)(t.code,{children:`RunConcurrentTasksResult`})]})]})]})]})]})}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};