plain-date
A simple, light-weight model for date handling in JavaScript
Module System
The package includes both an ESM module (browser-compatible) and CJS modules (npm-compatible).
plain-date
is written in node-style and converted to ESM for wider distribution. The default is therefore the node variant.
CJS (node)
require('plain-date')
gives you the PlainDate class.
require('plain-date/calculation')
gives you helper functions.
const PlainDate = const startOfMonth weekNumber =
ESM (browser)
index.mjs
yields the PlainDate
class as its default export and
the helper functions as named exports.
API
Table of Contents
- PlainDate
- PlainDate/3_parameters
- PlainDate/2_parameters
- PlainDate/1_parameter
- daysBetween
- startOfMonth
- endOfMonth
- startOfWeek
- endOfWeek
- weekNumber
PlainDate
PlainDate objects represent calendar dates or months. They focus on ease of use and are very light in comparison with JavaScript's native Date type.
They have a small set of properties, are immutable, and every date can only ever exist once.
If you try to create a new PlainDate object with a date that has previously been created, you will receive that pre-existing PlainDate object.
Additionally, PlainDate objects can be intuitively compared.
PlainDate objects can be constructed with one to three parameters. Behaviour for unexpected inputs is not defined. In order to stay light-weight, there is no intelligent type checking.
Type: Object
Properties
Examples
'2019-04-01' === '2019-04-01' // => true
'2019-04-01' < '2019-04-01' // => false
'2019-04-01' < '2019-04-11' // => true
'2019-04-01' > '2019-04-11' // => false
getNativeDate
Creates a new equivalent Date
object.
Multiple calls yield multiple distinct objects.
Returns Date
getComplexDate
Returns Date
Meta
- deprecated: Use
getNativeDate
instead
toString
Replaces each token in the given string by the appropriate string representation of the related data:
- YYYY: full year-number.
- YY: last two digits of year.
- MM: zero-padded two-digit month.
- DD: zero-padded two-digit date.
Defaults to the ISO format.
Parameters
format
string (optional, default'YYYY-MM[-DD]'
)
Returns string
valueOf
Enables fast comparison via <
and >
.
Returns number
PlainDate/3_parameters
Parameters
Examples
2019 4 1
'2019' '04' '01'
PlainDate/2_parameters
Parameters
Examples
2019 4
'2019' '4'
PlainDate/1_parameter
Parameters
Examples
'2019-04-01'
'2019-04'
201931
year: 2019 month: 4
daysBetween
Parameters
Returns number Difference between both dates, in days.
startOfMonth
Parameters
given
PlainDate
Returns PlainDate The first of the same month.
endOfMonth
Parameters
given
PlainDate
Returns PlainDate The last of the same month.
startOfWeek
Parameters
Returns PlainDate The first of the same week.
endOfWeek
Parameters
Returns PlainDate The last of the same week.
weekNumber
Parameters
given
PlainDate
Returns number The number of the week within the current year, as per ISO 8601.