TypeScript icon, indicating that this package has built-in type declarations

    1.3.2 • Public • Published


    GoTime is a simple but powerful library and syntax for defining times when you desire something to be active, and test dates against that definition.

    (  .'11 12 1'.  )
    |  :10 \|   2:  |
    |  :9   @   3:  |
    |  :8       4;  |
    '. '..7 6 5..' .'

    GoTime Syntax

    A GoTime definition is a series of test statements, each following this pattern: {part}{operator}{value}


    The first section of a test is the part, and it can be one of the following:

    Part code Meaning
    y Year. i.e. 2021
    m Month. 1 - 12 or Jan or January, etc.
    woy Week of the Year. 1 - 53
    wom Week of the Month. 1 - 5
    doy Day of the Year. 1 - 365
    dom Day of the Month. 1 - 31
    dow Day of the Week. 1 - 7 or Monday or Mon, etc. Monday is 1.
    time Time of Day. 00:00 - 23:59 must have hours : minutes
    datetime A complete date time value like yyyy-mm-dd hh:mm:ss


    The second section of a GoTime test is the operator.

    Operator Meaning
    = Equals
    <= Less than or equal
    >= Greater than or equal
    < Greater than
    > Less than


    The third section of a GoTime test is the value. Valid values depend on the part used in the test. For example, m=2022 is invalid because the m (Month) part is being used, and 2022 isn't a valid Month.

    This section can declare a single value, a series of comma separated values, or a span of values with a minimum (inclusive) and maximum (exclusive) separated by a dash or pipe. Only the equals operator can be used with the comma separated values or span syntax; it doesn't make sense to be less than a span or a list of values, for example.

    Multiple Statements

    A GoTime definition needs at least one test statement, but can include multiple tests separated by a semicolon. Tests using the same part are OR'd together, so if any one is true, the part test passes. For the entire definition to evaluate to true, a the input Date must pass every part. See the exmaples below.

    GoTime Examples

    Here are some example definitions

    Definition Syntax Meaning
    M=Oct; DoM>=24 Halloween week. The last 7 days of October.
    DoM<7; DoW=Sat,Sun The first weekend of the month. (Might only be one Sunday!)
    Time=00:00-01:00; Time=12:00-13:00 Midnight hour or noon hour
    Datetime>2022-04-20 After a specific point in time
    Datetime=2022-03-20 13:00:00|2022-03-22 05:30:00 Between two absolute points in time (separate by pipe symbol; only escaped for markdown)

    GoTime Usage

    const firstWeekend = new GoTime('DoM<7; DoW=Sat,Sun')
    const now = new Date()
    if (firstWeekend.test(now)) {
      // Do something here


    npm i @nimaimalle/go-time

    DownloadsWeekly Downloads






    Unpacked Size

    39.1 kB

    Total Files


    Last publish


    • nimaimalle