From 523c7c1987912146e5b76aa9832b42e0e709dad1 Mon Sep 17 00:00:00 2001 From: jannikac Date: Wed, 26 Jun 2024 12:52:46 +0200 Subject: [PATCH] add typedef for designSet --- lib/ical/component.js | 11 ++++++++- lib/ical/design.js | 54 ++++++++++++++++++++----------------------- lib/ical/parse.js | 14 ++++++----- lib/ical/property.js | 17 ++++++++++---- lib/ical/stringify.js | 16 ++++++++++--- lib/ical/types.d.js | 16 ++++++++++++- 6 files changed, 84 insertions(+), 44 deletions(-) diff --git a/lib/ical/component.js b/lib/ical/component.js index 6ff13074..5fe0a3e0 100644 --- a/lib/ical/component.js +++ b/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; @@ -103,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() { diff --git a/lib/ical/design.js b/lib/ical/design.js index 1778df65..fc5c8ebc 100644 --- a/lib/ical/design.js +++ b/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,19 +943,6 @@ 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. */ @@ -954,7 +950,7 @@ const design = { /** * 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,19 +996,19 @@ 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, @@ -1020,7 +1016,7 @@ const design = { * 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; diff --git a/lib/ical/parse.js b/lib/ical/parse.js index b6e86649..db431c3b 100644 --- a/lib/ical/parse.js +++ b/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 @@ -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) { diff --git a/lib/ical/property.js b/lib/ical/property.js index 2a293b5d..1ce7447f 100644 --- a/lib/ical/property.js +++ b/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)); @@ -97,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() { diff --git a/lib/ical/stringify.js b/lib/ical/stringify.js index 12415968..0ebff760 100644 --- a/lib/ical/stringify.js +++ b/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 diff --git a/lib/ical/types.d.js b/lib/ical/types.d.js index 94d9e8f9..4f6a7dd5 100644 --- a/lib/ical/types.d.js +++ b/lib/ical/types.d.js @@ -41,7 +41,7 @@ import Component from "./component"; * @private * @memberof ICAL.parse * @typedef {Object} parserState - * @property {ICAL.design.designSet} designSet The design set to use for parsing + * @property {designSet} designSet The design set to use for parsing * @property {Component[]} stack The stack of components being processed * @property {Component} component The currently active component */ @@ -61,4 +61,18 @@ import Component from "./component"; * @property {jCalProperty[]} 1 The properties of this component * @property {jCalComponent[]} 2 The subcomponents of this component */ + +/** + * 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. + * + * @memberof ICAL.design + * @typedef {Object} designSet + * @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 + */ + export const _ = {};