npm package: @shahid19/stringjs
Description: Lightweight and type-safe string utility library for JavaScript and TypeScript with 80+ functions.
Author: Shahid Ullah Safi
Latest version: 1.0.0

# @shahid19/stringjs

A lightweight, flexible, and modern **string manipulation utility library** for JavaScript and TypeScript.
Inspired by libraries like **Lodash** and **Validator.js** — but focused only on **string operations**.

---

## ✨ Features

- 📦 **Modular**: Import only what you need
- ⚡ **Lightweight**: No external dependencies
- 🛠️ **Comprehensive**: Includes casing, trimming, validation, word utilities, and more
- 🔒 **TypeScript support** out of the box
- 📦 **ESM & CJS**: Supports both ESM and CommonJS modules
- 🔢 **80+ functions** More than 80 functions are available

---

## 📦 Installation

```bash
npm install @shahid19/stringjs
# or
yarn add @shahid19/stringjs
```

---

## 🚀 Usage

### Option 1: Named Imports (Tree-shaking friendly)

```ts
import { capitalize, snakeCase, isEmail } from "@shahid19/stringjs";

console.log(capitalize("hello world")); // "Hello world"
console.log(snakeCase("Hello World")); // "hello_world"
console.log(isEmail("foo@bar.com")); // true
```

### Option 2: Namespaced Import

```ts
import * as str from "@shahid19/stringjs";

console.log(str.capitalize("hello world")); // "Hello world"
console.log(str.snakeCase("Hello World")); // "hello_world"
console.log(str.isEmail("foo@bar.com")); // true
```

## Option 3: CommonJS (require)

```ts
// Named import style
const { capitalize } = require("@shahid19/stringjs");
console.log(capitalize("hello world")); // "Hello world"

// Namespaced style
const str = require("@shahid19/stringjs");
console.log(str.snakeCase("Hello World")); // "hello_world"
```

---

## 📂 Categories & Functions

### 🔤 Case Utilities

| Function          | Description                                           |
| ----------------- | ----------------------------------------------------- |
| `capitalize`      | Capitalize the first letter of a string.              |
| `capitalizeWords` | Capitalize the first letter of every word.            |
| `upperCase`       | Convert string to uppercase.                          |
| `lowerCase`       | Convert string to lowercase.                          |
| `camelCase`       | Convert string to camelCase.                          |
| `pascalCase`      | Convert string to PascalCase.                         |
| `kebabCase`       | Convert string to kebab-case.                         |
| `snakeCase`       | Convert string to snake_case.                         |
| `titleCase`       | Convert string to Title Case.                         |
| `swapCase`        | Swap uppercase letters with lowercase and vice versa. |

---

### ✂️ Trim & Modify

| Function          | Description                                                                                    |
| ----------------- | ---------------------------------------------------------------------------------------------- |
| `trim`            | Remove whitespace from both ends.                                                              |
| `trimLeft`        | Remove whitespace from start.                                                                  |
| `trimRight`       | Remove whitespace from end.                                                                    |
| `padStart`        | Pad string at start.                                                                           |
| `padEnd`          | Pad string at end.                                                                             |
| `padCenter`       | Centers a string within a given total length by padding both sides with a specified character. |
| `repeat`          | Repeat a string n times.                                                                       |
| `truncate`        | Shorten string with ellipsis.                                                                  |
| `contains`        | Check if a string contains a substring.                                                        |
| `startsWith`      | Check if string starts with given prefix.                                                      |
| `endsWith`        | Check if string ends with given suffix.                                                        |
| `countSubstring`  | Counts the occurrences of a substring within a string.                                         |
| `countCharacters` | Counts the number of characters in a string.                                                   |
| `indexOf`         | Return index of first occurrence.                                                              |
| `lastIndexOf`     | Return index of last occurrence.                                                               |
| `replace`         | Replaces the first occurrence of a substring with another string.                              |
| `replaceAll`      | Replace all occurrences of a substring.                                                        |
| `remove`          | Remove all occurrences of a substring.                                                         |
| `slugify`         | Convert string to a URL-friendly slug.                                                         |
| `strictSlugify`   | Generates a strict, ASCII-only slug by aggressively removing non-URL-safe characters.          |
| `isValidSlug`     | Validates if a string is a valid slug format.                                                  |
| `uniqueSlug`      | Generates a unique slug by appending a counter if the slug already exists.                     |
| `escapeHTML`      | Escape HTML special characters.                                                                |
| `unescapeHTML`    | Unescape HTML entities back to characters.                                                     |
| `stripTags`       | Remove all HTML tags from string.                                                              |
| `insert`          | Inserts a substring at a specified position in a string.                                       |
| `between`         | Extracts a substring between two delimiters.                                                   |

---

### ✅ Validation

| Function          | Description                                     |
| ----------------- | ----------------------------------------------- |
| `isEmpty`         | Check if string is empty.                       |
| `isNotEmpty`      | Check if string is not empty.                   |
| `isAlpha`         | Only letters allowed.                           |
| `isNumeric`       | Only numbers allowed.                           |
| `isAlphaNumeric`  | Letters and numbers allowed.                    |
| `isUpperCase`     | Check if string is uppercase.                   |
| `isLowerCase`     | Check if string is lowercase.                   |
| `isEmail`         | Validate email address.                         |
| `isUrl`           | Validate URL.                                   |
| `isUUID`          | Validate UUID (v1–v5).                          |
| `isJSON`          | Validate JSON string.                           |
| `isHex`           | Validate hexadecimal characters.                |
| `isCreditCard`    | Validate credit card number (Luhn algorithm).   |
| `isIP`            | Validate IPv4 / IPv6 address.                   |
| `isPhoneNumber`   | Validate phone number (basic format).           |
| `isDate`          | Validate date (YYYY-MM-DD).                     |
| `isTime`          | Validate time (HH\:MM\:SS).                     |
| `isWhitespace`    | Check if string has only whitespace.            |
| `matchesPattern`  | Match string against a regex.                   |
| `hasMinLength`    | Check if string meets minimum length.           |
| `hasMaxLength`    | Check if string does not exceed maximum length. |
| `isLengthBetween` | Check if string length is within range.         |

---

### 📝 Word Utilities

| Function               | Description                                             |
| ---------------------- | ------------------------------------------------------- |
| `words`                | Split string into words.                                |
| `countWords`           | Count words in string.                                  |
| `getMostFrequentWords` | Return most frequent words with counts.                 |
| `getRandomWord`        | Gets a random word from a string.                       |
| `getWordStats`         | Get word statistics.                                    |
| `firstWord`            | Return first word.                                      |
| `lastWord`             | Return last word.                                       |
| `truncateWords`        | Truncate string to n words.                             |
| `extractWords`         | Extracts words that match a specific pattern or string. |
| `longestWord`          | Finds the first longest word in a string.               |
| `shortestWord`         | Find the first shortest word in a string.               |
| `wordsLongerThan`      | Returns words that are longer than a specified length.  |
| `wordsShorterThan`     | Returns words that are shorter than a specified length. |
| `wordAt`               | Returns the word at a specific position in the string.  |
| `removeWords`          | Remove specific words.                                  |
| `containsWord`         | Check if word exists in string.                         |

---

### 🔧 Miscellaneous

| Function        | Description                              |
| --------------- | ---------------------------------------- |
| `randomString`  | Generate random alphanumeric string.     |
| `hashCode`      | Compute 32-bit integer hash of string.   |
| `toCharArray`   | Convert string into array of characters. |
| `removeAccents` | Remove accents/diacritics.               |
| `toAscii`       | Convert string to ASCII-safe characters. |
| `fromCharCode`  | Convert Unicode code to character.       |
| `toSlug`        | Convert string to slug.                  |
| `reverse`       | Reverse a string.                        |

## Maintainers

- **Shahid Ullah Safi** (author) - [@ShahidKhanDev](https://github.com/ShahidKhanDev)
- **Sodais Alokozay** - [@sodaisdev](https://github.com/sodaisdev)

---

## 📖 Documentation

All functions are fully documented with **JSDoc**.
TypeScript users get **type hints and autocomplete** automatically.

---

## 🛠️ Contributing

Currently, contributions are not open.\
This will change in the future — stay tuned!

---

## 📜 License

[MIT](./LICENSE) © 2025 Shahid Ullah Safi