npm 中文文档

Unique Names Generator


More than 50,000,000 name combinations out of the box


What is Unique name generator?


Unique name generator is a tree-shakeable Node package for generating random and unique names.

It comes with a list of dictionaries out of the box, but you can also provide your custom ones.

Docs


This documentation is for the unique-names-generator v4.

If you are using a version 3.x of the library, please refer to the v3 Docs

For the version 1 & 2, please refer to the v2 Docs

Migrating to v4


If you want to migrate, from an older version of the library to v4, please read the Migration guide

Table of contents


Unique Names Generator
What is Unique name generator?
Docs
Migrating to v4

Table of contents
Prerequisites
Installation
Usage
Typescript support

API
uniqueNamesGenerator (options)
options
dictionaries
separator
length
style
seed

Dictionaries available
Numbers
Adjectives
Animals
Colors
Countries
Names
Languages
Star Wars
Default dictionaries
Custom dictionaries
Numbers Dictionary

Numbers Dictionary API
generate (options)
options
min
max
length

Combining custom and provided dictionaries

Migration guide
Migration guide from version 3 to version 4
Mandatory dictionaries config

Migration guide from version 1 or 2
uniqueNamesGenerator
Separator
Short

Contributing
License
Contributors ✨

Prerequisites


This project requires NodeJS (at least version 6) and NPM. Node and NPM are really easy to install. To make sure you have them available on your machine, try running the following command.

  1. ``` shell
  2. $ node --version
  3. v7.10.1

  5. $ npm --version
  6. 4.2.0
  7. ```

Installation


BEFORE YOU INSTALL:please read the prerequisites

Install the package using npm or Yarn

  1. ``` shell
  2. $ npm i -S unique-names-generator
  3. ```

Or using Yarn

  1. ``` shell
  2. $ yarn add unique-names-generator
  3. ```

Usage


  1. ``` js
  2. const { uniqueNamesGenerator, adjectives, colors, animals } = require('unique-names-generator');

  4. const randomName = uniqueNamesGenerator({ dictionaries: [adjectives, colors, animals] }); // big_red_donkey

  6. const shortName = uniqueNamesGenerator({
  7.   dictionaries: [adjectives, animals, colors], // colors can be omitted here as not used
  8.   length: 2
  9. }); // big-donkey
  10. ```

Typescript support


This package export a type definition file so you can use it, out of the box, inside your Typescript project.

  1. ``` ts
  2. import { uniqueNamesGenerator, Config, adjectives, colors, animals } from 'unique-names-generator';

  4. const customConfig: Config = {
  5.   dictionaries: [adjectives, colors],
  6.   separator: '-',
  7.   length: 2,
  8. };

  10. const randomName: string = uniqueNamesGenerator({
  11.   dictionaries: [adjectives, colors, animals]
  12. }); // big_red_donkey

  14. const shortName: string = uniqueNamesGenerator(customConfig); // big-donkey
  15. ```

API


uniqueNamesGenerator (options)


Returns a string with a random generated name

options


Type: Config

dictionaries


Type: array

required: true

This is an array of dictionaries. Each dictionary is an array of strings containing the words to use for generating the string.

The provided dictionaries can be imported from the library as a separate modules and provided in the desired order.

  1. ``` ts
  2. import { uniqueNamesGenerator, adjectives, colors, animals } from 'unique-names-generator';

  4. const shortName: string = uniqueNamesGenerator({
  5.   dictionaries: [colors, adjectives, animals]
  6. }); // red_big_donkey
  7. ```

Read more about the dictionaries and how to use them, in the Dictionaries section.

separator


Type: string

required: false

Default: _

A string separator to be used for separate the words generated. The default separator is set to _.

length


Type: number

required: false

Default: 3

The default value is set to 3 and it will return a name composed of 3 words. This values must be equal or minor to the number of dictionaries defined (3 by default). Setting the length to a value of 4 will throw an error when only 3 dictionaries are provided.

style


Type: lowerCase | upperCase | capital

required: false

Default: lowerCase

The default value is set to lowerCase and it will return a lower case name. By setting the value to upperCase, the words, will be returned with all the letters in upper case format. The capital option will capitalize each word of the unique name generated

  1. ``` ts
  2. import { uniqueNamesGenerator, adjectives, colors, animals } from 'unique-names-generator';

  4. const capitalizedName: string = uniqueNamesGenerator({
  5.   dictionaries: [colors, adjectives, animals],
  6.   style: 'capital'
  7. }); // Red_Big_Donkey

  9. const upperCaseName: string = uniqueNamesGenerator({
  10.   dictionaries: [colors, adjectives, animals],
  11.   style: 'upperCase'
  12. }); // RED_BIG_DONKEY

  14. const lowerCaseName: string = uniqueNamesGenerator({
  15.   dictionaries: [colors, adjectives, animals],
  16.   style: 'lowerCase'
  17. }); // red_big_donkey
  18. ```

seed


Type: number | string

required: false

A seed is used when wanting to deterministically generate a name. As long as the provided seed is the same the generated name will also always be the same.

  1. ``` ts
  2. import { uniqueNamesGenerator, adjectives, colors, animals } from 'unique-names-generator';
  3. const config: Config = {
  4.   dictionaries: [adjectives, colors, animals],
  5.   separator: '-',
  6.   seed: 120498,
  7. };

  9. const nameFromSeed: string = uniqueNamesGenerator(config); // continuous-gray-dragonfly
  10. ```

  1. ``` ts
  2. import { uniqueNamesGenerator, adjectives, colors, animals } from 'unique-names-generator';
  3. const config: Config = {
  4.   dictionaries: [adjectives, colors, animals],
  5.   separator: '-',
  6.   seed: 'you can use strings as a seed',
  7. };

  9. const nameFromSeed: string = uniqueNamesGenerator(config); // stable-crimson-porpoise
  10. ```

Dictionaries available


Numbers


This is a dynamic dictionary. Read more in the Numbers Dictionary section

Adjectives


A list of more than 1,400 adjectives ready for you to use

  1. ``` ts
  2. import { uniqueNamesGenerator, Config, adjectives } from 'unique-names-generator';

  4. const config: Config = {
  5.   dictionaries: [adjectives]
  6. }

  8. const characterName: string = uniqueNamesGenerator(config); // big
  9. ```

Animals


A list of more than 350 animals ready to use

  1. ``` ts
  2. import { uniqueNamesGenerator, Config, animals } from 'unique-names-generator';

  4. const config: Config = {
  5.   dictionaries: [animals]
  6. }

  8. const characterName: string = uniqueNamesGenerator(config); // donkey
  9. ```

Colors


A list of more than 50 different colors

  1. ``` ts
  2. import { uniqueNamesGenerator, Config, colors } from 'unique-names-generator';

  4. const config: Config = {
  5.   dictionaries: [colors]
  6. }

  8. const characterName: string = uniqueNamesGenerator(config); // red
  9. ```

Countries


A list of more than 250 different countries

  1. ``` ts
  2. import { uniqueNamesGenerator, Config, countries } from 'unique-names-generator';

  4. const config: Config = {
  5.   dictionaries: [countries]
  6. }

  8. const characterName: string = uniqueNamesGenerator(config); // United Arab Emirates
  9. ```

Names


A list of more than 4,900 unique names

  1. ``` ts
  2. import { uniqueNamesGenerator, Config, names } from 'unique-names-generator';

  4. const config: Config = {
  5.   dictionaries: [names]
  6. }

  8. const characterName: string = uniqueNamesGenerator(config); // Winona
  9. ```

Languages


A list of languages

  1. ``` ts
  2. import { uniqueNamesGenerator, Config, languages } from 'unique-names-generator';

  4. const config: Config = {
  5.   dictionaries: [languages]
  6. }

  8. const characterName: string = uniqueNamesGenerator(config); // polish
  9. ```

Star Wars


A list of more than 80 unique character names from Star Wars

  1. ``` ts
  2. import { uniqueNamesGenerator, Config, starWars } from 'unique-names-generator';

  4. const config: Config = {
  5.   dictionaries: [starWars]
  6. }

  8. const characterName: string = uniqueNamesGenerator(config); // Han Solo
  9. ```

Default dictionaries


By default, the Unique name generator library comes with 3 dictionaries out of the box, so that you can use them straight away. Starting from the version 4 of the library, however, you must explicitly provide the dictionaries within the configuration object. This is for reducing the bundle size and allowing tree shaking to remove the extra dictionaries from your bundle when using custom ones.

The new syntax for using the default dictionaries is the following:

  1. ``` ts
  2. import { uniqueNamesGenerator, Config, adjectives, colors, animals } from 'unique-names-generator';

  4. const config: Config = {
  5.   dictionaries: [adjectives, colors, animals]
  6. }

  8. const characterName: string = uniqueNamesGenerator(config); // red_big_donkey
  9. ```

Custom dictionaries


You might want to provide your custom dictionaries to use for generating your unique names, in order to meet your business requirements.

You can easily do that using the dictionaries option.

  1. ``` ts
  2. import { uniqueNamesGenerator } from 'unique-names-generator';

  4. const starWarsCharacters = [
  5.   'Han Solo',
  6.   'Jabba The Hutt',
  7.   'R2-D2',
  8.   'Luke Skywalker',
  9.   'Princess Leia Organa'
  10. ];
  11. const colors = [
  12.   'Green', 'Red', 'Yellow', 'Black'
  13. ]

  15. const characterName: string = uniqueNamesGenerator({
  16.   dictionaries: [colors, starWarsCharacters],
  17.   length: 2,
  18.   separator: ' '
  19. }); // Green Luke Skywalker
  20. ```

Numbers Dictionary


You can easily generate random numbers inside your unique name using the Numbers dictionary helper.

  1. ``` ts
  2. import { uniqueNamesGenerator, NumberDictionary } from 'unique-names-generator';

  4. const numberDictionary = NumberDictionary.generate({ min: 100, max: 999 });
  5. const characterName: string = uniqueNamesGenerator({
  6. dictionaries: [['Dangerous'], ['Snake'], numberDictionary],
  7.   length: 3,
  8.   separator: '',
  9.   style: 'capital'
  10. }); // DangerousSnake123
  11. ```

Numbers Dictionary API


generate (options)


Returns a string with a random generated number between 1 and 999

options


Type: Config

min


Type: number

required: false

default: 1

The minimum value to be returned as a random number

max


Type: number

required: false

default: 999

The maximum value to be returned as a random number

length


Type: number

required: false

The length of the random generated number to be returned.

Setting a length of 3 will always return a random number between 100 and 999. This is the same as setting 100 and 999 as min and max option.

NoteIf set, this will ignore any min and max options provided.

Combining custom and provided dictionaries


You can reuse the dictionaries provided by the library. Just import the ones that you need and use them directly in your app.

  1. ``` ts
  2. import { uniqueNamesGenerator, adjectives, colors } from 'unique-names-generator';

  4. const improvedAdjectives = [
  5.   ...adjectives,
  6.   'abrasive',
  7.   'brash',
  8.   'callous',
  9.   'daft',
  10.   'eccentric',
  11. ];
  12. const xMen = [
  13. 'professorX',
  14. 'beast',
  15. 'colossus',
  16. 'cyclops',
  17. 'iceman',
  18. 'wolverine',
  19. ];

  21. const characterName: string = uniqueNamesGenerator({
  22.   dictionaries: [improvedAdjectives, color, xMen],
  23.   length: 2,
  24.   separator: '-'
  25. }); // eccentric-blue-iceman
  26. ```

Migration guide


Migration guide from version 3 to version 4


Unique names generator v4 implement a new breaking change.

Mandatory dictionaries config


You must now explicitly provide the library with the dictionaries to use. This is for improving flexibility and allowing tree-shaking to remove the unused dictionaries from your bundle size.

Read more about the dictionaries in the Dictionaries section.

v3

  1. ``` ts
  2. import { uniqueNamesGenerator } from 'unique-names-generator';

  4. const randomName = uniqueNamesGenerator(); // big_red_donkey
  5. ```

v4

  1. ``` ts
  2. import { uniqueNamesGenerator, Config, adjectives, colors, animals } from 'unique-names-generator';

  4. const config: Config = {
  5.   dictionaries: [adjectives, colors, animals]
  6. }

  8. const randomName = uniqueNamesGenerator(config); // big_red_donkey
  9. ```

Migration guide from version 1 or 2


Unique names generator v3 implements a couple of breaking changes. If are upgrading your library from a version 1 or 2, you might be interested in knowing the following:

uniqueNamesGenerator


This will now work only when a dictionaries array is provided according to the v4 breaking change.

v2

  1. ``` ts
  2. import { uniqueNamesGenerator } from 'unique-names-generator';

  4. const randomName = uniqueNamesGenerator();
  5. ```

v4

  1. ``` ts
  2. import { uniqueNamesGenerator, Config, adjectives, colors, animals } from 'unique-names-generator';

  4. const config: Config = {
  5.   dictionaries: [adjectives, colors, animals]
  6. }

  8. const randomName = uniqueNamesGenerator(config); // big_red_donkey
  9. ```

Separator


v2

  1. ``` ts
  2. import { uniqueNamesGenerator } from 'unique-names-generator';

  4. const shortName = uniqueNamesGenerator('-'); // big-red-donkey
  5. ```

v4

  1. ``` ts
  2. import { uniqueNamesGenerator, Config, adjectives, colors, animals } from 'unique-names-generator';

  4. const config: Config = {
  5.   dictionaries: [adjectives, colors, animals],
  6.   separator: '-'
  7. }

  9. const shortName = uniqueNamesGenerator(config); // big-red-donkey
  10. ```

Short


The short property has been replaced by length so you can specify as many word as you want

v2

  1. ``` ts
  2. import { uniqueNamesGenerator } from 'unique-names-generator';

  4. const shortName = uniqueNamesGenerator(true); // big-donkey
  5. ```

v4

  1. ``` ts
  2. import { uniqueNamesGenerator, Config, adjectives, colors, animals } from 'unique-names-generator';

  4. const config: Config = {
  5.   dictionaries: [adjectives, colors, animals],
  6.   length: 2
  7. }

  9. const shortName = uniqueNamesGenerator(config); // big-donkey
  10. ```

Contributing


Please read CONTRIBUTING.md for details on our code of conduct, and the process for submitting pull requests to us.

Fork it!
Create your feature branch: git checkout -b my-new-feature
Add your changes: git add .
Commit your changes: git commit -am 'Add some feature'
Push to the branch: git push origin my-new-feature
Submit a pull request 😎

License


MIT License © Andrea SonnY