ts-data-forge 5.0.0 → 5.1.0

package/src/collections/queue.mts

@@ -45,21 +45,29 @@ export type Queue<T> = Readonly<{
    * const queue = createQueue<number>();
    *
    * assert.ok(queue.isEmpty);
+   *
    * assert(queue.size === 0);
    *
    * queue.enqueue(1);
+   *
    * queue.enqueue(2);
    *
    * assert.notOk(queue.isEmpty);
+   *
    * assert(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(seededQueue.size === 2);
+   *
    * assert.deepStrictEqual(seededQueue.dequeue(), Optional.some('first'));
+   *
    * assert.deepStrictEqual(seededQueue.dequeue(), Optional.some('second'));
    * ```
    */
@@ -74,21 +82,29 @@ export type Queue<T> = Readonly<{
    * const queue = createQueue<number>();
    *
    * assert.ok(queue.isEmpty);
+   *
    * assert(queue.size === 0);
    *
    * queue.enqueue(1);
+   *
    * queue.enqueue(2);
    *
    * assert.notOk(queue.isEmpty);
+   *
    * assert(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(seededQueue.size === 2);
+   *
    * assert.deepStrictEqual(seededQueue.dequeue(), Optional.some('first'));
+   *
    * assert.deepStrictEqual(seededQueue.dequeue(), Optional.some('second'));
    * ```
    */
@@ -103,21 +119,29 @@ export type Queue<T> = Readonly<{
    * const queue = createQueue<number>();
    *
    * assert.ok(queue.isEmpty);
+   *
    * assert(queue.size === 0);
    *
    * queue.enqueue(1);
+   *
    * queue.enqueue(2);
    *
    * assert.notOk(queue.isEmpty);
+   *
    * assert(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(seededQueue.size === 2);
+   *
    * assert.deepStrictEqual(seededQueue.dequeue(), Optional.some('first'));
+   *
    * assert.deepStrictEqual(seededQueue.dequeue(), Optional.some('second'));
    * ```
    *
@@ -135,21 +159,29 @@ export type Queue<T> = Readonly<{
    * const queue = createQueue<number>();
    *
    * assert.ok(queue.isEmpty);
+   *
    * assert(queue.size === 0);
    *
    * queue.enqueue(1);
+   *
    * queue.enqueue(2);
    *
    * assert.notOk(queue.isEmpty);
+   *
    * assert(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(seededQueue.size === 2);
+   *
    * assert.deepStrictEqual(seededQueue.dequeue(), Optional.some('first'));
+   *
    * assert.deepStrictEqual(seededQueue.dequeue(), Optional.some('second'));
    * ```
    *
@@ -206,8 +238,11 @@ class QueueClass<T> implements Queue<T> {
     );
 
     this.#head = 0;
+
     this.#tail = 0;
+
     this.#mut_size = 0;
+
     this.#capacity = initialCapacity;
 
     // Add initial values
@@ -247,8 +282,11 @@ class QueueClass<T> implements Queue<T> {
 
     // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
     const element = this.#buffer[this.#head]!;
+
     this.#buffer[this.#head] = undefined; // Clear reference for garbage collection
+
     this.#head = (this.#head + 1) % this.#capacity;
+
     this.#mut_size -= 1;
 
     return Optional.some(element);
@@ -278,7 +316,9 @@ class QueueClass<T> implements Queue<T> {
     }
 
     this.#buffer[this.#tail] = value;
+
     this.#tail = (this.#tail + 1) % this.#capacity;
+
     this.#mut_size += 1;
   }
 
@@ -289,6 +329,7 @@ class QueueClass<T> implements Queue<T> {
    */
   #resize(): void {
     const newCapacity = asUint32(this.#capacity * 2);
+
     const newBuffer = Array.from<unknown, T | undefined>(
       { length: newCapacity },
       () => undefined,
@@ -297,12 +338,16 @@ class QueueClass<T> implements Queue<T> {
     // Copy elements in order from head to tail
     for (const i of range(asSafeUint(this.#mut_size))) {
       const sourceIndex = (this.#head + i) % this.#capacity;
+
       newBuffer[i] = this.#buffer[sourceIndex];
     }
 
     this.#buffer = newBuffer;
+
     this.#head = 0;
+
     this.#tail = this.#mut_size;
+
     this.#capacity = newCapacity;
   }
 }
@@ -337,21 +382,29 @@ class QueueClass<T> implements Queue<T> {
  * const queue = createQueue<number>();
  *
  * assert.ok(queue.isEmpty);
+ *
  * assert(queue.size === 0);
  *
  * queue.enqueue(1);
+ *
  * queue.enqueue(2);
  *
  * assert.notOk(queue.isEmpty);
+ *
  * assert(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(seededQueue.size === 2);
+ *
  * assert.deepStrictEqual(seededQueue.dequeue(), Optional.some('first'));
+ *
  * assert.deepStrictEqual(seededQueue.dequeue(), Optional.some('second'));
  * ```
  *

package/src/collections/queue.test.mts

@@ -10,6 +10,7 @@ describe('Queue test', () => {
       const q = createQueue();
 
       expect(q.isEmpty).toBe(true);
+
       expect(q.size).toBe(0);
     });
 
@@ -17,6 +18,7 @@ describe('Queue test', () => {
       const q = createQueue([1, 2, 3]);
 
       expect(q.isEmpty).toBe(false);
+
       expect(q.size).toBe(3);
     });
   });
@@ -33,11 +35,13 @@ describe('Queue test', () => {
       mut_q.enqueue(1);
 
       expect(mut_q.isEmpty).toBe(false);
+
       expect(mut_q.size).toBe(1);
     });
 
     test('should increase size when enqueueing to a non-empty queue', () => {
       mut_q.enqueue(1);
+
       mut_q.enqueue(2);
 
       expect(mut_q.size).toBe(2);
@@ -47,15 +51,19 @@ describe('Queue test', () => {
   describe('dequeue', () => {
     test('should return Optional.none and size should be 0 when dequeuing from an empty queue', () => {
       const q = createQueue<number>();
+
       const result = q.dequeue();
 
       expect(Optional.isNone(result)).toBe(true);
+
       expect(q.isEmpty).toBe(true);
+
       expect(q.size).toBe(0);
     });
 
     test('should decrease size and return the dequeued element for a non-empty queue', () => {
       const q = createQueue([1, 2, 3]); // FIFO: elements are in order [1, 2, 3]
+
       const initialSize = q.size;
 
       const result1 = q.dequeue(); // Dequeues 1 (first element)
@@ -81,10 +89,13 @@ describe('Queue test', () => {
 
     test('should become empty after dequeuing all elements', () => {
       const q = createQueue([1, 2]); // Internal: [1, 2]
+
       q.dequeue(); // Dequeues 1
+
       q.dequeue(); // Dequeues 2
 
       expect(q.isEmpty).toBe(true);
+
       expect(q.size).toBe(0);
 
       const result = q.dequeue(); // Dequeue from empty
@@ -96,8 +107,11 @@ describe('Queue test', () => {
   describe('FIFO behavior', () => {
     test('elements should be dequeued in first-in, first-out order', () => {
       const q = createQueue<number>();
+
       q.enqueue(1); // internal: [1]
+
       q.enqueue(2); // internal: [1, 2]
+
       q.enqueue(3); // internal: [1, 2, 3]
 
       expect(q.size).toBe(3);
@@ -105,17 +119,21 @@ describe('Queue test', () => {
       let mut_result = q.dequeue(); // Dequeues 1 (first in)
 
       expect(Optional.isSome(mut_result) && mut_result.value === 1).toBe(true);
+
       expect(q.size).toBe(2);
 
       mut_result = q.dequeue(); // Dequeues 2
 
       expect(Optional.isSome(mut_result) && mut_result.value === 2).toBe(true);
+
       expect(q.size).toBe(1);
 
       mut_result = q.dequeue(); // Dequeues 3
 
       expect(Optional.isSome(mut_result) && mut_result.value === 3).toBe(true);
+
       expect(q.size).toBe(0);
+
       expect(q.isEmpty).toBe(true);
 
       mut_result = q.dequeue();
@@ -147,6 +165,7 @@ describe('Queue test', () => {
       const q = createQueue<string>();
 
       q.enqueue('A');
+
       q.enqueue('B');
 
       const result1 = q.dequeue();
@@ -154,6 +173,7 @@ describe('Queue test', () => {
       expect(Optional.isSome(result1) && result1.value === 'A').toBe(true);
 
       q.enqueue('C');
+
       q.enqueue('D');
 
       const result2 = q.dequeue();
@@ -183,19 +203,27 @@ describe('Queue test', () => {
 
       // Remove first 3 elements
       expect(Optional.unwrap(q.dequeue())).toBe(1);
+
       expect(Optional.unwrap(q.dequeue())).toBe(2);
+
       expect(Optional.unwrap(q.dequeue())).toBe(3);
 
       // Add more elements (this should wrap around in the buffer)
       q.enqueue(6);
+
       q.enqueue(7);
+
       q.enqueue(8);
 
       // Verify FIFO order is maintained
       expect(Optional.unwrap(q.dequeue())).toBe(4);
+
       expect(Optional.unwrap(q.dequeue())).toBe(5);
+
       expect(Optional.unwrap(q.dequeue())).toBe(6);
+
       expect(Optional.unwrap(q.dequeue())).toBe(7);
+
       expect(Optional.unwrap(q.dequeue())).toBe(8);
 
       expect(q.isEmpty).toBe(true);
@@ -247,6 +275,7 @@ describe('Queue test', () => {
       for (const i of range(51, 101)) {
         expect(Optional.unwrap(q.dequeue())).toBe(i);
       }
+
       for (const i of range(101, 151)) {
         expect(Optional.unwrap(q.dequeue())).toBe(i);
       }
@@ -268,12 +297,14 @@ describe('Queue test', () => {
         expect(Optional.isSome(result) && result.value === `item-${i}`).toBe(
           true,
         );
+
         expect(q.isEmpty).toBe(true);
       }
     });
 
     test('should handle large initial values array', () => {
       const largeArray = Arr.range(1, asUint32(51));
+
       const q = createQueue(largeArray);
 
       expect(q.size).toBe(50);
@@ -288,6 +319,7 @@ describe('Queue test', () => {
 
     test('should properly clean up references for garbage collection', () => {
       const q = createQueue<{ id: number }>();
+
       const objects = Arr.seq(10).map((i) => ({ id: i }));
 
       // Add all objects

package/src/collections/stack.mts

@@ -45,21 +45,28 @@ export type Stack<T> = Readonly<{
    * const stack = createStack<string>();
    *
    * assert.ok(stack.isEmpty);
+   *
    * assert(stack.size === 0);
    *
    * stack.push('first');
+   *
    * // eslint-disable-next-line unicorn/prefer-single-call
    * stack.push('second');
    *
    * assert.notOk(stack.isEmpty);
+   *
    * assert(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(seededStack.size === 3);
+   *
    * assert.deepStrictEqual(seededStack.pop(), Optional.some(30));
    * ```
    */
@@ -74,21 +81,28 @@ export type Stack<T> = Readonly<{
    * const stack = createStack<string>();
    *
    * assert.ok(stack.isEmpty);
+   *
    * assert(stack.size === 0);
    *
    * stack.push('first');
+   *
    * // eslint-disable-next-line unicorn/prefer-single-call
    * stack.push('second');
    *
    * assert.notOk(stack.isEmpty);
+   *
    * assert(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(seededStack.size === 3);
+   *
    * assert.deepStrictEqual(seededStack.pop(), Optional.some(30));
    * ```
    */
@@ -103,21 +117,28 @@ export type Stack<T> = Readonly<{
    * const stack = createStack<string>();
    *
    * assert.ok(stack.isEmpty);
+   *
    * assert(stack.size === 0);
    *
    * stack.push('first');
+   *
    * // eslint-disable-next-line unicorn/prefer-single-call
    * stack.push('second');
    *
    * assert.notOk(stack.isEmpty);
+   *
    * assert(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(seededStack.size === 3);
+   *
    * assert.deepStrictEqual(seededStack.pop(), Optional.some(30));
    * ```
    *
@@ -135,21 +156,28 @@ export type Stack<T> = Readonly<{
    * const stack = createStack<string>();
    *
    * assert.ok(stack.isEmpty);
+   *
    * assert(stack.size === 0);
    *
    * stack.push('first');
+   *
    * // eslint-disable-next-line unicorn/prefer-single-call
    * stack.push('second');
    *
    * assert.notOk(stack.isEmpty);
+   *
    * assert(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(seededStack.size === 3);
+   *
    * assert.deepStrictEqual(seededStack.pop(), Optional.some(30));
    * ```
    *
@@ -197,7 +225,9 @@ class StackClass<T> implements Stack<T> {
       { length: initialCapacity },
       () => undefined,
     );
+
     this.#mut_size = asUint32(0);
+
     this.#capacity = initialCapacity;
 
     // Add initial values
@@ -236,8 +266,10 @@ class StackClass<T> implements Stack<T> {
     }
 
     this.#mut_size = Uint32.sub(this.#mut_size, 1);
+
     // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
     const element = this.#buffer[this.#mut_size]!;
+
     this.#buffer[this.#mut_size] = undefined; // Clear reference for garbage collection
 
     return Optional.some(element);
@@ -267,6 +299,7 @@ class StackClass<T> implements Stack<T> {
     }
 
     this.#buffer[this.#mut_size] = value;
+
     this.#mut_size = Uint32.add(this.#mut_size, 1);
   }
 
@@ -277,6 +310,7 @@ class StackClass<T> implements Stack<T> {
    */
   #resize(): void {
     const newCapacity = asUint32(this.#capacity * 2);
+
     const newBuffer = Array.from<unknown, T | undefined>(
       { length: newCapacity },
       () => undefined,
@@ -288,6 +322,7 @@ class StackClass<T> implements Stack<T> {
     }
 
     this.#buffer = newBuffer;
+
     this.#capacity = newCapacity;
   }
 }
@@ -322,21 +357,28 @@ class StackClass<T> implements Stack<T> {
  * const stack = createStack<string>();
  *
  * assert.ok(stack.isEmpty);
+ *
  * assert(stack.size === 0);
  *
  * stack.push('first');
+ *
  * // eslint-disable-next-line unicorn/prefer-single-call
  * stack.push('second');
  *
  * assert.notOk(stack.isEmpty);
+ *
  * assert(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(seededStack.size === 3);
+ *
  * assert.deepStrictEqual(seededStack.pop(), Optional.some(30));
  * ```
  *