From f54448ff159b228b780700f25b0a5d4c398d08d3 Mon Sep 17 00:00:00 2001 From: Piotr Kuczynski Date: Fri, 28 Jan 2022 19:14:20 +0100 Subject: [PATCH 01/11] chore: fix JSDoc comments in datatype.ts --- src/datatype.ts | 110 +++++++++++++++++++++++++++++++++--------------- 1 file changed, 76 insertions(+), 34 deletions(-) diff --git a/src/datatype.ts b/src/datatype.ts index 7cf280121d3..b3d2bb442f3 100644 --- a/src/datatype.ts +++ b/src/datatype.ts @@ -19,10 +19,20 @@ export class Datatype { } /** - * Returns a single random number based on a max number or range. + * Returns a single random number for the given max value or range and precision. * - * @method faker.datatype.number - * @param options + * @param [options] Maximum value or options object. + * @param [options.min=0] Lower bound for generated number. + * @param [options.max=99999] Upper bound for generated number. + * @param [options.precision=1] Precision of the generated number. + * + * @example + * faker.datatype.number() // 55422 + * faker.datatype.number(100) // 52 + * faker.datatype.number({ min: 1000000 }) // 431433 + * 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 */ number( options?: number | { min?: number; max?: number; precision?: number } @@ -64,10 +74,20 @@ export class Datatype { } /** - * Returns a single random floating-point number based on a max number or range. + * Returns a single random floating-point number for the given precision or range and precision. + * + * @param [options] Precision or options object. + * @param [options.min=0] Lower bound for generated number. + * @param [options.max=99999] Upper bound for generated number. + * @param [options.precision=0.01] Precision of the generated number. * - * @method faker.datatype.float - * @param options + * @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 */ float( options?: number | { min?: number; max?: number; precision?: number } @@ -89,11 +109,17 @@ export class Datatype { } /** - * Returns a Date object using a random number of milliseconds since 1. Jan 1970 UTC - * Caveat: seeding is not working + * 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). * - * @method faker.datatype.datetime - * @param options pass min OR max as number of milliseconds since 1. Jan 1970 UTC + * @param [options] Max number of milliseconds since unix epoch or options object + * @param [options.min=633880849813] Lower bound for milliseconds since base date. + * When not provided or smaller than -8640000000000000, 1990-01-01 is considered + * as minimum generated date. + * @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. + * @param [options.precision] */ datetime( options?: number | { min?: number; max?: number; precision?: number } @@ -121,12 +147,15 @@ export class Datatype { } /** - * Returns a string, containing UTF-16 chars between 33 and 125 ('!' to '}') + * Returns a string containing UTF-16 chars between 33 and 125 ('!' to '}'). + * + * @param [length=10] Length of the generated string. Max length is 2^20. * - * @method faker.datatype.string - * @param length length of generated string, default = 10, max length = 2^20 + * @example + * faker.datatype.string() // 'Zo!.:*e>wR' + * faker.datatype.string(5) // '6Bye8' */ - string(length: number = 10): string { + string(length = 10): string { const maxLength = Math.pow(2, 20); if (length >= maxLength) { length = maxLength; @@ -149,9 +178,10 @@ export class Datatype { } /** - * uuid + * Returns UUID v4 ([Universally Unique Identifier](https://en.wikipedia.org/wiki/Universally_unique_identifier)). * - * @method faker.datatype.uuid + * @example + * faker.datatype.uuid() // '4136cd0b-d90b-4af7-b485-5d1ded8db252' */ uuid(): string { const RFC4122_TEMPLATE = 'xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx'; @@ -164,23 +194,28 @@ export class Datatype { } /** - * boolean + * Returns boolean value true or false. * - * @method faker.datatype.boolean + * @example + * faker.datatype.boolean() // false */ boolean(): boolean { return !!this.faker.datatype.number(1); } /** - * hexaDecimal + * Returns [hexadecimal](https://en.wikipedia.org/wiki/Hexadecimal) number. * - * @method faker.datatype.hexaDecimal - * @param count defaults to 1 + * @param [length=1] Length of the generated number. + * + * @example + * faker.datatype.hexaDecimal() // '0xb' + * faker.datatype.hexaDecimal(10) // '0xaE13F044fb' */ - hexaDecimal(count: number = 1): string { + hexaDecimal(length = 1): string { let wholeString = ''; - for (let i = 0; i < count; i++) { + + for (let i = 0; i < length; i++) { wholeString += this.faker.random.arrayElement([ '0', '1', @@ -211,14 +246,15 @@ export class Datatype { } /** - * Returns json object with 7 pre-defined properties + * Returns string representing JSON object with 7 pre-defined properties. * - * @method faker.datatype.json + * @example + * faker.datatype.json() // `{"foo":"mxz.v8ISij","bar":29154,"bike":8658,"a":"GxTlw$nuC:","b":40693,"name":"%'77"}` */ json(): string { const properties = ['foo', 'bar', 'bike', 'a', 'b', 'name', 'prop']; - const returnObject: Record = {}; + properties.forEach((prop) => { returnObject[prop] = this.faker.datatype.boolean() ? this.faker.datatype.string() @@ -229,13 +265,15 @@ export class Datatype { } /** - * Returns an array with values generated by faker.datatype.number and faker.datatype.string + * Returns array with random strings and numbers. + * + * @param [length=10] Size of the returned array * - * @method faker.datatype.array - * @param length length of the returned 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' ] */ - - array(length: number = 10): Array { + array(length = 10): Array { const returnArray = new Array(length); for (let i = 0; i < length; i++) { returnArray[i] = this.faker.datatype.boolean() @@ -246,10 +284,14 @@ export class Datatype { } /** - * Returns a Big Integer with values generated by faker.datatype.bigInt + * Returns a [BigInt](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#bigint_type) number + * + * @param [value] When provided, this method simply converts it to BigInt type * - * @method faker.datatype.bigInt - * @param value + * @example + * faker.datatype.bigInt() // 8507209999914928n + * faker.datatype.bigInt(30) // 30n + * faker.datatype.bigInt(true) // 1n */ bigInt(value?: string | number | bigint | boolean): bigint { if (value === undefined) { From 538740c34c6a6f4116ac26cdf9822e9943221432 Mon Sep 17 00:00:00 2001 From: Piotr Kuczynski Date: Fri, 28 Jan 2022 19:17:50 +0100 Subject: [PATCH 02/11] dots --- src/datatype.ts | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/src/datatype.ts b/src/datatype.ts index b3d2bb442f3..c7c43ef8cbe 100644 --- a/src/datatype.ts +++ b/src/datatype.ts @@ -267,7 +267,7 @@ export class Datatype { /** * Returns array with random strings and numbers. * - * @param [length=10] Size of the returned array + * @param [length=10] Size of the returned array. * * @example * faker.datatype.array() // [ 94099, 85352, 'Hz%T.C\\l;8', '|#gmtw3otS', '2>:rJ|3$&d', 56864, 'Ss2-p0RXSI', 51084, 2039, 'mNEU[.r0Vf' ] @@ -284,9 +284,9 @@ export class Datatype { } /** - * Returns a [BigInt](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#bigint_type) number + * Returns a [BigInt](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#bigint_type) number. * - * @param [value] When provided, this method simply converts it to BigInt type + * @param [value] When provided, this method simply converts it to BigInt type. * * @example * faker.datatype.bigInt() // 8507209999914928n From 30c5d61f01cb125a36d7b92b8f27c85a2f8b0469 Mon Sep 17 00:00:00 2001 From: Piotr Kuczynski Date: Fri, 28 Jan 2022 19:27:51 +0100 Subject: [PATCH 03/11] More examples --- src/datatype.ts | 2 ++ 1 file changed, 2 insertions(+) diff --git a/src/datatype.ts b/src/datatype.ts index c7c43ef8cbe..edc91a021ad 100644 --- a/src/datatype.ts +++ b/src/datatype.ts @@ -290,7 +290,9 @@ export class Datatype { * * @example * faker.datatype.bigInt() // 8507209999914928n + * faker.datatype.bigInt('156') // 156n * faker.datatype.bigInt(30) // 30n + * faker.datatype.bigInt(3000n) // 3000n * faker.datatype.bigInt(true) // 1n */ bigInt(value?: string | number | bigint | boolean): bigint { From 9ae2dbf8ab6aaed590412b76640854c5c087e2dd Mon Sep 17 00:00:00 2001 From: Piotr Kuczynski Date: Tue, 1 Feb 2022 18:33:41 +0100 Subject: [PATCH 04/11] Update src/datatype.ts Co-authored-by: ST-DDT --- src/datatype.ts | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/src/datatype.ts b/src/datatype.ts index 687629b6538..d1ae571be6d 100644 --- a/src/datatype.ts +++ b/src/datatype.ts @@ -19,7 +19,8 @@ export class Datatype { } /** - * Returns a single random number for the given max value or range and precision. + * 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=0] Lower bound for generated number. From 576cab01976bbcf351fc7eeefa91c08b78c55333 Mon Sep 17 00:00:00 2001 From: Piotr Kuczynski Date: Tue, 1 Feb 2022 18:50:33 +0100 Subject: [PATCH 05/11] remove optional --- src/datatype.ts | 37 ++++++++++++++++++------------------- 1 file changed, 18 insertions(+), 19 deletions(-) diff --git a/src/datatype.ts b/src/datatype.ts index 687629b6538..041911fc2b4 100644 --- a/src/datatype.ts +++ b/src/datatype.ts @@ -21,10 +21,10 @@ export class Datatype { /** * Returns a single random number for the given max value or range and precision. * - * @param [options] Maximum value or options object. - * @param [options.min=0] Lower bound for generated number. - * @param [options.max=99999] Upper bound for generated number. - * @param [options.precision=1] Precision of the generated number. + * @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 `99999`. + * @param options.precision Precision of the generated number. Defaults to `1`. * * @example * faker.datatype.number() // 55422 @@ -76,10 +76,10 @@ export class Datatype { /** * Returns a single random floating-point number for the given precision or range and precision. * - * @param [options] Precision or options object. - * @param [options.min=0] Lower bound for generated number. - * @param [options.max=99999] Upper bound for generated number. - * @param [options.precision=0.01] Precision of the generated number. + * @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 `99999`. + * @param options.precision Precision of the generated number. Defaults to `0.01`. * * @example * faker.datatype.float() // 51696.36 @@ -112,14 +112,13 @@ export class Datatype { * 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=633880849813] Lower bound for milliseconds since base date. - * When not provided or smaller than -8640000000000000, 1990-01-01 is considered - * as minimum generated date. - * @param [options.max] Upper bound for milliseconds since base date. - * When not provided or larger than 8640000000000000, 2100-01-01 is considered + * @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 `633880849813`. + * @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. - * @param [options.precision] */ datetime(options?: number | { min?: number; max?: number }): Date { const minMax = 8640000000000000; @@ -141,7 +140,7 @@ export class Datatype { /** * Returns a string containing UTF-16 chars between 33 and 125 ('!' to '}'). * - * @param [length=10] Length of the generated string. Max length is 2^20. + * @param length Length of the generated string. Max length is `2^20`. Defaults to `10`. * * @example * faker.datatype.string() // 'Zo!.:*e>wR' @@ -198,7 +197,7 @@ export class Datatype { /** * Returns [hexadecimal](https://en.wikipedia.org/wiki/Hexadecimal) number. * - * @param [length=1] Length of the generated number. + * @param length Length of the generated number. Defaults to `1`. * * @example * faker.datatype.hexaDecimal() // '0xb' @@ -259,7 +258,7 @@ export class Datatype { /** * Returns array with random strings and numbers. * - * @param [length=10] Size of the returned array. + * @param length Size of the returned array. Defaults to `10`. * * @example * faker.datatype.array() // [ 94099, 85352, 'Hz%T.C\\l;8', '|#gmtw3otS', '2>:rJ|3$&d', 56864, 'Ss2-p0RXSI', 51084, 2039, 'mNEU[.r0Vf' ] @@ -278,7 +277,7 @@ export class Datatype { /** * Returns a [BigInt](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#bigint_type) number. * - * @param [value] When provided, this method simply converts it to BigInt type. + * @param value When provided, this method simply converts it to `BigInt` type. * * @example * faker.datatype.bigInt() // 8507209999914928n From 521cb050f42eefd2249c49d6d736899b1734e0ad Mon Sep 17 00:00:00 2001 From: Piotr Kuczynski Date: Tue, 1 Feb 2022 21:55:37 +0100 Subject: [PATCH 06/11] Update src/datatype.ts Co-authored-by: ST-DDT --- src/datatype.ts | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/datatype.ts b/src/datatype.ts index 02855e5b25e..e2e13fba193 100644 --- a/src/datatype.ts +++ b/src/datatype.ts @@ -77,7 +77,7 @@ export class Datatype { /** * Returns a single random floating-point number for the given precision or range and precision. * - * @param options] Precision or options object. + * @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 `99999`. * @param options.precision Precision of the generated number. Defaults to `0.01`. From b5ea6e729501a064c10a3995c40cfb8af37d30c4 Mon Sep 17 00:00:00 2001 From: Piotr Kuczynski Date: Tue, 1 Feb 2022 21:55:53 +0100 Subject: [PATCH 07/11] Update src/datatype.ts Co-authored-by: ST-DDT --- src/datatype.ts | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/datatype.ts b/src/datatype.ts index e2e13fba193..dcd51a3077a 100644 --- a/src/datatype.ts +++ b/src/datatype.ts @@ -170,7 +170,7 @@ export class Datatype { } /** - * Returns UUID v4 ([Universally Unique Identifier](https://en.wikipedia.org/wiki/Universally_unique_identifier)). + * Returns a UUID v4 ([Universally Unique Identifier](https://en.wikipedia.org/wiki/Universally_unique_identifier)). * * @example * faker.datatype.uuid() // '4136cd0b-d90b-4af7-b485-5d1ded8db252' From 03b80d579658e5c5cf3dd8aef072ed712640687a Mon Sep 17 00:00:00 2001 From: Piotr Kuczynski Date: Tue, 1 Feb 2022 21:56:12 +0100 Subject: [PATCH 08/11] Update src/datatype.ts Co-authored-by: ST-DDT --- src/datatype.ts | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/datatype.ts b/src/datatype.ts index dcd51a3077a..06c7d7fbbdf 100644 --- a/src/datatype.ts +++ b/src/datatype.ts @@ -186,7 +186,7 @@ export class Datatype { } /** - * Returns boolean value true or false. + * Returns the boolean value true or false. * * @example * faker.datatype.boolean() // false From dd79deafed90cd9f12c7d9443a3ee5257e5b38bc Mon Sep 17 00:00:00 2001 From: Piotr Kuczynski Date: Tue, 1 Feb 2022 21:56:22 +0100 Subject: [PATCH 09/11] Update src/datatype.ts Co-authored-by: ST-DDT --- src/datatype.ts | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/datatype.ts b/src/datatype.ts index 06c7d7fbbdf..2048722c10c 100644 --- a/src/datatype.ts +++ b/src/datatype.ts @@ -238,7 +238,7 @@ export class Datatype { } /** - * Returns string representing JSON object with 7 pre-defined properties. + * 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":"%'77"}` From d3156711b0f7f555c0b5d71ef60702cfbb62d1dd Mon Sep 17 00:00:00 2001 From: Piotr Kuczynski Date: Tue, 1 Feb 2022 21:56:29 +0100 Subject: [PATCH 10/11] Update src/datatype.ts Co-authored-by: ST-DDT --- src/datatype.ts | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/datatype.ts b/src/datatype.ts index 2048722c10c..2c5ba77da6a 100644 --- a/src/datatype.ts +++ b/src/datatype.ts @@ -257,7 +257,7 @@ export class Datatype { } /** - * Returns array with random strings and numbers. + * Returns an array with random strings and numbers. * * @param length Size of the returned array. Defaults to `10`. * From 02153d731a10cb8b0f0fee068e208947bcf9ca1e Mon Sep 17 00:00:00 2001 From: Piotr Kuczynski Date: Tue, 1 Feb 2022 21:56:38 +0100 Subject: [PATCH 11/11] Update src/datatype.ts Co-authored-by: ST-DDT --- src/datatype.ts | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/datatype.ts b/src/datatype.ts index 2c5ba77da6a..2fbc5c6b7ec 100644 --- a/src/datatype.ts +++ b/src/datatype.ts @@ -196,7 +196,7 @@ export class Datatype { } /** - * Returns [hexadecimal](https://en.wikipedia.org/wiki/Hexadecimal) number. + * Returns a [hexadecimal](https://en.wikipedia.org/wiki/Hexadecimal) number. * * @param length Length of the generated number. Defaults to `1`. *