Naija Faker

Naija Faker is a javascript library that generates fake typical Nigerian data ranging from name, address, phone number, lgas and states for you. It supports Yoruba, Igbo, and Hausa ethnic groups with culturally authentic data.

Features

• Authentic Nigerian names (Yoruba, Igbo, Hausa)
• Phone numbers for all 4 major networks (MTN, Glo, Airtel, 9mobile)
• Addresses across all Nigerian regions
• All 37 states (36 states + FCT)
• 774 Local Government Areas
• Nigerian-specific titles (Chief, Alhaji, Oba, Emir, Igwe, and more)
• BVN, NIN, and bank account generation (26 Nigerian banks)
• License plates, companies, and 42 Nigerian universities
• Geographically consistent identities (name + state + LGA all match)
• Detailed persons with education, work, and vehicle records
• Date of birth, blood group, genotype, marital status
• Salary generation with level-based income bands
• Next of kin generation
• Bulk export to JSON or CSV
• Seeded deterministic generation for reproducible tests
• TypeScript support with full IntelliSense
• AI/LLM integration via schema.json and describe() method

Installation

Install the package in your existing project

npm install @codegrenade/naija-faker

Basic Usage/Examples

Import or require the the package in your project to initialize the faker generator.

import faker from '@codegrenade/naija-faker'

or

const faker = require('@codegrenade/naija-faker')

Configuration for data choice (optional)

sets default language and gender for names to be generated and the local network provider for phone number

faker.config({
	language: "yoruba",
	gender: "male",
	network: "glo",
})

NB: Yoruba, Igbo and Hausa are the only Nigerian languages supported at the moment.

Generate fake data by calling faker methods.

faker.title() // Mrs.

faker.name() // Temilade Abolade

faker.address() // 45, Alhaji Kazeem Street, Kaduna
faker.address("west") // Plot 12, Adebayo Ogunlesi Avenue, Ibadan

faker.phoneNumber() // 09123456634

faker.email() // [email protected]

faker.states() // array of states in Nigeria (36 states + FCT)

faker.lgas() // array of local government areas in Nigeria

// returns a bank account details
faker.bankAccount()
// → { bankName: 'Zenith Bank', bankCode: '057', accountNumber: '1234567890' }

// returns a BVN (11-digit Bank Verification Number)
faker.bvn() // → '22312345678'

// returns a NIN (11-digit National Identification Number)
faker.nin() // → '98765432101'

// call to person method
faker.person() 

// object of person details
{
  title: 'Engr.',
  firstName: 'Akintunde',
  lastName: 'Owoyele',
  fullName: 'Akintunde Owoyele',
  email: '[email protected]',
  phone: '+2349093636382',
  address: '63, Ebubedike Uzoma Avenue, Awka'
}

If you want a person of a particular language and gender

// returns person details of a male from the hausa language
faker.person("hausa", "male") 

// call to people method
faker.people()

// array of person objects
[
  {
    title: 'Engr.',
    firstName: 'Akintunde',
    lastName: 'Owoyele',
    fullName: 'Akintunde Owoyele',
    email: '[email protected]',
    phone: '+2349093636382',
    address: '63, Ebubedike Uzoma Avenue, Awka'
  }
  {
    title: 'Mr.',
    firstName: 'Olayinka',
    lastName: 'Adedayo',
    fullName: 'Olayinka Adedayo',
    email: '[email protected]',
    phone: '+2348189416772',
    address: 'Km 9, Lanre Ayotunde Crescent, Ilorin'
  }
]

The people method returns 10 persons by default. If you want more persons to be returned by the method, use the example below.

faker.people(20) // returns 20 persons in the array

Specifing desired parameter values

// returns a male title
faker.title("male") 

// returns an igbo language name
faker.name("igbo") 

// returns a yoruba name for the male gender
faker.name("yoruba", "male") 

// returns a phone number from the mtn network
faker.phoneNumber("mtn")

// returns an email address from the name supplied
faker.email("Aboderin Joshua")

// returns a bank account for a specific bank
faker.bankAccount("Access Bank")

Seeded Generation

Use faker.seed() for reproducible output — perfect for snapshot testing and consistent test fixtures.

faker.seed(12345)
faker.name("yoruba", "male") // Always returns the same name
faker.person("igbo")         // Always returns the same person

faker.seed(12345)            // Reset to same seed
faker.name("yoruba", "male") // Identical output as above

faker.seed()                 // Reset to non-deterministic mode

Consistent Identities

Generate persons where name ethnicity, address, state, and LGA are all geographically coherent.

faker.consistentPerson("yoruba", "male")

// → All fields match: Yoruba name, western address, western state, matching LGA
{
  title: 'Chief',
  firstName: 'Adebayo',
  lastName: 'Ogunlesi',
  fullName: 'Adebayo Ogunlesi',
  email: '[email protected]',
  phone: '+2348031234567',
  address: 'Plot 45, Oluwaseun Adedayo Street, Ibadan',
  state: 'Oyo',
  lga: 'Ibadan North',
  language: 'yoruba',
  region: 'west'
}

Titles are filtered against the identity too, so an Igbo person is never an Emir and a Yoruba person is never an Igwe. Pass an optional profile to narrow it further:

faker.consistentPerson("igbo", "female", { age: 29, maritalStatus: "Single" })
// → never "Mrs.", never "Chief" (too young), never "Alhaja" (wrong group)

// Generate multiple consistent people
faker.consistentPeople(5, "hausa", "female")
// → 5 Hausa female persons, all with northern states and matching LGAs

License Plates, Companies & Universities

// Generate a Nigerian license plate
faker.licensePlate() // → 'LAG-234XY'
faker.licensePlate("Kano") // → 'KAN-891AB'

// Generate a Nigerian company
faker.company()
// → { name: 'Pan-African Solutions Ltd', rcNumber: 'RC-1234567', industry: 'Technology' }

// Generate a Nigerian university
faker.university()
// → { name: 'University of Lagos', abbreviation: 'UNILAG', state: 'Lagos', type: 'federal' }

Records

faker.educationRecord("yoruba")
// → { university: 'University of Lagos', abbreviation: 'UNILAG', degree: 'B.Sc', discipline: 'science', course: 'Computer Science', graduationYear: 2019 }

// Pass an age and the degree is one the person lived long enough to earn,
// awarded in a year after their birth. The course always fits the degree,
// so there is no "B.Pharm in History".
faker.educationRecord("yoruba", 27)

// Too young to have finished anything → null, rather than an invented degree
faker.educationRecord("yoruba", 18) // → null

faker.workRecord()
// → { company: 'Pan-African Solutions Ltd', position: 'Senior Analyst', industry: 'Technology', startYear: 2019, yearsOfExperience: 7, level: 'mid' }

// Pass an age and graduation year: the job starts after the degree, and
// seniority, position and salary band all follow years of experience
faker.workRecord(30, 2018)

faker.vehicleRecord("Lagos")
// → { licensePlate: 'LAG-234XY', make: 'Toyota', model: 'Corolla', year: 2021, color: 'Silver' }

Detailed Person

Generate a rich identity with education, work, and vehicle records — all geographically coherent.

faker.detailedPerson("yoruba", "male")

{
  title: 'Chief',
  firstName: 'Adebayo',
  lastName: 'Ogunlesi',
  fullName: 'Adebayo Ogunlesi',
  email: '[email protected]',
  phone: '+2348031234567',
  address: 'Plot 45, Oluwaseun Adedayo Street, Ibadan',
  state: 'Oyo',
  lga: 'Ibadan North',
  dateOfBirth: { date: '1990-03-15', age: 35 },
  maritalStatus: 'Married',
  bloodGroup: 'O+',
  genotype: 'AA',
  salary: {
    amount: 450000,
    currency: 'NGN',
    level: 'mid',
    frequency: 'monthly'
  },
  nextOfKin: {
    fullName: 'Folake Adeyemi',
    relationship: 'Spouse',
    phone: '+2348091234567',
    address: '12, Akinola Crescent, Ibadan'
  },
  education: {
    university: 'University of Ibadan',
    abbreviation: 'UI',
    degree: 'B.Sc',
    discipline: 'science',
    course: 'Computer Science',
    graduationYear: 2019
  },
  work: {
    company: 'Pan-African Solutions Ltd',
    position: 'Software Engineer',
    industry: 'Technology',
    startYear: 2020,
    yearsOfExperience: 7,
    level: 'mid'
  },
  vehicle: {
    licensePlate: 'OYO-234XY',
    make: 'Toyota',
    model: 'Corolla',
    year: 2021,
    color: 'Silver'
  }
}

// Generate multiple detailed people
faker.detailedPeople(5, "igbo", "female")

Detailed people are 22 to 65 by default, since the record carries a degree and a job. Widen it and the young are represented honestly — education is null rather than a qualification they could not have finished:

faker.detailedPerson("igbo", "female", { minAge: 18, maxAge: 24 })
// → an 18-year-old comes back with education: null, entry-level work and pay

Every field of a detailed person is derived from one identity rather than drawn independently, so the record holds together:

• the title matches the ethnic group, the age, the marital status and the qualification — no Igbo Emir, no 24-year-old Prof., no single Mrs.
• graduation comes after birth at a plausible age for the degree, and never in the future
• employment starts after graduation (or after turning 18, for those with no degree yet), and seniority, position and salary band all follow years of experience
• marital status and the next of kin's relationship fit the age — no widowed 19-year-olds, no 25-year-old whose next of kin is their son
• the next of kin shares the family name and lives in the same part of the country
• Oba, Igwe and Emir stay rare instead of turning up in 1 record in 15

Called on their own, the individual providers keep their old, unconstrained behaviour — the sanity rules apply to the context you give them.

Personal Data

faker.dateOfBirth() // → { date: '1990-03-15', age: 35 }
faker.dateOfBirth({ minAge: 25, maxAge: 40 }) // custom range

faker.maritalStatus() // → 'Married'
faker.bloodGroup() // → 'O+'
faker.genotype() // → 'AS'

Salary

faker.salary()
// → { amount: 450000, currency: 'NGN', level: 'mid', frequency: 'monthly' }

faker.salary({ level: 'executive' })
// → { amount: 3500000, currency: 'NGN', level: 'executive', frequency: 'monthly' }

Next of Kin

faker.nextOfKin("yoruba", "male")
// → { fullName: 'Adebayo Ogunlesi', relationship: 'Brother', phone: '+234...', address: '...' }

Bulk Export

// Export as JSON string
faker.export("person", 5) // 5 persons as JSON

// Export as CSV
faker.export("person", 5, "csv")
// → title,firstName,lastName,fullName,email,phone,address\n...

// Export detailed persons (nested fields are flattened in CSV)
faker.export("detailedPerson", 10, "csv")

Custom Providers

Extend naija-faker with your own data generators:

// Register a custom provider
faker.registerProvider('religion', (f) => {
  const religions = ['Christianity', 'Islam', 'Traditional']
  return religions[Math.floor(f._random() * religions.length)]
})

faker.generate('religion') // → 'Islam'

// Complex return types work too
faker.registerProvider('vehicle_insurance', (f) => ({
  provider: 'AXA Mansard',
  policyNumber: `POL-${Math.floor(f._random() * 900000 + 100000)}`,
  type: 'comprehensive',
}))

faker.generate('vehicle_insurance')
// → { provider: 'AXA Mansard', policyNumber: 'POL-482917', type: 'comprehensive' }

// List registered providers
faker.listProviders() // → ['religion', 'vehicle_insurance']

Note: Custom providers receive the faker instance as an argument — use f._random() instead of Math.random() for seeded deterministic output.

Error Handling

All validation errors throw a NaijaFakerError with a machine-readable code:

const faker = require('@codegrenade/naija-faker')

// Access via property
const { NaijaFakerError } = faker

try {
  faker.name("klingon")
} catch (err) {
  if (err instanceof faker.NaijaFakerError) { ... }
}

| Error Code | Methods | |-----------|---------| | INVALID_LANGUAGE | name(), config(), consistentPerson(), detailedPerson() | | INVALID_GENDER | config() | | INVALID_NETWORK | phoneNumber(), config() | | INVALID_STATE | licensePlate() | | INVALID_REGION | address() | | INVALID_BANK | bankAccount() | | INVALID_LEVEL | salary() | | INVALID_TYPE | export() | | INVALID_PARAM | config(), phoneNumber() |

TypeScript Support

Naija Faker ships with TypeScript declarations out of the box. You get full IntelliSense and type checking with no additional setup.

import faker from '@codegrenade/naija-faker'

const person = faker.person("yoruba", "female")
// Full autocomplete for person.title, person.firstName, etc.

AI/LLM Integration

Naija Faker is designed to work seamlessly with AI agents and LLM-powered development tools.

Runtime Introspection

Use the describe() method to discover available methods at runtime:

// Get schema for all methods
faker.describe()

// Get schema for a specific method
faker.describe('person')
// Returns: { name: 'person', description: '...', parameters: [...], returns: {...}, example: {...} }

Schema File

A schema.json file is included in the package, providing a full JSON Schema description of the API. AI agents can use this for tool discovery:

const schema = require('@codegrenade/naija-faker/schema.json')

Disclaimer :warning:

See DISCLAIMER for details.

Contributing

Please feel free to fork the package and contribute by submitting a pull request to enhance the functionlities.

License

Naija Faker is release under the MIT License. See LICENSE for details.

Feedback

If you have any feedback, please reach out to me at [email protected]

Author

• @kodegrenade