feat(number): add distributor functions

[ST-DDT]

Implements #1862

• Adding Random probability distribution function #1862

---

Adds a distributor option to faker.number.int and float. The distributor function can be used to influence the distribution of the generated values. E.g. uniformDistributor and exponentialDistributor.

• Preview Distributors
• Preview NumberModule

---

The following table shows the rough distribution of values generated using
exponentialDistributor({ base: x }):

Result	Base 0.1	Base 0.5	Base 1	Base 2	Base 10
0.0 - 0.1	4.1%	7.4%	10.0%	13.8%	27.8%
0.1 - 0.2	4.5%	7.8%	10.0%	12.5%	16.9%
0.2 - 0.3	5.0%	8.2%	10.0%	11.5%	12.1%
0.3 - 0.4	5.7%	8.7%	10.0%	10.7%	9.4%
0.4 - 0.5	6.6%	9.3%	10.0%	10.0%	7.8%
0.5 - 0.6	7.8%	9.9%	10.0%	9.3%	6.6%
0.6 - 0.7	9.4%	10.7%	10.0%	8.8%	5.7%
0.7 - 0.8	12.1%	11.5%	10.0%	8.2%	5.0%
0.8 - 0.9	16.9%	12.6%	10.0%	7.8%	4.5%
0.9 - 1.0	27.9%	13.8%	10.0%	7.5%	4.1%

The exponential distribution is achieved by using base ** exponent where exponent is a random float between 0 and 1.
The result is then stretched evenly to fit to min and max.

[netlify]

✅ Deploy Preview for fakerjs ready!

Name	Link
🔨 Latest commit	2311597
🔍 Latest deploy log	https://app.netlify.com/projects/fakerjs/deploys/69e26ad79cb73b0008b44c30
😎 Deploy Preview	https://deploy-preview-3375.fakerjs.dev
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify project configuration.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 98.90%. Comparing base (bbabc4b) to head (2311597).
⚠️ Report is 1 commits behind head on next.

Additional details and impacted files

@@            Coverage Diff             @@
##             next    #3375      +/-   ##
==========================================
+ Coverage   98.83%   98.90%   +0.06%     
==========================================
  Files         894      896       +2     
  Lines        3086     3100      +14     
  Branches      548      556       +8     
==========================================
+ Hits         3050     3066      +16     
+ Misses         32       30       -2     
  Partials        4        4              

Files with missing lines	Coverage Δ
src/distributors/exponential.ts	100.00% <100.00%> (ø)
src/distributors/uniform.ts	100.00% <100.00%> (ø)
src/modules/number/index.ts	100.00% <100.00%> (ø)

... and 1 file with indirect coverage changes

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[ST-DDT]

I'm also not sure whether exponentialDistribution is the correct name for the function.

[matthewmayer]

I don't like calling it "exponentialDistribution " because you're not returning a distribution, you are returning a single value from that distribution.

So I'd call it exponentialValue or floatExponential or something similar to emphasise the thing that is returned is a float or a value.

[ST-DDT]

you are returning a single value from that distribution.

I'm not even sure that is the case.

So I'd call it exponentialValue or floatExponential or something similar to emphasise the thing that is returned is a float or a value.

Good idea. I'm not finally sure which term I would like to use but stepping away from calling it exponentialDistribution is the correct choice.

I'm currently considering one of these:

• exponential
• exponentialValue
• exponentialNumber
• exponentialFloat
• floatExponential
• exponentiallySpread (or something similar)
• powerLaw___ (<- ChatGpt)

[xDivisionByZerox]

Team decision

The feature will be implemented by extending the already existing methods (number.int(), number.float(), etc). An additional parameter will be added. The parameter will be a function that exepts a randomizer instance and will return a biased randomized value. The return value will be used by the original function to "push" the value in the direction the distribution desires.

We are currently unsure how to name the parameter. While distribution is okay, we are not sure if this is the mathmatical correct term.
The name "spread" was discussed, but discarded since it might confuse users with the JS spread operator.
We will think about other names until the next meeting. If we do not come up with any, the current name of "distribution" is fine for us.

[ST-DDT]

Ready for review.

I changed the implementations to use a distributor parameter.
distributor is close enough to distribution so that you can guess what the option does, without actually running into the mathematical specification.

[Copilot]

Pull request overview

Adds a new “distributor” concept to influence randomness distribution for faker.number.int() / faker.number.float(), and publishes built-in distributor helpers with matching API docs support.

Changes:

• Add distributor option to NumberModule.int() and NumberModule.float() (defaulting to uniform).
• Introduce Distributor type plus uniformDistributor and exponentialDistributor, exported from the package entrypoint.
• Extend API docs generation/rendering to include a new “Distributors” page and support table output + refreshable distributor calls in examples.

Reviewed changes

Copilot reviewed 14 out of 14 changed files in this pull request and generated 8 comments.

Show a summary per file

File	Description
test/scripts/apidocs/snapshots/verify-jsdoc-tags.spec.ts.snap	Snapshot update to include new distributors docs section.
test/modules/number.spec.ts	Adds distribution-behavior tests for exponentialDistributor with int/float.
src/modules/number/index.ts	Adds distributor option to int/float and uses it to derive the underlying random float.
src/index.ts	Re-exports Distributor, uniformDistributor, and exponentialDistributor.
src/distributors/distributor.ts	Introduces the Distributor type and its documentation.
src/distributors/uniform.ts	Adds the uniform distributor helper.
src/distributors/exponential.ts	Adds the exponential/power-law distributor helper with base/bias configuration.
scripts/shared/refreshable-code.ts	Records distributor(...) calls in doc examples for “refreshable code”.
scripts/shared/markdown.ts	Allows table tags/attributes in sanitized HTML and adds wrapCode() helper.
scripts/apidocs/processing/method.ts	Adds discovery/processing of distributor functions for API docs.
scripts/apidocs/processing/class.ts	Adds “Distributors” API docs page generation.
scripts/apidocs/generate.ts	Includes distributors page in docs generation pipeline.
docs/.vitepress/components/api-docs/refreshable-code.vue	Updates recorded-invocation detection to include distributor(...).
docs/.vitepress/api-pages.ts	Adds “Distributors” to the API sidebar.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[xDivisionByZerox]

Other than the comment in #3375 (comment) I couldn't find anything that is blocking from my side. After I got some other opinions on the matter, I'm feeling confident in approving this.

[ST-DDT]

Other than the comment in #3375 (comment) I couldn't find anything that is blocking from my side.

Fixed

[xDivisionByZerox]

Thank you for bringing this to an end @ST-DDT! 🙏