styles: Simplify trampoline to a traditional approach. release: Publish version 2.0.2.

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.0](https://github.com/zrwusa/data-structure-typed/compare/v1.51.5...main) (upcoming)
+## [v2.0.1](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.0",
+  "version": "2.0.1",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "data-structure-typed",
-      "version": "2.0.0",
+      "version": "2.0.1",
       "license": "MIT",
       "devDependencies": {
         "@eslint/compat": "^1.2.2",

package.json

@@ -1,6 +1,6 @@
 {
   "name": "data-structure-typed",
-  "version": "2.0.1",
+  "version": "2.0.2",
   "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,
+  RBTNColor, Thunk,
   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 = trampoline((cur: BinaryTreeNode<K, V>): BinaryTreeNode<K, V> => {
+      const dfs = (cur: BinaryTreeNode<K, V>): BinaryTreeNode<K, V> | Thunk<BinaryTreeNode<K, V>> => {
         if (!this.isRealNode(cur.left)) return cur;
-        return dfs.cont(cur.left);
-      });
+        return () => dfs(cur.left!);
+      };
 
-      return callback(dfs(startNode));
+      return callback(trampoline(() => dfs(startNode)));
     }
   }
 
@@ -1352,13 +1352,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 = trampoline((cur: BinaryTreeNode<K, V>) => {
+      const dfs = (cur: BinaryTreeNode<K, V>) => {
         if (!this.isRealNode(cur.right)) return cur;
-        return dfs.cont(cur.right);
-      });
+        return () => dfs(cur.right!) as Thunk<BinaryTreeNode<K, V>>;
+      };
 
-      return callback(dfs(startNode));
+      return callback(trampoline(() => dfs(startNode)));
     }
   }
 

src/data-structures/linked-list/singly-linked-list.ts

@@ -38,6 +38,72 @@ export class SinglyLinkedListNode<E = any> extends LinkedListNode<E> {
  * 4. High Efficiency in Insertion and Deletion: Adding or removing elements in a linked list does not require moving other elements, making these operations more efficient than in arrays.
  * Caution: Although our linked list classes provide methods such as at, setAt, addAt, and indexOf that are based on array indices, their time complexity, like that of the native Array.lastIndexOf, is 𝑂(𝑛). If you need to use these methods frequently, you might want to consider other data structures, such as Deque or Queue (designed for random access). Similarly, since the native Array.shift method has a time complexity of 𝑂(𝑛), using an array to simulate a queue can be inefficient. In such cases, you should use Queue or Deque, as these data structures leverage deferred array rearrangement, effectively reducing the average time complexity to 𝑂(1).
  *
+ * @example
+ * // implementation of a basic text editor
+ *     class TextEditor {
+ *       private content: SinglyLinkedList<string>;
+ *       private cursorIndex: number;
+ *       private undoStack: Stack<{ operation: string; data?: any }>;
+ *
+ *       constructor() {
+ *         this.content = new SinglyLinkedList<string>();
+ *         this.cursorIndex = 0; // Cursor starts at the beginning
+ *         this.undoStack = new Stack<{ operation: string; data?: any }>(); // Stack to keep track of operations for undo
+ *       }
+ *
+ *       insert(char: string) {
+ *         this.content.addAt(this.cursorIndex, char);
+ *         this.cursorIndex++;
+ *         this.undoStack.push({ operation: 'insert', data: { index: this.cursorIndex - 1 } });
+ *       }
+ *
+ *       delete() {
+ *         if (this.cursorIndex === 0) return; // Nothing to delete
+ *         const deleted = this.content.deleteAt(this.cursorIndex - 1);
+ *         this.cursorIndex--;
+ *         this.undoStack.push({ operation: 'delete', data: { index: this.cursorIndex, char: deleted } });
+ *       }
+ *
+ *       moveCursor(index: number) {
+ *         this.cursorIndex = Math.max(0, Math.min(index, this.content.length));
+ *       }
+ *
+ *       undo() {
+ *         if (this.undoStack.size === 0) return; // No operations to undo
+ *         const lastAction = this.undoStack.pop();
+ *
+ *         if (lastAction!.operation === 'insert') {
+ *           this.content.deleteAt(lastAction!.data.index);
+ *           this.cursorIndex = lastAction!.data.index;
+ *         } else if (lastAction!.operation === 'delete') {
+ *           this.content.addAt(lastAction!.data.index, lastAction!.data.char);
+ *           this.cursorIndex = lastAction!.data.index + 1;
+ *         }
+ *       }
+ *
+ *       getText(): string {
+ *         return [...this.content].join('');
+ *       }
+ *     }
+ *
+ *     // Example Usage
+ *     const editor = new TextEditor();
+ *     editor.insert('H');
+ *     editor.insert('e');
+ *     editor.insert('l');
+ *     editor.insert('l');
+ *     editor.insert('o');
+ *     console.log(editor.getText()); // 'Hello' // Output: "Hello"
+ *
+ *     editor.delete();
+ *     console.log(editor.getText()); // 'Hell' // Output: "Hell"
+ *
+ *     editor.undo();
+ *     console.log(editor.getText()); // 'Hello' // Output: "Hello"
+ *
+ *     editor.moveCursor(1);
+ *     editor.insert('a');
+ *     console.log(editor.getText()); // 'Haello'
  */
 export class SinglyLinkedList<E = any, R = any> extends LinearLinkedBase<E, R, SinglyLinkedListNode<E>> {
   constructor(

src/data-structures/stack/stack.ts

@@ -15,6 +15,127 @@ import { IterableElementBase } from '../base';
  * 4. Function Calls: In most modern programming languages, the records of function calls are managed through a stack. When a function is called, its record (including parameters, local variables, and return address) is 'pushed' into the stack. When the function returns, its record is 'popped' from the stack.
  * 5. Expression Evaluation: Used for the evaluation of arithmetic or logical expressions, especially when dealing with parenthesis matching and operator precedence.
  * 6. Backtracking Algorithms: In problems where multiple branches need to be explored but only one branch can be explored at a time, stacks can be used to save the state at each branching point.
+ * @example
+ * // Balanced Parentheses or Brackets
+ *     type ValidCharacters = ')' | '(' | ']' | '[' | '}' | '{';
+ *
+ *     const stack = new Stack<string>();
+ *     const input: ValidCharacters[] = '[({})]'.split('') as ValidCharacters[];
+ *     const matches: { [key in ValidCharacters]?: ValidCharacters } = { ')': '(', ']': '[', '}': '{' };
+ *     for (const char of input) {
+ *       if ('([{'.includes(char)) {
+ *         stack.push(char);
+ *       } else if (')]}'.includes(char)) {
+ *         if (stack.pop() !== matches[char]) {
+ *           fail('Parentheses are not balanced');
+ *         }
+ *       }
+ *     }
+ *     console.log(stack.isEmpty()); // true
+ * @example
+ * // Expression Evaluation and Conversion
+ *     const stack = new Stack<number>();
+ *     const expression = [5, 3, '+']; // Equivalent to 5 + 3
+ *     expression.forEach(token => {
+ *       if (typeof token === 'number') {
+ *         stack.push(token);
+ *       } else {
+ *         const b = stack.pop()!;
+ *         const a = stack.pop()!;
+ *         stack.push(token === '+' ? a + b : 0); // Only handling '+' here
+ *       }
+ *     });
+ *     console.log(stack.pop()); // 8
+ * @example
+ * // Depth-First Search (DFS)
+ *     const stack = new Stack<number>();
+ *     const graph: { [key in number]: number[] } = { 1: [2, 3], 2: [4], 3: [5], 4: [], 5: [] };
+ *     const visited: number[] = [];
+ *     stack.push(1);
+ *     while (!stack.isEmpty()) {
+ *       const node = stack.pop()!;
+ *       if (!visited.includes(node)) {
+ *         visited.push(node);
+ *         graph[node].forEach(neighbor => stack.push(neighbor));
+ *       }
+ *     }
+ *     console.log(visited); // [1, 3, 5, 2, 4]
+ * @example
+ * // Backtracking Algorithms
+ *     const stack = new Stack<[number, number]>();
+ *     const maze = [
+ *       ['S', ' ', 'X'],
+ *       ['X', ' ', 'X'],
+ *       [' ', ' ', 'E']
+ *     ];
+ *     const start: [number, number] = [0, 0];
+ *     const end = [2, 2];
+ *     const directions = [
+ *       [0, 1], // To the right
+ *       [1, 0], // down
+ *       [0, -1], // left
+ *       [-1, 0] // up
+ *     ];
+ *
+ *     const visited = new Set<string>(); // Used to record visited nodes
+ *     stack.push(start);
+ *     const path: number[][] = [];
+ *
+ *     while (!stack.isEmpty()) {
+ *       const [x, y] = stack.pop()!;
+ *       if (visited.has(`${x},${y}`)) continue; // Skip already visited nodes
+ *       visited.add(`${x},${y}`);
+ *
+ *       path.push([x, y]);
+ *
+ *       if (x === end[0] && y === end[1]) {
+ *         break; // Find the end point and exit
+ *       }
+ *
+ *       for (const [dx, dy] of directions) {
+ *         const nx = x + dx;
+ *         const ny = y + dy;
+ *         if (
+ *           maze[nx]?.[ny] === ' ' || // feasible path
+ *           maze[nx]?.[ny] === 'E' // destination
+ *         ) {
+ *           stack.push([nx, ny]);
+ *         }
+ *       }
+ *     }
+ *
+ *     expect(path).toContainEqual(end);
+ * @example
+ * // Function Call Stack
+ *     const functionStack = new Stack<string>();
+ *     functionStack.push('main');
+ *     functionStack.push('foo');
+ *     functionStack.push('bar');
+ *     console.log(functionStack.pop()); // 'bar'
+ *     console.log(functionStack.pop()); // 'foo'
+ *     console.log(functionStack.pop()); // 'main'
+ * @example
+ * // Simplify File Paths
+ *     const stack = new Stack<string>();
+ *     const path = '/a/./b/../../c';
+ *     path.split('/').forEach(segment => {
+ *       if (segment === '..') stack.pop();
+ *       else if (segment && segment !== '.') stack.push(segment);
+ *     });
+ *     console.log(stack.elements.join('/')); // 'c'
+ * @example
+ * // Stock Span Problem
+ *     const stack = new Stack<number>();
+ *     const prices = [100, 80, 60, 70, 60, 75, 85];
+ *     const spans: number[] = [];
+ *     prices.forEach((price, i) => {
+ *       while (!stack.isEmpty() && prices[stack.peek()!] <= price) {
+ *         stack.pop();
+ *       }
+ *       spans.push(stack.isEmpty() ? i + 1 : i - stack.peek()!);
+ *       stack.push(i);
+ *     });
+ *     console.log(spans); // [1, 1, 1, 2, 1, 4, 6]
  */
 export class Stack<E = any, R = any> extends IterableElementBase<E, R> {
   constructor(elements: Iterable<E> | Iterable<R> = [], options?: StackOptions<E, R>) {

src/types/utils/utils.ts

@@ -1,9 +1,4 @@
-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 Thunk<T> = () => T | Thunk<T>;
 
 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, ToThunkFn, TrlAsyncFn, TrlFn } from '../types';
+import type { Comparable, ComparablePrimitive, Thunk } from '../types';
 
 /**
  * The function generates a random UUID (Universally Unique Identifier) in TypeScript.
@@ -47,90 +47,18 @@ 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;
-};
+export function isThunk<T>(result: T | Thunk<T>): result is Thunk<T> {
+  return typeof result === 'function';
+}
 
-/**
- * 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 }
-  );
-};
+export function trampoline<T>(thunk: Thunk<T>): T {
+  let result: T | Thunk<T> = thunk;
+  while (isThunk(result)) {
+    result = result();
+  }
+  return result;
+}
 
 /**
  * The function `getMSB` returns the most significant bit of a given number.

test/unit/data-structures/linked-list/singly-linked-list.test.ts

@@ -665,20 +665,12 @@ describe('classic uses', () => {
         this.undoStack = new Stack<{ operation: string; data?: any }>(); // Stack to keep track of operations for undo
       }
 
-      /**
-       * Inserts a character at the current cursor position.
-       * @param char - The character to insert.
-       */
       insert(char: string) {
         this.content.addAt(this.cursorIndex, char);
         this.cursorIndex++;
         this.undoStack.push({ operation: 'insert', data: { index: this.cursorIndex - 1 } });
       }
 
-      /**
-       * Deletes the character at the current cursor position.
-       * If the cursor is at the end, deletes the character before the cursor.
-       */
       delete() {
         if (this.cursorIndex === 0) return; // Nothing to delete
         const deleted = this.content.deleteAt(this.cursorIndex - 1);
@@ -686,17 +678,10 @@ describe('classic uses', () => {
         this.undoStack.push({ operation: 'delete', data: { index: this.cursorIndex, char: deleted } });
       }
 
-      /**
-       * Moves the cursor to a specific position.
-       * @param index - The position to move the cursor to.
-       */
       moveCursor(index: number) {
         this.cursorIndex = Math.max(0, Math.min(index, this.content.length));
       }
 
-      /**
-       * Undoes the last operation (insert or delete).
-       */
       undo() {
         if (this.undoStack.size === 0) return; // No operations to undo
         const lastAction = this.undoStack.pop();
@@ -710,10 +695,6 @@ describe('classic uses', () => {
         }
       }
 
-      /**
-       * Displays the current text content of the editor.
-       * @returns The concatenated string representation of the text.
-       */
       getText(): string {
         return [...this.content].join('');
       }

test/unit/utils/utils.test.ts

@@ -1,11 +1,11 @@
+import { isComparable, trampoline } from '../../../src';
+
 describe('isNaN', () => {
   it('should isNaN', function () {
     expect(isNaN('string' as unknown as number)).toBe(true);
   });
 });
 
-import { isComparable } from '../../../src';
-
 describe('isComparable', () => {
   describe('primitive types', () => {
     it('numbers should be comparable', () => {
@@ -172,3 +172,38 @@ 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);
+  });
+});