senaev-utils 1.0.0

package/src/utils/Signal/useSignal.ts

@@ -0,0 +1,10 @@
+import { useSyncExternalStore } from 'react';
+
+import { Signal } from './Signal';
+
+export function useSignal<T>(signal: Signal<T>): T {
+    return useSyncExternalStore(
+        (cb) => signal.subscribe(cb),
+        () => signal.value()
+    );
+}

package/src/utils/String/HexString/HEX_SYMBOLS.ts

@@ -0,0 +1 @@
+export const HEX_SYMBOLS = '0123456789abcdef';

package/src/utils/String/HexString/HexString.ts

@@ -0,0 +1,2 @@
+// Hexadecimal string like "1234567890abcdef"
+export type HexString = string;

package/src/utils/String/HexString/isHexString.ts

@@ -0,0 +1,16 @@
+import { HEX_SYMBOLS } from './HEX_SYMBOLS';
+import { HexString } from './HexString';
+
+export function isHexString(str: unknown): str is HexString {
+    if (typeof str !== 'string') {
+        return false;
+    }
+
+    for (let key = 0; key < str.length; key++) {
+        if (HEX_SYMBOLS.indexOf(str[key].toLowerCase()) < 0) {
+            return false;
+        }
+    }
+
+    return true;
+}

package/src/utils/String/NonEmptyString/NonEmptyString.ts

@@ -0,0 +1,22 @@
+import { isString } from '../isString';
+
+export type NonEmptyString = string;
+
+/**
+ * Проверяет, что аргумент - строка, причем непустая
+ */
+export function isNonEmptyString (str: unknown): str is string {
+    return isString(str) && str.length > 0;
+}
+
+export function assertNonEmptyString(value: unknown, errorMessage?: string): asserts value is NonEmptyString {
+    if (!isNonEmptyString(value)) {
+        let message = `value=[${value}] is not a string or empty`;
+
+        if (errorMessage) {
+            message += ` message=[${errorMessage}]`;
+        }
+
+        throw new Error(message);
+    }
+}

package/src/utils/String/endsWith/index.ts

@@ -0,0 +1,6 @@
+/**
+ * Проверка на то, что строка имеет определенное окончание
+ */
+export function endsWith(str: string, suffix: string): boolean {
+    return suffix === str.substring(str.length - suffix.length);
+}

package/src/utils/String/isString.ts

@@ -0,0 +1,3 @@
+export function isString (value: unknown): value is string {
+    return typeof value === 'string';
+}

package/src/utils/binarySearch/binarySearch.ts

@@ -0,0 +1,20 @@
+export function binarySearch(sortedArray: number[], key: number): number {
+    let left = 0;
+    let right = sortedArray.length - 1;
+
+    while (left <= right) {
+        const middle = Math.floor((left + right) / 2);
+
+        if (sortedArray[middle] === key) {
+            return middle;
+        }
+
+        if (sortedArray[middle] < key) {
+            left = middle + 1;
+        } else {
+            right = middle - 1;
+        }
+    }
+
+    return -1;
+}

package/src/utils/binarySearchClosest/binarySearchClosest.ts

@@ -0,0 +1,43 @@
+import { UnsignedInteger } from '../../types/Number/UnsignedInteger';
+
+export function binarySearchClosest<T>(
+    sortedArray: T[],
+    /**
+     * return positive to search left, negative to search right, 0 to return index
+     * for equal distances, returns lower index
+     */
+    compareFunction: (a: T) => number
+): UnsignedInteger {
+    if (sortedArray.length === 0) {
+        throw new Error('Array must not be empty for binarySearchClosest function');
+    }
+
+    let left = 0;
+    let right = sortedArray.length - 1;
+
+    while (left < right - 1) {
+        const midIndex = Math.floor((left + right) / 2);
+        const midValue = sortedArray[midIndex];
+
+        const compareResult = compareFunction(midValue);
+
+        if (compareResult === 0) {
+            return midIndex;
+        }
+
+        if (compareResult > 0) {
+            right = midIndex;
+        } else {
+            left = midIndex;
+        }
+    }
+
+    const leftDistance = Math.abs(compareFunction(sortedArray[left]));
+    const rightDistance = Math.abs(compareFunction(sortedArray[right]));
+
+    if (leftDistance > rightDistance) {
+        return right;
+    }
+
+    return left;
+}

package/src/utils/createIncrementalIntegerGenerator.ts

@@ -0,0 +1,7 @@
+import { PositiveInteger } from '../types/Number/PositiveInteger';
+
+export function createIncrementalIntegerGenerator(): () => PositiveInteger {
+    let i = 0;
+
+    return () => ++i;
+}

package/src/utils/createRemoteDataProcessingWindow/createRemoteDataProcessingWindow.ts

@@ -0,0 +1,157 @@
+import { assertPositiveInteger, PositiveInteger } from '../../types/Number/PositiveInteger';
+import { CircularBuffer } from '../CircularBuffer/CircularBuffer';
+import { noop } from '../Function/noop';
+import { restrictParallelCalls } from '../Promise/restrictParallelCalls/restrictParallelCalls';
+
+export type RemoteDataProcessingWindowLoadNextItemsReturnType<T> = {
+    items: T[];
+    isLast: boolean;
+};
+export type RemoteDataProcessingWindowExtractItemsFunction<T> = (requestedItemsCount: PositiveInteger) => Promise<RemoteDataProcessingWindowLoadNextItemsReturnType<T>>;
+
+export type RemoteDataProcessingWindowLoadNextItemsParams<T> = {
+    lastItem: T | undefined;
+    count: PositiveInteger;
+};
+export type RemoteDataProcessingWindowLoadNextItemsFunction<T> = (params: RemoteDataProcessingWindowLoadNextItemsParams<T>) => Promise<RemoteDataProcessingWindowLoadNextItemsReturnType<T>>;
+
+/**
+ * The function receives a buffer size and a function for loading data from remote source
+ *
+ * The function is dedicated to fill the buffer in the beginning and every time when the client extracts data from it,
+ * until the remote data is finished
+ */
+export function createRemoteDataProcessingWindow<T>({
+    bufferSize,
+    loadNextItems,
+}: {
+    /**
+     * The size of the buffer (how many items are kept in the memory)
+     */
+    bufferSize: PositiveInteger;
+    /**
+     * The method for requesting data from local buffer or from server.
+     */
+    loadNextItems: RemoteDataProcessingWindowLoadNextItemsFunction<T>;
+}): RemoteDataProcessingWindowExtractItemsFunction<T> {
+    const buffer = new CircularBuffer<T>(bufferSize);
+
+    let isRemoteDataFinished = false;
+    let lastItemPushedToBuffer: T | undefined = undefined;
+
+    let processingCallback: VoidFunction = noop;
+
+    // One error is enough to stop the whole process
+    let error: {
+        error: Error;
+    } | undefined = undefined;
+
+    let isRequestInProgress = false;
+
+    async function requestRemoteItemsToFillBuffer() {
+        if (isRequestInProgress || isRemoteDataFinished) {
+            return;
+        }
+
+        const countToLoad = bufferSize - buffer.length;
+
+        if (countToLoad === 0) {
+            return;
+        }
+
+        isRequestInProgress = true;
+
+        try {
+            const { isLast, items } = await loadNextItems({
+                count: countToLoad,
+                lastItem: lastItemPushedToBuffer,
+            });
+
+            isRequestInProgress = false;
+
+            if (isLast) {
+                isRemoteDataFinished = true;
+            } else if (items.length !== countToLoad) {
+                throw new Error(`createRemoteDataProcessingWindow: loadNextItems for isLast=false returned wrong items count=[${items.length}] expected=[${countToLoad}]`);
+            }
+
+            for (const item of items) {
+                buffer.push(item);
+            }
+
+            lastItemPushedToBuffer = items.at(-1);
+
+            requestRemoteItemsToFillBuffer();
+        } catch (e) {
+            isRequestInProgress = false;
+            error = {
+                error: e as Error,
+            };
+        } finally {
+            processingCallback();
+        }
+    }
+
+    requestRemoteItemsToFillBuffer();
+
+    // eslint-disable-next-line require-await
+    return restrictParallelCalls(async (requestedItemsCount): Promise<RemoteDataProcessingWindowLoadNextItemsReturnType<T>> => {
+        if (error) {
+            throw error.error;
+        }
+
+        assertPositiveInteger(requestedItemsCount);
+
+        if (requestedItemsCount > bufferSize) {
+            throw new Error(`createRemoteDataProcessingWindow: requestedItemsCount=[${requestedItemsCount}] must be less than bufferSize=[${bufferSize}]`);
+        }
+
+        // Has enough items to extract
+        if (buffer.length >= requestedItemsCount) {
+            const items = buffer.shiftCount(requestedItemsCount);
+
+            requestRemoteItemsToFillBuffer();
+
+            return {
+                items,
+                isLast: isRemoteDataFinished && buffer.length === 0,
+            };
+        }
+
+        // No more data in remote, nothing to wait
+        if (isRemoteDataFinished) {
+            const items = buffer.shiftCount(requestedItemsCount);
+
+            return {
+                items,
+                isLast: buffer.length === 0,
+            };
+        }
+
+        return new Promise<RemoteDataProcessingWindowLoadNextItemsReturnType<T>>((resolve, reject) => {
+            processingCallback = () => {
+                if (error) {
+                    reject(error.error);
+
+                    return;
+                }
+
+                if (buffer.length < requestedItemsCount && !isRemoteDataFinished) {
+                    return;
+                }
+
+                processingCallback = noop;
+
+                const items = buffer.shiftCount(requestedItemsCount);
+                const isLast = isRemoteDataFinished && buffer.length === 0;
+
+                requestRemoteItemsToFillBuffer();
+
+                resolve({
+                    items,
+                    isLast,
+                });
+            };
+        });
+    }, 'createRemoteDataProcessingWindow');
+}

package/src/utils/createSimultaneousOperationsHandler/createSimultaneousOperationsHandler.ts

@@ -0,0 +1,65 @@
+import { UnsignedInteger } from '../../types/Number/UnsignedInteger';
+
+export type SimultaneousOperationsHandlerParams<T> = {
+    index: UnsignedInteger;
+    param: T;
+};
+
+export type SimultaneousOperationsHandlerParamsWithResult<T, R> = {
+    paramsList: SimultaneousOperationsHandlerParams<T>[];
+    result: R;
+};
+
+export type SimultaneousOperationCall<T, R> = {
+    param: T;
+    resolve: (result: SimultaneousOperationsHandlerParamsWithResult<T, R>) => void;
+    reject: (error: Error) => void;
+};
+
+export function createSimultaneousOperationsHandler<T, R>(callback: (syncParamsToCall: SimultaneousOperationsHandlerParams<T>[]) => R): (
+    param: T,
+    index: UnsignedInteger
+) => Promise<SimultaneousOperationsHandlerParamsWithResult<T, R>> {
+    let expectedNextIndex: UnsignedInteger = 0;
+    const queuedOperationsStore = new Map<UnsignedInteger, SimultaneousOperationCall<T, R>>();
+
+    return (param: T, index: UnsignedInteger): Promise<SimultaneousOperationsHandlerParamsWithResult<T, R>> => {
+        const promise = new Promise<SimultaneousOperationsHandlerParamsWithResult<T, R>>((resolve, reject) => {
+            queuedOperationsStore.set(index, {
+                param,
+                resolve,
+                reject,
+            });
+        });
+
+        const syncParamsToCall: SimultaneousOperationsHandlerParams<T>[] = [];
+        const operationCalls: SimultaneousOperationCall<T, R>[] = [];
+
+        while (queuedOperationsStore.has(expectedNextIndex)) {
+            const nextOperation = queuedOperationsStore.get(expectedNextIndex)!;
+
+            syncParamsToCall.push({
+                index: expectedNextIndex,
+                param: nextOperation.param,
+            });
+
+            operationCalls.push(nextOperation);
+
+            queuedOperationsStore.delete(expectedNextIndex);
+            expectedNextIndex++;
+        }
+
+        if (syncParamsToCall.length > 0) {
+            const result = callback(syncParamsToCall);
+
+            for (const operation of operationCalls) {
+                operation.resolve({
+                    paramsList: syncParamsToCall,
+                    result,
+                });
+            }
+        }
+
+        return promise;
+    };
+}

package/src/utils/encryptDecryptString/encryptDecryptString.ts

@@ -0,0 +1,34 @@
+import {
+    base64url,
+    EncryptJWT,
+    jwtDecrypt,
+} from 'jose';
+
+export function encryptString({
+    string,
+    secret,
+}: {
+    string: string;
+    secret: string;
+}): Promise<string> {
+    return new EncryptJWT({
+        string,
+    })
+        .setProtectedHeader({
+            alg: 'dir',
+            enc: 'A128CBC-HS256',
+        })
+        .encrypt(base64url.decode(secret));
+}
+
+export async function decryptString({
+    string,
+    secret,
+}: {
+    string: string;
+    secret: string;
+}): Promise<string> {
+    const { payload } = await jwtDecrypt(string, base64url.decode(secret));
+
+    return payload.string as string;
+}

package/src/utils/getPrimeNumbersWithEratosthenesSieve/getPrimeNumbersWithEratosthenesSieve.ts

@@ -0,0 +1,21 @@
+import { PositiveInteger } from '../../types/Number/PositiveInteger';
+
+export function getPrimeNumbersWithEratosthenesSieve(max: PositiveInteger): PositiveInteger[] {
+    const sieve = Array.from({ length: max + 1 });
+
+    for (let base = 2; base <= max ** 0.5; base++) {
+        for (let i = base ** 2; i <= max; i += base) {
+            sieve[i] = true;
+        }
+    }
+
+    const primes = [];
+
+    for (let i = 2; i <= max; i++) {
+        if (!sieve[i]) {
+            primes.push(i);
+        }
+    }
+
+    return primes;
+}

package/src/utils/isPromise/isPromise.ts

@@ -0,0 +1,30 @@
+import { isObject } from '../../types/Object/Object';
+import { isFunction } from '../Function/isFunction';
+
+const isPromiseLike = (maybePromise: unknown): boolean => {
+    if (!isObject(maybePromise)) {
+        return false;
+    }
+
+    if (!isFunction(maybePromise.then)) {
+        return false;
+    }
+
+    if (!isFunction(maybePromise.catch)) {
+        return false;
+    }
+
+    if (!isFunction(maybePromise.finally)) {
+        return false;
+    }
+
+    return true;
+};
+
+export const isPromise = <T extends Promise<PT>, PT>(maybePromise: unknown): maybePromise is T => {
+    if (maybePromise instanceof Promise) {
+        return true;
+    }
+
+    return isPromiseLike(maybePromise);
+};

package/src/utils/makeAsyncFunctionCallsSimultaneous/makeAsyncFunctionCallsSimultaneous.ts

@@ -0,0 +1,64 @@
+import { isPromise } from '../isPromise/isPromise';
+
+/**
+ * Creates a wrapper that ensures async function calls are executed sequentially
+ * even when called simultaneously. Maintains order of execution by using a queue.
+ *
+ * @param callback The async function to be wrapped
+ * @returns A function that queues and executes the async operations sequentially
+ */
+export function makeAsyncFunctionCallsSimultaneous<T, R>(callback: (param: T) => (R | Promise<R>)): (param: T) => Promise<R> {
+    let isAsyncOperationRunning = false;
+    const operationsQueue: {
+        resolve: (value: R) => void;
+        reject: (error: Error) => void;
+        param: T;
+    }[] = [];
+
+    function runAsyncOperations() {
+        isAsyncOperationRunning = true;
+
+        const operation = operationsQueue.shift();
+
+        if (!operation) {
+            isAsyncOperationRunning = false;
+
+            return;
+        }
+
+        try {
+            const returnValue = callback(operation.param);
+
+            if (isPromise(returnValue)) {
+                returnValue
+                    .then(operation.resolve)
+                    .catch(operation.reject)
+                    .finally(runAsyncOperations);
+            } else {
+                operation.resolve(returnValue);
+                runAsyncOperations();
+            }
+        } catch (error) {
+            operation.reject(error as Error);
+            runAsyncOperations();
+        }
+    }
+
+    return (param: T): Promise<R> => {
+        const promise = new Promise<R>((resolve, reject) => {
+            operationsQueue.push({
+                resolve,
+                reject,
+                param,
+            });
+        });
+
+        if (isAsyncOperationRunning) {
+            return promise;
+        }
+
+        runAsyncOperations();
+
+        return promise;
+    };
+}

package/src/utils/parallelsLimitPromise/index.ts

@@ -0,0 +1,28 @@
+import { parallelLimit } from 'async';
+
+import { PositiveInteger } from '../../types/Number/PositiveInteger';
+
+export function parallelsLimitPromise<T>(functions: (() => Promise<T>)[], limit: PositiveInteger): Promise<T[]> {
+    return new Promise<T[]>((resolve, reject) => {
+        parallelLimit<T>(
+            functions.map((asyncFunction) => (callback) => {
+                asyncFunction()
+                    .then((result) => {
+                        callback(null, result);
+                    })
+                    .catch((error) => {
+                        callback(error);
+                    });
+            }),
+            limit,
+            (error, result) => {
+                if (error) {
+                    error.message = `parallelsLimitPromise error=[${error.message}]`;
+                    reject(error);
+                } else {
+                    resolve(result as T[]);
+                }
+            }
+        );
+    });
+}

package/src/utils/parallelsLimitQueue/parallelsLimitQueue.ts

@@ -0,0 +1,69 @@
+import { PositiveInteger } from '../../types/Number/PositiveInteger';
+import { UnsignedInteger } from '../../types/Number/UnsignedInteger';
+import { isPromise } from '../isPromise/isPromise';
+
+export function parallelsLimitQueue<T, R>({
+    callback,
+    limit,
+}: {
+    callback: (param: T) => R | Promise<R>;
+    limit: PositiveInteger;
+}): (param: T) => Promise<R> {
+    let operationsRunning: UnsignedInteger = 0;
+    const queue: {
+        param: T;
+        resolve: (result: R) => void;
+        reject: (error: Error) => void;
+    }[] = [];
+
+    async function runOperations() {
+        if (operationsRunning >= limit) {
+            return;
+        }
+
+        const operation = queue.shift();
+
+        if (!operation) {
+            return;
+        }
+
+        const {
+            param,
+            resolve,
+            reject,
+        } = operation;
+
+        operationsRunning++;
+
+        try {
+            const resultValue = callback(param);
+
+            if (isPromise(resultValue)) {
+                const result = await resultValue;
+
+                resolve(result);
+            } else {
+                resolve(resultValue);
+            }
+        } catch (error) {
+            reject(error as Error);
+        } finally {
+            operationsRunning--;
+            runOperations();
+        }
+    }
+
+    return (param: T) => {
+        const promise = new Promise<R>((resolve, reject) => {
+            queue.push({
+                param,
+                resolve,
+                reject,
+            });
+        });
+
+        runOperations();
+
+        return promise;
+    };
+}

package/src/utils/prettyStringify/index.ts

@@ -0,0 +1,3 @@
+export function prettyStringify (jsonObject: unknown): string {
+    return JSON.stringify(jsonObject, undefined, 2);
+}