somali-names/README.md

Random Somali first names (male/female) with optional meanings. Library + CLI.

# 🇸🇴 Somali Names Generator

> **Magacyada Soomaaliyeed** - A beautiful collection of traditional Somali names with meanings

[![npm version](https://img.shields.io/npm/v/somali-names.svg)](https://www.npmjs.com/package/somali-names)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Tests](https://img.shields.io/badge/tests-passing-brightgreen.svg)](./TESTING.md)

Generate authentic Somali first names for your projects, stories, or applications. This library includes both male and female names with their beautiful meanings, honoring Somali culture and heritage.

## ✨ Features

- 🎲 **Random name generation** - Get single or multiple names
- 👥 **Gender-specific** - Filter by male, female, or any gender
- 📖 **Meaningful names** - Optional inclusion of name meanings
- 🎯 **Deterministic** - Use seeds for reproducible results
- 🔍 **Search functionality** - Find names by prefix
- 💻 **CLI & Library** - Use programmatically or from command line
- 🌍 **Cultural authenticity** - Curated collection of traditional Somali names

## 📊 Current Collection

- **Male names**: ~30 traditional names with meanings
- **Female names**: ~30 traditional names with meanings
- **Total**: 60+ authentic Somali names

*Help us grow this collection! See [Contributing](#-contributing) below.*

## 🚀 Quick Start

### Installation

```bash
npm install somali-names
```

### Library Usage

```javascript
const { randomName, randomMany, findByPrefix } = require('somali-names');

// Get a random name
const name = randomName();
console.log(name); // "Amina"

// Get a name with meaning
const nameWithMeaning = randomName({ withMeaning: true });
console.log(nameWithMeaning); // { name: "Amina", meaning: "Trustworthy" }

// Get multiple unique female names
const femaleNames = randomMany({ 
  count: 5, 
  gender: 'female', 
  unique: true 
});
console.log(femaleNames); // ["Ayan", "Hodan", "Faduma", "Sahra", "Maryan"]

// Find names starting with 'A'
const aNames = findByPrefix('A');
console.log(aNames); // ["Ahmed", "Ali", "Amina", "Ayan", ...]
```

### CLI Usage

```bash
# Install globally for CLI access
npm install -g somali-names

# Generate one random name
somaname one
# Output: Yusuf

# Generate female name with meaning
somaname one --female --meaning
# Output: Ayan — Good fortune; time

# Generate 5 unique male names
somaname many 5 --male --unique
# Output: Ahmed, Hassan, Omar, Ali, Ismail

# Find names starting with 'Ha'
somaname find Ha --female
# Output: Halima, Hawa

# Get help
somaname help
```

## 📚 API Reference

### `randomName(options)`

Generate a single random name.

**Options:**
- `gender` (string): `'male'`, `'female'`, or `'any'` (default: `'any'`)
- `withMeaning` (boolean): Include name meaning (default: `false`)
- `seed` (number): Seed for deterministic results (optional)

**Returns:** String name or object with `{name, meaning}` if `withMeaning: true`

### `randomMany(options)`

Generate multiple random names.

**Options:**
- `count` (number): Number of names to generate (default: `5`)
- `gender` (string): `'male'`, `'female'`, or `'any'` (default: `'any'`)
- `unique` (boolean): Ensure all names are unique (default: `false`)
- `withMeaning` (boolean): Include name meanings (default: `false`)
- `seed` (number): Seed for deterministic results (optional)

**Returns:** Array of names (strings or objects)

### `findByPrefix(prefix, options)`

Find names starting with a given prefix.

**Parameters:**
- `prefix` (string): The prefix to search for
- `options.gender` (string): Filter by gender (optional)

**Returns:** Array of matching name strings

## 🎨 Examples

### Deterministic Generation
```javascript
// Same seed = same results
const name1 = randomName({ seed: 12345 });
const name2 = randomName({ seed: 12345 });
console.log(name1 === name2); // true
```

### Story Character Generator
```javascript
const characters = randomMany({ 
  count: 3, 
  withMeaning: true, 
  unique: true 
});

characters.forEach(char => {
  console.log(`${char.name} (${char.meaning})`);
});
// Output:
// Ahmed (Highly praised)
// Ayan (Good fortune; time)
// Hassan (Good; handsome)
```

### Name Validation
```javascript
const userInput = "Ami";
const suggestions = findByPrefix(userInput);
if (suggestions.length > 0) {
  console.log(`Did you mean: ${suggestions.join(', ')}?`);
}
```

## 🤝 Contributing

We warmly welcome contributions to expand our collection of Somali names! This project aims to preserve and celebrate Somali naming traditions.

### 🎯 How You Can Help

1. **Add more names** - Expand our male/female name collections
2. **Improve meanings** - Enhance or correct existing name meanings
3. **Cultural context** - Add regional variations or historical context
4. **Documentation** - Improve examples, translations, or guides
5. **Code improvements** - Enhance functionality or performance

### 📝 Adding Names

Names are stored in JSON files in the `data/` directory:

**For male names** (`data/male.json`):
```json
{
  "name": "Cabdullahi",
  "meaning": "Servant of Allah"
}
```

**For female names** (`data/female.json`):
```json
{
  "name": "Caasha",
  "meaning": "Life; she who lives"
}
```

### 🔄 Contribution Process

1. **Fork** this repository
2. **Add names** to the appropriate JSON file
3. **Verify accuracy** - Ensure names and meanings are authentic
4. **Run tests** - `npm test` to ensure everything works
5. **Submit PR** - Include a brief description of the names added

### 📋 Name Guidelines

- **Authenticity**: Only traditional Somali names
- **Accuracy**: Verify meanings with reliable sources
- **Format**: Follow existing JSON structure exactly
- **Uniqueness**: Check for duplicates before adding
- **Respect**: Honor the cultural significance of names

### 🌟 Recognition

Contributors will be acknowledged in our [CONTRIBUTORS.md](./CONTRIBUTORS.md) file. Thank you for helping preserve Somali heritage!

## 🧪 Testing

This project has comprehensive tests covering all functionality:

```bash
# Run all tests
npm test

# Run tests with coverage
npm run test:coverage

# Run tests in watch mode
npm run test:watch
```

See [TESTING.md](./TESTING.md) for detailed testing information.

## 📄 License

MIT License - see [LICENSE](./LICENSE) file for details.

## 🙏 Acknowledgments

- The Somali community for preserving these beautiful naming traditions
- Contributors who help expand and maintain this collection
- Everyone working to digitally preserve cultural heritage

## 🔗 Related Projects

- Looking for other cultural name generators? Let us know!
- Interested in Somali language resources? We'd love to connect!

---

**Mahadsanid!** (Thank you!) for using and contributing to this project. Together, we're preserving and sharing the beauty of Somali names with the world. 🌍

*Made with ❤️ for the Somali community and developers worldwide*