README
Date & time library built for Typescript first.
Optimized for ease of use, speed of use and minimization of bugs.
- Dates, times, timestamps, time zones, durations.
- Conversion between them and calculations with them.
- Type safe. An API that works. No comparing apples and oranges. You want to express an instant in time, a date on a calendar, a time on the clock? When zones come into play, they are not interchangeable. No longer are these concepts all thrown into one date type. Clearly de-obfuscated, dates & time become intuitive.
- Immutable.
- Fail early. No more
NaN
's slipping 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
Install
npm install globol
How to use
This library consists mainly of a few smart data types that each describe a different concept of time. This is what they are and how they relate to eachother:
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.
Instant
This is a moment in time, a timestamp. Is equivalent to a number of (milli)seconds since the epoch.
ZonedDateTime
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).
LocalDateTime
A date and a time together, but without a zone, e.g. 2020-01-20T19:34
LocalDate
A date without a time, e.g. 2020-01-20
LocalTime
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.
Duration
A fixed length of physical time.
ZoneId & ZoneOffset
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.
Usage examples
Get the current timestamp
Instant.now() // returns an Instant
Or use the shorthand
now() // returns an Instant
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'
Future work
Time zone information
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.
Feedback
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.
License
The content of this project is licensed under the MIT license.