doubly-linked-list-typed 2.1.1 → 2.1.2

package/dist/types/types/utils/utils.d.ts

@@ -0,0 +1,22 @@
+export type SpecifyOptional<T, K extends keyof T> = Omit<T, K> & Partial<Pick<T, K>>;
+export type Any = string | number | bigint | boolean | symbol | undefined | object;
+export type Arithmetic = number | bigint;
+export type ElemOf<T> = T extends (infer U)[] ? U : never;
+export type ComparablePrimitive = number | bigint | string | boolean;
+export interface BaseComparableObject {
+    [key: string]: unknown;
+}
+export interface ValueComparableObject extends BaseComparableObject {
+    valueOf: () => ComparablePrimitive | ValueComparableObject;
+    toString?: () => string;
+}
+export interface StringComparableObject extends BaseComparableObject {
+    toString: () => string;
+}
+export type ComparableObject = ValueComparableObject | StringComparableObject;
+export type Comparable = ComparablePrimitive | Date | ComparableObject;
+export type TrampolineThunk<T> = {
+    readonly isThunk: true;
+    readonly fn: () => Trampoline<T>;
+};
+export type Trampoline<T> = T | TrampolineThunk<T>;

package/dist/types/utils/index.d.ts

@@ -1,2 +1,2 @@
 export * from './utils';
-export * from './validate-type';
+export * from './number';

package/dist/types/utils/utils.d.ts

@@ -1,22 +1,209 @@
-export type SpecifyOptional<T, K extends keyof T> = Omit<T, K> & Partial<Pick<T, K>>;
-export type Any = string | number | bigint | boolean | symbol | undefined | object;
-export type Arithmetic = number | bigint;
-export type ElemOf<T> = T extends (infer U)[] ? U : never;
-export type ComparablePrimitive = number | bigint | string | boolean;
-export interface BaseComparableObject {
-    [key: string]: unknown;
-}
-export interface ValueComparableObject extends BaseComparableObject {
-    valueOf: () => ComparablePrimitive | ValueComparableObject;
-    toString?: () => string;
-}
-export interface StringComparableObject extends BaseComparableObject {
-    toString: () => string;
-}
-export type ComparableObject = ValueComparableObject | StringComparableObject;
-export type Comparable = ComparablePrimitive | Date | ComparableObject;
-export type TrampolineThunk<T> = {
-    readonly isThunk: true;
-    readonly fn: () => Trampoline<T>;
-};
-export type Trampoline<T> = T | TrampolineThunk<T>;
+/**
+ * data-structure-typed
+ *
+ * @author Pablo Zeng
+ * @copyright Copyright (c) 2022 Pablo Zeng <zrwusa@gmail.com>
+ * @license MIT License
+ */
+import type { Comparable, Trampoline, TrampolineThunk } from '../types';
+/**
+ * The function generates a random UUID (Universally Unique Identifier) in TypeScript.
+ * @returns A randomly generated UUID (Universally Unique Identifier) in the format
+ * 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx' where each 'x' is replaced with a random hexadecimal
+ * character.
+ */
+export declare const uuidV4: () => string;
+/**
+ * The `arrayRemove` function removes elements from an array based on a specified predicate function
+ * and returns the removed elements.
+ * @param {T[]} array - An array of elements that you want to filter based on the provided predicate
+ * function.
+ * @param predicate - The `predicate` parameter is a function that takes three arguments:
+ * @returns The `arrayRemove` function returns an array containing the elements that satisfy the given
+ * `predicate` function.
+ */
+export declare const arrayRemove: <T>(array: T[], predicate: (item: T, index: number, array: T[]) => boolean) => T[];
+/**
+ * The function `getMSB` returns the most significant bit of a given number.
+ * @param {number} value - The `value` parameter is a number for which we want to find the position of
+ * the Most Significant Bit (MSB). The function `getMSB` takes this number as input and calculates the
+ * position of the MSB in its binary representation.
+ * @returns The function `getMSB` returns the most significant bit (MSB) of the input `value`. If the
+ * input value is less than or equal to 0, it returns 0. Otherwise, it calculates the position of the
+ * MSB using the `Math.clz32` function and bitwise left shifts 1 to that position.
+ */
+export declare const getMSB: (value: number) => number;
+/**
+ * The `rangeCheck` function in TypeScript is used to validate if an index is within a specified range
+ * and throws a `RangeError` with a custom message if it is out of bounds.
+ * @param {number} index - The `index` parameter represents the value that you want to check if it
+ * falls within a specified range.
+ * @param {number} min - The `min` parameter represents the minimum value that the `index` should be
+ * compared against in the `rangeCheck` function.
+ * @param {number} max - The `max` parameter in the `rangeCheck` function represents the maximum value
+ * that the `index` parameter is allowed to have. If the `index` is greater than this `max` value, a
+ * `RangeError` will be thrown.
+ * @param [message=Index out of bounds.] - The `message` parameter is a string that represents the
+ * error message to be thrown if the index is out of bounds. By default, if no message is provided when
+ * calling the `rangeCheck` function, the message "Index out of bounds." will be used.
+ */
+export declare const rangeCheck: (index: number, min: number, max: number, message?: string) => void;
+/**
+ * The function `throwRangeError` throws a RangeError with a custom message if called.
+ * @param [message=The value is off-limits.] - The `message` parameter is a string that represents the
+ * error message to be displayed when a `RangeError` is thrown. If no message is provided, the default
+ * message is 'The value is off-limits.'.
+ */
+export declare const throwRangeError: (message?: string) => void;
+/**
+ * The function `isWeakKey` checks if the input is an object or a function in TypeScript.
+ * @param {unknown} input - The `input` parameter in the `isWeakKey` function is of type `unknown`,
+ * which means it can be any type. The function checks if the `input` is an object (excluding `null`)
+ * or a function, and returns a boolean indicating whether the `input` is a weak
+ * @returns The function `isWeakKey` returns a boolean value indicating whether the input is an object
+ * or a function.
+ */
+export declare const isWeakKey: (input: unknown) => input is object;
+/**
+ * The function `calcMinUnitsRequired` calculates the minimum number of units required to accommodate a
+ * given total quantity based on a specified unit size.
+ * @param {number} totalQuantity - The `totalQuantity` parameter represents the total quantity of items
+ * that need to be processed or handled.
+ * @param {number} unitSize - The `unitSize` parameter represents the size of each unit or package. It
+ * is used in the `calcMinUnitsRequired` function to calculate the minimum number of units required to
+ * accommodate a total quantity of items.
+ */
+export declare const calcMinUnitsRequired: (totalQuantity: number, unitSize: number) => number;
+/**
+ * The `roundFixed` function in TypeScript rounds a number to a specified number of decimal places.
+ * @param {number} num - The `num` parameter is a number that you want to round to a certain number of
+ * decimal places.
+ * @param {number} [digit=10] - The `digit` parameter in the `roundFixed` function specifies the number
+ * of decimal places to round the number to. By default, it is set to 10 if not provided explicitly.
+ * @returns The function `roundFixed` returns a number that is rounded to the specified number of
+ * decimal places (default is 10 decimal places).
+ */
+export declare const roundFixed: (num: number, digit?: number) => number;
+/**
+ * The function `isComparable` in TypeScript checks if a value is comparable, handling primitive values
+ * and objects with optional force comparison.
+ * @param {unknown} value - The `value` parameter in the `isComparable` function represents the value
+ * that you want to check if it is comparable. It can be of any type (`unknown`), and the function will
+ * determine if it is comparable based on certain conditions.
+ * @param [isForceObjectComparable=false] - The `isForceObjectComparable` parameter in the
+ * `isComparable` function is a boolean flag that determines whether to treat non-primitive values as
+ * comparable objects. When set to `true`, it forces the function to consider non-primitive values as
+ * comparable objects, regardless of their type.
+ * @returns The function `isComparable` returns a boolean value indicating whether the `value` is
+ * considered comparable or not.
+ */
+export declare function isComparable(value: unknown, isForceObjectComparable?: boolean): value is Comparable;
+/**
+ * Creates a trampoline thunk object.
+ *
+ * A "thunk" is a deferred computation — instead of performing a recursive call immediately,
+ * it wraps the next step of the computation in a function. This allows recursive processes
+ * to be executed iteratively, preventing stack overflows.
+ *
+ * @template T - The type of the final computation result.
+ * @param computation - A function that, when executed, returns the next trampoline step.
+ * @returns A TrampolineThunk object containing the deferred computation.
+ */
+export declare const makeTrampolineThunk: <T>(computation: () => Trampoline<T>) => TrampolineThunk<T>;
+/**
+ * Type guard to check whether a given value is a TrampolineThunk.
+ *
+ * This function is used to distinguish between a final computation result (value)
+ * and a deferred computation (thunk).
+ *
+ * @template T - The type of the value being checked.
+ * @param value - The value to test.
+ * @returns True if the value is a valid TrampolineThunk, false otherwise.
+ */
+export declare const isTrampolineThunk: <T>(value: Trampoline<T>) => value is TrampolineThunk<T>;
+/**
+ * Executes a trampoline computation until a final (non-thunk) result is obtained.
+ *
+ * The trampoline function repeatedly invokes the deferred computations (thunks)
+ * in an iterative loop. This avoids deep recursive calls and prevents stack overflow,
+ * which is particularly useful for implementing recursion in a stack-safe manner.
+ *
+ * @template T - The type of the final result.
+ * @param initial - The initial Trampoline value or thunk to start execution from.
+ * @returns The final result of the computation (a non-thunk value).
+ */
+export declare function trampoline<T>(initial: Trampoline<T>): T;
+/**
+ * Wraps a recursive function inside a trampoline executor.
+ *
+ * This function transforms a potentially recursive function (that returns a Trampoline<Result>)
+ * into a *stack-safe* function that executes iteratively using the `trampoline` runner.
+ *
+ * In other words, it allows you to write functions that look recursive,
+ * but actually run in constant stack space.
+ *
+ * @template Args - The tuple type representing the argument list of the original function.
+ * @template Result - The final return type after all trampoline steps are resolved.
+ *
+ * @param fn - A function that performs a single step of computation
+ *             and returns a Trampoline (either a final value or a deferred thunk).
+ *
+ * @returns A new function with the same arguments, but which automatically
+ *          runs the trampoline process and returns the *final result* instead
+ *          of a Trampoline.
+ *
+ * @example
+ * // Example: Computing factorial in a stack-safe way
+ * const factorial = makeTrampoline(function fact(n: number, acc: number = 1): Trampoline<number> {
+ *   return n === 0
+ *     ? acc
+ *     : makeTrampolineThunk(() => fact(n - 1, acc * n));
+ * });
+ *
+ * console.log(factorial(100000)); // Works without stack overflow
+ */
+export declare function makeTrampoline<Args extends any[], Result>(fn: (...args: Args) => Trampoline<Result>): (...args: Args) => Result;
+/**
+ * Executes an asynchronous trampoline computation until a final (non-thunk) result is obtained.
+ *
+ * This function repeatedly invokes asynchronous deferred computations (thunks)
+ * in an iterative loop. Each thunk may return either a Trampoline<T> or a Promise<Trampoline<T>>.
+ *
+ * It ensures that asynchronous recursive functions can run without growing the call stack,
+ * making it suitable for stack-safe async recursion.
+ *
+ * @template T - The type of the final result.
+ * @param initial - The initial Trampoline or Promise of Trampoline to start execution from.
+ * @returns A Promise that resolves to the final result (a non-thunk value).
+ */
+export declare function asyncTrampoline<T>(initial: Trampoline<T> | Promise<Trampoline<T>>): Promise<T>;
+/**
+ * Wraps an asynchronous recursive function inside an async trampoline executor.
+ *
+ * This helper transforms a recursive async function that returns a Trampoline<Result>
+ * (or Promise<Trampoline<Result>>) into a *stack-safe* async function that executes
+ * iteratively via the `asyncTrampoline` runner.
+ *
+ * @template Args - The tuple type representing the argument list of the original function.
+ * @template Result - The final return type after all async trampoline steps are resolved.
+ *
+ * @param fn - An async or sync function that performs a single step of computation
+ *             and returns a Trampoline (either a final value or a deferred thunk).
+ *
+ * @returns An async function with the same arguments, but which automatically
+ *          runs the trampoline process and resolves to the *final result*.
+ *
+ * @example
+ * // Example: Async factorial using trampoline
+ * const asyncFactorial = makeAsyncTrampoline(async function fact(
+ *   n: number,
+ *   acc: number = 1
+ * ): Promise<Trampoline<number>> {
+ *   return n === 0
+ *     ? acc
+ *     : makeTrampolineThunk(() => fact(n - 1, acc * n));
+ * });
+ *
+ * asyncFactorial(100000).then(console.log); // Works without stack overflow
+ */
+export declare function makeAsyncTrampoline<Args extends any[], Result>(fn: (...args: Args) => Trampoline<Result> | Promise<Trampoline<Result>>): (...args: Args) => Promise<Result>;