@procedures/collections 0.0.0-stage → 0.2.0

package/dist/utils/factories.js

@@ -0,0 +1,293 @@
+/**
+ * Factory utilities for creating collections.
+ *
+ * Provides convenient factory methods similar to Java's Collections class.
+ * These mirror methods like Collections.emptyList(), singletonList(), etc.
+ */
+import { arrayList, ArrayList } from "../impl/array-list.js";
+import { arrayDeque, ArrayDeque } from "../impl/array-deque.js";
+import { hashMap, HashMap } from "../impl/hash-map.js";
+import { readonly } from "../behaviors/readonly.js";
+import { compose } from "../core/middleware.js";
+// ============================================================================
+// Empty collections
+// ============================================================================
+/**
+ * Returns an empty, immutable list.
+ * Multiple calls return the same instance (singleton pattern).
+ *
+ * @example
+ * const list = emptyList<number>()
+ * list.size // 0
+ * list.add(1) // Error: Cannot modify readonly collection
+ */
+const EMPTY_LIST_CACHE = new Map();
+export function emptyList() {
+    const key = "list";
+    if (!EMPTY_LIST_CACHE.has(key)) {
+        const list = compose(readonly())(arrayList());
+        EMPTY_LIST_CACHE.set(key, list);
+    }
+    return EMPTY_LIST_CACHE.get(key);
+}
+/**
+ * Returns an empty, immutable queue.
+ */
+const EMPTY_QUEUE_CACHE = new Map();
+export function emptyQueue() {
+    const key = "queue";
+    if (!EMPTY_QUEUE_CACHE.has(key)) {
+        const queue = compose(readonly())(arrayDeque());
+        EMPTY_QUEUE_CACHE.set(key, queue);
+    }
+    return EMPTY_QUEUE_CACHE.get(key);
+}
+/**
+ * Returns an empty, immutable map.
+ */
+const EMPTY_MAP_CACHE = new Map();
+export function emptyMap() {
+    const key = "map";
+    if (!EMPTY_MAP_CACHE.has(key)) {
+        const map = compose(readonly())(hashMap());
+        EMPTY_MAP_CACHE.set(key, map);
+    }
+    return EMPTY_MAP_CACHE.get(key);
+}
+// ============================================================================
+// Singleton collections (single element)
+// ============================================================================
+/**
+ * Returns an immutable list containing only the specified element.
+ *
+ * @example
+ * const list = singletonList(42)
+ * list.size // 1
+ * list.get(0) // 42
+ * list.add(2) // Error: Cannot modify readonly collection
+ */
+export function singletonList(element) {
+    const list = arrayList();
+    list.add(element);
+    return compose(readonly())(list);
+}
+/**
+ * Returns an immutable map containing only the specified key-value mapping.
+ */
+export function singletonMap(key, value) {
+    const map = hashMap();
+    map.set(key, value);
+    return compose(readonly())(map);
+}
+// ============================================================================
+// N-copies collections
+// ============================================================================
+/**
+ * Returns an immutable list consisting of n copies of the specified element.
+ *
+ * @example
+ * const list = nCopies(5, 'hello')
+ * list.size // 5
+ * list.get(2) // 'hello'
+ */
+export function nCopies(n, element) {
+    if (n < 0) {
+        throw new Error(`n must be non-negative, got ${n}`);
+    }
+    const list = arrayList();
+    for (let i = 0; i < n; i++) {
+        list.add(element);
+    }
+    return compose(readonly())(list);
+}
+// ============================================================================
+// Collection creation from iterables
+// ============================================================================
+/**
+ * Creates a new ArrayList from the given elements.
+ *
+ * @example
+ * const list = listOf(1, 2, 3, 4, 5)
+ */
+export function listOf(...elements) {
+    return arrayList(elements);
+}
+/**
+ * Creates a new ArrayDeque from the given elements.
+ */
+export function queueOf(...elements) {
+    return arrayDeque(elements);
+}
+/**
+ * Creates a new HashMap from the given key-value pairs.
+ *
+ * @example
+ * const map = mapOf(['a', 1], ['b', 2], ['c', 3])
+ */
+export function mapOf(...entries) {
+    return hashMap(entries);
+}
+// ============================================================================
+// Mutable collection factories
+// ============================================================================
+/**
+ * Creates a new mutable ArrayList with optional initial elements.
+ *
+ * @example
+ * const list = mutableListOf(1, 2, 3)
+ * list.add(4)
+ */
+export function mutableListOf(...elements) {
+    return arrayList(elements);
+}
+/**
+ * Creates a new mutable HashMap with optional initial entries.
+ */
+export function mutableMapOf(...entries) {
+    return hashMap(entries);
+}
+// ============================================================================
+// Immutable collection factories
+// ============================================================================
+/**
+ * Creates an immutable List from the given elements.
+ *
+ * @example
+ * const list = immutableListOf(1, 2, 3)
+ * list.get(0) // 1
+ * list.add(4) // Error: Cannot modify readonly collection
+ */
+export function immutableListOf(...elements) {
+    if (elements.length === 0) {
+        return emptyList();
+    }
+    if (elements.length === 1) {
+        return singletonList(elements[0]);
+    }
+    const list = arrayList(elements);
+    return compose(readonly())(list);
+}
+/**
+ * Creates an immutable Map from the given entries.
+ */
+export function immutableMapOf(...entries) {
+    if (entries.length === 0) {
+        return emptyMap();
+    }
+    if (entries.length === 1) {
+        return singletonMap(entries[0][0], entries[0][1]);
+    }
+    const map = hashMap(entries);
+    return compose(readonly())(map);
+}
+// ============================================================================
+// Range factories
+// ============================================================================
+/**
+ * Creates a list containing integers from start (inclusive) to end (exclusive).
+ *
+ * @example
+ * const list = range(0, 5) // [0, 1, 2, 3, 4]
+ * const list2 = range(10, 15) // [10, 11, 12, 13, 14]
+ */
+export function range(start, end, step = 1) {
+    if (step === 0) {
+        throw new Error("step cannot be zero");
+    }
+    const list = arrayList();
+    if (step > 0) {
+        for (let i = start; i < end; i += step) {
+            list.add(i);
+        }
+    }
+    else {
+        for (let i = start; i > end; i += step) {
+            list.add(i);
+        }
+    }
+    return list;
+}
+/**
+ * Creates a list containing integers from 0 to n (exclusive).
+ *
+ * @example
+ * const list = rangeTo(5) // [0, 1, 2, 3, 4]
+ */
+export function rangeTo(n) {
+    return range(0, n);
+}
+// ============================================================================
+// Collection builders
+// ============================================================================
+/**
+ * Builder for constructing lists with a fluent API.
+ *
+ * @example
+ * const list = buildList<number>((builder) => {
+ *   builder.add(1)
+ *   builder.add(2)
+ *   if (someCondition) {
+ *     builder.add(3)
+ *   }
+ * })
+ */
+export function buildList(builder) {
+    const list = arrayList();
+    builder(list);
+    return list;
+}
+/**
+ * Builder for constructing maps with a fluent API.
+ */
+export function buildMap(builder) {
+    const map = hashMap();
+    builder(map);
+    return map;
+}
+// ============================================================================
+// Conversion utilities
+// ============================================================================
+/**
+ * Converts an iterable to an ArrayList.
+ *
+ * @example
+ * const set = new Set([1, 2, 3])
+ * const list = toList(set)
+ */
+export function toList(iterable) {
+    return arrayList(iterable);
+}
+export function toMap(iterable, keyExtractor, valueExtractor) {
+    const map = hashMap();
+    for (const item of iterable) {
+        const key = keyExtractor(item);
+        const value = valueExtractor ? valueExtractor(item) : item;
+        map.set(key, value);
+    }
+    return map;
+}
+// ============================================================================
+// Grouping utilities
+// ============================================================================
+/**
+ * Groups elements by a key extractor function.
+ *
+ * @example
+ * const users = [
+ *   { age: 25, name: 'Alice' },
+ *   { age: 30, name: 'Bob' },
+ *   { age: 25, name: 'Charlie' }
+ * ]
+ * const byAge = groupBy(users, u => u.age)
+ * // Map { 25 => [Alice, Charlie], 30 => [Bob] }
+ */
+export function groupBy(iterable, keyExtractor) {
+    const map = hashMap();
+    for (const item of iterable) {
+        const key = keyExtractor(item);
+        const list = map.computeIfAbsent(key, () => arrayList());
+        list.add(item);
+    }
+    return map;
+}
+//# sourceMappingURL=factories.js.map

package/dist/utils/factories.js.map

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

package/dist/utils/helpers.d.ts

@@ -0,0 +1,137 @@
+/**
+ * Common helper utilities for collections.
+ *
+ * Provides shared functionality to reduce code duplication across implementations.
+ */
+import type { Eq } from "../core/traits.js";
+/**
+ * Checks if an index is within valid bounds [0, size).
+ * Throws RangeError if out of bounds.
+ *
+ * @param index The index to check
+ * @param size The size of the collection
+ * @param collectionName Optional name for error message
+ * @throws RangeError if index is out of bounds
+ */
+export declare function checkBounds(index: number, size: number, collectionName?: string): void;
+/**
+ * Checks if an index is valid for insertion [0, size].
+ * Allows index === size for append operations.
+ *
+ * @param index The index to check
+ * @param size The size of the collection
+ * @param collectionName Optional name for error message
+ * @throws RangeError if index is out of bounds
+ */
+export declare function checkInsertBounds(index: number, size: number, collectionName?: string): void;
+/**
+ * Checks if a range [start, end) is valid.
+ *
+ * @param start Start index (inclusive)
+ * @param end End index (exclusive)
+ * @param size The size of the collection
+ * @param collectionName Optional name for error message
+ * @throws RangeError if range is invalid
+ */
+export declare function checkRangeBounds(start: number, end: number, size: number, collectionName?: string): void;
+/**
+ * Finds the index of an element in an array using custom equality.
+ *
+ * @param array The array to search
+ * @param element The element to find
+ * @param eq Equality function
+ * @returns Index of element, or -1 if not found
+ */
+export declare function findIndex<T>(array: T[], element: T, eq: Eq<T>): number;
+/**
+ * Finds the last index of an element in an array using custom equality.
+ *
+ * @param array The array to search
+ * @param element The element to find
+ * @param eq Equality function
+ * @returns Last index of element, or -1 if not found
+ */
+export declare function findLastIndex<T>(array: T[], element: T, eq: Eq<T>): number;
+/**
+ * Checks if an array contains an element using custom equality.
+ *
+ * @param array The array to search
+ * @param element The element to find
+ * @param eq Equality function
+ * @returns true if element is found
+ */
+export declare function arrayContains<T>(array: T[], element: T, eq: Eq<T>): boolean;
+/**
+ * Removes the first occurrence of an element from an array.
+ *
+ * @param array The array to modify
+ * @param element The element to remove
+ * @param eq Equality function
+ * @returns true if element was found and removed
+ */
+export declare function arrayRemove<T>(array: T[], element: T, eq: Eq<T>): boolean;
+/**
+ * Removes all occurrences of an element from an array.
+ *
+ * @param array The array to modify
+ * @param element The element to remove
+ * @param eq Equality function
+ * @returns Number of elements removed
+ */
+export declare function arrayRemoveAll<T>(array: T[], element: T, eq: Eq<T>): number;
+/**
+ * Creates a simple iterator for an array.
+ *
+ * @param array The array to iterate
+ * @returns Iterator over the array
+ */
+export declare function arrayIterator<T>(array: T[]): Iterator<T>;
+/**
+ * Creates a reversed iterator for an array.
+ *
+ * @param array The array to iterate
+ * @returns Reversed iterator over the array
+ */
+export declare function reverseArrayIterator<T>(array: T[]): Iterator<T>;
+/**
+ * Converts an iterable to an array.
+ *
+ * @param iterable The iterable to convert
+ * @returns Array containing all elements
+ */
+export declare function toArray<T>(iterable: Iterable<T>): T[];
+/**
+ * Ensures a value is not null or undefined.
+ *
+ * @param value The value to check
+ * @param message Error message
+ * @returns The non-null value
+ * @throws Error if value is null or undefined
+ */
+export declare function requireNonNull<T>(value: T | null | undefined, message?: string): T;
+/**
+ * Ensures a collection is not empty.
+ *
+ * @param size Current size
+ * @param collectionName Optional name for error message
+ * @throws Error if collection is empty
+ */
+export declare function requireNonEmpty(size: number, collectionName?: string): void;
+/**
+ * Clamps a value between min and max.
+ *
+ * @param value The value to clamp
+ * @param min Minimum value
+ * @param max Maximum value
+ * @returns Clamped value
+ */
+export declare function clamp(value: number, min: number, max: number): number;
+/**
+ * Calculates hash code for a string.
+ * Uses Java's String.hashCode() algorithm.
+ *
+ * @param str The string to hash
+ * @returns Hash code
+ */
+export declare function stringHashCode(str: string): number;
+//# sourceMappingURL=helpers.d.ts.map

package/dist/utils/helpers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"helpers.d.ts","sourceRoot":"","sources":["../../src/utils/helpers.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,EAAE,EAAE,MAAM,mBAAmB,CAAC;AAM5C;;;;;;;;GAQG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,cAAc,GAAE,MAAqB,GAAG,IAAI,CAIpG;AAED;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,cAAc,GAAE,MAAqB,GAAG,IAAI,CAI1G;AAED;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAC9B,KAAK,EAAE,MAAM,EACb,GAAG,EAAE,MAAM,EACX,IAAI,EAAE,MAAM,EACZ,cAAc,GAAE,MAAqB,GACpC,IAAI,CAMN;AAMD;;;;;;;GAOG;AACH,wBAAgB,SAAS,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,EAAE,OAAO,EAAE,CAAC,EAAE,EAAE,EAAE,EAAE,CAAC,CAAC,CAAC,GAAG,MAAM,CAOtE;AAED;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,EAAE,OAAO,EAAE,CAAC,EAAE,EAAE,EAAE,EAAE,CAAC,CAAC,CAAC,GAAG,MAAM,CAO1E;AAED;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,EAAE,OAAO,EAAE,CAAC,EAAE,EAAE,EAAE,EAAE,CAAC,CAAC,CAAC,GAAG,OAAO,CAE3E;AAED;;;;;;;GAOG;AACH,wBAAgB,WAAW,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,EAAE,OAAO,EAAE,CAAC,EAAE,EAAE,EAAE,EAAE,CAAC,CAAC,CAAC,GAAG,OAAO,CAKzE;AAED;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,EAAE,OAAO,EAAE,CAAC,EAAE,EAAE,EAAE,EAAE,CAAC,CAAC,CAAC,GAAG,MAAM,CAS3E;AAMD;;;;;GAKG;AACH,wBAAiB,aAAa,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,GAAG,QAAQ,CAAC,CAAC,CAAC,CAEzD;AAED;;;;;GAKG;AACH,wBAAiB,oBAAoB,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,GAAG,QAAQ,CAAC,CAAC,CAAC,CAIhE;AAED;;;;;GAKG;AACH,wBAAgB,OAAO,CAAC,CAAC,EAAE,QAAQ,EAAE,QAAQ,CAAC,CAAC,CAAC,GAAG,CAAC,EAAE,CAErD;AAMD;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,GAAG,IAAI,GAAG,SAAS,EAAE,OAAO,GAAE,MAA4C,GAAG,CAAC,CAKvH;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,cAAc,GAAE,MAAqB,GAAG,IAAI,CAIzF;AAMD;;;;;;;GAOG;AACH,wBAAgB,KAAK,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAErE;AAED;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAQlD"}

package/dist/utils/helpers.js

@@ -0,0 +1,221 @@
+/**
+ * Common helper utilities for collections.
+ *
+ * Provides shared functionality to reduce code duplication across implementations.
+ */
+// ============================================================================
+// Bounds checking utilities
+// ============================================================================
+/**
+ * Checks if an index is within valid bounds [0, size).
+ * Throws RangeError if out of bounds.
+ *
+ * @param index The index to check
+ * @param size The size of the collection
+ * @param collectionName Optional name for error message
+ * @throws RangeError if index is out of bounds
+ */
+export function checkBounds(index, size, collectionName = "Collection") {
+    if (index < 0 || index >= size) {
+        throw new RangeError(`${collectionName}: Index ${index} out of bounds [0, ${size})`);
+    }
+}
+/**
+ * Checks if an index is valid for insertion [0, size].
+ * Allows index === size for append operations.
+ *
+ * @param index The index to check
+ * @param size The size of the collection
+ * @param collectionName Optional name for error message
+ * @throws RangeError if index is out of bounds
+ */
+export function checkInsertBounds(index, size, collectionName = "Collection") {
+    if (index < 0 || index > size) {
+        throw new RangeError(`${collectionName}: Index ${index} out of bounds [0, ${size}]`);
+    }
+}
+/**
+ * Checks if a range [start, end) is valid.
+ *
+ * @param start Start index (inclusive)
+ * @param end End index (exclusive)
+ * @param size The size of the collection
+ * @param collectionName Optional name for error message
+ * @throws RangeError if range is invalid
+ */
+export function checkRangeBounds(start, end, size, collectionName = "Collection") {
+    if (start < 0 || end > size || start > end) {
+        throw new RangeError(`${collectionName}: Invalid range [${start}, ${end}) for size ${size}`);
+    }
+}
+// ============================================================================
+// Equality and search utilities
+// ============================================================================
+/**
+ * Finds the index of an element in an array using custom equality.
+ *
+ * @param array The array to search
+ * @param element The element to find
+ * @param eq Equality function
+ * @returns Index of element, or -1 if not found
+ */
+export function findIndex(array, element, eq) {
+    for (let i = 0; i < array.length; i++) {
+        if (eq(array[i], element)) {
+            return i;
+        }
+    }
+    return -1;
+}
+/**
+ * Finds the last index of an element in an array using custom equality.
+ *
+ * @param array The array to search
+ * @param element The element to find
+ * @param eq Equality function
+ * @returns Last index of element, or -1 if not found
+ */
+export function findLastIndex(array, element, eq) {
+    for (let i = array.length - 1; i >= 0; i--) {
+        if (eq(array[i], element)) {
+            return i;
+        }
+    }
+    return -1;
+}
+/**
+ * Checks if an array contains an element using custom equality.
+ *
+ * @param array The array to search
+ * @param element The element to find
+ * @param eq Equality function
+ * @returns true if element is found
+ */
+export function arrayContains(array, element, eq) {
+    return findIndex(array, element, eq) !== -1;
+}
+/**
+ * Removes the first occurrence of an element from an array.
+ *
+ * @param array The array to modify
+ * @param element The element to remove
+ * @param eq Equality function
+ * @returns true if element was found and removed
+ */
+export function arrayRemove(array, element, eq) {
+    const index = findIndex(array, element, eq);
+    if (index === -1)
+        return false;
+    array.splice(index, 1);
+    return true;
+}
+/**
+ * Removes all occurrences of an element from an array.
+ *
+ * @param array The array to modify
+ * @param element The element to remove
+ * @param eq Equality function
+ * @returns Number of elements removed
+ */
+export function arrayRemoveAll(array, element, eq) {
+    let count = 0;
+    for (let i = array.length - 1; i >= 0; i--) {
+        if (eq(array[i], element)) {
+            array.splice(i, 1);
+            count++;
+        }
+    }
+    return count;
+}
+// ============================================================================
+// Iterator utilities
+// ============================================================================
+/**
+ * Creates a simple iterator for an array.
+ *
+ * @param array The array to iterate
+ * @returns Iterator over the array
+ */
+export function* arrayIterator(array) {
+    yield* array;
+}
+/**
+ * Creates a reversed iterator for an array.
+ *
+ * @param array The array to iterate
+ * @returns Reversed iterator over the array
+ */
+export function* reverseArrayIterator(array) {
+    for (let i = array.length - 1; i >= 0; i--) {
+        yield array[i];
+    }
+}
+/**
+ * Converts an iterable to an array.
+ *
+ * @param iterable The iterable to convert
+ * @returns Array containing all elements
+ */
+export function toArray(iterable) {
+    return Array.from(iterable);
+}
+// ============================================================================
+// Validation utilities
+// ============================================================================
+/**
+ * Ensures a value is not null or undefined.
+ *
+ * @param value The value to check
+ * @param message Error message
+ * @returns The non-null value
+ * @throws Error if value is null or undefined
+ */
+export function requireNonNull(value, message = "Value cannot be null or undefined") {
+    if (value === null || value === undefined) {
+        throw new Error(message);
+    }
+    return value;
+}
+/**
+ * Ensures a collection is not empty.
+ *
+ * @param size Current size
+ * @param collectionName Optional name for error message
+ * @throws Error if collection is empty
+ */
+export function requireNonEmpty(size, collectionName = "Collection") {
+    if (size === 0) {
+        throw new Error(`${collectionName} is empty`);
+    }
+}
+// ============================================================================
+// Math utilities
+// ============================================================================
+/**
+ * Clamps a value between min and max.
+ *
+ * @param value The value to clamp
+ * @param min Minimum value
+ * @param max Maximum value
+ * @returns Clamped value
+ */
+export function clamp(value, min, max) {
+    return Math.max(min, Math.min(max, value));
+}
+/**
+ * Calculates hash code for a string.
+ * Uses Java's String.hashCode() algorithm.
+ *
+ * @param str The string to hash
+ * @returns Hash code
+ */
+export function stringHashCode(str) {
+    let hash = 0;
+    for (let i = 0; i < str.length; i++) {
+        const char = str.charCodeAt(i);
+        hash = ((hash << 5) - hash) + char;
+        hash = hash & hash; // Convert to 32-bit integer
+    }
+    return hash;
+}
+//# sourceMappingURL=helpers.js.map

package/dist/utils/helpers.js.map

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