faker.time module to simplify time (not datetime) usecases

[douglasg14b]

Clear and concise description of the problem

Generating fakes specifically for times, not necessarily dates. These will only produce times, and not consider dates.

The date fucntions do perform this utility to some degree but require additional work to achieve which could be baked into a time module directly.

Suggested solution

in module faker.date or in a new module faker.time it would have fucntions for:

• faker.time.between
• faker.time.after
• faker.time.range
• ....etc

These should accept a format argument that allows the time output to be formatted as 24/12h time (or others)

Alternative

Users build their own time fucntions that work on top of faker.date

Additional context

Naive examples from my own use:

function getFakeTime(options?: { from?: Date; to?: Date } = {}) {
    const from = options?.from || '2024-01-01T00:00:00.000Z';
    const to = options?.to || '2024-01-01T23:59:59.999Z';

    return faker.date.between({from, to});
}

function getFake24hTime(time?: Date) {
    const dateTime = time || getFakeTime();
    return dateTime.toISOString().slice(11, 16);
}

function getFake24hTimeRange() {
    const from = getFakeTime();
    const to = getFakeTime({from});
    return {
        from: getFake24hTime(from),
        to: getFake24hTime(to),
    }
}

[github-actions]

Thank you for your feature proposal.

We marked it as "waiting for user interest" for now to gather some feedback from our community:

• If you would like to see this feature be implemented, please react to the description with an up-vote (:+1:).
• If you have a suggestion or want to point out some special cases that need to be considered, please leave a comment, so we are aware about them.

We would also like to hear about other community members' use cases for the feature to give us a better understanding of their potential implicit or explicit requirements.

We will start the implementation based on:

• the number of votes (:+1:) and comments
• the relevance for the ecosystem
• availability of alternatives and workarounds
• and the complexity of the requested feature

We do this because:

• There are plenty of languages/countries out there and we would like to ensure that every method can cover all or almost all of them.
• Every feature we add to faker has "costs" associated to it:
  • initial costs: design, implementation, reviews, documentation
  • running costs: awareness of the feature itself, more complex module structure, increased bundle size, more work during refactors

---

View more issues which are waiting for user interest

[ST-DDT]

The date functions do perform this utility to some degree but require additional work to achieve which could be baked into a time module directly.

Could you explain which issues you are encountering with the date module when generating times other than date.toISOString().slice(11, 16)?

Maybe these issues also apply to the date module in general and just haven't been raised yet.

---

• faker.time.range

return {
        from: getFake24hTime(from),
        to: getFake24hTime(to),
    }

IMO it is unlikely that we add a method like this, because it is likely a user dependent structure. e.g. maybe you use {from,to}, others might want to use {start,end} or from-to.

As a workaround for that, I can recommend the faker.date.betweens({ from, to, count: 2) function (or from the time module, if we add it). It returns a sorted list, so you can just use it like this:

const [ rangeFrom, rangeTo ] = faker.date.betweens({ from, to, count: 2);
return {
    from: toTime(rangeFrom),
    to: toTime(rangeTo ),
}

---

These should accept a format argument that allows the time output to be formatted as 24/12h time (or others)

IMO the format parameter is unlikely, because there are too many possible variations to it, that we might end up with a full date formatting library.

e.g. one user wants the time formatted like this: HH:mm, HH:mm:ss, or HH:mm:ss.SSS, what about timezones, 12h vs 24h format?

This is currently my main concern with the time module.

[ST-DDT]

@douglasg14b Could you please answer these questions/respond to the suggestions?

Or are the additions to the following section sufficient?

• https://next.fakerjs.dev/api/date.html#overview

[douglasg14b]

Hi, sorry, my github notifications as skuffed (nearly 1000/d for work, and when not SSOd like when home github shows me zero other notifications for some reason). If I am mentioned I get a push notification though.

---

That said:, the issue I was encountering was:

1. Generating times on the same day
2. Generated formatted times as strings

I think these are two different problems.

1. Could be solved as part of the date module
2. Could be soled by utilizing a formatting lib (ie. dayjs which is minuscule) with a date argument or helper

[ST-DDT]

@douglasg14b

Generating times on the same day

Would the following solve your issue:

const someDate = new Date(faker.date.soon().toISOString().substring(0, 10)).valueOf();
const timeAtThatDay = faker.date.between({from: someDate, to: someDate + 86400000 - 1000});

The main issue we have here is that the it is unclear, which timezone the time (of day) should be in. The example assumes local timezone.

I assume some usecases apply to subsets of days. e.g. working hours.

const timeAtThatWorkDay = faker.date.between({from: someDate + 9 * 60 * 60 * 1000, to: someDate + 17 * 60 * 60 * 1000});

But what if you want the times to be alligned in a 15minute grid?

Maybe a custom/user defined function can produce these results more easily?

const slottedTimeAtThatWorkDay = new Date(someDate + 9 * 60 * 60 * 1000 + faker.number.int({multipleOf: 15, min: 0, max: 8 * 60}) * 60 * 1000)

I could see usefulness for multipleOf/a slotting feature for between/the date module in general though.

Is any of this what you need? Any ideas on how to solve the timezone issue?

---

Generated formatted times as strings

IMO that is out of scope for faker

[ST-DDT]

@douglasg14b Could you please explain your needs in more detail/check whether the above would help you in any way?

[douglasg14b]

The above does solve it, technically. However, it's not elegant and means that functions to fake the (standardized) data are still present in mocking locations 🤔

But I see your point though.

That is out of scope for faker

Why is this? A format is faked data, which is somewhat omnipresent in the concept of fakerjs. What makes this different?

There are light libs that accept semi-standardized string format inputs for date/times, like dayjs. Making such a surface area, ideally, straightforward.

---

In this case we had a need to fake fragments of an ISO 8601 timestamp. As well as faking 24 hour time strings (ie. 14:13). Often in sequence.

This was largely solved at the time it was needed, but it was a surprise that some of the date & time faking wasn't part of the fakerjs API. So I made this suggestion.

Especially helpful utilities like faking time between two times, or after/before. Ie. Having controls over the variance of the faked date/times.

[ST-DDT]

What is the input and output format for the methods? HH:mm? HH:mm:ss.S? Are partial inputs allowed?

Is 23:00 - 01:00 allowed?

Which methods do you need?

• between?
• betweens?
• ?

Which options do you need for those methods (please include types)?