effect 4.0.0-beta.73 → 4.0.0-beta.75

package/src/Iterable.ts

@@ -332,7 +332,7 @@ export const fromRecord = <K extends string, A>(self: Readonly<Record<K, A>>): I
  * console.log(Array.from(withZ)) // ["z", "a", "b", "c"]
  * ```
  *
- * @category concatenating
+ * @category combining
  * @since 2.0.0
  */
 export const prepend: {
@@ -354,7 +354,7 @@ export const prepend: {
    * console.log(Array.from(withZ)) // ["z", "a", "b", "c"]
    * ```
    *
-   * @category concatenating
+   * @category combining
    * @since 2.0.0
    */
   <B>(head: B): <A>(self: Iterable<A>) => Iterable<A | B>
@@ -376,7 +376,7 @@ export const prepend: {
    * console.log(Array.from(withZ)) // ["z", "a", "b", "c"]
    * ```
    *
-   * @category concatenating
+   * @category combining
    * @since 2.0.0
    */
   <A, B>(self: Iterable<A>, head: B): Iterable<A | B>
@@ -397,7 +397,7 @@ export const prepend: {
  * )
  * ```
  *
- * @category concatenating
+ * @category combining
  * @since 2.0.0
  */
 export const prependAll: {
@@ -416,7 +416,7 @@ export const prependAll: {
    * )
    * ```
    *
-   * @category concatenating
+   * @category combining
    * @since 2.0.0
    */
   <B>(that: Iterable<B>): <A>(self: Iterable<A>) => Iterable<A | B>
@@ -435,7 +435,7 @@ export const prependAll: {
    * )
    * ```
    *
-   * @category concatenating
+   * @category combining
    * @since 2.0.0
    */
   <A, B>(self: Iterable<A>, that: Iterable<B>): Iterable<A | B>
@@ -482,7 +482,7 @@ export const prependAll: {
  * @see {@link prepend} for adding one element before the existing elements
  * @see {@link appendAll} for appending all elements from another iterable
  *
- * @category concatenating
+ * @category combining
  * @since 2.0.0
  */
 export const append: {
@@ -524,7 +524,7 @@ export const append: {
    * @see {@link prepend} for adding one element before the existing elements
    * @see {@link appendAll} for appending all elements from another iterable
    *
-   * @category concatenating
+   * @category combining
    * @since 2.0.0
    */
   <B>(last: B): <A>(self: Iterable<A>) => Iterable<A | B>
@@ -566,7 +566,7 @@ export const append: {
    * @see {@link prepend} for adding one element before the existing elements
    * @see {@link appendAll} for appending all elements from another iterable
    *
-   * @category concatenating
+   * @category combining
    * @since 2.0.0
    */
   <A, B>(self: Iterable<A>, last: B): Iterable<A | B>
@@ -615,7 +615,7 @@ export const append: {
  * @see {@link append} for appending one value instead of another iterable
  * @see {@link prependAll} for yielding another iterable before `self`
  *
- * @category concatenating
+ * @category combining
  * @since 2.0.0
  */
 export const appendAll: {
@@ -662,7 +662,7 @@ export const appendAll: {
    * @see {@link append} for appending one value instead of another iterable
    * @see {@link prependAll} for yielding another iterable before `self`
    *
-   * @category concatenating
+   * @category combining
    * @since 2.0.0
    */
   <B>(that: Iterable<B>): <A>(self: Iterable<A>) => Iterable<A | B>
@@ -709,7 +709,7 @@ export const appendAll: {
    * @see {@link append} for appending one value instead of another iterable
    * @see {@link prependAll} for yielding another iterable before `self`
    *
-   * @category concatenating
+   * @category combining
    * @since 2.0.0
    */
   <A, B>(self: Iterable<A>, that: Iterable<B>): Iterable<A | B>
@@ -933,7 +933,16 @@ export const head = <A>(self: Iterable<A>): Option<A> => {
 }
 
 /**
- * Gets the first element of a `Iterable`, or throw an error if the `Iterable` is empty.
+ * Gets the first element of an `Iterable` without returning an `Option`.
+ *
+ * **When to use**
+ *
+ * Use when the `Iterable` is known to be non-empty and direct access to the
+ * first element is preferred over handling `Option.none`.
+ *
+ * **Gotchas**
+ *
+ * Throws if the `Iterable` is empty.
  *
  * **Example** (Getting the first element unsafely)
  *
@@ -2273,7 +2282,7 @@ export const zipWith: {
  * console.log(Array.from(css).join("")) // "color: red; font-size: 14px; margin: 10px"
  * ```
  *
- * @category concatenating
+ * @category combining
  * @since 2.0.0
  */
 export const intersperse: {
@@ -2319,7 +2328,7 @@ export const intersperse: {
    * console.log(Array.from(css).join("")) // "color: red; font-size: 14px; margin: 10px"
    * ```
    *
-   * @category concatenating
+   * @category combining
    * @since 2.0.0
    */
   <B>(middle: B): <A>(self: Iterable<A>) => Iterable<A | B>
@@ -2365,7 +2374,7 @@ export const intersperse: {
    * console.log(Array.from(css).join("")) // "color: red; font-size: 14px; margin: 10px"
    * ```
    *
-   * @category concatenating
+   * @category combining
    * @since 2.0.0
    */
   <A, B>(self: Iterable<A>, middle: B): Iterable<A | B>
@@ -3081,8 +3090,8 @@ const constEmptyIterator: Iterator<never> = {
  *
  * **When to use**
  *
- * Use as a base case for operations or when you
- * need to represent "no data" in a type-safe way.
+ * Use when you need an empty iterable as a typed "no data" value or a base
+ * case for iterable operations.
  *
  * **Example** (Creating an empty iterable)
  *
@@ -3149,7 +3158,7 @@ export const of = <A>(a: A): Iterable<A> => [a]
  *
  * This is one of the most fundamental operations for working with iterables.
  * It applies a transformation function to each element, creating a new iterable
- * with the transformed values. The operation is lazy - elements are only
+ * with the transformed values. The operation is lazy, so elements are only
  * transformed when the iterable is consumed.
  *
  * **Example** (Mapping elements)
@@ -3185,7 +3194,7 @@ export const map: {
    *
    * This is one of the most fundamental operations for working with iterables.
    * It applies a transformation function to each element, creating a new iterable
-   * with the transformed values. The operation is lazy - elements are only
+   * with the transformed values. The operation is lazy, so elements are only
    * transformed when the iterable is consumed.
    *
    * **Example** (Mapping elements)
@@ -3221,7 +3230,7 @@ export const map: {
    *
    * This is one of the most fundamental operations for working with iterables.
    * It applies a transformation function to each element, creating a new iterable
-   * with the transformed values. The operation is lazy - elements are only
+   * with the transformed values. The operation is lazy, so elements are only
    * transformed when the iterable is consumed.
    *
    * **Example** (Mapping elements)
@@ -3449,8 +3458,9 @@ export const flatten = <A>(self: Iterable<Iterable<A>>): Iterable<A> => ({
  *
  * **Details**
  *
- * This combines mapping and filtering in a single operation - the function is applied to each element,
- * and only elements that result in `Result.succeed` are included in the result.
+ * This combines mapping and filtering in a single operation. The function is
+ * applied to each element, and only elements that result in `Result.succeed`
+ * are included in the result.
  *
  * **Example** (Filtering and transforming Result values)
  *
@@ -3497,8 +3507,9 @@ export const filterMap: {
    *
    * **Details**
    *
-   * This combines mapping and filtering in a single operation - the function is applied to each element,
-   * and only elements that result in `Result.succeed` are included in the result.
+   * This combines mapping and filtering in a single operation. The function is
+   * applied to each element, and only elements that result in `Result.succeed`
+   * are included in the result.
    *
    * **Example** (Filtering and transforming Result values)
    *
@@ -3545,8 +3556,9 @@ export const filterMap: {
    *
    * **Details**
    *
-   * This combines mapping and filtering in a single operation - the function is applied to each element,
-   * and only elements that result in `Result.succeed` are included in the result.
+   * This combines mapping and filtering in a single operation. The function is
+   * applied to each element, and only elements that result in `Result.succeed`
+   * are included in the result.
    *
    * **Example** (Filtering and transforming Result values)
    *

package/src/JsonPatch.ts

@@ -194,9 +194,8 @@ export type JsonPatch = ReadonlyArray<JsonPatchOperation>
  *
  * **When to use**
  *
- * Use to compute differences between JSON documents, detect structural
- * changes, or create deterministic update operations from before and after
- * states.
+ * Use to compute a JSON Patch from before and after JSON documents, detect
+ * structural changes, or create deterministic update operations.
  *
  * **Details**
  *

package/src/JsonPointer.ts

@@ -57,9 +57,7 @@
  *
  * **When to use**
  *
- * Use to build JSON Pointers from object keys or path segments that may contain special characters
- * - Escaping tokens before joining them with `/` to form a complete JSON Pointer
- * - Preparing reference tokens for use in JSON Patch operations or schema references
+ * Use when you need to escape a single JSON Pointer path segment.
  *
  * **Details**
  *
@@ -95,9 +93,7 @@ export function escapeToken(token: string): string {
  *
  * **When to use**
  *
- * Use to parse JSON Pointers to extract the original token values from escaped segments
- * - Converting escaped tokens back to their original form for use as object keys or identifiers
- * - Resolving schema references or JSON Patch paths that use escaped tokens
+ * Use when you need to decode a single escaped JSON Pointer path segment.
  *
  * **Details**
  *

package/src/JsonSchema.ts

@@ -259,8 +259,8 @@ export const META_SCHEMA_URI_DRAFT_07 = "http://json-schema.org/draft-07/schema"
  *
  * **When to use**
  *
- * Use to populate the `$schema` field when emitting a JSON Schema document that
- * should declare JSON Schema Draft 2020-12.
+ * Use when you need to populate the `$schema` field while emitting a JSON
+ * Schema document that should declare JSON Schema Draft 2020-12.
  *
  * **Details**
  *
@@ -283,8 +283,8 @@ const RE_COMPONENTS_SCHEMAS = /^#\/components\/schemas(?=\/|$)/
  *
  * **When to use**
  *
- * Use when you have a JSON Schema that follows Draft-07 conventions and
- * need the canonical Draft-2020-12 document representation.
+ * Use when you have a raw JSON Schema object that follows Draft-07 conventions
+ * and need the canonical Draft-2020-12 document representation.
  *
  * **Details**
  *
@@ -436,7 +436,7 @@ export function fromSchemaDraft07(js: JsonSchema): Document<"draft-2020-12"> {
  *
  * **When to use**
  *
- * Use when you already have a schema in Draft-2020-12 format.
+ * Use when you already have a raw JSON Schema object in Draft-2020-12 format.
  *
  * **Details**
  *
@@ -478,7 +478,8 @@ export function fromSchemaDraft2020_12(js: JsonSchema): Document<"draft-2020-12"
  *
  * **When to use**
  *
- * Use when consuming schemas from an OpenAPI 3.1 specification.
+ * Use when you need to consume raw JSON Schema objects from an OpenAPI 3.1
+ * specification.
  *
  * **Details**
  *
@@ -517,7 +518,8 @@ export function fromSchemaOpenApi3_1(js: JsonSchema): Document<"draft-2020-12">
  *
  * **When to use**
  *
- * Use when consuming schemas from an OpenAPI 3.0 specification.
+ * Use when you need to consume raw JSON Schema objects from an OpenAPI 3.0
+ * specification.
  *
  * **Details**
  *
@@ -556,7 +558,8 @@ export function fromSchemaOpenApi3_0(schema: JsonSchema): Document<"draft-2020-1
  *
  * **When to use**
  *
- * Use when you need to output a schema in Draft-07 format.
+ * Use when you need to output a canonical JSON Schema document in Draft-07
+ * format.
  *
  * **Details**
  *
@@ -706,7 +709,8 @@ function toSchemaDraft07(schema: JsonSchema): JsonSchema {
  *
  * **When to use**
  *
- * Use when generating an OpenAPI 3.1 specification from internal schemas.
+ * Use when you need to emit an OpenAPI 3.1 multi-document from canonical JSON
+ * Schema documents.
  *
  * **Details**
  *
@@ -930,8 +934,8 @@ function widen_type(node: Record<string, unknown>): Record<string, unknown> {
  *
  * **When to use**
  *
- * Use when you need to dereference a `$ref` pointer to get the actual
- * schema it points to.
+ * Use when you need to dereference a `$ref` pointer to get the JSON Schema
+ * object it points to.
  *
  * **Details**
  *
@@ -979,8 +983,8 @@ export function resolve$ref($ref: string, definitions: Definitions): JsonSchema
  *
  * **When to use**
  *
- * Use to dereference a top-level `$ref` before inspecting the root
- * schema's properties directly.
+ * Use when you need to dereference a top-level `$ref` before inspecting the
+ * root JSON Schema object's properties directly.
  *
  * **Details**
  *

package/src/Latch.ts

@@ -146,7 +146,8 @@ export interface Latch {
  *
  * **When to use**
  *
- * Use when synchronous allocation is required outside an Effect workflow.
+ * Use when you need to allocate a `Latch` synchronously outside an Effect
+ * workflow.
  *
  * **Details**
  *
@@ -248,8 +249,8 @@ export const open = (self: Latch): Effect.Effect<boolean> => self.open
  *
  * **When to use**
  *
- * Use when synchronous code needs to open a latch immediately and release the
- * fibers waiting on it.
+ * Use when you need synchronous code to open a latch immediately and release
+ * the fibers waiting on it.
  *
  * **Details**
  *