path: root/src/modules/datatype/index.ts

import type { Faker } from '../..';
import { deprecated } from '../../internal/deprecated';

/**
 * Module to generate various primitive values and data types.
 *
 * ### Overview
 *
 * Most of the methods in this module are deprecated and have been moved to other modules like [`faker.number`](https://next.fakerjs.dev/api/number.html) and [`faker.string`](https://next.fakerjs.dev/api/string.html), see individual entries for replacements.
 *
 * For a simple random true or false value, use [`boolean()`](https://next.fakerjs.dev/api/datatype.html#boolean).
 */
export class DatatypeModule {
  constructor(private readonly faker: Faker) {
    // Bind `this` so namespaced is working correctly
    for (const name of Object.getOwnPropertyNames(
      DatatypeModule.prototype
    ) as Array<keyof DatatypeModule | 'constructor'>) {
      if (name === 'constructor' || typeof this[name] !== 'function') {
        continue;
      }

      this[name] = this[name].bind(this);
    }
  }

  /**
   * Returns a single random number between zero and the given max value or the given range with the specified precision.
   * The bounds are inclusive.
   *
   * @param options Maximum value or options object.
   * @param options.min Lower bound for generated number. Defaults to `0`.
   * @param options.max Upper bound for generated number. Defaults to `min + 99999`.
   * @param options.precision Precision of the generated number. Defaults to `1`.
   *
   * @throws When options define `max < min`.
   *
   * @see faker.number.int() for the default precision of `1`
   * @see faker.number.float() for a custom precision
   *
   * @example
   * faker.datatype.number() // 55422
   * faker.datatype.number(100) // 52
   * faker.datatype.number({ min: 1000000 }) // 1031433
   * faker.datatype.number({ max: 100 }) // 42
   * faker.datatype.number({ precision: 0.01 }) // 64246.18
   * faker.datatype.number({ min: 10, max: 100, precision: 0.01 }) // 36.94
   *
   * @since 5.5.0
   *
   * @deprecated Use `faker.number.int()` or `faker.number.float()` instead.
   */
  number(
    options:
      | number
      | {
          /**
           * Lower bound for generated number.
           *
           * @default 0
           */
          min?: number;
          /**
           * Upper bound for generated number.
           *
           * @default min + 99999
           */
          max?: number;
          /**
           * Precision of the generated number.
           *
           * @default 1
           */
          precision?: number;
        } = 99999
  ): number {
    deprecated({
      deprecated: 'faker.datatype.number()',
      proposed: 'faker.number.int()',
      since: '8.0',
      until: '9.0',
    });

    if (typeof options === 'number') {
      options = { max: options };
    }

    const { min = 0, max = min + 99999, precision = 1 } = options;

    return this.faker.number.float({ min, max, precision });
  }

  /**
   * Returns a single random floating-point number for the given precision or range and precision.
   *
   * @param options Precision or options object.
   * @param options.min Lower bound for generated number. Defaults to `0`.
   * @param options.max Upper bound for generated number. Defaults to `min + 99999`.
   * @param options.precision Precision of the generated number. Defaults to `0.01`.
   *
   * @see faker.number.float()
   *
   * @example
   * faker.datatype.float() // 51696.36
   * faker.datatype.float(0.1) // 52023.2
   * faker.datatype.float({ min: 1000000 }) // 212859.76
   * faker.datatype.float({ max: 100 }) // 28.11
   * faker.datatype.float({ precision: 0.1 }) // 84055.3
   * faker.datatype.float({ min: 10, max: 100, precision: 0.001 }) // 57.315
   *
   * @since 5.5.0
   *
   * @deprecated Use `faker.number.float()` instead.
   */
  float(
    options:
      | number
      | {
          /**
           * Lower bound for generated number.
           *
           * @default 0
           */
          min?: number;
          /**
           * Upper bound for generated number.
           *
           * @default min + 99999
           */
          max?: number;
          /**
           * Precision of the generated number.
           *
           * @default 0.01
           */
          precision?: number;
        } = {}
  ): number {
    deprecated({
      deprecated: 'faker.datatype.float()',
      proposed: 'faker.number.float()',
      since: '8.0',
      until: '9.0',
    });

    if (typeof options === 'number') {
      options = {
        precision: options,
      };
    }

    const { min = 0, max = min + 99999, precision = 0.01 } = options;

    return this.faker.number.float({ min, max, precision });
  }

  /**
   * Returns a Date object using a random number of milliseconds since
   * the [Unix Epoch](https://en.wikipedia.org/wiki/Unix_time) (1 January 1970 UTC).
   *
   * @param options Max number of milliseconds since unix epoch or options object.
   * @param options.min Lower bound for milliseconds since base date.
   *    When not provided or smaller than `-8640000000000000`, `1990-01-01` is considered
   *    as minimum generated date. Defaults to `631152000000`.
   * @param options.max Upper bound for milliseconds since base date.
   *    When not provided or larger than `8640000000000000`, `2100-01-01` is considered
   *    as maximum generated date. Defaults to `4102444800000`.
   *
   * @see faker.date.anytime()
   * @see faker.date.between()
   *
   * @example
   * faker.datatype.datetime() // '2089-04-17T18:03:24.956Z'
   * faker.datatype.datetime(1893456000000) // '2022-03-28T07:00:56.876Z'
   * faker.datatype.datetime({ min: 1577836800000, max: 1893456000000 }) // '2021-09-12T07:13:00.255Z'
   *
   * @since 5.5.0
   *
   * @deprecated Use `faker.date.between({ from: min, to: max })` or `faker.date.anytime()` instead.
   */
  datetime(
    options:
      | number
      | {
          /**
           * Lower bound for milliseconds since base date.
           *
           * When not provided or smaller than `-8640000000000000`, `1990-01-01` is considered as minimum generated date.
           *
           * @default 631152000000
           */
          min?: number;
          /**
           * Upper bound for milliseconds since base date.
           *
           * When not provided or larger than `8640000000000000`, `2100-01-01` is considered as maximum generated date.
           *
           * @default 4102444800000
           */
          max?: number;
        } = {}
  ): Date {
    deprecated({
      deprecated: 'faker.datatype.datetime({ min, max })',
      proposed: 'faker.date.between({ from, to }) or faker.date.anytime()',
      since: '8.0',
      until: '9.0',
    });

    const minMax = 8640000000000000;

    let min = typeof options === 'number' ? undefined : options.min;
    let max = typeof options === 'number' ? options : options.max;

    if (min == null || min < minMax * -1) {
      min = Date.UTC(1990, 0);
    }

    if (max == null || max > minMax) {
      max = Date.UTC(2100, 0);
    }

    return this.faker.date.between({ from: min, to: max });
  }

  /**
   * Returns a string containing UTF-16 chars between 33 and 125 (`!` to `}`).
   *
   * @param options Length of the generated string or an options object. Defaults to `{}`.
   * @param options.length Length of the generated string. Max length is `2^20`. Defaults to `10`.
   *
   * @see faker.string.sample()
   *
   * @example
   * faker.datatype.string() // 'Zo!.:*e>wR'
   * faker.datatype.string(5) // '6Bye8'
   * faker.datatype.string({ length: 7 }) // 'dzOT00e'
   *
   * @since 5.5.0
   *
   * @deprecated Use `faker.string.sample()` instead.
   */
  string(
    options:
      | number
      | {
          /**
           * Length of the generated string. Max length is `2^20`.
           *
           * @default 10
           */
          length?: number;
        } = {}
  ): string {
    deprecated({
      deprecated: 'faker.datatype.string()',
      proposed: 'faker.string.sample()',
      since: '8.0',
      until: '9.0',
    });
    if (typeof options === 'number') {
      options = { length: options };
    }

    const { length = 10 } = options;

    return this.faker.string.sample(length);
  }

  /**
   * Returns a UUID v4 ([Universally Unique Identifier](https://en.wikipedia.org/wiki/Universally_unique_identifier)).
   *
   * @see faker.string.uuid()
   *
   * @example
   * faker.datatype.uuid() // '4136cd0b-d90b-4af7-b485-5d1ded8db252'
   *
   * @since 5.5.0
   *
   * @deprecated Use `faker.string.uuid()` instead.
   */
  uuid(): string {
    deprecated({
      deprecated: 'faker.datatype.uuid()',
      proposed: 'faker.string.uuid()',
      since: '8.0',
      until: '9.0',
    });
    return this.faker.string.uuid();
  }

  /**
   * Returns the boolean value true or false.
   *
   * **Note:**
   * A probability of `0.75` results in `true` being returned `75%` of the calls; likewise `0.3` => `30%`.
   * If the probability is `<= 0.0`, it will always return `false`.
   * If the probability is `>= 1.0`, it will always return `true`.
   * The probability is limited to two decimal places.
   *
   * @param options The optional options object or the probability (`[0.00, 1.00]`) of returning `true`. Defaults to `0.5`.
   * @param options.probability The probability (`[0.00, 1.00]`) of returning `true`. Defaults to `0.5`.
   *
   * @example
   * faker.datatype.boolean() // false
   * faker.datatype.boolean(0.9) // true
   * faker.datatype.boolean({ probability: 0.1 }) // false
   *
   * @since 5.5.0
   */
  boolean(
    options:
      | number
      | {
          /**
           * The probability (`[0.00, 1.00]`) of returning `true`.
           *
           * @default 0.5
           */
          probability?: number;
        } = {}
  ): boolean {
    if (typeof options === 'number') {
      options = {
        probability: options,
      };
    }

    const { probability = 0.5 } = options;
    if (probability <= 0) {
      return false;
    }

    if (probability >= 1) {
      // This check is required to avoid returning false when float() returns 1
      return true;
    }

    return this.faker.number.float() < probability;
  }

  /**
   * Returns a [hexadecimal](https://en.wikipedia.org/wiki/Hexadecimal) number.
   *
   * @param options The optional options object.
   * @param options.length Length of the generated number. Defaults to `1`.
   * @param options.prefix Prefix for the generated number. Defaults to `'0x'`.
   * @param options.case Case of the generated number. Defaults to `'mixed'`.
   *
   * @see faker.string.hexadecimal()
   *
   * @example
   * faker.datatype.hexadecimal() // '0xB'
   * faker.datatype.hexadecimal({ length: 10 }) // '0xaE13d044cB'
   * faker.datatype.hexadecimal({ prefix: '0x' }) // '0xE'
   * faker.datatype.hexadecimal({ case: 'lower' }) // '0xf'
   * faker.datatype.hexadecimal({ length: 10, prefix: '#' }) // '#f12a974eB1'
   * faker.datatype.hexadecimal({ length: 10, case: 'upper' }) // '0xE3F38014FB'
   * faker.datatype.hexadecimal({ prefix: '', case: 'lower' }) // 'd'
   * faker.datatype.hexadecimal({ length: 10, prefix: '0x', case: 'mixed' }) // '0xAdE330a4D1'
   *
   * @since 6.1.2
   *
   * @deprecated Use `faker.string.hexadecimal()` or `faker.number.hex()` instead.
   */
  hexadecimal(
    options: {
      /**
       * Length of the generated number.
       *
       * @default 1
       */
      length?: number;
      /**
       * Prefix for the generated number.
       *
       * @default '0x'
       */
      prefix?: string;
      /**
       * Case of the generated number.
       *
       * @default 'mixed'
       */
      case?: 'lower' | 'upper' | 'mixed';
    } = {}
  ): string {
    deprecated({
      deprecated: 'faker.datatype.hexadecimal()',
      proposed: 'faker.string.hexadecimal() or faker.number.hex()',
      since: '8.0',
      until: '9.0',
    });
    return this.faker.string.hexadecimal({ ...options, casing: options.case });
  }

  /**
   * Returns a string representing JSON object with 7 pre-defined properties.
   *
   * @example
   * faker.datatype.json() // `{"foo":"mxz.v8ISij","bar":29154,"bike":8658,"a":"GxTlw$nuC:","b":40693,"name":"%'<FTou{7X","prop":"X(bd4iT>77"}`
   *
   * @since 5.5.0
   *
   * @deprecated Build your own function to generate complex objects.
   */
  json(): string {
    deprecated({
      deprecated: 'faker.datatype.json()',
      proposed: 'your own function to generate complex objects',
      since: '8.0',
      until: '9.0',
    });

    const properties = ['foo', 'bar', 'bike', 'a', 'b', 'name', 'prop'];
    const returnObject: Record<string, string | number> = {};

    properties.forEach((prop) => {
      returnObject[prop] = this.boolean()
        ? this.faker.string.sample()
        : this.faker.number.int();
    });

    return JSON.stringify(returnObject);
  }

  /**
   * Returns an array with random strings and numbers.
   *
   * @param length Size of the returned array. Defaults to `10`.
   * @param length.min The minimum size of the array.
   * @param length.max The maximum size of the array.
   *
   * @example
   * faker.datatype.array() // [ 94099, 85352, 'Hz%T.C\\l;8', '|#gmtw3otS', '2>:rJ|3$&d', 56864, 'Ss2-p0RXSI', 51084, 2039, 'mNEU[.r0Vf' ]
   * faker.datatype.array(3) // [ 61845, 'SK7H$W3:d*', 'm[%7N8*GVK' ]
   * faker.datatype.array({ min: 3, max: 5 }) // [ 99403, 76924, 42281, "Q'|$&y\\G/9" ]
   *
   * @since 5.5.0
   *
   * @deprecated Use your own function to build complex arrays.
   */
  array(
    length:
      | number
      | {
          /**
           * The minimum size of the array.
           */
          min: number;
          /**
           * The maximum size of the array.
           */
          max: number;
        } = 10
  ): Array<string | number> {
    deprecated({
      deprecated: 'faker.datatype.array()',
      proposed: 'your own function to build complex arrays',
      since: '8.0',
      until: '9.0',
    });

    return this.faker.helpers.multiple(
      () =>
        this.boolean() ? this.faker.string.sample() : this.faker.number.int(),
      { count: length }
    );
  }

  /**
   * Returns a [BigInt](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#bigint_type) number.
   *
   * @param options Maximum value or options object.
   * @param options.min Lower bound for generated bigint. Defaults to `0n`.
   * @param options.max Upper bound for generated bigint. Defaults to `min + 999999999999999n`.
   *
   * @throws When options define `max < min`.
   *
   * @see faker.number.bigInt()
   *
   * @example
   * faker.datatype.bigInt() // 55422n
   * faker.datatype.bigInt(100n) // 52n
   * faker.datatype.bigInt({ min: 1000000n }) // 431433n
   * faker.datatype.bigInt({ max: 100n }) // 42n
   * faker.datatype.bigInt({ min: 10n, max: 100n }) // 36n
   *
   * @since 6.0.0
   *
   * @deprecated Use `faker.number.bigInt()` instead.
   */
  bigInt(
    options?:
      | bigint
      | boolean
      | number
      | string
      | {
          /**
           * Lower bound for generated bigint.
           *
           * @default 0n
           */
          min?: bigint | boolean | number | string;
          /**
           * Upper bound for generated bigint.
           *
           * @default min + 999999999999999n
           */
          max?: bigint | boolean | number | string;
        }
  ): bigint {
    deprecated({
      deprecated: 'faker.datatype.bigInt()',
      proposed: 'faker.number.bigInt()',
      since: '8.0',
      until: '9.0',
    });
    return this.faker.number.bigInt(options);
  }
}