directed-graph-typed 2.0.4 → 2.1.0

package/dist/types/data-structures/base/base.d.ts

@@ -3,7 +3,7 @@ import { LinearBase } from '../../../data-structures/base/linear-base';
 export type EntryCallback<K, V, R> = (key: K, value: V, index: number, original: IterableEntryBase<K, V>) => R;
 export type ElementCallback<E, R, RT> = (element: E, index: number, original: IterableElementBase<E, R>) => RT;
 export type ReduceEntryCallback<K, V, R> = (accumulator: R, value: V, key: K, index: number, original: IterableEntryBase<K, V>) => R;
-export type ReduceElementCallback<E, R, RT = E> = (accumulator: RT, element: E, index: number, original: IterableElementBase<E, R>) => RT;
+export type ReduceElementCallback<E, R, U = E> = (accumulator: U, value: E, index: number, self: IterableElementBase<E, R>) => U;
 export type ReduceLinearCallback<E, RT = E> = (accumulator: RT, element: E, index: number, original: LinearBase<E>) => RT;
 export type IterableElementBaseOptions<E, R> = {
     toElementFn?: (rawElement: R) => E;

package/dist/types/data-structures/graph/abstract-graph.d.ts

@@ -8,3 +8,7 @@ export type DijkstraResult<V> = {
     minDist: number;
     minPath: V[];
 } | undefined;
+export type GraphOptions<V = any> = {
+    vertexValueInitializer?: (key: VertexKey) => V;
+    defaultEdgeWeight?: number;
+};

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

@@ -1,12 +1,7 @@
-export type ToThunkFn<R = any> = () => R;
-export type Thunk<R = any> = ToThunkFn<R> & {
-    __THUNK__?: symbol;
-};
-export type TrlFn<A extends any[] = any[], R = any> = (...args: A) => R;
-export type TrlAsyncFn = (...args: any[]) => any;
 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;
@@ -20,3 +15,8 @@ export interface StringComparableObject extends BaseComparableObject {
 }
 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/utils/utils.d.ts

@@ -5,7 +5,7 @@
  * @copyright Copyright (c) 2022 Pablo Zeng <zrwusa@gmail.com>
  * @license MIT License
  */
-import type { Comparable, Thunk, ToThunkFn, TrlAsyncFn, TrlFn } from '../types';
+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
@@ -23,54 +23,6 @@ export declare const uuidV4: () => string;
  * `predicate` function.
  */
 export declare const arrayRemove: <T>(array: T[], predicate: (item: T, index: number, array: T[]) => boolean) => T[];
-export declare const THUNK_SYMBOL: unique symbol;
-/**
- * The function `isThunk` checks if a given value is a function with a specific symbol property.
- * @param {any} fnOrValue - The `fnOrValue` parameter in the `isThunk` function can be either a
- * function or a value that you want to check if it is a thunk. Thunks are functions that are wrapped
- * around a value or computation for lazy evaluation. The function checks if the `fnOrValue` is
- * @returns The function `isThunk` is checking if the input `fnOrValue` is a function and if it has a
- * property `__THUNK__` equal to `THUNK_SYMBOL`. The return value will be `true` if both conditions are
- * met, otherwise it will be `false`.
- */
-export declare const isThunk: (fnOrValue: any) => boolean;
-/**
- * The `toThunk` function in TypeScript converts a function into a thunk by wrapping it in a closure.
- * @param {ToThunkFn} fn - `fn` is a function that will be converted into a thunk.
- * @returns A thunk function is being returned. Thunk functions are functions that delay the evaluation
- * of an expression or operation until it is explicitly called or invoked. In this case, the `toThunk`
- * function takes a function `fn` as an argument and returns a thunk function that, when called, will
- * execute the `fn` function provided as an argument.
- */
-export declare const toThunk: (fn: ToThunkFn) => Thunk;
-/**
- * The `trampoline` function in TypeScript enables tail call optimization by using thunks to avoid
- * stack overflow.
- * @param {TrlFn} fn - The `fn` parameter in the `trampoline` function is a function that takes any
- * number of arguments and returns a value.
- * @returns The `trampoline` function returns an object with two properties:
- * 1. A function that executes the provided function `fn` and continues to execute any thunks returned
- * by `fn` until a non-thunk value is returned.
- * 2. A `cont` property that is a function which creates a thunk for the provided function `fn`.
- */
-export declare const trampoline: (fn: TrlFn) => ((...args: [...Parameters<TrlFn>]) => any) & {
-    cont: (...args: [...Parameters<TrlFn>]) => ReturnType<TrlFn>;
-};
-/**
- * The `trampolineAsync` function in TypeScript allows for asynchronous trampolining of a given
- * function.
- * @param {TrlAsyncFn} fn - The `fn` parameter in the `trampolineAsync` function is expected to be a
- * function that returns a Promise. This function will be called recursively until a non-thunk value is
- * returned.
- * @returns The `trampolineAsync` function returns an object with two properties:
- * 1. An async function that executes the provided `TrlAsyncFn` function and continues to execute any
- * thunks returned by the function until a non-thunk value is returned.
- * 2. A `cont` property that is a function which wraps the provided `TrlAsyncFn` function in a thunk
- * and returns it.
- */
-export declare const trampolineAsync: (fn: TrlAsyncFn) => ((...args: [...Parameters<TrlAsyncFn>]) => Promise<any>) & {
-    cont: (...args: [...Parameters<TrlAsyncFn>]) => ReturnType<TrlAsyncFn>;
-};
 /**
  * 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
@@ -146,3 +98,112 @@ export declare const roundFixed: (num: number, digit?: number) => number;
  * 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>;

package/dist/utils/utils.js

@@ -9,7 +9,7 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
     });
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.isComparable = exports.roundFixed = exports.calcMinUnitsRequired = exports.isWeakKey = exports.throwRangeError = exports.rangeCheck = exports.getMSB = exports.trampolineAsync = exports.trampoline = exports.toThunk = exports.isThunk = exports.THUNK_SYMBOL = exports.arrayRemove = exports.uuidV4 = void 0;
+exports.makeAsyncTrampoline = exports.asyncTrampoline = exports.makeTrampoline = exports.trampoline = exports.isTrampolineThunk = exports.makeTrampolineThunk = exports.isComparable = exports.roundFixed = exports.calcMinUnitsRequired = exports.isWeakKey = exports.throwRangeError = exports.rangeCheck = exports.getMSB = exports.arrayRemove = exports.uuidV4 = void 0;
 /**
  * The function generates a random UUID (Universally Unique Identifier) in TypeScript.
  * @returns A randomly generated UUID (Universally Unique Identifier) in the format
@@ -46,78 +46,6 @@ const arrayRemove = function (array, predicate) {
     return result;
 };
 exports.arrayRemove = arrayRemove;
-exports.THUNK_SYMBOL = Symbol('thunk');
-/**
- * The function `isThunk` checks if a given value is a function with a specific symbol property.
- * @param {any} fnOrValue - The `fnOrValue` parameter in the `isThunk` function can be either a
- * function or a value that you want to check if it is a thunk. Thunks are functions that are wrapped
- * around a value or computation for lazy evaluation. The function checks if the `fnOrValue` is
- * @returns The function `isThunk` is checking if the input `fnOrValue` is a function and if it has a
- * property `__THUNK__` equal to `THUNK_SYMBOL`. The return value will be `true` if both conditions are
- * met, otherwise it will be `false`.
- */
-const isThunk = (fnOrValue) => {
-    return typeof fnOrValue === 'function' && fnOrValue.__THUNK__ === exports.THUNK_SYMBOL;
-};
-exports.isThunk = isThunk;
-/**
- * The `toThunk` function in TypeScript converts a function into a thunk by wrapping it in a closure.
- * @param {ToThunkFn} fn - `fn` is a function that will be converted into a thunk.
- * @returns A thunk function is being returned. Thunk functions are functions that delay the evaluation
- * of an expression or operation until it is explicitly called or invoked. In this case, the `toThunk`
- * function takes a function `fn` as an argument and returns a thunk function that, when called, will
- * execute the `fn` function provided as an argument.
- */
-const toThunk = (fn) => {
-    const thunk = () => fn();
-    thunk.__THUNK__ = exports.THUNK_SYMBOL;
-    return thunk;
-};
-exports.toThunk = toThunk;
-/**
- * The `trampoline` function in TypeScript enables tail call optimization by using thunks to avoid
- * stack overflow.
- * @param {TrlFn} fn - The `fn` parameter in the `trampoline` function is a function that takes any
- * number of arguments and returns a value.
- * @returns The `trampoline` function returns an object with two properties:
- * 1. A function that executes the provided function `fn` and continues to execute any thunks returned
- * by `fn` until a non-thunk value is returned.
- * 2. A `cont` property that is a function which creates a thunk for the provided function `fn`.
- */
-const trampoline = (fn) => {
-    const cont = (...args) => (0, exports.toThunk)(() => fn(...args));
-    return Object.assign((...args) => {
-        let result = fn(...args);
-        while ((0, exports.isThunk)(result) && typeof result === 'function') {
-            result = result();
-        }
-        return result;
-    }, { cont });
-};
-exports.trampoline = trampoline;
-/**
- * The `trampolineAsync` function in TypeScript allows for asynchronous trampolining of a given
- * function.
- * @param {TrlAsyncFn} fn - The `fn` parameter in the `trampolineAsync` function is expected to be a
- * function that returns a Promise. This function will be called recursively until a non-thunk value is
- * returned.
- * @returns The `trampolineAsync` function returns an object with two properties:
- * 1. An async function that executes the provided `TrlAsyncFn` function and continues to execute any
- * thunks returned by the function until a non-thunk value is returned.
- * 2. A `cont` property that is a function which wraps the provided `TrlAsyncFn` function in a thunk
- * and returns it.
- */
-const trampolineAsync = (fn) => {
-    const cont = (...args) => (0, exports.toThunk)(() => fn(...args));
-    return Object.assign((...args) => __awaiter(void 0, void 0, void 0, function* () {
-        let result = yield fn(...args);
-        while ((0, exports.isThunk)(result) && typeof result === 'function') {
-            result = yield result();
-        }
-        return result;
-    }), { cont });
-};
-exports.trampolineAsync = trampolineAsync;
 /**
  * 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
@@ -276,3 +204,150 @@ function isComparable(value, isForceObjectComparable = false) {
     return isPrimitiveComparable(comparableValue);
 }
 exports.isComparable = isComparable;
+/**
+ * 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.
+ */
+const makeTrampolineThunk = (computation) => ({
+    isThunk: true,
+    fn: computation // The deferred computation function
+});
+exports.makeTrampolineThunk = makeTrampolineThunk;
+/**
+ * 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.
+ */
+const isTrampolineThunk = (value) => typeof value === 'object' && // Must be an object
+    value !== null && // Must not be null
+    'isThunk' in value && // Must have the 'isThunk' property
+    value.isThunk; // The flag must be true
+exports.isTrampolineThunk = isTrampolineThunk;
+/**
+ * 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).
+ */
+function trampoline(initial) {
+    let current = initial; // Start with the initial trampoline value
+    while ((0, exports.isTrampolineThunk)(current)) {
+        // Keep unwrapping while we have thunks
+        current = current.fn(); // Execute the deferred function to get the next step
+    }
+    return current; // Once no thunks remain, return the final result
+}
+exports.trampoline = trampoline;
+/**
+ * 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
+ */
+function makeTrampoline(fn // A function that returns a trampoline step
+) {
+    // Return a wrapped function that automatically runs the trampoline execution loop
+    return (...args) => trampoline(fn(...args));
+}
+exports.makeTrampoline = makeTrampoline;
+/**
+ * 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).
+ */
+function asyncTrampoline(initial) {
+    return __awaiter(this, void 0, void 0, function* () {
+        let current = yield initial; // Wait for the initial step to resolve if it's a Promise
+        // Keep executing thunks until we reach a non-thunk (final) value
+        while ((0, exports.isTrampolineThunk)(current)) {
+            current = yield current.fn(); // Execute the thunk function (may be async)
+        }
+        // Once the final value is reached, return it
+        return current;
+    });
+}
+exports.asyncTrampoline = asyncTrampoline;
+/**
+ * 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
+ */
+function makeAsyncTrampoline(fn) {
+    // Return a wrapped async function that runs through the async trampoline loop
+    return (...args) => __awaiter(this, void 0, void 0, function* () {
+        return asyncTrampoline(fn(...args));
+    });
+}
+exports.makeAsyncTrampoline = makeAsyncTrampoline;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "directed-graph-typed",
-  "version": "2.0.4",
+  "version": "2.1.0",
   "description": "Directed Graph",
   "main": "dist/index.js",
   "scripts": {
@@ -147,6 +147,6 @@
     "typescript": "^4.9.5"
   },
   "dependencies": {
-    "data-structure-typed": "^2.0.4"
+    "data-structure-typed": "^2.1.0"
   }
 }