{"id":20719894,"url":"https://github.com/itw-creative-works/node-powertools","last_synced_at":"2025-07-23T17:06:04.573Z","repository":{"id":65950812,"uuid":"266017716","full_name":"itw-creative-works/node-powertools","owner":"itw-creative-works","description":"Powerful quick and dirty tools","archived":false,"fork":false,"pushed_at":"2025-05-10T02:19:00.000Z","size":141,"stargazers_count":4,"open_issues_count":1,"forks_count":2,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-06-13T16:37:37.024Z","etag":null,"topics":["javascript","javascript-library","js","node-module","nodejs","nodejs-modules","productivity"],"latest_commit_sha":null,"homepage":"https://itwcreativeworks.com","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/itw-creative-works.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2020-05-22T04:26:29.000Z","updated_at":"2025-05-10T02:19:03.000Z","dependencies_parsed_at":"2023-11-20T14:26:51.697Z","dependency_job_id":"a7f35b0f-9bae-481b-8cba-d0cebee05449","html_url":"https://github.com/itw-creative-works/node-powertools","commit_stats":{"total_commits":35,"total_committers":2,"mean_commits":17.5,"dds":"0.37142857142857144","last_synced_commit":"d979dcd09fd7734bf25d811895d7d2aa7a908d80"},"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/itw-creative-works/node-powertools","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/itw-creative-works%2Fnode-powertools","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/itw-creative-works%2Fnode-powertools/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/itw-creative-works%2Fnode-powertools/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/itw-creative-works%2Fnode-powertools/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/itw-creative-works","download_url":"https://codeload.github.com/itw-creative-works/node-powertools/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/itw-creative-works%2Fnode-powertools/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":265353873,"owners_count":23751937,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["javascript","javascript-library","js","node-module","nodejs","nodejs-modules","productivity"],"created_at":"2024-11-17T03:18:43.882Z","updated_at":"2025-07-23T17:06:04.542Z","avatar_url":"https://github.com/itw-creative-works.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://itwcreativeworks.com\"\u003e\n    \u003cimg src=\"https://cdn.itwcreativeworks.com/assets/itw-creative-works/images/logo/itw-creative-works-brandmark-black-x.svg\" width=\"100px\"\u003e\n  \u003c/a\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"https://img.shields.io/github/package-json/v/itw-creative-works/node-powertools.svg\"\u003e\n  \u003cbr\u003e\n  \u003cimg src=\"https://img.shields.io/librariesio/release/npm/node-powertools.svg\"\u003e\n  \u003cimg src=\"https://img.shields.io/bundlephobia/min/node-powertools.svg\"\u003e\n  \u003cimg src=\"https://img.shields.io/codeclimate/maintainability-percentage/itw-creative-works/node-powertools.svg\"\u003e\n  \u003cimg src=\"https://img.shields.io/npm/dm/node-powertools.svg\"\u003e\n  \u003cimg src=\"https://img.shields.io/node/v/node-powertools.svg\"\u003e\n  \u003cimg src=\"https://img.shields.io/website/https/itwcreativeworks.com.svg\"\u003e\n  \u003cimg src=\"https://img.shields.io/github/license/itw-creative-works/node-powertools.svg\"\u003e\n  \u003cimg src=\"https://img.shields.io/github/contributors/itw-creative-works/node-powertools.svg\"\u003e\n  \u003cimg src=\"https://img.shields.io/github/last-commit/itw-creative-works/node-powertools.svg\"\u003e\n  \u003cbr\u003e\n  \u003cbr\u003e\n  \u003ca href=\"https://itwcreativeworks.com\"\u003eSite\u003c/a\u003e | \u003ca href=\"https://www.npmjs.com/package/node-powertools\"\u003eNPM Module\u003c/a\u003e | \u003ca href=\"https://github.com/itw-creative-works/node-powertools\"\u003eGitHub Repo\u003c/a\u003e\n  \u003cbr\u003e\n  \u003cbr\u003e\n  \u003cstrong\u003eNode Powertools\u003c/strong\u003e is an NPM module for backend and frontend developers that exposes powerful utilities and tools.\n\u003c/p\u003e\n\n## 🌐 Node Powertools Works in Node AND browser environments\nYes, this module works in both Node and browser environments, including compatibility with [Webpack](https://www.npmjs.com/package/webpack) and [Browserify](https://www.npmjs.com/package/browserify)!\n\n## 🦄 Features\n* Useful **randomization** tools to mix things up\n* Helpful **polling** utilities to wait for variables or events\n* Powerful **regexify** and **escape** functions to go work with `RegExp`\n\n## 📦 Install Node Powertools\n### Option 1: Install via npm\nInstall with npm if you plan to use **Node Powertools** in a Node.js project or in the browser.\n```shell\nnpm install node-powertools\n```\nIf you plan to use `node-powertools` in a browser environment, you will probably need to use [Webpack](https://www.npmjs.com/package/webpack), [Browserify](https://www.npmjs.com/package/browserify), or a similar service to compile it.\n\n```js\nconst powertools = require('node-powertools');\n```\n\n### Option 2: Install via CDN\nInstall with CDN if you plan to use **Node Powertools** only in a browser environment.\n```html\n\u003cscript src=\"https://cdn.jsdelivr.net/npm/node-powertools@latest/dist/index.min.js\"\u003e\u003c/script\u003e\n\u003cscript type=\"text/javascript\"\u003e\n  var powertools = Powertools(); // The script above exposes the global variable 'Powertools'\n\u003c/script\u003e\n```\n\n\n## ⚡️ Usage\n### powertools.random(min, max, options)\nGenerate a random number between two numbers `min` and `max`. You can use `options` to supply a sign or randomize the sign as well. If an array is supplied, a random element from the array is returned.\nThe default `options.mode` is `uniform` but you can also supply `gaussian` which will generate random values on a gaussian bell curve.\n```js\npowertools.random(0, 100, {mode: 'uniform'}); // Possible output: 69\npowertools.random(-100, 100, {mode: 'uniform'}); // Possible output: -69\npowertools.random(-100, 100, {mode: 'gaussian'}); // Possible output: -69\npowertools.random(['Apple', 'Orange', 'Pear']); // Possible output: Orange (random element)\n```\n\n### powertools.cahnce(chance, options)\nGenerate a random number between 0 and 100. If the random number is less than or equal to `chance`, return `true`. Otherwise, return `false`. You can use `options` to supply a sign or randomize the sign as well.\n```js\npowertools.chance(0.5); // Possible output: true\n```\n\n### powertools.arrayify(input)\nTransform the `input` into an array if it is not already.\n```js\npowertools.arrayify(1); // Output: [1]\npowertools.arrayify([1]); // Output: [1]\n```\n\n### powertools.wait(time)\nAsynchronously wait for the specified `time` in milliseconds.\n```js\nawait powertools.wait(1000); // waits for 1000 ms (1 second)\n```\n\n### powertools.poll(fn, options)\nAsynchronously wait for the specified `fn` to return `true`. You can use `options` to supply a polling interval and timeout in milliseconds. The promise **rejects** if the timeout is reached.\n```js\n// Call this function every 100 ms until it returns true or 30000 ms passes\nawait powertools.poll(function (index) {\n  return something === somethingElse;\n}, {interval: 100, timeout: 30000});\n```\n\n### powertools.queue(options)\nReturns a `Queue` which you can run `.add(fn)` where `fn` is an Asynchronous function. The queue will process the functions in FIFO (first in, first out) order and will only process the next async function after the one before it resolves or rejects.\n```js\n// Queue options\nconst options = {\n  delay: 100, // Delay between each function in milliseconds\n}\n\n// Create the queue\nconst queue = powertools.queue(options)\n\n// Queue the first function\nqueue.add(async () =\u003e {\n  console.log('Queue 1 started');\n  await powertools.wait(1000)\n  console.log('Queue 1 finished');\n})\n\n// Queue the second function\n// This will only begin executing after the first function completes\nqueue.add(async () =\u003e {\n  console.log('Queue 2 started');\n  await powertools.wait(1000)\n  console.log('Queue 2 finished');\n})\n```\n\n### powertools.getPromiseState(promise)\nReturns `pending`, `resolved`, or `rejected` based on the state of the `promise`. This is useful for checking if a promise has been resolved or rejected.\n\nThis method depends on `util` from Node.js, so it will not work in the browser.\n```js\nconst promise = new Promise((resolve, reject) =\u003e {\n  setTimeout(() =\u003e {\n    resolve('done');\n  }, 1000);\n});\n\npowertools.getPromiseState(promise); // Output: 'pending'\nawait promise;\npowertools.getPromiseState(promise); // Output: 'resolved'\n```\n\n### powertools.waitForPendingPromises(promises, options)\nWait for `options.max` promises to resolve before continuing. This is useful for when you have a large number of promises and you want to limit the number of concurrent promises that are running at any given time. This promise **rejects** if the `options.timeout` is reached.\n\nThis method depends on `util` from Node.js, so it will not work in the browser.\n```js\nconst promises = [\n  powertools.wait(1000),\n  powertools.wait(2000),\n  powertools.wait(3000),\n];\n\nconsole.log('Starting processing', promises);\n\nawait powertools.waitForPendingPromises(promises, {max: 2, timeout: 2000});\n\nconsole.log('Finished processing', promises);\n```\n\n### powertools.escape(str)\nAdd the escape character `\\` before any character in `str` that needs to be escaped for a `RegExp`.\n```js\npowertools.escape('*'); // Output: \\*\npowertools.escape('/'); // Output: \\/\npowertools.escape('\\\\'); // Output: \\\\\npowertools.escape('.$^'); // Output: \\.\\$\\^\n```\n\n### powertools.regexify(str)\nRevive a `str` into a `RegExp`. Supports flags. Depending on how you want special characters to be treated, you can use `powertools.escape(str)` prior to using `powertools.regexify(str)`.\n```js\npowertools.regexify('/Apple/'); // Output: RegExp /Apple/\npowertools.regexify('/Apple/i'); // Output: RegExp /Apple/i\npowertools.regexify('Apple'); // Output: Throws error (needs to start and end with /)\npowertools.regexify('/Apple/x'); // Output: Throws error (x is not a valid flag)\n\npowertools.regexify('/Ap.le/'); // Output: RegExp /Ap.le/\npowertools.regexify(`/${powertools.escape('Ap.le')}/`); // Output: RegExp /Ap\\.le/\n```\n\n### powertools.timestamp(date, options)\nConvert a `date` to a timestamp in 3 formats: an ISO `string`, a UNIX `number`, or a plain-ol' JS `Date` (as specified in `options`).\nThe first argument `date`  can be a JS `Date`, a UNIX timestamp `number`, or a `string` that will be parsed by the `new Date()` method.\n```js\npowertools.timestamp(new Date('2999/12/31'), {output: 'string'}); // Output: \"2999-12-31T08:00:00.000Z\"\npowertools.timestamp(new Date('2999/12/31'), {output: 'unix'}); // Output: 32503622400\npowertools.timestamp(new Date('2999/12/31'), {output: 'date'}); // Output: Tue Dec 31 2999 00:00:00 GMT-0800 (Pacific Standard Time)\n\npowertools.timestamp(32503622400, {output: 'string'}); // Output: \"2999-12-31T08:00:00.000Z\"\npowertools.timestamp(32503622400, {output: 'unix'}); // Output: 32503622400\npowertools.timestamp(32503622400, {output: 'date'}); // Output: Tue Dec 31 2999 00:00:00 GMT-0800 (Pacific Standard Time)\n```\n\n### powertools.force(value, type, options)\nIntelligently converts a `value` to a `type` how JavaScript **should**. The acceptable types are `string`, `number`, `boolean`, `array`. This is useful for helping to validate user input, such as considering `'true'` (string) to be `true` (boolean) or `'0'` (string of a number) to be `false` (boolean).\n```js\npowertools.force('true', 'boolean'); // Output: true\npowertools.force('false', 'boolean'); // Output: false\npowertools.force('0', 'boolean'); // Output: false\npowertools.force('1,2,3', 'array'); // Output: ['1', '2', '3']\npowertools.force('1,2,3', 'array', {force: 'number'}); // Output: [1, 2, 3]\npowertools.force(undefined, 'string'); // Output: ''\n```\n\n### powertools.defaults(settings, defaults)\nEasily structure your `settings` object by validating them with a `defaults` object. This function automatically fills in any missing keys in `settings` with the corresponding key in `defaults`, removes any keys in `settings` that are not in `defaults`, and converts any values in `settings` to the same type as the corresponding key in `defaults`.\n\n#### How to Define Defaults\n- `types`: An array of valid types for the value.\n- `default`: Any value that will be used if the key is missing.\n- `min`: A number limiting the minimum value if the value is a number, or the minimum length if the value is a string.\n- `max`: A number limiting the maximum value if the value is a number, or the maximum length if the value is a\n- `value`: Any value that will override the value in `settings` regardless of what it is (force the value).\n\n```js\nconst defaults = {\n  name: {\n    types: ['string'],\n    default: '',\n    min: 0,\n    max: 10,\n  },\n  stats: {\n    level: {\n      types: ['number'],\n      default: 1,\n      min: 1,\n      max: 2,\n    },\n    index: {\n      value: 1,\n    },\n  },\n}\npowertools.defaults({}, defaults); // Output: {name: '', stats: {level: 1}}\npowertools.defaults({name: 'What a long name!'}, defaults); // Output: {name: 'What a lon', stats: {level: 1}}\npowertools.defaults({stats: {level: 3}}, defaults); // Output: {name: '', stats: {level: 2}}\n```\n\n### powertools.getKeys(obj)\nWalk through any `obj` and get an array of every key, including nested keys.\n```js\npowertools.getKeys({name: 'Jon Snow'}); // Output: ['name']\npowertools.getKeys({name: 'Jon Snow', favorites: {color: 'red'}}); // Output: ['name', 'favorites.color']\npowertools.getKeys({}); // Output: []\n```\n\n### powertools.isObject(obj)\nCheck if `obj` is a good ol... object. In JavaScript, `null` is, unfortunately, considered an object. This function does not consider `null` to be an object.\n```js\npowertools.isObject({}); // Output: true\npowertools.isObject(null); // Output: false\n```\n\n### powertools.stringify(obj)\nStringify an `obj` into a JSON string even if it has circular references.\n```js\npowertools.stringify({}); // Output: '{}'\n```\n\n### powertools.template(str, data, options)\nReplace all instances of `{key}` in `str` with the corresponding value in `data`. You can use `options` to customize the template. `options.escape` will escape any HTML characters, and defaults to `true` if we're in a browser environment.\n```js\npowertools.template(\n  'My favorite color is {color}',\n  {color: 'purple'}\n); // Output: 'My favorite color is purple'\n\npowertools.template(\n  'Ian\\'s favorite color is {ian.color}',\n  {ian: {color: 'purple'}\n); // Output: 'Ian\\'s favorite color is purple'\n\npowertools.template(\n  'My favorite color is {color}',\n  {color: '\u003cb\u003epurple\u003c/b\u003e'},\n  {escape: true}\n); // Output: 'My favorite color is \u0026lt;b\u0026gt;purple\u0026lt;/b\u0026gt;'\n\npowertools.template(\n  'My favorite color is %color%',\n  {color: 'purple'},\n  {brackets: ['%', '%']}\n); // Output: 'My favorite color is purple'\n```\n\n### powertools.uniquify(arr)\nReturn an array `arr` with all duplicates removed.\n```js\npowertools.uniquify([{id: 1}, {id: 1}, {id: 2}]); // Output: [{id: 1}, {id: 2}]\n```\n\n### powertools.iterate(arr, callback)\nAsynchronously iterate through an array `arr` and call `callback` on each element. This function is useful for when you need to wait for asynchronous functions to complete before moving on to the next element in the array.\n```js\nconst sampleArray = [1, 2, 3, 4, 5];\n\n// Simulate an async operation like a database call\nconst asyncTask = (item, index) =\u003e {\n  return new Promise((resolve, reject) =\u003e {\n    setTimeout(() =\u003e {\n      console.log(`Processing item ${item} at index ${index}`);\n      return resolve();\n    }, 1000);\n  });\n};\n\n// Process each item in the array asynchronously\nPowertools.iterate(sampleArray, asyncTask)\n  .then(() =\u003e console.log('All tasks completed.'));\n```\n\n### powertools.execute(command, options, setupCallback)\nAsynchronously execute a `command` in the terminal. This function is useful for when you need to run a command in the terminal and wait for it to complete before moving on to the next step in your code.\n```js\n// Run a simple command\nawait powertools.execute('ls -a')\n.then((output) =\u003e {\n  console.log('Files:', output);\n})\n\n// Run a command with config\nawait powertools.execute('ls -a', {\n  config: {cwd: '/path/to/directory'},\n})\n.then((output) =\u003e {\n  console.log('Files:', output);\n})\n\n// Run a command with options like options.log\n// This will write the command's output to process.stdout and process.stderr\n// This is useful if you're running an intensive command and want to see the output in real-time\nawait powertools.execute('ls -a', {\n  log: true,\n})\n.then((output) =\u003e {\n  console.log('Files:', output);\n})\n\n// Run with a setupCallback\nawait powertools.execute('ls -a', {\n  log: true,\n}, (child) =\u003e {\n  console.log('Child process:', child);\n})\n.then((output) =\u003e {\n  console.log('Files:', output);\n})\n```\n\n### powertools.whitelist(obj, keys)\nReturn a new object with only the keys in `keys` from `obj`.\n```js\npowertools.whiteList({name: 'Jon Snow', age: 25}, ['name']); // Output: {name: 'Jon Snow'}\n```\n\n### powertools.hyphenate(str, options)\nConvert a `str` to hyphenated case. You can use `options` to customize the hyphenation.\n```js\npowertools.hyphenate('Jon Snow'); // Output: 'jon-snow'\npowertools.hyphenate('Jon Snow', {lowercase: false}); // Output: 'Jon-Snow'\npowerTools.hyphenate('Jon Snow!', {removeNonAlphanumeric: true}); // Output: 'jon-snow'\n```\n\n### powertools.parseProxy(proxy)\nParse a `proxy` string into an object with `protocol`, `host`, `port`, `username`, and `password` keys.\n```js\nconst proxy = powertools.parseProxy('http://username:password@1.2.3.4:8080'); // Output: {protocol: 'http', host: '1.2.3.4', port: '8080', username: 'username', password: 'password'}\n\n// Stringify it\nconsole.log(proxy.toString()); // Output: 'http://username:password@1.2.3.4:8080'\n\n// Stringify it without the auth\nconsole.log(proxy.toString({auth: false})); // Output: 'http://1.2.3.4:8080'\n```\n\n## 🗨️ Final Words\nIf you are still having difficulty, we would love for you to post a question to [the Node Powertools issues page](https://github.com/itw-creative-works/node-powertools/issues). It is much easier to answer questions that include your code and relevant files! So if you can provide them, we'd be extremely grateful (and more likely to help you find the answer!)\n\n## 📚 Projects Using this Library\n[Somiibo](https://somiibo.com/): A Social Media Bot with an open-source module library. \u003cbr\u003e\n[JekyllUp](https://jekyllup.com/): A website devoted to sharing the best Jekyll themes. \u003cbr\u003e\n[Slapform](https://slapform.com/): A backend processor for your HTML forms on static sites. \u003cbr\u003e\n[Proxifly](https://proxifly.com/): A backend processor for your HTML forms on static sites. \u003cbr\u003e\n[SoundGrail Music App](https://app.soundgrail.com/): A resource for producers, musicians, and DJs. \u003cbr\u003e\n[Hammock Report](https://hammockreport.com/): An API for exploring and listing backyard products. \u003cbr\u003e\n\nAsk us to have your project listed! :)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fitw-creative-works%2Fnode-powertools","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fitw-creative-works%2Fnode-powertools","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fitw-creative-works%2Fnode-powertools/lists"}