(01/03/2024) This package has been depreciated. This package separates the intrinsic link between date and time, but in doing so does not support date-times, which are handy more often than they are not. Thus, this package is unhelpful in many situations and has been depreciated to ensure nobody uses it themselves.

Chiral

Chiral is a timekeeping library built for JavaScript and TypeScript projects. It sits as a layer of abstraction on top of JavaScript's Date class, aiming to effectively replace it for most uses.

The primary purpose of Chiral is to separate Date and Time. There are a number of preferential reasons for doing this, most of which are outlined in this Thread. Although exact implementation details are different, the general idea of separating the two remains constant.

Chiral does not support Timezones, due to the inherent complexity of the topic. This is by design, and will almost certainly never be changed.

Installation

npm

npm install chiral

RealTime

The RealTime class represents date-agnostic time. It only has four properties; hours, minutes, seconds and milliseconds. It's epoch is 00:00:00 AM, or midnight. RealTime objects are generally immutable, except when their properties are accessed via setters.

import { RealTime } from "chiral";

const time = new RealTime(9, 35, 40);
console.log(time.toDigital());
// 09:35:40 AM

Individual increments can be set (this is a mutable transformation!):

time.minutes = 41;
console.log(time.toDigital());
// 09:41:40 AM

Rounding to a particular precision precision/p is also possible, and will by default round down. This can be set manually using the rounding/r parameter, which accepts "down", "up" or "nearest":

console.log(time.round({ p: "m" }).toDigital());
// 09:41:00 AM
console.log(time.round({ precision: "m", rounding: "nearest"}).toDigital());
// 09:42:00 AM
console.log(time.round({ p: "m", r: "nearest"}).toDigital());
// 09:42:00 AM

Milliseconds are also supported, but occluded by default:

const time = new RealTime(9, 41, 40, 325);
console.log(time.toDigital());
// 09:41:40 AM
console.log(time.toDigital({ p: "ms" }));
// 09:41:40:325 AM

Arithmetic can also be performed on times, like so:

const time = new RealTime(9, 35, 40);
console.log(time.add({ unit: "m", value: 3 }).toDigital());
// 09:38:40 AM
// OR
console.log(time.add({ u: "m", v: 3 }).toDigital());
// 09:38:40 AM

And with lists of actions, including double-ups, like so:

const time = new RealTime(9, 35, 40);
console.log(time.add([
  { u: "m", v: 3 },
  { u: "m", v: 5 },
  { u: "h", v: 1 },
]).toDigital());
// 10:43:40 AM

The same goes for subtraction.

Equality and comparison checks can also be performed to certain precisions. Rounding to a precision will accept and obey the same default parameters as the .round() function:

const firstTime = new RealTime(9, 35, 40);    // 09:35:40 AM
const secondTime = new RealTime(9);           // 09:00:00 AM

console.log(firstTime.equals(secondTime));
// false
console.log(firstTime.equals(secondTime, { p: "h" }));
// true   - round down by default!
console.log(firstTime.equals(secondTime, { p: "h", r: "nearest" }));
// false

console.log(firstTime.isBefore(secondTime));
// false
console.log(secondTime.isBefore(firstTime));
// true
console.log(firstTime.isBefore(secondTime, { p: "h" }));
// false   - exact equality is not before

// Same behaviour for .isAfter

const thirdTime = new RealTime(9, 41, 40);    // 09:41:40 AM
console.log(thirdTime.isBetween(firstTime, secondTime));
// true
console.log(firstTime.isBetween(firstTime, secondTime));
// true    - here, exact equality is counted
console.log(firstTime.isBetween(secondTime, thirdTime));
// false
console.log(firstTime.isBetween(secondTime, thirdTime, { p: "h" }));
// true    - again, we round down by default!

RealDate

Chiral's RealDate is largely the converse of the RealTime class; it is a time-agnostic date that has the normal JavaScript epoch. Rather than a complete re-implementation (like RealTime is), RealDate is a simple wrapper around JavaScript's Date class that provides a similar API to the RealTime.

import { RealDate } from "chiral";

const date = new RealDate(2023, 10, 25);
console.log(date.toReadable());
// 25/10/2023

The .toReadable() method is the functional equivalent of RealTime's .toDigital() method, but offers the format (f) parameters to format the date as you wish. This defaults to DD/MM/YYYY, because I'm not American and read dates like a normal person.

console.log(date.toReadable({ f: "MM/DD/YYYY" }));
// 10/25/2023    - For all the Americans out there

// Other supported formats are:
// - YYYY/MM/DD      - 2023/10/25
// - Month DD, YYYY  - October 25, 2023

Other methods and parameters are almost identical to those defined RealTime, so they won't be re-explained here. They scale as one would expect to a date object.

Building your own

Chiral also exports the Chiral namespace, which contains all the underlying types used by the RealDate and RealTime classes. This contains parameter types, and the class interfaces for both.

import { Chiral } from "chiral";

class RealTime implements Chiral.Time.I_Time<RealTime> {
  // ...
}

class RealDate implements Chiral.Date.I_Time<RealDate> {
  // ...
}

This is handy if you want to re-implement the classes for your own use, or build extensions or wrappers.