effect 4.0.0-beta.70 → 4.0.0-beta.72

package/src/Ordering.ts

@@ -40,6 +40,11 @@ import * as Reducer_ from "./Reducer.ts"
 /**
  * Represents the result of comparing two values.
  *
+ * **When to use**
+ *
+ * Use to model a normalized comparison result that is exactly less than,
+ * equal to, or greater than.
+ *
  * **Details**
  *
  * - `-1` indicates the first value is less than the second
@@ -74,9 +79,14 @@ import * as Reducer_ from "./Reducer.ts"
 export type Ordering = -1 | 0 | 1
 
 /**
- * Inverts the ordering of the input Ordering.
+ * Reverses the ordering of the input Ordering.
  * This is useful for creating descending sort orders from ascending ones.
  *
+ * **When to use**
+ *
+ * Use to flip an ordering result when reversing sort direction or comparison
+ * priority.
+ *
  * **Example** (Reversing comparison order)
  *
  * ```ts
@@ -111,7 +121,11 @@ export type Ordering = -1 | 0 | 1
 export const reverse = (o: Ordering): Ordering => (o === -1 ? 1 : o === 1 ? -1 : 0)
 
 /**
- * Depending on the `Ordering` parameter given to it, returns a value produced by one of the 3 functions provided as parameters.
+ * Matches an `Ordering` value and returns the branch selected by that ordering.
+ *
+ * **When to use**
+ *
+ * Use to branch on the three possible comparison outcomes in one expression.
  *
  * **Example** (Pattern matching on orderings)
  *
@@ -135,7 +149,11 @@ export const reverse = (o: Ordering): Ordering => (o === -1 ? 1 : o === 1 ? -1 :
  */
 export const match: {
   /**
-   * Depending on the `Ordering` parameter given to it, returns a value produced by one of the 3 functions provided as parameters.
+   * Matches an `Ordering` value and returns the branch selected by that ordering.
+   *
+   * **When to use**
+   *
+   * Use to branch on the three possible comparison outcomes in one expression.
    *
    * **Example** (Pattern matching on orderings)
    *
@@ -165,7 +183,11 @@ export const match: {
     }
   ): (self: Ordering) => A | B | C
   /**
-   * Depending on the `Ordering` parameter given to it, returns a value produced by one of the 3 functions provided as parameters.
+   * Matches an `Ordering` value and returns the branch selected by that ordering.
+   *
+   * **When to use**
+   *
+   * Use to branch on the three possible comparison outcomes in one expression.
    *
    * **Example** (Pattern matching on orderings)
    *
@@ -205,13 +227,23 @@ export const match: {
 ): A | B | C => self === -1 ? onLessThan() : self === 0 ? onEqual() : onGreaterThan())
 
 /**
- * A `Reducer` for combining `Ordering`s.
+ * Reducer for combining `Ordering`s.
+ *
+ * **When to use**
+ *
+ * Use to combine multiple comparison results in priority order, such as
+ * checking secondary criteria only when earlier criteria compare as equal.
  *
  * **Details**
  *
  * 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.
  *
+ * **Gotchas**
+ *
+ * `combineAll` stops consuming the iterable as soon as it finds a non-zero
+ * `Ordering`.
+ *
  * @category ordering
  * @since 4.0.0
  */

package/src/PartitionedSemaphore.ts

@@ -46,10 +46,10 @@ import * as Option from "./Option.ts"
  *
  * **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.
+ * This marker is part of the runtime representation of partitioned semaphore
+ * values.
  *
- * @category models
+ * @category type IDs
  * @since 4.0.0
  */
 export const PartitionedTypeId: PartitionedTypeId = "~effect/PartitionedSemaphore"
@@ -57,12 +57,16 @@ export const PartitionedTypeId: PartitionedTypeId = "~effect/PartitionedSemaphor
 /**
  * Literal type of the `PartitionedSemaphore` runtime type identifier.
  *
+ * **When to use**
+ *
+ * Use to type fields that store the exact `PartitionedSemaphore` runtime marker.
+ *
  * **Details**
  *
  * Use this type when declaring fields that must contain the exact
  * `PartitionedTypeId` marker value.
  *
- * @category models
+ * @category type IDs
  * @since 4.0.0
  */
 export type PartitionedTypeId = "~effect/PartitionedSemaphore"
@@ -71,6 +75,11 @@ export type PartitionedTypeId = "~effect/PartitionedSemaphore"
  * A `PartitionedSemaphore` controls access to a shared permit pool while
  * tracking waiters by partition key.
  *
+ * **When to use**
+ *
+ * Use to coordinate shared permits across partition keys so waiting groups make
+ * progress without one group monopolizing the pool.
+ *
  * **Details**
  *
  * Waiting permits are distributed across partitions in round-robin order.
@@ -97,6 +106,10 @@ export interface PartitionedSemaphore<in K> {
 /**
  * Alias interface for a `PartitionedSemaphore` keyed by values of type `K`.
  *
+ * **When to use**
+ *
+ * Use as an alternate exported name for a partitioned permit pool keyed by `K`.
+ *
  * **Details**
  *
  * This interface does not add members beyond `PartitionedSemaphore`; it
@@ -113,8 +126,8 @@ export interface Partitioned<in K> extends PartitionedSemaphore<K> {}
  *
  * **When to use**
  *
- * Prefer `make` when the semaphore should be created inside an `Effect`
- * workflow.
+ * Use when a partitioned semaphore must be constructed synchronously outside an
+ * `Effect` workflow.
  *
  * **Details**
  *
@@ -122,6 +135,8 @@ export interface Partitioned<in K> extends PartitionedSemaphore<K> {}
  * an unbounded semaphore whose acquire and release operations complete
  * immediately.
  *
+ * @see {@link make} for creating a partitioned semaphore inside `Effect`
+ *
  * @category constructors
  * @since 3.19.4
  */
@@ -315,12 +330,23 @@ export const makeUnsafe = <K = unknown>(options: {
 /**
  * Creates a `PartitionedSemaphore` inside an `Effect`.
  *
+ * **When to use**
+ *
+ * Use when semaphore construction should stay inside an `Effect` workflow.
+ *
  * **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.
  *
+ * **Gotchas**
+ *
+ * Negative permit counts are clamped to `0`. Non-finite permit counts create
+ * an unbounded semaphore.
+ *
+ * @see {@link makeUnsafe} for synchronous construction
+ *
  * @category constructors
  * @since 3.19.4
  */
@@ -331,6 +357,24 @@ export const make = <K = unknown>(options: {
 /**
  * Gets the current number of available permits.
  *
+ * **When to use**
+ *
+ * Use to inspect a snapshot of how many permits are currently free.
+ *
+ * **Details**
+ *
+ * Running the returned effect reads the semaphore's current availability.
+ * Taking permits decreases availability, and releasing permits can increase it
+ * up to the semaphore capacity.
+ *
+ * **Gotchas**
+ *
+ * Reading availability does not reserve permits.
+ *
+ * @see {@link capacity} for the fixed total permit capacity
+ * @see {@link release} for returning permits to the shared pool
+ * @see {@link withPermitsIfAvailable} for running only when permits are immediately available
+ *
  * @category combinators
  * @since 4.0.0
  */
@@ -339,6 +383,17 @@ export const available = <K>(self: PartitionedSemaphore<K>): Effect.Effect<numbe
 /**
  * Gets the total capacity.
  *
+ * **When to use**
+ *
+ * Use to inspect the fixed number of permits configured for the semaphore.
+ *
+ * **Details**
+ *
+ * Capacity is stored when the semaphore is created and does not change as
+ * permits are acquired or released.
+ *
+ * @see {@link available} for the current number of free permits
+ *
  * @category getters
  * @since 4.0.0
  */
@@ -348,12 +403,25 @@ export const capacity = <K>(self: PartitionedSemaphore<K>): number => self.capac
  * Returns an effect that acquires the requested number of permits for the
  * given partition key.
  *
+ * **When to use**
+ *
+ * Use to manually acquire permits for a partition when acquisition and release
+ * must be controlled as separate effects.
+ *
  * **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.
+ * it waits until released permits are assigned to this partition.
+ *
+ * **Gotchas**
+ *
+ * Requests for more permits than the semaphore capacity never complete.
+ * Requests for zero or a negative number of permits complete without acquiring
+ * anything.
+ *
+ * @see {@link release} for manually returning permits to the shared pool
+ * @see {@link withPermits} for automatic acquire and release around an effect
+ * @see {@link withPermit} for acquiring exactly one permit around an effect
  *
  * @category combinators
  * @since 4.0.0
@@ -363,12 +431,25 @@ export const take: {
    * Returns an effect that acquires the requested number of permits for the
    * given partition key.
    *
+   * **When to use**
+   *
+   * Use to manually acquire permits for a partition when acquisition and release
+   * must be controlled as separate effects.
+   *
    * **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.
+   * it waits until released permits are assigned to this partition.
+   *
+   * **Gotchas**
+   *
+   * Requests for more permits than the semaphore capacity never complete.
+   * Requests for zero or a negative number of permits complete without acquiring
+   * anything.
+   *
+   * @see {@link release} for manually returning permits to the shared pool
+   * @see {@link withPermits} for automatic acquire and release around an effect
+   * @see {@link withPermit} for acquiring exactly one permit around an effect
    *
    * @category combinators
    * @since 4.0.0
@@ -378,12 +459,25 @@ export const take: {
    * Returns an effect that acquires the requested number of permits for the
    * given partition key.
    *
+   * **When to use**
+   *
+   * Use to manually acquire permits for a partition when acquisition and release
+   * must be controlled as separate effects.
+   *
    * **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.
+   * it waits until released permits are assigned to this partition.
+   *
+   * **Gotchas**
+   *
+   * Requests for more permits than the semaphore capacity never complete.
+   * Requests for zero or a negative number of permits complete without acquiring
+   * anything.
+   *
+   * @see {@link release} for manually returning permits to the shared pool
+   * @see {@link withPermits} for automatic acquire and release around an effect
+   * @see {@link withPermit} for acquiring exactly one permit around an effect
    *
    * @category combinators
    * @since 4.0.0
@@ -395,12 +489,21 @@ export const take: {
  * Returns an effect that releases permits back to the shared pool and returns
  * the current available permit count.
  *
+ * **When to use**
+ *
+ * Use to manually return permits acquired with `take` when a lower-level
+ * partitioned permit protocol needs explicit release control.
+ *
  * **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.
  *
+ * @see {@link take} for manual acquisition
+ * @see {@link withPermits} for automatic acquire and release around an effect
+ * @see {@link available} for reading the permit count without releasing
+ *
  * @category combinators
  * @since 4.0.0
  */
@@ -409,12 +512,21 @@ export const release: {
    * Returns an effect that releases permits back to the shared pool and returns
    * the current available permit count.
    *
+   * **When to use**
+   *
+   * Use to manually return permits acquired with `take` when a lower-level
+   * partitioned permit protocol needs explicit release control.
+   *
    * **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.
    *
+   * @see {@link take} for manual acquisition
+   * @see {@link withPermits} for automatic acquire and release around an effect
+   * @see {@link available} for reading the permit count without releasing
+   *
    * @category combinators
    * @since 4.0.0
    */
@@ -423,12 +535,21 @@ export const release: {
    * Returns an effect that releases permits back to the shared pool and returns
    * the current available permit count.
    *
+   * **When to use**
+   *
+   * Use to manually return permits acquired with `take` when a lower-level
+   * partitioned permit protocol needs explicit release control.
+   *
    * **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.
    *
+   * @see {@link take} for manual acquisition
+   * @see {@link withPermits} for automatic acquire and release around an effect
+   * @see {@link available} for reading the permit count without releasing
+   *
    * @category combinators
    * @since 4.0.0
    */
@@ -439,13 +560,28 @@ export const release: {
  * Runs an effect after acquiring permits for a partition, then releases those
  * permits when the effect exits.
  *
+ * **When to use**
+ *
+ * Use to guard weighted partitioned work with automatic permit acquisition and
+ * release around an effect.
+ *
  * **Details**
  *
  * Permit acquisition may wait according to `take` semantics. Once acquired,
  * the permits are released even if the wrapped effect fails or is interrupted.
+ *
+ * **Gotchas**
+ *
+ * Requests for more permits than the semaphore capacity never complete.
  * Requests for zero or a negative number of permits run the effect without
  * acquiring anything.
  *
+ * @see {@link withPermit} for the single-permit variant
+ * @see {@link withPermitsIfAvailable} for running only when permits are
+ * immediately available
+ * @see {@link take} for manual acquisition
+ * @see {@link release} for manual release
+ *
  * @category combinators
  * @since 4.0.0
  */
@@ -454,13 +590,28 @@ export const withPermits: {
    * Runs an effect after acquiring permits for a partition, then releases those
    * permits when the effect exits.
    *
+   * **When to use**
+   *
+   * Use to guard weighted partitioned work with automatic permit acquisition and
+   * release around an effect.
+   *
    * **Details**
    *
    * Permit acquisition may wait according to `take` semantics. Once acquired,
    * the permits are released even if the wrapped effect fails or is interrupted.
+   *
+   * **Gotchas**
+   *
+   * Requests for more permits than the semaphore capacity never complete.
    * Requests for zero or a negative number of permits run the effect without
    * acquiring anything.
    *
+   * @see {@link withPermit} for the single-permit variant
+   * @see {@link withPermitsIfAvailable} for running only when permits are
+   * immediately available
+   * @see {@link take} for manual acquisition
+   * @see {@link release} for manual release
+   *
    * @category combinators
    * @since 4.0.0
    */
@@ -469,13 +620,28 @@ export const withPermits: {
    * Runs an effect after acquiring permits for a partition, then releases those
    * permits when the effect exits.
    *
+   * **When to use**
+   *
+   * Use to guard weighted partitioned work with automatic permit acquisition and
+   * release around an effect.
+   *
    * **Details**
    *
    * Permit acquisition may wait according to `take` semantics. Once acquired,
    * the permits are released even if the wrapped effect fails or is interrupted.
+   *
+   * **Gotchas**
+   *
+   * Requests for more permits than the semaphore capacity never complete.
    * Requests for zero or a negative number of permits run the effect without
    * acquiring anything.
    *
+   * @see {@link withPermit} for the single-permit variant
+   * @see {@link withPermitsIfAvailable} for running only when permits are
+   * immediately available
+   * @see {@link take} for manual acquisition
+   * @see {@link release} for manual release
+   *
    * @category combinators
    * @since 4.0.0
    */
@@ -498,11 +664,22 @@ export const withPermits: {
  * Runs an effect after acquiring one permit for a partition, then releases the
  * permit when the effect exits.
  *
+ * **When to use**
+ *
+ * Use to guard partitioned work with exactly one permit and automatic release
+ * 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.
  *
+ * @see {@link withPermits} for acquiring a weighted number of permits
+ * @see {@link withPermitsIfAvailable} for running only when permits are
+ * immediately available
+ * @see {@link take} for manual acquisition
+ * @see {@link release} for manual release
+ *
  * @category combinators
  * @since 4.0.0
  */
@@ -511,11 +688,22 @@ export const withPermit: {
    * Runs an effect after acquiring one permit for a partition, then releases the
    * permit when the effect exits.
    *
+   * **When to use**
+   *
+   * Use to guard partitioned work with exactly one permit and automatic release
+   * 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.
    *
+   * @see {@link withPermits} for acquiring a weighted number of permits
+   * @see {@link withPermitsIfAvailable} for running only when permits are
+   * immediately available
+   * @see {@link take} for manual acquisition
+   * @see {@link release} for manual release
+   *
    * @category combinators
    * @since 4.0.0
    */
@@ -524,11 +712,22 @@ export const withPermit: {
    * Runs an effect after acquiring one permit for a partition, then releases the
    * permit when the effect exits.
    *
+   * **When to use**
+   *
+   * Use to guard partitioned work with exactly one permit and automatic release
+   * 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.
    *
+   * @see {@link withPermits} for acquiring a weighted number of permits
+   * @see {@link withPermitsIfAvailable} for running only when permits are
+   * immediately available
+   * @see {@link take} for manual acquisition
+   * @see {@link release} for manual release
+   *
    * @category combinators
    * @since 4.0.0
    */
@@ -546,6 +745,11 @@ export const withPermit: {
  * Runs an effect only when the requested permits can be acquired immediately,
  * returning the result in `Some`.
  *
+ * **When to use**
+ *
+ * Use when guarded work should run only if the shared permit pool can provide
+ * the requested permits immediately.
+ *
  * **Details**
  *
  * If the permits are not available, the effect is not run and the result is
@@ -553,6 +757,9 @@ export const withPermit: {
  * effect completes, fails, or is interrupted. Requests for zero or a negative
  * number of permits run the effect and return `Some`.
  *
+ * @see {@link withPermits} for the keyed variant that waits until permits are
+ * available for a partition
+ *
  * @category combinators
  * @since 4.0.0
  */
@@ -561,6 +768,11 @@ export const withPermitsIfAvailable: {
    * Runs an effect only when the requested permits can be acquired immediately,
    * returning the result in `Some`.
    *
+   * **When to use**
+   *
+   * Use when guarded work should run only if the shared permit pool can provide
+   * the requested permits immediately.
+   *
    * **Details**
    *
    * If the permits are not available, the effect is not run and the result is
@@ -568,6 +780,9 @@ export const withPermitsIfAvailable: {
    * effect completes, fails, or is interrupted. Requests for zero or a negative
    * number of permits run the effect and return `Some`.
    *
+   * @see {@link withPermits} for the keyed variant that waits until permits are
+   * available for a partition
+   *
    * @category combinators
    * @since 4.0.0
    */
@@ -576,6 +791,11 @@ export const withPermitsIfAvailable: {
    * Runs an effect only when the requested permits can be acquired immediately,
    * returning the result in `Some`.
    *
+   * **When to use**
+   *
+   * Use when guarded work should run only if the shared permit pool can provide
+   * the requested permits immediately.
+   *
    * **Details**
    *
    * If the permits are not available, the effect is not run and the result is
@@ -583,6 +803,9 @@ export const withPermitsIfAvailable: {
    * effect completes, fails, or is interrupted. Requests for zero or a negative
    * number of permits run the effect and return `Some`.
    *
+   * @see {@link withPermits} for the keyed variant that waits until permits are
+   * available for a partition
+   *
    * @category combinators
    * @since 4.0.0
    */

package/src/Path.ts

@@ -40,13 +40,26 @@ import { BadArgument } from "./PlatformError.ts"
 /**
  * Runtime type identifier used to mark implementations of the `Path` service.
  *
+ * **Details**
+ *
+ * The marker is the exact string stored on `Path` service implementations.
+ * Most code should depend on the `Path` service instead of inspecting this
+ * value directly.
+ *
+ * @see {@link layer} for the built-in POSIX `Path` service layer
+ *
  * @category type IDs
  * @since 4.0.0
  */
 export const TypeId = "~effect/platform/Path"
 
 /**
- * Service interface for platform-specific path manipulation.
+ * Defines the service interface for platform-specific path manipulation.
+ *
+ * **When to use**
+ *
+ * Use to depend on path operations through the Effect environment instead of a
+ * concrete host path module.
  *
  * **Details**
  *
@@ -111,6 +124,10 @@ export interface Path {
 /**
  * Namespace containing types associated with the `Path` service.
  *
+ * **When to use**
+ *
+ * Use to reference types associated with path parsing and formatting.
+ *
  * **Example** (Working with parsed paths)
  *
  * ```ts
@@ -142,6 +159,11 @@ export declare namespace Path {
   /**
    * Structured representation of a parsed file system path.
    *
+   * **When to use**
+   *
+   * Use to model the object form produced by `Path.parse` and consumed by
+   * `Path.format`.
+   *
    * **Details**
    *
    * The fields correspond to the path root, directory, base filename,
@@ -190,12 +212,11 @@ export declare namespace Path {
 }
 
 /**
- * Context service tag for accessing the current `Path` implementation.
+ * Service tag for accessing the current `Path` implementation.
  *
  * **When to use**
  *
- * Yield this service inside an effect to use path operations supplied by the
- * environment, or provide a custom implementation with `Layer.succeed`.
+ * Use when an effect needs path operations supplied by its environment.
  *
  * **Example** (Providing a custom Path service)
  *
@@ -855,8 +876,15 @@ const posixImpl = Path.of({
  *
  * **When to use**
  *
- * Use this layer when an effect requires the `Path` service and should use
- * forward-slash path semantics.
+ * Use when an effect requires the `Path` service and should run with the
+ * built-in POSIX path implementation.
+ *
+ * **Details**
+ *
+ * The layer provides a static service whose separator is `/` and whose
+ * operations use POSIX path semantics.
+ *
+ * @see {@link Path} for accessing the `Path` service from an effect
  *
  * @category layers
  * @since 4.0.0