dbaron / tz.js

# 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
</FilesMatch>

  * 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.