ts-data-forge 1.5.2 → 2.0.0

package/dist/array/array-utils.mjs

@@ -2,7 +2,6 @@ import '../collections/imap-mapped.mjs';
 import { IMap } from '../collections/imap.mjs';
 import '../collections/iset-mapped.mjs';
 import '../collections/iset.mjs';
-import './tuple-utils.mjs';
 import { isString, isUndefined } from '../guard/is-type.mjs';
 import { Optional } from '../functional/optional.mjs';
 import { pipe } from '../functional/pipe.mjs';
@@ -52,11 +51,90 @@ import { range } from '../iterator/range.mjs';
  */
 var Arr;
 (function (Arr) {
-    function size(array) {
-        return asUint32(array.length);
-    }
-    Arr.size = size;
-    Arr.length = size;
+    /**
+     * Returns the size (length) of an array as a type-safe branded integer.
+     *
+     * This function provides the array length with enhanced type safety through branded types:
+     * - For arrays known to be non-empty at compile time: returns `PositiveNumber & SizeType.Arr`
+     * - For general arrays that may be empty: returns `SizeType.Arr` (branded Uint32)
+     *
+     * The returned value is always a non-negative integer that can be safely used for array indexing
+     * and size comparisons. The branded type prevents common integer overflow issues and provides
+     * better type checking than plain numbers.
+     *
+     * @template Ar The exact type of the input array, used for precise return type inference.
+     * @param array The array to measure. Can be any readonly array type.
+     * @returns The length of the array as a branded type:
+     *   - `IntersectBrand<PositiveNumber, SizeType.Arr>` for known non-empty arrays
+     *   - `SizeType.Arr` for general arrays (branded Uint32, may be 0)
+     *
+     * @example
+     * ```typescript
+     * // Known non-empty arrays get positive branded type
+     * const tuple = [1, 2, 3] as const;
+     * const tupleSize = Arr.size(tuple);
+     * // Type: IntersectBrand<PositiveNumber, SizeType.Arr>
+     * // Value: 3 (branded, guaranteed positive)
+     *
+     * const nonEmpty: NonEmptyArray<string> = ['a', 'b'];
+     * const nonEmptySize = Arr.size(nonEmpty);
+     * // Type: IntersectBrand<PositiveNumber, SizeType.Arr>
+     * // Guaranteed to be > 0
+     *
+     * // General arrays may be empty, get regular branded type
+     * const generalArray: number[] = [1, 2, 3];
+     * const generalSize = Arr.size(generalArray);
+     * // Type: SizeType.Arr (branded Uint32)
+     * // May be 0 or positive
+     *
+     * // Empty arrays
+     * const emptyArray = [] as const;
+     * const emptySize = Arr.size(emptyArray);
+     * // Type: SizeType.Arr
+     * // Value: 0 (branded)
+     *
+     * // Runtime arrays with unknown content
+     * const dynamicArray = Array.from({ length: Math.random() * 10 }, (_, i) => i);
+     * const dynamicSize = Arr.size(dynamicArray);
+     * // Type: SizeType.Arr (may be 0)
+     *
+     * // Using size for safe operations
+     * const data = [10, 20, 30];
+     * const dataSize = Arr.size(data);
+     *
+     * // Safe for array creation
+     * const indices = Arr.seq(dataSize); // Creates [0, 1, 2]
+     * const zeros = Arr.zeros(dataSize); // Creates [0, 0, 0]
+     *
+     * // Functional composition
+     * const arrays = [
+     *   [1, 2],
+     *   [3, 4, 5],
+     *   [],
+     *   [6]
+     * ];
+     * const sizes = arrays.map(Arr.size); // [2, 3, 0, 1] (all branded)
+     * const totalElements = sizes.reduce(Uint32.add, 0); // 6
+     *
+     * // Type guards work with size
+     * if (Arr.size(data) > 0) {
+     *   // TypeScript knows data is non-empty here
+     *   const firstElement = data[0]; // Safe access
+     * }
+     *
+     * // Type inference examples
+     * expectType<typeof tupleSize, IntersectBrand<PositiveNumber, SizeType.Arr>>('=');
+     * expectType<typeof generalSize, SizeType.Arr>('=');
+     * expectType<typeof emptySize, SizeType.Arr>('=');
+     * ```
+     *
+     * @see {@link length} - Alias for this function
+     * @see {@link isEmpty} for checking if size is 0
+     * @see {@link isNonEmpty} for checking if size > 0
+     */
+    Arr.size = (array) => 
+    // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion
+    array.length;
     // type guard
     /**
      * Type guard that checks if a value is an array, excluding types that cannot be arrays.
@@ -106,26 +184,11 @@ var Arr;
      *   if (Arr.isEmpty(arr)) {
      *     // arr is now typed as readonly []
      *     console.log('Array is empty');
+     *     // arr[0]; // type error!
      *     return 0;
-     *   } else {
-     *     // arr is now typed as NonEmptyArray<number>
-     *     return arr[0]; // Safe access - TypeScript knows it's non-empty
      *   }
      * }
      *
-     * // Conditional processing
-     * const data = [10, 20, 30];
-     * if (!Arr.isEmpty(data)) {
-     *   // Safe to access elements
-     *   const firstElement = data[0]; // No undefined risk
-     *   const lastElement = data[data.length - 1];
-     * }
-     *
-     * // Filtering empty arrays
-     * const arrayList: readonly number[][] = [[1, 2], [], [3], []];
-     * const nonEmptyArrays = arrayList.filter(arr => !Arr.isEmpty(arr));
-     * // nonEmptyArrays: [[1, 2], [3]]
-     *
      * // Early returns
      * function sumArray(numbers: readonly number[]): number {
      *   if (Arr.isEmpty(numbers)) {
@@ -134,12 +197,6 @@ var Arr;
      *   return numbers.reduce((sum, n) => sum + n, 0);
      * }
      *
-     * // Type inference examples
-     * const testEmpty = [] as const;
-     * const testNonEmpty = [1, 2] as const;
-     *
-     * expectType<Parameters<typeof Arr.isEmpty>[0], readonly unknown[]>('=');
-     * expectType<ReturnType<typeof Arr.isEmpty>, boolean>('=');
      * ```
      *
      * @see {@link isNonEmpty} for the opposite check (non-empty arrays)
@@ -180,16 +237,14 @@ var Arr;
      *
      * // Safe operations on non-empty arrays
      * function processData(data: readonly string[]) {
-     *   if (Arr.isNonEmpty(data)) {
-     *     // All of these are now safe without undefined checks
-     *     const first = data[0];
-     *     const last = data[data.length - 1];
-     *     const middle = data[Math.floor(data.length / 2)];
-     *
-     *     // Can safely use non-empty array methods
-     *     const joined = data.join(', ');
-     *     const reduced = data.reduce((acc, item) => acc + item.length, 0);
-     *   }
+     *   if (!Arr.isNonEmpty(data)) return;  // early return pattern
+     *
+     *   // This is now safe without undefined checks
+     *   const first = data[0];
+     *
+     *   // Can safely use non-empty array methods
+     *   const lastElement = Arr.last(data);
+     *
      * }
      *
      * // Filtering and working with arrays
@@ -214,7 +269,7 @@ var Arr;
      *   }
      *
      *   // numbers is now NonEmptyArray<number>
-     *   return numbers.reduce((sum, n) => sum + n, 0) / numbers.length;
+     *   return Arr.sum(numbers) / Arr.size(numbers);
      * }
      *
      * // Functional composition
@@ -309,19 +364,141 @@ var Arr;
      * ```
      */
     Arr.indexIsInRange = (array, index) => Num.isInRange(0, array.length)(index);
-    function zeros(len) {
-        return Array.from({ length: len }).fill(0);
-    }
-    Arr.zeros = zeros;
-    function seq(len) {
-        return Array.from({ length: len }, (_, i) => asUint32(i));
-    }
-    Arr.seq = seq;
-    function create(len, init) {
-        return Array.from({ length: Math.max(0, len) }, () => init);
-    }
-    Arr.create = create;
-    Arr.newArray = create;
+    // array creation
+    /**
+     * Creates an array of zeros with the specified length.
+     *
+     * This function provides compile-time type safety with precise return types:
+     * - When `len` is a compile-time known `SmallUint` (0-100), returns a tuple with exact length
+     * - When `len` is a positive runtime value, returns a `NonEmptyArray<0>`
+     * - Otherwise, returns a `readonly 0[]` that may be empty
+     *
+     * @template N The type of the length parameter. When a `SmallUint` literal is provided,
+     *   the return type will be a tuple of exactly that length filled with zeros.
+     * @param len The length of the array to create. Must be a non-negative integer.
+     * @returns An immutable array of zeros. The exact return type depends on the input:
+     *   - `ArrayOfLength<N, 0>` when `N` is a `SmallUint` literal
+     *   - `NonEmptyArray<0>` when `len` is a positive runtime value
+     *   - `readonly 0[]` for general non-negative values
+     *
+     * @example
+     * ```typescript
+     * // Compile-time known lengths produce precise tuple types
+     * const exactLength = Arr.zeros(3); // readonly [0, 0, 0]
+     * const empty = Arr.zeros(0); // readonly []
+     *
+     * // Runtime positive values produce non-empty arrays
+     * const count = Math.floor(Math.random() * 5) + 1;
+     * const nonEmpty = Arr.zeros(count); // NonEmptyArray<0>
+     *
+     * // General runtime values may be empty
+     * const maybeEmpty = Arr.zeros(Math.floor(Math.random() * 5)); // readonly 0[]
+     *
+     * // Type inference examples
+     * expectType<typeof exactLength, readonly [0, 0, 0]>('=');
+     * expectType<typeof empty, readonly []>('=');
+     * expectType<typeof nonEmpty, NonEmptyArray<0>>('=');
+     * expectType<typeof maybeEmpty, readonly 0[]>('=');
+     * ```
+     */
+    Arr.zeros = (len) => 
+    // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion
+    Array.from({ length: len }).fill(0);
+    /**
+     * Creates a sequence of consecutive integers from 0 to `len-1`.
+     *
+     * This function generates index sequences with precise compile-time typing:
+     * - When `len` is a compile-time known `SmallUint` (0-100), returns a tuple of consecutive integers
+     * - When `len` is a positive runtime value, returns a `NonEmptyArray<SizeType.Arr>`
+     * - Otherwise, returns a `readonly SizeType.Arr[]` that may be empty
+     *
+     * @template N The type of the length parameter. When a `SmallUint` literal is provided,
+     *   the return type will be a tuple containing the sequence [0, 1, 2, ..., N-1].
+     * @param len The length of the sequence to create. Must be a non-negative integer.
+     * @returns An immutable array containing the sequence [0, 1, 2, ..., len-1].
+     *   The exact return type depends on the input:
+     *   - `Seq<N>` (precise tuple) when `N` is a `SmallUint` literal
+     *   - `NonEmptyArray<SizeType.Arr>` when `len` is a positive runtime value
+     *   - `readonly SizeType.Arr[]` for general non-negative values
+     *
+     * @example
+     * ```typescript
+     * // Compile-time known lengths produce precise tuple types
+     * const indices = Arr.seq(4); // readonly [0, 1, 2, 3]
+     * const empty = Arr.seq(0); // readonly []
+     * const single = Arr.seq(1); // readonly [0]
+     *
+     * // Runtime positive values produce non-empty arrays
+     * const count = Math.floor(Math.random() * 5) + 1;
+     * const nonEmpty = Arr.seq(count); // NonEmptyArray<SizeType.Arr>
+     *
+     * // General runtime values may be empty
+     * const maybeEmpty = Arr.seq(Math.floor(Math.random() * 5)); // readonly SizeType.Arr[]
+     *
+     * // Useful for generating array indices
+     * const data = ['a', 'b', 'c', 'd'];
+     * const indexSequence = Arr.seq(data.length); // [0, 1, 2, 3]
+     *
+     * // Type inference examples
+     * expectType<typeof indices, readonly [0, 1, 2, 3]>('=');
+     * expectType<typeof empty, readonly []>('=');
+     * expectType<typeof single, readonly [0]>('=');
+     * ```
+     */
+    Arr.seq = (len) => 
+    // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion
+    Array.from({ length: len }, (_, i) => i);
+    /**
+     * Creates a new array of the specified length, with each position filled with the provided initial value.
+     *
+     * This function provides compile-time type safety with precise return types and performs shallow copying
+     * of the initial value (the same reference is used for all positions):
+     * - When `len` is a compile-time known `SmallUint` (0-100), returns a tuple of exactly that length
+     * - When `len` is a positive runtime value, returns a `NonEmptyArray<V>`
+     * - Otherwise, returns a `readonly V[]` that may be empty
+     *
+     * @template V The type of the initial value. The `const` constraint preserves literal types.
+     * @template N The type of the length parameter when it's a `SmallUint` literal.
+     * @param len The length of the array to create. Must be a non-negative integer.
+     * @param init The value to fill each position with. The same reference is used for all positions.
+     * @returns An immutable array filled with the initial value. The exact return type depends on the length:
+     *   - `ArrayOfLength<N, V>` when `len` is a `SmallUint` literal
+     *   - `NonEmptyArray<V>` when `len` is a positive runtime value
+     *   - `readonly V[]` for general non-negative values
+     *
+     * @example
+     * ```typescript
+     * // Compile-time known lengths produce precise tuple types
+     * const strings = Arr.create(3, 'hello'); // readonly ['hello', 'hello', 'hello']
+     * const numbers = Arr.create(2, 42); // readonly [42, 42]
+     * const empty = Arr.create(0, 'unused'); // readonly []
+     *
+     * // Object references are shared (shallow copy behavior)
+     * const obj = { id: 1, name: 'test' };
+     * const objects = Arr.create(3, obj); // readonly [obj, obj, obj]
+     * objects[0] === objects[1]; // true - same reference
+     * objects[0].id = 999; // Mutates the shared object
+     * console.log(objects[1].id); // 999 - all positions affected
+     *
+     * // Runtime positive values produce non-empty arrays
+     * const count = Math.floor(Math.random() * 5) + 1;
+     * const nonEmpty = Arr.create(count, 'item'); // NonEmptyArray<string>
+     *
+     * // Literal type preservation with const assertion
+     * const literals = Arr.create(2, 'success' as const); // readonly ['success', 'success']
+     *
+     * // Type inference examples
+     * expectType<typeof strings, readonly ['hello', 'hello', 'hello']>('=');
+     * expectType<typeof numbers, readonly [42, 42]>('=');
+     * expectType<typeof empty, readonly []>('=');
+     * ```
+     *
+     * @see {@link zeros} for creating arrays filled with zeros
+     * @see {@link seq} for creating sequences of consecutive integers
+     */
+    Arr.create = (len, init) => 
+    // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion
+    Array.from({ length: Math.max(0, len) }, () => init);
     /**
      * Creates an array from a generator function.
      *
@@ -429,16 +606,163 @@ var Arr;
         }
     }
     Arr.at = at;
-    function head(array) {
-        const element = array.at(0);
-        return element === undefined ? Optional.none : Optional.some(element);
-    }
-    Arr.head = head;
-    function last(array) {
-        const element = array.at(-1);
-        return element === undefined ? Optional.none : Optional.some(element);
-    }
-    Arr.last = last;
+    /**
+     * Returns the first element of an array wrapped in an Optional.
+     *
+     * This function provides type-safe access to the first element with precise return types:
+     * - For empty arrays: returns `Optional.None`
+     * - For tuples with known first element: returns `Optional.Some<FirstElementType>`
+     * - For non-empty arrays: returns `Optional.Some<ElementType>`
+     * - For general arrays: returns `Optional<ElementType>`
+     *
+     * The function leverages TypeScript's type system to provide the most precise return type
+     * based on the input array type, making it safer than direct indexing.
+     *
+     * @template E The type of elements in the array.
+     * @param array The array to get the first element from.
+     * @returns An Optional containing the first element:
+     *   - `Optional.None` if the array is empty
+     *   - `Optional.Some<E>` containing the first element if the array is non-empty
+     *
+     * @example
+     * ```typescript
+     * // Empty array - precise None type
+     * const emptyResult = Arr.head([]); // Optional.None
+     * console.log(Optional.isNone(emptyResult)); // true
+     *
+     * // Tuple with known structure - precise Some type
+     * const tupleResult = Arr.head(['first', 'second', 'third'] as const);
+     * // Type: Optional.Some<'first'>
+     * if (Optional.isSome(tupleResult)) {
+     *   console.log(tupleResult.value); // 'first' - TypeScript knows exact type
+     * }
+     *
+     * // Non-empty array - guaranteed Some type
+     * const nonEmpty: NonEmptyArray<number> = [10, 20, 30] as NonEmptyArray<number>;
+     * const guaranteedResult = Arr.head(nonEmpty); // Optional.Some<number>
+     * // No need to check - always Some for NonEmptyArray
+     *
+     * // General array - may be Some or None
+     * const generalArray: number[] = [1, 2, 3];
+     * const maybeResult = Arr.head(generalArray); // Optional<number>
+     * if (Optional.isSome(maybeResult)) {
+     *   console.log(`First element: ${maybeResult.value}`);
+     * } else {
+     *   console.log('Array is empty');
+     * }
+     *
+     * // Working with different types
+     * const strings = ['hello', 'world'];
+     * const firstString = Arr.head(strings); // Optional<string>
+     *
+     * const objects = [{ id: 1, name: 'Alice' }, { id: 2, name: 'Bob' }];
+     * const firstObject = Arr.head(objects); // Optional<{id: number, name: string}>
+     *
+     * // Functional composition
+     * const getFirstElements = (arrays: readonly number[][]) =>
+     *   arrays.map(Arr.head).filter(Optional.isSome);
+     *
+     * const nestedArrays = [[1, 2], [3, 4], [], [5]];
+     * const firstElements = getFirstElements(nestedArrays);
+     * // [Optional.Some(1), Optional.Some(3), Optional.Some(5)]
+     *
+     * // Type inference examples
+     * expectType<typeof emptyResult, Optional.None>('=');
+     * expectType<typeof tupleResult, Optional.Some<'first'>>('=');
+     * expectType<typeof guaranteedResult, Optional.Some<number>>('=');
+     * expectType<typeof maybeResult, Optional<number>>('=');
+     * ```
+     *
+     * @see {@link last} for getting the last element
+     * @see {@link at} for accessing elements at specific indices
+     * @see {@link tail} for getting all elements except the first
+     */
+    Arr.head = (array) => 
+    // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion
+    (array.length === 0 ? Optional.none : Optional.some(array.at(0)));
+    /**
+     * Returns the last element of an array wrapped in an Optional.
+     *
+     * This function provides type-safe access to the last element with precise return types:
+     * - For empty arrays: returns `Optional.None`
+     * - For tuples with known last element: returns `Optional.Some<LastElementType>`
+     * - For non-empty arrays: returns `Optional.Some<ElementType>`
+     * - For general arrays: returns `Optional<ElementType>`
+     *
+     * The function leverages TypeScript's type system to provide the most precise return type
+     * based on the input array type, making it safer than direct indexing.
+     *
+     * @template E The type of elements in the array.
+     * @param array The array to get the last element from.
+     * @returns An Optional containing the last element:
+     *   - `Optional.None` if the array is empty
+     *   - `Optional.Some<E>` containing the last element if the array is non-empty
+     *
+     * @example
+     * ```typescript
+     * // Empty array - precise None type
+     * const emptyResult = Arr.last([]); // Optional.None
+     * console.log(Optional.isNone(emptyResult)); // true
+     *
+     * // Tuple with known structure - precise Some type
+     * const tupleResult = Arr.last(['first', 'middle', 'last'] as const);
+     * // Type: Optional.Some<'last'>
+     * if (Optional.isSome(tupleResult)) {
+     *   console.log(tupleResult.value); // 'last' - TypeScript knows exact type
+     * }
+     *
+     * // Non-empty array - guaranteed Some type
+     * const nonEmpty: NonEmptyArray<number> = [10, 20, 30] as NonEmptyArray<number>;
+     * const guaranteedResult = Arr.last(nonEmpty); // Optional.Some<number>
+     * // No need to check - always Some for NonEmptyArray
+     *
+     * // General array - may be Some or None
+     * const generalArray: number[] = [1, 2, 3];
+     * const maybeResult = Arr.last(generalArray); // Optional<number>
+     * if (Optional.isSome(maybeResult)) {
+     *   console.log(`Last element: ${maybeResult.value}`);
+     * } else {
+     *   console.log('Array is empty');
+     * }
+     *
+     * // Working with different types
+     * const strings = ['hello', 'world', 'example'];
+     * const lastString = Arr.last(strings); // Optional<string>
+     *
+     * const coordinates = [{x: 0, y: 0}, {x: 1, y: 1}, {x: 2, y: 2}];
+     * const lastCoordinate = Arr.last(coordinates); // Optional<{x: number, y: number}>
+     *
+     * // Single element arrays
+     * const single = [42];
+     * const singleResult = Arr.last(single); // Optional<number> containing 42
+     *
+     * // Functional composition with arrays of arrays
+     * const getLastElements = (arrays: readonly string[][]) =>
+     *   arrays.map(Arr.last).filter(Optional.isSome);
+     *
+     * const nestedArrays = [['a', 'b'], ['c'], [], ['d', 'e', 'f']];
+     * const lastElements = getLastElements(nestedArrays);
+     * // [Optional.Some('b'), Optional.Some('c'), Optional.Some('f')]
+     *
+     * // Common pattern: get last element or default
+     * const data = [10, 20, 30];
+     * const lastOrDefault = Optional.unwrapOr(Arr.last(data), 0); // 30
+     * const emptyLastOrDefault = Optional.unwrapOr(Arr.last([]), 0); // 0
+     *
+     * // Type inference examples
+     * expectType<typeof emptyResult, Optional.None>('=');
+     * expectType<typeof tupleResult, Optional.Some<'last'>>('=');
+     * expectType<typeof guaranteedResult, Optional.Some<number>>('=');
+     * expectType<typeof maybeResult, Optional<number>>('=');
+     * ```
+     *
+     * @see {@link head} for getting the first element
+     * @see {@link at} for accessing elements at specific indices with negative indexing support
+     * @see {@link butLast} for getting all elements except the last
+     */
+    Arr.last = (array) => 
+    // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion
+    (array.length === 0 ? Optional.none : Optional.some(array.at(-1)));
     function sliceClamped(...args) {
         switch (args.length) {
             case 3: {
@@ -502,7 +826,7 @@ var Arr;
         switch (args.length) {
             case 2: {
                 const [array, num] = args;
-                return sliceClamped(array, Uint32.sub(size(array), num), size(array));
+                return sliceClamped(array, Uint32.sub(Arr.size(array), num), Arr.size(array));
             }
             case 1: {
                 const [num] = args;
@@ -515,7 +839,7 @@ var Arr;
         switch (args.length) {
             case 2: {
                 const [array, num] = args;
-                return sliceClamped(array, num, size(array));
+                return sliceClamped(array, num, Arr.size(array));
             }
             case 1: {
                 const [num] = args;
@@ -528,7 +852,7 @@ var Arr;
         switch (args.length) {
             case 2: {
                 const [array, num] = args;
-                return sliceClamped(array, 0, Uint32.sub(size(array), num));
+                return sliceClamped(array, 0, Uint32.sub(Arr.size(array), num));
             }
             case 1: {
                 const [num] = args;
@@ -537,14 +861,26 @@ var Arr;
         }
     }
     Arr.skipLast = skipLast;
+    function set(...args) {
+        switch (args.length) {
+            case 3: {
+                const [array, index, newValue] = args;
+                // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion
+                return array.with(index, newValue);
+            }
+            case 2: {
+                const [index, newValue] = args;
+                return (array) => set(array, index, newValue);
+            }
+        }
+    }
+    Arr.set = set;
     function toUpdated(...args) {
         switch (args.length) {
             case 3: {
                 const [array, index, updater] = args;
-                return index < 0 || index >= array.length
-                    ? array // Return a copy if index is out of bounds
-                    : // eslint-disable-next-line @typescript-eslint/no-non-null-assertion, @typescript-eslint/no-unsafe-type-assertion
-                        array.with(index, updater(array[index]));
+                // eslint-disable-next-line @typescript-eslint/no-non-null-assertion, @typescript-eslint/no-unsafe-type-assertion
+                return array.with(index, updater(array[index]));
             }
             case 2: {
                 const [index, updater] = args;
@@ -612,9 +948,7 @@ var Arr;
         switch (args.length) {
             case 2: {
                 const [array, value] = args;
-                const cp = castMutable(Arr.copy(array));
-                cp.fill(value);
-                return cp;
+                return Arr.create(asPositiveUint32(array.length), value);
             }
             case 1: {
                 const [value] = args;
@@ -657,6 +991,25 @@ var Arr;
         }
     }
     Arr.find = find;
+    function findLast(...args) {
+        switch (args.length) {
+            case 2: {
+                const [array, predicate] = args;
+                const foundIndex = array.findLastIndex(
+                // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion
+                predicate);
+                return foundIndex === -1
+                    ? Optional.none
+                    : // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+                        Optional.some(array[foundIndex]);
+            }
+            case 1: {
+                const [predicate] = args;
+                return (array) => findLast(array, predicate);
+            }
+        }
+    }
+    Arr.findLast = findLast;
     function findIndex(...args) {
         switch (args.length) {
             case 2: {
@@ -672,6 +1025,21 @@ var Arr;
         }
     }
     Arr.findIndex = findIndex;
+    function findLastIndex(...args) {
+        switch (args.length) {
+            case 2: {
+                const [array, predicate] = args;
+                return pipe(array.findLastIndex(
+                // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion
+                predicate)).map((idx) => (idx >= 0 ? asUint32(idx) : -1)).value;
+            }
+            case 1: {
+                const [predicate] = args;
+                return (array) => findLastIndex(array, predicate);
+            }
+        }
+    }
+    Arr.findLastIndex = findLastIndex;
     function indexOf(...args) {
         switch (args.length) {
             case 2: {
@@ -728,6 +1096,32 @@ var Arr;
         }
     }
     Arr.lastIndexOfFrom = lastIndexOfFrom;
+    function every(...args) {
+        switch (args.length) {
+            case 2: {
+                const [array, predicate] = args;
+                return array.every((a, i) => predicate(a, asUint32(i)));
+            }
+            case 1: {
+                const [predicate] = args;
+                return (array) => every(array, predicate);
+            }
+        }
+    }
+    Arr.every = every;
+    function some(...args) {
+        switch (args.length) {
+            case 2: {
+                const [array, predicate] = args;
+                return array.some((a, i) => predicate(a, asUint32(i)));
+            }
+            case 1: {
+                const [predicate] = args;
+                return (array) => some(array, predicate);
+            }
+        }
+    }
+    Arr.some = some;
     function foldl(...args) {
         switch (args.length) {
             case 3: {
@@ -868,10 +1262,37 @@ var Arr;
      */
     Arr.zip = (array1, array2) => 
     // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion
-    seq(Uint32.min(size(array1), size(array2))).map((i) => 
+    Arr.seq(Uint32.min(Arr.size(array1), Arr.size(array2))).map((i) => 
     // Non-null assertion is safe here because `i` is always within bounds of both arrays up to the length of the shorter one.
     // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
     tp(array1[i], array2[i]));
+    function map(...args) {
+        switch (args.length) {
+            case 2: {
+                const [array, mapFn] = args;
+                // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion
+                return array.map(mapFn);
+            }
+            case 1: {
+                const [mapFn] = args;
+                return (array) => map(array, mapFn);
+            }
+        }
+    }
+    Arr.map = map;
+    function filter(...args) {
+        switch (args.length) {
+            case 2: {
+                const [array, predicate] = args;
+                return array.filter((a, i) => predicate(a, asUint32(i)));
+            }
+            case 1: {
+                const [predicate] = args;
+                return (array) => filter(array, predicate);
+            }
+        }
+    }
+    Arr.filter = filter;
     function filterNot(...args) {
         switch (args.length) {
             case 2: {
@@ -885,6 +1306,43 @@ var Arr;
         }
     }
     Arr.filterNot = filterNot;
+    function flat(...args) {
+        switch (args.length) {
+            case 2: {
+                const [array, depth] = args;
+                return array.flat(depth);
+            }
+            case 1: {
+                const [arrayOrDepth] = args;
+                if (typeof arrayOrDepth === 'number') {
+                    const depth = arrayOrDepth;
+                    return (array) => flat(array, depth);
+                }
+                else if (arrayOrDepth === undefined) {
+                    return (array) => flat(array, 1);
+                }
+                else {
+                    return arrayOrDepth.flat(1);
+                }
+            }
+            case 0:
+                return (array) => flat(array, 1);
+        }
+    }
+    Arr.flat = flat;
+    function flatMap(...args) {
+        switch (args.length) {
+            case 2: {
+                const [array, mapFn] = args;
+                return array.flatMap((a, i) => mapFn(a, asUint32(i)));
+            }
+            case 1: {
+                const [mapFn] = args;
+                return (array) => flatMap(array, mapFn);
+            }
+        }
+    }
+    Arr.flatMap = flatMap;
     /**
      * Concatenates two arrays.
      * @template E1 The type of the first array (can be a tuple).
@@ -906,7 +1364,7 @@ var Arr;
                 const [array, chunkSize] = args;
                 return chunkSize < 2
                     ? []
-                    : seq(asUint32(Math.ceil(array.length / chunkSize))).map((i) => array.slice(chunkSize * i, chunkSize * (i + 1)));
+                    : Arr.seq(asUint32(Math.ceil(array.length / chunkSize))).map((i) => array.slice(chunkSize * i, chunkSize * (i + 1)));
             }
             case 1: {
                 const [chunkSize] = args;
@@ -915,6 +1373,61 @@ var Arr;
         }
     }
     Arr.partition = partition;
+    /**
+     * Reverses a tuple, preserving element types in their new positions.
+     *
+     * The type system precisely tracks the reversal, so the returned tuple
+     * has its element types in the exact reverse order. This is more precise
+     * than array reversal which loses positional type information.
+     *
+     * @template T - The tuple type to reverse
+     * @param array - The input tuple
+     * @returns A new tuple with elements in reverse order and precise typing
+     *
+     * @example
+     * ```typescript
+     * // Basic reversal
+     * const nums = [1, 2, 3] as const;
+     * const reversed = Arr.toReversed(nums); // readonly [3, 2, 1]
+     *
+     * // Mixed types preserved in reverse positions
+     * const mixed = [1, 'hello', true, null] as const;
+     * const revMixed = Arr.toReversed(mixed);
+     * // readonly [null, true, 'hello', 1]
+     *
+     * // Empty and single-element tuples
+     * const empty = [] as const;
+     * const revEmpty = Arr.toReversed(empty); // readonly []
+     * const single = [42] as const;
+     * const revSingle = Arr.toReversed(single); // readonly [42]
+     * ```
+     */
+    Arr.toReversed = (array) => 
+    // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion
+    array.toReversed();
+    /**
+     * Sorts an array by a value derived from its elements, using a numeric mapping.
+     * @template E The type of elements in the array.
+     * @param array The input array.
+     * @param comparatorValueMapper A function `(value: A) => number` that maps an element to a number for comparison.
+     * @param comparator An optional custom comparator function `(x: number, y: number) => number` for the mapped numbers. Defaults to ascending sort (x - y).
+     * @returns A new array sorted by the mapped values.
+     * @example
+     * ```ts
+     * const items = [{ name: 'Eve', score: 70 }, { name: 'Adam', score: 90 }, { name: 'Bob', score: 80 }];
+     * Arr.toSortedBy(items, item => item.score);
+     * // [{ name: 'Eve', score: 70 }, { name: 'Bob', score: 80 }, { name: 'Adam', score: 90 }]
+     * Arr.toSortedBy(items, item => item.score, (a, b) => b - a); // Sort descending
+     * // [{ name: 'Adam', score: 90 }, { name: 'Bob', score: 80 }, { name: 'Eve', score: 70 }]
+     * ```
+     */
+    Arr.toSorted = (...[array, comparator]) => 
+    // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion
+    array.toSorted(
+    // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion
+    comparator ??
+        // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion
+        ((x, y) => x - y));
     function toSortedBy(array, comparatorValueMapper, comparator) {
         return array.toSorted((x, y) => comparator === undefined
             ? // This branch assumes V is number if comparator is undefined.
@@ -981,9 +1494,33 @@ var Arr;
      * Arr.uniq([1, 2, 2, 3, 1, 4]); // [1, 2, 3, 4]
      * ```
      */
-    Arr.uniq = (array) => Array.from(new Set(array));
-    function uniqBy(array, mapFn) {
+    Arr.uniq = (array) => 
+    // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion
+    Array.from(new Set(array));
+    /**
+     * Creates a new array with unique elements from the input array, based on the values returned by `mapFn`.
+     *
+     * - If the input is a non-empty array, returns a non-empty array.
+     * - Otherwise, returns a readonly array.
+     *
+     * @template E The type of elements in the array.
+     * @template P The type of the mapped value (used for uniqueness comparison).
+     * @param array The input array.
+     * @param mapFn A function `(value: A) => P` to map elements to values for uniqueness comparison.
+     * @returns A new array with unique elements based on the mapped values.
+     * @example
+     * ```ts
+     * const users = [
+     *   { id: 1, name: 'Alice' },
+     *   { id: 2, name: 'Bob' },
+     *   { id: 1, name: 'Alicia' }, // Duplicate id
+     * ];
+     * Arr.uniqBy(users, user => user.id); // [{ id: 1, name: 'Alice' }, { id: 2, name: 'Bob' }]
+     * ```
+     */
+    Arr.uniqBy = (array, mapFn) => {
         const mut_mappedValues = new Set();
+        // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion
         return array.filter((val) => {
             const mappedValue = mapFn(val);
             if (mut_mappedValues.has(mappedValue))
@@ -991,8 +1528,7 @@ var Arr;
             mut_mappedValues.add(mappedValue);
             return true;
         });
-    }
-    Arr.uniqBy = uniqBy;
+    };
     // set operations & equality
     /**
      * Checks if two arrays are equal by performing a shallow comparison of their elements.
@@ -1135,12 +1671,101 @@ var Arr;
         }
         return mut_result;
     };
+    // iterators
+    /**
+     * Returns an iterable of key-value pairs for every entry in the array.
+     *
+     * This function returns an array where each element is a tuple containing the index and value.
+     * The indices are branded as `SizeType.Arr` for type safety.
+     *
+     * @template Ar The exact type of the input array.
+     * @param array The array to get entries from.
+     * @returns An array of `[index, value]` pairs.
+     *
+     * @example
+     * ```typescript
+     * // Direct usage
+     * const fruits = ['apple', 'banana', 'cherry'];
+     * const entries = Arr.entries(fruits); // [[0, 'apple'], [1, 'banana'], [2, 'cherry']]
+     *
+     * // Curried usage
+     * const getEntries = Arr.entries;
+     * const result = getEntries(['a', 'b']); // [[0, 'a'], [1, 'b']]
+     *
+     * // With tuples
+     * const tuple = [10, 20, 30] as const;
+     * const tupleEntries = Arr.entries(tuple); // [[0, 10], [1, 20], [2, 30]]
+     * ```
+     */
+    function* entries(array) {
+        for (const [index, value] of array.entries()) {
+            yield [asUint32(index), value];
+        }
+    }
+    Arr.entries = entries;
+    /**
+     * Returns an iterable of values in the array.
+     *
+     * This function is essentially an identity function that returns a copy of the array.
+     * It's included for API completeness and consistency with native Array methods.
+     *
+     * @template Ar The exact type of the input array.
+     * @param array The array to get values from.
+     * @returns A copy of the input array.
+     *
+     * @example
+     * ```typescript
+     * // Direct usage
+     * const numbers = [1, 2, 3];
+     * const values = Arr.values(numbers); // [1, 2, 3]
+     *
+     * // Curried usage
+     * const getValues = Arr.values;
+     * const result = getValues(['a', 'b']); // ['a', 'b']
+     * ```
+     */
+    function* values(array) {
+        for (const value of array.values()) {
+            yield value;
+        }
+    }
+    Arr.values = values;
+    /**
+     * Returns an iterable of keys in the array.
+     *
+     * This function returns an array of branded indices (`SizeType.Arr`) for type safety.
+     *
+     * @template Ar The exact type of the input array.
+     * @param array The array to get indices from.
+     * @returns An array of indices.
+     *
+     * @example
+     * ```typescript
+     * // Direct usage
+     * const fruits = ['apple', 'banana', 'cherry'];
+     * const indices = Arr.indices(fruits); // [0, 1, 2]
+     *
+     * // Curried usage
+     * const getIndices = Arr.indices;
+     * const result = getIndices(['a', 'b']); // [0, 1]
+     *
+     * // Empty array
+     * const empty: string[] = [];
+     * const emptyIndices = Arr.indices(empty); // []
+     * ```
+     */
+    function* indices(array) {
+        for (const key of array.keys()) {
+            yield asUint32(key);
+        }
+    }
+    Arr.indices = indices;
     // aliases
     /**
      * Alias for `head`. Returns the first element of an array.
      * @see {@link head}
      */
-    Arr.first = head;
+    Arr.first = Arr.head;
     /**
      * Alias for `tail`. Returns all elements of an array except the first one.
      * @see {@link tail}
@@ -1166,6 +1791,21 @@ var Arr;
      * @see {@link partition}
      */
     Arr.chunk = partition;
+    /**
+     * Alias for `create`. Creates a new array of the specified length, with each position filled with the provided initial value.
+     * @see {@link create}
+     */
+    Arr.newArray = Arr.create;
+    /**
+     * Alias for `size`. Returns the length of an array.
+     * @see {@link size}
+     */
+    Arr.length = Arr.size;
+    /**
+     * Alias for `indices`. Returns an iterable of keys in the array.
+     * @see {@link indices}
+     */
+    Arr.keys = indices;
 })(Arr || (Arr = {}));
 
 export { Arr };