Fix remaining typescript issues (#712)

This change also swaps the argument order in TimezoneService.register() to accommodate for more correct typing. It has been done in a backwards compatible way, v3 will require the correct ordering.

lib/ical/component.js

@@ -9,6 +9,15 @@ import ICALParse from "./parse.js";
 import stringify from "./stringify.js";
 import design from "./design.js";
 
+/**
+ * This lets typescript resolve our custom types in the
+ * generated d.ts files (jsdoc typedefs are converted to typescript types).
+ * Ignore prevents the typedefs from being documented more than once.
+ * @ignore
+ * @typedef {import("./types.d.js").designSet} designSet
+ * Imports the 'designSet' type from the "types.d.js" module
+ */
+
 const NAME_INDEX = 0;
 const PROPERTY_INDEX = 1;
 const COMPONENT_INDEX = 2;
@@ -95,7 +104,6 @@ class Component {
    * The name of this component
    *
    * @type {String}
-   * @readonly
    */
   get name() {
     return this.jCal[NAME_INDEX];
@@ -104,7 +112,7 @@ class Component {
   /**
    * The design set for this component, e.g. icalendar vs vcard
    *
-   * @type {ICAL.design.designSet}
+   * @type {designSet}
    * @private
    */
   get _designSet() {

lib/ical/design.js

@@ -12,6 +12,15 @@ import Duration from "./duration.js";
 import Time from "./time.js";
 import Binary from "./binary.js";
 
+/**
+ * This lets typescript resolve our custom types in the
+ * generated d.ts files (jsdoc typedefs are converted to typescript types).
+ * Ignore prevents the typedefs from being documented more than once.
+ * @ignore
+ * @typedef {import("./types.d.js").designSet} designSet
+ * Imports the 'designSet' type from the "types.d.js" module
+ */
+
 /** @module ICAL.design */
 
 const FROM_ICAL_NEWLINE = /\\\\|\\;|\\,|\\[Nn]/g;
@@ -895,7 +904,7 @@ let vcard3Properties = extend(commonProperties, {
 
 /**
  * iCalendar design set
- * @type {ICAL.design.designSet}
+ * @type {designSet}
  */
 let icalSet = {
   value: icalValues,
@@ -906,7 +915,7 @@ let icalSet = {
 
 /**
  * vCard 4.0 design set
- * @type {ICAL.design.designSet}
+ * @type {designSet}
  */
 let vcardSet = {
   value: vcardValues,
@@ -917,7 +926,7 @@ let vcardSet = {
 
 /**
  * vCard 3.0 design set
- * @type {ICAL.design.designSet}
+ * @type {designSet}
  */
 let vcard3Set = {
   value: vcard3Values,
@@ -934,27 +943,14 @@ let vcard3Set = {
  * @exports module:ICAL.design
  */
 const design = {
-  /**
-   * A designSet describes value, parameter and property data. It is used by
-   * ther parser and stringifier in components and properties to determine they
-   * should be represented.
-   *
-   * @typedef {Object} designSet
-   * @memberOf ICAL.design
-   * @property {Object} value       Definitions for value types, keys are type names
-   * @property {Object} param       Definitions for params, keys are param names
-   * @property {Object} property    Definitions for properties, keys are property names
-   * @property {boolean} propertyGroups  If content lines may include a group name
-   */
-
   /**
    * Can be set to false to make the parser more lenient.
    */
   strict: true,
 
   /**
    * The default set for new properties and components if none is specified.
-   * @type {ICAL.design.designSet}
+   * @type {designSet}
    */
   defaultSet: icalSet,
 
@@ -968,14 +964,14 @@ const design = {
    * Holds the design set for known top-level components
    *
    * @type {Object}
-   * @property {ICAL.design.designSet} vcard       vCard VCARD
-   * @property {ICAL.design.designSet} vevent      iCalendar VEVENT
-   * @property {ICAL.design.designSet} vtodo       iCalendar VTODO
-   * @property {ICAL.design.designSet} vjournal    iCalendar VJOURNAL
-   * @property {ICAL.design.designSet} valarm      iCalendar VALARM
-   * @property {ICAL.design.designSet} vtimezone   iCalendar VTIMEZONE
-   * @property {ICAL.design.designSet} daylight    iCalendar DAYLIGHT
-   * @property {ICAL.design.designSet} standard    iCalendar STANDARD
+   * @property {designSet} vcard       vCard VCARD
+   * @property {designSet} vevent      iCalendar VEVENT
+   * @property {designSet} vtodo       iCalendar VTODO
+   * @property {designSet} vjournal    iCalendar VJOURNAL
+   * @property {designSet} valarm      iCalendar VALARM
+   * @property {designSet} vtimezone   iCalendar VTIMEZONE
+   * @property {designSet} daylight    iCalendar DAYLIGHT
+   * @property {designSet} standard    iCalendar STANDARD
    *
    * @example
    * let propertyName = 'fn';
@@ -1000,27 +996,27 @@ const design = {
 
   /**
    * The design set for iCalendar (rfc5545/rfc7265) components.
-   * @type {ICAL.design.designSet}
+   * @type {designSet}
    */
   icalendar: icalSet,
 
   /**
    * The design set for vCard (rfc6350/rfc7095) components.
-   * @type {ICAL.design.designSet}
+   * @type {designSet}
    */
   vcard: vcardSet,
 
   /**
    * The design set for vCard (rfc2425/rfc2426/rfc7095) components.
-   * @type {ICAL.design.designSet}
+   * @type {designSet}
    */
   vcard3: vcard3Set,
 
   /**
    * Gets the design set for the given component name.
    *
    * @param {String} componentName        The name of the component
-   * @return {ICAL.design.designSet}      The design set for the component
+   * @return {designSet}      The design set for the component
    */
   getDesignSet: function(componentName) {
     let isInDesign = componentName && componentName in design.components;

lib/ical/event.js

@@ -38,10 +38,10 @@ class Event {
    * Creates a new ICAL.Event instance.
    *
    * @param {Component=} component              The ICAL.Component to base this event on
-   * @param {Object} options                    Options for this event
-   * @param {Boolean} options.strictExceptions  When true, will verify exceptions are related by
+   * @param {Object} [options]                  Options for this event
+   * @param {Boolean=} options.strictExceptions  When true, will verify exceptions are related by
    *                                              their UUID
-   * @param {Array<Component|Event>} options.exceptions
+   * @param {Array<Component|Event>=} options.exceptions
    *          Exceptions to this event, either as components or events. If not
    *            specified exceptions will automatically be set in relation of
    *            component's parent
@@ -426,7 +426,6 @@ class Event {
   /**
    * The attendees in the event
    * @type {Property[]}
-   * @readonly
    */
   get attendees() {
     //XXX: This is way lame we should have a better

lib/ical/parse.js

@@ -14,6 +14,8 @@ import { unescapedIndexOf } from "./helpers.js";
  * @ignore
  * @typedef {import("./types.d.js").parserState} parserState
  * Imports the 'parserState' type from the "types.d.js" module
+ * @typedef {import("./types.d.js").designSet} designSet
+ * Imports the 'designSet' type from the "types.d.js" module
  */
 
 const CHAR = /[^ \t]/;
@@ -67,7 +69,7 @@ export default function parse(input) {
  * @function ICAL.parse.property
  * @param {String} str
  *   The iCalendar property string to parse
- * @param {ICAL.design.designSet=} designSet
+ * @param {designSet=} designSet
  *   The design data to use for this property
  * @return {Object}
  *   The jCal Object containing the property
@@ -309,7 +311,7 @@ parse._parseValue = function(value, type, designSet, structuredValue) {
  * @function ICAL.parse._parseParameters
  * @private
  * @param {String} line           A single unfolded line
- * @param {Numeric} start         Position to start looking for properties
+ * @param {Number} start         Position to start looking for properties
  * @param {Object} designSet      The design data to use for this property
  * @return {Object} key/value pairs
  */
@@ -450,12 +452,12 @@ parse._rfc6868Escape = function(val) {
  *
  * @private
  * @function ICAL.parse._parseMultiValue
- * @param {String} buffer     The buffer containing the full value
- * @param {String} delim      The multi-value delimiter
- * @param {String} type       The value type to be parsed
+ * @param {String} buffer           The buffer containing the full value
+ * @param {String} delim            The multi-value delimiter
+ * @param {String} type             The value type to be parsed
  * @param {Array.<?>} result        The array to append results to, varies on value type
- * @param {String} innerMulti The inner delimiter to split each value with
- * @param {ICAL.design.designSet} designSet   The design data for this value
+ * @param {String} innerMulti       The inner delimiter to split each value with
+ * @param {designSet} designSet     The design data for this value
  * @return {?|Array.<?>}            Either an array of results, or the first result
  */
 parse._parseMultiValue = function(buffer, delim, type, result, innerMulti, designSet, structuredValue) {

lib/ical/period.js

@@ -9,6 +9,15 @@ import Duration from "./duration.js";
 // eslint-disable-next-line no-unused-vars
 import Property from "./property.js";
 
+/**
+ * This lets typescript resolve our custom types in the
+ * generated d.ts files (jsdoc typedefs are converted to typescript types).
+ * Ignore prevents the typedefs from being documented more than once.
+ * @ignore
+ * @typedef {import("./types.d.js").jCalComponent} jCalComponent
+ * Imports the 'occurrenceDetails' type from the "types.d.js" module
+ */
+
 /**
  * This class represents the "period" value type, with various calculation and manipulation methods.
  *
@@ -65,7 +74,7 @@ class Period {
    * member is always the start date string, the second member is either a
    * duration or end date string.
    *
-   * @param {Array<String,String>} aData    The jCal data array
+   * @param {jCalComponent} aData           The jCal data array
    * @param {Property} aProp                The property this jCal data is on
    * @param {Boolean} aLenient              If true, data value can be both date and date-time
    * @return {Period}                       The period instance

lib/ical/property.js

@@ -15,6 +15,15 @@ import Component from "./component.js";
 import ICALStringify from "./stringify.js";
 import ICALParse from "./parse.js";
 
+/**
+ * This lets typescript resolve our custom types in the
+ * generated d.ts files (jsdoc typedefs are converted to typescript types).
+ * Ignore prevents the typedefs from being documented more than once.
+ * @ignore
+ * @typedef {import("./types.d.js").designSet} designSet
+ * Imports the 'designSet' type from the "types.d.js" module
+ */
+
 /**
  * Provides a layer on top of the raw jCal object for manipulating a single property, with its
  * parameters and value.
@@ -25,9 +34,9 @@ class Property {
   /**
    * Create an {@link ICAL.Property} by parsing the passed iCalendar string.
    *
-   * @param {String} str                        The iCalendar string to parse
-   * @param {ICAL.design.designSet=} designSet  The design data to use for this property
-   * @return {Property}                         The created iCalendar property
+   * @param {String} str            The iCalendar string to parse
+   * @param {designSet=} designSet  The design data to use for this property
+   * @return {Property}             The created iCalendar property
    */
   static fromString(str, designSet) {
     return new Property(ICALParse.property(str, designSet));
@@ -59,7 +68,6 @@ class Property {
 
   /**
    * The value type for this property
-   * @readonly
    * @type {String}
    */
   get type() {
@@ -68,7 +76,6 @@ class Property {
 
   /**
    * The name of this property, in lowercase.
-   * @readonly
    * @type {String}
    */
   get name() {
@@ -99,7 +106,7 @@ class Property {
   /**
    * The design set for this property, e.g. icalendar vs vcard
    *
-   * @type {ICAL.design.designSet}
+   * @type {designSet}
    * @private
    */
   get _designSet() {

lib/ical/stringify.js

@@ -6,6 +6,16 @@
 import design from "./design.js";
 import { foldline } from "./helpers.js";
 
+/**
+ * This lets typescript resolve our custom types in the
+ * generated d.ts files (jsdoc typedefs are converted to typescript types).
+ * Ignore prevents the typedefs from being documented more than once.
+ *
+ * @ignore
+ * @typedef {import("./types.d.js").designSet} designSet
+ * Imports the 'designSet' type from the "types.d.js" module
+ */
+
 const LINE_ENDING = '\r\n';
 const DEFAULT_VALUE_TYPE = 'unknown';
 const RFC6868_REPLACE_MAP = { '"': "^'", "\n": "^n", "^": "^^" };
@@ -45,7 +55,7 @@ export default function stringify(jCal) {
  * @function ICAL.stringify.component
  * @param {Array} component
  *        jCal/jCard fragment of a component
- * @param {ICAL.design.designSet} designSet
+ * @param {designSet} designSet
  *        The design data to use for this component
  * @return {String}       The iCalendar/vCard string
  */
@@ -89,7 +99,7 @@ stringify.component = function(component, designSet) {
  * @function ICAL.stringify.property
  * @param {Array} property
  *        jCal/jCard property array
- * @param {ICAL.design.designSet} designSet
+ * @param {designSet} designSet
  *        The design data to use for this property
  * @param {Boolean} noFold
  *        If true, the line is not folded
@@ -236,7 +246,7 @@ stringify.paramPropertyValue = function(value, force) {
  *        (like boolean, date-time, etc..)
  * @param {?String} innerMulti If set, each value will again be processed
  *        Used for structured values
- * @param {ICAL.design.designSet} designSet
+ * @param {designSet} designSet
  *        The design data to use for this property
  *
  * @return {String}           iCalendar/vCard string for value

lib/ical/time.js

@@ -422,7 +422,6 @@ class Time {
   /**
    * The type name, to be used in the jCal object. This value may change and
    * is strictly defined by the {@link ICAL.Time#isDate isDate} member.
-   * @readonly
    * @type {String}
    * @default "date-time"
    */