ymd-object v0.0.10
Preface
I recommend using dayjs for your project.
While I may continue to expand ymd-object
for fun, I made it as a minimal alternative for one feature that Moment.js made convenient for me. This was before I knew about dayjs.
If you want to use or contribute to ymd-object
anyways, go right ahead!
What's ymd-object
?
ymd-object
is a tiny library which defines a handy class called YMD
which stores a simple date (no time components).
Why?
Confusing results may arise when using the standard Date object for dates (e.g. new Date("2020-01-01")
).
If you construct a normal Date
as shown above, you sometimes find yourself facing off by one errors when you try to figure out what day it is, depending on your timezone.
For example, (new Date("2020-01-01")).getDate()
may return 31
.
In this case, the correct solution would have been to use getUTCDate
instead of getDate
.
In many situations it would be nicer to not think about the time components at all. The YMD
class is here to make it harder to make mistakes related to time zones. It stores the year month and date as plain old numbers and provides some common formatting options and a toDate
function which creates a date set to midnight UTC or local time (UTC by default).
In summary, this package just helps you get the date right.
How to use ymd-object
install with npm
npm install ymd-object
import YMD
import { YMD } from "ymd-object";
or with require
const { YMD } = require("ymd-object");
Create a YMD object
from a string formatted like YYYY-MM-DD
const myDate = new YMD("2020-01-31");
or from a simple object
const myDate = new YMD({y: 2020, m: 1, d: 31});
or from a vanilla js Date (optional 2nd parameter utc defaults to true)
const myDate = YMD.fromDate(someDate); // uses UTC date of someDate
const myDate = YMD.fromDate(new Date(), false); // uses current local date
or using current date (optional 2nd parameter utc defaults to true)
const myDate = YMD.today(); // uses current UTC date
const myDate = YMD.today(false); // uses current local date
Get or set year / month / date
const { y, m, d } = myDate; // deconstruct a YMD object
myDate.y = 1999; // change a YMD object
myDate.setFromString("1999-10-20"); // change date using a string
myDate.setFromDate(someDate); // change date using a vanilla js Date (UTC date)
myDate.setFromDate(someDate, false); // change date using a vanilla js Date (local date)
Convert to a vanilla js Date (set at midnight UTC unless optional utc param is false)
myDate.toDate(); // 2020-01-31T00:00:00.000Z
myDate.toDate().getUTCDate(); // 31
myDate.toDate(false); // 2020-01-31T08:00:00.000Z (for me; depends on time zone)
myDate.toDate(false).getDate(); // 31 (local date)
Formatting
ymd-object
provides some minimal date formatting options
myDate.toString(); // returns "2020-01-31"
myDate.toString("MDY"); // returns "01/31/2020"
myDate.toString("MDY_NO_PAD"); // returns "1/31/2020"
myDate.toString("LONG"); // returns "Fri, 31 Jan 2020"
You can also simply combine the static "from" methods with the "toString" method if you don't want to keep the YMD object around:
YMD.fromString("2020-01-31").toString("LONG"); // returns "Fri, 31 Jan 2020"
The formatting feature may be expanded in the future to allow formatting with special strings to define the format e.g. maybe you are weird and like hashtags instead of dashes so you would use
myDate.toString("YYYY#MM#DD"); // DOESN'T WORK YET!