effect 4.0.0-rc.111 → 4.0.0-rc.113

package/src/Array.ts

@@ -16,6 +16,7 @@ import { dual, identity } from "./Function.ts"
 import * as Hash from "./Hash.ts"
 import type { TypeLambda } from "./HKT.ts"
 import * as internalArray from "./internal/array.ts"
+import * as Count from "./internal/count.ts"
 import * as internalDoNotation from "./internal/doNotation.ts"
 import * as InternalRecord from "./internal/record.ts"
 import * as moduleIterable from "./Iterable.ts"
@@ -158,6 +159,7 @@ export const make = <Elements extends NonEmptyArray<unknown>>(
  *
  * **Details**
  *
+ * `n` is rounded down. `NaN` and non-positive values are treated as `0`.
  * Elements are typed as `A | undefined` because the slots are empty.
  *
  * **Example** (Allocating a fixed-size array)
@@ -173,7 +175,7 @@ export const make = <Elements extends NonEmptyArray<unknown>>(
  * @category constructors
  * @since 2.0.0
  */
-export const allocate = <A = never>(n: number): Array<A | undefined> => new Array(n)
+export const allocate = <A = never>(n: number): Array<A | undefined> => new Array(Count.normalize(n))
 
 /**
  * Creates a `NonEmptyArray` of length `n` where element `i` is computed by `f(i)`.
@@ -184,9 +186,9 @@ export const allocate = <A = never>(n: number): Array<A | undefined> => new Arra
  *
  * **Details**
  *
- * `n` is normalized to an integer greater than or equal to 1, so this function
- * always returns at least one element. Supports both data-first and data-last
- * usage.
+ * `n` is rounded down and normalized to an integer greater than or equal to 1.
+ * `NaN` is treated as `1`, so this function always returns at least one
+ * element. Supports both data-first and data-last usage.
  *
  * **Example** (Generating values from indices)
  *
@@ -212,9 +214,9 @@ export const makeBy: {
    *
    * **Details**
    *
-   * `n` is normalized to an integer greater than or equal to 1, so this function
-   * always returns at least one element. Supports both data-first and data-last
-   * usage.
+   * `n` is rounded down and normalized to an integer greater than or equal to 1.
+   * `NaN` is treated as `1`, so this function always returns at least one
+   * element. Supports both data-first and data-last usage.
    *
    * **Example** (Generating values from indices)
    *
@@ -240,9 +242,9 @@ export const makeBy: {
    *
    * **Details**
    *
-   * `n` is normalized to an integer greater than or equal to 1, so this function
-   * always returns at least one element. Supports both data-first and data-last
-   * usage.
+   * `n` is rounded down and normalized to an integer greater than or equal to 1.
+   * `NaN` is treated as `1`, so this function always returns at least one
+   * element. Supports both data-first and data-last usage.
    *
    * **Example** (Generating values from indices)
    *
@@ -260,7 +262,7 @@ export const makeBy: {
    */
   <A>(n: number, f: (i: number) => A): NonEmptyArray<A>
 } = dual(2, <A>(n: number, f: (i: number) => A) => {
-  const max = Math.max(1, Math.floor(n))
+  const max = Count.normalizeNonEmpty(n)
   const out = new Array(max)
   for (let i = 0; i < max; i++) {
     out[i] = f(i)
@@ -1659,13 +1661,23 @@ export const isReadonlyArrayNonEmpty: <A>(self: ReadonlyArray<A>) => self is Non
  */
 export const length = <A>(self: ReadonlyArray<A>): number => self.length
 
+/**
+ * Checks whether a string represents a JavaScript array index: a non-negative
+ * integer below `2 ** 32 - 1`, written without leading zeroes, a sign, or
+ * exponent notation.
+ *
+ * @internal
+ */
+export function isCanonicalArrayIndex(key: string): boolean {
+  const index = Number(key)
+  return String(index) === key && Number.isInteger(index) && index >= 0 && index < 2 ** 32 - 1
+}
+
 /** @internal */
 export function isOutOfBounds<A>(i: number, as: ReadonlyArray<A>): boolean {
   return !Number.isFinite(i) || i < 0 || i >= as.length
 }
 
-const clamp = <A>(i: number, as: ReadonlyArray<A>): number => Math.floor(Math.min(Math.max(0, i), as.length))
-
 /**
  * Reads an element at the given index safely, returning `Option.some` or
  * `Option.none` if the index is out of bounds.
@@ -2124,6 +2136,8 @@ export function init<A>(self: Iterable<A>): Option.Option<Array<A>> {
  */
 export const initNonEmpty = <A>(self: NonEmptyReadonlyArray<A>): Array<A> => self.slice(0, -1)
 
+const clampCount = (n: number, length: number): number => Math.min(Count.normalize(n), length)
+
 /**
  * Keeps the first `n` elements, creating a new array.
  *
@@ -2133,7 +2147,8 @@ export const initNonEmpty = <A>(self: NonEmptyReadonlyArray<A>): Array<A> => sel
  *
  * **Details**
  *
- * `n` is clamped to `[0, length]`. Returns an empty array when `n <= 0`.
+ * `n` is rounded down and clamped to `[0, length]`. `NaN` is treated as `0`.
+ * Returns an empty array when `n <= 0`.
  *
  * **Example** (Taking from the start)
  *
@@ -2160,7 +2175,8 @@ export const take: {
    *
    * **Details**
    *
-   * `n` is clamped to `[0, length]`. Returns an empty array when `n <= 0`.
+   * `n` is rounded down and clamped to `[0, length]`. `NaN` is treated as `0`.
+   * Returns an empty array when `n <= 0`.
    *
    * **Example** (Taking from the start)
    *
@@ -2187,7 +2203,8 @@ export const take: {
    *
    * **Details**
    *
-   * `n` is clamped to `[0, length]`. Returns an empty array when `n <= 0`.
+   * `n` is rounded down and clamped to `[0, length]`. `NaN` is treated as `0`.
+   * Returns an empty array when `n <= 0`.
    *
    * **Example** (Taking from the start)
    *
@@ -2207,7 +2224,7 @@ export const take: {
   <A>(self: Iterable<A>, n: number): Array<A>
 } = dual(2, <A>(self: Iterable<A>, n: number): Array<A> => {
   const input = fromIterable(self)
-  return input.slice(0, clamp(n, input))
+  return input.slice(0, clampCount(n, input.length))
 })
 
 /**
@@ -2219,7 +2236,8 @@ export const take: {
  *
  * **Details**
  *
- * `n` is clamped to `[0, length]`. Returns an empty array when `n <= 0`.
+ * `n` is rounded down and clamped to `[0, length]`. `NaN` is treated as `0`.
+ * Returns an empty array when `n <= 0`.
  *
  * **Example** (Taking from the end)
  *
@@ -2245,7 +2263,8 @@ export const takeRight: {
    *
    * **Details**
    *
-   * `n` is clamped to `[0, length]`. Returns an empty array when `n <= 0`.
+   * `n` is rounded down and clamped to `[0, length]`. `NaN` is treated as `0`.
+   * Returns an empty array when `n <= 0`.
    *
    * **Example** (Taking from the end)
    *
@@ -2271,7 +2290,8 @@ export const takeRight: {
    *
    * **Details**
    *
-   * `n` is clamped to `[0, length]`. Returns an empty array when `n <= 0`.
+   * `n` is rounded down and clamped to `[0, length]`. `NaN` is treated as `0`.
+   * Returns an empty array when `n <= 0`.
    *
    * **Example** (Taking from the end)
    *
@@ -2290,7 +2310,7 @@ export const takeRight: {
   <A>(self: Iterable<A>, n: number): Array<A>
 } = dual(2, <A>(self: Iterable<A>, n: number): Array<A> => {
   const input = fromIterable(self)
-  const i = clamp(n, input)
+  const i = clampCount(n, input.length)
   return i === 0 ? [] : input.slice(-i)
 })
 
@@ -2718,8 +2738,8 @@ export const span: {
  *
  * **Details**
  *
- * `n` is clamped to `[0, length]`. When `n <= 0`, this returns a copy of the
- * full array.
+ * `n` is rounded down and clamped to `[0, length]`. `NaN` is treated as `0`.
+ * When `n <= 0`, this returns a copy of the full array.
  *
  * **Example** (Dropping from the start)
  *
@@ -2747,8 +2767,8 @@ export const drop: {
    *
    * **Details**
    *
-   * `n` is clamped to `[0, length]`. When `n <= 0`, this returns a copy of the
-   * full array.
+   * `n` is rounded down and clamped to `[0, length]`. `NaN` is treated as `0`.
+   * When `n <= 0`, this returns a copy of the full array.
    *
    * **Example** (Dropping from the start)
    *
@@ -2776,8 +2796,8 @@ export const drop: {
    *
    * **Details**
    *
-   * `n` is clamped to `[0, length]`. When `n <= 0`, this returns a copy of the
-   * full array.
+   * `n` is rounded down and clamped to `[0, length]`. `NaN` is treated as `0`.
+   * When `n <= 0`, this returns a copy of the full array.
    *
    * **Example** (Dropping from the start)
    *
@@ -2797,7 +2817,7 @@ export const drop: {
   <A>(self: Iterable<A>, n: number): Array<A>
 } = dual(2, <A>(self: Iterable<A>, n: number): Array<A> => {
   const input = fromIterable(self)
-  return input.slice(clamp(n, input), input.length)
+  return input.slice(clampCount(n, input.length), input.length)
 })
 
 /**
@@ -2809,7 +2829,7 @@ export const drop: {
  *
  * **Details**
  *
- * `n` is clamped to `[0, length]`.
+ * `n` is rounded down and clamped to `[0, length]`. `NaN` is treated as `0`.
  *
  * **Example** (Dropping from the end)
  *
@@ -2835,7 +2855,7 @@ export const dropRight: {
    *
    * **Details**
    *
-   * `n` is clamped to `[0, length]`.
+   * `n` is rounded down and clamped to `[0, length]`. `NaN` is treated as `0`.
    *
    * **Example** (Dropping from the end)
    *
@@ -2861,7 +2881,7 @@ export const dropRight: {
    *
    * **Details**
    *
-   * `n` is clamped to `[0, length]`.
+   * `n` is rounded down and clamped to `[0, length]`. `NaN` is treated as `0`.
    *
    * **Example** (Dropping from the end)
    *
@@ -2880,7 +2900,7 @@ export const dropRight: {
   <A>(self: Iterable<A>, n: number): Array<A>
 } = dual(2, <A>(self: Iterable<A>, n: number): Array<A> => {
   const input = fromIterable(self)
-  return input.slice(0, input.length - clamp(n, input))
+  return input.slice(0, input.length - clampCount(n, input.length))
 })
 
 /**
@@ -5695,8 +5715,8 @@ export const chop: {
  *
  * **Details**
  *
- * `n` can be `0`, in which case all elements are placed in the second array.
- * The index is floored to an integer.
+ * `n` is rounded down and clamped to `[0, length]`. `NaN` is treated as `0`,
+ * which places all elements in the second array.
  *
  * **Example** (Splitting at an index)
  *
@@ -5722,8 +5742,8 @@ export const splitAt: {
    *
    * **Details**
    *
-   * `n` can be `0`, in which case all elements are placed in the second array.
-   * The index is floored to an integer.
+   * `n` is rounded down and clamped to `[0, length]`. `NaN` is treated as `0`,
+   * which places all elements in the second array.
    *
    * **Example** (Splitting at an index)
    *
@@ -5749,8 +5769,8 @@ export const splitAt: {
    *
    * **Details**
    *
-   * `n` can be `0`, in which case all elements are placed in the second array.
-   * The index is floored to an integer.
+   * `n` is rounded down and clamped to `[0, length]`. `NaN` is treated as `0`,
+   * which places all elements in the second array.
    *
    * **Example** (Splitting at an index)
    *
@@ -5769,7 +5789,7 @@ export const splitAt: {
   <A>(self: Iterable<A>, n: number): [beforeIndex: Array<A>, fromIndex: Array<A>]
 } = dual(2, <A>(self: Iterable<A>, n: number): [Array<A>, Array<A>] => {
   const input = Array.from(self)
-  const _n = Math.floor(n)
+  const _n = Count.normalize(n)
   if (isReadonlyArrayNonEmpty(input)) {
     if (_n >= 1) {
       return splitAtNonEmpty(input, _n)
@@ -5788,6 +5808,10 @@ export const splitAt: {
  * Use when downstream code requires the left side of the split to contain at
  * least one element.
  *
+ * **Details**
+ *
+ * `n` is rounded down and clamped to `[1, length]`. `NaN` is treated as `1`.
+ *
  * **Example** (Splitting a non-empty array)
  *
  * ```ts import.meta.vitest
@@ -5811,6 +5835,10 @@ export const splitAtNonEmpty: {
    * Use when downstream code requires the left side of the split to contain at
    * least one element.
    *
+   * **Details**
+   *
+   * `n` is rounded down and clamped to `[1, length]`. `NaN` is treated as `1`.
+   *
    * **Example** (Splitting a non-empty array)
    *
    * ```ts import.meta.vitest
@@ -5834,6 +5862,10 @@ export const splitAtNonEmpty: {
    * Use when downstream code requires the left side of the split to contain at
    * least one element.
    *
+   * **Details**
+   *
+   * `n` is rounded down and clamped to `[1, length]`. `NaN` is treated as `1`.
+   *
    * **Example** (Splitting a non-empty array)
    *
    * ```ts import.meta.vitest
@@ -5849,7 +5881,7 @@ export const splitAtNonEmpty: {
    */
   <A>(self: NonEmptyReadonlyArray<A>, n: number): [beforeIndex: NonEmptyArray<A>, fromIndex: Array<A>]
 } = dual(2, <A>(self: NonEmptyReadonlyArray<A>, n: number): [NonEmptyArray<A>, Array<A>] => {
-  const _n = Math.max(1, Math.floor(n))
+  const _n = Count.normalizeNonEmpty(n)
   return _n >= self.length ?
     [copy(self), []] :
     [prepend(self.slice(1, _n), headNonEmpty(self)), self.slice(_n)]
@@ -5864,7 +5896,8 @@ export const splitAtNonEmpty: {
  *
  * **Details**
  *
- * Uses `chunksOf(ceil(length / n))` internally. The last chunk may be shorter.
+ * `n` is rounded down and normalized to at least `1`, with `NaN` treated as
+ * `1`. The last chunk may be shorter.
  *
  * **Example** (Splitting into groups)
  *
@@ -5889,7 +5922,8 @@ export const split: {
    *
    * **Details**
    *
-   * Uses `chunksOf(ceil(length / n))` internally. The last chunk may be shorter.
+   * `n` is rounded down and normalized to at least `1`, with `NaN` treated as
+   * `1`. The last chunk may be shorter.
    *
    * **Example** (Splitting into groups)
    *
@@ -5914,7 +5948,8 @@ export const split: {
    *
    * **Details**
    *
-   * Uses `chunksOf(ceil(length / n))` internally. The last chunk may be shorter.
+   * `n` is rounded down and normalized to at least `1`, with `NaN` treated as
+   * `1`. The last chunk may be shorter.
    *
    * **Example** (Splitting into groups)
    *
@@ -5932,7 +5967,7 @@ export const split: {
   <A>(self: Iterable<A>, n: number): Array<Array<A>>
 } = dual(2, <A>(self: Iterable<A>, n: number) => {
   const input = fromIterable(self)
-  return chunksOf(input, Math.ceil(input.length / Math.floor(n)))
+  return chunksOf(input, Math.ceil(input.length / Count.normalizeNonEmpty(n)))
 })
 
 /**
@@ -6118,7 +6153,8 @@ export const copy: {
  *
  * **Details**
  *
- * Returns an empty array when `n <= 0`.
+ * `n` is rounded down. `NaN` and non-positive values are treated as `0`, which
+ * returns an empty array.
  *
  * **Example** (Padding an array)
  *
@@ -6145,7 +6181,8 @@ export const pad: {
    *
    * **Details**
    *
-   * Returns an empty array when `n <= 0`.
+   * `n` is rounded down. `NaN` and non-positive values are treated as `0`, which
+   * returns an empty array.
    *
    * **Example** (Padding an array)
    *
@@ -6174,7 +6211,8 @@ export const pad: {
    *
    * **Details**
    *
-   * Returns an empty array when `n <= 0`.
+   * `n` is rounded down. `NaN` and non-positive values are treated as `0`, which
+   * returns an empty array.
    *
    * **Example** (Padding an array)
    *
@@ -6192,12 +6230,13 @@ export const pad: {
    */
   <A, T>(self: Array<A>, n: number, fill: T): Array<A | T>
 } = dual(3, <A, T>(self: Array<A>, n: number, fill: T): Array<A | T> => {
-  if (self.length >= n) {
-    return take(self, n)
+  const length = Count.normalize(n)
+  if (self.length >= length) {
+    return take(self, length)
   }
   return appendAll(
     self,
-    makeBy(n - self.length, () => fill)
+    makeBy(length - self.length, () => fill)
   )
 })
 
@@ -6212,8 +6251,10 @@ export const pad: {
  *
  * **Details**
  *
- * `chunksOf(n)([])` is `[]`, not `[[]]`. Each chunk is a `NonEmptyArray`, and
- * the outer return type preserves `NonEmptyArray`.
+ * `n` is rounded down and normalized to at least `1`; `NaN` and non-positive
+ * values therefore produce singleton chunks. `chunksOf(n)([])` is `[]`, not
+ * `[[]]`. Each chunk is a `NonEmptyArray`, and the outer return type preserves
+ * `NonEmptyArray`.
  *
  * **Example** (Chunking an array)
  *
@@ -6241,8 +6282,10 @@ export const chunksOf: {
    *
    * **Details**
    *
-   * `chunksOf(n)([])` is `[]`, not `[[]]`. Each chunk is a `NonEmptyArray`, and
-   * the outer return type preserves `NonEmptyArray`.
+   * `n` is rounded down and normalized to at least `1`; `NaN` and non-positive
+   * values therefore produce singleton chunks. `chunksOf(n)([])` is `[]`, not
+   * `[[]]`. Each chunk is a `NonEmptyArray`, and the outer return type preserves
+   * `NonEmptyArray`.
    *
    * **Example** (Chunking an array)
    *
@@ -6272,8 +6315,10 @@ export const chunksOf: {
    *
    * **Details**
    *
-   * `chunksOf(n)([])` is `[]`, not `[[]]`. Each chunk is a `NonEmptyArray`, and
-   * the outer return type preserves `NonEmptyArray`.
+   * `n` is rounded down and normalized to at least `1`; `NaN` and non-positive
+   * values therefore produce singleton chunks. `chunksOf(n)([])` is `[]`, not
+   * `[[]]`. Each chunk is a `NonEmptyArray`, and the outer return type preserves
+   * `NonEmptyArray`.
    *
    * **Example** (Chunking an array)
    *
@@ -6301,8 +6346,10 @@ export const chunksOf: {
    *
    * **Details**
    *
-   * `chunksOf(n)([])` is `[]`, not `[[]]`. Each chunk is a `NonEmptyArray`, and
-   * the outer return type preserves `NonEmptyArray`.
+   * `n` is rounded down and normalized to at least `1`; `NaN` and non-positive
+   * values therefore produce singleton chunks. `chunksOf(n)([])` is `[]`, not
+   * `[[]]`. Each chunk is a `NonEmptyArray`, and the outer return type preserves
+   * `NonEmptyArray`.
    *
    * **Example** (Chunking an array)
    *
@@ -6336,8 +6383,9 @@ export const chunksOf: {
  *
  * **Details**
  *
- * Returns an empty array if `n <= 0` or the array has fewer than `n` elements.
- * Each window is a tuple of exactly `n` elements.
+ * `n` is rounded down, with `NaN` and non-positive values treated as `0`.
+ * Returns an empty array if the normalized size is `0` or exceeds the array
+ * length. Each window is a tuple of exactly the normalized size.
  *
  * **Example** (Creating sliding windows)
  *
@@ -6365,8 +6413,9 @@ export const window: {
    *
    * **Details**
    *
-   * Returns an empty array if `n <= 0` or the array has fewer than `n` elements.
-   * Each window is a tuple of exactly `n` elements.
+   * `n` is rounded down, with `NaN` and non-positive values treated as `0`.
+   * Returns an empty array if the normalized size is `0` or exceeds the array
+   * length. Each window is a tuple of exactly the normalized size.
    *
    * **Example** (Creating sliding windows)
    *
@@ -6394,8 +6443,9 @@ export const window: {
    *
    * **Details**
    *
-   * Returns an empty array if `n <= 0` or the array has fewer than `n` elements.
-   * Each window is a tuple of exactly `n` elements.
+   * `n` is rounded down, with `NaN` and non-positive values treated as `0`.
+   * Returns an empty array if the normalized size is `0` or exceeds the array
+   * length. Each window is a tuple of exactly the normalized size.
    *
    * **Example** (Creating sliding windows)
    *
@@ -6416,10 +6466,11 @@ export const window: {
   <A, N extends number>(self: Iterable<A>, n: N): Array<TupleOf<N, A>>
 } = dual(2, <A>(self: Iterable<A>, n: number): Array<Array<A>> => {
   const input = fromIterable(self)
-  if (n > 0 && isReadonlyArrayNonEmpty(input)) {
+  const size = Count.normalize(n)
+  if (size > 0 && size <= input.length && isReadonlyArrayNonEmpty(input)) {
     return Array.from(
-      { length: input.length - (n - 1) },
-      (_, index) => input.slice(index, index + n)
+      { length: input.length - (size - 1) },
+      (_, index) => input.slice(index, index + size)
     )
   }
   return []
@@ -6583,6 +6634,13 @@ export const group: <A>(self: NonEmptyReadonlyArray<A>) => NonEmptyArray<NonEmpt
  * Unlike `group` and `groupWith`, elements do not need to be adjacent to be
  * grouped together. The key function must return a `string` or `symbol`.
  *
+ * **Gotchas**
+ *
+ * When the key function returns a finite union of string literals or unique
+ * symbols, the result preserves those keys as optional properties because the
+ * input may not produce every key. Open `string` and `symbol` key types retain
+ * their record index signatures.
+ *
  * **Example** (Grouping by a property)
  *
  * ```ts import.meta.vitest
@@ -6617,6 +6675,13 @@ export const groupBy: {
    * Unlike `group` and `groupWith`, elements do not need to be adjacent to be
    * grouped together. The key function must return a `string` or `symbol`.
    *
+   * **Gotchas**
+   *
+   * When the key function returns a finite union of string literals or unique
+   * symbols, the result preserves those keys as optional properties because the
+   * input may not produce every key. Open `string` and `symbol` key types retain
+   * their record index signatures.
+   *
    * **Example** (Grouping by a property)
    *
    * ```ts import.meta.vitest
@@ -6637,7 +6702,7 @@ export const groupBy: {
    * @category grouping
    * @since 2.0.0
    */
-  <A, K extends string | symbol>(f: (a: A) => K): (self: Iterable<A>) => Record<Record.ReadonlyRecord.NonLiteralKey<K>, NonEmptyArray<A>>
+  <A, K extends string | symbol>(f: (a: A) => K): (self: Iterable<A>) => Record.ReadonlyRecord.GroupByResult<K, NonEmptyArray<A>>
   /**
    * Groups elements into a record by a key-returning function. Each key maps
    * to a `NonEmptyArray` of elements that produced that key.
@@ -6651,6 +6716,13 @@ export const groupBy: {
    * Unlike `group` and `groupWith`, elements do not need to be adjacent to be
    * grouped together. The key function must return a `string` or `symbol`.
    *
+   * **Gotchas**
+   *
+   * When the key function returns a finite union of string literals or unique
+   * symbols, the result preserves those keys as optional properties because the
+   * input may not produce every key. Open `string` and `symbol` key types retain
+   * their record index signatures.
+   *
    * **Example** (Grouping by a property)
    *
    * ```ts import.meta.vitest
@@ -6671,11 +6743,11 @@ export const groupBy: {
    * @category grouping
    * @since 2.0.0
    */
-  <A, K extends string | symbol>(self: Iterable<A>, f: (a: A) => K): Record<Record.ReadonlyRecord.NonLiteralKey<K>, NonEmptyArray<A>>
+  <A, K extends string | symbol>(self: Iterable<A>, f: (a: A) => K): Record.ReadonlyRecord.GroupByResult<K, NonEmptyArray<A>>
 } = dual(2, <A, K extends string | symbol>(
   self: Iterable<A>,
   f: (a: A) => K
-): Record<Record.ReadonlyRecord.NonLiteralKey<K>, NonEmptyArray<A>> => {
+): Record.ReadonlyRecord.GroupByResult<K, NonEmptyArray<A>> => {
   const out: Record<string | symbol, NonEmptyArray<A>> = {}
   for (const a of self) {
     const k = f(a)