Concerns and Decisions
Generally I design my software by listing my concerns and then making decisions. These usually form a journal, but lately, I've simply taken to creating a concerns and decisions document such as this one. Feel free email me at alan@prettyrobots.com to discuss your concerns and decisions regarding Timezone.
Timezones are policial, localized and arbitrary. The Olson zonefiles are not authorative. They are a best effort to record the constant, capricous changes to the calendar by nation states and provences.
This library aims to:
- Support all of the timezones in the Olson zonefiles for dates after 1970.
- Make writing timezone aware web applications easy.
This library aims to be an international library. Please help this American make sure your locale is just so.
We'll get there eventually, but I'm in no hurry to:
- Support timezones before 1970.
- Support sundials (pre 19th century).
The Olson zone files are accurate after 1970 and have historical timezone information prior to 1970, but you can only do so much.
JavaScript and databases like MySQL who have minimal timezone support. The idea is to make it easy to write your new web application and support timezones correctly.
Timezone does not:
- Extend the Date prototype, nor
- use a special structure.
Timezone has a single method that it exports. It is a magic method that formats if a date is the first parameter, and parsers if a string is the first parameter. There are methods attached to the one function that will get and set global properties. The properties are global.
Timezone will only ever be one function. If you want to wrap this in an object,
or use it to create a Date prototype extension, feel free, but it won't get
rolled back into Timezone.
It does not extend the Date prototype. You can tuck the timezone into a zone
property on the date, or you can pass in the zone as an option.
Timezone will supply a full blown date parser so you don't have to search elsewhere for date parsing.
Parsing like Perl's
DateManip.
Since we're implementing UNIX date, it would make sense to parse dates according
to UNIX date, but back in the day, when I was Perl programmer, I would forgo
JavaScript date pickers and simply feed the psychotic ramblings of the user to
ParseDate, and it would almost always do the right thing.
Timezone will supply a full blown date parser that uses UNIX date formats, so you don't have to search elsewhere for date formatting. The formatted dates will account for timezone.
Locale information is stored in a JSON file. Until I find a source of locale information to use, I'll create some handwritten locales for Germanic and Romance languages.
This is how I deal with my inner troll. That voice in the back of my head anticipating all the faults that the teeming hordes on the Internet will find.
This is kind of an angry section. It reflects my experience as a Java programmer with the Java community. These people have a great many shibbleths to argue. When you program Java there's a voice in the back of your head, anticipating the feedback about checked exceptions, Law of Demeter, encapsulation, black boxes, white boxes, etc.
As Node.js and CoffeeScript programmer, I find people unfailingly encouraging and cooperative, but I've still got a voice in my head, and here's how I deal with it.
You, sir, are a bad programmer who doesn't know what he's doing, and I am a better programmer than you, because I am able to see that:
You have global state ~ Yes, because there is only one set of timezones and
locales. You have a different notion of Europe/Berlin or cs_CZ? You think
your users are going to want tweek their very zh_CN? Fine, pass it in as
parameter.
You use synchronous I/O ~ In examples and IRL I'll use sync to slurp up JSON zone files and parse them, because it's a one time hit and it keeps the API from getting callbacky, for this little one time hit.
You didn't create an object hierarcy ~ There are alternatives if you really
want an extended Date object. This exists because I found that disquieting.
One function is wierd ~ I don't want to pollute the namespace. Also, UNIX date is one function that does it all. This library aspires to be as cool as all that.
If you want to take up one of these issues start from my response here. Please don't think that I'm defending my thesis. If you like the code, use it.