Needless Patchouli Manufacture

    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')
    

    Install

    npm i matter-of-time

    DownloadsWeekly Downloads

    2

    Version

    1.0.2

    License

    GPL-3.0

    Unpacked Size

    68.5 kB

    Total Files

    5

    Last publish

    Collaborators

    • kiruse