dayjs feat: add parse zone plugin

Closes https://github.com/iamkun/dayjs/issues/651

I'm opening this PR based on the discussion in the linked issue above. This is something that affects many people as timezone is a complicated topic.

Example scenarios are:

use the date timezone in format, rather than converting to the local one
do calculations in the provided format, rather than converting to the local one
display date and times with the original location in travel websites, rather than the user location (it confuses customers)

Example usage:

import dayjs from "dayjs";
import parseZone from "dayjs/plugins/parseZone";

dayjs.extend(parseZone);

const parsedDate = dayjs.parseZone("2016-12-21T07:01:21-08:00");

expect(parsedDate.format("MMMM D, YYYY, h:mm A")).toBe("December 21, 2016, 7:01 AM");

Sep 12 '22 16:09 LucaColonnello

@iamkun let me know if you need me to do anything else, or add docs, I'm happy to progress this quickly. Feel free to suggest more tests if you think anything here has not been accounted for.

Having this plugin as part of dayjs, I think we would be able to catch problems and benefit from the work people can put in OSS, rather than copying and pasting this code everywhere like the issue seem to imply...

Sep 12 '22 16:09 LucaColonnello

@iamkun

Sep 12 '22 20:09 abdirahmanjama

I think we're just going to publish this internally to use as we need it, but I'll leave the PR open hoping eventually it will get merge or reviewed :)

Sep 15 '22 17:09 LucaColonnello

@vronifuchsberger @abdirahmanjama guys, any ETA on when these changes will be released? it's a big pain :(

Oct 25 '22 14:10 Va1

not a maintainer, so unfortunately can't help you getting this in - we ended up publishing it internally in our company and re-use it in our repos until this (hopefully) get's merged 😄

Oct 25 '22 15:10 vronifuchsberger

It would be amazing to have this released. For now, I will also try to use it internally :) Thank you for your effort guys!

Dec 16 '22 18:12 poush

This looks awesome!

Dec 18 '22 04:12 wh1t3h47

Thank you all! Please release this 🤕

Feb 22 '23 13:02 akkayaburak

really looking for this one.

Feb 22 '23 14:02 guyschlider

This is an essential feature for a library trying to be a replacement for moment! I'm going to have to use this internally until this is included in an official release.

Mar 31 '23 15:03 peter2gossell

Would love to have this in dayjs! One thing I noticed when trying this out (which might well be a bug in the utc or timezone plugins) is that offsetName() doesn't render the result I expect:

const str = '2018-11-13T14:54:59Z'

const value = dayjs.parseZone(str)

expect(value.offsetName()).toEqual('UTC') // <-- this fails, it is my local timezone (currently GMT+1)
expect(value.format()).toEqual(str)