feat(lorem): add character length parameter to lorem.text

CONTRIBUTING.md

@@ -9,7 +9,7 @@ This is a shorthand for running the following scripts in order:
 
 - `pnpm install` - installs npm packages defined in package.json
 - `pnpm run generate:locales` - generates locale files
-- `pnpm run generate:api-doc` - generates API documentation
+- `pnpm run generate:api-docs` - generates API documentation
 - `pnpm run format` - runs [prettify](https://github.com/prettier/prettier) to format code
 - `pnpm run lint` - runs [ESLint](https://github.com/eslint/eslint) to enforce project code standards
 - `pnpm run build:clean` - removes artifacts from previous builds

src/modules/lorem/index.ts

@@ -1,4 +1,5 @@
 import type { Faker } from '../..';
+import { FakerError } from '../../errors/faker-error';
 import { filterWordListByLength } from '../word/filterWordListByLength';
 
 /**
@@ -318,6 +319,11 @@ export class LoremModule {
   /**
    * Generates a random text based on a random lorem method.
    *
+   * @param options The options for the text to generate or options.length as quick primitive argument.
+   * @param options.length The length (range) of text to generate.
+   * @param options.length.min The minimum length of text to generate.
+   * @param options.length.max The maximum length of text to generate.
+   *
    * @example
    * faker.lorem.text() // 'Doloribus autem non quis vero quia.'
    * faker.lorem.text()
@@ -326,10 +332,35 @@ export class LoremModule {
    * // Quis ut dolor dolores facilis possimus tempore voluptates.
    * // Iure nam officia optio cumque.
    * // Dolor tempora iusto.'
+   * faker.lorem.text(14) // 'Doloribus aut.' (14 characters)
+   * faker.lorem.text({length: 14}) // 'Doloribus aut.' (14 characters)
+   * faker.lorem.text({length: {min: 10, max: 15}}) // 'autem non quis.' (15 characters)
+   * faker.lorem.text({length: {min: 10, max: 12}}) // 'autem non.' (10 characters)
+   * faker.lorem.text({length: {min: 3, max: 10}}) // 'autem.' (6 characters)
    *
    * @since 3.1.0
    */
-  text(): string {
+  text(
+    options?:
+      | number
+      | {
+          /**
+           * The length (range) of text to generate.
+           */
+          length?:
+            | number
+            | {
+                /**
+                 * The minimum length of text to generate.
+                 */
+                min?: number;
+                /**
+                 * The maximum length of text to generate.
+                 */
+                max?: number;
+              };
+        }
+  ): string {
     const methods: Array<keyof LoremModule> = [
       'sentence',
       'sentences',
@@ -340,7 +371,57 @@ export class LoremModule {
 
     const method = this.faker.helpers.arrayElement(methods);
 
-    return `${this[method]()}`;
+    if (typeof options === 'undefined') {
+      return `${this[method]()}`;
+    }
+
+    if (typeof options === 'number') {
+      return this.faker.lorem.text({ length: options });
+    }
+
+    if (typeof options?.length === 'number') {
+      if (options.length >= 0) {
+        let text = `${this[method]()}`;
+        while (text.length <= options?.length) {
+          text = `${text} ${this[method]()}`;
+        }
+
+        return options.length
+          ? `${text.substring(0, options.length - 1)}.`
+          : '';
+      }
+
+      throw new FakerError(
+        `Length ${options.length} should be a non-negative integer.`
+      );
+    }
+
+    if (options.length?.max != null && options.length?.max < 0) {
+      throw new FakerError(
+        `Max ${options.length.max} should be a non-negative integer.`
+      );
+    }
+
+    if (options.length?.min != null && options.length?.min < 0) {
+      throw new FakerError(
+        `Min ${options.length.min} should be a non-negative integer.`
+      );
+    }
+
+    if (options.length?.min > options.length?.max) {
+      throw new FakerError(
+        `Max ${options.length.max} should be greater than min ${options.length.min}.`
+      );
+    }
+
+    const min = options.length?.min ?? 0;
+    const max = options.length?.max ?? 2 * min;
+    const randomLength = this.faker.number.int({
+      min: min,
+      max: max,
+    });
+
+    return this.faker.lorem.text({ length: randomLength });
   }
 
   /**

test/__snapshots__/lorem.spec.ts.snap

@@ -97,9 +97,9 @@ exports[`lorem > 42 > slug > with length range 1`] = `"minus-a-qui-tempore-quo-p
 
 exports[`lorem > 42 > text > noArgs 1`] = `"Qui tempore quo perspiciatis perspiciatis quia in quia architecto ipsa. Pariatur veniam unde fugit facilis mollitia. Ipsa reiciendis nam. Earum dolorem alias qui asperiores qui natus aliquam iste. Consequatur eum sit dolore rem iste aliquid."`;
 
-exports[`lorem > 42 > text > with length 1`] = `"Qui tempore quo perspiciatis perspiciatis quia in quia architecto ipsa. Pariatur veniam unde fugit facilis mollitia. Ipsa reiciendis nam. Earum dolorem alias qui asperiores qui natus aliquam iste. Consequatur eum sit dolore rem iste aliquid."`;
+exports[`lorem > 42 > text > with length 1`] = `"Qui tempo."`;
 
-exports[`lorem > 42 > text > with length range 1`] = `"Qui tempore quo perspiciatis perspiciatis quia in quia architecto ipsa. Pariatur veniam unde fugit facilis mollitia. Ipsa reiciendis nam. Earum dolorem alias qui asperiores qui natus aliquam iste. Consequatur eum sit dolore rem iste aliquid."`;
+exports[`lorem > 42 > text > with length range 1`] = `""`;
 
 exports[`lorem > 42 > word > noArgs 1`] = `"voluptas"`;
 
@@ -233,17 +233,9 @@ Ullam consequuntur quidem nobis placeat aut.
 Est animi libero repellendus recusandae iure magnam pariatur doloribus."
 `;
 
-exports[`lorem > 1211 > text > with length 1`] = `
-"Quo amet explicabo repellat accusantium laborum quia fuga dolorem cumque.
-Ullam consequuntur quidem nobis placeat aut.
-Est animi libero repellendus recusandae iure magnam pariatur doloribus."
-`;
+exports[`lorem > 1211 > text > with length 1`] = `"Quo amet ."`;
 
-exports[`lorem > 1211 > text > with length range 1`] = `
-"Quo amet explicabo repellat accusantium laborum quia fuga dolorem cumque.
-Ullam consequuntur quidem nobis placeat aut.
-Est animi libero repellendus recusandae iure magnam pariatur doloribus."
-`;
+exports[`lorem > 1211 > text > with length range 1`] = `""`;
 
 exports[`lorem > 1211 > word > noArgs 1`] = `"recusandae"`;
 
@@ -354,9 +346,9 @@ exports[`lorem > 1337 > slug > with length range 1`] = `"molestias-quia-dolorem-
 
 exports[`lorem > 1337 > text > noArgs 1`] = `"Dolorem incidunt atque esse. Ad consectetur totam. Eius veniam voluptatibus tempora tempore aliquam vitae. Laboriosam quasi similique nemo sunt cum doloribus consequuntur reprehenderit."`;
 
-exports[`lorem > 1337 > text > with length 1`] = `"Dolorem incidunt atque esse. Ad consectetur totam. Eius veniam voluptatibus tempora tempore aliquam vitae. Laboriosam quasi similique nemo sunt cum doloribus consequuntur reprehenderit."`;
+exports[`lorem > 1337 > text > with length 1`] = `"Dolorem i."`;
 
-exports[`lorem > 1337 > text > with length range 1`] = `"Dolorem incidunt atque esse. Ad consectetur totam. Eius veniam voluptatibus tempora tempore aliquam vitae. Laboriosam quasi similique nemo sunt cum doloribus consequuntur reprehenderit."`;
+exports[`lorem > 1337 > text > with length range 1`] = `""`;
 
 exports[`lorem > 1337 > word > noArgs 1`] = `"eius"`;
 

test/lorem.spec.ts

@@ -325,6 +325,117 @@ describe('lorem', () => {
           expect(actual).toBeTruthy();
           expect(actual).toBeTypeOf('string');
         });
+
+        it('should return text of length 15 for the options object', () => {
+          const actual = faker.lorem.text({ length: 15 });
+
+          expect(actual).toBeTruthy();
+          expect(actual).toBeTypeOf('string');
+          expect(actual).toHaveLength(15);
+          expect(actual.trim()).toHaveLength(15);
+        });
+
+        it('should return text of length 15 for the quick primitive argument', () => {
+          const actual = faker.lorem.text(15);
+
+          expect(actual).toBeTruthy();
+          expect(actual).toBeTypeOf('string');
+          expect(actual).toHaveLength(15);
+          expect(actual.trim()).toHaveLength(15);
+        });
+
+        it('should return text with a length in range [25, 40]', () => {
+          const actual = faker.lorem.text({ length: { min: 25, max: 40 } });
+
+          expect(actual).toBeTruthy();
+          expect(actual).toBeTypeOf('string');
+          expect(actual.length).toBeGreaterThanOrEqual(25);
+          expect(actual.length).toBeLessThanOrEqual(40);
+        });
+
+        it('should throw an error for a negative length in the options object', () => {
+          expect(() => faker.lorem.text({ length: -3 })).toThrowError(
+            /^Length -3 should be a non-negative integer.$/
+          );
+        });
+
+        it('should throw an error for a negative length in the quick primitive argument', () => {
+          expect(() => faker.lorem.text(-3)).toThrowError(
+            /^Length -3 should be a non-negative integer.$/
+          );
+        });
+
+        it('should throw an error if min is negative', () => {
+          expect(() => faker.lorem.text({ length: { min: -11 } })).toThrowError(
+            /^Min -11 should be a non-negative integer.$/
+          );
+        });
+
+        it('should throw an error if min is greater than max', () => {
+          expect(() =>
+            faker.lorem.text({ length: { min: 3, max: 1 } })
+          ).toThrowError(/^Max 1 should be greater than min 3.$/);
+        });
+
+        it('should throw an error if max is negative', () => {
+          expect(() => faker.lorem.text({ length: { max: -11 } })).toThrowError(
+            /^Max -11 should be a non-negative integer.$/
+          );
+        });
+
+        it('should return an empty string for length zero', () => {
+          const actual = faker.lorem.text({ length: 0 });
+
+          expect(actual).toBeTypeOf('string');
+          expect(actual).toBe('');
+        });
+
+        it('should return a dot for length one', () => {
+          const actual = faker.lorem.text({ length: 1 });
+
+          expect(actual).toBeTypeOf('string');
+          expect(actual).toBe('.');
+        });
+
+        it('should return a string of length 0 or length 1 for [0, 1]', () => {
+          const actual = faker.lorem.text({ length: { min: 0, max: 1 } });
+
+          expect(actual).toBeTypeOf('string');
+          expect(actual.length).toBeGreaterThanOrEqual(0);
+          expect(actual.length).toBeLessThanOrEqual(1);
+        });
+
+        it('should return text with length between 0 and 32 for [0, 32]', () => {
+          const actual = faker.lorem.text({ length: { min: 0, max: 32 } });
+
+          expect(actual).toBeTypeOf('string');
+          expect(actual.length).toBeGreaterThanOrEqual(0);
+          expect(actual.length).toBeLessThanOrEqual(32);
+        });
+
+        it('should return a string of length 77 for [77, 77]', () => {
+          const actual = faker.lorem.text({ length: { min: 77, max: 77 } });
+
+          expect(actual).toBeTruthy();
+          expect(actual).toBeTypeOf('string');
+          expect(actual).toHaveLength(77);
+        });
+
+        it('should return a string with length in [33, 66] for min = 33', () => {
+          const actual = faker.lorem.text({ length: { min: 33 } });
+
+          expect(actual).toBeTypeOf('string');
+          expect(actual.length).toBeGreaterThanOrEqual(33);
+          expect(actual.length).toBeLessThanOrEqual(66);
+        });
+
+        it('should return a string with length between 0 and 51 for max = 51', () => {
+          const actual = faker.lorem.text({ length: { max: 51 } });
+
+          expect(actual).toBeTypeOf('string');
+          expect(actual.length).toBeGreaterThanOrEqual(0);
+          expect(actual.length).toBeLessThanOrEqual(51);
+        });
       });
 
       describe('lines()', () => {