@ryuzaki13/react-foundation-lib 2.29.0 → 2.30.0

package/README.md

@@ -125,6 +125,7 @@ npm run pack:dry-run
 | `/form`                | [`form/README.mdx`](./src/form/README.mdx)                                     |
 | `/formatters`          | [`formatters/README.mdx`](./src/formatters/README.mdx) и его предметные README |
 | `/formulas`            | [`formulas/README.mdx`](./src/formulas/README.mdx)                             |
+| `/value-transformers`  | [Преобразования числовых значений](./src/value-transformers/README.md)        |
 | `/hooks`               | [`hooks/README.mdx`](./src/hooks/README.mdx)                                   |
 | `/http`                | [`http/README.mdx`](./src/http/README.mdx)                                     |
 | `/media`               | [`media/README.mdx`](./src/media/README.mdx)                                   |

package/dist/value-transformers/execute.d.ts

@@ -0,0 +1,16 @@
+import { type ValueTransformerCompileResult, type ValueTransformerExecutionResult } from "./types";
+/**
+ * Фиксирует доверенную функцию один раз для многократной обработки значений.
+ *
+ * Вход и результат не приводятся к числу и не заменяются значением по умолчанию:
+ * parsing и правила пустых данных принадлежат самой функции преобразования.
+ */
+export declare function compileValueTransformer(args: {
+    transformerId: string | undefined;
+}): ValueTransformerCompileResult;
+/** Разовый запуск через активный реестр; для строк таблицы предпочтительна предварительная компиляция. */
+export declare function executeValueTransformer(args: {
+    transformerId: string | undefined;
+    value: unknown;
+}): ValueTransformerExecutionResult;
+//# sourceMappingURL=execute.d.ts.map

package/dist/value-transformers/execute.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"execute.d.ts","sourceRoot":"","sources":["../../src/value-transformers/execute.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,KAAK,6BAA6B,EAAE,KAAK,+BAA+B,EAAE,MAAM,SAAS,CAAC;AAEnG;;;;;GAKG;AACH,wBAAgB,uBAAuB,CAAC,IAAI,EAAE;IAAE,aAAa,EAAE,MAAM,GAAG,SAAS,CAAA;CAAE,GAAG,6BAA6B,CAelH;AAED,0GAA0G;AAC1G,wBAAgB,uBAAuB,CAAC,IAAI,EAAE;IAAE,aAAa,EAAE,MAAM,GAAG,SAAS,CAAC;IAAC,KAAK,EAAE,OAAO,CAAA;CAAE,GAAG,+BAA+B,CAGpI"}

package/dist/value-transformers/index.d.ts

@@ -0,0 +1,4 @@
+export { compileValueTransformer, executeValueTransformer } from "./execute";
+export { configureValueTransformerRegistry, createValueTransformerRegistry, getValueTransformerById, getValueTransformerList, type ValueTransformerRegistry } from "./registry";
+export { type ValueTransformerCompiledExecutor, type ValueTransformerCompileResult, type ValueTransformerDefinition, type ValueTransformerExecutionResult, type ValueTransformerFn } from "./types";
+//# sourceMappingURL=index.d.ts.map

package/dist/value-transformers/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/value-transformers/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,uBAAuB,EAAE,uBAAuB,EAAE,MAAM,WAAW,CAAC;AAC7E,OAAO,EACN,iCAAiC,EACjC,8BAA8B,EAC9B,uBAAuB,EACvB,uBAAuB,EACvB,KAAK,wBAAwB,EAC7B,MAAM,YAAY,CAAC;AACpB,OAAO,EACN,KAAK,gCAAgC,EACrC,KAAK,6BAA6B,EAClC,KAAK,0BAA0B,EAC/B,KAAK,+BAA+B,EACpC,KAAK,kBAAkB,EACvB,MAAM,SAAS,CAAC"}

package/dist/value-transformers/index.js

@@ -0,0 +1,69 @@
+//#region src/value-transformers/registry.ts
+function e(e) {
+	let t = /* @__PURE__ */ new Map(), n = [];
+	for (let r of e) {
+		let e = r.id.trim();
+		if (!e) throw Error("ID преобразования значения не может быть пустым.");
+		if (t.has(e)) throw Error(`Найден дублирующийся transformerId: ${e}.`);
+		let i = Object.freeze({
+			...r,
+			id: e,
+			name: r.name.trim(),
+			description: r.description.trim(),
+			...r.keywords === void 0 ? {} : { keywords: Object.freeze([...r.keywords]) }
+		});
+		t.set(e, i), n.push(i);
+	}
+	return Object.freeze({
+		list: Object.freeze(n),
+		byId: t
+	});
+}
+var t = e([]);
+function n(e) {
+	t = e;
+}
+function r() {
+	return t.list;
+}
+function i(e) {
+	let n = e?.trim();
+	return n ? t.byId.get(n) : void 0;
+}
+//#endregion
+//#region src/value-transformers/execute.ts
+function a(e) {
+	let t = i(e.transformerId);
+	if (!t) return {
+		ok: !1,
+		reason: "transformer_not_found"
+	};
+	let n = t.fn;
+	return {
+		ok: !0,
+		execute: (e) => {
+			try {
+				return {
+					ok: !0,
+					value: n(e)
+				};
+			} catch {
+				return {
+					ok: !1,
+					reason: "runtime_error"
+				};
+			}
+		}
+	};
+}
+function o(e) {
+	let t = a(e);
+	return t.ok ? t.execute(e.value) : {
+		ok: !1,
+		reason: t.reason
+	};
+}
+//#endregion
+export { a as compileValueTransformer, n as configureValueTransformerRegistry, e as createValueTransformerRegistry, o as executeValueTransformer, i as getValueTransformerById, r as getValueTransformerList };
+
+//# sourceMappingURL=index.js.map

package/dist/value-transformers/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","names":[],"sources":["../../src/value-transformers/registry.ts","../../src/value-transformers/execute.ts"],"sourcesContent":["import { type ValueTransformerDefinition } from \"./types\";\n\nexport type ValueTransformerRegistry = Readonly<{\n\tlist: readonly ValueTransformerDefinition[];\n\tbyId: ReadonlyMap<string, ValueTransformerDefinition>;\n}>;\n\n/** Создаёт независимый каталог с устойчивыми ID и неизменяемыми метаданными. */\nexport function createValueTransformerRegistry(definitions: readonly ValueTransformerDefinition[]): ValueTransformerRegistry {\n\tconst byId = new Map<string, ValueTransformerDefinition>();\n\tconst list: ValueTransformerDefinition[] = [];\n\n\tfor (const definition of definitions) {\n\t\tconst id = definition.id.trim();\n\t\tif (!id) throw new Error(\"ID преобразования значения не может быть пустым.\");\n\t\tif (byId.has(id)) throw new Error(`Найден дублирующийся transformerId: ${id}.`);\n\n\t\tconst normalizedDefinition: ValueTransformerDefinition = Object.freeze({\n\t\t\t...definition,\n\t\t\tid,\n\t\t\tname: definition.name.trim(),\n\t\t\tdescription: definition.description.trim(),\n\t\t\t...(definition.keywords === undefined ? {} : { keywords: Object.freeze([...definition.keywords]) })\n\t\t});\n\t\tbyId.set(id, normalizedDefinition);\n\t\tlist.push(normalizedDefinition);\n\t}\n\n\treturn Object.freeze({ list: Object.freeze(list), byId });\n}\n\nlet valueTransformerRegistry = createValueTransformerRegistry([]);\n\n/**\n * Устанавливает каталог host-приложения до первого чтения или компиляции.\n * Библиотека предоставляет механизм и не регистрирует прикладные преобразования.\n */\nexport function configureValueTransformerRegistry(registry: ValueTransformerRegistry): void {\n\tvalueTransformerRegistry = registry;\n}\n\nexport function getValueTransformerList(): readonly ValueTransformerDefinition[] {\n\treturn valueTransformerRegistry.list;\n}\n\nexport function getValueTransformerById(transformerId: string | undefined): ValueTransformerDefinition | undefined {\n\tconst id = transformerId?.trim();\n\treturn id ? valueTransformerRegistry.byId.get(id) : undefined;\n}\n","import { getValueTransformerById } from \"./registry\";\nimport { type ValueTransformerCompileResult, type ValueTransformerExecutionResult } from \"./types\";\n\n/**\n * Фиксирует доверенную функцию один раз для многократной обработки значений.\n *\n * Вход и результат не приводятся к числу и не заменяются значением по умолчанию:\n * parsing и правила пустых данных принадлежат самой функции преобразования.\n */\nexport function compileValueTransformer(args: { transformerId: string | undefined }): ValueTransformerCompileResult {\n\tconst definition = getValueTransformerById(args.transformerId);\n\tif (!definition) return { ok: false, reason: \"transformer_not_found\" };\n\tconst fn = definition.fn;\n\n\treturn {\n\t\tok: true,\n\t\texecute: (value) => {\n\t\t\ttry {\n\t\t\t\treturn { ok: true, value: fn(value) };\n\t\t\t} catch {\n\t\t\t\treturn { ok: false, reason: \"runtime_error\" };\n\t\t\t}\n\t\t}\n\t};\n}\n\n/** Разовый запуск через активный реестр; для строк таблицы предпочтительна предварительная компиляция. */\nexport function executeValueTransformer(args: { transformerId: string | undefined; value: unknown }): ValueTransformerExecutionResult {\n\tconst compiled = compileValueTransformer(args);\n\treturn compiled.ok ? compiled.execute(args.value) : { ok: false, reason: compiled.reason };\n}\n"],"mappings":";AAQA,SAAgB,EAA+B,GAA8E;CAC5H,IAAM,oBAAO,IAAI,IAAwC,GACnD,IAAqC,CAAC;CAE5C,KAAK,IAAM,KAAc,GAAa;EACrC,IAAM,IAAK,EAAW,GAAG,KAAK;EAC9B,IAAI,CAAC,GAAI,MAAU,MAAM,kDAAkD;EAC3E,IAAI,EAAK,IAAI,CAAE,GAAG,MAAU,MAAM,uCAAuC,EAAG,EAAE;EAE9E,IAAM,IAAmD,OAAO,OAAO;GACtE,GAAG;GACH;GACA,MAAM,EAAW,KAAK,KAAK;GAC3B,aAAa,EAAW,YAAY,KAAK;GACzC,GAAI,EAAW,aAAa,KAAA,IAAY,CAAC,IAAI,EAAE,UAAU,OAAO,OAAO,CAAC,GAAG,EAAW,QAAQ,CAAC,EAAE;EAClG,CAAC;EAED,AADA,EAAK,IAAI,GAAI,CAAoB,GACjC,EAAK,KAAK,CAAoB;CAC/B;CAEA,OAAO,OAAO,OAAO;EAAE,MAAM,OAAO,OAAO,CAAI;EAAG;CAAK,CAAC;AACzD;AAEA,IAAI,IAA2B,EAA+B,CAAC,CAAC;AAMhE,SAAgB,EAAkC,GAA0C;CAC3F,IAA2B;AAC5B;AAEA,SAAgB,IAAiE;CAChF,OAAO,EAAyB;AACjC;AAEA,SAAgB,EAAwB,GAA2E;CAClH,IAAM,IAAK,GAAe,KAAK;CAC/B,OAAO,IAAK,EAAyB,KAAK,IAAI,CAAE,IAAI,KAAA;AACrD;;;ACvCA,SAAgB,EAAwB,GAA4E;CACnH,IAAM,IAAa,EAAwB,EAAK,aAAa;CAC7D,IAAI,CAAC,GAAY,OAAO;EAAE,IAAI;EAAO,QAAQ;CAAwB;CACrE,IAAM,IAAK,EAAW;CAEtB,OAAO;EACN,IAAI;EACJ,UAAU,MAAU;GACnB,IAAI;IACH,OAAO;KAAE,IAAI;KAAM,OAAO,EAAG,CAAK;IAAE;GACrC,QAAQ;IACP,OAAO;KAAE,IAAI;KAAO,QAAQ;IAAgB;GAC7C;EACD;CACD;AACD;AAGA,SAAgB,EAAwB,GAA8F;CACrI,IAAM,IAAW,EAAwB,CAAI;CAC7C,OAAO,EAAS,KAAK,EAAS,QAAQ,EAAK,KAAK,IAAI;EAAE,IAAI;EAAO,QAAQ,EAAS;CAAO;AAC1F"}

package/dist/value-transformers/registry.d.ts

@@ -0,0 +1,15 @@
+import { type ValueTransformerDefinition } from "./types";
+export type ValueTransformerRegistry = Readonly<{
+    list: readonly ValueTransformerDefinition[];
+    byId: ReadonlyMap<string, ValueTransformerDefinition>;
+}>;
+/** Создаёт независимый каталог с устойчивыми ID и неизменяемыми метаданными. */
+export declare function createValueTransformerRegistry(definitions: readonly ValueTransformerDefinition[]): ValueTransformerRegistry;
+/**
+ * Устанавливает каталог host-приложения до первого чтения или компиляции.
+ * Библиотека предоставляет механизм и не регистрирует прикладные преобразования.
+ */
+export declare function configureValueTransformerRegistry(registry: ValueTransformerRegistry): void;
+export declare function getValueTransformerList(): readonly ValueTransformerDefinition[];
+export declare function getValueTransformerById(transformerId: string | undefined): ValueTransformerDefinition | undefined;
+//# sourceMappingURL=registry.d.ts.map

package/dist/value-transformers/registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../../src/value-transformers/registry.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,0BAA0B,EAAE,MAAM,SAAS,CAAC;AAE1D,MAAM,MAAM,wBAAwB,GAAG,QAAQ,CAAC;IAC/C,IAAI,EAAE,SAAS,0BAA0B,EAAE,CAAC;IAC5C,IAAI,EAAE,WAAW,CAAC,MAAM,EAAE,0BAA0B,CAAC,CAAC;CACtD,CAAC,CAAC;AAEH,gFAAgF;AAChF,wBAAgB,8BAA8B,CAAC,WAAW,EAAE,SAAS,0BAA0B,EAAE,GAAG,wBAAwB,CAqB3H;AAID;;;GAGG;AACH,wBAAgB,iCAAiC,CAAC,QAAQ,EAAE,wBAAwB,GAAG,IAAI,CAE1F;AAED,wBAAgB,uBAAuB,IAAI,SAAS,0BAA0B,EAAE,CAE/E;AAED,wBAAgB,uBAAuB,CAAC,aAAa,EAAE,MAAM,GAAG,SAAS,GAAG,0BAA0B,GAAG,SAAS,CAGjH"}

package/dist/value-transformers/types.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Синхронное преобразование одного исходного значения в числовое значение.
+ *
+ * Функция владеет разбором входа и решением для пустых или ошибочных данных.
+ * Runtime сохраняет её результат буквально, включая null и undefined.
+ */
+export type ValueTransformerFn = (value: unknown) => number | null | undefined;
+/** Метаданные доверенной функции; прикладной каталог определяет host-приложение. */
+export type ValueTransformerDefinition = Readonly<{
+    id: string;
+    name: string;
+    description: string;
+    keywords?: readonly string[];
+    fn: ValueTransformerFn;
+}>;
+/** Ошибка механизма отделена от значения, которое решила вернуть сама функция. */
+export type ValueTransformerExecutionResult = {
+    ok: true;
+    value: number | null | undefined;
+} | {
+    ok: false;
+    reason: "transformer_not_found" | "runtime_error";
+};
+export type ValueTransformerCompiledExecutor = (value: unknown) => ValueTransformerExecutionResult;
+export type ValueTransformerCompileResult = {
+    ok: true;
+    execute: ValueTransformerCompiledExecutor;
+} | {
+    ok: false;
+    reason: "transformer_not_found";
+};
+//# sourceMappingURL=types.d.ts.map

package/dist/value-transformers/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/value-transformers/types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,MAAM,MAAM,kBAAkB,GAAG,CAAC,KAAK,EAAE,OAAO,KAAK,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC;AAE/E,oFAAoF;AACpF,MAAM,MAAM,0BAA0B,GAAG,QAAQ,CAAC;IACjD,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC7B,EAAE,EAAE,kBAAkB,CAAC;CACvB,CAAC,CAAC;AAEH,kFAAkF;AAClF,MAAM,MAAM,+BAA+B,GAC1C;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,KAAK,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,uBAAuB,GAAG,eAAe,CAAA;CAAE,CAAC;AAEnH,MAAM,MAAM,gCAAgC,GAAG,CAAC,KAAK,EAAE,OAAO,KAAK,+BAA+B,CAAC;AAEnG,MAAM,MAAM,6BAA6B,GACxC;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,OAAO,EAAE,gCAAgC,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,uBAAuB,CAAA;CAAE,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@ryuzaki13/react-foundation-lib",
-	"version": "2.29.0",
+	"version": "2.30.0",
 	"description": "Reusable React and TypeScript foundation utilities, hooks, and primitives.",
 	"license": "MIT",
 	"author": "Ryuzaki13",
@@ -217,6 +217,10 @@
 			"types": "./dist/validators/index.d.ts",
 			"import": "./dist/validators/index.js"
 		},
+		"./value-transformers": {
+			"types": "./dist/value-transformers/index.d.ts",
+			"import": "./dist/value-transformers/index.js"
+		},
 		"./virtualizer": {
 			"types": "./dist/virtualizer/index.d.ts",
 			"import": "./dist/virtualizer/index.js"

package/src/value-transformers/README.md

@@ -0,0 +1,56 @@
+# Преобразования числовых значений
+
+Публичный subpath `@ryuzaki13/react-foundation-lib/value-transformers` предоставляет реестр и синхронное исполнение доверенных функций одного аргумента. Прикладные определения принадлежат host-приложению; встроенного каталога операций или единиц измерения нет.
+
+## Контракт функции
+
+```ts
+import { type ValueTransformerDefinition } from "@ryuzaki13/react-foundation-lib/value-transformers";
+
+const definition: ValueTransformerDefinition = {
+	id: "double",
+	name: "Удвоение",
+	description: "Удваивает числовое значение; остальные входы оставляет без результата.",
+	fn: (value) => (typeof value === "number" ? value * 2 : undefined)
+};
+```
+
+`ValueTransformerFn` принимает `unknown` и возвращает `number | null | undefined`. Функция сама определяет разбор строк, допустимые типы, конечность числа и поведение при пустых или ошибочных данных. Механизм не вызывает `Number`, не подставляет `0` и не меняет результат функции, включая `null`, `undefined`, `NaN` или `Infinity`. Эти правила не наследуются от табличных формул или display-форматтеров.
+
+Функция должна работать синхронно. Вход передаётся буквально и не копируется: определение не должно изменять объекты строки, Query cache или внешнее состояние. Асинхронные функции и строковые результаты не входят в TypeScript-контракт.
+
+## Реестр
+
+```ts
+import { configureValueTransformerRegistry, createValueTransformerRegistry } from "@ryuzaki13/react-foundation-lib/value-transformers";
+
+const registry = createValueTransformerRegistry([definition]);
+configureValueTransformerRegistry(registry);
+```
+
+Host устанавливает каталог в composition root до чтения или компиляции. `createValueTransformerRegistry` сохраняет порядок определений, удаляет внешние пробелы в `id`, `name` и `description`, отклоняет пустой и повторный ID. Registry object, список, определения и независимые копии `keywords` заморожены; индекс представлен `ReadonlyMap`.
+
+`getValueTransformerList()` возвращает текущий readonly-список. `getValueTransformerById(id)` удаляет внешние пробелы в ID и возвращает `undefined` для пустого или неизвестного ID. Создание каталога не устанавливает его автоматически; `configureValueTransformerRegistry` полностью заменяет активный каталог данного экземпляра модуля.
+
+## Исполнение
+
+```ts
+import { compileValueTransformer, executeValueTransformer } from "@ryuzaki13/react-foundation-lib/value-transformers";
+
+executeValueTransformer({ transformerId: "double", value: 3 });
+// { ok: true, value: 6 }
+
+const compiled = compileValueTransformer({ transformerId: "double" });
+if (compiled.ok) {
+	compiled.execute(3); // { ok: true, value: 6 }
+	compiled.execute(null); // { ok: true, value: undefined } — решение fn из примера
+}
+```
+
+Разовый `executeValueTransformer` использует активный каталог. Для повторной обработки строк `compileValueTransformer` фиксирует функцию один раз: замена исходного определения или активного registry не меняет уже созданный executor.
+
+Compile-result: `{ ok: true, execute } | { ok: false, reason: "transformer_not_found" }`.
+
+Execution-result: `{ ok: true, value: number | null | undefined } | { ok: false, reason: "transformer_not_found" | "runtime_error" }`. Неизвестный ID даёт `transformer_not_found`; исключение функции — `runtime_error`. Ошибка не содержит исходное значение и не превращается в успешный результат по умолчанию. Потребитель отвечает за контекст диагностики и отображение ошибки.
+
+Модуль не читает поля строки, не строит граф зависимостей и не материализует колонки. Потребитель выбирает исходное поле, передаёт его значение и записывает успешный результат в принадлежащую ему модель до исполнения зависимых формул. Сериализуемая конфигурация хранит стабильный ID преобразования, а функция остаётся доверенным кодом приложения.