feat(string): generate string from characters (#1717)

4 files changed, 141 insertions, 10 deletions

diff --git a/test/__snapshots__/string.spec.ts.snap b/test/__snapshots__/string.spec.ts.snap
index 6a3ccead..61245b7b 100644
--- a/test/__snapshots__/string.spec.ts.snap
+++ b/test/__snapshots__/string.spec.ts.snap
@@ -62,6 +62,18 @@ exports[`string > 42 > binary > with length and empty prefix 1`] = `"0110111"`;
 
 exports[`string > 42 > binary > with length range 1`] = `"0b11011110000001"`;
 
+exports[`string > 42 > fromCharacters > with string characters 1`] = `"o"`;
+
+exports[`string > 42 > fromCharacters > with string characters and length 1`] = `"oaroa"`;
+
+exports[`string > 42 > fromCharacters > with string characters and length range 1`] = `"aroaabbfofffor"`;
+
+exports[`string > 42 > fromCharacters > with string[] characters 1`] = `"o"`;
+
+exports[`string > 42 > fromCharacters > with string[] characters and length 1`] = `"oaroa"`;
+
+exports[`string > 42 > fromCharacters > with string[] characters and length range 1`] = `"aroaabbfofffor"`;
+
 exports[`string > 42 > hexadecimal > noArgs 1`] = `"0x8"`;
 
 exports[`string > 42 > hexadecimal > with casing = lower 1`] = `"0x8"`;
@@ -224,6 +236,18 @@ exports[`string > 1211 > binary > with length and empty prefix 1`] = `"1011001"`
 
 exports[`string > 1211 > binary > with length range 1`] = `"0b01100101010100011101"`;
 
+exports[`string > 1211 > fromCharacters > with string characters 1`] = `"r"`;
+
+exports[`string > 1211 > fromCharacters > with string characters and length 1`] = `"rorao"`;
+
+exports[`string > 1211 > fromCharacters > with string characters and length range 1`] = `"oraofrfafaoaoofaaafa"`;
+
+exports[`string > 1211 > fromCharacters > with string[] characters 1`] = `"r"`;
+
+exports[`string > 1211 > fromCharacters > with string[] characters and length 1`] = `"rorao"`;
+
+exports[`string > 1211 > fromCharacters > with string[] characters and length range 1`] = `"oraofrfafaoaoofaaafa"`;
+
 exports[`string > 1211 > hexadecimal > noArgs 1`] = `"0xE"`;
 
 exports[`string > 1211 > hexadecimal > with casing = lower 1`] = `"0xe"`;
@@ -386,6 +410,18 @@ exports[`string > 1337 > binary > with length and empty prefix 1`] = `"0100010"`
 
 exports[`string > 1337 > binary > with length range 1`] = `"0b100010000110"`;
 
+exports[`string > 1337 > fromCharacters > with string characters 1`] = `"o"`;
+
+exports[`string > 1337 > fromCharacters > with string characters and length 1`] = `"obfoo"`;
+
+exports[`string > 1337 > fromCharacters > with string characters and length range 1`] = `"bfoobofoobbo"`;
+
+exports[`string > 1337 > fromCharacters > with string[] characters 1`] = `"o"`;
+
+exports[`string > 1337 > fromCharacters > with string[] characters and length 1`] = `"obfoo"`;
+
+exports[`string > 1337 > fromCharacters > with string[] characters and length range 1`] = `"bfoobofoobbo"`;
+
 exports[`string > 1337 > hexadecimal > noArgs 1`] = `"0x5"`;
 
 exports[`string > 1337 > hexadecimal > with casing = lower 1`] = `"0x5"`;
diff --git a/test/all_functional.spec.ts b/test/all_functional.spec.ts
index cc784660..ae4ac991 100644
--- a/test/all_functional.spec.ts
+++ b/test/all_functional.spec.ts
@@ -29,6 +29,9 @@ const BROKEN_LOCALE_METHODS = {
     state: ['az', 'cz', 'nb_NO', 'sk'],
     stateAbbr: ['cz', 'sk'],
   },
+  string: {
+    fromCharacters: '*',
+  },
   person: {
     prefix: ['az', 'id_ID', 'ru', 'zh_CN', 'zh_TW'],
     suffix: ['az', 'it', 'mk', 'pt_PT', 'ru'],
diff --git a/test/random.spec.ts b/test/random.spec.ts
index 510009db..e03e7428 100644
--- a/test/random.spec.ts
+++ b/test/random.spec.ts
@@ -213,7 +213,7 @@ describe('random', () => {
             })
           ).toThrowError(
             new FakerError(
-              'Unable to generate string, because all possible characters are excluded.'
+              'Unable to generate string: No characters to select from.'
             )
           );
         });
@@ -332,7 +332,7 @@ describe('random', () => {
             })
           ).toThrowError(
             new FakerError(
-              'Unable to generate string, because all possible characters are excluded.'
+              'Unable to generate string: No characters to select from.'
             )
           );
         });
diff --git a/test/string.spec.ts b/test/string.spec.ts
index 1ad429ca..5c256a32 100644
--- a/test/string.spec.ts
+++ b/test/string.spec.ts
@@ -7,6 +7,21 @@ const NON_SEEDED_BASED_RUN = 5;
 
 describe('string', () => {
   seededTests(faker, 'string', (t) => {
+    t.describe('fromCharacters', (t) => {
+      t.it('with string characters', 'foobar')
+        .it('with string[] characters', 'foobar'.split(''))
+        .it('with string characters and length', 'foobar', 5)
+        .it('with string[] characters and length', 'foobar'.split(''), 5)
+        .it('with string characters and length range', 'foobar', {
+          min: 10,
+          max: 20,
+        })
+        .it('with string[] characters and length range', 'foobar'.split(''), {
+          min: 10,
+          max: 20,
+        });
+    });
+
     t.describe('alpha', (t) => {
       t.it('noArgs')
         .itRepeated('with length parameter', 5, 5)
@@ -113,6 +128,64 @@ describe('string', () => {
 
   describe(`random seeded tests for seed ${faker.seed()}`, () => {
     for (let i = 1; i <= NON_SEEDED_BASED_RUN; i++) {
+      describe('fromCharacters', () => {
+        it('should return single character when no length provided', () => {
+          const actual = faker.string.fromCharacters('foobar');
+
+          expect(actual).toHaveLength(1);
+        });
+
+        it('should only contain characters from provided string', () => {
+          const actual = faker.string.fromCharacters('foobar');
+
+          expect(actual).toMatch(/^[foobar]$/);
+        });
+
+        it('should generate 5 random letters', () => {
+          const actual = faker.string.fromCharacters('foobar', 5);
+
+          expect(actual).toHaveLength(5);
+        });
+
+        it.each([0, -1, -100])(
+          'should return empty string when length is <= 0',
+          (length) => {
+            const actual = faker.string.fromCharacters('foobar', length);
+
+            expect(actual).toBe('');
+          }
+        );
+
+        it('should return a random amount of characters', () => {
+          const actual = faker.string.fromCharacters('foobar', {
+            min: 10,
+            max: 20,
+          });
+
+          expect(actual).toBeTruthy();
+          expect(actual).toBeTypeOf('string');
+
+          expect(actual.length).toBeGreaterThanOrEqual(10);
+          expect(actual.length).toBeLessThanOrEqual(20);
+        });
+
+        it('should throw if no characters are passed (string)', () => {
+          expect(() => faker.string.fromCharacters('')).toThrowError(
+            new FakerError(
+              'Unable to generate string: No characters to select from.'
+            )
+          );
+        });
+
+        it('should throw if no characters are passed (string[])', () => {
+          expect(() => faker.string.fromCharacters([])).toThrowError(
+            new FakerError(
+              'Unable to generate string: No characters to select from.'
+            )
+          );
+        });
+      });
+
       describe('alpha', () => {
         it('should return single letter when no length provided', () => {
           const actual = faker.string.alpha();
@@ -193,7 +266,22 @@ describe('string', () => {
           expect(alphaText).toMatch(/^[b-oq-z]{5}$/);
         });
 
-        it('should throw if all possible characters being excluded', () => {
+        it('should throw if all possible characters being excluded (string)', () => {
+          const exclude = 'abcdefghijklmnopqrstuvwxyz';
+          expect(() =>
+            faker.string.alpha({
+              length: 5,
+              casing: 'lower',
+              exclude,
+            })
+          ).toThrowError(
+            new FakerError(
+              'Unable to generate string: No characters to select from.'
+            )
+          );
+        });
+
+        it('should throw if all possible characters being excluded (string[])', () => {
           const exclude = 'abcdefghijklmnopqrstuvwxyz'.split('');
           expect(() =>
             faker.string.alpha({
@@ -203,7 +291,7 @@ describe('string', () => {
             })
           ).toThrowError(
             new FakerError(
-              'Unable to generate string, because all possible characters are excluded.'
+              'Unable to generate string: No characters to select from.'
             )
           );
         });
@@ -332,8 +420,8 @@ describe('string', () => {
           expect(alphaText).toMatch(/^[0-9b-oq-z]{5}$/);
         });
 
-        it('should throw if all possible characters being excluded', () => {
-          const exclude = 'abcdefghijklmnopqrstuvwxyz0123456789'.split('');
+        it('should throw if all possible characters being excluded (string)', () => {
+          const exclude = 'abcdefghijklmnopqrstuvwxyz0123456789';
           expect(() =>
             faker.string.alphanumeric({
               length: 5,
@@ -342,20 +430,24 @@ describe('string', () => {
             })
           ).toThrowError(
             new FakerError(
-              'Unable to generate string, because all possible characters are excluded.'
+              'Unable to generate string: No characters to select from.'
             )
           );
         });
 
-        it('should throw if all possible characters being excluded via string', () => {
-          const exclude = 'abcdefghijklmnopqrstuvwxyz0123456789';
+        it('should throw if all possible characters being excluded (string[])', () => {
+          const exclude = 'abcdefghijklmnopqrstuvwxyz0123456789'.split('');
           expect(() =>
             faker.string.alphanumeric({
               length: 5,
               casing: 'lower',
               exclude,
             })
-          ).toThrowError();
+          ).toThrowError(
+            new FakerError(
+              'Unable to generate string: No characters to select from.'
+            )
+          );
         });
 
         it('should not mutate the input object', () => {