effect 4.0.0-beta.65 → 4.0.0-beta.67

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>,

package/src/Path.ts

@@ -1,4 +1,34 @@
 /**
+ * The `Path` module provides a platform path service for manipulating file
+ * system paths through Effect's environment. It models path operations as a
+ * replaceable service so programs can depend on path behavior without directly
+ * coupling to a particular runtime implementation.
+ *
+ * **Mental model**
+ *
+ * - `Path.Path` is a `Context.Service` tag used to access the current path implementation
+ * - The service offers familiar path operations such as joining, resolving, parsing, and formatting
+ * - Most operations are pure string transformations and follow POSIX-style path semantics
+ * - File URL conversions return `Effect`s because invalid paths or URLs can fail with `BadArgument`
+ * - Custom implementations can be provided with `Layer.succeed` for alternate platforms or tests
+ *
+ * **Common tasks**
+ *
+ * - Combine path segments with `join` or turn segments into an absolute path with `resolve`
+ * - Normalize `.` and `..` segments with `normalize`
+ * - Inspect paths with `basename`, `dirname`, `extname`, and `isAbsolute`
+ * - Convert between structured path parts and strings with `parse` and `format`
+ * - Compute relative paths with `relative`
+ * - Convert between file paths and `file:` URLs with `toFileUrl` and `fromFileUrl`
+ *
+ * **Gotchas**
+ *
+ * - Path strings are not checked against the file system; these operations only manipulate syntax
+ * - `resolve` may consult the host current working directory when no absolute segment is supplied
+ * - `fromFileUrl` only accepts valid `file:` URLs and rejects encoded path separators
+ * - Use the service from the environment when writing portable Effect code instead of importing
+ *   host-specific path APIs directly
+ *
  * @since 4.0.0
  */
 import * as Context from "./Context.ts"
@@ -8,14 +38,21 @@ import * as Layer from "./Layer.ts"
 import { BadArgument } from "./PlatformError.ts"
 
 /**
+ * Runtime type identifier used to mark implementations of the `Path` service.
+ *
  * @since 4.0.0
  */
 export const TypeId = "~effect/platform/Path"
 
 /**
- * @since 4.0.0
- * @category model
- * @example
+ * Service interface for platform-specific path manipulation.
+ *
+ * The service exposes operations for joining, normalizing, parsing,
+ * formatting, and converting file system paths. URL conversion methods return
+ * `Effect`s because invalid file URLs or paths can fail with `BadArgument`.
+ *
+ * **Example** (Using path operations)
+ *
  * ```ts
  * import { Effect, Path } from "effect"
  *
@@ -46,6 +83,9 @@ export const TypeId = "~effect/platform/Path"
  *   })
  * })
  * ```
+ *
+ * @category model
+ * @since 4.0.0
  */
 export interface Path {
   readonly [TypeId]: typeof TypeId
@@ -66,9 +106,10 @@ export interface Path {
 }
 
 /**
- * @since 4.0.0
- * @category namespace
- * @example
+ * Namespace containing types associated with the `Path` service.
+ *
+ * **Example** (Working with parsed paths)
+ *
  * ```ts
  * import { Effect, Path } from "effect"
  *
@@ -91,12 +132,20 @@ export interface Path {
  *   console.log(parsed, exampleParsed)
  * })
  * ```
+ *
+ * @category namespace
+ * @since 4.0.0
  */
 export declare namespace Path {
   /**
-   * @since 4.0.0
-   * @category model
-   * @example
+   * Structured representation of a parsed file system path.
+   *
+   * The fields correspond to the path root, directory, base filename,
+   * extension, and filename without extension, matching the shape consumed by
+   * `Path.format`.
+   *
+   * **Example** (Parsing and formatting paths)
+   *
    * ```ts
    * import { Effect, Path } from "effect"
    *
@@ -123,6 +172,9 @@ export declare namespace Path {
    *   console.log(formatted) // "/home/user/newfile.ts"
    * })
    * ```
+   *
+   * @category model
+   * @since 4.0.0
    */
   export interface Parsed {
     readonly root: string
@@ -134,9 +186,13 @@ export declare namespace Path {
 }
 
 /**
- * @since 4.0.0
- * @category tag
- * @example
+ * Context service tag for accessing the current `Path` implementation.
+ *
+ * Yield this service inside an effect to use path operations supplied by the
+ * environment, or provide a custom implementation with `Layer.succeed`.
+ *
+ * **Example** (Providing a custom Path service)
+ *
  * ```ts
  * import { Effect, Layer, Path } from "effect"
  *
@@ -190,6 +246,9 @@ export declare namespace Path {
  * // Run with custom path implementation
  * const result = Effect.provide(program, customPathLayer)
  * ```
+ *
+ * @category tag
+ * @since 4.0.0
  */
 export const Path: Context.Service<Path, Path> = Context.Service("effect/Path")
 
@@ -786,7 +845,12 @@ const posixImpl = Path.of({
 })
 
 /**
- * @since 4.0.0
+ * Layer that provides the built-in POSIX `Path` implementation.
+ *
+ * Use this layer when an effect requires the `Path` service and should use
+ * forward-slash path semantics.
+ *
  * @category Layers
+ * @since 4.0.0
  */
 export const layer: Layer.Layer<Path> = Layer.succeed(Path)(posixImpl)