ts-data-forge 14.6.2 → 14.6.3

package/dist/collections/queue.mjs

@@ -1,37 +1,37 @@
 import { Optional } from '../functional/index.mjs';
 import { range } from '../iterator/index.mjs';
 import { asSafeUint, asUint32 } from '../number/index.mjs';
-/**
- * Class implementation for a queue with FIFO (First-In, First-Out) behavior
- * using a circular buffer. This implementation provides O(1) enqueue and
- * dequeue operations by using a fixed-size buffer with head and tail pointers
- * that wrap around when they reach the buffer boundary.
- *
- * The circular buffer automatically resizes when it becomes full, ensuring that
- * the queue can grow to accommodate any number of elements while maintaining
- * efficient operations.
- *
- * @template T The type of elements in the queue.
- * @implements Queue
- */
+
+
+
+
+
+
+
+
+
+
+
+
+
 class QueueClass {
-    /** @internal Initial capacity for new queues. */
+
     static #INITIAL_CAPACITY = 8;
-    /** @internal Circular buffer to store queue elements. */
+
     #mut_buffer;
-    /** @internal Index of the first element (front of queue). */
+
     #mut_head;
-    /** @internal Index where the next element will be added (back of queue). */
+
     #mut_tail;
-    /** @internal Current number of elements in the queue. */
+
     #mut_size;
-    /** @internal Current capacity of the buffer. */
+
     #mut_capacity;
-    /**
-     * Constructs a new QueueClass instance.
-     *
-     * @param initialValues Optional initial values to populate the queue.
-     */
+
+
+
+
+
     constructor(initialValues = []) {
         const initialCapacity = asUint32(Math.max(QueueClass.#INITIAL_CAPACITY, initialValues.length * 2));
         this.#mut_buffer = Array.from({ length: initialCapacity }, () => undefined);
@@ -39,20 +39,20 @@ class QueueClass {
         this.#mut_tail = 0;
         this.#mut_size = 0;
         this.#mut_capacity = initialCapacity;
-        // Add initial values
+
         for (const value of initialValues) {
             this.enqueue(value);
         }
     }
-    /**
-     * @internal
-     * Resizes the circular buffer when it becomes full.
-     * Doubles the capacity and reorganizes elements to maintain queue order.
-     */
+
+
+
+
+
     #resize() {
         const newCapacity = asUint32(this.#mut_capacity * 2);
         const newBuffer = Array.from({ length: newCapacity }, () => undefined);
-        // Copy elements in order from head to tail
+
         for (const i of range(asSafeUint(this.#mut_size))) {
             const sourceIndex = (this.#mut_head + i) % this.#mut_capacity;
             newBuffer[i] = this.#mut_buffer[sourceIndex];
@@ -62,58 +62,58 @@ class QueueClass {
         this.#mut_tail = this.#mut_size;
         this.#mut_capacity = newCapacity;
     }
-    /** @inheritdoc */
+
     get isEmpty() {
         return this.#mut_size === 0;
     }
-    /** @inheritdoc */
+
     get size() {
         return asUint32(this.#mut_size);
     }
-    /**
-     * Removes and returns the element at the front of the queue (FIFO).
-     *
-     * This operation removes the element that was added earliest (first-in) and
-     * returns it. If the queue is empty, returns `Optional.none`. The operation
-     * is guaranteed to be O(1) and does not require any array shifting or
-     * copying.
-     *
-     * **Time Complexity:** O(1) - constant time operation **Space Complexity:**
-     * O(1) - no additional memory allocation
-     *
-     * @returns An Optional containing the removed element, or `Optional.none` if
-     *   the queue is empty.
-     */
+
+
+
+
+
+
+
+
+
+
+
+
+
+
     dequeue() {
         if (this.isEmpty) {
             return Optional.none;
         }
-        // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+
         const element = this.#mut_buffer[this.#mut_head];
-        this.#mut_buffer[this.#mut_head] = undefined; // Clear reference for garbage collection
+        this.#mut_buffer[this.#mut_head] = undefined;
         this.#mut_head = (this.#mut_head + 1) % this.#mut_capacity;
         this.#mut_size -= 1;
         return Optional.some(element);
     }
-    /**
-     * Adds an element to the back of the queue (FIFO).
-     *
-     * This operation adds the element to the end of the queue, where it will be
-     * the last to be dequeued (first-in, first-out ordering). The operation is
-     * amortized O(1), meaning it's O(1) for most operations with occasional O(n)
-     * when the buffer needs resizing.
-     *
-     * **Time Complexity:** O(1) amortized - O(n) only when buffer resize is
-     * needed **Space Complexity:** O(1) - constant additional memory per element
-     *
-     * **Buffer Resizing:** When the internal buffer becomes full, it
-     * automatically doubles in size and reorganizes elements to maintain the
-     * circular buffer structure.
-     *
-     * @param value The element to add to the back of the queue.
-     */
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
     enqueue(value) {
-        // Resize if buffer is full
+
         if (this.#mut_size === this.#mut_capacity) {
             this.#resize();
         }
@@ -122,68 +122,68 @@ class QueueClass {
         this.#mut_size += 1;
     }
 }
-/**
- * Creates a new Queue instance with FIFO (First-In, First-Out) behavior using a
- * high-performance circular buffer.
- *
- * This factory function creates an optimized queue implementation that
- * maintains excellent performance characteristics for both enqueue and dequeue
- * operations. The underlying circular buffer automatically resizes to
- * accommodate growing workloads while providing predictable O(1) operations.
- *
- * **Implementation Features:**
- *
- * - **O(1) enqueue operations** (amortized - occasionally O(n) when resizing)
- * - **O(1) dequeue operations** (always)
- * - **Automatic buffer resizing** - starts at 8 elements, doubles when full
- * - **Memory efficient** - garbage collects removed elements immediately
- * - **Circular buffer design** - eliminates need for array shifting operations
- *
- * **Performance Benefits:**
- *
- * - No array copying during normal operations
- * - Minimal memory allocation overhead
- * - Predictable performance under high load
- * - Efficient memory usage with automatic cleanup
- *
- * @example
- *
- * ```ts
- * const queue = createQueue<number>();
- *
- * assert.isTrue(queue.isEmpty);
- *
- * assert.isTrue(queue.size === 0);
- *
- * queue.enqueue(1);
- *
- * queue.enqueue(2);
- *
- * assert.isFalse(queue.isEmpty);
- *
- * assert.isTrue(queue.size === 2);
- *
- * assert.deepStrictEqual(queue.dequeue(), Optional.some(1));
- *
- * assert.deepStrictEqual(queue.dequeue(), Optional.some(2));
- *
- * assert.deepStrictEqual(queue.dequeue(), Optional.none);
- *
- * const seededQueue = createQueue(['first', 'second']);
- *
- * assert.isTrue(seededQueue.size === 2);
- *
- * assert.deepStrictEqual(seededQueue.dequeue(), Optional.some('first'));
- *
- * assert.deepStrictEqual(seededQueue.dequeue(), Optional.some('second'));
- * ```
- *
- * @template T The type of elements stored in the queue.
- * @param initialValues Optional array of initial elements to populate the
- *   queue. Elements will be dequeued in the same order they appear in the
- *   array. If provided, the initial buffer capacity will be at least twice the
- *   array length.
- * @returns A new Queue instance optimized for high-performance FIFO operations.
- */
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
 export const createQueue = (initialValues) => new QueueClass(initialValues);
 //# sourceMappingURL=queue.mjs.map

package/dist/collections/stack.mjs

@@ -1,108 +1,108 @@
 import { Optional } from '../functional/index.mjs';
 import { range } from '../iterator/index.mjs';
 import { asUint32, Uint32 } from '../number/index.mjs';
-/**
- * Class implementation for a stack with LIFO (Last-In, First-Out) behavior
- * using a dynamic array. This implementation provides O(1) amortized push and
- * O(1) pop operations by using a resizable buffer that grows as needed.
- *
- * The underlying array automatically resizes when it becomes full, ensuring
- * that the stack can grow to accommodate any number of elements while
- * maintaining efficient operations.
- *
- * @template T The type of elements in the stack.
- * @implements Stack
- */
+
+
+
+
+
+
+
+
+
+
+
+
 class StackClass {
-    /** @internal Initial capacity for new stacks. */
+
     static #INITIAL_CAPACITY = 8;
-    /** @internal Dynamic array to store stack elements. */
+
     #mut_buffer;
-    /** @internal Current number of elements in the stack. */
+
     #mut_size;
-    /** @internal Current capacity of the buffer. */
+
     #mut_capacity;
-    /**
-     * Constructs a new StackClass instance.
-     *
-     * @param initialValues Optional initial values to populate the stack.
-     */
+
+
+
+
+
     constructor(initialValues = []) {
         const initialCapacity = asUint32(Math.max(StackClass.#INITIAL_CAPACITY, initialValues.length * 2));
         this.#mut_buffer = Array.from({ length: initialCapacity }, () => undefined);
         this.#mut_size = asUint32(0);
         this.#mut_capacity = initialCapacity;
-        // Add initial values
+
         for (const value of initialValues) {
             this.push(value);
         }
     }
-    /**
-     * @internal
-     * Resizes the buffer when it becomes full.
-     * Doubles the capacity while preserving all elements.
-     */
+
+
+
+
+
     #resize() {
         const newCapacity = asUint32(this.#mut_capacity * 2);
         const newBuffer = Array.from({ length: newCapacity }, () => undefined);
-        // Copy existing elements
+
         for (const i of range(this.#mut_size)) {
             newBuffer[i] = this.#mut_buffer[i];
         }
         this.#mut_buffer = newBuffer;
         this.#mut_capacity = newCapacity;
     }
-    /** @inheritdoc */
+
     get isEmpty() {
         return this.#mut_size === 0;
     }
-    /** @inheritdoc */
+
     get size() {
         return asUint32(this.#mut_size);
     }
-    /**
-     * Removes and returns the element at the top of the stack (LIFO).
-     *
-     * This operation removes the element that was added most recently (last-in)
-     * and returns it. If the stack is empty, returns `Optional.none`. The
-     * operation is guaranteed to be O(1) and does not require any array resizing
-     * or memory reallocation.
-     *
-     * **Time Complexity:** O(1) - constant time operation **Space Complexity:**
-     * O(1) - no additional memory allocation
-     *
-     * @returns An Optional containing the removed element, or `Optional.none` if
-     *   the stack is empty.
-     */
+
+
+
+
+
+
+
+
+
+
+
+
+
+
     pop() {
         if (this.isEmpty) {
             return Optional.none;
         }
         this.#mut_size = Uint32.sub(this.#mut_size, 1);
-        // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+
         const element = this.#mut_buffer[this.#mut_size];
-        this.#mut_buffer[this.#mut_size] = undefined; // Clear reference for garbage collection
+        this.#mut_buffer[this.#mut_size] = undefined;
         return Optional.some(element);
     }
-    /**
-     * Adds an element to the top of the stack (LIFO).
-     *
-     * This operation adds the element to the top of the stack, where it will be
-     * the first to be popped (last-in, first-out ordering). The operation is
-     * amortized O(1), meaning it's O(1) for most operations with occasional O(n)
-     * when the buffer needs resizing.
-     *
-     * **Time Complexity:** O(1) amortized - O(n) only when buffer resize is
-     * needed **Space Complexity:** O(1) - constant additional memory per element
-     *
-     * **Buffer Resizing:** When the internal buffer becomes full, it
-     * automatically doubles in size and copies existing elements to maintain the
-     * stack structure.
-     *
-     * @param value The element to add to the top of the stack.
-     */
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
     push(value) {
-        // Resize if buffer is full
+
         if (this.#mut_size === this.#mut_capacity) {
             this.#resize();
         }
@@ -110,66 +110,66 @@ class StackClass {
         this.#mut_size = Uint32.add(this.#mut_size, 1);
     }
 }
-/**
- * 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');
- *
- * 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 const createStack = (initialValues) => new StackClass(initialValues);
 //# sourceMappingURL=stack.mjs.map