@tushardev01/farm-password 1.0.11 → 1.0.13

package/README.md

@@ -25,8 +25,8 @@ genpass
 genpass -c
 ```
 
-genpass: logs random password
-genpass -c: logs random password and copies to clipboard
+- `genpass`: logs random password
+- `genpass -c`: logs random password and copies to clipboard
 
 
 ---
@@ -39,7 +39,7 @@ npm install @tushardev01/farm-password
 
 # Usage (JavaScript / ESM)
 ```bash
-import { genPassword, shuffleMax, genLowerLetters, genUpperLetters, genNumbers, genSymbols, randomNumIn, shuffle } from '@tushardev01/farm-password';
+import { genPassword, shuffleMax, genLowerLetters, genUpperLetters, genNumbers, genSymbols, randomNumIn, shuffle,collect, sample } from '@tushardev01/farm-password';
 
 // Generate a password with default character sets
 const password1 = genPassword(16);
@@ -96,11 +96,18 @@ randomNumIn(x,y): number
 
 shuffle(arr: any[],inPlace: boolean): any[]
     Returns a new array or the same one with items shuffled
+
+collect<T>(arr: T[], population?: number): T[]
+    Returns an array of randomly selected elements (duplicates allowed).
+
+sample<T>(arr: T[], population?: number): T[] | undefined
+    Returns an array of randomly selected unique elements (no duplicates).
+
 ```
 
 ### TypeScript Support
 ```bash
-import { genPassword, shuffleMax, shuffle, randomNumIn } from '@tushardev01/farm-password';
+import { genPassword, shuffleMax, shuffle, randomNumIn, sample, collect } from '@tushardev01/farm-password';
 
 const password: string = genPassword(16);
 const chars: string[] = shuffleMax(12, [
@@ -113,4 +120,4 @@ Types are included automatically via index.d.ts.
 
 ### License
 
-ISC © Tushar Kumar
+ISC © Tushar Kumar

package/app.js

@@ -7,6 +7,8 @@ import {
   genPassword,
   randomNumIn,
   shuffle,
+  sample,
+  collect
 } from './utility.js';
 
 export {
@@ -17,5 +19,7 @@ export {
   shuffleMax,
   genPassword,
   randomNumIn,
-  shuffle
-};
+  shuffle,
+  sample,
+  collect
+};

package/index.d.ts

@@ -49,6 +49,31 @@ export function shuffleMax(
   lists?: string[][] 
 ): string[];
 
+
+/**
+ * A utility function to collect a specified number of random elements from an array, 
+ * allowing duplicates in the collected array.
+ * 
+ * @param arr The array to collect random elements from.
+ * @param population The number of random elements to collect. Defaults to 5.
+ * @returns An array of random elements, which may include duplicates.
+ */
+declare function collect<T>(arr: T[], population?: number): T[];
+
+/**
+ * A utility function to sample a specified number of unique random elements from an array.
+ * 
+ * Throws an error if there aren't enough unique elements in the array to meet the requested population.
+ * 
+ * @param arr The array to sample unique random elements from.
+ * @param population The number of unique random elements to sample. Defaults to 5.
+ * @returns An array of unique random elements, or `undefined` if an error occurs.
+ * @throws Error If the number of unique elements in the array is less than the requested population.
+ */
+declare function sample<T>(arr: T[], population?: number): T[] | undefined;
+
+export { collect, sample };
+
 /**
  * Generates a password by randomly selecting characters from predefined lists (lowercase, uppercase, symbols, numbers),
  * then shuffling them to create a secure, random password.
@@ -57,4 +82,4 @@ export function shuffleMax(
  */
 export function genPassword(
   charLength?: number
-): string;
+): string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tushardev01/farm-password",
-  "version": "1.0.11",
+  "version": "1.0.13",
   "type": "module",
   "main": "./app.js",
   "exports": {
@@ -21,16 +21,23 @@
     "test": "echo \"Error: no test specified\" && exit 1"
   },
   "keywords": [
+    "utility",
+    "random",
+    "random-array",
+    "array-utils",
+    "array-sample",
+    "sampling",
+    "collect",
+    "shuffle",
+    "generator",
     "password",
     "password-generator",
-    "cli",
     "security",
-    "generator"
+    "cli",
+    "javascript",
+    "node",
+    "npm"
   ],
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/TusharKumar1007/farm-password"
-  },
   "author": "Tushar Kumar",
   "license": "ISC",
   "description": "Generates passwords and provides handy character arrays.",

package/utility.js

@@ -78,14 +78,75 @@ export const shuffleMax = (charLength = 25, lists) => {
         return arr;
 };
 
+/**
+ * Collects a specified number of random elements from an array (with possible duplicates).
+ * 
+ * @param {Array} arr - The array from which to collect random elements.
+ * @param {number} [population=5] - The number of random elements to collect. Defaults to 5.
+ * 
+ * @returns {Array} A new array containing the randomly collected elements. The array may contain duplicates.
+ * 
+ * @example
+ * const fruits = ['apple', 'banana', 'cherry', 'date', 'elderberry'];
+ * const collected = collect(fruits, 3);  // Could return ['banana', 'apple', 'banana']
+ */
+export const collect = (arr, population = 5) => {
+        const collectedArray = [];
+        for (let i = 0; i < population; i++) {
+                const randomNumber = randomNumIn(0, arr.length - 1);
+                collectedArray.push(arr[randomNumber]);
+        }
+        return collectedArray;
+}
+
+/**
+ * Samples a specified number of unique random elements from an array (no duplicates).
+ * 
+ * If the array has fewer unique elements than the requested population, an error will be thrown.
+ * 
+ * @param {Array} arr - The array from which to sample unique random elements.
+ * @param {number} [population=5] - The number of unique random elements to sample. Defaults to 5.
+ * 
+ * @returns {Array|undefined} An array of unique sampled elements, or `undefined` if an error occurs.
+ * 
+ * @throws {Error} Throws an error if there are not enough unique elements in the array to meet the requested population.
+ * 
+ * @example
+ * const fruits = ['apple', 'banana', 'cherry', 'date', 'elderberry'];
+ * const sampled = sample(fruits, 3);  // Could return ['banana', 'apple', 'cherry']
+ * 
+ * @example
+ * const fruits = ['apple', 'banana', 'apple', 'banana'];
+ * sample(fruits, 3);  // Throws an error: "Array length without duplicates must be greater than population."
+ */
+export const sample = (arr, population = 5) => {
+        const set = new Set();
+        try {
+                if (new Set(arr).size < population) {
+                        throw new Error("Array length without duplicates must be greater than population. Use collect function instead.");
+                }
+                while (set.size !== population) {
+                        const randomNumber = randomNumIn(0, arr.length - 1);
+                        set.add(arr[randomNumber]);
+                }
+
+                return [...set];
+        } catch (e) {
+                console.error(e);
+                return undefined;
+        }
+}
+
+
 /**
  * Generates a password by randomly selecting characters from predefined lists (lowercase, uppercase, symbols, numbers),
  * then shuffling them to create a secure, random password.
  * @param {number} [charLength=25] The length of the password to generate. Default is 25 characters.
  * @returns {string} The generated random password.
  */
-const passLists=[genLowerLetters(),genNumbers(),genSymbols(),genUpperLetters()];
+const passLists = [genLowerLetters(), genNumbers(), genSymbols(), genUpperLetters()];
 export const genPassword = (charLength = 25) => {
         const password = shuffle(shuffleMax(charLength, passLists)).join('');
         return password;
 };
+