@mark1russell7/collections 0.0.0-stage → 0.2.0

package/src/interfaces/collection.ts

@@ -0,0 +1,141 @@
+/**
+ * Base collection interfaces that mirror Java Collections Framework.
+ *
+ * These form the root of the collection hierarchy and define the
+ * fundamental operations common to all collections.
+ */
+
+import type { Eq } from "../core/traits.js";
+
+/**
+ * ReadonlyCollection<T> - The root interface for readonly collections.
+ *
+ * Mirrors java.util.Collection but without mutation operations.
+ * All collections must extend this or a more specific readonly interface.
+ */
+export interface ReadonlyCollection<T> extends Iterable<T> {
+  /**
+   * This value is the number of elements in this collection.
+   */
+  readonly size: number;
+
+  /**
+   * This value is true if this collection contains no elements.
+   */
+  readonly isEmpty: boolean;
+
+  /**
+   * This method gives true if this collection contains the specified element.
+   * This method uses the collection's equality function to compare elements.
+   *
+   * @param element The element to check for
+   */
+  contains(element: T): boolean;
+
+  /**
+   * This method gives true if this collection contains all elements in the specified collection.
+   *
+   * @param other The collection whose elements to check for
+   */
+  containsAll(other: Iterable<T>): boolean;
+
+  /**
+   * This method gives an array containing all elements in this collection.
+   * The given array is safe to change (it's a copy).
+   */
+  toArray(): T[];
+
+  /**
+   * This method does the given action for each element.
+   *
+   * @param action The action to do for each element
+   */
+  forEach(action: (element: T, index: number) => void): void;
+
+  /**
+   * This value is the equality function used by this collection.
+   */
+  readonly eq: Eq<T>;
+}
+
+/**
+ * Collection<T> - The root interface for mutable collections.
+ *
+ * Mirrors java.util.Collection with mutation operations.
+ * All mutable collections must extend this or a more specific interface.
+ */
+export interface Collection<T> extends ReadonlyCollection<T> {
+  /**
+   * This method adds an element to this collection.
+   *
+   * This method gives true if the collection was changed as a result of this call.
+   * Some collections (like Set) can give false if the element already exists.
+   *
+   * @param element The element to add
+   * @returns true if the collection changed
+   * @throws Error if collection is full (bounded) and policy is 'throw'
+   */
+  add(element: T): boolean;
+
+  /**
+   * This method adds all elements from the specified collection to this collection.
+   *
+   * @param other The collection whose elements to add
+   * @returns true if the collection changed
+   */
+  addAll(other: Iterable<T>): boolean;
+
+  /**
+   * This method removes a single instance of the specified element from this collection.
+   *
+   * This method gives true if an element was removed as a result of this call.
+   *
+   * @param element The element to remove
+   * @returns true if an element was removed
+   */
+  remove(element: T): boolean;
+
+  /**
+   * This method removes all elements from this collection that are also in the specified collection.
+   *
+   * @param other The collection whose elements to remove
+   * @returns true if the collection changed
+   */
+  removeAll(other: Iterable<T>): boolean;
+
+  /**
+   * This method retains only the elements in this collection that are in the specified collection.
+   * In other words, removes all elements not in the specified collection.
+   *
+   * @param other The collection of elements to retain
+   * @returns true if the collection changed
+   */
+  retainAll(other: Iterable<T>): boolean;
+
+  /**
+   * This method removes all elements from this collection.
+   * The collection will be empty after this call gives.
+   */
+  clear(): void;
+}
+
+/**
+ * Utility type to check if a collection is readonly.
+ */
+export type IsReadonly<C> = C extends ReadonlyCollection<any>
+  ? C extends Collection<any>
+    ? false
+    : true
+  : false;
+
+/**
+ * Extract element type from a collection.
+ */
+export type ElementOf<C> = C extends ReadonlyCollection<infer T> ? T : never;
+
+/**
+ * Make a collection readonly by removing mutation methods.
+ */
+export type Readonly<C extends Collection<any>> = C extends Collection<infer T>
+  ? ReadonlyCollection<T>
+  : never;

package/src/interfaces/list.ts

@@ -0,0 +1,281 @@
+/**
+ * List interfaces that mirror Java's List interface.
+ *
+ * Lists are ordered collections that can hold duplicate elements
+ * and give positional (indexed) access to elements.
+ */
+
+import type { Collection, ReadonlyCollection } from "./collection.js";
+import type { Compare } from "../core/traits.js";
+
+/**
+ * ReadonlyList<T> - Readonly ordered collection with indexed access.
+ *
+ * Mirrors java.util.List but without mutation operations.
+ * Elements maintain their insertion order and can be accessed by index.
+ */
+export interface ReadonlyList<T> extends ReadonlyCollection<T> {
+  /**
+   * This method gives the element at the specified position.
+   *
+   * @param index The index of the element to give (0-based)
+   * @returns The element at the specified position
+   * @throws RangeError if index is out of bounds
+   */
+  get(index: number): T;
+
+  /**
+   * This method gives the index of the first occurrence of the specified element,
+   * or -1 if not found.
+   *
+   * @param element The element to search for
+   * @param fromIndex Optional starting index for the search
+   */
+  indexOf(element: T, fromIndex?: number): number;
+
+  /**
+   * This method gives the index of the last occurrence of the specified element,
+   * or -1 if not found.
+   *
+   * @param element The element to search for
+   * @param fromIndex Optional starting index for backwards search
+   */
+  lastIndexOf(element: T, fromIndex?: number): number;
+
+  /**
+   * This method gives a view of the portion of this list between fromIndex (inclusive)
+   * and toIndex (exclusive).
+   *
+   * Changes to the sublist are reflected in the original list.
+   *
+   * @param fromIndex Start index (inclusive)
+   * @param toIndex End index (exclusive)
+   */
+  subList(fromIndex: number, toIndex: number): ReadonlyList<T>;
+
+  /**
+   * This method gives the first element in the list.
+   *
+   * @throws Error if list is empty
+   */
+  first(): T;
+
+  /**
+   * This method gives the last element in the list.
+   *
+   * @throws Error if list is empty
+   */
+  last(): T;
+}
+
+/**
+ * List<T> - Mutable ordered collection with indexed access.
+ *
+ * Mirrors java.util.List with full mutation capabilities.
+ * This type gives methods to insert, replace, and remove elements by index.
+ */
+export interface List<T> extends ReadonlyList<T>, Collection<T> {
+  /**
+   * This method replaces the element at the specified position.
+   *
+   * @param index The index of the element to replace
+   * @param element The new element
+   * @returns The element previously at the specified position
+   * @throws RangeError if index is out of bounds
+   */
+  set(index: number, element: T): T;
+
+  /**
+   * This method inserts an element at the specified position.
+   * Shifts elements at and after the position to the right.
+   *
+   * @param index The index at which to insert
+   * @param element The element to insert
+   * @throws RangeError if index is out of bounds (0 to size inclusive)
+   */
+  insert(index: number, element: T): void;
+
+  /**
+   * This method inserts all elements from the specified collection at the specified position.
+   *
+   * @param index The index at which to insert
+   * @param other The collection whose elements to insert
+   * @returns true if the list changed
+   */
+  insertAll(index: number, other: Iterable<T>): boolean;
+
+  /**
+   * This method removes the element at the specified position.
+   * Shifts elements after the position to the left.
+   *
+   * @param index The index of the element to remove
+   * @returns The element that was removed
+   * @throws RangeError if index is out of bounds
+   */
+  removeAt(index: number): T;
+
+  /**
+   * This method removes elements in the specified index range.
+   *
+   * @param fromIndex Start index (inclusive)
+   * @param toIndex End index (exclusive)
+   */
+  removeRange(fromIndex: number, toIndex: number): void;
+
+  /**
+   * This method sorts this list according to the specified comparator.
+   *
+   * @param compare The comparison function
+   */
+  sort(compare?: Compare<T>): void;
+
+  /**
+   * This method reverses the order of elements in this list.
+   */
+  reverse(): void;
+
+  /**
+   * This method gives a mutable sublist view.
+   *
+   * @param fromIndex Start index (inclusive)
+   * @param toIndex End index (exclusive)
+   */
+  subList(fromIndex: number, toIndex: number): List<T>;
+
+  // Stack-like operations
+
+  /**
+   * This method appends an element to the end of this list.
+   * Equivalent to add() but doesn't give boolean.
+   *
+   * @param element The element to append
+   */
+  push(element: T): void;
+
+  /**
+   * Removes and gives the last element in this list.
+   *
+   * @returns The last element
+   * @throws Error if list is empty
+   */
+  pop(): T;
+
+  /**
+   * Removes and gives the first element in this list.
+   *
+   * @returns The first element
+   * @throws Error if list is empty
+   */
+  shift(): T;
+
+  /**
+   * This method prepends an element to the beginning of this list.
+   *
+   * @param element The element to prepend
+   */
+  unshift(element: T): void;
+}
+
+/**
+ * RandomAccess - Marker interface for lists with O(1) indexed access.
+ *
+ * This type shows that the list gives fast (constant-time) random access.
+ * Examples: ArrayList (yes), LinkedList (no).
+ */
+export interface RandomAccess {
+  /**
+   * This marker property shows random access capability.
+   * Always true for collections implementing this interface.
+   */
+  readonly supportsRandomAccess: true;
+}
+
+/**
+ * Stack<T> - LIFO (Last-In-First-Out) collection.
+ *
+ * A stack of elements with push/pop operations.
+ * A specialized list or a standalone class can implement this type.
+ */
+export interface Stack<T> extends Iterable<T> {
+  /** Number of elements */
+  readonly size: number;
+
+  /** True if empty */
+  readonly isEmpty: boolean;
+
+  /**
+   * This method pushes an element onto the stack.
+   */
+  push(element: T): void;
+
+  /**
+   * Removes and gives the top element.
+   *
+   * @throws Error if stack is empty
+   */
+  pop(): T;
+
+  /**
+   * This method gives the top element without removing it.
+   *
+   * @throws Error if stack is empty
+   */
+  peek(): T;
+
+  /**
+   * This method removes all elements.
+   */
+  clear(): void;
+
+  /**
+   * This method searches for an element and gives its distance from the top.
+   * This method gives -1 if not found.
+   */
+  search(element: T): number;
+}
+
+/**
+ * Vector<T> - Synchronized growable array.
+ *
+ * Like ArrayList but with synchronized access.
+ * This interface is a legacy of Java. Use compose(synchronized())(arrayList()) instead.
+ */
+export interface Vector<T> extends List<T> {
+  /**
+   * Current capacity of the underlying array.
+   */
+  readonly capacity: number;
+
+  /**
+   * Trims capacity to current size to minimize memory usage.
+   */
+  trimToSize(): void;
+
+  /**
+   * This method increases capacity to make sure that it can hold at least the specified number of elements.
+   */
+  ensureCapacity(minCapacity: number): void;
+}
+
+/**
+ * CircularList<T> - List with circular/ring buffer behavior.
+ *
+ * When capacity is reached, oldest elements are overwritten.
+ * Useful for fixed-size buffers like logs or history.
+ */
+export interface CircularList<T> extends List<T> {
+  /**
+   * Maximum capacity of the circular list.
+   */
+  readonly capacity: number;
+
+  /**
+   * This value is true if the list has reached capacity.
+   */
+  readonly isFull: boolean;
+
+  /**
+   * Number of elements that have been overwritten.
+   */
+  readonly overwriteCount: number;
+}