@uon/string-utils

A small collection of zero-dependency string utility functions used across the @uon workspace: case conversion, quoting, hashing, formatting, padding and similarity.

Installation

npm i @uon/string-utils

No peer dependencies — this package is standalone.

Usage

import { CamelCase, Hyphenate, Quote, Format } from '@uon/string-utils';

CamelCase('background-color');   // 'backgroundColor'
Hyphenate('backgroundColor');    // 'background-color'
Quote('say "hi"');               // '"say \\"hi\\""'
Format('Hello {0}!', 'world');   // 'Hello world!'

API Reference

Case conversion

CamelCase(str, upperCamelCase?)

Transforms a string separated by :, -, _ or . into camelCase. Pass upperCamelCase = true for PascalCase. A null/undefined input is returned as-is.

CamelCase('foo-bar-baz');        // 'fooBarBaz'
CamelCase('foo_bar');            // 'fooBar'
CamelCase('foo-bar', true);      // 'FooBar'

| Param | Type | Description | |-------|------|-------------| | str | string | The subject string. | | upperCamelCase | boolean? | Capitalize the first letter when true. | | returns | string | The camelCased string. |

Hyphenate(str, sep?)

Inverse of CamelCase: each uppercase letter becomes sep + its lowercase form. A leading separator (from an UpperCamelCase input) is stripped. sep may contain regex‑special characters safely.

Hyphenate('backgroundColor');    // 'background-color'
Hyphenate('FooBar');             // 'foo-bar'
Hyphenate('fooBar', '_');        // 'foo_bar'

| Param | Type | Description | |-------|------|-------------| | str | string | The camelCase string. | | sep | string? | Separator, defaults to '-'. | | returns | string | The hyphenated, lower-cased string. |

Quoting

Quote(str)

Wraps a string in double quotes, escaping embedded double quotes as \".

Quote('hello');                  // '"hello"'
Quote('a"b');                    // '"a\\"b"'

Unquote(str, quoteChar?)

Removes surrounding quoteChar only when the string starts and ends with it, and unescapes every \<quoteChar> inside. Assumes the string is trimmed. The inverse of Quote for the default ". Returns the input unchanged if it is not quoted. quoteChar may contain regex‑special characters safely.

Unquote('"hello"');              // 'hello'
Unquote('"a\\"b"');              // 'a"b'
Unquote('hello');                // 'hello' (unchanged)
Unquote("'x'", "'");             // 'x'

Hashing

Hash(s)

Returns the classic Java String.hashCode as a 32-bit signed integer. Fast and deterministic, but not cryptographically secure — use it for bucketing/keys.

Hash('hello');                   // a stable 32-bit integer
Hash('');                        // 0

Formatting

Format(str, ...args)

Replaces {0}, {1}, … placeholders with the corresponding positional argument. Unmatched placeholders are left intact.

Format('{0} + {1} = {2}', 1, 2, 3);   // '1 + 2 = 3'
Format('{0} {1}', 'only');            // 'only {1}'

PadLeft(val, maxLen, padWith) / PadRight(val, maxLen, padWith)

Pads val (string or number) to maxLen characters using padWith (which may be longer than one character). When padWith does not fit evenly, the partial padding is sliced from the back (PadLeft) or the front (PadRight). The value is returned unchanged when it is already at least maxLen, or when padWith is empty.

PadLeft('5', 3, '0');            // '005'
PadRight('5', 3, '0');           // '500'
PadLeft('5', 4, 'ab');           // 'bab5'
PadRight('5', 4, 'ab');          // '5aba'

Similarity

Similarity(str1, str2)

Computes cosine similarity over the character-frequency vectors of the two strings.

Similarity('abc', 'abc');        // 1.0
Similarity('abc', '');           // 0.0
Similarity('night', 'nacht');    // a value in [0, 1]

Returns 1.0 for identical strings and 0.0 when either string is empty; otherwise a value in [0, 1].

License

MIT