Standardize function parameters and defaults

[ST-DDT]

Clear and concise description of the problem

Most methods have various ways to specify parameters and have different defaults.

Suggested solution

All methods should be checked that they have:

• consistent parameter definitions
• consistent parameter names
• consistent parameter defaults

The consistency should span across all modules.

Alternative

No response

Additional context

No response

[ST-DDT]

Blocked by #1346

[ST-DDT]

• string.hexadecimal doesn't support length without options
• string.sample doesn't support options

[Shinigami92]

• Merge sentences options https://github.com/faker-js/faker/pull/1486/files#diff-6a52f070da035438588918337a536421fd92d4d78ef4998bf140f6fd925b8974R140-R143

[Shinigami92]

• date doesn't support options

[xDivisionByZerox]

Is the LoremModule already considered "standardized"?
All functions already have an object argument, but with a more descriptive name than our standard "options".
For Example:

faker/src/modules/lorem/index.ts

Lines 106 to 119 in fccd641

	words(
	wordCount:
	| number
	| {
	/**
	* The minimum number of words to generate.
	*/
	min: number;
	/**
	* The maximum number of words to generate.
	*/
	max: number;
	} = 3
	): string {

I'm not sure what to do here.

[matthewmayer]

I was going to add a section to the migration guide about these changes, but to clarify is it intended that the non-options-object parameters will be deprecated in v8 and removed in v9? Or will both versions be supported in v8+?

[xDivisionByZerox]

TLDR;

So yes, some of the signatures will be deprecated in v8 and removed in v9. So they are usable for v8.x. But most of them simply get standardized into an options object and can be used even after v9.

---

[...] to clarify is it intended that the non-options-object parameters will be deprecated in v8 and removed in v9

No, not entirely. Primitive arguments are often desired for configuring the parameter which is most likely to be used the most by users. For example:

faker.number.int(10); // number between 0 and 10
faker.number.int({ max: 10 }); // number between 0 and 10
faker.number.int({ max: 10, min: 10 }); // number between 0 and 10

As you can see, all functions do exactly the same, but the biggest use-case for int is most likely to get a number between 0 and x. It would hurt the DX to require an options object altho you only want to change the max option.

The downside of primitives is that they are hard to maintain. You can extend signatures by always adding an additional parameter at the end (example faker.number.int(min, max, steps, format, foo, bar)). But as soon as you need to change or remove one of them it gets awkward. Thats why we decided that each function signature essentially should follow this pattern:

1. Function has no arguments
2. Function has object argument (typically named options)
3. Function can have overload with options argument OR at most one primitive argument
4. Exceptions may apply (helpers most likely)

[ST-DDT]

Team Decision

We will rewrite the lorem methods to support options.
The range object support that was added in the alpha will be removed and will only be available from inside the options object.

[Shinigami92]

It seems we have tackled all needed changes. If we want to change something additionally, we should open issues/PRs specifically.