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

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)

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)

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):

<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

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:

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

Reset stats with:

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.