feat(string): add special() method (#1634)

3 files changed, 141 insertions, 0 deletions

diff --git a/src/modules/string/index.ts b/src/modules/string/index.ts
index 827c1f45..32f76b72 100644
--- a/src/modules/string/index.ts
+++ b/src/modules/string/index.ts
@@ -442,4 +442,65 @@ export class StringModule {
     };
     return RFC4122_TEMPLATE.replace(/[xy]/g, replacePlaceholders);
   }
+
+  /**
+   * Returns a string containing only special characters.
+   *
+   * @param length Length of the generated string. Defaults to `1`.
+   * @param length.min The minimum number of special characters to generate.
+   * @param length.max The maximum number of special characters to generate.
+   *
+   * @example
+   * faker.string.special() // '$'
+   * faker.string.special(5) // '#*!.~'
+   * faker.string.special({ min: 5, max: 10 }) // ')|@*>^+'
+   *
+   * @since 8.0.0
+   */
+  special(length: number | { min: number; max: number } = 1): string {
+    length = this.faker.helpers.rangeToNumber(length);
+    if (length <= 0) {
+      return '';
+    }
+
+    let specialString = '';
+    for (let i = 0; i < length; i++) {
+      specialString += this.faker.helpers.arrayElement([
+        '!',
+        '"',
+        '#',
+        '$',
+        '%',
+        '&',
+        "'",
+        '(',
+        ')',
+        '*',
+        '+',
+        ',',
+        '-',
+        '.',
+        '/',
+        ':',
+        ';',
+        '<',
+        '=',
+        '>',
+        '?',
+        '@',
+        '[',
+        '\\',
+        ']',
+        '^',
+        '_',
+        '`',
+        '{',
+        '|',
+        '}',
+        '~',
+      ]);
+    }
+
+    return specialString;
+  }
 }
diff --git a/test/__snapshots__/string.spec.ts.snap b/test/__snapshots__/string.spec.ts.snap
index 9de8545d..bd7522f9 100644
--- a/test/__snapshots__/string.spec.ts.snap
+++ b/test/__snapshots__/string.spec.ts.snap
@@ -104,6 +104,20 @@ exports[`string > 42 > sample > with length parameter 5`] = `"\\"&{dn"`;
 
 exports[`string > 42 > sample > with length range 1`] = `"ky2eiXX/J/*&Kq"`;
 
+exports[`string > 42 > special > noArgs 1`] = `","`;
+
+exports[`string > 42 > special > with length parameter 1`] = `",^}&\\\\"`;
+
+exports[`string > 42 > special > with length parameter 2`] = `"]>>%/"`;
+
+exports[`string > 42 > special > with length parameter 3`] = `"%$\\"/\`"`;
+
+exports[`string > 42 > special > with length parameter 4`] = `"+>%[?"`;
+
+exports[`string > 42 > special > with length parameter 5`] = `"!\\"~\\\\_"`;
+
+exports[`string > 42 > special > with length range 1`] = `"^}&\\\\]>>%/%$\\"/\`"`;
+
 exports[`string > 42 > uuid 1`] = `"5cf2bc99-2721-407d-992b-a00fbdf302f2"`;
 
 exports[`string > 42 > uuid 2`] = `"94980604-8962-404f-9371-c9368f970d9a"`;
@@ -218,6 +232,20 @@ exports[`string > 1211 > sample > with length parameter 5`] = `"h^]dn"`;
 
 exports[`string > 1211 > sample > with length range 1`] = `"Kti5-}$_/\`4hHA0afl\\"h"`;
 
+exports[`string > 1211 > special > noArgs 1`] = `"|"`;
+
+exports[`string > 1211 > special > with length parameter 1`] = `"|/{]("`;
+
+exports[`string > 1211 > special > with length parameter 2`] = `"%~\\"@&"`;
+
+exports[`string > 1211 > special > with length parameter 3`] = `"@'].,"`;
+
+exports[`string > 1211 > special > with length parameter 4`] = `"&[\\\\_!"`;
+
+exports[`string > 1211 > special > with length parameter 5`] = `"]@?\\\\_"`;
+
+exports[`string > 1211 > special > with length range 1`] = `"/{](%~\\"@&@'].,&[\\\\_!]"`;
+
 exports[`string > 1211 > uuid 1`] = `"e7ec32f0-a2a3-4c65-abbd-0caabde64dfd"`;
 
 exports[`string > 1211 > uuid 2`] = `"f379e325-9f7c-4064-a086-f23942b68e5f"`;
@@ -332,6 +360,20 @@ exports[`string > 1337 > sample > with length parameter 5`] = `"D)[B,"`;
 
 exports[`string > 1337 > sample > with length range 1`] = `"U/4:SK$>6QX9"`;
 
+exports[`string > 1337 > special > noArgs 1`] = `")"`;
+
+exports[`string > 1337 > special > with length parameter 1`] = `")<&')"`;
+
+exports[`string > 1337 > special > with length parameter 2`] = `"</\\"+("`;
+
+exports[`string > 1337 > special > with length parameter 3`] = `";=)+~"`;
+
+exports[`string > 1337 > special > with length parameter 4`] = `")\\\\*$^"`;
+
+exports[`string > 1337 > special > with length parameter 5`] = `"-$?,%"`;
+
+exports[`string > 1337 > special > with length range 1`] = `"<&')</\\"+(;=)"`;
+
 exports[`string > 1337 > uuid 1`] = `"48234870-5389-445f-8b41-c61a52bf27dc"`;
 
 exports[`string > 1337 > uuid 2`] = `"cc057669-8c53-474d-a677-226d3e8ed92f"`;
diff --git a/test/string.spec.ts b/test/string.spec.ts
index fe8235b0..8963e3cf 100644
--- a/test/string.spec.ts
+++ b/test/string.spec.ts
@@ -75,6 +75,12 @@ describe('string', () => {
     });
 
     t.itRepeated('uuid', 5);
+
+    t.describe('special', (t) => {
+      t.it('noArgs')
+        .itRepeated('with length parameter', 5, 5)
+        .it('with length range', { min: 10, max: 20 });
+    });
   });
 
   describe(`random seeded tests for seed ${faker.seed()}`, () => {
@@ -550,6 +556,38 @@ describe('string', () => {
           expect(UUID).toMatch(RFC4122);
         });
       });
+
+      describe('special', () => {
+        it('should return a value of type string with default length of 1', () => {
+          const actual = faker.string.special();
+
+          expect(actual).toBeTypeOf('string');
+          expect(actual).toHaveLength(1);
+        });
+
+        it('should return an empty string when length is negative', () => {
+          const actual = faker.string.special(
+            faker.number.int({ min: -1000, max: -1 })
+          );
+
+          expect(actual).toBe('');
+          expect(actual).toHaveLength(0);
+        });
+
+        it('should return string of designated length', () => {
+          const length = 87;
+          const actual = faker.string.special(length);
+
+          expect(actual).toHaveLength(length);
+        });
+
+        it('should return string with a length within a given range', () => {
+          const actual = faker.string.special({ min: 10, max: 20 });
+
+          expect(actual.length).toBeGreaterThanOrEqual(10);
+          expect(actual.length).toBeLessThanOrEqual(20);
+        });
+      });
     }
   });
 });