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

package/src/Order.ts

@@ -324,7 +324,7 @@ export const BigInt: Order<bigint> = make((self, that) => self < that ? -1 : 1)
  * - {@link combine} - Combine orders for multi-criteria comparison
  *
  * @category combinators
- * @since 2.0.0
+ * @since 4.0.0
  */
 export function flip<A>(O: Order<A>): Order<A> {
   return make((self, that) => O(that, self))
@@ -906,7 +906,7 @@ export function Struct<const R extends { readonly [x: string]: Order<any> }>(
  * - {@link isGreaterThan} - Strict greater than
  *
  * @category predicates
- * @since 2.0.0
+ * @since 4.0.0
  */
 export const isLessThan = <A>(O: Order<A>): {
   (that: A): (self: A) => boolean
@@ -944,7 +944,7 @@ export const isLessThan = <A>(O: Order<A>): {
  * - {@link isLessThan} - Strict less than
  *
  * @category predicates
- * @since 2.0.0
+ * @since 4.0.0
  */
 export const isGreaterThan = <A>(O: Order<A>): {
   (that: A): (self: A) => boolean
@@ -982,7 +982,7 @@ export const isGreaterThan = <A>(O: Order<A>): {
  * - {@link isGreaterThan} - Strict greater than
  *
  * @category predicates
- * @since 2.0.0
+ * @since 4.0.0
  */
 export const isLessThanOrEqualTo = <A>(O: Order<A>): {
   (that: A): (self: A) => boolean
@@ -1020,7 +1020,7 @@ export const isLessThanOrEqualTo = <A>(O: Order<A>): {
  * - {@link isLessThanOrEqualTo} - Less than or equal
  *
  * @category predicates
- * @since 2.0.0
+ * @since 4.0.0
  */
 export const isGreaterThanOrEqualTo = <A>(O: Order<A>): {
   (that: A): (self: A) => boolean
@@ -1243,7 +1243,7 @@ export const isBetween = <A>(O: Order<A>): {
  * - {@link combineAll} - Combine multiple orders
  * - {@link Reducer} - Reducer type for collection operations
  *
- * @category utilities
+ * @category utils
  * @since 4.0.0
  */
 export function makeReducer<A>() {

package/src/Ordering.ts

@@ -1,29 +1,37 @@
 /**
- * @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
- * @category utilities
  */
 import type { LazyArg } from "./Function.ts"
 import { dual } from "./Function.ts"
@@ -36,7 +44,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"
  *
@@ -57,7 +66,7 @@ import * as Reducer_ from "./Reducer.ts"
  * }
  * ```
  *
- * @category model
+ * @category models
  * @since 2.0.0
  */
 export type Ordering = -1 | 0 | 1
@@ -66,7 +75,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"
  *
@@ -93,7 +103,7 @@ export type Ordering = -1 | 0 | 1
  * }
  * ```
  *
- * @category transformations
+ * @category transforming
  * @since 2.0.0
  */
 export const reverse = (o: Ordering): Ordering => (o === -1 ? 1 : o === 1 ? -1 : 0)
@@ -101,16 +111,16 @@ 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"
+ * import { Function, Ordering } from "effect"
  * import * as assert from "node:assert"
  *
  * const toMessage = Ordering.match({
- *   onLessThan: constant("less than"),
- *   onEqual: constant("equal"),
- *   onGreaterThan: constant("greater than")
+ *   onLessThan: Function.constant("less than"),
+ *   onEqual: Function.constant("equal"),
+ *   onGreaterThan: Function.constant("greater than")
  * })
  *
  * assert.deepStrictEqual(toMessage(-1), "less than")
@@ -125,16 +135,16 @@ 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"
+   * import { Function, Ordering } from "effect"
    * import * as assert from "node:assert"
    *
    * const toMessage = Ordering.match({
-   *   onLessThan: constant("less than"),
-   *   onEqual: constant("equal"),
-   *   onGreaterThan: constant("greater than")
+   *   onLessThan: Function.constant("less than"),
+   *   onEqual: Function.constant("equal"),
+   *   onGreaterThan: Function.constant("greater than")
    * })
    *
    * assert.deepStrictEqual(toMessage(-1), "less than")
@@ -155,16 +165,16 @@ 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"
+   * import { Function, Ordering } from "effect"
    * import * as assert from "node:assert"
    *
    * const toMessage = Ordering.match({
-   *   onLessThan: constant("less than"),
-   *   onEqual: constant("equal"),
-   *   onGreaterThan: constant("greater than")
+   *   onLessThan: Function.constant("less than"),
+   *   onEqual: Function.constant("equal"),
+   *   onGreaterThan: Function.constant("greater than")
    * })
    *
    * assert.deepStrictEqual(toMessage(-1), "less than")
@@ -198,6 +208,7 @@ export const match: {
  * If any of the `Ordering`s is non-zero, the result is the first non-zero `Ordering`.
  * If all the `Ordering`s are zero, the result is zero.
  *
+ * @category ordering
  * @since 4.0.0
  */
 export const Reducer: Reducer_.Reducer<Ordering> = Reducer_.make<Ordering>(

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 3.19.4
  */
 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 3.19.4
  */
 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 3.19.4
  */
 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>,