bst-typed 2.0.4 → 2.0.5

package/dist/data-structures/binary-tree/binary-tree.js

@@ -1092,18 +1092,20 @@ class BinaryTree extends base_1.IterableEntryBase {
             return callback(startNode);
         if (iterationType === 'RECURSIVE') {
             const dfs = (cur) => {
-                if (!this.isRealNode(cur.left))
+                const { left } = cur;
+                if (!this.isRealNode(left))
                     return cur;
-                return dfs(cur.left);
+                return dfs(left);
             };
             return callback(dfs(startNode));
         }
         else {
             // Indirect implementation of iteration using tail recursion optimization
-            const dfs = (0, utils_1.trampoline)((cur) => {
-                if (!this.isRealNode(cur.left))
+            const dfs = (0, utils_1.makeTrampoline)((cur) => {
+                const { left } = cur;
+                if (!this.isRealNode(left))
                     return cur;
-                return dfs.cont(cur.left);
+                return (0, utils_1.makeTrampolineThunk)(() => dfs(left));
             });
             return callback(dfs(startNode));
         }
@@ -1138,18 +1140,20 @@ class BinaryTree extends base_1.IterableEntryBase {
             return callback(startNode);
         if (iterationType === 'RECURSIVE') {
             const dfs = (cur) => {
-                if (!this.isRealNode(cur.right))
+                const { right } = cur;
+                if (!this.isRealNode(right))
                     return cur;
-                return dfs(cur.right);
+                return dfs(right);
             };
             return callback(dfs(startNode));
         }
         else {
             // Indirect implementation of iteration using tail recursion optimization
-            const dfs = (0, utils_1.trampoline)((cur) => {
-                if (!this.isRealNode(cur.right))
+            const dfs = (0, utils_1.makeTrampoline)((cur) => {
+                const { right } = cur;
+                if (!this.isRealNode(right))
                     return cur;
-                return dfs.cont(cur.right);
+                return (0, utils_1.makeTrampolineThunk)(() => dfs(right));
             });
             return callback(dfs(startNode));
         }

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

@@ -1,9 +1,3 @@
-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;
@@ -20,3 +14,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, TrampolineThunk, Trampoline } 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,149 @@ 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": "bst-typed",
-  "version": "2.0.4",
+  "version": "2.0.5",
   "description": "Binary Search Tree",
   "main": "dist/index.js",
   "scripts": {
@@ -144,6 +144,6 @@
     "typescript": "^4.9.5"
   },
   "dependencies": {
-    "data-structure-typed": "^2.0.4"
+    "data-structure-typed": "^2.0.5"
   }
 }

package/src/data-structures/binary-tree/binary-tree.ts

@@ -21,10 +21,11 @@ import type {
   NodePredicate,
   OptNodeOrNull,
   RBTNColor,
-  ToEntryFn
+  ToEntryFn,
+  Trampoline
 } from '../../types';
 import { IBinaryTree } from '../../interfaces';
-import { isComparable, trampoline } from '../../utils';
+import { isComparable, makeTrampoline, makeTrampolineThunk } from '../../utils';
 import { Queue } from '../queue';
 import { IterableEntryBase } from '../base';
 import { DFSOperation, Range } from '../../common';
@@ -1294,19 +1295,20 @@ export class BinaryTree<K = any, V = any, R = object, MK = any, MV = any, MR = o
     startNode = this.ensureNode(startNode);
 
     if (!this.isRealNode(startNode)) return callback(startNode);
-
     if (iterationType === 'RECURSIVE') {
       const dfs = (cur: BinaryTreeNode<K, V>): BinaryTreeNode<K, V> => {
-        if (!this.isRealNode(cur.left)) return cur;
-        return dfs(cur.left);
+        const { left } = cur;
+        if (!this.isRealNode(left)) return cur;
+        return dfs(left);
       };
 
       return callback(dfs(startNode));
     } else {
       // Indirect implementation of iteration using tail recursion optimization
-      const dfs = trampoline((cur: BinaryTreeNode<K, V>): BinaryTreeNode<K, V> => {
-        if (!this.isRealNode(cur.left)) return cur;
-        return dfs.cont(cur.left);
+      const dfs = makeTrampoline((cur: BinaryTreeNode<K, V>): Trampoline<BinaryTreeNode<K, V>> => {
+        const { left } = cur;
+        if (!this.isRealNode(left)) return cur;
+        return makeTrampolineThunk(() => dfs(left));
       });
 
       return callback(dfs(startNode));
@@ -1346,16 +1348,19 @@ export class BinaryTree<K = any, V = any, R = object, MK = any, MV = any, MR = o
 
     if (iterationType === 'RECURSIVE') {
       const dfs = (cur: BinaryTreeNode<K, V>): BinaryTreeNode<K, V> => {
-        if (!this.isRealNode(cur.right)) return cur;
-        return dfs(cur.right);
+        const { right } = cur;
+        if (!this.isRealNode(right)) return cur;
+        return dfs(right);
       };
 
       return callback(dfs(startNode));
     } else {
       // Indirect implementation of iteration using tail recursion optimization
-      const dfs = trampoline((cur: BinaryTreeNode<K, V>) => {
-        if (!this.isRealNode(cur.right)) return cur;
-        return dfs.cont(cur.right);
+
+      const dfs = makeTrampoline((cur: BinaryTreeNode<K, V>): Trampoline<BinaryTreeNode<K, V>> => {
+        const { right } = cur;
+        if (!this.isRealNode(right)) return cur;
+        return makeTrampolineThunk(() => dfs(right));
       });
 
       return callback(dfs(startNode));

package/src/types/utils/utils.ts

@@ -1,8 +1,3 @@
-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;
@@ -27,3 +22,10 @@ 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/src/utils/utils.ts

@@ -5,7 +5,7 @@
  * @copyright Copyright (c) 2022 Pablo Zeng <zrwusa@gmail.com>
  * @license MIT License
  */
-import type { Comparable, ComparablePrimitive, Thunk, ToThunkFn, TrlAsyncFn, TrlFn } from '../types';
+import type { Comparable, ComparablePrimitive, TrampolineThunk, Trampoline } from '../types';
 
 /**
  * The function generates a random UUID (Universally Unique Identifier) in TypeScript.
@@ -47,91 +47,6 @@ export const arrayRemove = function <T>(array: T[], predicate: (item: T, index:
   return result;
 };
 
-export const 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`.
- */
-export const isThunk = (fnOrValue: any) => {
-  return typeof fnOrValue === 'function' && fnOrValue.__THUNK__ === THUNK_SYMBOL;
-};
-
-/**
- * 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 const toThunk = (fn: ToThunkFn): Thunk => {
-  const thunk = () => fn();
-  thunk.__THUNK__ = THUNK_SYMBOL;
-  return 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 const trampoline = (fn: TrlFn) => {
-  const cont = (...args: [...Parameters<TrlFn>]): ReturnType<TrlFn> => toThunk(() => fn(...args));
-
-  return Object.assign(
-    (...args: [...Parameters<TrlFn>]) => {
-      let result = fn(...args);
-
-      while (isThunk(result) && typeof result === 'function') {
-        result = result();
-      }
-
-      return result;
-    },
-    { cont }
-  );
-};
-
-/**
- * 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 const trampolineAsync = (fn: TrlAsyncFn) => {
-  const cont = (...args: [...Parameters<TrlAsyncFn>]): ReturnType<TrlAsyncFn> => toThunk(() => fn(...args));
-
-  return Object.assign(
-    async (...args: [...Parameters<TrlAsyncFn>]) => {
-      let result = await fn(...args);
-
-      while (isThunk(result) && typeof result === 'function') {
-        result = await result();
-      }
-
-      return result;
-    },
-    { cont }
-  );
-};
-
 /**
  * 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
@@ -282,3 +197,159 @@ export function isComparable(value: unknown, isForceObjectComparable = false): v
   if (comparableValue === null || comparableValue === undefined) return false;
   return isPrimitiveComparable(comparableValue);
 }
+
+/**
+ * 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 const makeTrampolineThunk = <T>(
+  computation: () => Trampoline<T>
+): TrampolineThunk<T> => ({
+  isThunk: true, // Marker indicating this is a thunk
+  fn: computation // The deferred computation function
+});
+
+/**
+ * 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 const isTrampolineThunk = <T>(
+  value: Trampoline<T>
+): value is TrampolineThunk<T> =>
+  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
+
+/**
+ * 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 function trampoline<T>(initial: Trampoline<T>): T {
+  let current = initial; // Start with the initial trampoline value
+  while (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
+}
+
+/**
+ * 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 function makeTrampoline<Args extends any[], Result>(
+  fn: (...args: Args) => Trampoline<Result> // A function that returns a trampoline step
+): (...args: Args) => Result {
+  // Return a wrapped function that automatically runs the trampoline execution loop
+  return (...args: Args) => trampoline(fn(...args));
+}
+
+/**
+ * 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 async function asyncTrampoline<T>(
+  initial: Trampoline<T> | Promise<Trampoline<T>>
+): Promise<T> {
+  let current = await 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 (isTrampolineThunk(current)) {
+    current = await current.fn(); // Execute the thunk function (may be async)
+  }
+
+  // Once the final value is reached, return it
+  return current;
+}
+
+/**
+ * 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 function makeAsyncTrampoline<Args extends any[], Result>(
+  fn: (...args: Args) => Trampoline<Result> | Promise<Trampoline<Result>>
+): (...args: Args) => Promise<Result> {
+  // Return a wrapped async function that runs through the async trampoline loop
+  return async (...args: Args): Promise<Result> => {
+    return asyncTrampoline(fn(...args));
+  };
+}