tz.js - Library for working with timezones in JavaScript

Written in 2011 by L. David Baron [email protected]

To the extent possible under law, the author(s) have dedicated all

copyright and related and neighboring rights to this software to the

public domain worldwide. This software is distributed without any

warranty.

You should have received a copy of the CC0 Public Domain Dedication

along with this software. If not, see

http://creativecommons.org/publicdomain/zero/1.0/.

This is tz.js, a library for working with time zones from JavaScript.

It incorporates data from the tz database (also known as the Olson database), available at http://www.iana.org/time-zones (with the unofficial repository at https://github.com/eggert/tz ) and in the public domain.

Files currently in the distribution are:

build.py

Python script to produce all output (tz.js and tests).

build-tests.py

Python script to produce the test output (invoked by build.py).

build-tz.py

Python script to build the tz database.

compiled-to-json.py

A working tool for converting the binary timezone data format (see
tzfile(5), available in the tzcode* file in the tz database) into
JSON suitable for use in tz.js.

get-latest-tz-release.py

A tool to download (into this source directory) the latest versions
of the tz database and print their names.

source-to-json.py

Work in progress on a tool to replace compiled-to-json.py (at some
time in the indefinite future) with data allowing the time zone data
to be represented more compactly.

tz.js.in

The source to tz.js, to be compiled using build.py.

The JavaScript API that this library provides is documented at the
end of the tz.js.in file.

A few notes about the goals of this library:

This library intentionally does not support times prior to 1970. This is both because it is unlikely to be useful, and because the timezone database does not split zones if there were differences within them prior to 1970, as described in http://www.iana.org/time-zones/repository/tz-link.html . This means that while the information from the zone data is intended to be valid for the reference city prior to 1970, it is often not valid throughout the zone. Therefore data from the tz database about transitions prior to 1970 have been removed to save space, and times prior to 1970 are intentionally rejected.

Build instructions:

• You probably need to build on a Unix-ish system (I use Ubuntu Linux; Mac OS X probably also works). (For building the tests correctly, a 'date' command that deals with a TZ environment variable containing file paths is required.)

• Note that the build process retrieves the latest version of the timezone database over the network.

• Run build.py, and the output appears in the output/ subdirectory.

• To properly serve tz.js.gz on an Apache server, you probably need this in an .htaccess file: <FilesMatch .js.gz$> ForceType text/javascript AddDefaultCharset UTF-8 AddEncoding x-gzip gz

• The output will need to be regenerated from new versions of the
  Time Zone Database in order to continue having correct time zone
  data. New versions tend to come out about 10-20 times per year.
  See http://www.iana.org/time-zones .

Further notes:

• The resulting tz.js (produced by build.py), or (preferably) its compressed form tz.js.gz, is the only file you need to serve to serve the library. With the current (2016i) copy of the tz database, the gzip-compressed tz.js is 54,285 bytes, which includes all of the necessary data from the tz database.

• The documentation of the actual JS API is at the end of tz.js.in.