@wtfalch/calendar 0.1.0 → 0.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,17 @@
1
+ /**
2
+ * The pure slot search behind `CalendarClient.findTime` (issue #13). No
3
+ * network and no server-shaped types here — just merging busy periods and
4
+ * walking the gaps between them, so the search itself is testable without a
5
+ * connection at all.
6
+ */
7
+ import type { AvailabilityResult, CalendarRange, WorkingHours } from './types.ts';
8
+ /** Every slot at least `duration` long where every *known* principal in
9
+ * `answers` is free. An unparseable `duration` (`wire.ts`'s
10
+ * `parseDurationMs` returning `null`) answers no slots rather than
11
+ * throwing — the same "do not crash a whole read over one bad value"
12
+ * discipline `availabilityFromWire` already follows. `principalIds` is
13
+ * only consulted when `workingHours` is a per-principal map, to know which
14
+ * principals besides `answers`' own keys (an unknown principal still gets
15
+ * its own working day considered, even with no busy periods to merge in)
16
+ * need one (wtfalch/calendar#31). */
17
+ export declare function findFreeSlots(answers: ReadonlyMap<string, AvailabilityResult>, range: CalendarRange, duration: string, workingHours: boolean | ReadonlyMap<string, WorkingHours>, principalIds?: readonly string[]): readonly CalendarRange[];
@@ -0,0 +1,198 @@
1
+ /**
2
+ * The pure slot search behind `CalendarClient.findTime` (issue #13). No
3
+ * network and no server-shaped types here — just merging busy periods and
4
+ * walking the gaps between them, so the search itself is testable without a
5
+ * connection at all.
6
+ */
7
+ import { parseDurationMs } from "./wire.js";
8
+ /** 09:00-17:00. Every busy period already arrives in UTC (`wire.ts`'s
9
+ * `availabilityFromWire`), so this is the fallback for `workingHours:
10
+ * true` and for a principal a per-attendee map (wtfalch/calendar#31)
11
+ * never names -- the same uniform bound the package used for everyone
12
+ * before that option existed (issue #13's original Decision). */
13
+ const WORKING_HOURS_START_UTC = 9;
14
+ const WORKING_HOURS_END_UTC = 17;
15
+ const UTC = { timeZone: 'UTC' };
16
+ /** Every *known* principal's busy periods, merged into one sorted,
17
+ * overlap-free timeline. An unknown principal contributes nothing, on
18
+ * purpose: this package never treats "cannot be seen" as a constraint to
19
+ * book around (`AvailabilityResult`'s own doc comment). */
20
+ function mergedBusy(answers) {
21
+ const raw = [];
22
+ for (const answer of answers.values()) {
23
+ if (answer.kind !== 'known')
24
+ continue;
25
+ for (const period of answer.periods) {
26
+ raw.push({ start: new Date(period.start).getTime(), end: new Date(period.end).getTime() });
27
+ }
28
+ }
29
+ raw.sort((a, b) => a.start - b.start);
30
+ const merged = [];
31
+ for (const interval of raw) {
32
+ const last = merged[merged.length - 1];
33
+ if (last && interval.start <= last.end)
34
+ last.end = Math.max(last.end, interval.end);
35
+ else
36
+ merged.push({ ...interval });
37
+ }
38
+ return merged;
39
+ }
40
+ /**
41
+ * The UTC instant of `hour:00` on the civil date `(year, month, day)` as
42
+ * read in `timeZone` (wtfalch/calendar#31). Guess the instant as if
43
+ * `timeZone` were UTC, read what `timeZone` actually shows for that guess,
44
+ * and correct by the difference — one pass, no timezone database beyond
45
+ * what `Intl.DateTimeFormat` already carries. Exact only up to a DST
46
+ * transition landing on this exact hour, which is the same limitation
47
+ * every offset-corrected-guess conversion has without a full tz-rules
48
+ * engine; a wrong hour on the one or two days a year that happens is a far
49
+ * smaller failure than the fixed-UTC window this option replaces.
50
+ */
51
+ function zonedHourToUtcMs(year, month, day, hour, timeZone) {
52
+ const guessMs = Date.UTC(year, month - 1, day, hour, 0, 0);
53
+ const parts = new Intl.DateTimeFormat('en-US', {
54
+ timeZone,
55
+ hourCycle: 'h23',
56
+ year: 'numeric',
57
+ month: '2-digit',
58
+ day: '2-digit',
59
+ hour: '2-digit',
60
+ minute: '2-digit',
61
+ second: '2-digit',
62
+ }).formatToParts(new Date(guessMs));
63
+ const get = (type) => Number(parts.find((part) => part.type === type)?.value ?? 0);
64
+ const asIfUtc = Date.UTC(get('year'), get('month') - 1, get('day'), get('hour'), get('minute'));
65
+ return guessMs - (asIfUtc - guessMs);
66
+ }
67
+ /** One principal's own working-day windows, one per civil day of theirs
68
+ * that overlaps `[rangeStart, rangeEnd)` -- walked by *their* calendar
69
+ * dates in `hours.timeZone`, not UTC's, so a zone far from UTC still gets
70
+ * its own correctly-placed window rather than one sliced by a UTC
71
+ * midnight that means nothing to that principal (wtfalch/calendar#31). */
72
+ function dailyWindows(rangeStart, rangeEnd, hours) {
73
+ const startHour = hours.startHour ?? WORKING_HOURS_START_UTC;
74
+ const endHour = hours.endHour ?? WORKING_HOURS_END_UTC;
75
+ const windows = [];
76
+ const civil = new Intl.DateTimeFormat('en-US', {
77
+ timeZone: hours.timeZone,
78
+ year: 'numeric',
79
+ month: '2-digit',
80
+ day: '2-digit',
81
+ }).formatToParts(new Date(rangeStart));
82
+ const get = (type) => Number(civil.find((part) => part.type === type)?.value ?? 0);
83
+ // Anchored as a UTC-noon instant per civil day, purely to step the
84
+ // calendar forward one day at a time with `setUTCDate` -- never read as
85
+ // a real instant itself.
86
+ const day = new Date(Date.UTC(get('year'), get('month') - 1, get('day'), 12));
87
+ // A year of days is far more than any sane `findTime` range asks for;
88
+ // it only guards a caller-supplied range from looping forever.
89
+ for (let i = 0; i < 366; i++) {
90
+ const start = zonedHourToUtcMs(day.getUTCFullYear(), day.getUTCMonth() + 1, day.getUTCDate(), startHour, hours.timeZone);
91
+ const end = zonedHourToUtcMs(day.getUTCFullYear(), day.getUTCMonth() + 1, day.getUTCDate(), endHour, hours.timeZone);
92
+ if (start >= rangeEnd)
93
+ break;
94
+ if (start < end && end > rangeStart) {
95
+ windows.push({ start: Math.max(start, rangeStart), end: Math.min(end, rangeEnd) });
96
+ }
97
+ day.setUTCDate(day.getUTCDate() + 1);
98
+ }
99
+ return windows;
100
+ }
101
+ /** The time covered by both `a` and `b` -- both already sorted and
102
+ * disjoint, so one sweep suffices. Used to fold one more principal's own
103
+ * working-day windows into the running candidate set: a slot must fall
104
+ * inside *every* named principal's own working day, not just one shared
105
+ * window (wtfalch/calendar#31). */
106
+ function intersect(a, b) {
107
+ const out = [];
108
+ let i = 0;
109
+ let j = 0;
110
+ while (i < a.length && j < b.length) {
111
+ const ai = a[i];
112
+ const bj = b[j];
113
+ if (!ai || !bj)
114
+ break;
115
+ const start = Math.max(ai.start, bj.start);
116
+ const end = Math.min(ai.end, bj.end);
117
+ if (start < end)
118
+ out.push({ start, end });
119
+ if (ai.end < bj.end)
120
+ i += 1;
121
+ else
122
+ j += 1;
123
+ }
124
+ return out;
125
+ }
126
+ /**
127
+ * `range`, split into candidate windows. `workingHours`:
128
+ * - `false`/`undefined`: the whole range, unsplit.
129
+ * - `true`: one uniform 09:00-17:00 UTC window per UTC day (issue #13's
130
+ * original behaviour, kept for a caller with no per-principal data).
131
+ * - a per-principal map: the intersection of every named principal's own
132
+ * working day, each in their own zone and hours -- a principal in
133
+ * `principalIds` but absent from the map falls back to the uniform
134
+ * 09:00-17:00 UTC window, same as `true` (wtfalch/calendar#31).
135
+ */
136
+ function candidateWindows(range, workingHours, principalIds) {
137
+ const rangeStart = new Date(range.after).getTime();
138
+ const rangeEnd = new Date(range.before).getTime();
139
+ if (rangeStart >= rangeEnd)
140
+ return [];
141
+ if (workingHours === false)
142
+ return [{ start: rangeStart, end: rangeEnd }];
143
+ if (workingHours === true)
144
+ return dailyWindows(rangeStart, rangeEnd, UTC);
145
+ let windows = [{ start: rangeStart, end: rangeEnd }];
146
+ for (const principalId of principalIds) {
147
+ const hours = workingHours.get(principalId) ?? UTC;
148
+ windows = intersect(windows, dailyWindows(rangeStart, rangeEnd, hours));
149
+ if (windows.length === 0)
150
+ break;
151
+ }
152
+ return windows;
153
+ }
154
+ /** One free slot per gap that fits `durationMs` — the earliest-starting fit
155
+ * in that gap, not every possible start inside it. `findTime` names where
156
+ * to look first; a start-time granularity nobody asked for would be an
157
+ * option this ticket does not need (issue #13 Decision). */
158
+ function slotsIn(window, busy, durationMs) {
159
+ const slots = [];
160
+ let cursor = window.start;
161
+ for (const period of busy) {
162
+ if (period.end <= cursor)
163
+ continue;
164
+ if (period.start >= window.end)
165
+ break;
166
+ if (period.start - cursor >= durationMs) {
167
+ slots.push({
168
+ after: new Date(cursor).toISOString(),
169
+ before: new Date(cursor + durationMs).toISOString(),
170
+ });
171
+ }
172
+ cursor = Math.max(cursor, period.end);
173
+ }
174
+ if (window.end - cursor >= durationMs) {
175
+ slots.push({
176
+ after: new Date(cursor).toISOString(),
177
+ before: new Date(cursor + durationMs).toISOString(),
178
+ });
179
+ }
180
+ return slots;
181
+ }
182
+ /** Every slot at least `duration` long where every *known* principal in
183
+ * `answers` is free. An unparseable `duration` (`wire.ts`'s
184
+ * `parseDurationMs` returning `null`) answers no slots rather than
185
+ * throwing — the same "do not crash a whole read over one bad value"
186
+ * discipline `availabilityFromWire` already follows. `principalIds` is
187
+ * only consulted when `workingHours` is a per-principal map, to know which
188
+ * principals besides `answers`' own keys (an unknown principal still gets
189
+ * its own working day considered, even with no busy periods to merge in)
190
+ * need one (wtfalch/calendar#31). */
191
+ export function findFreeSlots(answers, range, duration, workingHours, principalIds = [...answers.keys()]) {
192
+ const durationMs = parseDurationMs(duration);
193
+ if (!durationMs)
194
+ return [];
195
+ const busy = mergedBusy(answers);
196
+ const windows = candidateWindows(range, workingHours, principalIds);
197
+ return windows.flatMap((window) => slotsIn(window, busy, durationMs));
198
+ }
@@ -0,0 +1,73 @@
1
+ /**
2
+ * Export a `CalendarEvent` (or several) as an RFC 5545 `.ics` document
3
+ * (wtfalch/calendar#28), and `icsToEventDrafts` to import one back
4
+ * (wtfalch/calendar#41, the other half of agora#159,
5
+ * https://github.com/wtfalch/agora/issues/159). Read-only subscription feeds
6
+ * are still a separate, deferred gap (`PRODUCT.md`) -- `icsToEventDrafts` is
7
+ * a one-time parse, not a poller, and has no opinion on where its output
8
+ * ends up (`CalendarClient.importIcs`, `types.ts`, calls `createEvent` once
9
+ * per draft).
10
+ *
11
+ * **Every date-time is written in UTC (`Z`-suffixed), naively.** `start` is
12
+ * a local date-time with no offset, and `timeZone` says which zone it is
13
+ * local to -- but this package already treats every `start` as if it were
14
+ * UTC for its own display arithmetic (`EventDetail.tsx`'s `formatWhen`,
15
+ * `Calendar.tsx`'s grid rendering both do `new Date(`${event.start}Z`)`).
16
+ * Doing anything more accurate here -- resolving a named zone's real UTC
17
+ * offset -- would make this file the one place in the package that treats
18
+ * `timeZone` differently from everywhere else, for an event whose zone is
19
+ * "UTC" or unset in every fixture and every sample this package ships.
20
+ * `RecurrenceRule.until` shares the same treatment, which is also what RFC
21
+ * 5545 §3.3.10 requires: `UNTIL` must carry the same value type (UTC or
22
+ * not) as `DTSTART`.
23
+ *
24
+ * **`rscale`/`skip` (RFC 8984 §3.3, non-Gregorian calendars) have no RFC
25
+ * 5545 `RRULE` equivalent** and are silently omitted -- there is no
26
+ * standard part to write them into. Every other `CalendarRecurrenceRule`
27
+ * part round-trips (wtfalch/calendar#27's own `byDay`/`byMonthDay`/`byMonth`/
28
+ * `bySetPosition`/`firstDayOfWeek`/... included).
29
+ *
30
+ * **`virtualLocations` and `alerts` are not carried into the export.**
31
+ * Neither RFC 5545 property (`VALARM` for alerts; nothing standard for a
32
+ * join link distinct from `LOCATION`) was part of this ticket's evidence
33
+ * (`EventDetail.tsx` has no export control at all, not "an export control
34
+ * that drops one field"), so adding them is left to a later ticket.
35
+ */
36
+ import type { CalendarEvent, CalendarEventDraft, ImportIcsSkippedEvent } from './types.ts';
37
+ export type IcsExportOptions = {
38
+ /** The `DTSTAMP` moment. Injectable so a caller (or a test) does not have
39
+ * to accept the real wall clock, mirroring `EventEditor`'s/`Calendar`'s
40
+ * own `now` prop. Defaults to `new Date()`. */
41
+ now?: Date;
42
+ };
43
+ /** One or more events as a single RFC 5545 `.ics` document (a `VCALENDAR`
44
+ * wrapping one `VEVENT` per event) -- CRLF line endings and folding
45
+ * included, so the string this returns is ready to write to a file or hand
46
+ * to a `Blob` exactly as is. */
47
+ export declare function eventsToIcs(events: readonly CalendarEvent[], options?: IcsExportOptions): string;
48
+ /** A single event's own `.ics` document -- `EventDetail`'s "Download .ics"
49
+ * control (wtfalch/calendar#28) is this, one event at a time. */
50
+ export declare function eventToIcs(event: CalendarEvent, options?: IcsExportOptions): string;
51
+ /**
52
+ * One `CalendarEventDraft` per `VEVENT` in an RFC 5545 `.ics` document --
53
+ * the inverse of `eventsToIcs` (wtfalch/calendar#41). `calendarId` on each
54
+ * draft is a placeholder empty string: this function only ever sees the
55
+ * document, never the calendar it is being imported into, so
56
+ * `CalendarClient.importIcs` (`calendar-client.ts`) overwrites it before
57
+ * calling `createEvent`.
58
+ *
59
+ * A `VEVENT` outside a `BEGIN:VCALENDAR`/`END:VCALENDAR` pair, or with no
60
+ * matching `END:VEVENT`, is silently not collected -- the same tolerance a
61
+ * hand-written or partially-truncated `.ics` file needs, since this is a
62
+ * one-time import rather than a validator.
63
+ *
64
+ * A `VEVENT` that parses structurally but that `veventToDraft` cannot turn
65
+ * into a draft (no `DTSTART`, an `RRULE` `FREQ` this package does not
66
+ * recognise) is caught per event and reported in `skipped` rather than
67
+ * thrown -- one malformed `VEVENT` used to abort the whole document and
68
+ * discard every other, otherwise-valid one in it (wtfalch/calendar#46).
69
+ */
70
+ export declare function icsToEventDrafts(ics: string): {
71
+ readonly drafts: readonly CalendarEventDraft[];
72
+ readonly skipped: readonly ImportIcsSkippedEvent[];
73
+ };