senaev-utils 1.0.0

package/README.md

@@ -0,0 +1,11 @@
+# senaev-utils
+
+Personal library with utils for `@senaev`.
+
+Published as raw source files without a root entrypoint.
+
+Import utilities directly by path, for example:
+
+```ts
+import { deepEqual } from 'senaev-utils/src/utils/Object/deepEqual/deepEqual';
+```

package/package.json

@@ -0,0 +1,66 @@
+{
+  "name": "senaev-utils",
+  "version": "1.0.0",
+  "description": "Personal library with utils for @senaev",
+  "files": [
+    "src",
+    "README.md"
+  ],
+  "scripts": {
+    "lint": "eslint .",
+    "lint:fix": "npx eslint . --fix",
+    "test": "vitest",
+    "test:ci": "vitest --run",
+    "typecheck": "tsc --noEmit"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/senaev/senaev-utils.git"
+  },
+  "author": "Andrei Senaev <andrei.senaev@gmail.com>",
+  "license": "ISC",
+  "bugs": {
+    "url": "https://github.com/senaev/senaev-utils/issues"
+  },
+  "homepage": "https://github.com/senaev/senaev-utils#readme",
+  "engines": {
+    "node": ">=18"
+  },
+  "devDependencies": {
+    "@eslint/js": "9.17.0",
+    "@stylistic/eslint-plugin": "2.12.1",
+    "@testing-library/react": "^16.3.0",
+    "@types/async": "^3.2.24",
+    "@types/react": "^19.1.3",
+    "eslint": "9.17.0",
+    "eslint-config-prettier": "9.1.0",
+    "eslint-plugin-import-x": "^4.6.1",
+    "eslint-plugin-no-only-tests": "^3.3.0",
+    "eslint-plugin-prettier": "5.2.1",
+    "eslint-plugin-react": "7.37.3",
+    "jsdom": "^27.0.0",
+    "lefthook": "^1.10.10",
+    "react": "^19.1.1",
+    "react-router": "^7.9.1",
+    "typescript": "^5.8.3",
+    "typescript-eslint": "^8.32.0",
+    "vitest": "^3.1.3"
+  },
+  "dependencies": {
+    "@types/node": "^24.0.0",
+    "jose": "^6.0.11",
+    "rxjs": "^7.8.2"
+  },
+  "peerDependencies": {
+    "react": ">=18",
+    "react-router": ">=7"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    },
+    "react-router": {
+      "optional": true
+    }
+  }
+}

package/src/reactHooks/setDeepEqualState.ts

@@ -0,0 +1,19 @@
+import { useState } from 'react';
+
+import { deepEqual } from '../utils/Object/deepEqual/deepEqual';
+
+export function setDeepEqualState<T>(defaultValue: T): [T, (nextValue: T) => void] {
+    const [
+        value,
+        setValue,
+    ] = useState(defaultValue);
+
+    return [
+        value,
+        (nextValue) => {
+            if (!deepEqual(value, nextValue)) {
+                setValue(nextValue);
+            }
+        },
+    ];
+}

package/src/reactHooks/useLocationParameter.ts

@@ -0,0 +1,46 @@
+import { useEffect, useState } from 'react';
+import { useLocation, useNavigate } from 'react-router';
+
+export function useLocationParameter({
+    parameterName,
+    defaultValue,
+}: {
+    parameterName: string;
+    defaultValue: string;
+}): [value: string, setValue: (nextValue: string) => void] {
+    const location = useLocation();
+    const navigate = useNavigate();
+
+    // Extract the query parameter from the URL
+    const queryParams = new URLSearchParams(location.search);
+
+    const initialValue = queryParams.get(parameterName) || defaultValue;
+
+    // Set the query parameter as state
+    const [
+        stateValue,
+        setStateValue,
+    ] = useState(initialValue);
+
+    // Update the query parameter in the URL when the state changes
+    useEffect(() => {
+        const params = new URLSearchParams(location.search);
+
+        if (stateValue === defaultValue) {
+            params.delete(parameterName);
+        } else {
+            params.set(parameterName, String(stateValue));
+        }
+
+        navigate(`?${params.toString()}`, { replace: true });
+    }, [
+        stateValue,
+        location.search,
+        navigate,
+    ]);
+
+    return [
+        stateValue,
+        setStateValue,
+    ];
+}

package/src/reactHooks/useObjectDeepChangesCounter.ts

@@ -0,0 +1,22 @@
+import { useRef } from 'react';
+
+import { PositiveInteger } from '../types/Number/PositiveInteger';
+import { deepEqual } from '../utils/Object/deepEqual/deepEqual';
+
+import { useReload } from './useReload';
+
+export function useObjectDeepChangesCounter(object: unknown): PositiveInteger {
+    const [
+        reload,
+        reloadIndex,
+    ] = useReload();
+
+    const objectRef = useRef(object);
+
+    if (!deepEqual(object, objectRef.current)) {
+        objectRef.current = object;
+        reload();
+    }
+
+    return reloadIndex;
+}

package/src/reactHooks/useObservableMap/useObservableMap.ts

@@ -0,0 +1,21 @@
+import { useEffect, useRef } from 'react';
+
+import { UnsignedInteger } from '../../types/Number/UnsignedInteger';
+import { ObservableMap } from '../../utils/Map/ObservableMap/ObservableMap';
+import { useReload } from '../useReload';
+
+export function useObservableMap<K, V>(initialValue?: Iterable<readonly [K, V]> | null): [ObservableMap<K, V>, UnsignedInteger] {
+    const [
+        reload,
+        reloadIndex,
+    ] = useReload();
+
+    const mapRef = useRef<ObservableMap<K, V>>(new ObservableMap(initialValue));
+
+    useEffect(() => mapRef.current.subscribe(reload), []);
+
+    return [
+        mapRef.current,
+        reloadIndex,
+    ];
+}

package/src/reactHooks/useRecentChangeTimer.ts

@@ -0,0 +1,42 @@
+import {
+    useEffect,
+    useRef,
+    useState,
+} from 'react';
+
+import { Milliseconds } from '../types/Time/Milliseconds';
+import { AbortableProcess } from '../utils/AbortableProcess';
+import { promiseTimeout } from '../utils/timers/promiseTimeout/promiseTimeout';
+
+export function useRecentChangeTimer<T>(value: T, timeoutMs: Milliseconds): boolean {
+    const [
+        isRecentlyChanged,
+        setIsRecentlyChanged,
+    ] = useState(true);
+
+    const lastValueRef = useRef<T>(value);
+
+    useEffect(() => {
+        const abortable = new AbortableProcess('useRecentChangeTimer');
+
+        setIsRecentlyChanged(true);
+        promiseTimeout(timeoutMs, { abortable }).then(() => {
+            setIsRecentlyChanged(false);
+        });
+
+        return () => {
+            abortable.abort('useEffect aborted');
+        };
+    }, [
+        value,
+        timeoutMs,
+    ]);
+
+    const isValueChanged = lastValueRef.current !== value;
+
+    if (isValueChanged) {
+        lastValueRef.current = value;
+    }
+
+    return isRecentlyChanged || isValueChanged;
+}

package/src/reactHooks/useReload.ts

@@ -0,0 +1,17 @@
+import { useState } from 'react';
+
+import { UnsignedInteger } from '../types/Number/UnsignedInteger';
+
+export function useReload(): [VoidFunction, UnsignedInteger] {
+    const [
+        reloadIndex,
+        setReloadIndex,
+    ] = useState(0);
+
+    return [
+        () => {
+            setReloadIndex((prevIndex) => prevIndex + 1);
+        },
+        reloadIndex,
+    ];
+}

package/src/reactHooks/useVisualizedProcessesTree.ts

@@ -0,0 +1,202 @@
+import { useRef, useState } from 'react';
+
+import {
+    VisualizedProcessesTree,
+    VisualizedProcessesTreeChange,
+    VisualizedProcessesTreeChangeAdd, VisualizedProcessesTreeChangeDelete, VisualizedProcessesTreeChangeStatus,
+} from '../utils/AbortableProcess';
+import { prettyStringify } from '../utils/prettyStringify';
+
+type Node = {
+    parentId: VisualizedProcessesTree['id'] | null;
+    node: VisualizedProcessesTree;
+};
+
+type AllNodesMap = Map<
+    VisualizedProcessesTree['id'],
+    Node
+>;
+
+function reconstructAllNodesMap(allNodesMap: AllNodesMap, tree: VisualizedProcessesTree): void {
+    allNodesMap.clear();
+
+    const stack: {
+        node: VisualizedProcessesTree;
+        parent: VisualizedProcessesTree['id'] | null;
+    }[] = [
+        {
+            node: tree,
+            parent: null,
+        },
+    ];
+
+    while (stack.length) {
+        const { node, parent } = stack.shift()!;
+
+        allNodesMap.set(node.id, {
+            parentId: parent,
+            node,
+        });
+
+        for (let i = node.children.length - 1; i >= 0; i--) {
+            stack.push({
+                node: node.children[i],
+                parent: node.id,
+            });
+        }
+    }
+}
+
+function addNodeToAllNodesMap(allNodesMap: AllNodesMap, change: VisualizedProcessesTreeChangeAdd): void {
+    const {
+        id,
+        name,
+        parentId,
+        startTimestamp,
+    } = change;
+
+    const parentNode = allNodesMap.get(parentId);
+
+    if (!parentNode) {
+        throw new Error(`Parent node is not found in tree for change=[${prettyStringify(change)}]`);
+    }
+
+    const newNode = {
+        id,
+        name,
+        status: undefined,
+        startTimestamp,
+        children: [],
+    };
+
+    parentNode.node.children.push(newNode);
+
+    allNodesMap.set(id, {
+        parentId,
+        node: newNode,
+    });
+}
+
+function deleteNodeFromAllNodesMap(allNodesMap: AllNodesMap, change: VisualizedProcessesTreeChangeDelete): void {
+    const {
+        id,
+    } = change;
+
+    const node = allNodesMap.get(id);
+
+    if (!node) {
+        throw new Error(`Node is not found in tree for change=[${prettyStringify(change)}]`);
+    }
+
+    const { parentId } = node;
+
+    if (!parentId) {
+        throw new Error(`Cannot remove node without parent for change=[${prettyStringify(change)}]`);
+    }
+
+    const parentNode = allNodesMap.get(parentId);
+
+    if (!parentNode) {
+        throw new Error(`Parent node is not found in tree for change=[${prettyStringify(change)}]`);
+    }
+
+    const nodeIndex = parentNode.node.children.indexOf(node.node);
+
+    if (nodeIndex === -1) {
+        throw new Error(`Child node is not found the parent node "children" array for change=[${prettyStringify(change)}]`);
+    }
+
+    parentNode.node.children.splice(nodeIndex, 1);
+}
+
+function changeNodeStatusInAllNodesMap(allNodesMap: AllNodesMap, change: VisualizedProcessesTreeChangeStatus): void {
+    const {
+        id,
+        status,
+    } = change;
+
+    const node = allNodesMap.get(id);
+
+    if (!node) {
+        throw new Error(`Node is not found in tree for change=[${prettyStringify(change)}]`);
+    }
+
+    node.node.status = status;
+}
+
+function getTreeForParentNodeWithId(allNodesMap: AllNodesMap, parentId: VisualizedProcessesTree['id']): VisualizedProcessesTree {
+    const parentNode = allNodesMap.get(parentId);
+
+    if (!parentNode) {
+        throw new Error(`Parent node is not found in tree for parentId=[${parentId}]`);
+    }
+
+    return parentNode.node;
+}
+
+export function useVisualizedProcessesTree(): {
+    tree: VisualizedProcessesTree | null;
+    setTree: (tree: VisualizedProcessesTree) => void;
+    handleChanges: (changes: VisualizedProcessesTreeChange[]) => void;
+} {
+    const [
+        tree,
+        setTree,
+    ] = useState<VisualizedProcessesTree | null>(null);
+
+    const allNodesMapRef = useRef<AllNodesMap>(new Map());
+
+    return {
+        tree,
+        setTree: (nextTree: VisualizedProcessesTree) => {
+            const allNodesMap = allNodesMapRef.current;
+
+            reconstructAllNodesMap(allNodesMap, nextTree);
+
+            const parentId = nextTree.id;
+            const nextTreeToDraw = getTreeForParentNodeWithId(allNodesMap, parentId);
+
+            setTree(nextTreeToDraw);
+        },
+        handleChanges: (changes) => {
+            const allNodesMap = allNodesMapRef.current;
+
+            changes.forEach((change) => {
+                const { type } = change;
+
+                if (type === 'add') {
+                    addNodeToAllNodesMap(allNodesMap, change);
+
+                    return;
+                }
+
+                if (type === 'delete') {
+                    deleteNodeFromAllNodesMap(allNodesMap, change);
+
+                    return;
+                }
+
+                if (type === 'status') {
+                    changeNodeStatusInAllNodesMap(allNodesMap, change);
+
+                    return;
+                }
+
+                throw new Error(`Unknown event type=[${type}] for change=[${prettyStringify(change)}]`);
+            });
+
+            setTree((previousTree) => {
+                if (!previousTree) {
+                    throw new Error('Initial tree has NOT been set');
+                }
+
+                const parentId = previousTree.id;
+                const nextTreeToDraw = getTreeForParentNodeWithId(allNodesMap, parentId);
+
+                return {
+                    ...nextTreeToDraw,
+                };
+            });
+        },
+    };
+}

package/src/types/Boolean.ts

@@ -0,0 +1,9 @@
+export function isBoolean(value: unknown): value is boolean {
+    return typeof value === 'boolean';
+}
+
+export function assertBoolean(value: unknown, errorMessage?: string): asserts value is boolean {
+    if (!isBoolean(value)) {
+        throw new Error(`assert boolean error${errorMessage ? ` errorMessage=[${errorMessage}]` : ''}`);
+    }
+}

package/src/types/DeepPartial.ts

@@ -0,0 +1 @@
+export type DeepPartial<T> = T extends string ? T : { [key in keyof T]?: DeepPartial<T[key]> };

package/src/types/GlobalContext.ts

@@ -0,0 +1,8 @@
+/**
+ * Глобальный объект.
+ * Соответствует `Window & typeof globalThis` начиная с ts3.6,
+ * и `Window` в более ранних версия ts
+ * @see https://github.com/microsoft/TypeScript/wiki/Breaking-Changes#dom-updates
+ */
+
+export type GlobalContext = typeof window;

package/src/types/HexColorString.ts

@@ -0,0 +1,9 @@
+/**
+ * string like:
+ * `#AABBCC`
+ * `#9900aa`
+ * `#123456`
+ *
+ * (6 hexadecimal symbols)
+ */
+export type HexColorString = `#${string}`;

package/src/types/ISOLang.ts

@@ -0,0 +1,5 @@
+/**
+ * Язык формате ISO 639-1
+ * Строка вида `"ru"` или `"en"`
+ */
+export type ISOLang = string;

package/src/types/IsEqualUnion.ts

@@ -0,0 +1 @@
+export type IsEqualUnion<T, U> = [T] extends [U] ? [U] extends [T] ? true : false : false;

package/src/types/IterableWithIndexAccess.ts

@@ -0,0 +1,4 @@
+export type IterableWithIndexAccess<T> = Iterable<T> & {
+    length: number;
+    at(index: number): T | undefined;
+};

package/src/types/Kilobits.ts

@@ -0,0 +1,4 @@
+/**
+ * Объем информации в килобитах
+ */
+export type Kilobits = number;

package/src/types/Network/Bits.ts

@@ -0,0 +1,4 @@
+/**
+ * Объем информации в битах
+ */
+export type Bits = number;

package/src/types/Network/Bps.ts

@@ -0,0 +1,4 @@
+/**
+ * Скорость в битах в секунду
+ */
+export type Bps = number;

package/src/types/Network/Kbps.ts

@@ -0,0 +1,4 @@
+/**
+ * Скорость в килобитах в секунду
+ */
+export type Kbps = number;

package/src/types/Network/Mbps.ts

@@ -0,0 +1,4 @@
+/**
+ * Скорость в мегабитах в секунду
+ */
+export type Mbps = number;

package/src/types/Number/AngleInDegrees.ts

@@ -0,0 +1,3 @@
+import { Integer } from './Integer';
+
+export type AngleInDegrees = Integer;

package/src/types/Number/FiniteNumber.ts

@@ -0,0 +1,11 @@
+export type FiniteNumber = number;
+
+export function isFiniteNumber(val: unknown): val is FiniteNumber {
+    return Number.isFinite(val);
+}
+
+export function assertFiniteNumber(val: unknown, message?: string): asserts val is FiniteNumber {
+    if (!isFiniteNumber(val)) {
+        throw new Error(`assertFiniteNumber error${message ? ` message=[${message}]` : ''}`);
+    }
+}

package/src/types/Number/Integer.ts

@@ -0,0 +1,14 @@
+/**
+ * Целое число
+ */
+export type Integer = number;
+
+export function isInteger(value: unknown): value is Integer {
+    return Number.isInteger(value);
+}
+
+export function assertInteger(value: unknown): asserts value is Integer {
+    if (!isInteger(value)) {
+        throw new Error(`value=[${value}] is not an integer`);
+    }
+}

package/src/types/Number/IntegerInString.ts

@@ -0,0 +1,13 @@
+import { isString } from '../../utils/String/isString';
+
+/**
+ * Целое цисло (положительное или отрицательное), представленное строкой
+ * 💁‍♂️ '0'
+ * 💁‍♂️ '-100500'
+ * 💁‍♂️ '3456'
+ */
+export type IntegerInString = string;
+
+export function isIntegerInString(str: unknown): boolean {
+    return isString(str) && str === parseInt(str, 10).toString(10);
+}

package/src/types/Number/Number.ts

@@ -0,0 +1,15 @@
+export function isNumber(value: unknown): value is number {
+    return typeof value === 'number';
+}
+
+export function assertNumber(value: unknown, message?: string): asserts value is number {
+    if (!isNumber(value)) {
+        let errorMessage = `value=[${value}] is not a number`;
+
+        if (message !== undefined) {
+            errorMessage += ` message=[${message}]`;
+        }
+
+        throw new Error(errorMessage);
+    }
+}

package/src/types/Number/Portion.ts

@@ -0,0 +1,4 @@
+/**
+ * Доля от 0 до 1
+ */
+export type Portion = number;

package/src/types/Number/PositiveInteger.ts

@@ -0,0 +1,30 @@
+import { PositiveNumber } from '../../types/Number/PositiveNumber';
+
+import { Integer } from './Integer';
+
+/**
+ * Целое положительное число
+ */
+export type PositiveInteger = PositiveNumber & Integer;
+
+export function isPositiveInteger(value: unknown): value is PositiveInteger {
+    if (!Number.isInteger(value)) {
+        return false;
+    }
+
+    return (value as Integer) > 0;
+}
+
+export function assertPositiveInteger(value: unknown, errorMessage?: string): asserts value is PositiveInteger {
+    if (!isPositiveInteger(value)) {
+        throw new Error(`value=[${value}] is not a positive integer${errorMessage ? ` errorMessage=[${errorMessage}]` : ''}`);
+    }
+}
+
+export function convertAndAssertPositiveInteger(value: unknown): PositiveInteger {
+    const result = Number(value);
+
+    assertPositiveInteger(result);
+
+    return result;
+}

package/src/types/Number/PositiveNumber.ts

@@ -0,0 +1,4 @@
+/**
+ * Положительное число
+ */
+export type PositiveNumber = number;

package/src/types/Number/StringUnsignedInteger.ts

@@ -0,0 +1,4 @@
+/**
+ * Unsigned int in string
+ */
+export type StringUnsignedInteger = string;

package/src/types/Number/UnsignedFiniteNumber.ts

@@ -0,0 +1,13 @@
+import { FiniteNumber, isFiniteNumber } from './FiniteNumber';
+
+export type UnsignedFiniteNumber = FiniteNumber;
+
+export function isUnsignedFiniteNumber(val: unknown): val is UnsignedFiniteNumber {
+    return isFiniteNumber(val) && val >= 0;
+}
+
+export function assertUnsignedFiniteNumber(val: unknown, message?: string): asserts val is UnsignedFiniteNumber {
+    if (!isUnsignedFiniteNumber(val)) {
+        throw new Error(`assertUnsignedFiniteNumber error${message ? ` message=[${message}]` : ''}`);
+    }
+}