@nemigo/helpers 0.13.2 → 1.5.0

package/dist/jiff/apply.d.ts

@@ -0,0 +1,93 @@
+import type { JiffPatch, Patch } from "./types.js";
+/**
+ * Кастомный патч или `never`. Вспомогательный тип для {@link jiffApply}
+ */
+export type NeverPatch = Patch<string> | never;
+/**
+ * Ошибка последовательности патчей из {@link jiffApply}
+ */
+export interface JIFF_PROPERTY_ERROR<CustomPatch extends NeverPatch = never> {
+    /**
+     * Нарушена последовательность, ключ не найден
+     */
+    type: "property";
+    /**
+     * Патч, который вызвал ошибку
+     */
+    patch: CustomPatch | JiffPatch;
+    /**
+     * Переданный в функцию объект
+     */
+    obj: object;
+    /**
+     * Объект, к которому применяется патч
+     */
+    cursor: object;
+    /**
+     * Ключ, который был не найден
+     */
+    property: string;
+}
+/**
+ * Ошибка патча из {@link jiffApply}
+ */
+export interface JIFF_PATCH_ERROR<CustomPatch extends NeverPatch = never> {
+    /**
+     * - "path" - невалидный путь в патче
+     * - "operation" - неизвестная операция в патче
+     */
+    type: "path" | "operation";
+    /**
+     * Патч, который вызвал ошибку
+     */
+    patch: CustomPatch | JiffPatch;
+    /**
+     * Переданный в функцию объект
+     */
+    obj: object;
+    /**
+     * Для совместимости с {@link JIFF_PROPERTY_ERROR}
+     */
+    cursor?: never;
+    /**
+     * Для совместимости с {@link JIFF_PROPERTY_ERROR}
+     */
+    property?: never;
+}
+/**
+ * Типы ошибок для {@link jiffApply}
+ */
+export type JIFF_ERROR<CustomPatch extends NeverPatch = never> = JIFF_PATCH_ERROR<CustomPatch> | JIFF_PROPERTY_ERROR<CustomPatch>;
+/**
+ * Дополнительные возможности {@link jiffApply}
+ */
+export interface JiffApplyProps<CustomPatch extends NeverPatch = never> {
+    /**
+     * Обработка ошибок
+     */
+    onerror?: (err: JIFF_ERROR<CustomPatch>) => void;
+    /**
+     * Обработка кастомных патчей
+     *
+     * @template CustomPatch
+     * @param patch - Патч
+     * @param cursor - Текущий объект-курсор
+     * @param target - Целевое свойство
+     * @returns `true` если патч успешно обработан, `false` в противном случае
+     */
+    custom?: (patch: CustomPatch, cursor: Record<string, unknown>, target: string) => boolean;
+}
+/**
+ * Применяет массив JSON-патчей к объекту
+ *
+ * Если патч неизвестен или нарушена последовательность модификации (`add "/foo/bar"` должен быть применён после `add "/foo"`) объекта,
+ * вызывает `props.onerror`, но объект будет изменён согласно патчам независимо от наличия ошибок
+ *
+ * @template CustomPatch - Типы пользовательских патчей (если используются), обработка через {@link JiffApplyProps.custom}
+ * @param obj - Объект, к которому применяется патч
+ * @param jiff - Массив патчей для применения
+ * @param [props] - Дополнительные возможности обработки патчей
+ *
+ * @see https://jsonpatch.com/ Документация стандарта
+ */
+export declare function jiffApply<CustomPatch extends NeverPatch = never>(obj: object, jiff: (CustomPatch | JiffPatch)[], props?: JiffApplyProps<CustomPatch>): void;

package/dist/jiff/apply.js

@@ -0,0 +1,64 @@
+/**
+ * Применяет массив JSON-патчей к объекту
+ *
+ * Если патч неизвестен или нарушена последовательность модификации (`add "/foo/bar"` должен быть применён после `add "/foo"`) объекта,
+ * вызывает `props.onerror`, но объект будет изменён согласно патчам независимо от наличия ошибок
+ *
+ * @template CustomPatch - Типы пользовательских патчей (если используются), обработка через {@link JiffApplyProps.custom}
+ * @param obj - Объект, к которому применяется патч
+ * @param jiff - Массив патчей для применения
+ * @param [props] - Дополнительные возможности обработки патчей
+ *
+ * @see https://jsonpatch.com/ Документация стандарта
+ */
+export function jiffApply(obj, jiff, props) {
+    for (const patch of jiff) {
+        // Разделение пути патча на массив сегментов ("/foo/bar" -> ["foo", "bar"])
+        const path = patch.path.split("/").slice(1);
+        // Извлекаем последний сегмент пути как целевой элемент ("bar")
+        const target = path.pop();
+        if (!target) {
+            // Если путь невалидный (например, пустой), вызываем onerror с ошибкой типа "path"
+            props?.onerror?.({ type: "path", obj, patch });
+            continue;
+        }
+        // Начинаем с основного объекта
+        let cursor = obj;
+        for (const property of path) {
+            if (!(property in cursor)) {
+                // Ожидаемый ключ не найден
+                cursor[property] = {};
+                props?.onerror?.({ type: "property", property, obj, cursor, patch });
+            }
+            // Вложенный объект
+            cursor = cursor[property];
+        }
+        // Для патчей "remove" и "replace" проверяем существование целевого элемента
+        if (patch.op === "remove" || patch.op === "replace") {
+            if (!(target in cursor)) {
+                // Ожидаемый ключ не найден
+                cursor[target] = {};
+                props?.onerror?.({ type: "property", property: target, obj, cursor, patch });
+            }
+        }
+        switch (patch.op) {
+            case "remove":
+                if (Array.isArray(cursor))
+                    cursor.splice(Number(target), 1);
+                else
+                    delete cursor[target];
+                break;
+            case "replace":
+            case "add":
+                // Для операций "replace" и "add" устанавливаем новое значение
+                cursor[target] = patch.value;
+                break;
+            default:
+                // Если патч неизвестный, пытаемся применить кастомный обработчик
+                if (props?.custom?.(patch, cursor, target))
+                    continue;
+                // В случае неизвестной операции вызываем onerror
+                props?.onerror?.({ type: "operation", obj, patch });
+        }
+    }
+}

package/dist/jiff/extract.d.ts

@@ -0,0 +1,7 @@
+import type { JiffPatch } from "./types.js";
+/**
+ * Генерирует список патчей для преобразования исходного объекта в целевой
+ *
+ * @see https://jsonpatch.com/ Документация стандарта
+ */
+export declare function jiffExtract(source: object, target: object): JiffPatch[];

package/dist/jiff/extract.js

@@ -0,0 +1,82 @@
+import { isObject, isSameType } from "../index.js";
+const handleArrayDifference = (sourceArr, targetArr, currentPath, diffs) => {
+    // Удаление лишних элементов
+    for (let i = sourceArr.length - 1; i >= targetArr.length; i--) {
+        diffs.remove.push({
+            op: "remove",
+            path: `/${[...currentPath, i].join("/")}`,
+        });
+    }
+    // Обработка существующих элементов
+    for (let i = 0; i < Math.max(sourceArr.length, targetArr.length); i++) {
+        const path = [...currentPath, i];
+        const sourceItem = sourceArr[i];
+        const targetItem = targetArr[i];
+        if (i >= targetArr.length) {
+            // Элементы за пределами targetArr уже обработаны в удалении
+            continue;
+        }
+        if (i >= sourceArr.length) {
+            // Добавление новых элементов обрабатываем здесь
+            diffs.add.push({
+                op: "add",
+                path: `/${path.join("/")}`,
+                value: targetItem,
+            });
+            continue;
+        }
+        compareValues(sourceItem, targetItem, path, diffs);
+    }
+};
+const handleObjectDifference = (sourceObj, targetObj, currentPath, diffs) => {
+    // Удаление отсутствующих свойств
+    Object.keys(sourceObj).forEach((key) => {
+        if (!(key in targetObj)) {
+            diffs.remove.push({
+                op: "remove",
+                path: `/${[...currentPath, key].join("/")}`,
+            });
+        }
+    });
+    // Обработка существующих и новых свойств
+    Object.entries(targetObj).forEach(([key, targetValue]) => {
+        const path = [...currentPath, key];
+        const sourceValue = sourceObj[key];
+        if (!(key in sourceObj)) {
+            diffs.add.push({ op: "add", path: `/${path.join("/")}`, value: targetValue });
+        }
+        else {
+            compareValues(sourceValue, targetValue, path, diffs);
+        }
+    });
+};
+const compareValues = (source, target, currentPath, diffs) => {
+    if (!isSameType(source, target)) {
+        diffs.replace.push({ op: "replace", path: `/${currentPath.join("/")}`, value: target });
+        return;
+    }
+    if (Array.isArray(target)) {
+        handleArrayDifference(source, target, currentPath, diffs);
+    }
+    else if (isObject(target)) {
+        handleObjectDifference(source, target, currentPath, diffs);
+    }
+    else if (source !== target) {
+        diffs.replace.push({ op: "replace", path: `/${currentPath.join("/")}`, value: target });
+    }
+};
+//...
+/**
+ * Генерирует список патчей для преобразования исходного объекта в целевой
+ *
+ * @see https://jsonpatch.com/ Документация стандарта
+ */
+export function jiffExtract(source, target) {
+    const diffs = {
+        remove: [],
+        replace: [],
+        add: [],
+    };
+    compareValues(source, target, [], diffs);
+    return [...diffs.remove.reverse(), ...diffs.replace, ...diffs.add];
+}

package/dist/jiff/types.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Интерфейс базового патча, который описывает операцию изменения объекта
+ *
+ * @see https://jsonpatch.com Документация стандарта
+ */
+export interface Patch<O extends string> {
+    /**
+     * Путь к изменяемому элементу в объекте
+     *
+     * @example "/foo/bar"
+     */
+    path: string;
+    /**
+     * Тип операции патча
+     *
+     * @example "add" | "remove" | "replace"
+     */
+    op: O;
+}
+/**
+ * Патч добавления значения ("add")
+ *
+ * @see https://jsonpatch.com Документация стандарта
+ */
+export interface JiffAddPatch<V = unknown> extends Patch<"add"> {
+    /**
+     * Значение, которое будет добавлено по указанному пути
+     */
+    value: V;
+}
+/**
+ * Патч удаления значения ("remove")
+ *
+ * Поле `value` типа `never`, так как для удаления значения оно не требуется
+ *
+ * @see https://jsonpatch.com Документация стандарта
+ */
+export interface JiffRemovePatch extends Patch<"remove"> {
+    value?: never;
+}
+/**
+ * Патч для замены значения ("replace")
+ *
+ * @see https://jsonpatch.com Документация стандарта
+ */
+export interface JiffReplacePatch<V = unknown> extends Patch<"replace"> {
+    /**
+     * Новое значение, которое заменит старое
+     */
+    value: V;
+}
+/**
+ * Поддерживаемые патчи: добавление, удаление и замена значений
+ *
+ * @see https://jsonpatch.com Документация стандарта
+ */
+export type JiffPatch<V = unknown> = JiffAddPatch<V> | JiffRemovePatch | JiffReplacePatch<V>;

package/dist/jiff/types.js

@@ -0,0 +1 @@
+export {};

package/dist/lens.d.ts

@@ -1,9 +1,13 @@
+import type { KEYS } from "./types.js";
 /**
- * Режим работы линзы:
+ * Режим работы линзы {@link Lens}:
  * - `"exclude"` (исключение)
  * - `"include"` (включение)
  */
 export type LensMode = "exclude" | "include";
+/**
+ * Схема для {@link Lens}, определяющая, какие ключи включить или исключить
+ */
 export type LensSchema<O> = {
     [K in keyof O]?: boolean;
 };
@@ -27,38 +31,23 @@ export interface LensConfig<O> {
 /**
  * Линза для фильтрации на основе схемы и режима
  *
- * @template O - Тип объект для схемы, с которой работает линза
+ * @template O - Тип-объект для схемы, с которой работает линза
+ *
+ * @example
+ * ```typescript
+ * // В режиме "exclude" с schema: { id: true }
+ * lens.check("id"); // false (исключен)
+ * lens.check("name"); // true (не исключен)
+ *
+ * // В режиме "include" с schema: { email: true }
+ * lens.check("email"); // true (включен)
+ * lens.check("phone"); // false (не включен)
+ * ```
  */
 export declare class Lens<O> {
-    /**
-     * Режим работы линзы {@link LensMode}
-     *
-     * @default "exclude"
-     */
-    _mode: LensMode;
-    /**
-     * Схема, определяющая, какие ключи включить или исключить
-     *
-     * @default {}
-     */
-    _schema: LensSchema<O>;
-    /**
-     * Создаёт экземпляр линзы
-     *
-     * @param config - Конфигурация линзы {@link LensConfig}
-     */
+    __mode: LensMode;
+    __schema: LensSchema<O>;
     constructor(config: LensConfig<O>);
-    /**
-     * Пересборка под другую конфигурацию
-     *
-     * @param config - Конфигурация линзы {@link LensConfig}
-     */
     reconstruct(config: LensConfig<O>): void;
-    /**
-     * Проверяет, должен ли ключ быть включён в результат
-     *
-     * @param key - Ключ для проверки
-     * @returns `true`, если ключ должен быть включён, иначе `false`
-     */
-    get(key: keyof O): boolean;
+    check(key: KEYS<O>): boolean;
 }

package/dist/lens.js

@@ -1,50 +1,35 @@
 /**
  * Линза для фильтрации на основе схемы и режима
  *
- * @template O - Тип объект для схемы, с которой работает линза
+ * @template O - Тип-объект для схемы, с которой работает линза
+ *
+ * @example
+ * ```typescript
+ * // В режиме "exclude" с schema: { id: true }
+ * lens.check("id"); // false (исключен)
+ * lens.check("name"); // true (не исключен)
+ *
+ * // В режиме "include" с schema: { email: true }
+ * lens.check("email"); // true (включен)
+ * lens.check("phone"); // false (не включен)
+ * ```
  */
 export class Lens {
-    /**
-     * Режим работы линзы {@link LensMode}
-     *
-     * @default "exclude"
-     */
-    _mode;
-    /**
-     * Схема, определяющая, какие ключи включить или исключить
-     *
-     * @default {}
-     */
-    _schema;
-    /**
-     * Создаёт экземпляр линзы
-     *
-     * @param config - Конфигурация линзы {@link LensConfig}
-     */
+    __mode;
+    __schema;
     constructor(config) {
         this.reconstruct(config);
     }
-    /**
-     * Пересборка под другую конфигурацию
-     *
-     * @param config - Конфигурация линзы {@link LensConfig}
-     */
     reconstruct(config) {
-        this._mode = config.mode ?? "exclude";
-        this._schema = config.schema ?? {};
+        this.__mode = config.mode ?? "exclude";
+        this.__schema = config.schema ?? {};
     }
-    /**
-     * Проверяет, должен ли ключ быть включён в результат
-     *
-     * @param key - Ключ для проверки
-     * @returns `true`, если ключ должен быть включён, иначе `false`
-     */
-    get(key) {
-        if (this._mode === "exclude") {
-            // Если в конфиге есть ключ в режиме исключения, то key false. Если нет — то true
-            return !this._schema[key];
+    check(key) {
+        if (this.__mode === "exclude") {
+            // Если в конфиге есть ключ в режиме исключения, то key false. Если нет - то true
+            return !this.__schema[key];
         }
-        // Если в конфиге есть ключ, то key true. Если нет — то false
-        return !!this._schema[key];
+        // Если в конфиге есть ключ, то key true. Если нет - то false
+        return !!this.__schema[key];
     }
 }

package/dist/msgpack.d.ts

@@ -1,42 +1,27 @@
 /**
- * Данные в формате MSGPACK
+ * Данные в формате {@link https://msgpack.org MSGPACK}
  *
- * @template Data - Исходный объект данных
+ * @template Data - Исходные данные
  * @template Pack - Флаг, определяющий, упакованы данные или нет
  *
  * @remarks Поля __meta с исходными данными **НЕ** существует. Только для типизации
- *
- * @see https://jsr.io/@std/msgpack Документация используемого пакета
- * @see https://msgpack.org/ Документация стандарта MSGPACK
  */
-export type MSGPACK<Data, Pack extends boolean = true> = (Pack extends true ? number[] : Data) & {
+export type MSGPACK<Data, Pack extends boolean = true> = (Pack extends true ? Uint8Array<ArrayBuffer> : Data) & {
     __meta: Data;
 };
 /**
- * Декодирует данные из формата MSGPACK в исходный объект
- *
- * Использует функцию {@link _decode} из пакета `@std/msgpack` для декодирования
- *
- * @template Data - Тип исходного объекта
- * @param {MSGPACK<Data>} data - Данные в формате MSGPACK для декодирования
- * @returns {Data} Декодированный объект
+ * Декодирует данные из формата {@link https://msgpack.org MSGPACK}
  *
- * @see https://jsr.io/@std/msgpack Документация используемого пакета
- * @see https://msgpack.org/ Документация стандарта MSGPACK
+ * Использует функцию {@link decode} из {@link https://jsr.io/@std/msgpack @std/msgpack}
  */
-export declare const decode: <Data>(data: MSGPACK<Data>) => Data;
+export declare const depack: <Data>(data: MSGPACK<Data>) => Data;
 /**
- * Кодирует исходный объект в формат MSGPACK.
- * Объект **НЕ** должен содержать методы, `null` и `undefined`
+ * Кодирует исходный объект в формат {@link https://msgpack.org MSGPACK}
  *
- * Использует функцию {@link _encode} из пакета `@std/msgpack` для кодирования
+ * @remarks Объект **НЕ** должен содержать методы, `null` и `undefined`
  *
- * @template Data - Тип исходного объекта
- * @param {Data} data - Объект для кодирования
- * @returns {MSGPACK<Data>} Объект, закодированный в формат MSGPACK
- * @throws {Error} Выбрасывает ошибку, если есть не поддерживаемые типы данных
+ * Использует функцию {@link encode} из {@link https://jsr.io/@std/msgpack @std/msgpack}
  *
- * @see https://jsr.io/@std/msgpack Документация используемого пакета
- * @see https://msgpack.org/ Документация стандарта MSGPACK
+ * @throws {Error} Выбрасывает ошибку, если есть не поддерживаемые типы данных
  */
-export declare const encode: <Data>(data: Data) => MSGPACK<Data>;
+export declare const enpack: <Data>(data: Data) => MSGPACK<Data>;

package/dist/msgpack.js

@@ -1,29 +1,17 @@
-import { decode as _decode, encode as _encode } from "@std/msgpack";
+import { decode, encode } from "@std/msgpack";
 /**
- * Декодирует данные из формата MSGPACK в исходный объект
+ * Декодирует данные из формата {@link https://msgpack.org MSGPACK}
  *
- * Использует функцию {@link _decode} из пакета `@std/msgpack` для декодирования
- *
- * @template Data - Тип исходного объекта
- * @param {MSGPACK<Data>} data - Данные в формате MSGPACK для декодирования
- * @returns {Data} Декодированный объект
- *
- * @see https://jsr.io/@std/msgpack Документация используемого пакета
- * @see https://msgpack.org/ Документация стандарта MSGPACK
+ * Использует функцию {@link decode} из {@link https://jsr.io/@std/msgpack @std/msgpack}
  */
-export const decode = (data) => _decode(new Uint8Array(data));
+export const depack = (data) => decode(new Uint8Array(data));
 /**
- * Кодирует исходный объект в формат MSGPACK.
- * Объект **НЕ** должен содержать методы, `null` и `undefined`
+ * Кодирует исходный объект в формат {@link https://msgpack.org MSGPACK}
  *
- * Использует функцию {@link _encode} из пакета `@std/msgpack` для кодирования
+ * @remarks Объект **НЕ** должен содержать методы, `null` и `undefined`
  *
- * @template Data - Тип исходного объекта
- * @param {Data} data - Объект для кодирования
- * @returns {MSGPACK<Data>} Объект, закодированный в формат MSGPACK
- * @throws {Error} Выбрасывает ошибку, если есть не поддерживаемые типы данных
+ * Использует функцию {@link encode} из {@link https://jsr.io/@std/msgpack @std/msgpack}
  *
- * @see https://jsr.io/@std/msgpack Документация используемого пакета
- * @see https://msgpack.org/ Документация стандарта MSGPACK
+ * @throws {Error} Выбрасывает ошибку, если есть не поддерживаемые типы данных
  */
-export const encode = (data) => Array.from(_encode(data));
+export const enpack = (data) => encode(data);

package/dist/mutate.d.ts

@@ -0,0 +1,70 @@
+import type { AnyFunc, Args, Return, ThisFuncCopy } from "./types.js";
+/**
+ * Рекурсивно модифицирует объект, приводя его структуру к виду целевого объекта.
+ * Использует внутри {@link deepMutateArray}
+ *
+ * Удаляет лишние свойства, обновляет существующие и добавляет новые.
+ * Работает **мутативно** — изменяет исходный объект напрямую
+ *
+ * @remarks **НЕ** предназначен для работы с декларативными методами (могут потерять `this`)
+ *
+ * @example
+ * ```typescript
+ * const source = { a: 1, b: 2, c: 3 };
+ * const target = { a: 10, d: 40 };
+ *
+ * deepMutateObject(source, target);
+ * // source теперь: { a: 10, d: 40 }
+ * // свойства b и c удалены, a обновлено, d добавлено
+ * ```
+ */
+export declare const deepMutateObject: (source: object, target: object) => void;
+/**
+ * Рекурсивно модифицирует массив, приводя его к виду целевого массива.
+ * Использует внутри {@link deepMutateObject}
+ *
+ * Обрезает лишние элементы, обновляет существующие и добавляет новые.
+ * Работает **мутативно** — изменяет исходный массив напрямую
+ *
+ * @example
+ * ```typescript
+ * const complexSource = [
+ *   { id: 1, name: "John" },
+ *   { id: 2, name: "Jane" }
+ * ];
+ * const complexTarget = [
+ *   { id: 1, name: "Johnny" },
+ *   { id: 3, name: "Bob" }
+ * ];
+ *
+ * deepMutateArray(complexSource, complexTarget);
+ *
+ * // complexSource теперь: [
+ * //   { id: 1, name: "Johnny" },
+ * //   { id: 3, name: "Bob" }
+ * // ]
+ * ```
+ */
+export declare const deepMutateArray: (source: unknown[], target: unknown[]) => void;
+/**
+ * Контекст для {@link inject}
+ */
+export interface injectContext<O extends Record<K, AnyFunc>, K extends keyof O> {
+    self: O;
+    method: ThisFuncCopy<O, O[K]>;
+    args: Args<O[K]>;
+}
+/**
+ * Заменяет метод объекта обёрткой, передающей управление указанной функции
+ *
+ * Обёртка предоставляет контекст с оригинальным объектом, прокси-методом через {@link Reflect.apply} для вызова
+ * исходной реализации и аргументами вызова
+ *
+ * @param self - Объект, метод которого будет заменён
+ * @param key - Ключ метода в объекте
+ * @param func - Функция-обработчик, получающая контекст вызова
+ * @param [dynamic=false] - Использовать связывание `this` при вызове, что позволяет переносить цепочки на другие объекты
+ *
+ * @throws {TypeError} Если `self[key]` не является функцией
+ */
+export declare const inject: <O extends Record<K, AnyFunc>, K extends keyof O>(self: O, key: K, func: (ctx: {}) => Return<O[K]>, dynamic?: boolean) => void;