refactor(phone): deprecate `format` argument for `phone.number` (#2229)

2 files changed, 35 insertions, 3 deletions

diff --git a/src/modules/helpers/index.ts b/src/modules/helpers/index.ts
index 228e410d..f124cec1 100644
--- a/src/modules/helpers/index.ts
+++ b/src/modules/helpers/index.ts
@@ -1154,7 +1154,7 @@ export class HelpersModule {
    * faker.helpers.fake('{{person.lastName}}, {{person.firstName}} {{person.suffix}}') // 'Durgan, Noe MD'
    * faker.helpers.fake('This is static test.') // 'This is static test.'
    * faker.helpers.fake('Good Morning {{person.firstName}}!') // 'Good Morning Estelle!'
-   * faker.helpers.fake('You can call me at {{phone.number(!## ### #####!)}}.') // 'You can call me at 202 555 973722.'
+   * faker.helpers.fake('You can visit me at {{location.streetAddress(true)}}.') // 'You can visit me at 3393 Ronny Way Apt. 742.'
    * faker.helpers.fake('I flipped the coin and got: {{helpers.arrayElement(["heads", "tails"])}}') // 'I flipped the coin and got: tails'
    * faker.helpers.fake(['A: {{person.firstName}}', 'B: {{person.lastName}}']) // 'A: Barry'
    *
diff --git a/src/modules/phone/index.ts b/src/modules/phone/index.ts
index 96b434a5..27b793db 100644
--- a/src/modules/phone/index.ts
+++ b/src/modules/phone/index.ts
@@ -1,4 +1,5 @@
 import type { Faker } from '../..';
+import { deprecated } from '../../internal/deprecated';
 
 /**
  * Module to generate phone-related data.
@@ -24,16 +25,47 @@ export class PhoneModule {
   /**
    * Generates a random phone number.
    *
-   * @param format Format of the phone number. Defaults to a random phone number format.
-   *
    * @example
    * faker.phone.number() // '961-770-7727'
+   *
+   * @since 7.3.0
+   */
+  number(): string;
+  /**
+   * Generates a random phone number.
+   *
+   * @param format Format of the phone number.
+   *
+   * @example
    * faker.phone.number('501-###-###') // '501-039-841'
    * faker.phone.number('+48 91 ### ## ##') // '+48 91 463 61 70'
    *
    * @since 7.3.0
+   *
+   * @deprecated Use `faker.phone.number()` without an argument instead.
    */
+  number(format: string): string;
+  /**
+   * Generates a random phone number.
+   *
+   * @param format Format of the phone number. Defaults to a random phone number format.
+   *
+   * @example
+   * faker.phone.number() // '961-770-7727'
+   *
+   * @since 7.3.0
+   */
+  number(format?: string): string;
   number(format?: string): string {
+    if (format != null) {
+      deprecated({
+        deprecated: 'faker.phone.number(format)',
+        proposed: 'faker.phone.number()',
+        since: '8.1',
+        until: '9.0',
+      });
+    }
+
     format =
       format ??
       this.faker.helpers.arrayElement(