README
date-str
Safely work with ISO-8601 dates in TypeScript
Working with the concept of "just a date" in JavaScript can be a challenge, as the built-in Date
type actually represents a date and a time. When you start making assumptions involving time zones, properly extracting the correct date from the Date
object can lead to errors. The best solution I've found is, when I need to work with a date, to store it as an ISO-8601 date string.
⚠️ Note: Although YYYYMMDD
is technically a valid date representation according to ISO-8601, this library only works with dates of the format YYYY-MM-DD
.
This package adds a branded type representing an ISO-8601 date. It is based on a these excellent articles published on the Atomic Object Blog:
- DateStr – A Strongly-Typed Date String for TypeScript
- Flavoring: Flexible Nominal Typing for TypeScript
Installation
npm install date-str
Usage
ES Module
import { DateStr, isDateStr, toDateStr } from 'date-str';
CommonJS
const { DateStr, isDateStr, toDateStr } = require('date-str');
Example
interface Person {
name: string,
birthday: DateStr
}
const ralph: Person = {
name: 'Ralph',
birthday: toDateStr(new Date())
}
ralph.birthday = toDateStr('2012-10-19');
function datePrinter(date: DateStr | Date) {
if (isDateStr(date)) {
console.log(date);
} else {
console.log(date.toISOString())
}
}
This package does not support any sort of date arithmetic, it simply handles labeling values as valid DateStr
instances. If you are working with these DateStr
types and need to perform any sort of parsing or manipulation, consider passing them into Luxon's DateTime.fromISO function. The resulting DateTime
values can be manipulated and then converted back into a DateStr
with Luxon's DateTime#toISODate function:
import { DateTime } from 'luxon';
import { toDateStr } from 'date-str';
const today = toDateStr(new Date()); // DateStr
const todayDateTime = DateTime.fromISO(today); // DateTime
const tomorrowDateTime = todayDateTime.plus({ days: 1 }); // DateTime
const tomorrow = toDateStr(tomorrowDateTime.toISODate()); // DateStr
API
isDateStr(str: unknown) => date is DateStr
Test if a value is a valid date string of the format YYYY-MM-DD
.
toDateStr(date: string | Date) => DateStr
Parses a date string or JS Date object into a DateStr. Throws a TypeError
if the date is not a valid value. If date
is a string, it must be of the format YYYY-MM-DD
.