slotlock 0.6.1 → 0.6.3

package/sync.d.ts

@@ -35,20 +35,17 @@ export interface ICalendarExpansionWindow {
 /** The most text one feed may be, in UTF-8 bytes. */
 export declare const MAX_ICAL_INPUT_BYTES = 2000000;
 /**
- * The ical.js release a series cursor holds the iterator state of. A cursor is ical.js's own
- * RecurIterator and RecurExpansion state, which only that release is known to continue exactly, so
- * a cursor another release wrote is ignored and the series searched from its start. A test pins this
- * to the installed package: upgrading ical.js means checking the state these cursors keep again.
+ * The ical.js release whose RecurIterator/RecurExpansion state a series cursor holds; only that
+ * release is known to continue it exactly, so a cursor another release wrote is ignored. A test
+ * pins this to the installed package: upgrading ical.js means rechecking cursor state.
  */
 export declare const ICAL_JS_VERSION = "2.2.1";
-/** The shape of the cursor this code writes and reads. */
 declare const SERIES_CURSOR_FORMAT = 1;
 /** A time's fields as ical.js holds them: year, month, day, hour, minute, second, a date or not. */
 type CursorTime = [number, number, number, number, number, number, boolean];
 /**
- * Where one expansion of a stored series stopped, as plain JSON a store keeps beside it: ical.js's
- * iterator state just before the first occurrence the next window may need, so the next expansion
- * continues there rather than searching again from the series' start.
+ * Where one expansion of a stored series stopped, as plain JSON stored beside it: ical.js's
+ * iterator state just before the first occurrence the next window may need.
  */
 export interface CalendarSeriesCursor {
     readonly v: typeof SERIES_CURSOR_FORMAT;
@@ -82,8 +79,7 @@ export declare class CalendarContractError extends Error {
     constructor(code: 'invalid_external_identity' | 'invalid_external_interval' | 'invalid_icalendar');
 }
 /**
- * A calendar that needs more work than Slotlock does to read or expand it: steps, time, a step or a
- * span longer than a century, or more occurrences, exceptions or dates than it keeps. Still
+ * A calendar that needs more work than Slotlock does to read or expand it. Still
  * `invalid_icalendar` to callers; the horizon roll counts these and skips the series.
  */
 export declare class CalendarExpansionLimitError extends CalendarContractError {
@@ -95,33 +91,28 @@ export declare class CalendarExpansionLimitError extends CalendarContractError {
  */
 export declare function recurrenceRuleProblem(rule: string): string | null;
 /**
- * A recurrence rule as RFC 5545 §3.3.10 writes it, in ical.js's canonical spelling, or `null`.
- * ical.js accepts more than it should: it drops unknown parts, lets a repeated part replace the
- * first, reads `COUNT=3X` as 3 and `COUNT=0` as no count at all. So every part must be one RFC 5545
- * names, appear once and match its grammar, with FREQ present and never UNTIL and COUNT together,
- * and the parts RFC 5545 forbids for a frequency (BYWEEKNO but YEARLY, BYYEARDAY with DAILY, WEEKLY
- * or MONTHLY, BYMONTHDAY with WEEKLY, a numbered BYDAY but MONTHLY or YEARLY) are refused. The
- * numeric BY lists come back in ascending order (sortRuleParts).
+ * A recurrence rule in ical.js's canonical spelling, or `null`. ical.js is too lenient (it drops
+ * unknown parts, lets a repeated part win, reads `COUNT=3X` as 3 and `COUNT=0` as none), so every
+ * part must be RFC 5545's, appear once and match its grammar, with FREQ present, never UNTIL with
+ * COUNT, and no part RFC 5545 forbids for the frequency. Numeric BY lists come back sorted
+ * (sortRuleParts).
  */
 export declare function canonicalRecurrenceRule(rule: string): string | null;
 /**
- * A rule Slotlock books from an agent: valid as RFC 5545 writes it, daily or less often, and able to
- * occur. ical.js searches day by day (or faster) for a DAILY, HOURLY, MINUTELY or SECONDLY rule's
- * next occurrence with no limit, so one that can never occur (`BYMONTH=2;BYMONTHDAY=30`), or a
- * sub-daily one that rarely does, holds the process forever.
+ * A rule Slotlock books from an agent: valid, daily or less often, and able to occur. ical.js
+ * searches sub-daily rules step by step with no limit, so one that never occurs
+ * (`BYMONTH=2;BYMONTHDAY=30`) would hold the process forever.
  */
 export declare function isBookableRecurrenceRule(rule: string): boolean;
 /** Validate, clone and bound trusted event content before persistence or serialization. */
 export declare function normalizeCalendarEventContent(input: CalendarEventContent): CalendarEventContent;
 export declare function normalizeExternalCalendarChange(input: ExternalCalendarChangeInput): ExternalCalendarChange;
 /**
- * Each line of `input` as ical.js 2.2.1's parser takes it, with the parameters it reads there: the
- * lines as parse._eachLine unfolds them, read with the design set ical.js picks at the first BEGIN,
- * and for a BEGIN line the component it begins. Ends at a line before that BEGIN, where ical.js
- * throws. ical.js changes its design set in one other place: a VCARD component's first property
- * (unless it is VERSION:4.0) moves it to vCard 3's for the rest of the feed. This does not follow
- * that move; boundPropertyHeads refuses a feed with a VCARD instead. With `limits`, a line's count
- * stops once it is past them. Exported for the tests, which hold it to ical.js's own reading.
+ * Each line of `input` as ical.js 2.2.1's parser takes it, with the parameters it reads there
+ * (parse._eachLine, with the design set picked at the first BEGIN), and for a BEGIN line the
+ * component. Stops before the first BEGIN, where ical.js throws. Does not follow a VCARD's switch
+ * to vCard 3 (boundPropertyHeads refuses those). With `limits`, a line's count stops once past
+ * them. Exported for the tests.
  */
 export declare function icalendarPropertyHeads(input: string, limits?: HeadLimits): Generator<{
     line: string;
@@ -135,12 +126,11 @@ interface HeadLimits {
     end: number;
 }
 /**
- * How many parameters ical.js 2.2.1 reads on one unfolded line and where it stops reading them
- * (parse._handleContentLine, then parse._parseParameters, step for step): a `"` opens a quoted value
- * only straight after `=`, a quoted value of a parameter that takes several (MEMBER, DELEGATED-TO)
- * goes on past `","`, and a `:` ends the parameters only where ical.js looks for one. ical.js throws
- * where this stops early (an empty name, an unclosed quote), and stops once past `limits` if given.
- * Exported for the tests, which hold it to ical.js's own count.
+ * How many parameters ical.js 2.2.1 reads on one unfolded line and where it stops
+ * (parse._handleContentLine, then _parseParameters, step for step): a `"` opens a quoted value only
+ * right after `=`, a multi-valued parameter (MEMBER, DELEGATED-TO) continues past `","`, and `:`
+ * ends the parameters only where ical.js looks for one. Stops early where ical.js throws, and past
+ * `limits` if given. Exported for the tests.
  */
 export declare function icalendarPropertyHead(line: string, params: Record<string, {
     multiValue?: string;
@@ -150,9 +140,9 @@ export declare function icalendarPropertyHead(line: string, params: Record<strin
 };
 /**
  * Parse VEVENTs with the standards library; event content is deliberately discarded. All or
- * nothing: a series Slotlock cannot read refuses the whole calendar, so a caller that reads the
- * result as the calendar's busy time never takes a refused series' time as free. To keep the rest
- * of a calendar when one series is refused, use parseICalendarFeed.
+ * nothing: a series Slotlock cannot read refuses the whole calendar, so a caller reading the result
+ * as busy time never takes its time as free. parseICalendarFeed keeps the rest of the calendar
+ * instead.
  */
 export declare function parseICalendarChanges(input: string, calendarTimezone?: string, expansionWindow?: ICalendarExpansionWindow): ExternalCalendarChange[];
 /** A series a feed holds that Slotlock refused to read, by its UID. */
@@ -169,11 +159,10 @@ export interface ICalendarFeedRead {
     refused: ICalendarSeriesRefusal[];
 }
 /**
- * parseICalendarChanges, refusing one series at a time: a series Slotlock cannot read (a rule
- * shape ical.js expands wrongly, an event whose end the clocks move before its start, DTEND with
- * DURATION, or one that needs more than its budget) is named in `refused` and the rest of the
- * calendar is read. A calendar that is not one (its size, its time zones, a missing UID, a window
- * past 367 days) is still refused whole, with CalendarContractError.
+ * parseICalendarChanges, refusing one series at a time: a series Slotlock cannot read (a
+ * misexpanded rule shape, an end the clocks move before its start, DTEND with DURATION, or over
+ * budget) is named in `refused` and the rest is read. A calendar that is not one (size, time zones,
+ * a missing UID, a window over 367 days) is still refused whole, with CalendarContractError.
  */
 export declare function parseICalendarFeed(input: string, calendarTimezone?: string, expansionWindow?: ICalendarExpansionWindow): ICalendarFeedRead;
 /** Deterministic RFC 5545 + iTIP payload, validated by the installed ical.js implementation. */
@@ -181,10 +170,9 @@ export declare function emitITipCalendar(input: ICalendarEvent, method: ITipMeth
 /** Backwards-compatible feed helper. Cancellation maps to iTIP CANCEL. */
 export declare function emitICalendar(input: ICalendarEvent): string;
 /**
- * Parse full, trusted event content. This is intentionally a different API from
- * parseICalendarChanges, whose return shape can never carry summaries, participants or notes.
- * All-day (DATE) events are converted to local-midnight bounds in the calendar's timezone: the
- * `calendarTimezone` argument, else the feed's X-WR-TIMEZONE; with neither they are refused.
+ * Parse full, trusted event content: deliberately a different API from parseICalendarChanges, whose
+ * result can never carry summaries, participants or notes. All-day events become local-midnight
+ * bounds in `calendarTimezone`, else X-WR-TIMEZONE; with neither they are refused.
  */
 export declare function parseTrustedICalendarEvents(input: string, calendarTimezone?: string): TrustedICalendarEvent[];
 /**
@@ -193,16 +181,16 @@ export declare function parseTrustedICalendarEvents(input: string, calendarTimez
  */
 export declare function expandCalendarEventOccurrences(input: CalendarEventContent, window: ICalendarExpansionWindow): CalendarEventOccurrence[];
 /**
- * The same expansion for a stored series as maintenance rolls it, within FEED_LIMITS: twice what it
- * was written within, so a series accepted once keeps rolling as its search grows.
+ * The same expansion for a stored series as maintenance rolls it, within FEED_LIMITS (more than a
+ * write gets), so a series accepted once keeps rolling as its search grows.
  */
 export declare function expandStoredCalendarEventOccurrences(input: CalendarEventContent, window: ICalendarExpansionWindow): CalendarEventOccurrence[];
 /**
- * Expand a stored series, resuming from the cursor its last expansion left when that cursor can
- * vouch for everything it skips, and leave a cursor for the next. Within FEED_LIMITS as maintenance
- * rolls it (`stored`), or EVENT_LIMITS as it is written. Whatever a cursor cannot serve (another
- * rule, start, zone or ical.js; a window starting before it; a longer event or an exception that
- * could reach the window from before it; anything malformed) is searched from the series' start.
+ * Expand a stored series, resuming from its last cursor when that cursor can vouch for everything
+ * it skips, and leave a cursor for the next. Within FEED_LIMITS when maintenance rolls it
+ * (`stored`), else EVENT_LIMITS. Anything a cursor cannot serve (other rule, start, zone or
+ * ical.js; a window before it; something that could reach the window from before it; malformed) is
+ * searched from the start.
  */
 export declare function expandCalendarEventSeries(input: CalendarEventContent, window: ICalendarExpansionWindow, options: {
     cursor: unknown;
@@ -211,12 +199,9 @@ export declare function expandCalendarEventSeries(input: CalendarEventContent, w
     resumeOnly?: boolean;
 }): CalendarSeriesExpansion;
 /**
- * Why this Slotlock refuses an event an earlier one stored, in words, or null when it expands it.
- * Maintenance counts such a series as refused on every roll and leaves it its old coverage: a rule
- * shape ical.js expands wrongly (recurrenceRuleProblem), COUNT with a yearly day some years lack, a
- * rule it no longer stores at all, or exceptions that name no occurrence (searched from the series'
- * start to the last of them, within a roll's budget). It writes nothing, so it can be run over
- * stored events before an upgrade.
+ * Why this Slotlock refuses an event an earlier one stored, or null. Maintenance counts such a
+ * series as refused on every roll and leaves its old coverage. Writes nothing, so it can be run
+ * over stored events before an upgrade.
  */
 export declare function storedCalendarEventProblem(event: CalendarEventContent): string | null;
 export {};