iamcal 2.1.2 → 3.0.1

package/src/property/escape.ts

@@ -0,0 +1,132 @@
+import { ord } from '../patterns'
+
+/**
+ * Escape special characters in a TEXT property value.
+ *
+ * Note: This method converts both CRLF and LF to '\n'.
+ * @param value The property value to escape.
+ * @returns The escaped property value.
+ * @see {@link unescapeTextPropertyValue}
+ */
+export function escapeTextPropertyValue(value: string): string {
+    return value.replace(/(?=[,;\\])/g, '\\').replace(/\r?\n/g, '\\n')
+}
+
+/**
+ * Unescape special characters in a TEXT property value.
+ * @param value The property value to unescape.
+ * @returns The unescaped property value.
+ * @throws If the value contains a bad escaped character, i.e., a character that should not be escaped after a backslash.
+ * @see {@link unescapeTextPropertyValue}
+ */
+export function unescapeTextPropertyValue(value: string): string {
+    /** List that will contain the characters of the unescaped string. */
+    const chars: number[] = []
+
+    // Character codes for special characters
+    const backslash = ord('\\')
+    const newline = ord('\n')
+    const lowercaseN = ord('n')
+    const uppercaseN = ord('N')
+    const comma = ord(',')
+    const semicolon = ord(';')
+
+    let previousCharWasBackslash = false
+    for (let i = 0; i < value.length; i++) {
+        const char = value.charCodeAt(i)
+
+        if (previousCharWasBackslash) {
+            // Previous character was a backslash, so this character is the second character in an escape sequence
+            if (char === lowercaseN || char === uppercaseN) {
+                chars.push(newline)
+            } else if (
+                char === comma ||
+                char === semicolon ||
+                char === backslash
+            ) {
+                chars.push(char)
+            } else {
+                const position = i - 1
+                throw new SyntaxError(
+                    `Bad escaped character '\\${String.fromCharCode(char)}' at position ${position}`
+                )
+            }
+            // End the escape sequence
+            previousCharWasBackslash = false
+        } else if (char === backslash) {
+            // Start of an escape sequence
+            previousCharWasBackslash = true
+        } else {
+            chars.push(char)
+        }
+    }
+
+    return String.fromCharCode(...chars)
+}
+
+/**
+ * Escape a property parameter value.
+ * @param param The parameter value to escape.
+ * @returns The escaped parameter value.
+ * @throws If the parameter value contains a DQUOTE (") character.
+ * @see {@link unescapePropertyParameterValue}
+ */
+export function escapePropertyParameterValue(param: string): string {
+    // Property parameter values MUST NOT contain the DQUOTE character.  The
+    // DQUOTE character is used as a delimiter for parameter values that
+    // contain restricted characters or URI text.
+    if (param.includes('"')) {
+        throw new Error('Parameter value must not contain DQUOTE (").')
+    }
+
+    // Property parameter values that contain the COLON, SEMICOLON, or COMMA
+    // character separators MUST be specified as quoted-string text values.
+    if (/[:;,]/.test(param)) {
+        return `"${param}"`
+    }
+    return param
+}
+
+/**
+ * Unescape a property parameter value.
+ * @param param The parameter value to unescape.
+ * @returns The unescaped parameter value.
+ * @see {@link escapePropertyParameterValue}
+ */
+export function unescapePropertyParameterValue(param: string): string {
+    if (param.startsWith('"') && param.endsWith('"')) {
+        return param.slice(1, -1)
+    }
+    return param
+}
+
+// Max line length as defined by RFC 5545 3.1.
+export const MAX_LINE_LENGTH = 75
+
+/**
+ * Fold a single line as specified in RFC 5545 3.1.
+ * @param line The line to fold.
+ * @returns The folded line.
+ */
+export function foldLine(line: string): string {
+    if (line.length < MAX_LINE_LENGTH) return line
+
+    const lines = [line.substring(0, MAX_LINE_LENGTH)]
+    const matches = line
+        .substring(MAX_LINE_LENGTH)
+        .matchAll(new RegExp(`.{${MAX_LINE_LENGTH - 2}}`, 'g'))
+    for (const match of matches) {
+        lines.push(match[0])
+    }
+
+    return lines.join('\r\n ')
+}
+
+/**
+ * Unfold a single line as specified in RFC 5545 3.1.
+ * @param lines The lines to unfold.
+ * @returns The unfolded line.
+ */
+export function unfoldLine(lines: string): string {
+    return lines.replace(/\r\n /g, '')
+}

package/src/property/index.ts

@@ -0,0 +1,6 @@
+export * from './escape'
+export * from './names'
+export * from './parameter'
+export * from './Property'
+export * from './validate'
+export * from './valueType'

package/src/property/names.ts

@@ -0,0 +1,65 @@
+export const knownPropertyNames = [
+    'CALSCALE',
+    'METHOD',
+    'PRODID',
+    'VERSION',
+    'ATTACH',
+    'CATEGORIES',
+    'CLASS',
+    'COMMENT',
+    'DESCRIPTION',
+    'GEO',
+    'LOCATION',
+    'PERCENT-COMPLETE',
+    'PRIORITY',
+    'RESOURCES',
+    'STATUS',
+    'SUMMARY',
+    'COMPLETED',
+    'DTEND',
+    'DUE',
+    'DTSTART',
+    'DURATION',
+    'FREEBUSY',
+    'TRANSP',
+    'TZID',
+    'TZNAME',
+    'TZOFFSETFROM',
+    'TZOFFSETTO',
+    'TZURL',
+    'ATTENDEE',
+    'CONTACT',
+    'ORGANIZER',
+    'RECURRENCE-ID',
+    'RELATED-TO',
+    'URL',
+    'UID',
+    'EXDATE',
+    'RDATE',
+    'RRULE',
+    'ACTION',
+    'REPEAT',
+    'TRIGGER',
+    'CREATED',
+    'DTSTAMP',
+    'LAST-MODIFIED',
+    'SEQUENCE',
+    'REQUEST-STATUS',
+] as const
+export type KnownPropertyName = (typeof knownPropertyNames)[number]
+export type AllowedPropertyName =
+    | KnownPropertyName
+    | (`X-${string}` & {})
+    | (string & {})
+
+/**
+ * Check if a property name is known. A property name is known if it is present
+ * in {@link knownPropertyNames}.
+ * @param name The property name to check.
+ * @returns If the name is a known property name.
+ */
+export function isKnownPropertyName(
+    name: AllowedPropertyName
+): name is KnownPropertyName {
+    return knownPropertyNames.includes(name as KnownPropertyName)
+}

package/src/property/parameter.ts

@@ -0,0 +1,33 @@
+export type CalendarUserType =
+    | 'INDIVIDUAL'
+    | 'GROUP'
+    | 'RESOURCE'
+    | 'ROOM'
+    | 'UNKNOWN'
+    | (string & {})
+export type Encoding = '8BIT' | 'BASE64'
+export type FreeBusyTimeType =
+    | 'FREE'
+    | 'BUSY'
+    | 'BUSY-UNAVAILABLE'
+    | 'BUSY-TENTATIVE'
+    | (string & {})
+export type ParticipationStatus =
+    | 'NEEDS-ACTION'
+    | 'ACCEPTED'
+    | 'DECLINED'
+    | 'TENTATIVE'
+    | 'DELEGATED'
+    | 'COMPLETED'
+    | 'IN-PROCESS'
+    | (string & {})
+export type RecurrenceIdentifierRange = 'THISANDFUTURE'
+export type AlarmTriggerRelationship = 'START' | 'END'
+export type RelationshipType = 'PARENT' | 'CHILD' | 'SIBLING' | (string & {})
+export type ParticipationRole =
+    | 'CHAIR'
+    | 'REQ-PARTICIPANT'
+    | 'OPT-PARTICIPANT'
+    | 'NON-PARTICIPANT'
+    | (string & {})
+export type RsvpExpectation = 'TRUE' | 'FALSE'

package/src/{property.ts → property/validate.ts}

@@ -1,185 +1,9 @@
-import { parseDateString, parseDateTimeString } from './date'
-import * as patterns from './patterns'
-import { matchesWholeString } from './patterns'
-
-export interface Property {
-    name: string
-    params: string[]
-    value: string
-}
-
-export const knownPropertyNames = [
-    'CALSCALE',
-    'METHOD',
-    'PRODID',
-    'VERSION',
-    'ATTACH',
-    'CATEGORIES',
-    'CLASS',
-    'COMMENT',
-    'DESCRIPTION',
-    'GEO',
-    'LOCATION',
-    'PERCENT-COMPLETE',
-    'PRIORITY',
-    'RESOURCES',
-    'STATUS',
-    'SUMMARY',
-    'COMPLETED',
-    'DTEND',
-    'DUE',
-    'DTSTART',
-    'DURATION',
-    'FREEBUSY',
-    'TRANSP',
-    'TZID',
-    'TZNAME',
-    'TZOFFSETFROM',
-    'TZOFFSETTO',
-    'TZURL',
-    'ATTENDEE',
-    'CONTACT',
-    'ORGANIZER',
-    'RECURRENCE-ID',
-    'RELATED-TO',
-    'URL',
-    'UID',
-    'EXDATE',
-    'RDATE',
-    'RRULE',
-    'ACTION',
-    'REPEAT',
-    'TRIGGER',
-    'CREATED',
-    'DTSTAMP',
-    'LAST-MODIFIED',
-    'SEQUENCE',
-    'REQUEST-STATUS',
-] as const
-export type KnownPropertyName = (typeof knownPropertyNames)[number]
-export type AllowedPropertyName =
-    | KnownPropertyName
-    | (`X-${string}` & {})
-    | (string & {})
-
-export const knownValueTypes = [
-    'BINARY',
-    'BOOLEAN',
-    'CAL-ADDRESS',
-    'DATE',
-    'DATE-TIME',
-    'DURATION',
-    'FLOAT',
-    'INTEGER',
-    'PERIOD',
-    'RECUR',
-    'TEXT',
-    'TIME',
-    'URI',
-    'UTC-OFFSET',
-] as const
-export type KnownValueType = (typeof knownValueTypes)[number]
-export type AllowedValueType = KnownValueType | (string & {})
-
-/**
- * The value types that each property supports as defined by the iCalendar
- * specification. The first in the list is the default type.
- */
-export const supportedValueTypes: {
-    [name in KnownPropertyName]: KnownValueType[]
-} = {
-    CALSCALE: ['TEXT'],
-    METHOD: ['TEXT'],
-    PRODID: ['TEXT'],
-    VERSION: ['TEXT'],
-    ATTACH: ['URI', 'BINARY'],
-    CATEGORIES: ['TEXT'],
-    CLASS: ['TEXT'],
-    COMMENT: ['TEXT'],
-    DESCRIPTION: ['TEXT'],
-    GEO: ['FLOAT'],
-    LOCATION: ['TEXT'],
-    'PERCENT-COMPLETE': ['INTEGER'],
-    PRIORITY: ['INTEGER'],
-    RESOURCES: ['TEXT'],
-    STATUS: ['TEXT'],
-    SUMMARY: ['TEXT'],
-    COMPLETED: ['DATE-TIME'],
-    DTEND: ['DATE-TIME', 'DATE'],
-    DUE: ['DATE-TIME', 'DATE'],
-    DTSTART: ['DATE-TIME', 'DATE'],
-    DURATION: ['DURATION'],
-    FREEBUSY: ['PERIOD'],
-    TRANSP: ['TEXT'],
-    TZID: ['TEXT'],
-    TZNAME: ['TEXT'],
-    TZOFFSETFROM: ['UTC-OFFSET'],
-    TZOFFSETTO: ['UTC-OFFSET'],
-    TZURL: ['URI'],
-    ATTENDEE: ['CAL-ADDRESS'],
-    CONTACT: ['TEXT'],
-    ORGANIZER: ['CAL-ADDRESS'],
-    'RECURRENCE-ID': ['DATE-TIME', 'DATE'],
-    'RELATED-TO': ['TEXT'],
-    URL: ['URI'],
-    UID: ['TEXT'],
-    EXDATE: ['DATE-TIME', 'DATE'],
-    RDATE: ['DATE-TIME', 'DATE', 'PERIOD'],
-    RRULE: ['RECUR'],
-    ACTION: ['TEXT'],
-    REPEAT: ['INTEGER'],
-    TRIGGER: ['DURATION', 'DATE-TIME'],
-    CREATED: ['DATE-TIME'],
-    DTSTAMP: ['DATE-TIME'],
-    'LAST-MODIFIED': ['DATE-TIME'],
-    SEQUENCE: ['INTEGER'],
-    'REQUEST-STATUS': ['TEXT'],
-}
-
-/**
- * Get the value type of a property, as defined by the VALUE parameter.
- * @param property The property to get the value type of.
- * @returns The value type if present, else `undefined`.
- * @throws If the parameter value is misformed.
- */
-export function getPropertyValueType(
-    property: Property
-): AllowedValueType | undefined
-
-/**
- * Get the value type of a property, as defined by the VALUE parameter.
- * @param property The property to get the value type of.
- * @param defaultValue The default value to return if the property VALUE parameter is not present.
- * @returns The value type if present, else `defaultValue` or `undefined`.
- * @throws If the parameter value is misformed.
- */
-export function getPropertyValueType(
-    property: Property,
-    defaultValue: AllowedValueType
-): AllowedValueType
-export function getPropertyValueType(
-    property: Property,
-    defaultValue: AllowedValueType | undefined
-): AllowedValueType | undefined
-export function getPropertyValueType(
-    property: Property,
-    defaultValue?: AllowedValueType | undefined
-): AllowedValueType | undefined {
-    const found = property.params.find(param => /^VALUE=.+$/i.test(param))
-    if (!found) return defaultValue
-
-    if (!patterns.matchesWholeString(patterns.paramValue, found)) {
-        throw new Error('Parameter value is misformed')
-    }
-
-    // Return as uppercase if known value
-    const value = found?.split('=')[1]
-    if ((knownValueTypes as readonly string[]).includes(value.toUpperCase())) {
-        return value.toUpperCase()
-    }
-
-    return value
-}
+import { parseDateString, parseDateTimeString } from '../date'
+import * as patterns from '../patterns'
+import { matchesWholeString } from '../patterns'
+import type { Property } from './Property'
+import { isKnownPropertyName, type KnownPropertyName } from './names'
+import { type AllowedValueType, supportedValueTypes } from './valueType'
 
 /** Represents an error which occurs while validating a calendar property. */
 export class PropertyValidationError extends Error {
@@ -431,6 +255,18 @@ export function validateValue(value: string, type: AllowedValueType) {
     }
 }
 
+/**
+ * Validate if a value is a valid content type.
+ * @param value The value to validate.
+ * @throws {PropertyValidationError} If the validation fails.
+ */
+export function validateContentType(value: string) {
+    if (!matchesWholeString(patterns.contentType, value))
+        throw new PropertyValidationError(
+            `${value} does not match pattern for content type`
+        )
+}
+
 /* eslint-disable jsdoc/require-description-complete-sentence --
  * Does not allow line to end with ':'.
  **/
@@ -452,32 +288,15 @@ export function validateValue(value: string, type: AllowedValueType) {
 export function validateProperty(property: Property) {
     // Get supported and default types
     let supportedTypes: AllowedValueType[] | undefined = undefined
-    let defaultType: AllowedValueType | undefined = undefined
-
-    if (knownPropertyNames.includes(property.name as KnownPropertyName)) {
-        const name = property.name as KnownPropertyName
+    if (isKnownPropertyName(property.name)) {
+        const name: KnownPropertyName = property.name
         supportedTypes = supportedValueTypes[name]
-        defaultType = supportedTypes[0]
     }
 
-    // Find value type
-    const valueType = getPropertyValueType(property, defaultType)
-
-    // If value type is unknown, validate as TEXT
-    if (valueType === undefined) {
-        try {
-            validateText(property.value)
-        } catch (e) {
-            throw e instanceof PropertyValidationError
-                ? new PropertyValidationError(
-                      `Unknown property ${property.name} is not valid text`
-                  )
-                : e
-        }
-        return
-    }
+    // Get value type
+    const valueType = property.getValueType()
 
-    // Check if type is unsupported
+    // Check if value type is unsupported by the property
     if (supportedTypes !== undefined && !supportedTypes.includes(valueType)) {
         throw new PropertyValidationError(
             supportedTypes.length === 1

package/src/property/valueType.ts

@@ -0,0 +1,87 @@
+import type { AllowedPropertyName, KnownPropertyName } from './names'
+
+export const knownValueTypes = [
+    'BINARY',
+    'BOOLEAN',
+    'CAL-ADDRESS',
+    'DATE',
+    'DATE-TIME',
+    'DURATION',
+    'FLOAT',
+    'INTEGER',
+    'PERIOD',
+    'RECUR',
+    'TEXT',
+    'TIME',
+    'URI',
+    'UTC-OFFSET',
+] as const
+export type KnownValueType = (typeof knownValueTypes)[number]
+export type AllowedValueType = KnownValueType | (string & {})
+
+/**
+ * The value types that each known property supports as defined by the iCalendar
+ * specification. The first in the list is the default type.
+ */
+export const supportedValueTypes: {
+    [name in KnownPropertyName]: KnownValueType[]
+} = {
+    CALSCALE: ['TEXT'],
+    METHOD: ['TEXT'],
+    PRODID: ['TEXT'],
+    VERSION: ['TEXT'],
+    ATTACH: ['URI', 'BINARY'],
+    CATEGORIES: ['TEXT'],
+    CLASS: ['TEXT'],
+    COMMENT: ['TEXT'],
+    DESCRIPTION: ['TEXT'],
+    GEO: ['FLOAT'],
+    LOCATION: ['TEXT'],
+    'PERCENT-COMPLETE': ['INTEGER'],
+    PRIORITY: ['INTEGER'],
+    RESOURCES: ['TEXT'],
+    STATUS: ['TEXT'],
+    SUMMARY: ['TEXT'],
+    COMPLETED: ['DATE-TIME'],
+    DTEND: ['DATE-TIME', 'DATE'],
+    DUE: ['DATE-TIME', 'DATE'],
+    DTSTART: ['DATE-TIME', 'DATE'],
+    DURATION: ['DURATION'],
+    FREEBUSY: ['PERIOD'],
+    TRANSP: ['TEXT'],
+    TZID: ['TEXT'],
+    TZNAME: ['TEXT'],
+    TZOFFSETFROM: ['UTC-OFFSET'],
+    TZOFFSETTO: ['UTC-OFFSET'],
+    TZURL: ['URI'],
+    ATTENDEE: ['CAL-ADDRESS'],
+    CONTACT: ['TEXT'],
+    ORGANIZER: ['CAL-ADDRESS'],
+    'RECURRENCE-ID': ['DATE-TIME', 'DATE'],
+    'RELATED-TO': ['TEXT'],
+    URL: ['URI'],
+    UID: ['TEXT'],
+    EXDATE: ['DATE-TIME', 'DATE'],
+    RDATE: ['DATE-TIME', 'DATE', 'PERIOD'],
+    RRULE: ['RECUR'],
+    ACTION: ['TEXT'],
+    REPEAT: ['INTEGER'],
+    TRIGGER: ['DURATION', 'DATE-TIME'],
+    CREATED: ['DATE-TIME'],
+    DTSTAMP: ['DATE-TIME'],
+    'LAST-MODIFIED': ['DATE-TIME'],
+    SEQUENCE: ['INTEGER'],
+    'REQUEST-STATUS': ['TEXT'],
+}
+
+/**
+ * Get the default value type of a property based on its name.
+ * @param name The name of the property.
+ * @returns The default value type of the property, or `TEXT` if the property is unknown.
+ */
+export function getDefaultValueType(name: AllowedPropertyName): KnownValueType {
+    const defaultType = supportedValueTypes[
+        name.toUpperCase() as KnownPropertyName
+    ]?.[0] as KnownValueType | undefined
+    return defaultType ?? 'TEXT'
+}

package/lib/property.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"property.d.ts","sourceRoot":"","sources":["../src/property.ts"],"names":[],"mappings":"AAIA,MAAM,WAAW,QAAQ;IACrB,IAAI,EAAE,MAAM,CAAA;IACZ,MAAM,EAAE,MAAM,EAAE,CAAA;IAChB,KAAK,EAAE,MAAM,CAAA;CAChB;AAED,eAAO,MAAM,kBAAkB,0hBA+CrB,CAAA;AACV,MAAM,MAAM,iBAAiB,GAAG,CAAC,OAAO,kBAAkB,CAAC,CAAC,MAAM,CAAC,CAAA;AACnE,MAAM,MAAM,mBAAmB,GACzB,iBAAiB,GACjB,CAAC,KAAK,MAAM,EAAE,GAAG,EAAE,CAAC,GACpB,CAAC,MAAM,GAAG,EAAE,CAAC,CAAA;AAEnB,eAAO,MAAM,eAAe,4JAelB,CAAA;AACV,MAAM,MAAM,cAAc,GAAG,CAAC,OAAO,eAAe,CAAC,CAAC,MAAM,CAAC,CAAA;AAC7D,MAAM,MAAM,gBAAgB,GAAG,cAAc,GAAG,CAAC,MAAM,GAAG,EAAE,CAAC,CAAA;AAE7D;;;GAGG;AACH,eAAO,MAAM,mBAAmB,EAAE;KAC7B,IAAI,IAAI,iBAAiB,GAAG,cAAc,EAAE;CAgDhD,CAAA;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAChC,QAAQ,EAAE,QAAQ,GACnB,gBAAgB,GAAG,SAAS,CAAA;AAE/B;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAChC,QAAQ,EAAE,QAAQ,EAClB,YAAY,EAAE,gBAAgB,GAC/B,gBAAgB,CAAA;AACnB,wBAAgB,oBAAoB,CAChC,QAAQ,EAAE,QAAQ,EAClB,YAAY,EAAE,gBAAgB,GAAG,SAAS,GAC3C,gBAAgB,GAAG,SAAS,CAAA;AAqB/B,6EAA6E;AAC7E,qBAAa,uBAAwB,SAAQ,KAAK;gBAClC,OAAO,EAAE,MAAM;CAI9B;AAED,0EAA0E;AAC1E,qBAAa,oBAAqB,SAAQ,KAAK;gBAC/B,OAAO,EAAE,MAAM;CAI9B;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,QAK3C;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,MAAM,QAK5C;AAED;;;;GAIG;AACH,wBAAgB,2BAA2B,CAAC,KAAK,EAAE,MAAM,QAQxD;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,QAQzC;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,MAAM,QAQ7C;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,MAAM,QAK7C;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,QAK1C;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,MAAM,QAK5C;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,QAK3C;AAED;;;;GAIG;AAEH,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,MAAM,QAEnD;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,QAKzC;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,QAKzC;AAED;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,QAQxC;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,MAAM,QAK9C;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,gBAAgB,QAgDlE;AAMD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,QAAQ,QAuClD"}