refactor(date): rename abbr to abbreviated (#2068)

3 files changed, 337 insertions, 21 deletions

diff --git a/src/modules/date/index.ts b/src/modules/date/index.ts
index 76987735..ad8be056 100644
--- a/src/modules/date/index.ts
+++ b/src/modules/date/index.ts
@@ -803,7 +803,40 @@ export class DateModule {
    * Returns a random name of a month.
    *
    * @param options The optional options to use.
-   * @param options.abbr Whether to return an abbreviation. Defaults to `false`.
+   * @param options.abbreviated Whether to return an abbreviation. Defaults to `false`.
+   * @param options.context Whether to return the name of a month in the context of a date. In the default `en` locale this has no effect, however, in other locales like `fr` or `ru`, this may affect grammar or capitalization, for example `'январь'` with `{ context: false }` and `'января'` with `{ context: true }` in `ru`. Defaults to `false`.
+   *
+   * @example
+   * faker.date.month() // 'October'
+   * faker.date.month({ abbreviated: true }) // 'Feb'
+   * faker.date.month({ context: true }) // 'June'
+   * faker.date.month({ abbreviated: true, context: true }) // 'Sep'
+   *
+   * @since 3.0.1
+   */
+  month(options?: {
+    /**
+     * Whether to return an abbreviation.
+     *
+     * @default false
+     */
+    abbreviated?: boolean;
+    /**
+     * Whether to return the name of a month in the context of a date.
+     *
+     * In the default `en` locale this has no effect,
+     * however, in other locales like `fr` or `ru`, this may affect grammar or capitalization,
+     * for example `'январь'` with `{ context: false }` and `'января'` with `{ context: true }` in `ru`.
+     *
+     * @default false
+     */
+    context?: boolean;
+  }): string;
+  /**
+   * Returns a random name of a month.
+   *
+   * @param options The optional options to use.
+   * @param options.abbr Deprecated, use `abbreviated` instead.
    * @param options.context Whether to return the name of a month in the context of a date. In the default `en` locale this has no effect, however, in other locales like `fr` or `ru`, this may affect grammar or capitalization, for example `'январь'` with `{ context: false }` and `'января'` with `{ context: true }` in `ru`. Defaults to `false`.
    *
    * @example
@@ -813,6 +846,86 @@ export class DateModule {
    * faker.date.month({ abbr: true, context: true }) // 'Sep'
    *
    * @since 3.0.1
+   *
+   * @deprecated Use `faker.date.month({ abbreviated, ... })` instead.
+   */
+  month(options?: {
+    /**
+     * Whether to return an abbreviation.
+     *
+     * @default false
+     *
+     * @deprecated Use `abbreviated` instead.
+     */
+    abbr?: boolean;
+    /**
+     * Whether to return the name of a month in the context of a date.
+     *
+     * In the default `en` locale this has no effect,
+     * however, in other locales like `fr` or `ru`, this may affect grammar or capitalization,
+     * for example `'январь'` with `{ context: false }` and `'января'` with `{ context: true }` in `ru`.
+     *
+     * @default false
+     */
+    context?: boolean;
+  }): string;
+  /**
+   * Returns a random name of a month.
+   *
+   * @param options The optional options to use.
+   * @param options.abbr Deprecated, use `abbreviated` instead.
+   * @param options.abbreviated Whether to return an abbreviation. Defaults to `false`.
+   * @param options.context Whether to return the name of a month in the context of a date. In the default `en` locale this has no effect, however, in other locales like `fr` or `ru`, this may affect grammar or capitalization, for example `'январь'` with `{ context: false }` and `'января'` with `{ context: true }` in `ru`. Defaults to `false`.
+   *
+   * @example
+   * faker.date.month() // 'October'
+   * faker.date.month({ abbreviated: true }) // 'Feb'
+   * faker.date.month({ context: true }) // 'June'
+   * faker.date.month({ abbreviated: true, context: true }) // 'Sep'
+   *
+   * @since 3.0.1
+   */
+  month(options?: {
+    /**
+     * Whether to return an abbreviation.
+     *
+     * @default false
+     *
+     * @deprecated Use `abbreviated` instead.
+     */
+    abbr?: boolean;
+    /**
+     * Whether to return an abbreviation.
+     *
+     * @default false
+     */
+    abbreviated?: boolean;
+    /**
+     * Whether to return the name of a month in the context of a date.
+     *
+     * In the default `en` locale this has no effect,
+     * however, in other locales like `fr` or `ru`, this may affect grammar or capitalization,
+     * for example `'январь'` with `{ context: false }` and `'января'` with `{ context: true }` in `ru`.
+     *
+     * @default false
+     */
+    context?: boolean;
+  }): string;
+  /**
+   * Returns a random name of a month.
+   *
+   * @param options The optional options to use.
+   * @param options.abbr Deprecated, use `abbreviated` instead.
+   * @param options.abbreviated Whether to return an abbreviation. Defaults to `false`.
+   * @param options.context Whether to return the name of a month in the context of a date. In the default `en` locale this has no effect, however, in other locales like `fr` or `ru`, this may affect grammar or capitalization, for example `'январь'` with `{ context: false }` and `'января'` with `{ context: true }` in `ru`. Defaults to `false`.
+   *
+   * @example
+   * faker.date.month() // 'October'
+   * faker.date.month({ abbreviated: true }) // 'Feb'
+   * faker.date.month({ context: true }) // 'June'
+   * faker.date.month({ abbreviated: true, context: true }) // 'Sep'
+   *
+   * @since 3.0.1
    */
   month(
     options: {
@@ -820,9 +933,17 @@ export class DateModule {
        * Whether to return an abbreviation.
        *
        * @default false
+       *
+       * @deprecated Use `abbreviated` instead.
        */
       abbr?: boolean;
       /**
+       * Whether to return an abbreviation.
+       *
+       * @default false
+       */
+      abbreviated?: boolean;
+      /**
        * Whether to return the name of a month in the context of a date.
        *
        * In the default `en` locale this has no effect,
@@ -834,11 +955,25 @@ export class DateModule {
       context?: boolean;
     } = {}
   ): string {
-    const { abbr = false, context = false } = options;
+    const {
+      // eslint-disable-next-line deprecation/deprecation
+      abbr,
+      abbreviated = abbr ?? false,
+      context = false,
+    } = options;
+
+    if (abbr != null) {
+      deprecated({
+        deprecated: 'faker.date.month({ abbr })',
+        proposed: 'faker.date.month({ abbreviated })',
+        since: '8.0',
+        until: '9.0',
+      });
+    }
 
     const source = this.faker.definitions.date.month;
     let type: keyof DateEntryDefinition;
-    if (abbr) {
+    if (abbreviated) {
       if (context && source['abbr_context'] != null) {
         type = 'abbr_context';
       } else {
@@ -857,7 +992,41 @@ export class DateModule {
    * Returns a random day of the week.
    *
    * @param options The optional options to use.
-   * @param options.abbr Whether to return an abbreviation. Defaults to `false`.
+   * @param options.abbreviated Whether to return an abbreviation. Defaults to `false`.
+   * @param options.context Whether to return the day of the week in the context of a date. In the default `en` locale this has no effect, however, in other locales like `fr` or `ru`, this may affect grammar or capitalization, for example `'Lundi'` with `{ context: false }` and `'lundi'` with `{ context: true }` in `fr`. Defaults to `false`.
+   *
+   * @example
+   * faker.date.weekday() // 'Monday'
+   * faker.date.weekday({ abbreviated: true }) // 'Thu'
+   * faker.date.weekday({ context: true }) // 'Thursday'
+   * faker.date.weekday({ abbreviated: true, context: true }) // 'Fri'
+   *
+   * @since 3.0.1
+   */
+  weekday(options?: {
+    /**
+     * Whether to return an abbreviation.
+     *
+     * @default false
+     */
+    abbreviated?: boolean;
+    /**
+     * Whether to return the day of the week in the context of a date.
+     *
+     * In the default `en` locale this has no effect,
+     * however, in other locales like `fr` or `ru`, this may affect grammar or capitalization,
+     * for example `'Lundi'` with `{ context: false }` and `'lundi'` with `{ context: true }` in `fr`.
+     *
+     * @default false
+     */
+    context?: boolean;
+  }): string;
+  /**
+   * Returns a random day of the week.
+   *
+   * @param options The optional options to use.
+   * @param options.abbr Deprecated, use `abbreviated` instead.
+   * @param options.abbreviated Whether to return an abbreviation. Defaults to `false`.
    * @param options.context Whether to return the day of the week in the context of a date. In the default `en` locale this has no effect, however, in other locales like `fr` or `ru`, this may affect grammar or capitalization, for example `'Lundi'` with `{ context: false }` and `'lundi'` with `{ context: true }` in `fr`. Defaults to `false`.
    *
    * @example
@@ -867,6 +1036,86 @@ export class DateModule {
    * faker.date.weekday({ abbr: true, context: true }) // 'Fri'
    *
    * @since 3.0.1
+   *
+   * @deprecated Use `faker.date.weekday({ abbreviated, ... })` instead.
+   */
+  weekday(options?: {
+    /**
+     * Whether to return an abbreviation.
+     *
+     * @default false
+     *
+     * @deprecated Use `abbreviated` instead.
+     */
+    abbr?: boolean;
+    /**
+     * Whether to return the day of the week in the context of a date.
+     *
+     * In the default `en` locale this has no effect,
+     * however, in other locales like `fr` or `ru`, this may affect grammar or capitalization,
+     * for example `'Lundi'` with `{ context: false }` and `'lundi'` with `{ context: true }` in `fr`.
+     *
+     * @default false
+     */
+    context?: boolean;
+  }): string;
+  /**
+   * Returns a random day of the week.
+   *
+   * @param options The optional options to use.
+   * @param options.abbr Deprecated, use `abbreviated` instead.
+   * @param options.abbreviated Whether to return an abbreviation. Defaults to `false`.
+   * @param options.context Whether to return the day of the week in the context of a date. In the default `en` locale this has no effect, however, in other locales like `fr` or `ru`, this may affect grammar or capitalization, for example `'Lundi'` with `{ context: false }` and `'lundi'` with `{ context: true }` in `fr`. Defaults to `false`.
+   *
+   * @example
+   * faker.date.weekday() // 'Monday'
+   * faker.date.weekday({ abbreviated: true }) // 'Thu'
+   * faker.date.weekday({ context: true }) // 'Thursday'
+   * faker.date.weekday({ abbreviated: true, context: true }) // 'Fri'
+   *
+   * @since 3.0.1
+   */
+  weekday(options?: {
+    /**
+     * Whether to return an abbreviation.
+     *
+     * @default false
+     *
+     * @deprecated Use `abbreviated` instead.
+     */
+    abbr?: boolean;
+    /**
+     * Whether to return an abbreviation.
+     *
+     * @default false
+     */
+    abbreviated?: boolean;
+    /**
+     * Whether to return the day of the week in the context of a date.
+     *
+     * In the default `en` locale this has no effect,
+     * however, in other locales like `fr` or `ru`, this may affect grammar or capitalization,
+     * for example `'Lundi'` with `{ context: false }` and `'lundi'` with `{ context: true }` in `fr`.
+     *
+     * @default false
+     */
+    context?: boolean;
+  }): string;
+  /**
+   * Returns a random day of the week.
+   *
+   * @param options The optional options to use.
+   * @param options.abbr Deprecated, use `abbreviated` instead.
+   * @param options.abbreviated Whether to return an abbreviation. Defaults to `false`.
+   * @param options.context Whether to return the day of the week in the context of a date. In the default `en` locale this has no effect, however, in other locales like `fr` or `ru`, this may affect grammar or capitalization, for example `'Lundi'` with `{ context: false }` and `'lundi'` with `{ context: true }` in `fr`. Defaults to `false`.
+   *
+   * @example
+   * faker.date.weekday() // 'Monday'
+   * faker.date.weekday({ abbreviated: true }) // 'Thu'
+   * faker.date.weekday({ context: true }) // 'Thursday'
+   * faker.date.weekday({ abbreviated: true, context: true }) // 'Fri'
+   *
+   * @since 3.0.1
    */
   weekday(
     options: {
@@ -874,9 +1123,17 @@ export class DateModule {
        * Whether to return an abbreviation.
        *
        * @default false
+       *
+       * @deprecated Use `abbreviated` instead.
        */
       abbr?: boolean;
       /**
+       * Whether to return an abbreviation.
+       *
+       * @default false
+       */
+      abbreviated?: boolean;
+      /**
        * Whether to return the day of the week in the context of a date.
        *
        * In the default `en` locale this has no effect,
@@ -888,11 +1145,25 @@ export class DateModule {
       context?: boolean;
     } = {}
   ): string {
-    const { abbr = false, context = false } = options;
+    const {
+      // eslint-disable-next-line deprecation/deprecation
+      abbr,
+      abbreviated = abbr ?? false,
+      context = false,
+    } = options;
+
+    if (abbr != null) {
+      deprecated({
+        deprecated: 'faker.date.weekday({ abbr })',
+        proposed: 'faker.date.weekday({ abbreviated })',
+        since: '8.0',
+        until: '9.0',
+      });
+    }
 
     const source = this.faker.definitions.date.weekday;
     let type: keyof DateEntryDefinition;
-    if (abbr) {
+    if (abbreviated) {
       if (context && source['abbr_context'] != null) {
         type = 'abbr_context';
       } else {
diff --git a/test/__snapshots__/date.spec.ts.snap b/test/__snapshots__/date.spec.ts.snap
index ca3b518b..a42c8786 100644
--- a/test/__snapshots__/date.spec.ts.snap
+++ b/test/__snapshots__/date.spec.ts.snap
@@ -83,9 +83,9 @@ exports[`date > 42 > future > with value 1`] = `2024-11-19T18:52:06.785Z`;
 
 exports[`date > 42 > month > noArgs 1`] = `"May"`;
 
-exports[`date > 42 > month > with abbr = true 1`] = `"May"`;
+exports[`date > 42 > month > with abbreviated = true 1`] = `"May"`;
 
-exports[`date > 42 > month > with abbr = true and context = true 1`] = `"May"`;
+exports[`date > 42 > month > with abbreviated = true and context = true 1`] = `"May"`;
 
 exports[`date > 42 > month > with context = true 1`] = `"May"`;
 
@@ -115,9 +115,9 @@ exports[`date > 42 > soon > with value 1`] = `2021-02-25T11:02:38.995Z`;
 
 exports[`date > 42 > weekday > noArgs 1`] = `"Tuesday"`;
 
-exports[`date > 42 > weekday > with abbr = true 1`] = `"Tue"`;
+exports[`date > 42 > weekday > with abbreviated = true 1`] = `"Tue"`;
 
-exports[`date > 42 > weekday > with abbr = true and context = true 1`] = `"Tue"`;
+exports[`date > 42 > weekday > with abbreviated = true and context = true 1`] = `"Tue"`;
 
 exports[`date > 42 > weekday > with context = true 1`] = `"Tuesday"`;
 
@@ -205,9 +205,9 @@ exports[`date > 1211 > future > with value 1`] = `2030-06-03T19:31:11.467Z`;
 
 exports[`date > 1211 > month > noArgs 1`] = `"December"`;
 
-exports[`date > 1211 > month > with abbr = true 1`] = `"Dec"`;
+exports[`date > 1211 > month > with abbreviated = true 1`] = `"Dec"`;
 
-exports[`date > 1211 > month > with abbr = true and context = true 1`] = `"Dec"`;
+exports[`date > 1211 > month > with abbreviated = true and context = true 1`] = `"Dec"`;
 
 exports[`date > 1211 > month > with context = true 1`] = `"December"`;
 
@@ -237,9 +237,9 @@ exports[`date > 1211 > soon > with value 1`] = `2021-03-02T23:59:57.196Z`;
 
 exports[`date > 1211 > weekday > noArgs 1`] = `"Saturday"`;
 
-exports[`date > 1211 > weekday > with abbr = true 1`] = `"Sat"`;
+exports[`date > 1211 > weekday > with abbreviated = true 1`] = `"Sat"`;
 
-exports[`date > 1211 > weekday > with abbr = true and context = true 1`] = `"Sat"`;
+exports[`date > 1211 > weekday > with abbreviated = true and context = true 1`] = `"Sat"`;
 
 exports[`date > 1211 > weekday > with context = true 1`] = `"Saturday"`;
 
@@ -325,9 +325,9 @@ exports[`date > 1337 > future > with value 1`] = `2023-10-06T02:30:58.333Z`;
 
 exports[`date > 1337 > month > noArgs 1`] = `"April"`;
 
-exports[`date > 1337 > month > with abbr = true 1`] = `"Apr"`;
+exports[`date > 1337 > month > with abbreviated = true 1`] = `"Apr"`;
 
-exports[`date > 1337 > month > with abbr = true and context = true 1`] = `"Apr"`;
+exports[`date > 1337 > month > with abbreviated = true and context = true 1`] = `"Apr"`;
 
 exports[`date > 1337 > month > with context = true 1`] = `"April"`;
 
@@ -357,9 +357,9 @@ exports[`date > 1337 > soon > with value 1`] = `2021-02-24T08:02:25.769Z`;
 
 exports[`date > 1337 > weekday > noArgs 1`] = `"Monday"`;
 
-exports[`date > 1337 > weekday > with abbr = true 1`] = `"Mon"`;
+exports[`date > 1337 > weekday > with abbreviated = true 1`] = `"Mon"`;
 
-exports[`date > 1337 > weekday > with abbr = true and context = true 1`] = `"Mon"`;
+exports[`date > 1337 > weekday > with abbreviated = true and context = true 1`] = `"Mon"`;
 
 exports[`date > 1337 > weekday > with context = true 1`] = `"Monday"`;
 
diff --git a/test/date.spec.ts b/test/date.spec.ts
index 7ed18f47..bfa01e7d 100644
--- a/test/date.spec.ts
+++ b/test/date.spec.ts
@@ -42,10 +42,10 @@ describe('date', () => {
       'month'
     )((t) => {
       t.it('noArgs')
-        .it('with abbr = true', { abbr: true })
+        .it('with abbreviated = true', { abbreviated: true })
         .it('with context = true', { context: true })
-        .it('with abbr = true and context = true', {
-          abbr: true,
+        .it('with abbreviated = true and context = true', {
+          abbreviated: true,
           context: true,
         });
     });
@@ -444,12 +444,26 @@ describe('date', () => {
           expect(faker.definitions.date.month.abbr).toContain(month);
         });
 
+        it('should return random value from date.month.abbr array for abbreviated option', () => {
+          const month = faker.date.month({ abbreviated: true });
+          expect(faker.definitions.date.month.abbr).toContain(month);
+        });
+
         it('should return random value from date.month.abbr_context array for abbr and context option', () => {
           // Use a locale (e.g. az) which has a wide_context array
           const month = fakerAZ.date.month({ abbr: true, context: true });
           expect(fakerAZ.definitions.date.month.abbr_context).toContain(month);
         });
 
+        it('should return random value from date.month.abbr_context array for abbreviated and context option', () => {
+          // Use a locale (e.g. az) which has a wide_context array
+          const month = fakerAZ.date.month({
+            abbreviated: true,
+            context: true,
+          });
+          expect(fakerAZ.definitions.date.month.abbr_context).toContain(month);
+        });
+
         it('should return random value from date.month.wide array for context option when date.month.wide_context array is missing', () => {
           // Use a locale (e.g. the default en) which has no wide_context array
           const month = faker.date.month({ context: true });
@@ -461,6 +475,12 @@ describe('date', () => {
           const month = faker.date.month({ abbr: true, context: true });
           expect(faker.definitions.date.month.abbr).toContain(month);
         });
+
+        it('should return random value from date.month.abbr array for abbreviated and context option when date.month.abbr_context array is missing', () => {
+          // Use a locale (e.g. the default en) which has no abbr_context array
+          const month = faker.date.month({ abbreviated: true, context: true });
+          expect(faker.definitions.date.month.abbr).toContain(month);
+        });
       });
 
       describe('weekday()', () => {
@@ -482,6 +502,11 @@ describe('date', () => {
           expect(faker.definitions.date.weekday.abbr).toContain(weekday);
         });
 
+        it('should return random value from date.weekday.abbr array for abbreviated option', () => {
+          const weekday = faker.date.weekday({ abbreviated: true });
+          expect(faker.definitions.date.weekday.abbr).toContain(weekday);
+        });
+
         it('should return random value from date.weekday.abbr_context array for abbr and context option', () => {
           // Use a locale (e.g. az) which has a abbr_context array
           const weekday = fakerAZ.date.weekday({ abbr: true, context: true });
@@ -490,6 +515,17 @@ describe('date', () => {
           );
         });
 
+        it('should return random value from date.weekday.abbr_context array for abbreviated and context option', () => {
+          // Use a locale (e.g. az) which has a abbr_context array
+          const weekday = fakerAZ.date.weekday({
+            abbreviated: true,
+            context: true,
+          });
+          expect(fakerAZ.definitions.date.weekday.abbr_context).toContain(
+            weekday
+          );
+        });
+
         it('should return random value from date.weekday.wide array for context option when date.weekday.wide_context array is missing', () => {
           // Use a locale (e.g. the default en) which has no wide_context array
           const weekday = faker.date.weekday({ context: true });
@@ -501,6 +537,15 @@ describe('date', () => {
           const weekday = faker.date.weekday({ abbr: true, context: true });
           expect(faker.definitions.date.weekday.abbr).toContain(weekday);
         });
+
+        it('should return random value from date.weekday.abbr array for abbreviated and context option when date.weekday.abbr_context array is missing', () => {
+          // Use a locale (e.g. the default en) which has no abbr_context array
+          const weekday = faker.date.weekday({
+            abbreviated: true,
+            context: true,
+          });
+          expect(faker.definitions.date.weekday.abbr).toContain(weekday);
+        });
       });
 
       describe('birthdate', () => {