indusagi-coding-agent 0.1.22 → 0.1.24

package/dist/utils/array.d.ts

@@ -0,0 +1,389 @@
+/**
+ * @fileoverview Advanced array manipulation utilities with functional programming patterns
+ *
+ * This module provides:
+ * - Array grouping and partitioning
+ * - Unique value extraction
+ * - Flattening and chunking
+ * - Sorting and searching
+ * - Array zipping and pairing
+ * - Filtering and transforming
+ * - Set operations (union, intersection, difference)
+ * - Performance optimized with O(n) complexity notes
+ *
+ * @example
+ * import { groupBy, unique, flatten, chunk, sortBy } from './array';
+ *
+ * const items = [{ id: 1, type: 'A' }, { id: 2, type: 'B' }];
+ * const grouped = groupBy(items, item => item.type);
+ * const flattened = flatten([1, [2, [3, [4]]]]);
+ *
+ * @author indusagi
+ * @version 1.0.0
+ */
+/**
+ * Group array items by key function
+ * @param items - Array to group
+ * @param keyFn - Function to determine grouping key
+ * @returns Object with grouped arrays
+ *
+ * Performance: O(n) where n = array length
+ *
+ * @example
+ * const users = [
+ *   { name: 'John', role: 'admin' },
+ *   { name: 'Jane', role: 'user' },
+ *   { name: 'Bob', role: 'admin' }
+ * ];
+ * const byRole = groupBy(users, u => u.role);
+ * // {
+ * //   admin: [{ name: 'John', role: 'admin' }, { name: 'Bob', role: 'admin' }],
+ * //   user: [{ name: 'Jane', role: 'user' }]
+ * // }
+ */
+export declare function groupBy<T, K extends string | number | symbol>(items: T[], keyFn: (item: T, index: number) => K): Record<K, T[]>;
+/**
+ * Get unique items from array
+ * @param items - Array with potential duplicates
+ * @param keyFn - Optional function to determine uniqueness
+ * @returns Array with unique items (preserves order of first occurrence)
+ *
+ * Performance: O(n) with Set, very efficient
+ *
+ * @example
+ * unique([1, 2, 2, 3, 3, 3, 4]);
+ * // [1, 2, 3, 4]
+ *
+ * @example
+ * const users = [
+ *   { id: 1, name: 'John' },
+ *   { id: 2, name: 'Jane' },
+ *   { id: 1, name: 'John' }
+ * ];
+ * const unique_ = unique(users, u => u.id);
+ * // [{ id: 1, name: 'John' }, { id: 2, name: 'Jane' }]
+ */
+export declare function unique<T, K = T>(items: T[], keyFn?: (item: T) => K): T[];
+/**
+ * Flatten nested array to specified depth
+ * @param items - Nested array
+ * @param depth - Flattening depth (default: Infinity)
+ * @returns Flattened array
+ *
+ * Performance: O(n) where n = total items at all levels
+ *
+ * @example
+ * flatten([1, [2, [3, [4]]]]);
+ * // [1, 2, 3, 4]
+ *
+ * @example
+ * flatten([1, [2, [3, [4]]]], 1);
+ * // [1, 2, [3, [4]]]
+ *
+ * @example
+ * flatten([1, [2, 3], [4, [5, 6]]]);
+ * // [1, 2, 3, 4, 5, 6]
+ */
+export declare function flatten<T>(items: any[], depth?: number): T[];
+/**
+ * Split array into chunks of specified size
+ * @param items - Array to chunk
+ * @param size - Chunk size
+ * @returns Array of chunks
+ *
+ * Performance: O(n) where n = array length
+ *
+ * @example
+ * chunk([1, 2, 3, 4, 5], 2);
+ * // [[1, 2], [3, 4], [5]]
+ *
+ * @example
+ * chunk(['a', 'b', 'c', 'd', 'e', 'f'], 3);
+ * // [['a', 'b', 'c'], ['d', 'e', 'f']]
+ */
+export declare function chunk<T>(items: T[], size: number): T[][];
+/**
+ * Sort array by criteria
+ * @param items - Array to sort
+ * @param compareFn - Comparison function
+ * @returns Sorted array (creates new array)
+ *
+ * Performance: O(n log n)
+ *
+ * @example
+ * const users = [
+ *   { name: 'Charlie', age: 30 },
+ *   { name: 'Alice', age: 25 },
+ *   { name: 'Bob', age: 25 }
+ * ];
+ * const sorted = sortBy(users, (a, b) => {
+ *   if (a.age !== b.age) return a.age - b.age;
+ *   return a.name.localeCompare(b.name);
+ * });
+ */
+export declare function sortBy<T>(items: T[], compareFn: (a: T, b: T) => number): T[];
+/**
+ * Find index of item matching predicate
+ * @param items - Array to search
+ * @param predicate - Test function
+ * @returns Index of first match or -1
+ *
+ * Performance: O(n) worst case
+ *
+ * @example
+ * const items = [10, 20, 30, 40];
+ * findIndex(items, x => x > 25); // 2
+ *
+ * @example
+ * const users = [{ id: 1 }, { id: 2 }, { id: 3 }];
+ * findIndex(users, u => u.id === 2); // 1
+ */
+export declare function findIndex<T>(items: T[], predicate: (item: T, index: number) => boolean): number;
+/**
+ * Find last index of item matching predicate
+ * @param items - Array to search
+ * @param predicate - Test function
+ * @returns Index of last match or -1
+ *
+ * @example
+ * const items = [10, 20, 30, 20, 40];
+ * findLastIndex(items, x => x === 20); // 3
+ */
+export declare function findLastIndex<T>(items: T[], predicate: (item: T, index: number) => boolean): number;
+/**
+ * Partition array into two arrays based on predicate
+ * @param items - Array to partition
+ * @param predicate - Test function
+ * @returns Tuple of [passing, failing]
+ *
+ * Performance: O(n)
+ *
+ * @example
+ * const numbers = [1, 2, 3, 4, 5, 6];
+ * const [even, odd] = partition(numbers, x => x % 2 === 0);
+ * // even: [2, 4, 6]
+ * // odd: [1, 3, 5]
+ *
+ * @example
+ * const users = [
+ *   { name: 'John', active: true },
+ *   { name: 'Jane', active: false },
+ *   { name: 'Bob', active: true }
+ * ];
+ * const [active, inactive] = partition(users, u => u.active);
+ */
+export declare function partition<T>(items: T[], predicate: (item: T) => boolean): [T[], T[]];
+/**
+ * Zip arrays together
+ * @param arrays - Arrays to zip
+ * @returns Array of tuples
+ *
+ * Performance: O(n) where n = length of shortest array
+ *
+ * @example
+ * const names = ['John', 'Jane', 'Bob'];
+ * const ages = [30, 28, 25];
+ * const zipped = zip(names, ages);
+ * // [['John', 30], ['Jane', 28], ['Bob', 25]]
+ *
+ * @example
+ * const a = [1, 2, 3];
+ * const b = ['a', 'b', 'c'];
+ * const c = [true, false, true];
+ * const result = zip(a, b, c);
+ * // [[1, 'a', true], [2, 'b', false], [3, 'c', true]]
+ */
+export declare function zip<T extends any[][]>(...arrays: T): Array<any[]>;
+/**
+ * Unzip array of tuples
+ * @param items - Array of tuples
+ * @returns Array of arrays
+ *
+ * @example
+ * const zipped = [['John', 30], ['Jane', 28], ['Bob', 25]];
+ * const [names, ages] = unzip(zipped);
+ * // names: ['John', 'Jane', 'Bob']
+ * // ages: [30, 28, 25]
+ */
+export declare function unzip<T extends any[]>(items: T[]): Array<any[]>;
+/**
+ * Get first n items from array
+ * @param items - Array
+ * @param n - Number of items
+ * @returns First n items
+ *
+ * @example
+ * take([1, 2, 3, 4, 5], 3); // [1, 2, 3]
+ */
+export declare function take<T>(items: T[], n: number): T[];
+/**
+ * Remove first n items from array
+ * @param items - Array
+ * @param n - Number of items to skip
+ * @returns Items after first n
+ *
+ * @example
+ * drop([1, 2, 3, 4, 5], 2); // [3, 4, 5]
+ */
+export declare function drop<T>(items: T[], n: number): T[];
+/**
+ * Get last n items from array
+ * @param items - Array
+ * @param n - Number of items
+ * @returns Last n items
+ *
+ * @example
+ * takeLast([1, 2, 3, 4, 5], 2); // [4, 5]
+ */
+export declare function takeLast<T>(items: T[], n: number): T[];
+/**
+ * Remove last n items from array
+ * @param items - Array
+ * @param n - Number of items to remove
+ * @returns Items excluding last n
+ *
+ * @example
+ * dropLast([1, 2, 3, 4, 5], 2); // [1, 2, 3]
+ */
+export declare function dropLast<T>(items: T[], n: number): T[];
+/**
+ * Find union of arrays (all unique items from all arrays)
+ * @param arrays - Arrays to union
+ * @returns Array of unique items from all arrays
+ *
+ * Performance: O(n) where n = total items
+ *
+ * @example
+ * union([1, 2, 3], [2, 3, 4], [3, 4, 5]);
+ * // [1, 2, 3, 4, 5]
+ */
+export declare function union<T>(...arrays: T[][]): T[];
+/**
+ * Find intersection of arrays (items present in all arrays)
+ * @param arrays - Arrays to intersect
+ * @returns Array of items present in all arrays
+ *
+ * Performance: O(n*m) where n = first array, m = other arrays
+ *
+ * @example
+ * intersection([1, 2, 3, 4], [2, 3, 4, 5], [3, 4, 5, 6]);
+ * // [3, 4]
+ */
+export declare function intersection<T>(...arrays: T[][]): T[];
+/**
+ * Find difference (items in first array not in others)
+ * @param first - First array
+ * @param rest - Other arrays to subtract
+ * @returns Items in first but not in others
+ *
+ * Performance: O(n+m) where n = first, m = total other items
+ *
+ * @example
+ * difference([1, 2, 3, 4], [2, 3], [4]);
+ * // [1]
+ */
+export declare function difference<T>(first: T[], ...rest: T[][]): T[];
+/**
+ * Remove duplicates while preserving order
+ * @param items - Array with potential duplicates
+ * @returns Array without duplicates
+ *
+ * @example
+ * compact([1, 2, 2, 3, 3, 3, 4, null, undefined]);
+ * // [1, 2, 3, 4, null, undefined]
+ */
+export declare function compact<T>(items: (T | null | undefined)[]): T[];
+/**
+ * Filter and map in one operation
+ * @param items - Array to transform
+ * @param fn - Function returning value or null/undefined to filter
+ * @returns Filtered and mapped array
+ *
+ * Performance: O(n)
+ *
+ * @example
+ * const items = [1, 2, 3, 4, 5];
+ * const result = mapFilter(items, x => x > 2 ? x * 2 : null);
+ * // [6, 8, 10]
+ */
+export declare function mapFilter<T, R>(items: T[], fn: (item: T) => R | null | undefined): R[];
+/**
+ * Shuffle array randomly
+ * @param items - Array to shuffle
+ * @returns Shuffled copy of array
+ *
+ * @example
+ * shuffle([1, 2, 3, 4, 5]);
+ * // [3, 1, 4, 5, 2] (random order)
+ */
+export declare function shuffle<T>(items: T[]): T[];
+/**
+ * Get random item from array
+ * @param items - Array to sample from
+ * @returns Random item or undefined if empty
+ *
+ * @example
+ * const item = sample([1, 2, 3, 4, 5]);
+ * // One random item from the array
+ */
+export declare function sample<T>(items: T[]): T | undefined;
+/**
+ * Get multiple random items from array
+ * @param items - Array to sample from
+ * @param n - Number of items to sample
+ * @returns Array of random items
+ *
+ * @example
+ * sampleSize([1, 2, 3, 4, 5], 3);
+ * // [2, 4, 1] (3 random items)
+ */
+export declare function sampleSize<T>(items: T[], n: number): T[];
+/**
+ * Find item with minimum value
+ * @param items - Array to search
+ * @param compareFn - Function to get comparable value
+ * @returns Item with minimum value or undefined
+ *
+ * @example
+ * const items = [{ val: 10 }, { val: 5 }, { val: 20 }];
+ * const min = minBy(items, x => x.val);
+ * // { val: 5 }
+ */
+export declare function minBy<T>(items: T[], compareFn: (item: T) => number): T | undefined;
+/**
+ * Find item with maximum value
+ * @param items - Array to search
+ * @param compareFn - Function to get comparable value
+ * @returns Item with maximum value or undefined
+ *
+ * @example
+ * const items = [{ val: 10 }, { val: 5 }, { val: 20 }];
+ * const max = maxBy(items, x => x.val);
+ * // { val: 20 }
+ */
+export declare function maxBy<T>(items: T[], compareFn: (item: T) => number): T | undefined;
+/**
+ * Sum array values
+ * @param items - Array to sum
+ * @param fn - Optional function to get numeric value
+ * @returns Sum of array
+ *
+ * @example
+ * sum([1, 2, 3, 4]); // 10
+ *
+ * @example
+ * const items = [{ val: 10 }, { val: 20 }];
+ * sum(items, x => x.val); // 30
+ */
+export declare function sum<T>(items: T[], fn?: (item: T) => number): number;
+/**
+ * Average array values
+ * @param items - Array to average
+ * @param fn - Optional function to get numeric value
+ * @returns Average of array
+ *
+ * @example
+ * average([1, 2, 3, 4]); // 2.5
+ */
+export declare function average<T>(items: T[], fn?: (item: T) => number): number;
+//# sourceMappingURL=array.d.ts.map

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

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