Skip to content

Commit

Permalink
add typedef for designSet
Browse files Browse the repository at this point in the history
  • Loading branch information
@jannikac
jannikac committed Jun 26, 2024
1 parent 153baa1 commit 523c7c1
Show file tree
Hide file tree
Showing 6 changed files with 84 additions and 44 deletions.
11 changes: 10 additions & 1 deletion lib/ical/component.js
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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;
Expand Down Expand Up @@ -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() {
Expand Down
54 changes: 25 additions & 29 deletions lib/ical/design.js
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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;
Expand Down Expand Up @@ -895,7 +904,7 @@ let vcard3Properties = extend(commonProperties, {

/**
* iCalendar design set
* @type {ICAL.design.designSet}
* @type {designSet}
*/
let icalSet = {
value: icalValues,
Expand All @@ -906,7 +915,7 @@ let icalSet = {

/**
* vCard 4.0 design set
* @type {ICAL.design.designSet}
* @type {designSet}
*/
let vcardSet = {
value: vcardValues,
Expand All @@ -917,7 +926,7 @@ let vcardSet = {

/**
* vCard 3.0 design set
* @type {ICAL.design.designSet}
* @type {designSet}
*/
let vcard3Set = {
value: vcard3Values,
Expand All @@ -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,

Expand All @@ -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';
Expand All @@ -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;
Expand Down
14 changes: 8 additions & 6 deletions lib/ical/parse.js
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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]/;
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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) {
Expand Down
17 changes: 13 additions & 4 deletions lib/ical/property.js
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand All @@ -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));
Expand Down Expand Up @@ -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() {
Expand Down
16 changes: 13 additions & 3 deletions lib/ical/stringify.js
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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", "^": "^^" };
Expand Down Expand Up @@ -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
*/
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down
16 changes: 15 additions & 1 deletion lib/ical/types.d.js
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
*/
Expand All @@ -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 _ = {};

0 comments on commit 523c7c1

Please sign in to comment.