@mark1russell7/collections 0.0.0-stage → 0.1.0

package/src/utils/defaults.ts

@@ -0,0 +1,345 @@
+/**
+ * Default implementations of equality, hashing, and comparison functions.
+ *
+ * This module gives sensible defaults for primitive types and utilities for
+ * making custom comparators.
+ */
+
+import type { Eq, Hash, Compare } from "../core/traits.js";
+
+// ============================================================================
+// Default Equality
+// ============================================================================
+
+/**
+ * Default equality using strict equality (===).
+ * Works for primitives and reference equality for objects.
+ */
+export const defaultEq: Eq<any> = (a, b) => a === b;
+
+/**
+ * Structural equality for objects (shallow comparison of properties).
+ * This function compares own enumerable properties using ===.
+ */
+export const shallowEq: Eq<any> = (a, b) => {
+  if (a === b) return true;
+  if (typeof a !== "object" || typeof b !== "object") return false;
+  if (a === null || b === null) return false;
+
+  const keysA = Object.keys(a);
+  const keysB = Object.keys(b);
+
+  if (keysA.length !== keysB.length) return false;
+
+  for (const key of keysA) {
+    if (!Object.prototype.hasOwnProperty.call(b, key)) return false;
+    if (a[key] !== b[key]) return false;
+  }
+
+  return true;
+};
+
+/**
+ * Deep structural equality (recursive comparison).
+ * This function handles nested objects and arrays.
+ */
+export const deepEq: Eq<any> = (a, b): boolean => {
+  if (a === b) return true;
+  if (typeof a !== typeof b) return false;
+  if (typeof a !== "object" || a === null || b === null) return false;
+
+  if (Array.isArray(a) && Array.isArray(b)) {
+    if (a.length !== b.length) return false;
+    for (let i = 0; i < a.length; i++) {
+      if (!deepEq(a[i], b[i])) return false;
+    }
+    return true;
+  }
+
+  if (Array.isArray(a) !== Array.isArray(b)) return false;
+
+  const keysA = Object.keys(a);
+  const keysB = Object.keys(b);
+
+  if (keysA.length !== keysB.length) return false;
+
+  for (const key of keysA) {
+    if (!Object.prototype.hasOwnProperty.call(b, key)) return false;
+    if (!deepEq(a[key], b[key])) return false;
+  }
+
+  return true;
+};
+
+/**
+ * Equality by comparing a specific property.
+ *
+ * @example
+ * const userEq = eqBy<User, 'id'>('id')
+ * // or with accessor function:
+ * const userEq = eqBy<User>((u) => u.id)
+ */
+export const eqBy = <T, K extends keyof T = keyof T>(
+  keyOrFn: K | ((value: T) => any)
+): Eq<T> => {
+  const accessor = typeof keyOrFn === "function" ? keyOrFn : (v: T) => v[keyOrFn];
+  return (a, b) => accessor(a) === accessor(b);
+};
+
+// ============================================================================
+// Default Hashing
+// ============================================================================
+
+/**
+ * Default hash function for primitives and objects.
+ * For objects, hashes the JSON string representation.
+ */
+export const defaultHash: Hash<any> = (value: any): number => {
+  if (value === null) return 0;
+  if (value === undefined) return 1;
+
+  const type = typeof value;
+
+  switch (type) {
+    case "boolean":
+      return value ? 1 : 0;
+    case "number":
+      return hashNumber(value);
+    case "string":
+      return hashString(value);
+    case "symbol":
+      return hashString(value.toString());
+    case "bigint":
+      return hashString(value.toString());
+    case "object":
+      // For objects, hash their JSON representation
+      // This is not ideal for all cases but provides a reasonable default
+      try {
+        return hashString(JSON.stringify(value));
+      } catch {
+        // If JSON.stringify fails, fall back to toString
+        return hashString(value.toString());
+      }
+    default:
+      return 2;
+  }
+};
+
+/**
+ * Hash function for strings using djb2 algorithm.
+ */
+export const hashString = (str: string): number => {
+  let hash = 5381;
+  for (let i = 0; i < str.length; i++) {
+    hash = ((hash << 5) + hash) + str.charCodeAt(i); // hash * 33 + c
+    hash = hash & hash; // Convert to 32-bit integer
+  }
+  return hash >>> 0; // Convert to unsigned
+};
+
+/**
+ * Hash function for numbers.
+ */
+export const hashNumber = (num: number): number => {
+  if (Number.isNaN(num)) return 0;
+  if (!Number.isFinite(num)) return num > 0 ? 1 : -1;
+
+  // For integers, use the number itself
+  if (Number.isInteger(num)) {
+    return num | 0; // Convert to 32-bit int
+  }
+
+  // For floats, hash the string representation
+  return hashString(num.toString());
+};
+
+/**
+ * Combine multiple hash values.
+ * Useful for hashing objects with multiple fields.
+ *
+ * @example
+ * const pointHash: Hash<Point> = (p) =>
+ *   combineHashes(hashNumber(p.x), hashNumber(p.y))
+ */
+export const combineHashes = (...hashes: number[]): number => {
+  let combined = 0;
+  for (const hash of hashes) {
+    combined = ((combined << 5) - combined) + hash;
+    combined = combined & combined; // Convert to 32-bit int
+  }
+  return combined >>> 0; // Convert to unsigned
+};
+
+/**
+ * Make a hash function that hashes by a specific property.
+ *
+ * @example
+ * const userHash = hashBy<User>((u) => u.id)
+ */
+export const hashBy = <T>(accessor: (value: T) => any): Hash<T> => {
+  return (value) => defaultHash(accessor(value));
+};
+
+// ============================================================================
+// Default Comparison
+// ============================================================================
+
+/**
+ * Natural ordering comparison for primitives.
+ * Numbers, strings, booleans, dates are compared naturally.
+ */
+export const defaultCompare: Compare<any> = (a, b) => {
+  if (a === b) return 0;
+  if (a === null || a === undefined) return -1;
+  if (b === null || b === undefined) return 1;
+
+  // Handle dates
+  if (a instanceof Date && b instanceof Date) {
+    return a.getTime() - b.getTime();
+  }
+
+  // Handle numbers
+  if (typeof a === "number" && typeof b === "number") {
+    if (Number.isNaN(a)) return Number.isNaN(b) ? 0 : -1;
+    if (Number.isNaN(b)) return 1;
+    return a - b;
+  }
+
+  // Handle strings
+  if (typeof a === "string" && typeof b === "string") {
+    return a.localeCompare(b);
+  }
+
+  // Handle booleans
+  if (typeof a === "boolean" && typeof b === "boolean") {
+    return a === b ? 0 : a ? 1 : -1;
+  }
+
+  // Fallback: convert to string and compare
+  return String(a).localeCompare(String(b));
+};
+
+/**
+ * Numeric comparison (for numbers).
+ */
+export const numberCompare: Compare<number> = (a, b) => {
+  if (Number.isNaN(a)) return Number.isNaN(b) ? 0 : -1;
+  if (Number.isNaN(b)) return 1;
+  return a - b;
+};
+
+/**
+ * String comparison using locale-aware sorting.
+ */
+export const stringCompare: Compare<string> = (a, b) => a.localeCompare(b);
+
+/**
+ * Case-insensitive string comparison.
+ */
+export const stringCompareIgnoreCase: Compare<string> = (a, b) =>
+  a.toLowerCase().localeCompare(b.toLowerCase());
+
+/**
+ * Date comparison.
+ */
+export const dateCompare: Compare<Date> = (a, b) =>
+  a.getTime() - b.getTime();
+
+/**
+ * Boolean comparison (false < true).
+ */
+export const booleanCompare: Compare<boolean> = (a, b) =>
+  a === b ? 0 : a ? 1 : -1;
+
+// ============================================================================
+// Comparator Combinators
+// ============================================================================
+
+/**
+ * This function reverses a comparator.
+ *
+ * @example
+ * const descending = reversed(numberCompare)
+ */
+export const reversed = <T>(compare: Compare<T>): Compare<T> =>
+  (a, b) => compare(b, a);
+
+/**
+ * This function makes a comparator that compares by a specific property or function.
+ *
+ * @example
+ * const byAge = comparing<Person>((p) => p.age)
+ * const byName = comparing<Person, 'name'>('name')
+ */
+export const comparing = <T, K extends keyof T = keyof T>(
+  keyOrFn: K | ((value: T) => any),
+  compare: Compare<any> = defaultCompare
+): Compare<T> => {
+  const accessor = typeof keyOrFn === "function" ? keyOrFn : (v: T) => v[keyOrFn];
+  return (a, b) => compare(accessor(a), accessor(b));
+};
+
+/**
+ * Chains comparators. If the first comparator gives 0 (equal),
+ * tries the next comparator, and so on.
+ *
+ * @example
+ * const userCompare = thenComparing(
+ *   comparing<User>('lastName'),
+ *   comparing<User>('firstName'),
+ *   comparing<User>('age')
+ * )
+ */
+export const thenComparing = <T>(...comparators: Compare<T>[]): Compare<T> => {
+  return (a, b) => {
+    for (const compare of comparators) {
+      const result = compare(a, b);
+      if (result !== 0) return result;
+    }
+    return 0;
+  };
+};
+
+/**
+ * This function makes a comparator that treats null/undefined as less than all other values.
+ *
+ * @example
+ * const compare = nullsFirst(numberCompare)
+ */
+export const nullsFirst = <T>(compare: Compare<T>): Compare<T | null | undefined> => {
+  return (a, b) => {
+    if (a == null && b == null) return 0;
+    if (a == null) return -1;
+    if (b == null) return 1;
+    return compare(a, b);
+  };
+};
+
+/**
+ * This function makes a comparator that treats null/undefined as greater than all other values.
+ *
+ * @example
+ * const compare = nullsLast(numberCompare)
+ */
+export const nullsLast = <T>(compare: Compare<T>): Compare<T | null | undefined> => {
+  return (a, b) => {
+    if (a == null && b == null) return 0;
+    if (a == null) return 1;
+    if (b == null) return -1;
+    return compare(a, b);
+  };
+};
+
+/**
+ * This function makes a comparator from a key extraction function.
+ * Elements are compared by their extracted keys.
+ *
+ * @example
+ * const byLength = comparingKey<string>((s) => s.length)
+ */
+export const comparingKey = <T, K>(
+  keyExtractor: (value: T) => K,
+  keyCompare: Compare<K> = defaultCompare
+): Compare<T> => {
+  return (a, b) => keyCompare(keyExtractor(a), keyExtractor(b));
+};

package/src/utils/factories.ts

@@ -0,0 +1,357 @@
+/**
+ * Factory utilities for making collections.
+ *
+ * This module gives convenient factory methods similar to Java's Collections class.
+ * These functions mirror Java methods like Collections.emptyList() and singletonList().
+ */
+
+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 type { List } from "../interfaces/list.js";
+import type { Queue } from "../interfaces/queue.js";
+import type { MapLike } from "../interfaces/map.js";
+import { readonly } from "../behaviors/readonly.js";
+import { compose } from "../core/middleware.js";
+
+// ============================================================================
+// Empty collections
+// ============================================================================
+
+/**
+ * This value is 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<any, any>();
+
+export function emptyList<T>(): List<T> {
+  const key = "list";
+  if (!EMPTY_LIST_CACHE.has(key)) {
+    const list = compose(readonly<List<T>>())(arrayList<T>());
+    EMPTY_LIST_CACHE.set(key, list);
+  }
+  return EMPTY_LIST_CACHE.get(key);
+}
+
+/**
+ * This value is an empty, immutable queue.
+ */
+const EMPTY_QUEUE_CACHE = new Map<any, any>();
+
+export function emptyQueue<T>(): Queue<T> {
+  const key = "queue";
+  if (!EMPTY_QUEUE_CACHE.has(key)) {
+    const queue = compose(readonly<Queue<T>>())(arrayDeque<T>() as Queue<T>);
+    EMPTY_QUEUE_CACHE.set(key, queue);
+  }
+  return EMPTY_QUEUE_CACHE.get(key);
+}
+
+/**
+ * This value is an empty, immutable map.
+ */
+const EMPTY_MAP_CACHE = new Map<any, any>();
+
+export function emptyMap<K, V>(): MapLike<K, V> {
+  const key = "map";
+  if (!EMPTY_MAP_CACHE.has(key)) {
+    const map = compose(readonly<MapLike<K, V>>())(hashMap<K, V>());
+    EMPTY_MAP_CACHE.set(key, map);
+  }
+  return EMPTY_MAP_CACHE.get(key);
+}
+
+// ============================================================================
+// Singleton collections (single element)
+// ============================================================================
+
+/**
+ * This function gives 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<T>(element: T): List<T> {
+  const list = arrayList<T>();
+  list.add(element);
+  return compose(readonly<List<T>>())(list);
+}
+
+/**
+ * This function gives an immutable map containing only the specified key-value mapping.
+ */
+export function singletonMap<K, V>(key: K, value: V): MapLike<K, V> {
+  const map = hashMap<K, V>();
+  map.set(key, value);
+  return compose(readonly<MapLike<K, V>>())(map);
+}
+
+// ============================================================================
+// N-copies collections
+// ============================================================================
+
+/**
+ * This function gives 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<T>(n: number, element: T): List<T> {
+  if (n < 0) {
+    throw new Error(`n must be non-negative, got ${n}`);
+  }
+
+  const list = arrayList<T>();
+  for (let i = 0; i < n; i++) {
+    list.add(element);
+  }
+  return compose(readonly<List<T>>())(list);
+}
+
+// ============================================================================
+// Collection creation from iterables
+// ============================================================================
+
+/**
+ * This function makes a new ArrayList from the given elements.
+ *
+ * @example
+ * const list = listOf(1, 2, 3, 4, 5)
+ */
+export function listOf<T>(...elements: T[]): ArrayList<T> {
+  return arrayList(elements);
+}
+
+/**
+ * This function makes a new ArrayDeque from the given elements.
+ */
+export function queueOf<T>(...elements: T[]): ArrayDeque<T> {
+  return arrayDeque(elements);
+}
+
+/**
+ * This function makes a new HashMap from the given key-value pairs.
+ *
+ * @example
+ * const map = mapOf(['a', 1], ['b', 2], ['c', 3])
+ */
+export function mapOf<K, V>(...entries: [K, V][]): HashMap<K, V> {
+  return hashMap(entries);
+}
+
+// ============================================================================
+// Mutable collection factories
+// ============================================================================
+
+/**
+ * This function makes a new mutable ArrayList with optional initial elements.
+ *
+ * @example
+ * const list = mutableListOf(1, 2, 3)
+ * list.add(4)
+ */
+export function mutableListOf<T>(...elements: T[]): ArrayList<T> {
+  return arrayList(elements);
+}
+
+/**
+ * This function makes a new mutable HashMap with optional initial entries.
+ */
+export function mutableMapOf<K, V>(...entries: [K, V][]): HashMap<K, V> {
+  return hashMap(entries);
+}
+
+// ============================================================================
+// Immutable collection factories
+// ============================================================================
+
+/**
+ * This function makes 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<T>(...elements: T[]): List<T> {
+  if (elements.length === 0) {
+    return emptyList<T>();
+  }
+  if (elements.length === 1) {
+    return singletonList(elements[0]! as T);
+  }
+  const list = arrayList(elements);
+  return compose(readonly<List<T>>())(list);
+}
+
+/**
+ * This function makes an immutable Map from the given entries.
+ */
+export function immutableMapOf<K, V>(...entries: [K, V][]): MapLike<K, V> {
+  if (entries.length === 0) {
+    return emptyMap<K, V>();
+  }
+  if (entries.length === 1) {
+    return singletonMap(entries[0]![0], entries[0]![1]);
+  }
+  const map = hashMap(entries);
+  return compose(readonly<MapLike<K, V>>())(map);
+}
+
+// ============================================================================
+// Range factories
+// ============================================================================
+
+/**
+ * This function makes 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: number, end: number, step: number = 1): ArrayList<number> {
+  if (step === 0) {
+    throw new Error("step cannot be zero");
+  }
+
+  const list = arrayList<number>();
+
+  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;
+}
+
+/**
+ * This function makes a list containing integers from 0 to n (exclusive).
+ *
+ * @example
+ * const list = rangeTo(5) // [0, 1, 2, 3, 4]
+ */
+export function rangeTo(n: number): ArrayList<number> {
+  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<T>(builder: (list: ArrayList<T>) => void): ArrayList<T> {
+  const list = arrayList<T>();
+  builder(list);
+  return list;
+}
+
+/**
+ * Builder for constructing maps with a fluent API.
+ */
+export function buildMap<K, V>(builder: (map: HashMap<K, V>) => void): HashMap<K, V> {
+  const map = hashMap<K, V>();
+  builder(map);
+  return map;
+}
+
+// ============================================================================
+// Conversion utilities
+// ============================================================================
+
+/**
+ * This function converts an iterable to an ArrayList.
+ *
+ * @example
+ * const set = new Set([1, 2, 3])
+ * const list = toList(set)
+ */
+export function toList<T>(iterable: Iterable<T>): ArrayList<T> {
+  return arrayList(iterable);
+}
+
+/**
+ * This function converts an iterable to a HashMap using a key extractor function.
+ *
+ * @example
+ * const users = [{ id: 1, name: 'Alice' }, { id: 2, name: 'Bob' }]
+ * const userMap = toMap(users, u => u.id)
+ */
+export function toMap<T, K>(
+  iterable: Iterable<T>,
+  keyExtractor: (value: T) => K
+): HashMap<K, T>;
+export function toMap<T, K, V>(
+  iterable: Iterable<T>,
+  keyExtractor: (value: T) => K,
+  valueExtractor: (value: T) => V
+): HashMap<K, V>;
+export function toMap<T, K, V>(
+  iterable: Iterable<T>,
+  keyExtractor: (value: T) => K,
+  valueExtractor?: (value: T) => V
+): HashMap<K, any> {
+  const map = hashMap<K, any>();
+  for (const item of iterable) {
+    const key = keyExtractor(item);
+    const value = valueExtractor ? valueExtractor(item) : item;
+    map.set(key, value);
+  }
+  return map;
+}
+
+// ============================================================================
+// Grouping utilities
+// ============================================================================
+
+/**
+ * This function 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<T, K>(
+  iterable: Iterable<T>,
+  keyExtractor: (value: T) => K
+): HashMap<K, ArrayList<T>> {
+  const map = hashMap<K, ArrayList<T>>();
+
+  for (const item of iterable) {
+    const key = keyExtractor(item);
+    const list = map.computeIfAbsent(key, () => arrayList<T>());
+    list.add(item);
+  }
+
+  return map;
+}