modern-ts 0.8.0

package/dist/types/Utils/Array/grouping.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Groups array items by a computed key. Keys are converted to strings -
+ * distinct original keys that stringify to the same value will merge groups.
+ * @param list Array to group
+ * @param keyGetter Function extracting grouping key from each item
+ * @returns Object with stringified keys mapping to arrays of grouped items
+ */
+export declare const groupBy: <T, K extends string | number | boolean>(list: readonly T[], keyGetter: (item: T) => K) => Record<string | number, T[]>;
+/**
+ * Creates object lookup by computed key. Last item wins for duplicate keys
+ * after string conversion. Returns empty object for empty array.
+ * @param list Array to index
+ * @param keyGetter Function extracting key from each item
+ * @returns Object with stringified keys mapping to the last corresponding item
+ */
+export declare const keyBy: <T, K extends string | number | boolean>(list: readonly T[], keyGetter: (item: T) => K) => Record<string | number, T>;
+/**
+ * Splits array into two groups based on predicate. Always returns tuple of
+ * two arrays (truthy group first). Both arrays are empty for empty input.
+ * @param list Array to partition
+ * @param predicate Filtering function
+ * @returns Tuple where first array contains items satisfying predicate
+ */
+export declare const partition: <T>(list: readonly T[], predicate: (item: T) => boolean) => [T[], T[]];
+/**
+ * Splits an array into chunks of the specified size. Returns an empty array
+ * if the input array is empty or chunk size is zero. Negative sizes are
+ * treated as zero. The final chunk may be smaller than the specified size.
+ *
+ * @param array - The array to process
+ * @param size - The length of each chunk (default: 1)
+ * @returns A new array of chunks
+ */
+export declare const chunk: <T>(array: readonly T[], size?: number) => T[][];
+/**
+ * Creates an object composed of keys generated from iteratee results,
+ * with corresponding values counting their occurrences in the array.
+ * String and number keys are supported; other types will be coerced to strings.
+ *
+ * @param array - The array to iterate over
+ * @param iteratee - The function to generate keys from elements
+ * @returns An object with keys and their counts
+ */
+export declare const countBy: <T>(array: readonly T[], iteratee: (value: T) => string | number) => Record<string, number>;

package/dist/types/Utils/Array/iteration.d.ts

@@ -0,0 +1,86 @@
+import { MaybePromise } from '../type-tool';
+/**
+ * Iterates over array elements from right to left (last to first).
+ * Executes the iteratee function for each element.
+ *
+ * @param array - The array to iterate over
+ * @param iteratee - Function invoked per iteration with (value, index, collection)
+ * @returns void
+ *
+ * @remarks
+ * - For empty arrays, no iterations occur
+ * - Iteration order is reversed: array[length-1] to array[0]
+ * - Original array modifications during iteration affect the iteration
+ */
+export declare const forEachRight: <T>(array: T[], iteratee: (value: T, index: number, collection: T[]) => void) => void;
+/**
+ * Asynchronously iterates over array elements with controlled concurrency.
+ * Executes callbacks concurrently up to the concurrency limit.
+ *
+ * @param array - The array to iterate over
+ * @param callback - Async function invoked per element with (value, index, array)
+ * @param concurrency - Maximum number of concurrent executions (default: Infinity)
+ * @returns Promise that resolves when all callbacks complete
+ *
+ * @remarks
+ * - Empty arrays resolve immediately
+ * - Concurrency values < 1 behave as concurrency=Infinity
+ * - If concurrency >= array.length, uses Promise.all for optimization
+ * - Callback exceptions cause immediate rejection; pending callbacks continue
+ * - Execution order starts from index 0, but completion order varies
+ */
+export declare const forEachAsync: <T>(array: T[], callback: (value: T, index: number, array: T[]) => Promise<void>, concurrency?: number) => Promise<void>;
+/**
+ * Asynchronously maps array elements with controlled concurrency.
+ * Returns new array with mapped values in original indices.
+ *
+ * @template T - Input array element type
+ * @template U - Output array element type
+ * @param array - Source array to map
+ * @param callback - Async mapping function with (value, index, array)
+ * @param concurrency - Maximum concurrent executions (default: Infinity)
+ * @returns Promise resolving to new array of mapped values
+ *
+ * @remarks
+ * - Empty arrays resolve to empty array
+ * - Concurrency behavior matches forEachAsync
+ * - Output array length equals input array length
+ * - Original indices are preserved regardless of execution timing
+ * - Any rejection immediately rejects the entire operation
+ */
+export declare const mapAsync: <T, U>(array: T[], callback: (value: T, index: number, array: T[]) => MaybePromise<U>, concurrency?: number) => Promise<U[]>;
+/**
+ * Asynchronously filters array elements with controlled concurrency.
+ * Returns new array containing elements where predicate returns truthy.
+ *
+ * @param array - Array to filter
+ * @param predicate - Async function returning truthy/falsy with (value, index, array)
+ * @param concurrency - Maximum concurrent executions (default: Infinity)
+ * @returns Promise resolving to filtered array
+ *
+ * @remarks
+ * - Empty arrays resolve to empty array
+ * - Concurrency behavior matches mapAsync
+ * - Output array order preserves original relative order
+ * - Predicate is called for every element (no short-circuiting)
+ * - All predicates execute before filtering occurs
+ */
+export declare const filterAsync: <T>(array: T[], predicate: (value: T, index: number, array: T[]) => MaybePromise<boolean>, concurrency?: number) => Promise<T[]>;
+/**
+ * Asynchronously reduces array to single value using callback.
+ * Executes callbacks sequentially from left to right.
+ *
+ * @template T - Array element type
+ * @template U - Accumulator type
+ * @param array - Array to reduce
+ * @param callback - Async reducer with (accumulator, value, index, array)
+ * @param initial_value - Initial accumulator value
+ * @returns Promise resolving to final accumulator value
+ *
+ * @remarks
+ * - Empty arrays with initial_value return initial_value
+ * - Execution is strictly sequential (no concurrency)
+ * - Reduction order: array[0] to array[length-1]
+ * - Callback awaited before processing next element
+ */
+export declare const reduceAsync: <T, U>(array: T[], callback: (accumulator: U, value: T, index: number, array: T[]) => MaybePromise<U>, initial_value: U) => Promise<U>;

package/dist/types/Utils/Array/operators.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Maps array in-place within specified range. Clamps indices to valid array bounds.
+ * Negative start/end count from array end. Returns modified original array.
+ * @param array - Array to modify (mutated)
+ * @param transform - Mapping function receiving current index
+ * @param start - Start index (clamped, negative counts from end)
+ * @param end - End index (clamped, negative counts from end)
+ * @returns Mutated original array with mixed types
+ */
+export declare const mapInPlace: <T, R>(array: readonly T[], transform: (index: number) => R, start?: number, end?: number) => readonly (T | R)[];
+/**
+ * Creates new array mapped within specified range. Clamps indices to valid bounds.
+ * Negative start/end count from array end. Original array remains unchanged.
+ * @param array - Source array (not mutated)
+ * @param transform - Mapping function receiving current index
+ * @param start - Start index (clamped, negative counts from end)
+ * @param end - End index (clamped, negative counts from end)
+ * @returns New array with mixed types
+ */
+export declare const mapToNewArray: <T, R>(array: readonly T[], transform: (index: number) => R, start?: number, end?: number) => readonly (T | R)[];
+/**
+ * Returns all arrays with minimum length. Empty arrays included in comparison.
+ * Returns single array if unique minimum, multiple arrays if tie.
+ * Returns empty array if no input arrays provided.
+ * @param arrays - Arrays to compare
+ * @returns Array of shortest arrays
+ */
+export declare const shortest: <T>(...arrays: readonly T[][]) => readonly T[][];
+/**
+ * Moves element between positions using circular indexing. Returns original array.
+ * No-op for single-element arrays or identical source/destination.
+ * Uses copyWithin for optimal performance. Handles both forward and backward moves.
+ * @param array - Array to modify (mutated)
+ * @param from - Source index (wraps circularly)
+ * @param to - Destination index (wraps circularly)
+ * @returns Mutated original array
+ */
+export declare const move: <T>(array: T[], from: number, to: number) => T[];
+/**
+ * Finds the element with maximum value according to the iteratee function
+ *
+ * @template T - The type of elements in the array
+ * @param array - The array to search (readonly, accepts sparse arrays)
+ * @param iteratee - Function that returns a numeric value for each element
+ * @returns The element with maximum iteratee value, or undefined for empty array
+ * @remarks - Returns undefined for empty arrays. Handles sparse arrays by skipping missing indices.
+ *           - If multiple elements have the same maximum value, returns the first found.
+ *           - Iteratee is called only for existing elements in sparse arrays.
+ */
+export declare const maxBy: <T>(array: readonly T[], iteratee: (value: T) => number) => T | undefined;
+/**
+ * Finds the element with minimum value according to the iteratee function
+ *
+ * @template T - The type of elements in the array
+ * @param array - The array to search (readonly, accepts sparse arrays)
+ * @param iteratee - Function that returns a numeric value for each element
+ * @returns The element with minimum iteratee value, or undefined for empty array
+ * @remarks - Returns undefined for empty arrays. Handles sparse arrays by skipping missing indices.
+ *           - If multiple elements have the same minimum value, returns the first found.
+ *           - Iteratee is called only for existing elements in sparse arrays.
+ */
+export declare const minBy: <T>(array: readonly T[], iteratee: (value: T) => number) => T | undefined;

package/dist/types/Utils/Array/randomization.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Returns a new array with elements randomly shuffled using Fisher-Yates algorithm
+ * @template T - Array element type
+ * @param {T[]} array - Input array to shuffle (will not be modified)
+ * @returns {T[]} New shuffled array. Empty array returns empty array.
+ */
+export declare const shuffle: <T>(array: T[]) => T[];
+/**
+ * Xorshift32 Pseudo-random number generator
+ * A small, fast PRNG that provides deterministic sequences based on a seed.
+ */
+export declare class Xorshift32 {
+    private seed_state;
+    /**
+     * @param {number} seed - Initial seed (must be a non-zero 32-bit integer)
+     */
+    constructor(seed: number);
+    /**
+     * Generates the next raw 32-bit unsigned integer
+     * @returns {number} 32-bit unsigned integer
+     */
+    nextUint32(): number;
+    /**
+     * Returns a random float between [0, 1)
+     * @returns {number}
+     */
+    nextFloat(): number;
+}
+/**
+ * Shuffles array in-place using Fisher-Yates algorithm
+ * @template T - Array element type
+ * @param {T[]} array - Array to shuffle (will be modified)
+ * @returns {T[]} The same array reference, now shuffled. Empty array returns same empty array.
+ */
+export declare const shuffleInplace: <T>(array: T[]) => T[];
+/**
+ * Returns a random element from array
+ * @template T - Array element type
+ * @param {T[]} collection - Input array
+ * @returns {T | undefined} Random element, or undefined if array is empty
+ */
+export declare const sample: <T>(collection: T[]) => T | undefined;
+/**
+ * Returns n random unique elements from array
+ * @template T - Array element type
+ * @param {T[]} collection - Input array (will not be modified)
+ * @param {number} n - Number of elements to sample
+ * @returns {T[]} Array of n random unique elements. Returns empty array if:
+ * - Input array is empty
+ * - n ≤ 0
+ * - n > collection.length: returns shuffled copy of entire array
+ */
+export declare const sampleSize: <T>(collection: T[], n: number) => T[];
+/**
+ * Returns n random elements with replacement (duplicates possible)
+ * @template T - Array element type
+ * @param {T[]} collection - Input array
+ * @param {number} n - Number of elements to pick
+ * @returns {T[]} Array of n random elements. Returns empty array if:
+ * - Input array is empty
+ * - n ≤ 0
+ */
+export declare const choices: <T>(collection: T[], n: number) => T[];
+/**
+ * Returns n random elements based on weights
+ * @template T - Array element type
+ * @param {T[]} collection - Input array
+ * @param {number[]} weights - Corresponding weights for each element
+ * @param {number} n - Number of elements to pick
+ * @returns {T[]} Array of n random weighted elements. Returns empty array if:
+ * - Input array is empty
+ * - Weights array length doesn't match collection length
+ * - n ≤ 0
+ * @throws No explicit error, but will return empty array for invalid inputs
+ */
+export declare const weightedChoices: <T>(collection: T[], weights: number[], n: number) => T[];

package/dist/types/Utils/Array/set.d.ts

@@ -0,0 +1,108 @@
+type Comparator<T> = (a: T, b: T) => boolean;
+type Iteratee<T, V> = (value: T) => V;
+/**
+ * Returns the difference between two arrays (elements in array1 but not in array2)
+ * @param array - The source array
+ * @param values - Arrays to exclude values from
+ * @returns Array containing elements present only in the first array
+ */
+export declare const difference: <T>(array: readonly T[], ...values: (readonly T[])[]) => T[];
+/**
+ * Returns the difference between arrays using an iteratee function
+ * @param array - The source array
+ * @param values - Array to exclude values from
+ * @param iteratee - Function to transform values before comparison
+ * @returns Array containing elements with unique transformed values
+ */
+export declare const differenceBy: <T, V>(array: readonly T[], values: readonly T[], iteratee: Iteratee<T, V>) => T[];
+/**
+ * Returns the difference between arrays using a comparator function
+ * @param array - The source array
+ * @param values - Array to exclude values from
+ * @param comparator - Function to compare two elements
+ * @returns Array containing elements not matching any in values
+ */
+export declare const differenceWith: <T>(array: readonly T[], values: readonly T[], comparator: Comparator<T>) => T[];
+/**
+ * Returns the intersection of multiple arrays
+ * @param arrays - Arrays to find common elements from
+ * @returns Array containing elements present in all arrays
+ */
+export declare const intersection: <T>(...arrays: (readonly T[])[]) => T[];
+/**
+ * Returns the intersection of two arrays using an iteratee function
+ * @param array1 - First array
+ * @param array2 - Second array
+ * @param iteratee - Function to transform values before comparison
+ * @returns Array containing elements with matching transformed values
+ */
+export declare const intersectionBy: <T, V>(array1: readonly T[], array2: readonly T[], iteratee: Iteratee<T, V>) => T[];
+/**
+ * Returns the intersection of two arrays using a comparator function
+ * @param array1 - First array
+ * @param array2 - Second array
+ * @param comparator - Function to compare two elements
+ * @returns Array containing elements matching at least one in both arrays
+ */
+export declare const intersectionWith: <T>(array1: readonly T[], array2: readonly T[], comparator: Comparator<T>) => T[];
+/**
+ * Returns the union of multiple arrays
+ * @param arrays - Arrays to combine
+ * @returns Array containing unique elements from all arrays
+ */
+export declare const union: <T>(...arrays: (readonly T[])[]) => T[];
+/**
+ * Returns the union of two arrays using an iteratee function
+ * @param array1 - First array
+ * @param array2 - Second array
+ * @param iteratee - Function to transform values before deduplication
+ * @returns Array containing unique elements based on transformed values
+ */
+export declare const unionBy: <T, V>(array1: readonly T[], array2: readonly T[], iteratee: Iteratee<T, V>) => T[];
+/**
+ * Returns the union of two arrays using a comparator function
+ * @param array1 - First array
+ * @param array2 - Second array
+ * @param comparator - Function to determine equality between elements
+ * @returns Array containing elements considered unique by the comparator
+ */
+export declare const unionWith: <T>(array1: readonly T[], array2: readonly T[], comparator: Comparator<T>) => T[];
+/**
+ * Returns the symmetric difference between two arrays
+ * @param array1 - First array
+ * @param array2 - Second array
+ * @returns Array containing elements present in only one of the arrays
+ */
+export declare const xor: <T>(array1: readonly T[], array2: readonly T[]) => T[];
+/**
+ * Returns the symmetric difference using an iteratee function
+ * @param array1 - First array
+ * @param array2 - Second array
+ * @param iteratee - Function to transform values before comparison
+ * @returns Array containing elements with unique transformed values
+ */
+export declare const xorBy: <T, V>(array1: readonly T[], array2: readonly T[], iteratee: Iteratee<T, V>) => T[];
+/**
+ * Returns the symmetric difference using a comparator function
+ * @param array1 - First array
+ * @param array2 - Second array
+ * @param comparator - Function to compare two elements
+ * @returns Array containing elements not matching any in the other array
+ */
+export declare const xorWith: <T>(array1: readonly T[], array2: readonly T[], comparator: Comparator<T>) => T[];
+/**
+ * Checks if one array is a subset of another
+ * @param subset - Array to check as subset
+ * @param superset - Array to check as superset
+ * @returns True if all elements of subset exist in superset
+ */
+export declare const isSubset: <T>(subset: readonly T[], superset: readonly T[]) => boolean;
+/**
+ * Checks if one array is a subset of another using a comparator
+ * @param subset - Array to check as subset
+ * @param superset - Array to check as superset
+ * @param comparator - Function to compare two elements
+ * @returns True if all elements of subset have matches in superset
+ */
+export declare const isSubsetWith: <T>(subset: readonly T[], superset: readonly T[], comparator: Comparator<T>) => boolean;
+export {};

package/dist/types/Utils/Array/slice.d.ts

@@ -0,0 +1,189 @@
+/**
+ * Gets the first element of an array.
+ * @param array - The array to query.
+ * @returns The first element, or undefined if array is empty.
+ * @example
+ * head([1, 2, 3]) // => 1
+ * head([]) // => undefined
+ */
+export declare const head: <T>(array: readonly T[]) => T;
+/**
+ * Gets the last element of an array.
+ * @param array - The array to query.
+ * @returns The last element, or undefined if array is empty.
+ * @example
+ * last([1, 2, 3]) // => 3
+ * last([]) // => undefined
+ */
+export declare const last: <T>(array: readonly T[]) => T | undefined;
+/**
+ * Gets all but the last element of an array.
+ * @param array - The array to query.
+ * @returns A new array excluding the last element.
+ * @remarks
+ * - Returns empty array if input array has 0 or 1 elements
+ * - Non-integer array length is handled by slice()
+ * @example
+ * initial([1, 2, 3]) // => [1, 2]
+ * initial([1]) // => []
+ * initial([]) // => []
+ */
+export declare const initial: <T>(array: readonly T[]) => T[];
+/**
+ * Gets all but the first element of an array.
+ * @param array - The array to query.
+ * @returns A new array excluding the first element.
+ * @remarks
+ * - Returns empty array if input array has 0 or 1 elements
+ * - Non-integer array length is handled by slice()
+ * @example
+ * tail([1, 2, 3]) // => [2, 3]
+ * tail([1]) // => []
+ * tail([]) // => []
+ */
+export declare const tail: <T>(array: readonly T[]) => T[];
+/**
+ * Takes n elements from the beginning.
+ * @param array - The array to query.
+ * @param n - Number of elements to take (default: 1).
+ * @returns A new array of taken elements.
+ * @remarks
+ * - n <= 0: returns empty array
+ * - n is not an integer: converted to integer via slice()
+ * - n > array.length: returns entire array copy
+ * - NaN or Infinity n: behavior depends on slice() conversion
+ * @example
+ * take([1, 2, 3], 2) // => [1, 2]
+ * take([1, 2, 3], 0) // => []
+ * take([1, 2, 3], -1) // => []
+ * take([1, 2, 3], 5) // => [1, 2, 3]
+ */
+export declare const take: <T>(array: readonly T[], n?: number) => T[];
+/**
+ * Takes n elements from the end.
+ * @param array - The array to query.
+ * @param n - Number of elements to take (default: 1).
+ * @returns A new array of taken elements.
+ * @remarks
+ * - n <= 0: returns empty array
+ * - n is not an integer: converted to integer via slice()
+ * - n > array.length: returns entire array copy
+ * - NaN or Infinity n: behavior depends on slice() conversion
+ * @example
+ * takeRight([1, 2, 3], 2) // => [2, 3]
+ * takeRight([1, 2, 3], 0) // => []
+ * takeRight([1, 2, 3], -1) // => []
+ */
+export declare const takeRight: <T>(array: readonly T[], n?: number) => T[];
+/**
+ * Drops n elements from the beginning.
+ * @param array - The array to query.
+ * @param n - Number of elements to drop (default: 1).
+ * @returns A new array of remaining elements.
+ * @remarks
+ * - n <= 0: returns full array copy
+ * - n is not an integer: converted to integer via slice()
+ * - n >= array.length: returns empty array
+ * - NaN or Infinity n: behavior depends on slice() conversion
+ * @example
+ * drop([1, 2, 3], 2) // => [3]
+ * drop([1, 2, 3], 0) // => [1, 2, 3]
+ * drop([1, 2, 3], 5) // => []
+ */
+export declare const drop: <T>(array: readonly T[], n?: number) => T[];
+/**
+ * Drops n elements from the end.
+ * @param array - The array to query.
+ * @param n - Number of elements to drop (default: 1).
+ * @returns A new array of remaining elements.
+ * @remarks
+ * - n <= 0: returns full array copy
+ * - n is not an integer: converted to integer via slice()
+ * - n >= array.length: returns empty array
+ * - NaN or Infinity n: behavior depends on slice() conversion
+ * @example
+ * dropRight([1, 2, 3], 2) // => [1]
+ * dropRight([1, 2, 3], 0) // => [1, 2, 3]
+ * dropRight([1, 2, 3], 5) // => []
+ */
+export declare const dropRight: <T>(array: readonly T[], n?: number) => T[];
+type Predicate<T> = (value: T) => boolean;
+/**
+ * Takes elements from the beginning while predicate returns true.
+ * @param array - The array to query.
+ * @param predicate - The function invoked per iteration.
+ * @returns A new array of taken elements.
+ * @remarks
+ * - Empty array: returns empty array
+ * - All elements satisfy predicate: returns full array copy
+ * - No elements satisfy predicate: returns empty array
+ * - Predicate throws: iteration stops at exception
+ * @example
+ * takeWhile([1, 2, 3, 4], x => x < 3) // => [1, 2]
+ * takeWhile([], x => x < 3) // => []
+ * takeWhile([1, 2, 3], x => x < 5) // => [1, 2, 3]
+ */
+export declare const takeWhile: <T>(array: readonly T[], predicate: Predicate<T>) => T[];
+/**
+ * Takes elements from the end while predicate returns true.
+ * @param array - The array to query.
+ * @param predicate - The function invoked per iteration.
+ * @returns A new array of taken elements.
+ * @remarks
+ * - Empty array: returns empty array
+ * - All elements satisfy predicate: returns full array copy
+ * - No elements satisfy predicate: returns empty array
+ * - Iterates from end; predicate called for each element until false
+ * @example
+ * takeRightWhile([1, 2, 3, 4], x => x > 2) // => [3, 4]
+ * takeRightWhile([], x => x > 2) // => []
+ */
+export declare const takeRightWhile: <T>(array: readonly T[], predicate: Predicate<T>) => T[];
+/**
+ * Drops elements from the beginning while predicate returns true.
+ * @param array - The array to query.
+ * @param predicate - The function invoked per iteration.
+ * @returns A new array of remaining elements.
+ * @remarks
+ * - Empty array: returns empty array
+ * - All elements satisfy predicate: returns empty array
+ * - No elements satisfy predicate: returns full array copy
+ * @example
+ * dropWhile([1, 2, 3, 4], x => x < 3) // => [3, 4]
+ * dropWhile([], x => x < 3) // => []
+ * dropWhile([1, 2, 3], x => x < 5) // => []
+ */
+export declare const dropWhile: <T>(array: readonly T[], predicate: Predicate<T>) => T[];
+/**
+ * Drops elements from the end while predicate returns true.
+ * @param array - The array to query.
+ * @param predicate - The function invoked per iteration.
+ * @returns A new array of remaining elements.
+ * @remarks
+ * - Empty array: returns empty array
+ * - All elements satisfy predicate: returns empty array
+ * - No elements satisfy predicate: returns full array copy
+ * - Iterates from end; predicate called for each element until false
+ * @example
+ * dropRightWhile([1, 2, 3, 4], x => x > 2) // => [1, 2]
+ * dropRightWhile([], x => x > 2) // => []
+ */
+export declare const dropRightWhile: <T>(array: readonly T[], predicate: Predicate<T>) => T[];
+/**
+ * Collects elements at specified indices. Returns empty array if either array or indices are empty.
+ * When circular is true, indices wrap around array bounds using modulo arithmetic.
+ * @param array - Source array
+ * @param indices - Target indices to collect
+ * @param circular - Enable circular indexing (default: false)
+ * @returns Array of collected elements, undefined for out-of-bounds non-circular indices
+ */
+export declare const collectAt: <T>(array: T[], indices: number[], circular?: boolean) => (T | undefined)[];
+/**
+ * Gets element at circular index. Returns undefined for empty array.
+ * Implements modulo arithmetic: negative indices wrap from end, positive from start.
+ * @param array - Source array
+ * @param index - Target index (wraps circularly)
+ * @returns Element at circular index or undefined if array empty
+ */
+export declare const circularAt: <T>(array: T[], index: number) => T | undefined;
+export {};

package/dist/types/Utils/Array/sorting.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Extracts a comparable value from an item for sorting
+ * @template T - The type of items being sorted
+ */
+export type Iteratee<T> = (item: T) => string | number | boolean | Date;
+/**
+ * Sort order direction
+ */
+export type Order = 'asc' | 'desc';
+/**
+ * Core sorting function with full configuration
+ * @template T - Array element type
+ * @param array - Source array to sort
+ * @param iteratees - Functions to extract sort values
+ * @param orders - Sort directions for each iteratee
+ * @param inplace - Modify original array if true
+ * @returns Sorted array (original if inplace)
+ */
+export declare const coreSort: <T>(array: T[], iteratees: Array<Iteratee<T>>, orders: Array<Order>, inplace: boolean) => T[];
+/**
+ * Returns a new sorted array by multiple criteria
+ * @template T - Array element type
+ * @param array - Source array
+ * @param iteratees - Value extraction functions
+ * @param orders - Sort directions
+ * @returns New sorted array
+ */
+export declare const orderBy: <T>(array: T[], iteratees: Array<Iteratee<T>>, orders: Array<Order>) => T[];
+/**
+ * Sorts array in-place by multiple criteria
+ * @template T - Array element type
+ * @param array - Array to sort (modified)
+ * @param iteratees - Value extraction functions
+ * @param orders - Sort directions
+ * @returns Original sorted array
+ */
+export declare const orderByInplace: <T>(array: T[], iteratees: Array<Iteratee<T>>, orders: Array<Order>) => T[];
+/**
+ * Returns new array sorted by single criterion
+ * @template T - Array element type
+ * @param array - Source array
+ * @param iteratee - Value extraction function
+ * @param order - Sort direction (defaults to 'asc')
+ * @returns New sorted array
+ */
+export declare const sortBy: <T>(array: T[], iteratee: Iteratee<T>, order?: Order) => T[];
+/**
+ * Sorts array in-place by single criterion
+ * @template T - Array element type
+ * @param array - Array to sort (modified)
+ * @param iteratee - Value extraction function
+ * @param order - Sort direction (defaults to 'asc')
+ * @returns Original sorted array
+ */
+export declare const sortByInplace: <T>(array: T[], iteratee: Iteratee<T>, order?: Order) => T[];