@ryuzaki13/react-foundation-lib 2.15.0 → 2.16.0

package/dist/virtualizer/index.d.ts

@@ -1,2 +1,3 @@
-export * from "./useFetchNextPageEffect";
+export { useFetchNextPageEffect } from "./useFetchNextPageEffect";
+export { type UseFetchNextPageEffectOptions } from "./useFetchNextPageEffectTypes";
 //# sourceMappingURL=index.d.ts.map

package/dist/virtualizer/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/virtualizer/index.ts"],"names":[],"mappings":"AAAA,cAAc,0BAA0B,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/virtualizer/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,sBAAsB,EAAE,MAAM,0BAA0B,CAAC;AAClE,OAAO,EAAE,KAAK,6BAA6B,EAAE,MAAM,+BAA+B,CAAC"}

package/dist/virtualizer/index.js

@@ -1,16 +1,28 @@
 import { useEffect as e, useRef as t } from "react";
 //#region src/virtualizer/useFetchNextPageEffect.ts
-function n({ virtualItems: n, currentItemsCount: r, fetchNextPage: i, hasNextPage: a }) {
-	let o = t(!1);
-	e(() => {
-		!n.length || !r || n[n.length - 1].index >= r - 1 && a && !o.current && (o.current = !0, i?.().finally(() => {
-			o.current = !1;
+function n({ virtualItems: n, currentItemsCount: r, fetchNextPage: i, hasNextPage: a, onError: o }) {
+	let s = t(!1), c = t(null), l = t(!1);
+	e(() => (l.current = !0, () => {
+		l.current = !1;
+	}), []), e(() => {
+		(!a || c.current !== r) && (c.current = null), !(!n.length || !r || !a || s.current || c.current === r) && n[n.length - 1].index >= r - 1 && (s.current = !0, Promise.resolve().then(i).then(() => {
+			s.current = !1;
+		}, async (e) => {
+			c.current = r;
+			try {
+				l.current && o ? await o(e) : console.error("Не удалось загрузить следующую страницу виртуализированного списка.", e);
+			} catch (t) {
+				console.error("Не удалось обработать ошибку дозагрузки виртуализированного списка.", e, t);
+			} finally {
+				s.current = !1;
+			}
 		}));
 	}, [
 		n,
 		r,
 		a,
-		i
+		i,
+		o
 	]);
 }
 //#endregion

package/dist/virtualizer/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","names":[],"sources":["../../src/virtualizer/useFetchNextPageEffect.ts"],"sourcesContent":["import { useEffect, useRef } from \"react\";\n\nimport { VirtualItem } from \"@tanstack/react-virtual\";\n\nexport function useFetchNextPageEffect({\n\tvirtualItems,\n\tcurrentItemsCount,\n\tfetchNextPage,\n\thasNextPage\n}: {\n\tvirtualItems: VirtualItem[];\n\tcurrentItemsCount: number;\n\thasNextPage: boolean;\n\tfetchNextPage: () => Promise<unknown>;\n}) {\n\tconst fetchingRef = useRef(false);\n\n\tuseEffect(() => {\n\t\tif (!virtualItems.length || !currentItemsCount) return;\n\t\tconst lastVirtual = virtualItems[virtualItems.length - 1];\n\n\t\tif (lastVirtual.index >= currentItemsCount - 1 && hasNextPage && !fetchingRef.current) {\n\t\t\tfetchingRef.current = true;\n\t\t\tfetchNextPage?.().finally(() => {\n\t\t\t\tfetchingRef.current = false;\n\t\t\t});\n\t\t}\n\t}, [virtualItems, currentItemsCount, hasNextPage, fetchNextPage]);\n}\n"],"mappings":";;AAIA,SAAgB,EAAuB,EACtC,iBACA,sBACA,kBACA,kBAME;CACF,IAAM,IAAc,EAAO,EAAK;CAEhC,QAAgB;EACX,CAAC,EAAa,UAAU,CAAC,KACT,EAAa,EAAa,SAAS,EAEnD,CAAY,SAAS,IAAoB,KAAK,KAAe,CAAC,EAAY,YAC7E,EAAY,UAAU,IACtB,IAAgB,CAAC,CAAC,cAAc;GAC/B,EAAY,UAAU;EACvB,CAAC;CAEH,GAAG;EAAC;EAAc;EAAmB;EAAa;CAAa,CAAC;AACjE"}
+{"version":3,"file":"index.js","names":[],"sources":["../../src/virtualizer/useFetchNextPageEffect.ts"],"sourcesContent":["import { useEffect, useRef } from \"react\";\n\nimport { type UseFetchNextPageEffectOptions } from \"./useFetchNextPageEffectTypes\";\n\n/**\n * Достигнутый край запускает одну дозагрузку. Отказ не превращается в detached\n * rejection и не повторяется из-за новых virtual items при каждом scroll/render.\n */\nexport function useFetchNextPageEffect({\n\tvirtualItems,\n\tcurrentItemsCount,\n\tfetchNextPage,\n\thasNextPage,\n\tonError\n}: UseFetchNextPageEffectOptions): void {\n\tconst fetchingRef = useRef(false);\n\tconst failedItemsCountRef = useRef<number | null>(null);\n\tconst mountedRef = useRef(false);\n\n\tuseEffect(() => {\n\t\tmountedRef.current = true;\n\t\treturn () => {\n\t\t\t// Transport принадлежит caller и не отменяется; поздний отказ остаётся\n\t\t\t// диагностикой, но уже не вызывает callback размонтированного UI.\n\t\t\tmountedRef.current = false;\n\t\t};\n\t}, []);\n\n\tuseEffect(() => {\n\t\t// Новые данные либо явное выключение pagination разрешают следующую\n\t\t// попытку. Identity callback и видимого диапазона не являются retry.\n\t\tif (!hasNextPage || failedItemsCountRef.current !== currentItemsCount) failedItemsCountRef.current = null;\n\t\tif (\n\t\t\t!virtualItems.length ||\n\t\t\t!currentItemsCount ||\n\t\t\t!hasNextPage ||\n\t\t\tfetchingRef.current ||\n\t\t\tfailedItemsCountRef.current === currentItemsCount\n\t\t)\n\t\t\treturn;\n\t\tconst lastVirtual = virtualItems[virtualItems.length - 1];\n\n\t\tif (lastVirtual.index >= currentItemsCount - 1) {\n\t\t\tfetchingRef.current = true;\n\t\t\t// Начало через Promise охватывает и синхронный throw transport callback.\n\t\t\t// Обе ветки завершения обработаны: finally не создаёт второй rejected Promise.\n\t\t\tvoid Promise.resolve()\n\t\t\t\t.then(fetchNextPage)\n\t\t\t\t.then(\n\t\t\t\t\t() => {\n\t\t\t\t\t\tfetchingRef.current = false;\n\t\t\t\t\t},\n\t\t\t\t\tasync (error: unknown) => {\n\t\t\t\t\t\tfailedItemsCountRef.current = currentItemsCount;\n\t\t\t\t\t\ttry {\n\t\t\t\t\t\t\tif (mountedRef.current && onError) await onError(error);\n\t\t\t\t\t\t\telse console.error(\"Не удалось загрузить следующую страницу виртуализированного списка.\", error);\n\t\t\t\t\t\t} catch (reporterError: unknown) {\n\t\t\t\t\t\t\tconsole.error(\"Не удалось обработать ошибку дозагрузки виртуализированного списка.\", error, reporterError);\n\t\t\t\t\t\t} finally {\n\t\t\t\t\t\t\tfetchingRef.current = false;\n\t\t\t\t\t\t}\n\t\t\t\t\t}\n\t\t\t\t);\n\t\t}\n\t}, [virtualItems, currentItemsCount, hasNextPage, fetchNextPage, onError]);\n}\n"],"mappings":";;AAQA,SAAgB,EAAuB,EACtC,iBACA,sBACA,kBACA,gBACA,cACuC;CACvC,IAAM,IAAc,EAAO,EAAK,GAC1B,IAAsB,EAAsB,IAAI,GAChD,IAAa,EAAO,EAAK;CAW/B,AATA,SACC,EAAW,UAAU,UACR;EAGZ,EAAW,UAAU;CACtB,IACE,CAAC,CAAC,GAEL,QAAgB;EAGf,CAAI,CAAC,KAAe,EAAoB,YAAY,OAAmB,EAAoB,UAAU,OAEpG,GAAC,EAAa,UACd,CAAC,KACD,CAAC,KACD,EAAY,WACZ,EAAoB,YAAY,MAGb,EAAa,EAAa,SAAS,EAEnD,CAAY,SAAS,IAAoB,MAC5C,EAAY,UAAU,IAGtB,QAAa,QAAQ,CAAC,CACpB,KAAK,CAAa,CAAC,CACnB,WACM;GACL,EAAY,UAAU;EACvB,GACA,OAAO,MAAmB;GACzB,EAAoB,UAAU;GAC9B,IAAI;IACH,AAAI,EAAW,WAAW,IAAS,MAAM,EAAQ,CAAK,IACjD,QAAQ,MAAM,uEAAuE,CAAK;GAChG,SAAS,GAAwB;IAChC,QAAQ,MAAM,uEAAuE,GAAO,CAAa;GAC1G,UAAU;IACT,EAAY,UAAU;GACvB;EACD,CACD;CAEH,GAAG;EAAC;EAAc;EAAmB;EAAa;EAAe;CAAO,CAAC;AAC1E"}

package/dist/virtualizer/useFetchNextPageEffect.d.ts

@@ -1,8 +1,7 @@
-import { VirtualItem } from "@tanstack/react-virtual";
-export declare function useFetchNextPageEffect({ virtualItems, currentItemsCount, fetchNextPage, hasNextPage }: {
-    virtualItems: VirtualItem[];
-    currentItemsCount: number;
-    hasNextPage: boolean;
-    fetchNextPage: () => Promise<unknown>;
-}): void;
+import { type UseFetchNextPageEffectOptions } from "./useFetchNextPageEffectTypes";
+/**
+ * Достигнутый край запускает одну дозагрузку. Отказ не превращается в detached
+ * rejection и не повторяется из-за новых virtual items при каждом scroll/render.
+ */
+export declare function useFetchNextPageEffect({ virtualItems, currentItemsCount, fetchNextPage, hasNextPage, onError }: UseFetchNextPageEffectOptions): void;
 //# sourceMappingURL=useFetchNextPageEffect.d.ts.map

package/dist/virtualizer/useFetchNextPageEffect.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"useFetchNextPageEffect.d.ts","sourceRoot":"","sources":["../../src/virtualizer/useFetchNextPageEffect.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AAEtD,wBAAgB,sBAAsB,CAAC,EACtC,YAAY,EACZ,iBAAiB,EACjB,aAAa,EACb,WAAW,EACX,EAAE;IACF,YAAY,EAAE,WAAW,EAAE,CAAC;IAC5B,iBAAiB,EAAE,MAAM,CAAC;IAC1B,WAAW,EAAE,OAAO,CAAC;IACrB,aAAa,EAAE,MAAM,OAAO,CAAC,OAAO,CAAC,CAAC;CACtC,QAcA"}
+{"version":3,"file":"useFetchNextPageEffect.d.ts","sourceRoot":"","sources":["../../src/virtualizer/useFetchNextPageEffect.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,KAAK,6BAA6B,EAAE,MAAM,+BAA+B,CAAC;AAEnF;;;GAGG;AACH,wBAAgB,sBAAsB,CAAC,EACtC,YAAY,EACZ,iBAAiB,EACjB,aAAa,EACb,WAAW,EACX,OAAO,EACP,EAAE,6BAA6B,GAAG,IAAI,CAoDtC"}

package/dist/virtualizer/useFetchNextPageEffectTypes.d.ts

@@ -0,0 +1,11 @@
+import { type VirtualItem } from "@tanstack/react-virtual";
+/** Дозагрузка не владеет данными и retry: caller передаёт состояние своей пагинации. */
+export type UseFetchNextPageEffectOptions = Readonly<{
+    virtualItems: readonly VirtualItem[];
+    currentItemsCount: number;
+    hasNextPage: boolean;
+    fetchNextPage: () => Promise<unknown>;
+    /** Ошибка передаётся один раз; без callback остаётся явная console-диагностика. */
+    onError?: (error: unknown) => void | Promise<void>;
+}>;
+//# sourceMappingURL=useFetchNextPageEffectTypes.d.ts.map

package/dist/virtualizer/useFetchNextPageEffectTypes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useFetchNextPageEffectTypes.d.ts","sourceRoot":"","sources":["../../src/virtualizer/useFetchNextPageEffectTypes.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,WAAW,EAAE,MAAM,yBAAyB,CAAC;AAE3D,wFAAwF;AACxF,MAAM,MAAM,6BAA6B,GAAG,QAAQ,CAAC;IACpD,YAAY,EAAE,SAAS,WAAW,EAAE,CAAC;IACrC,iBAAiB,EAAE,MAAM,CAAC;IAC1B,WAAW,EAAE,OAAO,CAAC;IACrB,aAAa,EAAE,MAAM,OAAO,CAAC,OAAO,CAAC,CAAC;IACtC,mFAAmF;IACnF,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACnD,CAAC,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@ryuzaki13/react-foundation-lib",
-	"version": "2.15.0",
+	"version": "2.16.0",
 	"description": "Reusable React and TypeScript foundation utilities, hooks, and primitives.",
 	"license": "MIT",
 	"author": "Ryuzaki13",

package/src/virtualizer/README.mdx

@@ -36,16 +36,18 @@ useFetchNextPageEffect({
 	virtualItems,
 	currentItemsCount,
 	fetchNextPage,
-	hasNextPage
+	hasNextPage,
+	onError
 });
 ```
 
-| Поле                | Значение                             |
-| ------------------- | ------------------------------------ |
-| `virtualItems`      | Текущий массив `VirtualItem[]`       |
-| `currentItemsCount` | Число реально загруженных data items |
-| `hasNextPage`       | Есть ли следующая server page        |
-| `fetchNextPage`     | Stable функция, возвращающая Promise |
+| Поле                | Значение                                                            |
+| ------------------- | ------------------------------------------------------------------- |
+| `virtualItems`      | Текущий массив `readonly VirtualItem[]`                             |
+| `currentItemsCount` | Число реально загруженных data items                                |
+| `hasNextPage`       | Есть ли следующая server page                                       |
+| `fetchNextPage`     | Stable функция, возвращающая Promise                                |
+| `onError`           | Необязательный callback `(error: unknown) => void \| Promise<void>` |
 
 Hook ничего не возвращает.
 
@@ -81,25 +83,41 @@ Trigger происходит строго на последнем загруже
 
 ## Защита от параллельного fetch
 
-Внутренний `useRef(false)` устанавливается до вызова и сбрасывается в `.finally()`:
+Внутренний single-flight ref устанавливается до вызова и сбрасывается после
+успеха либо завершения обработки ошибки:
 
 ```text
 idle ── trigger ──► fetchingRef=true
                        │
                  Promise pending
                        │
-             resolve или reject
+        resolve или завершение onError
                        ▼
                  fetchingRef=false
 ```
 
 Защита действует только внутри одного mounted hook instance. TanStack Query также должен владеть дедупликацией/network state.
 
-Если `fetchNextPage` отклоняет Promise, hook не добавляет `.catch`; rejection может стать unhandled. Передавайте функцию с принятой error policy или wrapper, который корректно обрабатывает ожидаемую ошибку.
+## Ошибки и повторная попытка
+
+Promise rejection и синхронный throw `fetchNextPage` передаются в `onError`
+один раз. Hook ожидает async callback; его собственный отказ также обрабатывается.
+Без `onError`, при отказе самого callback либо после unmount исходная ошибка
+остаётся в явной `console.error`-диагностике с контекстом дозагрузки. Hook не
+создаёт дополнительный unhandled Promise rejection и не решает, как показывать
+ошибку пользователю: это остаётся у владельца Query и UI.
+
+После отказа hook не пытается загрузить ту же страницу при каждом scroll/render.
+Неудачная попытка привязана к `currentItemsCount`: новое количество загруженных
+строк либо явное выключение `hasNextPage` и последующее включение разрешают новую
+попытку. Смена identity `fetchNextPage`, `onError` или `virtualItems` не является
+retry. Изменение данных без изменения количества само по себе latch не снимает;
+явная ручная retry-команда остаётся у владельца Query. Интервалов и собственной
+retry-policy в hook нет.
 
 ## Referential stability
 
-Effect зависит от `virtualItems`, `currentItemsCount`, `hasNextPage`, `fetchNextPage`.
+Effect зависит от `virtualItems`, `currentItemsCount`, `hasNextPage`, `fetchNextPage`, `onError`.
 
 - Используйте значение virtualizer как предусмотрено его API.
 - Не создавайте лишний async callback с новой identity без причины.
@@ -110,7 +128,9 @@ Effect зависит от `virtualItems`, `currentItemsCount`, `hasNextPage`, `
 
 Сам hook не читает `window`, но является React effect и не выполняет fetch во время server render. В browser effect запускается после commit.
 
-При unmount Promise не отменяется. Abort/cancel должен быть реализован query/transport owner. `fetchingRef` больше не влияет после удаления hook instance.
+При unmount Promise не отменяется. Abort/cancel должен быть реализован query/transport owner.
+Поздний отказ не вызывает `onError` размонтированного UI, но остаётся в явной
+console-диагностике. Уже начатый async `onError` не отменяется, его отказ не теряется.
 
 ## Типичные ошибки
 
@@ -118,17 +138,20 @@ Effect зависит от `virtualItems`, `currentItemsCount`, `hasNextPage`, `
 - Включить client-side sorting/filtering одной страницы при server-side модели.
 - Добавить фиктивный loader row в `currentItemsCount`.
 - Ожидать preload заранее — trigger находится на самом конце.
-- Передать rejecting Promise без error handling.
+- Ожидать, что hook сам покажет Query-ошибку или автоматически повторит failed page.
 - Выполнять fetch прямо в row render вместо effect.
 - Использовать изменяемый index как domain identity строки.
 
 ## API
 
 ```ts
-function useFetchNextPageEffect(args: {
-	virtualItems: VirtualItem[];
+type UseFetchNextPageEffectOptions = Readonly<{
+	virtualItems: readonly VirtualItem[];
 	currentItemsCount: number;
 	hasNextPage: boolean;
 	fetchNextPage: () => Promise<unknown>;
-}): void;
+	onError?: (error: unknown) => void | Promise<void>;
+}>;
+
+function useFetchNextPageEffect(options: UseFetchNextPageEffectOptions): void;
 ```