npm - vietnamese-name-generator - Versions diffs - 0.9.0 → 0.11.0 - Mend

vietnamese-name-generator 0.9.0 → 0.11.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (6) hide show

package/README.md CHANGED Viewed

@@ -9,13 +9,16 @@ The most comprehensive Vietnamese name toolkit for JavaScript/TypeScript. Genera
 Zero runtime dependencies. Ships as CJS + ESM with full TypeScript declarations.
+> **Disclaimer:** This library generates fictional data for testing, development, and educational purposes only. Do not use generated data for identity fraud, impersonation, phishing, social engineering, or any activity that violates applicable laws. Generated names are synthetic and any resemblance to real individuals is coincidental. The authors bear no responsibility for misuse.
 ## Why this library?
 - **No npm alternative** for Vietnamese name parsing, gender detection, or validation
-- **Census-weighted** surname distribution (Nguyen 40%, Tran 11%, Le 9%...)
-- **Culturally correct** — regional variants (Hoang/Huynh), gender-encoded middle names, proper honorifics
-- **i18n-ready** — NFC normalization, accent-insensitive search, Vietnamese sort order
-- **AI/testing-friendly** — deterministic seed, batch generation, CSV/JSON export
+- **Census-weighted** surname distribution (Nguyễn ~40%, Trần ~11%, Lê ~9%...)
+- **Culturally correct** -- regional variants (Hoang/Huynh), gender-encoded middle names, proper honorifics
+- **i18n-ready** -- NFC normalization, accent-insensitive search, Vietnamese sort order
+- **Cultural depth** -- Five Elements (Ngu Hanh), Han Viet characters, protective nicknames, pet names
+- **AI/testing-friendly** -- deterministic seed, batch generation, CSV/JSON export
 ## Installation
@@ -34,13 +37,15 @@ import {
   detectGender,
   salutation,
   romanize,
+  getHanViet,
+  getBirthYearElement,
+  generatePetName,
+  generateNickname,
 } from 'vietnamese-name-generator';
 // Generate a realistic Vietnamese name
 const name = generate({ seed: 42 });
-// { surname: 'Phan', middleName: 'Ngoc', givenName: 'Kim Trang',
-//   fullName: 'Phan Ngoc Kim Trang', gender: 'female', region: 'central',
-//   era: 'modern', romanized: {...}, formatted: {...} }
+// { surname: 'Phan', middleName: 'Ngoc', givenName: 'Kim Trang', ... }
 // Parse any Vietnamese name into structured parts
 parseName('Nguyen Van An');
@@ -48,15 +53,27 @@ parseName('Nguyen Van An');
 // Detect gender from name
 detectGender('Nguyen Thi Mai');
-// { gender: 'female', confidence: 'high', signals: { middleName: { gender: 'female', value: 'Thi' } } }
+// { gender: 'female', confidence: 'high' }
-// Generate culturally correct salutation
+// Culturally correct salutation ("Ong Nam", not "Mr. Nguyen")
 salutation('Nguyen Van Nam', { formality: 'formal' });
 // { honorific: 'Ong', addressName: 'Nam', fullSalutation: 'Kinh gui Ong Nam' }
-// Romanize (remove diacritics)
-romanize('Nguyen Van An');
-// 'Nguyen Van An'
+// Han Viet character lookup
+getHanViet('Minh');
+// { character: '明', meaning: 'bright/intelligent', alternates: [{character: '銘', meaning: 'inscribe'}] }
+// Five Elements from birth year
+getBirthYearElement(1990);
+// 'kim' (Metal)
+// Vietnamese pet name
+generatePetName({ category: 'byFood' });
+// { name: 'Pho', meaning: 'pho noodle soup', category: 'byFood' }
+// Protective baby nickname (ten xau de nuoi)
+generateNickname({ category: 'animal' });
+// { nickname: 'Coc', meaning: 'toad', culturalNote: '...' }
 ```
 ## CLI
@@ -66,7 +83,7 @@ romanize('Nguyen Van An');
 npx vietnamese-name-generator --count 10 --gender female --region south
 npx vietnamese-name-generator --seed 42 --format slug --json
-# Parse, validate, detect
+# Parse, validate, detect gender
 npx vietnamese-name-generator --parse "Nguyen Van An"
 npx vietnamese-name-generator --validate "Nguyen Van An"
 npx vietnamese-name-generator --detect "Nguyen Thi Mai"
@@ -88,66 +105,24 @@ npx vietnamese-name-generator --export json --count 50
 | `generateManyFullNames(count, options?)` | `string[]` | Batch full name strings |
 | `generateEmail(options?)` | `IEmailResult` | Email from generated name |
 | `generateUsername(options?)` | `IUsernameResult` | Username from generated name |
-#### Options
-```typescript
-type TGenerateOptions = {
-  gender?: EGender;          // 'male' | 'female' | 'unisex'
-  region?: ERegion;          // 'north' | 'central' | 'south'
-  era?: EEra;                // 'traditional' | 'modern'
-  compoundName?: boolean;    // two-syllable given name
-  meaningCategory?: EMeaningCategory;  // 9 semantic categories
-  withMiddleName?: boolean;  // default: true
-  seed?: number;             // deterministic output
-  format?: ENameFormat | ENameFormat[];  // output formats
-};
-```
-#### Result
-```typescript
-interface INameResult {
-  surname: string;
-  middleName: string;
-  givenName: string;
-  fullName: string;
-  gender: EGender;
-  region: ERegion;
-  era: EEra;
-  romanized: IRomanizedName;   // ASCII versions of all parts
-  formatted: Partial<Record<ENameFormat, string>>;  // requested formats
-}
-```
+| `generateNickname(options?)` | `INicknameResult` | Traditional protective nickname |
+| `generatePetName(options?)` | `IPetNameResult` | Vietnamese pet name |
+| `generateManyPetNames(count, options?)` | `IPetNameResult[]` | Batch pet names |
 ### Parsing & Validation
 | Function | Returns | Description |
 |----------|---------|-------------|
 | `parseName(input)` | `IParsedName` | Split full name into surname/middle/given |
-| `validateName(input)` | `IValidationResult` | Check if string is a valid Vietnamese name |
+| `validateName(input)` | `IValidationResult` | Validate Vietnamese name with specific failure reasons |
 | `detectGender(input)` | `IGenderResult` | Infer gender from middle + given name signals |
-```typescript
-// Parse — handles compound surnames (Ton That), romanized input (Nguyen)
-parseName('Ton That Minh An');
-// { surname: 'Ton That', middleName: 'Minh', givenName: 'An' }
-// Validate — returns specific failure reasons
-validateName('xyz van an');
-// { valid: false, reasons: ['Each part must start with uppercase', 'Unknown surname: xyz'] }
-// Detect gender — confidence levels based on signal strength
-detectGender('Tran Van An');
-// { gender: 'male', confidence: 'high', signals: { middleName: { gender: 'male', value: 'Van' } } }
-```
 ### Formatting & i18n
 | Function | Returns | Description |
 |----------|---------|-------------|
 | `romanize(input)` | `string` | Remove Vietnamese diacritics |
-| `formatName(parts, format)` | `string` | Format name as full/abbreviated/reversed/slug |
+| `formatName(parts, format)` | `string` | Format as full/abbreviated/reversed/slug |
 | `salutation(name, options?)` | `ISalutationResult` | Culturally correct Vietnamese honorific |
 | `normalize(input)` | `string` | NFC Unicode normalization |
 | `accentInsensitiveMatch(text, query)` | `boolean` | Search ignoring diacritics |
@@ -156,66 +131,34 @@ detectGender('Tran Van An');
 | `vietnameseNameComparator(options?)` | `Function` | Comparator for `Array.sort()` |
 | `VIETNAMESE_NAME_REGEX` | `RegExp` | Validates Vietnamese characters |
-```typescript
-// Format — 4 built-in formats, request multiple at once
-generate({ format: ['full', 'slug', 'abbreviated'] });
-// result.formatted = { full: 'Nguyen Van An', slug: 'nguyen-van-an', abbreviated: 'N.V. An' }
-// Salutation — "Ong Nam" not "Mr. Nguyen"
-salutation('Nguyen Van Nam', { formality: 'formal' });
-// { honorific: 'Ong', addressName: 'Nam', fullSalutation: 'Kinh gui Ong Nam' }
-// Accent-insensitive search
-accentInsensitiveMatch('Nguyen Van An', 'nguyen');  // true
-// Sort by given name (Vietnamese convention)
-sortVietnamese(['Tran Thi Binh', 'Nguyen Van An']);
-// ['Nguyen Van An', 'Tran Thi Binh']  (An < Binh)
-```
-### Data & Lookup
+### Cultural Data
 | Function | Returns | Description |
 |----------|---------|-------------|
+| `getHanViet(name)` | `THanVietEntry \| null` | Chinese character origin + meaning |
+| `getElementInfo(element)` | `IElementInfo` | Five Elements relationships |
+| `getNameElement(name)` | `EElement \| null` | Which element a name belongs to |
+| `getNamesByElement(element, options?)` | `string[]` | Names belonging to an element |
+| `getBirthYearElement(year)` | `EElement` | Element from Heavenly Stems cycle |
 | `getMeaning(name)` | `INameMeaning` | Meaning category, gender/region/era distribution |
 | `getSurnameInfo(surname)` | `ISurnameInfo` | Frequency, rank, regional variants |
 | `getRegionalVariant(surname, region)` | `string` | Convert Hoang<->Huynh, Vu<->Vo |
-| `nameSimilarity(name1, name2)` | `ISimilarityResult` | Compare names accounting for diacritics/variants |
+| `nameSimilarity(name1, name2)` | `ISimilarityResult` | Compare names with diacritics/variant tolerance |
 | `getStatistics()` | `IStatisticsResult` | Dataset overview counts |
 | `getTopSurnames(options?)` | `IRankedName[]` | Top N surnames by frequency |
-| `getGivenNameCount(options?)` | `number` | Count given names by gender/region/era |
-| `getUniqueGivenNames(options?)` | `string[]` | List unique given names |
-```typescript
-// Name meaning
-getMeaning('Hung');
-// { found: true, category: 'strength', genders: ['male'], regions: ['north','central','south'], ... }
-// Surname info
-getSurnameInfo('Nguyen');
-// { found: true, frequency: { north: 31.5, central: 30.2, south: 28.5 }, rank: { north: 1, ... } }
-// Regional variant
-getRegionalVariant('Hoang', 'south');  // 'Huynh'
-getRegionalVariant('Vo', 'north');     // 'Vu'
-// Name similarity (handles diacritics, variants)
-nameSimilarity('Nguyen Van An', 'Nguyen Van An');
-// { score: 0.9, romanizedMatch: true, ... }
-```
 ### Faker.js Compatible
 ```typescript
 import { fakerVi } from 'vietnamese-name-generator';
-fakerVi.person.firstName();          // 'An'
-fakerVi.person.lastName();           // 'Nguyen'
-fakerVi.person.fullName();           // 'Nguyen Van An'
-fakerVi.person.sex();                // 'male'
-fakerVi.person.prefix('female');     // 'Ba'
-fakerVi.internet.email();            // 'an.nguyen@gmail.com'
-fakerVi.internet.username();         // 'annguyen'
+fakerVi.person.firstName();        // 'An'
+fakerVi.person.lastName();         // 'Nguyen'
+fakerVi.person.fullName();         // 'Nguyen Van An'
+fakerVi.person.sex();              // 'male'
+fakerVi.person.prefix('female');   // 'Ba'
+fakerVi.internet.email();          // 'an.nguyen@gmail.com'
+fakerVi.internet.username();       // 'annguyen'
 ```
 ### Enums
@@ -227,31 +170,168 @@ fakerVi.internet.username();         // 'annguyen'
 | `EEra` | `traditional`, `modern` |
 | `EMeaningCategory` | `strength`, `virtue`, `nature`, `precious`, `beauty`, `celestial`, `season`, `intellect`, `prosperity` |
 | `ENameFormat` | `full`, `abbreviated`, `reversed`, `slug` |
+| `EElement` | `kim` (Metal), `moc` (Wood), `thuy` (Water), `hoa` (Fire), `tho` (Earth) |
-## Data Sources
+---
+## Vietnamese Naming Culture
-Names are collected from 6 web sources via an automated crawl pipeline:
+### Name Structure
-- [duyet/vietnamese-namedb](https://github.com/duyet/vietnamese-namedb) (GitHub)
-- faker-vi (Vietnamese faker library)
-- Wiktionary Vietnamese entries
-- Wikipedia Vietnamese surname pages
-- [surnam.es](https://surnam.es) genealogy database
-- DrPapie Vietnamese name database
+Vietnamese names follow **surname - middle name - given name** order, the reverse of Western convention. In daily life, people are addressed by their **given name** (the last word), not their surname.
-Surnames are weighted by census frequency. Given names are tagged by gender, region, era, and meaning category.
+| Part | Vietnamese | Example | Role |
+|------|-----------|---------|------|
+| Surname (Họ) | Họ | Nguyễn | Family lineage |
+| Middle name (Tên đệm) | Tên đệm / Tên lót | Văn, Thị | Gender marker, generational marker |
+| Given name (Tên) | Tên gọi | An, Mai | Personal identity -- this is "the name" |
-## Vietnamese Naming Context
+### Why ~40% of Vietnam is Named Nguyễn
-Vietnamese names are written **surname - middle name - given name** (reverse of Western order). In daily life, people are addressed by their **given name**, not surname.
+Vietnamese surname concentration is extreme by world standards. Approximately 38-40% of the population carries the surname Nguyễn ([Atlas Obscura](https://www.atlasobscura.com/articles/pronounce-nguyen-common-vietnam), [Wikipedia](https://en.wikipedia.org/wiki/Nguyen)), a direct consequence of **forced surname changes during dynasty transitions** ([Nguyễn, V.K., 2024, *Genealogy*](https://www.mdpi.com/2313-5778/8/1/16)):
-**Surname concentration is extreme.** About 40% of Vietnamese carry the surname Nguyen. The top 14 surnames cover 90%+ of the population.
+- **1232 (Lý -> Trần):** The Trần dynasty forced Lý families to change their surname to avoid the former emperor's name (kỵ húy), pushing many to adopt Nguyễn
+- **1400-1407 (Trần -> Hồ):** Hồ Quý Ly seized power from the Trần dynasty in 1400; when the Hồ dynasty fell in 1407, Hồ descendants changed to Nguyễn for safety
+- **1592 (Mạc -> Lê restoration):** Mạc families adopted Nguyễn to avoid persecution
+- **1802 (Nguyễn dynasty):** The Nguyễn lords unified Vietnam; many adopted the ruling surname for favor or protection
-**The middle name encodes gender.** Van marks male, Thi marks female (traditional). Modern names use varied middle names like Minh, Bao, Ngoc.
+The top 14 Vietnamese surnames cover **90%+** of the population ([Wikipedia: Vietnamese name](https://en.wikipedia.org/wiki/Vietnamese_name)): Nguyễn (~38-40%), Trần (~11%), Lê (~9.5%), Phạm (~7.1%), Hoàng/Huỳnh (~5.1%), Vũ/Võ (~3.9%)...
-**Region determines surname form.** Hoang (North) = Huynh (South). Vu (North) = Vo (South).
+### The Middle Name Encodes Gender
-**Every given name carries meaning.** Lan = orchid, Ha = river, Minh = bright, Phuc = blessing, Nguyet = moon.
+The middle name (ten dem/ten lot) has traditionally served as a **gender marker** ([Vietcetera: Why "Van" and "Thi" are popular](https://vietcetera.com/en/why-are-middle-names-van-and-thi-popular-in-vietnam)):
+- **Văn** (文, literature) -- marks male names. Usage declining in modern naming
+- **Thị** (氏, clan) -- marks female names. Usage declining in modern naming
+- **Modern alternatives:** Minh, Gia, Bảo, Đức (male); Ngọc, Khánh, Bảo (female); An, Minh (unisex)
+Middle names also function as **generation markers** ([Wikipedia: Generation name](https://en.wikipedia.org/wiki/Generation_name)) -- siblings and cousins of the same generation share the same middle name, enabling family tree identification.
+### Regional Surname Variants
+The same Chinese character is read differently by regional dialect ([Cultural Atlas: Vietnamese Naming](https://culturalatlas.sbs.com.au/vietnamese-culture/vietnamese-culture-naming)):
+| North | South | Chinese Origin |
+|-------|-------|---------------|
+| Hoàng | Huỳnh | 黄 (yellow) |
+| Vũ | Võ | 武 (martial) |
+These splits originate from the kỵ húy (naming taboo) laws of the Nguyễn Lords ([Wikipedia: Vietnamese name](https://en.wikipedia.org/wiki/Vietnamese_name)), where the imperial name could not be spoken and regional pronunciations diverged permanently.
+### Sino-Vietnamese (Han Viet) Origins
+Nearly all Vietnamese given names derive from Chinese characters (Han tu), read in Sino-Vietnamese pronunciation. A single romanized name can map to multiple characters with different meanings:
+| Name | Character | Meaning | Alternate | Meaning |
+|------|-----------|---------|-----------|---------|
+| Minh | 明 | Bright/intelligent | 銘 | Inscribe/remember |
+| An | 安 | Peace | 晏 | Calm |
+| Thanh | 清 | Pure | 青 | Blue/green |
+| Long | 龍 | Dragon | 隆 | Prosperous |
+This library includes Han Viet character data for 80+ common names via `getHanViet()`.
+### Five Elements (Ngũ Hành) Naming
+Vietnamese parents traditionally choose names based on the **Five Elements** ([Feng Shui Master Academy: Baby Names Using Bazi](https://fengshuimasteryacademy.com/how-to-choose-chinese-baby-names-using-bazi-analysis/)) to balance a child's destiny:
+| Element | Vietnamese | Chinese | Associated Names |
+|---------|-----------|---------|-----------------|
+| Metal | Kim | 金 | Kim, Ngân, Bảo, Châu |
+| Wood | Mộc | 木 | Lâm, Phong, Xuân, Trúc, Mai |
+| Water | Thủy | 水 | Thủy, Hà, Hải, Giang, Linh |
+| Fire | Hỏa | 火 | Quang, Huy, Minh, Hồng |
+| Earth | Thổ | 土 | Sơn, Bình, An, Thành, Long |
+The birth year determines the child's element via the **Heavenly Stems (Thiên Can)** cycle. Parents select names from the **generating element** (tương sinh) to support the child's destiny.
+### Name Taboos (Kỵ Húy)
+Under feudal dynasties, using the emperor's personal name or a near-homophone was forbidden ([Wikipedia: Naming taboo](https://en.wikipedia.org/wiki/Naming_taboo#Vietnam)). This practice permanently altered the Vietnamese name pool:
+- Emperor's name banned -> families respelled similar names
+- Children were never named after living parents or grandparents
+- Some families gave babies **"ugly names" (tên xấu để nuôi)** -- Cóc (toad), Tý (mouse), Chí (louse) -- to deceive evil spirits who might harm a beautiful child
+This library includes a protective nickname generator (`generateNickname()`) honoring this tradition.
+### Compound Names (Tên Kép)
+Two-syllable given names like Bảo Châu, Minh Khôi, or Thanh Hà became popular from the late 20th century. With so few surnames in circulation, compound names reduce ambiguity while adding poetic meaning. Modern compound names often combine two auspicious characters.
+### Pet Naming Culture
+Vietnamese pet naming is a rich cultural practice ([PetMart.vn](https://www.petmart.vn/dat-ten-cho-cho-bang-tieng-viet)):
+- **By appearance**: Vàng (gold), Mực (ink), Bông (cotton), Đốm (spotted) ([PetChoice.vn](https://petchoice.vn/blogs/news/dat-ten-meo-theo-mau-long))
+- **By food**: Phở, Bún, Bánh Mì, Xôi -- a uniquely Vietnamese trend
+- **By luck**: Tài (wealth), Lộc (fortune), Phúc (blessing) -- feng shui influence
+- **By humor**: Đại Ca (big boss for tiny dogs), Cậu Vàng (Mr. Gold, from Nam Cao's literary classic "Lão Hạc", 1943)
+- **Modern trends**: anime names (Luna, Totoro), K-drama influence, English names
+This library includes 150+ pet names across 7 categories via `generatePetName()`.
+---
+## Data Sources
+### Name Data (Crawl Pipeline)
+Names are collected from 6 web sources via an automated crawl pipeline, then merged, deduplicated, tagged, and validated:
+| Source | Type | URL |
+|--------|------|-----|
+| Vietnamese Name DB | 6,284 given names by gender | [github.com/duyet/vietnamese-namedb](https://github.com/duyet/vietnamese-namedb) |
+| faker-vi | Vietnamese faker library data | Internal extraction |
+| Wiktionary | Vietnamese name entries with etymology | [en.wiktionary.org](https://en.wiktionary.org) |
+| Wikipedia | Vietnamese surname pages | [en.wikipedia.org/wiki/Vietnamese_name](https://en.wikipedia.org/wiki/Vietnamese_name) |
+| surnam.es | Genealogy surname database | [surnam.es](https://surnam.es) |
+| DrPapie | Vietnamese baby names with meanings | [drpapie.com](https://drpapie.com) |
+### Cultural Data
+| Data | Source |
+|------|--------|
+| Han Viet characters | Sino-Vietnamese dictionaries, [hvdic.thivien.net](https://hvdic.thivien.net) |
+| Five Elements | Traditional Vietnamese metaphysics, feng shui references |
+| Surname frequency | Vietnamese census data, demographic studies |
+| Regional variants | [MDPI: Onomastic Account of Vietnamese Surnames](https://www.mdpi.com/2313-5778/8/1/16) |
+| Gender detection | [ArXiv: Gender Prediction Based on Vietnamese Names](https://arxiv.org/abs/2010.10852) |
+| Naming taboos | [Wikipedia: Vietnamese name](https://en.wikipedia.org/wiki/Vietnamese_name), historical dynasty records |
+### Pet Name Data
+| Source | Coverage |
+|--------|----------|
+| [PetMart.vn](https://www.petmart.vn) | 8 naming categories, feng shui names |
+| [PetChoice.vn](https://petchoice.vn) | Names by fur color |
+| [CatHouse.vn](https://cathouse.vn) | 500+ cat names |
+| [PetPress.net](https://petpress.net/vietnamese-dog-names/) | 60 Vietnamese dog names with English meanings |
+| [WeReAllAboutPets.com](https://wereallaboutpets.com/pet-names/dog/vietnamese) | 90 names with meanings |
+### Academic References
+- Nguyen, V.K. (2024). "Toward an Onomastic Account of Vietnamese Surnames." *Genealogy*, 8(1), 16. [doi:10.3390/genealogy8010016](https://www.mdpi.com/2313-5778/8/1/16)
+- To, H.Q., Nguyen, K.V., Nguyen, N.L.T., Nguyen, A.G.T. (2020). "Gender Prediction Based on Vietnamese Names with Machine Learning Techniques." *ArXiv*. [arxiv.org/abs/2010.10852](https://arxiv.org/abs/2010.10852)
+- Cultural Atlas. "Vietnamese Culture - Naming." [culturalatlas.sbs.com.au](https://culturalatlas.sbs.com.au/vietnamese-culture/vietnamese-culture-naming)
+---
+## Disclaimer
+This library is intended for:
+- Software testing and development (mock data, seed databases, unit tests)
+- Educational purposes (learning about Vietnamese naming culture)
+- Creative applications (fiction writing, game character generation)
+- i18n development (building applications that correctly handle Vietnamese names)
+**This library must NOT be used for:**
+- Identity fraud or impersonation
+- Phishing, social engineering, or scam operations
+- Creating fake accounts on platforms that prohibit synthetic identities
+- Any activity that violates applicable laws in your jurisdiction
+All generated data is synthetic. The authors provide this tool in good faith and bear no responsibility for misuse.
 ## License