effect 4.0.0-beta.69 → 4.0.0-beta.70

package/src/Console.ts

@@ -81,10 +81,7 @@ import * as effect from "./internal/effect.ts"
 import type { Scope } from "./Scope.ts"
 
 /**
- * Represents a console interface for logging and debugging operations.
- *
- * Provides methods for various console operations including logging, debugging,
- * timing, and grouping output.
+ * Represents a console interface for logging, debugging, timing, and grouping output.
  *
  * @category models
  * @since 2.0.0
@@ -112,10 +109,7 @@ export interface Console {
 }
 
 /**
- * A reference to the current console service in the Effect system.
- *
- * This reference allows you to access the current console implementation
- * from within the Effect context.
+ * A reference to the current console service in the Effect system, allowing access to the active console implementation from within the Effect context.
  *
  * **Example** (Accessing the current console)
  *
@@ -135,10 +129,7 @@ export interface Console {
 export const Console: Context.Reference<Console> = effect.ConsoleRef
 
 /**
- * Creates an Effect that provides access to the current console instance.
- *
- * This function allows you to access the console service and perform operations
- * with it within an Effect context.
+ * Creates an Effect that provides access to the current console service and lets you perform operations with it within an Effect context.
  *
  * **Example** (Using the current console service)
  *
@@ -160,10 +151,7 @@ export const consoleWith = <A, E, R>(f: (console: Console) => Effect.Effect<A, E
   core.withFiber((fiber) => f(fiber.getRef(Console)))
 
 /**
- * Writes an assertion message to the console if the condition is false.
- *
- * If the condition is true, nothing happens. If the condition is false,
- * the message is logged to the console as an error.
+ * Writes the supplied assertion message to the console as an error when `condition` is false; when `condition` is true, no console output is produced.
  *
  * **Example** (Logging failed assertions)
  *
@@ -187,9 +175,7 @@ export const assert = (condition: boolean, ...args: ReadonlyArray<any>): Effect.
   )
 
 /**
- * Clears the console.
- *
- * This function clears all previously logged messages from the console.
+ * Clears all previously logged messages from the console.
  *
  * **Example** (Clearing console output)
  *
@@ -213,10 +199,7 @@ export const clear: Effect.Effect<void> = consoleWith((console) =>
 )
 
 /**
- * Logs the number of times that this particular call to count has been called.
- *
- * This function maintains a counter for each unique label and increments it
- * each time count is called with that label.
+ * Logs and increments the counter associated with `label`, using the console's default counter when no label is provided.
  *
  * **Example** (Counting repeated calls)
  *
@@ -241,10 +224,7 @@ export const count = (label?: string): Effect.Effect<void> =>
   )
 
 /**
- * Resets the counter for the given label.
- *
- * This function resets the counter associated with the specified label
- * back to zero.
+ * Resets the counter associated with the specified label back to zero.
  *
  * **Example** (Resetting a counter)
  *
@@ -273,6 +253,7 @@ export const countReset = (label?: string): Effect.Effect<void> =>
  * Writes a debug message through the current `Console` service.
  *
  * **Details**
+ *
  * The arguments are passed to the service's `debug` method when the returned
  * Effect is executed. Any filtering behavior depends on the active console
  * implementation.
@@ -299,10 +280,7 @@ export const debug = (...args: ReadonlyArray<any>): Effect.Effect<void> =>
   )
 
 /**
- * Displays an interactive list of the properties of the specified object.
- *
- * This function provides a detailed view of an object's properties,
- * which can be useful for debugging complex data structures.
+ * Displays an interactive list of the properties of the specified object, optionally using console-specific inspection options for debugging complex data structures.
  *
  * **Example** (Inspecting an object)
  *
@@ -327,9 +305,7 @@ export const dir = (item: any, options?: any): Effect.Effect<void> =>
   )
 
 /**
- * Displays an interactive tree of the descendant elements of the specified XML/HTML element.
- *
- * This function is particularly useful for inspecting DOM elements in browser environments.
+ * Displays an interactive tree of descendant XML or HTML elements, which is particularly useful for inspecting DOM elements in browser environments.
  *
  * **Example** (Inspecting XML-like data)
  *
@@ -355,10 +331,7 @@ export const dirxml = (...args: ReadonlyArray<any>): Effect.Effect<void> =>
   )
 
 /**
- * Outputs an error message to the console.
- *
- * This function logs messages at the error level, typically displayed
- * in red or with an error icon in most console implementations.
+ * Outputs an error-level message to the console, typically displayed with error styling by the active console implementation.
  *
  * **Example** (Writing error messages)
  *
@@ -385,10 +358,7 @@ export const error = (...args: ReadonlyArray<any>): Effect.Effect<void> =>
   )
 
 /**
- * Creates a new inline group in the console and returns a scoped Effect.
- *
- * This function creates a collapsible group of console messages. The group
- * is automatically closed when the Effect's scope is finalized.
+ * Creates a scoped console group, optionally collapsed and labeled, and closes it automatically when the Effect scope is finalized.
  *
  * **Example** (Grouping scoped output)
  *
@@ -430,10 +400,7 @@ export const group = (
   )
 
 /**
- * Outputs an informational message to the console.
- *
- * This function logs messages at the info level, typically displayed
- * with an info icon in most console implementations.
+ * Outputs an informational message to the console, typically displayed with info styling by the active console implementation.
  *
  * **Example** (Writing informational messages)
  *
@@ -460,9 +427,7 @@ export const info = (...args: ReadonlyArray<any>): Effect.Effect<void> =>
   )
 
 /**
- * Outputs a message to the console.
- *
- * This is the most commonly used console method for general purpose logging.
+ * Outputs a general-purpose message to the console for ordinary logging.
  *
  * **Example** (Writing log messages)
  *
@@ -487,10 +452,7 @@ export const log = (...args: ReadonlyArray<any>): Effect.Effect<void> =>
   )
 
 /**
- * Displays tabular data as a table in the console.
- *
- * This function takes tabular data and displays it in a formatted table,
- * making it easier to read structured data.
+ * Displays tabular data as a formatted table in the console, optionally limited to selected properties.
  *
  * **Example** (Displaying tabular data)
  *
@@ -519,10 +481,7 @@ export const table = (tabularData: any, properties?: ReadonlyArray<string>): Eff
   )
 
 /**
- * Starts a timer that can be used to compute the duration of an operation.
- *
- * This function returns a scoped Effect that starts a timer when entered
- * and automatically ends the timer when the scope is finalized.
+ * Starts a scoped timer for `label` and automatically ends it when the Effect scope is finalized.
  *
  * **Example** (Timing scoped work)
  *
@@ -558,10 +517,7 @@ export const time = (label?: string | undefined): Effect.Effect<void, never, Sco
   )
 
 /**
- * Logs the current value of a timer that was previously started by calling time.
- *
- * This function logs the elapsed time for a timer without stopping it,
- * allowing you to track progress of long-running operations.
+ * Logs the elapsed time for an existing timer without stopping it, allowing progress reports for long-running operations.
  *
  * **Example** (Logging timer progress)
  *
@@ -592,10 +548,7 @@ export const timeLog = (label?: string, ...args: ReadonlyArray<any>): Effect.Eff
   )
 
 /**
- * Outputs a stack trace to the console.
- *
- * This function logs the current stack trace, which is useful for debugging
- * to understand how the current point in the code was reached.
+ * Outputs the current stack trace to the console to show how the current point in the code was reached.
  *
  * **Example** (Writing stack traces)
  *
@@ -619,10 +572,7 @@ export const trace = (...args: ReadonlyArray<any>): Effect.Effect<void> =>
   )
 
 /**
- * Outputs a warning message to the console.
- *
- * This function logs messages at the warning level, typically displayed
- * in yellow or with a warning icon in most console implementations.
+ * Outputs a warning-level message to the console, typically displayed with warning styling by the active console implementation.
  *
  * **Example** (Writing warning messages)
  *
@@ -648,11 +598,7 @@ export const warn = (...args: ReadonlyArray<any>): Effect.Effect<void> =>
   )
 
 /**
- * Wraps an Effect with a console group.
- *
- * This function creates a console group around the execution of an Effect,
- * automatically starting the group before the Effect runs and ending it
- * after the Effect completes.
+ * Runs an Effect inside an optionally labeled or collapsed console group, starting the group before execution and ending it after the Effect completes.
  *
  * **Example** (Wrapping an effect in a group)
  *
@@ -676,11 +622,7 @@ export const warn = (...args: ReadonlyArray<any>): Effect.Effect<void> =>
  */
 export const withGroup = dual<
   /**
-   * Wraps an Effect with a console group.
-   *
-   * This function creates a console group around the execution of an Effect,
-   * automatically starting the group before the Effect runs and ending it
-   * after the Effect completes.
+   * Runs an Effect inside an optionally labeled or collapsed console group, starting the group before execution and ending it after the Effect completes.
    *
    * **Example** (Wrapping an effect in a group)
    *
@@ -709,11 +651,7 @@ export const withGroup = dual<
     }
   ) => <A, E, R>(self: Effect.Effect<A, E, R>) => Effect.Effect<A, E, R>,
   /**
-   * Wraps an Effect with a console group.
-   *
-   * This function creates a console group around the execution of an Effect,
-   * automatically starting the group before the Effect runs and ending it
-   * after the Effect completes.
+   * Runs an Effect inside an optionally labeled or collapsed console group, starting the group before execution and ending it after the Effect completes.
    *
    * **Example** (Wrapping an effect in a group)
    *
@@ -761,11 +699,7 @@ export const withGroup = dual<
   ))
 
 /**
- * Wraps an Effect with a timer.
- *
- * This function measures the execution time of an Effect, automatically
- * starting a timer before the Effect runs and logging the elapsed time
- * after the Effect completes.
+ * Runs an Effect with a console timer, starting the timer before execution and ending it after the Effect completes.
  *
  * **Example** (Timing an effect)
  *
@@ -788,11 +722,7 @@ export const withGroup = dual<
  */
 export const withTime = dual<
   /**
-   * Wraps an Effect with a timer.
-   *
-   * This function measures the execution time of an Effect, automatically
-   * starting a timer before the Effect runs and logging the elapsed time
-   * after the Effect completes.
+   * Runs an Effect with a console timer, starting the timer before execution and ending it after the Effect completes.
    *
    * **Example** (Timing an effect)
    *
@@ -815,11 +745,7 @@ export const withTime = dual<
    */
   (label?: string) => <A, E, R>(self: Effect.Effect<A, E, R>) => Effect.Effect<A, E, R>,
   /**
-   * Wraps an Effect with a timer.
-   *
-   * This function measures the execution time of an Effect, automatically
-   * starting a timer before the Effect runs and logging the elapsed time
-   * after the Effect completes.
+   * Runs an Effect with a console timer, starting the timer before execution and ending it after the Effect completes.
    *
    * **Example** (Timing an effect)
    *

package/src/Context.ts

@@ -543,7 +543,7 @@ export interface Context<in Services> extends Equal.Equal, Pipeable, Inspectable
  * Creates a `Context` from an existing service map without validating or
  * copying it.
  *
- * **Notes**
+ * **Gotchas**
  *
  * This is unsafe because later mutation of the provided map can affect the
  * created `Context`. Prefer `empty`, `make`, `add`, or `merge` for normal
@@ -969,7 +969,7 @@ export const getOrElse: {
  * Returns the service currently stored for a key, or `undefined` when the key
  * is absent.
  *
- * **Notes**
+ * **Details**
  *
  * This is a raw lookup and does not resolve default values for
  * `Context.Reference` keys.
@@ -982,7 +982,7 @@ export const getOrUndefined: {
    * Returns the service currently stored for a key, or `undefined` when the key
    * is absent.
    *
-   * **Notes**
+   * **Details**
    *
    * This is a raw lookup and does not resolve default values for
    * `Context.Reference` keys.
@@ -995,7 +995,7 @@ export const getOrUndefined: {
    * Returns the service currently stored for a key, or `undefined` when the key
    * is absent.
    *
-   * **Notes**
+   * **Details**
    *
    * This is a raw lookup and does not resolve default values for
    * `Context.Reference` keys.

package/src/Cron.ts

@@ -66,9 +66,11 @@ const TypeId = "~effect/time/Cron"
 /**
  * Represents a cron schedule with time constraints and timezone information.
  *
- * A Cron instance defines when a scheduled task should run, supporting
- * seconds, minutes, hours, days, months, and weekdays constraints.
- * It also supports timezone-aware scheduling.
+ * **Details**
+ *
+ * A `Cron` instance defines when a scheduled task should run, supporting
+ * seconds, minutes, hours, days, months, and weekday constraints. It also
+ * supports timezone-aware scheduling.
  *
  * **Example** (Creating a cron schedule)
  *
@@ -229,6 +231,8 @@ const CronProto = {
 /**
  * Checks if a given value is a Cron instance.
  *
+ * **Details**
+ *
  * This function is a type guard that determines whether the provided
  * value is a valid Cron instance by checking for the presence of the
  * Cron type identifier.
@@ -259,6 +263,8 @@ export const isCron = (u: unknown): u is Cron => hasProperty(u, TypeId)
 /**
  * Creates a Cron instance from time constraints.
  *
+ * **Details**
+ *
  * Constructs a cron schedule by specifying which seconds, minutes, hours,
  * days, months, and weekdays the schedule should match. Empty arrays mean
  * "match all" for that time unit.
@@ -456,9 +462,10 @@ const CronParseErrorTypeId = "~effect/time/Cron/CronParseError"
 /**
  * Represents an error that occurs when parsing a cron expression fails.
  *
- * This error provides detailed information about what went wrong during
- * the parsing process, including the error message and optionally the
- * input that caused the error.
+ * **Details**
+ *
+ * This error provides information about what went wrong during parsing,
+ * including the error message and optionally the input that caused the error.
  *
  * **Example** (Handling cron parse failures)
  *
@@ -486,6 +493,8 @@ export class CronParseError extends Data.TaggedError("CronParseError")<{
 /**
  * Checks if a given value is a CronParseError instance.
  *
+ * **Details**
+ *
  * This function is a type guard that determines whether the provided
  * value is a CronParseError by checking for the presence of the
  * CronParseError type identifier.
@@ -514,6 +523,8 @@ export const isCronParseError = (u: unknown): u is CronParseError => hasProperty
  * Parses a cron expression into a `Cron` instance, returning a `Result` instead
  * of throwing.
  *
+ * **Details**
+ *
  * The expression may contain five fields, where seconds default to `0`, or six
  * fields including seconds. Fields support `*`, comma-separated values, ranges,
  * steps, and month or weekday aliases. Invalid expressions fail with
@@ -572,11 +583,12 @@ export const parse = (cron: string, tz?: DateTime.TimeZone | string): Result.Res
 }
 
 /**
- * Parses a cron expression into a Cron instance, throwing on failure.
+ * Parses a cron expression into a `Cron` instance, throwing on failure.
+ *
+ * **When to use**
  *
- * This function provides a convenience method for parsing cron expressions
- * when you're confident the input is valid and want to avoid handling
- * the Result type.
+ * Use this when the input is expected to be valid and you want to avoid
+ * handling the `Result` type.
  *
  * **Example** (Parsing cron expressions unsafely)
  *
@@ -601,6 +613,8 @@ export const parseUnsafe = (cron: string, tz?: DateTime.TimeZone | string): Cron
 /**
  * Returns `true` when a date/time matches a `Cron` schedule.
  *
+ * **Details**
+ *
  * Seconds, minutes, hours, months, and the optional timezone are checked
  * directly. For day constraints, an empty `days` or `weekdays` set means that
  * field matches every value; when both sets are non-empty, a date matches if
@@ -669,9 +683,11 @@ const daysInMonth = (date: Date): number =>
 /**
  * Returns the next scheduled date/time for the given Cron instance.
  *
- * This function calculates the next date and time when the cron schedule
- * should trigger, starting from the specified date (or current time if
- * not provided).
+ * **Details**
+ *
+ * Searches for the next date and time when the cron schedule should trigger,
+ * starting after the specified date/time or after the current time when no
+ * date is provided.
  *
  * **Example** (Finding the next occurrence)
  *
@@ -864,9 +880,11 @@ const stepCron = (cron: Cron, now: DateTime.DateTime.Input | undefined, directio
 /**
  * Returns an infinite iterator that yields dates matching the Cron schedule.
  *
- * This function creates an iterator that generates an infinite sequence
- * of dates when the cron schedule should trigger, starting from the
- * specified date.
+ * **Details**
+ *
+ * The iterator generates an infinite sequence of dates when the cron schedule
+ * should trigger, starting after the specified date/time or after the current
+ * time when no date is provided.
  *
  * **Example** (Iterating scheduled occurrences)
  *
@@ -896,6 +914,8 @@ export const sequence = function*(cron: Cron, now?: DateTime.DateTime.Input): It
  * An `Equivalence` instance for comparing the field restrictions of two `Cron`
  * schedules.
  *
+ * **Details**
+ *
  * This comparison checks seconds, minutes, hours, days, months, and weekdays.
  * It does not compare the optional timezone.
  *
@@ -942,6 +962,8 @@ const restrictionsEquals = (self: ReadonlySet<number>, that: ReadonlySet<number>
 /**
  * Checks whether two `Cron` instances have the same field restrictions.
  *
+ * **Details**
+ *
  * The comparison checks seconds, minutes, hours, days, months, and weekdays.
  * It does not compare the optional timezone.
  *
@@ -977,6 +999,8 @@ export const equals: {
   /**
    * Checks whether two `Cron` instances have the same field restrictions.
    *
+   * **Details**
+   *
    * The comparison checks seconds, minutes, hours, days, months, and weekdays.
    * It does not compare the optional timezone.
    *
@@ -1012,6 +1036,8 @@ export const equals: {
   /**
    * Checks whether two `Cron` instances have the same field restrictions.
    *
+   * **Details**
+   *
    * The comparison checks seconds, minutes, hours, days, months, and weekdays.
    * It does not compare the optional timezone.
    *

package/src/Crypto.ts

@@ -62,6 +62,8 @@ const TypeId = "~effect/platform/Crypto"
 /**
  * Digest algorithms supported by the platform `Crypto` service.
  *
+ * **Gotchas**
+ *
  * SHA-1 is included for interoperability with existing protocols. Do not use
  * SHA-1 for new security-sensitive designs.
  *
@@ -81,6 +83,8 @@ export type DigestAlgorithm = "SHA-1" | "SHA-256" | "SHA-384" | "SHA-512"
 /**
  * Platform-agnostic cryptographic operations.
  *
+ * **Details**
+ *
  * `Crypto` implementations must use cryptographically secure platform APIs.
  * The random generator helpers are derived by the `make` constructor from
  * the random methods on this service.
@@ -166,6 +170,8 @@ export interface Crypto {
   /**
    * Generates a cryptographically secure random integer between `min` and `max`.
    *
+   * **Details**
+   *
    * The lower bound is rounded up with `Math.ceil` and the upper bound is
    * rounded down with `Math.floor`. By default the range is inclusive; set
    * `options.halfOpen: true` to exclude the upper bound.