effect 4.0.0-beta.70 → 4.0.0-beta.72

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
  */
@@ -18,7 +80,19 @@ import * as predicate from "./Predicate.ts"
 import * as Reducer from "./Reducer.ts"
 
 /**
- * Reference to the global `String` constructor.
+ * Exposes the global string constructor.
+ *
+ * **When to use**
+ *
+ * Use to access native JavaScript string coercion or constructor behavior from
+ * the Effect module namespace.
+ *
+ * **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
@@ -26,7 +100,7 @@ import * as Reducer from "./Reducer.ts"
 export const String = globalThis.String
 
 /**
- * Tests if a value is a `string`.
+ * Checks whether a value is a `string`.
  *
  * **Example** (Checking for strings)
  *
@@ -44,7 +118,8 @@ export const String = globalThis.String
 export const isString: Refinement<unknown, string> = predicate.isString
 
 /**
- * `Order` instance for comparing strings using lexicographic ordering.
+ * Provides an `Order` instance for comparing strings using lexicographic
+ * ordering.
  *
  * **Example** (Comparing strings lexicographically)
  *
@@ -62,7 +137,7 @@ export const isString: Refinement<unknown, string> = predicate.isString
 export const Order: order.Order<string> = order.String
 
 /**
- * An `Equivalence` instance for strings using strict equality (`===`).
+ * Provides an `Equivalence` instance for strings using strict equality (`===`).
  *
  * **Example** (Comparing strings for equality)
  *
@@ -79,7 +154,11 @@ export const Order: order.Order<string> = order.String
 export const Equivalence: Equ.Equivalence<string> = Equ.String
 
 /**
- * The empty string `""`.
+ * Provides the empty string `""`.
+ *
+ * **When to use**
+ *
+ * Use when you need the canonical empty string value from the `String` module.
  *
  * **Example** (Using the empty string)
  *
@@ -90,7 +169,7 @@ export const Equivalence: Equ.Equivalence<string> = Equ.String
  * console.log(String.isEmpty(String.empty)) // true
  * ```
  *
- * @category constructors
+ * @category constants
  * @since 2.0.0
  */
 export const empty: "" = "" as const
@@ -399,7 +478,7 @@ export const trimEnd = <A extends string>(self: A): TrimEnd<A> => self.trimEnd()
 export const slice = (start?: number, end?: number) => (self: string): string => self.slice(start, end)
 
 /**
- * Test whether a `string` is empty.
+ * Checks whether a `string` is empty.
  *
  * **Example** (Checking for empty strings)
  *
@@ -417,7 +496,7 @@ export const slice = (start?: number, end?: number) => (self: string): string =>
 export const isEmpty = (self: string): self is "" => self.length === 0
 
 /**
- * Test whether a `string` is non empty.
+ * Checks whether a `string` is non-empty.
  *
  * **Example** (Checking for non-empty strings)
  *
@@ -569,7 +648,7 @@ export const endsWith = (searchString: string, position?: number) => (self: stri
   self.endsWith(searchString, position)
 
 /**
- * Returns the character code at the specified index, or `None` if the index is out of bounds.
+ * Returns the character code at the specified index safely, or `None` if the index is out of bounds.
  *
  * **Example** (Reading character codes)
  *
@@ -585,7 +664,7 @@ export const endsWith = (searchString: string, position?: number) => (self: stri
  */
 export const charCodeAt: {
   /**
-   * Returns the character code at the specified index, or `None` if the index is out of bounds.
+   * Returns the character code at the specified index safely, or `None` if the index is out of bounds.
    *
    * **Example** (Reading character codes)
    *
@@ -601,7 +680,7 @@ export const charCodeAt: {
    */
   (index: number): (self: string) => Option.Option<number>
   /**
-   * Returns the character code at the specified index, or `None` if the index is out of bounds.
+   * Returns the character code at the specified index safely, or `None` if the index is out of bounds.
    *
    * **Example** (Reading character codes)
    *
@@ -640,7 +719,7 @@ export const charCodeAt: {
 export const substring = (start: number, end?: number) => (self: string): string => self.substring(start, end)
 
 /**
- * Returns the character at the specified index, or `None` if the index is out of bounds.
+ * Returns the character at the specified relative index safely, or `None` if the index is out of bounds.
  *
  * **Example** (Accessing characters safely)
  *
@@ -656,7 +735,7 @@ export const substring = (start: number, end?: number) => (self: string): string
  */
 export const at: {
   /**
-   * Returns the character at the specified index, or `None` if the index is out of bounds.
+   * Returns the character at the specified relative index safely, or `None` if the index is out of bounds.
    *
    * **Example** (Accessing characters safely)
    *
@@ -672,7 +751,7 @@ export const at: {
    */
   (index: number): (self: string) => Option.Option<string>
   /**
-   * Returns the character at the specified index, or `None` if the index is out of bounds.
+   * Returns the character at the specified relative index safely, or `None` if the index is out of bounds.
    *
    * **Example** (Accessing characters safely)
    *
@@ -690,7 +769,7 @@ export const at: {
 } = dual(2, (self: string, index: number): Option.Option<string> => Option.fromUndefinedOr(self.at(index)))
 
 /**
- * Returns the character at the specified index, or `None` if the index is out of bounds.
+ * Returns the character at the specified non-negative index safely, or `None` if the index is out of bounds.
  *
  * **Example** (Reading characters safely)
  *
@@ -706,7 +785,7 @@ export const at: {
  */
 export const charAt: {
   /**
-   * Returns the character at the specified index, or `None` if the index is out of bounds.
+   * Returns the character at the specified non-negative index safely, or `None` if the index is out of bounds.
    *
    * **Example** (Reading characters safely)
    *
@@ -722,7 +801,7 @@ export const charAt: {
    */
   (index: number): (self: string) => Option.Option<string>
   /**
-   * Returns the character at the specified index, or `None` if the index is out of bounds.
+   * Returns the character at the specified non-negative index safely, or `None` if the index is out of bounds.
    *
    * **Example** (Reading characters safely)
    *
@@ -743,7 +822,7 @@ export const charAt: {
 )
 
 /**
- * Returns the Unicode code point at the specified index, or `None` if the index is out of bounds.
+ * Returns the Unicode code point at the specified index safely, or `None` if the index is out of bounds.
  *
  * **Example** (Reading code points)
  *
@@ -759,7 +838,7 @@ export const charAt: {
  */
 export const codePointAt: {
   /**
-   * Returns the Unicode code point at the specified index, or `None` if the index is out of bounds.
+   * Returns the Unicode code point at the specified index safely, or `None` if the index is out of bounds.
    *
    * **Example** (Reading code points)
    *
@@ -775,7 +854,7 @@ export const codePointAt: {
    */
   (index: number): (self: string) => Option.Option<number>
   /**
-   * Returns the Unicode code point at the specified index, or `None` if the index is out of bounds.
+   * Returns the Unicode code point at the specified index safely, or `None` if the index is out of bounds.
    *
    * **Example** (Reading code points)
    *
@@ -793,7 +872,7 @@ export const codePointAt: {
 } = dual(2, (self: string, index: number): Option.Option<number> => Option.fromUndefinedOr(self.codePointAt(index)))
 
 /**
- * Returns the index of the first occurrence of a substring, or `None` if not found.
+ * Returns the index of the first occurrence of a substring safely, or `None` if not found.
  *
  * **Example** (Finding the first substring index)
  *
@@ -811,7 +890,7 @@ export const indexOf = (searchString: string) => (self: string): Option.Option<n
   Option.filter(Option.some(self.indexOf(searchString)), number.isGreaterThanOrEqualTo(0))
 
 /**
- * Returns the index of the last occurrence of a substring, or `None` if not found.
+ * Returns the index of the last occurrence of a substring safely, or `None` if not found.
  *
  * **Example** (Finding the last substring index)
  *
@@ -829,7 +908,7 @@ export const lastIndexOf = (searchString: string) => (self: string): Option.Opti
   Option.filter(Option.some(self.lastIndexOf(searchString)), number.isGreaterThanOrEqualTo(0))
 
 /**
- * Compares two strings using locale-aware collation, with optional locales and
+ * Computes locale-aware ordering for two strings, with optional locales and
  * collator options, and returns the result as an `Ordering` (`-1`, `0`, or
  * `1`).
  *
@@ -852,7 +931,7 @@ export const localeCompare =
     number.sign(self.localeCompare(that, locales, options))
 
 /**
- * Matches a string against a pattern and returns `Option.some` with the match
+ * Matches a string against a pattern safely and returns `Option.some` with the match
  * array, or `Option.none` when the pattern does not match.
  *
  * **Example** (Matching regular expressions)
@@ -996,7 +1075,7 @@ export const replaceAll = (searchValue: string | RegExp, replaceValue: string) =
   self.replaceAll(searchValue, replaceValue)
 
 /**
- * Returns the index of the first match for a string or regular expression, or
+ * Returns the index of the first match for a string or regular expression safely, or
  * `Option.none` when no match is found.
  *
  * **Example** (Searching strings)
@@ -1014,7 +1093,7 @@ export const replaceAll = (searchValue: string | RegExp, replaceValue: string) =
  */
 export const search: {
   /**
-   * Returns the index of the first match for a string or regular expression, or
+   * Returns the index of the first match for a string or regular expression safely, or
    * `Option.none` when no match is found.
    *
    * **Example** (Searching strings)
@@ -1032,7 +1111,7 @@ export const search: {
    */
   (regExp: RegExp | string): (self: string) => Option.Option<number>
   /**
-   * Returns the index of the first match for a string or regular expression, or
+   * Returns the index of the first match for a string or regular expression safely, or
    * `Option.none` when no match is found.
    *
    * **Example** (Searching strings)
@@ -1094,7 +1173,7 @@ export const toLocaleUpperCase = (locale?: string | Array<string>) => (self: str
   self.toLocaleUpperCase(locale)
 
 /**
- * Keep the specified number of characters from the start of a string.
+ * Keeps the specified number of characters from the start of a string.
  *
  * **Details**
  *
@@ -1119,7 +1198,7 @@ export const toLocaleUpperCase = (locale?: string | Array<string>) => (self: str
  */
 export const takeLeft: {
   /**
-   * Keep the specified number of characters from the start of a string.
+   * Keeps the specified number of characters from the start of a string.
    *
    * **Details**
    *
@@ -1144,7 +1223,7 @@ export const takeLeft: {
    */
   (n: number): (self: string) => string
   /**
-   * Keep the specified number of characters from the start of a string.
+   * Keeps the specified number of characters from the start of a string.
    *
    * **Details**
    *
@@ -1171,7 +1250,7 @@ export const takeLeft: {
 } = dual(2, (self: string, n: number): string => self.slice(0, Math.max(n, 0)))
 
 /**
- * Keep the specified number of characters from the end of a string.
+ * Keeps the specified number of characters from the end of a string.
  *
  * **Details**
  *
@@ -1196,7 +1275,7 @@ export const takeLeft: {
  */
 export const takeRight: {
   /**
-   * Keep the specified number of characters from the end of a string.
+   * Keeps the specified number of characters from the end of a string.
    *
    * **Details**
    *
@@ -1221,7 +1300,7 @@ export const takeRight: {
    */
   (n: number): (self: string) => string
   /**
-   * Keep the specified number of characters from the end of a string.
+   * Keeps the specified number of characters from the end of a string.
    *
    * **Details**
    *
@@ -1290,9 +1369,8 @@ export const linesIterator = (self: string): LinesIterator => linesSeparated(sel
 export const linesWithSeparators = (s: string): LinesIterator => linesSeparated(s, false)
 
 /**
- * For every line in this string, strip a leading prefix consisting of blanks
- * or control characters followed by the character specified by `marginChar`
- * from the line.
+ * Strips a leading margin prefix from every line using the supplied margin
+ * character.
  *
  * **Example** (Stripping custom margins)
  *
@@ -1309,9 +1387,8 @@ export const linesWithSeparators = (s: string): LinesIterator => linesSeparated(
  */
 export const stripMarginWith: {
   /**
-   * For every line in this string, strip a leading prefix consisting of blanks
-   * or control characters followed by the character specified by `marginChar`
-   * from the line.
+   * Strips a leading margin prefix from every line using the supplied margin
+   * character.
    *
    * **Example** (Stripping custom margins)
    *
@@ -1328,9 +1405,8 @@ export const stripMarginWith: {
    */
   (marginChar: string): (self: string) => string
   /**
-   * For every line in this string, strip a leading prefix consisting of blanks
-   * or control characters followed by the character specified by `marginChar`
-   * from the line.
+   * Strips a leading margin prefix from every line using the supplied margin
+   * character.
    *
    * **Example** (Stripping custom margins)
    *
@@ -1367,8 +1443,7 @@ export const stripMarginWith: {
 })
 
 /**
- * For every line in this string, strip a leading prefix consisting of blanks
- * or control characters followed by the `"|"` character from the line.
+ * Strips a leading `|` margin prefix from every line.
  *
  * **Example** (Stripping pipe margins)
  *
@@ -1548,7 +1623,7 @@ class LinesIterator implements IterableIterator<string> {
 }
 
 /**
- * Test if the provided character is a line break character (i.e. either `"\r"`
+ * Checks whether the provided character is a line break character (i.e. either `"\r"`
  * or `"\n"`).
  */
 const isLineBreak = (char: string): boolean => {
@@ -1557,7 +1632,7 @@ const isLineBreak = (char: string): boolean => {
 }
 
 /**
- * Test if the provided characters combine to form a carriage return/line-feed
+ * Checks whether the provided characters combine to form a carriage return/line-feed
  * (i.e. `"\r\n"`).
  */
 const isLineBreak2 = (char0: string, char1: string): boolean => char0.charCodeAt(0) === CR && char1.charCodeAt(0) === LF
@@ -1568,6 +1643,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 +1663,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 +1690,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 +1758,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 +1783,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 +1805,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 +1827,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 +1848,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
  */
@@ -1703,7 +1865,17 @@ export const snakeCase: (self: string) => string = noCase({
 })
 
 /**
- * A `Reducer` for concatenating `string`s.
+ * 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