Timestamps in the Standard Gleam Time Package

[jrstrunk]

Hello all!

A standard gleam time package is in the works, and I would like to invite community involvement in its development. Its immediate goal is to provide interop between time packages in the ecosystem.

As a first step, the Timestamp type is being explored. Timestamps are just Ints, but by giving it a standard type we can help assure that a second denominated timestamp is not accidentally compared to a millisecond denominated timestamp.

The current design is this:

pub type Timestamp {
  Timestamp(milliseconds: Int)
}

For now, we would like to focus on providing types in the standard package with minimal functionality, relying on the ecosystem to deliver richer functionality. If just core types are provided, then less can be committed to in the standard package. Gleam's type system is unique (and fantastic), and as such we may want to take some novel approaches to dealing with time. The less we commit to the standard library, the more experimentation we can do as a community, and the more cool things we might discover!

Do any of you amazing community members have any additional points we should take into consideration before canonicalizing this design?

After timestamps are settled, we could move on to probably the next simplest type which really isn't all that simple: dates. Some big questions are: 1. how should they be represented? 2. should the constructor be opaque?

I am the author of tempo (gtempo on hex), but I would like to make sure @massivefermion (author of birl), @maxdeviant (author of bigben), and @michaeljones (author of rada) are aware of this thread. I am not part of the Gleam core team, so while I have had prior conversations with Louis, nothing I say should be taken as official.

[jrstrunk]

These two functions are also being considered, but we may want to keep functionality light so we don't over commit to anything. External packages can also provide additional functions.

pub fn to_seconds(timestamp: Timestamp) -> Int {
  timestamp.milliseconds / 1000
}

// Maybe, for use in pipelines mostly I assume
pub fn to_milliseconds(timestamp: Timestamp) -> Int {
  timestamp.milliseconds
}

[massivefermion]

I think it's better to have an approach that is flexible while at the same time provides the safeguards around units which I think phantom types provide:

pub type Unit {
  MicroSecond
  MilliSecond
  Second
  Minute
  Hour
  Day
  Week
  Month
  Year
}

pub type Timestamp(unit) {
  Timestamp(Int)
}

We may even omit the Unit type itself in the stdlib!

[massivefermion]

The time for which the timestamp in microseconds would exceed the safe int range for js is hundreds of years from now.

That doesn't seem very far away. I have used dates many years in the future before.

Does birl have issues for those workflows?

[lpil]

@jrstrunk What was your reason for going for days there? Anything in particular? Or just a semi-arbitrary decision and it could have been years or something else?

[jrstrunk]

@maxdeviant cool piece of context, good to keep in mind. @massivefermion I believe it does, but you may want to write some tests to verify you lose duration precision past year 2255 something.

@lpil it was semi-arbitrary, we could also do something like this:

pub opaque type Timestamp {
  // milliseconds is the number of milliseconds since Jan 1st, 1970
  // nanoseconds is the number of nanoseconds since the last millisecond (never surpasses 100,000)
  Timestamp(milliseconds: Int, nanoseconds: Int)
}

This would optimize for millisecond operations (which I assume will be very common) while allowing for nanosecond precision if needed.

[lpil]

I suppose we would do a bit of maths to work out the precision limits of a few options and then decide if there's any particular advantage to any of them.

[jrstrunk]

A timestamp based on milliseconds should be safe for another 30,000 years, and a timestamp based on seconds should be safe for another 30,000,000 years. The performance difference between something like

pub opaque type Timestamp {
  Timestamp(milliseconds: Int, nanoseconds: Int)
}

and something like

pub opaque type Timestamp {
  Timestamp(days: Int, nanoseconds: Int)
}

for any given function should not be more than 1 div or mul operation, so less than a nanosecond on modern machines. The only exception to this would be add or subtract operations to the lesser value, leading to an update of the greater value (eg. when nanoseconds is added to and becomes larger than 100,000, then the milliseconds value has to be updated and the nanoseconds value has to be recalculated).

Also if we make the constructor opaque, couldn't we change around some inner workings later if a compelling reason emerges? (Keeping the same functions of course.)

[lpil]

The Elm time library has some other functions that make use of zones. Would we want to adapt those too?

https://package.elm-lang.org/packages/elm/time/latest/Time

If we do not provide anything along these lines how would the programmer be expected to work with these timestamps? Being able to convert them to a textual representation seems like it would be one of the most common needs.

[jrstrunk]

Just for some clarification, those Elm functions are taking a integer (assuming it is in UTC), converting it to the given time zone, then returning a different integer (then converting it to a month or whatever else). It is just a transformation on a naive int type. We could implement those Elm functions with the current proposed timestamp type in the original post.

Are you asking if we should add more functions to the package, or asking if we should add more properties to the type?

If we are just discussing adding functions, then I'd quickly say yes eventually those would be nice to add. If we are discussing adding more properties to the type, then there is a lot to talk over.

[lpil]

The frequency with which it is updated doesn't really matter as it's unavoidable. The database will need to be packaged for Gleam programs.

@jrstrunk not sure what you mean- they don't take an int, there is a zone type.

I don't have any ideas for additional fields, what did you have in mind?

If we were not to provide any basic functions for working with timestamps then birl or gtempo would presumably need to add these for the timestamp type to be usable at all. Is there a benefit to doing it that way?

[jrstrunk]

I guess I meant the function takes an Int (the Elm Posix type) and a time zone and returns an Int. The time zone data isn't tied to the return data type.

I think the benefit of offloading the logic to Birl and Tempo (and maybe more) is that it gives the community much more time to design and experiment with what will eventually become the standard types and functions. I'd like to see the standard be really thought out and done in a Gleamy way :)

[kwando]

It would be annoying to have to rebuild your app to get the latest timezone information. Would be cool if it could be dynamic somehow. Maybe look at how it is done in Elixir, which I personally think is quite good.

[lpil]

I want to take the same approach as Elixir and Elm and have no restrictions on where zone information comes from, so each application can decide what's best for them.

[michaeljones]

I appreciate being included in the initial message but rada is a line by line port of justinmimbs/date from Elm which I did because I liked the API and it had served me well in my Elm projects. I don't have any particular knowledge to share from this experience. Standardising date and time types seems like a good idea though!

[lpil]

I have started on a time library here: gleam-lang/time#1

[jrstrunk]

Exciting! I'll put any discussion points as separate issues there so they can be discussed and resolved individually