effect 4.0.0-beta.78 → 4.0.0-beta.79

package/src/NonEmptyIterable.ts

@@ -4,141 +4,6 @@
  * `NonEmptyIterable<A>` can be consumed anywhere an `Iterable<A>` is expected,
  * while also carrying the guarantee that reading the first element is safe.
  *
- * **Mental model**
- *
- * - `NonEmptyIterable<A>` is an `Iterable<A>` branded with a non-empty guarantee
- * - The guarantee is static: values should only be typed this way when construction or validation proves at least one element exists
- * - The iterable can be an array, string, set, map, generator, or any custom iterable
- * - `unprepend` safely separates the first element from an iterator for the remaining elements
- * - Operations that may remove elements, such as filtering, usually return ordinary collections because they can become empty
- *
- * **Common tasks**
- *
- * - Accept inputs that must contain at least one value
- * - Extract a head element and process the remaining iterator with {@link unprepend}
- * - Model APIs such as reductions, comparisons, or aggregation that are undefined for empty inputs
- * - Preserve compatibility with the JavaScript iteration protocol while documenting the stronger invariant
- *
- * **Gotchas**
- *
- * - A type assertion does not make an empty iterable non-empty; only assert after a trusted check or constructor
- * - Iterators are stateful, so calling {@link unprepend} consumes the first yielded value from that iterator
- * - The order of the first element follows the source iterable's iteration order, for example insertion order for `Map` and `Set`
- * - Some transformations preserve non-emptiness, but transformations that can discard elements must account for the empty case
- *
- * **Quickstart**
- *
- * **Example** (Requiring a non-empty iterable)
- *
- * ```ts
- * import { NonEmptyIterable } from "effect"
- *
- * // NonEmptyIterable is a type that represents any iterable with at least one element
- * function processNonEmpty<A>(data: NonEmptyIterable.NonEmptyIterable<A>): A {
- *   // Safe to get the first element - guaranteed to exist
- *   const [first] = NonEmptyIterable.unprepend(data)
- *   return first
- * }
- *
- * // Using Array.make to create non-empty arrays
- * const numbers = Array.make(
- *   1,
- *   2,
- *   3,
- *   4,
- *   5
- * ) as unknown as NonEmptyIterable.NonEmptyIterable<number>
- * const firstNumber = processNonEmpty(numbers) // number
- *
- * // Regular arrays can be asserted as NonEmptyIterable when known to be non-empty
- * const values = [1, 2, 3] as unknown as NonEmptyIterable.NonEmptyIterable<number>
- * const firstValue = processNonEmpty(values) // number
- *
- * // Custom iterables that are guaranteed non-empty
- * function* generateNumbers(): NonEmptyIterable.NonEmptyIterable<number> {
- *   yield 1
- *   yield 2
- *   yield 3
- * }
- *
- * const firstGenerated = processNonEmpty(generateNumbers()) // number
- * ```
- *
- * ## Working with Different Iterable Types
- *
- * **Example** (Adapting iterable inputs)
- *
- * ```ts
- * import { Array } from "effect"
- *
- * // Creating non-empty arrays
- * const nonEmptyArray = Array.make(
- *   1,
- *   2,
- *   3
- * ) as unknown as NonEmptyIterable.NonEmptyIterable<number>
- *
- * // Working with strings (assert as NonEmptyIterable when known to be non-empty)
- * const nonEmptyString = "hello" as unknown as NonEmptyIterable.NonEmptyIterable<
- *   string
- * >
- * const [firstChar] = NonEmptyIterable.unprepend(nonEmptyString)
- * console.log(firstChar) // "h"
- *
- * // Working with Maps (assert when known to be non-empty)
- * const nonEmptyMap = new Map([
- *   ["key1", "value1"],
- *   ["key2", "value2"]
- * ]) as unknown as NonEmptyIterable.NonEmptyIterable<[string, string]>
- * const [firstEntry] = NonEmptyIterable.unprepend(nonEmptyMap)
- * console.log(firstEntry) // ["key1", "value1"]
- *
- * // Custom generator functions
- * function* fibonacci(): NonEmptyIterable.NonEmptyIterable<number> {
- *   let a = 1, b = 1
- *   yield a
- *   while (true) {
- *     yield b
- *     const next = a + b
- *     a = b
- *     b = next
- *   }
- * }
- *
- * const [firstFib, restFib] = NonEmptyIterable.unprepend(
- *   fibonacci() as unknown as NonEmptyIterable.NonEmptyIterable<number>
- * )
- * console.log(firstFib) // 1
- * ```
- *
- * ## Integration with Effect Arrays
- *
- * **Example** (Processing non-empty iterables with Array)
- *
- * ```ts
- * import { Array, pipe } from "effect"
- * import type { NonEmptyIterable } from "effect"
- *
- * // Many Array functions work with NonEmptyIterable
- * declare const nonEmptyData: NonEmptyIterable.NonEmptyIterable<number>
- *
- * const processData = pipe(
- *   nonEmptyData,
- *   Array.fromIterable,
- *   Array.map((x) => x * 2),
- *   Array.filter((x) => x > 5)
- *   // Result is a regular array since filtering might make it empty
- * )
- *
- * // Safe operations that preserve non-emptiness
- * const doubledData = pipe(
- *   nonEmptyData,
- *   Array.fromIterable,
- *   Array.map((x) => x * 2)
- *   // This would still be non-empty if the source was non-empty
- * )
- * ```
- *
  * @since 2.0.0
  */
 

package/src/Number.ts

@@ -1,60 +1,9 @@
 /**
- * Operations for working with TypeScript `number` values. Use this module for
- * arithmetic, safe parsing and division, comparisons, range checks, clamping,
- * rounding, and reducers for numeric aggregation.
- *
- * **Mental model**
- *
- * Numbers remain plain JavaScript numbers, including `NaN`, `Infinity`, and
- * floating-point behavior. The module adds named operations around that runtime
- * model: arithmetic such as {@link sum}, {@link multiply}, {@link subtract},
- * and {@link remainder}; safety wrappers such as {@link parse} and
- * {@link divide}; range helpers such as {@link between} and {@link clamp}; and
- * instances such as {@link Order} and {@link Equivalence}.
- *
- * **Common tasks**
- *
- * - Coerce, parse, or narrow input: {@link Number}, {@link parse},
- *   {@link isNumber}
- * - Do arithmetic: {@link sum}, {@link multiply}, {@link subtract},
- *   {@link divide}, {@link divideUnsafe}, {@link remainder}, {@link round}
- * - Work with counters and powers: {@link increment}, {@link decrement},
- *   {@link nextPow2}
- * - Compare and bound values: {@link isLessThan}, {@link isGreaterThan},
- *   {@link between}, {@link clamp}, {@link min}, {@link max}, {@link sign}
- * - Aggregate iterables or reducer inputs: {@link sumAll}, {@link multiplyAll},
- *   {@link ReducerSum}, {@link ReducerMultiply}, {@link ReducerMax},
- *   {@link ReducerMin}
+ * Works with TypeScript `number` values.
  *
- * **Gotchas**
- *
- * - {@link Number} is the native JavaScript constructor. For example,
- *   `Number.Number("")` returns `0`; {@link parse} returns `Option.none()` for
- *   blank strings and invalid numeric text.
- * - {@link divide} returns `Option.none()` only when the divisor is `0`.
- *   Other JavaScript number results, including `NaN`, still follow normal
- *   number semantics.
- * - {@link Equivalence} treats `NaN` as equivalent to `NaN`, unlike `===`.
- * - Reducers have identity values: {@link ReducerSum} starts at `0`,
- *   {@link ReducerMultiply} starts at `1`, {@link ReducerMax} starts at
- *   `-Infinity`, and {@link ReducerMin} starts at `Infinity`.
- *
- * **Quickstart**
- *
- * **Example** (Parsing and bounding a number)
- *
- * ```ts
- * import { Number } from "effect"
- *
- * const parsed = Number.parse("42")
- * console.log(parsed) // Option.some(42)
- *
- * const bounded = Number.clamp(120, { minimum: 0, maximum: 100 })
- * console.log(bounded) // 100
- *
- * const total = Number.sumAll([1, 2, 3])
- * console.log(total) // 6
- * ```
+ * This module exposes the native `Number` constructor together with helpers for
+ * checking, parsing, arithmetic, safe division, comparison, range checks,
+ * clamping, rounding, ordering, equivalence, and numeric aggregation.
  *
  * @since 2.0.0
  */

package/src/Optic.ts

@@ -1,95 +1,13 @@
 /**
- * Composable, immutable accessors for reading and updating nested data
- * structures without mutation.
- *
- * **Mental model**
- *
- * - **Optic** — a first-class reference to a piece inside a larger structure.
- *   Compose optics to reach deeply nested values.
- * - **Iso** — lossless two-way conversion (`get`/`set`) between `S` and `A`.
- *   Extends both {@link Lens} and {@link Prism}.
- * - **Lens** — focuses on exactly one part of `S`. `get` always succeeds;
- *   `replace` needs the original `S` to produce the updated whole.
- * - **Prism** — focuses on a part that may not be present (e.g. a union
- *   variant). `getResult` can fail; `set` builds a new `S` from `A` alone.
- * - **Optional** — the most general optic: both reading and writing can fail.
- * - **Traversal** — focuses on zero or more elements of an array-like
- *   structure. Technically `Optional<S, ReadonlyArray<A>>`.
- * - **Hierarchy** (strongest → weakest):
- *   `Iso > Lens | Prism > Optional`. Composing a weaker optic with any other
- *   produces the weaker kind.
- *
- * **Common tasks**
- *
- * - Start a chain → {@link id} (identity iso)
- * - Drill into a struct key → `.key("name")` / `.optionalKey("name")`
- * - Drill into a key that may not exist → `.at("name")`
- * - Narrow a tagged union → `.tag("MyVariant")`
- * - Narrow by type guard → `.refine(guard)`
- * - Add validation → `.check(Schema.isGreaterThan(0))`
- * - Filter out `undefined` → `.notUndefined()`
- * - Pick/omit struct keys → `.pick(["a","b"])` / `.omit(["c"])`
- * - Traverse array elements → `.forEach(el => el.key("field"))`
- * - Build an iso → {@link makeIso}
- * - Build a lens → {@link makeLens}
- * - Build a prism → {@link makePrism}, {@link fromChecks}
- * - Build an optional → {@link makeOptional}
- * - Focus into `Option.Some` → {@link some}
- * - Focus into `Result.Success`/`Failure` → {@link success}, {@link failure}
- * - Convert record ↔ entries → {@link entries}
- * - Extract all traversal elements → {@link getAll}
- *
- * **Gotchas**
- *
- * - Updates are structurally persistent: only nodes on the path are cloned.
- *   Unrelated branches keep referential identity. However, **no-op updates
- *   may still allocate** a new root — do not rely on reference identity to
- *   detect no-ops.
- * - `replace` silently returns the original `S` when the optic cannot focus
- *   (e.g. wrong tag). Use `replaceResult` for explicit failure.
- * - `modify` also returns the original `S` on focus failure — it never throws.
- * - `.key()` and `.optionalKey()` do not work on union types (compile error).
- * - Only plain objects (`Object.prototype` or `null` prototype) and arrays can
- *   be cloned. Class instances cause a runtime error on `replace`/`modify`.
- *
- * **Quickstart**
- *
- * **Example** (reading and updating nested state)
- *
- * ```ts
- * import { Optic } from "effect"
- *
- * type State = { user: { name: string; age: number } }
- *
- * const _age = Optic.id<State>().key("user").key("age")
- *
- * const s1: State = { user: { name: "Alice", age: 30 } }
- *
- * // Read
- * console.log(_age.get(s1))
- * // Output: 30
- *
- * // Update immutably
- * const s2 = _age.replace(31, s1)
- * console.log(s2)
- * // Output: { user: { name: "Alice", age: 31 } }
- *
- * // Modify with a function
- * const s3 = _age.modify((n) => n + 1)(s1)
- * console.log(s3)
- * // Output: { user: { name: "Alice", age: 31 } }
- *
- * // Referential identity is preserved for unrelated branches
- * console.log(s2.user !== s1.user)
- * // Output: true (on the path)
- * ```
- *
- * **See also**
- *
- * - {@link id} — entry point for optic chains
- * - {@link Lens} / {@link Prism} / {@link Optional} — core optic types
- * - {@link Traversal} / {@link getAll} — multi-focus optics
- * - {@link some} / {@link success} / {@link failure} — built-in prisms
+ * Reads and updates focused parts of values without mutating the original
+ * value.
+ *
+ * An optic describes where to look inside a value, such as a record field, a
+ * union variant, an optional value, or several values in a collection. Different
+ * optic types describe different kinds of focus: some always find a value,
+ * some may not, and some can find many. This module includes the optic types,
+ * constructors, focusing helpers, and operations for replacing, modifying, or
+ * collecting focused values.
  *
  * @since 4.0.0
  */

package/src/Option.ts

@@ -1,73 +1,12 @@
 /**
- * The `Option` module provides a type-safe way to represent values that may or
- * may not exist. An `Option<A>` is either `Some<A>` (containing a value) or
- * `None` (representing absence).
- *
- * **Mental model**
- *
- * - `Option<A>` is a discriminated union: `None | Some<A>`
- * - `None` represents the absence of a value (like `null`/`undefined`, but type-safe)
- * - `Some<A>` wraps a present value of type `A`, accessed via `.value`
- * - `Option` is a monad: chain operations with {@link flatMap}, compose pipelines with `pipe`
- * - All operations are pure and return new `Option` values; the input is never mutated
- * - `Option` is yieldable in `Effect.gen`, producing the inner value or short-circuiting with `NoSuchElementError`
- *
- * **Common tasks**
- *
- * - Create from a value: {@link some}, {@link none}
- * - Create from nullable: {@link fromNullishOr}, {@link fromNullOr}, {@link fromUndefinedOr}
- * - Create from iterable: {@link fromIterable}
- * - Create from Result: {@link getSuccess}, {@link getFailure}
- * - Transform: {@link map}, {@link flatMap}, {@link andThen}
- * - Unwrap: {@link getOrElse}, {@link getOrNull}, {@link getOrUndefined}, {@link getOrThrow}
- * - Pattern match: {@link match}
- * - Fallbacks: {@link orElse}, {@link orElseSome}, {@link firstSomeOf}
- * - Filter: {@link filter}, {@link filterMap}
- * - Combine multiple: {@link all}, {@link zipWith}, {@link product}
- * - Generator syntax: {@link gen}
- * - Do notation: {@link Do}, {@link bind}, {@link let_ let}
- * - Check contents: {@link isSome}, {@link isNone}, {@link contains}, {@link exists}
- *
- * **Gotchas**
- *
- * - `Option.some(null)` is a valid `Some`; use {@link fromNullishOr} to treat `null`/`undefined` as `None`
- * - {@link filterMap} uses a `Filter` callback that returns `Result`
- * - {@link getOrThrow} throws a generic `Error`; prefer {@link getOrThrowWith} for custom errors
- * - `None` is a singleton; compare with {@link isNone}, not `===`
- * - When yielded in `Effect.gen`, a `None` becomes a `NoSuchElementError` defect
- *
- * **Quickstart**
- *
- * **Example** (Working with optional values)
- *
- * ```ts
- * import { Option } from "effect"
- *
- * const name = Option.some("Alice")
- * const age = Option.none<number>()
- *
- * // Transform
- * const upper = Option.map(name, (s) => s.toUpperCase())
- *
- * // Unwrap with fallback
- * console.log(Option.getOrElse(upper, () => "unknown"))
- * // Output: "ALICE"
- *
- * console.log(Option.getOrElse(age, () => 0))
- * // Output: 0
- *
- * // Combine multiple options
- * const both = Option.all({ name, age })
- * console.log(Option.isNone(both))
- * // Output: true
- * ```
- *
- * **See also**
- *
- * - {@link some} / {@link none} for creating values
- * - {@link map} / {@link flatMap} for transforming values
- * - {@link match} for pattern matching
- * - {@link gen} for generator-based syntax
+ * Models a value that may be present or absent.
+ *
+ * An `Option<A>` is `Some<A>` when a value is available and `None` when it is
+ * not. This lets code handle missing values explicitly instead of relying on
+ * `null` or `undefined`. The module includes helpers for creating, checking,
+ * transforming, combining, and extracting optional values, plus conversions to
+ * and from common nullable or result-like shapes. It also includes `Option.gen`
+ * for writing small generator-based computations that stop at the first `None`.
  *
  * @since 2.0.0
  */

package/src/Order.ts

@@ -1,80 +1,12 @@
 /**
- * The `Order` module defines total orderings: pure comparison functions that
- * decide whether one value is less than, equal to, or greater than another. An
- * `Order<A>` returns a normalized {@link Ordering} (`-1`, `0`, or `1`), making
- * it suitable for sorting, finding minimum and maximum values, range checks, and
- * building ordered data structures.
- *
- * **Mental model**
- *
- * - An {@link Order} is a comparator with laws: totality, antisymmetry, and
- *   transitivity. If those laws do not hold, sorting and range operations can
- *   produce surprising results.
- * - `-1` means the left value comes before the right value, `0` means they are
- *   equal for this ordering, and `1` means the left value comes after the right
- *   value.
- * - Primitive orders such as {@link Number}, {@link String}, {@link Boolean},
- *   {@link BigInt}, and {@link Date} are building blocks.
- * - Use {@link mapInput} to compare larger values by a field or derived key.
- * - Use {@link combine} or {@link combineAll} for tie-breaking, where the first
- *   non-zero comparison result wins.
- *
- * **Common tasks**
- *
- * - Create a custom order from a comparison function with {@link make}.
- * - Sort or compare using built-in orders such as {@link Number} and
- *   {@link String}.
- * - Compare records and tuples with {@link Struct} and {@link Tuple}.
- * - Compare arrays lexicographically with {@link Array}.
- * - Convert an order into predicates with {@link isLessThan},
- *   {@link isGreaterThan}, {@link isLessThanOrEqualTo}, and
- *   {@link isGreaterThanOrEqualTo}.
- * - Select boundaries with {@link min}, {@link max}, {@link clamp}, and
- *   {@link isBetween}.
- *
- * **Gotchas**
- *
- * - {@link make} returns `0` immediately when `self === that`; the custom
- *   comparison function is not called for identical references.
- * - {@link Number} treats all `NaN` values as equal to each other and less than
- *   every non-`NaN` number.
- * - {@link Array} compares elements first and length second. {@link Tuple}
- *   compares a fixed number of positions.
- * - {@link Struct} compares fields in the key order of the object passed to it,
- *   so put the highest-priority fields first.
- * - {@link min} and {@link max} return the first argument when two values
- *   compare as equal.
- *
- * **Example** (Sorting by multiple fields)
- *
- * ```ts
- * import { Array, Order } from "effect"
- *
- * interface User {
- *   readonly name: string
- *   readonly age: number
- * }
- *
- * const byAge = Order.mapInput(Order.Number, (user: User) => user.age)
- * const byName = Order.mapInput(Order.String, (user: User) => user.name)
- * const byAgeThenName = Order.combine(byAge, byName)
- *
- * const users = [
- *   { name: "Charlie", age: 30 },
- *   { name: "Bob", age: 25 },
- *   { name: "Alice", age: 30 }
- * ]
- *
- * const sorted = Array.sort(users, byAgeThenName)
- * console.log(sorted.map((user) => user.name))
- * // ["Bob", "Alice", "Charlie"]
- * ```
- *
- * **See also**
- *
- * - {@link Ordering} for the normalized comparison result type.
- * - `Equivalence` for equality without less-than or greater-than.
- * - {@link Reducer} for combining orders with reducer-style APIs.
+ * Defines comparison functions for ordered values.
+ *
+ * An `Order<A>` compares two `A` values and returns whether the first is less
+ * than, equal to, or greater than the second. Orders are used for sorting,
+ * choosing minimum or maximum values, checking ranges, and building ordered data
+ * structures. This module includes built-in orders, constructors for custom
+ * orders, tools for reversing and combining comparisons, tuple and struct
+ * helpers, comparison predicates, clamping, and reducer support.
  *
  * @since 2.0.0
  */

package/src/Ordering.ts

@@ -1,35 +1,9 @@
 /**
- * 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
+ * The standard result of comparing two values. An `Ordering` is `-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. This module also
+ * provides helpers for reversing an ordering, matching on the three cases, and
+ * combining ordered comparison results with a reducer.
  *
  * @since 2.0.0
  */

package/src/PartitionedSemaphore.ts

@@ -5,34 +5,6 @@
  * 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"

package/src/Path.ts

@@ -1,33 +1,11 @@
 /**
- * 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
+ * Provides path operations through the Effect environment.
+ *
+ * The `Path` service works with file system paths without tying code to one
+ * concrete platform module. It exposes common operations such as joining,
+ * normalizing, parsing, formatting, resolving, and converting paths to or from
+ * file URLs. This module includes the service interface, parsed path type,
+ * service tag, runtime marker, and built-in POSIX path layer.
  *
  * @since 4.0.0
  */

package/src/Pipeable.ts

@@ -8,17 +8,6 @@
  * to compose transformations, validations, and effectful operations while
  * keeping the original value as the starting point of the pipeline.
  *
- * **Common tasks**
- *
- * - Type values that expose a `.pipe(...)` method with the {@link Pipeable} interface
- * - Implement a custom `.pipe(...)` method with {@link pipeArguments}
- * - Reuse the standard implementation through {@link Prototype}, {@link Class}, or {@link Mixin}
- *
- * **Gotchas**
- *
- * - Each function receives the result of the previous function, not the original value
- * - The overloads preserve precise types for long pipelines, but very long chains may be easier to read when split
- *
  * @since 2.0.0
  */
 

package/src/PlatformError.ts

@@ -1,33 +1,11 @@
 /**
- * The `PlatformError` module defines the normalized error model used by
- * platform APIs when adapting host operations into Effect programs. It gives
- * callers a stable `PlatformError` wrapper whose `reason` is either a
- * `BadArgument`, for invalid inputs rejected before an operation runs, or a
- * `SystemError`, for failures reported by the host platform or operating
- * system.
- *
- * Use this module when implementing or consuming platform services such as
- * file systems, terminal access, sockets, or other environment-specific APIs.
- * `SystemError` intentionally groups many low-level failures into a small set
- * of portable tags like `NotFound`, `PermissionDenied`, and `TimedOut`, while
- * still preserving operation details such as the module, method, syscall, path
- * or descriptor, description, and original cause when available.
- *
- * **Common tasks**
- *
- * - Create platform failures from system operations with {@link systemError}
- * - Report rejected caller input with {@link badArgument}
- * - Inspect the underlying reason via {@link PlatformError.reason}
- * - Match normalized system failures with {@link SystemErrorTag}
- *
- * **Gotchas**
- *
- * - `PlatformError` is a wrapper; inspect `reason` to distinguish
- *   `BadArgument` from `SystemError`
- * - `SystemErrorTag` values are normalized categories, not necessarily raw
- *   platform error codes
- * - The original cause is preserved when provided, but portable handling
- *   should rely on the normalized fields
+ * Normalized errors for platform APIs.
+ *
+ * Platform services such as file systems, terminals, and sockets use
+ * `PlatformError` to report host-level failures in a consistent shape. The
+ * wrapper records whether the problem came from an invalid argument or from the
+ * operating system, while preserving useful details such as the module, method,
+ * path, descriptor, description, and original cause when available.
  *
  * @since 4.0.0
  */