@systemix/password 0.0.1 → 0.0.3

package/README.md

@@ -1,14 +1,17 @@
 # @systemix/password
 
+[![npm](https://img.shields.io/npm/v/@systemix/password.svg)](https://www.npmjs.com/package/@systemix/password)
+
 `@systemix/password` is a customizable, lightweight, and cryptographically secure password generator for JavaScript and TypeScript. Built for maximum security, it relies entirely on Node.js built-in `crypto` modules, ensuring zero external dependencies and a low supply-chain risk profile.
 
 ## Features
 
-- **Secure**: Uses `crypto.getRandomValues()` for cryptographically strong random data.
+- **Secure**: Uses `crypto.getRandomValues()` with bias-free distribution for maximum security.
+- **Character Guarantees**: Ensure a minimum number of uppercase, lowercase, numbers, or symbols.
+- **Custom Charsets**: Pass your own character sets for generation.
+- **Entropy Calculation**: Built-in utility to calculate technical password entropy.
 - **Zero Dependencies**: Purely built with Node.js built-ins.
 - **TypeScript Ready**: Full type definitions included.
-- **Customizable**: Control length, character sets (numbers, symbols, uppercase, lowercase), and exclude similar characters.
-- **Validation**: Built-in strict validation for generation options.
 
 ## Installation
 
@@ -22,6 +25,14 @@ or
 npm install @systemix/password
 ```
 
+From GitHub Packages (add to `.npmrc`: `@shahadathhs:registry=https://npm.pkg.github.com`):
+
+```bash
+pnpm add @shahadathhs/password
+```
+
+Use `@shahadathhs/password` in imports.
+
 ## Usage
 
 ### Simple Example
@@ -33,37 +44,58 @@ const password = generatePassword({
   length: 16,
   useNumbers: true,
   useSymbols: true,
-  useUppercase: true,
-  useLowercase: true,
 });
 
 console.log(password); // Example: "Z#kM@4p*J!h2X&b7"
 ```
 
-### Advanced Configuration
+### Guarantees and Character Sets
 
 ```typescript
-const password = generatePassword({
+const securePass = generatePassword({
   length: 12,
-  useNumbers: true,
-  excludeSimilarCharacters: true, // Excludes: i, l, 1, L, o, 0, O
-  exclude: 'abc', // Manually exclude specific characters
+  minNumbers: 2,
+  minSymbols: 2,
+  useUppercase: true,
+  customSymbols: '!@#$%^&*', // Use specific symbols only
 });
 ```
 
+### Entropy Calculation
+
+```typescript
+import { calculatePasswordEntropy } from '@systemix/password';
+
+const entropy = calculatePasswordEntropy(12, 62); // length, charset size
+console.log(`Entropy: ${entropy} bits`);
+```
+
 ## API Reference
 
-### `generatePassword(props?: PasswordProps): string`
-
-| Property                   | Type      | Default | Description                          |
-| :------------------------- | :-------- | :------ | :----------------------------------- |
-| `length`                   | `number`  | `8`     | Password length (1 to 50).           |
-| `useNumbers`               | `boolean` | `true`  | Include 0-9.                         |
-| `useUppercase`             | `boolean` | `true`  | Include A-Z.                         |
-| `useLowercase`             | `boolean` | `true`  | Include a-z.                         |
-| `useSymbols`               | `boolean` | `false` | Include special characters.          |
-| `excludeSimilarCharacters` | `boolean` | `false` | Exclude visually similar characters. |
-| `exclude`                  | `string`  | `""`    | Specific characters to exclude.      |
+### `generatePassword(props?: PasswordProps): string | string[]`
+
+| Property                   | Type      | Default   | Description                           |
+| :------------------------- | :-------- | :-------- | :------------------------------------ |
+| `length`                   | `number`  | `12`      | Password length (1 to 100).           |
+| `useNumbers`               | `boolean` | `true`    | Include 0-9.                          |
+| `useUppercase`             | `boolean` | `true`    | Include A-Z.                          |
+| `useLowercase`             | `boolean` | `true`    | Include a-z.                          |
+| `useSymbols`               | `boolean` | `false`   | Include special characters.           |
+| `minNumbers`               | `number`  | `0`       | Minimum numbers to include.           |
+| `minUppercase`             | `number`  | `0`       | Minimum uppercase letters to include. |
+| `minLowercase`             | `number`  | `0`       | Minimum lowercase letters to include. |
+| `minSymbols`               | `number`  | `0`       | Minimum symbols to include.           |
+| `customNumbers`            | `string`  | _0-9_     | Custom number set.                    |
+| `customUppercase`          | `string`  | _A-Z_     | Custom uppercase set.                 |
+| `customLowercase`          | `string`  | _a-z_     | Custom lowercase set.                 |
+| `customSymbols`            | `string`  | _Special_ | Custom symbol set.                    |
+| `excludeSimilarCharacters` | `boolean` | `false`   | Exclude visually similar characters.  |
+| `exclude`                  | `string`  | `""`      | Specific characters to exclude.       |
+| `count`                    | `number`  | `1`       | Number of passwords to generate.      |
+
+### `calculatePasswordEntropy(length: number, charsetSize: number): number`
+
+Calculates the theoretical entropy of a password (H = L \* log2(N)).
 
 ## License
 

package/dist/index.cjs

@@ -22,6 +22,7 @@ var index_exports = {};
 __export(index_exports, {
   GeneratePasswordPropsEnum: () => GeneratePasswordPropsEnum,
   allOptionsFalseError: () => allOptionsFalseError,
+  calculatePasswordEntropy: () => calculatePasswordEntropy,
   countError: () => countError,
   excludeError: () => excludeError,
   excludeSimilarCharactersError: () => excludeSimilarCharactersError,
@@ -45,6 +46,14 @@ var GeneratePasswordPropsEnum = /* @__PURE__ */ ((GeneratePasswordPropsEnum2) =>
   GeneratePasswordPropsEnum2["EXCLUDE_SIMILAR_CHARACTERS"] = "excludeSimilarCharacters";
   GeneratePasswordPropsEnum2["EXCLUDE"] = "exclude";
   GeneratePasswordPropsEnum2["COUNT"] = "count";
+  GeneratePasswordPropsEnum2["MIN_NUMBERS"] = "minNumbers";
+  GeneratePasswordPropsEnum2["MIN_UPPERCASE"] = "minUppercase";
+  GeneratePasswordPropsEnum2["MIN_LOWERCASE"] = "minLowercase";
+  GeneratePasswordPropsEnum2["MIN_SYMBOLS"] = "minSymbols";
+  GeneratePasswordPropsEnum2["CUSTOM_LOWERCASE"] = "customLowercase";
+  GeneratePasswordPropsEnum2["CUSTOM_UPPERCASE"] = "customUppercase";
+  GeneratePasswordPropsEnum2["CUSTOM_NUMBERS"] = "customNumbers";
+  GeneratePasswordPropsEnum2["CUSTOM_SYMBOLS"] = "customSymbols";
   return GeneratePasswordPropsEnum2;
 })(GeneratePasswordPropsEnum || {});
 
@@ -89,14 +98,46 @@ function generatePasswordPropValidation(props) {
     useSymbols,
     excludeSimilarCharacters,
     exclude,
-    count
+    count,
+    minNumbers,
+    minUppercase,
+    minLowercase,
+    minSymbols,
+    customNumbers,
+    customUppercase,
+    customLowercase,
+    customSymbols
   } = props;
   if (typeof length !== "number" || length < 1) {
     throw new Error(lengthError.invalidLength);
   }
-  if (length > 50) {
+  if (length > 100) {
     throw new Error(lengthError.lengthTooLarge);
   }
+  const checkMin = (val, name) => {
+    if (val !== void 0 && (typeof val !== "number" || val < 0)) {
+      throw new Error(`${name} must be a non-negative number.`);
+    }
+  };
+  checkMin(minNumbers, "minNumbers");
+  checkMin(minUppercase, "minUppercase");
+  checkMin(minLowercase, "minLowercase");
+  checkMin(minSymbols, "minSymbols");
+  const totalMin = (minNumbers ?? 0) + (minUppercase ?? 0) + (minLowercase ?? 0) + (minSymbols ?? 0);
+  if (totalMin > length) {
+    throw new Error(
+      "Total minimum character requirements exceed requested password length."
+    );
+  }
+  const checkString = (val, name) => {
+    if (val !== void 0 && typeof val !== "string") {
+      throw new Error(`${name} must be a string.`);
+    }
+  };
+  checkString(customNumbers, "customNumbers");
+  checkString(customUppercase, "customUppercase");
+  checkString(customLowercase, "customLowercase");
+  checkString(customSymbols, "customSymbols");
   if (typeof useNumbers !== "boolean") {
     throw new Error(useNumbersError);
   }
@@ -127,9 +168,32 @@ function generatePasswordPropValidation(props) {
 }
 
 // src/functions/generate.function.ts
+function calculatePasswordEntropy(length, charsetSize) {
+  if (length <= 0 || charsetSize <= 0) return 0;
+  return length * Math.log2(charsetSize);
+}
+function getRandomInt(max) {
+  if (max <= 1) return 0;
+  const array = new Uint32Array(1);
+  const range = Math.floor(4294967295 / max) * max;
+  let randomValue;
+  do {
+    import_node_crypto.webcrypto.getRandomValues(array);
+    randomValue = array[0];
+  } while (randomValue >= range);
+  return randomValue % max;
+}
+function shuffleString(str) {
+  const arr = str.split("");
+  for (let i = arr.length - 1; i > 0; i--) {
+    const j = getRandomInt(i + 1);
+    [arr[i], arr[j]] = [arr[j], arr[i]];
+  }
+  return arr.join("");
+}
 function generatePassword(props = {}) {
   const {
-    length = 8,
+    length = 12,
     useNumbers = true,
     useUppercase = true,
     useLowercase = true,
@@ -137,57 +201,76 @@ function generatePassword(props = {}) {
     excludeSimilarCharacters = false,
     exclude = "",
     count = 1,
-    ...extraProps
+    minUppercase = 0,
+    minLowercase = 0,
+    minNumbers = 0,
+    minSymbols = 0,
+    customUppercase = "ABCDEFGHIJKLMNOPQRSTUVWXYZ",
+    customLowercase = "abcdefghijklmnopqrstuvwxyz",
+    customNumbers = "0123456789",
+    customSymbols = "@#$%^&*()_+=<>?/|"
   } = props;
-  const allProps = {
-    length,
-    useNumbers,
-    useUppercase,
-    useLowercase,
-    useSymbols,
-    excludeSimilarCharacters,
-    exclude,
-    count,
-    ...extraProps
-  };
-  generatePasswordPropValidation(allProps);
-  const lowercaseChars = "abcdefghijklmnopqrstuvwxyz";
-  const uppercaseChars = "ABCDEFGHIJKLMNOPQRSTUVWXYZ";
-  const numberChars = "0123456789";
-  const symbolChars = "@#$%^&*()_+=<>?/|";
+  generatePasswordPropValidation(props);
   const similarChars = "il1Lo0O";
-  let charset = "";
-  const charsetOptions = [
-    { condition: useLowercase, value: lowercaseChars },
-    { condition: useUppercase, value: uppercaseChars },
-    { condition: useNumbers, value: numberChars },
-    { condition: useSymbols, value: symbolChars }
-  ];
-  charset = charsetOptions.reduce((acc, { condition, value }) => {
-    return condition ? acc + value : acc;
-  }, "");
-  if (excludeSimilarCharacters) {
-    charset = charset.split("").filter((char) => !similarChars.includes(char)).join("");
-  }
-  if (exclude) {
-    charset = charset.split("").filter((char) => !exclude.includes(char)).join("");
-  }
-  if (charset.length === 0) {
+  const filterCharset = (base) => {
+    let result = base;
+    if (excludeSimilarCharacters) {
+      result = result.split("").filter((char) => !similarChars.includes(char)).join("");
+    }
+    if (exclude) {
+      result = result.split("").filter((char) => !exclude.includes(char)).join("");
+    }
+    return result;
+  };
+  const charsets = {
+    uppercase: filterCharset(customUppercase),
+    lowercase: filterCharset(customLowercase),
+    numbers: filterCharset(customNumbers),
+    symbols: filterCharset(customSymbols)
+  };
+  const activeCharsets = [];
+  if (useUppercase && charsets.uppercase)
+    activeCharsets.push(charsets.uppercase);
+  if (useLowercase && charsets.lowercase)
+    activeCharsets.push(charsets.lowercase);
+  if (useNumbers && charsets.numbers) activeCharsets.push(charsets.numbers);
+  if (useSymbols && charsets.symbols) activeCharsets.push(charsets.symbols);
+  const fullCharset = activeCharsets.join("");
+  if (fullCharset.length === 0) {
     throw new Error("No valid characters to generate password.");
   }
   const generateSinglePassword = () => {
-    const randomIndices = new Uint32Array(length);
-    import_node_crypto.webcrypto.getRandomValues(randomIndices);
-    const password = Array.from(randomIndices).map((index) => charset[index % charset.length]).join("");
-    return password;
+    const passwordChars = [];
+    const addGuaranteed = (count2, set) => {
+      if (count2 > 0 && set.length > 0) {
+        for (let i = 0; i < count2; i++) {
+          passwordChars.push(set[getRandomInt(set.length)]);
+        }
+      }
+    };
+    if (useUppercase) addGuaranteed(minUppercase, charsets.uppercase);
+    if (useLowercase) addGuaranteed(minLowercase, charsets.lowercase);
+    if (useNumbers) addGuaranteed(minNumbers, charsets.numbers);
+    if (useSymbols) addGuaranteed(minSymbols, charsets.symbols);
+    if (passwordChars.length > length) {
+      throw new Error(
+        "Minimum character requirements exceed requested password length."
+      );
+    }
+    const remainingLength = length - passwordChars.length;
+    for (let i = 0; i < remainingLength; i++) {
+      passwordChars.push(fullCharset[getRandomInt(fullCharset.length)]);
+    }
+    return shuffleString(passwordChars.join(""));
   };
   if (count === 1) return generateSinglePassword();
-  return Array.from({ length: count }, generateSinglePassword);
+  return Array.from({ length: count }, () => generateSinglePassword());
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   GeneratePasswordPropsEnum,
   allOptionsFalseError,
+  calculatePasswordEntropy,
   countError,
   excludeError,
   excludeSimilarCharactersError,

package/dist/index.d.cts

@@ -6,14 +6,33 @@ declare enum GeneratePasswordPropsEnum {
     USE_SYMBOLS = "useSymbols",
     EXCLUDE_SIMILAR_CHARACTERS = "excludeSimilarCharacters",
     EXCLUDE = "exclude",
-    COUNT = "count"
+    COUNT = "count",
+    MIN_NUMBERS = "minNumbers",
+    MIN_UPPERCASE = "minUppercase",
+    MIN_LOWERCASE = "minLowercase",
+    MIN_SYMBOLS = "minSymbols",
+    CUSTOM_LOWERCASE = "customLowercase",
+    CUSTOM_UPPERCASE = "customUppercase",
+    CUSTOM_NUMBERS = "customNumbers",
+    CUSTOM_SYMBOLS = "customSymbols"
 }
 
 type GeneratePasswordFunctionProps = {
-    [key in GeneratePasswordPropsEnum]?: key extends GeneratePasswordPropsEnum.LENGTH | GeneratePasswordPropsEnum.COUNT ? number : key extends GeneratePasswordPropsEnum.EXCLUDE ? string : key extends GeneratePasswordPropsEnum.USE_NUMBERS | GeneratePasswordPropsEnum.USE_UPPERCASE | GeneratePasswordPropsEnum.USE_LOWERCASE | GeneratePasswordPropsEnum.USE_SYMBOLS | GeneratePasswordPropsEnum.EXCLUDE_SIMILAR_CHARACTERS ? boolean : never;
+    [key in GeneratePasswordPropsEnum]?: key extends GeneratePasswordPropsEnum.LENGTH | GeneratePasswordPropsEnum.COUNT | GeneratePasswordPropsEnum.MIN_NUMBERS | GeneratePasswordPropsEnum.MIN_UPPERCASE | GeneratePasswordPropsEnum.MIN_LOWERCASE | GeneratePasswordPropsEnum.MIN_SYMBOLS ? number : key extends GeneratePasswordPropsEnum.EXCLUDE | GeneratePasswordPropsEnum.CUSTOM_LOWERCASE | GeneratePasswordPropsEnum.CUSTOM_UPPERCASE | GeneratePasswordPropsEnum.CUSTOM_NUMBERS | GeneratePasswordPropsEnum.CUSTOM_SYMBOLS ? string : key extends GeneratePasswordPropsEnum.USE_NUMBERS | GeneratePasswordPropsEnum.USE_UPPERCASE | GeneratePasswordPropsEnum.USE_LOWERCASE | GeneratePasswordPropsEnum.USE_SYMBOLS | GeneratePasswordPropsEnum.EXCLUDE_SIMILAR_CHARACTERS ? boolean : never;
 };
 
-declare function generatePassword(props?: GeneratePasswordFunctionProps): string | string[];
+interface ExtendedGeneratePasswordFunctionProps extends GeneratePasswordFunctionProps {
+    minUppercase?: number;
+    minLowercase?: number;
+    minNumbers?: number;
+    minSymbols?: number;
+    customUppercase?: string;
+    customLowercase?: string;
+    customNumbers?: string;
+    customSymbols?: string;
+}
+declare function calculatePasswordEntropy(length: number, charsetSize: number): number;
+declare function generatePassword(props?: ExtendedGeneratePasswordFunctionProps): string | string[];
 
 declare const lengthError: {
     invalidLength: string;
@@ -32,4 +51,4 @@ declare const countError: {
 declare const unwantedPropsError: (unwantedProps: string[]) => string;
 declare const allOptionsFalseError = "At least one of the options must be true.";
 
-export { type GeneratePasswordFunctionProps, GeneratePasswordPropsEnum, allOptionsFalseError, countError, excludeError, excludeSimilarCharactersError, generatePassword, lengthError, unwantedPropsError, useLowercaseError, useNumbersError, useSymbolsError, useUppercaseError };
+export { type ExtendedGeneratePasswordFunctionProps, type GeneratePasswordFunctionProps, GeneratePasswordPropsEnum, allOptionsFalseError, calculatePasswordEntropy, countError, excludeError, excludeSimilarCharactersError, generatePassword, lengthError, unwantedPropsError, useLowercaseError, useNumbersError, useSymbolsError, useUppercaseError };

package/dist/index.d.ts

@@ -6,14 +6,33 @@ declare enum GeneratePasswordPropsEnum {
     USE_SYMBOLS = "useSymbols",
     EXCLUDE_SIMILAR_CHARACTERS = "excludeSimilarCharacters",
     EXCLUDE = "exclude",
-    COUNT = "count"
+    COUNT = "count",
+    MIN_NUMBERS = "minNumbers",
+    MIN_UPPERCASE = "minUppercase",
+    MIN_LOWERCASE = "minLowercase",
+    MIN_SYMBOLS = "minSymbols",
+    CUSTOM_LOWERCASE = "customLowercase",
+    CUSTOM_UPPERCASE = "customUppercase",
+    CUSTOM_NUMBERS = "customNumbers",
+    CUSTOM_SYMBOLS = "customSymbols"
 }
 
 type GeneratePasswordFunctionProps = {
-    [key in GeneratePasswordPropsEnum]?: key extends GeneratePasswordPropsEnum.LENGTH | GeneratePasswordPropsEnum.COUNT ? number : key extends GeneratePasswordPropsEnum.EXCLUDE ? string : key extends GeneratePasswordPropsEnum.USE_NUMBERS | GeneratePasswordPropsEnum.USE_UPPERCASE | GeneratePasswordPropsEnum.USE_LOWERCASE | GeneratePasswordPropsEnum.USE_SYMBOLS | GeneratePasswordPropsEnum.EXCLUDE_SIMILAR_CHARACTERS ? boolean : never;
+    [key in GeneratePasswordPropsEnum]?: key extends GeneratePasswordPropsEnum.LENGTH | GeneratePasswordPropsEnum.COUNT | GeneratePasswordPropsEnum.MIN_NUMBERS | GeneratePasswordPropsEnum.MIN_UPPERCASE | GeneratePasswordPropsEnum.MIN_LOWERCASE | GeneratePasswordPropsEnum.MIN_SYMBOLS ? number : key extends GeneratePasswordPropsEnum.EXCLUDE | GeneratePasswordPropsEnum.CUSTOM_LOWERCASE | GeneratePasswordPropsEnum.CUSTOM_UPPERCASE | GeneratePasswordPropsEnum.CUSTOM_NUMBERS | GeneratePasswordPropsEnum.CUSTOM_SYMBOLS ? string : key extends GeneratePasswordPropsEnum.USE_NUMBERS | GeneratePasswordPropsEnum.USE_UPPERCASE | GeneratePasswordPropsEnum.USE_LOWERCASE | GeneratePasswordPropsEnum.USE_SYMBOLS | GeneratePasswordPropsEnum.EXCLUDE_SIMILAR_CHARACTERS ? boolean : never;
 };
 
-declare function generatePassword(props?: GeneratePasswordFunctionProps): string | string[];
+interface ExtendedGeneratePasswordFunctionProps extends GeneratePasswordFunctionProps {
+    minUppercase?: number;
+    minLowercase?: number;
+    minNumbers?: number;
+    minSymbols?: number;
+    customUppercase?: string;
+    customLowercase?: string;
+    customNumbers?: string;
+    customSymbols?: string;
+}
+declare function calculatePasswordEntropy(length: number, charsetSize: number): number;
+declare function generatePassword(props?: ExtendedGeneratePasswordFunctionProps): string | string[];
 
 declare const lengthError: {
     invalidLength: string;
@@ -32,4 +51,4 @@ declare const countError: {
 declare const unwantedPropsError: (unwantedProps: string[]) => string;
 declare const allOptionsFalseError = "At least one of the options must be true.";
 
-export { type GeneratePasswordFunctionProps, GeneratePasswordPropsEnum, allOptionsFalseError, countError, excludeError, excludeSimilarCharactersError, generatePassword, lengthError, unwantedPropsError, useLowercaseError, useNumbersError, useSymbolsError, useUppercaseError };
+export { type ExtendedGeneratePasswordFunctionProps, type GeneratePasswordFunctionProps, GeneratePasswordPropsEnum, allOptionsFalseError, calculatePasswordEntropy, countError, excludeError, excludeSimilarCharactersError, generatePassword, lengthError, unwantedPropsError, useLowercaseError, useNumbersError, useSymbolsError, useUppercaseError };

package/dist/index.js

@@ -8,6 +8,14 @@ var GeneratePasswordPropsEnum = /* @__PURE__ */ ((GeneratePasswordPropsEnum2) =>
   GeneratePasswordPropsEnum2["EXCLUDE_SIMILAR_CHARACTERS"] = "excludeSimilarCharacters";
   GeneratePasswordPropsEnum2["EXCLUDE"] = "exclude";
   GeneratePasswordPropsEnum2["COUNT"] = "count";
+  GeneratePasswordPropsEnum2["MIN_NUMBERS"] = "minNumbers";
+  GeneratePasswordPropsEnum2["MIN_UPPERCASE"] = "minUppercase";
+  GeneratePasswordPropsEnum2["MIN_LOWERCASE"] = "minLowercase";
+  GeneratePasswordPropsEnum2["MIN_SYMBOLS"] = "minSymbols";
+  GeneratePasswordPropsEnum2["CUSTOM_LOWERCASE"] = "customLowercase";
+  GeneratePasswordPropsEnum2["CUSTOM_UPPERCASE"] = "customUppercase";
+  GeneratePasswordPropsEnum2["CUSTOM_NUMBERS"] = "customNumbers";
+  GeneratePasswordPropsEnum2["CUSTOM_SYMBOLS"] = "customSymbols";
   return GeneratePasswordPropsEnum2;
 })(GeneratePasswordPropsEnum || {});
 
@@ -52,14 +60,46 @@ function generatePasswordPropValidation(props) {
     useSymbols,
     excludeSimilarCharacters,
     exclude,
-    count
+    count,
+    minNumbers,
+    minUppercase,
+    minLowercase,
+    minSymbols,
+    customNumbers,
+    customUppercase,
+    customLowercase,
+    customSymbols
   } = props;
   if (typeof length !== "number" || length < 1) {
     throw new Error(lengthError.invalidLength);
   }
-  if (length > 50) {
+  if (length > 100) {
     throw new Error(lengthError.lengthTooLarge);
   }
+  const checkMin = (val, name) => {
+    if (val !== void 0 && (typeof val !== "number" || val < 0)) {
+      throw new Error(`${name} must be a non-negative number.`);
+    }
+  };
+  checkMin(minNumbers, "minNumbers");
+  checkMin(minUppercase, "minUppercase");
+  checkMin(minLowercase, "minLowercase");
+  checkMin(minSymbols, "minSymbols");
+  const totalMin = (minNumbers ?? 0) + (minUppercase ?? 0) + (minLowercase ?? 0) + (minSymbols ?? 0);
+  if (totalMin > length) {
+    throw new Error(
+      "Total minimum character requirements exceed requested password length."
+    );
+  }
+  const checkString = (val, name) => {
+    if (val !== void 0 && typeof val !== "string") {
+      throw new Error(`${name} must be a string.`);
+    }
+  };
+  checkString(customNumbers, "customNumbers");
+  checkString(customUppercase, "customUppercase");
+  checkString(customLowercase, "customLowercase");
+  checkString(customSymbols, "customSymbols");
   if (typeof useNumbers !== "boolean") {
     throw new Error(useNumbersError);
   }
@@ -90,9 +130,32 @@ function generatePasswordPropValidation(props) {
 }
 
 // src/functions/generate.function.ts
+function calculatePasswordEntropy(length, charsetSize) {
+  if (length <= 0 || charsetSize <= 0) return 0;
+  return length * Math.log2(charsetSize);
+}
+function getRandomInt(max) {
+  if (max <= 1) return 0;
+  const array = new Uint32Array(1);
+  const range = Math.floor(4294967295 / max) * max;
+  let randomValue;
+  do {
+    crypto.getRandomValues(array);
+    randomValue = array[0];
+  } while (randomValue >= range);
+  return randomValue % max;
+}
+function shuffleString(str) {
+  const arr = str.split("");
+  for (let i = arr.length - 1; i > 0; i--) {
+    const j = getRandomInt(i + 1);
+    [arr[i], arr[j]] = [arr[j], arr[i]];
+  }
+  return arr.join("");
+}
 function generatePassword(props = {}) {
   const {
-    length = 8,
+    length = 12,
     useNumbers = true,
     useUppercase = true,
     useLowercase = true,
@@ -100,56 +163,75 @@ function generatePassword(props = {}) {
     excludeSimilarCharacters = false,
     exclude = "",
     count = 1,
-    ...extraProps
+    minUppercase = 0,
+    minLowercase = 0,
+    minNumbers = 0,
+    minSymbols = 0,
+    customUppercase = "ABCDEFGHIJKLMNOPQRSTUVWXYZ",
+    customLowercase = "abcdefghijklmnopqrstuvwxyz",
+    customNumbers = "0123456789",
+    customSymbols = "@#$%^&*()_+=<>?/|"
   } = props;
-  const allProps = {
-    length,
-    useNumbers,
-    useUppercase,
-    useLowercase,
-    useSymbols,
-    excludeSimilarCharacters,
-    exclude,
-    count,
-    ...extraProps
-  };
-  generatePasswordPropValidation(allProps);
-  const lowercaseChars = "abcdefghijklmnopqrstuvwxyz";
-  const uppercaseChars = "ABCDEFGHIJKLMNOPQRSTUVWXYZ";
-  const numberChars = "0123456789";
-  const symbolChars = "@#$%^&*()_+=<>?/|";
+  generatePasswordPropValidation(props);
   const similarChars = "il1Lo0O";
-  let charset = "";
-  const charsetOptions = [
-    { condition: useLowercase, value: lowercaseChars },
-    { condition: useUppercase, value: uppercaseChars },
-    { condition: useNumbers, value: numberChars },
-    { condition: useSymbols, value: symbolChars }
-  ];
-  charset = charsetOptions.reduce((acc, { condition, value }) => {
-    return condition ? acc + value : acc;
-  }, "");
-  if (excludeSimilarCharacters) {
-    charset = charset.split("").filter((char) => !similarChars.includes(char)).join("");
-  }
-  if (exclude) {
-    charset = charset.split("").filter((char) => !exclude.includes(char)).join("");
-  }
-  if (charset.length === 0) {
+  const filterCharset = (base) => {
+    let result = base;
+    if (excludeSimilarCharacters) {
+      result = result.split("").filter((char) => !similarChars.includes(char)).join("");
+    }
+    if (exclude) {
+      result = result.split("").filter((char) => !exclude.includes(char)).join("");
+    }
+    return result;
+  };
+  const charsets = {
+    uppercase: filterCharset(customUppercase),
+    lowercase: filterCharset(customLowercase),
+    numbers: filterCharset(customNumbers),
+    symbols: filterCharset(customSymbols)
+  };
+  const activeCharsets = [];
+  if (useUppercase && charsets.uppercase)
+    activeCharsets.push(charsets.uppercase);
+  if (useLowercase && charsets.lowercase)
+    activeCharsets.push(charsets.lowercase);
+  if (useNumbers && charsets.numbers) activeCharsets.push(charsets.numbers);
+  if (useSymbols && charsets.symbols) activeCharsets.push(charsets.symbols);
+  const fullCharset = activeCharsets.join("");
+  if (fullCharset.length === 0) {
     throw new Error("No valid characters to generate password.");
   }
   const generateSinglePassword = () => {
-    const randomIndices = new Uint32Array(length);
-    crypto.getRandomValues(randomIndices);
-    const password = Array.from(randomIndices).map((index) => charset[index % charset.length]).join("");
-    return password;
+    const passwordChars = [];
+    const addGuaranteed = (count2, set) => {
+      if (count2 > 0 && set.length > 0) {
+        for (let i = 0; i < count2; i++) {
+          passwordChars.push(set[getRandomInt(set.length)]);
+        }
+      }
+    };
+    if (useUppercase) addGuaranteed(minUppercase, charsets.uppercase);
+    if (useLowercase) addGuaranteed(minLowercase, charsets.lowercase);
+    if (useNumbers) addGuaranteed(minNumbers, charsets.numbers);
+    if (useSymbols) addGuaranteed(minSymbols, charsets.symbols);
+    if (passwordChars.length > length) {
+      throw new Error(
+        "Minimum character requirements exceed requested password length."
+      );
+    }
+    const remainingLength = length - passwordChars.length;
+    for (let i = 0; i < remainingLength; i++) {
+      passwordChars.push(fullCharset[getRandomInt(fullCharset.length)]);
+    }
+    return shuffleString(passwordChars.join(""));
   };
   if (count === 1) return generateSinglePassword();
-  return Array.from({ length: count }, generateSinglePassword);
+  return Array.from({ length: count }, () => generateSinglePassword());
 }
 export {
   GeneratePasswordPropsEnum,
   allOptionsFalseError,
+  calculatePasswordEntropy,
   countError,
   excludeError,
   excludeSimilarCharactersError,

package/package.json

@@ -1,31 +1,27 @@
 {
   "name": "@systemix/password",
-  "version": "0.0.1",
+  "version": "0.0.3",
   "publishConfig": {
     "access": "public"
   },
   "private": false,
   "type": "module",
-  "main": "./dist/index.js",
-  "module": "./dist/index.mjs",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
   "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
   "repository": {
     "type": "git",
     "url": "git+https://github.com/shahadathhs/systemix.git",
     "directory": "packages/password"
   },
   "homepage": "https://github.com/shahadathhs/systemix/tree/main/packages/password#readme",
-  "scripts": {
-    "build": "tsup src/index.ts --format cjs,esm --dts",
-    "typecheck": "tsc --noEmit",
-    "lint": "eslint .",
-    "lint:fix": "eslint . --fix",
-    "format": "prettier --check . --ignore-path .prettierignore",
-    "format:fix": "prettier --write . --ignore-path .prettierignore",
-    "clean": "rimraf dist node_modules",
-    "clean:turbo": "rimraf .turbo dist node_modules",
-    "prepublishOnly": "pnpm build"
-  },
   "keywords": [
     "systemix",
     "password",
@@ -38,16 +34,16 @@
     "node",
     "utility"
   ],
-  "author": "Shahadath Hossain <shahadath.dev@gmail.com> (https://github.com/shahadathhs)",
+  "author": "Shahadath Hossen Sajib <shahadathhossensajib732@gmail.com> (https://github.com/shahadathhs)",
   "license": "MIT",
   "description": "A cryptographically secure password generator with customizable complexity. Part of the Systemix toolkit.",
   "devDependencies": {
-    "@systemix/eslint": "workspace:*",
-    "@systemix/typescript": "workspace:*",
     "@types/node": "^25.2.3",
     "eslint": "^10.0.0",
     "tsup": "^8.5.1",
-    "typescript": "^5.9.3"
+    "typescript": "^5.9.3",
+    "@systemix/eslint": "0.2.1",
+    "@systemix/typescript": "0.2.1"
   },
   "directories": {
     "test": "tests"
@@ -63,5 +59,15 @@
     "dist",
     "README.md",
     "package.json"
-  ]
-}
+  ],
+  "scripts": {
+    "build": "tsup src/index.ts --format cjs,esm --dts",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint .",
+    "lint:fix": "eslint . --fix",
+    "format": "prettier --check . --ignore-path .prettierignore",
+    "format:fix": "prettier --write . --ignore-path .prettierignore",
+    "clean": "rimraf dist node_modules",
+    "clean:turbo": "rimraf .turbo dist node_modules"
+  }
+}

package/dist/index.d.mts

@@ -1,35 +0,0 @@
-declare enum GeneratePasswordPropsEnum {
-    LENGTH = "length",
-    USE_NUMBERS = "useNumbers",
-    USE_UPPERCASE = "useUppercase",
-    USE_LOWERCASE = "useLowercase",
-    USE_SYMBOLS = "useSymbols",
-    EXCLUDE_SIMILAR_CHARACTERS = "excludeSimilarCharacters",
-    EXCLUDE = "exclude",
-    COUNT = "count"
-}
-
-type GeneratePasswordFunctionProps = {
-    [key in GeneratePasswordPropsEnum]?: key extends GeneratePasswordPropsEnum.LENGTH | GeneratePasswordPropsEnum.COUNT ? number : key extends GeneratePasswordPropsEnum.EXCLUDE ? string : key extends GeneratePasswordPropsEnum.USE_NUMBERS | GeneratePasswordPropsEnum.USE_UPPERCASE | GeneratePasswordPropsEnum.USE_LOWERCASE | GeneratePasswordPropsEnum.USE_SYMBOLS | GeneratePasswordPropsEnum.EXCLUDE_SIMILAR_CHARACTERS ? boolean : never;
-};
-
-declare function generatePassword(props?: GeneratePasswordFunctionProps): string | string[];
-
-declare const lengthError: {
-    invalidLength: string;
-    lengthTooLarge: string;
-};
-declare const useNumbersError = "Invalid useNumbers. It must be a boolean value.";
-declare const useUppercaseError = "Invalid useUppercase. It must be a boolean value.";
-declare const useLowercaseError = "Invalid useLowercase. It must be a boolean value.";
-declare const useSymbolsError = "Invalid useSymbols. It must be a boolean value.";
-declare const excludeSimilarCharactersError = "Invalid excludeSimilarCharacters. It must be a boolean value.";
-declare const excludeError = "Invalid exclude. It must be a string.";
-declare const countError: {
-    invalidCount: string;
-    countTooLarge: string;
-};
-declare const unwantedPropsError: (unwantedProps: string[]) => string;
-declare const allOptionsFalseError = "At least one of the options must be true.";
-
-export { type GeneratePasswordFunctionProps, GeneratePasswordPropsEnum, allOptionsFalseError, countError, excludeError, excludeSimilarCharactersError, generatePassword, lengthError, unwantedPropsError, useLowercaseError, useNumbersError, useSymbolsError, useUppercaseError };

package/dist/index.mjs

@@ -1,158 +0,0 @@
-// src/enum/props.enum.ts
-var GeneratePasswordPropsEnum = /* @__PURE__ */ ((GeneratePasswordPropsEnum2) => {
-  GeneratePasswordPropsEnum2["LENGTH"] = "length";
-  GeneratePasswordPropsEnum2["USE_NUMBERS"] = "useNumbers";
-  GeneratePasswordPropsEnum2["USE_UPPERCASE"] = "useUppercase";
-  GeneratePasswordPropsEnum2["USE_LOWERCASE"] = "useLowercase";
-  GeneratePasswordPropsEnum2["USE_SYMBOLS"] = "useSymbols";
-  GeneratePasswordPropsEnum2["EXCLUDE_SIMILAR_CHARACTERS"] = "excludeSimilarCharacters";
-  GeneratePasswordPropsEnum2["EXCLUDE"] = "exclude";
-  GeneratePasswordPropsEnum2["COUNT"] = "count";
-  return GeneratePasswordPropsEnum2;
-})(GeneratePasswordPropsEnum || {});
-
-// src/utils/error.message.ts
-var lengthError = {
-  invalidLength: "Invalid length. Length must be a positive number.",
-  lengthTooLarge: "Invalid length. Length must be less than or equal to 50."
-};
-var useNumbersError = "Invalid useNumbers. It must be a boolean value.";
-var useUppercaseError = "Invalid useUppercase. It must be a boolean value.";
-var useLowercaseError = "Invalid useLowercase. It must be a boolean value.";
-var useSymbolsError = "Invalid useSymbols. It must be a boolean value.";
-var excludeSimilarCharactersError = "Invalid excludeSimilarCharacters. It must be a boolean value.";
-var excludeError = "Invalid exclude. It must be a string.";
-var countError = {
-  invalidCount: "Invalid count. Count must be a positive number.",
-  countTooLarge: "Invalid count. Count must be less than or equal to 10."
-};
-var unwantedPropsError = (unwantedProps) => {
-  return `Invalid prop(s): ${unwantedProps.join(", ")}. Only the following options are allowed: length, useNumbers, useUppercase, useLowercase, useSymbols, excludeSimilarCharacters, exclude, count.`;
-};
-var allOptionsFalseError = "At least one of the options must be true.";
-
-// src/functions/validation.function.ts
-var allValidProps = Object.values(GeneratePasswordPropsEnum);
-function generatePasswordPropValidation(props) {
-  const propsValue = Object.keys(props);
-  const unwantedProps = propsValue.filter((prop) => !allValidProps.includes(prop));
-  if (unwantedProps.length > 0) {
-    throw new Error(unwantedPropsError(unwantedProps));
-  }
-  const {
-    length,
-    useNumbers,
-    useUppercase,
-    useLowercase,
-    useSymbols,
-    excludeSimilarCharacters,
-    exclude,
-    count
-  } = props;
-  if (typeof length !== "number" || length < 1) {
-    throw new Error(lengthError.invalidLength);
-  }
-  if (length > 50) {
-    throw new Error(lengthError.lengthTooLarge);
-  }
-  if (typeof useNumbers !== "boolean") {
-    throw new Error(useNumbersError);
-  }
-  if (typeof useUppercase !== "boolean") {
-    throw new Error(useUppercaseError);
-  }
-  if (typeof useLowercase !== "boolean") {
-    throw new Error(useLowercaseError);
-  }
-  if (typeof useSymbols !== "boolean") {
-    throw new Error(useSymbolsError);
-  }
-  if (typeof excludeSimilarCharacters !== "boolean") {
-    throw new Error(excludeSimilarCharactersError);
-  }
-  if (typeof exclude !== "string") {
-    throw new Error(excludeError);
-  }
-  if (typeof count !== "number" || count < 1) {
-    throw new Error(countError.invalidCount);
-  }
-  if (count > 10) {
-    throw new Error(countError.countTooLarge);
-  }
-  if (!useNumbers && !useUppercase && !useLowercase && !useSymbols) {
-    throw new Error(allOptionsFalseError);
-  }
-}
-
-// src/functions/generate.function.ts
-function generatePassword(props = {}) {
-  const {
-    length = 8,
-    useNumbers = true,
-    useUppercase = true,
-    useLowercase = true,
-    useSymbols = false,
-    excludeSimilarCharacters = false,
-    exclude = "",
-    count = 1,
-    ...extraProps
-  } = props;
-  const allProps = {
-    length,
-    useNumbers,
-    useUppercase,
-    useLowercase,
-    useSymbols,
-    excludeSimilarCharacters,
-    exclude,
-    count,
-    ...extraProps
-  };
-  generatePasswordPropValidation(allProps);
-  const lowercaseChars = "abcdefghijklmnopqrstuvwxyz";
-  const uppercaseChars = "ABCDEFGHIJKLMNOPQRSTUVWXYZ";
-  const numberChars = "0123456789";
-  const symbolChars = "@#$%^&*()_+=<>?/|";
-  const similarChars = "il1Lo0O";
-  let charset = "";
-  const charsetOptions = [
-    { condition: useLowercase, value: lowercaseChars },
-    { condition: useUppercase, value: uppercaseChars },
-    { condition: useNumbers, value: numberChars },
-    { condition: useSymbols, value: symbolChars }
-  ];
-  charset = charsetOptions.reduce((acc, { condition, value }) => {
-    return condition ? acc + value : acc;
-  }, "");
-  if (excludeSimilarCharacters) {
-    charset = charset.split("").filter((char) => !similarChars.includes(char)).join("");
-  }
-  if (exclude) {
-    charset = charset.split("").filter((char) => !exclude.includes(char)).join("");
-  }
-  if (charset.length === 0) {
-    throw new Error("No valid characters to generate password.");
-  }
-  const generateSinglePassword = () => {
-    const randomIndices = new Uint32Array(length);
-    crypto.getRandomValues(randomIndices);
-    const password = Array.from(randomIndices).map((index) => charset[index % charset.length]).join("");
-    return password;
-  };
-  if (count === 1) return generateSinglePassword();
-  return Array.from({ length: count }, generateSinglePassword);
-}
-export {
-  GeneratePasswordPropsEnum,
-  allOptionsFalseError,
-  countError,
-  excludeError,
-  excludeSimilarCharactersError,
-  generatePassword,
-  lengthError,
-  unwantedPropsError,
-  useLowercaseError,
-  useNumbersError,
-  useSymbolsError,
-  useUppercaseError
-};