🏷️ Add union type overloads for nat() and bigInt() (#6119)

**Description**

Adds the following function definitions:
```typescript
declare function nat(arg?: number | NatConstraints): Arbitrary<number>;
declare function bigInt(...args: [] | [bigint, bigint] | [BigIntConstraints]): Arbitrary<bigint>;
```

Previously, passing a `number | NatConstraints` to `nat` would fail:
```
    nat can accept a number, but number | NatConstraints is not assignable to number.
    nat can accept a NatConstraints, but number | NatConstraints is not assignable to NatConstraints.
```

And similar behavior for `bigInt`.

These are the only arbitraries that require appropriate union type
overloads.

Fixes #6073.

<!-- You can provide any additional context to help into understanding
what's this PR is attempting to solve: reproduction of a bug, code
snippets... -->

**Checklist** — _Don't delete this checklist and make sure you do the
following before opening the PR_

- [x] The name of my PR follows [gitmoji](https://gitmoji.dev/)
specification
- [x] My PR references one of several related issues (if any)
- [x] New features or breaking changes must come with an associated
Issue or Discussion
- [x] My PR does not add any new dependency without an associated Issue
or Discussion
- [x] My PR includes bumps details, please run `pnpm run bump` and flag
the impacts properly
- [x] My PR adds relevant tests and they would have failed without my PR
(when applicable)

<!-- More about contributing at
https://github.com/dubzzz/fast-check/blob/main/CONTRIBUTING.md -->

**Advanced**

<!-- How to fill the advanced section is detailed below! -->

- [x] Category: 🏷️ Types change.
- [x] Impacts: Reflection on calls to `bigInt` or `nat` may be impacted
(see the changes to `double.spec.ts` for an example). This shouldn't be
guaranteed stable IMO, since it's very unlikely that production software
would need rely on such a thing.

---------

Co-authored-by: Nicolas DUBIEN <github@dubien.org>

Author: dmurvihill

.changeset/light-eggs-cut.md

@@ -0,0 +1,5 @@
+---
+'fast-check': patch
+---
+
+Add union type overloads for `nat` and `bigInt`

packages/fast-check/src/arbitrary/bigInt.ts

@@ -81,6 +81,15 @@ function bigInt(min: bigint, max: bigint): Arbitrary<bigint>;
  * @public
  */
 function bigInt(constraints: BigIntConstraints): Arbitrary<bigint>;
+/**
+ * For bigint between min (included) and max (included)
+ *
+ * @param args - Either min/max bounds as an object or constraints to apply when building instances
+ *
+ * @remarks Since 2.6.0
+ * @public
+ */
+function bigInt(...args: [] | [bigint, bigint] | [BigIntConstraints]): Arbitrary<bigint>;
 function bigInt(...args: [] | [bigint, bigint] | [BigIntConstraints]): Arbitrary<bigint> {
   const constraints = buildCompleteBigIntConstraints(extractBigIntConstraints(args));
   if (constraints.min > constraints.max) {

packages/fast-check/src/arbitrary/nat.ts

@@ -42,6 +42,15 @@ function nat(max: number): Arbitrary<number>;
  * @public
  */
 function nat(constraints: NatConstraints): Arbitrary<number>;
+/**
+ * For positive integers between 0 (included) and max (included)
+ *
+ * @param arg - Either a maximum number or constraints to apply when building instances
+ *
+ * @remarks Since 2.6.0
+ * @public
+ */
+function nat(arg?: number | NatConstraints): Arbitrary<number>;
 function nat(arg?: number | NatConstraints): Arbitrary<number> {
   const max = typeof arg === 'number' ? arg : arg && arg.max !== undefined ? arg.max : 0x7fffffff;
   if (max < 0) {

packages/fast-check/test/unit/arbitrary/bigInt.spec.ts

@@ -1,6 +1,6 @@
 import { describe, it, expect, vi } from 'vitest';
 import * as fc from 'fast-check';
-import { bigInt } from '../../../src/arbitrary/bigInt';
+import { bigInt, type BigIntConstraints } from '../../../src/arbitrary/bigInt';
 
 import { fakeArbitrary } from './__test-helpers__/ArbitraryHelpers';
 import { declareCleaningHooksForSpies } from './__test-helpers__/SpyCleaner';
@@ -89,4 +89,44 @@ describe('bigInt', () => {
         expect(() => bigInt({ min: high, max: low })).toThrowError();
       }),
     ));
+
+  it('should handle union type of [number, number] | BigIntConstraints', () =>
+    fc.assert(
+      fc.property(
+        fc.oneof(
+          // no argument
+          fc.tuple(),
+          // min, max range
+          fc.tuple(fc.bigInt(), fc.bigInt()).map<[bigint, bigint]>((t) => (t[0] < t[1] ? [t[0], t[1]] : [t[1], t[0]])),
+          // both min and max defined
+          fc.tuple(
+            fc.record({ min: fc.bigInt(), max: fc.bigInt() }).map((c) => ({
+              min: c.min < c.max ? c.min : c.max,
+              max: c.min < c.max ? c.max : c.min,
+            })),
+          ),
+          // one or the other maybe defined
+          fc.tuple(fc.record({ min: fc.option(fc.bigInt(), { nil: undefined }) })),
+          fc.tuple(fc.record({ max: fc.option(fc.bigInt(), { nil: undefined }) })),
+        ),
+        (args: [] | [bigint, bigint] | [BigIntConstraints]) => {
+          // Arrange
+          const [expectedMin, expectedMax] =
+            args.length === 0 ? [null, null] : args.length === 1 ? [args[0].min, args[0].max] : [args[0], args[1]];
+          const instance = fakeBigIntArbitrary();
+          const BigIntArbitrary = vi.spyOn(BigIntArbitraryMock, 'BigIntArbitrary');
+          BigIntArbitrary.mockImplementation(() => instance);
+
+          // Act
+          const arb = bigInt(...args);
+
+          // Assert
+          expect(BigIntArbitrary).toHaveBeenCalledWith(
+            expectedMin ?? expect.any(BigInt),
+            expectedMax ?? expect.any(BigInt),
+          );
+          expect(arb).toBe(instance);
+        },
+      ),
+    ));
 });

packages/fast-check/test/unit/arbitrary/double.spec.ts

@@ -190,7 +190,16 @@ describe('double', () => {
           expect(bigInt).toHaveBeenCalledTimes(2);
           const constraintsNoNaN = bigInt.mock.calls[0];
           const constraintsWithNaN = bigInt.mock.calls[1];
+          if (constraintsNoNaN.length !== 1) {
+            expect.fail(`Expected bigInt to be called with one constraints object; got ${constraintsNoNaN}`);
+          }
+          if (constraintsWithNaN.length !== 1) {
+            expect.fail(`Expected bigInt to be called with one constraints object; got ${constraintsWithNaN}`);
+          }
           if (max > Number.MIN_VALUE || (max > 0 && !ct.maxExcluded)) {
+            if (constraintsNoNaN.length !== 1) {
+              expect.fail(`Expected bigInt to be called with one constraints object; got ${constraintsNoNaN}`);
+            }
             // max > 0  --> NaN will be added as the greatest value
             expect(constraintsWithNaN[0]).toEqual({
               min: constraintsNoNaN[0].min,
@@ -226,6 +235,12 @@ describe('double', () => {
             double({ ...ct, noNaN: true });
             const arb = double(ct);
             // Extract NaN "index"
+            if (bigInt.mock.calls[0].length !== 1) {
+              expect.fail(`Expected bigInt to be called with one constraints object; got ${bigInt.mock.calls[0]}`);
+            }
+            if (bigInt.mock.calls[1].length !== 1) {
+              expect.fail(`Expected bigInt to be called with one constraints object; got ${bigInt.mock.calls[1]}`);
+            }
             const [{ min: minNonNaN }] = bigInt.mock.calls[0];
             const [{ min: minNaN, max: maxNaN }] = bigInt.mock.calls[1];
             const indexForNaN = minNonNaN !== minNaN ? minNaN : maxNaN;

packages/fast-check/test/unit/arbitrary/nat.spec.ts

@@ -1,6 +1,6 @@
 import { describe, it, expect, vi } from 'vitest';
 import * as fc from 'fast-check';
-import { nat } from '../../../src/arbitrary/nat';
+import { nat, type NatConstraints } from '../../../src/arbitrary/nat';
 
 import { fakeArbitrary } from './__test-helpers__/ArbitraryHelpers';
 
@@ -96,4 +96,30 @@ describe('nat', () => {
       }),
     );
   });
+
+  it('should handle union type of number | NatConstraints', () =>
+    fc.assert(
+      fc.property(
+        fc.oneof(
+          fc.constant(undefined),
+          fc.integer({ min: 0 }),
+          fc.record({}),
+          fc.record({ max: fc.integer({ min: 0 }) }),
+        ),
+        (constraints: number | NatConstraints | undefined) => {
+          // Arrange
+          const expectedMax = typeof constraints === 'number' ? constraints : (constraints?.max ?? null);
+          const instance = fakeIntegerArbitrary();
+          const IntegerArbitrary = vi.spyOn(IntegerArbitraryMock, 'IntegerArbitrary');
+          IntegerArbitrary.mockImplementation(() => instance);
+
+          // Act
+          const arb = constraints === undefined ? nat() : nat(constraints);
+
+          // Assert
+          expect(IntegerArbitrary).toHaveBeenCalledWith(0, expectedMax ?? expect.anything());
+          expect(arb).toBe(instance);
+        },
+      ),
+    ));
 });