@js-joda/timezone 2.26.0 → 3.0.0

package/README.md

@@ -9,7 +9,8 @@
 ## Motivation
 
 Implementation of the js-joda ZoneRulesProvider, providing the 
-bindings to the iana tzdb, using latest zone file generated by moment-timezone
+bindings to the iana tzdb. The zone data is generated from the official IANA releases by
+[@js-joda/tzdb-builder](../tzdb-builder) in this repository.
 
 The package doesn't export anything but it still has to be imported for side effects.
 
@@ -76,16 +77,44 @@ Install joda using npm
     </script>
 
 ## Reducing js-joda-timezone file size
-If you don't need all the historical data that @js-joda/timezone provides, you can instead use one of the reduced files ize builds:
+If you don't need all the historical data that @js-joda/timezone provides, you can instead use one of the reduced file size builds.
+Each one contains the data for a range of years relative to the year the data was generated.
+The years below are for the data generated in 2026; the sizes are of the minified browser build.
 
-* `js-joda-timezone-10-year-range.js` covers +- five years from the current version's release
-* `js-joda-timezone-1970-2030.js` covers from 1970 to 2030
-* `js-joda-timezone-2012-2022.js` covers from 2012 to 2022 // deprecated, will be removed in future releases
-* `js-joda-timezone-2017-2027.js` covers from 2017 to 2027 
+| Bundle | Covers | Years (2026 data) | Size (min / gzip) |
+|---|---|---|---|
+| `js-joda-timezone` | all years | all | 708 KB / 35 KB |
+| `js-joda-timezone-300-year-range` | ± 150 years | 1876 to 2176 | 331 KB / 29 KB |
+| `js-joda-timezone-lifetime-range` | - 120 / + 15 years | 1906 to 2041 | 170 KB / 24 KB |
+| `js-joda-timezone-60-year-range` | ± 30 years | 1996 to 2056 | 83 KB / 12 KB |
+| `js-joda-timezone-10-year-range` | ± 5 years | 2021 to 2031 | 30 KB / 8 KB |
+| `js-joda-timezone-4-year-range` | ± 2 years | 2024 to 2028 | 27 KB / 8 KB |
 
-To use one of these, just change your import path to the following format:
+The `-lifetime-range` bundle covers the birth dates of all living people plus 15 years ahead, e.g. for websites that
+handle birth dates. Note that a birth date stored as a `LocalDate` needs no time zone data at all; the bundle is only
+needed when you convert birth date-times between zones or determine today's date in a zone.
 
-    import '@js-joda/timezone/dist/js-joda-timezone-1970-2030'
+Every bundle comes as CommonJS (`.js`), ES module (`.esm.js`) and minified UMD for the browser (`.min.js`).
+To use one of them, change the import path, e.g.:
+
+    import '@js-joda/timezone/dist/js-joda-timezone-10-year-range'
+
+or in the browser:
+
+    <script src="./packages/timezone/dist/js-joda-timezone-10-year-range.min.js"></script>
+
+Things to keep in mind when you pick a range:
+
+* Outside its range, a reduced bundle gives **wrong offsets without any error**: before the range it uses the
+  zone's first offset in the range, after it the zone's last one. For example, with the 4-year bundle,
+  `Europe/Berlin` in July 2035 resolves to `+01:00` instead of `+02:00`. Choose a range that covers every
+  date your application converts, including stored historical dates and future dates.
+* The ranges move with the data: they are relative to the year a release's data was generated, not to the
+  year your application runs. An older `@js-joda/timezone` version covers fewer years into the future.
+* All bundles contain the same zone IDs; zones whose rules are identical within the range are shared as links.
+
+The fixed-year bundles `js-joda-timezone-1970-2030`, `-2012-2022` and `-2017-2027` have been removed,
+use the `-lifetime-range` or `-300-year-range` bundle (with the 2026 data, both cover 1970 onwards; see the table above), the `-60-year-range` bundle or the full bundle instead.
 
 ## Implementation details
 
@@ -98,6 +127,7 @@ To use one of these, just change your import path to the following format:
 
 * The author of joda time and the lead architect of the JSR-310 is Stephen Colebourne.
 
-* The json versions of the iana tzdb are imported from and generated with [moment-timezone](https://github.com/moment/moment-timezone).   
+* The json versions of the iana tzdb are generated with [@js-joda/tzdb-builder](../tzdb-builder) from the [IANA time zone database](https://www.iana.org/time-zones).
+  The packed data format and its unpacking code originate from [moment-timezone](https://github.com/moment/moment-timezone) (MIT license).