od

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
  • Guides developers away from common pitfalls
• fast
  • As fast as you can get with the core libraries
• transparent
  • Uses standard JavaScript Date objects everywhere
• 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
  • On this very readme
• curried
  • All functions support partial-application
• dependency-free
  • Zero dependencies were used in the making of this library

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

• of: Create a new Date from existing information

• add: Add a time unit to a Date
• subtract: Subtract a time unit from a Date
• startOf: Wind a Date back to the start of specified time unit

• distance: Calculate the number of time-units between two dates

• get: Access one field of an existing Date

Creating Dates

of

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

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

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

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

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

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