effect 4.0.0-beta.70 → 4.0.0-beta.71

package/src/ChannelSchema.ts

@@ -53,11 +53,19 @@ import * as Schema from "./Schema.ts"
  * Creates a channel that encodes non-empty chunks of schema values into the
  * schema's encoded representation.
  *
+ * **When to use**
+ *
+ * Use to encode typed channel input into the schema's encoded representation
+ * before passing chunks to an encoded downstream boundary.
+ *
  * **Details**
  *
  * Encoding failures are emitted as `SchemaError`, and any encoding services
  * required by the schema become channel requirements.
  *
+ * @see {@link encodeUnknown} for encoded output chunks that should be typed as `unknown`
+ * @see {@link decode} for the inverse channel that decodes encoded chunks into schema values
+ *
  * @category constructors
  * @since 4.0.0
  */
@@ -83,9 +91,10 @@ export const encode = <S extends Schema.Top>(
  *
  * **When to use**
  *
- * Use this at channel boundaries where the encoded representation is
- * intentionally untyped, while still encoding typed input chunks with the
- * provided schema.
+ * Use when a channel boundary should encode typed input chunks while the encoded
+ * output representation is intentionally untyped.
+ *
+ * @see {@link encode} for the variant that preserves the schema encoded type
  *
  * @category constructors
  * @since 4.0.0
@@ -106,11 +115,19 @@ export const encodeUnknown: <S extends Schema.Top>(
  * Creates a channel that decodes non-empty chunks from the schema's encoded
  * representation into schema values.
  *
+ * **When to use**
+ *
+ * Use to validate and decode encoded channel output into typed schema values
+ * before application code consumes it.
+ *
  * **Details**
  *
  * Decoding failures are emitted as `SchemaError`, and any decoding services
  * required by the schema become channel requirements.
  *
+ * @see {@link decodeUnknown} for boundaries where the encoded input side is intentionally untyped
+ * @see {@link encode} for the inverse adapter that encodes typed schema values
+ *
  * @category constructors
  * @since 4.0.0
  */
@@ -133,12 +150,19 @@ export const decode = <S extends Schema.Top>(
 /**
  * Creates a `decode` channel variant for schema-decoding channel boundaries.
  *
+ * **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.
+ *
  * **Details**
  *
  * The channel decodes non-empty encoded chunks into schema values, emits
  * `SchemaError` when decoding fails, and requires the schema's decoding
  * services.
  *
+ * @see {@link decode} for the typed variant that preserves the schema's encoded type
+ *
  * @category constructors
  * @since 4.0.0
  */
@@ -158,6 +182,11 @@ export const decodeUnknown: <S extends Schema.Top>(
  * Wraps a channel so callers work with typed input and output chunks while the
  * wrapped channel uses encoded chunks.
  *
+ * **When to use**
+ *
+ * Use to expose typed input and output at a bidirectional channel boundary
+ * while the wrapped channel continues to operate on schema-encoded chunks.
+ *
  * **Details**
  *
  * Values sent into the resulting channel are encoded with `inputSchema` before
@@ -165,6 +194,10 @@ export const decodeUnknown: <S extends Schema.Top>(
  * decoded with `outputSchema` before they are emitted downstream. Schema
  * failures are surfaced as `SchemaError`.
  *
+ * @see {@link duplexUnknown} for the variant whose encoded side is intentionally untyped
+ * @see {@link encode} for encoding typed chunks at one-way channel boundaries
+ * @see {@link decode} for decoding encoded chunks at one-way channel boundaries
+ *
  * @category combinators
  * @since 4.0.0
  */
@@ -173,6 +206,11 @@ export const duplex: {
    * Wraps a channel so callers work with typed input and output chunks while the
    * wrapped channel uses encoded chunks.
    *
+   * **When to use**
+   *
+   * Use to expose typed input and output at a bidirectional channel boundary
+   * while the wrapped channel continues to operate on schema-encoded chunks.
+   *
    * **Details**
    *
    * Values sent into the resulting channel are encoded with `inputSchema` before
@@ -180,6 +218,10 @@ export const duplex: {
    * decoded with `outputSchema` before they are emitted downstream. Schema
    * failures are surfaced as `SchemaError`.
    *
+   * @see {@link duplexUnknown} for the variant whose encoded side is intentionally untyped
+   * @see {@link encode} for encoding typed chunks at one-way channel boundaries
+   * @see {@link decode} for decoding encoded chunks at one-way channel boundaries
+   *
    * @category combinators
    * @since 4.0.0
    */
@@ -211,6 +253,11 @@ export const duplex: {
    * Wraps a channel so callers work with typed input and output chunks while the
    * wrapped channel uses encoded chunks.
    *
+   * **When to use**
+   *
+   * Use to expose typed input and output at a bidirectional channel boundary
+   * while the wrapped channel continues to operate on schema-encoded chunks.
+   *
    * **Details**
    *
    * Values sent into the resulting channel are encoded with `inputSchema` before
@@ -218,6 +265,10 @@ export const duplex: {
    * decoded with `outputSchema` before they are emitted downstream. Schema
    * failures are surfaced as `SchemaError`.
    *
+   * @see {@link duplexUnknown} for the variant whose encoded side is intentionally untyped
+   * @see {@link encode} for encoding typed chunks at one-way channel boundaries
+   * @see {@link decode} for decoding encoded chunks at one-way channel boundaries
+   *
    * @category combinators
    * @since 4.0.0
    */
@@ -271,6 +322,11 @@ export const duplex: {
    * Wraps a channel so callers work with typed input and output chunks while the
    * wrapped channel uses encoded chunks.
    *
+   * **When to use**
+   *
+   * Use to expose typed input and output at a bidirectional channel boundary
+   * while the wrapped channel continues to operate on schema-encoded chunks.
+   *
    * **Details**
    *
    * Values sent into the resulting channel are encoded with `inputSchema` before
@@ -278,6 +334,10 @@ export const duplex: {
    * decoded with `outputSchema` before they are emitted downstream. Schema
    * failures are surfaced as `SchemaError`.
    *
+   * @see {@link duplexUnknown} for the variant whose encoded side is intentionally untyped
+   * @see {@link encode} for encoding typed chunks at one-way channel boundaries
+   * @see {@link decode} for decoding encoded chunks at one-way channel boundaries
+   *
    * @category combinators
    * @since 4.0.0
    */
@@ -285,6 +345,11 @@ export const duplex: {
    * Wraps a channel so callers work with typed input and output chunks while the
    * wrapped channel uses encoded chunks.
    *
+   * **When to use**
+   *
+   * Use to expose typed input and output at a bidirectional channel boundary
+   * while the wrapped channel continues to operate on schema-encoded chunks.
+   *
    * **Details**
    *
    * Values sent into the resulting channel are encoded with `inputSchema` before
@@ -292,6 +357,10 @@ export const duplex: {
    * decoded with `outputSchema` before they are emitted downstream. Schema
    * failures are surfaced as `SchemaError`.
    *
+   * @see {@link duplexUnknown} for the variant whose encoded side is intentionally untyped
+   * @see {@link encode} for encoding typed chunks at one-way channel boundaries
+   * @see {@link decode} for decoding encoded chunks at one-way channel boundaries
+   *
    * @category combinators
    * @since 4.0.0
    */
@@ -303,12 +372,20 @@ export const duplex: {
 /**
  * Like `duplex`, but for channels whose encoded side is not statically typed.
  *
+ * **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.
+ *
  * **Details**
  *
  * The resulting channel accepts typed input chunks, encodes them with
  * `inputSchema`, decodes unknown output chunks with `outputSchema`, and
  * surfaces schema failures as `SchemaError`.
  *
+ * @see {@link duplex} for the variant that preserves the schema encoded types on the wrapped channel
+ *
  * @category combinators
  * @since 4.0.0
  */
@@ -316,12 +393,20 @@ export const duplexUnknown: {
   /**
    * Like `duplex`, but for channels whose encoded side is not statically typed.
    *
+   * **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.
+   *
    * **Details**
    *
    * The resulting channel accepts typed input chunks, encodes them with
    * `inputSchema`, decodes unknown output chunks with `outputSchema`, and
    * surfaces schema failures as `SchemaError`.
    *
+   * @see {@link duplex} for the variant that preserves the schema encoded types on the wrapped channel
+   *
    * @category combinators
    * @since 4.0.0
    */
@@ -352,12 +437,20 @@ export const duplexUnknown: {
   /**
    * Like `duplex`, but for channels whose encoded side is not statically typed.
    *
+   * **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.
+   *
    * **Details**
    *
    * The resulting channel accepts typed input chunks, encodes them with
    * `inputSchema`, decodes unknown output chunks with `outputSchema`, and
    * surfaces schema failures as `SchemaError`.
    *
+   * @see {@link duplex} for the variant that preserves the schema encoded types on the wrapped channel
+   *
    * @category combinators
    * @since 4.0.0
    */

package/src/Chunk.ts

@@ -813,6 +813,11 @@ export const getUnsafe: {
 /**
  * Appends the specified element to the end of the `Chunk`.
  *
+ * **When to use**
+ *
+ * Use to add one element after the existing elements and get a non-empty
+ * result.
+ *
  * **Example** (Appending an element)
  *
  * ```ts
@@ -828,6 +833,9 @@ export const getUnsafe: {
  * console.log(Chunk.toArray(singleElement)) // [42]
  * ```
  *
+ * @see {@link prepend} for adding one element before the existing elements
+ * @see {@link appendAll} for appending all elements from another chunk
+ *
  * @category concatenating
  * @since 2.0.0
  */
@@ -835,6 +843,11 @@ export const append: {
   /**
    * Appends the specified element to the end of the `Chunk`.
    *
+   * **When to use**
+   *
+   * Use to add one element after the existing elements and get a non-empty
+   * result.
+   *
    * **Example** (Appending an element)
    *
    * ```ts
@@ -850,6 +863,9 @@ export const append: {
    * console.log(Chunk.toArray(singleElement)) // [42]
    * ```
    *
+   * @see {@link prepend} for adding one element before the existing elements
+   * @see {@link appendAll} for appending all elements from another chunk
+   *
    * @category concatenating
    * @since 2.0.0
    */
@@ -857,6 +873,11 @@ export const append: {
   /**
    * Appends the specified element to the end of the `Chunk`.
    *
+   * **When to use**
+   *
+   * Use to add one element after the existing elements and get a non-empty
+   * result.
+   *
    * **Example** (Appending an element)
    *
    * ```ts
@@ -872,6 +893,9 @@ export const append: {
    * console.log(Chunk.toArray(singleElement)) // [42]
    * ```
    *
+   * @see {@link prepend} for adding one element before the existing elements
+   * @see {@link appendAll} for appending all elements from another chunk
+   *
    * @category concatenating
    * @since 2.0.0
    */
@@ -1353,6 +1377,11 @@ export const prependAll: {
  * Concatenates two chunks, combining their elements.
  * If either chunk is non-empty, the result is also a non-empty chunk.
  *
+ * **When to use**
+ *
+ * Use to concatenate two chunks when the second chunk's elements should come
+ * after the first.
+ *
  * **Example** (Appending all elements)
  *
  * ```ts
@@ -1367,6 +1396,9 @@ export const prependAll: {
  * // [ 1, 2, "a", "b" ]
  * ```
  *
+ * @see {@link prependAll} for concatenating chunks in the opposite order
+ * @see {@link append} for adding a single element to the end
+ *
  * @category concatenating
  * @since 2.0.0
  */
@@ -1375,6 +1407,11 @@ export const appendAll: {
    * Concatenates two chunks, combining their elements.
    * If either chunk is non-empty, the result is also a non-empty chunk.
    *
+   * **When to use**
+   *
+   * Use to concatenate two chunks when the second chunk's elements should come
+   * after the first.
+   *
    * **Example** (Appending all elements)
    *
    * ```ts
@@ -1389,6 +1426,9 @@ export const appendAll: {
    * // [ 1, 2, "a", "b" ]
    * ```
    *
+   * @see {@link prependAll} for concatenating chunks in the opposite order
+   * @see {@link append} for adding a single element to the end
+   *
    * @category concatenating
    * @since 2.0.0
    */
@@ -1397,6 +1437,11 @@ export const appendAll: {
    * Concatenates two chunks, combining their elements.
    * If either chunk is non-empty, the result is also a non-empty chunk.
    *
+   * **When to use**
+   *
+   * Use to concatenate two chunks when the second chunk's elements should come
+   * after the first.
+   *
    * **Example** (Appending all elements)
    *
    * ```ts
@@ -1411,6 +1456,9 @@ export const appendAll: {
    * // [ 1, 2, "a", "b" ]
    * ```
    *
+   * @see {@link prependAll} for concatenating chunks in the opposite order
+   * @see {@link append} for adding a single element to the end
+   *
    * @category concatenating
    * @since 2.0.0
    */
@@ -1419,6 +1467,11 @@ export const appendAll: {
    * Concatenates two chunks, combining their elements.
    * If either chunk is non-empty, the result is also a non-empty chunk.
    *
+   * **When to use**
+   *
+   * Use to concatenate two chunks when the second chunk's elements should come
+   * after the first.
+   *
    * **Example** (Appending all elements)
    *
    * ```ts
@@ -1433,6 +1486,9 @@ export const appendAll: {
    * // [ 1, 2, "a", "b" ]
    * ```
    *
+   * @see {@link prependAll} for concatenating chunks in the opposite order
+   * @see {@link append} for adding a single element to the end
+   *
    * @category concatenating
    * @since 2.0.0
    */
@@ -1441,6 +1497,11 @@ export const appendAll: {
    * Concatenates two chunks, combining their elements.
    * If either chunk is non-empty, the result is also a non-empty chunk.
    *
+   * **When to use**
+   *
+   * Use to concatenate two chunks when the second chunk's elements should come
+   * after the first.
+   *
    * **Example** (Appending all elements)
    *
    * ```ts
@@ -1455,6 +1516,9 @@ export const appendAll: {
    * // [ 1, 2, "a", "b" ]
    * ```
    *
+   * @see {@link prependAll} for concatenating chunks in the opposite order
+   * @see {@link append} for adding a single element to the end
+   *
    * @category concatenating
    * @since 2.0.0
    */
@@ -1472,6 +1536,11 @@ export const appendAll: {
      * Concatenates two chunks, combining their elements.
      * If either chunk is non-empty, the result is also a non-empty chunk.
      *
+     * **When to use**
+     *
+     * Use to concatenate two chunks when the second chunk's elements should come
+     * after the first.
+     *
      * **Example** (Appending all elements)
      *
      * ```ts
@@ -1486,6 +1555,9 @@ export const appendAll: {
      * // [ 1, 2, "a", "b" ]
      * ```
      *
+     * @see {@link prependAll} for concatenating chunks in the opposite order
+     * @see {@link append} for adding a single element to the end
+     *
      * @category concatenating
      * @since 2.0.0
      */
@@ -2132,6 +2204,20 @@ export const flatten: <S extends Chunk<Chunk<any>>>(self: S) => Chunk.Flatten<S>
 /**
  * Groups elements in chunks of up to `n` elements.
  *
+ * **When to use**
+ *
+ * Use to divide a chunk into ordered, non-overlapping batches with at most `n`
+ * elements each.
+ *
+ * **Details**
+ *
+ * The final chunk may contain fewer than `n` elements. Empty input produces an
+ * empty chunk of chunks.
+ *
+ * **Gotchas**
+ *
+ * Values of `n` less than or equal to zero produce singleton chunks.
+ *
  * **Example** (Splitting into fixed-size chunks)
  *
  * ```ts
@@ -2150,6 +2236,8 @@ export const flatten: <S extends Chunk<Chunk<any>>>(self: S) => Chunk.Flatten<S>
  * // [[1, 2], [3, 4], [5]]
  * ```
  *
+ * @see {@link split} for splitting into a target number of chunks instead of a fixed chunk size
+ *
  * @category elements
  * @since 2.0.0
  */
@@ -2157,6 +2245,20 @@ export const chunksOf: {
   /**
    * Groups elements in chunks of up to `n` elements.
    *
+   * **When to use**
+   *
+   * Use to divide a chunk into ordered, non-overlapping batches with at most `n`
+   * elements each.
+   *
+   * **Details**
+   *
+   * The final chunk may contain fewer than `n` elements. Empty input produces an
+   * empty chunk of chunks.
+   *
+   * **Gotchas**
+   *
+   * Values of `n` less than or equal to zero produce singleton chunks.
+   *
    * **Example** (Splitting into fixed-size chunks)
    *
    * ```ts
@@ -2175,6 +2277,8 @@ export const chunksOf: {
    * // [[1, 2], [3, 4], [5]]
    * ```
    *
+   * @see {@link split} for splitting into a target number of chunks instead of a fixed chunk size
+   *
    * @category elements
    * @since 2.0.0
    */
@@ -2182,6 +2286,20 @@ export const chunksOf: {
   /**
    * Groups elements in chunks of up to `n` elements.
    *
+   * **When to use**
+   *
+   * Use to divide a chunk into ordered, non-overlapping batches with at most `n`
+   * elements each.
+   *
+   * **Details**
+   *
+   * The final chunk may contain fewer than `n` elements. Empty input produces an
+   * empty chunk of chunks.
+   *
+   * **Gotchas**
+   *
+   * Values of `n` less than or equal to zero produce singleton chunks.
+   *
    * **Example** (Splitting into fixed-size chunks)
    *
    * ```ts
@@ -2200,6 +2318,8 @@ export const chunksOf: {
    * // [[1, 2], [3, 4], [5]]
    * ```
    *
+   * @see {@link split} for splitting into a target number of chunks instead of a fixed chunk size
+   *
    * @category elements
    * @since 2.0.0
    */

package/src/Clock.ts

@@ -67,6 +67,11 @@ import * as effect from "./internal/effect.ts"
  * Represents a time-based clock which provides functionality related to time
  * and scheduling.
  *
+ * **When to use**
+ *
+ * Use to define or provide a clock service for current-time and sleep
+ * operations.
+ *
  * **Example** (Reading current time)
  *
  * ```ts
@@ -87,22 +92,44 @@ import * as effect from "./internal/effect.ts"
 export interface Clock {
   /**
    * Unsafely returns the current time in milliseconds.
+   *
+   * **When to use**
+   *
+   * Use to read millisecond time synchronously when you already have a `Clock`
+   * service and can accept non-effectful access.
    */
   currentTimeMillisUnsafe(): number
   /**
    * Returns the current time in milliseconds.
+   *
+   * **When to use**
+   *
+   * Use to read millisecond time through this `Clock` service in `Effect`.
    */
   readonly currentTimeMillis: Effect<number>
   /**
    * Unsafely returns the current time in nanoseconds.
+   *
+   * **When to use**
+   *
+   * Use to read nanosecond time synchronously when you already have a `Clock`
+   * service and can accept non-effectful access.
    */
   currentTimeNanosUnsafe(): bigint
   /**
    * Returns the current time in nanoseconds.
+   *
+   * **When to use**
+   *
+   * Use to read nanosecond time through this `Clock` service in `Effect`.
    */
   readonly currentTimeNanos: Effect<bigint>
   /**
    * Asynchronously sleeps for the specified duration.
+   *
+   * **When to use**
+   *
+   * Use to delay an `Effect` workflow by a duration through this `Clock` service.
    */
   sleep(duration: Duration.Duration): Effect<void>
 }
@@ -110,6 +137,11 @@ export interface Clock {
 /**
  * A reference to the current Clock 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.
+ *
  * **Example** (Accessing the Clock service)
  *
  * ```ts
@@ -121,6 +153,10 @@ export interface Clock {
  * })
  * ```
  *
+ * @see {@link clockWith} for using the current Clock service inside an effect
+ * @see {@link currentTimeMillis} for reading the current time in milliseconds
+ * @see {@link currentTimeNanos} for reading the current time in nanoseconds
+ *
  * @category references
  * @since 2.0.0
  */
@@ -129,6 +165,11 @@ export const Clock: Context.Reference<Clock> = effect.ClockRef
 /**
  * Accesses the current Clock service and uses it to run the provided function.
  *
+ * **When to use**
+ *
+ * Use when you need the full Clock service interface to perform multiple time
+ * operations or call unsafe variants within a single effect.
+ *
  * **Example** (Using the current Clock service)
  *
  * ```ts
@@ -143,6 +184,9 @@ export const Clock: Context.Reference<Clock> = effect.ClockRef
  * )
  * ```
  *
+ * @see {@link Clock} for the service reference
+ * @see {@link currentTimeMillis} for convenience accessor that returns milliseconds
+ * @see {@link currentTimeNanos} for convenience accessor that returns nanoseconds
  * @category constructors
  * @since 2.0.0
  */
@@ -151,6 +195,11 @@ export const clockWith: <A, E, R>(f: (clock: Clock) => Effect<A, E, R>) => Effec
 /**
  * Returns an Effect that succeeds with the current time in milliseconds.
  *
+ * **When to use**
+ *
+ * Use to read wall-clock time from the active Clock service with millisecond
+ * precision.
+ *
  * **Example** (Reading milliseconds)
  *
  * ```ts
@@ -163,6 +212,9 @@ export const clockWith: <A, E, R>(f: (clock: Clock) => Effect<A, E, R>) => Effec
  * })
  * ```
  *
+ * @see {@link currentTimeNanos} for nanosecond precision
+ * @see {@link clockWith} for accessing the full Clock service
+ *
  * @category constructors
  * @since 2.0.0
  */
@@ -171,6 +223,11 @@ export const currentTimeMillis: Effect<number> = effect.currentTimeMillis
 /**
  * Returns an Effect that succeeds with the current time in nanoseconds.
  *
+ * **When to use**
+ *
+ * Use to read wall-clock time from the active `Clock` service with nanosecond
+ * precision.
+ *
  * **Example** (Reading nanoseconds)
  *
  * ```ts