diff options
author | Hugo Hörnquist <hugo@lysator.liu.se> | 2023-09-13 00:01:28 +0200 |
---|---|---|
committer | Hugo Hörnquist <hugo@lysator.liu.se> | 2023-09-13 00:01:28 +0200 |
commit | a82b6c772089aa46e30c6c89ef48f514294df3cb (patch) | |
tree | e25d9b6fd1fefe8b6ac293a5c0b53293872a8f54 /static/ts/types.ts | |
parent | Add basic documentation for lens. (diff) | |
parent | Even more documentation. (diff) | |
download | calp-a82b6c772089aa46e30c6c89ef48f514294df3cb.tar.gz calp-a82b6c772089aa46e30c6c89ef48f514294df3cb.tar.xz |
Merge branch 'next' into datarewrite-structures
Diffstat (limited to '')
-rw-r--r-- | static/ts/types.ts (renamed from static/types.ts) | 80 |
1 files changed, 77 insertions, 3 deletions
diff --git a/static/types.ts b/static/ts/types.ts index 64e2c709..a01f6672 100644 --- a/static/types.ts +++ b/static/ts/types.ts @@ -1,3 +1,8 @@ +/** + * Collection of type information for calendar data. + * @module + */ + export { ical_type, valid_input_types, @@ -6,6 +11,8 @@ export { ChangeLogEntry } + +/** Name of all valid icalendar types. */ let all_types = [ 'text', 'uri', @@ -23,6 +30,7 @@ let all_types = [ ] +/** The union of all elements in `all_types`. */ type ical_type = 'text' | 'uri' @@ -39,6 +47,10 @@ type ical_type | 'boolean' | 'unknown' +/** + * All known names properties (top level keys) can have. + * Such as "calscale", "dtstart", ... + */ let property_names = [ 'calscale', 'method', 'prodid', 'version', 'attach', 'categories', 'class', 'comment', 'description', 'geo', 'location', 'percent-complete', @@ -50,6 +62,15 @@ let property_names = [ ]; +/** + * Which property fields each component can hold. + * + * ```json + * { 'VCALENDAR': ['PRODID', 'VERSION', 'CALSCALE', 'METHOD'], + * ... + * } + * ``` + */ let valid_fields: Map<string, string[]> = new Map([ ['VCALENDAR', ['PRODID', 'VERSION', 'CALSCALE', 'METHOD']], ['VEVENT', ['DTSTAMP', 'UID', 'DTSTART', 'CLASS', 'CREATED', @@ -83,6 +104,12 @@ let valid_fields: Map<string, string[]> = new Map([ valid_fields.set('DAYLIGHT', valid_fields.get('STANDARD')!); +/** + All registered property types for VComponents. + + Note that only some of these are valid for each type of component (VCALENDAR, + VEVENT, ...), and that they all support both iana and `x-` extensions. + */ type known_ical_types = 'ACTION' | 'ATTACH' @@ -130,6 +157,18 @@ type known_ical_types | 'URL' | 'VERSION' +/** + * Which types are valid to store under each property. + * If multiple values are an option for that property, then + * the list of possibilities will contain a sub-list (see example). + * + * ```json + * { 'DTSTART': ['date', 'date-time'], + * 'CATEGORIES': [['text']], + * ... + * } + * ``` + */ let valid_input_types: Map<string, Array<ical_type | ical_type[]>> = new Map([ ['ACTION', ['text']], // AUDIO|DISPLAY|EMAIL|*other* @@ -184,25 +223,60 @@ let valid_input_types: Map<string, Array<ical_type | ical_type[]>> = // type JCalLine { // } -type tagname = 'vevent' | string - +/** The UID of a VEvent, to make declarations clearer. */ type uid = string /* TODO is this type correct? What really are valid values for any? Does that depend on ical_type? Why is the tail a list? What really is the type for the parameter map? */ +/* TODO link to RFC 7265 (jCal) */ +/** + * Alias for a record consisting of + * - the name of the type, as a string + * - all parameters of the object, as a `Record<String, any>` + * - An `ical_type` value, noting the type of the final field(s) + * - and one or more values of the type specified by the third field. + */ type JCalProperty = [string, Record<string, any>, ical_type, any] | [string, Record<string, any>, ical_type, ...any[]] -type JCal = [tagname, JCalProperty[], JCal[]] +/** + Base type for JCal documents. + + Each VComponent in a JCal document is of this form. + - The first element is the components type + ('vevent', 'vcalendar', ...), in all lower case + - The second element is is all properties directly + on the component. + - The third element is a list of all children. +*/ +type JCal = [string, JCalProperty[], JCal[]] + +/** The xml namespace name for xcalendar */ const xcal = "urn:ietf:params:xml:ns:icalendar-2.0"; +/** + An entry into a changelog. + + This is primarily used by VEvent, to track what has happened during a + session. + */ interface ChangeLogEntry { + /** + Type of change + + 'property' is used for changes to properties. + + 'calendar' is used when the containing calendar of a VEVENT is changed + */ type: 'calendar' | 'property', + /** The name of the filed changed */ name: string, + /** The previous value, `null` if just created */ from: string | null, + /** The new value, `null` if removed */ to: string | null, } |