matter-of-time

1.0.2 • Public • Published

node-matter-of-time

A Date extension library to make it what it should've always been.

Matter of Time is semantically and syntactically more human than the standard's Date "class". It is a functional approach with a structure similar to other literal string parsing libraries out there, without the string parsing aspect!

String parsing is nice and all, but strings cannot be processed by linters and are often exempt from refactorization. If the API changes, strings that once were valid suddenly break without notice or reason as to why.

Installation

Install via npm:

npm i --save matter-of-time

Has no dependencies, but one dev dep for the unit tests.

API Facets

The API exports a class with various static methods. Import like so:

let MatterOfTime = require('matter-of-time');

For convenience, you might consider overriding Date instead:

let Date = require('matter-of-time');

See the unit tests for more use cases!

Absolute Dates

MatterOfTime.<month>([date]).in(<year>)

// e.g.
MatterOfTime.january(2).in(1980)
MatterOfTime.february(29).in(2000)
MatterOfTime.november(20).in(2018)

A call to .in() is optional and works on any date object, not just in this context. By default, dates are created with respect to this year.

first, second, third, fourth, fifth, and last weekday getters

Following this format:

MatterOfTime.<first|second|third|fourth|fifth|last>.<weekday>.of.<month>()

Examples:

MatterOfTime.first.monday.of.january()
MatterOfTime.last.sunday.of.december()

// .fifth may not always return a value, to aid in testing if a fifth instance
// of a weekday even exists!
let date = MatterOfTime.fifth.wednesday.of.july()
if (date) // ... do stuff!

Convenience Functions

The following three related functions create new MatterOfTime instances and should be self-explanatory:

MatterOfTime.now()
MatterOfTime.tomorrow()
MatterOfTime.yesterday()

.now() directly corresponds to Date.now(), except it returns a MatterOfTime instance. .tomorrow() and .yesterday() are implemented as MatterOfTime.now().tomorrow() and MatterOfTime.now().yesterday() respectively.

Timespans

Matter of Time offers a variety of durational functions to create Date objects representing a timespan of a certain resolution.

MatterOfTime.milliseconds(1234)
MatterOfTime.seconds(33)
MatterOfTime.days(5)

The various available resolutions are:

  • milliseconds
  • seconds
  • minutes
  • hours
  • days
  • weeks
  • fortnites
  • months
  • trimester
  • semester
  • years
  • decades
  • centuries
  • millenia

.from(MatterOfTime.now())

Specifically designed for timespans, the .from(<date>) method adds this represented timespan to the specified date.

MatterOfTime.days(3).from(MatterOfTime.now())
MatterOfTime.days(-3).from(MatterOfTime.first.monday.of.january())

Relative Dates

last, current, upcoming, next weekday getters

Following this format:

MatterOfTime.now().<last|current|upcoming|next>.<weekday>()

All of these interfaces work on different scopes of weeks, which should be self-explanatory:

last operates on the last week.

current operates on this week.

next operates on the next week.

upcoming is a bit different in that it combines current with next. When the queried weekday already lies in the past with respect to this date, it retrieves the weekday of the next week instead.

Examples:

MatterOfTime.now().next.monday()
MatterOfTime.now().last.friday()
MatterOfTime.now().upcoming.tuesday()
MatterOfTime.now().current.sunday()

<last|next>.<week|month|year>([count=1])

Both the next and last interfaces expose the week, month and year functions which all take an optional argument to get this date in count cycles.

Examples:

MatterOfTime.now().next.week()
MatterOfTime.now().next.month(2)
MatterOfTime.now().next.year(4)

Time Adjustment

There's a single method available to adjust the time through a formatted string.

The format is:

HH:MM:SS.XXX [am|pm]

am|pm is illegal when HH > 12 and will throw an error to aid in clarity. If omitted, am is assumed.

HH is any number from 0-24, single digit numbers allowed.

MM and SS is any number from 00-59, with double digit numbers required.

X may be any digit. Up to 3 digits may be provided.

Except for HH, none of the time components are required. When omitted their respective separator must be omitted as well, otherwise throwing an exception.

Examples:

MatterOfTime.now().at('5pm')

// Midnight
MatterOfTime.now().at('0')
MatterOfTime.now().at('00:00')
MatterOfTime.now().at('12am')

// Midday
MatterOfTime.now().at('12')
MatterOfTime.now().at('12:00')
MatterOfTime.now().at('12pm')

MatterOfTime.now().at('17')
MatterOfTime.now().at('17:24')
MatterOfTime.now().at('17:24:33')
MatterOfTime.now().at('17:24:33.123')

Versions

Current Tags

  • Version
    Downloads (Last 7 Days)
    • Tag
  • 1.0.2
    0
    • latest

Version History

  • Version
    Downloads (Last 7 Days)
    • Published
  • 1.0.2
    0
  • 1.0.1
    1
  • 1.0.0
    1

Package Sidebar

Install

npm i matter-of-time

Weekly Downloads

2

Version

1.0.2

License

GPL-3.0

Unpacked Size

68.5 kB

Total Files

5

Last publish

Collaborators

  • kiruse