chore: use a standardized deprecated function (#689)

Co-authored-by: pkuczynski <piotr.kuczynski@gmail.com>

src/helpers.ts

@@ -1,4 +1,5 @@
 import type { Faker } from '.';
+import { deprecated } from './internal/deprecated';
 
 /**
  * A full card with various details.
@@ -143,9 +144,12 @@ export class Helpers {
   randomize<T = string>(
     array: ReadonlyArray<T> = ['a', 'b', 'c'] as unknown as ReadonlyArray<T>
   ): T {
-    console.warn(
-      'Deprecation Warning: faker.helpers.randomize is now located in faker.random.arrayElement'
-    );
+    deprecated({
+      deprecated: 'faker.helpers.randomize()',
+      proposed: 'faker.random.arrayElement()',
+      // since: 'v5.0.0', (?)
+      until: 'v7.0.0',
+    });
     return this.faker.random.arrayElement(array);
   }
 
@@ -511,9 +515,12 @@ export class Helpers {
    * @deprecated If you need some specific object you should create your own method.
    */
   createCard(): Card {
-    console.warn(
-      'Deprecation Warning: If you need some specific object you should create your own method.'
-    );
+    deprecated({
+      deprecated: 'helpers.createCard()',
+      proposed: 'a self-build function',
+      since: 'v6.1.0',
+      until: 'v7.0.0',
+    });
     return {
       name: this.faker.name.findName(),
       username: this.faker.internet.userName(),
@@ -582,9 +589,12 @@ export class Helpers {
    * @deprecated If you need some specific object you should create your own method.
    */
   contextualCard(): ContextualCard {
-    console.warn(
-      'Deprecation Warning: If you need some specific object you should create your own method.'
-    );
+    deprecated({
+      deprecated: 'helpers.contextualCard()',
+      proposed: 'a self-build function',
+      since: 'v6.1.0',
+      until: 'v7.0.0',
+    });
     const name = this.faker.name.firstName();
     const userName = this.faker.internet.userName(name);
     return {
@@ -631,9 +641,12 @@ export class Helpers {
    * @deprecated If you need some specific object you should create your own method.
    */
   userCard(): UserCard {
-    console.warn(
-      'Deprecation Warning: If you need some specific object you should create your own method.'
-    );
+    deprecated({
+      deprecated: 'helpers.userCard()',
+      proposed: 'a self-build function',
+      since: 'v6.1.0',
+      until: 'v7.0.0',
+    });
     return {
       name: this.faker.name.findName(),
       username: this.faker.internet.userName(),

src/internal/deprecated.ts

@@ -0,0 +1,29 @@
+/* eslint-disable jsdoc/check-tag-names */
+/* eslint-disable jsdoc/require-param */
+
+/** @internal */
+export interface DeprecatedOptions {
+  deprecated: string;
+  proposed?: string;
+  since?: string;
+  until?: string;
+}
+
+/** @internal */
+export function deprecated(opts: DeprecatedOptions): void {
+  let message = `[@faker-js/faker]: ${opts.deprecated} is deprecated`;
+
+  if (opts.since) {
+    message += ` since ${opts.since}`;
+  }
+
+  if (opts.until) {
+    message += ` and will be removed in ${opts.until}`;
+  }
+
+  if (opts.proposed) {
+    message += `. Please use ${opts.proposed} instead`;
+  }
+
+  console.warn(message + '.');
+}

src/name.ts

@@ -1,4 +1,5 @@
 import type { Faker } from '.';
+import { deprecated } from './internal/deprecated';
 
 export enum Gender {
   female = 'female',
@@ -12,10 +13,12 @@ export type GenderType = 'female' | 'male' | 0 | 1;
  * Normalize gender.
  *
  * @param gender Gender.
+ * @param functionName Temporary parameter for deprecation message.
  * @returns Normalized gender.
  */
 function normalizeGender(
-  gender?: GenderType
+  gender?: GenderType,
+  functionName?: string
 ): Exclude<GenderType, number> | undefined {
   if (gender == null || typeof gender === 'string') {
     // TODO @Shinigami92 21-03-2022: Cast can be removed when we set `strict: true`
@@ -24,9 +27,12 @@ function normalizeGender(
 
   const normalizedGender = gender === 0 ? 'male' : 'female';
 
-  console.warn(
-    `Deprecation Warning: Please use '${normalizedGender}' for gender instead of ${gender}`
-  );
+  deprecated({
+    deprecated: `name.${functionName}(number)`,
+    proposed: "'female' or 'male'",
+    since: 'v6.1.0',
+    until: 'v7.0.0',
+  });
 
   return normalizedGender;
 }
@@ -40,6 +46,7 @@ function normalizeGender(
  * @param param2.generic Non-gender definitions.
  * @param param2.female Female definitions.
  * @param param2.male Male definitions.
+ * @param functionName Temporary parameter for deprecation message.
  * @returns Definition based on given gender.
  */
 function selectDefinition(
@@ -50,9 +57,10 @@ function selectDefinition(
     generic,
     female,
     male,
-  }: { generic?: string[]; female?: string[]; male?: string[] } = {}
+  }: { generic?: string[]; female?: string[]; male?: string[] } = {},
+  functionName?: string
 ) {
-  const normalizedGender = normalizeGender(gender);
+  const normalizedGender = normalizeGender(gender, functionName);
 
   let values: string[] | undefined;
   switch (normalizedGender) {
@@ -107,11 +115,16 @@ export class Name {
     const { first_name, female_first_name, male_first_name } =
       this.faker.definitions.name;
 
-    return selectDefinition(this.faker, gender, {
-      generic: first_name,
-      female: female_first_name,
-      male: male_first_name,
-    });
+    return selectDefinition(
+      this.faker,
+      gender,
+      {
+        generic: first_name,
+        female: female_first_name,
+        male: male_first_name,
+      },
+      'firstName'
+    );
   }
 
   /**
@@ -129,11 +142,16 @@ export class Name {
     const { last_name, female_last_name, male_last_name } =
       this.faker.definitions.name;
 
-    return selectDefinition(this.faker, gender, {
-      generic: last_name,
-      female: female_last_name,
-      male: male_last_name,
-    });
+    return selectDefinition(
+      this.faker,
+      gender,
+      {
+        generic: last_name,
+        female: female_last_name,
+        male: male_last_name,
+      },
+      'lastName'
+    );
   }
 
   /**
@@ -151,11 +169,16 @@ export class Name {
     const { middle_name, female_middle_name, male_middle_name } =
       this.faker.definitions.name;
 
-    return selectDefinition(this.faker, gender, {
-      generic: middle_name,
-      female: female_middle_name,
-      male: male_middle_name,
-    });
+    return selectDefinition(
+      this.faker,
+      gender,
+      {
+        generic: middle_name,
+        female: female_middle_name,
+        male: male_middle_name,
+      },
+      'middleName'
+    );
   }
 
   /**
@@ -179,7 +202,7 @@ export class Name {
     let suffix = '';
 
     const normalizedGender: Exclude<GenderType, number> =
-      normalizeGender(gender) ??
+      normalizeGender(gender, 'findName') ??
       this.faker.random.arrayElement(['female', 'male']);
 
     firstName = firstName || this.faker.name.firstName(normalizedGender);
@@ -237,11 +260,16 @@ export class Name {
   prefix(gender?: GenderType): string {
     const { prefix, female_prefix, male_prefix } = this.faker.definitions.name;
 
-    return selectDefinition(this.faker, gender, {
-      generic: prefix,
-      female: female_prefix,
-      male: male_prefix,
-    });
+    return selectDefinition(
+      this.faker,
+      gender,
+      {
+        generic: prefix,
+        female: female_prefix,
+        male: male_prefix,
+      },
+      'prefix'
+    );
   }
 
   /**

src/random.ts

@@ -1,4 +1,5 @@
 import type { Faker } from '.';
+import { deprecated } from './internal/deprecated';
 
 /**
  * Method to reduce array of characters.
@@ -52,9 +53,12 @@ export class Random {
   number(
     options?: number | { min?: number; max?: number; precision?: number }
   ): number {
-    console.warn(
-      'Deprecation Warning: faker.random.number is now located in faker.datatype.number'
-    );
+    deprecated({
+      deprecated: 'faker.random.number()',
+      proposed: 'faker.datatype.number()',
+      // since: 'v5.0.0', (?)
+      until: 'v7.0.0',
+    });
     return this.faker.datatype.number(options);
   }
 
@@ -81,9 +85,12 @@ export class Random {
   float(
     options?: number | { min?: number; max?: number; precision?: number }
   ): number {
-    console.warn(
-      'Deprecation Warning: faker.random.float is now located in faker.datatype.float'
-    );
+    deprecated({
+      deprecated: 'faker.random.float()',
+      proposed: 'faker.datatype.float()',
+      // since: 'v5.0.0', (?)
+      until: 'v7.0.0',
+    });
     return this.faker.datatype.float(options);
   }
 
@@ -213,9 +220,12 @@ export class Random {
    * @deprecated
    */
   uuid(): string {
-    console.warn(
-      'Deprecation Warning: faker.random.uuid is now located in faker.datatype.uuid'
-    );
+    deprecated({
+      deprecated: 'faker.random.uuid()',
+      proposed: 'faker.datatype.uuid()',
+      // since: 'v5.0.0', (?)
+      until: 'v7.0.0',
+    });
     return this.faker.datatype.uuid();
   }
 
@@ -230,9 +240,12 @@ export class Random {
    * @deprecated
    */
   boolean(): boolean {
-    console.warn(
-      'Deprecation Warning: faker.random.boolean is now located in faker.datatype.boolean'
-    );
+    deprecated({
+      deprecated: 'faker.random.boolean()',
+      proposed: 'faker.datatype.boolean()',
+      // since: 'v5.0.0', (?)
+      until: 'v7.0.0',
+    });
     return this.faker.datatype.boolean();
   }
 
@@ -347,9 +360,12 @@ export class Random {
    * @deprecated
    */
   image(): string {
-    console.warn(
-      'Deprecation Warning: faker.random.image is now located in faker.image.image'
-    );
+    deprecated({
+      deprecated: 'faker.random.image()',
+      proposed: 'faker.image.image()',
+      // since: 'v5.0.0', (?)
+      until: 'v7.0.0',
+    });
     return this.faker.image.image();
   }
 
@@ -533,9 +549,12 @@ export class Random {
    * @deprecated
    */
   hexaDecimal(count?: number): string {
-    console.warn(
-      'Deprecation Warning: faker.random.hexaDecimal is now located in faker.datatype.hexaDecimal'
-    );
+    deprecated({
+      deprecated: 'faker.random.hexaDecimal()',
+      proposed: 'faker.datatype.hexaDecimal()',
+      // since: 'v5.0.0', (?)
+      until: 'v7.0.0',
+    });
     return this.faker.datatype.hexaDecimal(count);
   }
 }

src/time.ts

@@ -1,4 +1,5 @@
 import type { LiteralUnion } from './faker';
+import { deprecated } from './internal/deprecated';
 
 /**
  * Module to generate time of dates in various formats.
@@ -28,13 +29,12 @@ export class Time {
   recent(
     format: LiteralUnion<'abbr' | 'date' | 'wide' | 'unix'> = 'unix'
   ): string | number | Date {
-    console.warn(
-      `Deprecation Warning: faker.time.recent() is deprecated. Use the native \`new Date()\` and call the function you want on it.
-  abbr => toLocaleTimeString()
-  wide => toTimeString()
-  unix => getTime()
-`
-    );
+    deprecated({
+      deprecated: 'faker.time.recent()',
+      proposed: 'native `new Date()` and call the function you want on it',
+      since: 'v6.1.0',
+      until: 'v7.0.0',
+    });
 
     let date: string | number | Date = new Date();
 

test/helpers.spec.ts

@@ -774,7 +774,7 @@ describe('helpers', () => {
             faker.helpers[functionName]();
 
             expect(spy).toHaveBeenCalledWith(
-              `Deprecation Warning: faker.helpers.${functionName} is now located in faker.${newLocation}`
+              `[@faker-js/faker]: faker.helpers.${functionName}() is deprecated and will be removed in v7.0.0. Please use faker.${newLocation}() instead.`
             );
             spy.mockRestore();
           }
@@ -791,7 +791,7 @@ describe('helpers', () => {
         faker.helpers[functionName]();
 
         expect(spy).toHaveBeenCalledWith(
-          `Deprecation Warning: If you need some specific object you should create your own method.`
+          `[@faker-js/faker]: helpers.${functionName}() is deprecated since v6.1.0 and will be removed in v7.0.0. Please use a self-build function instead.`
         );
         spy.mockRestore();
       }