Merge branch 'next' into chore/es-mx-names

LICENSE

@@ -1,4 +1,4 @@
-Faker - Copyright (c) 2022
+Faker - Copyright (c) 2022-2023
 
 This software consists of voluntary contributions made by many individuals.
 For exact contribution history, see the revision history

src/internal/mersenne/twister.ts

@@ -1,5 +1,5 @@
 /**
- * Copyright (c) 2022 Faker
+ * Copyright (c) 2022-2023 Faker
  *
  * This is a version of the original source code migrated to TypeScript and
  * modified by the Faker team.

src/locales/en/company/bs_noun.ts

@@ -1,6 +1,5 @@
 export default [
   'synergies',
-  'web-readiness',
   'paradigms',
   'markets',
   'partnerships',
@@ -12,14 +11,11 @@ export default [
   'communities',
   'ROI',
   'solutions',
-  'e-tailers',
-  'e-services',
   'action-items',
   'portals',
   'niches',
   'technologies',
   'content',
-  'vortals',
   'supply-chains',
   'convergence',
   'relationships',
@@ -29,7 +25,6 @@ export default [
   'e-commerce',
   'systems',
   'bandwidth',
-  'infomediaries',
   'models',
   'mindshare',
   'deliverables',
@@ -44,4 +39,5 @@ export default [
   'web services',
   'methodologies',
   'blockchains',
+  'lifetime value',
 ];

src/modules/helpers/index.ts

@@ -459,6 +459,55 @@ export class HelpersModule {
     return array[index];
   }
 
+  /**
+   * Returns a weighted random element from the given array. Each element of the array should be an object with two keys `weight` and `value`.
+   *
+   * - Each `weight` key should be a number representing the probability of selecting the value, relative to the sum of the weights. Weights can be any positive float or integer.
+   * - Each `value` key should be the corresponding value.
+   *
+   * For example, if there are two values A and B, with weights 1 and 2 respectively, then the probability of picking A is 1/3 and the probability of picking B is 2/3.
+   *
+   * @template T The type of the entries to pick from.
+   * @param array Array to pick the value from.
+   *
+   * @example
+   * faker.helpers.weightedArrayElement([{ weight: 5, value: 'sunny' }, { weight: 4, value: 'rainy' }, { weight: 1, value: 'snowy' }]) // 'sunny', 50% of the time, 'rainy' 40% of the time, 'snowy' 10% of the time
+   *
+   * @since 8.0.0
+   */
+  weightedArrayElement<T>(
+    array: ReadonlyArray<{ weight: number; value: T }>
+  ): T {
+    if (array.length === 0) {
+      throw new FakerError(
+        'weightedArrayElement expects an array with at least one element'
+      );
+    }
+
+    if (!array.every((elt) => elt.weight > 0)) {
+      throw new FakerError(
+        'weightedArrayElement expects an array of { weight, value } objects where weight is a positive number'
+      );
+    }
+
+    const total = array.reduce((acc, { weight }) => acc + weight, 0);
+    const random = this.faker.number.float({
+      min: 0,
+      max: total,
+      precision: 1e-9,
+    });
+    let current = 0;
+    for (const { weight, value } of array) {
+      current += weight;
+      if (random < current) {
+        return value;
+      }
+    }
+
+    // In case of rounding errors, return the last element
+    return array[array.length - 1].value;
+  }
+
   /**
    * Returns a subset with random elements of the given array in random order.
    *

src/modules/internet/user-agent.ts

@@ -1,5 +1,5 @@
 /**
- * Copyright (c) 2022 Faker
+ * Copyright (c) 2022-2023 Faker
  *
  * This is a version of the original code migrated to TypeScript and modified
  * by the Faker team.

src/modules/location/index.ts

@@ -1,4 +1,5 @@
 import type { Faker } from '../..';
+import { deprecated } from '../../internal/deprecated';
 
 /**
  * Module to generate addresses and locations.
@@ -368,6 +369,27 @@ export class LocationModule {
     );
   }
 
+  /**
+   * Generates a random GPS coordinate within the specified radius from the given coordinate.
+   *
+   * @param options The options for generating a GPS coordinate.
+   * @param options.origin The original coordinate to get a new coordinate close to.
+   * If no coordinate is given, a random one will be chosen.
+   * @param options.radius The maximum distance from the given coordinate to the new coordinate. Defaults to `10`.
+   * @param options.isMetric If `true` assume the radius to be in kilometers. If `false` for miles. Defaults to `false`.
+   *
+   * @example
+   * faker.location.nearbyGPSCoordinate() // [ 33.8475, -170.5953 ]
+   * faker.location.nearbyGPSCoordinate({ origin: [33, -170] }) // [ 33.0165, -170.0636 ]
+   * faker.location.nearbyGPSCoordinate({ origin: [33, -170], radius: 1000, isMetric: true }) // [ 37.9163, -179.2408 ]
+   *
+   * @since 8.0.0
+   */
+  nearbyGPSCoordinate(options?: {
+    origin?: [latitude: number, longitude: number];
+    radius?: number;
+    isMetric?: boolean;
+  }): [latitude: number, longitude: number];
   /**
    * Generates a random GPS coordinate within the specified radius from the given coordinate.
    *
@@ -382,14 +404,74 @@ export class LocationModule {
    * faker.location.nearbyGPSCoordinate([33, -170], 1000, true) // [ 37.9163, -179.2408 ]
    *
    * @since 8.0.0
+   *
+   * @deprecated Use `faker.location.nearbyGPSCoordinate({ origin, radius, isMetric })` instead.
    */
   nearbyGPSCoordinate(
     coordinate?: [latitude: number, longitude: number],
-    radius: number = 10,
-    isMetric: boolean = false
+    radius?: number,
+    isMetric?: boolean
+  ): [latitude: number, longitude: number];
+  /**
+   * Generates a random GPS coordinate within the specified radius from the given coordinate.
+   *
+   * @param options The options for generating a GPS coordinate.
+   * @param options.origin The original coordinate to get a new coordinate close to.
+   * If no coordinate is given, a random one will be chosen.
+   * @param options.radius The maximum distance from the given coordinate to the new coordinate. Defaults to `10`.
+   * @param options.isMetric If `true` assume the radius to be in kilometers. If `false` for miles. Defaults to `false`.
+   * @param legacyRadius Deprecated, use `options.radius` instead.
+   * @param legacyIsMetric Deprecated, use `options.isMetric` instead.
+   *
+   * @example
+   * faker.location.nearbyGPSCoordinate() // [ 33.8475, -170.5953 ]
+   * faker.location.nearbyGPSCoordinate({ origin: [33, -170] }) // [ 33.0165, -170.0636 ]
+   * faker.location.nearbyGPSCoordinate({ origin: [33, -170], radius: 1000, isMetric: true }) // [ 37.9163, -179.2408 ]
+   *
+   * @since 8.0.0
+   */
+  nearbyGPSCoordinate(
+    options?:
+      | [latitude: number, longitude: number]
+      | {
+          origin?: [latitude: number, longitude: number];
+          radius?: number;
+          isMetric?: boolean;
+        },
+    legacyRadius?: number,
+    legacyIsMetric?: boolean
+  ): [latitude: number, longitude: number];
+  nearbyGPSCoordinate(
+    options:
+      | [latitude: number, longitude: number]
+      | {
+          origin?: [latitude: number, longitude: number];
+          radius?: number;
+          isMetric?: boolean;
+        } = {},
+    legacyRadius: number = 10,
+    legacyIsMetric: boolean = false
   ): [latitude: number, longitude: number] {
-    // If there is no coordinate, the best we can do is return a random GPS coordinate.
-    if (coordinate === undefined) {
+    if (Array.isArray(options)) {
+      deprecated({
+        deprecated:
+          'faker.location.nearbyGPSCoordinate(coordinate, radius, isMetric)',
+        proposed:
+          'faker.location.nearbyGPSCoordinate({ origin, radius, isMetric })',
+        since: '8.0',
+        until: '9.0',
+      });
+      options = { origin: options };
+    }
+
+    const {
+      origin,
+      radius = legacyRadius,
+      isMetric = legacyIsMetric,
+    } = options;
+
+    // If there is no origin, the best we can do is return a random GPS coordinate.
+    if (origin == null) {
       return [this.latitude(), this.longitude()];
     }
 
@@ -414,22 +496,22 @@ export class LocationModule {
 
     const distanceInDegree = distanceInKm / kmPerDegree; // in °
 
-    const newCoordinate: [latitude: number, longitude: number] = [
-      coordinate[0] + Math.sin(angleRadians) * distanceInDegree,
-      coordinate[1] + Math.cos(angleRadians) * distanceInDegree,
+    const coordinate: [latitude: number, longitude: number] = [
+      origin[0] + Math.sin(angleRadians) * distanceInDegree,
+      origin[1] + Math.cos(angleRadians) * distanceInDegree,
     ];
 
     // Box latitude [-90°, 90°]
-    newCoordinate[0] = newCoordinate[0] % 180;
-    if (newCoordinate[0] < -90 || newCoordinate[0] > 90) {
-      newCoordinate[0] = Math.sign(newCoordinate[0]) * 180 - newCoordinate[0];
-      newCoordinate[1] += 180;
+    coordinate[0] = coordinate[0] % 180;
+    if (coordinate[0] < -90 || coordinate[0] > 90) {
+      coordinate[0] = Math.sign(coordinate[0]) * 180 - coordinate[0];
+      coordinate[1] += 180;
     }
 
     // Box longitude [-180°, 180°]
-    newCoordinate[1] = (((newCoordinate[1] % 360) + 540) % 360) - 180;
+    coordinate[1] = (((coordinate[1] % 360) + 540) % 360) - 180;
 
-    return [newCoordinate[0], newCoordinate[1]];
+    return [coordinate[0], coordinate[1]];
   }
 
   /**

test/__snapshots__/company.spec.ts.snap

@@ -1,12 +1,12 @@
 // Vitest Snapshot v1
 
-exports[`company > 42 > bs 1`] = `"seize impactful web services"`;
+exports[`company > 42 > bs 1`] = `"seize impactful methodologies"`;
 
 exports[`company > 42 > bsAdjective 1`] = `"dynamic"`;
 
 exports[`company > 42 > bsBuzz 1`] = `"seize"`;
 
-exports[`company > 42 > bsNoun 1`] = `"portals"`;
+exports[`company > 42 > bsNoun 1`] = `"technologies"`;
 
 exports[`company > 42 > catchPhrase 1`] = `"Implemented responsive throughput"`;
 
@@ -29,13 +29,13 @@ exports[`company > 42 > suffixes 1`] = `
 ]
 `;
 
-exports[`company > 1211 > bs 1`] = `"cultivate bleeding-edge functionalities"`;
+exports[`company > 1211 > bs 1`] = `"cultivate bleeding-edge experiences"`;
 
 exports[`company > 1211 > bsAdjective 1`] = `"plug-and-play"`;
 
 exports[`company > 1211 > bsBuzz 1`] = `"cultivate"`;
 
-exports[`company > 1211 > bsNoun 1`] = `"experiences"`;
+exports[`company > 1211 > bsNoun 1`] = `"methodologies"`;
 
 exports[`company > 1211 > catchPhrase 1`] = `"Up-sized high-level success"`;
 

test/__snapshots__/helpers.spec.ts.snap

@@ -177,6 +177,10 @@ exports[`helpers > 42 > uniqueArray > with array 1`] = `
 ]
 `;
 
+exports[`helpers > 42 > weightedArrayElement > with array 1`] = `"sunny"`;
+
+exports[`helpers > 42 > weightedArrayElement > with array with percentages 1`] = `"sunny"`;
+
 exports[`helpers > 1211 > arrayElement > noArgs 1`] = `"c"`;
 
 exports[`helpers > 1211 > arrayElement > with array 1`] = `"!"`;
@@ -368,6 +372,10 @@ exports[`helpers > 1211 > uniqueArray > with array 1`] = `
 ]
 `;
 
+exports[`helpers > 1211 > weightedArrayElement > with array 1`] = `"snowy"`;
+
+exports[`helpers > 1211 > weightedArrayElement > with array with percentages 1`] = `"snowy"`;
+
 exports[`helpers > 1337 > arrayElement > noArgs 1`] = `"a"`;
 
 exports[`helpers > 1337 > arrayElement > with array 1`] = `"l"`;
@@ -541,3 +549,7 @@ exports[`helpers > 1337 > uniqueArray > with array 1`] = `
   "d",
 ]
 `;
+
+exports[`helpers > 1337 > weightedArrayElement > with array 1`] = `"sunny"`;
+
+exports[`helpers > 1337 > weightedArrayElement > with array with percentages 1`] = `"sunny"`;