lex-module

v1.3.2

Published

11 days ago

A comprehensive JavaScript string manipulation library with fluent API

0High
0Medium
0Low

lexuss1979s

string manipulation text fluent api chainable string-operations text-processing utilities helper

lex-module

A lightweight, chainable JavaScript string manipulation library with comprehensive text processing capabilities.

Features

Chainable API: Fluent method chaining for elegant string operations
Comprehensive Methods: 54+ string manipulation utilities
Input Validation: Built-in validation for robust error handling
Zero Dependencies: Pure JavaScript implementation
Well Tested: Comprehensive test suite with Mocha (529+ tests)
HTML-Safe Truncation: Smart text truncation that preserves HTML structure
Smart Truncation: Word boundary truncation for better readability
Comprehensive Validation: Email, IP, phone number, and date validation
Modular Architecture: Well-organized source code in 15 functional modules

Project Structure

The library has been refactored into a modular architecture for better maintainability:

src/
  core/           # Core string operations (length, split, toString, duplicate, inverse, trim)
  case/           # Case manipulation (uppercase, lowercase, ucFirst, capitalize)
  search/         # Search and truncation (startsWith, endsWith, contains, truncate, truncateRight, truncateWithTags, smartTruncate)
  words/          # Word operations (words, wordsCount, wordsFreq, firstWord, lastWord, randomWord, randomizeWords, acronym)
  comparison/     # String comparison (compareByChar, compareByWord)
  replace/        # Replacement (replace, replaceFirst, compile)
  html/           # HTML handling (stripTags, isHtml, highlight)
  url/            # URL parsing (isUrl, urlScheme, urlDomain, urlRoute, queryParams, slug)
  path/           # File path operations (baseFileName, pathToFile, toFileNameWithExtension, fileExtension)
  validation/     # Validation (isNumeric, isInt, isJSON, validEmail, validIP, validPhoneNumber, validDate)
  random/         # Random generation (randomLetter, randomChars, insertTypo)
  text/           # Text utilities (sentences, lines)
  counting/       # Character counting (lettersCount, digitsCount, punctuationCount, emailsCount, ipCount, urlCount)
  crypto/         # Cryptographic (hash, hashEquals)
  distance/       # Distance calculation (levenstain)
  StringObj.js    # Main class that composes all modules
  index.js        # Entry point

test/             # Test files mirroring src/ structure (529+ tests)

Key Design Principles

Composability: The main StringObj class inherits from StringCore and mixes in methods from 14 functional modules
Backward Compatibility: All methods work exactly as before; the public API remains unchanged
Testability: Each module has its own test file, enabling focused unit testing

Installation

npm install lex-module

Or with yarn:

yarn add lex-module

Bundle Formats

The library is distributed in multiple formats for maximum compatibility:

CommonJS (dist/lex-module.cjs.js) - For Node.js and older bundlers
ES Modules (dist/lex-module.mjs) - For modern bundlers (webpack, rollup, esbuild)
UMD (dist/lex-module.umd.js) - For direct browser usage via CDN

Minified versions are also available:

dist/lex-module.cjs.min.js (~12 KB)
dist/lex-module.mjs.min.js (~12 KB)
dist/lex-module.umd.min.js (~13 KB)

75% size reduction from the original unminified version!

CDN Usage

You can use the library directly in browsers via CDN:

<!-- Using unpkg -->
<script src="https://unpkg.com/lex-module@latest/dist/lex-module.umd.min.js"></script>

<!-- Using jsDelivr -->
<script src="https://cdn.jsdelivr.net/npm/lex-module@latest/dist/lex-module.umd.min.js"></script>

<script>
  const result = LexModule('hello world').uppercase().toString();
  console.log(result); // "HELLO WORLD"
</script>

Quick Start

const str = require('lex-module');

// Basic usage
const result = str('hello world')
  .uppercase()
  .replace('WORLD', 'Universe')
  .toString();

console.log(result); // "HELLO UNIVERSE"

// Method chaining
const text = str('  the quick brown fox  ')
  .trim()
  .capitalize()
  .words();
  // Returns: ['The', 'Quick', 'Brown', 'Fox']

API Reference

String Transformation

`uppercase()`

Converts the entire string to uppercase.

str('hello world').uppercase(); // "HELLO WORLD"

`lowercase()`

Converts the entire string to lowercase.

str('HELLO WORLD').lowercase(); // "hello world"

`ucFirst()`

Capitalizes only the first character of the string.

str('hello world').ucFirst(); // "Hello world"

`capitalize()`

Capitalizes the first character of each word.

str('hello world').capitalize(); // "Hello World"

`inverse()`

Reverses the string character by character.

str('hello').inverse(); // "olleh"

`duplicate()`

Duplicates the string content.

str('hello').duplicate(); // "hellohello"

Search and Match

`startsWith(needle)`

Checks if the string starts with the specified substring.

str('hello world').startsWith('hello'); // true
str('hello world').startsWith('world'); // false

`endsWith(needle)`

Checks if the string ends with the specified substring.

str('hello world').endsWith('world'); // true
str('hello world').endsWith('hello'); // false

`contains(needle)`

Checks if the string contains the specified substring.

str('hello world').contains('world'); // true
str('hello world').contains('foo'); // false

Replacement

`replace(from, to)`

Replaces all occurrences of a pattern or array of patterns. Supports both string and array parameters.

// Simple replacement
str('hello world').replace('world', 'universe'); // "hello universe"

// Array replacement
str('one two three').replace(['one', 'two'], ['1', '2']); // "1 2 three"

// Multiple replacements with arrays
str('The village was not so large')
  .replace(['village', 'not '], ['town', '']); // "The town was so large"

Throws: Error if from parameter is undefined/null or if to parameter is undefined.

`replaceFirst(from, to)`

Replaces only the first occurrence of a pattern or array of patterns.

str('one two one').replaceFirst('one', '1'); // "1 two one"

// Array replacement
str('The village was not so large. The village was small.')
  .replaceFirst(['village', 'not '], ['town', '']); // "The town was so large. The village was small."

Throws: Error if from parameter is undefined/null or if to parameter is undefined.

`compile(params, template)`

Replaces wildcards in the string with values from a params object.

// Default template {key}
str('Hello {name}, you are {age} years old')
  .compile({ name: 'John', age: 30 }); // "Hello John, you are 30 years old"

// Custom template
str('Hello #{name}').compile({ name: 'World' }, /#\{(\w*)\}/g); // "Hello World"

// Handles missing params gracefully
str('Hello {name}').compile({}); // "Hello {name}"

Parameters:

params (Object): Key-value pairs for replacement
template (RegExp, optional): Custom regex template (default: /\{(\w*)\}/g)

Throws: Error if params is null or not an object.

Text Analysis

`words()`

Extracts all words from the string as an array of lowercase strings.

str('Hello, World! This is a Test.').words();
// Returns: ['hello', 'world', 'this', 'is', 'a', 'test']

`wordsCount()`

Returns the number of words in the string.

str('Hello world').wordsCount(); // 2

`wordsFreq()`

Returns word frequency analysis as a two-element array: [words, frequencies].

str('hello world hello').wordsFreq();
// Returns: [['hello', 'world'], [2, 1]]

`sentences()`

Splits the string into an array of sentences.

str('First sentence. Second one! What about third?').sentences();
// Returns: ['First sentence.', 'Second one!', 'What about third?']

`lines()`

Splits the string into an array of lines using various line ending formats.

str('line1\nline2\nline3').lines(); // ['line1', 'line2', 'line3']
str('line1\r\nline2\r\nline3').lines(); // ['line1', 'line2', 'line3'] (Windows)
str('line1\rline2\rline3').lines(); // ['line1', 'line2', 'line3'] (old Mac)
str('line1\n\nline2').lines(); // ['line1', '', 'line2'] (empty lines preserved)

Note: This is a getter method that returns an array directly (not this for chaining). Supports Unix (\n), Windows (\r\n), and old Mac (\r) line endings.

`lettersCount()`

Counts the number of letter characters (a-z, A-Z) in the string.

str('hello world').lettersCount(); // 10
str('ABC-123-XYZ').lettersCount(); // 6

Note: Only ASCII letters are counted. International characters (accents, Cyrillic, etc.) are not included.

`digitsCount()`

Counts the number of digit characters (0-9) in the string.

str('hello123world').digitsCount(); // 3
str('ABC-123-XYZ').digitsCount(); // 3

Note: Only ASCII digits are counted.

`punctuationCount()`

Counts the number of ASCII punctuation characters in the string.

str('Hello, World!').punctuationCount(); // 2
str('arr[i]++;').punctuationCount(); // 5

Note: Counts ASCII punctuation: !"#$%&'()*+,-./:;<=>?@[]^_`{|}~

`emailsCount()`

Counts the number of email addresses in the string.

str('Contact us at [email protected]').emailsCount(); // 1
str('[email protected] and [email protected]').emailsCount(); // 2

`ipCount()`

Counts the number of IP addresses (IPv4 and IPv6) in the string.

str('Server: 192.168.1.1').ipCount(); // 1
str('IPv4: 192.168.1.1, IPv6: ::1').ipCount(); // 2

Note: Supports IPv4 (xxx.xxx.xxx.xxx) and IPv6 formats including mixed notation.

`urlCount()`

Counts the number of URLs (with http/https/www prefix) in the string.

str('Visit http://example.com').urlCount(); // 1
str('www.google.com and https://github.com').urlCount(); // 2

Note: Only counts URLs with scheme (http://, https://) or www prefix.

`length()`

Returns the length of the string.

str('hello').length(); // 5

`acronym()`

Creates an acronym by taking the first letter of each word.

str('Hello World').acronym(); // 'HW'
str('JavaScript Object Notation').acronym(); // 'JON'
str('Hyper Text Markup Language').acronym(); // 'HTML'
str('3D Studio Max').acronym(); // '3DSM' (numbers included)
str('C++ Programming').acronym(); // 'CP' (special chars skipped)

Note: This is a getter method that returns a string directly (not this for chaining). Only ASCII alphanumeric characters are supported; international characters are skipped. The previous typo acronim() is kept as a backward-compatible alias.