Keystone 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 ifarg
is a function -
isObject(arg)
- determines ifarg
is an object -
isValidObjectId(arg)
- determines ifarg
looks like a valid MongoDB ObjectId -
isArray(arg)
- determines ifarg
is an array -
isDate(arg)
- determines ifarg
is a date -
isString(arg)
- determines ifarg
is a string -
isNumber(arg)
- determines ifarg
is a number -
isDataURL(arg)
- determines ifarg
is a base64 encoded data URI -
isEmail(arg)
- make surearg
looks 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 defaults -
optionsMap(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
clone
is 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 containment -
bindMethods(obj, scope)
- recursively binds method properties ofobj
toscope
and 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).-
len
can be an array of[min, max]
length to generate -
chars
is 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 expression -
escapeString(str)
- escapes a string to be safely used as a Javascript string literal -
stripDiacritics(str)
- stips accented characters from a string, replacing them with their simple equivalents -
transliterate(str)
- transliterates Russian and Ukrainian words from cyrillic to latin -
singular(str)
- converts a string to its singular form -
plural(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
singular
toplural
when 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 Uppercase -
downcase(str)
- converts the first letter in a string to lowercase -
titlecase(str)
- converts a string to Title Case -
camelcase(str, lowercase)
- converts a string to camelCase- The
lowercase
argument causes the first letter to be lowercase, and default totrue
.
- The
-
decodeHTMLEntities(str)
- decodes html entities in a string -
encodeHTMLEntities(str)
- encodes html entities in a string -
stringify(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
,th
tags 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-markdown
andhtml-to-text
packages 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
preserveWords
is 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 HTML -
slug(str, separator)
- generates a slug from a string. Word breaks are hyphenated.-
separator
defaults 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
keyToPath
but converts to headlessCamelCase instead of dash-separated
- Like
-
calculateDistance(point1 [lat, lng], point2 [lat, lng])
- Returns the distance between two[lat,lng]
points in radians -
kmBetween
- Returns the distance between two[lat,lng]
points in kilometers -
milesBetween
- 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