JedWatsonKeystone Utils
A useful library of utilities for node.js used by KeystoneJS and you!
It provides additional functionality for manipulating and converting various types of data, including converting strings between various forms, and lightweight html ← → text conversion.
Usage
npm install keystone-utils --save... then ...
var utils = require('keystone-utils');
console.log(utils.isObject({})); // true!Bundled with KeystoneJS
If you're using KeystoneJS, it exposes this library
as .utils.
var keystone = require('keystone');
var utils = keystone.utils;Test utilities
isFunction(arg)- determines ifargis a functionisObject(arg)- determines ifargis an objectisValidObjectId(arg)- determines ifarglooks like a valid MongoDB ObjectIdisArray(arg)- determines ifargis an arrayisDate(arg)- determines ifargis a dateisString(arg)- determines ifargis a stringisNumber(arg)- determines ifargis a numberisDataURL(arg)- determines ifargis a base64 encoded data URIisEmail(arg)- make surearglooks like a valid email address- Uses a regular expression to check, so may cause false-negatives in extremely rare cases. See http://www.regular-expressions.info/email.html
Option utilities
options(defaults, options)- copies and merges options into the defaultsoptionsMap(arr, property, clone)- creates a map of options- Turns an array of objects into an object of objects, with each object
under the value of
property - Performs a deep clone of the objects when
cloneis set to true
- Turns an array of objects into an object of objects, with each object
under the value of
Function utilities
noop()- a simple function that does nothing ("no operation")defer(fn, args...)- wraps the function and invokes it inprocess.nextTick, great for Zalgo containmentbindMethods(obj, scope)- recursively binds method properties ofobjtoscopeand returns a new object containing the bound methods.
Random utilities
randomString(len, chars)- Generates a 'random' string of characters to the specified length (uses Math.random).lencan be an array of[min, max]length to generatecharsis a string of characters to include, defaults to0123456789ABCDEFGHIJKLMNOPQRSTUVWXTZabcdefghiklmnopqrstuvwxyz
Conversion utilities
number(arg)- converts a string to a number, accepting human-friendly input- e.g.
1,432»1432,$1432»1432,2.5»2.5
- e.g.
escapeRegExp(str)- escapes a string to be safely converted to a regular expressionescapeString(str)- escapes a string to be safely used as a Javascript string literalstripDiacritics(str)- stips accented characters from a string, replacing them with their simple equivalentstransliterate(str)- transliterates Russian and Ukrainian words from cyrillic to latinsingular(str)- converts a string to its singular formplural(count, singular, plural)- displays the singular or plural of a string based on a number or number of items in an array.- Replaces
*in the string with the number - Will automatically convert
singulartopluralwhen plural is not provided - When only given one argument, will return the plural form of a string
- e.g.
plural(1, '* thing')»'1 thing'plural(2, '* thing')»'2 things'plural([1,2], 'single', 'couple')»'couple'plural('friend')»'friends'
- Replaces
upcase(str)- converts the first letter in a string to Uppercasedowncase(str)- converts the first letter in a string to lowercasetitlecase(str)- converts a string to Title Casecamelcase(str, lowercase)- converts a string to camelCase- The
lowercaseargument causes the first letter to be lowercase, and default totrue.
- The
decodeHTMLEntities(str)- decodes html entities in a stringencodeHTMLEntities(str)- encodes html entities in a stringstringify(obj)- safely stringifies an object to JSON for output in JavaScript source (escapes illegal JS but valid JSON unicode characters)textToHTML(str)- lightweight conversion of text to HTML (line breaks to<br>)htmlToText(str)- lightweight conversion to HTML to text- Really only useful when you need a lightweight way to remove html from a string before cropping it, so you don't end up with partial tags or an invalid DOM structure.
- It will convert
br,p,div,li,td,thtags to single line-breaks. All other tags are stripped. - Multiple line breaks are then compressed to a single line break, and leading / trailing white space is stripped.
- For a more sophisticated use-case, you should check out the
to-markdownandhtml-to-textpackages on npm.
cropString(str, length, append, preserveWords)- crops a string to the specified length- You can optionally provide a string to
append(only appended if the original string was longer than the specified length). - If
preserveWordsis true, the length is extended to the end of the last word that would have been cropped.
- You can optionally provide a string to
cropHTMLString(str, length, append, preserveWords)- crops an HTML string safely by converting it to text, cropping it, then converting it back to HTMLslug(str, separator)- generates a slug from a string. Word breaks are hyphenated.separatordefaults to '-'
keyToLabel(str)- converts a key to a label- e.g.
keyToLabel('myKey')»My Key
- e.g.
keyToPath(str, plural)- converts a key to a path- Like
slug(keyToLabel(str))but will optionally converts the last word to a plural. - e.g.
keyToPath('someThing', true)»some-things
- Like
keyToProperty(str, plural)- Converts a key to a property.- Like
keyToPathbut converts to headlessCamelCase instead of dash-separated
- Like
calculateDistance(point1 [lat, lng], point2 [lat, lng])- Returns the distance between two[lat,lng]points in radianskmBetween- Returns the distance between two[lat,lng]points in kilometersmilesBetween- Returns the distance between two[lat,lng]points in miles
Credits
Uses the inflect library for singular / plural conversion,
see https://github.com/pksunkara/inflect or npm info i
Some utils are borrowed from / inspired by mongoose/utils.js,
see https://github.com/LearnBoost/mongoose
HTML Entity encode / decode is based on code in node-html-to-text,
see https://github.com/werk85/node-html-to-text
The transliteration code is based on https://www.npmjs.org/package/transliteration.cyr