effect 4.0.0-beta.66 → 4.0.0-beta.68

package/src/Clock.ts

@@ -17,7 +17,8 @@
  * - **Testable**: Mock time control for deterministic testing
  * - **Resource-safe**: Automatic cleanup of time-based resources
  *
- * @example
+ * **Example** (Measuring elapsed time)
+ *
  * ```ts
  * import { Clock, Effect } from "effect"
  *
@@ -36,7 +37,8 @@
  * })
  * ```
  *
- * @example
+ * **Example** (Using the Clock service)
+ *
  * ```ts
  * import { Clock, Effect } from "effect"
  *
@@ -65,7 +67,8 @@ import * as effect from "./internal/effect.ts"
  * Represents a time-based clock which provides functionality related to time
  * and scheduling.
  *
- * @example
+ * **Example** (Reading current time)
+ *
  * ```ts
  * import { Clock, Effect } from "effect"
  *
@@ -78,8 +81,8 @@ import * as effect from "./internal/effect.ts"
  * })
  * ```
  *
- * @since 2.0.0
  * @category models
+ * @since 2.0.0
  */
 export interface Clock {
   /**
@@ -107,7 +110,8 @@ export interface Clock {
 /**
  * A reference to the current Clock service in the environment.
  *
- * @example
+ * **Example** (Accessing the Clock service)
+ *
  * ```ts
  * import { Clock, Effect } from "effect"
  *
@@ -118,14 +122,15 @@ export interface Clock {
  * ```
  *
  * @category references
- * @since 4.0.0
+ * @since 2.0.0
  */
 export const Clock: Context.Reference<Clock> = effect.ClockRef
 
 /**
  * Accesses the current Clock service and uses it to run the provided function.
  *
- * @example
+ * **Example** (Using the current Clock service)
+ *
  * ```ts
  * import { Clock, Effect } from "effect"
  *
@@ -146,7 +151,8 @@ 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.
  *
- * @example
+ * **Example** (Reading milliseconds)
+ *
  * ```ts
  * import { Clock, Effect } from "effect"
  *
@@ -165,7 +171,8 @@ export const currentTimeMillis: Effect<number> = effect.currentTimeMillis
 /**
  * Returns an Effect that succeeds with the current time in nanoseconds.
  *
- * @example
+ * **Example** (Reading nanoseconds)
+ *
  * ```ts
  * import { Clock, Effect } from "effect"
  *

package/src/Combiner.ts

@@ -88,7 +88,7 @@ import type * as Order from "./Order.ts"
  *
  * @see {@link make} – create a `Combiner` from a function
  *
- * @category model
+ * @category models
  * @since 4.0.0
  */
 export interface Combiner<A> {
@@ -105,10 +105,8 @@ export interface Combiner<A> {
  * - You have a custom combining operation that is not covered by the built-in
  *   constructors (`min`, `max`, `first`, `last`, `constant`).
  *
- * Behavior:
- * - Returns a new `Combiner` whose `combine` method delegates to the provided
- *   function.
- * - Pure – the returned combiner does not mutate its arguments.
+ * The returned combiner's `combine` method delegates to the provided function.
+ * Any purity, associativity, or mutation behavior comes from that function.
  *
  * **Example** (multiplying numbers)
  *
@@ -123,6 +121,7 @@ export interface Combiner<A> {
  *
  * @see {@link Combiner} – the interface this creates
  *
+ * @category constructors
  * @since 4.0.0
  */
 export function make<A>(combine: (self: A, that: A) => A): Combiner<A> {
@@ -155,6 +154,7 @@ export function make<A>(combine: (self: A, that: A) => A): Combiner<A> {
  *
  * @see {@link make}
  *
+ * @category combinators
  * @since 4.0.0
  */
 export function flip<A>(combiner: Combiner<A>): Combiner<A> {
@@ -190,6 +190,7 @@ export function flip<A>(combiner: Combiner<A>): Combiner<A> {
  *
  * @see {@link max}
  *
+ * @category constructors
  * @since 4.0.0
  */
 export function min<A>(order: Order.Order<A>): Combiner<A> {
@@ -225,6 +226,7 @@ export function min<A>(order: Order.Order<A>): Combiner<A> {
  *
  * @see {@link min}
  *
+ * @category constructors
  * @since 4.0.0
  */
 export function max<A>(order: Order.Order<A>): Combiner<A> {
@@ -256,6 +258,7 @@ export function max<A>(order: Order.Order<A>): Combiner<A> {
  *
  * @see {@link last}
  *
+ * @category constructors
  * @since 4.0.0
  */
 export function first<A>(): Combiner<A> {
@@ -286,6 +289,7 @@ export function first<A>(): Combiner<A> {
  *
  * @see {@link first}
  *
+ * @category constructors
  * @since 4.0.0
  */
 export function last<A>(): Combiner<A> {
@@ -319,6 +323,7 @@ export function last<A>(): Combiner<A> {
  * @see {@link first}
  * @see {@link last}
  *
+ * @category constructors
  * @since 4.0.0
  */
 export function constant<A>(a: A): Combiner<A> {
@@ -353,6 +358,7 @@ export function constant<A>(a: A): Combiner<A> {
  *
  * @see {@link make}
  *
+ * @category combinators
  * @since 4.0.0
  */
 export function intercalate<A>(middle: A) {

package/src/Config.ts

@@ -104,8 +104,8 @@ const TypeId = "~effect/Config"
  * console.log(Config.isConfig("not a config"))        // false
  * ```
  *
- * @since 4.0.0
- * @category Guards
+ * @category guards
+ * @since 2.0.0
  */
 export const isConfig = (u: unknown): u is Config<unknown> => Predicate.hasProperty(u, TypeId)
 
@@ -125,8 +125,8 @@ export const isConfig = (u: unknown): u is Config<unknown> => Predicate.hasPrope
  * @see {@link orElse} – recover from a ConfigError
  * @see {@link withDefault} – provide a fallback for missing-data errors
  *
+ * @category errors
  * @since 4.0.0
- * @category Models
  */
 export class ConfigError {
   readonly _tag = "ConfigError"
@@ -156,7 +156,8 @@ export class ConfigError {
  * @see {@link schema} – the main way to create a Config
  * @see {@link make} – low-level constructor
  *
- * @since 4.0.0
+ * @category models
+ * @since 2.0.0
  */
 export interface Config<out T> extends Effect.Effect<T, ConfigError> {
   readonly [TypeId]: typeof TypeId
@@ -208,7 +209,7 @@ const Proto = {
  *
  * @see {@link schema} – higher-level constructor using Schema codecs
  *
- * @category Constructors
+ * @category constructors
  * @since 4.0.0
  */
 export function make<T>(
@@ -243,8 +244,8 @@ export function make<T>(
  *
  * @see {@link mapOrFail} – when the transformation can fail
  *
- * @category Mapping
- * @since 4.0.0
+ * @category mapping
+ * @since 2.0.0
  */
 export const map: {
   /**
@@ -271,8 +272,8 @@ export const map: {
    *
    * @see {@link mapOrFail} – when the transformation can fail
    *
-   * @category Mapping
-   * @since 4.0.0
+   * @category mapping
+   * @since 2.0.0
    */
   <A, B>(f: (a: A) => B): (self: Config<A>) => Config<B>
   /**
@@ -299,8 +300,8 @@ export const map: {
    *
    * @see {@link mapOrFail} – when the transformation can fail
    *
-   * @category Mapping
-   * @since 4.0.0
+   * @category mapping
+   * @since 2.0.0
    */
   <A, B>(self: Config<A>, f: (a: A) => B): Config<B>
 } = dual(2, <A, B>(self: Config<A>, f: (a: A) => B): Config<B> => {
@@ -328,8 +329,8 @@ export const map: {
  *
  * @see {@link map} – when the transformation cannot fail
  *
- * @category Mapping
- * @since 4.0.0
+ * @category mapping
+ * @since 2.0.0
  */
 export const mapOrFail: {
   /**
@@ -353,8 +354,8 @@ export const mapOrFail: {
    *
    * @see {@link map} – when the transformation cannot fail
    *
-   * @category Mapping
-   * @since 4.0.0
+   * @category mapping
+   * @since 2.0.0
    */
   <A, B>(f: (a: A) => Effect.Effect<B, ConfigError>): (self: Config<A>) => Config<B>
   /**
@@ -378,8 +379,8 @@ export const mapOrFail: {
    *
    * @see {@link map} – when the transformation cannot fail
    *
-   * @category Mapping
-   * @since 4.0.0
+   * @category mapping
+   * @since 2.0.0
    */
   <A, B>(self: Config<A>, f: (a: A) => Effect.Effect<B, ConfigError>): Config<B>
 } = dual(2, <A, B>(self: Config<A>, f: (a: A) => Effect.Effect<B, ConfigError>): Config<B> => {
@@ -411,7 +412,8 @@ export const mapOrFail: {
  *
  * @see {@link withDefault} – fallback only on missing data
  *
- * @since 4.0.0
+ * @category combinators
+ * @since 2.0.0
  */
 export const orElse: {
   /**
@@ -439,7 +441,8 @@ export const orElse: {
    *
    * @see {@link withDefault} – fallback only on missing data
    *
-   * @since 4.0.0
+   * @category combinators
+   * @since 2.0.0
    */
   <A2>(that: (error: ConfigError) => Config<A2>): <A>(self: Config<A>) => Config<A2 | A>
   /**
@@ -467,7 +470,8 @@ export const orElse: {
    *
    * @see {@link withDefault} – fallback only on missing data
    *
-   * @since 4.0.0
+   * @category combinators
+   * @since 2.0.0
    */
   <A, A2>(self: Config<A>, that: (error: ConfigError) => Config<A2>): Config<A | A2>
 } = dual(2, <A, A2>(self: Config<A>, that: (error: ConfigError) => Config<A2>): Config<A | A2> => {
@@ -498,7 +502,8 @@ export const orElse: {
  * // { host: "localhost", port: 5432 }
  * ```
  *
- * @since 4.0.0
+ * @category combinators
+ * @since 2.0.0
  */
 export function all<const Arg extends Iterable<Config<any>> | Record<string, Config<any>>>(
   arg: Arg
@@ -576,7 +581,8 @@ function isMissingDataOnly(issue: Issue.Issue): boolean {
  * @see {@link option} – returns `Option` instead of a default value
  * @see {@link orElse} – catches all errors, not just missing data
  *
- * @since 4.0.0
+ * @category combinators
+ * @since 2.0.0
  */
 export const withDefault: {
   /**
@@ -605,7 +611,8 @@ export const withDefault: {
    * @see {@link option} – returns `Option` instead of a default value
    * @see {@link orElse} – catches all errors, not just missing data
    *
-   * @since 4.0.0
+   * @category combinators
+   * @since 2.0.0
    */
   <const A2>(defaultValue: A2): <A>(self: Config<A>) => Config<A2 | A>
   /**
@@ -634,7 +641,8 @@ export const withDefault: {
    * @see {@link option} – returns `Option` instead of a default value
    * @see {@link orElse} – catches all errors, not just missing data
    *
-   * @since 4.0.0
+   * @category combinators
+   * @since 2.0.0
    */
   <A, const A2>(self: Config<A>, defaultValue: A2): Config<A | A2>
 } = dual(2, <A, const A2>(self: Config<A>, defaultValue: A2): Config<A | A2> => {
@@ -673,13 +681,17 @@ export const withDefault: {
  *
  * @see {@link withDefault} – provide a concrete fallback value instead
  *
- * @since 4.0.0
+ * @category combinators
+ * @since 2.0.0
  */
 export const option = <A>(self: Config<A>): Config<Option.Option<A>> =>
   self.pipe(map(Option.some), withDefault(Option.none()))
 
 /**
- * @since 3.0.0
+ * Extracts the successfully parsed value type from a `Config`.
+ *
+ * @category utility types
+ * @since 2.5.0
  */
 export type Success<T> = [T] extends [Config<infer A>] ? A : never
 
@@ -696,7 +708,7 @@ export type Success<T> = [T] extends [Config<infer A>] ? A : never
  * @see {@link unwrap} – construct a `Config` from a `Wrap<T>`
  *
  * @category Wrap
- * @since 4.0.0
+ * @since 2.0.0
  */
 export type Wrap<A> = [NonNullable<A>] extends [infer T] ? [IsPlainObject<T>] extends [true] ?
       | { readonly [K in keyof A]: Wrap<A[K]> }
@@ -734,7 +746,7 @@ type IsPlainObject<A> = [A] extends [Record<string, any>]
  * @see {@link Wrap} – the utility type accepted by this function
  *
  * @category Wrap
- * @since 4.0.0
+ * @since 2.0.0
  */
 export const unwrap = <T>(wrapped: Wrap<T>): Config<T> => {
   if (isConfig(wrapped)) return wrapped
@@ -881,7 +893,7 @@ const recur: (
  * @see {@link string} / {@link number} / {@link boolean} – shortcuts for
  *   single-value configs
  *
- * @category Schema
+ * @category schemas
  * @since 4.0.0
  */
 export function schema<T, E>(codec: Schema.Codec<T, E>, path?: string | ConfigProvider.Path): Config<T> {
@@ -922,7 +934,7 @@ export const FalseValues = Schema.Literals(["false", "no", "off", "0", "n"])
  *
  * @see {@link boolean} – convenience constructor
  *
- * @category Schema
+ * @category schemas
  * @since 4.0.0
  */
 export const Boolean = Schema.Literals([...TrueValues.literals, ...FalseValues.literals]).pipe(
@@ -944,7 +956,7 @@ export const Boolean = Schema.Literals([...TrueValues.literals, ...FalseValues.l
  *
  * @see {@link port} – convenience constructor
  *
- * @category Schema
+ * @category schemas
  * @since 4.0.0
  */
 export const Port = Schema.Int.check(Schema.isBetween({ minimum: 1, maximum: 65535 }))
@@ -961,7 +973,7 @@ export const Port = Schema.Int.check(Schema.isBetween({ minimum: 1, maximum: 655
  *
  * @see {@link logLevel} – convenience constructor
  *
- * @category Schema
+ * @category schemas
  * @since 4.0.0
  */
 export const LogLevel = Schema.Literals(LogLevel_.values)
@@ -1001,7 +1013,7 @@ export const LogLevel = Schema.Literals(LogLevel_.values)
  * // }
  * ```
  *
- * @category Schemas
+ * @category schemas
  * @since 4.0.0
  */
 export const Record = <K extends Schema.Record.Key, V extends Schema.Top>(key: K, value: V, options?: {
@@ -1031,8 +1043,8 @@ export const Record = <K extends Schema.Record.Key, V extends Schema.Top>(key: K
  * - Inside {@link orElse} to re-raise a specific error.
  * - Testing error handling paths.
  *
- * @category Constructors
- * @since 4.0.0
+ * @category constructors
+ * @since 2.0.0
  */
 export function fail(err: SourceError | Schema.SchemaError) {
   return make(() => Effect.fail(new ConfigError(err)))
@@ -1056,8 +1068,8 @@ export function fail(err: SourceError | Schema.SchemaError) {
  * )
  * ```
  *
- * @category Constructors
- * @since 4.0.0
+ * @category constructors
+ * @since 2.0.0
  */
 export function succeed<T>(value: T) {
   return make(() => Effect.succeed(value))
@@ -1085,8 +1097,8 @@ export function succeed<T>(value: T) {
  * @see {@link nonEmptyString} – rejects empty strings
  * @see {@link schema} – for more complex types
  *
- * @category Constructors
- * @since 4.0.0
+ * @category constructors
+ * @since 2.0.0
  */
 export function string(name?: string) {
   return schema(Schema.String, name)
@@ -1100,8 +1112,8 @@ export function string(name?: string) {
  *
  * @see {@link string} – allows empty strings
  *
- * @category Constructors
- * @since 4.0.0
+ * @category constructors
+ * @since 3.7.0
  */
 export function nonEmptyString(name?: string) {
   return schema(Schema.NonEmptyString, name)
@@ -1115,8 +1127,8 @@ export function nonEmptyString(name?: string) {
  * @see {@link finite} – rejects `NaN` and `Infinity`
  * @see {@link int} – only integers
  *
- * @category Constructors
- * @since 4.0.0
+ * @category constructors
+ * @since 2.0.0
  */
 export function number(name?: string) {
   return schema(Schema.Number, name)
@@ -1130,7 +1142,7 @@ export function number(name?: string) {
  * @see {@link number} – allows `NaN` and `Infinity`
  * @see {@link int} – only integers
  *
- * @category Constructors
+ * @category constructors
  * @since 4.0.0
  */
 export function finite(name?: string) {
@@ -1145,7 +1157,7 @@ export function finite(name?: string) {
  * @see {@link number} – allows any number
  * @see {@link port} – integers in 1–65535
  *
- * @category Constructors
+ * @category constructors
  * @since 4.0.0
  */
 export function int(name?: string) {
@@ -1165,8 +1177,8 @@ export function int(name?: string) {
  * const env = Config.literal("production", "ENV")
  * ```
  *
- * @category Constructors
- * @since 4.0.0
+ * @category constructors
+ * @since 2.0.0
  */
 export function literal<L extends AST.LiteralValue>(literal: L, name?: string) {
   return schema(Schema.Literal(literal), name)
@@ -1185,7 +1197,7 @@ export function literal<L extends AST.LiteralValue>(literal: L, name?: string) {
  * const env = Config.literals(["development", "production"], "ENV")
  * ```
  *
- * @category Constructors
+ * @category constructors
  * @since 4.0.0
  */
 export function literals<const L extends ReadonlyArray<AST.LiteralValue>>(literals: L, name?: string) {
@@ -1223,8 +1235,8 @@ export function literals<const L extends ReadonlyArray<AST.LiteralValue>>(litera
  * // Output: true
  * ```
  *
- * @category Constructors
- * @since 4.0.0
+ * @category constructors
+ * @since 2.0.0
  */
 export function boolean(name?: string) {
   return schema(Boolean, name)
@@ -1261,8 +1273,8 @@ export function boolean(name?: string) {
  * // Output: Duration { _tag: "millis", value: 10000 }
  * ```
  *
- * @category Constructors
- * @since 4.0.0
+ * @category constructors
+ * @since 2.5.0
  */
 export function duration(name?: string) {
   return schema(Schema.DurationFromString, name)
@@ -1295,8 +1307,8 @@ export function duration(name?: string) {
  * // Output: 8080
  * ```
  *
- * @category Constructors
- * @since 4.0.0
+ * @category constructors
+ * @since 3.16.0
  */
 export function port(name?: string) {
   return schema(Port, name)
@@ -1332,8 +1344,8 @@ export function port(name?: string) {
  * // Output: "Info"
  * ```
  *
- * @category Constructors
- * @since 4.0.0
+ * @category constructors
+ * @since 2.0.0
  */
 export function logLevel(name?: string) {
   return schema(LogLevel, name)
@@ -1367,8 +1379,8 @@ export function logLevel(name?: string) {
  * // Output: <redacted>
  * ```
  *
- * @category Constructors
- * @since 4.0.0
+ * @category constructors
+ * @since 2.0.0
  */
 export function redacted(name?: string) {
   return schema(Schema.Redacted(Schema.String), name)
@@ -1415,8 +1427,8 @@ export function redacted(name?: string) {
  * // }
  * ```
  *
- * @category Constructors
- * @since 4.0.0
+ * @category constructors
+ * @since 3.11.0
  */
 export function url(name?: string) {
   return schema(Schema.URL, name)
@@ -1441,8 +1453,8 @@ export function url(name?: string) {
  * // Date("2024-01-15T00:00:00.000Z")
  * ```
  *
- * @category Constructors
- * @since 4.0.0
+ * @category constructors
+ * @since 2.0.0
  */
 export function date(name?: string) {
   return schema(Schema.DateValid, name)
@@ -1496,8 +1508,8 @@ export function date(name?: string) {
  * @see {@link all} – combine multiple configs into a struct
  * @see {@link schema} – read structured config from a schema
  *
- * @category Combinators
- * @since 4.0.0
+ * @category combinators
+ * @since 2.0.0
  */
 export const nested: {
   /**
@@ -1548,8 +1560,8 @@ export const nested: {
    * @see {@link all} – combine multiple configs into a struct
    * @see {@link schema} – read structured config from a schema
    *
-   * @category Combinators
-   * @since 4.0.0
+   * @category combinators
+   * @since 2.0.0
    */
   (name: string): <A>(self: Config<A>) => Config<A>
   /**
@@ -1600,8 +1612,8 @@ export const nested: {
    * @see {@link all} – combine multiple configs into a struct
    * @see {@link schema} – read structured config from a schema
    *
-   * @category Combinators
-   * @since 4.0.0
+   * @category combinators
+   * @since 2.0.0
    */
   <A>(self: Config<A>, name: string): Config<A>
 } = dual(