diff --git a/README.md b/README.md index b31db29..9cd83e7 100644 --- a/README.md +++ b/README.md @@ -11,10 +11,10 @@ Lightweight time zone listing and date converting. Intended for adding time zone support to high-level date libraries, but also for direct application usage. -* Tiny code base - 3.5 KB minified, 1.5 KB gzipped. Do not pack unnecessary weight in your application. -* Packed time zone data - 178 KB minified, 22.5 KB gzipped. Single time zones are unpacked on demand. -* Even smaller version with limited, 2012-2022 timezone data - 31 KB minified, 8K gzipped. -* Generated from the official time zone database version 2018e. Canonical time zone names, aliases, UTC offsets, and daylight-saving time changes. +* Tiny code base - 4.6 KB minified, 1.7 KB gzipped. Do not pack unnecessary weight in your application. +* Packed time zone data - 923 KB minified, 33.3 KB gzipped. Single time zones are unpacked on demand. +* Smaller bundles with limited data - 1900-2050 (204 kB minified, 25.2 kB gzipped) and 2012-2022 (31.2 KB minified, 8.2 kB gzipped). +* Generated from the official time zone database version 2018g. Canonical time zone names, aliases, UTC offsets, and daylight-saving time changes. * Minimal interface for time zone lookup and conversions. Parsing, formatting and manipulating dates is usually the task for a higher-level date library. ### Table of Contents @@ -83,6 +83,7 @@ In lieu of a formal styleguide, take care to maintain the existing coding style. ## Release History +* 2018-11-06 v1.6.0 Upgrade the time zone database to the version 2018g. * 2018-10-08 v1.5.5 Fix compatibility with IE. Thanks, [Andrii](https://github.com/AndriiDidkivsky)! * 2018-10-06 v1.5.0 Add TypeScript export declarations. * 2018-09-30 v1.4.0 Add limited data for just the current decade - years 2012-2022. diff --git a/docs/API.md b/docs/API.md index 32ca955..44f884d 100644 --- a/docs/API.md +++ b/docs/API.md @@ -49,7 +49,7 @@ Load the main module in the browser with plain JavaScript: ``` -You can also load a specific version from CDN, for example: https://unpkg.com/timezone-support@1.5.5/dist/index.umd.js. +You can also load a specific version from CDN, for example: https://unpkg.com/timezone-support@1.6.0/dist/index.umd.js. ## Modules @@ -430,5 +430,34 @@ const berlinTime = setTimeZone(date, berlin, { useUTC: true }) `Date` objects in the last two scenarios are initialized only for formatting or conversion purposes, because other methods, than the date part getters, deliver wrong results. Such "invalid" `Date` instances should exist only temporarily in a restricted scope. They should not be shared widely in the application to prevent mistakes from happening. The local time in a valid `Date` object has to match the UTC time maintained by the same object. +## Data Generator + +If you want to [limit the time zone data](#limit-the-loaded-time-zone-data) to improve performance of your application by reducing the size of the JavaScript code, you can use the command-line tool included in this package: + +```txt +Usage: create-timezone-data [options] + +Options: + -V, --version output the version number + -a, --all-years includes all available years + -c, --as-cjs-module format the time zone data as a CommonJS module + -d, --as-amd-module format the time zone data as an AMD module + -m, --as-module format the time zone data as a JavaScript module + -n, --umd-name UMD global export name, if not "timeZoneData" + -o, --output-file write the time zone data to a file + -u, --as-umd-module format the time zone data as an UMD module + -o, --output-file write the time zone data to a file + -h, --help output usage information + +Time zone data are printed on the standard output as JSON by default. + +Examples: + + $ create-timezone-data 2012 2022 + $ create-timezone-data -m -o custom-data.js 1970 2038 +``` + +The module generated by this tool exposes a data object as a default export, which is expected bu the function[populatePluralData](#populatepluraldata). + [time object]: ./design.md#time-object [IANA time zones]: https://en.wikipedia.org/wiki/List_of_tz_database_time_zones diff --git a/docs/design.md b/docs/design.md index 0a8eb14..58d97a0 100644 --- a/docs/design.md +++ b/docs/design.md @@ -4,7 +4,7 @@ The purpose of this library is to offer an efficient support for time zone handl * Lightweight - nothing else is included. Thus serving well for other date & time libraries, but also for applications, which do not manipulate dates. * Tiny - use packed time zone data, unpacked on demand. Compromise between loading time and being ready to use immediately. -* Reliable - generated from the fresh official time zone database version 2018e. Canonical time zone names, aliases, UTC offsets, and daylight-saving time changes. +* Reliable - generated from the fresh official time zone database version 2018g. Canonical time zone names, aliases, UTC offsets, and daylight-saving time changes. * Customizable - named exports and functions divided to separate modules allow tree-shaking. Alternative time zone data can be supplied to reduce the library size. ### Table of Contents diff --git a/docs/usage.md b/docs/usage.md index 0ad9bc5..3d038a0 100644 --- a/docs/usage.md +++ b/docs/usage.md @@ -170,18 +170,20 @@ See the functions [convertDateToTime](./API.md#convertdatetotime) and [convertTi ## Limit the loaded time zone data -The full time zone data cover all dates between 1970 and 2018. If you process dates only from a limited time period, you can initialize this library with a subset of time zone data and decrease the loading time of your application. For example, the difference between the full time zone data and the data for this decade only: +If you process dates only from a limited time period, you can initialize this library with a subset of the [IANA time zone database] and decrease the loading time of your application. For example, the difference between the full time zone data and the data for this decade only: -``` -Data for 1970-2018: 178 KB minified, 22.5 KB gzipped +```txt +Full IANA TZ data: 923 KB minified, 33.3 KB gzipped +Data for 1900-2050: 200 KB minified, 23.3 KB gzipped +Data for 1970-2018: 106 KB minified, 13.1 KB gzipped Data for 2012-2022: 27 KB minified, 6.5 KB gzipped ``` Custom time zone data can be used if the module `lookup-convert` is loaded instead of the default `index` module. ```html - - + + + ``` +The following data modules ara published within this project: + +```txt +dist/data.umd.js +dist/data-1900-2050.umd.js +dist/data-2012-2022.umd.js +``` + +The following complete (code+data) modules ara published within this project: + +```txt +dist/index.umd.js +dist/index-1900-2050.umd.js +dist/index-2012-2022.umd.js +``` + See the function [populateTimeZones](./API.md#populatetimezones) for more information. + +[IANA time zone database]: https://www.iana.org/time-zones