@asaidimu/utils-strings

A comprehensive utility library providing static methods for robust string manipulation, validation, formatting, and UI-specific transformations.

Table of Contents

• Features
• Technology Stack
• Installation
• Quick Start
• Usage
  • Case Conversion
  • Validation & Checks
  • Manipulation
  • UI & Localization Formatting
  • Hashing
• Configuration
• Development
• Testing
• Contributing
• License

@asaidimu/utils-strings is a TypeScript-first utility library designed to be a foundational toolkit for applications requiring robust string handling, from data processing to user interface rendering. It centralizes common string operations, ensuring consistency and reducing boilerplate across projects.

This library provides a single, well-tested, and comprehensive String class with static methods to address a wide array of common string-related tasks. By offering a consistent API for these operations, it aims to improve code quality, enhance developer efficiency, and ensure predictable string behavior across applications.

Features

@asaidimu/utils-strings offers a rich set of features, including:

• Case Conversion: Convert strings to uppercase, lowercase, capitalize, camelCase, kebab-case, snake_case, PascalCase, sentence case, and title case.
• Validation & Checks: Check for null, undefined, empty, or whitespace-only strings; verify if a string starts with, ends with, or contains a substring; and validate if a string consists purely of numeric or alphabetic characters.
• Manipulation: Trim whitespace, truncate strings with an ellipsis, reverse strings, replace all occurrences of a substring, remove diacritical marks (accents), and slugify strings for URL-friendly formats.
• UI & Localization Formatting: Handle basic pluralization logic, escape HTML special characters to prevent XSS, and format numbers as currency for localized display.
• Hashing: Generate short, deterministic hashes for strings.

Technology Stack

This library is built with:

• TypeScript: Ensures type safety and improves developer experience.
• JavaScript: The compiled output is fully compatible with JavaScript environments.

Installation

You can install @asaidimu/utils-strings using npm or yarn:

npm install @asaidimu/utils-strings
# or
yarn add @asaidimu/utils-strings

Quick Start

Once installed, you can import and use the String class directly:

import { String } from "@asaidimu/utils-strings";

// Basic Usage
console.log(String.capitalize("hello world")); // Output: "Hello world"
console.log(String.kebabCase("HelloWorld")); // Output: "hello-world"
console.log(String.isEmpty("")); // Output: true
console.log(String.formatCurrency(123.45, "en-US", "USD")); // Output: "$123.45"

// More examples
const text = "  Crème Brûlée Dessert  ";
console.log(String.slugify(text)); // Output: "creme-brulee-dessert"
console.log(String.escapeHtml(`<script>alert('xss')</script>`)); // Output: "&lt;script&gt;alert(&#39;xss&#39;)&lt;/script&gt;"

Usage

Here are detailed examples of the various utility methods available in String.

Case Conversion

import { String } from "@asaidimu/utils-strings";

String.uppercase("hello"); // Returns "HELLO"
String.lowercase("HELLO"); // Returns "hello"
String.capitalize("hello world"); // Returns "Hello world"
String.camelCase("foo bar baz"); // Returns "fooBarBaz"
String.kebabCase("fooBarBaz"); // Returns "foo-bar-baz"
String.snakeCase("fooBarBaz"); // Returns "foo_bar_baz"
String.pascalCase("hello world"); // Returns "HelloWorld"
String.toSentenceCase("hello WORLD"); // Returns "Hello world"
String.toTitleCase("the quick brown fox"); // Returns "The Quick Brown Fox"

Validation & Checks

import { String } from "@asaidimu/utils-strings";

String.isEmpty(null); // Returns true
String.isWhitespace("   "); // Returns true
String.startsWith("hello world", "hello"); // Returns true
String.endsWith("hello world", "world"); // Returns true
String.contains("hello world", "lo w"); // Returns true
String.isNumeric("123"); // Returns true
String.isAlpha("abc"); // Returns true

Manipulation

import { String } from "@asaidimu/utils-strings";

String.trim("  hello  "); // Returns "hello"
String.truncate("Long text example", 10); // Returns "Long text..."
String.reverse("hello"); // Returns "olleh"
String.replaceAll("banana", "a", "o"); // Returns "bonono"
String.removeAccents("crème brûlée"); // Returns "creme brulee"
String.slugify("Hello World! This is a test."); // Returns "hello-world-this-is-a-test"

UI & Localization Formatting

import { String } from "@asaidimu/utils-strings";

String.pluralize(1, "item"); // Returns "item"
String.pluralize(2, "item"); // Returns "items"
String.escapeHtml(`<div>content</div>`); // Returns "&lt;div&gt;content&lt;/div&gt;"
String.formatCurrency(1234.5, "de-DE", "EUR"); // Returns "1.234,50 €"

Hashing

import { String } from "@asaidimu/utils-strings";

String.hash("my-secret-string"); // Returns a short, deterministic hash like "03a7jk"
String.hash("another-string", 8); // Returns a hash of length 8

Configuration

This library currently does not require any external configuration.

Development

To set up the project for local development, follow these steps:

1. Clone the repository:

   git clone https://github.com/asaidimu/erp-utils.git
   cd erp-utils/src/strings

2. Install dependencies:

   bun install
   # or
   yarn install

3. Build the project (if needed): (No specific build script provided, typically handled by consumer or pre-publish)

Testing

Tests are run using Vitest.

• Run all tests:

  bun test

• Run tests in watch mode:

  bun run test:watch

• Run tests in a browser environment:

  bun run test:browser

Contributing

Contributions are welcome! Please refer to the main repository for guidelines on how to contribute:

https://github.com/asaidimu/erp-utils

License

This project is licensed under the MIT License - see the LICENSE file for details.