effect 4.0.0-beta.71 → 4.0.0-beta.73

package/src/Iterable.ts

@@ -147,7 +147,7 @@ export const range = (start: number, end?: number): Iterable<number> => {
 }
 
 /**
- * Return a `Iterable` containing a value repeated the specified number of times.
+ * Returns a `Iterable` containing a value repeated the specified number of times.
  *
  * **Details**
  *
@@ -167,7 +167,7 @@ export const range = (start: number, end?: number): Iterable<number> => {
  */
 export const replicate: {
   /**
-   * Return a `Iterable` containing a value repeated the specified number of times.
+   * Returns a `Iterable` containing a value repeated the specified number of times.
    *
    * **Details**
    *
@@ -187,7 +187,7 @@ export const replicate: {
    */
   (n: number): <A>(a: A) => Iterable<A>
   /**
-   * Return a `Iterable` containing a value repeated the specified number of times.
+   * Returns a `Iterable` containing a value repeated the specified number of times.
    *
    * **Details**
    *
@@ -315,7 +315,7 @@ export const fromRecord = <K extends string, A>(self: Readonly<Record<K, A>>): I
 })
 
 /**
- * Prepend an element to the front of an `Iterable`, creating a new `Iterable`.
+ * Prepends an element to the front of an `Iterable`, creating a new `Iterable`.
  *
  * **Example** (Prepending an element)
  *
@@ -337,7 +337,7 @@ export const fromRecord = <K extends string, A>(self: Readonly<Record<K, A>>): I
  */
 export const prepend: {
   /**
-   * Prepend an element to the front of an `Iterable`, creating a new `Iterable`.
+   * Prepends an element to the front of an `Iterable`, creating a new `Iterable`.
    *
    * **Example** (Prepending an element)
    *
@@ -359,7 +359,7 @@ export const prepend: {
    */
   <B>(head: B): <A>(self: Iterable<A>) => Iterable<A | B>
   /**
-   * Prepend an element to the front of an `Iterable`, creating a new `Iterable`.
+   * Prepends an element to the front of an `Iterable`, creating a new `Iterable`.
    *
    * **Example** (Prepending an element)
    *
@@ -445,7 +445,7 @@ export const prependAll: {
 )
 
 /**
- * Append an element to the end of an `Iterable`, creating a new `Iterable`.
+ * Appends an element to the end of an `Iterable`, creating a new `Iterable`.
  *
  * **When to use**
  *
@@ -487,7 +487,7 @@ export const prependAll: {
  */
 export const append: {
   /**
-   * Append an element to the end of an `Iterable`, creating a new `Iterable`.
+   * Appends an element to the end of an `Iterable`, creating a new `Iterable`.
    *
    * **When to use**
    *
@@ -529,7 +529,7 @@ export const append: {
    */
   <B>(last: B): <A>(self: Iterable<A>) => Iterable<A | B>
   /**
-   * Append an element to the end of an `Iterable`, creating a new `Iterable`.
+   * Appends an element to the end of an `Iterable`, creating a new `Iterable`.
    *
    * **When to use**
    *
@@ -739,7 +739,7 @@ export const appendAll: {
 )
 
 /**
- * Reduce an `Iterable` from the left, keeping all intermediate results instead of only the final result.
+ * Reduces an `Iterable` from the left, keeping all intermediate results instead of only the final result.
  *
  * **Example** (Tracking running results)
  *
@@ -767,7 +767,7 @@ export const appendAll: {
  */
 export const scan: {
   /**
-   * Reduce an `Iterable` from the left, keeping all intermediate results instead of only the final result.
+   * Reduces an `Iterable` from the left, keeping all intermediate results instead of only the final result.
    *
    * **Example** (Tracking running results)
    *
@@ -795,7 +795,7 @@ export const scan: {
    */
   <B, A>(b: B, f: (b: B, a: A) => B): (self: Iterable<A>) => Iterable<B>
   /**
-   * Reduce an `Iterable` from the left, keeping all intermediate results instead of only the final result.
+   * Reduces an `Iterable` from the left, keeping all intermediate results instead of only the final result.
    *
    * **Example** (Tracking running results)
    *
@@ -843,7 +843,7 @@ export const scan: {
 }))
 
 /**
- * Determine if an `Iterable` is empty
+ * Checks whether an `Iterable` is empty.
  *
  * **Example** (Checking for emptiness)
  *
@@ -864,7 +864,7 @@ export const isEmpty = <A>(self: Iterable<A>): self is Iterable<never> => {
 }
 
 /**
- * Return the number of elements in a `Iterable`.
+ * Returns the number of elements in a `Iterable`.
  *
  * **Example** (Counting iterable elements)
  *
@@ -899,7 +899,7 @@ export const size = <A>(self: Iterable<A>): number => {
 }
 
 /**
- * Get the first element of a `Iterable`, or `None` if the `Iterable` is empty.
+ * Gets the first element of a `Iterable` safely, or `None` if the `Iterable` is empty.
  *
  * **Example** (Getting the first element)
  *
@@ -933,7 +933,7 @@ export const head = <A>(self: Iterable<A>): Option<A> => {
 }
 
 /**
- * Get the first element of a `Iterable`, or throw an error if the `Iterable` is empty.
+ * Gets the first element of a `Iterable`, or throw an error if the `Iterable` is empty.
  *
  * **Example** (Getting the first element unsafely)
  *
@@ -965,7 +965,7 @@ export const headUnsafe = <A>(self: Iterable<A>): A => {
 }
 
 /**
- * Keep only a max number of elements from the start of an `Iterable`, creating a new `Iterable`.
+ * Keeps only a max number of elements from the start of an `Iterable`, creating a new `Iterable`.
  *
  * **Details**
  *
@@ -999,7 +999,7 @@ export const headUnsafe = <A>(self: Iterable<A>): A => {
  */
 export const take: {
   /**
-   * Keep only a max number of elements from the start of an `Iterable`, creating a new `Iterable`.
+   * Keeps only a max number of elements from the start of an `Iterable`, creating a new `Iterable`.
    *
    * **Details**
    *
@@ -1033,7 +1033,7 @@ export const take: {
    */
   (n: number): <A>(self: Iterable<A>) => Iterable<A>
   /**
-   * Keep only a max number of elements from the start of an `Iterable`, creating a new `Iterable`.
+   * Keeps only a max number of elements from the start of an `Iterable`, creating a new `Iterable`.
    *
    * **Details**
    *
@@ -1083,7 +1083,8 @@ export const take: {
 }))
 
 /**
- * Calculate the longest initial Iterable for which all element satisfy the specified predicate, creating a new `Iterable`.
+ * Takes the longest initial `Iterable` prefix for which all elements satisfy the
+ * specified predicate.
  *
  * **Example** (Taking while a predicate holds)
  *
@@ -1118,7 +1119,8 @@ export const take: {
  */
 export const takeWhile: {
   /**
-   * Calculate the longest initial Iterable for which all element satisfy the specified predicate, creating a new `Iterable`.
+   * Takes the longest initial `Iterable` prefix for which all elements satisfy the
+   * specified predicate.
    *
    * **Example** (Taking while a predicate holds)
    *
@@ -1153,7 +1155,8 @@ export const takeWhile: {
    */
   <A, B extends A>(refinement: (a: NoInfer<A>, i: number) => a is B): (self: Iterable<A>) => Iterable<B>
   /**
-   * Calculate the longest initial Iterable for which all element satisfy the specified predicate, creating a new `Iterable`.
+   * Takes the longest initial `Iterable` prefix for which all elements satisfy the
+   * specified predicate.
    *
    * **Example** (Taking while a predicate holds)
    *
@@ -1188,7 +1191,8 @@ export const takeWhile: {
    */
   <A>(predicate: (a: NoInfer<A>, i: number) => boolean): (self: Iterable<A>) => Iterable<A>
   /**
-   * Calculate the longest initial Iterable for which all element satisfy the specified predicate, creating a new `Iterable`.
+   * Takes the longest initial `Iterable` prefix for which all elements satisfy the
+   * specified predicate.
    *
    * **Example** (Taking while a predicate holds)
    *
@@ -1223,7 +1227,8 @@ export const takeWhile: {
    */
   <A, B extends A>(self: Iterable<A>, refinement: (a: A, i: number) => a is B): Iterable<B>
   /**
-   * Calculate the longest initial Iterable for which all element satisfy the specified predicate, creating a new `Iterable`.
+   * Takes the longest initial `Iterable` prefix for which all elements satisfy the
+   * specified predicate.
    *
    * **Example** (Taking while a predicate holds)
    *
@@ -1274,7 +1279,7 @@ export const takeWhile: {
 }))
 
 /**
- * Drop a max number of elements from the start of an `Iterable`
+ * Drops a max number of elements from the start of an `Iterable`
  *
  * **Details**
  *
@@ -1307,7 +1312,7 @@ export const takeWhile: {
  */
 export const drop: {
   /**
-   * Drop a max number of elements from the start of an `Iterable`
+   * Drops a max number of elements from the start of an `Iterable`
    *
    * **Details**
    *
@@ -1340,7 +1345,7 @@ export const drop: {
    */
   (n: number): <A>(self: Iterable<A>) => Iterable<A>
   /**
-   * Drop a max number of elements from the start of an `Iterable`
+   * Drops a max number of elements from the start of an `Iterable`
    *
    * **Details**
    *
@@ -1700,7 +1705,7 @@ export const findFirst: {
 )
 
 /**
- * Find the last element for which a predicate holds.
+ * Finds the last element for which a predicate holds.
  *
  * **Example** (Finding the last match)
  *
@@ -1733,7 +1738,7 @@ export const findFirst: {
  */
 export const findLast: {
   /**
-   * Find the last element for which a predicate holds.
+   * Finds the last element for which a predicate holds.
    *
    * **Example** (Finding the last match)
    *
@@ -1766,7 +1771,7 @@ export const findLast: {
    */
   <A, B>(f: (a: NoInfer<A>, i: number) => Option<B>): (self: Iterable<A>) => Option<B>
   /**
-   * Find the last element for which a predicate holds.
+   * Finds the last element for which a predicate holds.
    *
    * **Example** (Finding the last match)
    *
@@ -1799,7 +1804,7 @@ export const findLast: {
    */
   <A, B extends A>(refinement: (a: NoInfer<A>, i: number) => a is B): (self: Iterable<A>) => Option<B>
   /**
-   * Find the last element for which a predicate holds.
+   * Finds the last element for which a predicate holds.
    *
    * **Example** (Finding the last match)
    *
@@ -1832,7 +1837,7 @@ export const findLast: {
    */
   <A>(predicate: (a: NoInfer<A>, i: number) => boolean): (self: Iterable<A>) => Option<A>
   /**
-   * Find the last element for which a predicate holds.
+   * Finds the last element for which a predicate holds.
    *
    * **Example** (Finding the last match)
    *
@@ -1865,7 +1870,7 @@ export const findLast: {
    */
   <A, B>(self: Iterable<A>, f: (a: A, i: number) => Option<B>): Option<B>
   /**
-   * Find the last element for which a predicate holds.
+   * Finds the last element for which a predicate holds.
    *
    * **Example** (Finding the last match)
    *
@@ -1898,7 +1903,7 @@ export const findLast: {
    */
   <A, B extends A>(self: Iterable<A>, refinement: (a: A, i: number) => a is B): Option<B>
   /**
-   * Find the last element for which a predicate holds.
+   * Finds the last element for which a predicate holds.
    *
    * **Example** (Finding the last match)
    *
@@ -2066,7 +2071,7 @@ export const zip: {
 )
 
 /**
- * Apply a function to pairs of elements at the same index in two `Iterable`s, collecting the results. If one
+ * Applies a function to pairs of elements at the same index in two `Iterable`s, collecting the results. If one
  * input `Iterable` is short, excess elements of the longer `Iterable` are discarded.
  *
  * **Example** (Zipping with a combining function)
@@ -2114,7 +2119,7 @@ export const zip: {
  */
 export const zipWith: {
   /**
-   * Apply a function to pairs of elements at the same index in two `Iterable`s, collecting the results. If one
+   * Applies a function to pairs of elements at the same index in two `Iterable`s, collecting the results. If one
    * input `Iterable` is short, excess elements of the longer `Iterable` are discarded.
    *
    * **Example** (Zipping with a combining function)
@@ -2162,7 +2167,7 @@ export const zipWith: {
    */
   <B, A, C>(that: Iterable<B>, f: (a: A, b: B) => C): (self: Iterable<A>) => Iterable<C>
   /**
-   * Apply a function to pairs of elements at the same index in two `Iterable`s, collecting the results. If one
+   * Applies a function to pairs of elements at the same index in two `Iterable`s, collecting the results. If one
    * input `Iterable` is short, excess elements of the longer `Iterable` are discarded.
    *
    * **Example** (Zipping with a combining function)
@@ -2227,7 +2232,14 @@ export const zipWith: {
 }))
 
 /**
- * Places an element in between members of an `Iterable`.
+ * Places a separator between members of an `Iterable`.
+ *
+ * **When to use**
+ *
+ * Use to lazily insert a separator between adjacent values.
+ *
+ * **Details**
+ *
  * If the input is a non-empty array, the result is also a non-empty array.
  *
  * **Example** (Interspersing separators)
@@ -2266,7 +2278,14 @@ export const zipWith: {
  */
 export const intersperse: {
   /**
-   * Places an element in between members of an `Iterable`.
+   * Places a separator between members of an `Iterable`.
+   *
+   * **When to use**
+   *
+   * Use to lazily insert a separator between adjacent values.
+   *
+   * **Details**
+   *
    * If the input is a non-empty array, the result is also a non-empty array.
    *
    * **Example** (Interspersing separators)
@@ -2305,7 +2324,14 @@ export const intersperse: {
    */
   <B>(middle: B): <A>(self: Iterable<A>) => Iterable<A | B>
   /**
-   * Places an element in between members of an `Iterable`.
+   * Places a separator between members of an `Iterable`.
+   *
+   * **When to use**
+   *
+   * Use to lazily insert a separator between adjacent values.
+   *
+   * **Details**
+   *
    * If the input is a non-empty array, the result is also a non-empty array.
    *
    * **Example** (Interspersing separators)
@@ -2677,7 +2703,7 @@ export const chunksOf: {
 })
 
 /**
- * Group equal, consecutive elements of an `Iterable` into `NonEmptyArray`s using the provided `isEquivalent` function.
+ * Groups equal, consecutive elements of an `Iterable` into `NonEmptyArray`s using the provided `isEquivalent` function.
  *
  * **Example** (Grouping consecutive elements with custom equivalence)
  *
@@ -2717,7 +2743,7 @@ export const chunksOf: {
  */
 export const groupWith: {
   /**
-   * Group equal, consecutive elements of an `Iterable` into `NonEmptyArray`s using the provided `isEquivalent` function.
+   * Groups equal, consecutive elements of an `Iterable` into `NonEmptyArray`s using the provided `isEquivalent` function.
    *
    * **Example** (Grouping consecutive elements with custom equivalence)
    *
@@ -2757,7 +2783,7 @@ export const groupWith: {
    */
   <A>(isEquivalent: (self: A, that: A) => boolean): (self: Iterable<A>) => Iterable<NonEmptyArray<A>>
   /**
-   * Group equal, consecutive elements of an `Iterable` into `NonEmptyArray`s using the provided `isEquivalent` function.
+   * Groups equal, consecutive elements of an `Iterable` into `NonEmptyArray`s using the provided `isEquivalent` function.
    *
    * **Example** (Grouping consecutive elements with custom equivalence)
    *
@@ -2834,7 +2860,7 @@ export const groupWith: {
 )
 
 /**
- * Group equal, consecutive elements of an `Iterable` into `NonEmptyArray`s.
+ * Groups equal, consecutive elements of an `Iterable` into `NonEmptyArray`s.
  *
  * **Example** (Grouping consecutive elements)
  *
@@ -4236,7 +4262,7 @@ export const flatMapNullishOr: {
 )
 
 /**
- * Check if a predicate holds true for some `Iterable` element.
+ * Checks whether a predicate holds true for some `Iterable` element.
  *
  * **Example** (Checking whether some element matches)
  *
@@ -4278,7 +4304,7 @@ export const flatMapNullishOr: {
  */
 export const some: {
   /**
-   * Check if a predicate holds true for some `Iterable` element.
+   * Checks whether a predicate holds true for some `Iterable` element.
    *
    * **Example** (Checking whether some element matches)
    *
@@ -4320,7 +4346,7 @@ export const some: {
    */
   <A>(predicate: (a: A, i: number) => boolean): (self: Iterable<A>) => boolean
   /**
-   * Check if a predicate holds true for some `Iterable` element.
+   * Checks whether a predicate holds true for some `Iterable` element.
    *
    * **Example** (Checking whether some element matches)
    *
@@ -4432,7 +4458,7 @@ export const unfold = <B, A>(b: B, f: (b: B) => Option<readonly [A, B]>): Iterab
 })
 
 /**
- * Iterate over the `Iterable` applying `f`.
+ * Iterates over the `Iterable`, applying `f` to each element.
  *
  * **Example** (Iterating with side effects)
  *
@@ -4471,7 +4497,7 @@ export const unfold = <B, A>(b: B, f: (b: B) => Option<readonly [A, B]>): Iterab
  */
 export const forEach: {
   /**
-   * Iterate over the `Iterable` applying `f`.
+   * Iterates over the `Iterable`, applying `f` to each element.
    *
    * **Example** (Iterating with side effects)
    *
@@ -4510,7 +4536,7 @@ export const forEach: {
    */
   <A>(f: (a: A, i: number) => void): (self: Iterable<A>) => void
   /**
-   * Iterate over the `Iterable` applying `f`.
+   * Iterates over the `Iterable`, applying `f` to each element.
    *
    * **Example** (Iterating with side effects)
    *
@@ -4556,7 +4582,7 @@ export const forEach: {
 })
 
 /**
- * Reduce an iterable to a single value by applying a function to each element and accumulating the result.
+ * Reduces an iterable to a single value by applying a function to each element and accumulating the result.
  *
  * **Details**
  *
@@ -4608,7 +4634,7 @@ export const forEach: {
  */
 export const reduce: {
   /**
-   * Reduce an iterable to a single value by applying a function to each element and accumulating the result.
+   * Reduces an iterable to a single value by applying a function to each element and accumulating the result.
    *
    * **Details**
    *
@@ -4660,7 +4686,7 @@ export const reduce: {
    */
   <B, A>(b: B, f: (b: B, a: A, i: number) => B): (self: Iterable<A>) => B
   /**
-   * Reduce an iterable to a single value by applying a function to each element and accumulating the result.
+   * Reduces an iterable to a single value by applying a function to each element and accumulating the result.
    *
    * **Details**
    *
@@ -5209,7 +5235,7 @@ export const cartesian: {
 )
 
 /**
- * Counts all the element of the given iterable that pass the given predicate
+ * Computes how many elements of the iterable pass the given predicate.
  *
  * **Example** (Counting matching elements)
  *
@@ -5225,7 +5251,7 @@ export const cartesian: {
  */
 export const countBy: {
   /**
-   * Counts all the element of the given iterable that pass the given predicate
+   * Computes how many elements of the iterable pass the given predicate.
    *
    * **Example** (Counting matching elements)
    *
@@ -5241,7 +5267,7 @@ export const countBy: {
    */
   <A>(predicate: (a: NoInfer<A>, i: number) => boolean): (self: Iterable<A>) => number
   /**
-   * Counts all the element of the given iterable that pass the given predicate
+   * Computes how many elements of the iterable pass the given predicate.
    *
    * **Example** (Counting matching elements)
    *

package/src/JsonPatch.ts

@@ -204,7 +204,7 @@ export type JsonPatch = ReadonlyArray<JsonPatchOperation>
  * yields `newValue` when applied to `oldValue`. It returns an empty array when
  * values are identical, recursively diffs nested structures, emits root
  * `replace` operations for primitive changes, and processes object keys in
- * sorted order for stable output. Inputs are not mutated.
+ * sorted order for stable output.
  *
  * **Gotchas**
  *

package/src/JsonPointer.ts

@@ -63,7 +63,7 @@
  *
  * **Details**
  *
- * - Does not mutate the input string; returns a new escaped string
+ * - Returns a new escaped string
  * - Replaces `~` (tilde) with `~0` and `/` (forward slash) with `~1`
  * - Returns the input unchanged if it contains no special characters
  * - Empty strings are valid and returned unchanged
@@ -91,7 +91,7 @@ export function escapeToken(token: string): string {
 }
 
 /**
- * Unescapes a JSON Pointer reference token according to RFC 6901 by decoding escaped characters to recover the original token value.
+ * Decodes a JSON Pointer reference token according to RFC 6901 escaping rules.
  *
  * **When to use**
  *
@@ -101,7 +101,7 @@ export function escapeToken(token: string): string {
  *
  * **Details**
  *
- * - Does not mutate the input string; returns a new unescaped string
+ * - Returns a new unescaped string
  * - Replaces `~1` with `/` (forward slash) and `~0` with `~` (tilde)
  * - Returns the input unchanged if it contains no escaped sequences
  * - Empty strings are valid and returned unchanged

package/src/JsonSchema.ts

@@ -235,7 +235,7 @@ export interface MultiDocument<D extends Dialect> {
 }
 
 /**
- * The `$schema` meta-schema URI for JSON Schema Draft-07.
+ * Represents the `$schema` meta-schema URI for JSON Schema Draft-07.
  *
  * **When to use**
  *
@@ -255,7 +255,7 @@ export interface MultiDocument<D extends Dialect> {
 export const META_SCHEMA_URI_DRAFT_07 = "http://json-schema.org/draft-07/schema"
 
 /**
- * The `$schema` meta-schema URI for JSON Schema Draft 2020-12.
+ * Represents the `$schema` meta-schema URI for JSON Schema Draft 2020-12.
  *
  * **When to use**
  *
@@ -291,8 +291,7 @@ const RE_COMPONENTS_SCHEMAS = /^#\/components\/schemas(?=\/|$)/
  * This converts Draft-07 tuple syntax (`items` as array plus
  * `additionalItems`) to Draft-2020-12 form (`prefixItems` plus `items`),
  * rewrites `#/definitions/...` refs to `#/$defs/...`, and extracts root-level
- * `definitions` into the `definitions` field. It does not mutate the input and
- * allocates a new `Document`.
+ * `definitions` into the `definitions` field.
  *
  * **Gotchas**
  *
@@ -441,9 +440,8 @@ export function fromSchemaDraft07(js: JsonSchema): Document<"draft-2020-12"> {
  *
  * **Details**
  *
- * This separates `$defs` from the root schema into the `definitions` field. It
- * does not mutate the input and allocates a new `Document`. Unlike
- * {@link fromSchemaDraft07}, this performs no keyword rewriting.
+ * This separates `$defs` from the root schema into the `definitions` field.
+ * Unlike {@link fromSchemaDraft07}, this performs no keyword rewriting.
  *
  * **Example** (Parsing a Draft-2020-12 schema)
  *
@@ -485,8 +483,7 @@ export function fromSchemaDraft2020_12(js: JsonSchema): Document<"draft-2020-12"
  * **Details**
  *
  * This rewrites `#/components/schemas/...` refs to `#/$defs/...`, then delegates
- * to {@link fromSchemaDraft2020_12}. It does not mutate the input and allocates
- * a new `Document`.
+ * to {@link fromSchemaDraft2020_12}.
  *
  * **Example** (Parsing an OpenAPI 3.1 schema)
  *
@@ -527,8 +524,7 @@ export function fromSchemaOpenApi3_1(js: JsonSchema): Document<"draft-2020-12">
  * This handles OpenAPI 3.0 extensions, including `nullable`, singular
  * `example`, and boolean `exclusiveMinimum` or `exclusiveMaximum`. It
  * normalizes the schema to Draft-07 first, then converts to Draft-2020-12 via
- * {@link fromSchemaDraft07}. It does not mutate the input and allocates a new
- * `Document`.
+ * {@link fromSchemaDraft07}.
  *
  * **Example** (Parsing an OpenAPI 3.0 nullable schema)
  *
@@ -567,8 +563,7 @@ export function fromSchemaOpenApi3_0(schema: JsonSchema): Document<"draft-2020-1
  * This rewrites `#/$defs/...` refs to `#/definitions/...`, converts
  * Draft-2020-12 tuple syntax (`prefixItems` plus `items`) to Draft-07 form
  * (`items` as array plus `additionalItems`), and converts both the root schema
- * and all definitions. It does not mutate the input and allocates a new
- * `Document`.
+ * and all definitions.
  *
  * **Gotchas**
  *
@@ -719,8 +714,7 @@ function toSchemaDraft07(schema: JsonSchema): JsonSchema {
  * definition keys to match the OpenAPI component key pattern
  * (`^[a-zA-Z0-9.\-_]+$`) by replacing invalid characters with `_`, updates all
  * `$ref` pointers to use the sanitized keys, and converts all schemas and
- * definitions in the multi-document. It does not mutate the input and allocates
- * a new `MultiDocument`.
+ * definitions in the multi-document.
  *
  * **Example** (Converting to OpenAPI 3.1)
  *
@@ -942,8 +936,7 @@ function widen_type(node: Record<string, unknown>): Record<string, unknown> {
  * **Details**
  *
  * This only resolves the final segment of the ref path, such as `"User"` from
- * `"#/$defs/User"`. It returns `undefined` if the definition is not found and
- * does not mutate anything.
+ * `"#/$defs/User"`. It returns `undefined` if the definition is not found.
  *
  * **Gotchas**
  *
@@ -982,10 +975,7 @@ export function resolve$ref($ref: string, definitions: Definitions): JsonSchema
 }
 
 /**
- * If the root schema of a document is a `$ref`, resolves it against the
- * document's definitions and returns a new document with the inlined
- * schema. Returns the original document unchanged if the root schema is
- * not a `$ref` or if the referenced definition is not found.
+ * Resolves a document whose root schema is a top-level `$ref`.
  *
  * **When to use**
  *
@@ -994,8 +984,8 @@ export function resolve$ref($ref: string, definitions: Definitions): JsonSchema
  *
  * **Details**
  *
- * This does not mutate the input. It returns the same object if no change is
- * needed, or a shallow copy with the resolved schema.
+ * This returns the same object if no change is needed, or a shallow copy with
+ * the resolved schema.
  *
  * **Example** (Resolving a top-level $ref)
  *

package/src/Latch.ts

@@ -244,7 +244,7 @@ export const make: (open?: boolean | undefined) => Effect.Effect<Latch> = intern
 export const open = (self: Latch): Effect.Effect<boolean> => self.open
 
 /**
- * Synchronously opens the latch and releases fibers waiting on it.
+ * Opens the latch synchronously and releases fibers waiting on it.
  *
  * **When to use**
  *
@@ -340,7 +340,7 @@ export {
 export const close = (self: Latch): Effect.Effect<boolean> => self.close
 
 /**
- * Synchronously closes the latch so future `await` and `whenOpen` calls
+ * Closes the latch synchronously so future `await` and `whenOpen` calls
  * suspend.
  *
  * **When to use**