effect 4.0.0-beta.69 → 4.0.0-beta.70

package/src/Ordering.ts

@@ -40,6 +40,8 @@ import * as Reducer_ from "./Reducer.ts"
 /**
  * Represents the result of comparing two values.
  *
+ * **Details**
+ *
  * - `-1` indicates the first value is less than the second
  * - `0` indicates the values are equal
  * - `1` indicates the first value is greater than the second
@@ -205,6 +207,8 @@ export const match: {
 /**
  * A `Reducer` for combining `Ordering`s.
  *
+ * **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.
  *

package/src/PartitionedSemaphore.ts

@@ -71,6 +71,8 @@ export type PartitionedTypeId = "~effect/PartitionedSemaphore"
  * A `PartitionedSemaphore` controls access to a shared permit pool while
  * tracking waiters by partition key.
  *
+ * **Details**
+ *
  * Waiting permits are distributed across partitions in round-robin order.
  *
  * @category models
@@ -109,17 +111,17 @@ export interface Partitioned<in K> extends PartitionedSemaphore<K> {}
 /**
  * Constructs a `PartitionedSemaphore` synchronously, outside of `Effect`.
  *
+ * **When to use**
+ *
+ * Prefer `make` when the semaphore should be created inside an `Effect`
+ * workflow.
+ *
  * **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.
- *
  * @category constructors
  * @since 3.19.4
  */

package/src/Path.ts

@@ -48,6 +48,8 @@ export const TypeId = "~effect/platform/Path"
 /**
  * Service interface for platform-specific path manipulation.
  *
+ * **Details**
+ *
  * 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`.
@@ -140,6 +142,8 @@ export declare namespace Path {
   /**
    * Structured representation of a parsed file system path.
    *
+   * **Details**
+   *
    * The fields correspond to the path root, directory, base filename,
    * extension, and filename without extension, matching the shape consumed by
    * `Path.format`.
@@ -188,6 +192,8 @@ export declare namespace Path {
 /**
  * Context 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`.
  *
@@ -847,6 +853,8 @@ const posixImpl = Path.of({
 /**
  * Layer that provides the built-in POSIX `Path` implementation.
  *
+ * **When to use**
+ *
  * Use this layer when an effect requires the `Path` service and should use
  * forward-slash path semantics.
  *

package/src/Pipeable.ts

@@ -25,6 +25,8 @@
 /**
  * Interface for values that support method-style `pipe` composition.
  *
+ * **Details**
+ *
  * Calling `value.pipe(f, g, h)` passes the value through each function from
  * left to right, returning the final result. Many Effect data types implement
  * this so operations can be chained without nesting function calls.
@@ -531,6 +533,8 @@ export interface Pipeable {
  * Applies a `pipe` method's variadic arguments to an initial value from left
  * to right.
  *
+ * **Details**
+ *
  * This helper is intended for implementing `Pipeable.pipe` methods that
  * receive JavaScript's `arguments` object. With no functions it returns the
  * original value; otherwise it feeds each result into the next function.
@@ -593,6 +597,8 @@ export const pipeArguments = <A>(self: A, args: IArguments): unknown => {
 /**
  * Reusable prototype that implements `Pipeable.pipe`.
  *
+ * **When to use**
+ *
  * Classes or object prototypes can reuse this value when they need the
  * standard pipe implementation backed by `pipeArguments`.
  *
@@ -609,6 +615,8 @@ export const Prototype: Pipeable = {
  * Base constructor whose instances implement the standard `Pipeable.pipe`
  * method.
  *
+ * **When to use**
+ *
  * Extend or compose this constructor when defining a class that should support
  * Effect-style method chaining through `.pipe(...)`.
  *
@@ -635,6 +643,8 @@ export interface PipeableConstructor {
  * Returns a subclass of the provided class that adds the standard `pipe`
  * method.
  *
+ * **Details**
+ *
  * The original constructor and instance members are preserved, and the added
  * method delegates to `pipeArguments`.
  *

package/src/PlatformError.ts

@@ -38,6 +38,8 @@ const TypeId = "~effect/platform/PlatformError"
 /**
  * Error data for an invalid argument passed to a platform API.
  *
+ * **Details**
+ *
  * The error records the module and method that rejected the argument, with an
  * optional description and cause. It is usually wrapped in `PlatformError`.
  *
@@ -63,6 +65,8 @@ export class BadArgument extends Data.TaggedError("BadArgument")<{
 /**
  * Normalized category for failures reported by platform or system operations.
  *
+ * **Details**
+ *
  * The tags group lower-level platform errors into a stable set such as
  * `NotFound`, `PermissionDenied`, `TimedOut`, and `Unknown`.
  *
@@ -85,6 +89,8 @@ export type SystemErrorTag =
 /**
  * Error data for a platform or system operation failure.
  *
+ * **Details**
+ *
  * The error records a normalized `_tag`, the module and method that failed,
  * and optional details such as the syscall, path or descriptor, description,
  * and original cause. It is usually wrapped in `PlatformError`.
@@ -117,6 +123,8 @@ export class SystemError extends Data.Error<{
  * Tagged error used by platform APIs to report either invalid arguments or
  * system-level failures.
  *
+ * **Details**
+ *
  * The `reason` field contains the underlying `BadArgument` or `SystemError`.
  * When that reason has a cause, the cause is preserved on the wrapper.
  *
@@ -149,6 +157,8 @@ export class PlatformError extends Data.TaggedError("PlatformError")<{
 /**
  * Creates a `PlatformError` whose reason is a `SystemError`.
  *
+ * **When to use**
+ *
  * Use this helper when adapting an operating-system or platform failure into
  * the normalized platform error model.
  *
@@ -168,6 +178,8 @@ export const systemError = (options: {
 /**
  * Creates a `PlatformError` whose reason is a `BadArgument`.
  *
+ * **When to use**
+ *
  * Use this helper when a platform API rejects caller input before performing
  * the underlying operation.
  *

package/src/Pool.ts

@@ -154,10 +154,13 @@ export interface Strategy<A, E> {
 export const isPool = (u: unknown): u is Pool<unknown, unknown> => hasProperty(u, TypeId)
 
 /**
- * Makes a new pool of the specified fixed size. The pool is returned in a
- * `Scope`, which governs the lifetime of the pool. When the pool is shutdown
- * because the `Scope` is closed, the individual items allocated by the pool
- * will be released in some unspecified order.
+ * Makes a new pool of the specified fixed size.
+ *
+ * **Details**
+ *
+ * The pool is returned in a `Scope`, which governs the lifetime of the pool.
+ * When the pool is shutdown because the `Scope` is closed, the individual
+ * items allocated by the pool will be released in some unspecified order.
  *
  * By setting the `concurrency` parameter, you can control the level of concurrent
  * access per pool item. By default, the number of permits is set to `1`.
@@ -198,23 +201,34 @@ export const make = <A, E, R>(options: {
  * from item creation, while `"usage"` measures from pool usage. The default is
  * `"usage"`.
  *
- * ```ts skip-type-checking
+ * **Example** (Create a connection pool)
+ *
+ * ```ts
  * import { Duration, Effect, Pool } from "effect"
- * import { createConnection } from "mysql2"
+ *
+ * interface Connection {
+ *   readonly execute: (sql: string) => Effect.Effect<ReadonlyArray<string>>
+ *   readonly close: Effect.Effect<void>
+ * }
  *
  * const acquireDBConnection = Effect.acquireRelease(
- *   Effect.sync(() => createConnection("mysql://...")),
- *   (connection) => Effect.sync(() => connection.end(() => {}))
+ *   Effect.succeed({
+ *     execute: (sql) => Effect.succeed([`executed: ${sql}`]),
+ *     close: Effect.void
+ *   } satisfies Connection),
+ *   (connection) => connection.close
  * )
  *
- * const connectionPool = Effect.flatMap(
- *   Pool.makeWithTTL({
- *     acquire: acquireDBConnection,
- *     min: 10,
- *     max: 20,
- *     timeToLive: Duration.seconds(60)
- *   }),
- *   (pool) => pool.get
+ * const program = Effect.scoped(
+ *   Effect.flatMap(
+ *     Pool.makeWithTTL({
+ *       acquire: acquireDBConnection,
+ *       min: 10,
+ *       max: 20,
+ *       timeToLive: Duration.seconds(60)
+ *     }),
+ *     (pool) => Effect.flatMap(Pool.get(pool), (connection) => connection.execute("select 1"))
+ *   )
  * )
  * ```
  *