Note JavaScript precision

Closes #11

src/gleam/time/duration.gleam

@@ -172,6 +172,15 @@ pub fn milliseconds(amount: Int) -> Duration {
 }
 
 /// Create a duration of a number of nanoseconds.
+///
+/// # JavaScript int limitations
+///
+/// Remember that JavaScript can only perfectly represent ints between positive
+/// and negative 9,007,199,254,740,991! If you use a single call to this
+/// function to create durations larger than that number of nanoseconds then
+/// you will likely not get exactly the value you expect. Use `seconds` and
+/// `milliseconds` as much as possible for large durations.
+///
 pub fn nanoseconds(amount: Int) -> Duration {
   Duration(0, amount)
   |> normalise
@@ -190,6 +199,7 @@ pub fn to_seconds(duration: Duration) -> Float {
 
 /// Convert the duration to a number of seconds and nanoseconds. There is no
 /// loss of precision with this conversion on any target.
+///
 pub fn to_seconds_and_nanoseconds(duration: Duration) -> #(Int, Int) {
   #(duration.seconds, duration.nanoseconds)
 }

src/gleam/time/timestamp.gleam

@@ -244,6 +244,14 @@ pub fn from_unix_seconds(seconds: Int) -> Timestamp {
 /// Create a timestamp from a number of seconds and nanoseconds since 00:00:00
 /// UTC on 1 January 1970.
 ///
+/// # JavaScript int limitations
+///
+/// Remember that JavaScript can only perfectly represent ints between positive
+/// and negative 9,007,199,254,740,991! If you only use the nanosecond field
+/// then you will almost certainly not get the date value you want due to this
+/// loss of precision. Always use seconds primarily and then use nanoseconds
+/// for the final sub-second adjustment.
+///
 pub fn from_unix_seconds_and_nanoseconds(
   seconds seconds: Int,
   nanoseconds nanoseconds: Int,