random-words-local 1.0.0

package/README.md

@@ -0,0 +1,69 @@
+# Random Words CLI
+
+A simple and secure CLI tool for generating random word passphrases.
+
+This tool uses cryptographically secure random numbers (`crypto.randomInt`) to pick words from a dictionary of over 275,000 English words, making it ideal for creating strong, memorable passphrases.
+
+## Installation
+
+You can run it directly using `npx`, or any of the laternatives such as `bunx`:
+
+```bash
+npx random-words-cli
+```
+
+Or install it globally:
+
+```bash
+npm install -g random-words-cli
+```
+
+## Usage
+
+```bash
+random-words [options]
+```
+
+### Options
+
+| Option                   | Description                                    | Default  |
+| :----------------------- | :--------------------------------------------- | :------- |
+| `-n, --count <number>`   | Number of words to generate                    | `4`      |
+| `-s, --separator <char>` | Separator between words                        | `-`      |
+| `-f, --format <type>`    | Output format: `joined`, `array`, or `newline` | `joined` |
+| `-h, --help`             | Show help message                              |          |
+
+## Examples
+
+**Default passphrase (4 words):**
+
+```bash
+random-words
+# output: correct-horse-battery-staple
+```
+
+**Generate 6 words with a space separator:**
+
+```bash
+random-words -n 6 -s " "
+```
+
+**Output as a JSON array:**
+
+```bash
+random-words -n 3 -f array
+```
+
+**One word per line:**
+
+```bash
+random-words -n 5 -f newline
+```
+
+## Security
+
+Passphrases generated by this tool are more secure than simple passwords because they are harder to brute-force but easier for humans to remember. By default, with 4 words chosen from a ~275,000 word dictionary, the entropy is approximately 72 bits ($4 \times \log_2(275,000)$).
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,72 @@
+#!/usr/bin/env node
+import { randomWords } from './words.js';
+const args = process.argv.slice(2);
+let count = 4;
+let separator = '-';
+let format = 'joined';
+for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (arg === '-n' || arg === '--count') {
+        const nextArg = args[++i];
+        if (!nextArg || isNaN(parseInt(nextArg))) {
+            console.error('Error: --count requires a valid number');
+            process.exit(1);
+        }
+        count = parseInt(nextArg);
+        if (count < 1 || count > 1000) {
+            console.error('Error: count must be between 1 and 1000');
+            process.exit(1);
+        }
+    }
+    else if (arg === '-s' || arg === '--separator') {
+        separator = args[++i];
+        if (separator === undefined) {
+            console.error('Error: --separator requires a value');
+            process.exit(1);
+        }
+    }
+    else if (arg === '-f' || arg === '--format') {
+        format = args[++i] || 'joined';
+        if (!['joined', 'array', 'newline'].includes(format)) {
+            console.error('Error: format must be one of: joined, array, newline');
+            process.exit(1);
+        }
+    }
+    else if (arg === '-h' || arg === '--help') {
+        console.log(`Usage: random-words [options]
+
+Options:
+  -n, --count <number>    Number of words to generate (default: 4)
+  -s, --separator <char>  Separator between words (default: -)
+  -f, --format <type>     Output format: joined, array, or newline (default: joined)
+  -h, --help              Show this help message
+
+Examples:
+  random-words
+  random-words -n 6
+  random-words -n 3 -s _
+  random-words -n 2 -f array`);
+        process.exit(0);
+    }
+    else if (!arg.startsWith('-')) {
+        const val = parseInt(arg);
+        if (!isNaN(val)) {
+            if (val < 1 || val > 1000) {
+                console.error('Error: count must be between 1 and 1000');
+                process.exit(1);
+            }
+            count = val;
+        }
+    }
+}
+const words = randomWords(count);
+if (format === 'array') {
+    console.log(JSON.stringify(words));
+}
+else if (format === 'newline') {
+    console.log(words.join('\n'));
+}
+else {
+    console.log(words.join(separator));
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/words.d.ts

@@ -0,0 +1,11 @@
+import words from 'an-array-of-english-words';
+/**
+ * Returns a list of random words.
+ * This is now more efficient for large lists by picking individual random indices
+ * instead of shuffling the entire array.
+ *
+ * @param count Number of words to return
+ * @returns Array of random words
+ */
+export declare function randomWords(count?: number): string[];
+export { words };

package/dist/words.js

@@ -0,0 +1,31 @@
+import { randomInt } from 'node:crypto';
+// @ts-ignore - The package doesn't have types but we know it's an array of strings
+import words from 'an-array-of-english-words';
+/**
+ * Returns a list of random words.
+ * This is now more efficient for large lists by picking individual random indices
+ * instead of shuffling the entire array.
+ *
+ * @param count Number of words to return
+ * @returns Array of random words
+ */
+export function randomWords(count = 4) {
+    const n = words.length;
+    const actualCount = Math.max(0, Math.min(count, n));
+    if (actualCount === 0)
+        return [];
+    const result = [];
+    const seenIndices = new Set();
+    // For small counts, we use a Set to pick unique indices.
+    // This is O(count) instead of O(N) where N is the total number of words (275,000+).
+    while (result.length < actualCount) {
+        const j = randomInt(0, n);
+        if (!seenIndices.has(j)) {
+            seenIndices.add(j);
+            result.push(words[j]);
+        }
+    }
+    return result;
+}
+export { words };
+//# sourceMappingURL=words.js.map

package/dist/words.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"words.js","sourceRoot":"","sources":["../src/words.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AACxC,mFAAmF;AACnF,OAAO,KAAK,MAAM,2BAA2B,CAAC;AAE9C;;;;;;;GAOG;AACH,MAAM,UAAU,WAAW,CAAC,QAAgB,CAAC;IAC3C,MAAM,CAAC,GAAG,KAAK,CAAC,MAAM,CAAC;IACvB,MAAM,WAAW,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,GAAG,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,CAAC;IAEpD,IAAI,WAAW,KAAK,CAAC;QAAE,OAAO,EAAE,CAAC;IAEjC,MAAM,MAAM,GAAa,EAAE,CAAC;IAC5B,MAAM,WAAW,GAAG,IAAI,GAAG,EAAU,CAAC;IAEtC,yDAAyD;IACzD,oFAAoF;IACpF,OAAO,MAAM,CAAC,MAAM,GAAG,WAAW,EAAE,CAAC;QACnC,MAAM,CAAC,GAAG,SAAS,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;QAC1B,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC;YACxB,WAAW,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;YACnB,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;QACxB,CAAC;IACH,CAAC;IAED,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,OAAO,EAAE,KAAK,EAAE,CAAC"}

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "random-words-local",
+  "version": "1.0.0",
+  "description": "Generate random words from English dictionary",
+  "main": "dist/index.js",
+  "bin": {
+    "random-words": "dist/index.js"
+  },
+  "type": "module",
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "npm run build",
+    "start": "node dist/index.js",
+    "dev": "tsx src/index.ts"
+  },
+  "keywords": [
+    "random",
+    "words",
+    "cli",
+    "generator"
+  ],
+  "author": "",
+  "license": "MIT",
+  "devDependencies": {
+    "@types/node": "^25.3.0",
+    "tsx": "^4.21.0",
+    "typescript": "^5.9.3"
+  },
+  "dependencies": {
+    "an-array-of-english-words": "^2.0.0"
+  }
+}

package/src/index.ts

@@ -0,0 +1,70 @@
+#!/usr/bin/env node
+
+import { randomWords } from './words.js';
+
+const args: string[] = process.argv.slice(2);
+let count: number = 4;
+let separator: string = '-';
+let format: string = 'joined';
+
+for (let i = 0; i < args.length; i++) {
+  const arg = args[i];
+  if (arg === '-n' || arg === '--count') {
+    const nextArg = args[++i];
+    if (!nextArg || isNaN(parseInt(nextArg))) {
+      console.error('Error: --count requires a valid number');
+      process.exit(1);
+    }
+    count = parseInt(nextArg);
+    if (count < 1 || count > 1000) {
+      console.error('Error: count must be between 1 and 1000');
+      process.exit(1);
+    }
+  } else if (arg === '-s' || arg === '--separator') {
+    separator = args[++i];
+    if (separator === undefined) {
+      console.error('Error: --separator requires a value');
+      process.exit(1);
+    }
+  } else if (arg === '-f' || arg === '--format') {
+    format = args[++i] || 'joined';
+    if (!['joined', 'array', 'newline'].includes(format)) {
+      console.error('Error: format must be one of: joined, array, newline');
+      process.exit(1);
+    }
+  } else if (arg === '-h' || arg === '--help') {
+    console.log(`Usage: random-words [options]
+
+Options:
+  -n, --count <number>    Number of words to generate (default: 4)
+  -s, --separator <char>  Separator between words (default: -)
+  -f, --format <type>     Output format: joined, array, or newline (default: joined)
+  -h, --help              Show this help message
+
+Examples:
+  random-words
+  random-words -n 6
+  random-words -n 3 -s _
+  random-words -n 2 -f array`);
+    process.exit(0);
+  } else if (!arg.startsWith('-')) {
+    const val = parseInt(arg);
+    if (!isNaN(val)) {
+      if (val < 1 || val > 1000) {
+        console.error('Error: count must be between 1 and 1000');
+        process.exit(1);
+      }
+      count = val;
+    }
+  }
+}
+
+const words: string[] = randomWords(count);
+
+if (format === 'array') {
+  console.log(JSON.stringify(words));
+} else if (format === 'newline') {
+  console.log(words.join('\n'));
+} else {
+  console.log(words.join(separator));
+}

package/src/words.ts

@@ -0,0 +1,35 @@
+import { randomInt } from 'node:crypto';
+// @ts-ignore - The package doesn't have types but we know it's an array of strings
+import words from 'an-array-of-english-words';
+
+/**
+ * Returns a list of random words.
+ * This is now more efficient for large lists by picking individual random indices
+ * instead of shuffling the entire array.
+ * 
+ * @param count Number of words to return
+ * @returns Array of random words
+ */
+export function randomWords(count: number = 4): string[] {
+  const n = words.length;
+  const actualCount = Math.max(0, Math.min(count, n));
+  
+  if (actualCount === 0) return [];
+
+  const result: string[] = [];
+  const seenIndices = new Set<number>();
+
+  // For small counts, we use a Set to pick unique indices.
+  // This is O(count) instead of O(N) where N is the total number of words (275,000+).
+  while (result.length < actualCount) {
+    const j = randomInt(0, n);
+    if (!seenIndices.has(j)) {
+      seenIndices.add(j);
+      result.push(words[j]);
+    }
+  }
+
+  return result;
+}
+
+export { words };

package/tsconfig.json

@@ -0,0 +1,17 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "esModuleInterop": true,
+    "strict": true,
+    "skipLibCheck": true,
+    "outDir": "dist",
+    "rootDir": "src",
+    "declaration": true,
+    "sourceMap": true,
+    "resolveJsonModule": true,
+    "forceConsistentCasingInFileNames": true
+  },
+  "include": ["src"]
+}