auxilium 1.0.0

package/dist/priorityQueue.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Generic priority queue implemented as a binary heap.
+ * By default it behaves as a min-heap for numbers.
+ *
+ * @example
+ * const pq = new PriorityQueue<number>();
+ * pq.enqueue(3);
+ * pq.enqueue(1);
+ * pq.enqueue(2);
+ * pq.dequeue(); // 1
+ */
+export declare class PriorityQueue<T> {
+    private heap;
+    private readonly compare;
+    constructor(compare?: (a: T, b: T) => number);
+    /**
+     * Number of items in the queue.
+     */
+    get length(): number;
+    /**
+     * Returns true when the queue has no items.
+     */
+    isEmpty(): boolean;
+    /**
+     * Adds an item to the queue.
+     */
+    enqueue(item: T): void;
+    /**
+     * Removes and returns the highest priority item from the queue.
+     * Returns undefined when the queue is empty.
+     */
+    dequeue(): T | undefined;
+    /**
+     * Returns the highest priority item without removing it.
+     */
+    peek(): T | undefined;
+    /**
+     * Removes all items from the queue.
+     */
+    clear(): void;
+    private bubbleUp;
+    private bubbleDown;
+}

package/dist/priorityQueue.js

@@ -0,0 +1,99 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PriorityQueue = void 0;
+/**
+ * Generic priority queue implemented as a binary heap.
+ * By default it behaves as a min-heap for numbers.
+ *
+ * @example
+ * const pq = new PriorityQueue<number>();
+ * pq.enqueue(3);
+ * pq.enqueue(1);
+ * pq.enqueue(2);
+ * pq.dequeue(); // 1
+ */
+class PriorityQueue {
+    constructor(compare) {
+        this.heap = [];
+        // Default: numeric ascending, otherwise fallback to 0 (no reordering)
+        this.compare =
+            compare ??
+                ((a, b) => typeof a === 'number' && typeof b === 'number' ? a - b : 0);
+    }
+    /**
+     * Number of items in the queue.
+     */
+    get length() {
+        return this.heap.length;
+    }
+    /**
+     * Returns true when the queue has no items.
+     */
+    isEmpty() {
+        return this.heap.length === 0;
+    }
+    /**
+     * Adds an item to the queue.
+     */
+    enqueue(item) {
+        this.heap.push(item);
+        this.bubbleUp(this.heap.length - 1);
+    }
+    /**
+     * Removes and returns the highest priority item from the queue.
+     * Returns undefined when the queue is empty.
+     */
+    dequeue() {
+        if (this.heap.length === 0)
+            return undefined;
+        const top = this.heap[0];
+        const last = this.heap.pop();
+        if (this.heap.length > 0) {
+            this.heap[0] = last;
+            this.bubbleDown(0);
+        }
+        return top;
+    }
+    /**
+     * Returns the highest priority item without removing it.
+     */
+    peek() {
+        return this.heap[0];
+    }
+    /**
+     * Removes all items from the queue.
+     */
+    clear() {
+        this.heap = [];
+    }
+    bubbleUp(index) {
+        while (index > 0) {
+            const parent = Math.floor((index - 1) / 2);
+            if (this.compare(this.heap[index], this.heap[parent]) >= 0) {
+                break;
+            }
+            [this.heap[index], this.heap[parent]] = [this.heap[parent], this.heap[index]];
+            index = parent;
+        }
+    }
+    bubbleDown(index) {
+        const length = this.heap.length;
+        while (true) {
+            const left = index * 2 + 1;
+            const right = index * 2 + 2;
+            let smallest = index;
+            if (left < length && this.compare(this.heap[left], this.heap[smallest]) < 0) {
+                smallest = left;
+            }
+            if (right < length && this.compare(this.heap[right], this.heap[smallest]) < 0) {
+                smallest = right;
+            }
+            if (smallest === index)
+                break;
+            [this.heap[index], this.heap[smallest]] = [this.heap[smallest], this.heap[index]];
+            index = smallest;
+        }
+    }
+}
+exports.PriorityQueue = PriorityQueue;
+//# sourceMappingURL=priorityQueue.js.map

package/dist/priorityQueue.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"priorityQueue.js","sourceRoot":"","sources":["../src/priorityQueue.ts"],"names":[],"mappings":"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"}

package/dist/queue.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Simple generic FIFO queue with amortized O(1) enqueue/dequeue.
+ *
+ * @example
+ * const q = new Queue<number>();
+ * q.enqueue(1);
+ * q.enqueue(2);
+ * q.dequeue(); // 1
+ * q.dequeue(); // 2
+ */
+export declare class Queue<T> {
+    private items;
+    private head;
+    /**
+     * Adds an item to the back of the queue.
+     */
+    enqueue(item: T): void;
+    /**
+     * Removes and returns the item at the front of the queue.
+     * Returns undefined when the queue is empty.
+     */
+    dequeue(): T | undefined;
+    /**
+     * Returns the item at the front of the queue without removing it.
+     */
+    peek(): T | undefined;
+    /**
+     * Returns the number of items currently in the queue.
+     */
+    get length(): number;
+    /**
+     * Returns true when the queue has no items.
+     */
+    isEmpty(): boolean;
+    /**
+     * Removes all items from the queue.
+     */
+    clear(): void;
+}

package/dist/queue.js

@@ -0,0 +1,69 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Queue = void 0;
+/**
+ * Simple generic FIFO queue with amortized O(1) enqueue/dequeue.
+ *
+ * @example
+ * const q = new Queue<number>();
+ * q.enqueue(1);
+ * q.enqueue(2);
+ * q.dequeue(); // 1
+ * q.dequeue(); // 2
+ */
+class Queue {
+    constructor() {
+        this.items = [];
+        this.head = 0;
+    }
+    /**
+     * Adds an item to the back of the queue.
+     */
+    enqueue(item) {
+        this.items.push(item);
+    }
+    /**
+     * Removes and returns the item at the front of the queue.
+     * Returns undefined when the queue is empty.
+     */
+    dequeue() {
+        if (this.isEmpty()) {
+            return undefined;
+        }
+        const value = this.items[this.head];
+        this.head += 1;
+        // Occasionally compact the internal array to avoid unbounded growth.
+        if (this.head > 50 && this.head * 2 > this.items.length) {
+            this.items = this.items.slice(this.head);
+            this.head = 0;
+        }
+        return value;
+    }
+    /**
+     * Returns the item at the front of the queue without removing it.
+     */
+    peek() {
+        return this.isEmpty() ? undefined : this.items[this.head];
+    }
+    /**
+     * Returns the number of items currently in the queue.
+     */
+    get length() {
+        return this.items.length - this.head;
+    }
+    /**
+     * Returns true when the queue has no items.
+     */
+    isEmpty() {
+        return this.length === 0;
+    }
+    /**
+     * Removes all items from the queue.
+     */
+    clear() {
+        this.items = [];
+        this.head = 0;
+    }
+}
+exports.Queue = Queue;
+//# sourceMappingURL=queue.js.map

package/dist/queue.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"queue.js","sourceRoot":"","sources":["../src/queue.ts"],"names":[],"mappings":";;;AAAA;;;;;;;;;GASG;AACH,MAAa,KAAK;IAAlB;QACU,UAAK,GAAQ,EAAE,CAAC;QAChB,SAAI,GAAG,CAAC,CAAC;IA0DnB,CAAC;IAxDC;;OAEG;IACH,OAAO,CAAC,IAAO;QACb,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACxB,CAAC;IAED;;;OAGG;IACH,OAAO;QACL,IAAI,IAAI,CAAC,OAAO,EAAE,EAAE,CAAC;YACnB,OAAO,SAAS,CAAC;QACnB,CAAC;QAED,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACpC,IAAI,CAAC,IAAI,IAAI,CAAC,CAAC;QAEf,qEAAqE;QACrE,IAAI,IAAI,CAAC,IAAI,GAAG,EAAE,IAAI,IAAI,CAAC,IAAI,GAAG,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,MAAM,EAAE,CAAC;YACxD,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;YACzC,IAAI,CAAC,IAAI,GAAG,CAAC,CAAC;QAChB,CAAC;QAED,OAAO,KAAK,CAAC;IACf,CAAC;IAED;;OAEG;IACH,IAAI;QACF,OAAO,IAAI,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAC5D,CAAC;IAED;;OAEG;IACH,IAAI,MAAM;QACR,OAAO,IAAI,CAAC,KAAK,CAAC,MAAM,GAAG,IAAI,CAAC,IAAI,CAAC;IACvC,CAAC;IAED;;OAEG;IACH,OAAO;QACL,OAAO,IAAI,CAAC,MAAM,KAAK,CAAC,CAAC;IAC3B,CAAC;IAED;;OAEG;IACH,KAAK;QACH,IAAI,CAAC,KAAK,GAAG,EAAE,CAAC;QAChB,IAAI,CAAC,IAAI,GAAG,CAAC,CAAC;IAChB,CAAC;CACF;AA5DD,sBA4DC"}

package/dist/stack.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Simple generic LIFO stack.
+ *
+ * @example
+ * const s = new Stack<number>();
+ * s.push(1);
+ * s.push(2);
+ * s.pop(); // 2
+ * s.pop(); // 1
+ */
+export declare class Stack<T> {
+    private items;
+    /**
+     * Pushes an item on top of the stack.
+     */
+    push(item: T): void;
+    /**
+     * Removes and returns the item from the top of the stack.
+     * Returns undefined when the stack is empty.
+     */
+    pop(): T | undefined;
+    /**
+     * Returns the item at the top of the stack without removing it.
+     */
+    peek(): T | undefined;
+    /**
+     * Returns the number of items currently in the stack.
+     */
+    get length(): number;
+    /**
+     * Returns true when the stack has no items.
+     */
+    isEmpty(): boolean;
+    /**
+     * Removes all items from the stack.
+     */
+    clear(): void;
+}

package/dist/stack.js

@@ -0,0 +1,57 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Stack = void 0;
+/**
+ * Simple generic LIFO stack.
+ *
+ * @example
+ * const s = new Stack<number>();
+ * s.push(1);
+ * s.push(2);
+ * s.pop(); // 2
+ * s.pop(); // 1
+ */
+class Stack {
+    constructor() {
+        this.items = [];
+    }
+    /**
+     * Pushes an item on top of the stack.
+     */
+    push(item) {
+        this.items.push(item);
+    }
+    /**
+     * Removes and returns the item from the top of the stack.
+     * Returns undefined when the stack is empty.
+     */
+    pop() {
+        return this.items.pop();
+    }
+    /**
+     * Returns the item at the top of the stack without removing it.
+     */
+    peek() {
+        return this.items.length ? this.items[this.items.length - 1] : undefined;
+    }
+    /**
+     * Returns the number of items currently in the stack.
+     */
+    get length() {
+        return this.items.length;
+    }
+    /**
+     * Returns true when the stack has no items.
+     */
+    isEmpty() {
+        return this.items.length === 0;
+    }
+    /**
+     * Removes all items from the stack.
+     */
+    clear() {
+        this.items = [];
+    }
+}
+exports.Stack = Stack;
+//# sourceMappingURL=stack.js.map

package/dist/stack.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"stack.js","sourceRoot":"","sources":["../src/stack.ts"],"names":[],"mappings":";;;AAAA;;;;;;;;;GASG;AACH,MAAa,KAAK;IAAlB;QACU,UAAK,GAAQ,EAAE,CAAC;IA4C1B,CAAC;IA1CC;;OAEG;IACH,IAAI,CAAC,IAAO;QACV,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACxB,CAAC;IAED;;;OAGG;IACH,GAAG;QACD,OAAO,IAAI,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC;IAC1B,CAAC;IAED;;OAEG;IACH,IAAI;QACF,OAAO,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;IAC3E,CAAC;IAED;;OAEG;IACH,IAAI,MAAM;QACR,OAAO,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC;IAC3B,CAAC;IAED;;OAEG;IACH,OAAO;QACL,OAAO,IAAI,CAAC,KAAK,CAAC,MAAM,KAAK,CAAC,CAAC;IACjC,CAAC;IAED;;OAEG;IACH,KAAK;QACH,IAAI,CAAC,KAAK,GAAG,EAAE,CAAC;IAClB,CAAC;CACF;AA7CD,sBA6CC"}

package/dist/utils/array.d.ts

@@ -0,0 +1,104 @@
+/**
+ * Returns a new array with duplicate items removed.
+ * Keeps the first occurrence of each item and preserves order.
+ *
+ * @example
+ * uniq([1, 2, 2, 3]); // [1, 2, 3]
+ */
+export declare function uniq<T>(items: readonly T[]): T[];
+/**
+ * Splits an array into chunks of a given size.
+ * If size is <= 0, returns the whole array as a single chunk.
+ *
+ * @example
+ * chunk([1, 2, 3, 4, 5], 2); // [[1, 2], [3, 4], [5]]
+ */
+export declare function chunk<T>(items: readonly T[], size: number): T[][];
+/**
+ * Removes falsy-like values (null, undefined, false) from an array.
+ *
+ * @example
+ * compact([0, 1, null, 2, undefined, 3, false]); // [0, 1, 2, 3]
+ */
+export declare function compact<T>(items: readonly (T | null | undefined | false)[]): T[];
+/**
+ * Flattens an array one level deep.
+ *
+ * @example
+ * flat([1, [2, 3], 4]); // [1, 2, 3, 4]
+ */
+export declare function flat<T>(items: readonly (T | T[])[]): T[];
+/**
+ * Returns the first item of an array, or undefined when empty.
+ *
+ * @example
+ * first([1, 2, 3]); // 1
+ */
+export declare function first<T>(items: readonly T[]): T | undefined;
+/**
+ * Returns the last item of an array, or undefined when empty.
+ *
+ * @example
+ * last([1, 2, 3]); // 3
+ */
+export declare function last<T>(items: readonly T[]): T | undefined;
+/**
+ * Groups an array of objects by a specific key.
+ *
+ * @example
+ * const users = [
+ *   { id: 1, role: 'admin' },
+ *   { id: 2, role: 'user' },
+ *   { id: 3, role: 'admin' }
+ * ];
+ *
+ * groupBy(users, 'role');
+ * // {
+ * //   admin: [{ id: 1, role: 'admin' }, { id: 3, role: 'admin' }],
+ * //   user: [{ id: 2, role: 'user' }]
+ * // }
+ */
+export declare function groupBy<T extends Record<string, any>, K extends keyof T>(items: readonly T[], key: K): Record<T[K] & PropertyKey, T[]>;
+/**
+ * Splits items into two arrays based on a predicate.
+ * The first array contains items where predicate(item) is true,
+ * the second where it is false.
+ *
+ * @example
+ * partition([1, 2, 3, 4], (n) => n % 2 === 0);
+ * // [[2, 4], [1, 3]]
+ */
+export declare function partition<T>(items: readonly T[], predicate: (item: T, index: number) => boolean): [T[], T[]];
+/**
+ * Returns the intersection of two arrays (items present in both).
+ *
+ * @example
+ * intersect([1, 2, 3], [2, 3, 4]); // [2, 3]
+ */
+export declare function intersect<T>(a: readonly T[], b: readonly T[]): T[];
+/**
+ * Returns the difference of two arrays (items in a that are not in b).
+ *
+ * @example
+ * difference([1, 2, 3], [2]); // [1, 3]
+ */
+export declare function difference<T>(a: readonly T[], b: readonly T[]): T[];
+/**
+ * Returns a new array with unique items based on a key selector.
+ *
+ * @example
+ * uniqueBy(
+ *   [{ id: 1 }, { id: 1 }, { id: 2 }],
+ *   (item) => item.id
+ * ); // [{ id: 1 }, { id: 2 }]
+ */
+export declare function uniqueBy<T, K extends PropertyKey>(items: readonly T[], keyFn: (item: T) => K): T[];
+/**
+ * Returns a new array sorted by a user-provided selector.
+ * Does not mutate the original array.
+ *
+ * @example
+ * sortBy(users, u => u.age);
+ * sortBy(users, u => u.name.toLowerCase());
+ */
+export declare function sortBy<T, K extends string | number>(items: readonly T[], selector: (item: T) => K, direction?: 'asc' | 'desc'): T[];

package/dist/utils/array.js

@@ -0,0 +1,203 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.uniq = uniq;
+exports.chunk = chunk;
+exports.compact = compact;
+exports.flat = flat;
+exports.first = first;
+exports.last = last;
+exports.groupBy = groupBy;
+exports.partition = partition;
+exports.intersect = intersect;
+exports.difference = difference;
+exports.uniqueBy = uniqueBy;
+exports.sortBy = sortBy;
+/**
+ * Returns a new array with duplicate items removed.
+ * Keeps the first occurrence of each item and preserves order.
+ *
+ * @example
+ * uniq([1, 2, 2, 3]); // [1, 2, 3]
+ */
+function uniq(items) {
+    return Array.from(new Set(items));
+}
+/**
+ * Splits an array into chunks of a given size.
+ * If size is <= 0, returns the whole array as a single chunk.
+ *
+ * @example
+ * chunk([1, 2, 3, 4, 5], 2); // [[1, 2], [3, 4], [5]]
+ */
+function chunk(items, size) {
+    if (size <= 0)
+        return [items.slice()];
+    const result = [];
+    for (let i = 0; i < items.length; i += size) {
+        result.push(items.slice(i, i + size));
+    }
+    return result;
+}
+/**
+ * Removes falsy-like values (null, undefined, false) from an array.
+ *
+ * @example
+ * compact([0, 1, null, 2, undefined, 3, false]); // [0, 1, 2, 3]
+ */
+function compact(items) {
+    return items.filter(Boolean);
+}
+/**
+ * Flattens an array one level deep.
+ *
+ * @example
+ * flat([1, [2, 3], 4]); // [1, 2, 3, 4]
+ */
+function flat(items) {
+    const result = [];
+    for (const item of items) {
+        if (Array.isArray(item)) {
+            result.push(...item);
+        }
+        else {
+            result.push(item);
+        }
+    }
+    return result;
+}
+/**
+ * Returns the first item of an array, or undefined when empty.
+ *
+ * @example
+ * first([1, 2, 3]); // 1
+ */
+function first(items) {
+    return items[0];
+}
+/**
+ * Returns the last item of an array, or undefined when empty.
+ *
+ * @example
+ * last([1, 2, 3]); // 3
+ */
+function last(items) {
+    return items.length ? items[items.length - 1] : undefined;
+}
+/**
+ * Groups an array of objects by a specific key.
+ *
+ * @example
+ * const users = [
+ *   { id: 1, role: 'admin' },
+ *   { id: 2, role: 'user' },
+ *   { id: 3, role: 'admin' }
+ * ];
+ *
+ * groupBy(users, 'role');
+ * // {
+ * //   admin: [{ id: 1, role: 'admin' }, { id: 3, role: 'admin' }],
+ * //   user: [{ id: 2, role: 'user' }]
+ * // }
+ */
+function groupBy(items, key) {
+    const result = {};
+    for (const item of items) {
+        const groupKey = item[key];
+        if (!result[groupKey]) {
+            result[groupKey] = [];
+        }
+        result[groupKey].push(item);
+    }
+    return result;
+}
+/**
+ * Splits items into two arrays based on a predicate.
+ * The first array contains items where predicate(item) is true,
+ * the second where it is false.
+ *
+ * @example
+ * partition([1, 2, 3, 4], (n) => n % 2 === 0);
+ * // [[2, 4], [1, 3]]
+ */
+function partition(items, predicate) {
+    const truthy = [];
+    const falsy = [];
+    items.forEach((item, index) => {
+        if (predicate(item, index)) {
+            truthy.push(item);
+        }
+        else {
+            falsy.push(item);
+        }
+    });
+    return [truthy, falsy];
+}
+/**
+ * Returns the intersection of two arrays (items present in both).
+ *
+ * @example
+ * intersect([1, 2, 3], [2, 3, 4]); // [2, 3]
+ */
+function intersect(a, b) {
+    const setB = new Set(b);
+    return a.filter((item) => setB.has(item));
+}
+/**
+ * Returns the difference of two arrays (items in a that are not in b).
+ *
+ * @example
+ * difference([1, 2, 3], [2]); // [1, 3]
+ */
+function difference(a, b) {
+    const setB = new Set(b);
+    return a.filter((item) => !setB.has(item));
+}
+/**
+ * Returns a new array with unique items based on a key selector.
+ *
+ * @example
+ * uniqueBy(
+ *   [{ id: 1 }, { id: 1 }, { id: 2 }],
+ *   (item) => item.id
+ * ); // [{ id: 1 }, { id: 2 }]
+ */
+function uniqueBy(items, keyFn) {
+    const seen = new Set();
+    const result = [];
+    for (const item of items) {
+        const key = keyFn(item);
+        if (!seen.has(key)) {
+            seen.add(key);
+            result.push(item);
+        }
+    }
+    return result;
+}
+/**
+ * Returns a new array sorted by a user-provided selector.
+ * Does not mutate the original array.
+ *
+ * @example
+ * sortBy(users, u => u.age);
+ * sortBy(users, u => u.name.toLowerCase());
+ */
+function sortBy(items, selector, direction = 'asc') {
+    const result = items.slice();
+    result.sort((a, b) => {
+        const av = selector(a);
+        const bv = selector(b);
+        if (av === bv)
+            return 0;
+        if (av == null)
+            return direction === 'asc' ? 1 : -1;
+        if (bv == null)
+            return direction === 'asc' ? -1 : 1;
+        if (av < bv)
+            return direction === 'asc' ? -1 : 1;
+        if (av > bv)
+            return direction === 'asc' ? 1 : -1;
+        return 0;
+    });
+    return result;
+}
+//# sourceMappingURL=array.js.map

package/dist/utils/array.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"array.js","sourceRoot":"","sources":["../../src/utils/array.ts"],"names":[],"mappings":"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"}