@nemigo/helpers 0.3.3 → 0.4.1

package/dist/lru.d.ts

@@ -0,0 +1,77 @@
+import type { RID } from "./types.js";
+/**
+ * LRU (Least Recently Used) кэш с поддержкой TTL (time-to-live)
+ *
+ * Элементы кэша удаляются при превышении максимального размера либо по истечении заданного TTL.
+ * TTL для каждого элемента можно задать как глобально при создании кэша, так и индивидуально при установке
+ *
+ * @template V - Тип значения для кэша
+ * @template K - Тип ключа для кэша
+ *
+ * @example
+ * const lruCache = new LRU<string, number>(2, 5); // Глобальный TTL 5 минут
+ * lruCache.set('one', 1);
+ * lruCache.set('two', 2);
+ * lruCache.set('three', 3); // Если кэш переполнен, удалится наименее недавно использованный или устаревший элемент
+ * console.log(lruCache.get('one')); // undefined, если значение устарело или удалено
+ * console.log(lruCache.get('two')); // 2
+ */
+export declare class LRU<V = unknown, K extends RID = string> {
+    /**
+     * Максимальное количество элементов в кэше
+     */
+    private readonly max;
+    /**
+     * Глобальный TTL (time-to-live) для каждого элемента в {@link Timestamp}.
+     * Если не задан (`undefined`), элементы не устаревают глобально
+     */
+    private readonly ttl?;
+    /**
+     * Внутреннее хранилище кэша.
+     * Хранит значения вместе с информацией о времени истечения срока их действия
+     */
+    private readonly cache;
+    /**
+     * @param [max=200] - Максимальное количество элементов в кэше
+     * @param ttl - Глобальный TTL (time-to-live) для каждого элемента в **минутах**
+     * Если не задан, элементы не устаревают глобально
+     */
+    constructor(max?: number, ttl?: number);
+    /**
+     * Перевод минут в {@link Timestamp}
+     */
+    private toTimeStamp;
+    /**
+     * Проверяет, устарел ли элемент кэша
+     *
+     * @param entry - Элемент кэша для проверки
+     * @returns `true`, если элемент устарел, иначе `false`
+     */
+    private isExpired;
+    /**
+     * Получает значение из кэша по ключу
+     *
+     * - Если элемент найден и не устарел, он перемещается в конец кэша (обновляется порядок использования)
+     * - Если элемент устарел, он удаляется, и возвращается `undefined`
+     *
+     * @param key - Ключ для получения значения
+     * @returns Значение из кэша или `undefined`, если ключ отсутствует или значение устарело
+     */
+    get(key: K): V | undefined;
+    /**
+     * Устанавливает значение в кэш
+     *
+     * - Если ключ уже существует, его значение обновляется и перемещается в конец
+     * - Если размер кэша превышает максимальное значение, производится очистка устаревших элементов
+     * - Если после очистки кэш все еще переполнен, удаляется наименее недавно использованный элемент
+     *
+     * @param key - Ключ для установки значения
+     * @param value - Значение для установки в кэш
+     * @param ttl - Индивидуальный TTL для данного элемента в **минутах**. Если не задан, используется TTL экземпляра, если он установлен
+     */
+    set(key: K, value: V, ttl?: number): void;
+    /**
+     * Очищает кэш
+     */
+    clear(key?: K): void;
+}

package/dist/lru.js

@@ -0,0 +1,128 @@
+/**
+ * LRU (Least Recently Used) кэш с поддержкой TTL (time-to-live)
+ *
+ * Элементы кэша удаляются при превышении максимального размера либо по истечении заданного TTL.
+ * TTL для каждого элемента можно задать как глобально при создании кэша, так и индивидуально при установке
+ *
+ * @template V - Тип значения для кэша
+ * @template K - Тип ключа для кэша
+ *
+ * @example
+ * const lruCache = new LRU<string, number>(2, 5); // Глобальный TTL 5 минут
+ * lruCache.set('one', 1);
+ * lruCache.set('two', 2);
+ * lruCache.set('three', 3); // Если кэш переполнен, удалится наименее недавно использованный или устаревший элемент
+ * console.log(lruCache.get('one')); // undefined, если значение устарело или удалено
+ * console.log(lruCache.get('two')); // 2
+ */
+export class LRU {
+    /**
+     * Максимальное количество элементов в кэше
+     */
+    max;
+    /**
+     * Глобальный TTL (time-to-live) для каждого элемента в {@link Timestamp}.
+     * Если не задан (`undefined`), элементы не устаревают глобально
+     */
+    ttl;
+    /**
+     * Внутреннее хранилище кэша.
+     * Хранит значения вместе с информацией о времени истечения срока их действия
+     */
+    cache;
+    /**
+     * @param [max=200] - Максимальное количество элементов в кэше
+     * @param ttl - Глобальный TTL (time-to-live) для каждого элемента в **минутах**
+     * Если не задан, элементы не устаревают глобально
+     */
+    constructor(max = 200, ttl) {
+        this.max = max;
+        if (ttl)
+            this.ttl = this.toTimeStamp(ttl);
+        this.cache = new Map();
+    }
+    /**
+     * Перевод минут в {@link Timestamp}
+     */
+    toTimeStamp(min) {
+        return min * 60 * 1000;
+    }
+    /**
+     * Проверяет, устарел ли элемент кэша
+     *
+     * @param entry - Элемент кэша для проверки
+     * @returns `true`, если элемент устарел, иначе `false`
+     */
+    isExpired(entry) {
+        return Boolean(entry.expired && Date.now() > entry.expired);
+    }
+    /**
+     * Получает значение из кэша по ключу
+     *
+     * - Если элемент найден и не устарел, он перемещается в конец кэша (обновляется порядок использования)
+     * - Если элемент устарел, он удаляется, и возвращается `undefined`
+     *
+     * @param key - Ключ для получения значения
+     * @returns Значение из кэша или `undefined`, если ключ отсутствует или значение устарело
+     */
+    get(key) {
+        const entry = this.cache.get(key);
+        if (!entry)
+            return undefined;
+        // Если элемент устарел, удаляем его и возвращаем undefined
+        if (this.isExpired(entry)) {
+            this.cache.delete(key);
+            return undefined;
+        }
+        // Обновляем порядок использования: удаляем и добавляем элемент в конец
+        this.cache.delete(key);
+        this.cache.set(key, entry);
+        return entry.value;
+    }
+    /**
+     * Устанавливает значение в кэш
+     *
+     * - Если ключ уже существует, его значение обновляется и перемещается в конец
+     * - Если размер кэша превышает максимальное значение, производится очистка устаревших элементов
+     * - Если после очистки кэш все еще переполнен, удаляется наименее недавно использованный элемент
+     *
+     * @param key - Ключ для установки значения
+     * @param value - Значение для установки в кэш
+     * @param ttl - Индивидуальный TTL для данного элемента в **минутах**. Если не задан, используется TTL экземпляра, если он установлен
+     */
+    set(key, value, ttl) {
+        // Если ключ уже существует, удаляем его для обновления порядка использования
+        if (this.cache.has(key))
+            this.cache.delete(key);
+        else {
+            if (this.cache.size >= this.max) {
+                // Если кэш достиг максимального размера, пробегаем по ключам и удаляем устаревшие элементы
+                for (const key of this.cache.keys()) {
+                    const entry = this.cache.get(key);
+                    if (!entry || this.isExpired(entry)) {
+                        this.cache.delete(key);
+                    }
+                }
+                // Если после очистки устаревших значений кэш все еще переполнен, удаляем первый (наименее недавно использованный) элемент
+                if (this.cache.size >= this.max) {
+                    const first = this.cache.keys().next().value;
+                    if (first !== undefined)
+                        this.cache.delete(first);
+                }
+            }
+        }
+        // Вычисляем время истечения для данного элемента
+        // prettier-ignore
+        const expired = ttl ? (Date.now() + this.toTimeStamp(ttl)) : (this.ttl ? (Date.now() + this.ttl) : undefined);
+        this.cache.set(key, { value, expired });
+    }
+    /**
+     * Очищает кэш
+     */
+    clear(key) {
+        if (key)
+            this.cache.delete(key);
+        else
+            this.cache.clear();
+    }
+}

package/dist/omitter.d.ts

@@ -0,0 +1,86 @@
+import type { DeepPartial, KEYS } from "./types.js";
+import type { ZIP } from "./zipper.js";
+/**
+ * Исключает ключи из объекта `Source`, которые присутствуют в объекте `Target`.
+ * Если значение ключа в `Source` и `Target` является объектом, рекурсивно применяет `OmitKEYS` к этим объектам
+ *
+ * @template Source - Исходный объект, из которого нужно исключить ключи
+ * @template Target - Объект, ключи которого нужно исключить из `Source`
+ *
+ * @example
+ * type Source = { a: number; b: { c: string; d: boolean }; e: string };
+ * type Target = { b: { c: string }; e: string };
+ * type Result = ExtractOmitSchema<Source, Target>; // { a: number; b: { d: boolean } }
+ */
+export type ExtractOmitSchema<Source, Target extends DeepPartial<Source>> = {
+    [K in keyof Source as K extends keyof Target ? Source[K] extends Record<string, unknown> ? Target[K] extends Record<string, unknown> ? K : never : never : K]: K extends keyof Target ? Source[K] extends Record<string, unknown> ? Target[K] extends Record<string, unknown> & DeepPartial<Source[K]> ? ExtractOmitSchema<Source[K], Target[K]> : never : never : null;
+};
+/**
+ * Вычисляет тип Target на основе исходного типа Source и схемы удаления OmitSchema.
+ * Удаляет ключи, помеченные в схеме как null, и рекурсивно обрабатывает вложенные объекты
+ *
+ * @example
+ * type Source = { a: number; b: { c: string; d: boolean }; e: string };
+ * type OmitSchema = { a: null; b: { c: null } };
+ * type Result = ExtractOmitTarget<Source, OmitSchema>; // { b: { d: boolean }; e: string }
+ */
+export type ExtractOmitTarget<Source, OmitSchema> = {
+    [K in keyof Source as K extends keyof OmitSchema ? (OmitSchema[K] extends Record<string, unknown> ? K : never) : K]: K extends keyof OmitSchema ? OmitSchema[K] extends Record<string, unknown> ? ExtractOmitTarget<Source[K], OmitSchema[K]> : never : Source[K];
+};
+/**
+ * Рекурсивно объединяет две схемы удаления ключей.
+ * Если ключ присутствует в обеих схемах:
+ * - Если оба значения являются объектами — объединяет вложенные схемы
+ * - Если хотя бы одно значение null — результат null (приоритет удаления)
+ *
+ * @example
+ *
+ * type SchemaA = { a: null; b: { c: null } };
+ * type SchemaB = { b: { d: null }; e: null };
+ *
+ * type MergedSchema = MergeOmitSchemas<SchemaA, SchemaB>;
+ * // Результат: { a: null; b: { c: null; d: null }; e: null }
+ *
+ * type ConflictSchema = MergeOmitSchemas<
+ *   { user: { name: null } },
+ *   { user: null }
+ * >;
+ * // Результат: { user: null } (приоритет удаления)
+ */
+export type MergeOmitSchemas<S1, S2> = {
+    [K in keyof (S1 & S2)]: K extends keyof S1 ? K extends keyof S2 ? S1[K] extends Record<string, unknown> ? S2[K] extends Record<string, unknown> ? MergeOmitSchemas<S1[K], S2[K]> : null : null : S1[K] : K extends keyof S2 ? S2[K] : never;
+};
+/**
+ * Класс для удаления указанных ключей из объекта на основе схемы
+ *
+ * @template Source - Исходный объект, из которого нужно удалить ключи
+ * @template OmitSchema - Схема удаления
+ *
+ * @example
+ * const source = { a: 1, b: { c: 2, d: 3 }, e: 4 };
+ * const schema = { b: { c: null } };
+ * const omitter = new Omitter(schema);
+ * const result = omitter.run(source); // { a: 1, b: { d: 3 }, e: 4 }
+ */
+export declare class Omitter<Source, OmitSchema> {
+    #private;
+    private readonly structure;
+    readonly schema: OmitSchema;
+    readonly zip: ZIP;
+    constructor(schema: OmitSchema);
+    /**
+     * Получение хэша вложенного эмиттера
+     */
+    into(key: KEYS<Source>): ZIP | undefined;
+    /**
+     * Проверяет, останется ли ключ в итоговом объекте
+     */
+    left(key: KEYS<Source>): boolean;
+    /**
+     * Удаление ключей из объекта
+     *
+     * @param source - Исходный объект
+     * @returns Объект с удалёнными ключами
+     */
+    run(source: Source): ExtractOmitTarget<Source, OmitSchema>;
+}

package/dist/omitter.js

@@ -0,0 +1,92 @@
+import { zipper } from "./zipper.js";
+/**
+ * Класс для удаления указанных ключей из объекта на основе схемы
+ *
+ * @template Source - Исходный объект, из которого нужно удалить ключи
+ * @template OmitSchema - Схема удаления
+ *
+ * @example
+ * const source = { a: 1, b: { c: 2, d: 3 }, e: 4 };
+ * const schema = { b: { c: null } };
+ * const omitter = new Omitter(schema);
+ * const result = omitter.run(source); // { a: 1, b: { d: 3 }, e: 4 }
+ */
+export class Omitter {
+    structure;
+    schema;
+    zip;
+    constructor(schema) {
+        this.zip = zipper(schema);
+        this.schema = schema;
+        const nested = new Map();
+        const keys = new Set(Object.keys(schema).filter((key) => {
+            const value = schema[key];
+            if (value && typeof value === "object") {
+                nested.set(key, new Omitter(value));
+                return false;
+            }
+            return true;
+        }));
+        this.structure = { keys, nested };
+    }
+    /**
+     * Получение хэша вложенного эмиттера
+     */
+    into(key) {
+        return this.structure.nested.get(key)?.zip;
+    }
+    /**
+     * Проверяет, останется ли ключ в итоговом объекте
+     */
+    left(key) {
+        return !this.structure.keys.has(key);
+    }
+    /**
+     * Рекурсивно удаляет ключи из объекта на основе структуры
+     *
+     * @param obj - Объект, из которого нужно удалить ключи
+     * @param structure - Структура, определяющая ключи для удаления
+     */
+    #process(obj, structure) {
+        const schema = structure.keys.size + structure.nested.size;
+        const keys = Object.keys(obj);
+        if (schema < keys.length) {
+            // Стратегия по схеме: итерируемся по ключам схемы
+            structure.keys.forEach((key) => {
+                delete obj[key];
+            });
+            structure.nested.forEach((omitter, key) => {
+                const nested = obj[key];
+                if (nested && typeof nested === "object")
+                    omitter.#process(nested, omitter.structure);
+            });
+        }
+        else {
+            // Стратегия по объекту: итерируемся по ключам объекта
+            for (const key of keys) {
+                if (structure.keys.has(key)) {
+                    delete obj[key];
+                }
+                else {
+                    const omitter = structure.nested.get(key);
+                    if (omitter) {
+                        const nested = obj[key];
+                        if (nested && typeof nested === "object") {
+                            omitter.#process(nested, omitter.structure);
+                        }
+                    }
+                }
+            }
+        }
+    }
+    /**
+     * Удаление ключей из объекта
+     *
+     * @param source - Исходный объект
+     * @returns Объект с удалёнными ключами
+     */
+    run(source) {
+        this.#process(source, this.structure);
+        return source;
+    }
+}

package/dist/phymath.d.ts

@@ -43,3 +43,13 @@ export declare const mult: (...args: number[]) => number;
  * @returns {number} Значение, ограниченное диапазоном [min, max]
  */
 export declare const clamp: (v: number, min: number, max: number) => number;
+/**
+ * Линейная интерполяция между двумя числами
+ *
+ * @param {number} s - Начальное значение
+ * @param {number} e - Конечное значение
+ * @param {number} t - Весовой коэффициент, определяющий пропорцию между начальным и конечным значениями. Значение должно быть в диапазоне [0, 1]
+ *
+ * @returns {number} Результат линейной интерполяции между s и e при коэффициенте t
+ */
+export declare const lerp: (s: number, e: number, t: number) => number;

package/dist/phymath.js

@@ -48,3 +48,14 @@ export const mult = (...args) => toRound(args.reduce((acc, v) => acc * v, 1));
  * @returns {number} Значение, ограниченное диапазоном [min, max]
  */
 export const clamp = (v, min, max) => Math.max(Math.min(v, max), min);
+//...
+/**
+ * Линейная интерполяция между двумя числами
+ *
+ * @param {number} s - Начальное значение
+ * @param {number} e - Конечное значение
+ * @param {number} t - Весовой коэффициент, определяющий пропорцию между начальным и конечным значениями. Значение должно быть в диапазоне [0, 1]
+ *
+ * @returns {number} Результат линейной интерполяции между s и e при коэффициенте t
+ */
+export const lerp = (s, e, t) => s * (1 - t) + e * t;

package/dist/phymath.types.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Пространственные характеристики
+ */
+export interface LWH<T = number> {
+    /**
+     * Длина
+     */
+    length: T;
+    /**
+     * Ширина
+     */
+    width: T;
+    /**
+     * Высота
+     */
+    height: T;
+}
+/**
+ * Физические характеристики
+ */
+export interface MVD<T = number> {
+    /**
+     * Масса
+     */
+    mass: T;
+    /**
+     * Объём
+     */
+    volume: T;
+    /**
+     * Плотность
+     */
+    density: T;
+}

package/dist/phymath.types.js

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

package/dist/promoter.d.ts

@@ -0,0 +1,22 @@
+import type { RID } from "./types.js";
+/**
+ * Класс для создания простого механизма подписок
+ */
+export declare class Promoter<Data> {
+    private __subs;
+    /**
+     * Вызывает подписчиков
+     */
+    notify(data: Data): void;
+    /**
+     * Подписка на события
+     */
+    sub(call: (data: Data) => void, params?: {
+        key?: RID;
+        once?: boolean;
+    }): () => boolean;
+    /**
+     * Удаляет подписчика по ключу. Если не указан, очищаются все
+     */
+    unsub(key?: RID): boolean;
+}

package/dist/promoter.js

@@ -0,0 +1,33 @@
+/**
+ * Класс для создания простого механизма подписок
+ */
+export class Promoter {
+    __subs = new Map();
+    /**
+     * Вызывает подписчиков
+     */
+    notify(data) {
+        this.__subs.forEach(({ call, once }, key) => {
+            call(data);
+            if (once)
+                this.__subs.delete(key);
+        });
+    }
+    /**
+     * Подписка на события
+     */
+    sub(call, params = {}) {
+        const { key = Symbol(), once } = params;
+        this.__subs.set(key, { call, once });
+        return () => this.__subs.delete(key);
+    }
+    /**
+     * Удаляет подписчика по ключу. Если не указан, очищаются все
+     */
+    unsub(key) {
+        if (key)
+            return this.__subs.delete(key);
+        this.__subs.clear();
+        return true;
+    }
+}

package/dist/types.d.ts

@@ -1,3 +1,6 @@
+export type * from "./phymath.types.js";
+import type { ZIP } from "./zipper.js";
+export type { ZIP };
 /**
  * Дата и время в формате UNIX
  */

package/dist/zipper.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Уникальный хэш для данных
+ */
+export type ZIP = string;
+/**
+ * Полином для {@link zipper}
+ */
+export declare const polynomial: Uint32Array<ArrayBuffer>;
+/**
+ * Вдохновлено (а может и является) CRC32
+ */
+export declare function zipper(data?: unknown): ZIP;

package/dist/zipper.js

@@ -0,0 +1,19 @@
+/**
+ * Полином для {@link zipper}
+ */
+export const polynomial = Uint32Array.from({ length: 256 }, (_, i) => {
+    let crc = i;
+    for (let j = 8; j--;)
+        crc = (crc >>> 1) ^ (0xedb88320 & -(crc & 1));
+    return crc;
+});
+/**
+ * Вдохновлено (а может и является) CRC32
+ */
+export function zipper(data = "undefined") {
+    const str = JSON.stringify(data);
+    let crc = 0 ^ -1;
+    for (let i = str.length - 1; i >= 0; i--)
+        crc = (crc >>> 8) ^ polynomial[(crc ^ str.charCodeAt(i)) & 0xff];
+    return "zi" + ((crc ^ -1) >>> 0).toString(16);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@nemigo/helpers",
-	"version": "0.3.3",
+	"version": "0.4.1",
 	"private": false,
 	"author": {
 		"name": "Vlad Logvin",
@@ -31,10 +31,18 @@
 			"types": "./dist/clean.d.ts",
 			"default": "./dist/clean.js"
 		},
+		"./cookie": {
+			"types": "./dist/cookie.d.ts",
+			"default": "./dist/cookie.js"
+		},
 		"./datetime": {
 			"types": "./dist/datetime.d.ts",
 			"default": "./dist/datetime.js"
 		},
+		"./emitter": {
+			"types": "./dist/emitter.d.ts",
+			"default": "./dist/emitter.js"
+		},
 		"./explorer": {
 			"types": "./dist/explorer.d.ts",
 			"default": "./dist/explorer.js"
@@ -47,6 +55,10 @@
 			"types": "./dist/format.d.ts",
 			"default": "./dist/format.js"
 		},
+		"./future": {
+			"types": "./dist/future.d.ts",
+			"default": "./dist/future.js"
+		},
 		"./html": {
 			"types": "./dist/html.d.ts",
 			"default": "./dist/html.js"
@@ -59,14 +71,30 @@
 			"types": "./dist/lens.d.ts",
 			"default": "./dist/lens.js"
 		},
+		"./lru": {
+			"types": "./dist/lru.d.ts",
+			"default": "./dist/lru.js"
+		},
 		"./msgpack": {
 			"types": "./dist/msgpack.d.ts",
 			"default": "./dist/msgpack.js"
 		},
+		"./omitter": {
+			"types": "./dist/omitter.d.ts",
+			"default": "./dist/omitter.js"
+		},
 		"./phymath": {
 			"types": "./dist/phymath.d.ts",
 			"default": "./dist/phymath.js"
 		},
+		"./phymath/types": {
+			"types": "./dist/phymath.types.d.ts",
+			"default": "./dist/phymath.types.js"
+		},
+		"./promoter": {
+			"types": "./dist/promoter.d.ts",
+			"default": "./dist/promoter.js"
+		},
 		"./queue": {
 			"types": "./dist/queue.d.ts",
 			"default": "./dist/queue.js"
@@ -94,6 +122,10 @@
 		"./xod": {
 			"types": "./dist/xod.d.ts",
 			"default": "./dist/xod.js"
+		},
+		"./zipper": {
+			"types": "./dist/zipper.d.ts",
+			"default": "./dist/zipper.js"
 		}
 	},
 	"peerDependencies": {