General purpose date & time library for Typescript & Javascript.
Based on porting the best API for time, java.time; made even better with the power of TS/JS.
- Dates, times, timestamps, time zones, durations, weekdays.
- Conversion between them and arithmetics with them.
- Type safe. You want to express an moment in time, a date on a calendar, a time on the clock? In a specific time zone, or you don't care? No longer will nuances like these overwhelm or confuse. It turns out time is very easy: you just needed the right API.
- Immutable.
- Fail early. No wrong input, like
NaN
s for milliseconds, sneaking into your date objects. Globol checks its input, and throws errors with helpful messages if there's something wrong. - Fluent. No searching the web for which functions suit your needs, but finding what you need with auto-complete.
- In-place documentation. Help yourself without leaving your IDE, with extensive JSDoc on all methods and functions.
- ISO-8601-compliant serilization/deserialization of all data representations.
- Under the hood, currently uses the well-tested, well-trusted
moment.js
internally for parsing, formatting and time zone conversions. - Uses moment-timezone for time zone information. Future work is to make this optionally injectable, so
globol
can be smaller for users that need it to be.
Example:
const timeInNewYork = now() // returns an Instant in time (≡ a timestamp)
.atZone('America/New_York') // returns that Instant expressed in a certain time zone; a ZonedDateTime
.toLocalTime(); // returns a time on the clock without a date, a LocalTime
npm install globol
Get the current timestamp
import {Instant} from 'globol';
Instant.now() // returns an Instant
All types and functions are in the globol
module, so we'll leave the import statement out from now.
You can also use a shorthand for the current time:
now() // returns an Instant
Get "tomorrow, in this timezone"
const tomorrow = now() // returns an Instant
.atZone(TimeZone.browser()) // returns a ZonedDateTime
.toLocalDate() // returns a LocalDate (dropped the zone and the time)
.plus({days: 1});
Get the current time on the clock (e.g. '14:57') in Berlin
now() // a timestamp
.atZone('Europe/Berlin') // returns a ZonedDateTime: the timestamp represented in this zone
.toLocalTime() // returns a LocalTime, e.g. '14:57'
This library consists mainly of a few smart data types that each describe a different concept of time. The most important one is Instant
, which denotes a point in time, regardless of time zone. A map with the other types:
You can create instances of any one of them with static methods from their classes, e.g. Instant.from(...)
,
Instant.parse(...)
or LocalTime.browser()
.
Similar methods exist on all Globol data types.
Once a data type is instantiated, there are methods for converting between them and doing calculations and
comparisons with them.
Below is a dedicated description for each data type.
This is a moment in time, a timestamp. Is equivalent to a number of (milli)seconds since the epoch.
A date with a time and a time zone offset, e.g. 2020-01-20T19:34Z 01
. A ZonedDateTime
implies one Instant
, but one Instant
can be represented in at least 24 ZonedDateTimes (one for each time zone).
A date and a time together, but without a zone, e.g. 2020-01-20T19:34
A date without a time, e.g. 2020-01-20
A time without a date, e.g. one LocalTime can mean 18:34
or 6:34 PM
, depending on how you format it in string form.
A fixed length of physical time.
These represent timezones. The difference between ZoneId and ZoneOffset is as follows: ZoneId represents something like Europe/Amsterdam
, which can have a ZoneOffset
of 1 in the winter and 2 in the summer.
Browsers provide time zone information, but the support is still limited/incomplete. Therefore we'd like to make it optional to include the moment-timezone dependency. This can be done by make a separate NPM dependency called globol-timezone
which, when included, runtime-enriches Globol with the moment-timezone
time zone information. When it's left out globol would rely on the time zone information supplied by the browser.
If something is missing from this library that makes it not fit your use case today, or if you find a bug that spoils it for you, don't hesitate to create an Issue (just a stub is better than nothing!) or a Pull Request. At this moment, the library is not at 1.0 yet and is organically growing to suit the use cases we run into first! Any feedback and/or contribution is sincerely appreciated.
The content of this project is licensed under the MIT license.