Method weightedArrayElement

src/modules/helpers/index.ts:970–1010

* 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 pos

(
    array: ReadonlyArray<{
      /**
       * The weight of the value.
       */
      weight: number;
      /**
       * The value to pick.
       */
      value: T;
    }>
  )

   * @since 8.0.0
   */
  weightedArrayElement<const T>(
    array: ReadonlyArray<{
      /**
       * The weight of the value.
       */
      weight: number;
      /**
       * The value to pick.
       */
      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((sum, { weight }) => sum + weight, 0);
    const random = this.faker.number.float({
      min: 0,
      max: total,
    });
    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
    // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
    return array.at(-1)!.value;
  }

  /**
   * Returns a subset with random elements of the given array in random order.