[tz] New JavaScript/Node.js timezone compiler

Kerry Shetline kerry at shetline.com
Thu Jun 3 23:47:10 UTC 2021


I spoke about this new tz compiler a while back, when I released my @tubular/time date-time library, but the compiler was only at the level of a tool for personal use, without decent documentation or all of the features I’d want for a general-purpose utility.

At first this compiler only produced data for use with @tubular/time, but now it can output zoneinfo/zic binaries too. One nice feature is that this tool, by default, reaches right out to https://www.iana.org/time-zones/ for data, with no need to download a release before using the compiler.

There’s a JavaScript/TypeScript API and a CLI command. I’ll show the CLI command help, just so people can get an idea of the options available. Anyone can go to https://github.com/kshetline/tubular_time_tzdb for more info.

npm install -g @tubular/time-tzdb

Usage: tzc [options] [output_file_name_or_directory]

Downloads and compiles IANA timezone data, converting to text, zoneinfo binary
files, or @tubular/time-compatible data.

  -v, --version       output the version number
  -5, --systemv       Include the SystemV timezones from the systemv file by
                      uncommenting the commented-out zone descriptions.
  -b, --binary        Output binary files to a directory, one file per timezone
  -B, --bloat         Equivalent to the zic "--bloat fat" option.
  -f                  Filter out Etc/GMTxxx and other timezones that are either
                      redundant or covered by options for creating fixed-offset
  -i                  Include leap seconds in binary files.
  -j, --javascript    Output JavaScript instead of JSON.
  --large             Apply presets for "large" timezone definitions.
  --large-alt         Apply presets for "large-alt" timezone definitions.
  --list              List available tz database versions.
  -m                  Round all UTC offsets to whole minutes.
  -n, --no-backward   Skip the additional aliases in the backward file.
  -o                  Overwrite existing file/directory.
  -q                  Display no progress messages, fewer warning messages.
  -R, --rearguard     Rearguard mode (skip vanguard features like negative
  -r                  Remove 'calendar rollbacks' from time zone transitions --
                      that is modify time zone data to prevent situations
                      where the calendar date goes backwards as well as the
                      hour and/or minute of the day.
  -p, --packrat       Add additional timezones from the backzone file.
  -s <zone-id>        ID/name for a single timezone/region to be rendered.
  --small             Apply presets for "small" timezone definitions.
  -t, --typescript    Output TypeScript instead of JSON.
  --text              Output (somewhat) human-readable text
  -u, --url <url>     URL or version number, such as '2018c', to parse and
                      Default: https://www.iana.org/time-zones/repository/tzdata-latest.tar.gz
  -V, --vanguard      Vanguard mode (use vanguard features like negative DST).
  -y <year-span>      <min_year,max_year> Year range for explicit time zone
                      Default: 1850,2050
  -z <zone-info-dir>  Validate this tool's output against output from the
                      standard zic tool stored in the given directory.
                      (Validation is done before applying the -r option.)
  -h, --help          display help for command
  -,                  Use dash by itself to output to stdout.

More information about the tz mailing list