🇸🇴 Somali Names Generator

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

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 below.

🚀 Quick Start

Installation

npm install somali-names

Library Usage

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

# 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

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

Story Character Generator

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

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

{
  "name": "Cabdullahi",
  "meaning": "Servant of Allah"
}

For female names (data/female.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 file. Thank you for helping preserve Somali heritage!

🧪 Testing

This project has comprehensive tests covering all functionality:

# 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 for detailed testing information.

📄 License

MIT License - see 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