shelving/util/string.d.ts

Toolkit for using data in JavaScript.

import type { ImmutableArray } from "./array.js";
import type { AnyCaller } from "./function.js";
/**
 * Type that never matches the `string` type.
 * - `string` itself is iterable (iterating over its individual characters) and implements `Iterable<string>`
 * - Using `Iterable<string> & NotString` allows an iterable containing strings but not `string` itself.
 * - This helps catch this category of subtle errors.
 */
export type NotString = {
    toUpperCase?: never;
    toLowerCase?: never;
};
/** Things that can be easily converted to a string. */
export type PossibleString = string | number | Date;
/** Is a value a string (optionally with specified min/max length). */
export declare function isString(value: unknown, min?: number, max?: number): value is string;
/** Assert that a value is a string (optionally with specified min/max length). */
export declare function assertString(value: unknown, min?: number, max?: number, caller?: AnyCaller): asserts value is string;
/** Convert an unknown value to a string, or return `undefined` if conversion fails. */
export declare function getString(value: unknown): string | undefined;
/** Convert a possible string to a string (optionally with specified min/max length), or throw `RequiredError` if conversion fails. */
export declare function requireString(value: PossibleString, min?: number, max?: number, caller?: AnyCaller): string;
/** Does a string have a length between `min` and `max` */
export declare function isStringBetween(str: string, min?: number, max?: number): boolean;
/** Concatenate an iterable set of strings together. */
export declare function joinStrings(strs: Iterable<string> & NotString, joiner?: string): string;
/**
 * Sanitize a single line of text.
 * - Used when you're sanitising a single-line input, e.g. a title for something.
 * - Remove allow control characters
 * - Normalise runs of whitespace to one ` ` space,
 * - Trim whitespace from the start and end of the string.
 *
 * @example santizeString("\x00Nice!   "); // Returns `"Nice!"`
 */
export declare function sanitizeText(str: string): string;
/**
 * Sanitize multiple lines of text.
 * - Used when you're sanitising a multi-line input, e.g. a description for something.
 * - Remove all control characters except `\n` newline.
 * - Normalise weird characters like paragraph separator, line separator, `\t` tab, `\r` carriage return.
 * - Normalise runs of whitespace to one ` ` space,
 * - Normalise indentation to tabs (four or more spaces are a tab, three or fewer spaces are removed).
 * - Allow spaces at the start of each line (for indentation) but trim the end of each line.
 * - Trim excess newlines at the start and end of the string and runs of more than two newlines in a row.
 */
export declare function sanitizeMultilineText(str: string): string;
/**
 * Simplify a string by removing anything that isn't a number, letter, or space.
 * - Normalizes the string by
 * - Useful when you're running a query against a string entered by a user.
 *
 * @example simplifyString("Däve-is\nREALLY    éxcitable—apparęntly!!!    😂"); // Returns "dave is really excitable apparently"
 *
 * @todo Convert confusables (e.g. `ℵ` alef symbol or `℮` estimate symbol) to their letterlike equivalent (e.g. `N` and `e`).
 */
export declare function simplifyString(str: string): string;
/** Convert a string to a `kebab-case` URL slug, or return `undefined` if conversion resulted in an empty ref. */
export declare function getSlug(str: string): string | undefined;
/** Convert a string to a `kebab-case` URL slug, or throw `RequiredError` if conversion resulted in an empty ref. */
export declare function requireSlug(str: string, caller?: AnyCaller): string;
/** Convert a string to a unique ref e.g. `abc123`, or return `undefined` if conversion resulted in an empty string. */
export declare function getRef(str: string): string | undefined;
/** Convert a string to a unique ref e.g. `abc123`, or throw `RequiredError` if conversion resulted in an empty string. */
export declare function requireRef(str: string, caller?: AnyCaller): string;
/**
 * Return an array of the separate words and "quoted phrases" found in a string.
 * - Phrases enclosed "in quotes" are a single word.
 * - Performs no processing on the words, so control chars, punctuation, symbols, and case are all preserved.
 *
 * Note: this splits words based on spaces, so won't work well with logographic writing systems e.g. kanji.
 */
export declare function getWords(str: string): ImmutableArray<string>;
/** Get the (trimmed) first full line of a string. */
export declare function getFirstLine(str: string): string;
/** Is the first character of a string an uppercase letter? */
export declare function isUppercaseLetter(str: string): boolean;
/** Is the first character of a string a lowercase letter? */
export declare function isLowercaseLetter(str: string): boolean;
/**
 * Limit a string to a given length.
 * - Stops at the last space inside `maxLength`
 * - Appends an `…` ellipses after the string (but only if a limit is applied).
 */
export declare function limitString(str: string, maxLength: number, append?: string): string;
/**
 * Divide a string into parts based on a separator.
 * - Like `String.prototype.split()` but with more useful arguments.
 * - Excess segments in `String.prototype.split()` is counterintuitive because further parts are thrown away.
 * - Excess segments in `splitString()` are concatenated onto the last segment (set `max` to `null` if you want infinite segments).
 *
 * @throws RequiredError if `min` isn't met.
 * @throws RequiredError if any of the segments are empty.
 */
export declare function splitString(str: string, separator: string, min: 1, max: 1, caller?: AnyCaller): readonly [string];
export declare function splitString(str: string, separator: string, min: 2, max: 2, caller?: AnyCaller): readonly [string, string];
export declare function splitString(str: string, separator: string, min: 3, max: 3, caller?: AnyCaller): readonly [string, string, string];
export declare function splitString(str: string, separator: string, min: 4, max: 4, caller?: AnyCaller): readonly [string, string, string, string];
export declare function splitString(str: string, separator: string, min?: 1, max?: number, caller?: AnyCaller): readonly [string, ...string[]];
export declare function splitString(str: string, separator: string, min: 2, max?: number, caller?: AnyCaller): readonly [string, string, ...string[]];
export declare function splitString(str: string, separator: string, min: 3, max?: number, caller?: AnyCaller): readonly [string, string, string, ...string[]];
export declare function splitString(str: string, separator: string, min: 4, max?: number, caller?: AnyCaller): readonly [string, string, string, string, ...string[]];
export declare function splitString(str: string, separator: string, min?: number, max?: number, caller?: AnyCaller): ImmutableArray<string>;