effect 4.0.0-beta.70 → 4.0.0-beta.71

package/src/String.ts

@@ -1,6 +1,68 @@
 /**
- * This module provides utility functions and type class instances for working with the `string` type in TypeScript.
- * It includes functions for basic string manipulation.
+ * Operations for working with TypeScript `string` values. Use this module to
+ * normalize text, inspect and extract characters, search with `Option` results,
+ * split or iterate lines, convert identifier casing, and pass string instances
+ * to generic APIs.
+ *
+ * **Mental model**
+ *
+ * Strings are plain JavaScript strings. Many operations mirror native string
+ * methods while giving them Effect-style names and data-last forms for `pipe`.
+ * Operations that may miss, such as {@link at}, {@link charCodeAt},
+ * {@link codePointAt}, {@link indexOf}, {@link lastIndexOf}, {@link match}, and
+ * {@link search}, return `Option` instead of sentinel values such as `-1`,
+ * `undefined`, or `null`.
+ *
+ * **Common tasks**
+ *
+ * - Coerce or narrow input: {@link String}, {@link isString}
+ * - Build and compare strings: {@link empty}, {@link concat}, {@link Order},
+ *   {@link Equivalence}, {@link ReducerConcat}
+ * - Change text shape: {@link trim}, {@link trimStart}, {@link trimEnd},
+ *   {@link toUpperCase}, {@link toLowerCase}, {@link capitalize},
+ *   {@link uncapitalize}
+ * - Slice, split, and inspect: {@link slice}, {@link substring},
+ *   {@link takeLeft}, {@link takeRight}, {@link split}, {@link length}
+ * - Search and match: {@link includes}, {@link startsWith}, {@link endsWith},
+ *   {@link indexOf}, {@link lastIndexOf}, {@link match}, {@link matchAll},
+ *   {@link search}
+ * - Normalize identifiers and text blocks: {@link camelCase},
+ *   {@link pascalCase}, {@link snakeCase}, {@link kebabCase},
+ *   {@link constantCase}, {@link linesIterator}, {@link linesWithSeparators},
+ *   {@link stripMargin}
+ *
+ * **Gotchas**
+ *
+ * - {@link length} reports JavaScript string length in UTF-16 code units, not
+ *   user-perceived characters.
+ * - {@link String} is the native JavaScript constructor. `String.String(value)`
+ *   returns native string coercion results.
+ * - {@link split} always returns a non-empty array; splitting `""` with `""`
+ *   returns `[""]`.
+ * - {@link replace} and {@link replaceAll} follow native JavaScript behavior.
+ *   In particular, `replace` only replaces all matches when given a global
+ *   regular expression.
+ * - Fixed converters such as {@link snakeToCamel} expect their named input
+ *   shape. For mixed free-form input, prefer {@link camelCase},
+ *   {@link pascalCase}, {@link snakeCase}, {@link kebabCase}, or
+ *   {@link noCase}.
+ *
+ * **Quickstart**
+ *
+ * **Example** (Normalizing and searching text)
+ *
+ * ```ts
+ * import { String } from "effect"
+ *
+ * const slug = String.kebabCase("User profile ID")
+ * console.log(slug) // "user-profile-id"
+ *
+ * const parts = String.split(slug, "-")
+ * console.log(parts) // ["user", "profile", "id"]
+ *
+ * const firstDash = String.indexOf("-")(slug)
+ * console.log(firstDash) // Option.some(4)
+ * ```
  *
  * @since 2.0.0
  */
@@ -20,6 +82,18 @@ import * as Reducer from "./Reducer.ts"
 /**
  * Reference to the global `String` constructor.
  *
+ * **When to use**
+ *
+ * Use when code in the Effect `String` namespace needs native JavaScript string
+ * coercion or constructor behavior.
+ *
+ * **Gotchas**
+ *
+ * Calling `String(value)` returns a primitive string. Calling
+ * `new String(value)` creates a boxed `String` object.
+ *
+ * @see {@link isString} for checking whether a value is a primitive string
+ *
  * @category constructors
  * @since 4.0.0
  */
@@ -1568,6 +1642,18 @@ const linesSeparated = (self: string, stripped: boolean): LinesIterator => new L
  * Normalizes a string by splitting it into word parts, transforming each part,
  * and joining the parts with a configurable delimiter.
  *
+ * **When to use**
+ *
+ * Use to normalize mixed-case, snake_case, kebab-case, or spaced input into
+ * custom word-case output when you need a delimiter or part transform that the
+ * fixed case helpers do not provide.
+ *
+ * @see {@link pascalCase} for fixed PascalCase output
+ * @see {@link camelCase} for fixed lower-initial camelCase output
+ * @see {@link constantCase} for fixed uppercase underscore-separated output
+ * @see {@link kebabCase} for fixed lowercase hyphen-separated output
+ * @see {@link snakeCase} for fixed lowercase underscore-separated output
+ *
  * @category transforming
  * @since 4.0.0
  */
@@ -1576,6 +1662,18 @@ export const noCase: {
    * Normalizes a string by splitting it into word parts, transforming each part,
    * and joining the parts with a configurable delimiter.
    *
+   * **When to use**
+   *
+   * Use to normalize mixed-case, snake_case, kebab-case, or spaced input into
+   * custom word-case output when you need a delimiter or part transform that the
+   * fixed case helpers do not provide.
+   *
+   * @see {@link pascalCase} for fixed PascalCase output
+   * @see {@link camelCase} for fixed lower-initial camelCase output
+   * @see {@link constantCase} for fixed uppercase underscore-separated output
+   * @see {@link kebabCase} for fixed lowercase hyphen-separated output
+   * @see {@link snakeCase} for fixed lowercase underscore-separated output
+   *
    * @category transforming
    * @since 4.0.0
    */
@@ -1591,6 +1689,18 @@ export const noCase: {
    * Normalizes a string by splitting it into word parts, transforming each part,
    * and joining the parts with a configurable delimiter.
    *
+   * **When to use**
+   *
+   * Use to normalize mixed-case, snake_case, kebab-case, or spaced input into
+   * custom word-case output when you need a delimiter or part transform that the
+   * fixed case helpers do not provide.
+   *
+   * @see {@link pascalCase} for fixed PascalCase output
+   * @see {@link camelCase} for fixed lower-initial camelCase output
+   * @see {@link constantCase} for fixed uppercase underscore-separated output
+   * @see {@link kebabCase} for fixed lowercase hyphen-separated output
+   * @see {@link snakeCase} for fixed lowercase underscore-separated output
+   *
    * @category transforming
    * @since 4.0.0
    */
@@ -1647,6 +1757,15 @@ const pascalCaseTransform = (input: string, index: number): string => {
 /**
  * Converts a string to PascalCase.
  *
+ * **When to use**
+ *
+ * Use to normalize strings from spaces, separators, or camel/Pascal word
+ * boundaries into PascalCase.
+ *
+ * @see {@link camelCase} for lower-initial camelCase output
+ * @see {@link noCase} for configurable delimiters and part transforms
+ * @see {@link snakeToPascal} for converting known snake_case input only
+ *
  * @category transforming
  * @since 4.0.0
  */
@@ -1663,6 +1782,17 @@ const camelCaseTransform = (input: string, index: number): string =>
 /**
  * Converts a string to camelCase.
  *
+ * **When to use**
+ *
+ * Use to normalize mixed word separators or existing PascalCase/camelCase text
+ * into lower-initial camelCase identifiers.
+ *
+ * @see {@link noCase} for configurable delimiters and part transforms
+ * @see {@link pascalCase} for upper-initial PascalCase output
+ * @see {@link snakeCase} for lowercase underscore-separated output
+ * @see {@link kebabCase} for lowercase hyphen-separated output
+ * @see {@link constantCase} for uppercase underscore-separated output
+ *
  * @category transforming
  * @since 4.0.0
  */
@@ -1674,6 +1804,17 @@ export const camelCase: (self: string) => string = noCase({
 /**
  * Converts a string to CONSTANT_CASE (uppercase with underscores).
  *
+ * **When to use**
+ *
+ * Use to normalize words from mixed input formats into uppercase,
+ * underscore-separated identifiers.
+ *
+ * @see {@link snakeCase} for lowercase underscore-separated output
+ * @see {@link kebabCase} for lowercase hyphen-separated output
+ * @see {@link camelCase} for lower-initial camelCase output
+ * @see {@link pascalCase} for upper-initial PascalCase output
+ * @see {@link noCase} for configurable delimiters and part transforms
+ *
  * @category transforming
  * @since 4.0.0
  */
@@ -1685,6 +1826,17 @@ export const constantCase: (self: string) => string = noCase({
 /**
  * Converts a string to kebab-case (lowercase with hyphens).
  *
+ * **When to use**
+ *
+ * Use to normalize free-form labels, identifiers, or keys into lowercase
+ * hyphen-separated text.
+ *
+ * @see {@link noCase} for configurable delimiters and part transforms
+ * @see {@link snakeCase} for lowercase underscore-separated output
+ * @see {@link constantCase} for uppercase underscore-separated output
+ * @see {@link camelCase} for lower-initial camelCase output
+ * @see {@link pascalCase} for upper-initial PascalCase output
+ *
  * @category transforming
  * @since 4.0.0
  */
@@ -1695,6 +1847,15 @@ export const kebabCase: (self: string) => string = noCase({
 /**
  * Converts a string to snake_case (lowercase with underscores).
  *
+ * **When to use**
+ *
+ * Use to normalize mixed-case or separator-delimited text into lowercase words
+ * joined with underscores.
+ *
+ * @see {@link noCase} for configurable lower-level normalization
+ * @see {@link kebabCase} for lowercase hyphen-separated output
+ * @see {@link constantCase} for uppercase underscore-separated output
+ *
  * @category transforming
  * @since 4.0.0
  */
@@ -1705,6 +1866,16 @@ export const snakeCase: (self: string) => string = noCase({
 /**
  * A `Reducer` for concatenating `string`s.
  *
+ * **When to use**
+ *
+ * Use to concatenate many strings through APIs that consume a `Reducer`.
+ *
+ * **Details**
+ *
+ * The reducer starts from `""`, so combining an empty collection returns `""`.
+ *
+ * @see {@link concat} for concatenating two strings directly
+ *
  * @category concatenating
  * @since 4.0.0
  */

package/src/Struct.ts

@@ -67,7 +67,7 @@
  * ## See also
  *
  * - {@link Equivalence} – building equivalence relations for structs
- * - {@link Order} – ordering structs by their fields
+ * - `Order` – ordering structs by their fields
  * - {@link Combiner} – combining two values of the same type
  * - {@link Reducer} – combining with an initial value
  *
@@ -175,7 +175,7 @@ export type Assign<T, U> = Simplify<keyof T & keyof U extends never ? T & U : Om
  *
  * **When to use**
  *
- * Use in a pipeline when you need to extract a single property.
+ * Use to extract a single property in a pipeline.
  *
  * **Details**
  *
@@ -201,7 +201,7 @@ export const get: {
    *
    * **When to use**
    *
-   * Use in a pipeline when you need to extract a single property.
+   * Use to extract a single property in a pipeline.
    *
    * **Details**
    *
@@ -227,7 +227,7 @@ export const get: {
    *
    * **When to use**
    *
-   * Use in a pipeline when you need to extract a single property.
+   * Use to extract a single property in a pipeline.
    *
    * **Details**
    *
@@ -255,7 +255,7 @@ export const get: {
  *
  * **When to use**
  *
- * Use instead of `Object.keys` when you want the return type narrowed to the
+ * Use when you use instead of `Object.keys` when you want the return type narrowed to the
  * known keys of the struct.
  *
  * **Details**
@@ -945,7 +945,7 @@ export const evolveEntries: {
  *
  * **When to use**
  *
- * Use for simple, declarative key renaming without custom logic.
+ * Use when you need simple, declarative key renaming without custom logic.
  *
  * **Details**
  *
@@ -976,7 +976,7 @@ export const renameKeys: {
    *
    * **When to use**
    *
-   * Use for simple, declarative key renaming without custom logic.
+   * Use when you need simple, declarative key renaming without custom logic.
    *
    * **Details**
    *
@@ -1007,7 +1007,7 @@ export const renameKeys: {
    *
    * **When to use**
    *
-   * Use for simple, declarative key renaming without custom logic.
+   * Use when you need simple, declarative key renaming without custom logic.
    *
    * **Details**
    *
@@ -1114,7 +1114,7 @@ export const makeOrder = order.Struct
  *
  * **When to use**
  *
- * Use this interface when defining a typed function for {@link map},
+ * Use when you use this interface when defining a typed function for {@link map},
  * {@link mapPick}, or {@link mapOmit}.
  *
  * **Details**
@@ -1150,7 +1150,7 @@ export interface Lambda {
  *
  * **When to use**
  *
- * Use this when you need to compute what type a Lambda would produce for a
+ * Use when you need to compute what type a Lambda would produce for a
  * given input.
  *
  * **Details**
@@ -1181,6 +1181,11 @@ export type Apply<L extends Lambda, V> = (L & { readonly "~lambda.in": V })["~la
  * Wraps a plain function as a {@link Lambda} value so it can be used with
  * {@link map}, {@link mapPick}, and {@link mapOmit}.
  *
+ * **When to use**
+ *
+ * Use to create a typed lambda for struct mapping APIs that need type-level
+ * input and output tracking.
+ *
  * **Details**
  *
  * The type parameter `L` encodes both the input and output types at the type
@@ -1699,6 +1704,10 @@ export function makeReducer<A>(
 /**
  * Creates a record with the given keys and value.
  *
+ * **When to use**
+ *
+ * Use to build an object where each provided key receives the same value.
+ *
  * **Example** (Creating a record)
  *
  * ```ts

package/src/SubscriptionRef.ts

@@ -1,17 +1,58 @@
 /**
- * The `SubscriptionRef` module provides a mutable reference that can be read
- * and updated like a `Ref`, while also exposing a stream of its current value
- * and every subsequent change. It is useful when one part of an application
- * owns evolving state and many fibers need to subscribe to consistent updates,
- * such as configuration, coordination state, cached snapshots, or UI models.
- *
- * Updates are serialized with an internal semaphore and each update is
- * published to subscribers. The {@link changes} stream replays the latest value
- * first, then emits future updates, so new subscribers can start from the
- * current state without performing a separate read. Prefer the effectful
- * getters and update operations for concurrent code; the unsafe helpers bypass
- * synchronization and should only be used when the caller already controls
- * access.
+ * The `SubscriptionRef` module combines a fiber-safe mutable reference with a
+ * replaying stream of state changes. A `SubscriptionRef<A>` stores the latest
+ * value, serializes updates, and publishes each committed value so subscribers
+ * can observe state as it evolves.
+ *
+ * **Mental model**
+ *
+ * - {@link make} creates the reference and immediately publishes the initial
+ *   value.
+ * - {@link get} reads the latest value without subscribing.
+ * - {@link set}, {@link update}, and {@link modify} change the value under the
+ *   reference semaphore and publish the new value.
+ * - {@link changes} returns a stream that first emits the current value and
+ *   then emits future published values.
+ * - The `Some` variants leave the value unchanged and publish nothing when
+ *   their `Option` result is empty.
+ *
+ * **Common tasks**
+ *
+ * - Create shared state with {@link make}.
+ * - Read once with {@link get} or observe over time with {@link changes}.
+ * - Replace state with {@link set}, {@link setAndGet}, or {@link getAndSet}.
+ * - Transform state with {@link update}, {@link updateAndGet},
+ *   {@link getAndUpdate}, or their effectful variants.
+ * - Compute a separate result while updating with {@link modify} or
+ *   {@link modifyEffect}.
+ *
+ * **Example** (Reading the current value through changes)
+ *
+ * ```ts
+ * import { Effect, Stream, SubscriptionRef } from "effect"
+ *
+ * const program = Effect.gen(function*() {
+ *   const ref = yield* SubscriptionRef.make(0)
+ *
+ *   yield* SubscriptionRef.update(ref, (n) => n + 1)
+ *
+ *   const latest = yield* SubscriptionRef.changes(ref).pipe(
+ *     Stream.take(1),
+ *     Stream.runCollect
+ *   )
+ *
+ *   return latest
+ * })
+ * ```
+ *
+ * **Gotchas**
+ *
+ * - Every successful set or non-empty update is published, even when the new
+ *   value is equal to the old one.
+ * - New subscribers receive the current value from the replay buffer before
+ *   future updates.
+ * - Unsafe helpers bypass the semaphore and should only be used when the caller
+ *   already controls access.
  *
  * @since 2.0.0
  */
@@ -34,7 +75,7 @@ const TypeId = "~effect/SubscriptionRef"
  *
  * **When to use**
  *
- * Use `changes` to observe the current value and subsequent updates as a
+ * Use to observe the current value and subsequent updates as a
  * stream.
  *
  * @category models
@@ -49,6 +90,11 @@ export interface SubscriptionRef<in out A> extends SubscriptionRef.Variance<A>,
 /**
  * Returns `true` if the provided value is a `SubscriptionRef`.
  *
+ * **When to use**
+ *
+ * Use to narrow an unknown value before calling `SubscriptionRef` operations
+ * that require a subscription reference.
+ *
  * @category guards
  * @since 4.0.0
  */
@@ -93,6 +139,19 @@ const Proto = {
 /**
  * Constructs a new `SubscriptionRef` from an initial value.
  *
+ * **When to use**
+ *
+ * Use to create shared mutable state when consumers need to read the latest
+ * value and subscribe to every update.
+ *
+ * **Details**
+ *
+ * The initial value is published during construction, so `changes` starts new
+ * subscribers with that value before future updates.
+ *
+ * @see {@link changes} for streaming the current value and subsequent updates
+ * @see {@link set} for replacing the value and notifying subscribers
+ *
  * @category constructors
  * @since 2.0.0
  */

package/src/Symbol.ts

@@ -1,11 +1,25 @@
 /**
- * The `Symbol` module provides a small runtime guard for working with
- * JavaScript `symbol` values. Use {@link isSymbol} when validating unknown
- * input, narrowing union types, or building predicates that need to recognize
- * primitive symbols such as those created by `Symbol()` or `Symbol.for`.
+ * The `Symbol` module contains the runtime predicate for JavaScript primitive
+ * `symbol` values. It is most useful at boundaries where a value is `unknown`
+ * and must be narrowed before it can be used as a symbol key, identifier, or
+ * discriminant.
  *
- * The guard checks for the primitive `symbol` type; boxed objects created with
- * `Object(Symbol())` are objects and do not satisfy this predicate.
+ * **Mental model**
+ *
+ * - {@link isSymbol} checks `typeof value === "symbol"`
+ * - Symbols created with `globalThis.Symbol()` or `globalThis.Symbol.for(...)`
+ *   satisfy the predicate
+ * - Boxed symbols such as `Object(globalThis.Symbol())` are objects, so they do
+ *   not satisfy the predicate
+ *
+ * **Example** (Narrowing unknown input)
+ *
+ * ```ts
+ * import { Symbol } from "effect"
+ *
+ * const describe = (value: unknown) =>
+ *   Symbol.isSymbol(value) ? value.description : "not a symbol"
+ * ```
  *
  * @since 2.0.0
  */
@@ -15,6 +29,10 @@ import * as predicate from "./Predicate.ts"
 /**
  * Tests if a value is a `symbol`.
  *
+ * **When to use**
+ *
+ * Use to validate unknown input before treating it as a JavaScript `symbol`.
+ *
  * **Example** (Checking for symbols)
  *
  * ```ts