Kng-engine NPM

kng-engine

How to try?

Check out configurator side-project https://github.com/Keiwen/kng-config

What is about?

The Keiwen Name Generator Engine aims to generate random names. It contains 4 specific parts:

Origin: represents the origin of the name (country, race, ...). It contains one or more compositions.
Composition: represents the name composition (first then last name, only a nickname, ...). It contains one or more components.
Component: represents a part of a full name (first name, last name, ...). It uses a process, that defines rules to generate a random name, based on entries given (the 'dictionary'). There are several types of processes, learn more in process documentation.

Process types

A process will generate a random name based on given entries (the 'dictionary'). Processes are using following boolean parameters to format output (default value is false):

Parameter	Description	Sample
`uppercaseFirst`	format first character to upper case	Name
`capitalize`	format name to upper case	NAME
`minimize`	format name to lower case	name

Raw list process

Raw list process aims to pick a random value among a list.

Dictionary sample:

Batman
Superman

Possible results:

Batman (50 %)
Superman (50 %)

Weighted list process

Weighted list process aims to pick a random value among a list, according to each element's weight (chance to be picked).

Each entry should be defined with an associated weight (or default weight is used).

Weighted list allow defaultWeight attribute to set default weight on entries (1 by default)

Dictionary sample:

Batman (weight 3)
Superman (weight 1)

Possible results:

Batman (75 % = 3/4)
Superman (25 % = 1/4)

Sequence process

Sequence process aims to build a random value following a list of characters group. It randomly picks a value among each entry.

Dictionary sample:

Super / Bat
man / girl

Possible results:

Superman (25 %)
Supergirl (25 %)
Batman (25 %)
Batgirl (25 %)

Char group pattern process

Char group pattern process aims to build a random value following a given pattern. Each entry contains a group of characters, identified by a key. On generation, it will follow the pattern to pick a random value from matching entry. If no match found, generated name will keep this value.

Each entry must be defined with an associated key.

Parameter 'pattern' is required. If multiple values provided, a random one will be picked before generation.

Dictionary sample:

a (key a)
p / m (key b)

Possible results (with pattern 'ab' an 'a-b'):

ap (25 %)
am (25 %)
a-p (25 %)
a-m (25 %)

Markov process

Markov process aims to build a random name similar to given entries, based on a Markov chain (see markov chain on wikipedia). A Markov state represents a characters group. Its linked to other states (neighbors) representing next character groups possibilities. Neighbors weight is based on how often this combination is found in given entries. Generation will pick a random initial char, then randomly process markov chain and concatenate all characters found.

Parameter 'order' is required. It will determine how many characters are considered in a group.

Dictionary sample:

Manwë
Yavanna

Possible results (with order 2):

Manwë (25 %)
Yavanna (25 %)
Manna (25 %)
Yavanwë (25 %)

This process can also use specific parameters, as described below.

Parameter	Description	default
`minLength`	Minimum length of generated name	1
`maxLength`	Maximum length of generated name (-1 to ignore limit)	-1
`maxAttempts`	How many attempts are allowed to generate a name matching requirements	25
`allowDuplicates`	Allow generated name to exactly match one of the entry	`true`
`allowSubDuplicates`	Allow generated name to match a sub-part of one of the entry	`true`

Global use

npm install

npm install --save kng-engine

import classes you need

import { RawListKngProcess } from 'kng-engine'

Sample here of usa people with small percentage having french first name:

// english first name
let enFirstNameComponent = new RawListKngProcess('efn')
enFirstNameComponent.addListToDictionary(['Michael', 'Andrew', 'Ryan'])
// french first name
let frFirstNameComponent = new RawListKngProcess('ffn')
frFirstNameComponent.addListToDictionary(['Pierre', 'Nicolas', 'Jean'])
// english last name
let enLastNameComponent = new RawListKngProcess('eln')
enLastNameComponent.addListToDictionary(['Smith', 'Jones', 'Williams'])
// _______________________________
// full english composition
let enComposition = new KngNameComposition('en', ['first', 'last'])
enComposition.addNameComponent(enFirstNameComponent, 'first')
enComposition.addNameComponent(enLastNameComponent, 'last')
// french & english composition
let frEnComposition = new KngNameComposition('frEn', ['first', 'last'])
frEnComposition.addNameComponent(frFirstNameComponent, 'first')
frEnComposition.addNameComponent(enLastNameComponent, 'last')
// _______________________________
// origin
let usaOrigin = new KngOrigin('usa')
usaOrigin.addNameComposition(enComposition, 'en', 9)
usaOrigin.addNameComposition(frEnComposition, 'fr', 1)
// _______________________________
// engine creation
let engine = new KngEngine()
engine.addOrigin(usaOrigin)
return engine.generateName()