graph-typed 1.46.1 → 1.46.2

package/dist/data-structures/queue/deque.js

@@ -16,6 +16,20 @@ const utils_1 = require("../../utils");
  * Deque is implemented using a dynamic array. Inserting or deleting beyond both ends of the array may require moving elements or reallocating space.
  */
 class DequeIterator {
+    /**
+     * The constructor initializes the index, iterate direction, and prev/next functions for a
+     * DequeIterator object.
+     * @param {number} index - The index parameter represents the current index position of the iterator
+     * within the deque. It is a number that indicates the position of the element that the iterator is
+     * currently pointing to.
+     * @param deque - The `deque` parameter is an instance of the `Deque` class. It represents a
+     * double-ended queue data structure, which allows elements to be added or removed from both ends.
+     * @param iterateDirection - The `iterateDirection` parameter is an optional parameter that specifies
+     * the direction in which the iterator should iterate over the elements of the `deque`. It has a
+     * default value of `IterateDirection.DEFAULT`.
+     * @returns The constructor is not returning anything. It is used to initialize the properties of the
+     * object being created.
+     */
     constructor(index, deque, iterateDirection = 0 /* IterateDirection.DEFAULT */) {
         this.index = index;
         this.iterateDirection = iterateDirection;
@@ -74,6 +88,15 @@ class DequeIterator {
 }
 exports.DequeIterator = DequeIterator;
 class Deque {
+    /**
+     * The constructor initializes a data structure with a specified bucket size and populates it with
+     * elements from an iterable.
+     * @param elements - The `elements` parameter is an iterable object (such as an array or a Set) that
+     * contains the initial elements to be stored in the data structure. It can also be an object with a
+     * `length` property or a `size` property, which represents the number of elements in the iterable.
+     * @param bucketSize - The `bucketSize` parameter is the maximum number of elements that can be
+     * stored in each bucket. It determines the size of each bucket in the data structure.
+     */
     constructor(elements = [], bucketSize = (1 << 12)) {
         this._bucketFirst = 0;
         this._firstInBucket = 0;
@@ -84,10 +107,16 @@ class Deque {
         this._size = 0;
         let _size;
         if ('length' in elements) {
-            _size = elements.length;
+            if (elements.length instanceof Function)
+                _size = elements.length();
+            else
+                _size = elements.length;
         }
         else {
-            _size = elements.size;
+            if (elements.size instanceof Function)
+                _size = elements.size();
+            else
+                _size = elements.size;
         }
         this._bucketSize = bucketSize;
         this._bucketCount = (0, utils_1.calcMinUnitsRequired)(_size, this._bucketSize) || 1;
@@ -107,6 +136,11 @@ class Deque {
     get size() {
         return this._size;
     }
+    /**
+     * The function returns the first element in a collection if it exists, otherwise it returns
+     * undefined.
+     * @returns The first element of the collection, of type E, is being returned.
+     */
     get first() {
         if (this.size === 0)
             return;
@@ -117,13 +151,6 @@ class Deque {
             return;
         return this._buckets[this._bucketLast][this._lastInBucket];
     }
-    /**
-     * Time Complexity: Amortized O(1) - Generally constant time, but resizing when the deque is full leads to O(n).
-     * Space Complexity: O(n) - In worst case, resizing doubles the array size.
-     */
-    empty() {
-        return this._size === 0;
-    }
     /**
      * Time Complexity: O(1) - Removes the last element.
      * Space Complexity: O(1) - Operates in-place.
@@ -182,24 +209,60 @@ class Deque {
     popFirst() {
         return this.shift();
     }
+    /**
+     * The clear() function resets the state of the object by initializing all variables to their default
+     * values.
+     */
     clear() {
         this._buckets = [new Array(this._bucketSize)];
         this._bucketCount = 1;
         this._bucketFirst = this._bucketLast = this._size = 0;
         this._firstInBucket = this._lastInBucket = this._bucketSize >> 1;
     }
+    /**
+     * The `begin()` function returns a new iterator for a deque starting from the first element.
+     * @returns A new instance of the DequeIterator class is being returned.
+     */
     begin() {
         return new DequeIterator(0, this);
     }
+    /**
+     * The `end()` function returns a new `DequeIterator` object with the size and reference to the
+     * current deque.
+     * @returns A new instance of the DequeIterator class is being returned.
+     */
     end() {
         return new DequeIterator(this.size, this);
     }
+    /**
+     * The reverseBegin function returns a new DequeIterator object that starts at the last element of
+     * the deque and iterates in reverse direction.
+     * @returns A new instance of the DequeIterator class is being returned.
+     */
     reverseBegin() {
         return new DequeIterator(this.size - 1, this, 1 /* IterateDirection.REVERSE */);
     }
+    /**
+     * The reverseEnd() function returns a new DequeIterator object that iterates over the elements of a
+     * Deque in reverse order.
+     * @returns A new instance of the DequeIterator class is being returned.
+     */
     reverseEnd() {
         return new DequeIterator(-1, this, 1 /* IterateDirection.REVERSE */);
     }
+    /**
+     * Time Complexity - Amortized O(1) (possible reallocation)
+     * Space Complexity - O(n) (due to potential resizing).
+     */
+    /**
+     * Time Complexity - Amortized O(1) (possible reallocation),
+     * Space Complexity - O(n) (due to potential resizing).
+     *
+     * The push function adds an element to a data structure and reallocates memory if necessary.
+     * @param {E} element - The `element` parameter represents the value that you want to add to the data
+     * structure.
+     * @returns The size of the data structure after the element has been pushed.
+     */
     push(element) {
         if (this.size) {
             if (this._lastInBucket < this._bucketSize - 1) {
@@ -221,6 +284,18 @@ class Deque {
         this._buckets[this._bucketLast][this._lastInBucket] = element;
         return this.size;
     }
+    /**
+     * Time Complexity: O(1)
+     * Space Complexity: O(1)
+     */
+    /**
+     * Time Complexity: O(1)
+     * Space Complexity: O(1)
+     *
+     * The `pop()` function removes and returns the last element from a data structure, updating the
+     * internal state variables accordingly.
+     * @returns The element that was removed from the data structure is being returned.
+     */
     pop() {
         if (this.size === 0)
             return;
@@ -241,6 +316,20 @@ class Deque {
         this._size -= 1;
         return element;
     }
+    /**
+     * Time Complexity: Amortized O(1)
+     * Space Complexity: O(n)
+     */
+    /**
+     * Time Complexity: Amortized O(1)
+     * Space Complexity: O(n)
+     *
+     * The `unshift` function adds an element to the beginning of an array-like data structure and
+     * returns the new size of the structure.
+     * @param {E} element - The `element` parameter represents the element that you want to add to the
+     * beginning of the data structure.
+     * @returns The size of the data structure after the element has been added.
+     */
     unshift(element) {
         if (this.size) {
             if (this._firstInBucket > 0) {
@@ -262,6 +351,19 @@ class Deque {
         this._buckets[this._bucketFirst][this._firstInBucket] = element;
         return this.size;
     }
+    /**
+     * Time Complexity: O(1)
+     * Space Complexity: O(1)
+     */
+    /**
+     * Time Complexity: O(1)
+     * Space Complexity: O(1)
+     *
+     * The `shift()` function removes and returns the first element from a data structure, updating the
+     * internal state variables accordingly.
+     * @returns The element that is being removed from the beginning of the data structure is being
+     * returned.
+     */
     shift() {
         if (this.size === 0)
             return;
@@ -282,16 +384,63 @@ class Deque {
         this._size -= 1;
         return element;
     }
+    /**
+     * Time Complexity: O(1)
+     * Space Complexity: O(1)
+     */
+    /**
+     * Time Complexity: O(1)
+     * Space Complexity: O(1)
+     *
+     * The `getAt` function retrieves an element at a specified position in an array-like data structure.
+     * @param {number} pos - The `pos` parameter represents the position of the element that you want to
+     * retrieve from the data structure. It is of type `number` and should be a valid index within the
+     * range of the data structure.
+     * @returns The element at the specified position in the data structure is being returned.
+     */
     getAt(pos) {
         utils_1.rangeCheck(pos, 0, this.size - 1);
         const { bucketIndex, indexInBucket } = this._getBucketAndPosition(pos);
         return this._buckets[bucketIndex][indexInBucket];
     }
+    /**
+     * Time Complexity: O(1)
+     * Space Complexity: O(1)
+     */
+    /**
+     * Time Complexity: O(1)
+     * Space Complexity: O(1)
+     *
+     * The `setAt` function sets an element at a specific position in an array-like data structure.
+     * @param {number} pos - The `pos` parameter represents the position at which the element needs to be
+     * set. It is of type `number`.
+     * @param {E} element - The `element` parameter is the value that you want to set at the specified
+     * position in the data structure.
+     */
     setAt(pos, element) {
         utils_1.rangeCheck(pos, 0, this.size - 1);
         const { bucketIndex, indexInBucket } = this._getBucketAndPosition(pos);
         this._buckets[bucketIndex][indexInBucket] = element;
     }
+    /**
+     * Time Complexity: O(n)
+     * Space Complexity: O(n)
+     */
+    /**
+     * Time Complexity: O(n)
+     * Space Complexity: O(n)
+     *
+     * The `insertAt` function inserts one or more elements at a specified position in an array-like data
+     * structure.
+     * @param {number} pos - The `pos` parameter represents the position at which the element(s) should
+     * be inserted. It is of type `number`.
+     * @param {E} element - The `element` parameter represents the element that you want to insert into
+     * the array at the specified position.
+     * @param [num=1] - The `num` parameter represents the number of times the `element` should be
+     * inserted at the specified position (`pos`). By default, it is set to 1, meaning that the `element`
+     * will be inserted once. However, you can provide a different value for `num` if you want
+     * @returns The size of the array after the insertion is being returned.
+     */
     insertAt(pos, element, num = 1) {
         const length = this.size;
         utils_1.rangeCheck(pos, 0, length);
@@ -316,6 +465,20 @@ class Deque {
         }
         return this.size;
     }
+    /**
+     * Time Complexity: O(1)
+     * Space Complexity: O(1)
+     */
+    /**
+     * Time Complexity: O(1)
+     * Space Complexity: O(1)
+     *
+     * The `cut` function updates the state of the object based on the given position and returns the
+     * updated size.
+     * @param {number} pos - The `pos` parameter represents the position at which the string should be
+     * cut. It is a number that indicates the index of the character where the cut should be made.
+     * @returns The method is returning the updated size of the data structure.
+     */
     cut(pos) {
         if (pos < 0) {
             this.clear();
@@ -327,6 +490,21 @@ class Deque {
         this._size = pos + 1;
         return this.size;
     }
+    /**
+     * Time Complexity: O(n)
+     * Space Complexity: O(1)
+     */
+    /**
+     * Time Complexity: O(n)
+     * Space Complexity: O(1)
+     *
+     * The `deleteAt` function removes an element at a specified position in an array-like data
+     * structure.
+     * @param {number} pos - The `pos` parameter in the `deleteAt` function represents the position at
+     * which an element needs to be deleted from the data structure. It is of type `number` and indicates
+     * the index of the element to be deleted.
+     * @returns The size of the data structure after the deletion operation is performed.
+     */
     deleteAt(pos) {
         utils_1.rangeCheck(pos, 0, this.size - 1);
         if (pos === 0)
@@ -346,6 +524,20 @@ class Deque {
         }
         return this.size;
     }
+    /**
+     * Time Complexity: O(n)
+     * Space Complexity: O(1)
+     */
+    /**
+     * Time Complexity: O(n)
+     * Space Complexity: O(1)
+     *
+     * The `delete` function removes all occurrences of a specified element from an array-like data
+     * structure.
+     * @param {E} element - The `element` parameter represents the element that you want to delete from
+     * the data structure.
+     * @returns The size of the data structure after the element has been deleted.
+     */
     delete(element) {
         const size = this.size;
         if (size === 0)
@@ -363,12 +555,38 @@ class Deque {
         this.cut(index - 1);
         return this.size;
     }
+    /**
+     * Time Complexity: O(n)
+     * Space Complexity: O(1)
+     */
+    /**
+     * Time Complexity: O(n)
+     * Space Complexity: O(1)
+     *
+     * The function deletes an element from a deque using an iterator and returns the next iterator.
+     * @param iter - The parameter `iter` is of type `DequeIterator<E>`. It represents an iterator object
+     * that is used to iterate over elements in a deque (double-ended queue).
+     * @returns the updated iterator after deleting an element from the deque.
+     */
     deleteByIterator(iter) {
         const index = iter.index;
         this.deleteAt(index);
         iter = iter.next();
         return iter;
     }
+    /**
+     * Time Complexity: O(n)
+     * Space Complexity: O(1)
+     */
+    /**
+     * Time Complexity: O(n)
+     * Space Complexity: O(1)
+     *
+     * The function `findIterator` searches for an element in a deque and returns an iterator pointing to
+     * the element if found, otherwise it returns an iterator pointing to the end of the deque.
+     * @param {E} element - The `element` parameter is the element that you want to find in the deque.
+     * @returns The method `findIterator(element: E)` returns a `DequeIterator<E>` object.
+     */
     findIterator(element) {
         for (let i = 0; i < this.size; ++i) {
             if (this.getAt(i) === element) {
@@ -377,6 +595,19 @@ class Deque {
         }
         return this.end();
     }
+    /**
+     * Time Complexity: O(n)
+     * Space Complexity: O(1)
+     */
+    /**
+     * Time Complexity: O(n)
+     * Space Complexity: O(1)
+     *
+     * The reverse() function reverses the order of the buckets and the elements within each bucket in a
+     * data structure.
+     * @returns The reverse() method is returning the object itself (this) after performing the reverse
+     * operation on the buckets and updating the relevant properties.
+     */
     reverse() {
         this._buckets.reverse().forEach(function (bucket) {
             bucket.reverse();
@@ -388,6 +619,18 @@ class Deque {
         this._lastInBucket = this._bucketSize - _firstInBucket - 1;
         return this;
     }
+    /**
+     * Time Complexity: O(n)
+     * Space Complexity: O(1)
+     */
+    /**
+     * Time Complexity: O(n)
+     * Space Complexity: O(1)
+     *
+     * The `unique()` function removes duplicate elements from an array-like data structure and returns
+     * the number of unique elements.
+     * @returns The size of the modified array is being returned.
+     */
     unique() {
         if (this.size <= 1) {
             return this.size;
@@ -404,6 +647,20 @@ class Deque {
         this.cut(index - 1);
         return this.size;
     }
+    /**
+     * Time Complexity: O(n log n)
+     * Space Complexity: O(n)
+     */
+    /**
+     * Time Complexity: O(n log n)
+     * Space Complexity: O(n)
+     *
+     * The `sort` function sorts the elements in a data structure using a provided comparator function.
+     * @param [comparator] - The `comparator` parameter is a function that takes in two elements `x` and
+     * `y` of type `E` and returns a number. The comparator function is used to determine the order of
+     * the elements in the sorted array.
+     * @returns The method is returning the sorted instance of the object on which the method is called.
+     */
     sort(comparator) {
         const arr = [];
         for (let i = 0; i < this.size; ++i) {
@@ -415,6 +672,19 @@ class Deque {
         }
         return this;
     }
+    /**
+     * Time Complexity: O(n)
+     * Space Complexity: O(n)
+     */
+    /**
+     * Time Complexity: O(n)
+     * Space Complexity: O(n)
+     *
+     * The `shrinkToFit` function reorganizes the elements in an array-like data structure to minimize
+     * memory usage.
+     * @returns Nothing is being returned. The function is using the `return` statement to exit early if
+     * `this.size` is 0, but it does not return any value.
+     */
     shrinkToFit() {
         if (this.size === 0)
             return;
@@ -438,11 +708,39 @@ class Deque {
         this._bucketLast = newBuckets.length - 1;
         this._buckets = newBuckets;
     }
+    /**
+     * Time Complexity: O(n)
+     * Space Complexity: O(1)
+     */
+    /**
+     * Time Complexity: O(n)
+     * Space Complexity: O(1)
+     *
+     * The `forEach` function iterates over each element in a deque and applies a callback function to
+     * each element.
+     * @param callback - The callback parameter is a function that will be called for each element in the
+     * deque. It takes three parameters:
+     */
     forEach(callback) {
         for (let i = 0; i < this.size; ++i) {
             callback(this.getAt(i), i, this);
         }
     }
+    /**
+     * Time Complexity: O(n)
+     * Space Complexity: O(1)
+     */
+    /**
+     * Time Complexity: O(n)
+     * Space Complexity: O(1)
+     *
+     * The `find` function iterates over the elements in a deque and returns the first element for which
+     * the callback function returns true, or undefined if no such element is found.
+     * @param callback - A function that takes three parameters: element, index, and deque. It should
+     * return a boolean value indicating whether the element satisfies a certain condition.
+     * @returns The method `find` returns the first element in the deque that satisfies the condition
+     * specified by the callback function. If no element satisfies the condition, it returns `undefined`.
+     */
     find(callback) {
         for (let i = 0; i < this.size; ++i) {
             const element = this.getAt(i);
@@ -452,6 +750,17 @@ class Deque {
         }
         return undefined;
     }
+    /**
+     * Time Complexity: O(n)
+     * Space Complexity: O(n)
+     */
+    /**
+     * Time Complexity: O(n)
+     * Space Complexity: O(n)
+     *
+     * The `toArray` function converts the elements of a data structure into an array.
+     * @returns The `toArray()` method is returning an array of elements of type `E`.
+     */
     toArray() {
         const arr = [];
         for (let i = 0; i < this.size; ++i) {
@@ -459,6 +768,19 @@ class Deque {
         }
         return arr;
     }
+    /**
+     * Time Complexity: O(n)
+     * Space Complexity: O(n)
+     */
+    /**
+     * Time Complexity: O(n)
+     * Space Complexity: O(n)
+     *
+     * The `map` function takes a callback function and applies it to each element in the deque,
+     * returning a new deque with the results.
+     * @param callback - The `callback` parameter is a function that takes three arguments:
+     * @returns The `map` method is returning a new `Deque` object with the transformed elements.
+     */
     map(callback) {
         const newDeque = new Deque([], this._bucketSize);
         for (let i = 0; i < this.size; ++i) {
@@ -466,6 +788,21 @@ class Deque {
         }
         return newDeque;
     }
+    /**
+     * Time Complexity: O(n)
+     * Space Complexity: O(n)
+     */
+    /**
+     * Time Complexity: O(n)
+     * Space Complexity: O(n)
+     *
+     * The `filter` function creates a new deque containing only the elements that satisfy the given
+     * predicate function.
+     * @param predicate - The `predicate` parameter is a function that takes three arguments: `element`,
+     * `index`, and `deque`.
+     * @returns The `filter` method is returning a new `Deque` object that contains only the elements
+     * that satisfy the given `predicate` function.
+     */
     filter(predicate) {
         const newDeque = new Deque([], this._bucketSize);
         for (let i = 0; i < this.size; ++i) {
@@ -476,6 +813,23 @@ class Deque {
         }
         return newDeque;
     }
+    /**
+     * Time Complexity: O(n)
+     * Space Complexity: O(1)
+     */
+    /**
+     * Time Complexity: O(n)
+     * Space Complexity: O(1)
+     *
+     * The `reduce` function iterates over the elements of a deque and applies a callback function to
+     * each element, accumulating a single value.
+     * @param callback - The `callback` parameter is a function that takes four arguments:
+     * @param {T} initialValue - The `initialValue` parameter is the initial value of the accumulator. It
+     * is the value that will be passed as the first argument to the `callback` function when reducing
+     * the elements of the deque.
+     * @returns the final value of the accumulator after iterating over all elements in the deque and
+     * applying the callback function to each element.
+     */
     reduce(callback, initialValue) {
         let accumulator = initialValue;
         for (let i = 0; i < this.size; ++i) {
@@ -483,6 +837,21 @@ class Deque {
         }
         return accumulator;
     }
+    /**
+     * Time Complexity: O(n)
+     * Space Complexity: O(1)
+     */
+    /**
+     * Time Complexity: O(n)
+     * Space Complexity: O(1)
+     *
+     * The function "indexOf" returns the index of the first occurrence of a given element in an array,
+     * or -1 if the element is not found.
+     * @param {E} element - The "element" parameter represents the element that you want to find the
+     * index of in the data structure.
+     * @returns The indexOf function returns the index of the first occurrence of the specified element
+     * in the data structure. If the element is not found, it returns -1.
+     */
     indexOf(element) {
         for (let i = 0; i < this.size; ++i) {
             if (this.getAt(i) === element) {
@@ -491,11 +860,35 @@ class Deque {
         }
         return -1;
     }
+    /**
+     * Time Complexity: O(n)
+     * Space Complexity: O(1)
+     */
+    /**
+     * Time Complexity: O(n)
+     * Space Complexity: O(1)
+     *
+     * The above function is an implementation of the iterator protocol in TypeScript, allowing the
+     * object to be iterated over using a for...of loop.
+     */
     *[Symbol.iterator]() {
         for (let i = 0; i < this.size; ++i) {
             yield this.getAt(i);
         }
     }
+    /**
+     * Time Complexity: O(n)
+     * Space Complexity: O(n)
+     */
+    /**
+     * Time Complexity: O(n)
+     * Space Complexity: O(n)
+     *
+     * The `_reallocate` function reallocates the buckets in an array, adding new buckets if needed.
+     * @param {number} [needBucketNum] - The `needBucketNum` parameter is an optional number that
+     * specifies the number of new buckets needed. If not provided, it will default to half of the
+     * current bucket count (`this._bucketCount >> 1`) or 1 if the current bucket count is less than 2.
+     */
     _reallocate(needBucketNum) {
         const newBuckets = [];
         const addBucketNum = needBucketNum || this._bucketCount >> 1 || 1;
@@ -517,6 +910,19 @@ class Deque {
         this._buckets = newBuckets;
         this._bucketCount = newBuckets.length;
     }
+    /**
+     * Time Complexity: O(1)
+     * Space Complexity: O(1)
+     */
+    /**
+     * Time Complexity: O(1)
+     * Space Complexity: O(1)
+     *
+     * The function calculates the bucket index and index within the bucket based on the given position.
+     * @param {number} pos - The `pos` parameter represents the position within the data structure. It is
+     * a number that indicates the index or position of an element within the structure.
+     * @returns an object with two properties: "bucketIndex" and "indexInBucket".
+     */
     _getBucketAndPosition(pos) {
         let bucketIndex;
         let indexInBucket;

package/dist/types/helpers.d.ts

@@ -11,9 +11,9 @@ export declare const enum IterateDirection {
     REVERSE = 1
 }
 export interface IterableWithSize<T> extends Iterable<T> {
-    size: number;
+    size: number | ((...args: any[]) => number);
 }
 export interface IterableWithLength<T> extends Iterable<T> {
-    length: number;
+    length: number | ((...args: any[]) => number);
 }
 export type IterableWithSizeOrLength<T> = IterableWithSize<T> | IterableWithLength<T>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "graph-typed",
-  "version": "1.46.1",
+  "version": "1.46.2",
   "description": "Graph. Javascript & Typescript Data Structure.",
   "main": "dist/index.js",
   "scripts": {
@@ -136,6 +136,6 @@
     "typescript": "^4.9.5"
   },
   "dependencies": {
-    "data-structure-typed": "^1.46.0"
+    "data-structure-typed": "^1.46.2"
   }
 }