senaev-utils 1.0.0

package/src/types/Number/UnsignedInteger.ts

@@ -0,0 +1,28 @@
+/**
+ * Целое неотрицательное число
+ */
+export type UnsignedInteger = number;
+
+export function isUnsignedInteger(value: unknown): value is UnsignedInteger {
+    if (!Number.isInteger(value)) {
+        return false;
+    }
+
+    return (value as UnsignedInteger) >= 0;
+}
+
+export function assertUnsignedInteger(number: unknown, errorMessage: string = ''): asserts number is UnsignedInteger {
+    if (!isUnsignedInteger(number)) {
+        throw new Error(`Expected unsigned integer (whole number >= 0), got ${number}${errorMessage ? ` errorMessage=[${errorMessage}]` : ''}`);
+    }
+}
+
+export function convertAndAssertUnsignedInteger(value: unknown): UnsignedInteger {
+    const result = Number(value);
+
+    if (isUnsignedInteger(result)) {
+        return result;
+    }
+
+    throw new Error(`value=[${value}] is not unsigned integer`);
+}

package/src/types/Object/Object.ts

@@ -0,0 +1,20 @@
+export function isObject<T extends Record<string, unknown> = Record<string, unknown>>(value: unknown): value is T {
+    const type = typeof value;
+
+    return Boolean(value) && (type === 'object' || type === 'function');
+}
+
+export function assertObject<T extends Record<string, unknown> = Record<string, unknown>>(
+    value: unknown,
+    message?: string
+): asserts value is T {
+    if (!isObject(value)) {
+        let errorMessage = 'assertObject error';
+
+        if (message !== undefined) {
+            errorMessage += ` message=[${message}]`;
+        }
+
+        throw new Error(errorMessage);
+    }
+}

package/src/types/Percent.ts

@@ -0,0 +1,4 @@
+/**
+ * Доля в процентах от 0 до 100
+ */
+export type Percent = number;

package/src/types/PixelPosition.ts

@@ -0,0 +1,9 @@
+import { Pixels } from './Pixels';
+
+/**
+ * Позиция чего-либо в пикселях
+ */
+export type PixelPosition = {
+    x: Pixels;
+    y: Pixels;
+};

package/src/types/PixelSize.ts

@@ -0,0 +1,9 @@
+import { Pixels } from './Pixels';
+
+/**
+ * Размеры чего-либо в пикселях
+ */
+export type PixelSize = {
+    width: Pixels;
+    height: Pixels;
+};

package/src/types/Pixels.ts

@@ -0,0 +1,4 @@
+/**
+ * Размер в пикселях
+ */
+export type Pixels = number;

package/src/types/RangeTuple.ts

@@ -0,0 +1 @@
+export type RangeTuple<T> = [from: T, to: T];

package/src/types/Size.ts

@@ -0,0 +1,8 @@
+/**
+ * @deprecated
+ * use PixelSize or another strict type
+ */
+export type Size = {
+    width: number;
+    height: number;
+};

package/src/types/Time/DaysCount.ts

@@ -0,0 +1,6 @@
+import { Integer } from '../Number/Integer';
+
+/**
+ * Количество дней
+ */
+export type DaysCount = Integer;

package/src/types/Time/Hours.ts

@@ -0,0 +1,4 @@
+/**
+ * Время в часах
+ */
+export type Hours = number;

package/src/types/Time/ISODateString/ISODateString.ts

@@ -0,0 +1,16 @@
+// use date.toISOString() method to convert date to this type
+
+// 💁‍♂️ 2025-01-01T07:29:12.263Z
+export type ISODateString = ReturnType<Date['toISOString']>;
+
+export function isISODateString(date: string): boolean {
+    const parsedDate = new Date(date);
+
+    return !isNaN(parsedDate.getTime()) && date === parsedDate.toISOString();
+}
+
+export function assertISODateString(date: string, errorMessage?: string): asserts date is ISODateString {
+    if (!isISODateString(date)) {
+        throw new Error(`date=[${date}] is not a valid ISO date string${errorMessage ? ` errorMessage=[${errorMessage}]` : ''}`);
+    }
+}

package/src/types/Time/Milliseconds.ts

@@ -0,0 +1,4 @@
+/**
+ * Время в миллисекундах
+ */
+export type Milliseconds = number;

package/src/types/Time/Minutes.ts

@@ -0,0 +1,4 @@
+/**
+ * Время в минутах
+ */
+export type Minutes = number;

package/src/types/Time/Seconds.ts

@@ -0,0 +1,5 @@
+/**
+ * Time in seconds
+ * Could be non integer
+ */
+export type Seconds = number;

package/src/types/Time/Time.ts

@@ -0,0 +1,13 @@
+import { Hours } from './Hours';
+import { Milliseconds } from './Milliseconds';
+import { Minutes } from './Minutes';
+import { Seconds } from './Seconds';
+
+export const MS_IN_SEC: Milliseconds = 1000;
+export const SEC_IN_MIN: Seconds = 60;
+export const MIN_IN_HOUR: Minutes = 60;
+export const HOUR_IN_DAY: Hours = 24;
+
+export const SEC_IN_HOUR: Seconds = MIN_IN_HOUR * SEC_IN_MIN;
+export const SEC_IN_DAY: Seconds = HOUR_IN_DAY * SEC_IN_HOUR;
+export const MS_IN_DAY: Milliseconds = SEC_IN_DAY * MS_IN_SEC;

package/src/types/Time/Timestamp.ts

@@ -0,0 +1,6 @@
+import { Milliseconds } from './Milliseconds';
+
+/**
+ * Тип для js-таймстампа в мс (с начала эпохи)
+ */
+export type Timestamp = Milliseconds;

package/src/types/Time/UnixTimeMs.ts

@@ -0,0 +1,6 @@
+import { Milliseconds } from './Milliseconds';
+
+/**
+ * Количество миллисекунд, прошедших с 00:00:00 Thursday, 1 January 1970 по UTC
+ */
+export type UnixTimeMs = Milliseconds;

package/src/types/Time/UnixTimeSec.ts

@@ -0,0 +1,11 @@
+import { Integer } from '../Number/Integer';
+
+import { Seconds } from './Seconds';
+
+/**
+ * https://en.wikipedia.org/wiki/Unix_time
+ *
+ * Number of seconds since 00:00:00 Thursday, 1 January 1970 UTC
+ * Always integer
+ */
+export type UnixTimeSec = Seconds & Integer;

package/src/types/Time/const.ts

@@ -0,0 +1,24 @@
+import { DaysCount } from './DaysCount';
+import { Hours } from './Hours';
+import { Milliseconds } from './Milliseconds';
+import { Minutes } from './Minutes';
+import { Seconds } from './Seconds';
+
+export const DAYS_IN_NOT_LEAP_YEAR: DaysCount = 365;
+export const DAYS_IN_WEEK: DaysCount = 7;
+export const DAYS_IN_AVERAGE_MONTH: DaysCount = 7;
+
+export const HOURS_IN_DAY: Hours = 24;
+
+export const MINUTES_IN_HOUR: Minutes = 60;
+export const MINUTES_IN_DAY: Minutes = MINUTES_IN_HOUR * HOURS_IN_DAY;
+export const MINUTES_IN_WEEK: Minutes = MINUTES_IN_DAY * DAYS_IN_WEEK;
+
+export const SECONDS_IN_MINUTE: Seconds = 60;
+export const SECONDS_IN_HOUR: Seconds = SECONDS_IN_MINUTE * MINUTES_IN_HOUR;
+export const SECONDS_IN_DAY: Seconds = SECONDS_IN_HOUR * HOURS_IN_DAY;
+export const SECONDS_IN_YEAR: Seconds = SECONDS_IN_DAY * DAYS_IN_NOT_LEAP_YEAR;
+
+export const MILLISECONDS_IN_SECOND: Milliseconds = 1000;
+export const MILLISECONDS_IN_MINUTE: Milliseconds = MILLISECONDS_IN_SECOND * SECONDS_IN_MINUTE;
+export const MILLISECONDS_IN_DAY: Milliseconds = HOURS_IN_DAY * MINUTES_IN_HOUR * SECONDS_IN_MINUTE * MILLISECONDS_IN_SECOND;

package/src/types/any/AnyAsyncFunction.ts

@@ -0,0 +1,2 @@
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export type AnyAsyncFunction = (...args: any[]) => Promise<any>;

package/src/types/any/AnyFunction.ts

@@ -0,0 +1,2 @@
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export type AnyFunction = (...args: any[]) => any;

package/src/types/assertions/ANY_VALUE.ts

@@ -0,0 +1,2 @@
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export const ANY_VALUE: any = undefined;

package/src/types/assertions/isNever/isNever.ts

@@ -0,0 +1,34 @@
+/**
+ * Функция используется для проверки, что переданный ей аргумент имеет тип
+ * never. Это позволяет на уровне статических проверок увидеть, что
+ * при изменении enum была пропущена обработка одного из вариантов.
+ *
+ * @example
+ *      enum Test {
+ *          one,
+ *          two,
+ *          tree
+ *      }
+ *
+ *      function success(arg: Test) {
+ *          switch(arg) {
+ *              case Test.one:
+ *              case Test.two:
+ *              case Test.tree: // <---
+ *                  return;
+ *              default:
+ *                  isNever(arg);
+ *          }
+ *      }
+ *
+ *      function fail(arg: Test) {
+ *          switch(arg) {
+ *              case Test.one:
+ *              case Test.two:
+ *                  return;
+ *              default:
+ *                  isNever(arg); <-- type error "Test.tree is not never"
+ *          }
+ *      }
+ */
+export function isNever(_: never) {}

package/src/types/assertions/isTrue/isTrue.ts

@@ -0,0 +1,13 @@
+/**
+ * Used for checking type assertions
+ *
+ *
+ * type IsEqualUnion<T, U> = [T] extends [U] ? [U] extends [T] ? true : false : false;
+ *
+ * type StringLiteralA = 'a' | 'b' | 'c';
+ *
+ * type StringLiteralB = 'a' | 'b' | 'c';
+ *
+ * isTrue(ANY_VALUE as IsEqualUnion<StringLiteralA, StringLiteralB>);
+ */
+export function isTrue(_: true) {}

package/src/utils/AbortableProcess.ts

@@ -0,0 +1,160 @@
+import { PositiveInteger } from '../types/Number/PositiveInteger';
+import { UnsignedInteger } from '../types/Number/UnsignedInteger';
+import { UnixTimeMs } from '../types/Time/UnixTimeMs';
+
+import { createIncrementalIntegerGenerator } from './createIncrementalIntegerGenerator';
+import { callFunctions } from './Function/callFunctions/callFunctions';
+import { Latch, LatchCallback } from './Latch/Latch';
+import { Signal } from './Signal/Signal';
+
+export type AbortableProcessAbortReason = string | undefined;
+
+export type VisualizedProcessesTree = {
+    name: string;
+    id: UnsignedInteger;
+    status: string | undefined;
+    startTimestamp: UnixTimeMs;
+    children: VisualizedProcessesTree[];
+};
+
+export type VisualizedProcessesTreeChangeAdd = {
+    type: 'add';
+    id: PositiveInteger;
+    name: string;
+    startTimestamp: UnixTimeMs;
+    parentId: PositiveInteger;
+};
+
+export type VisualizedProcessesTreeChangeStatus = {
+    type: 'status';
+    id: PositiveInteger;
+    status: string | undefined;
+};
+export type VisualizedProcessesTreeChangeDelete = {
+    type: 'delete';
+    id: PositiveInteger;
+};
+
+export type VisualizedProcessesTreeChange =
+    | VisualizedProcessesTreeChangeAdd
+    | VisualizedProcessesTreeChangeStatus
+    | VisualizedProcessesTreeChangeDelete;
+
+export type VisualizedProcessesTreeChangeCallback = (change: VisualizedProcessesTreeChange) => void;
+
+const incrementalIntegerGenerator = createIncrementalIntegerGenerator();
+
+export type AbortableProcessStatus = string;
+
+export class AbortableProcess {
+    public readonly id = incrementalIntegerGenerator();
+
+    private readonly abortLatch = new Latch<AbortableProcessAbortReason>();
+
+    private readonly children = new Set<AbortableProcess>();
+
+    private readonly startTimestamp: UnixTimeMs = Date.now();
+
+    private _status = new Signal<AbortableProcessStatus>('');
+
+    private _visualizedProcessesTreeSubscribers = new Set<VisualizedProcessesTreeChangeCallback>();
+
+    public constructor(private readonly name: string) {
+        this.abortLatch.subscribe(() => {
+            this.dispatchVisualizedProcessesTreeChange({
+                type: 'delete',
+                id: this.id,
+            });
+        });
+
+        this._status.subscribe((nextStatus) => {
+            this.dispatchVisualizedProcessesTreeChange({
+                type: 'status',
+                id: this.id,
+                status: nextStatus,
+            });
+        });
+    }
+
+    public isAborted(): boolean {
+        return this.abortLatch.isDispatched();
+    }
+
+    public abort(reason: AbortableProcessAbortReason): void {
+        this.abortLatch.dispatch(reason);
+    }
+
+    public subscribeAbort(callback: LatchCallback<AbortableProcessAbortReason>): VoidFunction {
+        return this.abortLatch.subscribe(callback);
+    }
+
+    public unsubscribe(callback: LatchCallback<AbortableProcessAbortReason>): void {
+        this.abortLatch.unsubscribe(callback);
+    }
+
+    public setStatus(status: AbortableProcessStatus): void {
+        this._status.next(status);
+    }
+
+    public child({
+        name,
+        parentNewStatus,
+    }: {
+        name: string;
+        parentNewStatus?: AbortableProcessStatus;
+    }): AbortableProcess {
+        const childProcess = new AbortableProcess(name);
+
+        if (parentNewStatus) {
+            this.setStatus(parentNewStatus);
+        }
+
+        this.abortLatch.subscribe(() => {
+            childProcess.abort('PARENT_ABORT');
+        });
+
+        childProcess.subscribeVisualizedProcessesTreeChange(this.dispatchVisualizedProcessesTreeChange);
+
+        this.children.add(childProcess);
+        this.dispatchVisualizedProcessesTreeChange({
+            type: 'add',
+            id: childProcess.id,
+            name,
+            parentId: this.id,
+            startTimestamp: childProcess.startTimestamp,
+        });
+
+        childProcess.subscribeAbort(() => {
+            this.children.delete(childProcess);
+        });
+
+        return childProcess;
+    }
+
+    public subscribeVisualizedProcessesTreeChange(callback: VisualizedProcessesTreeChangeCallback): VoidFunction {
+        this._visualizedProcessesTreeSubscribers.add(callback);
+
+        return () => {
+            this._visualizedProcessesTreeSubscribers.delete(callback);
+        };
+    }
+
+    public toJSON(): VisualizedProcessesTree {
+        const result: VisualizedProcessesTree = {
+            name: this.name,
+            id: this.id,
+            status: this._status.value(),
+            startTimestamp: this.startTimestamp,
+            children: Array.from(
+                this.children.values(),
+                (process) => process.toJSON()
+            ),
+        };
+
+        return result;
+    }
+
+    private readonly dispatchVisualizedProcessesTreeChange = (change: VisualizedProcessesTreeChange): void => {
+        callFunctions(this._visualizedProcessesTreeSubscribers, change);
+    };
+}

package/src/utils/Array/createArray/createArray.ts

@@ -0,0 +1,8 @@
+import { UnsignedInteger } from '../../../types/Number/UnsignedInteger';
+
+interface CreateArray {
+    (length: UnsignedInteger): undefined[];
+    <T>(length: UnsignedInteger, value: T): T[];
+}
+
+export const createArray: CreateArray = <T>(length: UnsignedInteger, value?: T) => Array.from({ length }, () => value);

package/src/utils/Array/createIntegerSequenceArray/createIntegerSequenceArray.ts

@@ -0,0 +1,3 @@
+import { Integer } from '../../../types/Number/Integer';
+
+export const createIntegerSequenceArray = (start: Integer, end: Integer): Integer[] => Array.from({ length: end - start + 1 }, (_, i) => start + i);

package/src/utils/Array/getUniqueValues/getUniqueValues.ts

@@ -0,0 +1,3 @@
+export function getUniqueValues<T>(array: ReadonlyArray<T>): T[] {
+    return array.filter((value, index, arr) => arr.indexOf(value) === index);
+}

package/src/utils/Array/separateToArrays/separateToArrays.ts

@@ -0,0 +1,24 @@
+export function separateToArrays<T>(
+    array: Iterable<T>,
+    separateFunction: (value: T, index: number, currentArray: Iterable<T>) => boolean
+): [T[], T[]] {
+    const appropriate: T[] = [];
+    const inappropriate: T[] = [];
+
+    let index = 0;
+
+    for (const value of array) {
+        if (separateFunction(value, index, array)) {
+            appropriate.push(value as T);
+        } else {
+            inappropriate.push(value);
+        }
+
+        index++;
+    }
+
+    return [
+        appropriate,
+        inappropriate,
+    ];
+}

package/src/utils/Array/shuffleArray/shuffleArray.ts

@@ -0,0 +1,18 @@
+export function shuffleArray <T>(array: T[]) {
+    let currentIndex = array.length;
+
+    while (currentIndex !== 0) {
+        // Pick a remaining element...
+        const randomIndex = Math.floor(Math.random() * currentIndex);
+
+        currentIndex--;
+
+        [
+            array[currentIndex],
+            array[randomIndex],
+        ] = [
+            array[randomIndex],
+            array[currentIndex],
+        ];
+    }
+}

package/src/utils/CircularBuffer/CircularBuffer.ts

@@ -0,0 +1,117 @@
+import { UnsignedInteger } from '../../types/Number/UnsignedInteger';
+
+/**
+ * Lightweight circular buffer implementation
+ *
+ * More advanced implementation is Deque
+ */
+export class CircularBuffer<T> {
+    public length = 0;
+
+    private readonly capacity: number;
+    private readonly buffer: (T | undefined)[];
+    private head = 0;
+    private tail = 0;
+
+    public constructor(capacity: number) {
+        this.capacity = capacity;
+        this.buffer = new Array(capacity);
+    }
+
+    public *[Symbol.iterator](): IterableIterator<T> {
+        for (let i = 0; i < this.length; i++) {
+            const index = (this.head + i) % this.capacity;
+            const item = this.buffer[index];
+
+            yield item!;
+        }
+    }
+
+    public at(index: number): T | undefined {
+        if (this.length === 0) {
+            return undefined;
+        }
+
+        if (index < 0) {
+            index = this.length + index;
+        }
+
+        if (index < 0 || index >= this.length) {
+            return undefined;
+        }
+
+        return this.buffer[(this.head + index) % this.capacity];
+    }
+
+    public push(item: T): void {
+        this.buffer[this.tail] = item;
+        this.tail = (this.tail + 1) % this.capacity;
+        if (this.length < this.capacity) {
+            this.length++;
+        } else {
+            this.head = (this.head + 1) % this.capacity;
+        }
+    }
+
+    public pop(): T | undefined {
+        if (this.length === 0) {
+            return undefined;
+        }
+
+        this.tail = (this.tail - 1 + this.capacity) % this.capacity;
+        const item = this.buffer[this.tail];
+
+        this.buffer[this.tail] = undefined;
+        this.length--;
+
+        return item;
+    }
+
+    public popCount(count: UnsignedInteger): T[] {
+        const resultCount = Math.min(count, this.length);
+
+        const items: T[] = [];
+
+        for (let i = 0; i < resultCount; i++) {
+            items.push(this.pop()!);
+        }
+
+        return items;
+    }
+
+    public shift(): T | undefined {
+        if (this.length === 0) {
+            return undefined;
+        }
+
+        const item = this.buffer[this.head];
+
+        this.buffer[this.head] = undefined;
+        this.head = (this.head + 1) % this.capacity;
+        this.length--;
+
+        return item;
+    }
+
+    public shiftCount(count: UnsignedInteger): T[] {
+        const resultCount = Math.min(count, this.length);
+
+        const items: T[] = [];
+
+        for (let i = 0; i < resultCount; i++) {
+            items.push(this.shift()!);
+        }
+
+        return items;
+    }
+
+    public unshift(item: T): void {
+        this.head = (this.head - 1 + this.capacity) % this.capacity;
+        this.buffer[this.head] = item;
+        if (this.length < this.capacity) {
+            this.length++;
+        } else {
+            this.tail = (this.tail - 1 + this.capacity) % this.capacity;
+        }
+    }
+}

package/src/utils/DOM/blurDocument.ts

@@ -0,0 +1,3 @@
+export function blurDocument(): void {
+    (document.activeElement as HTMLElement)?.blur();
+}

package/src/utils/DOM/unfocusDocument.ts

@@ -0,0 +1,3 @@
+import { blurDocument } from './blurDocument';
+
+export const unfocusDocument = blurDocument;

package/src/utils/Date/dateToUnixTimeSec/dateToUnixTimeSec.ts

@@ -0,0 +1,6 @@
+import { MS_IN_SEC } from '../../../types/Time/Time';
+import { UnixTimeSec } from '../../../types/Time/UnixTimeSec';
+
+export function dateToUnixTimeSec(date: Date): UnixTimeSec {
+    return Math.floor(date.getTime() / MS_IN_SEC);
+}

package/src/utils/Date/isoDateStringToUnixTimeMs/isoDateStringToUnixTimeMs.ts

@@ -0,0 +1,6 @@
+import { ISODateString } from '../../../types/Time/ISODateString/ISODateString';
+import { UnixTimeMs } from '../../../types/Time/UnixTimeMs';
+
+export function isoDateStringToUnixTimeMs(date: ISODateString): UnixTimeMs {
+    return new Date(date).getTime();
+}

package/src/utils/Date/isoDateStringToUnixTimeSec/isoDateStringToUnixTimeSec.ts

@@ -0,0 +1,7 @@
+import { ISODateString } from '../../../types/Time/ISODateString/ISODateString';
+import { UnixTimeSec } from '../../../types/Time/UnixTimeSec';
+import { isoDateStringToUnixTimeMs } from '../isoDateStringToUnixTimeMs/isoDateStringToUnixTimeMs';
+
+export function isoDateStringToUnixTimeSec(date: ISODateString): UnixTimeSec {
+    return Math.floor(isoDateStringToUnixTimeMs(date) / 1000);
+}

package/src/utils/Date/unixTimeSecToIsoDateString/unixTimeSecToIsoDateString.ts

@@ -0,0 +1,6 @@
+import { ISODateString } from '../../../types/Time/ISODateString/ISODateString';
+import { UnixTimeSec } from '../../../types/Time/UnixTimeSec';
+
+export function unixTimeSecToIsoDateString(time: UnixTimeSec): ISODateString {
+    return new Date(time * 1000).toISOString();
+}