artytext
Version:
A comprehensive utility library for text manipulation, slug generation, password generation, case conversion, and more. Works with both TypeScript and JavaScript.
384 lines (295 loc) • 10.1 kB
Markdown
# ArtyText
A comprehensive utility library for text manipulation, slug generation, password generation, case conversion, and more. Works seamlessly with both TypeScript and JavaScript.
## Features
- 🔐 **Password Generation**: Generate secure passwords with customizable options
- 🔗 **Slug Generation**: Create URL-friendly slugs with various options
- 🎲 **Random Generation**: Generate random numbers, strings, colors, and more
- 📝 **Text Case Conversion**: Convert text between various case formats
- ✂️ **Text Manipulation**: Truncate, reverse, count, and format text
- 🎨 **Text Formatting**: Format phone numbers, credit cards, currency, and more
## Installation
```bash
npm install artytext
```
## Quick Start
### JavaScript (CommonJS)
```javascript
const artytext = require('artytext');
// Generate a password
const password = artytext.generatePassword({ length: 16, includeSymbols: true });
// Create a slug
const slug = artytext.generateSlug('Hello World!');
// Convert case
const camelCase = artytext.toCamelCase('hello world');
```
### JavaScript (ES Modules)
```javascript
import artytext from 'artytext';
// Or import specific functions
import { generatePassword, generateSlug, toCamelCase } from 'artytext';
```
### TypeScript
```typescript
import artytext, { PasswordOptions, SlugOptions } from 'artytext';
const options: PasswordOptions = {
length: 16,
includeSymbols: true,
excludeSimilar: true
};
const password = artytext.generatePassword(options);
```
## API Reference
### Password Utilities
#### `generatePassword(options?: PasswordOptions): string`
Generate a secure random password.
```typescript
interface PasswordOptions {
length?: number; // Default: 12
includeUppercase?: boolean; // Default: true
includeLowercase?: boolean; // Default: true
includeNumbers?: boolean; // Default: true
includeSymbols?: boolean; // Default: false
excludeSimilar?: boolean; // Default: false
excludeAmbiguous?: boolean; // Default: false
}
```
```javascript
// Basic usage
const password = artytext.generatePassword();
// Custom options
const strongPassword = artytext.generatePassword({
length: 20,
includeSymbols: true,
excludeSimilar: true
});
```
#### `generateMemorablePassword(wordCount?: number, separator?: string, includeNumbers?: boolean): string`
Generate a memorable password using words.
```javascript
const memorable = artytext.generateMemorablePassword(4, '-', true);
// Output: "apple-banana-cherry-dragon123"
```
#### `checkPasswordStrength(password: string): PasswordStrength`
Check the strength of a password.
```javascript
const strength = artytext.checkPasswordStrength('MyPassword123!');
// Returns: { score: 85, strength: 'strong', feedback: [...] }
```
### Slug Utilities
#### `generateSlug(text: string, options?: SlugOptions): string`
Generate a URL-friendly slug.
```typescript
interface SlugOptions {
separator?: string; // Default: '-'
lowercase?: boolean; // Default: true
removeSpecialChars?: boolean; // Default: true
maxLength?: number; // Optional
}
```
```javascript
const slug = artytext.generateSlug('Hello World!');
// Output: "hello-world"
const customSlug = artytext.generateSlug('Hello World!', {
separator: '_',
maxLength: 10
});
// Output: "hello_worl"
```
#### `generateUniqueSlug(text: string, options?: SlugOptions): string`
Generate a unique slug with timestamp.
```javascript
const uniqueSlug = artytext.generateUniqueSlug('Hello World');
// Output: "hello-world-lm2n9x"
```
#### `generateRandomSlug(text: string, options?: SlugOptions, suffixLength?: number): string`
Generate a slug with random suffix.
```javascript
const randomSlug = artytext.generateRandomSlug('Hello World', {}, 8);
// Output: "hello-world-a1b2c3d4"
```
### Random Utilities
#### `randomInt(min?: number, max?: number): number`
Generate a random integer.
```javascript
const number = artytext.randomInt(1, 100);
```
#### `randomString(options?: RandomOptions): string`
Generate a random string.
```typescript
interface RandomOptions {
length?: number; // Default: 10
charset?: string; // Default: alphanumeric
}
```
```javascript
const randomStr = artytext.randomString({ length: 8 });
```
#### `randomUUID(): string`
Generate a random UUID (version 4).
```javascript
const uuid = artytext.randomUUID();
// Output: "550e8400-e29b-41d4-a716-446655440000"
```
#### `randomColor(includeHash?: boolean): string`
Generate a random hex color.
```javascript
const color = artytext.randomColor();
// Output: "#ff6b35"
```
### Case Conversion
#### `changeCase(text: string, options: TextCaseOptions): string`
Convert text to different case formats.
```typescript
type CaseType = 'lowercase' | 'uppercase' | 'camelCase' | 'kebab-case' |
'snake_case' | 'pascalCase' | 'titleCase' | 'sentenceCase';
interface TextCaseOptions {
type: CaseType;
preserveWords?: boolean; // Default: false
}
```
```javascript
const text = 'Hello World';
artytext.changeCase(text, { type: 'camelCase' }); // "helloWorld"
artytext.changeCase(text, { type: 'kebab-case' }); // "hello-world"
artytext.changeCase(text, { type: 'snake_case' }); // "hello_world"
artytext.changeCase(text, { type: 'pascalCase' }); // "HelloWorld"
artytext.changeCase(text, { type: 'titleCase' }); // "Hello World"
```
#### Individual Case Functions
```javascript
artytext.toCamelCase('hello world'); // "helloWorld"
artytext.toKebabCase('hello world'); // "hello-world"
artytext.toSnakeCase('hello world'); // "hello_world"
artytext.toPascalCase('hello world'); // "HelloWorld"
artytext.toTitleCase('hello world'); // "Hello World"
artytext.toSentenceCase('hello world.'); // "Hello world."
```
### Text Utilities
#### `truncate(text: string, options: TruncateOptions): string`
Truncate text to a specified length.
```typescript
interface TruncateOptions {
length: number;
suffix?: string; // Default: '...'
preserveWords?: boolean; // Default: false
separator?: string; // Default: ' '
}
```
```javascript
const longText = 'This is a very long text that needs to be truncated';
const truncated = artytext.truncate(longText, { length: 20 });
// Output: "This is a very long..."
const wordPreserved = artytext.truncate(longText, {
length: 20,
preserveWords: true
});
// Output: "This is a very..."
```
#### `countWords(text: string): number`
Count words in text.
```javascript
const wordCount = artytext.countWords('Hello world!');
// Output: 2
```
#### `countCharacters(text: string, includeSpaces?: boolean): number`
Count characters in text.
```javascript
const charCount = artytext.countCharacters('Hello world!', false);
// Output: 10 (excluding spaces)
```
#### `format(text: string, options: FormatOptions): string`
Format text according to common patterns.
```typescript
interface FormatOptions {
type: 'phone' | 'credit-card' | 'ssn' | 'zip' | 'currency';
format?: string;
locale?: string;
}
```
```javascript
// Phone number formatting
artytext.format('1234567890', { type: 'phone' });
// Output: "(123) 456-7890"
// Credit card formatting
artytext.format('1234567890123456', { type: 'credit-card' });
// Output: "1234 5678 9012 3456"
// Currency formatting
artytext.format('1234.56', { type: 'currency', locale: 'en-US' });
// Output: "$1,234.56"
```
#### `mask(text: string, options: MaskOptions): string`
Mask text according to a pattern.
```typescript
interface MaskOptions {
pattern: string; // Use '#' for digits
placeholder?: string; // Default: '*'
reverse?: boolean; // Default: false
}
```
```javascript
const masked = artytext.mask('1234567890', { pattern: '(###) ###-####' });
// Output: "(123) 456-7890"
```
## Examples
### Complete Example
```javascript
import artytext from 'artytext';
// Generate a secure password
const password = artytext.generatePassword({
length: 16,
includeSymbols: true,
excludeSimilar: true
});
// Create a blog post slug
const title = 'My Amazing Blog Post!';
const slug = artytext.generateSlug(title, { maxLength: 50 });
// Convert user input to camelCase
const userInput = 'user first name';
const fieldName = artytext.toCamelCase(userInput);
// Format a phone number
const phone = artytext.format('1234567890', { type: 'phone' });
// Generate a random color for UI
const color = artytext.randomColor();
console.log({
password, // "Kj#mN9$pL2@vX7qR"
slug, // "my-amazing-blog-post"
fieldName, // "userFirstName"
phone, // "(123) 456-7890"
color // "#ff6b35"
});
```
## TypeScript Support
ArtyText is written in TypeScript and provides full type definitions. All functions are properly typed with interfaces for options and return values.
```typescript
import artytext, {
PasswordOptions,
SlugOptions,
CaseType,
TextCaseOptions
} from 'artytext';
const passwordOptions: PasswordOptions = {
length: 20,
includeSymbols: true
};
const caseOptions: TextCaseOptions = {
type: 'camelCase' as CaseType,
preserveWords: true
};
```
## Contributing
1. Fork the repository
2. Create your feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add some amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request
## License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
## Changelog
### v1.0.0
- Initial release
- Password generation utilities
- Slug generation utilities
- Random generation utilities
- Text case conversion utilities
- Text manipulation utilities
- Full TypeScript support