legal-markdown-js 0.1.0

package/dist/helpers/string-helpers.d.ts

@@ -0,0 +1,391 @@
+/**
+ * @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';
+ *
+ * // 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): 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 | 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 | 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;
+//# sourceMappingURL=string-helpers.d.ts.map

package/dist/helpers/string-helpers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"string-helpers.d.ts","sourceRoot":"","sources":["../../src/helpers/string-helpers.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;iTAqBiT;AAEjT;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,GAAG,MAAM,CAGjE;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,GAAG,MAAM,CAMtE;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,KAAK,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,GAAG,MAAM,CAE5D;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,KAAK,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,GAAG,MAAM,CAE5D;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,GAAG,MAAM,CAwChE;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,GAAG,MAAM,CAMhE;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,GAAG,MAAM,CAMhE;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,GAAG,MAAM,CAWhE;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,GAAG,MAAM,CAIjE;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,QAAQ,CACtB,GAAG,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,EAC9B,MAAM,EAAE,MAAM,EACd,MAAM,GAAE,MAAc,GACrB,MAAM,CAIR;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,KAAK,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,GAAG,MAAM,CAG5D;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,MAAM,CAoB9E;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,QAAQ,CACtB,GAAG,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,EAC9B,MAAM,EAAE,MAAM,EACd,IAAI,GAAE,MAAY,GACjB,MAAM,CAGR;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,GAAE,MAAY,GAAG,MAAM,CAGjG;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,QAAQ,CACtB,GAAG,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,EAC9B,SAAS,EAAE,MAAM,EACjB,aAAa,GAAE,OAAe,GAC7B,OAAO,CAQT;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,UAAU,CACxB,GAAG,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,EAC9B,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,MAAM,GACd,MAAM,CAGR;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,GAAG,MAAM,CAMhE"}