Sugar Array Module

import Sugar from "sugar";

const Sugar = require("sugar");

import Sugar from "sugar";

// Array construction
const numbers = Sugar.Array.range(1, 10);
// [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]

// Array modification
const fruits = ['apple', 'banana', 'cherry'];
Sugar.Array.add(fruits, 'date', 1);
// ['apple', 'date', 'banana', 'cherry']

// Statistical operations
const scores = [85, 92, 78, 96, 88];
const average = Sugar.Array.average(scores);
// 87.8

// Functional operations
const users = [
  { name: 'Alice', age: 30 },
  { name: 'Bob', age: 25 },
  { name: 'Charlie', age: 35 }
];
const grouped = Sugar.Array.groupBy(users, 'age');
// { 25: [{ name: 'Bob', age: 25 }], 30: [...], 35: [...] }

/**
 * Creates array with mapping function applied to each index
 * @param n - Number of elements to create
 * @param indexMapFn - Optional function to map each index to a value
 * @returns New array with mapped values
 */
function construct<T>(n: number, indexMapFn?: mapFn<number, T>): T[];

/**
 * Creates array from object, number, or other input
 * @param obj - Input to convert to array
 * @param clone - Whether to clone the input
 * @returns New array created from input
 */
function create<T>(obj: any, clone?: boolean): T[];

/**
 * Creates array containing range of numbers
 * @param start - Starting number (default: 0)
 * @param end - Ending number (exclusive)
 * @returns Array of numbers in range
 */
function range(start?: number, end?: number): number[];

// Create array with index mapping
const squares = Sugar.Array.construct(5, (i) => i * i);
// [0, 1, 4, 9, 16]

// Create array from various inputs
const fromString = Sugar.Array.create('hello');
// ['h', 'e', 'l', 'l', 'o']

// Create number ranges
const oneToTen = Sugar.Array.range(1, 11);
// [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]

const zeroToFive = Sugar.Array.range(6);
// [0, 1, 2, 3, 4, 5]

/**
 * Adds item to array at specified index
 * @param instance - Array to modify
 * @param item - Item to add
 * @param index - Position to insert (default: end)
 * @returns Modified array
 */
function add<T>(instance: T[], item: T, index?: number): T[];

/**
 * Appends item to array
 * @param instance - Array to modify
 * @param item - Item to append
 * @param index - Position to insert (default: end)
 * @returns Modified array
 */
function append<T>(instance: T[], item: T, index?: number): T[];

/**
 * Inserts item at specific index
 * @param instance - Array to modify
 * @param item - Item to insert
 * @param index - Position to insert (default: 0)
 * @returns Modified array
 */
function insert<T>(instance: T[], item: T, index?: number): T[];

/**
 * Removes all matching elements from array
 * @param instance - Array to modify
 * @param search - Item or function to match for removal
 * @returns Modified array
 */
function remove<T>(instance: T[], search: any): T[];

/**
 * Removes elements at specified indices
 * @param instance - Array to modify
 * @param start - Starting index
 * @param end - Ending index (optional)
 * @returns Modified array
 */
function removeAt<T>(instance: T[], start: number, end?: number): T[];

/**
 * Excludes matching elements from array
 * @param instance - Array to modify
 * @param search - Item or function to match for exclusion
 * @returns Modified array
 */
function exclude<T>(instance: T[], search: any): T[];

/**
 * Removes null, undefined, and optionally falsy values
 * @param instance - Array to compact
 * @param all - If true, removes all falsy values
 * @returns Array with null/undefined removed
 */
function compact<T>(instance: T[], all?: boolean): T[];

/**
 * Flattens nested arrays up to specified depth
 * @param instance - Array to flatten
 * @param limit - Maximum depth to flatten (default: 1)
 * @returns Flattened array
 */
function flatten<T>(instance: T[], limit?: number): T[];

/**
 * Removes duplicate elements from array
 * @param instance - Array to process
 * @param map - Optional function to determine uniqueness
 * @returns Array with duplicates removed
 */
function unique<T, U>(instance: T[], map?: mapFn<T, U>): T[];

/**
 * Randomizes array element order
 * @param instance - Array to shuffle
 * @returns Array with randomized order
 */
function shuffle<T>(instance: T[]): T[];

// Adding and inserting elements
const numbers = [1, 2, 3];
Sugar.Array.add(numbers, 4); // [1, 2, 3, 4]
Sugar.Array.insert(numbers, 0, 0); // [0, 1, 2, 3, 4]

// Removing elements
const colors = ['red', 'blue', 'green', 'blue'];
Sugar.Array.remove(colors, 'blue'); // ['red', 'green']

// Compacting arrays
const mixed = [1, null, 2, undefined, 3, '', 4, false];
Sugar.Array.compact(mixed); // [1, 2, 3, '', 4, false]
Sugar.Array.compact(mixed, true); // [1, 2, 3, 4]

// Flattening nested arrays
const nested = [[1, 2], [3, [4, 5]], 6];
Sugar.Array.flatten(nested); // [1, 2, 3, [4, 5], 6]
Sugar.Array.flatten(nested, 2); // [1, 2, 3, 4, 5, 6]

// Removing duplicates
const duplicates = [1, 2, 2, 3, 3, 3];
Sugar.Array.unique(duplicates); // [1, 2, 3]

// Unique by property
const users = [
  { id: 1, name: 'Alice' },
  { id: 2, name: 'Bob' },
  { id: 1, name: 'Alice Clone' }
];
Sugar.Array.unique(users, (u) => u.id); // [{ id: 1, name: 'Alice' }, { id: 2, name: 'Bob' }]

/**
 * Gets element at index with optional looping
 * @param instance - Array to access
 * @param index - Index to retrieve (supports negative indices)
 * @param loop - Whether to loop around array bounds
 * @returns Element at index
 */
function at<T>(instance: T[], index: number, loop?: boolean): T;

/**
 * Gets first n elements from array
 * @param instance - Array to access
 * @param num - Number of elements to get (default: 1)
 * @returns First n elements
 */
function first<T>(instance: T[], num?: number): T | T[];

/**
 * Gets last n elements from array
 * @param instance - Array to access
 * @param num - Number of elements to get (default: 1)
 * @returns Last n elements
 */
function last<T>(instance: T[], num?: number): T | T[];

/**
 * Gets slice from specified index to end
 * @param instance - Array to slice
 * @param index - Starting index
 * @returns Slice from index to end
 */
function from<T>(instance: T[], index: number): T[];

/**
 * Gets slice from beginning to specified index
 * @param instance - Array to slice
 * @param index - Ending index (exclusive)
 * @returns Slice from beginning to index
 */
function to<T>(instance: T[], index: number): T[];

/**
 * Gets random sample of elements from array
 * @param instance - Array to sample from
 * @param num - Number of elements to sample (default: 1)
 * @param remove - Whether to remove sampled elements
 * @returns Random sample of elements
 */
function sample<T>(instance: T[], num?: number, remove?: boolean): T | T[];

const letters = ['a', 'b', 'c', 'd', 'e'];

// Accessing with indices
Sugar.Array.at(letters, 0); // 'a'
Sugar.Array.at(letters, -1); // 'e'
Sugar.Array.at(letters, 10, true); // 'a' (loops around)

// Getting first/last elements
Sugar.Array.first(letters); // 'a'
Sugar.Array.first(letters, 3); // ['a', 'b', 'c']
Sugar.Array.last(letters, 2); // ['d', 'e']

// Slicing operations
Sugar.Array.from(letters, 2); // ['c', 'd', 'e']
Sugar.Array.to(letters, 3); // ['a', 'b', 'c']

// Random sampling
Sugar.Array.sample(letters); // Random single letter
Sugar.Array.sample(letters, 3); // Array of 3 random letters

/**
 * Finds first element matching search criteria
 * @param instance - Array to search
 * @param search - Search criteria (value, function, or object)
 * @param context - Optional context for function execution
 * @returns First matching element or undefined
 */
function find<T>(instance: T[], search: any, context?: any): T | undefined;

/**
 * Finds index of first element matching search criteria
 * @param instance - Array to search
 * @param search - Search criteria (value, function, or object)
 * @param context - Optional context for function execution
 * @returns Index of first match or -1 if not found
 */
function findIndex<T>(instance: T[], search: any, context?: any): number;

/**
 * Filters elements matching search criteria
 * @param instance - Array to filter
 * @param search - Filter criteria (value, function, or object)
 * @param context - Optional context for function execution
 * @returns Array of matching elements
 */
function filter<T>(instance: T[], search: any, context?: any): T[];

/**
 * Counts elements matching search criteria
 * @param instance - Array to count in
 * @param search - Count criteria (value, function, or object)
 * @param context - Optional context for function execution
 * @returns Number of matching elements
 */
function count<T>(instance: T[], search: any, context?: any): number;

const products = [
  { name: 'Laptop', price: 999, category: 'electronics' },
  { name: 'Book', price: 29, category: 'books' },
  { name: 'Phone', price: 699, category: 'electronics' }
];

// Finding elements
const laptop = Sugar.Array.find(products, { name: 'Laptop' });
const expensiveIndex = Sugar.Array.findIndex(products, (p) => p.price > 500);

// Filtering elements
const electronics = Sugar.Array.filter(products, { category: 'electronics' });
const affordable = Sugar.Array.filter(products, (p) => p.price < 100);

// Counting matches
const electronicsCount = Sugar.Array.count(products, { category: 'electronics' }); // 2
const expensiveCount = Sugar.Array.count(products, (p) => p.price > 500); // 2

/**
 * Tests if all elements match criteria
 * @param instance - Array to test
 * @param search - Test criteria (value, function, or object)
 * @param context - Optional context for function execution
 * @returns True if all elements match
 */
function every<T>(instance: T[], search: any, context?: any): boolean;

/**
 * Tests if some elements match criteria
 * @param instance - Array to test
 * @param search - Test criteria (value, function, or object)
 * @param context - Optional context for function execution
 * @returns True if at least one element matches
 */
function some<T>(instance: T[], search: any, context?: any): boolean;

/**
 * Tests if no elements match criteria
 * @param instance - Array to test
 * @param search - Test criteria (value, function, or object)
 * @param context - Optional context for function execution
 * @returns True if no elements match
 */
function none<T>(instance: T[], search: any, context?: any): boolean;

/**
 * Tests if array is empty
 * @param instance - Array to test
 * @returns True if array has no elements
 */
function isEmpty<T>(instance: T[]): boolean;

/**
 * Tests equality with another array
 * @param instance - First array
 * @param arr - Second array to compare
 * @returns True if arrays are deeply equal
 */
function isEqual<T>(instance: T[], arr: T[]): boolean;

const numbers = [2, 4, 6, 8, 10];
const mixed = [1, 2, 3, 4, 5];

// Testing all elements
Sugar.Array.every(numbers, (n) => n % 2 === 0); // true (all even)
Sugar.Array.every(mixed, (n) => n > 0); // true (all positive)

// Testing some elements
Sugar.Array.some(mixed, (n) => n > 4); // true (5 is > 4)
Sugar.Array.some(numbers, (n) => n > 10); // false

// Testing no elements
Sugar.Array.none(numbers, (n) => n % 2 === 1); // true (no odd numbers)
Sugar.Array.none(mixed, (n) => n < 0); // true (no negatives)

// Testing emptiness and equality
Sugar.Array.isEmpty([]); // true
Sugar.Array.isEmpty([1]); // false
Sugar.Array.isEqual([1, 2, 3], [1, 2, 3]); // true
Sugar.Array.isEqual([1, 2, 3], [1, 2, 4]); // false

/**
 * Returns intersection of two arrays
 * @param instance - First array
 * @param arr - Second array
 * @returns Array containing elements present in both arrays
 */
function intersect<T>(instance: T[], arr: T[]): T[];

/**
 * Removes items from array
 * @param instance - Array to subtract from
 * @param item - Item or array of items to remove
 * @returns Array with specified items removed
 */
function subtract<T>(instance: T[], item: T | T[]): T[];

/**
 * Returns union of two arrays
 * @param instance - First array
 * @param arr - Second array
 * @returns Array containing all unique elements from both arrays
 */
function union<T>(instance: T[], arr: T[]): T[];

const set1 = [1, 2, 3, 4, 5];
const set2 = [3, 4, 5, 6, 7];

// Intersection (common elements)
const common = Sugar.Array.intersect(set1, set2); // [3, 4, 5]

// Subtraction (remove elements)
const remaining = Sugar.Array.subtract(set1, [2, 4]); // [1, 3, 5]

// Union (all unique elements)
const combined = Sugar.Array.union(set1, set2); // [1, 2, 3, 4, 5, 6, 7]

// String arrays
const fruits1 = ['apple', 'banana', 'cherry'];
const fruits2 = ['banana', 'cherry', 'date'];
Sugar.Array.intersect(fruits1, fruits2); // ['banana', 'cherry']

/**
 * Groups elements by specified criteria
 * @param instance - Array to group
 * @param map - Grouping function or property name
 * @param groupFn - Optional function for processing groups
 * @returns Object with grouped elements
 */
function groupBy<T, U>(instance: T[], map?: mapFn<T, U>, groupFn?: Function): { [key: string]: T[] };

/**
 * Splits array into specified number of groups
 * @param instance - Array to split
 * @param num - Number of groups to create
 * @param padding - Value to pad incomplete groups
 * @returns Array of group arrays
 */
function inGroups<T>(instance: T[], num: number, padding?: T): T[][];

/**
 * Groups array into chunks of specified size
 * @param instance - Array to chunk
 * @param num - Size of each chunk
 * @param padding - Value to pad incomplete chunks
 * @returns Array of chunk arrays
 */
function inGroupsOf<T>(instance: T[], num: number, padding?: T): T[][];

/**
 * Sorts array by specified criteria
 * @param instance - Array to sort
 * @param map - Sorting function or property name
 * @param desc - Whether to sort in descending order
 * @returns Sorted array
 */
function sortBy<T, U>(instance: T[], map?: mapFn<T, U>, desc?: boolean): T[];

/**
 * Zips array with other arrays
 * @param instance - First array
 * @param args - Additional arrays to zip with
 * @returns Array of tuples containing elements from each position
 */
function zip<T>(instance: T[], ...args: T[][]): T[][];

const students = [
  { name: 'Alice', grade: 'A', class: 'Math' },
  { name: 'Bob', grade: 'B', class: 'Math' },
  { name: 'Charlie', grade: 'A', class: 'Science' },
  { name: 'David', grade: 'C', class: 'Science' }
];

// Grouping by property
const byGrade = Sugar.Array.groupBy(students, 'grade');
// { A: [Alice, Charlie], B: [Bob], C: [David] }

const byClass = Sugar.Array.groupBy(students, (s) => s.class);
// { Math: [Alice, Bob], Science: [Charlie, David] }

// Splitting into groups
const numbers = [1, 2, 3, 4, 5, 6, 7, 8];
const groups = Sugar.Array.inGroups(numbers, 3);
// [[1, 2, 3], [4, 5, 6], [7, 8]]

const chunks = Sugar.Array.inGroupsOf(numbers, 3);
// [[1, 2, 3], [4, 5, 6], [7, 8]]

// Sorting
const sorted = Sugar.Array.sortBy(students, 'name');
// Sorted alphabetically by name

const gradeSort = Sugar.Array.sortBy(students, 'grade', true);
// Sorted by grade descending (C, B, A)

// Zipping arrays
const names = ['Alice', 'Bob', 'Charlie'];
const ages = [25, 30, 35];
const cities = ['NYC', 'LA', 'Chicago'];
const zipped = Sugar.Array.zip(names, ages, cities);
// [['Alice', 25, 'NYC'], ['Bob', 30, 'LA'], ['Charlie', 35, 'Chicago']]

/**
 * Calculates average of array elements
 * @param instance - Array to process
 * @param map - Optional function to extract numeric values
 * @returns Average value
 */
function average<T, U>(instance: T[], map?: mapFn<T, U>): number;

/**
 * Calculates sum of array elements
 * @param instance - Array to process
 * @param map - Optional function to extract numeric values
 * @returns Sum of values
 */
function sum<T, U>(instance: T[], map?: mapFn<T, U>): number;

/**
 * Finds minimum elements in array
 * @param instance - Array to process
 * @param all - Whether to return all minimum elements or just one
 * @param map - Optional function to extract comparable values
 * @returns Minimum element(s)
 */
function min<T, U>(instance: T[], all?: boolean, map?: mapFn<T, U>): T | T[];

/**
 * Finds maximum elements in array
 * @param instance - Array to process
 * @param all - Whether to return all maximum elements or just one
 * @param map - Optional function to extract comparable values
 * @returns Maximum element(s)
 */
function max<T, U>(instance: T[], all?: boolean, map?: mapFn<T, U>): T | T[];

/**
 * Finds minimum elements in array (alias for min)
 * @param instance - Array to process
 * @param all - Whether to return all minimum elements or just one
 * @param map - Optional function to extract comparable values
 * @returns Minimum element(s)
 */
function least<T, U>(instance: T[], all?: boolean, map?: mapFn<T, U>): T | T[];

/**
 * Finds maximum elements in array (alias for max)
 * @param instance - Array to process
 * @param all - Whether to return all maximum elements or just one
 * @param map - Optional function to extract comparable values
 * @returns Maximum element(s)
 */
function most<T, U>(instance: T[], all?: boolean, map?: mapFn<T, U>): T | T[];

/**
 * Calculates median of array elements
 * @param instance - Array to process
 * @param map - Optional function to extract numeric values
 * @returns Median value
 */
function median<T, U>(instance: T[], map?: mapFn<T, U>): number;

// Basic statistical operations
const scores = [85, 92, 78, 96, 88, 90];

Sugar.Array.average(scores); // 88.17
Sugar.Array.sum(scores); // 529
Sugar.Array.min(scores); // 78
Sugar.Array.max(scores); // 96
Sugar.Array.median(scores); // 89

// With object arrays and mapping functions
const products = [
  { name: 'Laptop', price: 999 },
  { name: 'Book', price: 29 },
  { name: 'Phone', price: 699 },
  { name: 'Tablet', price: 299 }
];

Sugar.Array.average(products, (p) => p.price); // 506.5
Sugar.Array.sum(products, 'price'); // 2026
Sugar.Array.min(products, false, 'price'); // { name: 'Book', price: 29 }
Sugar.Array.max(products, false, (p) => p.price); // { name: 'Laptop', price: 999 }

// Finding all min/max elements
const grades = [85, 92, 85, 96, 92];
Sugar.Array.min(grades, true); // [85, 85] (all minimum values)
Sugar.Array.max(grades, true); // [96] (all maximum values)

// Complex mapping
const teams = [
  { name: 'Alpha', members: 5 },
  { name: 'Beta', members: 3 },
  { name: 'Gamma', members: 8 },
  { name: 'Delta', members: 3 }
];

Sugar.Array.least(teams, true, 'members'); 
// [{ name: 'Beta', members: 3 }, { name: 'Delta', members: 3 }]

/**
 * Maps elements using transformation function
 * @param instance - Array to transform
 * @param map - Transformation function
 * @param context - Optional context for function execution
 * @returns New array with transformed elements
 */
function map<T, U>(instance: T[], map: mapFn<T, U>, context?: any): U[];

/**
 * Creates deep clone of array and its elements
 * @param instance - Array to clone
 * @returns Deep clone of array
 */
function clone<T>(instance: T[]): T[];

// Basic mapping
const numbers = [1, 2, 3, 4, 5];
const doubled = Sugar.Array.map(numbers, (n) => n * 2);
// [2, 4, 6, 8, 10]

// Complex object mapping
const users = [
  { firstName: 'John', lastName: 'Doe', age: 30 },
  { firstName: 'Jane', lastName: 'Smith', age: 25 }
];

const fullNames = Sugar.Array.map(users, (user) => `${user.firstName} ${user.lastName}`);
// ['John Doe', 'Jane Smith']

const adults = Sugar.Array.map(users, (user) => ({
  name: `${user.firstName} ${user.lastName}`,
  isAdult: user.age >= 18
}));

// Deep cloning
const original = [
  { id: 1, tags: ['a', 'b'] },
  { id: 2, tags: ['c', 'd'] }
];

const cloned = Sugar.Array.clone(original);
cloned[0].tags.push('e'); // Doesn't affect original

/**
 * Mapping function type for transforming array elements
 */
type mapFn<T, U> = (item: T, index: number, array: T[]) => U;

/**
 * Sugar Array namespace containing all array methods
 */
declare namespace Array {
  // Construction & Creation
  function construct<T>(n: number, indexMapFn?: mapFn<number, T>): T[];
  function create<T>(obj: any, clone?: boolean): T[];
  function range(start?: number, end?: number): number[];

  // Modification
  function add<T>(instance: T[], item: T, index?: number): T[];
  function append<T>(instance: T[], item: T, index?: number): T[];
  function insert<T>(instance: T[], item: T, index?: number): T[];
  function remove<T>(instance: T[], search: any): T[];
  function removeAt<T>(instance: T[], start: number, end?: number): T[];
  function exclude<T>(instance: T[], search: any): T[];
  function compact<T>(instance: T[], all?: boolean): T[];
  function flatten<T>(instance: T[], limit?: number): T[];
  function unique<T, U>(instance: T[], map?: mapFn<T, U>): T[];
  function shuffle<T>(instance: T[]): T[];

  // Access
  function at<T>(instance: T[], index: number, loop?: boolean): T;
  function first<T>(instance: T[], num?: number): T | T[];
  function last<T>(instance: T[], num?: number): T | T[];
  function from<T>(instance: T[], index: number): T[];
  function to<T>(instance: T[], index: number): T[];
  function sample<T>(instance: T[], num?: number, remove?: boolean): T | T[];

  // Search & Filter
  function find<T>(instance: T[], search: any, context?: any): T | undefined;
  function findIndex<T>(instance: T[], search: any, context?: any): number;
  function filter<T>(instance: T[], search: any, context?: any): T[];
  function count<T>(instance: T[], search: any, context?: any): number;

  // Test
  function every<T>(instance: T[], search: any, context?: any): boolean;
  function some<T>(instance: T[], search: any, context?: any): boolean;
  function none<T>(instance: T[], search: any, context?: any): boolean;
  function isEmpty<T>(instance: T[]): boolean;
  function isEqual<T>(instance: T[], arr: T[]): boolean;

  // Set Operations
  function intersect<T>(instance: T[], arr: T[]): T[];
  function subtract<T>(instance: T[], item: T | T[]): T[];
  function union<T>(instance: T[], arr: T[]): T[];

  // Grouping & Organization
  function groupBy<T, U>(instance: T[], map?: mapFn<T, U>, groupFn?: Function): { [key: string]: T[] };
  function inGroups<T>(instance: T[], num: number, padding?: T): T[][];
  function inGroupsOf<T>(instance: T[], num: number, padding?: T): T[][];
  function sortBy<T, U>(instance: T[], map?: mapFn<T, U>, desc?: boolean): T[];
  function zip<T>(instance: T[], ...args: T[][]): T[][];

  // Statistical
  function average<T, U>(instance: T[], map?: mapFn<T, U>): number;
  function sum<T, U>(instance: T[], map?: mapFn<T, U>): number;
  function min<T, U>(instance: T[], all?: boolean, map?: mapFn<T, U>): T | T[];
  function max<T, U>(instance: T[], all?: boolean, map?: mapFn<T, U>): T | T[];
  function least<T, U>(instance: T[], all?: boolean, map?: mapFn<T, U>): T | T[];
  function most<T, U>(instance: T[], all?: boolean, map?: mapFn<T, U>): T | T[];
  function median<T, U>(instance: T[], map?: mapFn<T, U>): number;

  // Transformation
  function map<T, U>(instance: T[], map: mapFn<T, U>, context?: any): U[];
  function clone<T>(instance: T[]): T[];
}