npm package: @neabyte/unicode-gen
Description: A lightweight TypeScript library for generating random Unicode emojis with embedded data for instant offline usage
Author: NeaByteLab
Latest version: 1.0.1

# Unicode-Gen 🎲

A lightweight TypeScript library for generating random Unicode emojis. Features embedded Unicode data for instant offline usage with 3,781+ emojis across 100 categories.

[![NPM Version](https://img.shields.io/npm/v/@neabyte/unicode-gen.svg)](https://www.npmjs.com/package/@neabyte/unicode-gen)
[![NPM Downloads](https://img.shields.io/npm/dm/@neabyte/unicode-gen.svg)](https://www.npmjs.com/package/@neabyte/unicode-gen)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![TypeScript](https://img.shields.io/badge/TypeScript-5.8.3-blue.svg)](https://www.typescriptlang.org/)
[![Node.js](https://img.shields.io/badge/Node.js-%3E%3D18.0.0-green.svg)](https://nodejs.org/)

## ✨ Features

- 🚀 **Instant startup** - No network requests, embedded data
- 📦 **Offline ready** - Works without internet connection
- 🎲 **3,781+ emojis** - Latest Unicode emoji data
- 📂 **98 categories** - Organized by emoji type
- ⚡ **Lightweight** - Minified browser bundle (~176KB, 26KB gzipped)
- 🔧 **TypeScript** - Full type safety and IntelliSense
- 🌐 **Universal** - Works in Node.js, browser, and standalone
- 🎯 **Zero dependencies** - No external files or network requests

## 📦 Installation

### Node.js

```bash
npm install @neabyte/unicode-gen
```

### Browser

```html
<!-- Via CDN -->
<script src="https://unpkg.com/@neabyte/unicode-gen@latest/dist/unicode-gen.min.js"></script>

<!-- Or download and include locally -->
<script src="path/to/unicode-gen.min.js"></script>

<!-- ES Modules -->
<script type="module">
  import generator from 'https://unpkg.com/@neabyte/unicode-gen@latest/dist/unicode-gen.esm.js'
</script>
```

## 🚀 Quick Start

### Node.js

```javascript
import generator from '@neabyte/unicode-gen'

// Get random emoji
generator.random() // '😀'
```

### Browser

```javascript
// Access the global UnicodeGen object
const generator = UnicodeGen.default

// Get random emoji
generator.random() // '😀'
```

### Basic Examples

```javascript
import generator from '@neabyte/unicode-gen'

// Get random emoji (default)
generator.random() // '😀'

// Get random emoji code
generator.random({ type: 'code' }) // '1F600'

// Get multiple random emojis
generator.random({ count: 5 }) // ['😀', '😃', '😄', '😁', '😆']

// Get from specific category
generator.random({ category: 'face-smiling' }) // '😀'

// Get full emoji object
generator.random({ type: 'both' }) // { code: '1F600', emoji: '😀' }
```

## 🔧 API Reference

### `generator.random(options?: RandomOptions)`

Generate random emojis with flexible options.

**Options:**

- `count?: number` - Number of emojis to return (default: 1)
- `category?: string` - Specific category to choose from
- `type?: 'code' | 'emoji' | 'both'` - Return format (default: 'emoji')

**Type Examples:**

- `type: 'emoji'` - Returns emoji characters (default)
- `type: 'code'` - Returns Unicode codes
- `type: 'both'` - Returns full objects with code and emoji

**Returns:**

- Single emoji: `string` or `EmojiData`
- Multiple emojis: `string[]` or `EmojiData[]`

### `generator.getCategories()`

Returns array of available category names.

### `generator.getEmojisByCategory(category: string)`

Returns all emojis in the specified category.

## 🚀 Advanced Usage

### Standalone Usage

```javascript
// Create your own instance
import { UnicodeGenerator } from '@neabyte/unicode-gen'

const generator = new UnicodeGenerator()
await generator.loadData()

// Use like normal
generator.random() // '😀'
```

### Category Management

```javascript
// Get all available categories
const categories = generator.getCategories()
console.log(categories) // ['face-smiling', 'heart', 'animal-mammal', ...]

// Get all emojis from a category
const hearts = generator.getEmojisByCategory('heart')
console.log(hearts.length) // 25
console.log(hearts.map(e => e.emoji).join(' ')) // '💌 💘 💝 💖 💗 ...'
```

### Validation Examples

```javascript
// Validate category exists
const categories = generator.getCategories()
if (categories.includes('face-smiling')) {
  const emoji = generator.random({ category: 'face-smiling' })
}

// Handle invalid options
try {
  generator.random({ count: 0 }) // Throws error
} catch (error) {
  console.log('Invalid count:', error.message)
}
```

## 📂 Available Categories

Your library includes **98 emoji categories**:

### 😊 **Faces & Emotions**

- `face-smiling`, `face-affection`, `face-tongue`, `face-hand`
- `face-neutral-skeptical`, `face-sleepy`, `face-unwell`
- `face-hat`, `face-glasses`, `face-concerned`, `face-negative`
- `face-costume`, `cat-face`, `monkey-face`, `heart`, `emotion`

### 🐾 **Animals & Nature**

- `animal-mammal`, `animal-bird`, `animal-amphibian`
- `animal-reptile`, `animal-marine`, `animal-bug`
- `plant-flower`, `plant-other`

### 🍕 **Food & Drink**

- `food-fruit`, `food-vegetable`, `food-prepared`
- `food-asian`, `food-sweet`, `drink`, `dishware`

### 🏠 **Places & Transport**

- `place-map`, `place-geographic`, `place-building`
- `place-religious`, `place-other`
- `transport-ground`, `transport-water`, `transport-air`

### 👤 **People & Activities**

- `person`, `person-gesture`, `person-role`, `person-fantasy`
- `person-activity`, `person-sport`, `person-resting`
- `family`, `person-symbol`

### 🎮 **Objects & Symbols**

- `clothing`, `sound`, `music`, `musical-instrument`
- `phone`, `computer`, `light-video`, `book-paper`
- `money`, `mail`, `writing`, `office`, `lock`, `tool`
- `science`, `medical`, `household`, `other-object`

### 🚦 **Signs & Symbols**

- `transport-sign`, `warning`, `arrow`, `religion`, `zodiac`
- `av-symbol`, `gender`, `math`, `punctuation`, `currency`
- `other-symbol`, `keycap`, `alphanum`, `geometric`

### 🏁 **Flags**

- `flag`, `country-flag`, `subdivision-flag`

## 📚 Documentation

For complete API reference and examples, see the [full documentation](docs/).

## 🤝 Contributing

1. Fork the repository
2. Create your feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'feat: add amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request

## 📄 License

MIT © NeaByteLab