JsonTime Package

JSON-serializable time types for API integrations.

Design Goals

  1. API Compatibility: Many APIs use Unix timestamps instead of ISO 8601 strings
  2. Type Safety: Distinct types prevent mixing seconds/milliseconds
  3. Bidirectional: Both serialization and deserialization supported

Types

TypeJSON FormatExampleUse Case
UnixInteger (seconds)1705315800General timestamps
MilliInteger (milliseconds)1705315800000High-precision timestamps
DurationString or Integer"1h30m" or 5400000000000Time intervals

Features

Unix Timestamps

Many APIs use Unix epoch timestamps rather than ISO 8601:

{
  "created_at": 1705315800,
  "updated_at": 1705316000
}

Millisecond Precision

JavaScript/browser APIs often use milliseconds:

{
  "timestamp": 1705315800000,
  "expires_at": 1705316000000
}

Flexible Duration Parsing

Duration supports both human-readable strings and raw nanoseconds:

{
  "timeout": "30s",
  "interval": "1h30m",
  "precise_delay": 5000000000
}

Time Operations

Both Unix and Milli support common time operations:

OperationDescription
Before(t)Is this time before t?
After(t)Is this time after t?
Equal(t)Are these times equal?
Sub(t)Duration between times
Add(d)Add duration to time
IsZero()Is this the zero time?

Duration String Format

The Duration type uses Go-style duration strings:

UnitSymbolExample
Hoursh2h
Minutesm30m
Secondss45s
Combined1h30m45s

Examples Directory

  • examples/go/jsontime/ - Go usage examples (if any)
  • examples/rust/jsontime/ - Rust usage examples (if any)
  • minimax - Uses Milli for timestamps in API responses
  • doubaospeech - Uses Unix/Milli for audio timestamps
  • dashscope - Uses Duration for timeout configuration