@nemigo/helpers 0.13.3 → 1.5.0

package/dist/url/slug.js

@@ -0,0 +1,102 @@
+/**
+ * Карта для транслитерации кириллических символов в латинские.
+ * Содержит соответствия для всех букв русского алфавита в нижнем регистре.
+ * Используется в функции {@link toSlug} для создания URL-friendly строк
+ *
+ * @example
+ * ```typescript
+ * cyrillicToLatinMap.get("а"); // "a"
+ * cyrillicToLatinMap.get("ё"); // "yo"
+ * cyrillicToLatinMap.get("ъ"); // ""
+ * ```
+ */
+export const cyrillicToLatinMap = new Map([
+    ["а", "a"],
+    ["б", "b"],
+    ["в", "v"],
+    ["г", "g"],
+    ["д", "d"],
+    ["е", "e"],
+    ["ё", "yo"],
+    ["ж", "zh"],
+    ["з", "z"],
+    ["и", "i"],
+    ["й", "y"],
+    ["к", "k"],
+    ["л", "l"],
+    ["м", "m"],
+    ["н", "n"],
+    ["о", "o"],
+    ["п", "p"],
+    ["р", "r"],
+    ["с", "s"],
+    ["т", "t"],
+    ["у", "u"],
+    ["ф", "f"],
+    ["х", "h"],
+    ["ц", "ts"],
+    ["ч", "ch"],
+    ["ш", "sh"],
+    ["щ", "sch"],
+    ["ъ", ""],
+    ["ы", "y"],
+    ["ь", ""],
+    ["э", "e"],
+    ["ю", "yu"],
+    ["я", "ya"],
+]);
+/**
+ * Конвертирует кириллицу в латиницу, удаляет специальные символы, нормализует пробелы и заменяет их на разделитель
+ *
+ * @param str - Строка для преобразования в slug
+ * @param [separator="-"] - Разделитель для замены пробелов
+ *
+ * @example
+ * ```typescript
+ * toSlug("Привет, мир!"); // "privet-mir"
+ * toSlug("JavaScript Programming"); // "javascript-programming"
+ * toSlug("Café & Restaurant", "_"); // "cafe_restaurant"
+ * toSlug("Специальные символы!!!", "."); // "specialnye-simvoly"
+ * ```
+ */
+export const toSlug = (str, separator = "-") => {
+    const buf = [];
+    let wasSpace = false;
+    for (const _char of str.split("")) {
+        const char = _char.toLowerCase();
+        const code = char.charCodeAt(0);
+        // Кириллица (а-я, ё)
+        if ((code >= 1072 && code <= 1103) || code === 1105) {
+            buf.push(cyrillicToLatinMap.get(char) ?? char);
+            wasSpace = false;
+        }
+        // Цифры (0-9)
+        else if (code >= 48 && code <= 57) {
+            buf.push(char);
+            wasSpace = false;
+        }
+        // Латиница (a-z)
+        else if (code >= 97 && code <= 122) {
+            buf.push(char);
+            wasSpace = false;
+        }
+        // Пробуем нормализовать символы с диакритиками в латиницу (é -> e)
+        else {
+            const normalized = char.normalize("NFD").replace(/[\u0300-\u036f]/g, "");
+            const nCode = normalized.charCodeAt(0);
+            if (normalized.length === 1 && nCode >= 97 && nCode <= 122) {
+                buf.push(normalized);
+                wasSpace = false;
+            }
+            else {
+                if (!wasSpace && buf.length > 0) {
+                    buf.push(separator);
+                    wasSpace = true;
+                }
+            }
+        }
+    }
+    const acc = buf.join("");
+    // Убираем завершающий separator (с учётом многосимвольного separator)
+    return separator && acc.endsWith(separator) ? acc.slice(0, -separator.length) : acc;
+};

package/dist/veil.d.ts

@@ -0,0 +1,14 @@
+import type { Serializable } from "./types.js";
+/**
+ * Декодирует строку, закодированную функцией {@link veil}, в исходное значение и десериализует
+ *
+ * @remarks Для десериализации используется {@link JSON.parse}
+ */
+export declare const unveil: <T = string>(veiled: string) => T;
+/**
+ * Кодирует serializable-значение в URL-safe base64-строку
+ *
+ * @remarks Для сериализации используется {@link JSON.stringify}
+ * @remarks Поддерживает полный Unicode, включая смайлики и символы вне BMP
+ */
+export declare const veil: (snap: Serializable) => string;

package/dist/veil.js

@@ -0,0 +1,26 @@
+const encoder = new TextEncoder();
+const decoder = new TextDecoder();
+/**
+ * Декодирует строку, закодированную функцией {@link veil}, в исходное значение и десериализует
+ *
+ * @remarks Для десериализации используется {@link JSON.parse}
+ */
+export const unveil = (veiled) => {
+    const decoded = atob(decodeURIComponent(veiled));
+    const bytes = new Uint8Array(decoded.length);
+    for (let i = 0; i < decoded.length; i++)
+        bytes[i] = decoded.charCodeAt(i);
+    return JSON.parse(decoder.decode(bytes));
+};
+/**
+ * Кодирует serializable-значение в URL-safe base64-строку
+ *
+ * @remarks Для сериализации используется {@link JSON.stringify}
+ * @remarks Поддерживает полный Unicode, включая смайлики и символы вне BMP
+ */
+export const veil = (snap) => {
+    const str = JSON.stringify(snap);
+    const bytes = encoder.encode(str);
+    const binary = String.fromCharCode(...bytes);
+    return encodeURIComponent(btoa(binary));
+};

package/dist/xod.d.ts

@@ -1,26 +1,247 @@
 import { z } from "zod";
-export declare const invalid: (value: unknown, ctx: z.core.$RefinementCtx, { message, expected }: {
+/**
+ * Параметры для создания ошибки валидации {@link https://zod.dev Zod}
+ */
+export interface InvalidValueIssue {
+    /**
+     * Исходное значение которое не прошло валидацию
+     */
+    value: unknown;
+    /**
+     * Контекст валидации {@link https://zod.dev Zod}
+     */
+    ctx: z.core.$RefinementCtx;
+    /**
+     * Сообщение об ошибке
+     */
     message: string;
+    /**
+     * Ожидаемый тип значения
+     */
     expected: string;
-}) => never;
+}
+/**
+ * Добавляет ошибку валидации в контекст {@link https://zod.dev Zod}-схемы через {@link RefinementCtx.addIssue} и прерывает выполнение
+ */
+export declare const throwValueIssue: (props: InvalidValueIssue) => never;
+/**
+ * Схема для отсутствующих значений
+ *
+ * Замаскировано под эквивалент: `z.union([z.null().optional().transform(() => undefined)])`
+ *
+ * Принимает:
+ * - `null` → `undefined`
+ * - `undefined` → `undefined`
+ * - `"nUll"` (любой регистр) → `undefined`
+ * - `"undeFinEd"` (любой регистр) → `undefined`
+ * - `""` → `undefined`
+ * - `ETC` → ZodError
+ */
 export declare const nullSchema: z.ZodPipe<z.ZodOptional<z.ZodNull>, z.ZodTransform<undefined, null | undefined>>;
+/**
+ * Создаёт схему: либо {@link nullSchema}, либо значения по переданной схеме
+ *
+ * @example
+ * ```typescript
+ * const nullableString = toNullable(z.string());
+ * nullableString.parse("hello"); // "hello"
+ * nullableString.parse(null);    // undefined
+ * nullableString.parse("null");  // undefined
+ * ```
+ */
+export declare const toNullable: <T extends z.core.SomeType>(schema: T) => z.ZodUnion<[typeof nullSchema, T]>;
+/**
+ * Схема для boolean-значений через {@link caseBoolean}
+ *
+ * Замаскировано под эквивалент: `z.boolean().transform((v) => v)`
+ */
 export declare const booleanSchema: z.ZodPipe<z.ZodBoolean, z.ZodTransform<boolean, boolean>>;
-export declare const booleanSchemaOptional: z.ZodUnion<readonly [z.ZodPipe<z.ZodOptional<z.ZodNull>, z.ZodTransform<undefined, null | undefined>>, z.ZodPipe<z.ZodBoolean, z.ZodTransform<boolean, boolean>>]>;
+/**
+ * Сочетает {@link nullSchema} и {@link booleanSchema}
+ */
+export declare const booleanSchemaOptional: z.ZodUnion<[z.ZodPipe<z.ZodOptional<z.ZodNull>, z.ZodTransform<undefined, null | undefined>>, z.ZodPipe<z.ZodBoolean, z.ZodTransform<boolean, boolean>>]>;
+/**
+ * Схема для числовых значений через {@link caseNumber}
+ *
+ * Замаскировано под эквивалент: `z.union([z.number(), z.string()]).transform((v) => Number(v))`
+ */
 export declare const numberSchema: z.ZodPipe<z.ZodUnion<[z.ZodNumber, z.ZodString]>, z.ZodTransform<number, string | number>>;
-export declare const numberSchemaOptional: z.ZodUnion<readonly [z.ZodPipe<z.ZodOptional<z.ZodNull>, z.ZodTransform<undefined, null | undefined>>, z.ZodPipe<z.ZodUnion<[z.ZodNumber, z.ZodString]>, z.ZodTransform<number, string | number>>]>;
-export declare const stringSchema: z.ZodUnion<[z.ZodString, z.ZodPipe<z.ZodNumber, z.ZodTransform<string, number>>]>;
-export declare const stringSchemaOptional: z.ZodUnion<readonly [z.ZodPipe<z.ZodOptional<z.ZodNull>, z.ZodTransform<undefined, null | undefined>>, z.ZodUnion<[z.ZodString, z.ZodPipe<z.ZodNumber, z.ZodTransform<string, number>>]>]>;
-declare const _default: {
-    invalid: (value: unknown, ctx: z.core.$RefinementCtx, { message, expected }: {
-        message: string;
-        expected: string;
-    }) => never;
+/**
+ * Сочетает {@link nullSchema} и {@link numberSchema}
+ */
+export declare const numberSchemaOptional: z.ZodUnion<[z.ZodPipe<z.ZodOptional<z.ZodNull>, z.ZodTransform<undefined, null | undefined>>, z.ZodPipe<z.ZodUnion<[z.ZodNumber, z.ZodString]>, z.ZodTransform<number, string | number>>]>;
+/**
+ * Отличается типизацией от {@link numberSchema} тем, что якобы не принимает строки
+ *
+ * Замаскировано под эквивалент: `z.number().transform((v) => v)`
+ *
+ * @example
+ * ```typescript
+ * numberStrictSchema.parse(42);     // 42
+ * numberStrictSchema.parse("42");   // Ошибка типизации!
+ * ```
+ */
+export declare const numberStrictSchema: z.ZodPipe<z.ZodNumber, z.ZodTransform<number, number>>;
+/**
+ * Сочетает {@link nullSchema} и {@link numberStrictSchema}
+ */
+export declare const numberStrictSchemaOptional: z.ZodUnion<[typeof nullSchema, typeof numberStrictSchema]>;
+/**
+ * Схема для строковых значений через {@link caseString}
+ *
+ * Замаскировано под эквивалент: `z.union([z.number(), z.string()]).transform((v) => String(v))`
+ */
+export declare const stringSchema: z.ZodPipe<z.ZodUnion<[z.ZodNumber, z.ZodString]>, z.ZodTransform<string, string | number>>;
+/**
+ * Сочетает {@link nullSchema} и {@link stringSchema}
+ */
+export declare const stringSchemaOptional: z.ZodUnion<[z.ZodPipe<z.ZodOptional<z.ZodNull>, z.ZodTransform<undefined, null | undefined>>, z.ZodPipe<z.ZodUnion<[z.ZodNumber, z.ZodString]>, z.ZodTransform<string, string | number>>]>;
+/**
+ * Отличается типизацией от {@link stringSchema} тем, что якобы не принимает числа
+ *
+ * Замаскировано под эквивалент: `z.string().transform((v) => v)`
+ *
+ * @example
+ * ```typescript
+ * stringStrictSchema.parse("hello"); // "hello"
+ * stringStrictSchema.parse(42);      // Ошибка типизации!
+ * ```
+ */
+export declare const stringStrictSchema: z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>;
+/**
+ * Сочетает {@link nullSchema} и {@link stringStrictSchema}
+ */
+export declare const stringStrictSchemaOptional: z.ZodUnion<[typeof nullSchema, typeof stringStrictSchema]>;
+/**
+ * Схема для {@link ZoneStamp}
+ */
+export declare const zoneStampSchema: z.ZodObject<{
+    stamp: z.ZodPipe<z.ZodUnion<[z.ZodNumber, z.ZodString]>, z.ZodTransform<number, string | number>>;
+    zone: z.ZodPipe<z.ZodUnion<[z.ZodNumber, z.ZodString]>, z.ZodTransform<number, string | number>>;
+}, z.core.$strip>;
+/**
+ * Сочетает {@link nullSchema} и {@link zoneStampSchema}
+ */
+export declare const zoneStampSchemaOptional: z.ZodUnion<[z.ZodPipe<z.ZodOptional<z.ZodNull>, z.ZodTransform<undefined, null | undefined>>, z.ZodObject<{
+    stamp: z.ZodPipe<z.ZodUnion<[z.ZodNumber, z.ZodString]>, z.ZodTransform<number, string | number>>;
+    zone: z.ZodPipe<z.ZodUnion<[z.ZodNumber, z.ZodString]>, z.ZodTransform<number, string | number>>;
+}, z.core.$strip>]>;
+/**
+ * Строгая версия {@link zoneStampSchema}, которая не якобы принимает строковые представления чисел
+ *
+ * @example
+ * ```typescript
+ * zoneStampStrictSchema.parse({ stamp: 1234567890, zone: 3 });     // { stamp: 1234567890, zone: 3 }
+ * zoneStampStrictSchema.parse({ stamp: 1234567890, zone: "3" }); // Ошибка типизации!
+ * ```
+ */
+export declare const zoneStampStrictSchema: z.ZodObject<{
+    stamp: typeof numberStrictSchema;
+    zone: typeof numberStrictSchema;
+}>;
+/**
+ * Сочетает {@link nullSchema} и {@link zoneStampStrictSchema}
+ */
+export declare const zoneStampStrictSchemaOptional: z.ZodUnion<[typeof nullSchema, typeof zoneStampStrictSchema]>;
+/**
+ * Схема для {@link LWH}
+ */
+export declare const lwhSchema: z.ZodObject<{
+    length: z.ZodPipe<z.ZodUnion<[z.ZodNumber, z.ZodString]>, z.ZodTransform<number, string | number>>;
+    width: z.ZodPipe<z.ZodUnion<[z.ZodNumber, z.ZodString]>, z.ZodTransform<number, string | number>>;
+    height: z.ZodPipe<z.ZodUnion<[z.ZodNumber, z.ZodString]>, z.ZodTransform<number, string | number>>;
+}, z.core.$strip>;
+/**
+ * Сочетает {@link nullSchema} и {@link lwhSchema}
+ */
+export declare const lwhSchemaOptional: z.ZodUnion<[z.ZodPipe<z.ZodOptional<z.ZodNull>, z.ZodTransform<undefined, null | undefined>>, z.ZodObject<{
+    length: z.ZodPipe<z.ZodUnion<[z.ZodNumber, z.ZodString]>, z.ZodTransform<number, string | number>>;
+    width: z.ZodPipe<z.ZodUnion<[z.ZodNumber, z.ZodString]>, z.ZodTransform<number, string | number>>;
+    height: z.ZodPipe<z.ZodUnion<[z.ZodNumber, z.ZodString]>, z.ZodTransform<number, string | number>>;
+}, z.core.$strip>]>;
+/**
+ * Отличается типизацией от {@link lwhSchema} тем, что якобы не принимает строковые представления чисел
+ *
+ * @example
+ * ```typescript
+ * lwhStrictSchema.parse({ length: 10, width: 20, height: 30 });        // { length: 10, width: 20, height: 30 }
+ * lwhStrictSchema.parse({ length: "10", width: "20", height: "30" });  // Ошибка типизации!
+ * ```
+ */
+export declare const lwhStrictSchema: z.ZodObject<{
+    length: typeof numberStrictSchema;
+    width: typeof numberStrictSchema;
+    height: typeof numberStrictSchema;
+}>;
+/**
+ * Сочетает {@link nullSchema} и {@link lwhStrictSchema}
+ */
+export declare const lwhStrictSchemaOptional: z.ZodUnion<[typeof nullSchema, typeof lwhStrictSchema]>;
+/**
+ * Коллекция расширенных {@link https://zod.dev Zod}-схем со встроенными преобразованиями типов
+ *
+ * @example
+ * ```typescript
+ * import { xod } from "./xod.js"; // or import xod from "./xod.js";
+ *
+ * const userSchema = z.object({
+ *   name: xod.string,           // Принимает string и number
+ *   age: xod.number,            // Принимает number и string
+ *   isActive: xod.boolean,      // Принимает boolean, number, string
+ *   notes: xod.stringOptional,  // Принимает string, number, null, undefined
+ *   created: xod.zoneStamp,     // Принимает объект с временной меткой и зоной
+ * });
+ * ```
+ */
+export declare const xod: {
+    throwValueIssue: (props: InvalidValueIssue) => never;
+    toNullable: <T extends z.core.SomeType>(schema: T) => z.ZodUnion<[typeof nullSchema, T]>;
     null: z.ZodPipe<z.ZodOptional<z.ZodNull>, z.ZodTransform<undefined, null | undefined>>;
     boolean: z.ZodPipe<z.ZodBoolean, z.ZodTransform<boolean, boolean>>;
-    booleanOptional: z.ZodUnion<readonly [z.ZodPipe<z.ZodOptional<z.ZodNull>, z.ZodTransform<undefined, null | undefined>>, z.ZodPipe<z.ZodBoolean, z.ZodTransform<boolean, boolean>>]>;
+    booleanOptional: z.ZodUnion<[z.ZodPipe<z.ZodOptional<z.ZodNull>, z.ZodTransform<undefined, null | undefined>>, z.ZodPipe<z.ZodBoolean, z.ZodTransform<boolean, boolean>>]>;
     number: z.ZodPipe<z.ZodUnion<[z.ZodNumber, z.ZodString]>, z.ZodTransform<number, string | number>>;
-    numberOptional: z.ZodUnion<readonly [z.ZodPipe<z.ZodOptional<z.ZodNull>, z.ZodTransform<undefined, null | undefined>>, z.ZodPipe<z.ZodUnion<[z.ZodNumber, z.ZodString]>, z.ZodTransform<number, string | number>>]>;
-    string: z.ZodUnion<[z.ZodString, z.ZodPipe<z.ZodNumber, z.ZodTransform<string, number>>]>;
-    stringOptional: z.ZodUnion<readonly [z.ZodPipe<z.ZodOptional<z.ZodNull>, z.ZodTransform<undefined, null | undefined>>, z.ZodUnion<[z.ZodString, z.ZodPipe<z.ZodNumber, z.ZodTransform<string, number>>]>]>;
+    numberStrict: z.ZodPipe<z.ZodNumber, z.ZodTransform<number, number>>;
+    numberOptional: z.ZodUnion<[z.ZodPipe<z.ZodOptional<z.ZodNull>, z.ZodTransform<undefined, null | undefined>>, z.ZodPipe<z.ZodUnion<[z.ZodNumber, z.ZodString]>, z.ZodTransform<number, string | number>>]>;
+    numberStrictOptional: z.ZodUnion<[z.ZodPipe<z.ZodOptional<z.ZodNull>, z.ZodTransform<undefined, null | undefined>>, z.ZodPipe<z.ZodNumber, z.ZodTransform<number, number>>]>;
+    string: z.ZodPipe<z.ZodUnion<[z.ZodNumber, z.ZodString]>, z.ZodTransform<string, string | number>>;
+    stringStrict: z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>;
+    stringOptional: z.ZodUnion<[z.ZodPipe<z.ZodOptional<z.ZodNull>, z.ZodTransform<undefined, null | undefined>>, z.ZodPipe<z.ZodUnion<[z.ZodNumber, z.ZodString]>, z.ZodTransform<string, string | number>>]>;
+    stringStrictOptional: z.ZodUnion<[z.ZodPipe<z.ZodOptional<z.ZodNull>, z.ZodTransform<undefined, null | undefined>>, z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>]>;
+    zoneStamp: z.ZodObject<{
+        stamp: z.ZodPipe<z.ZodUnion<[z.ZodNumber, z.ZodString]>, z.ZodTransform<number, string | number>>;
+        zone: z.ZodPipe<z.ZodUnion<[z.ZodNumber, z.ZodString]>, z.ZodTransform<number, string | number>>;
+    }, z.core.$strip>;
+    zoneStampOptional: z.ZodUnion<[z.ZodPipe<z.ZodOptional<z.ZodNull>, z.ZodTransform<undefined, null | undefined>>, z.ZodObject<{
+        stamp: z.ZodPipe<z.ZodUnion<[z.ZodNumber, z.ZodString]>, z.ZodTransform<number, string | number>>;
+        zone: z.ZodPipe<z.ZodUnion<[z.ZodNumber, z.ZodString]>, z.ZodTransform<number, string | number>>;
+    }, z.core.$strip>]>;
+    zoneStampStrict: z.ZodObject<{
+        stamp: typeof numberStrictSchema;
+        zone: typeof numberStrictSchema;
+    }, z.core.$strip>;
+    zoneStampStrictOptional: z.ZodUnion<[z.ZodPipe<z.ZodOptional<z.ZodNull>, z.ZodTransform<undefined, null | undefined>>, z.ZodObject<{
+        stamp: typeof numberStrictSchema;
+        zone: typeof numberStrictSchema;
+    }, z.core.$strip>]>;
+    lwh: z.ZodObject<{
+        length: z.ZodPipe<z.ZodUnion<[z.ZodNumber, z.ZodString]>, z.ZodTransform<number, string | number>>;
+        width: z.ZodPipe<z.ZodUnion<[z.ZodNumber, z.ZodString]>, z.ZodTransform<number, string | number>>;
+        height: z.ZodPipe<z.ZodUnion<[z.ZodNumber, z.ZodString]>, z.ZodTransform<number, string | number>>;
+    }, z.core.$strip>;
+    lwhOptional: z.ZodUnion<[z.ZodPipe<z.ZodOptional<z.ZodNull>, z.ZodTransform<undefined, null | undefined>>, z.ZodObject<{
+        length: z.ZodPipe<z.ZodUnion<[z.ZodNumber, z.ZodString]>, z.ZodTransform<number, string | number>>;
+        width: z.ZodPipe<z.ZodUnion<[z.ZodNumber, z.ZodString]>, z.ZodTransform<number, string | number>>;
+        height: z.ZodPipe<z.ZodUnion<[z.ZodNumber, z.ZodString]>, z.ZodTransform<number, string | number>>;
+    }, z.core.$strip>]>;
+    lwhStrict: z.ZodObject<{
+        length: typeof numberStrictSchema;
+        width: typeof numberStrictSchema;
+        height: typeof numberStrictSchema;
+    }, z.core.$strip>;
+    lwhStrictOptional: z.ZodUnion<[z.ZodPipe<z.ZodOptional<z.ZodNull>, z.ZodTransform<undefined, null | undefined>>, z.ZodObject<{
+        length: typeof numberStrictSchema;
+        width: typeof numberStrictSchema;
+        height: typeof numberStrictSchema;
+    }, z.core.$strip>]>;
 };
-export default _default;
+export default xod;

package/dist/xod.js

@@ -1,66 +1,240 @@
 import { caseBoolean, caseNumber, caseString } from "./cases.js";
 import { z } from "zod";
-export const invalid = (value, ctx, { message, expected }) => {
-    ctx.addIssue({
+/**
+ * Добавляет ошибку валидации в контекст {@link https://zod.dev Zod}-схемы через {@link RefinementCtx.addIssue} и прерывает выполнение
+ */
+export const throwValueIssue = (props) => {
+    props.ctx.addIssue({
         code: "invalid_type",
-        message,
-        input: value,
-        expected: expected,
+        message: props.message,
+        input: props.value,
+        expected: props.expected,
     });
     return z.NEVER;
 };
+//...
+/**
+ * Схема для отсутствующих значений
+ *
+ * Замаскировано под эквивалент: `z.union([z.null().optional().transform(() => undefined)])`
+ *
+ * Принимает:
+ * - `null` → `undefined`
+ * - `undefined` → `undefined`
+ * - `"nUll"` (любой регистр) → `undefined`
+ * - `"undeFinEd"` (любой регистр) → `undefined`
+ * - `""` → `undefined`
+ * - `ETC` → ZodError
+ */
 export const nullSchema = z.union([
-    z
-        .null()
-        .optional()
-        .transform(() => undefined),
+    // prettier-ignore
+    z.null().optional().transform(() => undefined),
     z.string().transform((value, ctx) => {
         if (!value)
             return undefined;
         const flat = value.trim().toLowerCase();
         if (flat === "undefined" || flat === "null")
             return undefined;
-        return invalid(value, ctx, {
+        return throwValueIssue({
+            ctx,
+            value,
             message: "It isn't a null / undefined",
             expected: "null / undefined (or string like null / undefined)",
         });
     }),
 ]);
+/**
+ * Создаёт схему: либо {@link nullSchema}, либо значения по переданной схеме
+ *
+ * @example
+ * ```typescript
+ * const nullableString = toNullable(z.string());
+ * nullableString.parse("hello"); // "hello"
+ * nullableString.parse(null);    // undefined
+ * nullableString.parse("null");  // undefined
+ * ```
+ */
+export const toNullable = (schema) => z.union([nullSchema, schema]);
 //...
+/**
+ * Схема для boolean-значений через {@link caseBoolean}
+ *
+ * Замаскировано под эквивалент: `z.boolean().transform((v) => v)`
+ */
 export const booleanSchema = z.unknown().transform((value, ctx) => caseBoolean(value, (result) => result === undefined
-    ? invalid(value, ctx, {
+    ? throwValueIssue({
+        ctx,
+        value,
         message: "It isn't a boolean",
         expected: "boolean (or string / number like boolean)",
     })
     : result));
-export const booleanSchemaOptional = z.union([nullSchema, booleanSchema]);
+/**
+ * Сочетает {@link nullSchema} и {@link booleanSchema}
+ */
+export const booleanSchemaOptional = toNullable(booleanSchema);
 //...
+/**
+ * Схема для числовых значений через {@link caseNumber}
+ *
+ * Замаскировано под эквивалент: `z.union([z.number(), z.string()]).transform((v) => Number(v))`
+ */
 export const numberSchema = z.unknown().transform((value, ctx) => caseNumber(value, (result) => result === undefined
-    ? invalid(value, ctx, {
+    ? throwValueIssue({
+        ctx,
+        value,
         message: "It isn't a number",
         expected: "number (or string like number)",
     })
     : result));
-export const numberSchemaOptional = z.union([nullSchema, numberSchema]);
+/**
+ * Сочетает {@link nullSchema} и {@link numberSchema}
+ */
+export const numberSchemaOptional = toNullable(numberSchema);
+/**
+ * Отличается типизацией от {@link numberSchema} тем, что якобы не принимает строки
+ *
+ * Замаскировано под эквивалент: `z.number().transform((v) => v)`
+ *
+ * @example
+ * ```typescript
+ * numberStrictSchema.parse(42);     // 42
+ * numberStrictSchema.parse("42");   // Ошибка типизации!
+ * ```
+ */
+export const numberStrictSchema = numberSchema;
+/**
+ * Сочетает {@link nullSchema} и {@link numberStrictSchema}
+ */
+export const numberStrictSchemaOptional = numberSchemaOptional;
 //...
+/**
+ * Схема для строковых значений через {@link caseString}
+ *
+ * Замаскировано под эквивалент: `z.union([z.number(), z.string()]).transform((v) => String(v))`
+ */
 export const stringSchema = z.unknown().transform((value, ctx) => caseString(value, (result) => {
     const trimmed = result === undefined ? "" : result.trim();
     return trimmed === ""
-        ? invalid(value, ctx, {
+        ? throwValueIssue({
+            ctx,
+            value,
             message: "It isn't a string or empty string",
             expected: "string (or number)",
         })
         : trimmed;
 }));
-export const stringSchemaOptional = z.union([nullSchema, stringSchema]);
+/**
+ * Сочетает {@link nullSchema} и {@link stringSchema}
+ */
+export const stringSchemaOptional = toNullable(stringSchema);
+/**
+ * Отличается типизацией от {@link stringSchema} тем, что якобы не принимает числа
+ *
+ * Замаскировано под эквивалент: `z.string().transform((v) => v)`
+ *
+ * @example
+ * ```typescript
+ * stringStrictSchema.parse("hello"); // "hello"
+ * stringStrictSchema.parse(42);      // Ошибка типизации!
+ * ```
+ */
+export const stringStrictSchema = stringSchema;
+/**
+ * Сочетает {@link nullSchema} и {@link stringStrictSchema}
+ */
+export const stringStrictSchemaOptional = stringSchemaOptional;
+//...
+/**
+ * Схема для {@link ZoneStamp}
+ */
+export const zoneStampSchema = z.object({
+    stamp: numberSchema,
+    zone: numberSchema,
+});
+/**
+ * Сочетает {@link nullSchema} и {@link zoneStampSchema}
+ */
+export const zoneStampSchemaOptional = toNullable(zoneStampSchema);
+/**
+ * Строгая версия {@link zoneStampSchema}, которая не якобы принимает строковые представления чисел
+ *
+ * @example
+ * ```typescript
+ * zoneStampStrictSchema.parse({ stamp: 1234567890, zone: 3 });     // { stamp: 1234567890, zone: 3 }
+ * zoneStampStrictSchema.parse({ stamp: 1234567890, zone: "3" }); // Ошибка типизации!
+ * ```
+ */
+export const zoneStampStrictSchema = zoneStampSchema;
+/**
+ * Сочетает {@link nullSchema} и {@link zoneStampStrictSchema}
+ */
+export const zoneStampStrictSchemaOptional = zoneStampSchemaOptional;
+//...
+/**
+ * Схема для {@link LWH}
+ */
+export const lwhSchema = z.object({
+    length: numberSchema,
+    width: numberSchema,
+    height: numberSchema,
+});
+/**
+ * Сочетает {@link nullSchema} и {@link lwhSchema}
+ */
+export const lwhSchemaOptional = toNullable(lwhSchema);
+/**
+ * Отличается типизацией от {@link lwhSchema} тем, что якобы не принимает строковые представления чисел
+ *
+ * @example
+ * ```typescript
+ * lwhStrictSchema.parse({ length: 10, width: 20, height: 30 });        // { length: 10, width: 20, height: 30 }
+ * lwhStrictSchema.parse({ length: "10", width: "20", height: "30" });  // Ошибка типизации!
+ * ```
+ */
+export const lwhStrictSchema = lwhSchema;
+/**
+ * Сочетает {@link nullSchema} и {@link lwhStrictSchema}
+ */
+export const lwhStrictSchemaOptional = lwhSchemaOptional;
 //...
-export default {
-    invalid,
+/**
+ * Коллекция расширенных {@link https://zod.dev Zod}-схем со встроенными преобразованиями типов
+ *
+ * @example
+ * ```typescript
+ * import { xod } from "./xod.js"; // or import xod from "./xod.js";
+ *
+ * const userSchema = z.object({
+ *   name: xod.string,           // Принимает string и number
+ *   age: xod.number,            // Принимает number и string
+ *   isActive: xod.boolean,      // Принимает boolean, number, string
+ *   notes: xod.stringOptional,  // Принимает string, number, null, undefined
+ *   created: xod.zoneStamp,     // Принимает объект с временной меткой и зоной
+ * });
+ * ```
+ */
+export const xod = {
+    throwValueIssue,
+    toNullable,
     null: nullSchema,
     boolean: booleanSchema,
     booleanOptional: booleanSchemaOptional,
     number: numberSchema,
+    numberStrict: numberStrictSchema,
     numberOptional: numberSchemaOptional,
+    numberStrictOptional: numberStrictSchemaOptional,
     string: stringSchema,
+    stringStrict: stringStrictSchema,
     stringOptional: stringSchemaOptional,
+    stringStrictOptional: stringStrictSchemaOptional,
+    zoneStamp: zoneStampSchema,
+    zoneStampOptional: zoneStampSchemaOptional,
+    zoneStampStrict: zoneStampStrictSchema,
+    zoneStampStrictOptional: zoneStampStrictSchemaOptional,
+    lwh: lwhSchema,
+    lwhOptional: lwhSchemaOptional,
+    lwhStrict: lwhStrictSchema,
+    lwhStrictOptional: lwhStrictSchemaOptional,
 };
+export default xod;