Base Utilities

/**
 * Universal iterator for objects and arrays
 * @param obj - Object or array to iterate
 * @param iterate - Iterator function receiving (value, key/index, obj)
 * @param context - Optional context for iterator
 */
function each<T, C = any>(
  obj: T[] | T, 
  iterate: (this: C, value: any, key: string | number, obj: T[] | T) => void, 
  context?: C
): void;

/**
 * For-of style iteration
 * @param obj - Object or array to iterate
 * @param iterate - Iterator function
 * @param context - Optional context
 */
function forOf<T, C = any>(
  obj: T[] | T, 
  iterate: (this: C, value: any, key: string | number, obj: T[] | T) => void, 
  context?: C
): void;

/**
 * Reverse iteration
 * @param obj - Object or array to iterate
 * @param iterate - Iterator function
 * @param context - Optional context
 */
function lastEach<T, C = any>(
  obj: T[] | T, 
  iterate: (this: C, value: any, key: string | number, obj: T[] | T) => void, 
  context?: C
): void;

/**
 * Get value at object path
 * @param obj - Object to access
 * @param path - Property path (string or array)
 * @param defaultValue - Default value if path doesn't exist
 * @returns Value at path or default value
 */
function get(obj: any, path: string | string[], defaultValue?: any): any;

/**
 * Set value at object path
 * @param obj - Object to modify
 * @param path - Property path (string or array)
 * @param value - Value to set
 * @returns Modified object
 */
function set(obj: any, path: string | string[], value: any): any;

/**
 * Check if object has property at path
 * @param obj - Object to check
 * @param path - Property path
 * @returns True if path exists
 */
function has(obj: any, path: string | string[]): boolean;

/**
 * Check if object has own property (not inherited)
 * @param obj - Object to check
 * @param key - Property key
 * @returns True if object has own property
 */
function hasOwnProp(obj: any, key: string): boolean;

/**
 * Get object keys
 * @param obj - Object to get keys from
 * @returns Array of object keys
 */
function keys(obj: any): string[];

/**
 * Get object values
 * @param obj - Object to get values from
 * @returns Array of object values
 */
function values(obj: any): any[];

/**
 * Get object entries as key-value pairs
 * @param obj - Object to get entries from
 * @returns Array of [key, value] pairs
 */
function entries(obj: any): [string, any][];

/**
 * Pick specified properties from object
 * @param obj - Source object
 * @param keys - Keys to pick (array or multiple arguments)
 * @returns New object with picked properties
 */
function pick(obj: any, keys: string[] | string): any;

/**
 * Omit specified properties from object
 * @param obj - Source object
 * @param keys - Keys to omit (array or multiple arguments)
 * @returns New object without omitted properties
 */
function omit(obj: any, keys: string[] | string): any;

/**
 * Clone object or array
 * @param obj - Object to clone
 * @param deep - Whether to perform deep clone (default: shallow)
 * @returns Cloned object
 */
function clone<T>(obj: T, deep?: boolean): T;

/**
 * Clear object or array properties
 * @param obj - Object to clear
 * @param defs - Default values to set
 * @param assigns - Additional values to assign
 * @returns Cleared object
 */
function clear(obj: any, defs?: any, assigns?: any): any;

/**
 * Get size/length of collection
 * @param obj - Collection to measure
 * @returns Size of collection
 */
function getSize(obj: any): number;

/**
 * Remove elements from collection
 * @param obj - Collection to modify
 * @param iterate - Predicate function for removal
 * @param context - Optional context
 * @returns Modified collection
 */
function remove<T, C = any>(
  obj: T[] | T, 
  iterate: (this: C, value: any, key: string | number, obj: T[] | T) => boolean, 
  context?: C
): T[] | T;

/**
 * Group array elements by computed key
 * @param array - Array to group
 * @param iterate - Function to compute grouping key
 * @param context - Optional context for iterator
 * @returns Object with grouped elements
 */
function groupBy<T, C = any>(
  array: T[], 
  iterate: (this: C, item: T) => string | number, 
  context?: C
): { [key: string]: T[] };

/**
 * Count array elements by computed key
 * @param array - Array to count
 * @param iterate - Function to compute counting key
 * @param context - Optional context for iterator
 * @returns Object with counts for each key
 */
function countBy<T, C = any>(
  array: T[], 
  iterate: (this: C, item: T) => string | number, 
  context?: C
): { [key: string]: number };

/**
 * Find index of element using predicate
 * @param array - Array to search
 * @param iterate - Predicate function
 * @param context - Optional context
 * @returns Index of matching element or -1
 */
function findIndexOf<T, C = any>(
  array: T[], 
  iterate: (this: C, item: T, index: number, array: T[]) => boolean, 
  context?: C
): number;

/**
 * Find last index of element using predicate
 * @param array - Array to search
 * @param iterate - Predicate function
 * @param context - Optional context
 * @returns Last index of matching element or -1
 */
function findLastIndexOf<T, C = any>(
  array: T[], 
  iterate: (this: C, item: T, index: number, array: T[]) => boolean, 
  context?: C
): number;

/**
 * Find index of element
 * @param array - Array to search
 * @param searchElement - Element to find
 * @param fromIndex - Starting index
 * @returns Index of element or -1
 */
function indexOf<T>(array: T[], searchElement: T, fromIndex?: number): number;

/**
 * Find last index of element
 * @param array - Array to search
 * @param searchElement - Element to find
 * @param fromIndex - Starting index for reverse search
 * @returns Last index of element or -1
 */
function lastIndexOf<T>(array: T[], searchElement: T, fromIndex?: number): number;

/**
 * Get first element of array
 * @param array - Array to access
 * @returns First element or undefined
 */
function first<T>(array: T[]): T | undefined;

/**
 * Get last element of array
 * @param array - Array to access
 * @returns Last element or undefined
 */
function last<T>(array: T[]): T | undefined;

/**
 * Convert value to JSON string
 * @param obj - Value to convert
 * @returns JSON string representation
 */
function toStringJSON(obj: any): string;

/**
 * Convert value to JSON string (alias for toStringJSON)
 * @param obj - Value to convert
 * @returns JSON string representation
 */
function toJSONString(obj: any): string;

/**
 * Generate unique ID
 * @param prefix - Optional prefix for ID
 * @returns Unique ID string
 */
function uniqueId(prefix?: string): string;

/**
 * Generate range of numbers
 * @param start - Start number (or count if only parameter)
 * @param stop - End number
 * @param step - Step increment (default: 1)
 * @returns Array of numbers in range
 */
function range(start: number, stop?: number, step?: number): number[];

/**
 * Destructure object properties to destination
 * @param destination - Destination object
 * @param source - Source object
 * @param keys - Keys to destructure
 * @returns Destination object with destructured properties
 */
function destructuring(destination: any, source: any, ...keys: string[]): any;

import { 
  each, get, set, has, clone, keys, values, 
  pick, omit, first, last, range, uniqueId 
} from 'xe-utils';

// Universal iteration
const data = { a: 1, b: 2, c: 3 };
each(data, (value, key) => {
  console.log(`${key}: ${value}`);
});

// Safe property access
const user = {
  profile: {
    personal: {
      name: 'Alice',
      age: 25
    }
  }
};

const name = get(user, 'profile.personal.name'); // 'Alice'
const email = get(user, 'profile.contact.email', 'No email'); // 'No email'

set(user, 'profile.contact.email', 'alice@example.com');
console.log(has(user, 'profile.contact.email')); // true

// Object manipulation
const original = { a: 1, b: 2, c: 3, d: 4 };
const picked = pick(original, ['a', 'c']); // { a: 1, c: 3 }
const omitted = omit(original, ['b', 'd']); // { a: 1, c: 3 }

console.log(keys(original)); // ['a', 'b', 'c', 'd']
console.log(values(original)); // [1, 2, 3, 4]

// Cloning
const deepObject = { user: { name: 'Alice', scores: [1, 2, 3] } };
const shallowCopy = clone(deepObject); // Shallow clone
const deepCopy = clone(deepObject, true); // Deep clone

// Array utilities
const numbers = [10, 20, 30, 40, 50];
console.log(first(numbers)); // 10
console.log(last(numbers)); // 50

// Generate utilities
const id1 = uniqueId(); // 'xe-123456'
const id2 = uniqueId('user-'); // 'user-123457'

const sequence = range(1, 6); // [1, 2, 3, 4, 5]
const steps = range(0, 10, 2); // [0, 2, 4, 6, 8]