chore(random): deprecate random module (#1939)

3 files changed, 35 insertions, 1 deletions

diff --git a/src/faker.ts b/src/faker.ts
index 6a23cffd..2d6d2936 100644
--- a/src/faker.ts
+++ b/src/faker.ts
@@ -64,6 +64,10 @@ export class Faker {
   /** @internal */
   private readonly _mersenne: Mersenne = mersenne();
 
+  /**
+   * @deprecated Use the modules specific to the type of data you want to generate instead.
+   */
+  // eslint-disable-next-line deprecation/deprecation
   readonly random: RandomModule = new RandomModule(this);
 
   readonly helpers: HelpersModule = new HelpersModule(this);
diff --git a/src/index.ts b/src/index.ts
index dc67c9d5..a526e317 100644
--- a/src/index.ts
+++ b/src/index.ts
@@ -81,6 +81,7 @@ export type {
   SexType,
 } from './modules/person';
 export type { PhoneModule } from './modules/phone';
+// eslint-disable-next-line deprecation/deprecation
 export type { RandomModule } from './modules/random';
 export type { ChemicalElement, ScienceModule, Unit } from './modules/science';
 export type { StringModule } from './modules/string';
diff --git a/src/modules/random/index.ts b/src/modules/random/index.ts
index b35b7c87..809c9322 100644
--- a/src/modules/random/index.ts
+++ b/src/modules/random/index.ts
@@ -11,12 +11,16 @@ import type {
 
 /**
  * Generates random values of different kinds.
+ *
+ * @deprecated Use the modules specific to the type of data you want to generate instead.
  */
 export class RandomModule {
   constructor(private readonly faker: Faker) {
     // Bind `this` so namespaced is working correctly
     for (const name of Object.getOwnPropertyNames(
+      // eslint-disable-next-line deprecation/deprecation
       RandomModule.prototype
+      // eslint-disable-next-line deprecation/deprecation
     ) as Array<keyof RandomModule | 'constructor'>) {
       if (name === 'constructor' || typeof this[name] !== 'function') {
         continue;
@@ -27,14 +31,26 @@ export class RandomModule {
   }
 
   /**
-   * Returns random word.
+   * Returns a random word.
+   *
+   * @see faker.lorem.word()
+   * @see faker.word.sample()
    *
    * @example
    * faker.random.word() // 'Seamless'
    *
    * @since 3.1.0
+   *
+   * @deprecated Use `faker.lorem.word()` or `faker.word.sample()` instead.
    */
   word(): string {
+    deprecated({
+      deprecated: 'faker.random.word()',
+      proposed: 'faker.lorem.word() or faker.word.sample()',
+      since: '8.0',
+      until: '9.0',
+    });
+
     const wordMethods = [
       this.faker.location.cardinalDirection,
       this.faker.location.cityName,
@@ -157,12 +173,17 @@ export class RandomModule {
    * @param count.min The minimum number of words. Defaults to `1`.
    * @param count.max The maximum number of words. Defaults to `3`.
    *
+   * @see faker.lorem.words()
+   * @see faker.word.words()
+   *
    * @example
    * faker.random.words() // 'neural'
    * faker.random.words(5) // 'copy Handcrafted bus client-server Point'
    * faker.random.words({ min: 3, max: 5 }) // 'cool sticky Borders'
    *
    * @since 3.1.0
+   *
+   * @deprecated Use `faker.lorem.words()` or `faker.word.words()` instead.
    */
   words(
     count:
@@ -178,6 +199,14 @@ export class RandomModule {
           max: number;
         } = { min: 1, max: 3 }
   ): string {
+    deprecated({
+      deprecated: 'faker.random.words()',
+      proposed: 'faker.lorem.words() or faker.word.words()',
+      since: '8.0',
+      until: '9.0',
+    });
+
+    // eslint-disable-next-line deprecation/deprecation
     return this.faker.helpers.multiple(this.word, { count }).join(' ');
   }