feat(phone)!: add new style parameter

docs/guide/upgrading_v9/2578.md

@@ -0,0 +1,15 @@
+### faker.phone.number `style` replaces explicit `format`
+
+`faker.phone.number()` generates a phone number for the current locale. However, previously there was little control over the generated number, which might or might not include country codes, extensions, white space and punctuation.
+
+If you wanted more control over the number, it was previously necessary to pass an explicit `format` parameter. This has now been removed. Instead, you can consider one of two options:
+
+1. The new `style` parameter has convenient options for common use cases. There are three possible values.
+
+- - `'human'`: (default, existing behavior) A human-input phone number, e.g. `555-770-7727` or `555.770.7727 x1234`
+- - `'national'`: A phone number in a standardized national format, e.g. `(555) 123-4567`.
+- - `'international'`: A phone number in a E.123 standard international format with country code, e.g. `+15551234567`
+
+The styles are locale-aware, so for example if you use pt_PT, phone numbers suitable for Portugal would be generated.
+
+2. If none of the `style`s match your needs, you can use `faker.string.numeric()` or `faker.helpers.fromRegExp()` to create a custom pattern.

src/definitions/phone_number.ts

@@ -12,5 +12,18 @@
    *
    * @see faker.helpers.replaceSymbolWithNumber(format): For more information about how the patterns are used.
    */
-  formats: string[];
+  format: {
+    /**
+     * Formats for a human-input phone number, e.g. `555-770-7727` or `555.770.7727 x1234`
+     */
+    human: string[];
+    /**
+     * Formats for a phone number in a standardized national format, e.g. `(555) 123-4567`.
+     */
+    national: string[];
+    /**
+     * Formats for a phone number in the standardised E.123 format, e.g. `+15551234567`
+     */
+    international: string[];
+  };
 }>;

src/locales/af_ZA/phone_number/format/index.ts

@@ -0,0 +1,16 @@
+/*
+ * This file is automatically generated.
+ * Run 'pnpm run generate:locales' to update.
+ */
+import type { PhoneNumberDefinition } from '../../../..';
+import human from './human';
+import international from './international';
+import national from './national';
+
+const format: PhoneNumberDefinition['format'] = {
+  human,
+  international,
+  national,
+};
+
+export default format;

src/locales/af_ZA/phone_number/format/international.ts

@@ -0,0 +1,9 @@
+export default [
+  '+271#########',
+  '+272#########',
+  '+273#########',
+  '+274#########',
+  '+275#########',
+  '+27800######',
+  '+27860######',
+];

src/locales/af_ZA/phone_number/format/national.ts

@@ -0,0 +1,9 @@
+export default [
+  '1#########',
+  '2#########',
+  '3#########',
+  '4#########',
+  '5#########',
+  '080 0## ####',
+  '0860 ### ###',
+];

src/locales/af_ZA/phone_number/index.ts

@@ -3,10 +3,10 @@
  * Run 'pnpm run generate:locales' to update.
  */
 import type { PhoneNumberDefinition } from '../../..';
-import formats from './formats';
+import format from './format';
 
 const phone_number: PhoneNumberDefinition = {
-  formats,
+  format,
 };
 
 export default phone_number;

src/locales/ar/index.ts

@@ -11,7 +11,6 @@ import location from './location';
 import lorem from './lorem';
 import metadata from './metadata';
 import person from './person';
-import phone_number from './phone_number';
 import team from './team';
 import vehicle from './vehicle';
 
@@ -24,7 +23,6 @@ const ar: LocaleDefinition = {
   lorem,
   metadata,
   person,
-  phone_number,
   team,
   vehicle,
 };

src/locales/az/phone_number/format/index.ts

@@ -0,0 +1,16 @@
+/*
+ * This file is automatically generated.
+ * Run 'pnpm run generate:locales' to update.
+ */
+import type { PhoneNumberDefinition } from '../../../..';
+import human from './human';
+import international from './international';
+import national from './national';
+
+const format: PhoneNumberDefinition['format'] = {
+  human,
+  international,
+  national,
+};
+
+export default format;

src/locales/az/phone_number/format/international.ts

@@ -0,0 +1 @@
+export default ['+9949#########'];

src/locales/az/phone_number/format/national.ts

@@ -0,0 +1 @@
+export default ['9#########'];

src/locales/az/phone_number/index.ts

@@ -3,10 +3,10 @@
  * Run 'pnpm run generate:locales' to update.
  */
 import type { PhoneNumberDefinition } from '../../..';
-import formats from './formats';
+import format from './format';
 
 const phone_number: PhoneNumberDefinition = {
-  formats,
+  format,
 };
 
 export default phone_number;

src/locales/cs_CZ/phone_number/format/index.ts

@@ -0,0 +1,16 @@
+/*
+ * This file is automatically generated.
+ * Run 'pnpm run generate:locales' to update.
+ */
+import type { PhoneNumberDefinition } from '../../../..';
+import human from './human';
+import international from './international';
+import national from './national';
+
+const format: PhoneNumberDefinition['format'] = {
+  human,
+  international,
+  national,
+};
+
+export default format;

src/locales/cs_CZ/phone_number/format/international.ts

@@ -0,0 +1,6 @@
+export default [
+  '+420601######',
+  '+420737######',
+  '+420736######',
+  '+420#########',
+];

src/locales/cs_CZ/phone_number/format/national.ts

@@ -0,0 +1 @@
+export default ['601 ### ###', '737 ### ###', '736 ### ###', '### ### ###'];

src/locales/cs_CZ/phone_number/index.ts

@@ -3,10 +3,10 @@
  * Run 'pnpm run generate:locales' to update.
  */
 import type { PhoneNumberDefinition } from '../../..';
-import formats from './formats';
+import format from './format';
 
 const phone_number: PhoneNumberDefinition = {
-  formats,
+  format,
 };
 
 export default phone_number;

src/locales/da/phone_number/format/index.ts

@@ -0,0 +1,16 @@
+/*
+ * This file is automatically generated.
+ * Run 'pnpm run generate:locales' to update.
+ */
+import type { PhoneNumberDefinition } from '../../../..';
+import human from './human';
+import international from './international';
+import national from './national';
+
+const format: PhoneNumberDefinition['format'] = {
+  human,
+  international,
+  national,
+};
+
+export default format;

src/locales/da/phone_number/format/international.ts

@@ -0,0 +1 @@
+export default ['+45!#######'];

src/locales/da/phone_number/format/national.ts

@@ -0,0 +1 @@
+export default ['!# ## ## ##'];

src/locales/da/phone_number/index.ts

@@ -3,10 +3,10 @@
  * Run 'pnpm run generate:locales' to update.
  */
 import type { PhoneNumberDefinition } from '../../..';
-import formats from './formats';
+import format from './format';
 
 const phone_number: PhoneNumberDefinition = {
-  formats,
+  format,
 };
 
 export default phone_number;

src/locales/de/phone_number/format/index.ts

@@ -0,0 +1,16 @@
+/*
+ * This file is automatically generated.
+ * Run 'pnpm run generate:locales' to update.
+ */
+import type { PhoneNumberDefinition } from '../../../..';
+import human from './human';
+import international from './international';
+import national from './national';
+
+const format: PhoneNumberDefinition['format'] = {
+  human,
+  international,
+  national,
+};
+
+export default format;

src/locales/de/phone_number/format/international.ts

@@ -0,0 +1 @@
+export default ['+49############', '+49###########', '+49##########'];

src/locales/de/phone_number/format/national.ts

@@ -0,0 +1 @@
+export default ['0#### ########', '0#### #######', '0#### ######'];

src/locales/de/phone_number/index.ts

@@ -3,10 +3,10 @@
  * Run 'pnpm run generate:locales' to update.
  */
 import type { PhoneNumberDefinition } from '../../..';
-import formats from './formats';
+import format from './format';
 
 const phone_number: PhoneNumberDefinition = {
-  formats,
+  format,
 };
 
 export default phone_number;

src/locales/de_AT/phone_number/format/index.ts

@@ -0,0 +1,16 @@
+/*
+ * This file is automatically generated.
+ * Run 'pnpm run generate:locales' to update.
+ */
+import type { PhoneNumberDefinition } from '../../../..';
+import human from './human';
+import international from './international';
+import national from './national';
+
+const format: PhoneNumberDefinition['format'] = {
+  human,
+  international,
+  national,
+};
+
+export default format;

src/locales/de_AT/phone_number/format/international.ts

@@ -0,0 +1 @@
+export default ['+431#######', '+43########', '+43#########'];

src/locales/de_AT/phone_number/format/national.ts

@@ -0,0 +1 @@
+export default ['01 #######', '0#### ####', '0#### #####'];

src/locales/de_AT/phone_number/index.ts

@@ -3,10 +3,10 @@
  * Run 'pnpm run generate:locales' to update.
  */
 import type { PhoneNumberDefinition } from '../../..';
-import formats from './formats';
+import format from './format';
 
 const phone_number: PhoneNumberDefinition = {
-  formats,
+  format,
 };
 
 export default phone_number;

src/locales/de_CH/phone_number/format/index.ts

@@ -0,0 +1,16 @@
+/*
+ * This file is automatically generated.
+ * Run 'pnpm run generate:locales' to update.
+ */
+import type { PhoneNumberDefinition } from '../../../..';
+import human from './human';
+import international from './international';
+import national from './national';
+
+const format: PhoneNumberDefinition['format'] = {
+  human,
+  international,
+  national,
+};
+
+export default format;

src/locales/de_CH/phone_number/format/international.ts

@@ -0,0 +1,8 @@
+export default [
+  '+41800######',
+  '+41#########',
+  '+41900######',
+  '+4176#######',
+  '+4178#######',
+  '+4179#######',
+];

src/locales/de_CH/phone_number/format/national.ts

@@ -0,0 +1,8 @@
+export default [
+  '0800 ### ###',
+  '0## ### ## ##',
+  '0900 ### ###',
+  '076 ### ## ##',
+  '078 ### ## ##',
+  '079 ### ## ##',
+];

src/locales/de_CH/phone_number/index.ts

@@ -3,10 +3,10 @@
  * Run 'pnpm run generate:locales' to update.
  */
 import type { PhoneNumberDefinition } from '../../..';
-import formats from './formats';
+import format from './format';
 
 const phone_number: PhoneNumberDefinition = {
-  formats,
+  format,
 };
 
 export default phone_number;

src/locales/dv/phone_number/format/index.ts

@@ -0,0 +1,16 @@
+/*
+ * This file is automatically generated.
+ * Run 'pnpm run generate:locales' to update.
+ */
+import type { PhoneNumberDefinition } from '../../../..';
+import human from './human';
+import international from './international';
+import national from './national';
+
+const format: PhoneNumberDefinition['format'] = {
+  human,
+  international,
+  national,
+};
+
+export default format;

src/locales/dv/phone_number/format/international.ts

@@ -0,0 +1,9 @@
+export default [
+  '+9603######',
+  '+9604######',
+  '+9605######',
+  '+9606######',
+  '+9607######',
+  '+9608######',
+  '+9609######',
+];

src/locales/dv/phone_number/format/national.ts

@@ -0,0 +1,9 @@
+export default [
+  '3##-####',
+  '4##-####',
+  '5######',
+  '6##-####',
+  '7##-####',
+  '8######',
+  '9##-####',
+];