avl-tree-typed 2.0.4 → 2.1.0

package/src/interfaces/binary-tree.ts

@@ -1,16 +1,250 @@
 import { BinaryTreeNode } from '../data-structures';
-import type { BinaryTreeDeleteResult, BinaryTreeOptions, BTNRep, NodePredicate } from '../types';
+import type {
+  BinaryTreeDeleteResult,
+  BinaryTreeOptions,
+  BTNRep,
+  DFSOrderPattern,
+  EntryCallback,
+  IterationType,
+  NodeCallback,
+  NodePredicate,
+  OptNodeOrNull,
+  ReduceEntryCallback,
+  ToEntryFn
+} from '../types';
 
-export interface IBinaryTree<K = any, V = any, R = object, MK = any, MV = any, MR = object> {
-  createNode(key: K, value?: BinaryTreeNode['value']): BinaryTreeNode;
+/**
+ * Public, implementation-agnostic binary tree API.
+ * K = key, V = value, R = raw/record used with toEntryFn (optional).
+ * Transforming methods like `map` use method-level generics MK/MV/MR.
+ */
+export interface IBinaryTree<K = any, V = any, R extends object = object> {
+  // ---- state ----
+  readonly size: number;
+  readonly root: BinaryTreeNode<K, V> | null | undefined;
+  readonly isMapMode: boolean;
+  // NOTE: iterationType is mutable on the class; remove readonly here to match
+  iterationType: IterationType;
+  // Extra public state/getters implemented by BinaryTree (useful to callers)
+  readonly NIL: BinaryTreeNode<K, V>;
+  readonly store: Map<K, V | undefined>;
+  readonly toEntryFn?: ToEntryFn<K, V, R>;
+  readonly isDuplicate: boolean;
 
-  createTree(options?: Partial<BinaryTreeOptions<K, V, R>>): IBinaryTree<K, V, R, MK, MV, MR>;
+  // ---- construction / mutation ----
+  _createNode(key: K, value?: BinaryTreeNode<K, V>['value']): BinaryTreeNode<K, V>;
+
+  createTree(options?: Partial<BinaryTreeOptions<K, V, R>>): IBinaryTree<K, V, R>;
 
   add(keyOrNodeOrEntryOrRawElement: BTNRep<K, V, BinaryTreeNode<K, V>>, value?: V, count?: number): boolean;
 
-  addMany(nodes: Iterable<BTNRep<K, V, BinaryTreeNode<K, V>>>, values?: Iterable<V | undefined>): boolean[];
+  // Accept raw R as well (when toEntryFn is configured)
+  addMany(
+    keysNodesEntriesOrRaws: Iterable<
+      K | BinaryTreeNode<K, V> | [K | null | undefined, V | undefined] | null | undefined | R
+    >,
+    values?: Iterable<V | undefined>
+  ): boolean[];
 
+  // Accept BTNRep, predicate, or raw R for deletion
   delete(
-    predicate: R | BTNRep<K, V, BinaryTreeNode<K, V>> | NodePredicate<BinaryTreeNode<K, V>>
+    keyNodeEntryRawOrPredicate: R | BTNRep<K, V, BinaryTreeNode<K, V>> | NodePredicate<BinaryTreeNode<K, V> | null>
   ): BinaryTreeDeleteResult<BinaryTreeNode<K, V>>[];
+
+  clear(): void;
+
+  isEmpty(): boolean;
+
+  // ---- query / read ----
+
+  // Widen `get` to support entry and optional traversal context (matches impl)
+  get(
+    keyNodeEntryOrPredicate: K | BinaryTreeNode<K, V> | [K | null | undefined, V | undefined] | null | undefined,
+    startNode?: K | BinaryTreeNode<K, V> | [K | null | undefined, V | undefined] | null | undefined,
+    iterationType?: IterationType
+  ): V | undefined;
+
+  // `has` also supports node/entry/predicate and optional traversal context
+  has(
+    keyNodeEntryOrPredicate?:
+      | K
+      | BinaryTreeNode<K, V>
+      | [K | null | undefined, V | undefined]
+      | null
+      | undefined
+      | NodePredicate<BinaryTreeNode<K, V> | null>,
+    startNode?: K | BinaryTreeNode<K, V> | [K | null | undefined, V | undefined] | null | undefined,
+    iterationType?: IterationType
+  ): boolean;
+
+  hasValue(value: V): boolean;
+
+  find(predicate: EntryCallback<K, V | undefined, boolean>, thisArg?: unknown): [K, V | undefined] | undefined;
+
+  // ---- iteration ----
+  [Symbol.iterator](): IterableIterator<[K, V | undefined]>;
+
+  entries(): IterableIterator<[K, V | undefined]>;
+
+  keys(): IterableIterator<K>;
+
+  values(): IterableIterator<V | undefined>;
+
+  forEach(callbackfn: EntryCallback<K, V | undefined, void>, thisArg?: unknown): void;
+
+  every(callbackfn: EntryCallback<K, V | undefined, boolean>, thisArg?: unknown): boolean;
+
+  some(callbackfn: EntryCallback<K, V | undefined, boolean>, thisArg?: unknown): boolean;
+
+  reduce<U>(reducer: ReduceEntryCallback<K, V | undefined, U>, initialValue: U): U;
+
+  // ---- node access / extremes ----
+  getNode(
+    keyNodeEntryOrPredicate:
+      | K
+      | BinaryTreeNode<K, V>
+      | [K | null | undefined, V | undefined]
+      | null
+      | undefined
+      | NodePredicate<BinaryTreeNode<K, V> | null>,
+    startNode?: K | BinaryTreeNode<K, V> | [K | null | undefined, V | undefined] | null | undefined,
+    iterationType?: IterationType
+  ): OptNodeOrNull<BinaryTreeNode<K, V>>;
+
+  getLeftMost<C extends NodeCallback<OptNodeOrNull<BinaryTreeNode<K, V>>>>(
+    callback?: C,
+    startNode?: K | BinaryTreeNode<K, V> | [K | null | undefined, V | undefined] | null | undefined,
+    iterationType?: IterationType
+  ): ReturnType<C>;
+
+  getRightMost<C extends NodeCallback<BinaryTreeNode<K, V> | undefined>>(
+    callback?: C,
+    startNode?: K | BinaryTreeNode<K, V> | [K | null | undefined, V | undefined] | null | undefined,
+    iterationType?: IterationType
+  ): ReturnType<C>;
+
+  // ---- traversal ----
+  dfs<C extends NodeCallback<BinaryTreeNode<K, V>>>(
+    callback?: C,
+    pattern?: DFSOrderPattern,
+    onlyOne?: boolean,
+    startNode?: K | BinaryTreeNode<K, V> | [K | null | undefined, V | undefined] | null | undefined,
+    iterationType?: IterationType
+  ): ReturnType<C>[];
+
+  dfs<C extends NodeCallback<BinaryTreeNode<K, V> | null>>(
+    callback?: C,
+    pattern?: DFSOrderPattern,
+    onlyOne?: boolean,
+    startNode?: K | BinaryTreeNode<K, V> | [K | null | undefined, V | undefined] | null | undefined,
+    iterationType?: IterationType,
+    includeNull?: boolean
+  ): ReturnType<C>[];
+
+  bfs<C extends NodeCallback<BinaryTreeNode<K, V>>>(
+    callback?: C,
+    startNode?: K | BinaryTreeNode<K, V> | [K | null | undefined, V | undefined] | null | undefined,
+    iterationType?: IterationType,
+    includeNull?: false
+  ): ReturnType<C>[];
+
+  bfs<C extends NodeCallback<BinaryTreeNode<K, V> | null>>(
+    callback?: C,
+    startNode?: K | BinaryTreeNode<K, V> | [K | null | undefined, V | undefined] | null | undefined,
+    iterationType?: IterationType,
+    includeNull?: true
+  ): ReturnType<C>[];
+
+  morris<C extends NodeCallback<BinaryTreeNode<K, V> | null>>(
+    callback?: C,
+    pattern?: DFSOrderPattern,
+    startNode?: K | BinaryTreeNode<K, V> | [K | null | undefined, V | undefined] | null | undefined
+  ): ReturnType<C>[];
+
+  leaves<C extends NodeCallback<BinaryTreeNode<K, V> | null>>(
+    callback?: C,
+    startNode?: K | BinaryTreeNode<K, V> | [K | null | undefined, V | undefined] | null | undefined,
+    iterationType?: IterationType
+  ): ReturnType<C>[];
+
+  listLevels<C extends NodeCallback<BinaryTreeNode<K, V>>>(
+    callback?: C,
+    startNode?: K | BinaryTreeNode<K, V> | [K | null | undefined, V | undefined] | null | undefined,
+    iterationType?: IterationType,
+    includeNull?: false
+  ): ReturnType<C>[][];
+
+  listLevels<C extends NodeCallback<BinaryTreeNode<K, V> | null>>(
+    callback?: C,
+    startNode?: K | BinaryTreeNode<K, V> | [K | null | undefined, V | undefined] | null | undefined,
+    iterationType?: IterationType,
+    includeNull?: true
+  ): ReturnType<C>[][];
+
+  getPathToRoot<C extends NodeCallback<OptNodeOrNull<BinaryTreeNode<K, V>>>>(
+    beginNode: K | BinaryTreeNode<K, V> | [K | null | undefined, V | undefined] | null | undefined,
+    callback?: C,
+    isReverse?: boolean
+  ): ReturnType<C>[];
+
+  // ---- metrics & validation ----
+  getDepth(
+    dist: K | BinaryTreeNode<K, V> | [K | null | undefined, V | undefined] | null | undefined,
+    startNode?: K | BinaryTreeNode<K, V> | [K | null | undefined, V | undefined] | null | undefined
+  ): number;
+
+  getHeight(
+    startNode?: K | BinaryTreeNode<K, V> | [K | null | undefined, V | undefined] | null | undefined,
+    iterationType?: IterationType
+  ): number;
+
+  getMinHeight(
+    startNode?: K | BinaryTreeNode<K, V> | [K | null | undefined, V | undefined] | null | undefined,
+    iterationType?: IterationType
+  ): number;
+
+  isPerfectlyBalanced(
+    startNode?: K | BinaryTreeNode<K, V> | [K | null | undefined, V | undefined] | null | undefined
+  ): boolean;
+
+  isBST(
+    startNode?: K | BinaryTreeNode<K, V> | [K | null | undefined, V | undefined] | null | undefined,
+    iterationType?: IterationType
+  ): boolean;
+
+  // ---- search helpers ----
+  search<C extends NodeCallback<BinaryTreeNode<K, V> | null>>(
+    keyNodeEntryOrPredicate:
+      | K
+      | BinaryTreeNode<K, V>
+      | [K | null | undefined, V | undefined]
+      | null
+      | undefined
+      | NodePredicate<BinaryTreeNode<K, V> | null>,
+    onlyOne?: boolean,
+    callback?: C,
+    startNode?: K | BinaryTreeNode<K, V> | [K | null | undefined, V | undefined] | null | undefined,
+    iterationType?: IterationType
+  ): ReturnType<C>[];
+
+  // ---- immutable transforms ----
+  clone(): this;
+
+  filter(predicate: EntryCallback<K, V | undefined, boolean>, thisArg?: unknown): this;
+
+  map<MK = K, MV = V, MR extends object = object>(
+    callback: EntryCallback<K, V | undefined, [MK, MV]>,
+    options?: Partial<BinaryTreeOptions<MK, MV, MR>>,
+    thisArg?: unknown
+  ): IBinaryTree<MK, MV, MR>;
+
+  // ---- bulk / interop ----
+  merge(anotherTree: IBinaryTree<K, V, R>): void;
+
+  refill(
+    keysNodesEntriesOrRaws: Iterable<
+      K | BinaryTreeNode<K, V> | [K | null | undefined, V | undefined] | null | undefined | R
+    >,
+    values?: Iterable<V | undefined>
+  ): void;
 }

package/src/interfaces/graph.ts

@@ -1,7 +1,44 @@
 import { VertexKey } from '../types';
 
 export interface IGraph<V, E, VO, EO> {
+  // Vertex factories
   createVertex(key: VertexKey, value?: V): VO;
 
+  // Edge factories
   createEdge(srcOrV1: VertexKey, destOrV2: VertexKey, weight?: number, value?: E): EO;
+
+  // Core vertex ops
+  getVertex(vertexKey: VertexKey): VO | undefined;
+
+  hasVertex(vertexOrKey: VO | VertexKey): boolean;
+
+  addVertex(vertex: VO): boolean;
+
+  addVertex(key: VertexKey, value?: V): boolean;
+
+  deleteVertex(vertexOrKey: VO | VertexKey): boolean;
+
+  // Core edge ops
+  deleteEdge(edge: EO): EO | undefined;
+
+  getEdge(srcOrKey: VO | VertexKey, destOrKey: VO | VertexKey): EO | undefined;
+
+  degreeOf(vertexOrKey: VO | VertexKey): number;
+
+  edgeSet(): EO[];
+
+  edgesOf(vertexOrKey: VO | VertexKey): EO[];
+
+  getNeighbors(vertexOrKey: VO | VertexKey): VO[];
+
+  getEndsOfEdge(edge: EO): [VO, VO] | undefined;
+
+  // Container-like ops
+  isEmpty(): boolean;
+
+  clear(): void;
+
+  clone(): this;
+
+  filter(...args: any[]): this;
 }

package/src/types/data-structures/base/base.ts

@@ -11,12 +11,12 @@ export type ReduceEntryCallback<K, V, R> = (
   original: IterableEntryBase<K, V>
 ) => R;
 
-export type ReduceElementCallback<E, R, RT = E> = (
-  accumulator: RT,
-  element: E,
+export type ReduceElementCallback<E, R, U = E> = (
+  accumulator: U,
+  value: E,
   index: number,
-  original: IterableElementBase<E, R>
-) => RT;
+  self: IterableElementBase<E, R>
+) => U;
 
 export type ReduceLinearCallback<E, RT = E> = (
   accumulator: RT,

package/src/types/data-structures/graph/abstract-graph.ts

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

package/src/types/utils/utils.ts

@@ -1,14 +1,11 @@
-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 {
@@ -27,3 +24,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, Trampoline, TrampolineThunk } 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,154 @@ 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));
+  };
+}