chore(vCard): deprecate vcalendar format (#53)

* docs(VCard): Update comments and deprecate buildVCalendar method

* refactor(constants): Mark VCALENDAR in ContentTypes and Formats as deprecated

* refactor(VCard): Add deprecation warnings for 'vcalendar' format

* "fix(test): Redirect stderr to null in test-functional script"

* docs(README): Mark iCalendar format as deprecated

* refactor(VCard): Update deprecation warning message in buildVCalendar method

Author: joaocarmo

README.md

@@ -102,7 +102,7 @@ vCard.addPhoto(image, 'JPEG')
 
 Include the proper [MIME type][mime-types] (defaults to `JPEG`).
 
-### iCalendar format
+### [DEPRECATED] iCalendar format
 
 For Apple devices that don't support the `vcf` file format, there is a
 workaround. Specify the format of the output as `vcalendar` and then save it

lib/VCard.ts

@@ -87,6 +87,10 @@ export default class VCard {
    */
   public setFormat(format: Format = constants.DEFAULT_FORMAT): void {
     if (format === constants.Formats.VCALENDAR) {
+      // eslint-disable-next-line no-console
+      console.warn(
+        `The format 'vcalendar' is deprecated and will be removed in the next major or minor release. Use 'vcard' instead.`,
+      )
       this.contentType = constants.ContentTypes.VCALENDAR
       this.useVCalendar = true
     } else if (format === constants.Formats.VCARD) {
@@ -479,12 +483,20 @@ ${lastName};${firstName};${additional};${prefix};${suffix}\
   }
 
   /**
-   * Build VCalender (.ics) - Safari (< iOS 8) can not open .vcf files, so we
-   * have build a workaround.
+   * Build VCalender (.ics) - Safari (< iOS 7) can not open .vcf files, so we
+   * built a workaround.
    *
+   * @deprecated This method is deprecated and will be removed in the next major
+   * or minor release. Use `buildVCard` instead. For more information, see
+   * https://stackoverflow.com/a/11405271/8713532.
    * @return {string}
    */
   public buildVCalendar(): string {
+    // eslint-disable-next-line no-console
+    console.warn(
+      `The method 'buildVCalendar' is deprecated and will be removed in the next major or minor release. Use 'buildVCard' instead.`,
+    )
+
     const nowISO = new Date().toISOString()
     const nowBase = nowISO.replace(/-/g, '').replace(/:/g, '').substring(0, 13)
     const dtstart = `${nowBase}00`

lib/utils/constants.ts

@@ -1,11 +1,13 @@
 import { Element } from '../types/VCard'
 
 export enum ContentTypes {
+  /** @deprecated */
   VCALENDAR = 'text/x-vcalendar',
   VCARD = 'text/x-vcard',
 }
 
 export enum Formats {
+  /** @deprecated */
   VCALENDAR = 'vcalendar',
   VCARD = 'vcard',
 }

package.json

@@ -22,7 +22,7 @@
     "preinstall": "npx only-allow pnpm",
     "pretty:fix": "prettier --write .",
     "pretty": "prettier --check .",
-    "test:functional": "(./test-functional/test-vcard.js | tee vcard.vcf) && (./test-functional/test-vcalendar.js | tee vcard.ics)",
+    "test:functional": "(./test-functional/test-vcard.js | tee vcard.vcf) && (./test-functional/test-vcalendar.js 2>/dev/null | tee vcard.ics)",
     "test:unit": "jest",
     "test:web-build": "NODE_ENV=development webpack --mode development && open ./test-functional/test-build.html",
     "test:web-export": "open ./test-functional/test-export.html",