timezones-ical-library 1.11.1 → 2.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (12) hide show
  1. package/Readme.md +92 -76
  2. package/dist/cjs/index.js +7 -209
  3. package/dist/cjs/package.json +3 -1
  4. package/dist/mjs/index.js +7 -209
  5. package/dist/mjs/package.json +3 -1
  6. package/dist/tzlib.js +8 -208
  7. package/package.json +12 -19
  8. package/test/load-commonjs.cjs +32 -3
  9. package/test/load-module.mjs +32 -3
  10. package/test/tests.js +55 -14
  11. package/dist/cjs/.eslintrc.json +0 -1
  12. package/test/.eslintrc.json +0 -7
package/Readme.md CHANGED
@@ -1,17 +1,17 @@
1
- ![Add to Calendar TimeZone iCal Library](https://github.com/add2cal/timezones-ical-library/blob/main/readme-header.png?raw=true)
1
+ ![Add to Calendar Time Zone iCal Library](https://github.com/add2cal/timezones-ical-library/blob/main/readme-header.png?raw=true)
2
2
 
3
- [![Codacy Grade](https://img.shields.io/codacy/grade/aa298c980fa4459a9f7a386c8f8dc35f?style=for-the-badge)](https://app.codacy.com/gh/add2cal/timezones-ical-library/dashboard)
4
3
  [![Build Status](https://img.shields.io/github/actions/workflow/status/add2cal/timezones-ical-library/npm-publish.yml?style=for-the-badge)](https://github.com/add2cal/timezones-ical-library/actions/workflows/npm-publish.yml)
5
4
  [![npm Installations](https://img.shields.io/npm/dt/timezones-ical-library?label=npm%20Installations&style=for-the-badge)](https://www.npmjs.com/package/timezones-ical-library)
6
5
  [![GitHub license](https://img.shields.io/github/license/add2cal/timezones-ical-library?style=for-the-badge)](https://github.com/add2cal/timezones-ical-library/blob/main/LICENSE)
7
6
 
8
7
  <br />
9
8
 
10
- # Add to Calendar TimeZones iCal Library
9
+ # Add to Calendar Time Zones iCal Library
11
10
 
12
- The tool to convert the [IANA (formerly Olson) time zone database files](http://www.iana.org/time-zones) into VTIMEZONE blocks, compatible with the iCalendar specification (RFC2445).
11
+ Convert the [IANA (formerly Olson) time zone database files](http://www.iana.org/time-zones) into VTIMEZONE blocks, compatible with the iCalendar specification (RFC2445).
13
12
 
14
- It is based on the awesome tool by Damon Chaplin ([github.com/libical/vzic](https://github.com/libical/vzic)), but only provides the VTIMEZONE part to easily put this into any other iCal generator (like the [add-to-calendar-button](https://github.com/add2cal/add-to-calendar-button)). It is built to be used standalone or as JavaScript module, hosted as npm package.
13
+ It is based on [vzic](https://github.com/libical/libical/tree/master/vzic), but only provides the VTIMEZONE part to easily put this into any other iCal generator (like the [add-to-calendar-button](https://github.com/add2cal/add-to-calendar-button)).
14
+ It is built to be used standalone, via API, or as JavaScript module, hosted as npm package.
15
15
 
16
16
  <br /><br />
17
17
 
@@ -21,94 +21,107 @@ It is based on the awesome tool by Damon Chaplin ([github.com/libical/vzic](http
21
21
 
22
22
  ## 📦 Installation / Setup
23
23
 
24
- ### 0. Update it (not required)
24
+ ### 0. Update it
25
+
26
+ <details>
27
+ <summary>Learn more (not required)</summary>
28
+
29
+ **This step is only relevant if you want to build the package and data on your own and from source!**
30
+ _(Requires Node.js as well as Linux as operating system. You would also need to load/include it manually into your codebase.)_
25
31
 
26
- **This step is only relevant if you want to build the package and data on your own and from source!**
27
- _(Requires Node.js as well as Linux as operating system.)_
28
32
  Run ...
29
33
 
30
34
  ```
31
- sudo sh update-tzdata.sh tzVersionNumber
35
+ sudo sh scripts/update-tzdata.sh tzVersionNumber rebuildVzic
32
36
  ```
33
37
 
34
- ... with _tzVersionNumber_ being the version of the [IANA time zone database](https://www.iana.org/time-zones) you want to use (e.g. sudo sh update-tzdata.sh 2025c).
38
+ - with _tzVersionNumber_ being the version of the [IANA time zone database](https://www.iana.org/time-zones) you want to use (e.g. `sudo sh scripts/update-tzdata.sh 2025c`);
39
+ - and _rebuildVzic_ as an optional param to rebuild the vzic library from scratch (e.g. `sudo sh scripts/update-tzdata.sh 2025c true`).
40
+ </details>
35
41
 
36
42
  <br />
37
43
 
38
- ### 1. Load it
39
-
40
- Install the package via npm with:
44
+ ### 1. Install it
41
45
 
42
46
  ```
43
47
  npm install timezones-ical-library
44
48
  ```
45
49
 
46
- After the installation:
50
+ <br />
51
+
52
+ ### 2. Import it
53
+
54
+ For CommonJS:
55
+
56
+ ```
57
+ require tzLib = require('timezones-ical-library');
58
+ ```
59
+
60
+ With ES:
47
61
 
48
- - require the package (commonJS) or ...
49
- - import the module (ES) via `import { tzlib_get_ical_block, tzlib_get_offset, tzlib_get_timezones } from 'timezones-ical-library';`.
62
+ ```
63
+ import { tzlib_get_ical_block, tzlib_get_offset, tzlib_get_timezones } from 'timezones-ical-library';
64
+ ```
50
65
 
51
66
  <br />
52
67
 
53
- ### 2. Use it
68
+ ### 3. Use it
54
69
 
55
70
  #### A. Get time zones
56
71
 
57
- Use `tzlib_get_timezones()` to retrieve a list of all available time zone strings. You can pass `true` to retrieve a JSON formatted string instead of an array.
72
+ Use `tzlib_get_timezones()` to retrieve a list of all available time zone strings.
73
+ You can pass `true` to retrieve a JSON formatted string instead of an array.
74
+ For CommonJS, you would use `tzLib.tzlib_get_timezones()`.
58
75
 
59
76
  #### B. Get the iCal time zone block
60
77
 
61
- Use the `tzlib_get_ical_block(tzName)` function to return the proper iCal VTIMEZONE block for a given time zone string (tzName). Again, pass `true` to retrieve a JSON formatted string instead of an array (not recommended).
78
+ Use the `tzlib_get_ical_block(tzName)` function to return the proper iCal VTIMEZONE block for a given time zone string (tzName).
79
+ Again, pass `true` to retrieve a JSON formatted string instead of an array _(not recommended)_.
80
+ For CommonJS, you would use `tzLib.tzlib_get_ical_block(tzName)`.
62
81
 
63
82
  You will receive an array, holding the VTIMEZONE block first, and the TZID line (additionally) second. The latter one is needed for any further time statement.
64
83
 
65
- Include this into your further iCal data to come up with a complete ics file.
84
+ Include this into your iCal data to come up with a complete ics file.
66
85
 
67
86
  A final constellation could look like this:
68
87
 
69
- ```
70
- BEGIN:VCALENDAR
71
- VERSION:2.0
72
- PRODID:-// github.com/add2cal/add-to-calendar-button //EN
73
- CALSCALE:GREGORIAN
74
- ```
75
-
76
- ```
77
- BEGIN:VTIMEZONE
78
- TZID:America/New_York
79
- LAST-MODIFIED:20220824T133813Z
80
- X-LIC-LOCATION:America/New_York
81
- BEGIN:DAYLIGHT
82
- TZNAME:EDT
83
- TZOFFSETFROM:-0500
84
- TZOFFSETTO:-0400
85
- DTSTART:19700308T020000
86
- RRULE:FREQ=YEARLY;BYMONTH=3;BYDAY=2SU
87
- END:DAYLIGHT
88
- BEGIN:STANDARD
89
- TZNAME:EST
90
- TZOFFSETFROM:-0400
91
- TZOFFSETTO:-0500
92
- DTSTART:19701101T020000
93
- RRULE:FREQ=YEARLY;BYMONTH=11;BYDAY=1SU
94
- END:STANDARD
95
- END:VTIMEZONE
96
- ```
97
-
98
- ```
99
- BEGIN:VEVENT
100
- UID:2022-08-30T19:29:38.618Z@add-to-calendar-button
101
- DTSTAMP:20230214T091500Z
102
- DTSTART;TZID=America/New_York:20230214T091500
103
- DTEND;TZID=America/New_York:20230218T223000
104
- SUMMARY:A sample event
105
- DESCRIPTION:Just some descriptive text...
106
- LOCATION:World Wide Web
107
- STATUS:CONFIRMED
108
- LAST-MODIFIED:20220830T192938Z
109
- SEQUENCE:0
110
- END:VEVENT
111
- END:VCALENDAR
88
+ ```diff
89
+ BEGIN:VCALENDAR
90
+ VERSION:2.0
91
+ PRODID:-// github.com/add2cal/add-to-calendar-button //EN
92
+ CALSCALE:GREGORIAN
93
+ + BEGIN:VTIMEZONE
94
+ + TZID:America/New_York
95
+ + LAST-MODIFIED:20220824T133813Z
96
+ + X-LIC-LOCATION:America/New_York
97
+ + BEGIN:DAYLIGHT
98
+ + TZNAME:EDT
99
+ + TZOFFSETFROM:-0500
100
+ + TZOFFSETTO:-0400
101
+ + DTSTART:19700308T020000
102
+ + RRULE:FREQ=YEARLY;BYMONTH=3;BYDAY=2SU
103
+ + END:DAYLIGHT
104
+ + BEGIN:STANDARD
105
+ + ZNAME:EST
106
+ + TZOFFSETFROM:-0400
107
+ + TZOFFSETTO:-0500
108
+ + DTSTART:19701101T020000
109
+ + RRULE:FREQ=YEARLY;BYMONTH=11;BYDAY=1SU
110
+ + END:STANDARD
111
+ + END:VTIMEZONE
112
+ BEGIN:VEVENT
113
+ UID:2022-08-30T19:29:38.618Z@add-to-calendar-button
114
+ DTSTAMP:20230214T091500Z
115
+ DTSTART;TZID=America/New_York:20230214T091500
116
+ DTEND;TZID=America/New_York:20230218T223000
117
+ SUMMARY:A sample event
118
+ DESCRIPTION:Just some descriptive text...
119
+ LOCATION:World Wide Web
120
+ STATUS:CONFIRMED
121
+ LAST-MODIFIED:20220830T192938Z
122
+ SEQUENCE:0
123
+ END:VEVENT
124
+ END:VCALENDAR
112
125
  ```
113
126
 
114
127
  #### C. Get a specific offset
@@ -127,22 +140,25 @@ For example, you can provide _tzName_ `'Europe/Berlin'`, _isoDate_ `'2023-05-23'
127
140
 
128
141
  Instead of using this code or the npm package, you could also make use of the free and open API.
129
142
 
130
- ### Getting a list of all zone names
143
+ ### GET a list of all zone names
131
144
 
132
145
  ```
133
146
  https://tz.add-to-calendar-technology.com/api/zones.json
134
147
  ```
135
148
 
136
- ### Getting the ics part of a respective zone
149
+ ### GET the ics part of a respective zone
137
150
 
138
151
  ```
139
- https://tz.add-to-calendar-technology.com/api/%zoneName%.ics
152
+ https://tz.add-to-calendar-technology.com/api/{{zoneName}}.ics
140
153
  ```
141
154
 
142
- With %zoneName% being your time zone. So, for New York, this would be [https://tz.add-to-calendar-technology.com/api/America/New_York.ics](https://tz.add-to-calendar-technology.com/api/America/New_York.ics).
155
+ With `{{zoneName}}` being your time zone.
156
+ So, for New York, this would be [https://tz.add-to-calendar-technology.com/api/America/New_York.ics](https://tz.add-to-calendar-technology.com/api/America/New_York.ics).
157
+
143
158
  **This is case sensitive!**
144
159
 
145
- (Mind that this does not deliver a fully valid ics file, since it only contains the VTIMEZONE part. You will need to combine this with your other event information.)
160
+ > [!WARNING]
161
+ > Mind that this does not deliver a fully valid ics file, since it only contains the VTIMEZONE part. You will need to combine this with your other event information.
146
162
 
147
163
  <br /><br />
148
164
 
@@ -162,16 +178,18 @@ Anyone is welcome to contribute, but mind the [guidelines](.github/CONTRIBUTING.
162
178
 
163
179
  ## 📃 Copyright and License
164
180
 
165
- Copyright (c) [Jens Kuerschner](https://jekuer.com).
166
-
167
- Licensed under [Apache-2.0](LICENSE).
181
+ Copyright (c) [Jens Kuerschner](https://jekuer.com). Licensed under [Apache-2.0](LICENSE).
168
182
 
169
183
  <br />
170
184
 
171
- ## ⚡ Changelog (without minor changes and fixes)
185
+ ## ⚡ Changelog
172
186
 
173
187
  ![npm version](https://img.shields.io/npm/v/timezones-ical-library?label=current%20version&style=for-the-badge)
174
188
 
189
+ <details>
190
+ <summary>History (without minor changes and fixes)</summary>
191
+
192
+ - v2.0 : Full refactoring reducing bundle size and easing future updates, using Astro for Demo page
175
193
  - v1.11 : database update (2025c)
176
194
  - v1.10 : upgrading to latest vzic improvements
177
195
  - v1.9 : database update (2025b)
@@ -184,8 +202,7 @@ Licensed under [Apache-2.0](LICENSE).
184
202
  - v1.2 : providing tzblock as array with separate tzid
185
203
  - v1.1 : get-offset function
186
204
  - v1.0 : initial release
187
-
188
- ---
205
+ </details>
189
206
 
190
207
  <br />
191
208
 
@@ -193,5 +210,4 @@ Licensed under [Apache-2.0](LICENSE).
193
210
 
194
211
  - The ["Time Zone King"](https://samueli.ucla.edu/time-zone-king-how-one-ucla-computer-scientist-keeps-digital-clocks-ticking/) [Paul Eggert](https://github.com/eggert) for optimizing time zones for the web, ...
195
212
  - as well as all the contributors at [the official tz repository](https://github.com/eggert/tz).
196
- - The awesome authors of zic and [vzic](https://github.com/libical/vzic/graphs/contributors); mainly Damon Chaplin, [Allen Winter](https://github.com/winterz), and [Ken Murchison](https://github.com/ksmurchison).
197
- - [Trevor Eyre](https://github.com/trevoreyre) for his smooth and beautiful [autocomplete script](https://github.com/trevoreyre/autocomplete).
213
+ - The awesome authors of zic, vzic, and [libical](https://github.com/libical/libical/graphs/contributors); mainly Damon Chaplin, [Allen Winter](https://github.com/winterz), and [Ken Murchison](https://github.com/ksmurchison).