README
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. |