at

README

at

Timestamps with millisecond precision, for data that gets stored and compared as text.

Go's time.Time marshals with nanosecond precision and a variable-length fraction, so two timestamps that are the same instant can serialise differently — which matters when the text is a CouchDB document key, a database column, or part of an API response someone diffs. at.Timestamp always writes exactly three decimal places, so encoding is stable and lexical order matches chronological order.

This package started inside invopop/couch and was moved out so anything can use it without depending on a persistence layer.

Install

go get github.com/invopop/at

Usage

Timestamp embeds time.Time, so every method you already know is there:

ts := at.Now()
fmt.Println(ts.String())  // 2026-08-03T12:29:08.123Z
fmt.Println(ts.Year())    // 2026, via the embedded time.Time
fmt.Println(ts.Before(other.Time))

In a struct it marshals and unmarshals as a quoted string, and an empty value round-trips as null:

type Invoice struct {
	IssuedAt at.Timestamp  `json:"issued_at"`
	PaidAt   *at.Timestamp `json:"paid_at,omitempty"`
}

{ "issued_at": "2026-08-03T12:29:08.123Z" }

Parsing takes any RFC3339 timestamp — milliseconds optional, offset or Z — and normalises it to UTC, so input that was written by something less strict still reads:

ts, _ := at.ParseTimestamp("2026-08-03T12:29:08.123Z")
ts, _ = at.ParseTimestamp("2026-08-03T14:29:08.123+02:00") // → 12:29:08.123Z
ts, _ = at.ParseTimestamp("2026-08-03T12:29:08Z")          // → 12:29:08.000Z

Local times

LocalTime is the same idea for a wall-clock time that must keep its zone rather than being normalised to UTC — a scheduled hour in a merchant's own timezone, for example:

lt := at.LocalTimeNow(loc)
fmt.Println(lt.String())  // 2026-08-03T14:29:08.123+02:00

Notes

• Marshalling always emits three decimal places, padding or truncating as needed. A timestamp with sub-millisecond precision loses it on the way out.
• The zero Timestamp marshals as null, and null unmarshals back to the zero value, so IsZero() is the test for "not set".

License

Apache 2.0 — see LICENSE.

Documentation

Overview

Package at provides timestamp handling with millisecond precision.

Index

• Constants
• type LocalTime
  • func LocalTimeNow(loc *time.Location) LocalTime
  • func ParseLocalTime(str string) (LocalTime, error)
  • func (t LocalTime) MarshalJSON() ([]byte, error)
  • func (t *LocalTime) String() string
  • func (t *LocalTime) UnmarshalJSON(data []byte) error
• type Timestamp
  • func Now() Timestamp
  • func ParseTimestamp(str string) (Timestamp, error)
  • func (t Timestamp) MarshalJSON() ([]byte, error)
  • func (t *Timestamp) String() string
  • func (t *Timestamp) UnmarshalJSON(data []byte) error

Constants

const (
	RFC3339Milli         string = "2006-01-02T15:04:05.000Z"
	RFC3339MilliWithZone string = "2006-01-02T15:04:05.000-07:00"
)

Millisecond time formats to comply with W3C datetime format that contains rules for local timezones so that they always include a ":".

Types

type LocalTime

type LocalTime struct {
	time.Time
}

LocalTime ensures the local time information is included in the timestamp.

func LocalTimeNow

func LocalTimeNow(loc *time.Location) LocalTime

LocalTimeNow is used to provide the current time in the provided location.

func ParseLocalTime

func ParseLocalTime(str string) (LocalTime, error)

ParseLocalTime attempts to read in the provided time data which hopefully includes a zone, but is not necessarily guaranteed.

func (LocalTime) MarshalJSON

func (t LocalTime) MarshalJSON() ([]byte, error)

MarshalJSON provides the local time in JSON format.

func (*LocalTime) String

func (t *LocalTime) String() string

String provides the local time including milliseconds and a time zone.

func (*LocalTime) UnmarshalJSON

func (t *LocalTime) UnmarshalJSON(data []byte) error

UnmarshalJSON parses the provided local time JSON data.

type Timestamp

type Timestamp struct {
	time.Time
}

Timestamp represents the basic time wrapper to be used in timestamps with millisecond precision.

func Now

func Now() Timestamp

Now provides a timestamp for the current UTC system Time

func ParseTimestamp

func ParseTimestamp(str string) (Timestamp, error)

ParseTimestamp attempts to parse the timestamp string.

func (Timestamp) MarshalJSON

func (t Timestamp) MarshalJSON() ([]byte, error)

MarshalJSON provides the timestamp in JSON format

func (*Timestamp) String

func (t *Timestamp) String() string

String provides the timestamp in RFC3339 format including milliseconds.

func (*Timestamp) UnmarshalJSON

func (t *Timestamp) UnmarshalJSON(data []byte) error

UnmarshalJSON uses our timestamp parser.