ts-data-forge 1.0.0 → 1.0.1

package/dist/collections/queue.mjs

@@ -0,0 +1,317 @@
+import { Arr } from '../array/array-utils.mjs';
+import '../array/tuple-utils.mjs';
+import { Optional } from '../functional/optional.mjs';
+import '../functional/result.mjs';
+import '../number/branded-types/finite-number.mjs';
+import '../number/branded-types/int.mjs';
+import '../number/branded-types/int16.mjs';
+import '../number/branded-types/int32.mjs';
+import '../number/branded-types/non-negative-finite-number.mjs';
+import '../number/branded-types/non-negative-int16.mjs';
+import '../number/branded-types/non-negative-int32.mjs';
+import '../number/branded-types/non-zero-finite-number.mjs';
+import '../number/branded-types/non-zero-int.mjs';
+import '../number/branded-types/non-zero-int16.mjs';
+import '../number/branded-types/non-zero-int32.mjs';
+import '../number/branded-types/non-zero-safe-int.mjs';
+import '../number/branded-types/non-zero-uint16.mjs';
+import '../number/branded-types/non-zero-uint32.mjs';
+import '../number/branded-types/positive-finite-number.mjs';
+import '../number/branded-types/positive-int.mjs';
+import '../number/branded-types/positive-int16.mjs';
+import '../number/branded-types/positive-int32.mjs';
+import '../number/branded-types/positive-safe-int.mjs';
+import '../number/branded-types/positive-uint16.mjs';
+import '../number/branded-types/positive-uint32.mjs';
+import '../number/branded-types/safe-int.mjs';
+import '../number/branded-types/safe-uint.mjs';
+import '../number/branded-types/uint.mjs';
+import '../number/branded-types/uint16.mjs';
+import { asUint32 } from '../number/branded-types/uint32.mjs';
+import '../number/enum/int8.mjs';
+import '../number/enum/uint8.mjs';
+import '../number/num.mjs';
+import '../number/refined-number-utils.mjs';
+import { castMutable } from '../others/cast-mutable.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 Circular buffer to store queue elements. */
+    #buffer;
+    /** @internal Index of the first element (front of queue). */
+    #head;
+    /** @internal Index where the next element will be added (back of queue). */
+    #tail;
+    /** @internal Current number of elements in the queue. */
+    #mut_size;
+    /** @internal Current capacity of the buffer. */
+    #capacity;
+    /** @internal Initial capacity for new queues. */
+    static #INITIAL_CAPACITY = 8;
+    /**
+     * 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.#buffer = castMutable(Arr.create(initialCapacity, undefined));
+        this.#head = 0;
+        this.#tail = 0;
+        this.#mut_size = 0;
+        this.#capacity = initialCapacity;
+        // Add initial values
+        for (const value of initialValues) {
+            this.enqueue(value);
+        }
+    }
+    /** @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.
+     *
+     * @example
+     * ```typescript
+     * const queue = createQueue<string>();
+     *
+     * // Add some elements
+     * queue.enqueue("first");
+     * queue.enqueue("second");
+     * queue.enqueue("third");
+     *
+     * // Remove elements in FIFO order
+     * const first = queue.dequeue();
+     * if (first.isSome) {
+     *   console.log(first.value); // "first"
+     * }
+     *
+     * const second = queue.dequeue().unwrap(); // "second"
+     * console.log(queue.size); // 1
+     *
+     * // Safe handling of empty queue
+     * const emptyQueue = createQueue<number>();
+     * const result = emptyQueue.dequeue();
+     * if (result.isNone) {
+     *   console.log("Queue is empty");
+     * }
+     * ```
+     */
+    dequeue() {
+        if (this.isEmpty) {
+            return Optional.none;
+        }
+        // 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);
+    }
+    /**
+     * 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.
+     *
+     * @example
+     * ```typescript
+     * const taskQueue = createQueue<string>();
+     *
+     * // Add tasks in order of arrival
+     * taskQueue.enqueue("Process order #1001");  // O(1)
+     * taskQueue.enqueue("Send notification");    // O(1)
+     * taskQueue.enqueue("Update inventory");     // O(1)
+     *
+     * console.log(taskQueue.size); // 3
+     *
+     * // Tasks will be processed in the order they were added
+     * while (!taskQueue.isEmpty) {
+     *   const task = taskQueue.dequeue().unwrap();
+     *   console.log(`Executing: ${task}`);
+     * }
+     *
+     * // High-volume enqueueing (demonstrates amortized O(1) performance)
+     * const dataQueue = createQueue<number>();
+     *
+     * for (let i = 0; i < 1000000; i++) {
+     *   dataQueue.enqueue(i); // Each operation is O(1) amortized
+     * }
+     *
+     * console.log(dataQueue.size); // 1000000
+     * ```
+     */
+    enqueue(value) {
+        // Resize if buffer is full
+        if (this.#mut_size === this.#capacity) {
+            this.#resize();
+        }
+        this.#buffer[this.#tail] = value;
+        this.#tail = (this.#tail + 1) % this.#capacity;
+        this.#mut_size += 1;
+    }
+    /**
+     * @internal
+     * Resizes the circular buffer when it becomes full.
+     * Doubles the capacity and reorganizes elements to maintain queue order.
+     */
+    #resize() {
+        const newCapacity = asUint32(this.#capacity * 2);
+        const newBuffer = castMutable(Arr.create(newCapacity, undefined));
+        // Copy elements in order from head to tail
+        for (let i = 0; i < this.#mut_size; i++) {
+            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;
+    }
+}
+/**
+ * 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
+ *
+ * @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.
+ *
+ * @example
+ * ```typescript
+ * import { createQueue } from './queue';
+ *
+ * // Example 1: Basic FIFO workflow
+ * const requestQueue = createQueue<string>();
+ *
+ * // Add requests to the queue
+ * requestQueue.enqueue("GET /api/users");     // O(1)
+ * requestQueue.enqueue("POST /api/orders");   // O(1)
+ * requestQueue.enqueue("DELETE /api/cache");  // O(1)
+ *
+ * // Process requests in order
+ * while (!requestQueue.isEmpty) {
+ *   const request = requestQueue.dequeue().unwrap(); // O(1)
+ *   console.log(`Processing: ${request}`);
+ * }
+ * // Output:
+ * // Processing: GET /api/users
+ * // Processing: POST /api/orders
+ * // Processing: DELETE /api/cache
+ *
+ * // Example 2: High-throughput event processing
+ * type Event = { timestamp: number; type: string; data: any };
+ * const eventQueue = createQueue<Event>();
+ *
+ * // Simulate high-volume event ingestion
+ * for (let i = 0; i < 10000; i++) {
+ *   eventQueue.enqueue({
+ *     timestamp: Date.now(),
+ *     type: `event-${i % 5}`,
+ *     data: { value: i }
+ *   }); // Each enqueue is O(1) amortized
+ * }
+ *
+ * // Process events efficiently
+ * let processedCount = 0;
+ * while (!eventQueue.isEmpty) {
+ *   const event = eventQueue.dequeue().unwrap(); // O(1)
+ *   // Process event...
+ *   processedCount++;
+ * }
+ * console.log(`Processed ${processedCount} events`); // 10000
+ *
+ * // Example 3: Queue with pre-populated data
+ * const priorityTasks = createQueue<string>([
+ *   "Initialize system",
+ *   "Load configuration",
+ *   "Start services",
+ *   "Begin processing"
+ * ]);
+ *
+ * console.log(priorityTasks.size); // Output: 4
+ *
+ * // Execute tasks in initialization order
+ * while (!priorityTasks.isEmpty) {
+ *   const task = priorityTasks.dequeue().unwrap();
+ *   console.log(`Executing: ${task}`);
+ * }
+ *
+ * // Example 4: Producer-Consumer pattern
+ * const workQueue = createQueue<() => Promise<void>>();
+ *
+ * // Producer: Add work items
+ * const addWork = (workFn: () => Promise<void>) => {
+ *   workQueue.enqueue(workFn);
+ * };
+ *
+ * // Consumer: Process work items
+ * const processWork = async () => {
+ *   while (!workQueue.isEmpty) {
+ *     const workItem = workQueue.dequeue().unwrap();
+ *     await workItem();
+ *   }
+ * };
+ *
+ * // Add some work
+ * addWork(async () => console.log("Work item 1"));
+ * addWork(async () => console.log("Work item 2"));
+ *
+ * // Process the work
+ * await processWork();
+ * ```
+ */
+const createQueue = (initialValues) => new QueueClass(initialValues);
+
+export { createQueue };
+//# sourceMappingURL=queue.mjs.map

package/dist/collections/queue.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"queue.mjs","sources":["../../src/collections/queue.mts"],"sourcesContent":[null],"names":[],"mappings":"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"}

package/dist/collections/stack.d.mts

@@ -0,0 +1,210 @@
+import { Optional } from '../functional/index.mjs';
+/**
+ * Interface for a high-performance stack with LIFO (Last-In, First-Out) 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.
+ *
+ * @example
+ * ```typescript
+ * import { createStack, Stack } from './stack';
+ *
+ * // Example 1: Basic LIFO operations
+ * const operationStack: Stack<string> = createStack<string>();
+ *
+ * operationStack.push("operation1");  // Add to top
+ * operationStack.push("operation2");  // Add to top
+ * operationStack.push("operation3");  // Add to top
+ *
+ * console.log(operationStack.size); // Output: 3
+ *
+ * // Process operations in LIFO order
+ * console.log(operationStack.pop().unwrap()); // "operation3" (last in, first out)
+ * console.log(operationStack.pop().unwrap()); // "operation2"
+ * console.log(operationStack.size); // Output: 1
+ *
+ * // Example 2: Undo functionality
+ * type Action = { type: string; data: any; timestamp: number };
+ * const undoStack: Stack<Action> = createStack<Action>();
+ *
+ * undoStack.push({ type: "delete", data: { id: 123 }, timestamp: Date.now() });
+ * undoStack.push({ type: "edit", data: { field: "name", oldValue: "old" }, timestamp: Date.now() });
+ *
+ * // Undo last action
+ * if (!undoStack.isEmpty) {
+ *   const lastAction = undoStack.pop().unwrap();
+ *   console.log(`Undoing: ${lastAction.type}`);
+ * }
+ * ```
+ */
+export type Stack<T> = Readonly<{
+    /** Checks if the stack is empty. */
+    isEmpty: boolean;
+    /** The number of elements in the stack. */
+    size: SizeType.Arr;
+    /**
+     * Removes and returns the element at the top of the stack.
+     * @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.
+     * @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
+ *
+ * @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.
+ *
+ * @example
+ * ```typescript
+ * import { createStack } from './stack';
+ *
+ * // Example 1: Function call simulation
+ * type FunctionCall = { name: string; args: any[]; context: any };
+ * const callStack = createStack<FunctionCall>();
+ *
+ * // Simulate function calls (push onto stack)
+ * callStack.push({ name: "main", args: [], context: {} });              // O(1)
+ * callStack.push({ name: "processData", args: [data], context: {} });   // O(1)
+ * callStack.push({ name: "validateInput", args: [input], context: {} }); // O(1)
+ *
+ * // Simulate function returns (pop from stack)
+ * while (!callStack.isEmpty) {
+ *   const call = callStack.pop().unwrap(); // O(1)
+ *   console.log(`Returning from: ${call.name}`);
+ * }
+ * // Output:
+ * // Returning from: validateInput
+ * // Returning from: processData
+ * // Returning from: main
+ *
+ * // Example 2: Expression evaluation with operator precedence
+ * const operatorStack = createStack<string>();
+ * const operandStack = createStack<number>();
+ *
+ * // Simulate parsing "3 + 4 * 2"
+ * operandStack.push(3);
+ * operatorStack.push("+");
+ * operandStack.push(4);
+ * operatorStack.push("*");  // Higher precedence
+ * operandStack.push(2);
+ *
+ * // Process higher precedence first (LIFO)
+ * const op = operatorStack.pop().unwrap(); // "*"
+ * const b = operandStack.pop().unwrap();   // 2
+ * const a = operandStack.pop().unwrap();   // 4
+ * operandStack.push(a * b); // Push result: 8
+ *
+ * // Example 3: Undo/Redo functionality
+ * type EditAction = {
+ *   type: 'insert' | 'delete' | 'modify';
+ *   position: number;
+ *   oldValue: string;
+ *   newValue: string;
+ * };
+ *
+ * const undoStack = createStack<EditAction>();
+ * const redoStack = createStack<EditAction>();
+ *
+ * // Perform edits (push to undo stack)
+ * const edit1: EditAction = { type: 'insert', position: 0, oldValue: '', newValue: 'Hello' };
+ * const edit2: EditAction = { type: 'insert', position: 5, oldValue: '', newValue: ' World' };
+ *
+ * undoStack.push(edit1);
+ * undoStack.push(edit2);
+ *
+ * // Undo last edit
+ * if (!undoStack.isEmpty) {
+ *   const lastEdit = undoStack.pop().unwrap();
+ *   redoStack.push(lastEdit);
+ *   console.log(`Undid: ${lastEdit.type} at position ${lastEdit.position}`);
+ * }
+ *
+ * // Example 4: High-throughput data processing
+ * const processingStack = createStack<number>();
+ *
+ * // Add large amount of data (demonstrates amortized O(1) performance)
+ * for (let i = 0; i < 100000; i++) {
+ *   processingStack.push(i); // Each push is O(1) amortized
+ * }
+ *
+ * // Process data in LIFO order
+ * let processedCount = 0;
+ * while (!processingStack.isEmpty) {
+ *   const value = processingStack.pop().unwrap(); // O(1)
+ *   // Process value...
+ *   processedCount++;
+ * }
+ * console.log(`Processed ${processedCount} items`); // 100000
+ *
+ * // Example 5: Stack with pre-populated data
+ * const historyStack = createStack<string>([
+ *   "page1.html",
+ *   "page2.html",
+ *   "page3.html",
+ *   "page4.html"
+ * ]);
+ *
+ * console.log(historyStack.size); // Output: 4
+ *
+ * // Navigate back through history (LIFO order)
+ * while (!historyStack.isEmpty) {
+ *   const page = historyStack.pop().unwrap();
+ *   console.log(`Going back to: ${page}`);
+ * }
+ * // Output:
+ * // Going back to: page4.html (last added, first removed)
+ * // Going back to: page3.html
+ * // Going back to: page2.html
+ * // Going back to: page1.html
+ * ```
+ */
+export declare const createStack: <T>(initialValues?: readonly T[]) => Stack<T>;
+//# sourceMappingURL=stack.d.mts.map

package/dist/collections/stack.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stack.d.mts","sourceRoot":"","sources":["../../src/collections/stack.mts"],"names":[],"mappings":"AACA,OAAO,EAAE,QAAQ,EAAE,MAAM,yBAAyB,CAAC;AAInD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2DG;AACH,MAAM,MAAM,KAAK,CAAC,CAAC,IAAI,QAAQ,CAAC;IAC9B,oCAAoC;IACpC,OAAO,EAAE,OAAO,CAAC;IAEjB,2CAA2C;IAC3C,IAAI,EAAE,QAAQ,CAAC,GAAG,CAAC;IAEnB;;;OAGG;IACH,GAAG,EAAE,MAAM,QAAQ,CAAC,CAAC,CAAC,CAAC;IAEvB;;;OAGG;IACH,IAAI,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,IAAI,CAAC;CAC1B,CAAC,CAAC;AA+MH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkIG;AACH,eAAO,MAAM,WAAW,GAAI,CAAC,EAAG,gBAAgB,SAAS,CAAC,EAAE,KAAG,KAAK,CAAC,CAAC,CACpC,CAAC"}