@ryuzaki13/react-foundation-lib 2.30.1 → 2.31.0

package/README.md

@@ -29,7 +29,7 @@ import type { RowRecord } from "@ryuzaki13/react-foundation-lib/types";
 
 | Entry point                                               | Что может потребоваться в host-проекте                                                                           |
 | --------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
-| `formatters`, `array`                                     | Обычно не требуют дополнительных runtime-зависимостей.                                                           |
+| `formatters`, `array`, `promise`                          | Обычно не требуют дополнительных runtime-зависимостей.                                                           |
 | `utils`, `hooks`, `binary`, `dom`, `copy`, `media`, `pwa` | `react`: `utils` экспортирует React helpers, `binary` — `useBinaryFile`, остальные entrypoints содержат hooks.   |
 | `query-client`, `error-report`                            | `@tanstack/react-query`, `@tanstack/query-persist-client-core`, `@tanstack/query-broadcast-client-experimental`. |
 | `odata-service`                                           | `zod`, `zustand`, `immer`, `react`; `unwrapODataQueryResult` типизирован вокруг `@tanstack/react-query`.         |
@@ -101,7 +101,7 @@ npm run pack:dry-run
 
 ## Полный каталог документации
 
-Каждый публичный subpath из `package.json#exports` покрыт русскоязычным MDX-руководством. Документы `tree-table` и `pwa/sw-cache-policy` намеренно объединены с ближайшим владельцем, чтобы правила одного сценария не расходились между файлами.
+Каждый публичный subpath из `package.json#exports` покрыт русскоязычным руководством. Документы `tree-table` и `pwa/sw-cache-policy` намеренно объединены с ближайшим владельцем, чтобы правила одного сценария не расходились между файлами.
 
 | Публичный import path  | Подробная документация                                                         |
 | ---------------------- | ------------------------------------------------------------------------------ |
@@ -133,6 +133,7 @@ npm run pack:dry-run
 | `/number-scale`        | [`number-scale/README.mdx`](./src/number-scale/README.mdx)                     |
 | `/odata-service`       | [`odata-service/README.mdx`](./src/odata-service/README.mdx)                   |
 | `/presets`             | [`presets/README.mdx`](./src/presets/README.mdx)                               |
+| `/promise`             | [Управляемое ожидание через Promise](./src/promise/README.md)                  |
 | `/pwa`                 | [`pwa/README.mdx`](./src/pwa/README.mdx)                                       |
 | `/pwa/sw-cache-policy` | Раздел cache policy в [`pwa/README.mdx`](./src/pwa/README.mdx)                 |
 | `/query-client`        | [`query-client/README.mdx`](./src/query-client/README.mdx)                     |

package/dist/promise/createDeferredPromise.d.ts

@@ -0,0 +1,8 @@
+import { type DeferredPromise } from "./deferredPromiseTypes";
+/**
+ * Создаёт управляемое ожидание через обычный Promise без дополнительных runtime API.
+ * Подходит для завершения операции из callback; не устанавливает полифиллы и
+ * сохраняет нативные правила разрешения thenable и первого завершения.
+ */
+export declare function createDeferredPromise<T>(): DeferredPromise<T>;
+//# sourceMappingURL=createDeferredPromise.d.ts.map

package/dist/promise/createDeferredPromise.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"createDeferredPromise.d.ts","sourceRoot":"","sources":["../../src/promise/createDeferredPromise.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAE9D;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,CAAC,KAAK,eAAe,CAAC,CAAC,CAAC,CAc7D"}

package/dist/promise/deferredPromiseTypes.d.ts

@@ -0,0 +1,7 @@
+/** Promise, завершением которого владелец управляет из внешнего события или lifecycle. */
+export type DeferredPromise<T> = {
+    readonly promise: Promise<T>;
+    readonly resolve: (value: T | PromiseLike<T>) => void;
+    readonly reject: (reason?: unknown) => void;
+};
+//# sourceMappingURL=deferredPromiseTypes.d.ts.map

package/dist/promise/deferredPromiseTypes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"deferredPromiseTypes.d.ts","sourceRoot":"","sources":["../../src/promise/deferredPromiseTypes.ts"],"names":[],"mappings":"AAAA,0FAA0F;AAC1F,MAAM,MAAM,eAAe,CAAC,CAAC,IAAI;IAChC,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC;IAC7B,QAAQ,CAAC,OAAO,EAAE,CAAC,KAAK,EAAE,CAAC,GAAG,WAAW,CAAC,CAAC,CAAC,KAAK,IAAI,CAAC;IACtD,QAAQ,CAAC,MAAM,EAAE,CAAC,MAAM,CAAC,EAAE,OAAO,KAAK,IAAI,CAAC;CAC5C,CAAC"}

package/dist/promise/index.d.ts

@@ -0,0 +1,3 @@
+export { createDeferredPromise } from "./createDeferredPromise";
+export { type DeferredPromise } from "./deferredPromiseTypes";
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/promise/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,qBAAqB,EAAE,MAAM,yBAAyB,CAAC;AAChE,OAAO,EAAE,KAAK,eAAe,EAAE,MAAM,wBAAwB,CAAC"}

package/dist/promise/index.js

@@ -0,0 +1,16 @@
+//#region src/promise/createDeferredPromise.ts
+function e() {
+	let e, t, n = new Promise((n, r) => {
+		e = n, t = r;
+	});
+	if (e === void 0 || t === void 0) throw Error("Конструктор Promise не предоставил функции завершения синхронно.");
+	return {
+		promise: n,
+		resolve: e,
+		reject: t
+	};
+}
+//#endregion
+export { e as createDeferredPromise };
+
+//# sourceMappingURL=index.js.map

package/dist/promise/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","names":[],"sources":["../../src/promise/createDeferredPromise.ts"],"sourcesContent":["import { type DeferredPromise } from \"./deferredPromiseTypes\";\n\n/**\n * Создаёт управляемое ожидание через обычный Promise без дополнительных runtime API.\n * Подходит для завершения операции из callback; не устанавливает полифиллы и\n * сохраняет нативные правила разрешения thenable и первого завершения.\n */\nexport function createDeferredPromise<T>(): DeferredPromise<T> {\n\tlet resolve: DeferredPromise<T>[\"resolve\"] | undefined;\n\tlet reject: DeferredPromise<T>[\"reject\"] | undefined;\n\tconst promise = new Promise<T>((resolvePromise, rejectPromise) => {\n\t\tresolve = resolvePromise;\n\t\treject = rejectPromise;\n\t});\n\n\t// Promise вызывает executor синхронно. Проверка фиксирует этот invariant для\n\t// TypeScript, который не отслеживает присваивания внутри callback конструктора.\n\tif (resolve === undefined || reject === undefined) {\n\t\tthrow new Error(\"Конструктор Promise не предоставил функции завершения синхронно.\");\n\t}\n\treturn { promise, resolve, reject };\n}\n"],"mappings":";AAOA,SAAgB,IAA+C;CAC9D,IAAI,GACA,GACE,IAAU,IAAI,SAAY,GAAgB,MAAkB;EAEjE,AADA,IAAU,GACV,IAAS;CACV,CAAC;CAID,IAAI,MAAY,KAAA,KAAa,MAAW,KAAA,GACvC,MAAU,MAAM,kEAAkE;CAEnF,OAAO;EAAE;EAAS;EAAS;CAAO;AACnC"}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@ryuzaki13/react-foundation-lib",
-	"version": "2.30.1",
+	"version": "2.31.0",
 	"description": "Reusable React and TypeScript foundation utilities, hooks, and primitives.",
 	"license": "MIT",
 	"author": "Ryuzaki13",
@@ -161,6 +161,10 @@
 			"types": "./dist/presets/index.d.ts",
 			"import": "./dist/presets/index.js"
 		},
+		"./promise": {
+			"types": "./dist/promise/index.d.ts",
+			"import": "./dist/promise/index.js"
+		},
 		"./pwa": {
 			"types": "./dist/pwa/index.d.ts",
 			"import": "./dist/pwa/index.js"

package/src/promise/README.md

@@ -0,0 +1,44 @@
+# Управляемое ожидание через Promise
+
+Модуль `@ryuzaki13/react-foundation-lib/promise` создаёт Promise, который можно
+завершить из внешнего callback или события. Он подходит для ожидания освобождения
+ресурсов, остановки фоновой операции и других технических lifecycle без знания
+конкретного приложения.
+
+```ts
+import { createDeferredPromise } from "@ryuzaki13/react-foundation-lib/promise";
+
+const completion = createDeferredPromise<void>();
+
+// Владелец операции завершает ожидание после освобождения своих ресурсов.
+completion.resolve();
+await completion.promise;
+```
+
+## Публичный API
+
+```ts
+type DeferredPromise<T> = {
+	readonly promise: Promise<T>;
+	readonly resolve: (value: T | PromiseLike<T>) => void;
+	readonly reject: (reason?: unknown) => void;
+};
+
+function createDeferredPromise<T>(): DeferredPromise<T>;
+```
+
+`promise` остаётся незавершённым до вызова `resolve` или `reject`. `resolve`
+принимает значение либо другой Promise/thenable и ожидает его итог. Для
+`DeferredPromise<void>` допустим вызов `resolve()` без аргумента. `reject`
+сохраняет исходную причину отказа, в том числе значение, отличное от `Error`.
+
+Каждый вызов создаёт независимое ожидание. Нативный Promise сохраняет первое
+решение: последующие вызовы `resolve`/`reject` его не меняют. Сам примитив не
+добавляет отмену, timeout или обработчик ошибок; владелец операции отвечает за
+обязательное завершение ожидания и обработку rejection.
+
+## Совместимость
+
+Реализация использует обычный `new Promise` и не требует API новее ES2022.
+Импорт не устанавливает полифиллы и не изменяет глобальный `Promise`.
+Модуль не зависит от React, Router, браузерного хранилища или Node.js.