od

Oh dear, another date library

Usage no npm install needed!

<script type="module">
  import od from 'https://cdn.skypack.dev/od';
</script>

README

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
    • 2 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/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