effect 4.0.0-beta.66 → 4.0.0-beta.67

package/src/Option.ts

@@ -70,7 +70,6 @@
  * - {@link gen} for generator-based syntax
  *
  * @since 2.0.0
- * @module
  */
 import * as Combiner from "./Combiner.ts"
 import * as Equal from "./Equal.ts"
@@ -106,23 +105,6 @@ const TypeId = "~effect/data/Option"
  * - Returning from partial functions (not defined for all inputs)
  * - Managing optional fields in data structures
  *
- * **Example** (Creating and matching Options)
- *
- * ```ts
- * import { Option } from "effect"
- *
- * const someValue: Option.Option<number> = Option.some(42)
- * const noneValue: Option.Option<number> = Option.none()
- *
- * const result = Option.match(someValue, {
- *   onNone: () => "No value",
- *   onSome: (value) => `Value is ${value}`
- * })
- *
- * console.log(result)
- * // Output: "Value is 42"
- * ```
- *
  * @see {@link some} for creating a `Some`
  * @see {@link none} for creating a `None`
  * @see {@link match} for pattern matching
@@ -164,8 +146,11 @@ export interface None<out A> extends Pipeable, Inspectable {
 }
 
 /**
+ * Iterator protocol used to yield an `Option` inside {@link gen}, returning the
+ * contained value type back to the generator.
+ *
+ * @category Generators
  * @since 4.0.0
- * @category Models
  */
 export interface OptionIterator<T extends Option<any>> {
   next(
@@ -208,8 +193,11 @@ export interface Some<out A> extends Pipeable, Inspectable {
 }
 
 /**
- * Internal unification interface for `Option` types. Used by the Effect
- * library's type system for type-level operations.
+ * Type-level unification support for `Option` values.
+ *
+ * This is used by Effect's `Unify` machinery to preserve the contained value
+ * type when generic code returns or combines `Option` values. Users normally
+ * do not need to reference this interface directly.
  *
  * @category Models
  * @since 2.0.0
@@ -221,19 +209,6 @@ export interface OptionUnify<A extends { [Unify.typeSymbol]?: any }> {
 /**
  * Namespace containing utility types for `Option`.
  *
- * **Example** (Extracting the value type)
- *
- * ```ts
- * import type { Option } from "effect"
- *
- * declare const myOption: Option.Option<string>
- *
- * //      ┌─── string
- * //      ▼
- * type MyType = Option.Option.Value<typeof myOption>
- * ```
- *
- * @category Namespaces
  * @since 2.0.0
  */
 export declare namespace Option {
@@ -252,14 +227,17 @@ export declare namespace Option {
    * type MyType = Option.Option.Value<typeof myOption>
    * ```
    *
-   * @since 2.0.0
    * @category Type-level Utils
+   * @since 2.0.0
    */
   export type Value<T extends Option<any>> = [T] extends [Option<infer _A>] ? _A : never
 }
 
 /**
- * Internal interface for type unification ignore behavior.
+ * Marker interface used by Effect's `Unify` machinery for `Option` values.
+ *
+ * This supports type-level unification behavior for `Option`. Users normally
+ * do not need to reference this interface directly.
  *
  * @category Models
  * @since 2.0.0
@@ -642,14 +620,14 @@ export const fromIterable = <A>(collection: Iterable<A>): Option<A> => {
 /**
  * Converts a `Result` into an `Option`, keeping only the success value.
  *
- * **When to use**
+ * **When to Use**
  *
- * - Discarding the error channel when you only care about success
+ * - Discarding the failure channel when you only care about success
  *
- * **Behavior**
+ * **Details**
  *
- * - `Ok` → `Some` with the success value
- * - `Err` → `None` (error is discarded)
+ * - `Success` becomes `Some` with the success value
+ * - `Failure` becomes `None` and the failure value is discarded
  *
  * **Example** (Extracting the success side)
  *
@@ -671,16 +649,16 @@ export const fromIterable = <A>(collection: Iterable<A>): Option<A> => {
 export const getSuccess: <A, E>(self: Result<A, E>) => Option<A> = result.getSuccess
 
 /**
- * Converts a `Result` into an `Option`, keeping only the error value.
+ * Converts a `Result` into an `Option`, keeping only the failure value.
  *
- * **When to use**
+ * **When to Use**
  *
- * - Extracting the error when you don't need the success channel
+ * - Extracting the failure when you do not need the success value
  *
- * **Behavior**
+ * **Details**
  *
- * - `Err` → `Some` with the error value
- * - `Ok` → `None` (success value is discarded)
+ * - `Failure` becomes `Some` with the failure value
+ * - `Success` becomes `None` and the success value is discarded
  *
  * **Example** (Extracting the failure side)
  *
@@ -4716,6 +4694,7 @@ export const gen: Gen.Gen<OptionTypeLambda> = (...args) => {
  *
  * @see {@link makeReducerFailFast} for fail-fast semantics
  *
+ * @category Reducer
  * @since 4.0.0
  */
 export function makeReducer<A>(combiner: Combiner.Combiner<A>): Reducer.Reducer<Option<A>> {
@@ -4755,6 +4734,7 @@ export function makeReducer<A>(combiner: Combiner.Combiner<A>): Reducer.Reducer<
  *
  * @see {@link makeReducerFailFast} to get a full `Reducer`
  *
+ * @category Combiner
  * @since 4.0.0
  */
 export function makeCombinerFailFast<A>(combiner: Combiner.Combiner<A>): Combiner.Combiner<Option<A>> {
@@ -4795,6 +4775,7 @@ export function makeCombinerFailFast<A>(combiner: Combiner.Combiner<A>): Combine
  * @see {@link makeCombinerFailFast} for just the combiner
  * @see {@link makeReducer} for non-fail-fast semantics
  *
+ * @category Reducer
  * @since 4.0.0
  */
 export function makeReducerFailFast<A>(reducer: Reducer.Reducer<A>): Reducer.Reducer<Option<A>> {

package/src/Ordering.ts

@@ -1,29 +1,39 @@
 /**
- * @fileoverview
- * The Ordering module provides utilities for working with comparison results and ordering operations.
- * An Ordering represents the result of comparing two values, expressing whether the first value is
- * less than (-1), equal to (0), or greater than (1) the second value.
- *
- * This module is fundamental for building comparison functions, sorting algorithms, and implementing
- * ordered data structures. It provides composable operations for combining multiple comparison results
- * and pattern matching on ordering outcomes.
- *
- * Key Features:
- * - Type-safe representation of comparison results (-1, 0, 1)
- * - Composable operations for combining multiple orderings
- * - Pattern matching utilities for handling different ordering cases
- * - Ordering reversal and combination functions
- * - Integration with Effect's functional programming patterns
- *
- * Common Use Cases:
- * - Implementing custom comparison functions
- * - Building complex sorting criteria
- * - Combining multiple comparison results
- * - Creating ordered data structures
- * - Pattern matching on comparison outcomes
+ * The `Ordering` module provides the standard representation for the result of
+ * comparing two values. An `Ordering` is one of three numeric literals: `-1`
+ * when the first value is less than the second, `0` when both values compare as
+ * equal, and `1` when the first value is greater than the second.
+ *
+ * **Mental model**
+ *
+ * - `Ordering` describes the relationship between two compared values, not the
+ *   values themselves
+ * - Negative means "less than", zero means "equal", and positive means "greater
+ *   than"
+ * - Unlike JavaScript comparators, this type is normalized to exactly `-1`, `0`,
+ *   or `1`
+ * - `0` is neutral when combining comparisons; the first non-zero ordering
+ *   determines the result
+ *
+ * **Common tasks**
+ *
+ * - Interpret a comparison result with {@link match}
+ * - Reverse ascending and descending order with {@link reverse}
+ * - Combine multiple comparison criteria with {@link Reducer}
+ * - Build custom comparison functions for sorting, ordered collections, and
+ *   domain-specific ordering rules
+ *
+ * **Gotchas**
+ *
+ * - Do not cast arbitrary comparator results such as `a.localeCompare(b)`
+ *   directly unless they have been normalized to `-1`, `0`, or `1`
+ * - In comparator-style APIs, `-1` means the left value should come before the
+ *   right value, while `1` means it should come after
+ * - Reversing an `Ordering` swaps `-1` and `1`, but leaves `0` unchanged
  *
- * @since 2.0.0
+ * @fileoverview
  * @category utilities
+ * @since 2.0.0
  */
 import type { LazyArg } from "./Function.ts"
 import { dual } from "./Function.ts"
@@ -36,7 +46,8 @@ import * as Reducer_ from "./Reducer.ts"
  * - `0` indicates the values are equal
  * - `1` indicates the first value is greater than the second
  *
- * @example
+ * **Example** (Defining comparison results)
+ *
  * ```ts
  * import type { Ordering } from "effect"
  *
@@ -66,7 +77,8 @@ export type Ordering = -1 | 0 | 1
  * Inverts the ordering of the input Ordering.
  * This is useful for creating descending sort orders from ascending ones.
  *
- * @example
+ * **Example** (Reversing comparison order)
+ *
  * ```ts
  * import { Ordering } from "effect"
  *
@@ -101,7 +113,8 @@ export const reverse = (o: Ordering): Ordering => (o === -1 ? 1 : o === 1 ? -1 :
 /**
  * Depending on the `Ordering` parameter given to it, returns a value produced by one of the 3 functions provided as parameters.
  *
- * @example
+ * **Example** (Pattern matching on orderings)
+ *
  * ```ts
  * import { Ordering } from "effect"
  * import { constant } from "effect/Function"
@@ -125,7 +138,8 @@ export const match: {
   /**
    * Depending on the `Ordering` parameter given to it, returns a value produced by one of the 3 functions provided as parameters.
    *
-   * @example
+   * **Example** (Pattern matching on orderings)
+   *
    * ```ts
    * import { Ordering } from "effect"
    * import { constant } from "effect/Function"
@@ -155,7 +169,8 @@ export const match: {
   /**
    * Depending on the `Ordering` parameter given to it, returns a value produced by one of the 3 functions provided as parameters.
    *
-   * @example
+   * **Example** (Pattern matching on orderings)
+   *
    * ```ts
    * import { Ordering } from "effect"
    * import { constant } from "effect/Function"

package/src/PartitionedSemaphore.ts

@@ -1,4 +1,38 @@
 /**
+ * The `PartitionedSemaphore` module provides a semaphore for limiting
+ * concurrency across a shared permit pool while keeping waiters grouped by
+ * partition key. A `PartitionedSemaphore<K>` is useful when many independent
+ * groups of work compete for the same bounded resource and each group should
+ * make progress without one busy group monopolizing released permits.
+ *
+ * **Mental model**
+ *
+ * - The semaphore has a fixed shared capacity measured in permits
+ * - Work acquires permits with a partition key of type `K`
+ * - Waiting acquisitions are tracked per partition
+ * - Released permits are assigned to waiting partitions in round-robin order
+ * - `withPermit` and `withPermits` acquire permits around an effect and
+ *   release them when the effect exits, fails, or is interrupted
+ *
+ * **Common tasks**
+ *
+ * - Create a semaphore: {@link make}, {@link makeUnsafe}
+ * - Inspect capacity and availability: {@link capacity}, {@link available}
+ * - Acquire and release manually: {@link take}, {@link release}
+ * - Limit a single operation per partition: {@link withPermit}
+ * - Limit weighted work per partition: {@link withPermits}
+ * - Run only when permits are immediately available:
+ *   {@link withPermitsIfAvailable}
+ *
+ * **Gotchas**
+ *
+ * - `withPermitsIfAvailable` does not use a partition key; it only succeeds
+ *   when the shared pool has enough permits immediately
+ * - Acquiring more permits than the semaphore capacity never completes
+ * - Requests for zero or negative permits complete without acquiring anything
+ * - Non-finite capacities create an unbounded semaphore whose acquire and
+ *   release operations complete immediately
+ *
  * @since 4.0.0
  */
 import * as Effect from "./Effect.ts"
@@ -7,14 +41,29 @@ import * as MutableHashMap from "./MutableHashMap.ts"
 import * as Option from "./Option.ts"
 
 /**
- * @since 4.0.0
+ * Runtime type identifier used to mark values that implement
+ * `PartitionedSemaphore`.
+ *
+ * **Details**
+ *
+ * This constant is stored on partitioned semaphore instances and can be used by
+ * library code that needs to recognize the data type at runtime.
+ *
  * @category models
+ * @since 4.0.0
  */
 export const PartitionedTypeId: PartitionedTypeId = "~effect/PartitionedSemaphore"
 
 /**
- * @since 4.0.0
+ * Literal type of the `PartitionedSemaphore` runtime type identifier.
+ *
+ * **Details**
+ *
+ * Use this type when declaring fields that must contain the exact
+ * `PartitionedTypeId` marker value.
+ *
  * @category models
+ * @since 4.0.0
  */
 export type PartitionedTypeId = "~effect/PartitionedSemaphore"
 
@@ -24,8 +73,8 @@ export type PartitionedTypeId = "~effect/PartitionedSemaphore"
  *
  * Waiting permits are distributed across partitions in round-robin order.
  *
- * @since 4.0.0
  * @category models
+ * @since 4.0.0
  */
 export interface PartitionedSemaphore<in K> {
   readonly [PartitionedTypeId]: PartitionedTypeId
@@ -44,16 +93,35 @@ export interface PartitionedSemaphore<in K> {
 }
 
 /**
- * @since 4.0.0
+ * Alias interface for a `PartitionedSemaphore` keyed by values of type `K`.
+ *
+ * **Details**
+ *
+ * This interface does not add members beyond `PartitionedSemaphore`; it
+ * provides an alternate exported name for APIs that refer to a partitioned
+ * permit pool.
+ *
  * @category models
+ * @since 4.0.0
  */
 export interface Partitioned<in K> extends PartitionedSemaphore<K> {}
 
 /**
- * Creates a `PartitionedSemaphore` unsafely.
+ * Constructs a `PartitionedSemaphore` synchronously, outside of `Effect`.
+ *
+ * **Details**
+ *
+ * Negative permit counts are clamped to `0`. Non-finite permit counts create
+ * an unbounded semaphore whose acquire and release operations complete
+ * immediately.
+ *
+ * **Notes**
+ *
+ * Prefer `make` when the semaphore should be created inside an `Effect`
+ * workflow.
  *
- * @since 4.0.0
  * @category constructors
+ * @since 4.0.0
  */
 export const makeUnsafe = <K = unknown>(options: {
   readonly permits: number
@@ -243,10 +311,16 @@ export const makeUnsafe = <K = unknown>(options: {
 }
 
 /**
- * Creates a `PartitionedSemaphore`.
+ * Creates a `PartitionedSemaphore` inside an `Effect`.
+ *
+ * **Details**
+ *
+ * The `permits` option sets the shared permit capacity. The resulting
+ * semaphore tracks waiters by partition key and distributes released permits
+ * across waiting partitions in round-robin order.
  *
- * @since 4.0.0
  * @category constructors
+ * @since 4.0.0
  */
 export const make = <K = unknown>(options: {
   readonly permits: number
@@ -255,84 +329,153 @@ export const make = <K = unknown>(options: {
 /**
  * Gets the current number of available permits.
  *
- * @since 4.0.0
  * @category combinators
+ * @since 4.0.0
  */
 export const available = <K>(self: PartitionedSemaphore<K>): Effect.Effect<number> => self.available
 
 /**
  * Gets the total capacity.
  *
- * @since 4.0.0
  * @category getters
+ * @since 4.0.0
  */
 export const capacity = <K>(self: PartitionedSemaphore<K>): number => self.capacity
 
 /**
- * Acquires permits for a partition.
+ * Returns an effect that acquires the requested number of permits for the
+ * given partition key.
+ *
+ * **Details**
+ *
+ * If enough permits are available, the effect completes immediately. Otherwise
+ * it waits until released permits are assigned to this partition. Requests for
+ * more permits than the semaphore capacity never complete. Requests for zero
+ * or a negative number of permits complete without acquiring anything.
  *
- * @since 4.0.0
  * @category combinators
+ * @since 4.0.0
  */
 export const take: {
   /**
-   * Acquires permits for a partition.
+   * Returns an effect that acquires the requested number of permits for the
+   * given partition key.
+   *
+   * **Details**
+   *
+   * If enough permits are available, the effect completes immediately. Otherwise
+   * it waits until released permits are assigned to this partition. Requests for
+   * more permits than the semaphore capacity never complete. Requests for zero
+   * or a negative number of permits complete without acquiring anything.
    *
-   * @since 4.0.0
    * @category combinators
+   * @since 4.0.0
    */
   <K>(key: K, permits: number): (self: PartitionedSemaphore<K>) => Effect.Effect<void>
   /**
-   * Acquires permits for a partition.
+   * Returns an effect that acquires the requested number of permits for the
+   * given partition key.
+   *
+   * **Details**
+   *
+   * If enough permits are available, the effect completes immediately. Otherwise
+   * it waits until released permits are assigned to this partition. Requests for
+   * more permits than the semaphore capacity never complete. Requests for zero
+   * or a negative number of permits complete without acquiring anything.
    *
-   * @since 4.0.0
    * @category combinators
+   * @since 4.0.0
    */
   <K>(self: PartitionedSemaphore<K>, key: K, permits: number): Effect.Effect<void>
 } = dual(3, <K>(self: PartitionedSemaphore<K>, key: K, permits: number): Effect.Effect<void> => self.take(key, permits))
 
 /**
- * Releases permits back to the shared pool.
+ * Returns an effect that releases permits back to the shared pool and returns
+ * the current available permit count.
+ *
+ * **Details**
+ *
+ * Released permits are first assigned to waiting partitions in round-robin
+ * order. Only permits not needed by waiters increase the available count,
+ * which is capped at the semaphore capacity.
  *
- * @since 4.0.0
  * @category combinators
+ * @since 4.0.0
  */
 export const release: {
   /**
-   * Releases permits back to the shared pool.
+   * Returns an effect that releases permits back to the shared pool and returns
+   * the current available permit count.
+   *
+   * **Details**
+   *
+   * Released permits are first assigned to waiting partitions in round-robin
+   * order. Only permits not needed by waiters increase the available count,
+   * which is capped at the semaphore capacity.
    *
-   * @since 4.0.0
    * @category combinators
+   * @since 4.0.0
    */
   (permits: number): <K>(self: PartitionedSemaphore<K>) => Effect.Effect<number>
   /**
-   * Releases permits back to the shared pool.
+   * Returns an effect that releases permits back to the shared pool and returns
+   * the current available permit count.
+   *
+   * **Details**
+   *
+   * Released permits are first assigned to waiting partitions in round-robin
+   * order. Only permits not needed by waiters increase the available count,
+   * which is capped at the semaphore capacity.
    *
-   * @since 4.0.0
    * @category combinators
+   * @since 4.0.0
    */
   <K>(self: PartitionedSemaphore<K>, permits: number): Effect.Effect<number>
 } = dual(2, <K>(self: PartitionedSemaphore<K>, permits: number): Effect.Effect<number> => self.release(permits))
 
 /**
- * Runs an effect with permits for a partition.
+ * Runs an effect after acquiring permits for a partition, then releases those
+ * permits when the effect exits.
+ *
+ * **Details**
+ *
+ * Permit acquisition may wait according to `take` semantics. Once acquired,
+ * the permits are released even if the wrapped effect fails or is interrupted.
+ * Requests for zero or a negative number of permits run the effect without
+ * acquiring anything.
  *
- * @since 4.0.0
  * @category combinators
+ * @since 4.0.0
  */
 export const withPermits: {
   /**
-   * Runs an effect with permits for a partition.
+   * Runs an effect after acquiring permits for a partition, then releases those
+   * permits when the effect exits.
+   *
+   * **Details**
+   *
+   * Permit acquisition may wait according to `take` semantics. Once acquired,
+   * the permits are released even if the wrapped effect fails or is interrupted.
+   * Requests for zero or a negative number of permits run the effect without
+   * acquiring anything.
    *
-   * @since 4.0.0
    * @category combinators
+   * @since 4.0.0
    */
   <K>(self: PartitionedSemaphore<K>, key: K, permits: number): <A, E, R>(effect: Effect.Effect<A, E, R>) => Effect.Effect<A, E, R>
   /**
-   * Runs an effect with permits for a partition.
+   * Runs an effect after acquiring permits for a partition, then releases those
+   * permits when the effect exits.
+   *
+   * **Details**
+   *
+   * Permit acquisition may wait according to `take` semantics. Once acquired,
+   * the permits are released even if the wrapped effect fails or is interrupted.
+   * Requests for zero or a negative number of permits run the effect without
+   * acquiring anything.
    *
-   * @since 4.0.0
    * @category combinators
+   * @since 4.0.0
    */
   <K, A, E, R>(
     self: PartitionedSemaphore<K>,
@@ -350,24 +493,42 @@ export const withPermits: {
 }) as any
 
 /**
- * Runs an effect with a single permit for a partition.
+ * Runs an effect after acquiring one permit for a partition, then releases the
+ * permit when the effect exits.
+ *
+ * **Details**
+ *
+ * This is the single-permit variant of `withPermits`. The permit is released
+ * even if the wrapped effect fails or is interrupted.
  *
- * @since 4.0.0
  * @category combinators
+ * @since 4.0.0
  */
 export const withPermit: {
   /**
-   * Runs an effect with a single permit for a partition.
+   * Runs an effect after acquiring one permit for a partition, then releases the
+   * permit when the effect exits.
+   *
+   * **Details**
+   *
+   * This is the single-permit variant of `withPermits`. The permit is released
+   * even if the wrapped effect fails or is interrupted.
    *
-   * @since 4.0.0
    * @category combinators
+   * @since 4.0.0
    */
   <K>(self: PartitionedSemaphore<K>, key: K): <A, E, R>(effect: Effect.Effect<A, E, R>) => Effect.Effect<A, E, R>
   /**
-   * Runs an effect with a single permit for a partition.
+   * Runs an effect after acquiring one permit for a partition, then releases the
+   * permit when the effect exits.
+   *
+   * **Details**
+   *
+   * This is the single-permit variant of `withPermits`. The permit is released
+   * even if the wrapped effect fails or is interrupted.
    *
-   * @since 4.0.0
    * @category combinators
+   * @since 4.0.0
    */
   <K, A, E, R>(self: PartitionedSemaphore<K>, key: K, effect: Effect.Effect<A, E, R>): Effect.Effect<A, E, R>
 } = ((...args: Array<any>) => {
@@ -380,24 +541,48 @@ export const withPermit: {
 }) as any
 
 /**
- * Runs an effect only if the permits are immediately available.
+ * Runs an effect only when the requested permits can be acquired immediately,
+ * returning the result in `Some`.
+ *
+ * **Details**
+ *
+ * If the permits are not available, the effect is not run and the result is
+ * `None`. When permits are acquired, they are released after the wrapped
+ * effect completes, fails, or is interrupted. Requests for zero or a negative
+ * number of permits run the effect and return `Some`.
  *
- * @since 4.0.0
  * @category combinators
+ * @since 4.0.0
  */
 export const withPermitsIfAvailable: {
   /**
-   * Runs an effect only if the permits are immediately available.
+   * Runs an effect only when the requested permits can be acquired immediately,
+   * returning the result in `Some`.
+   *
+   * **Details**
+   *
+   * If the permits are not available, the effect is not run and the result is
+   * `None`. When permits are acquired, they are released after the wrapped
+   * effect completes, fails, or is interrupted. Requests for zero or a negative
+   * number of permits run the effect and return `Some`.
    *
-   * @since 4.0.0
    * @category combinators
+   * @since 4.0.0
    */
   <K>(self: PartitionedSemaphore<K>, permits: number): <A, E, R>(effect: Effect.Effect<A, E, R>) => Effect.Effect<Option.Option<A>, E, R>
   /**
-   * Runs an effect only if the permits are immediately available.
+   * Runs an effect only when the requested permits can be acquired immediately,
+   * returning the result in `Some`.
+   *
+   * **Details**
+   *
+   * If the permits are not available, the effect is not run and the result is
+   * `None`. When permits are acquired, they are released after the wrapped
+   * effect completes, fails, or is interrupted. Requests for zero or a negative
+   * number of permits run the effect and return `Some`.
    *
-   * @since 4.0.0
    * @category combinators
+   * @since 4.0.0
    */
   <K, A, E, R>(
     self: PartitionedSemaphore<K>,