pragi-string/readme.md

A package to modify strings

# pragiString

🚀 A simple utility to transform text into different capitalization styles!

## 📦 Installation

Install using npm or yarn:

```bash
npm install pragi-string
```

## ✨ Features

- Transform text into various cases (title, sentence, camel, snake, kebab, etc.)
- ✨ Smart text truncation with customizable length and suffix
- 🔍 Intelligent whitespace trimming
- 🎯 Exclude specific words from case transformations
- 🛠️ Convenient method-based API (e.g., pragiString.titleCase())
- 📦 CLI tool for quick transformations
- 🔒 Full TypeScript support

## 🔥 Usage

### Importing the Package

**JavaScript**
```javascript
const pragiString = require("pragi-string");
```

**TypeScript**
```typescript
import { pragiString } from "pragi-string";
```

### 🛠 Text Transformations

```typescript
// Method-based API for better readability
pragiString.titleCase("hello world");  // Hello World
pragiString.camelCase("hello world");  // helloWorld
pragiString.snakeCase("hello world");  // hello_world
```

### ⚡ Smart Features

#### 1️⃣ Text Truncation
```typescript
// Truncate with custom length and suffix
pragiString.titleCase("this is a very long text", { 
  truncate: { length: 10, suffix: "..." } 
});
// Output: "This Is..." (truncates before case transformation)

// Custom suffix
pragiString.titleCase("this is a very long text", { 
  truncate: { length: 12, suffix: " [...]" } 
});
// Output: "This Is [...]"
```

#### 2️⃣ Intelligent Trimming
```typescript
// Automatically handles various whitespace scenarios
pragiString.titleCase("  hello   world  ", { trim: true });
// Output: "Hello World"

// Trim specific characters
pragiString.titleCase("***hello***world***", { 
  trim: { chars: "*" } 
});
// Output: "Hello World"
```

#### 3️⃣ Word Exclusions
```typescript
// Exclude specific words from case transformation
pragiString.titleCase("the quick brown fox", { 
  exclude: ["the", "of", "and"] 
});
// Output: "the Quick Brown Fox"

// Combine with other features
pragiString.titleCase("  the quick brown fox  ", { 
  exclude: ["the"],
  trim: true,
  truncate: { length: 15, suffix: "..." }
});
// Output: "the Quick Brown..."
```

#### 4️⃣ Number Conversions
```typescript
// Convert numbers to words
pragiString.toWords(42);  // "forty two"
pragiString.toWords(1234);  // "one thousand two hundred thirty four"

// Convert words to numbers
pragiString.toNumbers("forty two");  // 42
pragiString.toNumbers("one thousand two hundred thirty four");  // 1234

// Convert to ordinal numbers
pragiString.toOrdinal(1);  // "1st"
pragiString.toOrdinal(42);  // "42nd"

// Roman numeral conversions
pragiString.toRoman(42);  // "XLII"
pragiString.fromRoman("XLII");  // 42

// Humanize large numbers
pragiString.humanizeNumber(1234567);  // "1.2M"

// Time and duration formatting
pragiString.humanizeDuration(3665);  // "1 hour, 1 minute, 5 seconds"
pragiString.toDigitalTime(3665);  // "01:01:05"
```

## 🛠️ Options

### Trim Whitespace
```javascript
console.log(pragiString("  hello world  ", "titlecase", { trim: true }));
// Output: "Hello World"
```

### Exclude Words from Capitalization
```javascript
console.log(pragiString("hello world example", "titlecase", { excludeWords: ["world"] }));
// Output: Hello world Example
```

## 🚀 CLI Usage

You can use pragiString as a command-line tool after installing it globally:

```bash
npm install -g pragi-string
```

### Convert Text
```bash
pragi-string "hello world" uppercase
# Output: HELLO WORLD
```

### Trim Before Conversion
```bash
pragi-string "   hello world   " titlecase --trim
# Output: Hello World
```

### Exclude Specific Words
```bash
pragi-string "hello world example" titlecase --exclude world
# Output: Hello world Example
```

## 🛠 API Reference

### Methods

Each transformation is available as a direct method:
- `pragiString.titleCase(text: string, options?: PragiOptions)`
- `pragiString.sentenceCase(text: string, options?: PragiOptions)`
- `pragiString.camelCase(text: string, options?: PragiOptions)`
- `pragiString.snakeCase(text: string, options?: PragiOptions)`
- `pragiString.kebabCase(text: string, options?: PragiOptions)`
- `pragiString.upperCase(text: string, options?: PragiOptions)`
- `pragiString.lowerCase(text: string, options?: PragiOptions)`

### Options

```typescript
interface PragiOptions {
  trim?: boolean | { chars?: string };
  truncate?: {
    length: number;
    suffix?: string;
  };
  exclude?: string[];
}
```

- `trim`: Enable trimming (boolean) or specify characters to trim
- `truncate`: Configure text truncation with custom length and suffix
- `exclude`: Array of words to exclude from case transformation

## 📜 License

This package is licensed under the MIT License.

---

Visit my portfolio: [https://pragatheeswaran.vercel.app/](https://pragatheeswaran.vercel.app/)