refactor(finance): rename mask to maskedNumber (#2055)

4 files changed, 135 insertions, 75 deletions

diff --git a/docs/guide/upgrading.md b/docs/guide/upgrading.md
index d0322a0b..41979dec 100644
--- a/docs/guide/upgrading.md
+++ b/docs/guide/upgrading.md
@@ -195,6 +195,10 @@ The `faker.address.*` methods will continue to work as an alias in v8 and v9, bu
 
 The `faker.finance.account` method has been renamed to `faker.finance.accountNumber` to better reflect the data it returns and not to get confused with a user "Account".
 
+### `faker.finance.mask` changed to `faker.finance.maskedNumber`
+
+The `faker.finance.mask` method has been renamed to `faker.finance.maskedNumber` to better reflect its purpose.
+
 ### Number methods of `faker.datatype` moved to new `faker.number` module
 
 The number-related methods previously found in `faker.datatype` have been moved to a new `faker.number` module.
diff --git a/src/modules/finance/index.ts b/src/modules/finance/index.ts
index fba04ce8..32b04795 100644
--- a/src/modules/finance/index.ts
+++ b/src/modules/finance/index.ts
@@ -217,6 +217,8 @@ export class FinanceModule {
    * @param parens Whether to use surrounding parenthesis. Defaults to `true`.
    * @param ellipsis Whether to prefix the numbers with an ellipsis. Defaults to `true`.
    *
+   * @see faker.finance.maskedNumber()
+   *
    * @example
    * faker.finance.mask() // '(...9711)'
    * faker.finance.mask(3) // '(...342)'
@@ -224,8 +226,31 @@ export class FinanceModule {
    * faker.finance.mask(3, false, false) // '298'
    *
    * @since 2.0.1
+   *
+   * @deprecated Use `faker.finance.maskedNumber` instead.
    */
-  mask(length?: number, parens?: boolean, ellipsis?: boolean): string;
+  mask(length?: number, parens?: boolean, ellipsis?: boolean): string {
+    deprecated({
+      deprecated: 'faker.finance.mask',
+      proposed: 'faker.finance.maskedNumber',
+      since: '8.0',
+      until: '9.0',
+    });
+    return this.maskedNumber({ length, parens, ellipsis });
+  }
+
+  /**
+   * Generates a random masked number.
+   *
+   * @param length The length of the unmasked number. Defaults to `4`.
+   *
+   * @example
+   * faker.finance.maskedNumber() // '(...9711)'
+   * faker.finance.maskedNumber(3) // '(...342)'
+   *
+   * @since 8.0.0
+   */
+  maskedNumber(length?: number): string;
   /**
    * Generates a random masked number.
    *
@@ -235,14 +260,14 @@ export class FinanceModule {
    * @param options.ellipsis Whether to prefix the numbers with an ellipsis. Defaults to `true`.
    *
    * @example
-   * faker.finance.mask() // '(...9711)'
-   * faker.finance.mask({ length: 3 }) // '(...342)'
-   * faker.finance.mask({ length: 3, parens: false }) // '...236'
-   * faker.finance.mask({ length: 3, parens: false, ellipsis: false }) // '298'
+   * faker.finance.maskedNumber() // '(...9711)'
+   * faker.finance.maskedNumber({ length: 3 }) // '(...342)'
+   * faker.finance.maskedNumber({ length: 3, parens: false }) // '...236'
+   * faker.finance.maskedNumber({ length: 3, parens: false, ellipsis: false }) // '298'
    *
-   * @since 2.0.1
+   * @since 8.0.0
    */
-  mask(options?: {
+  maskedNumber(options?: {
     length?: number;
     parens?: boolean;
     ellipsis?: boolean;
@@ -254,21 +279,17 @@ export class FinanceModule {
    * @param optionsOrLength.length The length of the unmasked number. Defaults to `4`.
    * @param optionsOrLength.parens Whether to use surrounding parenthesis. Defaults to `true`.
    * @param optionsOrLength.ellipsis Whether to prefix the numbers with an ellipsis. Defaults to `true`.
-   * @param legacyParens Whether to use surrounding parenthesis. Defaults to `true`.
-   * @param legacyEllipsis Whether to prefix the numbers with an ellipsis. Defaults to `true`.
    *
    * @example
-   * faker.finance.mask() // '(...9711)'
-   * faker.finance.mask({ length: 3 }) // '(...342)'
-   * faker.finance.mask({ length: 3, parens: false }) // '...236'
-   * faker.finance.mask({ length: 3, parens: false, ellipsis: false }) // '298'
-   * faker.finance.mask(3) // '(...342)'
-   * faker.finance.mask(3, false) // '...236'
-   * faker.finance.mask(3, false, false) // '298'
+   * faker.finance.maskedNumber() // '(...9711)'
+   * faker.finance.maskedNumber(3) // '(...342)'
+   * faker.finance.maskedNumber({ length: 3 }) // '(...342)'
+   * faker.finance.maskedNumber({ length: 3, parens: false }) // '...236'
+   * faker.finance.maskedNumber({ length: 3, parens: false, ellipsis: false }) // '298'
    *
-   * @since 2.0.1
+   * @since 8.0.0
    */
-  mask(
+  maskedNumber(
     optionsOrLength?:
       | number
       | {
@@ -290,9 +311,7 @@ export class FinanceModule {
            * @default true
            */
           ellipsis?: boolean;
-        },
-    legacyParens?: boolean,
-    legacyEllipsis?: boolean
+        }
   ): string;
   /**
    * Generates a random masked number.
@@ -301,18 +320,17 @@ export class FinanceModule {
    * @param options.length The length of the unmasked number. Defaults to `4`.
    * @param options.parens Whether to use surrounding parenthesis. Defaults to `true`.
    * @param options.ellipsis Whether to prefix the numbers with an ellipsis. Defaults to `true`.
-   * @param legacyParens Whether to use surrounding parenthesis. Defaults to `true`.
-   * @param legacyEllipsis Whether to use surrounding parenthesis. Defaults to `true`.
    *
    * @example
-   * faker.finance.mask() // '(...9711)'
-   * faker.finance.mask(3) // '(...342)'
-   * faker.finance.mask(3, false) // '...236'
-   * faker.finance.mask(3, false, false) // '298'
+   * faker.finance.maskedNumber() // '(...9711)'
+   * faker.finance.maskedNumber(3) // '(...342)'
+   * faker.finance.maskedNumber({ length: 3 }) // '(...342)'
+   * faker.finance.maskedNumber({ length: 3, parens: false }) // '...236'
+   * faker.finance.maskedNumber({ length: 3, parens: false, ellipsis: false }) // '298'
    *
-   * @since 2.0.1
+   * @since 8.0.0
    */
-  mask(
+  maskedNumber(
     options:
       | number
       | {
@@ -334,20 +352,14 @@ export class FinanceModule {
            * @default true
            */
           ellipsis?: boolean;
-        } = {},
-    legacyParens: boolean = true,
-    legacyEllipsis: boolean = true
+        } = {}
   ): string {
     if (typeof options === 'number') {
       options = { length: options };
     }
 
     // set defaults
-    const {
-      ellipsis = legacyEllipsis,
-      length = 4,
-      parens = legacyParens,
-    } = options;
+    const { ellipsis, length = 4, parens } = options;
 
     // create a template for length
     let template = '';
@@ -1219,7 +1231,7 @@ export class FinanceModule {
     const company = this.faker.company.name();
     const transactionType = this.transactionType();
     const account = this.accountNumber();
-    const card = this.mask();
+    const card = this.maskedNumber();
     const currency = this.currencyCode();
 
     return `${transactionType} transaction at ${company} using card ending with ***${card} for ${currency} ${amount} in account ***${account}`;
diff --git a/test/__snapshots__/finance.spec.ts.snap b/test/__snapshots__/finance.spec.ts.snap
index fe7a51b7..69d73820 100644
--- a/test/__snapshots__/finance.spec.ts.snap
+++ b/test/__snapshots__/finance.spec.ts.snap
@@ -76,21 +76,25 @@ exports[`finance > 42 > iban > with formatted option 1`] = `"GT03 9751 1086 7098
 
 exports[`finance > 42 > litecoinAddress 1`] = `"3XbJMAAara64sSkA9HD24YHQWd1b"`;
 
-exports[`finance > 42 > mask > noArgs 1`] = `"(...3791)"`;
+exports[`finance > 42 > mask > noArgs 1`] = `"3791"`;
 
-exports[`finance > 42 > mask > with legacy ellipsis 1`] = `"(...3791)"`;
+exports[`finance > 42 > mask > with ellipsis 1`] = `"...3791"`;
 
-exports[`finance > 42 > mask > with legacy parenthesis 1`] = `"(...3791)"`;
+exports[`finance > 42 > mask > with length 1`] = `"37917"`;
 
-exports[`finance > 42 > mask > with length 1`] = `"(...37917)"`;
+exports[`finance > 42 > mask > with length, parenthesis and ellipsis 1`] = `"(...37917)"`;
 
-exports[`finance > 42 > mask > with length and parenthesis option 1`] = `"...37917"`;
+exports[`finance > 42 > mask > with parenthesis 1`] = `"(3791)"`;
 
-exports[`finance > 42 > mask > with length option 1`] = `"(...37917)"`;
+exports[`finance > 42 > maskedNumber > noArgs 1`] = `"3791"`;
 
-exports[`finance > 42 > mask > with length, legacy parenthesis, and legacy ellipsis 1`] = `"(...37917)"`;
+exports[`finance > 42 > maskedNumber > with length 1`] = `"37917"`;
 
-exports[`finance > 42 > mask > with length, parenthesis and ellipsis option 1`] = `"...37917"`;
+exports[`finance > 42 > maskedNumber > with length and parenthesis option 1`] = `"37917"`;
+
+exports[`finance > 42 > maskedNumber > with length option 1`] = `"37917"`;
+
+exports[`finance > 42 > maskedNumber > with length, parenthesis and ellipsis option 1`] = `"...37917"`;
 
 exports[`finance > 42 > pin > noArgs 1`] = `"3791"`;
 
@@ -100,7 +104,7 @@ exports[`finance > 42 > pin > with length option 1`] = `"3791775514"`;
 
 exports[`finance > 42 > routingNumber 1`] = `"379177554"`;
 
-exports[`finance > 42 > transactionDescription 1`] = `"invoice transaction at Wiegand, Deckow and Reynolds using card ending with ***(...8361) for RSD 374.54 in account ***55141004"`;
+exports[`finance > 42 > transactionDescription 1`] = `"invoice transaction at Wiegand, Deckow and Reynolds using card ending with ***8361 for RSD 374.54 in account ***55141004"`;
 
 exports[`finance > 42 > transactionType 1`] = `"withdrawal"`;
 
@@ -180,21 +184,25 @@ exports[`finance > 1211 > iban > with formatted option 1`] = `"TN42 8201 6024 17
 
 exports[`finance > 1211 > litecoinAddress 1`] = `"MTMe8Z3EaFdLqmaGKP1LEEJQVriSZRZds"`;
 
-exports[`finance > 1211 > mask > noArgs 1`] = `"(...9487)"`;
+exports[`finance > 1211 > mask > noArgs 1`] = `"9487"`;
+
+exports[`finance > 1211 > mask > with ellipsis 1`] = `"...9487"`;
 
-exports[`finance > 1211 > mask > with legacy ellipsis 1`] = `"(...9487)"`;
+exports[`finance > 1211 > mask > with length 1`] = `"94872"`;
 
-exports[`finance > 1211 > mask > with legacy parenthesis 1`] = `"(...9487)"`;
+exports[`finance > 1211 > mask > with length, parenthesis and ellipsis 1`] = `"(...94872)"`;
 
-exports[`finance > 1211 > mask > with length 1`] = `"(...94872)"`;
+exports[`finance > 1211 > mask > with parenthesis 1`] = `"(9487)"`;
 
-exports[`finance > 1211 > mask > with length and parenthesis option 1`] = `"...94872"`;
+exports[`finance > 1211 > maskedNumber > noArgs 1`] = `"9487"`;
 
-exports[`finance > 1211 > mask > with length option 1`] = `"(...94872)"`;
+exports[`finance > 1211 > maskedNumber > with length 1`] = `"94872"`;
 
-exports[`finance > 1211 > mask > with length, legacy parenthesis, and legacy ellipsis 1`] = `"(...94872)"`;
+exports[`finance > 1211 > maskedNumber > with length and parenthesis option 1`] = `"94872"`;
 
-exports[`finance > 1211 > mask > with length, parenthesis and ellipsis option 1`] = `"...94872"`;
+exports[`finance > 1211 > maskedNumber > with length option 1`] = `"94872"`;
+
+exports[`finance > 1211 > maskedNumber > with length, parenthesis and ellipsis option 1`] = `"...94872"`;
 
 exports[`finance > 1211 > pin > noArgs 1`] = `"9487"`;
 
@@ -204,7 +212,7 @@ exports[`finance > 1211 > pin > with length option 1`] = `"9487219061"`;
 
 exports[`finance > 1211 > routingNumber 1`] = `"948721904"`;
 
-exports[`finance > 1211 > transactionDescription 1`] = `"deposit transaction at Trantow - Satterfield using card ending with ***(...4316) for SDG 928.52 in account ***19061627"`;
+exports[`finance > 1211 > transactionDescription 1`] = `"deposit transaction at Trantow - Satterfield using card ending with ***4316 for SDG 928.52 in account ***19061627"`;
 
 exports[`finance > 1211 > transactionType 1`] = `"invoice"`;
 
@@ -284,21 +292,25 @@ exports[`finance > 1337 > iban > with formatted option 1`] = `"FO56 1005 0250 09
 
 exports[`finance > 1337 > litecoinAddress 1`] = `"Madhxs2jewAgkYgJi7No6Cn8JZar"`;
 
-exports[`finance > 1337 > mask > noArgs 1`] = `"(...2512)"`;
+exports[`finance > 1337 > mask > noArgs 1`] = `"2512"`;
+
+exports[`finance > 1337 > mask > with ellipsis 1`] = `"...2512"`;
+
+exports[`finance > 1337 > mask > with length 1`] = `"25122"`;
 
-exports[`finance > 1337 > mask > with legacy ellipsis 1`] = `"(...2512)"`;
+exports[`finance > 1337 > mask > with length, parenthesis and ellipsis 1`] = `"(...25122)"`;
 
-exports[`finance > 1337 > mask > with legacy parenthesis 1`] = `"(...2512)"`;
+exports[`finance > 1337 > mask > with parenthesis 1`] = `"(2512)"`;
 
-exports[`finance > 1337 > mask > with length 1`] = `"(...25122)"`;
+exports[`finance > 1337 > maskedNumber > noArgs 1`] = `"2512"`;
 
-exports[`finance > 1337 > mask > with length and parenthesis option 1`] = `"...25122"`;
+exports[`finance > 1337 > maskedNumber > with length 1`] = `"25122"`;
 
-exports[`finance > 1337 > mask > with length option 1`] = `"(...25122)"`;
+exports[`finance > 1337 > maskedNumber > with length and parenthesis option 1`] = `"25122"`;
 
-exports[`finance > 1337 > mask > with length, legacy parenthesis, and legacy ellipsis 1`] = `"(...25122)"`;
+exports[`finance > 1337 > maskedNumber > with length option 1`] = `"25122"`;
 
-exports[`finance > 1337 > mask > with length, parenthesis and ellipsis option 1`] = `"...25122"`;
+exports[`finance > 1337 > maskedNumber > with length, parenthesis and ellipsis option 1`] = `"...25122"`;
 
 exports[`finance > 1337 > pin > noArgs 1`] = `"2512"`;
 
@@ -308,6 +320,6 @@ exports[`finance > 1337 > pin > with length option 1`] = `"2512254032"`;
 
 exports[`finance > 1337 > routingNumber 1`] = `"251225401"`;
 
-exports[`finance > 1337 > transactionDescription 1`] = `"withdrawal transaction at Cronin - Effertz using card ending with ***(...3927) for GIP 262.02 in account ***54032552"`;
+exports[`finance > 1337 > transactionDescription 1`] = `"withdrawal transaction at Cronin - Effertz using card ending with ***3927 for GIP 262.02 in account ***54032552"`;
 
 exports[`finance > 1337 > transactionType 1`] = `"withdrawal"`;
diff --git a/test/finance.spec.ts b/test/finance.spec.ts
index 5af487f8..b0a2b8ed 100644
--- a/test/finance.spec.ts
+++ b/test/finance.spec.ts
@@ -96,14 +96,14 @@ describe('finance', () => {
     t.describe('mask', (t) => {
       t.it('noArgs')
         .it('with length', 5)
-        .it('with legacy parenthesis', undefined, true)
-        .it('with legacy ellipsis', undefined, undefined, true)
-        .it(
-          'with length, legacy parenthesis, and legacy ellipsis',
-          5,
-          true,
-          true
-        )
+        .it('with parenthesis', undefined, true)
+        .it('with ellipsis', undefined, undefined, true)
+        .it('with length, parenthesis and ellipsis', 5, true, true);
+    });
+
+    t.describe('maskedNumber', (t) => {
+      t.it('noArgs')
+        .it('with length', 5)
         .it('with length option', { length: 5 })
         .it('with length and parenthesis option', { length: 5, parens: false })
         .it('with length, parenthesis and ellipsis option', {
@@ -189,7 +189,7 @@ describe('finance', () => {
 
       describe('mask()', () => {
         it('should set a default length', () => {
-          const expected = 4; //default account mask length
+          const expected = 4; // default account mask length
           const mask = faker.finance.mask(undefined, false, false);
 
           expect(
@@ -203,7 +203,39 @@ describe('finance', () => {
 
           expected = expected || 4;
 
-          const mask = faker.finance.mask(expected, false, false); //the length of mask picks 4 if the random number generator picks 0
+          const mask = faker.finance.mask(expected, false, false); // the length of mask picks 4 if the random number generator picks 0
+
+          expect(
+            mask,
+            `The expected default mask length is ${expected} but it was ${mask.length}`
+          ).toHaveLength(expected);
+        });
+      });
+
+      describe('maskedNumber()', () => {
+        it('should set a default length', () => {
+          const expected = 4; // default account mask length
+          const mask = faker.finance.maskedNumber({
+            parens: false,
+            ellipsis: false,
+          });
+
+          expect(
+            mask,
+            `The expected default mask length is ${expected} but it was ${mask.length}`
+          ).toHaveLength(expected);
+        });
+
+        it('should set a specified length', () => {
+          let expected = faker.number.int(20);
+
+          expected = expected || 4;
+
+          const mask = faker.finance.maskedNumber({
+            length: expected,
+            parens: false,
+            ellipsis: false,
+          }); // the length of mask picks 4 if the random number generator picks 0
 
           expect(
             mask,