fepper-utils

Fepper Utilities

If you are creating a Fepper extension:

npm install --save fepper-utils

Then, require in your JavaScript:

const utils = require('fepper-utils');
const property = utils.deepGet(obj, 'path.to.nested.property');

Functions

t(key) ⇒ string

Translate using an English key.

beautifyTemplate(extendedTemplate) ⇒ string

Beautify an HTML-like template. Any Feplet/Mustache code within will be beautified as well.

deepGet(obj, path) ⇒ * | null

Get data from a nested property within an object.

extendButNotOverride(...objects) ⇒ object

Recursively merge properties of two or more objects into the first object.

regexReservedCharsEscape(regexStr) ⇒ string

Escape reserved regular expression characters.

shuffle(a) ⇒ array

Shuffle the elements of an array with the Fisher-Yates algorithm.

strReplaceGlobal(haystack, needle, replacement) ⇒ string

More efficient global string replace than String.prototype.replace.

backendDirCheck(backendDir) ⇒ string

Validate existence of a backend subdirectory.

rmRfFilesNotDirs(dirToEmpty)

Recursively empty a directory of files, but not nested directories.

extNormalize(ext) ⇒ string

Normalize a file extension. Ensure that it is trimmed of extraneous whitespace, contains only valid characters, and is prepended with a dot if it was omitted as the first valid character.

findup(filename, workDir) ⇒ string

Search the file system from a starting directory upward.

pathResolve(...pathSegments) ⇒ string

Concatenate and normalize path segments, and also ensure that path separators are forward-slashes. Resolution will not occur with the file system, so relative paths will stay relative and wrong paths will stay wrong. Accepts string arguments to be concatenated into a forward-slash separated path.

uiConfigNormalize(uiObj, workDir, [appDir]) ⇒ object

Normalize UI config values. Strip leading dot+slashes and trailing slashes from relative paths and save. Turn relative paths into absolute paths and save. Prepend leading dots to extension nnames if necessary.

error(...args)

Abstract console.error to not trigger lint warnings/errors. Outputs the error in red text.

i(obj, [depth], [showHidden])

"i" for "inspect". Shorthand for util.inspect or console.dir. This exists primarily for internal debugging.

info(...args)

Abstract console.info to not trigger lint warnings/errors. Outputs the info in green text.

log(...args)

Abstract console.log to not trigger lint warnings/errors.

warn(...args)

Abstract console.warn to not trigger lint warnings/errors. Outputs the warning in yellow text.

webservedDirnamesTruncate(webservedDirsFull) ⇒ array

Remove first path segment from values in webservedDirsFull array. Return a new array composed of these new values.

webservedDirsCopy(webservedDirsFull, webservedDirsShort, staticDir)

Copy webserved dirs to static site dir.

t(key) ⇒ string

Translate using an English key.

Kind: exported function
Returns: string - The phrase in another language (or an English alternative).

Param	Type	Description
key	string	The phrase in English.

beautifyTemplate(extendedTemplate) ⇒ string

Beautify an HTML-like template. Any Feplet/Mustache code within will be beautified as well.

Kind: exported function
Returns: string - The beautified template code.

Param	Type	Description
extendedTemplate	string	The string contents of an HTML-like template.

deepGet(obj, path) ⇒ * | null

Get data from a nested property within an object.

Kind: exported function
Returns: * | null - The retrieved data or null on failure.

Param	Type	Description
obj	object	The object from which to get the data.
path	string | array	Dot-notation string to the nested property, or array of keys if dot-notation won't work.

extendButNotOverride(...objects) ⇒ object

Recursively merge properties of two or more objects into the first object.

Kind: exported function
Returns: object - The mutated first object.

Param	Type	Description
...objects	object	The objects to get merged. The first object will not have its properties overwritten. It will be extended with additional properties from the additional objects. Since the first object gets mutated, the return value is only necessary for referencing to a new variable.

regexReservedCharsEscape(regexStr) ⇒ string

Escape reserved regular expression characters.

Kind: exported function
Returns: string - A regular expression with escaped reserved characters.

Param	Type	Description
regexStr	string	The regular expression with unescaped reserved characters.

shuffle(a) ⇒ array

Shuffle the elements of an array with the Fisher-Yates algorithm.

Kind: exported function
Returns: array - Shuffled array.
See

• https://stackoverflow.com/questions/6274339/how-can-i-shuffle-an-array
• https://en.wikipedia.org/wiki/Fisher%E2%80%93Yates_shuffle
• https://github.com/e2tha-e/js-shuffle-algorithms

Param	Type	Description
a	array	Array to be shuffled. Since a gets mutated, the return value is only necessary for the purpose of referencing to a new variable.

strReplaceGlobal(haystack, needle, replacement) ⇒ string

More efficient global string replace than String.prototype.replace.

Kind: exported function
Returns: string - Modified full string.

Param	Type	Description
haystack	string	Full string to be modified.
needle	string	The substring to be replaced.
replacement	string	The substring to replace needle.

backendDirCheck(backendDir) ⇒ string

Validate existence of a backend subdirectory.

Kind: exported function
Returns: string - A valid absolute path to the backend subdirectory, or an empty string.

Param	Type	Description
backendDir	string	The path to a subdirectory of the backend.

rmRfFilesNotDirs(dirToEmpty)

Recursively empty a directory of files, but not nested directories.

Kind: exported function

Param	Type	Description
dirToEmpty	string	Directory to empty.

extNormalize(ext) ⇒ string

Normalize a file extension. Ensure that it is trimmed of extraneous whitespace, contains only valid characters, and is prepended with a dot if it was omitted as the first valid character.

Kind: exported function
Returns: string - A normalized file extension, or an empty string if it fails validation.

Param	Type	Description
ext	string	File extension.

findup(filename, workDir) ⇒ string

Search the file system from a starting directory upward.

Kind: exported function
Returns: string - The absolute path to the found file or an empty string if the search fails.

Param	Type	Description
filename	string	The file being searched for.
workDir	string	The absolute path where the search starts.

pathResolve(...pathSegments) ⇒ string

Concatenate and normalize path segments, and also ensure that path separators are forward-slashes. Resolution will not occur with the file system, so relative paths will stay relative and wrong paths will stay wrong. Accepts string arguments to be concatenated into a forward-slash separated path.

Kind: exported function
Returns: string - Path.

Param	Type	Description
...pathSegments	string	Path or path segments.

uiConfigNormalize(uiObj, workDir, [appDir]) ⇒ object

Normalize UI config values. Strip leading dot+slashes and trailing slashes from relative paths and save. Turn relative paths into absolute paths and save. Prepend leading dots to extension nnames if necessary.

Kind: exported function
Returns: object - The mutated uiObj.

Param	Type	Description
uiObj	object	The UI configuration object. Since uiObj gets mutated, the return value is only necessary for the purpose of referencing to a new variable.
workDir	string	The absolute path to the directory directly above the relative paths in the uiObj.
[appDir]	string	The absolute path to the fepper-npm directory. Only necessary when Pattern Lab is instantiated without Fepper.

error(...args)

Abstract console.error to not trigger lint warnings/errors. Outputs the error in red text.

Kind: exported function

Param	Type	Description
...args	*	Same arguments as console.error.

i(obj, [depth], [showHidden])

"i" for "inspect". Shorthand for util.inspect or console.dir. This exists primarily for internal debugging.

Kind: exported function

Param	Type	Default	Description
obj	object		The object to inspect.
[depth]	null | number	null	Number of times to recurse while inspecting the object. null means infinity.
[showHidden]	boolean	false	Whether the object's non-enumerable properties will be included in the result.

info(...args)

Abstract console.info to not trigger lint warnings/errors. Outputs the info in green text.

Kind: exported function

Param	Type	Description
...args	*	Same arguments as console.info.

log(...args)

Abstract console.log to not trigger lint warnings/errors.

Kind: exported function

Param	Type	Description
...args	*	Same arguments as console.log.

warn(...args)

Abstract console.warn to not trigger lint warnings/errors. Outputs the warning in yellow text.

Kind: exported function

Param	Type	Description
...args	*	Same arguments as console.warn.

webservedDirnamesTruncate(webservedDirsFull) ⇒ array

Remove first path segment from values in webservedDirsFull array. Return a new array composed of these new values.

Kind: exported function
Returns: array - The webserved directories stripped of configuration prefix.

Param	Type	Description
webservedDirsFull	array	The array of webserved directories.

webservedDirsCopy(webservedDirsFull, webservedDirsShort, staticDir)

Copy webserved dirs to static site dir.

Kind: exported function

Param	Type	Description
webservedDirsFull	array	Path to directories webserved by Fepper.
webservedDirsShort	array	Path to directories webserved by Fepper truncated for publishing to static site.
staticDir	string	The destination directory.