From 943623e1364754ec30810c0cdab1b60c1087201d Mon Sep 17 00:00:00 2001 From: Ferdinand Prantl Date: Mon, 10 Jun 2019 23:54:59 +0200 Subject: [PATCH] fix: Use valid JavaScript identifiers for exports in vanilla browser modules BREAKING CHANGE: Previous kebab-case keys in the `window` object changed to camelCase global vbariables. Usage of shims or tools loading UMD modules becomes easier. See the migration guide for more information. --- README.md | 6 ++- bin/create-timezone-data | 2 +- docs/API.md | 6 +-- docs/design.md | 2 +- docs/migration.md | 72 ++++++++++++++++++++++++++++++++++ docs/usage.md | 36 +++++++++-------- rollup.config.js | 20 +++++----- util/data-creator.js | 2 +- util/generate-browser-tests.js | 11 ++++-- 9 files changed, 120 insertions(+), 37 deletions(-) create mode 100644 docs/migration.md diff --git a/README.md b/README.md index 525115a..3bae546 100644 --- a/README.md +++ b/README.md @@ -17,6 +17,8 @@ Lightweight time zone listing and date converting. Intended for adding time zone * 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. +**Attention**: export identifiers in vanilla browser modules changed in the version 2.0.0. See the [migration guide] for more information. + ### Table of Contents - [Synopsis](#synopsis) @@ -83,6 +85,7 @@ In lieu of a formal styleguide, take care to maintain the existing coding style. ## Release History +* 2018-06-10 v2.0.0 Use proper identifiers in vanilla browser modules. * 2018-11-17 v1.8.0 Include time zone data for years 1970-2038. * 2018-11-17 v1.7.0 Include full time zone data separately loadable. * 2018-11-06 v1.6.0 Upgrade the time zone database to the version 2018g. @@ -96,7 +99,7 @@ In lieu of a formal styleguide, take care to maintain the existing coding style. ## License -Copyright (c) 2018 Ferdinand Prantl +Copyright (c) 2018-2019 Ferdinand Prantl Licensed under the MIT license. @@ -107,3 +110,4 @@ Licensed under the MIT license. [date-fns]: https://github.com/date-fns/date-fns [timeZone plugin]: https://github.com/prantlf/dayjs/blob/combined/docs/en/Plugin.md#timezone [date-fns-timezone]: https://github.com/prantlf/date-fns-timezone +[migration guide]: docs/migration.md diff --git a/bin/create-timezone-data b/bin/create-timezone-data index d8721c1..5019b60 100755 --- a/bin/create-timezone-data +++ b/bin/create-timezone-data @@ -13,7 +13,7 @@ commander.version(pkg.version) .option('-c, --as-cjs-module', 'format the time zone data as a CommonJS module') .option('-d, --as-amd-module', 'format the time zone data as an AMD module') .option('-m, --as-module', 'format the time zone data as a JavaScript module') - .option('-n, --umd-name ', 'UMD global export name, if not "timeZoneData"') + .option('-n, --umd-name ', 'UMD global export name, if not "timezoneData"') .option('-o, --output-file ', 'write the time zone data to a file') .option('-u, --as-umd-module', 'format the time zone data as an UMD module') .option('-o, --output-file ', 'write the time zone data to a file') diff --git a/docs/API.md b/docs/API.md index f7484d5..3050f8d 100644 --- a/docs/API.md +++ b/docs/API.md @@ -45,12 +45,12 @@ 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.8.0/dist/index.umd.js. +You can also load a specific version from CDN, for example: https://unpkg.com/timezone-support@2.0.0/dist/index.umd.js. ## Modules @@ -446,7 +446,7 @@ Options: -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" + -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 diff --git a/docs/design.md b/docs/design.md index 58d97a0..7d8ec49 100644 --- a/docs/design.md +++ b/docs/design.md @@ -1,6 +1,6 @@ # Design Concepts -The purpose of this library is to offer an efficient support for time zone handling in th esmallest package. +The purpose of this library is to offer an efficient support for time zone handling in the smallest package. * 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. diff --git a/docs/migration.md b/docs/migration.md new file mode 100644 index 0000000..a0edd2d --- /dev/null +++ b/docs/migration.md @@ -0,0 +1,72 @@ +# Migration from 1.x to 2.x + +Names of global variables that expose the exported objects in vanilla JavaScript modules changed. Basically, convert the kebab-case keys exposing the global objects to camelCase. For example: `window['timezone-support']` to `window.timezoneSupport`. + +Nothing else changed. File names of scripts in the `dist` directory did not change. The structure of objects exported from these files did not change either. The behaviour of exposed functions did not change. + +## Renamed Variables + +Names of global variables that expose the exported objects in vanilla JavaScript modules changed. They do not contain hyphens any more and they became valid JavaScript identifiers. It was necessary to satisfy tools, which integrate UMD modules via shims. + +| File name | Old object | New object | +| :-------------- | :-------------------------------- | :------------------------- | +| index | window['timezone-support'] | window.timezoneSupport | +| index-1900-2050 | window['timezone-support'] | window.timezoneSupport | +| index-1970-2038 | window['timezone-support'] | window.timezoneSupport | +| index-2012-2022 | window['timezone-support'] | window.timezoneSupport | +| lookup-convert | window['timezone-lookup-convert'] | window.timezoneSupport | +| data | window['timezone-data'] | window.timezoneData | +| data-1900-2050 | window['timezone-data-1900-2050'] | window.timezoneData | +| data-1970-2038 | window['timezone-data-1970-2038'] | window.timezoneData | +| data-2012-2022 | window['timezone-data-2012-2022'] | window.timezoneData | +| parse-format | window['timezone-parse-format'] | window.timezoneParseFormat | + +The `lookup-convert` file is meant to be used together with a `data*` file. The name of the object-exposing variable (`timezoneSupport`) can be the same as the one exposed from `index*` files. It allows for easier dependency modifications without additional code changes in dependency sources. + +The `data*` files are not meant to be used together; just one of them is supposed to be used with the `lookup-convert` file. The exposing variable name can be the same (`timezoneData`). It allows for easier swapping of data-files when having the exposing variable called always `timezoneData`. + +## Change Examples + +Replace keys that you used to consume objects exported from files in the `dist` directory: + +```js +const { populateTimeZones, findTimeZone, getZonedTime } = window['timezone-lookup-convert'] +populateTimeZones(window['timezone-data-1970-2038']) + +const berlin = findTimeZone('Europe/Berlin') +const inputDate = new Date('2018-09-01T09:19:17.276Z') +const berlinTime = getZonedTime(inputDate, berlin) +``` + +with the new keys: + +```js +const { populateTimeZones, findTimeZone, getZonedTime } = window.timezoneSupport +populateTimeZones(window.timezoneData) +// The rest of API remains the same. +const berlin = findTimeZone('Europe/Berlin') +const inputDate = new Date('2018-09-01T09:19:17.276Z') +const berlinTime = getZonedTime(inputDate, berlin) +``` + +And other old keys, for example: + +```js +const { findTimeZone, getZonedTime } = window['timezone-support'] +const { formatZonedTime } = window['timezone-parse-format'] + +const zonedTime = { year: 2018, month: 9, day: 2, hours: 10, minutes: 0, + zone: { abbreviation: 'CEST', offset: -120 } } +const displayTime = formatZonedTime(zonedTime, 'D.M.YYYY H:mm zZ') +``` + +with the new keys: + +```js +const { findTimeZone, getZonedTime } = window.timezoneSupport +const { formatZonedTime } = window.timezoneParseFormat +// The rest of API remains the same. +const zonedTime = { year: 2018, month: 9, day: 2, hours: 10, minutes: 0, + zone: { abbreviation: 'CEST', offset: -120 } } +const displayTime = formatZonedTime(zonedTime, 'D.M.YYYY H:mm zZ') +``` diff --git a/docs/usage.md b/docs/usage.md index 528d42f..b213b54 100644 --- a/docs/usage.md +++ b/docs/usage.md @@ -84,7 +84,7 @@ const { formatZonedTime } = require('timezone-support/dist/parse-format') const zonedTime = { year: 2018, month: 9, day: 2, hours: 10, minutes: 0, zone: { abbreviation: 'CEST', offset: -120 } } -const displayTime = formatZonedTime(zonedTime, 'D.M YYYY H:mm:ss Z') +const displayTime = formatZonedTime(zonedTime, 'D.M.YYYY H:mm:ss zZ') ``` See the function [formatZonedTime](./API.md#formatzonedtime) for more information. @@ -96,8 +96,8 @@ Some applications let their users freely configure, what date format will be use ```js const { parseZonedTime } = require('timezone-support/dist/parse-format') -const displayTime = '2.9. 2018 10:00 CET+02:00' -const zonedTime = parseZonedTime(displayTime, 'D.M YYYY H:mm:ss Z') +const displayTime = '2.9.2018 10:00 CET+02:00' +const zonedTime = parseZonedTime(displayTime, 'D.M.YYYY H:mm zZ') ``` See the function [parseZonedTime](./API.md#parsezonedtime) for more information. @@ -183,17 +183,17 @@ 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 - - + + @@ -202,13 +202,13 @@ Custom time zone data can be used if the module `lookup-convert` is loaded inste If you want to use the time zone data for years 2012-2022 published by this project, you can simplify your code by using a bundled package with both data and code. ```html - + @@ -238,7 +238,7 @@ See the function [populateTimeZones](./API.md#populatetimezones) for more inform Except for the time zone data for the three year spans bundled with this module, other data modules can be generated to customize the year span and thus the overall package size. There is a command line tool [`create-timezone-data`](./API.md#data-generator) for this included in this package. -For example, you can generate time zone data for years 1978-2028 and save it to the module `data-1978-2028.js` in the CommonJS format, which you wil bundle to your application: +For example, you can generate time zone data for years 1978-2028 and save it to the module `data-1978-2028.js` in the CommonJS format, which you will bundle to your application: ```sh create-timezone-data -c -o custom-data-1978-2028.js 1978 2028 @@ -253,10 +253,10 @@ const data = require('./data-1978-2028') populateTimeZones(data) ``` -Let us have alook, how the same would work in an application loading their assets directly in the browser. You would generate a UMD module instead: +Let us have a look, how the same would work in an application loading their assets directly in the browser. You would generate a UMD module instead: ```sh -create-timezone-data -u -o custom-data-1978-2028.js -n timeZoneData10782028 1978 2028 +create-timezone-data -u -o custom-data-1978-2028.js -n timezoneData10782028 1978 2028 ``` And then load them at the beginning of a plain JavaScript application: @@ -266,9 +266,9 @@ And then load them at the beginning of a plain JavaScript application: ``` @@ -280,7 +280,9 @@ Or load it in an application using AMD modules: diff --git a/rollup.config.js b/rollup.config.js index 6b4db16..2ae58c1 100644 --- a/rollup.config.js +++ b/rollup.config.js @@ -118,7 +118,7 @@ export default [ output: { file: 'dist/index.umd.js', format: 'umd', - name: 'timezone-support', + name: 'timezoneSupport', sourcemap: true }, plugins: [ @@ -131,7 +131,7 @@ export default [ output: { file: 'dist/index-1970-2038.umd.js', format: 'umd', - name: 'timezone-support', + name: 'timezoneSupport', sourcemap: true }, plugins: [ @@ -144,7 +144,7 @@ export default [ output: { file: 'dist/index-2012-2022.umd.js', format: 'umd', - name: 'timezone-support', + name: 'timezoneSupport', sourcemap: true }, plugins: [ @@ -157,7 +157,7 @@ export default [ output: { file: 'dist/index-1900-2050.umd.js', format: 'umd', - name: 'timezone-support', + name: 'timezoneSupport', sourcemap: true }, plugins: [ @@ -170,7 +170,7 @@ export default [ output: { file: 'dist/lookup-convert.umd.js', format: 'umd', - name: 'timezone-lookup-convert', + name: 'timezoneSupport', sourcemap: true }, plugins: [ @@ -183,7 +183,7 @@ export default [ output: { file: 'dist/data.umd.js', format: 'umd', - name: 'timezone-data', + name: 'timezoneData', sourcemap: true }, plugins: [ @@ -196,7 +196,7 @@ export default [ output: { file: 'dist/data-1970-2038.umd.js', format: 'umd', - name: 'timezone-data-1970-2038', + name: 'timezoneData', sourcemap: true }, plugins: [ @@ -209,7 +209,7 @@ export default [ output: { file: 'dist/data-2012-2022.umd.js', format: 'umd', - name: 'timezone-data-2012-2022', + name: 'timezoneData', sourcemap: true }, plugins: [ @@ -222,7 +222,7 @@ export default [ output: { file: 'dist/data-1900-2050.umd.js', format: 'umd', - name: 'timezone-data-1900-2050', + name: 'timezoneData', sourcemap: true }, plugins: [ @@ -235,7 +235,7 @@ export default [ output: { file: 'dist/parse-format.umd.js', format: 'umd', - name: 'timezone-parse-format', + name: 'timezoneParseFormat', sourcemap: true }, plugins: [ diff --git a/util/data-creator.js b/util/data-creator.js index f4b4b37..c151fdc 100644 --- a/util/data-creator.js +++ b/util/data-creator.js @@ -28,7 +28,7 @@ function formatUMDModule (content, umdName) { return `(function (global, factory) { typeof exports === 'object' && typeof module !== 'undefined' ? factory(exports) : typeof define === 'function' && define.amd ? define(['exports'], factory) : - factory(global.${umdName || 'timeZoneData'} = {}) + factory(global.${umdName || 'timezoneData'} = {}) } (this, (function (exports) { Object.assign(exports, ${content}) Object.defineProperty(exports, '__esModule', { value: true }) diff --git a/util/generate-browser-tests.js b/util/generate-browser-tests.js index 206827a..4285394 100644 --- a/util/generate-browser-tests.js +++ b/util/generate-browser-tests.js @@ -32,9 +32,14 @@ function formatFunctionImport (input) { throw new Error('Statement requiring the code module not found.') } const name = match[2] - const variable = name.startsWith('index') ? 'support' : name + let variable + if (name.startsWith('parse-format')) { + variable = 'ParseFormat' + } else { + variable = 'Support' + } const functionCodeLine = input.replace(importFunctionsExpression, - `const $1 = window['timezone-${variable}']`) + `const $1 = window.timezone${variable}`) const functionScriptElement = [ '' ] @@ -48,7 +53,7 @@ function formatDataImport (input) { } const name = match[2] const dataCodeLine = input.replace(importDataExpression, - `const $1 = window['timezone-${name}']`) + 'const $1 = window.timezoneData') const dataScriptElement = [ '' ]