Add Date module

[jdharrisnz]

Type

• Refactor
• Feature
• Bug Fix
• Optimization
• Documentation Update

Description

Add Date module.

Related

N/A

Questions from me

Hi, my first time contributing to this! Hopefully this module is valuable and well-written.

I had some questions about code style and documentation.

First - @since tags - who adds these? I don't think I can do it since I don't know which version this might be added to.

Second - Predicate-based dual api functions. I've never seen these in Effect, but there are a few functions that offer optional arguments with default values, such as the week functions and their dowOffset. There's no difference between these usages:

pipe(Date.create(), Date.toWeekNumber)
pipe(Date.create(), Date.toWeekNumber(1))

...and TypeScript has no problem figuring out which overload to use, but it's a bit confusing to read.

Third - Is there some requirement for test coverage? I've added tests for everything that might be considered complex, but a lot of functions are also extremely trivial.

Fourth - I've added a lot in here and surely cover all the basics, but there's surely also more inspiration I could take from projects like date-fns. How comprehensive is something like this expected to be before it's accepted?

Thanks!

[changeset-bot]

🦋 Changeset detected

Latest commit: 42d8257

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 24 packages

Name	Type
effect	Minor
@effect/cli	Major
@effect/experimental	Major
@effect/opentelemetry	Major
@effect/platform-browser	Major
@effect/platform-bun	Major
@effect/platform-node-shared	Major
@effect/platform-node	Major
@effect/platform	Major
@effect/printer-ansi	Major
@effect/printer	Major
@effect/rpc-http	Major
@effect/rpc	Major
@effect/schema	Major
@effect/sql-mssql	Major
@effect/sql-mysql2	Major
@effect/sql-pg	Major
@effect/sql-sqlite-bun	Major
@effect/sql-sqlite-node	Major
@effect/sql-sqlite-react-native	Major
@effect/sql-sqlite-wasm	Major
@effect/sql	Major
@effect/typeclass	Major
@effect/vitest	Major

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[tim-smart]

Hi, thanks for the PR :) Tackling a Date module is a brave first contribution lol.

First - @since tags - who adds these? I don't think I can do it since I don't know which version this might be added to.

You can add @since 3.3.0 for the time being.

Second - Predicate-based dual api functions. I've never seen these in Effect, but there are a few functions that offer optional arguments with default values, such as the week functions and their dowOffset. There's no difference between these usages:

I think what you have there is fine.

Third - Is there some requirement for test coverage? I've added tests for everything that might be considered complex, but a lot of functions are also extremely trivial.

It will be reviewed on a case by case basis. If we feel there are tests missing during review, we will let you know.

Fourth - I've added a lot in here and surely cover all the basics, but there's surely also more inspiration I could take from projects like date-fns. How comprehensive is something like this expected to be before it's accepted?

We will give your PR a proper review soon. A Date module has the potential to get quite complex (especially if you want to add timezone support etc), so sticking to the basics for now is a good choice.

[jdharrisnz]

Hi @tim-smart , is there anything I need to do to move this along, or still just waiting for code review?

I see one of the GitHub checks fails but I'm not sure what causes it.

[tim-smart]

Hi @tim-smart , is there anything I need to do to move this along, or still just waiting for code review?

I see one of the GitHub checks fails but I'm not sure what causes it.

Sorry for the neglect, but I think we just need to set aside some time to think about how we want to approach dates in effect.

Maybe we could introduce a UtcDate module first, which has APIs that only deal with UTC. Then afterwards look at how to add timezone support.

js Date also has so many footguns it might be better to side step it and create a more type safe data structure.

The upcoming Temporal proposal could be used as inspiration: https://tc39.es/proposal-temporal/docs/index.html

[tim-smart]

I had a play around with the domain here: #3296

Not sure about the direction yet, but I think putting up some guard rails is a good approach.

[jdharrisnz]

Thanks Tim. Agreed on shipping only UTC functions - there's a lot to keep in mind with the local stuff 😅

Your domain looks like a great start. Do you want me to move over the UTC getters, setters, and math functions from this PR into that? (Not sure how this fits with the WithZone part of it though - is that basically just an offset on top of UTC?)

[tim-smart]

I think for time zones we can lean on the Intl APIs.

Yeah feel free to pitch in.

For the math functions it could be quite nice to have something like:

DateTime.add(self, 6, "months")
DateTime.add(self, Duration)

Then we can just "do the right thing" to prevent issues when crossing over daylight savings.

[tim-smart]

Made some solid progress. Will close this in favour of the other PR.