nam

names

API client for retrieving random names

Showing:

Readme

names Build Status

This package acts as an API client for my favorite generator of random names: uinames. It's perfect for prototyping stuff or examples of real names in production apps.

Usage

Install the package using npm and save it to the dependency list:

npm install --save names

Now you have two choices to interact with the package. Since it's based on the concept of promises, you can either use async/await (it hasn't yet landed in node, so you'll have to transpile the code)...

import names from 'names'

try {
  const list = await names()
} catch (err) {
  console.error(err)
}

...or the old way of doing it:

const names = require('names')()

names.then(function (list) {
  console.log(list)
})

names.catch(function (err) {
  console.error(err)
})

Both examples will result in a response that looks like the following:

{
  "name": "John",
  "surname": "Doe",
  "gender": "male",
  "region": "United States"
}

Configuration

Indipendent from which of the methods mentioned above you would like to use, you can always pass a configuration object to the module's main method:

names({
  gender: 'female',
  amount: 10
  ...
})

Here's the full list of all available options:

NameDescriptionType
amountAmount of names to return, between 1 and 500Integer
genderLimit results to the male or female genderString
regionRegion-specific resultsString
minLengthRequire a minimum number of characters in a nameInteger
maxLengthRequire a maximum number of characters in a nameInteger

Contribute

  1. Fork this repository to your own GitHub account and then clone it to your local device
  2. Link the package to the global module directory: npm link
  3. Transpile the source code and watch for changes: npm start
  4. Within the module you want to test your local development instance of names, just link it to the dependencies: npm link names. Instead of the default one from npm, node will now use your clone of names!