legal-markdown-js
Version:
Node.js implementation of LegalMarkdown for processing legal documents with markdown and YAML - Complete feature parity with Ruby version
394 lines • 16.1 kB
TypeScript
/**
* @fileoverview String Manipulation and Formatting Helpers
*
* This module provides comprehensive string manipulation utilities designed
* for legal document processing. It includes functions for case conversion,
* text formatting, string validation, and various text processing operations
* commonly needed in legal document generation and formatting.
*
* Features:
* - Case conversion (capitalize, title case, upper, lower)
* - String formatting (camelCase, kebab-case, snake_case, PascalCase)
* - Text manipulation (truncate, clean, pad, pluralize)
* - String validation and search (contains, replace)
* - Name processing (initials extraction)
* - Safe handling of null/undefined values
*
* @example
* ```typescript
* import { capitalize, titleCase, pluralize } from './string-helpers.js';
*
* // Case conversion
* const title = titleCase('legal document processing'); // \"Legal Document Processing\"\n *\n * // Text formatting\n * const name = capitalize('john doe'); // \"John doe\"\n *\n * // Pluralization\n * const items = pluralize('contract', 5); // \"contracts\"\n * ```\n */
/**
* Capitalizes the first letter of a string
*
* Converts the first character to uppercase and the rest to lowercase.
* Safely handles null and undefined values by returning an empty string.
*
* @param {string | undefined | null} str - The string to capitalize
* @returns {string} The capitalized string, or empty string if input is null/undefined
*
* @example
* ```typescript
* capitalize('hello world'); // "Hello world"
* capitalize('HELLO WORLD'); // "Hello world"
* capitalize('hELLO wORLD'); // "Hello world"
* capitalize(''); // ""
* capitalize(null); // ""
* capitalize(undefined); // ""
* ```
*/
export declare function capitalize(str: string | undefined | null): string;
/**
* Capitalizes the first letter of each word in a string
*
* Applies the capitalize function to each word separated by spaces,
* useful for formatting names, titles, and other multi-word strings.
*
* @param {string | undefined | null} str - The string to capitalize
* @returns {string} The string with each word capitalized
*
* @example
* ```typescript
* capitalizeWords('john doe'); // "John Doe"
* capitalizeWords('legal document'); // "Legal Document"
* capitalizeWords('HELLO WORLD'); // "Hello World"
* capitalizeWords('mixed CaSe WoRdS'); // "Mixed Case Words"
* capitalizeWords(''); // ""
* capitalizeWords(null); // ""
* ```
*/
export declare function capitalizeWords(str: string | undefined | null): string;
/**
* Converts a string to uppercase
*
* Safely converts all characters in the string to uppercase,
* handling null and undefined values gracefully.
*
* @param {string | undefined | null} str - The string to convert
* @returns {string} The uppercase string, or empty string if input is null/undefined
*
* @example
* ```typescript
* upper('hello world'); // "HELLO WORLD"
* upper('Mixed Case'); // "MIXED CASE"
* upper(''); // ""
* upper(null); // ""
* upper(undefined); // ""
* ```
*/
export declare function upper(str: string | undefined | null): string;
/**
* Converts a string to lowercase
*
* Safely converts all characters in the string to lowercase,
* handling null and undefined values gracefully.
*
* @param {string | undefined | null} str - The string to convert
* @returns {string} The lowercase string, or empty string if input is null/undefined
*
* @example
* ```typescript
* lower('HELLO WORLD'); // "hello world"
* lower('Mixed Case'); // "mixed case"
* lower(''); // ""
* lower(null); // ""
* lower(undefined); // ""
* ```
*/
export declare function lower(str: string | undefined | null): string;
/**
* Converts a string to title case with proper handling of articles and prepositions
*
* Applies title case rules where the first and last words are always capitalized,
* and small words (articles, prepositions, conjunctions) are kept lowercase
* unless they appear at the beginning or end of the string.
*
* @param {string | undefined | null} str - The string to convert to title case
* @returns {string} The title-cased string
*
* Small words that remain lowercase: a, an, and, as, at, but, by, for, if, in,
* nor, of, on, or, so, the, to, up, yet
*
* @example
* ```typescript
* titleCase('the quick brown fox'); // "The Quick Brown Fox"
* titleCase('a tale of two cities'); // "A Tale of Two Cities"
* titleCase('for whom the bell tolls'); // "For Whom the Bell Tolls"
* titleCase('HELLO WORLD'); // "Hello World"
* titleCase(''); // ""
* titleCase(null); // ""
* ```
*/
export declare function titleCase(str: string | undefined | null): string;
/**
* Converts a string to kebab-case format
*
* Transforms camelCase, PascalCase, or space-separated strings into
* kebab-case (lowercase with hyphens). Useful for URL slugs, CSS classes,
* and file names.
*
* @param {string | undefined | null} str - The string to convert
* @returns {string} The kebab-cased string
*
* @example
* ```typescript
* kebabCase('camelCaseString'); // "camel-case-string"
* kebabCase('PascalCaseString'); // "pascal-case-string"
* kebabCase('normal string'); // "normal-string"
* kebabCase('mixed_case string'); // "mixed-case-string"
* kebabCase(''); // ""
* kebabCase(null); // ""
* ```
*/
export declare function kebabCase(str: string | undefined | null): string;
/**
* Converts a string to snake_case format
*
* Transforms camelCase, PascalCase, or space-separated strings into
* snake_case (lowercase with underscores). Commonly used for variable
* names, database fields, and API parameters.
*
* @param {string | undefined | null} str - The string to convert
* @returns {string} The snake_cased string
*
* @example
* ```typescript
* snakeCase('camelCaseString'); // "camel_case_string"
* snakeCase('PascalCaseString'); // "pascal_case_string"
* snakeCase('normal string'); // "normal_string"
* snakeCase('kebab-case-string'); // "kebab_case_string"
* snakeCase(''); // ""
* snakeCase(null); // ""
* ```
*/
export declare function snakeCase(str: string | undefined | null): string;
/**
* Converts a string to camelCase format
*
* Transforms space-separated, hyphenated, or snake_case strings into
* camelCase where the first word is lowercase and subsequent words
* are capitalized. Commonly used for JavaScript variable names.
*
* @param {string | undefined | null} str - The string to convert
* @returns {string} The camelCased string
*
* @example
* ```typescript
* camelCase('normal string'); // "normalString"
* camelCase('kebab-case-string'); // "kebabCaseString"
* camelCase('snake_case_string'); // "snakeCaseString"
* camelCase('PascalCaseString'); // "pascalCaseString"
* camelCase(''); // ""
* camelCase(null); // ""
* ```
*/
export declare function camelCase(str: string | undefined | null): string;
/**
* Converts a string to PascalCase format
*
* Transforms strings into PascalCase where the first letter of each word
* is capitalized and there are no spaces or separators. Commonly used
* for class names, constructor functions, and type names.
*
* @param {string | undefined | null} str - The string to convert
* @returns {string} The PascalCased string
*
* @example
* ```typescript
* pascalCase('normal string'); // "NormalString"
* pascalCase('kebab-case-string'); // "KebabCaseString"
* pascalCase('snake_case_string'); // "SnakeCaseString"
* pascalCase('camelCaseString'); // "CamelCaseString"
* pascalCase(''); // ""
* pascalCase(null); // ""
* ```
*/
export declare function pascalCase(str: string | undefined | null): string;
/**
* Truncates a string to a specified length with optional suffix
*
* Shortens a string to the specified maximum length and appends a suffix
* (default: '...') if the string exceeds the limit. Useful for creating
* previews, summaries, or fitting text into constrained spaces.
*
* @param {string | undefined | null} str - The string to truncate
* @param {number} length - The maximum length of the result
* @param {string} suffix - The suffix to append when truncating (default: '...')
* @returns {string} The truncated string with suffix if needed
*
* @example
* ```typescript
* truncate('This is a long string', 10); // "This is a..."
* truncate('Short', 10); // "Short"
* truncate('This is a long string', 15, '…'); // "This is a long…"
* truncate('', 10); // ""
* truncate(null, 10); // ""
* ```
*/
export declare function truncate(str: string | undefined | null, length: number, suffix?: string): string;
/**
* Removes extra whitespace and trims a string
*
* Collapses multiple consecutive whitespace characters into single spaces
* and removes leading/trailing whitespace. Useful for cleaning up user
* input or text from various sources.
*
* @param {string | undefined | null} str - The string to clean
* @returns {string} The cleaned string with normalized whitespace
*
* @example
* ```typescript
* clean(' hello world '); // "hello world"
* clean('\t\n text \r\n'); // "text"
* clean('normal spacing'); // "normal spacing"
* clean(''); // ""
* clean(null); // ""
* ```
*/
export declare function clean(str: string | undefined | null): string;
/**
* Pluralizes a word based on count with optional custom plural form
*
* Returns the singular form if count is 1, otherwise returns the plural form.
* Can accept a custom plural form or will apply basic English pluralization
* rules automatically.
*
* @param {string} word - The singular form of the word
* @param {number} count - The count to determine singular/plural
* @param {string} [plural] - Optional custom plural form
* @returns {string} The appropriate singular or plural form
*
* Basic pluralization rules applied:
* - Words ending in 's', 'x', 'z', 'sh', 'ch' → add 'es'
* - Words ending in consonant + 'y' → change 'y' to 'ies'
* - All other words → add 's'
*
* @example
* ```typescript
* pluralize('cat', 1); // "cat"
* pluralize('cat', 2); // "cats"
* pluralize('box', 5); // "boxes"
* pluralize('city', 3); // "cities"
* pluralize('child', 2, 'children'); // "children"
* pluralize('person', 1, 'people'); // "person"
* pluralize('person', 3, 'people'); // "people"
* ```
*/
export declare function pluralize(word: string, count: number, plural?: string | object): string;
/**
* Pads a string to a specified length from the start (left side)
*
* Adds padding characters to the beginning of a string until it reaches
* the specified length. Useful for formatting numbers, creating aligned
* text, or ensuring consistent string lengths.
*
* @param {string | undefined | null} str - The string to pad
* @param {number} length - The target length of the result
* @param {string} char - The character to use for padding (default: ' ')
* @returns {string} The padded string
*
* @example
* ```typescript
* padStart('42', 5); // " 42"
* padStart('42', 5, '0'); // "00042"
* padStart('hello', 8, '-'); // "---hello"
* padStart('toolong', 4); // "toolong" (no padding if already longer)
* padStart('', 3); // " "
* padStart(null, 5); // " "
* ```
*/
export declare function padStart(str: string | number | undefined | null, length: number, char?: string): string;
/**
* Pads a string to a specified length from the end (right side)
*
* Adds padding characters to the end of a string until it reaches
* the specified length. Useful for creating aligned columns,
* formatting output, or ensuring consistent string lengths.
*
* @param {string | undefined | null} str - The string to pad
* @param {number} length - The target length of the result
* @param {string} char - The character to use for padding (default: ' ')
* @returns {string} The padded string
*
* @example
* ```typescript
* padEnd('42', 5); // "42 "
* padEnd('42', 5, '0'); // "42000"
* padEnd('hello', 8, '-'); // "hello---"
* padEnd('toolong', 4); // "toolong" (no padding if already longer)
* padEnd('', 3); // " "
* padEnd(null, 5); // " "
* ```
*/
export declare function padEnd(str: string | number | undefined | null, length: number, char?: string): string;
/**
* Checks if a string contains a substring with optional case sensitivity
*
* Performs substring search with configurable case sensitivity.
* Useful for filtering, validation, and text analysis.
*
* @param {string | undefined | null} str - The string to search in
* @param {string} substring - The substring to search for
* @param {boolean} caseSensitive - Whether the search is case sensitive (default: false)
* @returns {boolean} True if the substring is found, false otherwise
*
* @example
* ```typescript
* contains('Hello World', 'hello'); // true (case insensitive)
* contains('Hello World', 'hello', true); // false (case sensitive)
* contains('Hello World', 'World'); // true
* contains('Hello World', 'xyz'); // false
* contains('', 'test'); // false
* contains(null, 'test'); // false
* contains('test', ''); // false
* ```
*/
export declare function contains(str: string | undefined | null, substring: string, caseSensitive?: boolean): boolean;
/**
* Replaces all occurrences of a substring with a replacement string
*
* Performs global string replacement without using regular expressions.
* Useful for text processing, template substitution, and content cleanup.
*
* @param {string | undefined | null} str - The string to perform replacements on
* @param {string} search - The substring to search for
* @param {string} replace - The replacement string
* @returns {string} The string with all occurrences replaced
*
* @example
* ```typescript
* replaceAll('hello world hello', 'hello', 'hi'); // "hi world hi"
* replaceAll('a,b,c', ',', ' | '); // "a | b | c"
* replaceAll('test', 'x', 'y'); // "test" (no change)
* replaceAll('', 'x', 'y'); // ""
* replaceAll(null, 'x', 'y'); // ""
* ```
*/
export declare function replaceAll(str: string | undefined | null, search: string, replace: string): string;
/**
* Extracts initials from a name or multi-word string
*
* Takes the first character of each word (separated by spaces) and
* combines them into uppercase initials. Useful for creating
* abbreviated representations of names or titles.
*
* @param {string | undefined | null} name - The name or string to extract initials from
* @returns {string} The initials in uppercase
*
* @example
* ```typescript
* initials('John Doe'); // "JD"
* initials('Mary Jane Watson'); // "MJW"
* initials('single'); // "S"
* initials('jean-claude van damme'); // "JVD" (hyphens treated as separators)
* initials(''); // ""
* initials(null); // ""
* ```
*/
export declare function initials(name: string | undefined | null): string;
export declare function join(arr: unknown[], separator?: string): string;
export declare function length(value: unknown): number;
export declare function defaultVal(value: unknown, fallback?: string): unknown;
//# sourceMappingURL=string-helpers.d.ts.map