npm - generate-pw - Versions diffs - 1.1.0 → 1.2.0 - Mend

generate-pw 1.1.0 → 1.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (11) hide show

package/README.md CHANGED Viewed

@@ -1,11 +1,27 @@
+<div align="right">
+    <h6>
+        <picture>
+            <source type="image/svg+xml" media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/adamlui/js-utils/main/docs/images/earth-icon/white/icon32.svg">
+            <img height=14 src="https://raw.githubusercontent.com/adamlui/js-utils/main/docs/images/earth-icon/black/icon32.svg">
+        </picture>
+        &nbsp;English |
+        <a href="https://github.com/adamlui/js-utils/tree/main/minify.js/docs/zh-cn#readme">简体中文</a> |
+        <a href="https://github.com/adamlui/js-utils/tree/main/minify.js/docs/zh-tw#readme">繁體中文</a>
+    </h6>
+</div>
 # > generate-pw
 ### Randomly generate cryptographically-secure passwords.
-<a href="#%EF%B8%8F-mit-license"><img height=28 src="https://img.shields.io/badge/License-MIT-orange.svg?logo=internetarchive&logoColor=white&labelColor=464646&style=for-the-badge"></a>
-<a href="https://www.npmjs.com/package/generate-pw?activeTab=versions"><img height=28 src="https://img.shields.io/badge/Latest_Build-1.1.0-44cc11.svg?logo=icinga&logoColor=white&labelColor=464646&style=for-the-badge"></a>
-<a href="https://www.npmjs.com/package/generate-pw?activeTab=code"><img height=28 src="https://img.shields.io/npm/unpacked-size/generate-pw?style=for-the-badge&logo=ebox&logoColor=white&labelColor=464646&color=blue"></a>
-<a href="https://sonarcloud.io/component_measures?metric=new_vulnerabilities&id=adamlui_js-utils:generate-pw/generate-pw.js"><img height=28 src="https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fsonarcloud.io%2Fapi%2Fmeasures%2Fcomponent%3Fcomponent%3Dadamlui_js-utils%3Agenerate-pw%2Fgenerate-pw.js%26metricKeys%3Dvulnerabilities&query=%24.component.measures.0.value&style=for-the-badge&logo=sonarcloud&logoColor=white&labelColor=464646&label=Vulnerabilities&color=gold"></a>
+<a href="#%EF%B8%8F-mit-license"><img height=31 src="https://img.shields.io/badge/License-MIT-orange.svg?logo=internetarchive&logoColor=white&labelColor=464646&style=for-the-badge"></a>
+<a href="https://www.npmjs.com/package/generate-pw?activeTab=versions"><img height=31 src="https://img.shields.io/badge/Latest_Build-1.2.0-44cc11.svg?logo=icinga&logoColor=white&labelColor=464646&style=for-the-badge"></a>
+<a href="https://www.npmjs.com/package/generate-pw?activeTab=code"><img height=31 src="https://img.shields.io/npm/unpacked-size/generate-pw?style=for-the-badge&logo=ebox&logoColor=white&labelColor=464646&color=blue"></a>
+<a href="https://sonarcloud.io/component_measures?metric=new_vulnerabilities&id=adamlui_js-utils:generate-pw/generate-pw.js"><img height=31 src="https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fsonarcloud.io%2Fapi%2Fmeasures%2Fcomponent%3Fcomponent%3Dadamlui_js-utils%3Agenerate-pw%2Fgenerate-pw.js%26metricKeys%3Dvulnerabilities&query=%24.component.measures.0.value&style=for-the-badge&logo=sonarcloud&logoColor=white&labelColor=464646&label=Vulnerabilities&color=gold"></a>
+<br>
+<img height=6px width="100%" src="https://raw.githubusercontent.com/adamlui/js-utils/main/docs/images/aqua-separator.png">
 ## ⚡ Installation
@@ -21,6 +37,10 @@ As a **runtime dependency**, from your project root:
 $ npm install generate-pw
 ```
+<br>
+<img height=6px width="100%" src="https://raw.githubusercontent.com/adamlui/js-utils/main/docs/images/aqua-separator.png">
 ## 🔌 API usage
 **generate-pw** can be imported into your app as an ECMAScript module or a CommonJS module.
@@ -37,6 +57,8 @@ import * as pw from 'generate-pw';
 const pw = require('generate-pw');
 ```
+#
 ### `generatePassword([options])`
 Generates **one** password if `qty` option is not given, returning a string:
@@ -44,7 +66,7 @@ Generates **one** password if `qty` option is not given, returning a string:
 ```js
 const password = pw.generatePassword({ length: 11, numbers: true });
 console.log(password);
-// sample output: 'bAsZmsmqoQn'
+// sample output: 'bAsZm3mq6Qn'
 ```
 ...or **multiple** passwords if `qty` option is given, returning an array of strings:
@@ -57,6 +79,10 @@ console.log(passwords);
 **💡 Note:** If no options are passed, passwords will be 8-chars long, consisting of upper/lower cased letters.
+See: [Available options](#available-options-for-generate-functions)
+#
 ### `generatePasswords(qty[, options])`
 Generates **multiple** passwords based on `qty` given, returning an array of strings:
@@ -67,16 +93,60 @@ console.log(passwords);
 // sample output: [ 'yilppxru', 'ckvkyjfp', 'zolcpyfb' ]
 ```
-### Available options
+**💡 Note:** If no `qty` arg is passed, just one password will be generated, returned as a string.
+See: [Available options](#available-options-for-generate-functions)
+#
+### `strictify(password[, requiredCharTypes])`
-Any of these can be passed into the options object for each function:
+Modifies `password` given to use at least one character of each `requiredCharTypes` element passed, returning a string.
+```js
+const password = 'abcdef',
+      strictPW = pw.strictify(password, ['numbers', 'symbols']);
+console.log(strictPW);
+// sample output: 'a!c2eR'
+```
+Available `requiredCharTypes` are: `['number', 'symbol', 'lower', 'upper']`
+**💡 Note:** If no `requiredCharTypes` array is passed, all available types will be required.
+#
+### `validateStrength(password)`
+Validates the strength of a password, returning an object containing `strengthScore` (out of 100) + `recommendations` array.
+```js
+const password = 'AawiddsE',
+      pwStrength = pw.validateStrength(password);
+console.log(pwStrength);
+/* outputs:
+{
+  strengthScore: 60,
+  recommendations: [ 'Include at least one number.', 'Include at least one symbol.' ]
+}
+*/
+```
+#
+### Available options for `generate*()` functions
+Any of these can be passed into the options object for each `generate*()` function:
 Name        | Type    | Description                                                                    | Default Value
 ------------|---------|--------------------------------------------------------------------------------|---------------
 `length`    | Integer | Length of password(s).                                                         | `8`
 `qty`*      | Integer | Number of passwords to generate.                                               | `1`
-`charset`   | String  | Characters to include in password(s).                                          | ''
-`exclude`   | String  | Characters to exclude from password(s).                                        | ''
+`charset`   | String  | Characters to include in password(s).                                          | `''`
+`exclude`   | String  | Characters to exclude from password(s).                                        | `''`
 `numbers`   | Boolean | Allow numbers in password(s).                                                  | `false`
 `symbols`   | Boolean | Allow symbols in password(s).                                                  | `false`
 `lowercase` | Boolean | Allow lowercase letters in password(s).                                        | `true`
@@ -87,9 +157,11 @@ Name        | Type    | Description
 <br>
+<img height=6px width="100%" src="https://raw.githubusercontent.com/adamlui/js-utils/main/docs/images/aqua-separator.png">
 ## 💻 Command line usage
-**generate-pw** can also be used from the command line. The basic **global command** is:
+When installed globally, **generate-pw** can also be used from the command line. The basic command is:
 ```
 $ generate-pw
@@ -97,10 +169,12 @@ $ generate-pw
 **💡 Note:** To generate multiple results, pass `--qty=n` where `n` is the number of passwords to generate.
+#
 ### Command line options
 ```
-Argument options:
+Parameter options:
  --length=n                  Generate password(s) of n length.
  --qty=n                     Generate n password(s).
  --charset=chars             Only include chars in password(s).
@@ -113,16 +187,13 @@ Boolean options:
  -U, --no-uppercase          Disallow uppercase letters in password(s).
 Info commands:
- -h, --help                  Display this help screen.
+ -h, --help                  Display help screen.
  -v, --version               Show version number.
 ```
 <br>
-## 💖 Support
-Please consider [giving a GitHub ⭐](https://github.com/adamlui/js-utils) or [funding](https://github.com/sponsors/adamlui) this project if it helped you!
-<br><br>
+<img height=6px width="100%" src="https://raw.githubusercontent.com/adamlui/js-utils/main/docs/images/aqua-separator.png">
 ## 🏛️ MIT License

package/docs/LICENSE.md CHANGED Viewed

@@ -1,3 +1,15 @@
+<div align="right">
+    <h6>
+        <picture>
+            <source type="image/svg+xml" media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/adamlui/js-utils/main/docs/images/earth-icon/white/icon32.svg">
+            <img height=14 src="https://raw.githubusercontent.com/adamlui/js-utils/main/docs/images/earth-icon/black/icon32.svg">
+        </picture>
+        &nbsp;English |
+        <a href="zh-cn/LICENSE.md">简体中文</a> |
+        <a href="zh-tw/LICENSE.md">繁體中文</a>
+    </h6>
+</div>
 # 🏛️ MIT License
 **Copyright © 2024 [Adam Lui](https://github.com/adamlui)**

package/docs/SECURITY.md CHANGED Viewed

@@ -1,3 +1,15 @@
+<div align="right">
+    <h6>
+        <picture>
+            <source type="image/svg+xml" media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/adamlui/js-utils/main/docs/images/earth-icon/white/icon32.svg">
+            <img height=14 src="https://raw.githubusercontent.com/adamlui/js-utils/main/docs/images/earth-icon/black/icon32.svg">
+        </picture>
+        &nbsp;English |
+        <a href="zh-cn/SECURITY.md">简体中文</a> |
+        <a href="zh-tw/SECURITY.md">繁體中文</a>
+    </h6>
+</div>
 # 🛡️ Security Policy
 If you find a vulnerability, please open a [draft security advisory](https://github.com/adamlui/js-utils/security/advisories/new).

package/docs/zh-cn/LICENSE.md ADDED Viewed

@@ -0,0 +1,21 @@
+<div align="right">
+    <h6>
+        <picture>
+            <source type="image/svg+xml" media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/adamlui/js-utils/main/docs/images/earth-icon/white/icon32.svg">
+            <img height=14 src="https://raw.githubusercontent.com/adamlui/js-utils/main/docs/images/earth-icon/black/icon32.svg">
+        </picture>
+        &nbsp;简体中文 |
+        <a href="../LICENSE.md">English</a> |
+        <a href="../zh-tw/LICENSE.md">繁體中文</a>
+    </h6>
+</div>
+# 🏛️ MIT 许可证
+**版权所有 © 2024 [刘展鹏 (Adam Lui)](https://github.com/adamlui)**
+特此免费向任何获得副本的人授予许可本软件和相关文档文件（『软件』），处理在软件中不受限制，包括但不限于权利使用、复制、修改、合并、发布、分发、再许可和/或出售该软件的副本，并允许该软件是提供这样做，但须满足以下条件：
+上述版权声明和本许可声明应包含在所有软件的副本或重要部分。
+本软件『按原样』提供，不提供任何形式的明示或保证暗示的，包括但不限于适销性保证，适用于特定目的和非侵权。 在任何情况下都不得作者或版权持有人对任何索赔、损害或其他责任，无论是在合同、侵权或其他方面的行为中，由以下原因引起，出于或与软件或使用或其他交易有关软件。

package/docs/zh-cn/README.md ADDED Viewed

@@ -0,0 +1,214 @@
+<div align="right">
+    <h6>
+        <picture>
+            <source type="image/svg+xml" media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/adamlui/js-utils/main/docs/images/earth-icon/white/icon32.svg">
+            <img height=14 src="https://raw.githubusercontent.com/adamlui/js-utils/main/docs/images/earth-icon/black/icon32.svg">
+        </picture>
+        &nbsp;简体中文 |
+        <a href="../..#readme">English</a> |
+        <a href="../zh-tw#readme">繁體中文</a>
+    </h6>
+</div>
+# > generate-pw
+### 随机生成加密安全密码。
+<a href="#%EF%B8%8F-mit-%E8%AE%B8%E5%8F%AF%E8%AF%81"><img height=31 src="https://img.shields.io/badge/许可证-MIT-orange.svg?logo=internetarchive&logoColor=white&labelColor=464646&style=for-the-badge"></a>
+<a href="https://www.npmjs.com/package/generate-pw?activeTab=versions"><img height=31 src="https://img.shields.io/badge/最新版本-1.2.0-44cc11.svg?logo=icinga&logoColor=white&labelColor=464646&style=for-the-badge"></a>
+<a href="https://www.npmjs.com/package/generate-pw?activeTab=code"><img height=31 src="https://img.shields.io/npm/unpacked-size/generate-pw?label=%E6%8B%86%E5%B0%81%E5%B0%BA%E5%AF%B8&style=for-the-badge&logo=ebox&logoColor=white&labelColor=464646&color=blue"></a>
+<a href="https://sonarcloud.io/component_measures?metric=new_vulnerabilities&id=adamlui_js-utils:generate-pw/generate-pw.js"><img height=31 src="https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fsonarcloud.io%2Fapi%2Fmeasures%2Fcomponent%3Fcomponent%3Dadamlui_js-utils%3Agenerate-pw%2Fgenerate-pw.js%26metricKeys%3Dvulnerabilities&query=%24.component.measures.0.value&style=for-the-badge&logo=sonarcloud&logoColor=white&labelColor=464646&label=%E6%BC%8F%E6%B4%9E&color=gold"></a>
+<br>
+<img height=6px width="100%" src="https://raw.githubusercontent.com/adamlui/js-utils/main/docs/images/aqua-separator.png">
+## ⚡ 安装
+作为**全局实用程序**：
+```
+$ npm install -g generate-pw
+```
+作为 **运行时依赖项**，从项目根目录：
+```
+$ npm install generate-pw
+```
+<br>
+<img height=6px width="100%" src="https://raw.githubusercontent.com/adamlui/js-utils/main/docs/images/aqua-separator.png">
+## 🔌 API 使用
+**generate-pw** 可以作为 ECMAScript 模块或 CommonJS 模块导入到您的应用程序中。
+#### ESM:
+```js
+import * as pw from 'generate-pw';
+```
+#### CJS:
+```js
+const pw = require('generate-pw');
+```
+#
+### `generatePassword([options])`
+如果未给出 `qty` 选项，则生成**一个**密码，并返回一个字符串：
+```js
+const password = pw.generatePassword({ length: 11, numbers: true });
+console.log(password);
+// 示例输出：'bAsZm3mq6Qn'
+```
+...或 **多个** 密码（如果给出了 `qty` 选项），返回一个字符串数组：
+```js
+const passwords = pw.generatePassword({ qty: 5, length: 8, symbols: true });
+console.log(passwords);
+// 示例输出：[ '!zSf@Q.s', '!,HT\\;m=', '?Lq&FV>^', 'gf}Y;}Ne', 'Stsx(GqE' ]
+```
+**💡 注意：**如果不传递任何选项，密码将为 8 个字符长，由大小写字母组成。
+请参阅：[可用选项](#available-options-for-generate-functions)
+#
+### `generatePasswords(qty[, options])`
+根据给定的 `qty` 生成**多个**密码，返回字符串数组：
+```js
+const passwords = pw.generatePasswords(5, { length: 3, uppercase: false });
+console.log(passwords);
+// 示例输出：[ 'yilppxru', 'ckvkyjfp', 'zolcpyfb' ]
+```
+**💡 注意：**如果没有传递 `qty` 参数，则只会生成一个密码，并以字符串形式返回。
+请参阅：[可用选项](#available-options-for-generate-functions)
+#
+### `strictify(password[, requiredCharTypes])`
+修改指定的 `password`，以使用传递的每个 `requiredCharTypes` 元素中的至少一个字符，返回一个字符串。
+```js
+const password = 'abcdef',
+      strictPW = pw.strictify(password, ['numbers', 'symbols']);
+console.log(strictPW);
+// 示例输出：'a!c2eR'
+```
+可用的 `requiredCharTypes` 有：`['number', 'symbol', 'lower', 'upper']`
+**💡注意：**如果没有传递 `requiredCharTypes` 数组，则所有可用类型都将是必需的。
+#
+### `validateStrength(password)`
+验证密码的强度，返回一个包含 `strengthScore`（满分 100）+ `recommendations` 数组的对象。
+```js
+const password = 'AawiddsE',
+      pwStrength = pw.validateStrength(password);
+console.log(pwStrength);
+/* 输出：
+{
+  strengthScore: 60,
+  recommendations: [ 'Include at least one number.', 'Include at least one symbol.' ]
+}
+*/
+```
+#
+### `generate*()` 函数的可用选项
+其中任何一个都可以传递到每个 `generate*()` 函数的选项对象中：
+姓名        | 类型   | 描述                                     | 默认值
+------------|--------|-----------------------------------------|--------
+`length`    | 整数   | 密码的长度。                              | `8`
+`qty`*      | 整数   | 要生成的密码数量。                         | `1`
+`charset`   | 字符串 | 密码中包含的字符。                         | `''`
+`exclude`   | 字符串 | 要从密码中排除的字符。                     | `''`
+`numbers`   | 布尔值 | 允许密码中包含数字。                       | `false`
+`symbols`   | 布尔值 | 允许密码中包含符号。                       | `false`
+`lowercase` | 布尔值 | 密码中允许使用小写字母。                   | `true`
+`uppercase` | 布尔值 | 密码中允许使用大写字母。                   | `true`
+`strict`    | 布尔值 | 要求密码中每个允许的字符集中至少有一个字符。 | `false`
+##### _*仅在 [`generatePassword([options])`](#generatepasswordoptions) 中可用，因为 [`generatePasswords(qty[, options])`](#generatepasswordsqty-options) 采用 `qty` 参数_
+<br>
+<img height=6px width="100%" src="https://raw.githubusercontent.com/adamlui/js-utils/main/docs/images/aqua-separator.png">
+## 💻 命令行使用
+全局安装时，**generate-pw** 也可以从命令行使用。 基本命令是：
+```
+$ generate-pw
+```
+**💡 注意：**要生成多个结果，请传递 `--qty=n`，其中 `n` 是要生成的密码数量。
+#
+### 命令行选项
+```
+参数选项：
+ --length=n                  生成 n 长度的密码。
+ --qty=n                     生成 n 个密码。
+ --charset=chars             密码中仅包含 chars。
+ --exclude=chars             从密码中排除 chars。
+布尔选项：
+ -n, --include-numbers       允许密码中包含数字。
+ -s, --include-symbols       允许密码中包含符号。
+ -L, --no-lowercase          密码中不允许使用小写字母。
+ -U, --no-uppercase          密码中不允许使用大写字母。
+信息命令：
+ -h, --help                  显示帮助屏幕。
+ -v, --version               显示版本号。
+```
+<br>
+<img height=6px width="100%" src="https://raw.githubusercontent.com/adamlui/js-utils/main/docs/images/aqua-separator.png">
+## 🏛️ MIT 许可证
+**版权所有 © 2024 [刘展鹏 (Adam Lui)](https://github.com/adamlui)**
+特此免费向任何获得副本的人授予许可本软件和相关文档文件（『软件』），处理在软件中不受限制，包括但不限于权利使用、复制、修改、合并、发布、分发、再许可和/或出售该软件的副本，并允许该软件是提供这样做，但须满足以下条件：
+上述版权声明和本许可声明应包含在所有软件的副本或重要部分。
+本软件『按原样』提供，不提供任何形式的明示或保证暗示的，包括但不限于适销性保证，适用于特定目的和非侵权。 在任何情况下都不得作者或版权持有人对任何索赔、损害或其他责任，无论是在合同、侵权或其他方面的行为中，由以下原因引起，出于或与软件或使用或其他交易有关软件。
+<br>
+<img height=6px width="100%" src="https://raw.githubusercontent.com/adamlui/js-utils/main/docs/images/aqua-separator.png">
+<a href="https://github.com/adamlui/js-utils">**家**</a> /
+<a href="https://github.com/adamlui/js-utils/discussions">讨论</a> /
+<a href="#-generate-pw">回到顶部 ↑</a>

package/docs/zh-cn/SECURITY.md ADDED Viewed

@@ -0,0 +1,17 @@
+<div align="right">
+    <h6>
+        <picture>
+            <source type="image/svg+xml" media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/adamlui/js-utils/main/docs/images/earth-icon/white/icon32.svg">
+            <img height=14 src="https://raw.githubusercontent.com/adamlui/js-utils/main/docs/images/earth-icon/black/icon32.svg">
+        </picture>
+        &nbsp;简体中文 |
+        <a href="../SECURITY.md">English</a> |
+        <a href="../zh-tw/SECURITY.md">繁體中文</a>
+    </h6>
+</div>
+# 🛡️ 安全政策
+如果您发现漏洞，请打开[安全公告草案](https://github.com/adamlui/js-utils/security/advisories/new)。
+也欢迎拉取请求，但出于安全原因，请发送电子邮件至 <adam@kudoai.com> 并等待回复后再公开。

package/docs/zh-tw/LICENSE.md ADDED Viewed

@@ -0,0 +1,21 @@
+<div align="right">
+    <h6>
+        <picture>
+            <source type="image/svg+xml" media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/adamlui/js-utils/main/docs/images/earth-icon/white/icon32.svg">
+            <img height=14 src="https://raw.githubusercontent.com/adamlui/js-utils/main/docs/images/earth-icon/black/icon32.svg">
+        </picture>
+        &nbsp;繁體中文 |
+        <a href="../LICENSE.md">English</a> |
+        <a href="../zh-cn/LICENSE.md">简体中文</a>
+    </h6>
+</div>
+# 🏛️ MIT 许可证
+**版權所有 © 2024 [刘展鹏 (Adam Lui)](https://github.com/adamlui)**
+特此免費授予任何取得副本的人許可本軟體和相關文件文件（『軟體』），處理在軟體中不受限制，包括但不限於權利使用、複製、修改、合併、發布、分發、再授權和/或出售該軟體的副本，並允許該軟體是提供這樣做，但須滿足以下條件：
+上述版權聲明和本許可聲明應包含在所有軟體的副本或重要部分。
+本軟體『依現況』提供，不提供任何形式的明示或保證暗示的，包括但不限於適銷性保證，適用於特定目的和非侵權。 在任何情況下都不得作者或版權持有人對任何索賠、損害或其他責任，無論是在合約、侵權或其他方面的行為中，由以下原因引起，出於或與軟體或使用或其他交易有關軟體。

package/docs/zh-tw/README.md ADDED Viewed

@@ -0,0 +1,214 @@
+<div align="right">
+    <h6>
+        <picture>
+            <source type="image/svg+xml" media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/adamlui/js-utils/main/docs/images/earth-icon/white/icon32.svg">
+            <img height=14 src="https://raw.githubusercontent.com/adamlui/js-utils/main/docs/images/earth-icon/black/icon32.svg">
+        </picture>
+        &nbsp;繁體中文 |
+        <a href="../..#readme">English</a> |
+        <a href="../zh-cn#readme">简体中文</a>
+    </h6>
+</div>
+# > generate-pw
+### 隨機產生加密安全密碼。
+<a href="#%EF%B8%8F-mit-%E8%AE%B8%E5%8F%AF%E8%AF%81"><img height=31 src="https://img.shields.io/badge/許可證-MIT-orange.svg?logo=internetarchive&logoColor=white&labelColor=464646&style=for-the-badge"></a>
+<a href="https://www.npmjs.com/package/generate-pw?activeTab=versions"><img height=31 src="https://img.shields.io/badge/最新版本-1.2.0-44cc11.svg?logo=icinga&logoColor=white&labelColor=464646&style=for-the-badge"></a>
+<a href="https://www.npmjs.com/package/generate-pw?activeTab=code"><img height=31 src="https://img.shields.io/npm/unpacked-size/generate-pw?label=%E6%8B%86%E5%B0%81%E5%B0%BA%E5%AF%B8&style=for-the-badge&logo=ebox&logoColor=white&labelColor=464646&color=blue"></a>
+<a href="https://sonarcloud.io/component_measures?metric=new_vulnerabilities&id=adamlui_js-utils:generate-pw/generate-pw.js"><img height=31 src="https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fsonarcloud.io%2Fapi%2Fmeasures%2Fcomponent%3Fcomponent%3Dadamlui_js-utils%3Agenerate-pw%2Fgenerate-pw.js%26metricKeys%3Dvulnerabilities&query=%24.component.measures.0.value&style=for-the-badge&logo=sonarcloud&logoColor=white&labelColor=464646&label=%E6%BC%8F%E6%B4%9E&color=gold"></a>
+<br>
+<img height=6px width="100%" src="https://raw.githubusercontent.com/adamlui/js-utils/main/docs/images/aqua-separator.png">
+## ⚡ 安裝
+作為**全域實用程式**：
+```
+$ npm install -g generate-pw
+```
+作為 **運行時依賴項**，從專案根目錄：
+```
+$ npm install generate-pw
+```
+<br>
+<img height=6px width="100%" src="https://raw.githubusercontent.com/adamlui/js-utils/main/docs/images/aqua-separator.png">
+## 🔌 API 使用
+**generate-pw** 可以作為 ECMAScript 模組或 CommonJS 模組匯入到您的應用程式中。
+#### ESM:
+```js
+import * as pw from 'generate-pw';
+```
+#### CJS:
+```js
+const pw = require('generate-pw');
+```
+#
+### `generatePassword([options])`
+如果未給予 `qty` 選項，則產生**一個**密碼，並傳回字串：
+```js
+const password = pw.generatePassword({ length: 11, numbers: true });
+console.log(password);
+// 範例輸出：'bAsZm3mq6Qn'
+```
+...或 **多個** 密碼（如果給了 `qty` 選項），傳回一個字串陣列：
+```js
+const passwords = pw.generatePassword({ qty: 5, length: 8, symbols: true });
+console.log(passwords);
+// 範例輸出：[ '!zSf@Q.s', '!,HT\\;m=', '?Lq&FV>^', 'gf}Y;}Ne', 'Stsx(GqE' ]
+```
+**💡注意：**如果不傳遞任何選項，密碼將為 8 個字元長，由大小寫字母組成。
+請參閱：[可用選項](#available-options-for-generate-functions)
+#
+### `generatePasswords(qty[, options])`
+根據給定的 `qty` 產生**多個**密碼，傳回字串陣列：
+```js
+const passwords = pw.generatePasswords(5, { length: 3, uppercase: false });
+console.log(passwords);
+// 範例輸出：[ 'yilppxru', 'ckvkyjfp', 'zolcpyfb' ]
+```
+**💡 注意：** 如果沒有傳遞 `qty` 參數，則只會產生一個密碼，並以字串形式傳回。
+請參閱：[可用選項](#available-options-for-generate-functions)
+#
+### `strictify(password[, requiredCharTypes])`
+修改指定的 `password`，以使用傳遞的每個 `requiredCharTypes` 元素中的至少一個字符，傳回一個字串。
+```js
+const password = 'abcdef',
+      strictPW = pw.strictify(password, ['numbers', 'symbols']);
+console.log(strictPW);
+// 範例輸出：'a!c2eR'
+```
+可用的 `requiredCharTypes` 有：`['number', 'symbol', 'lower', 'upper']`
+**💡注意：**如果沒有傳遞 `requiredCharTypes` 數組，則所有可用類型都將是必需的。
+#
+### `validateStrength(password)`
+驗證密碼的強度，傳回一個包含 `strengthScore`（滿分 100）+ `recommendations` 陣列的物件。
+```js
+const password = 'AawiddsE',
+      pwStrength = pw.validateStrength(password);
+console.log(pwStrength);
+/* 輸出：
+{
+  strengthScore: 60,
+  recommendations: [ 'Include at least one number.', 'Include at least one symbol.' ]
+}
+*/
+```
+#
+### `generate*()` 函數的可用選項
+其中任何一個都可以傳遞到每個 `generate*()` 函數的選項物件中：
+姓名        | 類型   | 描述                                     | 預設值
+------------|--------|-----------------------------------------|---------
+`length`    | 整數   | 密碼的長度。                              | `8`
+`qty`*      | 整數   | 要產生的密碼數量。                         | `1`
+`charset`   | 字串   | 密碼中包含的字元。                         | `''`
+`exclude`   | 字串   | 要從密碼中排除的字元。                     | `''`
+`numbers`   | 布林值 | 允許密碼中包含數字。                       | `false`
+`symbols`   | 布林值 | 允許密碼中包含符號。                       | `false`
+`lowercase` | 布林值 | 密碼中允許使用小寫字母。                   | `true`
+`uppercase` | 布林值 | 密碼中允許使用大寫字母。                   | `true`
+`strict`    | 布林值 | 要求密碼中每個允許的字元集中至少有一個字元。 | `false`
+##### _*只在 [`generatePassword([options])`](#generatepasswordoptions) 中可用，因為 [`generatePasswords(qty[, options])`](#generatepasswordsqty-options) 採用 `qty` 參數_
+<br>
+<img height=6px width="100%" src="https://raw.githubusercontent.com/adamlui/js-utils/main/docs/images/aqua-separator.png">
+## 💻 命令列使用
+全域安裝時，**generate-pw** 也可以從命令列使用。 基本指令是：
+```
+$ generate-pw
+```
+**💡 注意：** 若要產生多個結果，請傳遞 `--qty=n`，其中 `n` 是要產生的密碼數量。
+#
+### 命令列選項
+```
+參數選項：
+ --length=n                  產生 n 長度的密碼。
+ --qty=n                     產生 n 個密碼。
+ --charset=chars             密碼中僅包含 chars。
+ --exclude=chars             從密碼中排除 chars。
+布林選項：
+ -n, --include-numbers       允許密碼中包含數字。
+ -s, --include-symbols       允許密碼中包含符號。
+ -L, --no-lowercase          密碼中不允許使用小寫字母。
+ -U, --no-uppercase          密碼中不允許使用大寫字母。
+訊息命令：
+ -h, --help                  顯示幫助畫面。
+ -v, --version               顯示版本號。
+```
+<br>
+<img height=6px width="100%" src="https://raw.githubusercontent.com/adamlui/js-utils/main/docs/images/aqua-separator.png">
+## 🏛️ MIT 许可证
+**版權所有 © 2024 [刘展鹏 (Adam Lui)](https://github.com/adamlui)**
+特此免費授予任何取得副本的人許可本軟體和相關文件文件（『軟體』），處理在軟體中不受限制，包括但不限於權利使用、複製、修改、合併、發布、分發、再授權和/或出售該軟體的副本，並允許該軟體是提供這樣做，但須滿足以下條件：
+上述版權聲明和本許可聲明應包含在所有軟體的副本或重要部分。
+本軟體『依現況』提供，不提供任何形式的明示或保證暗示的，包括但不限於適銷性保證，適用於特定目的和非侵權。 在任何情況下都不得作者或版權持有人對任何索賠、損害或其他責任，無論是在合約、侵權或其他方面的行為中，由以下原因引起，出於或與軟體或使用或其他交易有關軟體。
+<br>
+<img height=6px width="100%" src="https://raw.githubusercontent.com/adamlui/js-utils/main/docs/images/aqua-separator.png">
+<a href="https://github.com/adamlui/js-utils">**家**</a> /
+<a href="https://github.com/adamlui/js-utils/discussions">討論</a> /
+<a href="#-generate-pw">回到頂部 ↑</a>

package/docs/zh-tw/SECURITY.md ADDED Viewed

@@ -0,0 +1,17 @@
+<div align="right">
+    <h6>
+        <picture>
+            <source type="image/svg+xml" media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/adamlui/js-utils/main/docs/images/earth-icon/white/icon32.svg">
+            <img height=14 src="https://raw.githubusercontent.com/adamlui/js-utils/main/docs/images/earth-icon/black/icon32.svg">
+        </picture>
+        &nbsp;繁體中文 |
+        <a href="../SECURITY.md">English</a> |
+        <a href="../zh-cn/SECURITY.md">简体中文</a>
+    </h6>
+</div>
+# 🛡️ 安全策略
+如果您發現漏洞，請打開[安全公告草案](https://github.com/adamlui/js-utils/security/advisories/new)。
+也歡迎拉取請求，但出於安全原因，請發送電子郵件至 <adam@kudoai.com> 並等待回復後再公開。

package/generate-pw.js CHANGED Viewed

@@ -29,6 +29,12 @@ function generatePassword(options = {}) {
     };
     options = { ...defaultOptions, ...options };
+    // Validate integer args
+    for (const numArgType of ['length', 'qty'])
+        if (isNaN(options[numArgType]) || options[numArgType] < 1)
+            return console.error(
+                `ERROR: [${ numArgType }] argument must be 1 or greater.`);
     if (options.qty > 1) { // return array of [qty] password strings
         const { qty, ...otherOptions } = options;
         return generatePasswords(qty, otherOptions);
@@ -56,34 +62,10 @@ function generatePassword(options = {}) {
         }
         // Enforce strict mode if enabled
-        if (options.strict) {
+        if (options.strict) {
             const charTypes = ['number', 'symbol', 'lower', 'upper'],
                   requiredCharTypes = charTypes.filter(charType => options[charType + 's'] || options[charType + 'case']);
-            // Init flags
-            for (const charType of requiredCharTypes)
-                global['has' + charType.charAt(0).toUpperCase() + charType.slice(1)] = false;
-            for (let i = 0; i < password.length; i++)
-                for (const charType of requiredCharTypes)
-                    if ((charsets[charType] || charsets[charType + 's']).includes(password.charAt(i)))
-                        global['has' + charType.charAt(0).toUpperCase() + charType.slice(1)] = true;
-            // Modify password if necessary
-            const maxReplacements = Math.min(password.length, requiredCharTypes.length),
-                  replacedPositions = []; let replacementCnt = 0;
-            for (const charType of requiredCharTypes) {
-                if (replacementCnt < maxReplacements) {
-                    if (!global['has' + charType.charAt(0).toUpperCase() + charType.slice(1)]) {
-                        let replacementPos;
-                        do replacementPos = randomInt(0, password.length); // pick random pos
-                        while (replacedPositions.includes(replacementPos)); // check if pos already replaced
-                        replacedPositions.push(replacementPos); // track new replacement pos
-                        const replacementCharSet = charsets[charType] || charsets[charType + 's'];
-                        password = password.substring(0, replacementPos) // perform actual replacement
-                                 + replacementCharSet.charAt(randomInt(0, replacementCharSet.length))
-                                 + password.substring(replacementPos + 1);
-                        replacementCnt++;
-            }}}
+            password = strictify(password, requiredCharTypes);
         }
         return password;
@@ -93,14 +75,76 @@ function generatePassword(options = {}) {
 function generatePasswords(qty, options) {
     qty = parseInt(qty);
     if (isNaN(qty)) return console.error(
-        'ERROR: First argument <qty> of generatePasswords() must be an integer');
+        'ERROR: First argument [qty] of generatePasswords() must be an integer');
     const passwords = [];
     for (let i = 0; i < qty; i++) passwords.push(generatePassword(options));
     return passwords;
 }
+function strictify(password, requiredCharTypes = ['number', 'symbol', 'lower', 'upper']) {
+    // Init flags
+    for (const charType of requiredCharTypes)
+        global['has' + charType.charAt(0).toUpperCase() + charType.slice(1)] = false;
+    for (let i = 0; i < password.length; i++)
+        for (const charType of requiredCharTypes)
+            if ((charsets[charType] || charsets[charType + 's']).includes(password.charAt(i)))
+                global['has' + charType.charAt(0).toUpperCase() + charType.slice(1)] = true;
+    // Modify password if necessary
+    const maxReplacements = Math.min(password.length, requiredCharTypes.length),
+          replacedPositions = []; let replacementCnt = 0;
+    for (const charType of requiredCharTypes) {
+        if (replacementCnt < maxReplacements) {
+            if (!global['has' + charType.charAt(0).toUpperCase() + charType.slice(1)]) {
+                let replacementPos;
+                do replacementPos = randomInt(0, password.length); // pick random pos
+                while (replacedPositions.includes(replacementPos)); // check if pos already replaced
+                replacedPositions.push(replacementPos); // track new replacement pos
+                const replacementCharSet = charsets[charType] || charsets[charType + 's'];
+                password = password.substring(0, replacementPos) // perform actual replacement
+                         + replacementCharSet.charAt(randomInt(0, replacementCharSet.length))
+                         + password.substring(replacementPos + 1);
+                replacementCnt++;
+    }}}
+    return password;
+}
+function validateStrength(password) {
+    const strengthCriteria = { minLength: 8, minLower: 1, minUpper: 1, minNumber: 1, minSymbol: 1 };
+    // Count occurrences of each char type
+    const charCnts = { 'lower': 0, 'upper': 0, 'number': 0, 'symbol': 0 };
+    for (let i = 0; i < password.length; i++) {
+        const char = password[i];
+        for (const charType of Object.keys(charCnts))
+            if ((charsets[charType] || charsets[charType + 's']).includes(char))
+                charCnts[charType]++;
+    }
+    // Check criteria + add recommendations
+    const recommendations = [];
+    if (password.length < strengthCriteria.minLength)
+        recommendations.push(`Make it at least ${ strengthCriteria.minLength } characters long.`);
+    for (const charType of Object.keys(charCnts))
+        if (charCnts[charType] < strengthCriteria['min' + charType.charAt(0).toUpperCase() + charType.slice(1)])
+            recommendations.push('Include at least one ' + charType
+                + `${ ['upper', 'lower'].includes(charType) ? 'case letter' : '' }.`);
+    // Calculate strength score based on counts and criteria
+    let strengthScore = 0;
+    strengthScore += ( // +20 for satisfying min length
+        password.length >= strengthCriteria.minLength) ? 20 : 0;
+    for (const charType of Object.keys(charCnts))
+        strengthScore += ( // +20 per char type included
+            charCnts[charType] >= strengthCriteria['min' + charType.charAt(0).toUpperCase() + charType.slice(1)]) ? 20 : 0;
+    return { strengthScore, recommendations };
+}
 // EXPORT functions if script was required
-if (require.main !== module) module.exports = { generatePassword, generatePasswords };
+if (require.main !== module) module.exports = { generatePassword, generatePasswords, strictify, validateStrength };
 else { // run as CLI tool
@@ -111,47 +155,56 @@ else { // run as CLI tool
           bw = '\x1b[1;97m'; // bright white
     // Load settings from ARGS
-    const config = {
-        length: parseInt(process.argv.find(arg => /^--?length/.test(arg))?.split('=')[1]) || 8,
-        qty: parseInt(process.argv.find(arg => /^--?qu?a?n?ti?t?y=\d+$/.test(arg))?.split('=')[1]) || 1,
-        charset: process.argv.find(arg => /^--?chars/.test(arg))?.split('=')[1],
-        excludeChars: process.argv.find(arg => /^--?exclude=/.test(arg))?.split('=')[1] || '',
-        includeNums: process.argv.some(arg => /^--?(?:n|(?:include-?)?num(?:ber)?s?=?(?:true|1)?)$/.test(arg)),
-        includeSymbols: process.argv.some(arg => /^--?(?:s|(?:include-?)?symbols?=?(?:true|1)?)$/.test(arg)),
-        excludeLowerChars: process.argv.some(arg =>
-            /^--?(?:L|(?:exclude|disable|no)-?lower-?(?:case)?|lower-?(?:case)?=(?:false|0))$/.test(arg)),
-        excludeUpperChars: process.argv.some(arg =>
-            /^--?(?:U|(?:exclude|disable|no)-?upper-?(?:case)?|upper-?(?:case)?=(?:false|0))$/.test(arg)),
-        strictMode: process.argv.some(arg => /^--?s(?:trict)?(?:-?mode)?$/.test(arg))
+    const config = {};
+    const argRegex = {
+        paramOptions: {
+            'length': /^--?length/,
+            'qty': /^--?qu?a?n?ti?t?y=\d+$/,
+            'charset': /^--?chars/,
+            'excludeChars': /^--?exclude=/
+        },
+        flags: {
+            'includeNums': /^--?(?:n|(?:include-?)?num(?:ber)?s?=?(?:true|1)?)$/,
+            'includeSymbols': /^--?(?:s|(?:include-?)?symbols?=?(?:true|1)?)$/,
+            'excludeLowerChars': /^--?(?:L|(?:exclude|disable|no)-?lower-?(?:case)?|lower-?(?:case)?=(?:false|0))$/,
+            'excludeUpperChars': /^--?(?:U|(?:exclude|disable|no)-?upper-?(?:case)?|upper-?(?:case)?=(?:false|0))$/,
+            'strictMode': /^--?s(?:trict)?(?:-?mode)?$/
+        },
+        cmds: {
+            'help': /^--?h(?:elp)?$/,
+            'version': /^--?ve?r?s?i?o?n?$/
+        }
     };
+    process.argv.forEach(arg => {
+        if (!arg.startsWith('-')) return;
+        const matchedFlag = Object.keys(argRegex.flags).find(flag => argRegex.flags[flag].test(arg)),
+              matchedArgOption = Object.keys(argRegex.paramOptions).find(option => argRegex.paramOptions[option].test(arg)),
+              matchedCmd = Object.keys(argRegex.cmds).find(cmd => argRegex.cmds[cmd].test(arg));
+        if (matchedFlag) config[matchedFlag] = true;
+        else if (matchedArgOption) {
+            const value = arg.split('=')[1];
+            config[matchedArgOption] = parseInt(value) || value;
+        } else if (!matchedCmd) {
+            console.error(`\n${br}ERROR: Arg [${ arg }] not recognized.${nc}`);
+            console.info(`\n${by}Valid arguments are below.${nc}`);
+            printHelpScreen(['paramOptions', 'booelanOptions', 'infoCmds']);
+            process.exit(1);
+    }});
     // Show HELP screen if -h or --help passed
-    if (process.argv.some(arg => /^--?h(?:elp)?$/.test(arg))) {
-        printHelp(`\n${by}generate-pw [options]${nc}`);
-        printHelp('\nArgument options:');
-        printHelp(' --length=n                  Generate password(s) of n length.');
-        printHelp(' --qty=n                     Generate n password(s).');
-        printHelp(' --charset=chars             Only include chars in password(s).');
-        printHelp(' --exclude=chars             Exclude chars from password(s).');
-        printHelp('\nBoolean options:');
-        printHelp(' -n, --include-numbers       Allow numbers in password(s).');
-        printHelp(' -s, --include-symbols       Allow symbols in password(s).');
-        printHelp(' -L, --no-lowercase          Disallow lowercase letters in password(s).');
-        printHelp(' -U, --no-uppercase          Disallow uppercase letters in password(s).');
-        printHelp('\nInfo commands:');
-        printHelp(' -h, --help                  Display this help screen.');
-        printHelp(' -v, --version               Show version number.');
+    if (process.argv.some(arg => /^--?h(?:elp)?$/.test(arg))) printHelpScreen();
     // Show VERSION number if -v or --version passed
-    } else if (process.argv.some(arg => /^--?ve?r?s?i?o?n?$/.test(arg))) {
+    else if (process.argv.some(arg => /^--?ve?r?s?i?o?n?$/.test(arg)))
         console.info('v' + require('./package.json').version);
-    } else { // run MAIN routine
+    else { // run MAIN routine
         for (const numArgType of ['length', 'qty'])
-            if (config[numArgType] < 1) return console.error(
-                `\n${br}Error: '${ numArgType }' argument must be 1 or greater.${nc}`);
+            if (config[numArgType] && (isNaN(config[numArgType]) || config[numArgType] < 1))
+                return console.error(`\n${br}Error: [${ numArgType }] argument must be 1 or greater.${nc}`);
         const funcOptions = {
-            length: config.length, qty: config.qty, charset: config.charset, exclude: config.excludeChars,
+            length: config.length || 8, qty: config.qty || 1,
+            charset: config.charset, exclude: config.excludeChars,
             numbers: config.includeNums, symbols: config.includeSymbols,
             lowercase: !config.excludeLowerChars, uppercase: !config.excludeUpperChars,
             strict: config.strictMode
@@ -160,7 +213,9 @@ else { // run as CLI tool
         console.log('\n' + bw + ( Array.isArray(pwResult) ? pwResult.join('\n') : pwResult ) + nc);
     }
-    function printHelp(msg) { // wrap msg + indent 2nd+ lines (for --help screen)
+    // Define LOGGING functions
+    function printHelpMsg(msg) { // wrap msg + indent 2nd+ lines (for --help screen)
         const terminalWidth = process.stdout.columns || 80,
               indentation = 29, lines = [], words = msg.match(/\S+|\s+/g);
@@ -182,4 +237,34 @@ else { // run as CLI tool
                 : ' '.repeat(indentation) + line // print subsequent lines indented
         ));
     }
+    function printHelpScreen(includeSections = ['cmdFormat', 'paramOptions', 'booelanOptions', 'infoCmds']) {
+        const sections = {
+            'cmdFormat': [
+                `\n${by}generate-pw [options|commands]${nc}`
+            ],
+            'paramOptions': [
+                '\nParameter options:',
+                ' --length=n                  Generate password(s) of n length.',
+                ' --qty=n                     Generate n password(s).',
+                ' --charset=chars             Only include chars in password(s).',
+                ' --charset=chars             Only include chars in password(s).',
+                ' --exclude=chars             Exclude chars from password(s).'
+            ],
+            'booelanOptions': [
+                '\nBoolean options:',
+                ' -n, --include-numbers       Allow numbers in password(s).',
+                ' -s, --include-symbols       Allow symbols in password(s).',
+                ' -L, --no-lowercase          Disallow lowercase letters in password(s).',
+                ' -U, --no-uppercase          Disallow uppercase letters in password(s).'
+            ],
+            'infoCmds': [
+                '\nInfo commands:',
+                ' -h, --help                  Display help screen.',
+                ' -v, --version               Show version number.'
+            ]
+        };
+        includeSections.forEach(section => { // print valid arg elems
+            if (sections[section]) sections[section].forEach(line => printHelpMsg(line)); });
+    }
 }

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "generate-pw",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "description": "Randomly generate cryptographically-secure passwords.",
   "author": {
     "name": "Adam Lui",