release: v2.0.3

CHANGELOG.md

@@ -8,7 +8,7 @@ All notable changes to this project will be documented in this file.
 - [Semantic Versioning](https://semver.org/spec/v2.0.0.html)
 - [`auto-changelog`](https://github.com/CookPete/auto-changelog)
 
-## [v2.0.1](https://github.com/zrwusa/data-structure-typed/compare/v1.51.5...main) (upcoming)
+## [v2.0.2](https://github.com/zrwusa/data-structure-typed/compare/v1.51.5...main) (upcoming)
 
 ### Changes
 

package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "data-structure-typed",
-  "version": "2.0.1",
+  "version": "2.0.2",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "data-structure-typed",
-      "version": "2.0.1",
+      "version": "2.0.2",
       "license": "MIT",
       "devDependencies": {
         "@eslint/compat": "^1.2.2",

package.json

@@ -1,6 +1,6 @@
 {
   "name": "data-structure-typed",
-  "version": "2.0.2",
+  "version": "2.0.3",
   "description": "Standard data structure",
   "main": "dist/cjs/index.js",
   "module": "dist/esm/index.js",

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

@@ -20,7 +20,7 @@ import type {
   NodeDisplayLayout,
   NodePredicate,
   OptNodeOrNull,
-  RBTNColor, Thunk,
+  RBTNColor,
   ToEntryFn
 } from '../../types';
 import { IBinaryTree } from '../../interfaces';
@@ -1304,12 +1304,12 @@ export class BinaryTree<K = any, V = any, R = object, MK = any, MV = any, MR = o
       return callback(dfs(startNode));
     } else {
       // Indirect implementation of iteration using tail recursion optimization
-      const dfs = (cur: BinaryTreeNode<K, V>): BinaryTreeNode<K, V> | Thunk<BinaryTreeNode<K, V>> => {
+      const dfs = trampoline((cur: BinaryTreeNode<K, V>): BinaryTreeNode<K, V> => {
         if (!this.isRealNode(cur.left)) return cur;
-        return () => dfs(cur.left!);
-      };
+        return dfs.cont(cur.left);
+      });
 
-      return callback(trampoline(() => dfs(startNode)));
+      return callback(dfs(startNode));
     }
   }
 
@@ -1352,12 +1352,13 @@ export class BinaryTree<K = any, V = any, R = object, MK = any, MV = any, MR = o
 
       return callback(dfs(startNode));
     } else {
-      const dfs = (cur: BinaryTreeNode<K, V>) => {
+      // Indirect implementation of iteration using tail recursion optimization
+      const dfs = trampoline((cur: BinaryTreeNode<K, V>) => {
         if (!this.isRealNode(cur.right)) return cur;
-        return () => dfs(cur.right!) as Thunk<BinaryTreeNode<K, V>>;
-      };
+        return dfs.cont(cur.right);
+      });
 
-      return callback(trampoline(() => dfs(startNode)));
+      return callback(dfs(startNode));
     }
   }
 

src/types/utils/utils.ts

@@ -1,4 +1,9 @@
-export type Thunk<T> = () => T | Thunk<T>;
+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;
 

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 } from '../types';
+import type { Comparable, ComparablePrimitive, Thunk, ToThunkFn, TrlAsyncFn, TrlFn } from '../types';
 
 /**
  * The function generates a random UUID (Universally Unique Identifier) in TypeScript.
@@ -47,18 +47,90 @@ export const arrayRemove = function <T>(array: T[], predicate: (item: T, index:
   return result;
 };
 
+export const THUNK_SYMBOL = Symbol('thunk');
 
-export function isThunk<T>(result: T | Thunk<T>): result is Thunk<T> {
-  return typeof result === 'function';
-}
+/**
+ * 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;
+};
 
-export function trampoline<T>(thunk: Thunk<T>): T {
-  let result: T | Thunk<T> = thunk;
-  while (isThunk(result)) {
-    result = result();
-  }
-  return result;
-}
+/**
+ * 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.

test/unit/data-structures/queue/queue.test.ts

@@ -603,7 +603,7 @@ describe('classic uses', () => {
     let maxSum = 0;
     let currentSum = 0;
 
-    nums.forEach((num, i) => {
+    nums.forEach((num) => {
       queue.push(num);
       currentSum += num;
 

test/unit/utils/utils.test.ts

@@ -1,4 +1,4 @@
-import { isComparable, trampoline } from '../../../src';
+import { isComparable } from '../../../src';
 
 describe('isNaN', () => {
   it('should isNaN', function () {
@@ -173,37 +173,3 @@ describe('isComparable', () => {
   });
 });
 
-describe('Factorial Performance Tests', () => {
-  const depth = 5000;
-  let arr: number[];
-
-  const recurseTrampoline = (n: number, arr: number[], acc = 1): (() => any) | number => {
-    if (n === 0) return acc;
-    arr.unshift(1);
-    return () => recurseTrampoline(n - 1, arr, acc);
-  };
-
-  const recurse = (n: number, arr: number[], acc = 1): number => {
-    if (n === 0) return acc;
-    arr.unshift(1);
-    return recurse(n - 1, arr, acc);
-  };
-
-  beforeEach(() => {
-    arr = new Array(depth).fill(0);
-  });
-
-  it('should calculate recursive function using trampoline without stack overflow', () => {
-    const result = trampoline(() => recurseTrampoline(depth, arr));
-    expect(result).toBe(1);
-    expect(arr.length).toBe(depth + depth);
-  });
-
-  it('should calculate recursive directly and possibly stack overflow', () => {
-    console.time('recurse');
-    const result = recurse(depth, arr);
-    console.timeEnd('recurse');
-    expect(result).toBe(1);
-    expect(arr.length).toBe(depth + depth);
-  });
-});