README.md

Short key generator

Why?

To reduce size of JSON with a large data set that is transmitted over the network. I've seen this in quite a few projects - always done from scratch and usually not very well.

Problem

var toSend = {
  data: [
    {
      selfExplanatoryKey1: 11,
      selfExplanatoryKey2: 22,
      ...
      selfExplanatoryKeyN: 997
    },
    {
      selfExplanatoryKey1: 66,
      selfExplanatoryKey2: 77,
      ...
    },
  ]
};

The stringified JSON gets very large because of the long self-explanatory keys.

Solution

var toSend = {
  data: [
    {
      A: 11,
      B: 22,
      ...
      Cm: 997
    },
    {
      A: 66,
      B: 77,
      ...
    },
  ],
  map: {
    selfExplanatoryKey1: 'A',
    selfExplanatoryKey2: 'B',
    ....
    selfExplanatoryKeyN: 'Cm'
  }
};

Basic Usage

var keyMapFactory = require('short-key-generator');
var keyMap = keyMapFactory();
keyMap.getOrCreate('selfExplanatoryKey1'); // 'A'
keyMap.getOrCreate('selfExplanatoryKey2'); // 'B'
keyMap.getOrCreate('selfExplanatoryKey1'); // 'A'

// map object keys and keep the values unchanged
keyMap.mapObjectKeys({
  selfExplanatoryKey2: 1,
  selfExplanatoryKey3: {selfExplanatoryKey4: 2}
}); // {'B': 1, 'C': {selfExplanatoryKey4: 2}}

keyMap.getMap();
// returns
//  {
//    selfExplanatoryKey1: 'A',
//    selfExplanatoryKey2: 'B',
//    selfExplanatoryKey3: 'C'
//  }

// if you need inverted map like {A: 'selfExplanatoryKey1'}, use
keyMap.getIvertedMap();

API Reference

The default export of this module is ~keyMap(). That and probably ~characterRange() are the only things you need. The other module members (classes) are exported just in case you feel like you want to extend them and it is not worth a pull request.

• short-key-generator
  • ~KeyMap
    • .getOrCreate(longKey) ⇒ string
    • .getKey(longKey) ⇒ string | undefined
    • .mapObjectKeys(obj) ⇒ Object
    • .getMap() ⇒ Object
    • .getInvertedMap() ⇒ Object
  • ~SequentialKeyGen
    • .getNextKey() ⇒ string
  • ~characterRange(firstChar, lastChar, optStep) ⇒ Array.<string>
  • ~keyMap() ⇒ KeyMap
  • ~sequentialKeyGen() ⇒ SequentialKeyGen

~~KeyMap

Kind: inner class of short-key-generator

• ~KeyMap
  • .getOrCreate(longKey) ⇒ string
  • .getKey(longKey) ⇒ string | undefined
  • .mapObjectKeys(obj) ⇒ Object
  • .getMap() ⇒ Object
  • .getInvertedMap() ⇒ Object

keyMap.getOrCreate(longKey) ⇒ string

Get an existing short key for provided long key. If it doesn't exist, new short key is created

Kind: instance method of KeyMap

Param	Type
longKey	string

keyMap.getKey(longKey) ⇒ string | undefined

Get an existing short key for provided long key

Kind: instance method of KeyMap
Returns: string | undefined - undefined if there is no entry for longKey

Param	Type
longKey	string

keyMap.mapObjectKeys(obj) ⇒ Object

Utility method to rename object keys

Kind: instance method of KeyMap
Returns: Object - new object with original values

Param	Type
obj	Object

keyMap.getMap() ⇒ Object

Kind: instance method of KeyMap
Returns: Object - map of all entries: {longKey: shortKey}

keyMap.getInvertedMap() ⇒ Object

Kind: instance method of KeyMap
Returns: Object - map of all entries: {shortKey: longKey}

~~SequentialKeyGen

Kind: inner class of short-key-generator

sequentialKeyGen.getNextKey() ⇒ string

Generate new key

Kind: instance method of SequentialKeyGen

~~characterRange(firstChar, lastChar, optStep) ⇒ Array.<string>

Utility function to create a range/array of characters

Kind: inner method of short-key-generator
Returns: Array.<string> - array of characters

Param	Type	Description
firstChar	string	first character of the desired range - first character of the provided string is used - non-strings are coverted to string - if no character (empty string) is provided, empty array is returned
lastChar	string	last character of the desired range; same behavior as firstChar
optStep	string	step - default is one, decimals are floored, 0 converted to 1

~~keyMap() ⇒ KeyMap

Function creating new instance of KeyMap

Kind: inner method of short-key-generator

Param	Type	Default	Description
[options.initInvertedMap]	Object.<string, string>	Object()	initialize map, e.g. {shortKey: 'longKey'}
[options.alphabet]	Array.<string>	['A'-'Z']	strings used to generate new keys
[options.initCounter]	number	0	use if you want to skip a few keys at the beginning
[options.glueFn]	function	fragments => fragments.join('')	keys are created with one or more strings from the alphabet. By default, they are combined with .join('')

~~sequentialKeyGen() ⇒ SequentialKeyGen

Function creating new instance of SequentialKeyGen Exported as member sequentialKeyGen

Kind: inner method of short-key-generator

Param	Type	Default	Description
[options.alphabet]	Array.<string>	['A'-'Z']	strings used to generate new keys
[options.initCounter]	number	0	use if you want to skip a few keys at the beginning
[options.glueFn]	function	fragments => fragments.join('')	keys are created with one or more strings from the alphabet. By default, they are combined with .join('')

Contributing

Feel free to suggest new features or create pull requests (PR). With PR, keep the test coverage at 100% ;)

Clone the repo and develop new feature or bug fix

$ git clone https://github.com/stropho/short-key-generator.git
$ cd short-key-generator
$ npm i
$ npm run test:unit:watch

Tests autamatically run on change in src/ or test/ folder.

To run other tasks like linter, coverage or build, simply run

$ npm run all

Basic concept

• JavaScript ES6
• ES6 Transpiler
  • babel
• Build system
  • gulp
• Test framework
  • mocha
  • istanbul & nyc
• Code style
  • idiomatic
  • eslint (using JS code style idiomatic)

Script Tasks

build

Build the code from ./src, store in ./dist

$ npm run build

Test

## Unit tests
$ npm run test:unit

## All tests and linter for test files
$ npm run test

Test coverage

$ npm run coverage

Linting

## Lint `./src`
$ npm run lint

## Lint './test`
$ npm run lint:test