ts-data-forge 14.6.0 → 14.6.2

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

@@ -1,27 +1,127 @@
-import { range as range$1 } from '../../iterator/range.mjs';
-
-const zeros = (len) => (
-  // eslint-disable-next-line total-functions/no-unsafe-type-assertion
-  Array.from({ length: len }, () => 0)
-);
-const seq = (len) => (
-  // eslint-disable-next-line total-functions/no-unsafe-type-assertion
-  Array.from({ length: len }, (_, i) => i)
-);
-const create = (len, init) => (
-  // eslint-disable-next-line total-functions/no-unsafe-type-assertion
-  Array.from({ length: Math.max(0, len) }, () => init)
-);
-const newArray = create;
-const generate = (generatorFn) => Array.from(generatorFn());
-const generateAsync = (generatorFn) => Array.fromAsync(generatorFn());
-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
+import { range as rangeIterator } from '../../iterator/index.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]);
+ * ```
+ */
+export const zeros = (len) => 
+// eslint-disable-next-line total-functions/no-unsafe-type-assertion
+Array.from({ length: len }, () => 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 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, []);
+ * ```
+ */
+export 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}
+ */
+export 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]);
+ * ```
+ */
+export 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']);
+ * ```
+ */
+export 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);
+ * ```
+ */
+export const copy = (array) => 
+// eslint-disable-next-line total-functions/no-unsafe-type-assertion
+array.slice();
+
+
+
+
+
+
+
+export function range(start, end, step = 1) {
+    return Array.from(rangeIterator(start, end, step));
+}
+//# sourceMappingURL=array-utils-creation.mjs.map

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

@@ -1 +1 @@
-{"version":3,"file":"array-utils-creation.mjs","sources":["../../../src/array/impl/array-utils-creation.mts"],"sourcesContent":["import {\n  type BoolOr,\n  type FixedLengthArray,\n  type FixedLengthTuple,\n  type Index,\n  type IsUnion,\n  type List,\n  type Min,\n  type NonEmptyArray,\n  type NonZeroSafeIntWithSmallInt,\n  type PositiveSafeIntWithSmallInt,\n  type RelaxedExclude,\n  type SafeInt,\n  type SafeIntWithSmallInt,\n  type SafeUint,\n  type SafeUintWithSmallInt,\n  type Seq,\n  type SmallUint,\n  type StructuralPrefixLength,\n  type SupportedLength,\n} from 'ts-type-forge';\nimport { expectType } from '../../expect-type.mjs';\nimport { range as rangeIterator } from '../../iterator/index.mjs';\nimport { type SizeType } from '../../types.mjs';\n\n/**\n * Creates an array of zeros with the specified length.\n *\n * @example\n *\n * ```ts\n * const emptyZeros = Arr.zeros(0);\n *\n * const threeZeros = Arr.zeros(3);\n *\n * assert.deepStrictEqual(emptyZeros, []);\n *\n * assert.deepStrictEqual(threeZeros, [0, 0, 0]);\n * ```\n */\nexport const zeros = <N extends SizeType.ArgArr>(\n  len: N,\n): N extends SmallUint\n  ? FixedLengthTuple<N, 0>\n  : N extends SizeType.ArgArrPositive\n    ? NonEmptyArray<0>\n    : readonly 0[] =>\n  // eslint-disable-next-line total-functions/no-unsafe-type-assertion\n  Array.from({ length: len }, () => 0) as never;\n\n/**\n * Creates a sequence of consecutive integers from 0 to `len-1`.\n *\n * @example\n *\n * ```ts\n * const emptySeq = Arr.seq(0);\n *\n * const firstFive = Arr.seq(5);\n *\n * assert.deepStrictEqual(emptySeq, []);\n *\n * assert.deepStrictEqual(firstFive, [0, 1, 2, 3, 4]);\n * ```\n */\nexport const seq = <N extends SizeType.ArgArr>(\n  len: N,\n): N extends SmallUint\n  ? Seq<N>\n  : N extends SizeType.ArgArrPositive\n    ? NonEmptyArray<SizeType.Arr>\n    : readonly SizeType.Arr[] =>\n  // eslint-disable-next-line total-functions/no-unsafe-type-assertion\n  Array.from({ length: len }, (_, i) => i) as never;\n\n/**\n * Creates a new array of the specified length, filled with the initial value.\n *\n * @example\n *\n * ```ts\n * const threeOnes = Arr.create(3, 1);\n *\n * const emptyStrings = Arr.create(0, 'Ada');\n *\n * assert.deepStrictEqual(threeOnes, [1, 1, 1]);\n *\n * assert.deepStrictEqual(emptyStrings, []);\n * ```\n */\nexport const create = <N extends SizeType.ArgArr, const V>(\n  len: N,\n  init: V,\n): N extends StructuralPrefixLength\n  ? FixedLengthTuple<N, V>\n  : N extends SupportedLength\n    ? FixedLengthArray<N, V>\n    : N extends SizeType.ArgArrPositive\n      ? NonEmptyArray<V>\n      : readonly V[] =>\n  // eslint-disable-next-line total-functions/no-unsafe-type-assertion\n  Array.from({ length: Math.max(0, len) }, () => init) as never;\n\n/**\n * Alias for `create`.\n *\n * @see {@link create}\n */\nexport const newArray = create;\n\n/**\n * Generates an array from a generator function.\n *\n * @example\n *\n * ```ts\n * const numbers = Arr.generate(function* () {\n *   yield 1;\n *\n *   yield 2;\n *\n *   yield 3;\n * });\n *\n * assert.deepStrictEqual(numbers, [1, 2, 3]);\n * ```\n */\nexport const generate = <T,>(\n  generatorFn: () => Generator<T, void, unknown>,\n): readonly T[] => Array.from(generatorFn());\n\n/**\n * Generates an array from an async generator function.\n *\n * @example\n *\n * ```ts\n * const values = await Arr.generateAsync(async function* () {\n *   yield 'Ada';\n *\n *   await Promise.resolve();\n *\n *   yield 'Lovelace';\n * });\n *\n * assert.deepStrictEqual(values, ['Ada', 'Lovelace']);\n * ```\n */\nexport const generateAsync = <T,>(\n  generatorFn: () => AsyncGenerator<T, void, unknown>,\n): Promise<readonly T[]> => Array.fromAsync(generatorFn());\n\n/**\n * Creates a shallow copy of an array.\n *\n * @example\n *\n * ```ts\n * const original = [{ id: 1 }, { id: 2 }] as const;\n *\n * const cloned = Arr.copy(original);\n *\n * assert.deepStrictEqual(cloned, original);\n *\n * assert.notStrictEqual(cloned, original);\n * ```\n */\nexport const copy = <const Ar extends readonly unknown[]>(array: Ar): Ar =>\n  // eslint-disable-next-line total-functions/no-unsafe-type-assertion\n  array.slice() as unknown as Ar;\n\ntype LT = Readonly<{ [N in SmallUint]: Index<N> }>;\n\ntype RangeList<S extends SmallUint, E extends SmallUint> =\n  BoolOr<IsUnion<S>, IsUnion<E>> extends true\n    ? readonly RelaxedExclude<LT[E], LT[Min<S>]>[] // Avoid incorrect type calculation for unions with Seq\n    : List.Skip<S, Seq<E>>;\n\nexpectType<RangeList<1, 5>, readonly [1, 2, 3, 4]>('=');\n\nexpectType<RangeList<1, 2>, readonly [1]>('=');\n\nexpectType<RangeList<1, 1>, readonly []>('=');\n\nexpectType<RangeList<1, 1 | 3>, readonly (1 | 2)[]>('=');\n\nexpectType<RangeList<1 | 3, 3 | 5>, readonly (1 | 2 | 3 | 4)[]>('=');\n\nexpectType<RangeList<1 | 2 | 3, 5 | 6 | 7>, readonly (1 | 2 | 3 | 4 | 5 | 6)[]>(\n  '=',\n);\n\nexpectType<RangeList<5, 1>, readonly []>('=');\n\n/**\n * Creates an array of numbers within a specified range with optional step.\n *\n * @example\n *\n * ```ts\n * const ascending = Arr.range(asUint32(1), asUint32(5));\n *\n * const empty = Arr.range(asUint32(2), asUint32(2));\n *\n * assert.deepStrictEqual(ascending, [1, 2, 3, 4]);\n *\n * assert.deepStrictEqual(empty, []);\n * ```\n */\nexport function range<S extends SmallUint, E extends SmallUint>(\n  start: S,\n  end: E,\n  step?: 1,\n): RangeList<S, E>;\n\nexport function range(\n  start: SafeUintWithSmallInt,\n  end: SafeUintWithSmallInt,\n  step?: PositiveSafeIntWithSmallInt,\n): readonly SafeUint[];\n\nexport function range(\n  start: SafeIntWithSmallInt,\n  end: SafeIntWithSmallInt,\n  step?: NonZeroSafeIntWithSmallInt,\n): readonly SafeInt[];\n\nexport function range(\n  start: SafeIntWithSmallInt,\n  end: SafeIntWithSmallInt,\n  step: NonZeroSafeIntWithSmallInt = 1,\n): readonly SafeInt[] {\n  return Array.from(rangeIterator(start, end, step));\n}\n"],"names":["rangeIterator"],"mappings":";;AAwCO,MAAM,QAAQ,CACnB,GAAA;AAAA;AAAA,EAOA,MAAM,IAAA,CAAK,EAAE,QAAQ,GAAA,EAAI,EAAG,MAAM,CAAC;AAAA;AAiB9B,MAAM,MAAM,CACjB,GAAA;AAAA;AAAA,EAOA,KAAA,CAAM,KAAK,EAAE,MAAA,EAAQ,KAAI,EAAG,CAAC,CAAA,EAAG,CAAA,KAAM,CAAC;AAAA;MAiB5B,MAAA,GAAS,CACpB,GAAA,EACA,IAAA;AAAA;AAAA,EASA,KAAA,CAAM,IAAA,CAAK,EAAE,MAAA,EAAQ,IAAA,CAAK,GAAA,CAAI,CAAA,EAAG,GAAG,CAAA,EAAE,EAAG,MAAM,IAAI;AAAA;AAO9C,MAAM,QAAA,GAAW;AAmBjB,MAAM,WAAW,CACtB,WAAA,KACiB,KAAA,CAAM,IAAA,CAAK,aAAa;AAmBpC,MAAM,gBAAgB,CAC3B,WAAA,KAC0B,KAAA,CAAM,SAAA,CAAU,aAAa;AAiBlD,MAAM,OAAO,CAAsC,KAAA;AAAA;AAAA,EAExD,MAAM,KAAA;AAAM;AA0DP,SAAS,KAAA,CACd,KAAA,EACA,GAAA,EACA,IAAA,GAAmC,CAAA,EACf;AACpB,EAAA,OAAO,MAAM,IAAA,CAAKA,OAAA,CAAc,KAAA,EAAO,GAAA,EAAK,IAAI,CAAC,CAAA;AACnD;;;;"}
+{"version":3,"file":"array-utils-creation.mjs","sourceRoot":"","sources":["../../../src/array/impl/array-utils-creation.mts"],"names":[],"mappings":"AAqBA,OAAO,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAC;AACnD,OAAO,EAAE,KAAK,IAAI,aAAa,EAAE,MAAM,0BAA0B,CAAC;AAGlE;;;;;;;;;;;;;;GAcG;AACH,MAAM,CAAC,MAAM,KAAK,GAAG,CACnB,GAAM,EAKW,EAAE;AACnB,oEAAoE;AACpE,KAAK,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,GAAG,EAAE,EAAE,GAAG,EAAE,CAAC,CAAC,CAAU,CAAC;AAEhD;;;;;;;;;;;;;;GAcG;AACH,MAAM,CAAC,MAAM,GAAG,GAAG,CACjB,GAAM,EAKsB,EAAE;AAC9B,oEAAoE;AACpE,KAAK,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,GAAG,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAU,CAAC;AAEpD;;;;;;;;;;;;;;GAcG;AACH,MAAM,CAAC,MAAM,MAAM,GAAG,CACpB,GAAM,EACN,IAAO,EAOY,EAAE;AACrB,oEAAoE;AACpE,KAAK,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,GAAG,CAAC,EAAE,EAAE,GAAG,EAAE,CAAC,IAAI,CAAU,CAAC;AAEhE;;;;GAIG;AACH,MAAM,CAAC,MAAM,QAAQ,GAAG,MAAM,CAAC;AAE/B;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,CAAC,MAAM,QAAQ,GAAG,CACtB,WAA8C,EAChC,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC,WAAW,EAAE,CAAC,CAAC;AAE7C;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,CAAC,MAAM,aAAa,GAAG,CAC3B,WAAmD,EAC5B,EAAE,CAAC,KAAK,CAAC,SAAS,CAAC,WAAW,EAAE,CAAC,CAAC;AAE3D;;;;;;;;;;;;;;GAcG;AACH,MAAM,CAAC,MAAM,IAAI,GAAG,CAAsC,KAAS,EAAM,EAAE;AACzE,oEAAoE;AACpE,KAAK,CAAC,KAAK,EAAmB,CAAC;AASjC,UAAU,CAAyC,GAAG,CAAC,CAAC;AAExD,UAAU,CAAgC,GAAG,CAAC,CAAC;AAE/C,UAAU,CAA+B,GAAG,CAAC,CAAC;AAE9C,UAAU,CAA0C,GAAG,CAAC,CAAC;AAEzD,UAAU,CAAsD,GAAG,CAAC,CAAC;AAErE,UAAU,CACR,GAAG,CACJ,CAAC;AAEF,UAAU,CAA+B,GAAG,CAAC,CAAC;AAmC9C,MAAM,UAAU,KAAK,CACnB,KAA0B,EAC1B,GAAwB,EACxB,IAAI,GAA+B,CAAC;IAEpC,OAAO,KAAK,CAAC,IAAI,CAAC,aAAa,CAAC,KAAK,EAAE,GAAG,EAAE,IAAI,CAAC,CAAC,CAAC;AACrD,CAAC"}

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

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

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

@@ -1 +1 @@
-{"version":3,"file":"array-utils-element-access.mjs","sources":["../../../src/array/impl/array-utils-element-access.mts"],"sourcesContent":["import { type NonEmptyTuple } from 'ts-type-forge';\nimport { Optional, pipe } from '../../functional/index.mjs';\nimport {\n  type ArgArrayIndexWithNegative,\n  type None,\n  type SizeType,\n  type Some,\n} from '../../types.mjs';\n\n/**\n * Safely retrieves an element at a given index from an array, returning an Optional.\n *\n * @example\n *\n * ```ts\n * const letters: readonly string[] = ['a', 'b', 'c'] as const;\n *\n * const two = Arr.at(letters, 1);\n *\n * const last = Arr.at(-1)(letters);\n *\n * const missing = Arr.at(letters, 5);\n *\n * assert.deepStrictEqual(two, Optional.some('b'));\n *\n * assert.deepStrictEqual(last, Optional.some('c'));\n *\n * assert.deepStrictEqual(missing, Optional.none);\n * ```\n */\nexport function at<const Ar extends readonly unknown[]>(\n  array: Ar,\n  index: ArgArrayIndexWithNegative<Ar>,\n): Optional<Ar[number]>;\n\n// Curried version\n\nexport function at(\n  index: SizeType.ArgArrWithNegative,\n): <E>(array: readonly E[]) => Optional<E>;\n\nexport function at<E>(\n  ...args:\n    | readonly [array: readonly E[], index: SizeType.ArgArrWithNegative]\n    | readonly [index: SizeType.ArgArrWithNegative]\n): Optional<E> | ((array: readonly E[]) => Optional<E>) {\n  switch (args.length) {\n    case 2:\n      return atImpl(...args);\n\n    case 1:\n      return (array) => atImpl(array, ...args);\n  }\n}\n\nconst atImpl = <E,>(\n  array: readonly E[],\n  index: SizeType.ArgArrWithNegative,\n): Optional<E> =>\n  pipe(index < 0 ? array.length + index : index).map((normalizedIndex) =>\n    normalizedIndex < 0 || normalizedIndex >= array.length\n      ? Optional.none\n      : // eslint-disable-next-line @typescript-eslint/no-non-null-assertion\n        Optional.some(array[normalizedIndex]!),\n  ).value;\n\n/**\n * Returns the first element of an array as an Optional.\n *\n * @example\n *\n * ```ts\n * const users = [{ id: 1 }, { id: 2 }] as const;\n *\n * const empty: readonly Readonly<{ id: number }>[] = [] as const;\n *\n * const first = Arr.head(users);\n *\n * const none = Arr.head(empty);\n *\n * assert.deepStrictEqual(first, Optional.some({ id: 1 }));\n *\n * assert.deepStrictEqual(none, Optional.none);\n * ```\n */\nexport const head = <const Ar extends readonly unknown[]>(\n  array: Ar,\n): Ar extends readonly []\n  ? None\n  : Ar extends readonly [infer E, ...unknown[]]\n    ? Some<E>\n    : Ar extends NonEmptyTuple<infer E>\n      ? Some<E>\n      : Optional<Ar[number]> =>\n  // eslint-disable-next-line total-functions/no-unsafe-type-assertion\n  (array.length === 0 ? Optional.none : Optional.some(array.at(0))) as never;\n\n/**\n * Returns the last element of an array as an Optional.\n *\n * @example\n *\n * ```ts\n * const queue = ['first', 'second'] as const;\n *\n * const emptyQueue: readonly string[] = [] as const;\n *\n * const lastValue = Arr.last(queue);\n *\n * const none = Arr.last(emptyQueue);\n *\n * assert.deepStrictEqual(lastValue, Optional.some('second'));\n *\n * assert.deepStrictEqual(none, Optional.none);\n * ```\n */\nexport const last = <const Ar extends readonly unknown[]>(\n  array: Ar,\n): Ar extends readonly []\n  ? None\n  : Ar extends readonly [...unknown[], infer E]\n    ? Some<E>\n    : Ar extends NonEmptyTuple<infer E>\n      ? Some<E>\n      : Optional<Ar[number]> =>\n  // eslint-disable-next-line total-functions/no-unsafe-type-assertion\n  (array.length === 0 ? Optional.none : Optional.some(array.at(-1))) as never;\n\n/**\n * Alias for `head`.\n *\n * @see {@link head}\n */\nexport const first = head;\n"],"names":["index","Optional.none","Optional.some"],"mappings":";;;;;AAyCO,SAAS,MACX,IAAA,EAGmD;AACtD,EAAA,QAAQ,KAAK,MAAA;AAAQ,IACnB,KAAK,CAAA;AACH,MAAA,OAAO,MAAA,CAAO,GAAG,IAAI,CAAA;AAAA,IAEvB,KAAK,CAAA;AACH,MAAA,OAAO,CAAC,KAAA,KAAU,MAAA,CAAO,KAAA,EAAO,GAAG,IAAI,CAAA;AAAA;AAE7C;AAEA,MAAM,MAAA,GAAS,CACb,KAAA,EACAA,OAAA,KAEA,IAAA,CAAKA,OAAA,GAAQ,CAAA,GAAI,KAAA,CAAM,MAAA,GAASA,OAAA,GAAQA,OAAK,CAAA,CAAE,GAAA;AAAA,EAAI,CAAC,eAAA,KAClD,eAAA,GAAkB,KAAK,eAAA,IAAmB,KAAA,CAAM,SAC5CC,IAAS;AAAA;AAAA,IAETC,IAAS,CAAK,KAAA,CAAM,eAAe,CAAE;AAAA;AAC3C,CAAA,CAAE,KAAA;AAqBG,MAAM,OAAO,CAClB,KAAA;AAAA;AAAA,EASC,KAAA,CAAM,MAAA,KAAW,CAAA,GAAID,IAAS,GAAOC,IAAS,CAAK,KAAA,CAAM,EAAA,CAAG,CAAC,CAAC;AAAA;AAqB1D,MAAM,OAAO,CAClB,KAAA;AAAA;AAAA,EASC,KAAA,CAAM,MAAA,KAAW,CAAA,GAAID,IAAS,GAAOC,IAAS,CAAK,KAAA,CAAM,EAAA,CAAG,EAAE,CAAC;AAAA;AAO3D,MAAM,KAAA,GAAQ;;;;"}
+{"version":3,"file":"array-utils-element-access.mjs","sourceRoot":"","sources":["../../../src/array/impl/array-utils-element-access.mts"],"names":[],"mappings":"AACA,OAAO,EAAE,QAAQ,EAAE,IAAI,EAAE,MAAM,4BAA4B,CAAC;AAwC5D,MAAM,UAAU,EAAE,CAChB,GAAG,IAE8C;IAEjD,QAAQ,IAAI,CAAC,MAAM,EAAE,CAAC;QACpB,KAAK,CAAC;YACJ,OAAO,MAAM,CAAC,GAAG,IAAI,CAAC,CAAC;QAEzB,KAAK,CAAC;YACJ,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,MAAM,CAAC,KAAK,EAAE,GAAG,IAAI,CAAC,CAAC;IAC7C,CAAC;AACH,CAAC;AAED,MAAM,MAAM,GAAG,CACb,KAAmB,EACnB,KAAkC,EACrB,EAAE,CACf,IAAI,CAAC,KAAK,GAAG,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,MAAM,GAAG,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,GAAG,CAAC,CAAC,eAAe,EAAE,EAAE,CACrE,eAAe,GAAG,CAAC,IAAI,eAAe,IAAI,KAAK,CAAC,MAAM;IACpD,CAAC,CAAC,QAAQ,CAAC,IAAI;IACf,CAAC,CAAC,oEAAoE;QACpE,QAAQ,CAAC,IAAI,CAAC,KAAK,CAAC,eAAe,CAAE,CAAC,CAC3C,CAAC,KAAK,CAAC;AAEV;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,CAAC,MAAM,IAAI,GAAG,CAClB,KAAS,EAOkB,EAAE;AAC7B,oEAAoE;AACpE,CAAC,KAAK,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,QAAQ,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAU,CAAC;AAE7E;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,CAAC,MAAM,IAAI,GAAG,CAClB,KAAS,EAOkB,EAAE;AAC7B,oEAAoE;AACpE,CAAC,KAAK,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,QAAQ,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAU,CAAC;AAE9E;;;;GAIG;AACH,MAAM,CAAC,MAAM,KAAK,GAAG,IAAI,CAAC"}

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

@@ -1,56 +1,72 @@
-import '../../number/branded-types/finite-number.mjs';
-import '../../number/branded-types/int.mjs';
-import '../../number/branded-types/int16.mjs';
-import '../../number/branded-types/int32.mjs';
-import '../../number/branded-types/negative-finite-number.mjs';
-import '../../number/branded-types/negative-int.mjs';
-import '../../number/branded-types/negative-safe-int.mjs';
-import '../../number/branded-types/non-negative-finite-number.mjs';
-import '../../number/branded-types/non-negative-int16.mjs';
-import '../../number/branded-types/non-negative-int32.mjs';
-import '../../number/branded-types/non-positive-finite-number.mjs';
-import '../../number/branded-types/non-positive-int.mjs';
-import '../../number/branded-types/non-positive-safe-int.mjs';
-import '../../number/branded-types/non-zero-finite-number.mjs';
-import '../../number/branded-types/non-zero-int.mjs';
-import '../../number/branded-types/non-zero-int16.mjs';
-import '../../number/branded-types/non-zero-int32.mjs';
-import '../../number/branded-types/non-zero-safe-int.mjs';
-import '../../number/branded-types/non-zero-uint16.mjs';
-import '../../number/branded-types/non-zero-uint32.mjs';
-import '../../number/branded-types/positive-finite-number.mjs';
-import '../../number/branded-types/positive-int.mjs';
-import '../../number/branded-types/positive-int16.mjs';
-import '../../number/branded-types/positive-int32.mjs';
-import '../../number/branded-types/positive-safe-int.mjs';
-import '../../number/branded-types/positive-uint16.mjs';
-import '../../number/branded-types/positive-uint32.mjs';
-import '../../number/branded-types/safe-int.mjs';
-import '../../number/branded-types/safe-uint.mjs';
-import '../../number/branded-types/uint.mjs';
-import '../../number/branded-types/uint16.mjs';
-import { asUint32 } from '../../number/branded-types/uint32.mjs';
-import '../../number/enum/int8.mjs';
-import '../../number/enum/uint8.mjs';
-import '../../number/num.mjs';
-import '../../number/refined-number-utils.mjs';
-
-const entries = function* (array) {
-  for (const [index, value] of array.entries()) {
-    yield [asUint32(index), value];
-  }
+import { asUint32 } from '../../number/index.mjs';
+/**
+ * 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 const entries = function* (array) {
+    for (const [index, value] of array.entries()) {
+        yield [asUint32(index), value];
+    }
 };
-const values = function* (array) {
-  for (const value of array) {
-    yield value;
-  }
+/**
+ * Returns an iterator of values for an array.
+ *
+ * @example
+ *
+ * ```ts
+ * const players = ['Ada', 'Grace', 'Alan'] as readonly string[];
+ *
+ * const valueList = Array.from(Arr.values(players));
+ *
+ * assert.deepStrictEqual(valueList, players);
+ * ```
+ */
+export const values = function* (array) {
+    for (const value of array) {
+        yield value;
+    }
 };
-const indices = function* (array) {
-  for (const key of array.keys()) {
-    yield asUint32(key);
-  }
+/**
+ * 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 const indices = function* (array) {
+    for (const key of array.keys()) {
+        yield asUint32(key);
+    }
 };
-const keys = indices;
-
-export { entries, indices, keys, values };
-//# sourceMappingURL=array-utils-iterators.mjs.map
+/**
+ * Alias for `indices`.
+ *
+ * @see {@link indices}
+ */
+export const keys = indices;
+//# sourceMappingURL=array-utils-iterators.mjs.map

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

@@ -1 +1 @@
-{"version":3,"file":"array-utils-iterators.mjs","sources":["../../../src/array/impl/array-utils-iterators.mts"],"sourcesContent":["import { asUint32 } from '../../number/index.mjs';\nimport { type SizeType } from '../../types.mjs';\n\n/**\n * Returns an iterator of `[index, value]` pairs for an array.\n *\n * @example\n *\n * ```ts\n * const tags = ['alpha', 'beta', 'gamma'] as const;\n *\n * const entryList = Array.from(\n *   Arr.entries(tags),\n *   ([index, tag]) => [Number(index), tag] as const,\n * );\n *\n * assert.deepStrictEqual(\n *   entryList,\n *   Array.from([\n *     [0, 'alpha'],\n *     [1, 'beta'],\n *     [2, 'gamma'],\n *   ]),\n * );\n * ```\n */\nexport const entries = function* <E>(\n  array: readonly E[],\n): ArrayIterator<readonly [SizeType.Arr, E]> {\n  for (const [index, value] of array.entries()) {\n    yield [asUint32(index), value] as const;\n  }\n};\n\n/**\n * Returns an iterator of values for an array.\n *\n * @example\n *\n * ```ts\n * const players = ['Ada', 'Grace', 'Alan'] as readonly string[];\n *\n * const valueList = Array.from(Arr.values(players));\n *\n * assert.deepStrictEqual(valueList, players);\n * ```\n */\nexport const values = function* <E>(array: readonly E[]): ArrayIterator<E> {\n  for (const value of array) {\n    yield value;\n  }\n};\n\n/**\n * Returns an iterator of indices for an array.\n *\n * @example\n *\n * ```ts\n * const items = ['zero', 'one', 'two'] as const;\n *\n * const indexList = Array.from(Arr.indices(items));\n *\n * assert.deepStrictEqual(indexList, [0, 1, 2]);\n * ```\n */\nexport const indices = function* <E>(\n  array: readonly E[],\n): ArrayIterator<SizeType.Arr> {\n  for (const key of array.keys()) {\n    yield asUint32(key);\n  }\n};\n\n/**\n * Alias for `indices`.\n *\n * @see {@link indices}\n */\nexport const keys = indices;\n"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA0BO,MAAM,OAAA,GAAU,WACrB,KAAA,EAC2C;AAC3C,EAAA,KAAA,MAAW,CAAC,KAAA,EAAO,KAAK,CAAA,IAAK,KAAA,CAAM,SAAQ,EAAG;AAC5C,IAAA,MAAM,CAAC,QAAA,CAAS,KAAK,CAAA,EAAG,KAAK,CAAA;AAAA,EAC/B;AACF;AAeO,MAAM,MAAA,GAAS,WAAc,KAAA,EAAuC;AACzE,EAAA,KAAA,MAAW,SAAS,KAAA,EAAO;AACzB,IAAA,MAAM,KAAA;AAAA,EACR;AACF;AAeO,MAAM,OAAA,GAAU,WACrB,KAAA,EAC6B;AAC7B,EAAA,KAAA,MAAW,GAAA,IAAO,KAAA,CAAM,IAAA,EAAK,EAAG;AAC9B,IAAA,MAAM,SAAS,GAAG,CAAA;AAAA,EACpB;AACF;AAOO,MAAM,IAAA,GAAO;;;;"}
+{"version":3,"file":"array-utils-iterators.mjs","sourceRoot":"","sources":["../../../src/array/impl/array-utils-iterators.mts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,wBAAwB,CAAC;AAGlD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAM,CAAC,MAAM,OAAO,GAAG,QAAQ,CAAC,EAC9B,KAAmB;IAEnB,KAAK,MAAM,CAAC,KAAK,EAAE,KAAK,CAAC,IAAI,KAAK,CAAC,OAAO,EAAE,EAAE,CAAC;QAC7C,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,KAAK,CAAU,CAAC;IAC1C,CAAC;AACH,CAAC,CAAC;AAEF;;;;;;;;;;;;GAYG;AACH,MAAM,CAAC,MAAM,MAAM,GAAG,QAAQ,CAAC,EAAK,KAAmB;IACrD,KAAK,MAAM,KAAK,IAAI,KAAK,EAAE,CAAC;QAC1B,MAAM,KAAK,CAAC;IACd,CAAC;AACH,CAAC,CAAC;AAEF;;;;;;;;;;;;GAYG;AACH,MAAM,CAAC,MAAM,OAAO,GAAG,QAAQ,CAAC,EAC9B,KAAmB;IAEnB,KAAK,MAAM,GAAG,IAAI,KAAK,CAAC,IAAI,EAAE,EAAE,CAAC;QAC/B,MAAM,QAAQ,CAAC,GAAG,CAAC,CAAC;IACtB,CAAC;AACH,CAAC,CAAC;AAEF;;;;GAIG;AACH,MAAM,CAAC,MAAM,IAAI,GAAG,OAAO,CAAC"}

package/dist/array/impl/array-utils-length-bounded-array-cast.mjs

@@ -1,87 +1,123 @@
-import { isFixedLengthArray, isMinLengthArray, isBoundedLengthArray, isMaxLengthArray } from './array-utils-length-bounded-array-guard.mjs';
-
-function asFixedLengthArray(...args) {
-  switch (args.length) {
-    case 2:
-      return asFixedLengthArrayImpl(...args);
-    case 1:
-      return (xs) => asFixedLengthArrayImpl(args[0], xs);
-  }
+import { isBoundedLengthArray, isFixedLengthArray, isMaxLengthArray, isMinLengthArray, } from './array-utils-length-bounded-array-guard.mjs';
+export function asFixedLengthArray(...args) {
+    switch (args.length) {
+        case 2:
+            return asFixedLengthArrayImpl(...args);
+        case 1:
+            return (xs) => asFixedLengthArrayImpl(args[0], xs);
+    }
 }
 const asFixedLengthArrayImpl = (length, xs) => {
-  const actualLength = xs.length;
-  if (!isFixedLengthArray(length, xs)) {
-    throw new TypeError(
-      `Expected an array of length ${length}, got an array of length ${actualLength}`
-    );
-  }
-  return xs;
+    const actualLength = xs.length;
+    if (!isFixedLengthArray(length, xs)) {
+        throw new TypeError(`Expected an array of length ${length}, got an array of length ${actualLength}`);
+    }
+    return xs;
 };
-function asMinLengthArray(...args) {
-  switch (args.length) {
-    case 2:
-      return asMinLengthArrayImpl(...args);
-    case 1:
-      return (xs) => asMinLengthArrayImpl(args[0], xs);
-  }
+export function asMinLengthArray(...args) {
+    switch (args.length) {
+        case 2:
+            return asMinLengthArrayImpl(...args);
+        case 1:
+            return (xs) => asMinLengthArrayImpl(args[0], xs);
+    }
 }
 const asMinLengthArrayImpl = (minLength, xs) => {
-  const actualLength = xs.length;
-  if (!isMinLengthArray(minLength, xs)) {
-    throw new TypeError(
-      `Expected an array of length >= ${minLength}, got an array of length ${actualLength}`
-    );
-  }
-  return xs;
+    const actualLength = xs.length;
+    if (!isMinLengthArray(minLength, xs)) {
+        throw new TypeError(`Expected an array of length >= ${minLength}, got an array of length ${actualLength}`);
+    }
+    return xs;
 };
-function asMaxLengthArray(...args) {
-  switch (args.length) {
-    case 2:
-      return asMaxLengthArrayImpl(...args);
-    case 1:
-      return (xs) => asMaxLengthArrayImpl(args[0], xs);
-  }
+export function asMaxLengthArray(...args) {
+    switch (args.length) {
+        case 2:
+            return asMaxLengthArrayImpl(...args);
+        case 1:
+            return (xs) => asMaxLengthArrayImpl(args[0], xs);
+    }
 }
 const asMaxLengthArrayImpl = (maxLength, xs) => {
-  const actualLength = xs.length;
-  if (!isMaxLengthArray(maxLength, xs)) {
-    throw new TypeError(
-      `Expected an array of length <= ${maxLength}, got an array of length ${actualLength}`
-    );
-  }
-  return xs;
+    const actualLength = xs.length;
+    if (!isMaxLengthArray(maxLength, xs)) {
+        throw new TypeError(`Expected an array of length <= ${maxLength}, got an array of length ${actualLength}`);
+    }
+    return xs;
 };
-function asBoundedLengthArray(...args) {
-  switch (args.length) {
-    case 3:
-      return asBoundedLengthArrayImpl(...args);
-    case 2:
-      return (xs) => asBoundedLengthArrayImpl(args[0], args[1], xs);
-  }
+export function asBoundedLengthArray(...args) {
+    switch (args.length) {
+        case 3:
+            return asBoundedLengthArrayImpl(...args);
+        case 2:
+            return (xs) => asBoundedLengthArrayImpl(args[0], args[1], xs);
+    }
 }
 const asBoundedLengthArrayImpl = (minLength, maxLength, xs) => {
-  const actualLength = xs.length;
-  if (!isBoundedLengthArray(minLength, maxLength, xs)) {
-    throw new TypeError(
-      `Expected an array of length in [${minLength}, ${maxLength}], got an array of length ${actualLength}`
-    );
-  }
-  return xs;
+    const actualLength = xs.length;
+    if (!isBoundedLengthArray(minLength, maxLength, xs)) {
+        throw new TypeError(`Expected an array of length in [${minLength}, ${maxLength}], got an array of length ${actualLength}`);
+    }
+    return xs;
 };
-const asEmptyArray = (xs) => {
-  if (!isFixedLengthArray(0, xs)) {
-    throw new TypeError(
-      `Expected an empty array, got an array of length ${xs.length}`
-    );
-  }
-  return xs;
+/**
+ * Casts an array to `FixedLengthArray<0, E>` after checking that it is empty.
+ *
+ * `Arr.isEmpty` narrows to that same type, so this is its cast counterpart —
+ * the length-0 specialization of {@link asFixedLengthArray}. Use this instead
+ * of writing `xs as unknown as FixedLengthArray<0, E>`: the length is verified
+ * at runtime, and the original array type is preserved via intersection.
+ *
+ * @example
+ *
+ * ```ts
+ * const nothing = Arr.asEmptyArray([]);
+ *
+ * const atMost5: MaxLengthArray<5, never> = nothing; // OK (0 <= 5)
+ *
+ * // Arr.asEmptyArray([1]); // throws TypeError
+ * ```
+ *
+ * @template Xs - The input array type (tuple types are preserved).
+ * @param xs - The array to cast.
+ * @returns `xs` typed as `FixedLengthArray<0, Xs[number]> & Xs`.
+ * @throws {TypeError} If `xs` is not empty.
+ */
+export const asEmptyArray = (xs) => {
+    if (!isFixedLengthArray(0, xs)) {
+        throw new TypeError(`Expected an empty array, got an array of length ${xs.length}`);
+    }
+    return xs;
 };
-const asNonEmptyArray = (xs) => {
-  if (!isMinLengthArray(1, xs)) {
-    throw new TypeError("Expected a non-empty array, got an empty array");
-  }
-  return xs;
+/**
+ * Casts an array to `NonEmptyArray<E>` after checking that it has at least one
+ * element.
+ *
+ * `NonEmptyArray<E>` is an alias of `MinLengthArray<1, E>`, so this is the
+ * length-1 specialization of {@link asMinLengthArray}. Use this instead of
+ * writing `xs as unknown as NonEmptyArray<E>`: the length is verified at
+ * runtime, and the original array type (e.g. tuple types) is preserved via
+ * intersection, so the result also benefits from the structural tuple prefix
+ * (`xs[0]` without `undefined` under `noUncheckedIndexedAccess`).
+ *
+ * @example
+ *
+ * ```ts
+ * const history = Arr.asNonEmptyArray([0, 1, 2, 3]);
+ *
+ * const first: number = history[0]; // OK — no `undefined`
+ *
+ * // Arr.asNonEmptyArray([]); // throws TypeError
+ * ```
+ *
+ * @template Xs - The input array type (tuple types are preserved).
+ * @param xs - The array to cast.
+ * @returns `xs` typed as `NonEmptyArray<Xs[number]> & Xs`.
+ * @throws {TypeError} If `xs` is empty.
+ */
+export const asNonEmptyArray = (xs) => {
+    if (!isMinLengthArray(1, xs)) {
+        throw new TypeError('Expected a non-empty array, got an empty array');
+    }
+    return xs;
 };
-
-export { asBoundedLengthArray, asEmptyArray, asFixedLengthArray, asMaxLengthArray, asMinLengthArray, asNonEmptyArray };
-//# sourceMappingURL=array-utils-length-bounded-array-cast.mjs.map
+//# sourceMappingURL=array-utils-length-bounded-array-cast.mjs.map