String
Works with TypeScript string values.
This module exposes common string operations in a pipe-friendly style. The helpers cover checks, comparison, concatenation, trimming, casing, slicing, padding, replacement, normalization, safe character access, search helpers that return Option, and joining strings through a reducer.
Combining
Signature
declare const concat: {
<B extends string>(that: B): <A extends string>(self: A) => `${A}${B}`;
<A extends string, B extends string>(self: A, that: B): `${A}${B}`;
};ReducerConcat
Reducer for concatenating strings.
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
concatfor concatenating two strings directly
Signature
declare const ReducerConcat: Reducer.Reducer<string>;Comparisons
localeCompare
Computes locale-aware ordering for two strings, with optional locales and collator options, and returns the result as an Ordering (-1, 0, or 1).
Signature
declare function localeCompare(
that: string,
locales?: Array<string>,
options?: CollatorOptions,
): (self: string) => Ordering;Constants
Constructors
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
isStringfor checking whether a value is a primitive string
Signature
declare const String: StringConstructor;Getters
Returns the character at the specified relative index safely, or None if the index is out of bounds.
Signature
declare const at: {
(index: number): (self: string) => Option<string>;
(self: string, index: number): Option<string>;
};Returns the character at the specified non-negative index safely, or None if the index is out of bounds.
Signature
declare const charAt: {
(index: number): (self: string) => Option<string>;
(self: string, index: number): Option<string>;
};charCodeAt
Returns the character code at the specified index safely, or None if the index is out of bounds.
Signature
declare const charCodeAt: {
(index: number): (self: string) => Option<number>;
(self: string, index: number): Option<number>;
};codePointAt
Returns the Unicode code point at the specified index safely, or None if the index is out of bounds.
Signature
declare const codePointAt: {
(index: number): (self: string) => Option<number>;
(self: string, index: number): Option<number>;
};Returns the JavaScript string length, measured in UTF-16 code units.
Signature
declare function length(self: string): number;Guards
Instances
Equivalence
Provides an Equivalence instance for strings using strict equality (===).
Signature
declare const Equivalence: Equ.Equivalence<string>;Provides an Order instance for comparing strings using lexicographic ordering.
Signature
declare const Order: order.Order<string>;Models
Concatenates two strings at the type level.
Signature
type Concat<A extends string, B extends string> = `${A}${B}`;Type-level representation of trimming whitespace from both ends of a string.
Signature
type Trim<A extends string> = TrimEnd<TrimStart<A>>;Type-level representation of trimming whitespace from the end of a string.
Signature
type TrimEnd<A extends string> = A extends `${infer B}${" " | "\n" | "\t" | "\r"}` ? TrimEnd<B> : A;Type-level representation of trimming whitespace from the start of a string.
Signature
type TrimStart<A extends string> = A extends `${" " | "\n" | "\t" | "\r"}${infer B}`
? TrimStart<B>
: A;Predicates
Returns true if the string ends with the specified search string.
Signature
declare function endsWith(searchString: string, position?: number): (self: string) => boolean;Returns true if searchString appears as a substring of self, at one or more positions that are greater than or equal to position; otherwise, returns false.
Signature
declare function includes(searchString: string, position?: number): (self: string) => boolean;isNonEmpty
Checks whether a string is non-empty.
Signature
declare function isNonEmpty(self: string): boolean;startsWith
Returns true if the string starts with the specified search string.
Signature
declare function startsWith(searchString: string, position?: number): (self: string) => boolean;Searching
Returns the index of the first occurrence of a substring safely, or None if not found.
Signature
declare function indexOf(searchString: string): (self: string) => Option<number>;lastIndexOf
Returns the index of the last occurrence of a substring safely, or None if not found.
Signature
declare function lastIndexOf(searchString: string): (self: string) => Option<number>;Matches a string against a pattern safely and returns Option.some with the match array, or Option.none when the pattern does not match.
Signature
declare function match(regExp: string | RegExp): (self: string) => Option<RegExpMatchArray>;Returns an iterator over all regular expression matches in the string using native String.prototype.matchAll semantics.
Signature
declare function matchAll(regExp: RegExp): (self: string) => IterableIterator<RegExpMatchArray>;Returns the index of the first match for a string or regular expression safely, or Option.none when no match is found.
Signature
declare const search: {
(regExp: string | RegExp): (self: string) => Option<number>;
(self: string, regExp: string | RegExp): Option<number>;
};Splitting
linesIterator
Returns an IterableIterator which yields each line contained within the string, trimming off the trailing newline character.
Signature
declare function linesIterator(self: string): LinesIterator;linesWithSeparators
Returns an IterableIterator which yields each line contained within the string as well as the trailing newline character.
Signature
declare function linesWithSeparators(s: string): LinesIterator;Transforming
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
noCasefor configurable delimiters and part transformspascalCasefor upper-initial PascalCase outputsnakeCasefor lowercase underscore-separated outputkebabCasefor lowercase hyphen-separated outputconstantCasefor uppercase underscore-separated output
Signature
declare const camelCase: (self: string) => string;camelToSnake
Converts a camelCase string to snake_case.
Signature
declare function camelToSnake(self: string): string;capitalize
Capitalizes the first character of a string.
Signature
declare function capitalize<T extends string>(self: T): Capitalize<T>;configCase
Converts a string to CONFIG_CASE (uppercase with underscores) for configuration keys.
When to use
Use to normalize configuration path segments into environment-variable-like keys while preserving numeric word groups such as v2.
Details
Unlike constantCase, digit-letter boundaries are not split. For example, "api-v2 xml" becomes "API_V2_XML".
See
constantCasefor standard uppercase underscore-separated output
Signature
declare const configCase: (self: string) => string;constantCase
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
snakeCasefor lowercase underscore-separated outputkebabCasefor lowercase hyphen-separated outputcamelCasefor lower-initial camelCase outputpascalCasefor upper-initial PascalCase outputconfigCasefor configuration key casing that preserves numeric word groupsnoCasefor configurable delimiters and part transforms
Signature
declare const constantCase: (self: string) => string;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
noCasefor configurable delimiters and part transformssnakeCasefor lowercase underscore-separated outputconstantCasefor uppercase underscore-separated outputcamelCasefor lower-initial camelCase outputpascalCasefor upper-initial PascalCase output
Signature
declare const kebabCase: (self: string) => string;kebabToSnake
Converts a kebab-case string to snake_case.
Signature
declare function kebabToSnake(self: string): string;Normalizes a string by splitting it into word parts, transforming each part, and joining the parts with a configurable delimiter.
When to use
Use when you need custom word-case output with a delimiter or part transform that the fixed case helpers do not provide.
See
pascalCasefor fixed PascalCase outputcamelCasefor fixed lower-initial camelCase outputconstantCasefor fixed uppercase underscore-separated outputkebabCasefor fixed lowercase hyphen-separated outputsnakeCasefor fixed lowercase underscore-separated output
Signature
declare const noCase: {
(options?: {
readonly delimiter?: string;
readonly splitRegExp?: RegExp | ReadonlyArray<RegExp>;
readonly stripRegExp?: RegExp | ReadonlyArray<RegExp>;
readonly transform?: (part: string, index: number, parts: ReadonlyArray<string>) => string;
}): (self: string) => string;
(
self: string,
options?: {
readonly delimiter?: string;
readonly splitRegExp?: RegExp | ReadonlyArray<RegExp>;
readonly stripRegExp?: RegExp | ReadonlyArray<RegExp>;
readonly transform?: (part: string, index: number, parts: ReadonlyArray<string>) => string;
},
): string;
};Normalizes a string according to the specified Unicode normalization form.
Signature
declare function normalize(form?: "NFC" | "NFD" | "NFKC" | "NFKD"): (self: string) => string;Pads the string from the end with a given fill string to a specified length.
Signature
declare function padEnd(maxLength: number, fillString?: string): (self: string) => string;Pads the string from the start with a given fill string to a specified length.
Signature
declare function padStart(maxLength: number, fillString?: string): (self: string) => string;pascalCase
Converts a string to PascalCase.
When to use
Use to normalize strings from spaces, separators, or camel/Pascal word boundaries into PascalCase.
See
camelCasefor lower-initial camelCase outputnoCasefor configurable delimiters and part transformssnakeToPascalfor converting known snake_case input only
Signature
declare const pascalCase: (self: string) => string;pascalToSnake
Converts a PascalCase string to snake_case.
Signature
declare function pascalToSnake(self: string): string;Repeats the string the specified number of times.
Signature
declare function repeat(count: number): (self: string) => string;Replaces matches in a string using String.prototype.replace.
Details
String search values and non-global regular expressions replace the first match; global regular expressions replace every match.
Signature
declare function replace(
searchValue: string | RegExp,
replaceValue: string,
): (self: string) => string;replaceAll
Replaces all occurrences of a substring or pattern in a string.
Signature
declare function replaceAll(
searchValue: string | RegExp,
replaceValue: string,
): (self: string) => string;Extracts a section of a string and returns it as a new string.
Signature
declare function slice(start?: number, end?: number): (self: string) => string;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
noCasefor configurable lower-level normalizationkebabCasefor lowercase hyphen-separated outputconstantCasefor uppercase underscore-separated output
Signature
declare const snakeCase: (self: string) => string;snakeToCamel
Converts a snake_case string to camelCase.
Signature
declare function snakeToCamel(self: string): string;snakeToKebab
Converts a snake_case string to kebab-case.
Signature
declare function snakeToKebab(self: string): string;snakeToPascal
Converts a snake_case string to PascalCase.
Signature
declare function snakeToPascal(self: string): string;Splits a string into an array of substrings using a separator.
Signature
declare const split: {
(separator: string | RegExp): (self: string) => [string, ...Array<string>];
(self: string, separator: string | RegExp): [string, ...Array<string>];
};stripMargin
Strips a leading | margin prefix from every line.
Signature
declare function stripMargin(self: string): string;stripMarginWith
Strips a leading margin prefix from every line using the supplied margin character.
Signature
declare const stripMarginWith: {
(marginChar: string): (self: string) => string;
(self: string, marginChar: string): string;
};Extracts characters from a string between two specified indices.
Signature
declare function substring(start: number, end?: number): (self: string) => string;Keeps the specified number of characters from the start of a string.
Details
If n is larger than the available number of characters, the string will be returned whole.
If n is not a positive number, an empty string will be returned.
If n is a float, it will be rounded down to the nearest integer.
Signature
declare const takeLeft: {
(n: number): (self: string) => string;
(self: string, n: number): string;
};Keeps the specified number of characters from the end of a string.
Details
If n is larger than the available number of characters, the string will be returned whole.
If n is not a positive number, an empty string will be returned.
If n is a float, it will be rounded down to the nearest integer.
Signature
declare const takeRight: {
(n: number): (self: string) => string;
(self: string, n: number): string;
};toLocaleLowerCase
Converts the string to lowercase according to the specified locale.
Signature
declare function toLocaleLowerCase(locale?: string | Array<string>): (self: string) => string;toLocaleUpperCase
Converts the string to uppercase according to the specified locale.
Signature
declare function toLocaleUpperCase(locale?: string | Array<string>): (self: string) => string;toLowerCase
Converts a string to lowercase.
Signature
declare function toLowerCase<T extends string>(self: T): Lowercase<T>;toUpperCase
Converts a string to uppercase.
Signature
declare function toUpperCase<S extends string>(self: S): Uppercase<S>;Removes whitespace from both ends of a string.
Signature
declare function trim<A extends string>(self: A): TrimEnd<TrimStart<A>>;Removes whitespace from the end of a string.
Signature
declare function trimEnd<A extends string>(self: A): TrimEnd<A>;Removes whitespace from the start of a string.
Signature
declare function trimStart<A extends string>(self: A): TrimStart<A>;uncapitalize
Uncapitalizes the first character of a string.
Signature
declare function uncapitalize<T extends string>(self: T): Uncapitalize<T>;
Concatenates two strings at runtime.