@mirta/basics 0.3.5 → 0.4.0

package/dist/index.d.mts

@@ -0,0 +1,236 @@
+interface DebounceOptions {
+    leading?: boolean;
+    trailing?: boolean;
+    maxWait?: number;
+}
+interface DebouncedFunc<TArgs extends unknown[]> {
+    (...args: TArgs): void;
+    cancel(): void;
+    flush(): void;
+}
+interface ThrottleOptions {
+    leading?: boolean;
+    trailing?: boolean;
+}
+interface ThrottledFunc<TArgs extends unknown[]> {
+    (...args: TArgs): void;
+    cancel(): void;
+    flush(): void;
+}
+declare function debounce<TArgs extends unknown[]>(callback: (...args: TArgs) => void, wait: number, options?: DebounceOptions): DebouncedFunc<TArgs>;
+declare function throttle<TArgs extends unknown[]>(callback: (...args: TArgs) => void, wait: number, options?: ThrottleOptions): ThrottledFunc<TArgs>;
+
+/**
+ * Проверяет, является ли переданное значение строковым примитивом (`string`).
+ *
+ * @param value - Значение, которое необходимо проверить.
+ * @returns `true`, если значение является строкой (`string`), иначе `false`.
+ *
+ * @example
+ * ```ts
+ * isString('hello'); // true
+ * isString(123);     // false
+ * ```
+ * @since 0.0.2
+ *
+ **/
+declare const isString: (value: unknown) => value is string;
+/**
+ * Проверяет, является ли переданное значение числовым примитивом (`number`), не равным `NaN`.
+ *
+ * @param value - Значение, которое необходимо проверить.
+ * @returns `true`, если значение является числом (`number`) и не является `NaN`, иначе `false`.
+ *
+ * @example
+ * ```ts
+ * isNumber(42)   // true
+ * isNumber('42') // false
+ * isNumber(NaN)  // false
+ * ```
+ * @since 0.0.2
+ *
+ **/
+declare const isNumber: (value: unknown) => value is number;
+/**
+ * Проверяет, является ли переданное значение булевым примитивом (`boolean`).
+ *
+ * @param value - Значение, которое необходимо проверить.
+ * @returns `true`, если значение является булевым примитивом (`true` или `false`), иначе `false`.
+ *
+ * @remarks
+ * Не возвращает `true` для объектов `Boolean`, даже если они обёрнуты.
+ *
+ * @example
+ *
+ * ```ts
+ * isBoolean(true)              // true
+ * isBoolean(false)             // true
+ * isBoolean(1)                 // false
+ * isBoolean('true')            // false
+ * isBoolean(new Boolean(true)) // false (это объект, не примитив)
+ * ```
+ * @since 0.0.2
+ *
+ **/
+declare function isBoolean(value: unknown): value is boolean;
+/**
+ * Проверяет, является ли переданное значение функцией.
+ *
+ * @param value - Значение, которое необходимо проверить.
+ * @returns `true`, если значение является функцией (включая стрелочные функции, функции-объявления, методы и т.д.), иначе `false`.
+ *
+ * @example
+ * ```ts
+ * isFunction(() => {});      // true
+ * isFunction(function() {}); // true
+ * isFunction(Math.max);      // true
+ * isFunction(class {});      // true (в JS классы — это функции)
+ * isFunction({});            // false
+ * isFunction('function');    // false
+ * ```
+ * @since 0.1.0
+ *
+ **/
+declare const isFunction: (value: unknown) => value is ((...args: unknown[]) => unknown);
+/**
+ * Проверяет, является ли значение объектом —
+ * имеет тип `object` и не равно `null`.
+ *
+ * @remarks
+ * Проходят массивы и все объектные типы, включая
+ * встроенные (`Date`, `Map`, `Set`, `RegExp` и прочие).
+ *
+ * @param value - Проверяемое значение.
+ * @returns `true`, если это объект.
+ *
+ * @example
+ * ```ts
+ * isObject({})       // true
+ * isObject([])       // true
+ *
+ * isObject(() => {}) // false
+ * isObject(null)     // false
+ * isObject('hello')  // false
+ * isObject(42)       // false
+ * ```
+ * @since 0.4.0
+ */
+declare const isObject: (value: unknown) => value is object;
+/**
+ * Проверяет, является ли значение "обычным объектом" —
+ * имеет прототип `Object.prototype` или `null`.
+ *
+ * @remarks
+ * Не проходят массивы и встроенные типы (`Date`, `Map`, `Set`, `RegExp` и прочие).
+ *
+ * Не пройдёт и `Object.create({})`, т.к. экземпляр _унаследован_ от обычного объекта `{}`.
+ *
+ * @param value - Проверяемое значение.
+ *
+ * @returns `true`, если это обычный объект.
+ *
+ * @example
+ * ```ts
+ * isPlainObject({})                  // true
+ * isPlainObject({ a: 1, b: 2 })      // true
+ * isPlainObject(Object.create(null)) // true
+ *
+ * isPlainObject(Object.create({}))   // false
+ * isPlainObject(new Date())          // false
+ * isPlainObject(() => {})            // false
+ * isPlainObject([])                  // false
+ * ```
+ * @since 0.4.0
+ *
+ **/
+declare const isPlainObject: (value: unknown) => value is Record<string, unknown>;
+
+declare const mqttToBoolean: (value: WbRules.MqttValue) => boolean;
+
+type EventHandler = (...args: unknown[]) => void;
+type OnEvent<THandler extends EventHandler> = (handler: THandler) => {
+    off: () => void;
+};
+type OnceEvent<THandler extends EventHandler> = (handler: THandler) => void;
+interface Event<THandler extends EventHandler> {
+    /**
+     * Подписывает на событие, есть возможность отписки.
+     * @example
+     * ```ts
+     * // Событие изменения состояния.
+     * const stateChanged = useEvent()
+     * // Подписка на прослушивание события.
+     * const subscription = stateChanged.on(() => { ... })
+     * // Отписка от прослушивания события.
+     * subscription.off()
+     * ```
+     **/
+    on: OnEvent<THandler>;
+    /**
+     * Подписывает на событие, однократное выполнение.
+     * @example
+     * ```ts
+     * // Событие изменения состояния.
+     * const stateChanged = useEvent()
+     * // Подписка на однократное прослушивание события.
+     * stateChanged.once(() => { ... })
+     * ```
+     **/
+    once: OnceEvent<THandler>;
+    /**
+     * Отписывает указанный обработчик от прослушивания события.
+     * @example
+     * ```ts
+     * // Событие изменения состояния.
+     * const stateChanged = useEvent()
+     * // Обработчик события.
+     * function handler() { ... }
+     * // Регистрация обработчика.
+     * stateChanged.on(handler)
+     * // Прекращение прослушивания.
+     * stateChanged.off(handler)
+     * ```
+     **/
+    off: (handler: THandler) => void;
+}
+interface EventRaiser<THandler extends EventHandler> extends Event<THandler> {
+    /**
+     * Объявляет всем подписчикам о наступлении события.
+     * @example
+     * ```ts
+     * // Событие изменения состояния.
+     * const stateChanged = useEvent()
+     * // Где-то в коде: объявление о наступлении события.
+     * stateChanged.raise()
+     * ```
+     **/
+    raise: (...args: Parameters<THandler>) => void;
+    withoutRaise: () => Event<THandler>;
+}
+/**
+ * Построитель экземпляра события.
+ * @example
+ * ```ts
+ * // Событие без передачи аргументов.
+ * const stateChanged = useEvent()
+ * // Регистрация обработчика события.
+ * stateChanged.on(() => { ... })
+ * // Генерация события.
+ * stateChanged.raise()
+ * ```
+ * @example
+ * ```ts
+ * // Тип обработчика события.
+ * type CountEventHandler = (value: number) => void
+ * // Событие с передачей типа обработчика.
+ * const countChanged = useEvent<CountEventHandler>()
+ * // Регистрация обработчика события.
+ * countChanged.on((value) => { ... })
+ * // Генерация события.
+ * countChanged.raise(100)
+ * ```
+ */
+declare function useEvent<THandler extends EventHandler>(): EventRaiser<THandler>;
+
+export { debounce, isBoolean, isFunction, isNumber, isObject, isPlainObject, isString, mqttToBoolean, throttle, useEvent };
+export type { Event, EventHandler, EventRaiser, OnEvent, OnceEvent };

package/dist/index.mjs

@@ -1,3 +1,6 @@
+import { i as isString, a as isNumber } from './guards.mjs';
+export { b as isBoolean, c as isFunction, d as isObject, e as isPlainObject } from './guards.mjs';
+
 const { now } = Date;
 const { min, max } = Math;
 function debounce(callback, wait, options = {}) {
@@ -91,14 +94,6 @@ function throttle(callback, wait, options = {}) {
     });
 }
 
-/** Сужает диапазон множества типов до string */
-const isString = (value) => typeof value === 'string';
-/** Сужает диапазон множества типов до number */
-const isNumber = (value) => typeof value === 'number';
-/** Сужает диапазон множества типов до boolean */
-const isBoolean = (value) => typeof value === 'boolean';
-const isFunction = (value) => typeof value === 'function';
-
 const mqttToBoolean = (value) => {
     if (isString(value))
         return !['', '0', 'off', 'false'].includes(value);
@@ -172,4 +167,4 @@ function useEvent() {
     };
 }
 
-export { debounce, isBoolean, isFunction, isNumber, isString, mqttToBoolean, throttle, useEvent };
+export { debounce, isNumber, isString, mqttToBoolean, throttle, useEvent };

package/dist/object/index.d.mts

@@ -0,0 +1,161 @@
+/**
+ * Результат рекурсивного объединения `TBase` и `TPatch`.
+ * Поля из `TPatch` переопределяют поля из `TBase`.
+ * Вложенные объекты объединяются, остальные значения — заменяются.
+ *
+ * @template TBase - Тип базового объекта.
+ * @template TPatch - Тип объекта с изменениями.
+ *
+ * @since 0.4.0
+ *
+ **/
+type DeepMerged<TBase, TPatch> = [TBase, TPatch] extends [object, object] ? {
+    [K in keyof TBase | keyof TPatch]: K extends keyof TPatch ? TPatch[K] extends object ? K extends keyof TBase ? TBase[K] extends object ? DeepMerged<TBase[K], TPatch[K]> : TPatch[K] : TPatch[K] : TPatch[K] : K extends keyof TBase ? TBase[K] : never;
+} : TBase;
+/**
+ * Рекурсивно объединяет базовый объект с патчем.
+ *
+ * - Вложенные объекты — объединяются,
+ * - Массивы, примитивы — заменяются целиком,
+ * - Не мутирует аргументы `base` и `patch`,
+ * - Если `patch` равен `null` или `undefined`, возвращает копию `base`.
+ *
+ * Для поверхностного объединения используйте {@link merge}.
+ *
+ * @param base - Объект, с которого начинается объединение.
+ * @param patch - Набор изменений (допускает `null` или `undefined`).
+ * @returns Новый объект — результат объединения.
+ *
+ * @throws {TypeError} Если `base` не является объектом.
+ *
+ * @example
+ * deepMerge({ a: { b: 1 } }, { a: { c: 2 } })
+ * // → { a: { b: 1, c: 2 } }
+ *
+ * @example
+ * deepMerge({ x: 1 }, null)
+ * // → { x: 1 }
+ *
+ * @since 0.4.0
+ *
+ **/
+declare function deepMerge<TBase extends object, TPatch extends object | null | undefined>(base: TBase, patch: TPatch): DeepMerged<TBase, TPatch>;
+
+/**
+ * Проверяет, является ли тип настоящим объектом (не `null`, не примитив).
+ * Фильтрует `null`, так как `null extends object` в TS.
+ *
+ * @template T - Входной тип.
+ *
+ * @since 0.4.0
+ *
+ **/
+type IsObject<TValue> = TValue extends object ? (TValue extends null ? never : TValue) : never;
+/**
+ * Заменяет свойства из `TBase` на свойства из `TPatch` по ключам.
+ * Оставляет несовпадающие свойства из `TBase`, добавляет новые из `TPatch`.
+ *
+ * Эквивалент `Omit<TBase, keyof TPatch> & TPatch`, но с `Expand`.
+ *
+ * @template TBase - Базовый тип.
+ * @template TPatch - Тип с переопределяющими полями.
+ *
+ * @since 0.4.0
+ *
+ **/
+type Overwrite<TBase, TPatch> = Expand<Omit<TBase, keyof TPatch> & TPatch>;
+/**
+ * Рекурсивно вычисляет тип результата слияния кортежа объектов слева направо.
+ * Игнорирует `null` и `undefined`, объединяя только объекты.
+ * Поля из правых объектов переопределяют поля из левых.
+ *
+ * @template TList - readonly кортеж из объектов, `null` или `undefined`.
+ *
+ * @since 0.4.0
+ *
+ **/
+type MergeList<TList> = TList extends readonly [infer Head, ...infer Tail] ? Head extends IsObject<Head> ? Expand<Overwrite<MergeList<Tail>, Head>> : MergeList<Tail> : {};
+/**
+ * Тип результата `merge`: объединение списка объектов с приоритетом правых полей.
+ * Поля из последующих объектов переопределяют уже существующие.
+ *
+ * @template TList - Кортеж аргументов типа `(object | null | undefined)[]`.
+ * @returns Итоговый тип после поверхностного слияния.
+ *
+ * @example
+ *
+ * ```ts
+ * type Result = Merged<[{ a: 1 }, { a: 2; b: 2 }]>
+ * // → { a: 2; b: 2 }
+ * ```
+ * @since 0.4.0
+ *
+ **/
+type Merged<TList> = Expand<MergeList<TList>>;
+/**
+ * Поверхностно копирует значения всех собственных перечисляемых свойств
+ * из одного и более исходных объектов в новый.
+ *
+ * Поля последующих объектов переопределяют предыдущие.
+ *
+ * Особенности:
+ * - Игнорирует `null` и `undefined` в списке аргументов,
+ * - Не мутирует исходные объекты.
+ *
+ * Для рекурсивного объединения вложенных свойств используйте {@link deepMerge}.
+ *
+ * @param objects - Список исходных объектов.
+ * @returns Новый объект — результат объединения.
+ *
+ * @example
+ *
+ * ```ts
+ * const a = { x: 1, y: 2 }
+ * const b = null
+ * const c = { y: 3, z: 4 }
+ *
+ * const result = merge(a, b, c)
+ * // → { x: 1, y: 3, z: 4 }
+ * ```
+ * @example
+ *
+ * ```ts
+ * merge({ a: 1 }, { a: 2 }, { a: undefined })
+ * // → { a: undefined }
+ * ```
+ * @example
+ *
+ * ```ts
+ * merge()
+ * // → {}
+ * ```
+ * @since 0.4.0
+ *
+ **/
+declare function merge<TList extends readonly (object | null | undefined)[]>(...objects: TList): Merged<TList>;
+
+/**
+ * Проверяет, содержит ли объект указанное собственное свойство.
+ *
+ * Метод обходит цепочку прототипов и возвращает `true` только в том случае,
+ * если свойство существует непосредственно в самом объекте, а не унаследовано.
+ *
+ * @param target - Объект, в котором выполняется проверка.
+ * @param key - Имя свойства, которое необходимо проверить.
+ * @returns `true`, если объект имеет указанное собственное свойство; иначе `false`.
+ *
+ * @example
+ *
+ * ```ts
+ * const obj = { key: 'value' };
+ * hasOwn(obj, 'key');      // true
+ * hasOwn(obj, 'toString'); // false (унаследованное свойство)
+ * ```
+ *
+ * @since 0.4.0
+ *
+ **/
+declare function hasOwn(target: object, key: PropertyKey): boolean;
+
+export { deepMerge, hasOwn, merge };
+export type { DeepMerged, Merged };

package/dist/object/index.mjs

@@ -0,0 +1,56 @@
+import { d as isObject, e as isPlainObject } from '../guards.mjs';
+
+/**
+ * Проверяет, содержит ли объект указанное собственное свойство.
+ *
+ * Метод обходит цепочку прототипов и возвращает `true` только в том случае,
+ * если свойство существует непосредственно в самом объекте, а не унаследовано.
+ *
+ * @param target - Объект, в котором выполняется проверка.
+ * @param key - Имя свойства, которое необходимо проверить.
+ * @returns `true`, если объект имеет указанное собственное свойство; иначе `false`.
+ *
+ * @example
+ *
+ * ```ts
+ * const obj = { key: 'value' };
+ * hasOwn(obj, 'key');      // true
+ * hasOwn(obj, 'toString'); // false (унаследованное свойство)
+ * ```
+ *
+ * @since 0.4.0
+ *
+ **/
+function hasOwn(target, key) {
+    return Object.prototype.hasOwnProperty
+        .call(target, key);
+}
+
+function deepMerge(base, patch) {
+    if (!isObject(base))
+        throw new TypeError('[deepMerge] first argument must be an object');
+    const output = { ...base };
+    if (patch == null || typeof patch !== 'object')
+        return output;
+    for (const key in patch) {
+        if (!hasOwn(patch, key))
+            continue;
+        const fromBase = output[key];
+        const fromPatch = patch[key];
+        if (isPlainObject(fromBase) && isPlainObject(fromPatch)) {
+            output[key] = deepMerge(fromBase, fromPatch);
+        }
+        else {
+            output[key] = fromPatch;
+        }
+    }
+    return output;
+}
+
+function merge(...objects) {
+    if (objects.length === 0)
+        return {};
+    return objects.reduce((base, patch) => (patch ? { ...base, ...patch } : base), {});
+}
+
+export { deepMerge, hasOwn, merge };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@mirta/basics",
-  "description": "Utility functions providing core functionality for the Mirta Framework.",
-  "version": "0.3.5",
+  "description": "Utility functions providing core functionality for the Mirta Framework",
+  "version": "0.4.0",
   "license": "Unlicense",
   "keywords": [
     "mirta",
@@ -13,14 +13,38 @@
     "LICENSE",
     "README.md"
   ],
+  "types": "./dist/index.d.mts",
   "exports": {
     ".": {
       "import": {
-        "types": "./dist/index.d.ts",
+        "types": "./dist/index.d.mts",
         "default": "./dist/index.mjs"
       }
+    },
+    "./fuzzy": {
+      "import": {
+        "types": "./dist/fuzzy/index.d.mts",
+        "default": "./dist/fuzzy/index.mjs"
+      }
+    },
+    "./array": {
+      "import": {
+        "types": "./dist/array/index.d.mts",
+        "default": "./dist/array/index.mjs"
+      }
+    },
+    "./object": {
+      "import": {
+        "types": "./dist/object/index.d.mts",
+        "default": "./dist/object/index.mjs"
+      }
     }
   },
+  "imports": {
+    "#src/*": "./src/*.js",
+    "#src/object/*": "./src/object/*.js",
+    "#array/*": "./src/array/*.js"
+  },
   "homepage": "https://github.com/wb-mirta/core/tree/latest/packages/mirta-basics#readme",
   "repository": {
     "type": "git",
@@ -31,7 +55,6 @@
     "url": "https://github.com/wb-mirta/core/issues"
   },
   "scripts": {
-    "clean": "rimraf dist",
-    "build:mono": "pnpm clean && rollup -c node:@mirta/rollup/config --config-package"
+    "build:mono": "rollup -c node:@mirta/rollup/config-package"
   }
 }

package/dist/index.d.ts

@@ -1,119 +0,0 @@
-interface DebounceOptions {
-    leading?: boolean;
-    trailing?: boolean;
-    maxWait?: number;
-}
-interface DebouncedFunc<TArgs extends unknown[]> {
-    (...args: TArgs): void;
-    cancel(): void;
-    flush(): void;
-}
-interface ThrottleOptions {
-    leading?: boolean;
-    trailing?: boolean;
-}
-interface ThrottledFunc<TArgs extends unknown[]> {
-    (...args: TArgs): void;
-    cancel(): void;
-    flush(): void;
-}
-declare function debounce<TArgs extends unknown[]>(callback: (...args: TArgs) => void, wait: number, options?: DebounceOptions): DebouncedFunc<TArgs>;
-declare function throttle<TArgs extends unknown[]>(callback: (...args: TArgs) => void, wait: number, options?: ThrottleOptions): ThrottledFunc<TArgs>;
-
-/** Сужает диапазон множества типов до string */
-declare const isString: (value: unknown) => value is string;
-/** Сужает диапазон множества типов до number */
-declare const isNumber: (value: unknown) => value is number;
-/** Сужает диапазон множества типов до boolean */
-declare const isBoolean: (value: unknown) => value is boolean;
-declare const isFunction: (value: unknown) => value is ((...args: unknown[]) => unknown);
-
-declare const mqttToBoolean: (value: WbRules.MqttValue) => boolean;
-
-type EventHandler = (...args: unknown[]) => void;
-type OnEvent<THandler extends EventHandler> = (handler: THandler) => {
-    off: () => void;
-};
-type OnceEvent<THandler extends EventHandler> = (handler: THandler) => void;
-interface Event<THandler extends EventHandler> {
-    /**
-     * Подписывает на событие, есть возможность отписки.
-     * @example
-     * ```ts
-     * // Событие изменения состояния.
-     * const stateChanged = useEvent()
-     * // Подписка на прослушивание события.
-     * const subscription = stateChanged.on(() => { ... })
-     * // Отписка от прослушивания события.
-     * subscription.off()
-     * ```
-     **/
-    on: OnEvent<THandler>;
-    /**
-     * Подписывает на событие, однократное выполнение.
-     * @example
-     * ```ts
-     * // Событие изменения состояния.
-     * const stateChanged = useEvent()
-     * // Подписка на однократное прослушивание события.
-     * stateChanged.once(() => { ... })
-     * ```
-     **/
-    once: OnceEvent<THandler>;
-    /**
-     * Отписывает указанный обработчик от прослушивания события.
-     * @example
-     * ```ts
-     * // Событие изменения состояния.
-     * const stateChanged = useEvent()
-     * // Обработчик события.
-     * function handler() { ... }
-     * // Регистрация обработчика.
-     * stateChanged.on(handler)
-     * // Прекращение прослушивания.
-     * stateChanged.off(handler)
-     * ```
-     **/
-    off: (handler: THandler) => void;
-}
-interface EventRaiser<THandler extends EventHandler> extends Event<THandler> {
-    /**
-     * Объявляет всем подписчикам о наступлении события.
-     * @example
-     * ```ts
-     * // Событие изменения состояния.
-     * const stateChanged = useEvent()
-     * // Где-то в коде: объявление о наступлении события.
-     * stateChanged.raise()
-     * ```
-     **/
-    raise: (...args: Parameters<THandler>) => void;
-    withoutRaise: () => Event<THandler>;
-}
-/**
- * Построитель экземпляра события.
- * @example
- * ```ts
- * // Событие без передачи аргументов.
- * const stateChanged = useEvent()
- * // Регистрация обработчика события.
- * stateChanged.on(() => { ... })
- * // Генерация события.
- * stateChanged.raise()
- * ```
- * @example
- * ```ts
- * // Тип обработчика события.
- * type CountEventHandler = (value: number) => void
- * // Событие с передачей типа обработчика.
- * const countChanged = useEvent<CountEventHandler>()
- * // Регистрация обработчика события.
- * countChanged.on((value) => { ... })
- * // Генерация события.
- * countChanged.raise(100)
- * ```
- */
-declare function useEvent<THandler extends EventHandler>(): EventRaiser<THandler>;
-
-export { debounce, isBoolean, isFunction, isNumber, isString, mqttToBoolean, throttle, useEvent };
-export type { Event, EventHandler, EventRaiser, OnEvent, OnceEvent };