@ppabari/strio 1.0.2 → 1.1.0

package/dist/str.d.cts

@@ -0,0 +1,579 @@
+/**
+ * str/manipulation.ts
+ * Core string manipulation helpers.
+ */
+/**
+ * Uppercase the first character of a string.
+ *
+ * @param str   The input string.
+ * @param lowerRest  When `true`, the remaining characters are lowercased
+ *                   (turning `'hELLO'` into `'Hello'`). Defaults to `false`.
+ *
+ * @example
+ * capitalize('hello');            // → 'Hello'
+ * capitalize('hELLO', true);      // → 'Hello'
+ */
+declare function capitalize(str: string, lowerRest?: boolean): string;
+/**
+ * Capitalize the first letter of every whitespace-separated word.
+ *
+ * @example
+ * capitalizeWords('hello world'); // → 'Hello World'
+ */
+declare function capitalizeWords(str: string): string;
+/**
+ * Reverse a string. Unicode-aware — surrogate pairs (e.g. emoji) stay intact.
+ *
+ * @example
+ * reverse('abc');   // → 'cba'
+ * reverse('a😀b');  // → 'b😀a'
+ */
+declare function reverse(str: string): string;
+/**
+ * Truncate a string to at most `length` characters, appending `suffix`
+ * (default `'…'`) when truncation occurs. The suffix counts toward `length`.
+ *
+ * @example
+ * truncate('The quick brown fox', 9);        // → 'The quic…'
+ * truncate('The quick brown fox', 9, '...');  // → 'The qu...'
+ * truncate('short', 20);                       // → 'short'
+ */
+declare function truncate(str: string, length: number, suffix?: string): string;
+/**
+ * Truncate a string to at most `count` words, appending `suffix`
+ * (default `'…'`) when truncation occurs.
+ *
+ * @example
+ * truncateWords('The quick brown fox', 2); // → 'The quick…'
+ */
+declare function truncateWords(str: string, count: number, suffix?: string): string;
+/**
+ * Trim characters from both ends of a string. With no `chars` argument this
+ * behaves like `String.prototype.trim` (all whitespace). When `chars` is
+ * provided, every character in that set is stripped from both ends.
+ *
+ * @example
+ * trim('  hi  ');        // → 'hi'
+ * trim('__hi__', '_');   // → 'hi'
+ * trim('xyabcyx', 'xy'); // → 'abc'
+ */
+declare function trim(str: string, chars?: string): string;
+/**
+ * Insert `substring` into `str` at the given `index`. Negative indexes count
+ * from the end; out-of-range indexes clamp to the nearest boundary.
+ *
+ * @example
+ * insert('helloworld', 5, ' ');  // → 'hello world'
+ * insert('ac', 1, 'b');          // → 'abc'
+ */
+declare function insert(str: string, index: number, substring: string): string;
+interface MaskOptions {
+    /** Character used for masking. @default '*' */
+    maskChar?: string;
+    /** Number of leading characters left visible. @default 0 */
+    visibleStart?: number;
+    /** Number of trailing characters left visible. @default 0 */
+    visibleEnd?: number;
+}
+/**
+ * Mask the middle of a string, revealing only the first `visibleStart` and
+ * last `visibleEnd` characters. Useful for redacting emails, cards, tokens.
+ *
+ * (For secret-grade masking with length hiding see `maskSecret` in the main
+ * `@ppabari/strio` export.)
+ *
+ * @example
+ * mask('4242424242424242', { visibleStart: 0, visibleEnd: 4 });
+ * // → '************4242'
+ * mask('john@example.com', { visibleStart: 2, visibleEnd: 0 });
+ * // → 'jo**************'
+ */
+declare function mask(str: string, options?: MaskOptions): string;
+
+/**
+ * str/case.ts
+ * Case-conversion helpers. All are built on the shared `extractWords` splitter,
+ * so they handle camelCase, PascalCase, snake_case, kebab-case, spaces, and
+ * mixed inputs consistently.
+ */
+/**
+ * Convert a string to `camelCase`.
+ *
+ * @example
+ * camelize('foo-bar');      // → 'fooBar'
+ * camelize('Foo Bar Baz');  // → 'fooBarBaz'
+ * camelize('foo_bar');      // → 'fooBar'
+ */
+declare function camelize(str: string): string;
+/**
+ * Convert a string to `PascalCase` (a.k.a. UpperCamelCase).
+ *
+ * @example
+ * pascalize('foo-bar');  // → 'FooBar'
+ * pascalize('foo bar');  // → 'FooBar'
+ */
+declare function pascalize(str: string): string;
+/**
+ * Convert a string to `kebab-case` (dash-separated, lowercase).
+ *
+ * @example
+ * dasherize('fooBar');    // → 'foo-bar'
+ * dasherize('Foo Bar');   // → 'foo-bar'
+ * dasherize('foo_bar');   // → 'foo-bar'
+ */
+declare function dasherize(str: string): string;
+/**
+ * Convert a string to `snake_case` (underscore-separated, lowercase).
+ *
+ * @example
+ * underscore('fooBar');   // → 'foo_bar'
+ * underscore('Foo-Bar');  // → 'foo_bar'
+ */
+declare function underscore(str: string): string;
+
+/**
+ * str/validation.ts
+ * Boolean predicates for inspecting strings. These never throw — they return
+ * `false` for non-string input (except `isString`, whose job is that check).
+ */
+/**
+ * Whether the value is a string primitive.
+ *
+ * @example
+ * isString('a'); // → true
+ * isString(42);  // → false
+ */
+declare function isString(value: unknown): value is string;
+/**
+ * Whether the string has zero length. Non-strings are treated as empty.
+ *
+ * @example
+ * isEmpty('');    // → true
+ * isEmpty(' ');   // → false
+ */
+declare function isEmpty(value: unknown): boolean;
+/**
+ * Whether the string is empty or contains only whitespace.
+ *
+ * @example
+ * isBlank('   ');  // → true
+ * isBlank('\n\t'); // → true
+ * isBlank('a');    // → false
+ */
+declare function isBlank(value: unknown): boolean;
+/**
+ * Whether the string contains only ASCII letters (`A–Z`, `a–z`) and is
+ * non-empty.
+ *
+ * @example
+ * isAlpha('Hello'); // → true
+ * isAlpha('Hi5');   // → false
+ */
+declare function isAlpha(value: unknown): boolean;
+/**
+ * Whether the string contains only ASCII digits (`0–9`) and is non-empty.
+ * Note: this checks the *character class*, not numeric parseability — `'007'`
+ * is numeric, `'-1'` and `'1.5'` are not.
+ *
+ * @example
+ * isNumeric('12345'); // → true
+ * isNumeric('1.5');   // → false
+ */
+declare function isNumeric(value: unknown): boolean;
+/**
+ * Whether the string contains only ASCII letters and digits, and is non-empty.
+ *
+ * @example
+ * isAlphaNumeric('abc123'); // → true
+ * isAlphaNumeric('abc 12'); // → false
+ */
+declare function isAlphaNumeric(value: unknown): boolean;
+/**
+ * Whether the string is fully uppercase. It must contain at least one cased
+ * letter and be unchanged by `toUpperCase()`.
+ *
+ * @example
+ * isUpperCase('HELLO');  // → true
+ * isUpperCase('HELLO1'); // → true
+ * isUpperCase('Hello');  // → false
+ * isUpperCase('123');    // → false (no cased letters)
+ */
+declare function isUpperCase(value: unknown): boolean;
+/**
+ * Whether the string is fully lowercase. It must contain at least one cased
+ * letter and be unchanged by `toLowerCase()`.
+ *
+ * @example
+ * isLowerCase('hello');  // → true
+ * isLowerCase('Hello');  // → false
+ */
+declare function isLowerCase(value: unknown): boolean;
+
+/**
+ * str/searching.ts
+ * Substring searching, counting, and extraction helpers.
+ */
+/**
+ * Whether `str` contains `substring`.
+ *
+ * @param caseSensitive  Defaults to `true`.
+ *
+ * @example
+ * contains('Hello World', 'World');        // → true
+ * contains('Hello World', 'world');        // → false
+ * contains('Hello World', 'world', false); // → true
+ */
+declare function contains(str: string, substring: string, caseSensitive?: boolean): boolean;
+/**
+ * Whether `str` contains *every* substring in the list.
+ *
+ * @example
+ * containsAll('the quick fox', ['the', 'fox']); // → true
+ * containsAll('the quick fox', ['the', 'dog']); // → false
+ */
+declare function containsAll(str: string, substrings: string[], caseSensitive?: boolean): boolean;
+/**
+ * Whether `str` contains *at least one* substring in the list.
+ *
+ * @example
+ * containsAny('the quick fox', ['cat', 'fox']); // → true
+ * containsAny('the quick fox', ['cat', 'dog']); // → false
+ */
+declare function containsAny(str: string, substrings: string[], caseSensitive?: boolean): boolean;
+/**
+ * Count occurrences of `substring` within `str`.
+ *
+ * @param overlapping  When `true`, counts overlapping matches
+ *                     (`count('aaa', 'aa', true)` → 2). Defaults to `false`.
+ *
+ * @example
+ * count('banana', 'a');        // → 3
+ * count('aaaa', 'aa');         // → 2
+ * count('aaaa', 'aa', true);   // → 3
+ */
+declare function count(str: string, substring: string, overlapping?: boolean): number;
+/**
+ * Extract the first substring found between `start` and `end` delimiters.
+ * Returns an empty string if the pair is not found.
+ *
+ * @example
+ * between('[a][b]', '[', ']'); // → 'a'
+ * between('key=value;', '=', ';'); // → 'value'
+ */
+declare function between(str: string, start: string, end: string): string;
+/**
+ * Extract *all* non-overlapping substrings found between `start` and `end`
+ * delimiters, in document order.
+ *
+ * @example
+ * betweenAll('[a][b][c]', '[', ']'); // → ['a', 'b', 'c']
+ */
+declare function betweenAll(str: string, start: string, end: string): string[];
+
+/**
+ * str/formatting.ts
+ * Human-facing formatting helpers.
+ *
+ * NOTE: `titleCase`, `pluralize`, and `ordinalize` implement **English** rules
+ * only. Internationalization is out of scope.
+ */
+/**
+ * Convert a machine identifier (snake_case, camelCase, kebab-case…) into a
+ * human-readable sentence: words separated by spaces with the first letter
+ * capitalized.
+ *
+ * @example
+ * humanize('first_name');   // → 'First name'
+ * humanize('userID');       // → 'User id'
+ * humanize('created-at');   // → 'Created at'
+ */
+declare function humanize(str: string): string;
+/**
+ * Convert a string to Title Case using English conventions: every word is
+ * capitalized except minor words (articles, short prepositions, conjunctions),
+ * which stay lowercase unless they are the first or last word.
+ *
+ * @example
+ * titleCase('the lord of the rings'); // → 'The Lord of the Rings'
+ * titleCase('a tale of two cities');  // → 'A Tale of Two Cities'
+ */
+declare function titleCase(str: string): string;
+/**
+ * Convert a string into a URL-friendly slug: transliterated to ASCII,
+ * lowercased, with runs of non-alphanumerics collapsed to `separator`.
+ *
+ * @param separator  Word separator. Defaults to `'-'`.
+ *
+ * @example
+ * slugify('Héllo, World!');       // → 'hello-world'
+ * slugify('Foo   Bar', '_');      // → 'foo_bar'
+ */
+declare function slugify(str: string, separator?: string): string;
+/**
+ * Return the ordinal form of a number: `1` → `'1st'`, `2` → `'2nd'`,
+ * `13` → `'13th'`, `22` → `'22nd'`. Accepts a number or a numeric string.
+ *
+ * @example
+ * ordinalize(1);   // → '1st'
+ * ordinalize(11);  // → '11th'
+ * ordinalize(103); // → '103rd'
+ */
+declare function ordinalize(n: number | string): string;
+/**
+ * Pluralize an English word. If `count` is provided, the word is only
+ * pluralized when `count !== 1`. Case of the first letter is preserved.
+ *
+ * @example
+ * pluralize('cat');         // → 'cats'
+ * pluralize('bus');         // → 'buses'
+ * pluralize('city');        // → 'cities'
+ * pluralize('child');       // → 'children'
+ * pluralize('cat', 1);      // → 'cat'
+ * pluralize('cat', 3);      // → 'cats'
+ */
+declare function pluralize(word: string, count?: number): string;
+
+/**
+ * str/utilities.ts
+ * General-purpose string utilities: tokenizing, templating, similarity,
+ * transliteration, and cryptographically-secure random strings.
+ */
+/**
+ * Split a string into an array of words (runs of letters/digits), discarding
+ * punctuation and whitespace. Unlike case conversion, this does NOT break
+ * camelCase boundaries.
+ *
+ * @example
+ * words('Hello, world! 42'); // → ['Hello', 'world', '42']
+ */
+declare function words(str: string): string[];
+/**
+ * Count the words in a string.
+ *
+ * @example
+ * wordCount('the quick brown fox'); // → 4
+ */
+declare function wordCount(str: string): number;
+/**
+ * Join a list of values with a separator, skipping `null`, `undefined`, and
+ * empty-string entries so you never get doubled or trailing separators.
+ *
+ * @param separator  Defaults to `' '`.
+ *
+ * @example
+ * join(['a', '', 'b', null, 'c']);        // → 'a b c'
+ * join(['2024', '01', '05'], '-');        // → '2024-01-05'
+ */
+declare function join(values: Array<string | number | null | undefined>, separator?: string): string;
+interface TemplateOptions {
+    /**
+     * Value substituted for keys missing from `data`. When `undefined`
+     * (default), the original `{{placeholder}}` is left untouched.
+     */
+    fallback?: string;
+}
+/**
+ * Interpolate `{{key}}` placeholders in `str` with values from `data`.
+ * Whitespace inside the braces is ignored (`{{ name }}` works). Values are
+ * coerced to strings.
+ *
+ * @example
+ * template('Hi {{name}}!', { name: 'Ada' });      // → 'Hi Ada!'
+ * template('{{a}}/{{b}}', { a: 1, b: 2 });         // → '1/2'
+ * template('Hi {{name}}', {}, { fallback: '?' });  // → 'Hi ?'
+ */
+declare function template(str: string, data: Record<string, unknown>, options?: TemplateOptions): string;
+/**
+ * Generate a cryptographically-secure random string of the given `length`.
+ * Uses the same bias-free Web-Crypto engine as the rest of `@ppabari/strio`.
+ *
+ * @param charset  A named charset alias (e.g. `'base58'`, `'hex'`) or a raw
+ *                 string of characters to draw from. Defaults to
+ *                 `'alphanumeric'`.
+ *
+ * @example
+ * random(16);              // → 16 alphanumeric chars
+ * random(8, 'hex');        // → 8 hex chars
+ * random(4, 'ABC');        // → 4 chars from {A, B, C}
+ */
+declare function random(length: number, charset?: string): string;
+/**
+ * Secure random string of ASCII letters (mixed case).
+ * @example randomAlpha(10); // → e.g. 'QwErTyUiOp'
+ */
+declare function randomAlpha(length: number): string;
+/**
+ * Secure random string of digits.
+ * @example randomNumeric(6); // → e.g. '048213'
+ */
+declare function randomNumeric(length: number): string;
+/**
+ * Secure random string of ASCII letters and digits.
+ * @example randomAlphanumeric(12);
+ */
+declare function randomAlphanumeric(length: number): string;
+/**
+ * Compute a normalized similarity ratio in `[0, 1]` between two strings,
+ * based on Levenshtein edit distance (`1` = identical, `0` = nothing in
+ * common). Two empty strings are considered identical.
+ *
+ * @example
+ * similarity('kitten', 'sitting'); // → ~0.571
+ * similarity('abc', 'abc');        // → 1
+ */
+declare function similarity(a: string, b: string): number;
+/**
+ * Transliterate accented and special Latin characters to their closest ASCII
+ * equivalents. Diacritics are stripped via Unicode NFKD normalization; a small
+ * map handles ligatures and letters that don't decompose (ß, æ, ø, …).
+ *
+ * Non-Latin scripts are left unchanged.
+ *
+ * @example
+ * transliterate('Héllo Wörld');  // → 'Hello World'
+ * transliterate('Straße');       // → 'Strasse'
+ * transliterate('naïve café');   // → 'naive cafe'
+ */
+declare function transliterate(str: string): string;
+
+/**
+ * str/padding.ts
+ * Padding and indentation helpers.
+ */
+/**
+ * Left-pad a string to `length` using `char` (default `' '`). Returns the
+ * string unchanged if it is already at least `length`.
+ *
+ * @example
+ * padLeft('7', 3, '0');  // → '007'
+ * padLeft('hi', 5);      // → '   hi'
+ */
+declare function padLeft(str: string, length: number, char?: string): string;
+/**
+ * Right-pad a string to `length` using `char` (default `' '`).
+ *
+ * @example
+ * padRight('7', 3, '0'); // → '700'
+ */
+declare function padRight(str: string, length: number, char?: string): string;
+/**
+ * Center a string within `length`, padding both sides with `char`. When the
+ * padding can't be split evenly, the extra character goes on the right.
+ *
+ * @example
+ * padCenter('hi', 6);       // → '  hi  '
+ * padCenter('hi', 7, '*');  // → '**hi***'
+ */
+declare function padCenter(str: string, length: number, char?: string): string;
+/**
+ * Indent every line of a string by `count` repetitions of `char`
+ * (default: 2 spaces). Blank lines are left untouched by default.
+ *
+ * @param char        The indentation unit. @default ' '
+ * @param indentEmpty When `true`, blank lines are indented too. @default false
+ *
+ * @example
+ * indent('a\nb');            // → '  a\n  b'
+ * indent('a\nb', 1, '\t');   // → '\ta\n\tb'
+ */
+declare function indent(str: string, count?: number, char?: string, indentEmpty?: boolean): string;
+/**
+ * Remove the common leading whitespace from every line — the inverse of
+ * `indent`, useful for tidying template literals. Fully-blank lines are ignored
+ * when computing the common indent, and leading/trailing blank lines are
+ * trimmed.
+ *
+ * @example
+ * dedent('    a\n    b');       // → 'a\nb'
+ * dedent('\n  foo\n    bar\n'); // → 'foo\n  bar'
+ */
+declare function dedent(str: string): string;
+
+/**
+ * str/security.ts
+ * Escaping, sanitizing, and safe-affix helpers.
+ *
+ * NOTE: `escapeHtml` / `stripTags` provide basic protection for text
+ * interpolation. They are NOT a substitute for a full HTML sanitizer (e.g.
+ * DOMPurify) when rendering untrusted rich markup.
+ */
+/**
+ * Escape the five characters that are significant in HTML (`& < > " '`) so a
+ * string can be safely interpolated into markup as text.
+ *
+ * @example
+ * escapeHtml('<a href="x">Tom & Jerry</a>');
+ * // → '&lt;a href=&quot;x&quot;&gt;Tom &amp; Jerry&lt;/a&gt;'
+ */
+declare function escapeHtml(str: string): string;
+/**
+ * Reverse `escapeHtml`, decoding the common named and numeric HTML entities.
+ *
+ * @example
+ * unescapeHtml('&lt;b&gt;hi&lt;/b&gt;'); // → '<b>hi</b>'
+ */
+declare function unescapeHtml(str: string): string;
+/**
+ * Escape a string so it can be used literally inside a `RegExp` — every
+ * regex-special character is backslash-escaped.
+ *
+ * @example
+ * escapeRegExp('a.b*c'); // → 'a\\.b\\*c'
+ * new RegExp(escapeRegExp('$5.00')).test('$5.00'); // → true
+ */
+declare function escapeRegExp(str: string): string;
+/**
+ * Strip all HTML/XML tags from a string, leaving the text content.
+ *
+ * @example
+ * stripTags('<p>Hello <b>world</b></p>'); // → 'Hello world'
+ */
+declare function stripTags(str: string): string;
+/**
+ * Collapse all runs of whitespace (spaces, tabs, newlines) into a single
+ * space and trim the ends.
+ *
+ * @example
+ * collapseWhitespace('  a\n\t  b   c '); // → 'a b c'
+ */
+declare function collapseWhitespace(str: string): string;
+/**
+ * Remove `prefix` from the start of `str`, if present. Idempotent.
+ *
+ * @example
+ * stripPrefix('usr_123', 'usr_'); // → '123'
+ * stripPrefix('123', 'usr_');     // → '123'
+ */
+declare function stripPrefix(str: string, prefix: string): string;
+/**
+ * Remove `suffix` from the end of `str`, if present. Idempotent.
+ *
+ * @example
+ * stripSuffix('report.txt', '.txt'); // → 'report'
+ * stripSuffix('report', '.txt');     // → 'report'
+ */
+declare function stripSuffix(str: string, suffix: string): string;
+
+/**
+ * str/ensuring.ts
+ * Idempotent affix helpers — guarantee a string starts/ends a certain way
+ * without duplicating an affix that is already present.
+ */
+/**
+ * Ensure `str` starts with `prefix`, prepending it only if missing. Idempotent.
+ *
+ * @example
+ * ensureLeft('example.com', 'https://');         // → 'https://example.com'
+ * ensureLeft('https://example.com', 'https://'); // → 'https://example.com'
+ */
+declare function ensureLeft(str: string, prefix: string): string;
+/**
+ * Ensure `str` ends with `suffix`, appending it only if missing. Idempotent.
+ *
+ * @example
+ * ensureRight('path', '/');   // → 'path/'
+ * ensureRight('path/', '/');  // → 'path/'
+ */
+declare function ensureRight(str: string, suffix: string): string;
+
+export { type MaskOptions, type TemplateOptions, between, betweenAll, camelize, capitalize, capitalizeWords, collapseWhitespace, contains, containsAll, containsAny, count, dasherize, dedent, ensureLeft, ensureRight, escapeHtml, escapeRegExp, humanize, indent, insert, isAlpha, isAlphaNumeric, isBlank, isEmpty, isLowerCase, isNumeric, isString, isUpperCase, join, mask, ordinalize, padCenter, padLeft, padRight, pascalize, pluralize, random, randomAlpha, randomAlphanumeric, randomNumeric, reverse, similarity, slugify, stripPrefix, stripSuffix, stripTags, template, titleCase, transliterate, trim, truncate, truncateWords, underscore, unescapeHtml, wordCount, words };