faker.date.betweens should return a fixed-length tuple type rather than array of Date

[fnimick]

Pre-Checks

• Follow our Code of Conduct.
• Read the Contributing Guidelines.
• Read the docs.
• Check that there isn't already an issue that reports the same bug to avoid creating a duplicate.
• Make sure this is a Faker issue and not related to a combination with another package.
• Check that this is a concrete bug. For Q&A open a GitHub Discussion or join our Discord Chat Server.
• The provided reproduction is a minimal reproducible example of the bug.
• I am willing to provide a PR.

Describe the bug

faker.date.betweens returns a Date[], which means:

• if typescript option noUncheckedIndexedAccess is set, all indexed values are Date | undefined
• if noUncheckedIndexAccess is not set, it is possible to index beyond the end of the array and have undefined at runtime, while the compile-type type is Date.

Ideally, faker.date.betweens should return a fixed-length tuple based on the provided count, defaulting to [Date, Date, Date] to match the default count of 3.

Minimal reproduction code

// noUncheckedIndexAccess is not set for this example
const fakeDates = faker.date.betweens({
from: "2020-01-01T00:00:00.000Z",
to: "2020-04-01T00:00:00.000Z",
count: 3,
});
let [a, b, c, d] = fakeDates;
// d is Date for type-checking, but undefined at runtime

const fakeDatesWithType = fakeDates as [Date, Date, Date];
// this is now a type error on h
let [e, f, g, h] = fakeDatesWithType;

Additional Context

No response

Environment Info

System:
    OS: macOS 15.3.1
    CPU: (10) arm64 Apple M1 Pro
    Memory: 96.45 MB / 16.00 GB
    Shell: 5.9 - /bin/zsh
  Binaries:
    Node: 22.14.0 - ~/.asdf/installs/nodejs/22.14.0/bin/node
    npm: 10.9.2 - ~/.asdf/installs/nodejs/22.14.0/bin/npm
    pnpm: 9.15.5 - ~/.asdf/shims/pnpm
  Browsers:
    Chrome: 133.0.6943.127
    Safari: 18.3
  npmPackages:
    @faker-js/faker: ^9.0.3 => 9.5.0

Which module system do you use?

• CJS
• ESM

Used Package Manager

npm

[ST-DDT]

Possible duplicate of:

• helpers.arrayElements should return a tuple instead of an array #2675 (comment)

IMO this is a limitation of typescript that we hardly can avoid. We could use recursive types but these are expensive and I consider them a non-option. I also dont like to add 10+ signatures to a method to cover all possible array lengths.

Are there other solutions to this?

---

As a workaround you can cast the result to a tuple.

---

What are the common lengths of betweens that you use and what for?

[fnimick]

We could use recursive types but these are expensive and I consider them a non-option.

How expensive? I have used recursive types up to 70 long in my codebase with no perceptible performance penalty.

I use this for creating a series of fake dates in order and assigning them to variables, e.g. const [a, b, c....] = faker.date.betweens(...). Having a fixed length tuple as the result ensures that we never assign a variable that is undefined at runtime. Of course this would only apply when count is a number, and not a range.

I am currently casting to ReadonlyTuple from https://github.com/sindresorhus/type-fest/blob/main/source/readonly-tuple.d.ts .