Add a function to create a datetime from a Timeable

[onelson]

Today, when v.startTimeRange is supplied to flux, it can be either a duration or datetime.

This can cause trouble for script authors who need to produce a datetime string from this value without knowing specifically which type the script will receive.

Use case

A use case for this is when you have a script that needs a datetime regardless of how the v.startTimeRange is specified.

As a concrete example, if you were calling sql.from() and needed to string interpolate this value as ISO 8601 in your query to limit the returned rows, your script could only be written to support either relative (duration-based) values, or explicit datetime values.

The script would need to be tweaked if your change the time range drop down in the UI, for example.

Proposal

Providing a function that can receive any Timeable and produce a datetime could solve for this situation.

package date

builtin time : (t: A) => time where A: Timeable

Example:

import "date"

// normalize to datetimes regardless of incoming types
start = date.time(t: v.startTimeRange)
end = date.time(t: v.endTimeRange)

sql.from(
  ...,
  // cast to ISO 8601 for use with SQL...
  query: "SELECT * from events WHERE timestamp >= '${start}' AND timestamp < '${end}'"
) |> // snip...

This also makes some sense for use with JSON APIs.

Note: there's a getTimeableTime function in stdlib/date/date.go which can be used to this aim.