Nondigestible Purple Mayonnaise

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

    4.0.5 • Public • Published

    od

    Build Status NPM Package Code Coverage NPM Downloads wakatime

    Oh dear, another date library

    Why Bother

    Need a date library?

    There's moment, so big and so slow it'll make continental-drift look snappy. Or js-joda, an imperative library with its own custom parsing! Doesn't that sound like a Good Idea™. Then there's dayjs, an imperative library that keeps data in its own custom objects like moment.... making tree-shaking impossible. Next up is date-fns, that only offers separate methods for incrementing a date by different units of time. Talk about crimping your polymorphic style. Maybe you're more of a functional programmer, so you'd reach for date-fp, until you find it's unmaintained and inconsistent with time-zones. There are plenty more date libraries, maybe you'll find a good fit if you keep looking for a few more years...

    Don't over-dose on the existing headaches, say hello to od!

    od, the one date library required. (Pronounced "oh dee".)

    It's

    • immutable
      • Every function returns a new Date object
    • consistent
      • UTC everywhere. Let's all just ignore everything else.
    • intuitive
    • fast
      • As fast as you can get with the core libraries
    • transparent
    • typed
      • Conceived in TypeScript, for TypeScript
    • simple
      • Each function has one job and does it well
    • tested
      • 100% code coverage, property-tested with fast-check
    • tiny
      • 1 kB gzipped
    • maintained
      • Maintenance becomes simple when scope is kept minimal
    • documented
    • curried
    • dependency-free

    Install

    npm install od

    Use

    import D from 'od'
    
    const start = D.of(Date.now())
    const end = D.add('day', 1, start)

    Or just import the functions you need

    import { add } from 'od/lib/add'

    Documentation

    Creating new Dates
    Transforming Dates
    Combining Dates
    Accessing properties of Dates

    Creating Dates

    of

    of :: number | string | DateDescriptor -> Date
    of :: number -> Date
    of :: string -> Date
    of :: DateDescriptor -> Date

    Creates a Date object representing the specified date.

    D.of(0)                      //=> 1970-01-01T00:00:00.000Z
    D.of('1912-04-15')           //=> 1912-04-15T00:00:00.000Z
    D.of('1969-07-20T20:17:00')  //=> 1969-07-20T20:17:00.000Z
    D.of({year: 1984})           //=> 1984-01-01T00:00:00.000Z

    Rules:

    • numbers are treated as milliseconds since the unix epoch
    • strings are treated as ISO 8601 timestamps in UTC timezone
      • 'YYYY-MM-DD'
      • 'YYYY-MM-DDTHH:MM:SS'
      • 'YYYY-MM-DDTHH:MM:SS.SSSZ'
      • 'YYYYYY-MM-DDTHH:MM:SS.SSSZ'
    • DateDescriptor properties default to beginning-of-interval when unspecified
      • {year: 2000, date: 25} => '2000-01-25T00:00:00.000Z'
      • {year: 2000, month: 1, date: 14, hour: 12, minute: 45, second: 0, millisecond: 0} => '2000-02-14T12:45:00.000Z'

    With DateDescriptors note that all fields are UTC time so months are zero-indexed.

    Read more in the additional documentation.

    Transforming Dates

    add

    add :: UnitOfTime -> number -> Date -> Date
    add :: UnitOfTime -> number -> Date -> Date

    Increments the given date by the specified number of time units, and returns a new Date with the new value.

    add('month', 2, D.of({year: 2000}))  //=> 2000-03-01T00:00:00.000Z

    Supported time units:

    • millisecond
    • second
    • minute
    • hour
    • day
    • week
    • month
    • year

    Note: when incrementing by month or year, if the day of the month for the input date is greater than the number of days in the output month, the day of the month for the output date will be set to the last day in the output month.

    add('month', 1, D.of('2000-01-31'))  //=> 2000-02-29T00:00:00.000Z

    Read more in the additional documentation.

    subtract

    subtract :: UnitOfTime -> number -> Date -> Date
    subtract :: UnitOfTime -> number -> Date -> Date

    Decrements the given date by the specified number of time units, and returns a new Date with the new value.

    subtract('month', 2, D.of({year: 2000}))  //=> 1999-11-01T00:00:00.000Z

    Supported time units:

    • millisecond
    • second
    • minute
    • hour
    • day
    • week
    • month
    • year

    startOf

    startOf :: ResetableUnitOfTime -> Date -> Date
    startOf :: ResetableUnitOfTime -> Date -> Date

    Reset a date back in time to the start of the specified time unit and returns a Date with the new value.

    startOf('year', D.of('1911-05-25'))  //=> 1911-01-01T00:00:00.000Z

    Supported time units:

    • second
    • minute
    • hour
    • day
    • week
    • month
    • year

    Combining Dates

    distance

    distance :: UnitOfTime -> Date -> Date -> number
    distance :: UnitOfTime -> Date -> Date -> number

    Returns the number of time-units between the first date and the second.

    distance('month', D.of('1914-07-11'), D.of('1939-09-01'))  //=> 302

    Supported time units:

    • millisecond
    • second
    • minute
    • hour
    • day
    • week
    • month
    • year

    Accessing Dates

    get

    get :: AccessibleUnitOfTime -> Date -> Date
    get :: AccessibleUnitOfTime -> Date -> Date

    Returns the numeric value of the specified property of the supplied date.

    get('month', D.of('1945-11-05'))  //=> 10

    Supported time units:

    • millisecond
    • second
    • minute
    • hour
    • day
    • date
    • month
    • year
    • unix

    where unix resolves to the number of milliseconds since the unix epoch.

    Caveats

    If you cause a Date overflow or underflow, od will return an Invalid Date object. You can test for invalid dates with the following code

    declare invalidDate: Date
    if (Number.isNaN(invalidDate.getTime())) {
      // `invalidDate` is invalid
    }

    The decision not to check for overflow or underflow was explicitly made to uphold the project goals. To use od without throwing or producing overflow or underflow errors, consider wrapping with fp-ts.

    When an official wrapper exists, I'll post to it on this page.

    License

    ISC licensed

    Keywords

    Install

    npm i od

    DownloadsWeekly Downloads

    36

    Version

    4.0.5

    License

    ISC

    Unpacked Size

    48.3 kB

    Total Files

    47

    Last publish

    Collaborators

    • hamroctopus