vs/v5.5.0/node_modules/npm/node_modules/request/node_modules/hawk/node_modules/hoek/package.json
|
{
"name": "hoek", "description": "General purpose node utilities", "version": "2.16.3", "repository": { "type": "git", "url": "git://github.com/hapijs/hoek.git" }, "main": "lib/index.js", "keywords": [ "utilities" ], "engines": { "node": ">=0.10.40" }, "dependencies": {}, "devDependencies": { "code": "1.x.x", "lab": "5.x.x" }, "scripts": { "test": "lab -a code -t 100 -L", "test-cov-html": "lab -a code -t 100 -L -r html -o coverage.html" }, "license": "BSD-3-Clause", "readme": "\n\nUtility methods for the hapi ecosystem. This module is not intended to solve every problem for everyone, but rather as a central place to store hapi-specific methods. If you're looking for a general purpose utility module, check out [lodash](https://github.com/lodash/lodash) or [underscore](https://github.com/jashkenas/underscore).\n\n[](http://travis-ci.org/hapijs/hoek)\n\nLead Maintainer: [Nathan LaFreniere](https://github.com/nlf)\n\n# Table of Contents\n\n* [Introduction](#introduction \"Introduction\")\n* [Object](#object \"Object\")\n * [clone](#cloneobj \"clone\")\n * [cloneWithShallow](#clonewithshallowobj-keys \"cloneWithShallow\")\n * [merge](#mergetarget-source-isnulloverride-ismergearrays \"merge\")\n * [applyToDefaults](#applytodefaultsdefaults-options-isnulloverride \"applyToDefaults\")\n * [applyToDefaultsWithShallow](#applytodefaultswithshallowdefaults-options-keys \"applyToDefaultsWithShallow\")\n * [deepEqual](#deepequala-b \"deepEqual\")\n * [unique](#uniquearray-key \"unique\")\n * [mapToObject](#maptoobjectarray-key \"mapToObject\")\n * [intersect](#intersectarray1-array2 \"intersect\")\n * [contain](#containref-values-options \"contain\")\n * [flatten](#flattenarray-target \"flatten\")\n * [reach](#reachobj-chain-options \"reach\")\n * [reachTemplate](#reachtemplateobj-template-options \"reachTemplate\")\n * [transform](#transformobj-transform-options \"transform\")\n * [shallow](#shallowobj \"shallow\")\n * [stringify](#stringifyobj \"stringify\")\n* [Timer](#timer \"Timer\")\n* [Bench](#bench \"Bench\")\n* [Binary Encoding/Decoding](#binary-encodingdecoding \"Binary Encoding/Decoding\")\n * [base64urlEncode](#base64urlencodevalue \"binary64urlEncode\")\n * [base64urlDecode](#base64urldecodevalue \"binary64urlDecode\")\n* [Escaping Characters](#escaping-characters \"Escaping Characters\")\n * [escapeHtml](#escapehtmlstring \"escapeHtml\")\n * [escapeHeaderAttribute](#escapeheaderattributeattribute \"escapeHeaderAttribute\")\n * [escapeRegex](#escaperegexstring \"escapeRegex\")\n* [Errors](#errors \"Errors\")\n * [assert](#assertcondition-message \"assert\")\n * [abort](#abortmessage \"abort\")\n * [displayStack](#displaystackslice \"displayStack\")\n * [callStack](#callstackslice \"callStack\")\n* [Function](#function \"Function\")\n * [nextTick](#nexttickfn \"nextTick\")\n * [once](#oncefn \"once\")\n * [ignore](#ignore \"ignore\")\n* [Miscellaneous](#miscellaneous \"Miscellaneous\")\n * [uniqueFilename](#uniquefilenamepath-extension \"uniqueFilename\")\n * [isAbsolutePath](#isabsolutepathpath-platform \"isAbsolutePath\")\n * [isInteger](#isintegervalue \"isInteger\")\n\n\n\n# Introduction\n\nThe *Hoek* library contains some common functions used within the hapi ecosystem. It comes with useful methods for Arrays (clone, merge, applyToDefaults), Objects (removeKeys, copy), Asserting and more.\n\nFor example, to use Hoek to set configuration with default options:\n```javascript\nvar Hoek = require('hoek');\n\nvar default = {url : \"www.github.com\", port : \"8000\", debug : true};\n\nvar config = Hoek.applyToDefaults(default, {port : \"3000\", admin : true});\n\n// In this case, config would be { url: 'www.github.com', port: '3000', debug: true, admin: true }\n```\n\nUnder each of the sections (such as Array), there are subsections which correspond to Hoek methods. Each subsection will explain how to use the corresponding method. In each js excerpt below, the `var Hoek = require('hoek');` is omitted for brevity.\n\n## Object\n\nHoek provides several helpful methods for objects and arrays.\n\n### clone(obj)\n\nThis method is used to clone an object or an array. A *deep copy* is made (duplicates everything, including values that are objects, as well as non-enumerable properties).\n\n```javascript\n\nvar nestedObj = {\n w: /^something$/ig,\n x: {\n a: [1, 2, 3],\n b: 123456,\n c: new Date()\n },\n y: 'y',\n z: new Date()\n };\n\nvar copy = Hoek.clone(nestedObj);\n\ncopy.x.b = 100;\n\nconsole.log(copy.y); // results in 'y'\nconsole.log(nestedObj.x.b); // results in 123456\nconsole.log(copy.x.b); // results in 100\n```\n\n### cloneWithShallow(obj, keys)\nkeys is an array of key names to shallow copy\n\nThis method is also used to clone an object or array, however any keys listed in the `keys` array are shallow copied while those not listed are deep copied.\n\n```javascript\n\nvar nestedObj = {\n w: /^something$/ig,\n x: {\n a: [1, 2, 3],\n b: 123456,\n c: new Date()\n },\n y: 'y',\n z: new Date()\n };\n\nvar copy = Hoek.cloneWithShallow(nestedObj, ['x']);\n\ncopy.x.b = 100;\n\nconsole.log(copy.y); // results in 'y'\nconsole.log(nestedObj.x.b); // results in 100\nconsole.log(copy.x.b); // results in 100\n```\n\n### merge(target, source, isNullOverride, isMergeArrays)\nisNullOverride, isMergeArrays default to true\n\nMerge all the properties of source into target, source wins in conflict, and by default null and undefined from source are applied.\nMerge is destructive where the target is modified. For non destructive merge, use `applyToDefaults`.\n\n\n```javascript\n\nvar target = {a: 1, b : 2};\nvar source = {a: 0, c: 5};\nvar source2 = {a: null, c: 5};\n\nHoek.merge(target, source); // results in {a: 0, b: 2, c: 5}\nHoek.merge(target, source2); // results in {a: null, b: 2, c: 5}\nHoek.merge(target, source2, false); // results in {a: 1, b: 2, c: 5}\n\nvar targetArray = [1, 2, 3];\nvar sourceArray = [4, 5];\n\nHoek.merge(targetArray, sourceArray); // results in [1, 2, 3, 4, 5]\nHoek.merge(targetArray, sourceArray, true, false); // results in [4, 5]\n```\n\n### applyToDefaults(defaults, options, isNullOverride)\nisNullOverride defaults to false\n\nApply options to a copy of the defaults\n\n```javascript\n\nvar defaults = { host: \"localhost\", port: 8000 };\nvar options = { port: 8080 };\n\nvar config = Hoek.applyToDefaults(defaults, options); // results in { host: \"localhost\", port: 8080 }\n```\n\nApply options with a null value to a copy of the defaults\n\n```javascript\n\nvar defaults = { host: \"localhost\", port: 8000 };\nvar options = { host: null, port: 8080 };\n\nvar config = Hoek.applyToDefaults(defaults, options, true); // results in { host: null, port: 8080 }\n```\n\n### applyToDefaultsWithShallow(defaults, options, keys)\nkeys is an array of key names to shallow copy\n\nApply options to a copy of the defaults. Keys specified in the last parameter are shallow copied from options instead of merged.\n\n```javascript\n\nvar defaults = {\n server: {\n host: \"localhost\",\n port: 8000\n },\n name: 'example'\n };\n\nvar options = { server: { port: 8080 } };\n\nvar config = Hoek.applyToDefaultsWithShallow(defaults, options, ['server']); // results in { server: { port: 8080 }, name: 'example' }\n```\n\n### deepEqual(b, a, [options])\n\nPerforms a deep comparison of the two values including support for circular dependencies, prototype, and properties. To skip prototype comparisons, use `options.prototype = false`\n\n```javascript\nHoek.deepEqual({ a: [1, 2], b: 'string', c: { d: true } }, { a: [1, 2], b: 'string', c: { d: true } }); //results in true\nHoek.deepEqual(Object.create(null), {}, { prototype: false }); //results in true\nHoek.deepEqual(Object.create(null), {}); //results in false\n```\n\n### unique(array, key)\n\nRemove duplicate items from Array\n\n```javascript\n\nvar array = [1, 2, 2, 3, 3, 4, 5, 6];\n\nvar newArray = Hoek.unique(array); // results in [1,2,3,4,5,6]\n\narray = [{id: 1}, {id: 1}, {id: 2}];\n\nnewArray = Hoek.unique(array, \"id\"); // results in [{id: 1}, {id: 2}]\n```\n\n### mapToObject(array, key)\n\nConvert an Array into an Object\n\n```javascript\n\nvar array = [1,2,3];\nvar newObject = Hoek.mapToObject(array); // results in [{\"1\": true}, {\"2\": true}, {\"3\": true}]\n\narray = [{id: 1}, {id: 2}];\nnewObject = Hoek.mapToObject(array, \"id\"); // results in [{\"id\": 1}, {\"id\": 2}]\n```\n\n### intersect(array1, array2)\n\nFind the common unique items in two arrays\n\n```javascript\n\nvar array1 = [1, 2, 3];\nvar array2 = [1, 4, 5];\n\nvar newArray = Hoek.intersect(array1, array2); // results in [1]\n```\n\n### contain(ref, values, [options])\n\nTests if the reference value contains the provided values where:\n- `ref` - the reference string, array, or object.\n- `values` - a single or array of values to find within the `ref` value. If `ref` is an object, `values` can be a key name,\n an array of key names, or an object with key-value pairs to compare.\n- `options` - an optional object with the following optional settings:\n - `deep` - if `true`, performed a deep comparison of the values.\n - `once` - if `true`, allows only one occurrence of each value.\n - `only` - if `true`, does not allow values not explicitly listed.\n - `part` - if `true`, allows partial match of the values (at least one must always match).\n\nNote: comparing a string to overlapping values will result in failed comparison (e.g. `contain('abc', ['ab', 'bc'])`).\nAlso, if an object key's value does not match the provided value, `false` is returned even when `part` is specified.\n\n```javascript\nHoek.contain('aaa', 'a', { only: true });\t\t\t\t\t\t\t// true\nHoek.contain([{ a: 1 }], [{ a: 1 }], { deep: true });\t\t\t\t// true\nHoek.contain([1, 2, 2], [1, 2], { once: true });\t\t\t\t\t// false\nHoek.contain({ a: 1, b: 2, c: 3 }, { a: 1, d: 4 }, { part: true }); // true\n```\n\n### flatten(array, [target])\n\nFlatten an array\n\n```javascript\n\nvar array = [1, [2, 3]];\n\nvar flattenedArray = Hoek.flatten(array); // results in [1, 2, 3]\n\narray = [1, [2, 3]];\ntarget = [4, [5]];\n\nflattenedArray = Hoek.flatten(array, target); // results in [4, [5], 1, 2, 3]\n```\n\n### reach(obj, chain, [options])\n\nConverts an object key chain string to reference\n\n- `options` - optional settings\n - `separator` - string to split chain path on, defaults to '.'\n - `default` - value to return if the path or value is not present, default is `undefined`\n - `strict` - if `true`, will throw an error on missing member, default is `false`\n - `functions` - if `true` allow traversing functions for properties. `false` will throw an error if a function is part of the chain.\n\nA chain including negative numbers will work like negative indices on an\narray.\n\nIf chain is `null`, `undefined` or `false`, the object itself will be returned.\n\n```javascript\n\nvar chain = 'a.b.c';\nvar obj = {a : {b : { c : 1}}};\n\nHoek.reach(obj, chain); // returns 1\n\nvar chain = 'a.b.-1';\nvar obj = {a : {b : [2,3,6]}};\n\nHoek.reach(obj, chain); // returns 6\n```\n\n### reachTemplate(obj, template, [options])\n\nReplaces string parameters (`{name}`) with their corresponding object key values by applying the\n(`reach()`)[#reachobj-chain-options] method where:\n\n- `obj` - the context object used for key lookup.\n- `template` - a string containing `{}` parameters.\n- `options` - optional (`reach()`)[#reachobj-chain-options] options.\n\n```javascript\n\nvar chain = 'a.b.c';\nvar obj = {a : {b : { c : 1}}};\n\nHoek.reachTemplate(obj, '1+{a.b.c}=2'); // returns '1+1=2'\n```\n\n### transform(obj, transform, [options])\n\nTransforms an existing object into a new one based on the supplied `obj` and `transform` map. `options` are the same as the `reach` options. The first argument can also be an array of objects. In that case the method will return an array of transformed objects.\n\n```javascript\nvar source = {\n address: {\n one: '123 main street',\n two: 'PO Box 1234'\n },\n title: 'Warehouse',\n state: 'CA'\n};\n\nvar result = Hoek.transform(source, {\n 'person.address.lineOne': 'address.one',\n 'person.address.lineTwo': 'address.two',\n 'title': 'title',\n 'person.address.region': 'state'\n});\n// Results in\n// {\n// person: {\n// address: {\n// lineOne: '123 main street',\n// lineTwo: 'PO Box 1234',\n// region: 'CA'\n// }\n// },\n// title: 'Warehouse'\n// }\n```\n\n### shallow(obj)\n\nPerforms a shallow copy by copying the references of all the top level children where:\n- `obj` - the object to be copied.\n\n```javascript\nvar shallow = Hoek.shallow({ a: { b: 1 } });\n```\n\n### stringify(obj)\n\nConverts an object to string using the built-in `JSON.stringify()` method with the difference that any errors are caught\nand reported back in the form of the returned string. Used as a shortcut for displaying information to the console (e.g. in\nerror message) without the need to worry about invalid conversion.\n\n```javascript\nvar a = {};\na.b = a;\nHoek.stringify(a);\t\t// Returns '[Cannot display object: Converting circular structure to JSON]'\n```\n\n# Timer\n\nA Timer object. Initializing a new timer object sets the ts to the number of milliseconds elapsed since 1 January 1970 00:00:00 UTC.\n\n```javascript\n\nvar timerObj = new Hoek.Timer();\nconsole.log(\"Time is now: \" + timerObj.ts);\nconsole.log(\"Elapsed time from initialization: \" + timerObj.elapsed() + 'milliseconds');\n```\n\n\n# Bench\n\nSame as Timer with the exception that `ts` stores the internal node clock which is not related to `Date.now()` and cannot be used to display\nhuman-readable timestamps. More accurate for benchmarking or internal timers.\n\n# Binary Encoding/Decoding\n\n### base64urlEncode(value)\n\nEncodes value in Base64 or URL encoding\n\n### base64urlDecode(value)\n\nDecodes data in Base64 or URL encoding.\n# Escaping Characters\n\nHoek provides convenient methods for escaping html characters. The escaped characters are as followed:\n\n```javascript\n\ninternals.htmlEscaped = {\n '&': '&',\n '<': '<',\n '>': '>',\n '\"': '"',\n \"'\": ''',\n '`': '`'\n};\n```\n\n### escapeHtml(string)\n\n```javascript\n\nvar string = '<html> hey </html>';\nvar escapedString = Hoek.escapeHtml(string); // returns <html> hey </html>\n```\n\n### escapeHeaderAttribute(attribute)\n\nEscape attribute value for use in HTTP header\n\n```javascript\n\nvar a = Hoek.escapeHeaderAttribute('I said \"go w\\\\o me\"'); //returns I said \\\"go w\\\\o me\\\"\n```\n\n\n### escapeRegex(string)\n\nEscape string for Regex construction\n\n```javascript\n\nvar a = Hoek.escapeRegex('4^f$s.4*5+-_?%=#!:@|~\\\\/`\"(>)[<]d{}s,'); // returns 4\\^f\\$s\\.4\\*5\\+\\-_\\?%\\=#\\!\\:@\\|~\\\\\\/`\"\\(>\\)\\[<\\]d\\{\\}s\\,\n```\n\n# Errors\n\n### assert(condition, message)\n\n```javascript\n\nvar a = 1, b = 2;\n\nHoek.assert(a === b, 'a should equal b'); // Throws 'a should equal b'\n```\n\nNote that you may also pass an already created Error object as the second parameter, and `assert` will throw that object.\n\n```javascript\n\nvar a = 1, b = 2;\n\nHoek.assert(a === b, new Error('a should equal b')); // Throws the given error object\n```\n\n### abort(message)\n\nFirst checks if `process.env.NODE_ENV === 'test'`, and if so, throws error message. Otherwise,\ndisplays most recent stack and then exits process.\n\n\n\n### displayStack(slice)\n\nDisplays the trace stack\n\n```javascript\n\nvar stack = Hoek.displayStack();\nconsole.log(stack); // returns something like:\n\n[ 'null (/Users/user/Desktop/hoek/test.js:4:18)',\n 'Module._compile (module.js:449:26)',\n 'Module._extensions..js (module.js:467:10)',\n 'Module.load (module.js:356:32)',\n 'Module._load (module.js:312:12)',\n 'Module.runMain (module.js:492:10)',\n 'startup.processNextTick.process._tickCallback (node.js:244:9)' ]\n```\n\n### callStack(slice)\n\nReturns a trace stack array.\n\n```javascript\n\nvar stack = Hoek.callStack();\nconsole.log(stack); // returns something like:\n\n[ [ '/Users/user/Desktop/hoek/test.js', 4, 18, null, false ],\n [ 'module.js', 449, 26, 'Module._compile', false ],\n [ 'module.js', 467, 10, 'Module._extensions..js', false ],\n [ 'module.js', 356, 32, 'Module.load', false ],\n [ 'module.js', 312, 12, 'Module._load', false ],\n [ 'module.js', 492, 10, 'Module.runMain', false ],\n [ 'node.js',\n 244,\n 9,\n 'startup.processNextTick.process._tickCallback',\n false ] ]\n```\n\n## Function\n\n### nextTick(fn)\n\nReturns a new function that wraps `fn` in `process.nextTick`.\n\n```javascript\n\nvar myFn = function () {\n console.log('Do this later');\n};\n\nvar nextFn = Hoek.nextTick(myFn);\n\nnextFn();\nconsole.log('Do this first');\n\n// Results in:\n//\n// Do this first\n// Do this later\n```\n\n### once(fn)\n\nReturns a new function that can be run multiple times, but makes sure `fn` is only run once.\n\n```javascript\n\nvar myFn = function () {\n console.log('Ran myFn');\n};\n\nvar onceFn = Hoek.once(myFn);\nonceFn(); // results in \"Ran myFn\"\nonceFn(); // results in undefined\n```\n\n### ignore\n\nA simple no-op function. It does nothing at all.\n\n## Miscellaneous\n\n### uniqueFilename(path, extension)\n`path` to prepend with the randomly generated file name. `extension` is the optional file extension, defaults to `''`.\n\nReturns a randomly generated file name at the specified `path`. The result is a fully resolved path to a file.\n\n```javascript\nvar result = Hoek.uniqueFilename('./test/modules', 'txt'); // results in \"full/path/test/modules/{random}.txt\"\n```\n\n### isAbsolutePath(path, [platform])\n\nDetermines whether `path` is an absolute path. Returns `true` or `false`.\n\n- `path` - A file path to test for whether it is absolute or not.\n- `platform` - An optional parameter used for specifying the platform. Defaults to `process.platform`.\n\n### isInteger(value)\n\nCheck `value` to see if it is an integer. Returns true/false.\n\n```javascript\nvar result = Hoek.isInteger('23')\n```\n", "readmeFilename": "README.md", "bugs": { "url": "https://github.com/hapijs/hoek/issues" }, "homepage": "https://github.com/hapijs/hoek#readme", "_id": "hoek@2.16.3", "_shasum": "20bb7403d3cea398e91dc4710a8ff1b8274a25ed", "_resolved": "https://registry.npmjs.org/hoek/-/hoek-2.16.3.tgz", "_from": "hoek@>=2.0.0 <3.0.0" } |