@kitiumai/utils-ts/dist/runtime/array.d.ts

Comprehensive TypeScript utilities for KitiumAI projects

/**
 * Array utility functions
 */
import { type ErrorHandlingOptions } from './error.js';
import { type Result } from './result.js';
interface ChunkOptions extends ErrorHandlingOptions {
    size: number;
    label?: string;
}
type ChunkReturn<T, O> = O extends {
    onError: 'return';
} ? Result<T[][]> : T[][];
/**
 * Split array into chunks of specified size with unified error handling.
 *
 * Supports data-first usage (`chunk(items, options)`) and data-last/curried
 * usage (`chunk(options)(items)`). Set `onError: 'return'` to get a Result
 * instead of throwing.
 *
 * @template T - The type of array elements
 * @param array - The array to chunk
 * @param sizeOrOptions - Size or options bag controlling chunking and errors
 * @returns An array of chunks or a Result when `onError` is set to `return`
 *
 * @example
 * ```ts
 * // data-first
 * chunk([1, 2, 3, 4, 5], 2) // [[1, 2], [3, 4], [5]]
 *
 * // data-last / curried
 * const byThree = chunk<number>({ size: 3 });
 * byThree([1, 2, 3, 4]); // [[1, 2, 3], [4]]
 *
 * // structured error channel
 * const result = chunk([1, 2], { size: 0, onError: 'return', label: 'example' });
 * if (!result.ok) console.log(result.error);
 * ```
 */
export declare function chunk<T>(array: T[], size: number): T[][];
export declare function chunk<T, O extends ChunkOptions & {
    onError?: 'throw' | undefined;
}>(array: T[], options: O): ChunkReturn<T, O>;
export declare function chunk<T>(options: number | ChunkOptions): (array: T[]) => T[][] | Result<T[][]>;
/**
 * Group array items by a key or function
 *
 * @template T - The type of array elements
 * @param array - The array to group
 * @param keyOrFn - A key of T or a function that returns a grouping key
 * @returns An object with keys as grouping keys and values as arrays of elements
 *
 * @example
 * ```ts
 * groupBy([{ type: 'a', value: 1 }, { type: 'b', value: 2 }], 'type')
 * // { a: [{ type: 'a', value: 1 }], b: [{ type: 'b', value: 2 }] }
 * ```
 */
interface GroupByOptions<T> extends ErrorHandlingOptions {
    selector: keyof T | ((item: T) => string | number | undefined);
    allowUndefined?: boolean;
}
type GroupByReturn<T, O> = O extends {
    onError: 'return';
} ? Result<Record<string, T[]>> : Record<string, T[]>;
/**
 * Group array items by a key or selector with predictable error semantics.
 *
 * Supports data-first (`groupBy(array, selector)`) and data-last/curried
 * (`groupBy(selector)(array)`) usage. When `onError` is set to `return`, a
 * `Result` is returned instead of throwing if a selector resolves to
 * `undefined` and `allowUndefined` is not enabled.
 */
export declare function groupBy<T>(array: T[], selector: keyof T | ((item: T) => string | number | undefined)): Record<string, T[]>;
export declare function groupBy<T, O extends GroupByOptions<T> & {
    onError?: 'throw' | undefined;
}>(array: T[], options: O): GroupByReturn<T, O>;
export declare function groupBy<T>(selector: keyof T | ((item: T) => string | number | undefined) | GroupByOptions<T>): (array: T[]) => Record<string, T[]> | Result<Record<string, T[]>>;
/**
 * Remove duplicate values from array
 *
 * @template T - The type of array elements
 * @param array - The array to deduplicate
 * @returns A new array with unique values
 *
 * @example
 * ```ts
 * unique([1, 2, 2, 3, 3, 3]) // [1, 2, 3]
 * ```
 */
export declare function unique<T>(array: T[]): T[];
/**
 * Remove duplicate values by a specific key
 *
 * @template T - The type of array elements
 * @param array - The array to deduplicate
 * @param key - The key to use for uniqueness comparison
 * @returns A new array with unique values based on the key
 *
 * @example
 * ```ts
 * uniqueBy([{ id: 1, name: 'a' }, { id: 1, name: 'b' }], 'id')
 * // [{ id: 1, name: 'a' }]
 * ```
 */
export declare function uniqueBy<T>(array: T[], key: keyof T): T[];
/**
 * Split array into two arrays based on predicate
 *
 * @template T - The type of array elements
 * @param array - The array to partition
 * @param predicate - Function that returns true for items in the first array
 * @returns A tuple of [passed, failed] arrays
 *
 * @example
 * ```ts
 * partition([1, 2, 3, 4, 5], x => x % 2 === 0) // [[2, 4], [1, 3, 5]]
 * ```
 */
export declare function partition<T>(array: T[], predicate: (item: T, index: number) => boolean): [T[], T[]];
/**
 * Find common elements across all arrays
 *
 * @template T - The type of array elements
 * @param arrays - Arrays to find intersection of
 * @returns A new array with elements present in all arrays
 *
 * @example
 * ```ts
 * intersection([1, 2, 3], [2, 3, 4], [3, 4, 5]) // [3]
 * ```
 */
export declare function intersection<T>(...arrays: T[][]): T[];
/**
 * Find elements in first array that are not in second array
 *
 * @template T - The type of array elements
 * @param a - The first array
 * @param b - The second array
 * @returns A new array with elements from a that are not in b
 *
 * @example
 * ```ts
 * difference([1, 2, 3, 4], [2, 4]) // [1, 3]
 * ```
 */
export declare function difference<T>(a: T[], b: T[]): T[];
/**
 * Flatten nested array one level
 *
 * @template T - The type of array elements
 * @param array - The array of arrays to flatten
 * @returns A flattened array
 *
 * @example
 * ```ts
 * flatten([[1, 2], [3, 4]]) // [1, 2, 3, 4]
 * ```
 */
export declare function flatten<T>(array: T[][]): T[];
/**
 * Flatten nested array recursively
 *
 * @template T - The type of array elements
 * @param array - The array to flatten
 * @returns A deeply flattened array
 *
 * @example
 * ```ts
 * flattenDeep([1, [2, [3, [4]]]]) // [1, 2, 3, 4]
 * ```
 */
export declare function flattenDeep<T>(array: T[]): T[];
/**
 * Create array of numbers from start to end
 *
 * @param start - Start value (inclusive)
 * @param end - End value (exclusive)
 * @param step - Step size (default: 1)
 * @returns An array of numbers
 *
 * @example
 * ```ts
 * range(0, 5) // [0, 1, 2, 3, 4]
 * range(0, 10, 2) // [0, 2, 4, 6, 8]
 * ```
 */
export declare function range(start: number, end: number, step?: number): number[];
/**
 * Shuffle array randomly using Fisher-Yates algorithm
 *
 * @template T - The type of array elements
 * @param array - The array to shuffle
 * @returns A new shuffled array
 *
 * @example
 * ```ts
 * shuffle([1, 2, 3, 4, 5]) // [3, 1, 5, 2, 4] (random order)
 * ```
 */
export declare function shuffle<T>(array: T[]): T[];
/**
 * Get random sample from array
 *
 * @template T - The type of array elements
 * @param array - The array to sample from
 * @param count - Number of items to sample (default: 1)
 * @returns A new array with random samples
 *
 * @example
 * ```ts
 * sample([1, 2, 3, 4, 5], 2) // [3, 1] (random)
 * ```
 */
export declare function sample<T>(array: T[], count?: number): T[];
/**
 * Check if arrays are equal (shallow comparison)
 *
 * @template T - The type of array elements
 * @param a - First array
 * @param b - Second array
 * @returns True if arrays have the same length and elements
 *
 * @example
 * ```ts
 * arraysEqual([1, 2, 3], [1, 2, 3]) // true
 * arraysEqual([1, 2], [1, 2, 3]) // false
 * ```
 */
export declare function arraysEqual<T>(a: T[], b: T[]): boolean;
/**
 * Remove falsy values from array
 *
 * @template T - The type of array elements
 * @param array - The array to compact
 * @returns A new array with falsy values removed
 *
 * @example
 * ```ts
 * compact([0, 1, false, 2, '', 3]) // [1, 2, 3]
 * ```
 */
export declare function compact<T>(array: (T | null | undefined | false | 0 | '')[]): T[];
/**
 * Get the first n elements of an array
 *
 * @template T - The type of array elements
 * @param array - The array to take from
 * @param n - Number of elements to take
 * @returns A new array with the first n elements
 *
 * @example
 * ```ts
 * take([1, 2, 3, 4, 5], 3) // [1, 2, 3]
 * ```
 */
export declare function take<T>(array: T[], n: number): T[];
/**
 * Get the last n elements of an array
 *
 * @template T - The type of array elements
 * @param array - The array to take from
 * @param n - Number of elements to take
 * @returns A new array with the last n elements
 *
 * @example
 * ```ts
 * takeRight([1, 2, 3, 4, 5], 3) // [3, 4, 5]
 * ```
 */
export declare function takeRight<T>(array: T[], n: number): T[];
/**
 * Remove the first n elements from an array
 *
 * @template T - The type of array elements
 * @param array - The array to drop from
 * @param n - Number of elements to drop
 * @returns A new array with the first n elements removed
 *
 * @example
 * ```ts
 * drop([1, 2, 3, 4, 5], 2) // [3, 4, 5]
 * ```
 */
export declare function drop<T>(array: T[], n: number): T[];
/**
 * Remove the last n elements from an array
 *
 * @template T - The type of array elements
 * @param array - The array to drop from
 * @param n - Number of elements to drop
 * @returns A new array with the last n elements removed
 *
 * @example
 * ```ts
 * dropRight([1, 2, 3, 4, 5], 2) // [1, 2, 3]
 * ```
 */
export declare function dropRight<T>(array: T[], n: number): T[];
/**
 * Combine two arrays into pairs
 *
 * @template T - The type of first array elements
 * @template U - The type of second array elements
 * @param array1 - First array
 * @param array2 - Second array
 * @returns An array of pairs
 *
 * @example
 * ```ts
 * zip([1, 2, 3], ['a', 'b', 'c']) // [[1, 'a'], [2, 'b'], [3, 'c']]
 * ```
 */
export declare function zip<T, U>(array1: T[], array2: U[]): Array<[T, U]>;
/**
 * Separate pairs into two arrays
 *
 * @template T - The type of first element in pairs
 * @template U - The type of second element in pairs
 * @param pairs - Array of pairs
 * @returns A tuple of two arrays
 *
 * @example
 * ```ts
 * unzip([[1, 'a'], [2, 'b']]) // [[1, 2], ['a', 'b']]
 * ```
 */
export declare function unzip<T, U>(pairs: Array<[T, U]>): [T[], U[]];
/**
 * Get the first element of an array
 *
 * @template T - The type of array elements
 * @param array - The array
 * @returns The first element, or undefined if array is empty
 *
 * @example
 * ```ts
 * head([1, 2, 3]) // 1
 * head([]) // undefined
 * ```
 */
export declare function head<T>(array: T[]): T | undefined;
/**
 * Get all elements except the first
 *
 * @template T - The type of array elements
 * @param array - The array
 * @returns A new array without the first element
 *
 * @example
 * ```ts
 * tail([1, 2, 3, 4]) // [2, 3, 4]
 * ```
 */
export declare function tail<T>(array: T[]): T[];
/**
 * Get the last element of an array
 *
 * @template T - The type of array elements
 * @param array - The array
 * @returns The last element, or undefined if array is empty
 *
 * @example
 * ```ts
 * last([1, 2, 3]) // 3
 * last([]) // undefined
 * ```
 */
export declare function last<T>(array: T[]): T | undefined;
/**
 * Get all elements except the last
 *
 * @template T - The type of array elements
 * @param array - The array
 * @returns A new array without the last element
 *
 * @example
 * ```ts
 * initial([1, 2, 3, 4]) // [1, 2, 3]
 * ```
 */
export declare function initial<T>(array: T[]): T[];
/**
 * Combine multiple arrays and remove duplicates
 *
 * @template T - The type of array elements
 * @param arrays - Arrays to combine
 * @returns A new array with unique elements from all arrays
 *
 * @example
 * ```ts
 * union([1, 2], [2, 3], [3, 4]) // [1, 2, 3, 4]
 * ```
 */
export declare function union<T>(...arrays: T[][]): T[];
/**
 * Remove specified values from an array
 *
 * @template T - The type of array elements
 * @param array - The array to filter
 * @param values - Values to remove
 * @returns A new array without the specified values
 *
 * @example
 * ```ts
 * without([1, 2, 3, 4, 5], 2, 4) // [1, 3, 5]
 * ```
 */
export declare function without<T>(array: T[], ...values: T[]): T[];
/**
 * Map and flatten in one operation
 *
 * @template T - The type of input array elements
 * @template R - The type of output array elements
 * @param array - The array to map
 * @param fn - Function that returns a value or array
 * @returns A flattened array of mapped values
 *
 * @example
 * ```ts
 * flatMap([1, 2, 3], x => [x, x * 2]) // [1, 2, 2, 4, 3, 6]
 * ```
 */
export declare function flatMap<T, R>(array: T[], fn: (item: T, index: number) => R | R[]): R[];
/**
 * Count occurrences of items by a key or function
 *
 * @template T - The type of array elements
 * @param array - The array to count
 * @param keyOrFn - A key of T or a function that returns a grouping key
 * @returns An object with keys as grouping keys and values as counts
 *
 * @example
 * ```ts
 * countBy([{ type: 'a' }, { type: 'b' }, { type: 'a' }], 'type')
 * // { a: 2, b: 1 }
 * ```
 */
export declare function countBy<T>(array: T[], keyOrFn: keyof T | ((item: T) => string | number)): Record<string, number>;
/**
 * Create an object from an array using a key
 *
 * @template T - The type of array elements
 * @param array - The array to convert
 * @param keyOrFn - A key of T or a function that returns a key
 * @returns An object with keys from the key function and values from the array
 *
 * @example
 * ```ts
 * keyBy([{ id: 1, name: 'a' }, { id: 2, name: 'b' }], 'id')
 * // { 1: { id: 1, name: 'a' }, 2: { id: 2, name: 'b' } }
 * ```
 */
export declare function keyBy<T>(array: T[], keyOrFn: keyof T | ((item: T) => string | number)): Record<string, T>;
export {};
//# sourceMappingURL=array.d.ts.map