All the siFunciona system functions for stringing together functions and simplifying logic.
\r\nManage how strings are manipulated with these utilities.
\r\nSimplify working with object by providing array-like parsing. Also, provides cloning and merging along with accessors that always have a return value for optimal nesting.
\r\nSome number comparators and random number generators.
\r\nManage how functions are called with these utilities.
\r\nA "descriptor" is a flat, serializable snapshot of an object or array's shape: for each property, its type(s),\r\nwhether it's nullable, and - if the property's own value is itself an object/array - a reference to that nested\r\nvalue's own descriptor elsewhere in the same list, rather than nesting descriptors inside descriptors. This flat,\r\nreference-based structure is what lets these utilities walk deeply nested and even circular object graphs (an\r\nobject that contains itself, directly or indirectly) without infinite recursion, since a value that's already\r\nbeen described is simply pointed to again instead of re-described.
\r\nStart with describeObjectMap, which takes any real object or array and produces\r\nthis flat list of descriptors for you - the other functions here (comparing, merging, cloning descriptors) are\r\nbuilding blocks used internally, or useful once you already have descriptors to work with directly.
\r\nThe concrete use this module has earned its keep on: describing two objects and comparing the results tells\r\nyou whether they're the same shape and values even when they're different references entirely (see\r\nsameDescriptor/compareDescriptor) - useful\r\nanywhere you need to check that two objects genuinely match without caring whether they're literally the same\r\ninstance. A descriptor also doubles as a flat, structured summary of an object's shape, which can be handy for\r\ndiscussion or assessment purposes (e.g. describing what an object looks like without dumping the whole thing).
\r\nUtilities for building, merging, deduplicating and comparing arrays, plus a basic FIFO queue (BasicQueue) for\r\nuse with functionHelpers' queueManager/queueTimeout.
\r\nArray.<string>\r\n * [.ucFirst(str)](#module_stringHelpers.ucFirst) ⇒ string\r\n * [.titleCase(str)](#module_stringHelpers.titleCase) ⇒ string\r\n * [.strBeforeLast(str, search)](#module_stringHelpers.strBeforeLast) ⇒ string\r\n * [.strBefore(str, search)](#module_stringHelpers.strBefore) ⇒ string\r\n * [.strAfterLast(str, search)](#module_stringHelpers.strAfterLast) ⇒ string\r\n * [.strAfter(str, search)](#module_stringHelpers.strAfter) ⇒ string\r\n * [.snakeCase(str)](#module_stringHelpers.snakeCase) ⇒ string\r\n * [.regexEscape(str)](#module_stringHelpers.regexEscape) ⇒ string\r\n * [.makeRelativePath(fromFile, toFile)](#module_stringHelpers.makeRelativePath) ⇒ string\r\n * [.makeFilepath(root, [append])](#module_stringHelpers.makeFilepath) ⇒ string\r\n * [.kabobCase(str)](#module_stringHelpers.kabobCase) ⇒ string\r\n * [.camelCase(str)](#module_stringHelpers.camelCase) ⇒ string\r\n\r\n\r\n\r\n### stringHelpers.words(str) ⇒ Array.<string>\r\nSplit a string into sets of numbers or letters - the shared tokenizer behind camelCase/kabobCase/snakeCase/\r\ntitleCase, so each can rebuild the string in its own casing style.\r\n\r\n**Kind**: static method of [stringHelpers](#module_stringHelpers) \r\n\r\n| Param | Type | Description |\r\n| --- | --- | --- |\r\n| str | string | The string to split. |\r\n\r\n\r\n\r\n### stringHelpers.ucFirst(str) ⇒ string\r\nGiven a string, make the first character uppercase and the rest lowercase.\r\n\r\n**Kind**: static method of [stringHelpers](#module_stringHelpers) \r\n\r\n| Param | Type | Description |\r\n| --- | --- | --- |\r\n| str | string | The string to convert. |\r\n\r\n\r\n\r\n### stringHelpers.titleCase(str) ⇒ string\r\nGiven a string in kebab-case, snake_case, camelCase or 'Sentence case', convert to 'Title Case'.\r\n\r\n**Kind**: static method of [stringHelpers](#module_stringHelpers) \r\n\r\n| Param | Type | Description |\r\n| --- | --- | --- |\r\n| str | string | The string to convert. |\r\n\r\n\r\n\r\n### stringHelpers.strBeforeLast(str, search) ⇒ string\r\nRetrieve the string part before the last search match.\r\n\r\n**Kind**: static method of [stringHelpers](#module_stringHelpers) \r\n**Returns**: string - The portion of `str` before the last occurrence of `search`, or `''` if not found. \r\n\r\n| Param | Type | Description |\r\n| --- | --- | --- |\r\n| str | string | The string to search within. |\r\n| search | string | The substring to search for. |\r\n\r\n\r\n\r\n### stringHelpers.strBefore(str, search) ⇒ string\r\nRetrieve the string part before the search match.\r\n\r\n**Kind**: static method of [stringHelpers](#module_stringHelpers) \r\n**Returns**: string - The portion of `str` before the first occurrence of `search`, or `''` if not found. \r\n\r\n| Param | Type | Description |\r\n| --- | --- | --- |\r\n| str | string | The string to search within. |\r\n| search | string | The substring to search for. |\r\n\r\n\r\n\r\n### stringHelpers.strAfterLast(str, search) ⇒ string\r\nRetrieve the string part after the last search match.\r\n\r\n**Kind**: static method of [stringHelpers](#module_stringHelpers) \r\n**Returns**: string - The portion of `str` after the last occurrence of `search`, or `''` if not found. \r\n\r\n| Param | Type | Description |\r\n| --- | --- | --- |\r\n| str | string | The string to search within. |\r\n| search | string | The substring to search for. |\r\n\r\n\r\n\r\n### stringHelpers.strAfter(str, search) ⇒ string\r\nRetrieve the string part after the search match.\r\n\r\n**Kind**: static method of [stringHelpers](#module_stringHelpers) \r\n**Returns**: string - The portion of `str` after the first occurrence of `search`, or `''` if not found. \r\n\r\n| Param | Type | Description |\r\n| --- | --- | --- |\r\n| str | string | The string to search within. |\r\n| search | string | The substring to search for. |\r\n\r\n\r\n\r\n### stringHelpers.snakeCase(str) ⇒ string\r\nGiven a string in kebab-case, camelCase or 'Sentence case', convert to snake_case.\r\n\r\n**Kind**: static method of [stringHelpers](#module_stringHelpers) \r\n\r\n| Param | Type | Description |\r\n| --- | --- | --- |\r\n| str | string | The string to convert. |\r\n\r\n\r\n\r\n### stringHelpers.regexEscape(str) ⇒ string\r\nTake a string and escape the regex characters.\r\n\r\n**Kind**: static method of [stringHelpers](#module_stringHelpers) \r\n\r\n| Param | Type | Description |\r\n| --- | --- | --- |\r\n| str | string | The string to escape, so it can be used literally inside a `RegExp`. |\r\n\r\n\r\n\r\n### stringHelpers.makeRelativePath(fromFile, toFile) ⇒ string\r\nCompare two file paths and simplify them to a relative path.\r\n\r\n**Kind**: static method of [stringHelpers](#module_stringHelpers) \r\n**Returns**: string - `toFile` expressed relative to `fromFile`. \r\n\r\n| Param | Type | Description |\r\n| --- | --- | --- |\r\n| fromFile | string | The path of the file the resulting relative path will be used from. |\r\n| toFile | string | The path of the file being referenced. |\r\n\r\n\r\n\r\n### stringHelpers.makeFilepath(root, [append]) ⇒ string\r\nFormat the given path so that it does not have trailing slashes and also correctly appends a path.\r\n\r\n**Kind**: static method of [stringHelpers](#module_stringHelpers) \r\n\r\n| Param | Type | Default | Description |\r\n| --- | --- | --- | --- |\r\n| root | string | | The base path to start from. |\r\n| [append] | string | "''" | A path to append to `root` - may itself use `./` or `../` segments. |\r\n\r\n\r\n\r\n### stringHelpers.kabobCase(str) ⇒ string\r\nGiven a string in snake_case, camelCase or 'Sentence case', convert to kabob-case.\r\n\r\n**Kind**: static method of [stringHelpers](#module_stringHelpers) \r\n\r\n| Param | Type | Description |\r\n| --- | --- | --- |\r\n| str | string | The string to convert. |\r\n\r\n\r\n\r\n### stringHelpers.camelCase(str) ⇒ string\r\nGiven a string in kebab-case, snake_case or 'Sentence case', convert to camelCase.\r\n\r\n**Kind**: static method of [stringHelpers](#module_stringHelpers) \r\n\r\n| Param | Type | Description |\r\n| --- | --- | --- |\r\n| str | string | The string to convert. |\r\n\r\n\r\n\r\n## objectHelpers\r\nSimplify working with object by providing array-like parsing. Also, provides cloning and merging along with accessors that always have a return value for optimal nesting.\r\n\r\n**Version**: 1.0.0 \r\n**Author**: Joshua Heagle \\*\r\n * [.mergeObjects](#module_objectHelpers.mergeObjects) ⇒ \\*\r\n * [.setValue(key, value, item)](#module_objectHelpers.setValue) ⇒ Object \\| Array\r\n * [.setAndReturnValue(item, key, value)](#module_objectHelpers.setAndReturnValue) ⇒ \\*\r\n * [.reduceObject(obj, fn, [initialValue])](#module_objectHelpers.reduceObject) ⇒ \\*\r\n * [.objectValues(object, [includeInherited])](#module_objectHelpers.objectValues) ⇒ Array\r\n * [.objectKeys(object, [includeInherited])](#module_objectHelpers.objectKeys) ⇒ Array.<(string\\|number)>\r\n * [.mergeObjectsBase([options])](#module_objectHelpers.mergeObjectsBase) ⇒ module:objectHelpers~mergeObjectsCallback \\| mergeObjectsCallback\r\n * [.mapObject(obj, fn, [thisArg])](#module_objectHelpers.mapObject) ⇒ Object \\| Array\r\n * [.isObject(object)](#module_objectHelpers.isObject) ⇒ boolean\r\n * [.isInstanceObject(object)](#module_objectHelpers.isInstanceObject) ⇒ boolean\r\n * [.isEqual(first, second)](#module_objectHelpers.isEqual) ⇒ boolean\r\n * [.isCloneable(value)](#module_objectHelpers.isCloneable) ⇒ boolean\r\n * [.filterObject(obj, fn, [thisArg])](#module_objectHelpers.filterObject) ⇒ Object \\| Array\r\n * [.emptyObject(item)](#module_objectHelpers.emptyObject) ⇒ boolean\r\n * [.dotUnset(arrayObject, dotNotation)](#module_objectHelpers.dotUnset) ⇒ Object\r\n * [.dotSet(arrayObject, dotNotation, value)](#module_objectHelpers.dotSet) ⇒ Object\r\n * [.dotNotate(arrayObject, [retainObjects])](#module_objectHelpers.dotNotate) ⇒ DotNotatedObject\r\n * [.dotGet(arrayObject, dotNotation, [defaultValue])](#module_objectHelpers.dotGet) ⇒ \\*\r\n * [.cloneObject(object, [options])](#module_objectHelpers.cloneObject) ⇒ Object\r\n * _inner_\r\n * [~handleRetainObjects([retainObjects])](#module_objectHelpers..handleRetainObjects) ⇒ function\r\n * [~performDotNotate(arrayObject, didRetain, [prepend], [results])](#module_objectHelpers..performDotNotate) ⇒ DotNotatedObject\r\n\r\n\r\n\r\n### objectHelpers.mergeObjectsMutable ⇒ \\*\r\nUses mergeObjectsBase deep merge objects and arrays, merge by reference.\r\n\r\n**Kind**: static constant of [objectHelpers](#module_objectHelpers) \r\n**See**: [module:objectHelpers~mergeObjectsCallback](module:objectHelpers~mergeObjectsCallback) \r\n\r\n| Param | Type | Description |\r\n| --- | --- | --- |\r\n| ...objects | Object | Provide a list of objects which will be merged starting from the end up into the first |\r\n\r\n\r\n\r\n### objectHelpers.mergeObjects ⇒ \\*\r\nUses mergeObjectsBase deep merge objects and arrays, merge by value.\r\n\r\n**Kind**: static constant of [objectHelpers](#module_objectHelpers) \r\n**See**: [module:objectHelpers~mergeObjectsCallback](module:objectHelpers~mergeObjectsCallback) \r\n\r\n| Param | Type | Description |\r\n| --- | --- | --- |\r\n| ...objects | Object | Provide a list of objects which will be merged starting from the end up into the first |\r\n\r\n\r\n\r\n### objectHelpers.setValue(key, value, item) ⇒ Object \\| Array\r\nSet a value on an item, then return the item.\r\nNOTE: Argument order designed for usage with pipe\r\n\r\n**Kind**: static method of [objectHelpers](#module_objectHelpers) \r\n\r\n| Param | Type | Description |\r\n| --- | --- | --- |\r\n| key | string \\| number | The key on the item which will have its value set |\r\n| value | \\* | Any value to be applied to the key |\r\n| item | Object \\| Array | An object or array to be updated |\r\n\r\n\r\n\r\n### objectHelpers.setAndReturnValue(item, key, value) ⇒ \\*\r\nSet a value on an item, then return the value\r\n\r\n**Kind**: static method of [objectHelpers](#module_objectHelpers) \r\n\r\n| Param | Type | Description |\r\n| --- | --- | --- |\r\n| item | Object \\| Array | An object or array to be updated |\r\n| key | string \\| number | The key on the item which will have its value set |\r\n| value | \\* | Any value to be applied to the key |\r\n\r\n\r\n\r\n### objectHelpers.reduceObject(obj, fn, [initialValue]) ⇒ \\*\r\nThis function is intended to replicate behaviour of the Array.reduce() function but for Objects.\r\nIf an array is passed in instead then it will perform standard reduce(). It is recommended to\r\nalways use the standard reduce() function when it is known that the object is actually an array.\r\n\r\n**Kind**: static method of [objectHelpers](#module_objectHelpers) \r\n\r\n| Param | Type | Description |\r\n| --- | --- | --- |\r\n| obj | Object \\| Array | The Object (or Array) to be filtered |\r\n| fn | module:objectHelpers~reduceCallback \\| function \\| reduceCallback | The function to be processed for each filtered property |\r\n| [initialValue] | Object \\| Array | Optional. Value to use as the first argument to the first call of the callback. If no initial value is supplied, the first element in the array will be used. Calling reduce on an empty array without an initial value is an error. |\r\n\r\n\r\n\r\n### objectHelpers.objectValues(object, [includeInherited]) ⇒ Array\r\nGet an array of values from any object or array. Will return empty array when invalid or there are no values.\r\nOptional flag will include the inherited values from prototype chain when set.\r\n\r\n**Kind**: static method of [objectHelpers](#module_objectHelpers) \r\n\r\n| Param | Type | Default |\r\n| --- | --- | --- |\r\n| object | Object \\| Array | | \r\n| [includeInherited] | boolean | false | \r\n\r\n\r\n\r\n### objectHelpers.objectKeys(object, [includeInherited]) ⇒ Array.<(string\\|number)>\r\nGet an array of keys from any object or array. Will return empty array when invalid or there are no keys.\r\nOptional flag will include the inherited keys from prototype chain when set.\r\n\r\n**Kind**: static method of [objectHelpers](#module_objectHelpers) \r\n\r\n| Param | Type | Default |\r\n| --- | --- | --- |\r\n| object | Object \\| Array | | \r\n| [includeInherited] | boolean | false | \r\n\r\n\r\n\r\n### objectHelpers.mergeObjectsBase([options]) ⇒ module:objectHelpers~mergeObjectsCallback \\| mergeObjectsCallback\r\nPerform a deep merge of objects. This will return a function that will combine all objects and sub-objects.\r\nObjects having the same attributes will overwrite from last object to first.\r\nEvery call of the returned function keeps its own record of the objects it has already visited (so circular\r\nreferences are followed only once, and an object which is referenced in several places is merged once), and nothing\r\nis remembered between calls: the results of separate calls never share state or go stale.\r\n\r\n**Kind**: static method of [objectHelpers](#module_objectHelpers) \r\n\r\n| Param | Type | Default | Description |\r\n| --- | --- | --- | --- |\r\n| [options] | Object | {} | |\r\n| [options.mapLimit] | number | 100 | Deprecated and ignored: the record of visited objects is now scoped to a single call, so it does not need trimming. |\r\n| [options.depthLimit] | number | -1 | Control how many nested levels deep will be used, -1 = no limit, >-1 = nth level limited. |\r\n| [options.relevancyRange] | number | 1000 | Deprecated and ignored: see mapLimit. |\r\n| [options.map] | Iterable \\| array | [] | A predetermined list of references (source and the object it should resolve to) which every call starts from. It is only read, never added to. |\r\n| [options.useClone] | boolean | false | |\r\n\r\n\r\n\r\n### objectHelpers.mapObject(obj, fn, [thisArg]) ⇒ Object \\| Array\r\nThis function is intended to replicate behaviour of the Array.map() function but for Objects.\r\nIf an array is passed in instead then it will perform standard map(). It is recommended to\r\nalways use the standard map() function when it is known that the object is actually an array.\r\n\r\n**Kind**: static method of [objectHelpers](#module_objectHelpers) \r\n\r\n| Param | Type | Description |\r\n| --- | --- | --- |\r\n| obj | Object \\| Array | The Object (or Array) to be mapped |\r\n| fn | module:objectHelpers~mapCallback \\| function | The function to be processed for each mapped property |\r\n| [thisArg] | Object \\| Array | Optional. Value to use as this when executing callback. |\r\n\r\n\r\n\r\n### objectHelpers.isObject(object) ⇒ boolean\r\nCheck if the provided thing is an object / array.\r\n\r\n**Kind**: static method of [objectHelpers](#module_objectHelpers) \r\n\r\n| Param | Type |\r\n| --- | --- |\r\n| object | \\* | \r\n\r\n\r\n\r\n### objectHelpers.isInstanceObject(object) ⇒ boolean\r\nCheck if the current object has inherited properties.\r\n\r\n**Kind**: static method of [objectHelpers](#module_objectHelpers) \r\n\r\n| Param | Type |\r\n| --- | --- |\r\n| object | Object \\| Array | \r\n\r\n\r\n\r\n### objectHelpers.isEqual(first, second) ⇒ boolean\r\nCheck whether two values are equal by value, however they are stored: two separately made arrays or objects with the\r\nsame contents are equal, while two references only need to be the same when the value is a function.\r\n- Primitives are equal when they are the same value (and NaN equals NaN)\r\n- Arrays are equal when they have the same elements in the same order\r\n- Objects are equal when they have the same prototype (the same kind of object) and the same own properties with\r\nequal values, the order of the properties does not matter\r\n- Dates, regular expressions, Maps and Sets are compared by what they hold\r\n- Circular references are handled: a pair of objects which is already being compared is taken to be equal\r\n\r\n**Kind**: static method of [objectHelpers](#module_objectHelpers) \r\n**Returns**: boolean - True when the values are equal. \r\n\r\n| Param | Type | Description |\r\n| --- | --- | --- |\r\n| first | \\* | The first value. |\r\n| second | \\* | The second value. |\r\n\r\n\r\n\r\n### objectHelpers.isCloneable(value) ⇒ boolean\r\nDetermine if the value is a reference instance\r\n\r\n**Kind**: static method of [objectHelpers](#module_objectHelpers) \r\n\r\n| Param | Type |\r\n| --- | --- |\r\n| value | Array \\| Object \\| \\* | \r\n\r\n\r\n\r\n### objectHelpers.filterObject(obj, fn, [thisArg]) ⇒ Object \\| Array\r\nThis function is intended to replicate behaviour of the Array.filter() function but for Objects.\r\nIf an array is passed in instead then it will perform standard filter(). It is recommended to\r\nalways use the standard filter() function when it is known that the object is actually an array.\r\n\r\n**Kind**: static method of [objectHelpers](#module_objectHelpers) \r\n\r\n| Param | Type | Description |\r\n| --- | --- | --- |\r\n| obj | Object \\| Array | The Object (or Array) to be filtered |\r\n| fn | module:objectHelpers~filterCallback \\| function | The function to be processed for each filtered property |\r\n| [thisArg] | Object \\| Array | Optional. Value to use as this when executing callback. |\r\n\r\n\r\n\r\n### objectHelpers.emptyObject(item) ⇒ boolean\r\nHelper function for testing if the item is an Object or Array that does not have any properties\r\n\r\n**Kind**: static method of [objectHelpers](#module_objectHelpers) \r\n\r\n| Param | Type | Description |\r\n| --- | --- | --- |\r\n| item | Object \\| Array | Object or Array to test |\r\n\r\n\r\n\r\n### objectHelpers.dotUnset(arrayObject, dotNotation) ⇒ Object\r\nUnset a nested property value an object.\r\n\r\n**Kind**: static method of [objectHelpers](#module_objectHelpers) \r\n**Returns**: Object - The modified object \r\n\r\n| Param | Type | Description |\r\n| --- | --- | --- |\r\n| arrayObject | Object | The array or object to set the property on |\r\n| dotNotation | string | The path for the property |\r\n\r\n\r\n\r\n### objectHelpers.dotSet(arrayObject, dotNotation, value) ⇒ Object\r\nSet a nested property value an object.\r\n\r\n**Kind**: static method of [objectHelpers](#module_objectHelpers) \r\n**Returns**: Object - The modified object \r\n\r\n| Param | Type | Default | Description |\r\n| --- | --- | --- | --- |\r\n| arrayObject | Object | | The array or object to set the property on |\r\n| dotNotation | string | | The path for the property |\r\n| value | \\* | DotNotatedObject\r\nConvert an array or object to a single dimensional associative array with dot notation.\r\n\r\n**Kind**: static method of [objectHelpers](#module_objectHelpers) \r\n**Returns**: DotNotatedObject - The dot-notated object \r\n\r\n| Param | Type | Default | Description |\r\n| --- | --- | --- | --- |\r\n| arrayObject | Object | | The array or object to dot-notate |\r\n| [retainObjects] | Array.<DotNotationString> | [] | An array of keys to retain as objects |\r\n\r\n\r\n\r\n### objectHelpers.dotGet(arrayObject, dotNotation, [defaultValue]) ⇒ \\*\r\nGet a nested property value from an object.\r\n\r\n**Kind**: static method of [objectHelpers](#module_objectHelpers) \r\n**Returns**: \\* - The value of the property \r\n\r\n| Param | Type | Default | Description |\r\n| --- | --- | --- | --- |\r\n| arrayObject | Object | | The array or object to get the property from |\r\n| dotNotation | string | | The path to the property |\r\n| [defaultValue] | string \\| null | null | The default value to return if the property is not found |\r\n\r\n\r\n\r\n### objectHelpers.cloneObject(object, [options]) ⇒ Object\r\nClone objects for manipulation without data corruption, returns a copy of the provided object.\r\n\r\n**Kind**: static method of [objectHelpers](#module_objectHelpers) \r\n\r\n| Param | Type | Default | Description |\r\n| --- | --- | --- | --- |\r\n| object | Object | | The original object that is being cloned |\r\n| [options] | Object | {} | |\r\n| [options.mapLimit] | number | 100 | Deprecated and ignored (circular references are handled without trimming). |\r\n| [options.depthLimit] | number | -1 | Control how many nested levels deep will be used, -1 = no limit, >-1 = nth level limited. |\r\n| [options.relevancyRange] | number | 1000 | Deprecated and ignored: see mapLimit. |\r\n\r\n\r\n\r\n### objectHelpers~handleRetainObjects([retainObjects]) ⇒ function\r\nConvert an array of keys into a regex, return a function to test if incoming keys match.\r\n\r\n**Kind**: inner method of [objectHelpers](#module_objectHelpers) \r\n**Returns**: function - The dot-notated array \r\n\r\n| Param | Type | Default | Description |\r\n| --- | --- | --- | --- |\r\n| [retainObjects] | Array.<DotNotationString> | [] | An array of keys to retain as objects |\r\n\r\n\r\n\r\n### objectHelpers~performDotNotate(arrayObject, didRetain, [prepend], [results]) ⇒ DotNotatedObject\r\nThe underlying logic function for converting arrays to dot-notation.\r\n\r\n**Kind**: inner method of [objectHelpers](#module_objectHelpers) \r\n**Returns**: DotNotatedObject - The dot-notated object \r\n\r\n| Param | Type | Default | Description |\r\n| --- | --- | --- | --- |\r\n| arrayObject | Object | | The array or object to dot-notate |\r\n| didRetain | function | | The test function to see if a key should be retained |\r\n| [prepend] | DotNotationString | '' | The path for the property being processed |\r\n| [results] | DotNotatedObject | {} | The final array to return |\r\n\r\n\r\n\r\n## numberHelpers\r\nSome number comparators and random number generators.\r\n\r\n**Version**: 1.0.0 \r\n**Author**: Joshua Heagle Array.<number>\r\n * [.randomNumber(range, [offset], [interval])](#module_numberHelpers.randomNumber) ⇒ number\r\n * [.randomInteger(range, [offset], [interval])](#module_numberHelpers.randomInteger) ⇒ number\r\n * [.lowestCommonDenominator(...numbers)](#module_numberHelpers.lowestCommonDenominator) ⇒ number\r\n * [.leastCommonMultiple(num1, num2)](#module_numberHelpers.leastCommonMultiple) ⇒ number\r\n * [.greatestCommonDivisor(num1, num2)](#module_numberHelpers.greatestCommonDivisor) ⇒ number\r\n * [.compare(val1, val2)](#module_numberHelpers.compare) ⇒ number\r\n * [.absoluteMin(num1, num2)](#module_numberHelpers.absoluteMin) ⇒ number\r\n * [.absoluteMax(num1, num2)](#module_numberHelpers.absoluteMax) ⇒ number\r\n\r\n\r\n\r\n### numberHelpers.simplestRatio(...numbers) ⇒ Array.<number>\r\nReduce several numbers to their simplest form / ratio\r\n\r\n**Kind**: static method of [numberHelpers](#module_numberHelpers) \r\n\r\n| Param | Type | Description |\r\n| --- | --- | --- |\r\n| ...numbers | number | Array of numbers to simplify |\r\n\r\n\r\n\r\n### numberHelpers.randomNumber(range, [offset], [interval]) ⇒ number\r\nCreate a single random number from offset up to (but never including) offset + range. With optional offset,\r\nthe distance between the result numbers can be adjusted with interval. Matches randomInteger, which gives the\r\nwhole numbers of the same span.\r\n\r\n**Kind**: static method of [numberHelpers](#module_numberHelpers) \r\n\r\n| Param | Type | Default | Description |\r\n| --- | --- | --- | --- |\r\n| range | number | | Choose the breadth of the random number (0 up to, but not including, 100 would be 100 for range) |\r\n| [offset] | number | 0 | Choose the starting number (1 up to, but not including, 10 would be 1 for offset, 9 for range) |\r\n| [interval] | number | 1 | Choose the multiplier applied to the result (~5, ~10, ~15 would be 5 for interval, 1 for offset, 2 for range) |\r\n\r\n\r\n\r\n### numberHelpers.randomInteger(range, [offset], [interval]) ⇒ number\r\nCreate a single random integer from a set of `range` possible values, starting at the optional offset.\r\nWith no offset the result is 0 to range - 1 (so range is the number of possible values, the same as an array length\r\nwhen choosing an index). The distance between the result numbers can be adjusted with interval.\r\n\r\n**Kind**: static method of [numberHelpers](#module_numberHelpers) \r\n\r\n| Param | Type | Default | Description |\r\n| --- | --- | --- | --- |\r\n| range | number | | The number of possible values (0-99 would be 100 for range) |\r\n| [offset] | number | 0 | Choose the starting number (1-10 would be 1 for offset, 10 for range) |\r\n| [interval] | number | 1 | Choose the distance between numbers (5, 10, 15 would be 5 for interval, 1 for offset, 3 for range) |\r\n\r\n**Example** \r\n```js\r\nrandomInteger(1) // always 0 (one possible value)\r\nrandomInteger(2) // 0 or 1\r\nrandomInteger(3, 1, 5) // 5, 10 or 15\r\nitems[randomInteger(items.length)] // a random valid index\r\n```\r\n\r\n\r\n### numberHelpers.lowestCommonDenominator(...numbers) ⇒ number\r\nFind the smallest number that all the given numbers divide into evenly, by reducing them pairwise with\r\nleastCommonMultiple.\r\n\r\n**Kind**: static method of [numberHelpers](#module_numberHelpers) \r\n\r\n| Param | Type | Description |\r\n| --- | --- | --- |\r\n| ...numbers | number | Two or more numbers to find the lowest common denominator of. |\r\n\r\n\r\n\r\n### numberHelpers.leastCommonMultiple(num1, num2) ⇒ number\r\nHelper for calculating the multiplier that would make each number relative to each other.\r\n\r\n**Kind**: static method of [numberHelpers](#module_numberHelpers) \r\n\r\n| Param | Type | Description |\r\n| --- | --- | --- |\r\n| num1 | number | A number to compare |\r\n| num2 | number | Another number to be compared against |\r\n\r\n\r\n\r\n### numberHelpers.greatestCommonDivisor(num1, num2) ⇒ number\r\nReturn the highest number that can be divided into both numbers.\r\n\r\n**Kind**: static method of [numberHelpers](#module_numberHelpers) \r\n\r\n| Param | Type | Description |\r\n| --- | --- | --- |\r\n| num1 | number | First number to assess |\r\n| num2 | number | Second number to compare for common divisor |\r\n\r\n\r\n\r\n### numberHelpers.compare(val1, val2) ⇒ number\r\nCompare two numbers and return:\r\n-1 to indicate val1 is less than val2\r\n0 to indicate both values are the equal\r\n1 to indicate val1 is greater than val2\r\n\r\n**Kind**: static method of [numberHelpers](#module_numberHelpers) \r\n\r\n| Param | Type | Description |\r\n| --- | --- | --- |\r\n| val1 | number | The first number to compare |\r\n| val2 | number | The second number to compare |\r\n\r\n\r\n\r\n### numberHelpers.absoluteMin(num1, num2) ⇒ number\r\nHelper for returning the absolute min value\r\n\r\n**Kind**: static method of [numberHelpers](#module_numberHelpers) \r\n\r\n| Param | Type | Description |\r\n| --- | --- | --- |\r\n| num1 | number | A number to compare |\r\n| num2 | number | Another number to be compared against |\r\n\r\n\r\n\r\n### numberHelpers.absoluteMax(num1, num2) ⇒ number\r\nHelper for returning the absolute max value\r\n\r\n**Kind**: static method of [numberHelpers](#module_numberHelpers) \r\n\r\n| Param | Type | Description |\r\n| --- | --- | --- |\r\n| num1 | number | A number to compare |\r\n| num2 | number | Another number to be compared against |\r\n\r\n\r\n\r\n## functionHelpers\r\nManage how functions are called with these utilities.\r\n\r\n**Version**: 1.0.0 \r\n**Author**: Joshua Heagle function\r\n * [.relevancyFilter(map, [options])](#module_functionHelpers.relevancyFilter) ⇒ relevanceMap\r\n * [.queueTimeout([queueManagerHandle])](#module_functionHelpers.queueTimeout) ⇒ module:functionHelpers~queueTimeoutHandle\r\n * [.queueManager([queue])](#module_functionHelpers.queueManager) ⇒ module:functionHelpers~queueManagerHandle\r\n * [~makeQueuedRunnable(resolve, reject, fn, ...args)](#module_functionHelpers.queueManager..makeQueuedRunnable) ⇒ queuedRunnable\r\n * [~postRun(result)](#module_functionHelpers.queueManager..postRun) ⇒ \\*\r\n * [~postFailedRun(error)](#module_functionHelpers.queueManager..postFailedRun)\r\n * [~runNextItem()](#module_functionHelpers.queueManager..runNextItem) ⇒ IteratorYieldResult \\| null\r\n * [~pushAnother(fn, ...args)](#module_functionHelpers.queueManager..pushAnother) ⇒\r\n * [.preloadParams(fn, params, [unassignedParam])](#module_functionHelpers.preloadParams) ⇒ module:functionHelpers~callWithMissing\r\n * [.pipe(...fns)](#module_functionHelpers.pipe) ⇒ \\*\r\n * [.onBodyLoad(callback, [reset])](#module_functionHelpers.onBodyLoad) ⇒ Array.<function()>\r\n * [.makeBasicQueue([initialQueue])](#module_functionHelpers.makeBasicQueue) ⇒ IsQueue\r\n * [.delay(time)](#module_functionHelpers.delay) ⇒ module:functionHelpers~delayHandler\r\n * [.curry(fn)](#module_functionHelpers.curry) ⇒ function \\| \\*\r\n * [.callWithParams(fn, params, [minimum])](#module_functionHelpers.callWithParams) ⇒ \\*\r\n\r\n\r\n\r\n### functionHelpers.trace(label, [useClone]) ⇒ function\r\nOutput the value with label to the console and return the value to not interrupt the code - useful for\r\ninspecting a value mid-pipe/mid-chain without altering the result.\r\n\r\n**Kind**: static method of [functionHelpers](#module_functionHelpers) \r\n\r\n| Param | Type | Default | Description |\r\n| --- | --- | --- | --- |\r\n| label | string | | Pass an identifying label of the value being output. |\r\n| [useClone] | boolean | true | Determines if the logged data should be a clone of the original to preserve its state at the time of logging (rather than a live reference that may show later mutations). |\r\n\r\n\r\n\r\n### functionHelpers.relevancyFilter(map, [options]) ⇒ relevanceMap\r\nRemove elements out of relevance range and update the max relevance.\r\n\r\n**Kind**: static method of [functionHelpers](#module_functionHelpers) \r\n\r\n| Param | Type | Default | Description |\r\n| --- | --- | --- | --- |\r\n| map | relevanceMap | | |\r\n| [options] | Object | {} | |\r\n| [options.mapLimit] | number | 1000 | Only filter once the map exceeds this many entries. |\r\n| [options.relevancyRange] | number | 100 | How many of the most-recent relevance values to keep. |\r\n\r\n\r\n\r\n### functionHelpers.queueTimeout([queueManagerHandle]) ⇒ module:functionHelpers~queueTimeoutHandle\r\nManage functions to run sequentially with delays.\r\n\r\n**Kind**: static method of [functionHelpers](#module_functionHelpers) \r\n\r\n| Param | Type | Default |\r\n| --- | --- | --- |\r\n| [queueManagerHandle] | module:functionHelpers~queueManagerHandle | module:functionHelpers~queueManagerHandle\r\nManage functions to run sequentially.\r\n\r\n**Kind**: static method of [functionHelpers](#module_functionHelpers) \r\n\r\n| Param | Type | Default | Description |\r\n| --- | --- | --- | --- |\r\n| [queue] | IsQueue \\| Array | module:functionHelpers~queueManagerHandle\r\n * [~makeQueuedRunnable(resolve, reject, fn, ...args)](#module_functionHelpers.queueManager..makeQueuedRunnable) ⇒ queuedRunnable\r\n * [~postRun(result)](#module_functionHelpers.queueManager..postRun) ⇒ \\*\r\n * [~postFailedRun(error)](#module_functionHelpers.queueManager..postFailedRun)\r\n * [~runNextItem()](#module_functionHelpers.queueManager..runNextItem) ⇒ IteratorYieldResult \\| null\r\n * [~pushAnother(fn, ...args)](#module_functionHelpers.queueManager..pushAnother) ⇒\r\n\r\n\r\n\r\n#### queueManager~makeQueuedRunnable(resolve, reject, fn, ...args) ⇒ queuedRunnable\r\nConvert a function to a queueable object.\r\n\r\n**Kind**: inner method of [queueManager](#module_functionHelpers.queueManager) \r\n\r\n| Param | Type |\r\n| --- | --- |\r\n| resolve | Promise.resolve | \r\n| reject | Promise.reject | \r\n| fn | function | \r\n| ...args | \\* | \r\n\r\n\r\n\r\n#### queueManager~postRun(result) ⇒ \\*\r\nAfter an item is run, THEN run this function to reset isRunning\r\n\r\n**Kind**: inner method of [queueManager](#module_functionHelpers.queueManager) \r\n\r\n| Param | Type |\r\n| --- | --- |\r\n| result | \\* | \r\n\r\n\r\n\r\n#### queueManager~postFailedRun(error)\r\nWhen a queued function throws (or returns a promise which rejects), carry on with the rest of the queue and pass the\r\nerror on to whoever queued it - otherwise the queue would stay marked as running and never start another function.\r\n\r\n**Kind**: inner method of [queueManager](#module_functionHelpers.queueManager) \r\n**Throws**:\r\n\r\n- \\* The same error\r\n\r\n\r\n| Param | Type |\r\n| --- | --- |\r\n| error | \\* | \r\n\r\n\r\n\r\n#### queueManager~runNextItem() ⇒ IteratorYieldResult \\| null\r\nWhen ready, runs the next queued runnable generator.\r\n\r\n**Kind**: inner method of [queueManager](#module_functionHelpers.queueManager) \r\n\r\n\r\n#### queueManager~pushAnother(fn, ...args) ⇒\r\nAdd a function into the queue to be run when ready.\r\n\r\n**Kind**: inner method of [queueManager](#module_functionHelpers.queueManager) \r\n**Returns**: Promise \r\n\r\n| Param | Type | Description |\r\n| --- | --- | --- |\r\n| fn | function | The function to run when ready |\r\n| ...args | \\* | Optional arguments to apply when the function is ready to be run |\r\n\r\n\r\n\r\n### functionHelpers.preloadParams(fn, params, [unassignedParam]) ⇒ module:functionHelpers~callWithMissing\r\nProvide an array of parameters to be used with a function, allow the function to be called later\r\nwith the missing parameter.\r\n\r\n**Kind**: static method of [functionHelpers](#module_functionHelpers) \r\n\r\n| Param | Type | Default | Description |\r\n| --- | --- | --- | --- |\r\n| fn | function | | The function to be called |\r\n| params | Array | | The parameters to preload |\r\n| [unassignedParam] | number | 0 | Position of missing parameter (zero indexed) |\r\n\r\n\r\n\r\n### functionHelpers.pipe(...fns) ⇒ \\*\r\nTake one or more function with a single parameter and return value.\r\nPass a parameter and the value will be transformed by each function then returned.\r\n\r\n**Kind**: static method of [functionHelpers](#module_functionHelpers) \r\n\r\n| Param | Type | Description |\r\n| --- | --- | --- |\r\n| ...fns | function | Takes a series of functions having the same parameter |\r\n\r\n\r\n\r\n### functionHelpers.onBodyLoad(callback, [reset]) ⇒ Array.<function()>\r\nPrepare functions to be called once the body is available.\r\n\r\n**Kind**: static method of [functionHelpers](#module_functionHelpers) \r\n\r\n| Param | Type | Default |\r\n| --- | --- | --- |\r\n| callback | function | | \r\n| [reset] | boolean | false | \r\n\r\n\r\n\r\n### functionHelpers.makeBasicQueue([initialQueue]) ⇒ IsQueue\r\nCreate an instance of a basic queue.\r\n\r\n**Kind**: static method of [functionHelpers](#module_functionHelpers) \r\n\r\n| Param | Type | Default | Description |\r\n| --- | --- | --- | --- |\r\n| [initialQueue] | Array | [] | Items to pre-populate the queue with, in order. |\r\n\r\n\r\n\r\n### functionHelpers.delay(time) ⇒ module:functionHelpers~delayHandler\r\nProvide a timeout which returns a promise.\r\n\r\n**Kind**: static method of [functionHelpers](#module_functionHelpers) \r\n\r\n| Param | Type | Default | Description |\r\n| --- | --- | --- | --- |\r\n| time | number | 0 | Delay in milliseconds |\r\n\r\n\r\n\r\n### functionHelpers.curry(fn) ⇒ function \\| \\*\r\nReturn a curried version of the passed function.\r\nThe returned function expects the same number of arguments minus the ones provided.\r\nfn is the name of the function being curried.\r\n\r\n**Kind**: static method of [functionHelpers](#module_functionHelpers) \r\n\r\n| Param | Type | Description |\r\n| --- | --- | --- |\r\n| fn | function | Receives a function to be curried |\r\n\r\n\r\n\r\n### functionHelpers.callWithParams(fn, params, [minimum]) ⇒ \\*\r\nGiven a function, call with the correct number of parameters from an array of possible parameters.\r\n\r\n**Kind**: static method of [functionHelpers](#module_functionHelpers) \r\n\r\n| Param | Type | Default | Description |\r\n| --- | --- | --- | --- |\r\n| fn | function | | The function to be called |\r\n| params | Array | | Array of possible function parameters |\r\n| [minimum] | number | 2 | Minimum number of parameters to use in the function |\r\n\r\n\r\n\r\n## objectDescriptors\r\nA \"descriptor\" is a flat, serializable snapshot of an object or array's shape: for each property, its type(s),\r\nwhether it's nullable, and - if the property's own value is itself an object/array - a reference to that nested\r\nvalue's own descriptor elsewhere in the same list, rather than nesting descriptors inside descriptors. This flat,\r\nreference-based structure is what lets these utilities walk deeply nested and even circular object graphs (an\r\nobject that contains itself, directly or indirectly) without infinite recursion, since a value that's already\r\nbeen described is simply pointed to again instead of re-described.\r\n\r\nStart with [describeObjectMap](#module_objectDescriptors.describeObjectMap), which takes any real object or array and produces\r\nthis flat list of descriptors for you - the other functions here (comparing, merging, cloning descriptors) are\r\nbuilding blocks used internally, or useful once you already have descriptors to work with directly.\r\n\r\nThe concrete use this module has earned its keep on: describing two objects and comparing the results tells\r\nyou whether they're the same shape and values even when they're different references entirely (see\r\n[sameDescriptor](#module_objectDescriptors.sameDescriptor)/[compareDescriptor](#module_objectDescriptors.compareDescriptor)) - useful\r\nanywhere you need to check that two objects genuinely match without caring whether they're literally the same\r\ninstance. A descriptor also doubles as a flat, structured summary of an object's shape, which can be handy for\r\ndiscussion or assessment purposes (e.g. describing what an object looks like without dumping the whole thing).\r\n\r\n**Version**: 1.0.0 \r\n**Author**: Joshua Heagle module:objectDescriptors~descriptorMap\r\n * [.descriptorMapSample](#module_objectDescriptors.descriptorMapSample) : module:objectDescriptors~descriptorMap\r\n * [.descriptorDetailSample](#module_objectDescriptors.descriptorDetailSample) : module:objectDescriptors~descriptorDetail\r\n * [.descriptorSample](#module_objectDescriptors.descriptorSample) : module:objectDescriptors~descriptor\r\n * [.sameDescriptor(descriptor1, descriptor2)](#module_objectDescriptors.sameDescriptor) ⇒ boolean\r\n * [.nextReference(descriptor, currentReference)](#module_objectDescriptors.nextReference) ⇒ number \\| undefined\r\n * [.describeObjectMap(object, [options])](#module_objectDescriptors.describeObjectMap) ⇒ module:objectDescriptors~descriptorMap\r\n * [.describeObjectDetail(value, [key], [index])](#module_objectDescriptors.describeObjectDetail) ⇒ module:objectDescriptors~descriptorDetail\r\n * [.describeObject(object)](#module_objectDescriptors.describeObject) ⇒ module:objectDescriptors~descriptor\r\n * [.compareDescriptor(descriptor1, descriptor2)](#module_objectDescriptors.compareDescriptor) ⇒ boolean\r\n * [.cloneDescriptorDetail(originalDetail)](#module_objectDescriptors.cloneDescriptorDetail) ⇒ module:objectDescriptors~descriptorDetail\r\n * [.cloneDescriptor(originalMap)](#module_objectDescriptors.cloneDescriptor) ⇒ module:objectDescriptors~descriptor\r\n * [.checkDescriptorComplete(descriptor)](#module_objectDescriptors.checkDescriptorComplete) ⇒ module:objectDescriptors~descriptor\r\n * [.checkClearValues(descriptor, [keepValues])](#module_objectDescriptors.checkClearValues) ⇒ module:objectDescriptors~descriptor\r\n * [.assignDescriptorDetail(originalDetail, ...details)](#module_objectDescriptors.assignDescriptorDetail) ⇒ module:objectDescriptors~descriptorDetail\r\n * [.assignDescriptor(originalMap, ...descriptors)](#module_objectDescriptors.assignDescriptor) ⇒ module:objectDescriptors~descriptor\r\n\r\n\r\n\r\n### objectDescriptors.mappedDescriptorMap : module:objectDescriptors~descriptorMap\r\nA worked example descriptorMap, produced by describing a `descriptor` value itself (i.e. describing the shape of\r\na descriptor) - useful as a realistic fixture showing what a multi-entry descriptorMap with actual references\r\nlooks like, since `descriptorSample`/`descriptorMapSample` alone only demonstrate a trivial single-entry case.\r\n\r\n**Kind**: static constant of [objectDescriptors](#module_objectDescriptors) \r\n\r\n\r\n### objectDescriptors.descriptorMapSample : module:objectDescriptors~descriptorMap\r\n**Kind**: static constant of [objectDescriptors](#module_objectDescriptors) \r\n\r\n\r\n### objectDescriptors.descriptorDetailSample : module:objectDescriptors~descriptorDetail\r\n**Kind**: static constant of [objectDescriptors](#module_objectDescriptors) \r\n\r\n\r\n### objectDescriptors.descriptorSample : module:objectDescriptors~descriptor\r\n**Kind**: static constant of [objectDescriptors](#module_objectDescriptors) \r\n\r\n\r\n### objectDescriptors.sameDescriptor(descriptor1, descriptor2) ⇒ boolean\r\nCheck if two descriptors describe the exact same underlying values (not just compatible types, like\r\n[compareDescriptor](#module_objectDescriptors.compareDescriptor) does) - used to detect genuine circular references, where a\r\nnested value's descriptor turns out to be identical to one of its own ancestors.\r\n\r\n**Kind**: static method of [objectDescriptors](#module_objectDescriptors) \r\n**Returns**: boolean - True if every detail's values match at the same position. \r\n\r\n| Param | Type | Description |\r\n| --- | --- | --- |\r\n| descriptor1 | module:objectDescriptors~descriptor | The first descriptor to compare. |\r\n| descriptor2 | module:objectDescriptors~descriptor | The second descriptor to compare. |\r\n\r\n\r\n\r\n### objectDescriptors.nextReference(descriptor, currentReference) ⇒ number \\| undefined\r\nFind the index (within `descriptor.details`) of the next referenced property - after `currentReference` - whose\r\nown nested object/array still needs its descriptor built. Used to walk through a descriptor's references one at\r\na time while building out a descriptorMap.\r\n\r\n**Kind**: static method of [objectDescriptors](#module_objectDescriptors) \r\n**Returns**: number \\| undefined - The next detail index to process, or `undefined` if none remain. \r\n\r\n| Param | Type | Description |\r\n| --- | --- | --- |\r\n| descriptor | module:objectDescriptors~descriptor | The descriptor whose references to search. |\r\n| currentReference | number | The `details` index already processed - search continues after this one. |\r\n\r\n\r\n\r\n### objectDescriptors.describeObjectMap(object, [options]) ⇒ module:objectDescriptors~descriptorMap\r\nTrace out the entire object including nested objects, producing a flat descriptorMap - see the\r\n[objectDescriptors](#module_objectDescriptors) module description for what a descriptor represents and why it's flat. This is\r\nthe main entry point into this module: start here to describe a real object/array before comparing, merging, or\r\ninspecting its structure with the other functions in this module.\r\n\r\n**Kind**: static method of [objectDescriptors](#module_objectDescriptors) \r\n\r\n| Param | Type | Default | Description |\r\n| --- | --- | --- | --- |\r\n| object | Object \\| Array | | The real object or array to describe. |\r\n| [options] | Object | {} | |\r\n| [options.mapLimit] | number | 1000000000 | Stop describing further nested references once the map reaches this many descriptors - a safety limit for extremely large or deeply-referenced structures. |\r\n| [options.depthLimit] | number | -1 | How many levels of nested objects/arrays to describe; `-1` means no limit, `0` describes only the top level, etc. |\r\n| [options.keepValues] | boolean | false | By default, each detail's actual values are cleared once its descriptor is complete (to save memory) - set true to keep them. |\r\n\r\n**Example** \r\n```js\r\ndescribeObjectMap({ name: 'example', tags: ['a', 'b'] })\r\n// [\r\n// { index: 0, details: [...], length: 2, keys: ['name', 'tags'], references: [1], isArray: false, complete: true },\r\n// { index: 1, details: [...], length: 2, keys: [0], references: [], isArray: true, complete: true }\r\n// ]\r\n// descriptorMap[0] describes the top-level object; its 'tags' property is a reference (references: [1]) to\r\n// descriptorMap[1], which separately describes that nested array. descriptorMap[1]'s own `length` (2) reflects\r\n// the array's actual length, but `keys` has only one entry (0) since both elements share the same type\r\n// ('string') and are described together by a single, representative descriptorDetail.\r\n```\r\n\r\n\r\n### objectDescriptors.describeObjectDetail(value, [key], [index]) ⇒ module:objectDescriptors~descriptorDetail\r\nTrace a single property's value and produce the descriptorDetail describing it (type, nullability, whether it\r\nreferences a nested object/array, etc.) - the per-property building block used by\r\n[describeObject](#module_objectDescriptors.describeObject).\r\n\r\n**Kind**: static method of [objectDescriptors](#module_objectDescriptors) \r\n\r\n| Param | Type | Default | Description |\r\n| --- | --- | --- | --- |\r\n| value | \\* | | The property's value to describe. |\r\n| [key] | string \\| number | 0 | The property name (or array index) this value belongs to. |\r\n| [index] | number | 0 | This detail's intended position within its parent descriptor's `details` array. |\r\n\r\n\r\n\r\n### objectDescriptors.describeObject(object) ⇒ module:objectDescriptors~descriptor\r\nTrace a single object or array (not its nested objects/arrays - see\r\n[describeObjectMap](#module_objectDescriptors.describeObjectMap) for that) and return the descriptor which defines its own\r\nstructure and attributes.\r\n\r\n**Kind**: static method of [objectDescriptors](#module_objectDescriptors) \r\n\r\n| Param | Type | Description |\r\n| --- | --- | --- |\r\n| object | Object \\| Array | The object or array to describe. |\r\n\r\n\r\n\r\n### objectDescriptors.compareDescriptor(descriptor1, descriptor2) ⇒ boolean\r\nCheck if two descriptors are the same or similar, in that the smaller one's keys are all present in the larger\r\none and their types line up - used to detect when a newly-described value actually matches a descriptor already\r\nin the map, so it can be pointed at instead of creating a duplicate.\r\n\r\n**Kind**: static method of [objectDescriptors](#module_objectDescriptors) \r\n**Returns**: boolean - True if the descriptors describe a compatible shape. \r\n\r\n| Param | Type | Description |\r\n| --- | --- | --- |\r\n| descriptor1 | module:objectDescriptors~descriptor | The first descriptor to compare. |\r\n| descriptor2 | module:objectDescriptors~descriptor | The second descriptor to compare. |\r\n\r\n\r\n\r\n### objectDescriptors.cloneDescriptorDetail(originalDetail) ⇒ module:objectDescriptors~descriptorDetail\r\nGet a new copy of an existing descriptor detail so that the original will not be mutated.\r\n\r\n**Kind**: static method of [objectDescriptors](#module_objectDescriptors) \r\n**Returns**: module:objectDescriptors~descriptorDetail - A new, independent copy. \r\n\r\n| Param | Type | Description |\r\n| --- | --- | --- |\r\n| originalDetail | module:objectDescriptors~descriptorDetail | The detail to copy. |\r\n\r\n\r\n\r\n### objectDescriptors.cloneDescriptor(originalMap) ⇒ module:objectDescriptors~descriptor\r\nMake a copy of an object descriptor so that the original will not be mutated.\r\n\r\n**Kind**: static method of [objectDescriptors](#module_objectDescriptors) \r\n**Returns**: module:objectDescriptors~descriptor - A new, independent copy. \r\n\r\n| Param | Type | Description |\r\n| --- | --- | --- |\r\n| originalMap | module:objectDescriptors~descriptor | The descriptor to copy. |\r\n\r\n\r\n\r\n### objectDescriptors.checkDescriptorComplete(descriptor) ⇒ module:objectDescriptors~descriptor\r\nCheck if every property this descriptor references (i.e. every nested object/array it points to) has actually\r\nhad its own descriptor built yet, and set the descriptor's `complete` flag to true if so.\r\n\r\n**Kind**: static method of [objectDescriptors](#module_objectDescriptors) \r\n**Returns**: module:objectDescriptors~descriptor - The same descriptor, with `complete` updated. \r\n\r\n| Param | Type | Description |\r\n| --- | --- | --- |\r\n| descriptor | module:objectDescriptors~descriptor | The descriptor to check. |\r\n\r\n\r\n\r\n### objectDescriptors.checkClearValues(descriptor, [keepValues]) ⇒ module:objectDescriptors~descriptor\r\nOnce a descriptor is complete (all its references have been resolved), its details' actual `value` arrays are no\r\nlonger needed to build the descriptor further - clear them to save memory, unless `keepValues` says otherwise.\r\n\r\n**Kind**: static method of [objectDescriptors](#module_objectDescriptors) \r\n**Returns**: module:objectDescriptors~descriptor - The same descriptor, with `details[].value` cleared if applicable. \r\n\r\n| Param | Type | Default | Description |\r\n| --- | --- | --- | --- |\r\n| descriptor | module:objectDescriptors~descriptor | | The descriptor to check. |\r\n| [keepValues] | boolean | false | Set true to keep the values even once the descriptor is complete. |\r\n\r\n\r\n\r\n### objectDescriptors.assignDescriptorDetail(originalDetail, ...details) ⇒ module:objectDescriptors~descriptorDetail\r\nAssign properties from other details onto an existing detail, widening it (e.g. combining `type`/`value` arrays,\r\nOR-ing boolean flags like `nullable`/`optional`) rather than overwriting it - the per-property counterpart to\r\n[assignDescriptor](#module_objectDescriptors.assignDescriptor).\r\n\r\n**Kind**: static method of [objectDescriptors](#module_objectDescriptors) \r\n**Returns**: module:objectDescriptors~descriptorDetail - A new detail representing the merge of all of the above. \r\n\r\n| Param | Type | Description |\r\n| --- | --- | --- |\r\n| originalDetail | module:objectDescriptors~descriptorDetail | The base detail to merge onto (not mutated - a clone is merged and returned). |\r\n| ...details | module:objectDescriptors~descriptorDetail | One or more further details to merge in. |\r\n\r\n\r\n\r\n### objectDescriptors.assignDescriptor(originalMap, ...descriptors) ⇒ module:objectDescriptors~descriptor\r\nApply one or more descriptors to an existing descriptor so that they represent a merged version of the descriptors.\r\nUsed to widen a descriptor as more differently-shaped objects are described into it (e.g. array elements of\r\ndifferent types), rather than replacing it outright.\r\n\r\n**Kind**: static method of [objectDescriptors](#module_objectDescriptors) \r\n**Returns**: module:objectDescriptors~descriptor - A new descriptor representing the merge of all of the above. \r\n\r\n| Param | Type | Description |\r\n| --- | --- | --- |\r\n| originalMap | module:objectDescriptors~descriptor | The base descriptor to merge onto (not mutated - a clone is merged and returned). |\r\n| ...descriptors | module:objectDescriptors~descriptor | One or more further descriptors to merge in. |\r\n\r\n\r\n\r\n## arrayHelpers\r\nUtilities for building, merging, deduplicating and comparing arrays, plus a basic FIFO queue (BasicQueue) for\r\nuse with functionHelpers' queueManager/queueTimeout.\r\n\r\n**Version**: 1.0.0 \r\n**Author**: Joshua Heagle queuedItem \\| \\*\r\n * [.empty()](#module_arrayHelpers.BasicQueue+empty) ⇒ boolean\r\n * [.enqueue(data)](#module_arrayHelpers.BasicQueue+enqueue) ⇒ BasicQueue\r\n * [.peek()](#module_arrayHelpers.BasicQueue+peek) ⇒ queuedItem \\| \\*\r\n * [.size()](#module_arrayHelpers.BasicQueue+size) ⇒ number\r\n * [.uniqueArray(array)](#module_arrayHelpers.uniqueArray) ⇒ Array\r\n * [.mergeArrays(...arrays)](#module_arrayHelpers.mergeArrays) ⇒ Array\r\n * [.compareArrays(...arrays)](#module_arrayHelpers.compareArrays) ⇒ Array.<module:arrayHelpers~compareArrayResult>\r\n * [.buildArrayOfReferences(item, length)](#module_arrayHelpers.buildArrayOfReferences) ⇒ Array.<\\*>\r\n * [.buildArray(item, length)](#module_arrayHelpers.buildArray) ⇒ Array.<\\*>\r\n * [.addUniqueToArray(item, array)](#module_arrayHelpers.","readmeFilename":"README.md"}