ts-data-forge
Version:
[](https://www.npmjs.com/package/ts-data-forge) [](https://www.npmjs.com/package/ts-data-forge) [
* behavior.
*
* This interface defines a mutable stack data structure where elements are
* added to and removed from the top, following the Last-In, First-Out
* principle. The implementation uses a dynamic array for optimal performance,
* providing O(1) operations for both push and pop operations.
*
* **LIFO Behavior:**
*
* - **push**: Adds elements to the top of the stack
* - **pop**: Removes and returns elements from the top of the stack
* - The last element added is the first element to be removed
*
* **Performance Characteristics:**
*
* - Push: O(1) amortized (O(n) when buffer needs resizing)
* - Pop: O(1) always
* - Size/isEmpty: O(1) always
* - Memory efficient with automatic garbage collection of removed elements
*
* **Use Cases:**
*
* - Function call management and recursion
* - Undo/redo functionality
* - Expression evaluation and parsing
* - Depth-first search algorithms
* - Backtracking algorithms
* - Browser history management
*
* @template T The type of elements stored in the stack.
*/
export type Stack<T> = Readonly<{
/**
* Checks if the stack is empty.
*
* @example
*
* ```ts
* const stack = createStack<string>();
*
* assert.isTrue(stack.isEmpty);
*
* assert.isTrue(stack.size === 0);
*
* stack.push('first');
*
* // eslint-disable-next-line unicorn/prefer-single-call
* stack.push('second');
*
* assert.isFalse(stack.isEmpty);
*
* assert.isTrue(stack.size === 2);
*
* assert.deepStrictEqual(stack.pop(), Optional.some('second'));
*
* assert.deepStrictEqual(stack.pop(), Optional.some('first'));
*
* assert.deepStrictEqual(stack.pop(), Optional.none);
*
* const seededStack = createStack([10, 20, 30]);
*
* assert.isTrue(seededStack.size === 3);
*
* assert.deepStrictEqual(seededStack.pop(), Optional.some(30));
* ```
*/
isEmpty: boolean;
/**
* The number of elements in the stack.
*
* @example
*
* ```ts
* const stack = createStack<string>();
*
* assert.isTrue(stack.isEmpty);
*
* assert.isTrue(stack.size === 0);
*
* stack.push('first');
*
* // eslint-disable-next-line unicorn/prefer-single-call
* stack.push('second');
*
* assert.isFalse(stack.isEmpty);
*
* assert.isTrue(stack.size === 2);
*
* assert.deepStrictEqual(stack.pop(), Optional.some('second'));
*
* assert.deepStrictEqual(stack.pop(), Optional.some('first'));
*
* assert.deepStrictEqual(stack.pop(), Optional.none);
*
* const seededStack = createStack([10, 20, 30]);
*
* assert.isTrue(seededStack.size === 3);
*
* assert.deepStrictEqual(seededStack.pop(), Optional.some(30));
* ```
*/
size: SizeType.Arr;
/**
* Removes and returns the element at the top of the stack.
*
* @example
*
* ```ts
* const stack = createStack<string>();
*
* assert.isTrue(stack.isEmpty);
*
* assert.isTrue(stack.size === 0);
*
* stack.push('first');
*
* // eslint-disable-next-line unicorn/prefer-single-call
* stack.push('second');
*
* assert.isFalse(stack.isEmpty);
*
* assert.isTrue(stack.size === 2);
*
* assert.deepStrictEqual(stack.pop(), Optional.some('second'));
*
* assert.deepStrictEqual(stack.pop(), Optional.some('first'));
*
* assert.deepStrictEqual(stack.pop(), Optional.none);
*
* const seededStack = createStack([10, 20, 30]);
*
* assert.isTrue(seededStack.size === 3);
*
* assert.deepStrictEqual(seededStack.pop(), Optional.some(30));
* ```
*
* @returns The element at the top of the stack, or `Optional.none` if the
* stack is empty.
*/
pop: () => Optional<T>;
/**
* Adds an element to the top of the stack.
*
* @example
*
* ```ts
* const stack = createStack<string>();
*
* assert.isTrue(stack.isEmpty);
*
* assert.isTrue(stack.size === 0);
*
* stack.push('first');
*
* // eslint-disable-next-line unicorn/prefer-single-call
* stack.push('second');
*
* assert.isFalse(stack.isEmpty);
*
* assert.isTrue(stack.size === 2);
*
* assert.deepStrictEqual(stack.pop(), Optional.some('second'));
*
* assert.deepStrictEqual(stack.pop(), Optional.some('first'));
*
* assert.deepStrictEqual(stack.pop(), Optional.none);
*
* const seededStack = createStack([10, 20, 30]);
*
* assert.isTrue(seededStack.size === 3);
*
* assert.deepStrictEqual(seededStack.pop(), Optional.some(30));
* ```
*
* @param value The element to add.
*/
push: (value: T) => void;
}>;
/**
* Creates a new Stack instance with LIFO (Last-In, First-Out) behavior using a
* high-performance dynamic array.
*
* This factory function creates an optimized stack implementation that
* maintains excellent performance characteristics for both push and pop
* operations. The underlying dynamic array automatically resizes to accommodate
* growing workloads while providing predictable O(1) operations.
*
* **Implementation Features:**
*
* - **O(1) push operations** (amortized - occasionally O(n) when resizing)
* - **O(1) pop operations** (always)
* - **Automatic buffer resizing** - starts at 8 elements, doubles when full
* - **Memory efficient** - garbage collects removed elements immediately
* - **Dynamic array design** - eliminates need for complex memory management
*
* **Performance Benefits:**
*
* - No array shifting required for stack operations
* - Minimal memory allocation overhead
* - Predictable performance under high load
* - Efficient memory usage with automatic cleanup
*
* @example
*
* ```ts
* const stack = createStack<string>();
*
* assert.isTrue(stack.isEmpty);
*
* assert.isTrue(stack.size === 0);
*
* stack.push('first');
*
* // eslint-disable-next-line unicorn/prefer-single-call
* stack.push('second');
*
* assert.isFalse(stack.isEmpty);
*
* assert.isTrue(stack.size === 2);
*
* assert.deepStrictEqual(stack.pop(), Optional.some('second'));
*
* assert.deepStrictEqual(stack.pop(), Optional.some('first'));
*
* assert.deepStrictEqual(stack.pop(), Optional.none);
*
* const seededStack = createStack([10, 20, 30]);
*
* assert.isTrue(seededStack.size === 3);
*
* assert.deepStrictEqual(seededStack.pop(), Optional.some(30));
* ```
*
* @template T The type of elements stored in the stack.
* @param initialValues Optional array of initial elements to populate the
* stack. Elements will be popped in reverse order of how they appear in the
* array (last array element will be popped first). If provided, the initial
* buffer capacity will be at least twice the array length.
* @returns A new Stack instance optimized for high-performance LIFO operations.
*/
export declare const createStack: <T>(initialValues?: readonly T[]) => Stack<T>;
//# sourceMappingURL=stack.d.mts.map