effect 2.0.0-next.55 → 2.0.0-next.57

package/dist/esm/ReadonlyArray.js

@@ -11,6 +11,7 @@ import * as readonlyArray from "./internal/readonlyArray.js";
 import * as O from "./Option.js";
 import * as Order from "./Order.js";
 import * as RR from "./ReadonlyRecord.js";
+import * as Tuple from "./Tuple.js";
 /**
  * Builds a `NonEmptyArray` from an non-empty collection of elements.
  *
@@ -122,15 +123,21 @@ export const matchRight = /*#__PURE__*/dual(2, (self, {
  */
 export const prepend = /*#__PURE__*/dual(2, (self, head) => [head, ...self]);
 /**
+ * Prepends the specified prefix array (or iterable) to the beginning of the specified array (or iterable).
+ * If either array is non-empty, the result is also a non-empty array.
+ *
+ * @example
+ * import * as ReadonlyArray from "effect/ReadonlyArray"
+ *
+ * assert.deepStrictEqual(
+ *   ReadonlyArray.prependAll([1, 2], ["a", "b"]),
+ *   ["a", "b", 1, 2]
+ * )
+ *
  * @category concatenating
  * @since 2.0.0
  */
 export const prependAll = /*#__PURE__*/dual(2, (self, that) => fromIterable(that).concat(fromIterable(self)));
-/**
- * @category concatenating
- * @since 2.0.0
- */
-export const prependAllNonEmpty = /*#__PURE__*/dual(2, (self, that) => prependAll(self, that));
 /**
  * Append an element to the end of an `Iterable`, creating a new `NonEmptyArray`.
  *
@@ -139,15 +146,13 @@ export const prependAllNonEmpty = /*#__PURE__*/dual(2, (self, that) => prependAl
  */
 export const append = /*#__PURE__*/dual(2, (self, last) => [...self, last]);
 /**
+ * Concatenates two arrays (or iterables), combining their elements.
+ * If either array is non-empty, the result is also a non-empty array.
+ *
  * @category concatenating
  * @since 2.0.0
  */
 export const appendAll = /*#__PURE__*/dual(2, (self, that) => fromIterable(self).concat(fromIterable(that)));
-/**
- * @category concatenating
- * @since 2.0.0
- */
-export const appendAllNonEmpty = /*#__PURE__*/dual(2, (self, that) => appendAll(self, that));
 /**
  * Reduce an `Iterable` from the left, keeping all intermediate results instead of only the final result.
  *
@@ -569,12 +574,8 @@ export const remove = /*#__PURE__*/dual(2, (self, i) => {
  */
 export const reverse = self => Array.from(self).reverse();
 /**
- * @category elements
- * @since 2.0.0
- */
-export const reverseNonEmpty = self => [lastNonEmpty(self), ...self.slice(0, -1).reverse()];
-/**
- * Sort the elements of an `Iterable` in increasing order, creating a new `Array`.
+ * Create a new array with elements sorted in increasing order based on the specified comparator.
+ * If the input is a `NonEmptyReadonlyArray`, the output will also be a `NonEmptyReadonlyArray`.
  *
  * @category sorting
  * @since 2.0.0
@@ -589,13 +590,6 @@ export const sort = /*#__PURE__*/dual(2, (self, O) => {
  * @category elements
  */
 export const sortWith = /*#__PURE__*/dual(3, (self, f, order) => sort(self, Order.mapInput(order, f)));
-/**
- * Sort the elements of a `NonEmptyReadonlyArray` in increasing order, creating a new `NonEmptyArray`.
- *
- * @category sorting
- * @since 2.0.0
- */
-export const sortNonEmpty = /*#__PURE__*/dual(2, (self, O) => sort(O)(self));
 /**
  * Sort the elements of an `Iterable` in increasing order, where elements are compared
  * using first `orders[0]`, then `orders[1]`, etc...
@@ -603,48 +597,44 @@ export const sortNonEmpty = /*#__PURE__*/dual(2, (self, O) => sort(O)(self));
  * @category sorting
  * @since 2.0.0
  */
-export const sortBy = (...orders) => self => {
-  const input = fromIterable(self);
-  return isNonEmptyReadonlyArray(input) ? sortByNonEmpty(...orders)(input) : [];
+export const sortBy = (...orders) => {
+  const sortByAll = sort(Order.combineAll(orders));
+  return self => {
+    const input = fromIterable(self);
+    if (isNonEmptyReadonlyArray(input)) {
+      return sortByAll(input);
+    }
+    return [];
+  };
 };
-/**
- * @category sorting
- * @since 2.0.0
- */
-export const sortByNonEmpty = (...orders) => sortNonEmpty(Order.combineAll(orders));
 /**
  * Takes two `Iterable`s and returns an `Array` of corresponding pairs.
  * If one input `Iterable` is short, excess elements of the
  * longer `Iterable` are discarded.
  *
+ * @category zipping
  * @since 2.0.0
  */
-export const zip = /*#__PURE__*/dual(2, (self, that) => zipWith(self, that, (a, b) => [a, b]));
+export const zip = /*#__PURE__*/dual(2, (self, that) => zipWith(self, that, Tuple.make));
 /**
  * Apply a function to pairs of elements at the same index in two `Iterable`s, collecting the results in a new `Array`. If one
  * input `Iterable` is short, excess elements of the longer `Iterable` are discarded.
  *
+ * @category zipping
  * @since 2.0.0
  */
 export const zipWith = /*#__PURE__*/dual(3, (self, that, f) => {
   const as = fromIterable(self);
   const bs = fromIterable(that);
-  return isNonEmptyReadonlyArray(as) && isNonEmptyReadonlyArray(bs) ? zipNonEmptyWith(bs, f)(as) : [];
-});
-/**
- * @since 2.0.0
- */
-export const zipNonEmpty = /*#__PURE__*/dual(2, (self, that) => zipNonEmptyWith(self, that, (a, b) => [a, b]));
-/**
- * @since 2.0.0
- */
-export const zipNonEmptyWith = /*#__PURE__*/dual(3, (self, that, f) => {
-  const cs = [f(headNonEmpty(self), headNonEmpty(that))];
-  const len = Math.min(self.length, that.length);
-  for (let i = 1; i < len; i++) {
-    cs[i] = f(self[i], that[i]);
+  if (isNonEmptyReadonlyArray(as) && isNonEmptyReadonlyArray(bs)) {
+    const out = [f(headNonEmpty(as), headNonEmpty(bs))];
+    const len = Math.min(as.length, bs.length);
+    for (let i = 1; i < len; i++) {
+      out[i] = f(as[i], bs[i]);
+    }
+    return out;
   }
-  return cs;
+  return [];
 });
 /**
  * This function is the inverse of `zip`. Takes an `Iterable` of pairs and return two corresponding `Array`s.
@@ -653,44 +643,37 @@ export const zipNonEmptyWith = /*#__PURE__*/dual(3, (self, that, f) => {
  */
 export const unzip = self => {
   const input = fromIterable(self);
-  return isNonEmptyReadonlyArray(input) ? unzipNonEmpty(input) : [[], []];
-};
-/**
- * @since 2.0.0
- */
-export const unzipNonEmpty = self => {
-  const fa = [self[0][0]];
-  const fb = [self[0][1]];
-  for (let i = 1; i < self.length; i++) {
-    fa[i] = self[i][0];
-    fb[i] = self[i][1];
+  if (isNonEmptyReadonlyArray(input)) {
+    const fa = [input[0][0]];
+    const fb = [input[0][1]];
+    for (let i = 1; i < input.length; i++) {
+      fa[i] = input[i][0];
+      fb[i] = input[i][1];
+    }
+    return [fa, fb];
   }
-  return [fa, fb];
+  return [[], []];
 };
 /**
- * Places an element in between members of an `Iterable`
+ * Places an element in between members of an `Iterable`.
+ * If the input is a non-empty array, the result is also a non-empty array.
  *
  * @since 2.0.0
  */
 export const intersperse = /*#__PURE__*/dual(2, (self, middle) => {
   const input = fromIterable(self);
-  return isNonEmptyReadonlyArray(input) ? intersperseNonEmpty(input, middle) : [];
-});
-/**
- * Places an element in between members of a `NonEmptyReadonlyArray`
- *
- * @since 2.0.0
- */
-export const intersperseNonEmpty = /*#__PURE__*/dual(2, (self, middle) => {
-  const out = [headNonEmpty(self)];
-  const tail = tailNonEmpty(self);
-  for (let i = 0; i < tail.length; i++) {
-    if (i < tail.length) {
-      out.push(middle);
+  if (isNonEmptyReadonlyArray(input)) {
+    const out = [headNonEmpty(input)];
+    const tail = tailNonEmpty(input);
+    for (let i = 0; i < tail.length; i++) {
+      if (i < tail.length) {
+        out.push(middle);
+      }
+      out.push(tail[i]);
     }
-    out.push(tail[i]);
+    return out;
   }
-  return out;
+  return [];
 });
 /**
  * Apply a function to the head, creating a new `NonEmptyReadonlyArray`.
@@ -718,30 +701,26 @@ export const modifyNonEmptyLast = /*#__PURE__*/dual(2, (self, f) => append(initN
 export const setNonEmptyLast = /*#__PURE__*/dual(2, (self, b) => modifyNonEmptyLast(self, () => b));
 /**
  * Rotate an `Iterable` by `n` steps.
+ * If the input is a non-empty array, the result is also a non-empty array.
  *
  * @since 2.0.0
  */
 export const rotate = /*#__PURE__*/dual(2, (self, n) => {
   const input = fromIterable(self);
-  return isNonEmptyReadonlyArray(input) ? rotateNonEmpty(input, n) : [];
-});
-/**
- * Rotate a `NonEmptyReadonlyArray` by `n` steps.
- *
- * @since 2.0.0
- */
-export const rotateNonEmpty = /*#__PURE__*/dual(2, (self, n) => {
-  const len = self.length;
-  const m = Math.round(n) % len;
-  if (isOutOfBound(Math.abs(m), self) || m === 0) {
-    return copy(self);
-  }
-  if (m < 0) {
-    const [f, s] = splitNonEmptyAt(self, -m);
-    return appendAllNonEmpty(s, f);
-  } else {
-    return rotateNonEmpty(self, m - len);
+  if (isNonEmptyReadonlyArray(input)) {
+    const len = input.length;
+    const m = Math.round(n) % len;
+    if (isOutOfBound(Math.abs(m), input) || m === 0) {
+      return copy(input);
+    }
+    if (m < 0) {
+      const [f, s] = splitNonEmptyAt(input, -m);
+      return appendAll(s, f);
+    } else {
+      return rotate(self, m - len);
+    }
   }
+  return [];
 });
 /**
  * Returns a function that checks if a `ReadonlyArray` contains a given value using a provided `isEquivalent` function.
@@ -765,27 +744,6 @@ const _equivalence = /*#__PURE__*/Equal.equivalence();
  * @since 2.0.0
  */
 export const contains = /*#__PURE__*/containsWith(_equivalence);
-/**
- * Remove duplicates from a `NonEmptyReadonlyArray`, keeping the first occurrence of an element using the provided `isEquivalent` function.
- *
- * @since 2.0.0
- */
-export const dedupeNonEmptyWith = /*#__PURE__*/dual(2, (self, isEquivalent) => {
-  const out = [headNonEmpty(self)];
-  const rest = tailNonEmpty(self);
-  for (const a of rest) {
-    if (out.every(o => !isEquivalent(a, o))) {
-      out.push(a);
-    }
-  }
-  return out;
-});
-/**
- * Remove duplicates from a `NonEmptyReadonlyArray`, keeping the first occurrence of an element.
- *
- * @since 2.0.0
- */
-export const dedupeNonEmpty = /*#__PURE__*/dedupeNonEmptyWith( /*#__PURE__*/Equal.equivalence());
 /**
  * A useful recursion pattern for processing an `Iterable` to produce a new `Array`, often used for "chopping" up the input
  * `Iterable`. Typically chop is called with some function that will consume an initial prefix of the `Iterable` and produce a
@@ -795,49 +753,51 @@ export const dedupeNonEmpty = /*#__PURE__*/dedupeNonEmptyWith( /*#__PURE__*/Equa
  */
 export const chop = /*#__PURE__*/dual(2, (self, f) => {
   const input = fromIterable(self);
-  return isNonEmptyReadonlyArray(input) ? chopNonEmpty(input, f) : [];
-});
-/**
- * A useful recursion pattern for processing a `NonEmptyReadonlyArray` to produce a new `NonEmptyReadonlyArray`, often used for "chopping" up the input
- * `NonEmptyReadonlyArray`. Typically `chop` is called with some function that will consume an initial prefix of the `NonEmptyReadonlyArray` and produce a
- * value and the tail of the `NonEmptyReadonlyArray`.
- *
- * @since 2.0.0
- */
-export const chopNonEmpty = /*#__PURE__*/dual(2, (self, f) => {
-  const [b, rest] = f(self);
-  const out = [b];
-  let next = rest;
-  while (readonlyArray.isNonEmptyArray(next)) {
-    const [b, rest] = f(next);
-    out.push(b);
-    next = rest;
+  if (isNonEmptyReadonlyArray(input)) {
+    const [b, rest] = f(input);
+    const out = [b];
+    let next = rest;
+    while (readonlyArray.isNonEmptyArray(next)) {
+      const [b, rest] = f(next);
+      out.push(b);
+      next = rest;
+    }
+    return out;
   }
-  return out;
+  return [];
 });
 /**
- * Splits an `Iterable` into two pieces, the first piece has max `n` elements.
+ * Splits an `Iterable` into two segments, with the first segment containing a maximum of `n` elements.
+ * The value of `n` can be `0`.
  *
  * @category getters
  * @since 2.0.0
  */
 export const splitAt = /*#__PURE__*/dual(2, (self, n) => {
   const input = Array.from(self);
-  return n >= 1 && isNonEmptyReadonlyArray(input) ? splitNonEmptyAt(input, n) : isEmptyReadonlyArray(input) ? [input, []] : [[], input];
+  const _n = Math.floor(n);
+  if (isNonEmptyReadonlyArray(input)) {
+    if (_n >= 1) {
+      return splitNonEmptyAt(input, _n);
+    }
+    return [[], input];
+  }
+  return [input, []];
 });
 /**
  * @since 2.0.0
  */
 export const copy = self => self.slice();
 /**
- * Splits a `NonEmptyReadonlyArray` into two pieces, the first piece has max `n` elements.
+ * Splits a `NonEmptyReadonlyArray` into two segments, with the first segment containing a maximum of `n` elements.
+ * The value of `n` must be `>= 1`.
  *
  * @category getters
  * @since 2.0.0
  */
 export const splitNonEmptyAt = /*#__PURE__*/dual(2, (self, n) => {
-  const m = Math.max(1, n);
-  return m >= self.length ? [copy(self), []] : [prepend(self.slice(1, m), headNonEmpty(self)), self.slice(m)];
+  const _n = Math.max(1, Math.floor(n));
+  return _n >= self.length ? [copy(self), []] : [prepend(self.slice(1, _n), headNonEmpty(self)), self.slice(_n)];
 });
 /**
  * Splits an `Iterable` into length-`n` pieces. The last piece will be shorter if `n` does not evenly divide the length of
@@ -855,23 +815,18 @@ export const splitNonEmptyAt = /*#__PURE__*/dual(2, (self, n) => {
  */
 export const chunksOf = /*#__PURE__*/dual(2, (self, n) => {
   const input = fromIterable(self);
-  return isNonEmptyReadonlyArray(input) ? chunksOfNonEmpty(input, n) : [];
+  if (isNonEmptyReadonlyArray(input)) {
+    return chop(input, splitNonEmptyAt(n));
+  }
+  return [];
 });
-/**
- * Splits a `NonEmptyReadonlyArray` into length-`n` pieces. The last piece will be shorter if `n` does not evenly divide the length of
- * the `NonEmptyReadonlyArray`.
- *
- * @category getters
- * @since 2.0.0
- */
-export const chunksOfNonEmpty = /*#__PURE__*/dual(2, (self, n) => chopNonEmpty(self, splitNonEmptyAt(n)));
 /**
  * Group equal, consecutive elements of a `NonEmptyReadonlyArray` into `NonEmptyArray`s using the provided `isEquivalent` function.
  *
  * @category grouping
  * @since 2.0.0
  */
-export const groupWith = /*#__PURE__*/dual(2, (self, isEquivalent) => chopNonEmpty(self, as => {
+export const groupWith = /*#__PURE__*/dual(2, (self, isEquivalent) => chop(self, as => {
   const h = headNonEmpty(as);
   const out = [h];
   let i = 1;
@@ -914,26 +869,22 @@ export const groupBy = /*#__PURE__*/dual(2, (self, f) => {
 /**
  * @since 2.0.0
  */
-export const unionWith = isEquivalent => dual(2, (self, that) => {
+export const unionWith = /*#__PURE__*/dual(3, (self, that, isEquivalent) => {
   const a = fromIterable(self);
   const b = fromIterable(that);
-  return isNonEmptyReadonlyArray(a) && isNonEmptyReadonlyArray(b) ? unionNonEmptyWith(isEquivalent)(a, b) : isNonEmptyReadonlyArray(a) ? a : b;
+  if (isNonEmptyReadonlyArray(a)) {
+    if (isNonEmptyReadonlyArray(b)) {
+      const dedupe = dedupeWith(isEquivalent);
+      return dedupe(appendAll(a, b));
+    }
+    return a;
+  }
+  return b;
 });
 /**
  * @since 2.0.0
  */
-export const union = /*#__PURE__*/unionWith(_equivalence);
-/**
- * @since 2.0.0
- */
-export const unionNonEmptyWith = isEquivalent => {
-  const dedupe = dedupeNonEmptyWith(isEquivalent);
-  return dual(2, (self, that) => dedupe(appendAllNonEmpty(self, that)));
-};
-/**
- * @since 2.0.0
- */
-export const unionNonEmpty = /*#__PURE__*/unionNonEmptyWith(_equivalence);
+export const union = /*#__PURE__*/dual(2, (self, that) => unionWith(self, that, _equivalence));
 /**
  * Creates an `Array` of unique values that are included in all given `Iterable`s using the provided `isEquivalent` function.
  * The order and references of result values are determined by the first `Iterable`.
@@ -962,7 +913,7 @@ export const differenceWith = isEquivalent => {
   return dual(2, (self, that) => fromIterable(self).filter(a => !has(that, a)));
 };
 /**
- * Creates a `Array` of values not included in the other given `Iterable` using the provided `isEquivalent` function.
+ * Creates a `Array` of values not included in the other given `Iterable`.
  * The order and references of result values are determined by the first `Iterable`.
  *
  * @since 2.0.0
@@ -986,6 +937,8 @@ export const of = a => [a];
  */
 export const map = /*#__PURE__*/dual(2, (self, f) => self.map(f));
 /**
+ * Applies a function to each element in an array and returns a new array containing the concatenated mapped elements.
+ *
  * @category sequencing
  * @since 2.0.0
  */
@@ -1000,20 +953,12 @@ export const flatMap = /*#__PURE__*/dual(2, (self, f) => {
   return out;
 });
 /**
- * @category sequencing
- * @since 2.0.0
- */
-export const flatMapNonEmpty = flatMap;
-/**
+ * Flattens an array of arrays into a single array by concatenating all arrays.
+ *
  * @category sequencing
  * @since 2.0.0
  */
 export const flatten = /*#__PURE__*/flatMap(identity);
-/**
- * @category sequencing
- * @since 2.0.0
- */
-export const flattenNonEmpty = /*#__PURE__*/flatMapNonEmpty(identity);
 /**
  * @category filtering
  * @since 2.0.0
@@ -1066,10 +1011,69 @@ export const partitionMap = /*#__PURE__*/dual(2, (self, f) => {
   return [left, right];
 });
 /**
+ * Retrieves the `Some` values from an `Iterable` of `Option`s, collecting them into an array.
+ *
+ * @example
+ * import { getSomes } from "effect/ReadonlyArray"
+ * import { some, none } from "effect/Option"
+ *
+ * assert.deepStrictEqual(
+ *   getSomes([some(1), none(), some(2)]),
+ *   [1, 2]
+ * )
+ *
+ * @category filtering
+ * @since 2.0.0
+ */
+export const getSomes = /*#__PURE__*/filterMap(identity);
+/**
+ * Retrieves the `Left` values from an `Iterable` of `Either`s, collecting them into an array.
+ *
+ * @example
+ * import { getLefts } from "effect/ReadonlyArray"
+ * import { right, left } from "effect/Either"
+ *
+ * assert.deepStrictEqual(
+ *   getLefts([right(1), left("err"), right(2)]),
+ *   ["err"]
+ * )
+ *
+ * @category filtering
+ * @since 2.0.0
+ */
+export const getLefts = self => {
+  const out = [];
+  for (const a of self) {
+    if (E.isLeft(a)) {
+      out.push(a.left);
+    }
+  }
+  return out;
+};
+/**
+ * Retrieves the `Right` values from an `Iterable` of `Either`s, collecting them into an array.
+ *
+ * @example
+ * import { getRights } from "effect/ReadonlyArray"
+ * import { right, left } from "effect/Either"
+ *
+ * assert.deepStrictEqual(
+ *   getRights([right(1), left("err"), right(2)]),
+ *   [1, 2]
+ * )
+ *
  * @category filtering
  * @since 2.0.0
  */
-export const compact = /*#__PURE__*/filterMap(identity);
+export const getRights = self => {
+  const out = [];
+  for (const a of self) {
+    if (E.isRight(a)) {
+      out.push(a.right);
+    }
+  }
+  return out;
+};
 /**
  * @category filtering
  * @since 2.0.0
@@ -1085,6 +1089,8 @@ export const filter = /*#__PURE__*/dual(2, (self, predicate) => {
   return out;
 });
 /**
+ * Separate elements based on a predicate that also exposes the index of the element.
+ *
  * @category filtering
  * @since 2.0.0
  */
@@ -1137,7 +1143,7 @@ export const fromNullable = a => a == null ? empty() : [a];
  */
 export const liftNullable = f => (...a) => fromNullable(f(...a));
 /**
- * @category combining
+ * @category sequencing
  * @since 2.0.0
  */
 export const flatMapNullable = /*#__PURE__*/dual(2, (self, f) => isNonEmptyReadonlyArray(self) ? fromNullable(f(headNonEmpty(self))) : empty());
@@ -1212,16 +1218,28 @@ export const getEquivalence = Equivalence.array;
  */
 export const forEach = /*#__PURE__*/dual(2, (self, f) => fromIterable(self).forEach((a, i) => f(a, i)));
 /**
- * Remove duplicates from am `Iterable` using the provided `isEquivalent` function, keeping the first occurrence of an element.
+ * Remove duplicates from an `Iterable` using the provided `isEquivalent` function,
+ * preserving the order of the first occurrence of each element.
  *
  * @since 2.0.0
  */
 export const dedupeWith = /*#__PURE__*/dual(2, (self, isEquivalent) => {
   const input = fromIterable(self);
-  return isNonEmptyReadonlyArray(input) ? dedupeNonEmptyWith(isEquivalent)(input) : [];
+  if (isNonEmptyReadonlyArray(input)) {
+    const out = [headNonEmpty(input)];
+    const rest = tailNonEmpty(input);
+    for (const r of rest) {
+      if (out.every(a => !isEquivalent(r, a))) {
+        out.push(r);
+      }
+    }
+    return out;
+  }
+  return [];
 });
 /**
- * Remove duplicates from am `Iterable`, keeping the first occurrence of an element.
+ * Remove duplicates from an `Iterable`, preserving the order of the first occurrence of each element.
+ * The equivalence used to compare elements is provided by `Equal.equivalence()` from the `Equal` module.
  *
  * @since 2.0.0
  */