feat: add minCharacters option to randomParagraph (#39)

* feat: add minCharacters option to randomParagraph

Adds an optional minCharacters parameter that ensures the generated
paragraph meets a minimum character length by adding words beyond
maxWords. The result is still capped by maxCharacters (truncation wins).

* chore: version bump for minCharacters option

Author: ssuverev

CHANGELOG.md

@@ -1,5 +1,11 @@
 # deverything
 
+## 5.1.0
+
+### Minor Changes
+
+- Add `minCharacters` option to `randomParagraph` — ensures the generated paragraph meets a minimum character length by adding words beyond `maxWords`, while still respecting `maxCharacters` as an upper bound.
+
 ## 5.0.0
 
 ### Major Changes

package.json

@@ -1,6 +1,6 @@
 {
   "name": "deverything",
-  "version": "5.0.0",
+  "version": "5.1.0",
   "description": "Everything you need for Dev",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",

src/random/randomParagraph.test.ts

@@ -38,4 +38,41 @@ describe(`randomParagraph`, () => {
     const result = randomParagraph();
     expect(result.endsWith(".")).toBeTruthy();
   });
+
+  it(`respects minCharacters`, () => {
+    for (let i = 0; i < 20; i++) {
+      const result = randomParagraph({ minCharacters: 100, maxCharacters: 500 });
+      expect(result.length).toBeGreaterThanOrEqual(100);
+    }
+  });
+
+  it(`respects minCharacters and maxCharacters together`, () => {
+    for (let i = 0; i < 20; i++) {
+      const result = randomParagraph({
+        minCharacters: 150,
+        maxCharacters: 200,
+      });
+      expect(result.length).toBeGreaterThanOrEqual(150);
+      expect(result.length).toBeLessThanOrEqual(200);
+    }
+  });
+
+  it(`caps at maxCharacters when minCharacters exceeds it`, () => {
+    for (let i = 0; i < 20; i++) {
+      const result = randomParagraph({
+        minCharacters: 300,
+        maxCharacters: 200,
+      });
+      expect(result.length).toBeLessThanOrEqual(200);
+    }
+  });
+
+  it(`default behavior is unchanged without minCharacters`, () => {
+    for (let i = 0; i < 20; i++) {
+      const result = randomParagraph();
+      expect(result.length).toBeLessThanOrEqual(200);
+      expect(result.endsWith(".")).toBeTruthy();
+      expect(result.length).toBeGreaterThan(0);
+    }
+  });
 });

src/random/randomParagraph.ts

@@ -7,21 +7,33 @@ import { randomWord } from "./randomWord";
 /**
  * Generates a random paragraph of text.
  * @param maxCharacters The maximum number of characters. The paragraph will be truncated to this length if it exceeds it. Default is 200.
- * @param words The number of words. Default is 8.
+ * @param minCharacters The minimum number of characters. Words will be added beyond maxWords until this threshold is met. Default is undefined (no minimum).
+ * @param minWords The minimum number of words. Default is 8.
+ * @param maxWords The maximum number of words. Default is 16.
  * @returns A random paragraph of text.
  */
 export const randomParagraph = ({
   maxCharacters = 200,
+  minCharacters,
   minWords = 8,
   maxWords = 16,
 }: {
   maxCharacters?: number;
+  minCharacters?: number;
   minWords?: number;
   maxWords?: number;
 } = {}) => {
-  return capitalize(
-    array(randomInt({ min: minWords, max: maxWords }), () => randomWord())
-      .join(" ")
-      .slice(0, maxCharacters - 1) + "."
-  );
+  const words: string[] = [];
+  const targetWordCount = randomInt({ min: minWords, max: maxWords });
+
+  for (
+    let i = 0;
+    i < targetWordCount ||
+    (minCharacters !== undefined && words.join(" ").length < minCharacters);
+    i++
+  ) {
+    words.push(randomWord());
+  }
+
+  return capitalize(words.join(" ").slice(0, maxCharacters - 1) + ".");
 };