effect 4.0.5 → 4.0.7

package/src/Array.ts

@@ -5735,7 +5735,7 @@ export const rotate: {
  * **When to use**
  *
  * Use when checking membership with caller-provided equality instead of
- * `Equal.equivalence()`.
+ * `Equal.asEquivalence()`.
  *
  * **Example** (Checking with custom equality)
  *
@@ -5747,7 +5747,7 @@ export const rotate: {
  * pipe([1, 2, 3, 4], containsNumber(3)) // => true
  * ```
  *
- * @see {@link contains} for the `Equal.equivalence()` variant
+ * @see {@link contains} for the `Equal.asEquivalence()` variant
  *
  * @stability stable
  * @category predicates
@@ -5767,7 +5767,7 @@ export const containsWith = <A>(isEquivalent: (self: A, that: A) => boolean): {
   })
 
 /**
- * Checks whether an array contains a value, using `Equal.equivalence()` for
+ * Checks whether an array contains a value, using `Equal.asEquivalence()` for
  * comparison.
  *
  * **When to use**
@@ -5791,7 +5791,7 @@ export const containsWith = <A>(isEquivalent: (self: A, that: A) => boolean): {
  */
 export const contains: {
   /**
-   * Checks whether an array contains a value, using `Equal.equivalence()` for
+   * Checks whether an array contains a value, using `Equal.asEquivalence()` for
    * comparison.
    *
    * **When to use**
@@ -5815,7 +5815,7 @@ export const contains: {
    */
   <A>(a: A): (self: Iterable<A>) => boolean
   /**
-   * Checks whether an array contains a value, using `Equal.equivalence()` for
+   * Checks whether an array contains a value, using `Equal.asEquivalence()` for
    * comparison.
    *
    * **When to use**
@@ -6806,7 +6806,7 @@ export const window: {
  * ) // => [["a", "a"], ["b", "b", "b"], ["c"], ["a"]]
  * ```
  *
- * @see {@link group} for grouping adjacent elements with `Equal.equivalence()`
+ * @see {@link group} for grouping adjacent elements with `Equal.asEquivalence()`
  * @see {@link groupBy} for grouping all elements into a record by key, regardless of adjacency
  *
  * @stability stable
@@ -6838,7 +6838,7 @@ export const groupWith: {
    * ) // => [["a", "a"], ["b", "b", "b"], ["c"], ["a"]]
    * ```
    *
-   * @see {@link group} for grouping adjacent elements with `Equal.equivalence()`
+   * @see {@link group} for grouping adjacent elements with `Equal.asEquivalence()`
    * @see {@link groupBy} for grouping all elements into a record by key, regardless of adjacency
    *
    * @stability stable
@@ -6870,7 +6870,7 @@ export const groupWith: {
    * ) // => [["a", "a"], ["b", "b", "b"], ["c"], ["a"]]
    * ```
    *
-   * @see {@link group} for grouping adjacent elements with `Equal.equivalence()`
+   * @see {@link group} for grouping adjacent elements with `Equal.asEquivalence()`
    * @see {@link groupBy} for grouping all elements into a record by key, regardless of adjacency
    *
    * @stability stable
@@ -6901,7 +6901,7 @@ export const groupWith: {
 )
 
 /**
- * Groups consecutive equal elements using `Equal.equivalence()`.
+ * Groups consecutive equal elements using `Equal.asEquivalence()`.
  *
  * **When to use**
  *
@@ -7114,13 +7114,22 @@ const hashBucketsHas = (buckets: HashBuckets, value: unknown): boolean => {
 }
 
 /**
- * Computes the union of two arrays using a custom equivalence, removing
- * duplicates.
+ * Computes the union of two iterables using a custom equivalence.
  *
  * **When to use**
  *
  * Use when you need the union of two arrays but duplicate detection must use a
- * custom equivalence instead of the default `Equal.equivalence()`.
+ * custom equivalence instead of the default `Equal.asEquivalence()`.
+ *
+ * **Details**
+ *
+ * Keeps the elements of `self`, then appends elements of `that` that have no
+ * equivalent in `self`. Calls `isEquivalent` with an element from `self` first
+ * and an element from `that` second.
+ *
+ * **Gotchas**
+ *
+ * Each input must already be deduplicated.
  *
  * **Example** (Computing unions with custom equality)
  *
@@ -7130,7 +7139,7 @@ const hashBucketsHas = (buckets: HashBuckets, value: unknown): boolean => {
  * Array.unionWith([1, 2], [2, 3], (a, b) => a === b) // => [1, 2, 3]
  * ```
  *
- * @see {@link union} for the `Equal.equivalence()` variant
+ * @see {@link union} for the `Equal.asEquivalence()` variant
  * @see {@link intersectionWith} for keeping elements present in both arrays
  * @see {@link differenceWith} for keeping elements present only in the first array
  *
@@ -7140,13 +7149,22 @@ const hashBucketsHas = (buckets: HashBuckets, value: unknown): boolean => {
  */
 export const unionWith: {
   /**
-   * Computes the union of two arrays using a custom equivalence, removing
-   * duplicates.
+   * Computes the union of two iterables using a custom equivalence.
    *
    * **When to use**
    *
    * Use when you need the union of two arrays but duplicate detection must use a
-   * custom equivalence instead of the default `Equal.equivalence()`.
+   * custom equivalence instead of the default `Equal.asEquivalence()`.
+   *
+   * **Details**
+   *
+   * Keeps the elements of `self`, then appends elements of `that` that have no
+   * equivalent in `self`. Calls `isEquivalent` with an element from `self` first
+   * and an element from `that` second.
+   *
+   * **Gotchas**
+   *
+   * Each input must already be deduplicated.
    *
    * **Example** (Computing unions with custom equality)
    *
@@ -7156,7 +7174,7 @@ export const unionWith: {
    * Array.unionWith([1, 2], [2, 3], (a, b) => a === b) // => [1, 2, 3]
    * ```
    *
-   * @see {@link union} for the `Equal.equivalence()` variant
+   * @see {@link union} for the `Equal.asEquivalence()` variant
    * @see {@link intersectionWith} for keeping elements present in both arrays
    * @see {@link differenceWith} for keeping elements present only in the first array
    *
@@ -7169,13 +7187,22 @@ export const unionWith: {
     isEquivalent: (self: ReadonlyArray.Infer<S>, that: ReadonlyArray.Infer<T>) => boolean
   ): (self: S) => ReadonlyArray.OrNonEmpty<S, T, ReadonlyArray.Infer<S> | ReadonlyArray.Infer<T>>
   /**
-   * Computes the union of two arrays using a custom equivalence, removing
-   * duplicates.
+   * Computes the union of two iterables using a custom equivalence.
    *
    * **When to use**
    *
    * Use when you need the union of two arrays but duplicate detection must use a
-   * custom equivalence instead of the default `Equal.equivalence()`.
+   * custom equivalence instead of the default `Equal.asEquivalence()`.
+   *
+   * **Details**
+   *
+   * Keeps the elements of `self`, then appends elements of `that` that have no
+   * equivalent in `self`. Calls `isEquivalent` with an element from `self` first
+   * and an element from `that` second.
+   *
+   * **Gotchas**
+   *
+   * Each input must already be deduplicated.
    *
    * **Example** (Computing unions with custom equality)
    *
@@ -7185,7 +7212,7 @@ export const unionWith: {
    * Array.unionWith([1, 2], [2, 3], (a, b) => a === b) // => [1, 2, 3]
    * ```
    *
-   * @see {@link union} for the `Equal.equivalence()` variant
+   * @see {@link union} for the `Equal.asEquivalence()` variant
    * @see {@link intersectionWith} for keeping elements present in both arrays
    * @see {@link differenceWith} for keeping elements present only in the first array
    *
@@ -7199,13 +7226,22 @@ export const unionWith: {
     isEquivalent: (self: A, that: B) => boolean
   ): NonEmptyArray<A | B>
   /**
-   * Computes the union of two arrays using a custom equivalence, removing
-   * duplicates.
+   * Computes the union of two iterables using a custom equivalence.
    *
    * **When to use**
    *
    * Use when you need the union of two arrays but duplicate detection must use a
-   * custom equivalence instead of the default `Equal.equivalence()`.
+   * custom equivalence instead of the default `Equal.asEquivalence()`.
+   *
+   * **Details**
+   *
+   * Keeps the elements of `self`, then appends elements of `that` that have no
+   * equivalent in `self`. Calls `isEquivalent` with an element from `self` first
+   * and an element from `that` second.
+   *
+   * **Gotchas**
+   *
+   * Each input must already be deduplicated.
    *
    * **Example** (Computing unions with custom equality)
    *
@@ -7215,7 +7251,7 @@ export const unionWith: {
    * Array.unionWith([1, 2], [2, 3], (a, b) => a === b) // => [1, 2, 3]
    * ```
    *
-   * @see {@link union} for the `Equal.equivalence()` variant
+   * @see {@link union} for the `Equal.asEquivalence()` variant
    * @see {@link intersectionWith} for keeping elements present in both arrays
    * @see {@link differenceWith} for keeping elements present only in the first array
    *
@@ -7229,13 +7265,22 @@ export const unionWith: {
     isEquivalent: (self: A, that: B) => boolean
   ): NonEmptyArray<A | B>
   /**
-   * Computes the union of two arrays using a custom equivalence, removing
-   * duplicates.
+   * Computes the union of two iterables using a custom equivalence.
    *
    * **When to use**
    *
    * Use when you need the union of two arrays but duplicate detection must use a
-   * custom equivalence instead of the default `Equal.equivalence()`.
+   * custom equivalence instead of the default `Equal.asEquivalence()`.
+   *
+   * **Details**
+   *
+   * Keeps the elements of `self`, then appends elements of `that` that have no
+   * equivalent in `self`. Calls `isEquivalent` with an element from `self` first
+   * and an element from `that` second.
+   *
+   * **Gotchas**
+   *
+   * Each input must already be deduplicated.
    *
    * **Example** (Computing unions with custom equality)
    *
@@ -7245,7 +7290,7 @@ export const unionWith: {
    * Array.unionWith([1, 2], [2, 3], (a, b) => a === b) // => [1, 2, 3]
    * ```
    *
-   * @see {@link union} for the `Equal.equivalence()` variant
+   * @see {@link union} for the `Equal.asEquivalence()` variant
    * @see {@link intersectionWith} for keeping elements present in both arrays
    * @see {@link differenceWith} for keeping elements present only in the first array
    *
@@ -7258,13 +7303,21 @@ export const unionWith: {
     that: Iterable<B>,
     isEquivalent: (self: A, that: B) => boolean
   ): Array<A | B>
-} = dual(3, <A>(self: Iterable<A>, that: Iterable<A>, isEquivalent: (self: A, that: A) => boolean): Array<A> => {
+} = dual(3, <A, B>(self: Iterable<A>, that: Iterable<B>, isEquivalent: (self: A, that: B) => boolean): Array<A | B> => {
   const a = fromIterable(self)
   const b = fromIterable(that)
   if (isReadonlyArrayNonEmpty(a)) {
     if (isReadonlyArrayNonEmpty(b)) {
-      const dedupe = dedupeWith(isEquivalent)
-      return dedupe(appendAll(a, b))
+      const out: Array<A | B> = [...a]
+      next: for (const value of b) {
+        for (const candidate of a) {
+          if (isEquivalent(candidate, value)) {
+            continue next
+          }
+        }
+        out.push(value)
+      }
+      return out
     }
     return a
   }
@@ -7272,8 +7325,12 @@ export const unionWith: {
 })
 
 /**
- * Computes the union of two arrays, removing duplicates using
- * `Equal.equivalence()`.
+ * Computes the union of two iterables using `Equal.asEquivalence()`.
+ *
+ * **Gotchas**
+ *
+ * Each input must already be deduplicated. Use {@link dedupe} to remove
+ * duplicates from an input first.
  *
  * **Example** (Computing array unions)
  *
@@ -7293,8 +7350,12 @@ export const unionWith: {
  */
 export const union: {
   /**
-   * Computes the union of two arrays, removing duplicates using
-   * `Equal.equivalence()`.
+   * Computes the union of two iterables using `Equal.asEquivalence()`.
+   *
+   * **Gotchas**
+   *
+   * Each input must already be deduplicated. Use {@link dedupe} to remove
+   * duplicates from an input first.
    *
    * **Example** (Computing array unions)
    *
@@ -7316,8 +7377,12 @@ export const union: {
     self: S
   ) => ReadonlyArray.OrNonEmpty<S, T, ReadonlyArray.Infer<S> | ReadonlyArray.Infer<T>>
   /**
-   * Computes the union of two arrays, removing duplicates using
-   * `Equal.equivalence()`.
+   * Computes the union of two iterables using `Equal.asEquivalence()`.
+   *
+   * **Gotchas**
+   *
+   * Each input must already be deduplicated. Use {@link dedupe} to remove
+   * duplicates from an input first.
    *
    * **Example** (Computing array unions)
    *
@@ -7337,8 +7402,12 @@ export const union: {
    */
   <A, B>(self: NonEmptyReadonlyArray<A>, that: ReadonlyArray<B>): NonEmptyArray<A | B>
   /**
-   * Computes the union of two arrays, removing duplicates using
-   * `Equal.equivalence()`.
+   * Computes the union of two iterables using `Equal.asEquivalence()`.
+   *
+   * **Gotchas**
+   *
+   * Each input must already be deduplicated. Use {@link dedupe} to remove
+   * duplicates from an input first.
    *
    * **Example** (Computing array unions)
    *
@@ -7358,8 +7427,12 @@ export const union: {
    */
   <A, B>(self: ReadonlyArray<A>, that: NonEmptyReadonlyArray<B>): NonEmptyArray<A | B>
   /**
-   * Computes the union of two arrays, removing duplicates using
-   * `Equal.equivalence()`.
+   * Computes the union of two iterables using `Equal.asEquivalence()`.
+   *
+   * **Gotchas**
+   *
+   * Each input must already be deduplicated. Use {@link dedupe} to remove
+   * duplicates from an input first.
    *
    * **Example** (Computing array unions)
    *
@@ -7411,7 +7484,7 @@ export const union: {
  * Array.intersectionWith(isEquivalent)(array2)(array1) // => [{ id: 1 }, { id: 3 }]
  * ```
  *
- * @see {@link intersection} for the `Equal.equivalence()` variant
+ * @see {@link intersection} for the `Equal.asEquivalence()` variant
  * @see {@link unionWith} for keeping values from either array with custom equality
  * @see {@link differenceWith} for keeping values only from the first array with custom equality
  *
@@ -7434,7 +7507,7 @@ export const intersectionWith = <A>(isEquivalent: (self: A, that: A) => boolean)
 }
 
 /**
- * Computes the intersection of two arrays using `Equal.equivalence()`. Order is
+ * Computes the intersection of two arrays using `Equal.asEquivalence()`. Order is
  * determined by the first array.
  *
  * **When to use**
@@ -7460,7 +7533,7 @@ export const intersectionWith = <A>(isEquivalent: (self: A, that: A) => boolean)
  */
 export const intersection: {
   /**
-   * Computes the intersection of two arrays using `Equal.equivalence()`. Order is
+   * Computes the intersection of two arrays using `Equal.asEquivalence()`. Order is
    * determined by the first array.
    *
    * **When to use**
@@ -7486,7 +7559,7 @@ export const intersection: {
    */
   <B>(that: Iterable<B>): <A>(self: Iterable<A>) => Array<A & B>
   /**
-   * Computes the intersection of two arrays using `Equal.equivalence()`. Order is
+   * Computes the intersection of two arrays using `Equal.asEquivalence()`. Order is
    * determined by the first array.
    *
    * **When to use**
@@ -7538,7 +7611,7 @@ export const intersection: {
  * Array.differenceWith<number>((a, b) => a === b)([1, 2, 3], [2, 3, 4]) // => [1]
  * ```
  *
- * @see {@link difference} for the `Equal.equivalence()` variant
+ * @see {@link difference} for the `Equal.asEquivalence()` variant
  * @see {@link unionWith} for keeping values from either array with custom equality
  * @see {@link intersectionWith} for keeping values present in both arrays with custom equality
  *
@@ -7562,12 +7635,12 @@ export const differenceWith = <A>(isEquivalent: (self: A, that: A) => boolean):
 
 /**
  * Computes elements in the first array that are not in the second, using
- * `Equal.equivalence()`.
+ * `Equal.asEquivalence()`.
  *
  * **When to use**
  *
  * Use when you need to keep values from the first array that are absent from
- * the second and the default `Equal.equivalence()` comparison is appropriate.
+ * the second and the default `Equal.asEquivalence()` comparison is appropriate.
  *
  * **Example** (Computing array differences)
  *
@@ -7588,12 +7661,12 @@ export const differenceWith = <A>(isEquivalent: (self: A, that: A) => boolean):
 export const difference: {
   /**
    * Computes elements in the first array that are not in the second, using
-   * `Equal.equivalence()`.
+   * `Equal.asEquivalence()`.
    *
    * **When to use**
    *
    * Use when you need to keep values from the first array that are absent from
-   * the second and the default `Equal.equivalence()` comparison is appropriate.
+   * the second and the default `Equal.asEquivalence()` comparison is appropriate.
    *
    * **Example** (Computing array differences)
    *
@@ -7614,12 +7687,12 @@ export const difference: {
   <A>(that: Iterable<A>): (self: Iterable<A>) => Array<A>
   /**
    * Computes elements in the first array that are not in the second, using
-   * `Equal.equivalence()`.
+   * `Equal.asEquivalence()`.
    *
    * **When to use**
    *
    * Use when you need to keep values from the first array that are absent from
-   * the second and the default `Equal.equivalence()` comparison is appropriate.
+   * the second and the default `Equal.asEquivalence()` comparison is appropriate.
    *
    * **Example** (Computing array differences)
    *
@@ -9702,7 +9775,7 @@ export const dedupeWith: {
 )
 
 /**
- * Removes duplicates using `Equal.equivalence()`, preserving the order of the
+ * Removes duplicates using `Equal.asEquivalence()`, preserving the order of the
  * first occurrence.
  *
  * **When to use**
@@ -9842,7 +9915,7 @@ export const dedupeAdjacentWith: {
 })
 
 /**
- * Removes consecutive duplicate elements using `Equal.equivalence()`.
+ * Removes consecutive duplicate elements using `Equal.asEquivalence()`.
  *
  * **When to use**
  *

package/src/Bytes.ts

@@ -0,0 +1,111 @@
+/**
+ * Joins and compares byte sequences stored in `Uint8Array` values.
+ *
+ * Byte-to-text conversions live in `TextEncoder` / `TextDecoder`, and hex or
+ * base64 conversions live in the `Encoding` modules.
+ *
+ * @stability unstable
+ * @since 4.0.6
+ */
+import * as Equ from "./Equivalence.ts"
+import * as order from "./Order.ts"
+
+/**
+ * Joins byte chunks into one new `Uint8Array`.
+ *
+ * **When to use**
+ *
+ * Use to combine frames, headers, or streamed chunks into a single buffer.
+ *
+ * **Gotchas**
+ *
+ * The result is always a new array, even when there is zero or one chunk, so
+ * it never aliases an input.
+ *
+ * **Example** (Joining byte chunks)
+ *
+ * ```ts import.meta.vitest
+ * import { Bytes } from "effect"
+ *
+ * const bytes = Bytes.concat([new Uint8Array([1, 2]), new Uint8Array([3])])
+ * Array.from(bytes) // => [1, 2, 3]
+ * ```
+ *
+ * @stability unstable
+ * @category combinators
+ * @since 4.0.6
+ */
+export const concat = (chunks: ReadonlyArray<Uint8Array>): Uint8Array<ArrayBuffer> => {
+  let length = 0
+  for (let i = 0; i < chunks.length; i++) {
+    length += chunks[i].length
+  }
+  const out = new Uint8Array(length)
+  let offset = 0
+  for (let i = 0; i < chunks.length; i++) {
+    out.set(chunks[i], offset)
+    offset += chunks[i].length
+  }
+  return out
+}
+
+/**
+ * Compares byte sequences for equality, byte by byte.
+ *
+ * **Gotchas**
+ *
+ * This returns as soon as a byte differs, so it is not constant-time. Do not
+ * use it to compare secrets.
+ *
+ * **Example** (Comparing byte sequences)
+ *
+ * ```ts import.meta.vitest
+ * import { Bytes } from "effect"
+ *
+ * Bytes.Equivalence(new Uint8Array([1, 2]), new Uint8Array([1, 2])) // => true
+ * Bytes.Equivalence(new Uint8Array([1, 2]), new Uint8Array([1])) // => false
+ * ```
+ *
+ * @stability unstable
+ * @category instances
+ * @since 4.0.6
+ */
+export const Equivalence: Equ.Equivalence<Uint8Array> = Equ.make((self, that) => {
+  if (self.length !== that.length) {
+    return false
+  }
+  for (let i = 0; i < self.length; i++) {
+    if (self[i] !== that[i]) {
+      return false
+    }
+  }
+  return true
+})
+
+/**
+ * Orders byte sequences lexicographically by unsigned byte value, placing a
+ * prefix before any longer sequence that starts with it.
+ *
+ * **Example** (Sorting byte sequences)
+ *
+ * ```ts import.meta.vitest
+ * import { Bytes } from "effect"
+ *
+ * Bytes.Order(new Uint8Array([1, 2]), new Uint8Array([1, 3])) // => -1
+ * Bytes.Order(new Uint8Array([2]), new Uint8Array([1, 9])) // => 1
+ * Bytes.Order(new Uint8Array([1]), new Uint8Array([1, 0])) // => -1
+ * ```
+ *
+ * @stability unstable
+ * @category instances
+ * @since 4.0.6
+ */
+export const Order: order.Order<Uint8Array> = order.make((self, that) => {
+  const length = Math.min(self.length, that.length)
+  for (let i = 0; i < length; i++) {
+    if (self[i] !== that[i]) {
+      return self[i] < that[i] ? -1 : 1
+    }
+  }
+  return self.length < that.length ? -1 : self.length > that.length ? 1 : 0
+})