js-generate-password 1.0.0 → 1.1.0

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2022 Ahmad Joya
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+
+Copyright (c) 2022 Ahmad Joya
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,172 +1,280 @@
-<!-- prettier-ignore-start -->
-<!-- SOMETHING AUTO-GENERATED BY TOOLS - START -->
-<br />
-<br />
-
-<p align ="center">
-  <a href="https://nodei.co/npm/js-generate-password" target="_blank">
-    <img src="https://nodei.co/npm/js-generate-password.png" alt="npm Info" />
-  </a>
-</p>
-
-<p align="center">
-  <a href="http://npm.im/js-generate-password" target="_blank">
-    <img src="https://img.shields.io/npm/v/js-generate-password.svg" alt="npm Version" />
-  </a>
-  <a href="http://npm.im/js-generate-password" target="_blank">
-    <img src="https://img.shields.io/github/v/release/ahmadjoya/js-generate-password" alt="npm Release Version" />
-  </a>
-  <a href="http://npm.im/js-generate-password" target="_blank">
-    <img src="https://img.shields.io/npm/dm/js-generate-password.svg" alt="npm Downloads" />
-  </a>
-  <a href="http://npm.im/js-generate-password" target="_blank">
-    <img src="https://img.shields.io/npm/l/js-generate-password.svg" alt="npm Package License" />
-  </a>
-</p>
-
-<p align="center">
-  <a href="https://github.com/ahmadjoya/js-generate-password/stargazers" target="_blank">
-    <img src="https://img.shields.io/github/stars/ahmadjoya/js-generate-password" alt="github Stars" />
-  </a>
-  <a href="https://github.com/ahmadjoya/js-generate-password/network/members" target="_blank">
-    <img src="https://img.shields.io/github/forks/ahmadjoya/js-generate-password" alt="github Forks" />
-  </a>
-  <a href="https://github.com/ahmadjoya/js-generate-password/stargazers" target="_blank">
-    <img src="https://img.shields.io/github/contributors/ahmadjoya/js-generate-password" alt="github Contributors" />
-  </a>
-  <a href="https://github.com/ahmadjoya/js-generate-password/issues" target="_blank">
-    <img src="https://img.shields.io/github/issues/ahmadjoya/js-generate-password" alt="github Issues" />
-  </a>
-</p>
-
-<br />
-
-# js-generate-password
-
-js-generate-password is usable for every typescript and typescript based project like react, vue, node, etc. it used to generate passwords that may contain alphabets, number and symbols. The options parameter enables the user to enable or disable the characters that are used to generate random password.
-
-The characters that may be choosen from are
-
-- Lowercase Characters
-- Uppercase Characters
-- Numbers
-- Symbols
-
-The user may also specify the minimum number of character for each type.
-
-## Installation
-
-```bash
-npm install js-generate-password
-```
-
-or
-
-```bash 
-yarn add js-generate-password
-```
-
-## Usage
-
-For the password to be generated, **parameters** are able to pass as an optional **options** object.
-
-```typescript
-import { GeneratePassword } from "js-generate-password";
-
-const password = GeneratePassword({
-  length: 14,
-  symbols: true,
-});
-
-console.log(password);
-```
-
-If no parameter is passed, the default parameter will be taken as :
-
-```typescript
-options = {
-  length: 10,
-  lowercase: true,
-  uppercase: true,
-  numbers: true,
-  symbols: false,
-  exclude: "",
-  minLengthLowercase: 1,
-  minLengthUppercase: 1,
-  minLengthNumbers: 1,
-  minLengthSymbols: 0,
-};
-```
-
-### Available options
-
-Any of these can be passed into the options object for each function.
-
-| Name               | Description                                                                                                                                                 | Default Value |
-| ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------- |
-| length             | Integer, length of password.                                                                                                                                | 10            |
-| lowercase\*        | Boolean, put lowercase letters in password                                                                                                                  | true          |
-| uppercase\*        | Boolean, put uppercase letters in password.                                                                                                                 | true          |
-| numbers\*          | Boolean, put numbers in password.                                                                                                                           | true          |
-| symbols\*          | Boolean, put symbols in password.                                                                                                                           | false         |
-| exclude            | String, characters to be excluded from password.                                                                                                            | ''            |
-| minLengthLowercase | only if **lowercase** is set to **true**, minLengthLowercase will create a password that will have minimum number of lower case characters in the password. | 1             |
-| minLengthUppercase | only if **uppercase** is set to **true**, minLengthUppercase will create a password that will have minimum number of upper case characters in the password. | 1             |
-| minLengthNumbers   | only if **numbers** is set to **true**, minLengthNumbers will create a password that will have minimum number of numbers in the password.                   | 1             |
-| minLengthSymbols   | only if **symbols** is set to **true**, minLengthSymbols will create a password that will have minimum number of symbols in the password.                   | 1             |
-
-* At least one should be true.
-
-## Example
-
-- **No Options passed.**
-
-```typescript
-const { GeneratePassword } = "js-generate-password";
-
-const password = GeneratePassword();
-
-console.log(password);
-```
-
-In the above case, no parameter is passed as option. Therefore the default values will be taken - which will have alphabets, both upper and lower case, numbers, and will be of length 10 characters.
-
-```typescript
-xDU6izb3PV;
-```
-
-- **Length parameter passed.**
-
-```typescript
-const password = GeneratePassword({ length: 25 });
-console.log(password);
-```
-
-The password generated is like this
-
-```typescript
-U4c3KpQP5UrbZgTcrqMgFeI3R;
-```
-
-- **exclude parameter passed.**
-
-```typescript
-options = {
-  exclude : 'abc567XYZ';
-}
-
-password = GeneratePassword(options);
-
-console.log(password);
-```
-
-The generated password wouldn't has none of 'abc567XYZ' characters
-
-```typescript
-J9yCfttQNj;
-```
-
-
-## License
-
-js-generate-password is licensed under the MIT License. See the [LICENSE](https://github.com/ahmadjoya/js-generate-password#readme) file for more details.
+<p align ="center">
+  <a href="https://nodei.co/npm/js-generate-password" target="_blank">
+    <img src="https://nodei.co/npm/js-generate-password.png" alt="npm Info" />
+  </a>
+</p>
+
+<p align="center">
+  <a href="https://npm.im/js-generate-password" target="_blank">
+    <img src="https://img.shields.io/npm/v/js-generate-password.svg" alt="npm Version" />
+  </a>
+  <a href="https://npm.im/js-generate-password" target="_blank">
+    <img src="https://img.shields.io/npm/dm/js-generate-password.svg" alt="npm Downloads" />
+  </a>
+  <a href="https://bundlephobia.com/package/js-generate-password" target="_blank">
+    <img src="https://img.shields.io/bundlephobia/minzip/js-generate-password" alt="Bundle Size" />
+  </a>
+  <a href="https://github.com/ahmadjoya/generate-password-lite/blob/main/LICENSE" target="_blank">
+    <img src="https://img.shields.io/npm/l/js-generate-password.svg" alt="License" />
+  </a>
+</p>
+
+<p align="center">
+  <a href="https://github.com/ahmadjoya/generate-password-lite/stargazers" target="_blank">
+    <img src="https://img.shields.io/github/stars/ahmadjoya/generate-password-lite" alt="GitHub Stars" />
+  </a>
+  <a href="https://github.com/ahmadjoya/generate-password-lite/network/members" target="_blank">
+    <img src="https://img.shields.io/github/forks/ahmadjoya/generate-password-lite" alt="GitHub Forks" />
+  </a>
+  <a href="https://github.com/ahmadjoya/generate-password-lite/issues" target="_blank">
+    <img src="https://img.shields.io/github/issues/ahmadjoya/generate-password-lite" alt="GitHub Issues" />
+  </a>
+</p>
+
+# js-generate-password
+
+A tiny, dependency-free password generator for JavaScript and TypeScript projects — Node.js, React, Next.js, Vue, Svelte, Deno, Bun, and the browser.
+
+Passwords may contain lowercase letters, uppercase letters, numbers and symbols. The `options` parameter lets you enable or disable each group, exclude specific characters, and require a minimum number of characters from each group.
+
+- **Secure by default** — every character comes from the Web Crypto CSPRNG (`crypto.getRandomValues`), never `Math.random()`.
+- **Zero dependencies** — nothing else is pulled into your lockfile.
+- **Dual ESM + CommonJS** — `import` and `require` both work, with matching type declarations.
+- **Fully typed** — TypeScript definitions ship with the package.
+
+> **Note**
+> This package is also published under the name [`generate-password-lite`](https://www.npmjs.com/package/generate-password-lite). The two packages are the same library — use whichever name you already depend on.
+
+## Installation
+
+```bash
+npm install js-generate-password
+```
+
+```bash
+yarn add js-generate-password
+```
+
+```bash
+pnpm add js-generate-password
+```
+
+**Requirements:** Node.js 18 or newer, or any modern browser. Both provide the Web Crypto API that this package relies on.
+
+## Usage
+
+### ES modules / TypeScript
+
+```ts
+import { GeneratePassword } from 'js-generate-password'
+
+const password = GeneratePassword({
+  length: 14,
+  symbols: true,
+})
+
+console.log(password) // => "q7#Rk2mV$pLx8w"
+```
+
+A default export is available too, if you prefer it:
+
+```ts
+import GeneratePassword from 'js-generate-password'
+```
+
+### CommonJS
+
+```js
+const { GeneratePassword } = require('js-generate-password')
+
+const password = GeneratePassword({ length: 14, symbols: true })
+```
+
+### React
+
+```tsx
+import { useState } from 'react'
+import { GeneratePassword } from 'js-generate-password'
+
+export function PasswordField() {
+  const [password, setPassword] = useState(() =>
+    GeneratePassword({ length: 16, symbols: true })
+  )
+
+  return (
+    <div>
+      <input readOnly value={password} />
+      <button onClick={() => setPassword(GeneratePassword({ length: 16, symbols: true }))}>
+        Regenerate
+      </button>
+    </div>
+  )
+}
+```
+
+### Next.js
+
+The package works in both the App Router and the Pages Router, on the server and in the browser.
+
+```ts
+// app/api/password/route.ts
+import { GeneratePassword } from 'js-generate-password'
+
+export function GET() {
+  return Response.json({ password: GeneratePassword({ length: 20, symbols: true }) })
+}
+```
+
+Generating a password during render of a **server component** produces a different value on the server and on the client. Generate it in an event handler, in a route handler, or inside `useState`'s initializer in a client component.
+
+## Options
+
+Every option is optional. Calling `GeneratePassword()` with no argument uses the defaults below.
+
+```ts
+GeneratePassword({
+  length: 10,
+  lowercase: true,
+  uppercase: true,
+  numbers: true,
+  symbols: false,
+  exclude: '',
+  minLengthLowercase: 1,
+  minLengthUppercase: 1,
+  minLengthNumbers: 1,
+  minLengthSymbols: 0,
+})
+```
+
+| Name                 | Type      | Description                                                                       | Default |
+| -------------------- | --------- | --------------------------------------------------------------------------------- | ------- |
+| `length`             | `number`  | Length of the generated password. Must be a positive integer.                      | `10`    |
+| `lowercase`          | `boolean` | Include lowercase letters (`a–z`).                                                 | `true`  |
+| `uppercase`          | `boolean` | Include uppercase letters (`A–Z`).                                                 | `true`  |
+| `numbers`            | `boolean` | Include digits (`0–9`).                                                            | `true`  |
+| `symbols`            | `boolean` | Include symbols (see [Symbols](#symbols)).                                         | `false` |
+| `exclude`            | `string`  | Characters to leave out of the password.                                           | `''`    |
+| `minLengthLowercase` | `number`  | Minimum number of lowercase letters. Forced to `0` when `lowercase` is `false`.    | `1`     |
+| `minLengthUppercase` | `number`  | Minimum number of uppercase letters. Forced to `0` when `uppercase` is `false`.    | `1`     |
+| `minLengthNumbers`   | `number`  | Minimum number of digits. Forced to `0` when `numbers` is `false`.                 | `1`     |
+| `minLengthSymbols`   | `number`  | Minimum number of symbols. Forced to `0` when `symbols` is `false`.                | `1`\*   |
+
+At least one of `lowercase`, `uppercase`, `numbers` or `symbols` must be `true`.
+
+\* `minLengthSymbols` defaults to `1` whenever you turn `symbols` on. Because `symbols` is `false` by default, the effective default for an untouched call is `0`.
+
+### Symbols
+
+When `symbols` is enabled the following characters are used:
+
+```text
+!#$%&'()*+,-./:;<=>?@[]^_{|}~
+```
+
+## Examples
+
+**No options.** Defaults apply: 10 characters, upper and lowercase letters plus digits, no symbols.
+
+```ts
+import { GeneratePassword } from 'js-generate-password'
+
+console.log(GeneratePassword())
+// => "xDU6izb3PV"
+```
+
+**A longer password.**
+
+```ts
+console.log(GeneratePassword({ length: 25 }))
+// => "U4c3KpQP5UrbZgTcrqMgFeI3R"
+```
+
+**Excluding characters.** Useful for dropping look-alikes such as `O`/`0` and `l`/`1`.
+
+```ts
+console.log(GeneratePassword({ length: 16, exclude: 'Ol01Il' }))
+// => "gT7yqW4nZbK9vRhs"
+```
+
+**Requiring a mix.** Guarantee at least two of each group.
+
+```ts
+console.log(
+  GeneratePassword({
+    length: 20,
+    symbols: true,
+    minLengthLowercase: 2,
+    minLengthUppercase: 2,
+    minLengthNumbers: 2,
+    minLengthSymbols: 2,
+  })
+)
+// => "k#9Wq2mZ$vT7pL4nRj%x"
+```
+
+**Digits only, for a one-time code.**
+
+```ts
+console.log(
+  GeneratePassword({
+    length: 6,
+    lowercase: false,
+    uppercase: false,
+    numbers: true,
+    symbols: false,
+  })
+)
+// => "482915"
+```
+
+## Errors
+
+`GeneratePassword` throws an `Error` when the options cannot produce a valid password:
+
+| Condition                                                                    | Example                                                              |
+| ---------------------------------------------------------------------------- | -------------------------------------------------------------------- |
+| `length` is not a positive integer                                           | `GeneratePassword({ length: 0 })`                                     |
+| A `minLength*` value is not a non-negative integer                           | `GeneratePassword({ minLengthNumbers: -1 })`                          |
+| Every character group is disabled                                            | `GeneratePassword({ lowercase: false, uppercase: false, numbers: false, symbols: false })` |
+| The `minLength*` values add up to more than `length`                         | `GeneratePassword({ length: 4, symbols: true, minLengthSymbols: 5 })` |
+| `exclude` removes every character of a group that still has a minimum        | `GeneratePassword({ exclude: '0123456789' })` — digits are on by default |
+
+The last case is worth calling out: excluding all digits while `numbers` is still `true` is a contradiction, so it fails loudly instead of quietly returning a password with no digits.
+
+## Security
+
+Passwords are generated with `crypto.getRandomValues`, the cryptographically secure random source built into Node.js 18+ and every modern browser. Values are drawn using rejection sampling, so each character in the allowed set is equally likely — a plain modulo would skew the results toward the start of the alphabet.
+
+The characters that satisfy your `minLength*` requirements are shuffled through the whole password rather than placed at the front, so the position of each group carries no information.
+
+If `globalThis.crypto` is unavailable, the package throws rather than silently falling back to a predictable random source.
+
+## TypeScript
+
+The `GenerateOptions` type is exported for reuse:
+
+```ts
+import { GeneratePassword, type GenerateOptions } from 'js-generate-password'
+
+const strongDefaults: GenerateOptions = {
+  length: 24,
+  symbols: true,
+  minLengthSymbols: 3,
+}
+
+const password = GeneratePassword(strongDefaults)
+```
+
+## Contributing
+
+Issues and pull requests are welcome at [github.com/ahmadjoya/generate-password-lite](https://github.com/ahmadjoya/generate-password-lite).
+
+```bash
+npm install
+npm run build
+npm test
+```
+
+## License
+
+[MIT](https://github.com/ahmadjoya/generate-password-lite/blob/main/LICENSE) © Ahmad Joya