effect 4.0.0-beta.73 → 4.0.0-beta.75

package/src/ChannelSchema.ts

@@ -152,8 +152,8 @@ export const decode = <S extends Schema.Top>(
  *
  * **When to use**
  *
- * Use when the encoded input type is intentionally unknown or untyped, so
- * that only the decoded output is statically typed according to the schema.
+ * Use when you need an intentionally unknown or untyped encoded input while
+ * keeping only the decoded output statically typed according to the schema.
  *
  * **Details**
  *
@@ -374,9 +374,9 @@ export const duplex: {
  *
  * **When to use**
  *
- * Use when a bidirectional channel crosses an encoded boundary whose chunk types
- * are intentionally erased, while callers should send and receive schema-typed
- * chunks.
+ * Use when you need a bidirectional channel to cross an encoded boundary whose
+ * chunk types are intentionally erased, while callers send and receive
+ * schema-typed chunks.
  *
  * **Details**
  *
@@ -395,9 +395,9 @@ export const duplexUnknown: {
    *
    * **When to use**
    *
-   * Use when a bidirectional channel crosses an encoded boundary whose chunk types
-   * are intentionally erased, while callers should send and receive schema-typed
-   * chunks.
+   * Use when you need a bidirectional channel to cross an encoded boundary whose
+   * chunk types are intentionally erased, while callers send and receive
+   * schema-typed chunks.
    *
    * **Details**
    *
@@ -439,9 +439,9 @@ export const duplexUnknown: {
    *
    * **When to use**
    *
-   * Use when a bidirectional channel crosses an encoded boundary whose chunk types
-   * are intentionally erased, while callers should send and receive schema-typed
-   * chunks.
+   * Use when you need a bidirectional channel to cross an encoded boundary whose
+   * chunk types are intentionally erased, while callers send and receive
+   * schema-typed chunks.
    *
    * **Details**
    *

package/src/Chunk.ts

@@ -225,7 +225,7 @@ const emptyArray: ReadonlyArray<never> = []
  * console.log(eq(chunk1, chunk3)) // false
  * ```
  *
- * @category equivalence
+ * @category instances
  * @since 4.0.0
  */
 export const makeEquivalence = <A>(isEquivalent: Equivalence.Equivalence<A>): Equivalence.Equivalence<Chunk<A>> =>
@@ -685,8 +685,16 @@ export const get: {
 )
 
 /**
- * Wraps an array into a chunk without copying, so mutating the source array can
- * mutate the chunk.
+ * Wraps an array into a chunk without copying.
+ *
+ * **When to use**
+ *
+ * Use when the input array can be shared with the resulting `Chunk` and avoiding
+ * a copy matters.
+ *
+ * **Gotchas**
+ *
+ * Mutating the source array after wrapping can mutate the resulting `Chunk`.
  *
  * **Example** (Creating chunks without copying arrays)
  *
@@ -709,8 +717,16 @@ export const fromArrayUnsafe = <A>(self: ReadonlyArray<A>): Chunk<A> =>
   self.length === 0 ? empty() : self.length === 1 ? of(self[0]) : makeChunk({ _tag: "IArray", array: self })
 
 /**
- * Wraps a non-empty array into a non-empty chunk without copying, so mutating
- * the source array can mutate the chunk.
+ * Wraps a non-empty array into a non-empty chunk without copying.
+ *
+ * **When to use**
+ *
+ * Use when the input array is already known to be non-empty, can be shared with
+ * the resulting `Chunk`, and avoiding a copy matters.
+ *
+ * **Gotchas**
+ *
+ * Mutating the source array after wrapping can mutate the resulting `Chunk`.
  *
  * **Example** (Creating non-empty chunks without copying arrays)
  *
@@ -732,7 +748,16 @@ export const fromNonEmptyArrayUnsafe = <A>(self: NonEmptyReadonlyArray<A>): NonE
   fromArrayUnsafe(self) as any
 
 /**
- * Gets an element unsafely, will throw on out of bounds
+ * Gets an element at the specified index without returning an `Option`.
+ *
+ * **When to use**
+ *
+ * Use when reading from a `Chunk` at an index known to be in bounds and direct
+ * element access is preferred over handling `Option.none`.
+ *
+ * **Gotchas**
+ *
+ * Throws if the index is out of bounds.
  *
  * **Example** (Accessing elements unsafely)
  *
@@ -753,7 +778,16 @@ export const fromNonEmptyArrayUnsafe = <A>(self: NonEmptyReadonlyArray<A>): NonE
  */
 export const getUnsafe: {
   /**
-   * Gets an element unsafely, will throw on out of bounds
+   * Gets an element at the specified index without returning an `Option`.
+   *
+   * **When to use**
+   *
+   * Use when reading from a `Chunk` at an index known to be in bounds and direct
+   * element access is preferred over handling `Option.none`.
+   *
+   * **Gotchas**
+   *
+   * Throws if the index is out of bounds.
    *
    * **Example** (Accessing elements unsafely)
    *
@@ -774,7 +808,16 @@ export const getUnsafe: {
    */
   (index: number): <A>(self: Chunk<A>) => A
   /**
-   * Gets an element unsafely, will throw on out of bounds
+   * Gets an element at the specified index without returning an `Option`.
+   *
+   * **When to use**
+   *
+   * Use when reading from a `Chunk` at an index known to be in bounds and direct
+   * element access is preferred over handling `Option.none`.
+   *
+   * **Gotchas**
+   *
+   * Throws if the index is out of bounds.
    *
    * **Example** (Accessing elements unsafely)
    *
@@ -828,8 +871,8 @@ export const getUnsafe: {
  *
  * **When to use**
  *
- * Use to add one element after the existing elements and get a non-empty
- * result.
+ * Use to add one element after the existing chunk elements and return a
+ * `NonEmptyChunk`.
  *
  * **Example** (Appending an element)
  *
@@ -849,7 +892,7 @@ export const getUnsafe: {
  * @see {@link prepend} for adding one element before the existing elements
  * @see {@link appendAll} for appending all elements from another chunk
  *
- * @category concatenating
+ * @category combining
  * @since 2.0.0
  */
 export const append: {
@@ -858,8 +901,8 @@ export const append: {
    *
    * **When to use**
    *
-   * Use to add one element after the existing elements and get a non-empty
-   * result.
+   * Use to add one element after the existing chunk elements and return a
+   * `NonEmptyChunk`.
    *
    * **Example** (Appending an element)
    *
@@ -879,7 +922,7 @@ export const append: {
    * @see {@link prepend} for adding one element before the existing elements
    * @see {@link appendAll} for appending all elements from another chunk
    *
-   * @category concatenating
+   * @category combining
    * @since 2.0.0
    */
   <A2>(a: A2): <A>(self: Chunk<A>) => NonEmptyChunk<A2 | A>
@@ -888,8 +931,8 @@ export const append: {
    *
    * **When to use**
    *
-   * Use to add one element after the existing elements and get a non-empty
-   * result.
+   * Use to add one element after the existing chunk elements and return a
+   * `NonEmptyChunk`.
    *
    * **Example** (Appending an element)
    *
@@ -909,7 +952,7 @@ export const append: {
    * @see {@link prepend} for adding one element before the existing elements
    * @see {@link appendAll} for appending all elements from another chunk
    *
-   * @category concatenating
+   * @category combining
    * @since 2.0.0
    */
   <A, A2>(self: Chunk<A>, a: A2): NonEmptyChunk<A | A2>
@@ -933,7 +976,7 @@ export const append: {
  * console.log(Chunk.toArray(singleElement)) // ["first"]
  * ```
  *
- * @category concatenating
+ * @category combining
  * @since 2.0.0
  */
 export const prepend: {
@@ -955,7 +998,7 @@ export const prepend: {
    * console.log(Chunk.toArray(singleElement)) // ["first"]
    * ```
    *
-   * @category concatenating
+   * @category combining
    * @since 2.0.0
    */
   <B>(elem: B): <A>(self: Chunk<A>) => NonEmptyChunk<B | A>
@@ -977,7 +1020,7 @@ export const prepend: {
    * console.log(Chunk.toArray(singleElement)) // ["first"]
    * ```
    *
-   * @category concatenating
+   * @category combining
    * @since 2.0.0
    */
   <A, B>(self: Chunk<A>, elem: B): NonEmptyChunk<A | B>
@@ -1292,7 +1335,7 @@ export const dropWhile: {
  * // [ "a", "b", 1, 2 ]
  * ```
  *
- * @category concatenating
+ * @category combining
  * @since 2.0.0
  */
 export const prependAll: {
@@ -1314,7 +1357,7 @@ export const prependAll: {
    * // [ "a", "b", 1, 2 ]
    * ```
    *
-   * @category concatenating
+   * @category combining
    * @since 2.0.0
    */
   <S extends Chunk<any>, T extends Chunk<any>>(that: T): (self: S) => Chunk.OrNonEmpty<S, T, Chunk.Infer<S> | Chunk.Infer<T>>
@@ -1336,7 +1379,7 @@ export const prependAll: {
    * // [ "a", "b", 1, 2 ]
    * ```
    *
-   * @category concatenating
+   * @category combining
    * @since 2.0.0
    */
   <A, B>(self: Chunk<A>, that: NonEmptyChunk<B>): NonEmptyChunk<A | B>
@@ -1358,7 +1401,7 @@ export const prependAll: {
    * // [ "a", "b", 1, 2 ]
    * ```
    *
-   * @category concatenating
+   * @category combining
    * @since 2.0.0
    */
   <A, B>(self: NonEmptyChunk<A>, that: Chunk<B>): NonEmptyChunk<A | B>
@@ -1380,7 +1423,7 @@ export const prependAll: {
    * // [ "a", "b", 1, 2 ]
    * ```
    *
-   * @category concatenating
+   * @category combining
    * @since 2.0.0
    */
   <A, B>(self: Chunk<A>, that: Chunk<B>): Chunk<A | B>
@@ -1412,7 +1455,7 @@ export const prependAll: {
  * @see {@link prependAll} for concatenating chunks in the opposite order
  * @see {@link append} for adding a single element to the end
  *
- * @category concatenating
+ * @category combining
  * @since 2.0.0
  */
 export const appendAll: {
@@ -1442,7 +1485,7 @@ export const appendAll: {
    * @see {@link prependAll} for concatenating chunks in the opposite order
    * @see {@link append} for adding a single element to the end
    *
-   * @category concatenating
+   * @category combining
    * @since 2.0.0
    */
   <S extends Chunk<any>, T extends Chunk<any>>(that: T): (self: S) => Chunk.OrNonEmpty<S, T, Chunk.Infer<S> | Chunk.Infer<T>>
@@ -1472,7 +1515,7 @@ export const appendAll: {
    * @see {@link prependAll} for concatenating chunks in the opposite order
    * @see {@link append} for adding a single element to the end
    *
-   * @category concatenating
+   * @category combining
    * @since 2.0.0
    */
   <A, B>(self: Chunk<A>, that: NonEmptyChunk<B>): NonEmptyChunk<A | B>
@@ -1502,7 +1545,7 @@ export const appendAll: {
    * @see {@link prependAll} for concatenating chunks in the opposite order
    * @see {@link append} for adding a single element to the end
    *
-   * @category concatenating
+   * @category combining
    * @since 2.0.0
    */
   <A, B>(self: NonEmptyChunk<A>, that: Chunk<B>): NonEmptyChunk<A | B>
@@ -1532,7 +1575,7 @@ export const appendAll: {
    * @see {@link prependAll} for concatenating chunks in the opposite order
    * @see {@link append} for adding a single element to the end
    *
-   * @category concatenating
+   * @category combining
    * @since 2.0.0
    */
   <A, B>(self: Chunk<A>, that: Chunk<B>): Chunk<A | B>
@@ -1571,7 +1614,7 @@ export const appendAll: {
      * @see {@link prependAll} for concatenating chunks in the opposite order
      * @see {@link append} for adding a single element to the end
      *
-     * @category concatenating
+     * @category combining
      * @since 2.0.0
      */
     A | B>({ _tag: "IConcat", left: self, right: that });
@@ -2219,7 +2262,7 @@ export const flatten: <S extends Chunk<Chunk<any>>>(self: S) => Chunk.Flatten<S>
  *
  * **When to use**
  *
- * Use to divide a chunk into ordered, non-overlapping batches with at most `n`
+ * Use to divide a chunk into ordered, non-overlapping chunks with at most `n`
  * elements each.
  *
  * **Details**
@@ -2260,7 +2303,7 @@ export const chunksOf: {
    *
    * **When to use**
    *
-   * Use to divide a chunk into ordered, non-overlapping batches with at most `n`
+   * Use to divide a chunk into ordered, non-overlapping chunks with at most `n`
    * elements each.
    *
    * **Details**
@@ -2301,7 +2344,7 @@ export const chunksOf: {
    *
    * **When to use**
    *
-   * Use to divide a chunk into ordered, non-overlapping batches with at most `n`
+   * Use to divide a chunk into ordered, non-overlapping chunks with at most `n`
    * elements each.
    *
    * **Details**
@@ -2509,6 +2552,11 @@ export const head: <A>(self: Chunk<A>) => Option<A> = get(0)
 /**
  * Returns the first element of this chunk.
  *
+ * **When to use**
+ *
+ * Use when you know the chunk is non-empty and need the first element directly
+ * without handling `Option.none`.
+ *
  * **Gotchas**
  *
  * Throws an error if the chunk is empty.
@@ -2576,6 +2624,11 @@ export const last = <A>(self: Chunk<A>): Option<A> => get(self, self.length - 1)
 /**
  * Returns the last element of this chunk.
  *
+ * **When to use**
+ *
+ * Use when you know the chunk is non-empty and need the last element directly
+ * without handling `Option.none`.
+ *
  * **Gotchas**
  *
  * Throws an error if the chunk is empty.

package/src/Clock.ts

@@ -135,12 +135,12 @@ export interface Clock {
 }
 
 /**
- * Context reference for the current Clock service in the environment.
+ * Context reference for the active time service in the environment.
  *
  * **When to use**
  *
- * Use when you need to access or provide the full Clock service rather than a
- * single timestamp accessor.
+ * Use when you need to access or provide the full time service, including sleep
+ * operations, rather than a single timestamp accessor.
  *
  * **Example** (Accessing the Clock service)
  *

package/src/Combiner.ts

@@ -138,9 +138,8 @@ export function make<A>(combine: (self: A, that: A) => A): Combiner<A> {
  *
  * **When to use**
  *
- * Use when the "right" value should act as the accumulator side, or when
- * you want to reverse the natural direction of a non-commutative combiner such
- * as string concatenation.
+ * Use when you want the right-hand value to act as the accumulator, or need to
+ * reverse a non-commutative combiner such as string concatenation.
  *
  * **Details**
  *
@@ -243,8 +242,7 @@ export function max<A>(order: Order.Order<A>): Combiner<A> {
  *
  * **When to use**
  *
- * Use when you want "first write wins" semantics while merging values, or
- * when the combining logic should keep the existing value.
+ * Use when you want "first write wins" semantics while merging values.
  *
  * **Details**
  *
@@ -274,8 +272,7 @@ export function first<A>(): Combiner<A> {
  *
  * **When to use**
  *
- * Use when you want "last write wins" semantics while merging values, or
- * when each new value should replace the accumulator.
+ * Use when you want "last write wins" semantics while merging values.
  *
  * **Details**
  *
@@ -306,9 +303,8 @@ export function last<A>(): Combiner<A> {
  *
  * **When to use**
  *
- * Use when a combiner should produce a fixed result regardless of input,
- * or when a generic API needs a combiner but the combined value is
- * predetermined.
+ * Use when you need a combiner that always returns a fixed value, including
+ * when a generic API requires a combiner but the result is predetermined.
  *
  * **Details**
  *
@@ -340,9 +336,9 @@ export function constant<A>(a: A): Combiner<A> {
  *
  * **When to use**
  *
- * Use when you are building delimited strings (CSV, paths, etc.) by
- * repeated combination, or when you need to inject a fixed separator between
- * accumulated values.
+ * Use when you need to inject a fixed separator between accumulated values,
+ * such as when building delimited strings, paths, or CSV-like output by
+ * repeated combination.
  *
  * **Details**
  *