stack-typed 2.1.1 → 2.1.2

package/dist/data-structures/stack/stack.js

@@ -1,401 +0,0 @@
-"use strict";
-/**
- * data-structure-typed
- *
- * @author Pablo Zeng
- * @copyright Copyright (c) 2022 Pablo Zeng <zrwusa@gmail.com>
- * @license MIT License
- */
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.Stack = void 0;
-const base_1 = require("../base");
-/**
- * LIFO stack with array storage and optional record→element conversion.
- * @remarks Time O(1), Space O(1)
- * @template E
- * @template R
- * 1. Last In, First Out (LIFO): The core characteristic of a stack is its last in, first out nature, meaning the last element added to the stack will be the first to be removed.
- * 2. Uses: Stacks are commonly used for managing a series of tasks or elements that need to be processed in a last in, first out manner. They are widely used in various scenarios, such as in function calls in programming languages, evaluation of arithmetic expressions, and backtracking algorithms.
- * 3. Performance: Stack operations are typically O(1) in time complexity, meaning that regardless of the stack's size, adding, removing, and viewing the top element are very fast operations.
- * 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]
- */
-class Stack extends base_1.IterableElementBase {
-    /**
-     * Create a Stack and optionally bulk-push elements.
-     * @remarks Time O(N), Space O(N)
-     * @param [elements] - Iterable of elements (or raw records if toElementFn is set).
-     * @param [options] - Options such as toElementFn and equality function.
-     * @returns New Stack instance.
-     */
-    constructor(elements = [], options) {
-        super(options);
-        this._equals = Object.is;
-        this._elements = [];
-        this.pushMany(elements);
-    }
-    /**
-     * Get the backing array of elements.
-     * @remarks Time O(1), Space O(1)
-     * @returns Internal elements array.
-     */
-    get elements() {
-        return this._elements;
-    }
-    /**
-     * Get the number of stored elements.
-     * @remarks Time O(1), Space O(1)
-     * @returns Current size.
-     */
-    get size() {
-        return this.elements.length;
-    }
-    /**
-     * Create a stack from an array of elements.
-     * @remarks Time O(N), Space O(N)
-     * @template E
-     * @template R
-     * @param this - The constructor (subclass) to instantiate.
-     * @param elements - Array of elements to push in order.
-     * @param [options] - Options forwarded to the constructor.
-     * @returns A new Stack populated from the array.
-     */
-    static fromArray(elements, options) {
-        return new this(elements, options);
-    }
-    /**
-     * Check whether the stack is empty.
-     * @remarks Time O(1), Space O(1)
-     * @returns True if size is 0.
-     */
-    isEmpty() {
-        return this.elements.length === 0;
-    }
-    /**
-     * Get the top element without removing it.
-     * @remarks Time O(1), Space O(1)
-     * @returns Top element or undefined.
-     */
-    peek() {
-        return this.isEmpty() ? undefined : this.elements[this.elements.length - 1];
-    }
-    /**
-     * Push one element onto the top.
-     * @remarks Time O(1), Space O(1)
-     * @param element - Element to push.
-     * @returns True when pushed.
-     */
-    push(element) {
-        this.elements.push(element);
-        return true;
-    }
-    /**
-     * Pop and return the top element.
-     * @remarks Time O(1), Space O(1)
-     * @returns Removed element or undefined.
-     */
-    pop() {
-        return this.isEmpty() ? undefined : this.elements.pop();
-    }
-    /**
-     * Push many elements from an iterable.
-     * @remarks Time O(N), Space O(1)
-     * @param elements - Iterable of elements (or raw records if toElementFn is set).
-     * @returns Array of per-element success flags.
-     */
-    pushMany(elements) {
-        const ans = [];
-        for (const el of elements) {
-            if (this.toElementFn)
-                ans.push(this.push(this.toElementFn(el)));
-            else
-                ans.push(this.push(el));
-        }
-        return ans;
-    }
-    /**
-     * Delete the first occurrence of a specific element.
-     * @remarks Time O(N), Space O(1)
-     * @param element - Element to remove (using the configured equality).
-     * @returns True if an element was removed.
-     */
-    delete(element) {
-        const idx = this._indexOfByEquals(element);
-        return this.deleteAt(idx);
-    }
-    /**
-     * Delete the element at an index.
-     * @remarks Time O(N), Space O(1)
-     * @param index - Zero-based index from the bottom.
-     * @returns True if removed.
-     */
-    deleteAt(index) {
-        if (index < 0 || index >= this.elements.length)
-            return false;
-        const spliced = this.elements.splice(index, 1);
-        return spliced.length === 1;
-    }
-    /**
-     * Delete the first element that satisfies a predicate.
-     * @remarks Time O(N), Space O(1)
-     * @param predicate - Function (value, index, stack) → boolean to decide deletion.
-     * @returns True if a match was removed.
-     */
-    deleteWhere(predicate) {
-        for (let i = 0; i < this.elements.length; i++) {
-            if (predicate(this.elements[i], i, this)) {
-                this.elements.splice(i, 1);
-                return true;
-            }
-        }
-        return false;
-    }
-    /**
-     * Remove all elements and reset storage.
-     * @remarks Time O(1), Space O(1)
-     * @returns void
-     */
-    clear() {
-        this._elements = [];
-    }
-    /**
-     * Deep clone this stack.
-     * @remarks Time O(N), Space O(N)
-     * @returns A new stack with the same content.
-     */
-    clone() {
-        const out = this._createInstance({ toElementFn: this.toElementFn });
-        for (const v of this)
-            out.push(v);
-        return out;
-    }
-    /**
-     * Filter elements into a new stack of the same class.
-     * @remarks Time O(N), Space O(N)
-     * @param predicate - Predicate (value, index, stack) → boolean to keep value.
-     * @param [thisArg] - Value for `this` inside the predicate.
-     * @returns A new stack with kept values.
-     */
-    filter(predicate, thisArg) {
-        const out = this._createInstance({ toElementFn: this.toElementFn });
-        let index = 0;
-        for (const v of this) {
-            if (predicate.call(thisArg, v, index, this))
-                out.push(v);
-            index++;
-        }
-        return out;
-    }
-    /**
-     * Map values into a new stack of the same element type.
-     * @remarks Time O(N), Space O(N)
-     * @param callback - Mapping function (value, index, stack) → newValue.
-     * @param [thisArg] - Value for `this` inside the callback.
-     * @returns A new stack with mapped values.
-     */
-    mapSame(callback, thisArg) {
-        const out = this._createInstance({ toElementFn: this.toElementFn });
-        let index = 0;
-        for (const v of this) {
-            const mv = thisArg === undefined ? callback(v, index++, this) : callback.call(thisArg, v, index++, this);
-            out.push(mv);
-        }
-        return out;
-    }
-    /**
-     * Map values into a new stack (possibly different element type).
-     * @remarks Time O(N), Space O(N)
-     * @template EM
-     * @template RM
-     * @param callback - Mapping function (value, index, stack) → newElement.
-     * @param [options] - Options for the output stack (e.g., toElementFn).
-     * @param [thisArg] - Value for `this` inside the callback.
-     * @returns A new Stack with mapped elements.
-     */
-    map(callback, options, thisArg) {
-        const out = this._createLike([], Object.assign({}, (options !== null && options !== void 0 ? options : {})));
-        let index = 0;
-        for (const v of this) {
-            out.push(thisArg === undefined ? callback(v, index, this) : callback.call(thisArg, v, index, this));
-            index++;
-        }
-        return out;
-    }
-    /**
-     * Set the equality comparator used by delete/search operations.
-     * @remarks Time O(1), Space O(1)
-     * @param equals - Equality predicate (a, b) → boolean.
-     * @returns This stack.
-     */
-    setEquality(equals) {
-        this._equals = equals;
-        return this;
-    }
-    /**
-     * (Protected) Find the index of a target element using the equality function.
-     * @remarks Time O(N), Space O(1)
-     * @param target - Element to search for.
-     * @returns Index or -1 if not found.
-     */
-    _indexOfByEquals(target) {
-        for (let i = 0; i < this.elements.length; i++)
-            if (this._equals(this.elements[i], target))
-                return i;
-        return -1;
-    }
-    /**
-     * (Protected) Create an empty instance of the same concrete class.
-     * @remarks Time O(1), Space O(1)
-     * @param [options] - Options forwarded to the constructor.
-     * @returns An empty like-kind stack instance.
-     */
-    _createInstance(options) {
-        const Ctor = this.constructor;
-        return new Ctor([], options);
-    }
-    /**
-     * (Protected) Create a like-kind stack and seed it from an iterable.
-     * @remarks Time O(N), Space O(N)
-     * @template T
-     * @template RR
-     * @param [elements] - Iterable used to seed the new stack.
-     * @param [options] - Options forwarded to the constructor.
-     * @returns A like-kind Stack instance.
-     */
-    _createLike(elements = [], options) {
-        const Ctor = this.constructor;
-        return new Ctor(elements, options);
-    }
-    /**
-     * (Protected) Iterate elements from bottom to top.
-     * @remarks Time O(N), Space O(1)
-     * @returns Iterator of elements.
-     */
-    *_getIterator() {
-        for (let i = 0; i < this.elements.length; i++)
-            yield this.elements[i];
-    }
-}
-exports.Stack = Stack;

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

@@ -1,17 +0,0 @@
-"use strict";
-var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    var desc = Object.getOwnPropertyDescriptor(m, k);
-    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
-      desc = { enumerable: true, get: function() { return m[k]; } };
-    }
-    Object.defineProperty(o, k2, desc);
-}) : (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    o[k2] = m[k];
-}));
-var __exportStar = (this && this.__exportStar) || function(m, exports) {
-    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
-};
-Object.defineProperty(exports, "__esModule", { value: true });
-__exportStar(require("./tree"), exports);

package/dist/data-structures/tree/tree.d.ts

@@ -1,62 +0,0 @@
-export declare class TreeNode<V = any> {
-    /**
-     * The constructor function initializes a TreeNode object with a key, optional value, and optional
-     * children.
-     * @param {string} key - A string representing the key of the tree node.
-     * @param {V} [value] - The `value` parameter is an optional parameter of type `V`. It represents the
-     * value associated with the node. If no value is provided, it defaults to `undefined`.
-     * @param {TreeNode<V>[]} [children] - The `children` parameter is an optional array of `TreeNode<V>`
-     * objects. It represents the child nodes of the current node. If no children are provided, the
-     * default value is an empty array.
-     */
-    constructor(key: string, value?: V, children?: TreeNode<V>[]);
-    protected _key: string;
-    /**
-     * The function returns the value of the protected variable _key.
-     * @returns The value of the `_key` property, which is a string.
-     */
-    get key(): string;
-    /**
-     * The above function sets the value of a protected variable called "key".
-     * @param {string} value - The value parameter is a string that represents the value to be assigned
-     * to the key.
-     */
-    set key(value: string);
-    protected _value?: V | undefined;
-    /**
-     * The function returns the value stored in a variable, or undefined if the variable is empty.
-     * @returns The value of the variable `_value` is being returned.
-     */
-    get value(): V | undefined;
-    /**
-     * The function sets the value of a variable.
-     * @param {V | undefined} value - The parameter "value" is of type "V | undefined", which means it
-     * can accept a value of type "V" or it can be undefined.
-     */
-    set value(value: V | undefined);
-    protected _children?: TreeNode<V>[] | undefined;
-    /**
-     * The function returns an array of TreeNode objects or undefined.
-     * @returns The `children` property is being returned. It is of type `TreeNode<V>[] | undefined`,
-     * which means it can either be an array of `TreeNode<V>` objects or `undefined`.
-     */
-    get children(): TreeNode<V>[] | undefined;
-    /**
-     * The function sets the value of the children property of a TreeNode object.
-     * @param {TreeNode<V>[] | undefined} value - The value parameter is of type TreeNode<V>[] |
-     * undefined. This means that it can accept an array of TreeNode objects or undefined.
-     */
-    set children(value: TreeNode<V>[] | undefined);
-    /**
-     * The function `addChildren` adds one or more child nodes to the current node.
-     * @param {TreeNode<V> | TreeNode<V>[]} children - The `children` parameter can be either a single
-     * `TreeNode<V>` object or an array of `TreeNode<V>` objects.
-     */
-    addChildren(children: TreeNode<V> | TreeNode<V>[]): void;
-    /**
-     * The function `getHeight()` calculates the maximum depth of a tree structure by performing a
-     * breadth-first search.
-     * @returns the maximum depth or height of the tree.
-     */
-    getHeight(): number;
-}

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

@@ -1,107 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.TreeNode = void 0;
-class TreeNode {
-    /**
-     * The constructor function initializes a TreeNode object with a key, optional value, and optional
-     * children.
-     * @param {string} key - A string representing the key of the tree node.
-     * @param {V} [value] - The `value` parameter is an optional parameter of type `V`. It represents the
-     * value associated with the node. If no value is provided, it defaults to `undefined`.
-     * @param {TreeNode<V>[]} [children] - The `children` parameter is an optional array of `TreeNode<V>`
-     * objects. It represents the child nodes of the current node. If no children are provided, the
-     * default value is an empty array.
-     */
-    constructor(key, value, children) {
-        this._key = key;
-        this._value = value || undefined;
-        if (children)
-            this._children = children;
-    }
-    /**
-     * The function returns the value of the protected variable _key.
-     * @returns The value of the `_key` property, which is a string.
-     */
-    get key() {
-        return this._key;
-    }
-    /**
-     * The above function sets the value of a protected variable called "key".
-     * @param {string} value - The value parameter is a string that represents the value to be assigned
-     * to the key.
-     */
-    set key(value) {
-        this._key = value;
-    }
-    /**
-     * The function returns the value stored in a variable, or undefined if the variable is empty.
-     * @returns The value of the variable `_value` is being returned.
-     */
-    get value() {
-        return this._value;
-    }
-    /**
-     * The function sets the value of a variable.
-     * @param {V | undefined} value - The parameter "value" is of type "V | undefined", which means it
-     * can accept a value of type "V" or it can be undefined.
-     */
-    set value(value) {
-        this._value = value;
-    }
-    /**
-     * The function returns an array of TreeNode objects or undefined.
-     * @returns The `children` property is being returned. It is of type `TreeNode<V>[] | undefined`,
-     * which means it can either be an array of `TreeNode<V>` objects or `undefined`.
-     */
-    get children() {
-        return this._children;
-    }
-    /**
-     * The function sets the value of the children property of a TreeNode object.
-     * @param {TreeNode<V>[] | undefined} value - The value parameter is of type TreeNode<V>[] |
-     * undefined. This means that it can accept an array of TreeNode objects or undefined.
-     */
-    set children(value) {
-        this._children = value;
-    }
-    /**
-     * The function `addChildren` adds one or more child nodes to the current node.
-     * @param {TreeNode<V> | TreeNode<V>[]} children - The `children` parameter can be either a single
-     * `TreeNode<V>` object or an array of `TreeNode<V>` objects.
-     */
-    addChildren(children) {
-        if (!this._children) {
-            this._children = [];
-        }
-        if (children instanceof TreeNode) {
-            this._children.push(children);
-        }
-        else {
-            this._children = this._children.concat(children);
-        }
-    }
-    /**
-     * The function `getHeight()` calculates the maximum depth of a tree structure by performing a
-     * breadth-first search.
-     * @returns the maximum depth or height of the tree.
-     */
-    getHeight() {
-        let maxDepth = 0;
-        if (this) {
-            const bfs = (node, level) => {
-                if (level > maxDepth) {
-                    maxDepth = level;
-                }
-                const { _children } = node;
-                if (_children) {
-                    for (let i = 0, len = _children.length; i < len; i++) {
-                        bfs(_children[i], level + 1);
-                    }
-                }
-            };
-            bfs(this, 0);
-        }
-        return maxDepth;
-    }
-}
-exports.TreeNode = TreeNode;

package/dist/data-structures/trie/index.js

@@ -1,17 +0,0 @@
-"use strict";
-var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    var desc = Object.getOwnPropertyDescriptor(m, k);
-    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
-      desc = { enumerable: true, get: function() { return m[k]; } };
-    }
-    Object.defineProperty(o, k2, desc);
-}) : (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    o[k2] = m[k];
-}));
-var __exportStar = (this && this.__exportStar) || function(m, exports) {
-    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
-};
-Object.defineProperty(exports, "__esModule", { value: true });
-__exportStar(require("./trie"), exports);