keymap
keymap
is a tool for compacting/expanding keys in an object. Its main use
is to process objects before saving them to the database/cache and after
retrieving them.
The motivation behind it was to make objects smaller before storing them in a database, such as MongoDB, for example, saving a reasonable amount of disk space.
Installation
As usual, just run npm install keymap
.
Usage
var keymap = map = ; map; // returns {f : 'foo', b : 'bar'}mapcompact foo : 'foo' bar : 'bar';
Defining keys
keymap
gives you some options as to how to define your keys and
abbreviations. The keymap()
function accepts one optional argument, which
can be either an object containing a key-abbr map (see #add()
) or a string
with the path to a file containing the mapping (see #import()
below).
If you wish to define or key-abbr pairs directly in your code,
you may use the #add()
method:
// Passing a key-abbr pair to #add()map ; map; //> 'f' // Passing an object to #add()map; map; //> 'b'map; //> 'baz'
Both will have exactly the same result.
If you wish to store your abbreviations in another file, you may use the
#import()
method to import your key-abbr maps. The #import()
method
takes a filepath as an argument. The file must be requirable, that is, must
work with require()
. keymap
uses the js-yaml package to make this
work with Yaml files.
// Works with json filesmap; // Works with yaml filesmap; // Works with node modulesmap;
Both #add()
and #import()
are chainable:
map ;
Note that duplicate keys or abbreviations are not allowed and will throw an error if found.
// Duplicate abbreviations are not allowedmap; //> err // Duplicate keys are not allowed eithermap; //> err
Abbreviating and expanding your keys
Once your keymap is defined, there are four methods that process your keys and abbreviations:
- 2 abbreviation/compacting methods
- 2 expansion methods
Use #getAbbr()
and #getKey()
to retrive the abbreviation or the original
form of simple strings.
map; map; //> 'f'map; //> 'foo' // They work with dot-separated keys...map; //> 'f.b'map; //> 'foo.bar' // and with an array too.map; //> ['f', 'b']map; //> ['foo', 'bar']
These methods default to the original value if no abbr/key is found:
map; map; //> 'foobar'map; //> 'foobar'
#compact()
and #expand()
work on entire objects:
map
They will compact/expand keys in nested objects too:
// Objects inside objectsmapcompactfoo : bar : 'baz'; //> {f : {b : 'baz'}} // Objects in arraysmapcompactfoo : 'bar'; //> [{f : 'bar'}]
But there's one caveat: it works only with object literals. Any other object will be returned as is.
var now = ;mapcompactnow === now; //> true
Also note that #compact()
and #expand()
won't have the same behavior as
#getAbbr()
and #getKeys()
when they receive a string. They will NOT try
to abbreviate/expand it, returning the original value.
map;map; //> 'f'mapcompact'foo'; //> 'foo' map; //> 'foo'map; //> 'f'
Contributing
Feel free to submit any patches or report any issues. I'll do my best to check them as quick as possible (in a few days, usually). When submitting a patch, please add your name and link to the author section below.
Issues and patches regarding grammar errors in code comments and docs are welcome as well. : )
Author
Created by Mathias Kretschek (mkretschek).