# emoji-string

**Repository Path**: nodets/emoji-string

## Basic Information

- **Project Name**: emoji-string
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-09-23
- **Last Updated**: 2025-09-23

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# EmojiString Library

A high-performance TypeScript library for handling mixed emoji and plain text strings. Designed for modern applications that require efficient processing of Unicode emojis and regular characters.

## Features

- **High Performance**: Optimized for both short and long strings using caching, lazy evaluation, and regex optimizations.
- **Unicode Emoji Support**: Comprehensive support for all Unicode emojis, including combined emojis (e.g., skin tone modifiers, gendered emojis).
- **Cache Mechanism**: Built-in caching for frequently accessed properties like unit arrays, length, and emoji counts.
- **Lazy Evaluation**: Computes values only when necessary, reducing redundant operations.
- **Type Safety**: Fully typed with TypeScript, ensuring robustness and developer-friendly usage.
- **Rich API**: Provides methods for slicing, inserting, replacing, filtering, mapping, and more.
- **Performance Monitoring**: Includes built-in performance statistics to track cache hits, misses, and regex executions.

## Installation

```bash
npm install emoji-string
```

## Usage

### Supported Environments

The library supports multiple environments:
- **ES Modules (ESM)**: Use `import` syntax in modern JavaScript/TypeScript projects.
- **CommonJS**: Use `require` syntax in Node.js projects.
- **Browser**: Directly include the library via a `<script>` tag.

---

### 1. Using ESM (Recommended)

```javascript
import { emojiString } from 'emoji-string';

const str = emojiString("Hello 😊🌍!");
console.log(str.length); // Visual length: 9
console.log(str.countEmojis()); // Emoji count: 2
```

---

### 2. Using CommonJS (`require`)

```javascript
const { emojiString } = require('emoji-string');

const str = emojiString("Hello 😊🌍!");
console.log(str.length); // Visual length: 9
console.log(str.countEmojis()); // Emoji count: 2
```

---

### 3. In Browser

Include the library via a CDN (e.g., [jsDelivr](https://www.jsdelivr.com/)):

```html
<script src="https://cdn.jsdelivr.net/npm/emoji-string/dist/emoji-string.min.js"></script>
<script>
  const str = EmojiString.emojiString("Hello 😊🌍!");
  console.log(str.length); // Visual length: 9
  console.log(str.countEmojis()); // Emoji count: 2
</script>
```

> **Note**: When using the browser version, the library is exposed globally as `EmojiString`.

---

## API Reference

### Constructor
```typescript
new EmojiString(input: string | EmojiString)
```
Creates a new `EmojiString` instance. Automatically normalizes the input.

### Properties
- `value`: The original string.
- `length`: The visual length of the string (cached and optimized).
- `isEmpty`: Checks if the string is empty.

### Methods
#### String Manipulation
- [toArray(): string[]]: Splits the string into an array of units (emojis or single characters).
- `slice(start: number, end?: number): EmojiString`: Extracts a substring.
- `insert(index: number, content: string | EmojiString): EmojiString`: Inserts content at a specific index.
- `replaceAt(index: number, newContent: string | EmojiString): EmojiString`: Replaces a unit at a specific index.
- `push(content: string | EmojiString): EmojiString`: Appends content to the end.
- `unshift(content: string | EmojiString): EmojiString`: Prepends content to the start.
- `remove(index: number): EmojiString`: Removes a unit at a specific index.
- `reverse(): EmojiString`: Reverses the string.

#### Querying
- `charAt(index: number): string | undefined`: Gets the unit at a specific index.
- `includes(content: string | EmojiString): boolean`: Checks if the string contains specific content.
- `indexOf(content: string | EmojiString): number`: Finds the first occurrence of specific content.
- `startsWith(content: string | EmojiString): boolean`: Checks if the string starts with specific content.
- `endsWith(content: string | EmojiString): boolean`: Checks if the string ends with specific content.

#### Statistics
- `countEmojis(): number`: Counts the number of emojis in the string.
- `countRegularChars(): number`: Counts the number of non-emoji characters.

#### Iteration
- `forEach(callback: (unit: string, index: number) => void): void`: Iterates over each unit.
- `map<T>(callback: (unit: string, index: number) => T): T[]`: Maps each unit to a new value.
- `filter(callback: (unit: string, index: number) => boolean): EmojiString`: Filters units based on a condition.

#### Debugging
- `getCacheDebugInfo(): object`: Retrieves cache-related debug information.
- `static getPerformanceStats(): object`: Retrieves performance statistics.

### Static Methods
- `EmojiString.repeat(str: string | EmojiString, count: number): EmojiString`: Creates a repeated string.
- `EmojiString.fromEncodedArray(encodedArray: Array<{ type: 'emoji' | 'char', value: string }>): EmojiString`: Creates an `EmojiString` from an encoded array.

## Performance Optimization

1. **Caching**:
   - Caches frequently accessed properties like unit arrays, length, and emoji counts.
   - Uses a hash-based validation mechanism to ensure cache consistency.

2. **Regex Optimization**:
   - Employs highly optimized regex patterns for emoji detection and string splitting.
   - Minimizes regex executions through lazy evaluation.

3. **Threshold-Based Strategies**:
   - Uses different strategies for short and long strings to balance performance and memory usage.

4. **Lazy Evaluation**:
   - Computes values like length and unit arrays only when needed, avoiding unnecessary calculations.

## Performance Monitoring

You can monitor performance using the built-in stats:

```typescript
console.log(EmojiString.getPerformanceStats());
// Output example:
// {
//   cacheHits: 15,
//   cacheMisses: 3,
//   regexExecutions: 8
// }
```

Reset stats with:
```typescript
EmojiString.resetPerformanceStats();
```

## Contributing

Contributions are welcome! Please follow these steps:
1. Fork the repository.
2. Create a new branch (`git checkout -b feature/your-feature`).
3. Commit your changes (`git commit -m 'Add some feature'`).
4. Push to the branch (`git push origin feature/your-feature`).
5. Open a pull request.

## License

This project is licensed under the MIT License.