Immutable Arrays

/**
 * Non-mutating Array.prototype.push()
 * @param list - Original array
 * @param items - Items to add
 * @returns New array with added items
 */
function push<T>(list: readonly T[], ...items: T[]): T[];

/**
 * Non-mutating function that drops n items from the array start
 * @param list - Original array
 * @param n - Number of items to drop (default: 1)
 * @returns New array with items dropped from start
 */
function drop<T>(list: T[], n?: number): T[];

/**
 * Non-mutating function that drops n items from the array end
 * @param list - Original array
 * @param n - Number of items to drop (default: 1)
 * @returns New array with items dropped from end
 */
function dropRight<T>(list: T[], n?: number): T[];

/**
 * Standalone Array.prototype.slice() function
 * @param list - Original array
 * @param start - Start index
 * @param end - End index
 * @returns New sliced array
 */
function slice<T>(list: readonly T[], start?: number, end?: number): T[];

import { createSignal } from "solid-js";
import { push, drop, dropRight, slice } from "@solid-primitives/utils/immutable";

const [items, setItems] = createSignal([1, 2, 3]);

// Add items
setItems(current => push(current, 4, 5)); // [1, 2, 3, 4, 5]

// Drop from start
setItems(current => drop(current, 2)); // [3, 4, 5]

// Drop from end  
setItems(current => dropRight(current, 1)); // [3, 4]

// Slice
const subset = slice(items(), 1, 3); // [4] (from current state)

/**
 * Standalone Array.prototype.filter()
 * @param list - Original array
 * @param predicate - Filter predicate function
 * @returns New filtered array with removed count property
 */
function filter<T>(list: readonly T[], predicate: Predicate<T>): T[] & { removed: number };

/**
 * Standalone Array.prototype.filter() that filters out passed item
 * @param list - Original array
 * @param item - Item to filter out
 * @returns New filtered array with removed count property
 */
function filterOut<T>(list: readonly T[], item: T): T[] & { removed: number };

/**
 * Returns a subset of items that are instances of provided Classes
 * @param list - Original array
 * @param classes - Classes to filter by
 * @returns New array with only instances of specified classes
 */
function filterInstance<T, I extends AnyClass[]>(
  list: readonly T[],
  ...classes: I
): Extract<T, InstanceType<ItemsOf<I>>>[];

/**
 * Returns a subset of items that aren't instances of provided Classes
 * @param list - Original array
 * @param classes - Classes to filter out
 * @returns New array excluding instances of specified classes
 */
function filterOutInstance<T, I extends AnyClass[]>(
  list: readonly T[],
  ...classes: I
): Exclude<T, InstanceType<ItemsOf<I>>>[];

type Predicate<T> = (item: T, index: number, array: readonly T[]) => boolean;

import { filter, filterOut, filterInstance } from "@solid-primitives/utils/immutable";

const numbers = [1, 2, 3, 4, 5];
const result = filter(numbers, x => x > 3);
console.log(result); // [4, 5]
console.log(result.removed); // 3

const withoutTwo = filterOut(numbers, 2); // [1, 3, 4, 5]

// Class filtering
class Dog {}
class Cat {}
const animals = [new Dog(), new Cat(), new Dog()];
const dogs = filterInstance(animals, Dog); // [Dog, Dog]

/**
 * Standalone Array.prototype.map() function
 * @param list - Original array
 * @param mapFn - Mapping function
 * @returns New mapped array
 */
function map<T, V>(list: readonly T[], mapFn: MappingFn<T, V>): V[];

/**
 * Flattens a nested array into a one-level array
 * @param arr - Nested array to flatten
 * @returns Flattened array
 */
function flatten<T extends any[]>(arr: T): FlattenArray<T>[];

/**
 * Creates a new array concatenating array with any additional arrays and/or values
 * @param a - Arrays or values to concatenate
 * @returns New concatenated array
 */
function concat<A extends any[], V extends ItemsOf<A>>(
  ...a: A
): Array<V extends any[] ? ItemsOf<V> : V>;

type MappingFn<T, V> = (item: T, index: number, array: readonly T[]) => V;
type FlattenArray<T> = T extends any[] ? FlattenArray<ItemsOf<T>> : T;

import { map, flatten, concat } from "@solid-primitives/utils/immutable";

// Mapping
const doubled = map([1, 2, 3], x => x * 2); // [2, 4, 6]

// Flattening
const nested = [[1, 2], [3, [4, 5]]];
const flat = flatten(nested); // [1, 2, 3, 4, 5]

// Concatenation
const combined = concat([1, 2], [3, 4], 5); // [1, 2, 3, 4, 5]

/**
 * Non-mutating Array.prototype.sort() as a standalone function
 * @param list - Original array
 * @param compareFn - Optional comparison function
 * @returns New sorted array
 */
function sort<T>(list: T[], compareFn?: (a: T, b: T) => number): T[];

/**
 * Sort an array by object key, or multiple keys
 * @param arr - Array to sort
 * @param paths - Property paths or functions to sort by
 * @returns New sorted array
 */
function sortBy<T>(
  arr: T[],
  ...paths: T extends object ? (Many<keyof T> | Many<(item: T) => any>)[] : Many<(item: T) => any>[]
): T[];

import { sort, sortBy } from "@solid-primitives/utils/immutable";

// Basic sorting
const sorted = sort([3, 1, 4, 1, 5]); // [1, 1, 3, 4, 5]
const descending = sort([3, 1, 4], (a, b) => b - a); // [4, 3, 1]

// Object sorting
const users = [
  { name: "Alice", age: 30 },
  { name: "Bob", age: 25 },
  { name: "Carol", age: 35 }
];
const byAge = sortBy(users, "age"); // Sorted by age ascending
const byName = sortBy(users, user => user.name.toLowerCase());

/**
 * Non-mutating Array.prototype.splice() as a standalone function
 * @param list - Original array
 * @param start - Start index
 * @param deleteCount - Number of items to delete (default: 0)
 * @param items - Items to insert
 * @returns New array with modifications
 */
function splice<T>(
  list: readonly T[],
  start: number,
  deleteCount?: number,
  ...items: T[]
): T[];

/**
 * Non-mutating Array.prototype.fill() as a standalone function
 * @param list - Original array
 * @param value - Value to fill with
 * @param start - Start index
 * @param end - End index
 * @returns New filled array
 */
function fill<T>(list: readonly T[], value: T, start?: number, end?: number): T[];

/**
 * Remove item from array
 * @param list - Original array
 * @param item - Item to remove
 * @param insertItems - Items to insert in place of removed item
 * @returns New array with item removed/replaced
 */
function remove<T>(list: readonly T[], item: T, ...insertItems: T[]): T[];

/**
 * Remove multiple items from an array
 * @param list - Original array
 * @param items - Items to remove
 * @returns New array with items removed
 */
function removeItems<T>(list: readonly T[], ...items: T[]): T[];

import { splice, fill, remove, removeItems } from "@solid-primitives/utils/immutable";

const numbers = [1, 2, 3, 4, 5];

// Splice operations
const spliced = splice(numbers, 2, 1, 99); // [1, 2, 99, 4, 5] (removed 3, added 99)
const inserted = splice(numbers, 2, 0, 88, 89); // [1, 2, 88, 89, 3, 4, 5]

// Fill operations
const filled = fill([1, 2, 3, 4, 5], 0, 1, 4); // [1, 0, 0, 0, 5]

// Remove operations
const withoutThree = remove(numbers, 3); // [1, 2, 4, 5]
const replaced = remove(numbers, 3, 33); // [1, 2, 33, 4, 5]
const withoutMultiple = removeItems(numbers, 2, 4); // [1, 3, 5]

type Predicate<T> = (item: T, index: number, array: readonly T[]) => boolean;
type MappingFn<T, V> = (item: T, index: number, array: readonly T[]) => V;
type FlattenArray<T> = T extends any[] ? FlattenArray<ItemsOf<T>> : T;
type Many<T> = T | T[];
type ItemsOf<T> = T extends (infer E)[] ? E : never;
type AnyClass = abstract new (...args: any) => any;