Temporal bindings

[tom-sherman]

https://tc39.es/proposal-temporal/docs

Currently incomplete, need to clean the rest up before committing them.

Couple of questions on approach:

• Is there a way to more directly type functions that type option bags? I assume no and we have to wait for this RFC
• Many modules share a lot of functions, is it worth segmenting these out into functors? Or is a more direct approach, as in this PR currently, more valuable?

I've skipped APIs that rely on bigints, I think official support need to land for these (at least in the form of a type in the stdlib) before adding bindings. See rescript-lang/rescript-compiler#4677

I've also skipped toLocaleString bindings as I think we should add general Intl bindings first (#77)

[tom-sherman]

I'm not sure if these (as well as the params for PlainTime.make) should be prefixed with iso, what do you think?

[TheSpyder]

The from methods don't prefix the keys with iso. So I think even though the spec describes them as isoYear etc we should stay consistent and not prefix the parameters.

[tom-sherman]

I've taken different approaches for option bags depending on the optionality of the properties. My logic goes as follows:

• If there is only one property, use an object type. Mark it as required even if the API accepts an empty object
• If there is more than one property but they're all required, use an object type
• If there is more than one property and one or more are optional, use an option bag module

Is this consistent with other bindings? If so, would be good to document this in some style guide.

[TheSpyder]

Record types are best when all properties are required, imo. They have the advantage of looking like objects when calling the function; the @obj system was created a long time ago and is now only used as a bit of a hack to omit unspecified properties instead of setting them to undefined.

And yes now that we're getting more contributors a style guide is probably worth starting. It might make a nice binding cheat-sheet too.

[TheSpyder]

Regarding BigInt, maybe we consider pulling in rescript-js. That might be a bit heavy-handed, though, to force webapi users to adopt the alternative Js implementation as well if they want to make use of the BigInt functions.

[TheSpyder]

This submodule doesn't seem to add anything? I think it would work just as well without the submodule wrapper.

[TheSpyder]

If you're careful the sub-module can be avoided for simple cases like this. I know the rest of the library does it this way but once we look at modernising the API (and reducing runtime code generation) I might try to rename some of the make submodule methods to be named directly, instead of encapsulated:

Suggested change

	module RoundOptions = {
	type t
	@obj
	external make: (
	~smallestUnit: roundTo,
	~roundingIncrement: int=?,
	~roundingMode: [#halfExpand | #ceil | #trunc | #floor]=?,
	unit
	) => t = ""
	}
	@send external round: (t, ~to: roundTo) => t = "round"
	@send external roundWithOptions: (t, RoundOptions.t) => t = "round"
	type roundOptions
	@obj
	external roundOptions: (
	~smallestUnit: roundTo,
	~roundingIncrement: int=?,
	~roundingMode: [#halfExpand | #ceil | #trunc | #floor]=?,
	unit
	) => roundOptions = ""
	@send external round: (t, ~to: roundTo) => t = "round"
	@send external roundWithOptions: (t, roundOptions) => t = "round"

And so on for the other submodules you've added in this PR. In this style using it becomes value->Instant.roundWithOptions(Instant.roundOptions(~smallestUnit=#hour, ())).

Although to be fair by the time we get to v2 we might have ReScript 10 available, and if the structural typing change in master works as well as we hope the entire @obj system will be replaced.

[TheSpyder]

The from methods don't prefix the keys with iso. So I think even though the spec describes them as isoYear etc we should stay consistent and not prefix the parameters.

[TheSpyder]

Record types are best when all properties are required, imo. They have the advantage of looking like objects when calling the function; the @obj system was created a long time ago and is now only used as a bit of a hack to omit unspecified properties instead of setting them to undefined.

And yes now that we're getting more contributors a style guide is probably worth starting. It might make a nice binding cheat-sheet too.