local-date
    TypeScript icon, indicating that this package has built-in type declarations

    2.0.6 • Public • Published

    LocalDate

    Replacement of Date for dealing with dates independent of timezone.

    Why

    To avoid some:

    And some:

    More seriously

    JavaScript Date is a representation of a point in time (timestamp). The question is: "a point in time where?".

    The problem with Date is that it always applies the user's current timezone to any parsed ISO date.

    This can be a serious issue when you're dealing with dates that should be completely agnostic of time like birthdates or expiration dates.

    // GMT -05:00 (New York)
    const date = new Date('1991-06-04');
    date.getDate(); // -> 3 (Date always applies user's timezone!)

    LocalDate and LocalDateTime replace the parser of Date with a simpler and stricter one which will consider only the date part (or the date + time parts), and conceptually adapt the timezone to it instead of the opposite.

    // GMT -05:00 (New York)
    const localDate = new LocalDate('1991-06-04');
    localDate.getDate(); // -> 4 (LocalDate always keeps the right year, month and day)
     
    // Under the hood
    new LocalDate('1991-06-04') == new Date(1991, 5, 4);

    Install

    yarn add local-date
    

    Browser Support

    LocalDate requires Reflect and Array.from from ES6. If you need to support pre-es6 browsers (like IE), you can import the two polyfills directly from local-date:

    import 'local-date/lib/polyfills/reflect';
    import 'local-date/lib/polyfills/array-from';

    Usage

    LocalDate and LocalDateTime extend Date so they reflect its API for most things. The only parts that change are the parser and the formatter toISOString.

    To help users check wether a string is a valid ISO date or not, LocalDate and LocalDateTime have also a static method test.

    Parser

    There are three possible ways to instantiate a LocalDate (LocalDateTime):

    1. ISO date (datetime) string
    2. no argument
    3. another LocalDate (LocalDateTime) instance

    1) ISO date

    This is the standard way to instantiate a LocalDate: by passing it an ISO date string. An ISO date is formatted as YYYY-MM-DD and doesn't contain any timezone.

    const localDate = new LocalDate('2016-05-20');
     
    localDate.getFullYear(); // -> 2016 (timezone independent!)
    localDate.getMonth(); // -> 4 (timezone independent!)
    localDate.getDate(); // -> 20 (timezone independent!)

    Similarly, with a LocalDateTime:

    const localDateTime = new LocalDateTime('2016-05-20T10:10:42');

    2) no argument

    new LocalDate() (new LocalDateTime()) will return a LocalDate (LocalDateTime) containing the current date for the user's timezone (internally it uses new Date())

    3) another LocalDate (LocalDateTime) instance

    This method is useful if you need to clone an instance of LocalDate (LocalDateTime):

    const localDate = new LocalDate('2016-05-20');
    const clonedLocalDate = new LocalDate(localDate);
     
    clonedLocalDate.getFullYear(); // -> 2016 (same as localDate!)
    clonedLocalDate.getMonth(); // -> 4 (same as localDate!)
    clonedLocalDate.getDate(); // -> 20 (same as localDate!)

    toISOString

    LocalDate overwrites the default toISOString function in order to return an ISO date instead of an ISO date-time:

    const localDate = new LocalDate('2016-05-20');
    const date = new Date('2016-05-20');
     
    localDate.toISOString(); // -> "2016-05-20" (only the "date" and timezone independent!)
    date.toISOString(); // -> ""2016-05-20T00:00:00.000Z"" (it contains the time as well and is therefore timezone dependent)

    test

    To check if a string is a valid ISO date or not, you can use the static method LocalDate.test (LocalDateTime.test):

    LocalDate.test('2016-05-20'); // -> true
    LocalDate.test('2016-05-20T00:00:00.000Z'); // -> false
    LocalDateTime.test('2016-05-20T00:00:00'); // -> true
    LocalDateTime.test('2016-05-20T00:00:00.000'); // -> true
    LocalDateTime.test('2016-05-20T00:00:00.000Z'); // -> false

    Install

    npm i local-date

    DownloadsWeekly Downloads

    107

    Version

    2.0.6

    License

    MIT

    Unpacked Size

    24.6 kB

    Total Files

    11

    Last publish

    Collaborators

    • federico.ercoles
    • gabro
    • veej
    • giogonzo
    • tpetrucciani
    • aslug
    • malpenzibo