ts-data-forge 3.2.0 → 3.3.1

package/README.md

@@ -32,6 +32,10 @@ This library offers a range of utilities, including:
 - **JSON Handling**: Type-safe JSON parsing and stringification.
 - **And more**: Including memoization, casting utilities, and other helpful tools.
 
+## Documentation
+
+- API reference: <https://noshiro-pf.github.io/ts-data-forge/>
+
 ## Installation
 
 ```bash
@@ -132,7 +136,7 @@ Here are some examples of how to use utilities from `ts-data-forge`:
 
 The `expectType` utility allows you to make assertions about types at compile time. This is useful for ensuring type correctness in complex type manipulations or when refactoring.
 
-```typescript
+```tsx
 import { expectType } from 'ts-data-forge';
 
 type User = { id: number; name: string };
@@ -158,7 +162,7 @@ expectType<User, any>('!='); // Error: Comparisons with `any` are also strictly
 
 Handle nullable values and error-prone operations safely.
 
-```typescript
+```tsx
 import { match, Optional, pipe, Result } from 'ts-data-forge';
 
 // Optional for nullable values
@@ -212,7 +216,7 @@ assert(processResult(Result.err('Failed')) === 'Error: Failed');
 
 The `Num` object provides safe and convenient functions for numerical operations.
 
-```typescript
+```tsx
 import { Num } from 'ts-data-forge';
 
 // Basic conversions
@@ -235,8 +239,8 @@ assert(clamp(-10) === 0);
 // Rounding utilities
 const round2 = Num.round(2);
 
-assert(round2(3.14159) === 3.14);
-assert(Num.roundAt(3.14159, 3) === 3.142);
+assert(round2(3.141_59) === 3.14);
+assert(Num.roundAt(3.141_59, 3) === 3.142);
 assert(Num.roundToInt(3.7) === 4);
 
 // Type guards
@@ -252,7 +256,7 @@ if (Num.isNonZero(value)) {
 
 `ts-data-forge` provides branded number types that enforce specific constraints at the type level.
 
-```typescript
+```tsx
 import {
     asFiniteNumber,
     asInt,
@@ -284,9 +288,9 @@ assert.throw(() => {
 
 // Range-constrained types (16-bit, 32-bit)
 const int16 = asInt16(1000); // Int16: [-32768, 32767]
-const uint32 = asUint32(3000000000); // Uint32: [0, 4294967295]
+const uint32 = asUint32(3_000_000_000); // Uint32: [0, 4294967295]
 assert(int16 === 1000);
-assert(uint32 === 3000000000);
+assert(uint32 === 3_000_000_000);
 
 // Non-zero and positive variants
 const nonZeroInt = asNonZeroInt(5); // NonZeroInt - excludes zero
@@ -296,9 +300,9 @@ assert(positiveInt === 10);
 
 // Type-safe arithmetic with automatic clamping
 const sum = Int16.add(int16, asInt16(2000)); // Int16 (3000)
-const clamped = Int16.clamp(100000); // Int16 (32767 - clamped to MAX_VALUE)
+const clamped = Int16.clamp(100_000); // Int16 (32767 - clamped to MAX_VALUE)
 assert(sum === 3000);
-assert(clamped === 32767);
+assert(clamped === 32_767);
 
 // Safe division with non-zero types
 const ratio = NonZeroInt.div(asNonZeroInt(10), nonZeroInt); // No division by zero risk
@@ -306,15 +310,15 @@ assert(ratio === 2);
 
 // Random generation within type constraints
 const randomInt16 = Int16.random(); // Int16 (random value in valid range)
-assert(-32768 <= randomInt16);
-assert(randomInt16 <= 32767);
+assert(-32_768 <= randomInt16);
+assert(randomInt16 <= 32_767);
 ```
 
 ### 4. Array Utilities with `Arr`
 
 The `Arr` object provides a rich set of functions for array manipulation.
 
-```typescript
+```tsx
 import { Arr, expectType, Optional } from 'ts-data-forge';
 
 const numbers: readonly number[] = [1, 2, 3, 4, 5, 2, 3];
@@ -369,7 +373,7 @@ if (Optional.isSome(oldestPerson)) {
 
 Type-safe, immutable data structures.
 
-```typescript
+```tsx
 import { Arr, IMap, ISet, Optional } from 'ts-data-forge';
 
 // IMap usage - immutable operations
@@ -415,7 +419,7 @@ assert(setWithItems.size === 2);
 
 Safe type narrowing with comprehensive type guards.
 
-```typescript
+```tsx
 import { hasKey, isNonNullObject, isRecord } from 'ts-data-forge';
 
 const processData = (data: unknown): string | undefined => {
@@ -448,7 +452,7 @@ assert(processData('not an object') === undefined);
 
 Generate ranges for iteration and array creation.
 
-```typescript
+```tsx
 import { range } from 'ts-data-forge';
 
 // Traditional for loop using range
@@ -480,25 +484,45 @@ assert.deepStrictEqual(mut_stepValues, [0, 2, 4, 6, 8]);
 Safely work with readonly types when interfacing with mutable APIs.
 
 ```tsx
+import type * as React from 'react';
 import { castMutable } from 'ts-data-forge';
 
 // Example: Material-UI Autocomplete
 import { Autocomplete, TextField } from '@mui/material';
 
+// Immer.js example
+import { produce } from 'immer';
+
 export const SomeComponent: React.FC = () => (
     <Autocomplete
         options={castMutable(readonlyOptions)}
-        renderInput={(params) => (
-            <TextField {...params} placeholder="Select an option" />
+        renderInput={({
+            InputLabelProps,
+            InputProps,
+            disabled,
+            fullWidth,
+            id,
+            inputProps,
+            size,
+        }) => (
+            <TextField
+                slotProps={{
+                    inputLabel: InputLabelProps,
+                    input: InputProps,
+                    htmlInput: inputProps,
+                }}
+                disabled={disabled}
+                fullWidth={fullWidth}
+                id={id}
+                size={size}
+                placeholder="Select an option"
+            />
         )}
     />
 );
 
 const readonlyOptions: readonly string[] = ['Option 1', 'Option 2', 'Option 3'];
 
-// Immer.js example
-import { produce } from 'immer';
-
 type State = Readonly<{
     items: readonly string[];
 }>;

package/dist/array/impl/array-utils-creation.d.mts

@@ -0,0 +1,116 @@
+/**
+ * Creates an array of zeros with the specified length.
+ *
+ * @example
+ *
+ * ```ts
+ * const emptyZeros = Arr.zeros(0);
+ * const threeZeros = Arr.zeros(3);
+ *
+ * assert.deepStrictEqual(emptyZeros, []);
+ * assert.deepStrictEqual(threeZeros, [0, 0, 0]);
+ * ```
+ */
+export declare const zeros: <N extends SizeType.ArgArr>(len: N) => N extends SmallUint ? ArrayOfLength<N, 0> : N extends SizeType.ArgArrPositive ? NonEmptyArray<0> : readonly 0[];
+/**
+ * Creates a sequence of consecutive integers from 0 to `len-1`.
+ *
+ * @example
+ *
+ * ```ts
+ * const emptySeq = Arr.seq(0);
+ * const firstFive = Arr.seq(5);
+ *
+ * assert.deepStrictEqual(emptySeq, []);
+ * assert.deepStrictEqual(firstFive, [0, 1, 2, 3, 4]);
+ * ```
+ */
+export declare const seq: <N extends SizeType.ArgArr>(len: N) => N extends SmallUint ? Seq<N> : N extends SizeType.ArgArrPositive ? NonEmptyArray<SizeType.Arr> : readonly SizeType.Arr[];
+/**
+ * Creates a new array of the specified length, filled with the initial value.
+ *
+ * @example
+ *
+ * ```ts
+ * const threeOnes = Arr.create(3, 1);
+ * const emptyStrings = Arr.create(0, 'Ada');
+ *
+ * assert.deepStrictEqual(threeOnes, [1, 1, 1]);
+ * assert.deepStrictEqual(emptyStrings, []);
+ * ```
+ */
+export declare const create: <const V, N extends SizeType.ArgArr>(len: N, init: V) => N extends SmallUint ? ArrayOfLength<N, V> : N extends SizeType.ArgArrPositive ? NonEmptyArray<V> : readonly V[];
+/**
+ * Alias for `create`.
+ *
+ * @see {@link create}
+ */
+export declare const newArray: <const V, N extends SizeType.ArgArr>(len: N, init: V) => N extends SmallUint ? ArrayOfLength<N, V> : N extends SizeType.ArgArrPositive ? NonEmptyArray<V> : readonly V[];
+/**
+ * Generates an array from a generator function.
+ *
+ * @example
+ *
+ * ```ts
+ * const numbers = Arr.generate(function* () {
+ *   yield 1;
+ *   yield 2;
+ *   yield 3;
+ * });
+ *
+ * assert.deepStrictEqual(numbers, [1, 2, 3]);
+ * ```
+ */
+export declare const generate: <T>(generatorFn: () => Generator<T, void, unknown>) => readonly T[];
+/**
+ * Generates an array from an async generator function.
+ *
+ * @example
+ *
+ * ```ts
+ * const values = await Arr.generateAsync(async function* () {
+ *   yield 'Ada';
+ *   await Promise.resolve();
+ *   yield 'Lovelace';
+ * });
+ *
+ * assert.deepStrictEqual(values, ['Ada', 'Lovelace']);
+ * ```
+ */
+export declare const generateAsync: <T>(generatorFn: () => AsyncGenerator<T, void, unknown>) => Promise<readonly T[]>;
+/**
+ * Creates a shallow copy of an array.
+ *
+ * @example
+ *
+ * ```ts
+ * const original = [{ id: 1 }, { id: 2 }] as const;
+ * const cloned = Arr.copy(original);
+ *
+ * assert.deepStrictEqual(cloned, original);
+ * assert.notStrictEqual(cloned, original);
+ * ```
+ */
+export declare const copy: <const Ar extends readonly unknown[]>(array: Ar) => Ar;
+type LT = Readonly<{
+    [N in SmallUint]: Index<N>;
+}>;
+type RangeList<S extends SmallUint, E extends SmallUint> = BoolOr<IsUnion<S>, IsUnion<E>> extends true ? readonly RelaxedExclude<LT[E], LT[Min<S>]>[] : List.Skip<S, Seq<E>>;
+/**
+ * Creates an array of numbers within a specified range with optional step.
+ *
+ * @example
+ *
+ * ```ts
+ * const ascending = Arr.range(asUint32(1), asUint32(5));
+ * const empty = Arr.range(asUint32(2), asUint32(2));
+ *
+ * assert.deepStrictEqual(ascending, [1, 2, 3, 4]);
+ * assert.deepStrictEqual(empty, []);
+ * ```
+ */
+export declare function range<S extends SmallUint, E extends SmallUint>(start: S, end: E, step?: 1): RangeList<S, E>;
+export declare function range(start: SafeUintWithSmallInt, end: SafeUintWithSmallInt, step?: PositiveSafeIntWithSmallInt): readonly SafeUint[];
+export declare function range(start: SafeIntWithSmallInt, end: SafeIntWithSmallInt, step?: NonZeroSafeIntWithSmallInt): readonly SafeInt[];
+export {};
+//# sourceMappingURL=array-utils-creation.d.mts.map

package/dist/array/impl/array-utils-creation.d.mts.map

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

package/dist/array/impl/array-utils-creation.mjs

@@ -0,0 +1,110 @@
+import { range as range$1 } from '../../iterator/range.mjs';
+
+/**
+ * Creates an array of zeros with the specified length.
+ *
+ * @example
+ *
+ * ```ts
+ * const emptyZeros = Arr.zeros(0);
+ * const threeZeros = Arr.zeros(3);
+ *
+ * assert.deepStrictEqual(emptyZeros, []);
+ * assert.deepStrictEqual(threeZeros, [0, 0, 0]);
+ * ```
+ */
+const zeros = (len) => 
+// eslint-disable-next-line total-functions/no-unsafe-type-assertion
+Array.from({ length: len }).fill(0);
+/**
+ * Creates a sequence of consecutive integers from 0 to `len-1`.
+ *
+ * @example
+ *
+ * ```ts
+ * const emptySeq = Arr.seq(0);
+ * const firstFive = Arr.seq(5);
+ *
+ * assert.deepStrictEqual(emptySeq, []);
+ * assert.deepStrictEqual(firstFive, [0, 1, 2, 3, 4]);
+ * ```
+ */
+const seq = (len) => 
+// eslint-disable-next-line total-functions/no-unsafe-type-assertion
+Array.from({ length: len }, (_, i) => i);
+/**
+ * Creates a new array of the specified length, filled with the initial value.
+ *
+ * @example
+ *
+ * ```ts
+ * const threeOnes = Arr.create(3, 1);
+ * const emptyStrings = Arr.create(0, 'Ada');
+ *
+ * assert.deepStrictEqual(threeOnes, [1, 1, 1]);
+ * assert.deepStrictEqual(emptyStrings, []);
+ * ```
+ */
+const create = (len, init) => 
+// eslint-disable-next-line total-functions/no-unsafe-type-assertion
+Array.from({ length: Math.max(0, len) }, () => init);
+/**
+ * Alias for `create`.
+ *
+ * @see {@link create}
+ */
+const newArray = create;
+/**
+ * Generates an array from a generator function.
+ *
+ * @example
+ *
+ * ```ts
+ * const numbers = Arr.generate(function* () {
+ *   yield 1;
+ *   yield 2;
+ *   yield 3;
+ * });
+ *
+ * assert.deepStrictEqual(numbers, [1, 2, 3]);
+ * ```
+ */
+const generate = (generatorFn) => Array.from(generatorFn());
+/**
+ * Generates an array from an async generator function.
+ *
+ * @example
+ *
+ * ```ts
+ * const values = await Arr.generateAsync(async function* () {
+ *   yield 'Ada';
+ *   await Promise.resolve();
+ *   yield 'Lovelace';
+ * });
+ *
+ * assert.deepStrictEqual(values, ['Ada', 'Lovelace']);
+ * ```
+ */
+const generateAsync = (generatorFn) => Array.fromAsync(generatorFn());
+/**
+ * Creates a shallow copy of an array.
+ *
+ * @example
+ *
+ * ```ts
+ * const original = [{ id: 1 }, { id: 2 }] as const;
+ * const cloned = Arr.copy(original);
+ *
+ * assert.deepStrictEqual(cloned, original);
+ * assert.notStrictEqual(cloned, original);
+ * ```
+ */
+const copy = (array) => 
+// eslint-disable-next-line total-functions/no-unsafe-type-assertion
+array.slice();
+function range(start, end, step = 1) {
+    return Array.from(range$1(start, end, step));
+}
+
+export { copy, create, generate, generateAsync, newArray, range, seq, zeros };
+//# sourceMappingURL=array-utils-creation.mjs.map

package/dist/array/impl/array-utils-creation.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"array-utils-creation.mjs","sources":["../../../src/array/impl/array-utils-creation.mts"],"sourcesContent":[null],"names":["rangeIterator"],"mappings":";;AAGA;;;;;;;;;;;;AAYG;AACI,MAAM,KAAK,GAAG,CACnB,GAAM;AAMN;AACA,KAAK,CAAC,IAAI,CAAI,EAAE,MAAM,EAAE,GAAG,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC;AAEvC;;;;;;;;;;;;AAYG;AACI,MAAM,GAAG,GAAG,CACjB,GAAM;AAMN;AACA,KAAK,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,GAAG,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,KAAK,CAAC;AAEzC;;;;;;;;;;;;AAYG;MACU,MAAM,GAAG,CACpB,GAAM,EACN,IAAO;AAMP;AACA,KAAK,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,GAAG,CAAC,EAAE,EAAE,MAAM,IAAI;AAErD;;;;AAIG;AACI,MAAM,QAAQ,GAAG;AAExB;;;;;;;;;;;;;;AAcG;AACI,MAAM,QAAQ,GAAG,CACtB,WAA8C,KAC7B,KAAK,CAAC,IAAI,CAAC,WAAW,EAAE;AAE3C;;;;;;;;;;;;;;AAcG;AACI,MAAM,aAAa,GAAG,CAC3B,WAAmD,KACzB,KAAK,CAAC,SAAS,CAAC,WAAW,EAAE;AAEzD;;;;;;;;;;;;AAYG;AACI,MAAM,IAAI,GAAG,CAAsC,KAAS;AACjE;AACA,KAAK,CAAC,KAAK;AAoDP,SAAU,KAAK,CACnB,KAA0B,EAC1B,GAAwB,EACxB,OAAmC,CAAC,EAAA;AAEpC,IAAA,OAAO,KAAK,CAAC,IAAI,CAACA,OAAa,CAAC,KAAK,EAAE,GAAG,EAAE,IAAI,CAAC,CAAC;AACpD;;;;"}

package/dist/array/impl/array-utils-element-access.d.mts

@@ -0,0 +1,61 @@
+import { Optional } from '../../functional/index.mjs';
+/**
+ * Safely retrieves an element at a given index from an array, returning an Optional.
+ *
+ * @example
+ *
+ * ```ts
+ * const letters: readonly string[] = ['a', 'b', 'c'];
+ *
+ * const two = Arr.at(letters, 1);
+ * const last = Arr.at(-1)(letters);
+ * const missing = Arr.at(letters, 5);
+ *
+ * assert.deepStrictEqual(two, Optional.some('b'));
+ * assert.deepStrictEqual(last, Optional.some('c'));
+ * assert.deepStrictEqual(missing, Optional.none);
+ * ```
+ */
+export declare function at<const Ar extends readonly unknown[]>(array: Ar, index: ArgArrayIndexWithNegative<Ar>): Optional<Ar[number]>;
+export declare function at(index: SizeType.ArgArrWithNegative): <E>(array: readonly E[]) => Optional<E>;
+/**
+ * Returns the first element of an array as an Optional.
+ *
+ * @example
+ *
+ * ```ts
+ * const users = [{ id: 1 }, { id: 2 }];
+ * const empty: { id: number }[] = [];
+ *
+ * const first = Arr.head(users);
+ * const none = Arr.head(empty);
+ *
+ * assert.deepStrictEqual(first, Optional.some({ id: 1 }));
+ * assert.deepStrictEqual(none, Optional.none);
+ * ```
+ */
+export declare const head: <const Ar extends readonly unknown[]>(array: Ar) => Ar extends readonly [] ? Optional.None : Ar extends readonly [infer E, ...unknown[]] ? Optional.Some<E> : Ar extends NonEmptyArray<infer E> ? Optional.Some<E> : Optional<Ar[number]>;
+/**
+ * Returns the last element of an array as an Optional.
+ *
+ * @example
+ *
+ * ```ts
+ * const queue = ['first', 'second'];
+ * const emptyQueue: string[] = [];
+ *
+ * const lastValue = Arr.last(queue);
+ * const none = Arr.last(emptyQueue);
+ *
+ * assert.deepStrictEqual(lastValue, Optional.some('second'));
+ * assert.deepStrictEqual(none, Optional.none);
+ * ```
+ */
+export declare const last: <const Ar extends readonly unknown[]>(array: Ar) => Ar extends readonly [] ? Optional.None : Ar extends readonly [...unknown[], infer E] ? Optional.Some<E> : Ar extends NonEmptyArray<infer E> ? Optional.Some<E> : Optional<Ar[number]>;
+/**
+ * Alias for `head`.
+ *
+ * @see {@link head}
+ */
+export declare const first: <const Ar extends readonly unknown[]>(array: Ar) => Ar extends readonly [] ? Optional.None : Ar extends readonly [infer E, ...unknown[]] ? Optional.Some<E> : Ar extends NonEmptyArray<infer E> ? Optional.Some<E> : Optional<Ar[number]>;
+//# sourceMappingURL=array-utils-element-access.d.mts.map

package/dist/array/impl/array-utils-element-access.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"array-utils-element-access.d.mts","sourceRoot":"","sources":["../../../src/array/impl/array-utils-element-access.mts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAQ,MAAM,4BAA4B,CAAC;AAE5D;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,EAAE,CAAC,KAAK,CAAC,EAAE,SAAS,SAAS,OAAO,EAAE,EACpD,KAAK,EAAE,EAAE,EACT,KAAK,EAAE,yBAAyB,CAAC,EAAE,CAAC,GACnC,QAAQ,CAAC,EAAE,CAAC,MAAM,CAAC,CAAC,CAAC;AAIxB,wBAAgB,EAAE,CAChB,KAAK,EAAE,QAAQ,CAAC,kBAAkB,GACjC,CAAC,CAAC,EAAE,KAAK,EAAE,SAAS,CAAC,EAAE,KAAK,QAAQ,CAAC,CAAC,CAAC,CAAC;AAyB3C;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,IAAI,GAAI,KAAK,CAAC,EAAE,SAAS,SAAS,OAAO,EAAE,EACtD,OAAO,EAAE,KACR,EAAE,SAAS,SAAS,EAAE,GACrB,QAAQ,CAAC,IAAI,GACb,EAAE,SAAS,SAAS,CAAC,MAAM,CAAC,EAAE,GAAG,OAAO,EAAE,CAAC,GACzC,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,GAChB,EAAE,SAAS,aAAa,CAAC,MAAM,CAAC,CAAC,GAC/B,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,GAChB,QAAQ,CAAC,EAAE,CAAC,MAAM,CAAC,CAEiD,CAAC;AAE7E;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,IAAI,GAAI,KAAK,CAAC,EAAE,SAAS,SAAS,OAAO,EAAE,EACtD,OAAO,EAAE,KACR,EAAE,SAAS,SAAS,EAAE,GACrB,QAAQ,CAAC,IAAI,GACb,EAAE,SAAS,SAAS,CAAC,GAAG,OAAO,EAAE,EAAE,MAAM,CAAC,CAAC,GACzC,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,GAChB,EAAE,SAAS,aAAa,CAAC,MAAM,CAAC,CAAC,GAC/B,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,GAChB,QAAQ,CAAC,EAAE,CAAC,MAAM,CAAC,CAEkD,CAAC;AAE9E;;;;GAIG;AACH,eAAO,MAAM,KAAK,SA7CS,EAAE,SAAS,SAAS,OAAO,EAAE,SAC/C,EAAE,KACR,EAAE,SAAS,SAAS,EAAE,GACrB,QAAQ,CAAC,IAAI,GACb,EAAE,SAAS,SAAS,CAAC,MAAM,CAAC,EAAE,GAAG,OAAO,EAAE,CAAC,GACzC,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,GAChB,EAAE,SAAS,aAAa,CAAC,MAAM,CAAC,CAAC,GAC/B,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,GAChB,QAAQ,CAAC,EAAE,CAAC,MAAM,CAAC,CAqCF,CAAC"}

package/dist/array/impl/array-utils-element-access.mjs

@@ -0,0 +1,66 @@
+import { Optional } from '../../functional/optional.mjs';
+import { pipe } from '../../functional/pipe.mjs';
+import '../../functional/result.mjs';
+
+function at(...args) {
+    switch (args.length) {
+        case 2: {
+            const [array, index] = args;
+            return pipe(index < 0 ? array.length + index : index).map((normalizedIndex) => normalizedIndex < 0 || normalizedIndex >= array.length
+                ? Optional.none
+                : // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+                    Optional.some(array[normalizedIndex])).value;
+        }
+        case 1: {
+            const [index] = args;
+            return (array) => at(array, index);
+        }
+    }
+}
+/**
+ * Returns the first element of an array as an Optional.
+ *
+ * @example
+ *
+ * ```ts
+ * const users = [{ id: 1 }, { id: 2 }];
+ * const empty: { id: number }[] = [];
+ *
+ * const first = Arr.head(users);
+ * const none = Arr.head(empty);
+ *
+ * assert.deepStrictEqual(first, Optional.some({ id: 1 }));
+ * assert.deepStrictEqual(none, Optional.none);
+ * ```
+ */
+const head = (array) => 
+// eslint-disable-next-line total-functions/no-unsafe-type-assertion
+(array.length === 0 ? Optional.none : Optional.some(array.at(0)));
+/**
+ * Returns the last element of an array as an Optional.
+ *
+ * @example
+ *
+ * ```ts
+ * const queue = ['first', 'second'];
+ * const emptyQueue: string[] = [];
+ *
+ * const lastValue = Arr.last(queue);
+ * const none = Arr.last(emptyQueue);
+ *
+ * assert.deepStrictEqual(lastValue, Optional.some('second'));
+ * assert.deepStrictEqual(none, Optional.none);
+ * ```
+ */
+const last = (array) => 
+// eslint-disable-next-line total-functions/no-unsafe-type-assertion
+(array.length === 0 ? Optional.none : Optional.some(array.at(-1)));
+/**
+ * Alias for `head`.
+ *
+ * @see {@link head}
+ */
+const first = head;
+
+export { at, first, head, last };
+//# sourceMappingURL=array-utils-element-access.mjs.map

package/dist/array/impl/array-utils-element-access.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"array-utils-element-access.mjs","sources":["../../../src/array/impl/array-utils-element-access.mts"],"sourcesContent":[null],"names":[],"mappings":";;;;AA8BM,SAAU,EAAE,CAChB,GAAG,IAE8C,EAAA;AAEjD,IAAA,QAAQ,IAAI,CAAC,MAAM;QACjB,KAAK,CAAC,EAAE;AACN,YAAA,MAAM,CAAC,KAAK,EAAE,KAAK,CAAC,GAAG,IAAI;AAC3B,YAAA,OAAO,IAAI,CAAC,KAAK,GAAG,CAAC,GAAG,KAAK,CAAC,MAAM,GAAG,KAAK,GAAG,KAAK,CAAC,CAAC,GAAG,CACvD,CAAC,eAAe,KACd,eAAe,GAAG,CAAC,IAAI,eAAe,IAAI,KAAK,CAAC;kBAC5C,QAAQ,CAAC;AACX;oBACE,QAAQ,CAAC,IAAI,CAAC,KAAK,CAAC,eAAe,CAAE,CAAC,CAC7C,CAAC,KAAK;QACT;QACA,KAAK,CAAC,EAAE;AACN,YAAA,MAAM,CAAC,KAAK,CAAC,GAAG,IAAI;YACpB,OAAO,CAAC,KAAK,KAAK,EAAE,CAAC,KAAK,EAAE,KAAK,CAAC;QACpC;;AAEJ;AAEA;;;;;;;;;;;;;;;AAeG;AACI,MAAM,IAAI,GAAG,CAClB,KAAS;AAQT;AACA,CAAC,KAAK,CAAC,MAAM,KAAK,CAAC,GAAG,QAAQ,CAAC,IAAI,GAAG,QAAQ,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;AAElE;;;;;;;;;;;;;;;AAeG;AACI,MAAM,IAAI,GAAG,CAClB,KAAS;AAQT;AACA,CAAC,KAAK,CAAC,MAAM,KAAK,CAAC,GAAG,QAAQ,CAAC,IAAI,GAAG,QAAQ,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC;AAEnE;;;;AAIG;AACI,MAAM,KAAK,GAAG;;;;"}

package/dist/array/impl/array-utils-iterators.d.mts

@@ -0,0 +1,59 @@
+/**
+ * Returns an iterator of `[index, value]` pairs for an array.
+ *
+ * @example
+ *
+ * ```ts
+ * const tags = ['alpha', 'beta', 'gamma'] as const;
+ *
+ * const entryList = Array.from(
+ *   Arr.entries(tags),
+ *   ([index, tag]) => [Number(index), tag] as const,
+ * );
+ *
+ * assert.deepStrictEqual(
+ *   entryList,
+ *   Array.from([
+ *     [0, 'alpha'],
+ *     [1, 'beta'],
+ *     [2, 'gamma'],
+ *   ]),
+ * );
+ * ```
+ */
+export declare const entries: <E>(array: readonly E[]) => ArrayIterator<readonly [SizeType.Arr, E]>;
+/**
+ * Returns an iterator of values for an array.
+ *
+ * @example
+ *
+ * ```ts
+ * const players = ['Ada', 'Grace', 'Alan'];
+ *
+ * const valueList = Array.from(Arr.values(players));
+ *
+ * assert.deepStrictEqual(valueList, players);
+ * ```
+ */
+export declare const values: <E>(array: readonly E[]) => ArrayIterator<E>;
+/**
+ * Returns an iterator of indices for an array.
+ *
+ * @example
+ *
+ * ```ts
+ * const items = ['zero', 'one', 'two'] as const;
+ *
+ * const indexList = Array.from(Arr.indices(items));
+ *
+ * assert.deepStrictEqual(indexList, [0, 1, 2]);
+ * ```
+ */
+export declare const indices: <E>(array: readonly E[]) => ArrayIterator<SizeType.Arr>;
+/**
+ * Alias for `indices`.
+ *
+ * @see {@link indices}
+ */
+export declare const keys: <E>(array: readonly E[]) => ArrayIterator<SizeType.Arr>;
+//# sourceMappingURL=array-utils-iterators.d.mts.map

package/dist/array/impl/array-utils-iterators.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"array-utils-iterators.d.mts","sourceRoot":"","sources":["../../../src/array/impl/array-utils-iterators.mts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,eAAO,MAAM,OAAO,GAAc,CAAC,EACjC,OAAO,SAAS,CAAC,EAAE,KAClB,aAAa,CAAC,SAAS,CAAC,QAAQ,CAAC,GAAG,EAAE,CAAC,CAAC,CAI1C,CAAC;AAEF;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,MAAM,GAAc,CAAC,EAAE,OAAO,SAAS,CAAC,EAAE,KAAG,aAAa,CAAC,CAAC,CAIxE,CAAC;AAEF;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,OAAO,GAAc,CAAC,EACjC,OAAO,SAAS,CAAC,EAAE,KAClB,aAAa,CAAC,QAAQ,CAAC,GAAG,CAI5B,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,IAAI,GAbiB,CAAC,SAC1B,SAAS,CAAC,EAAE,KAClB,aAAa,CAAC,QAAQ,CAAC,GAAG,CAWF,CAAC"}