react-native-roster 0.0.0 → 0.0.1

package/src/adapters/rrule/README.md

@@ -0,0 +1,41 @@
+# rrule adapter
+
+The shipped adapter. It converts a `RuleSet` of RFC 5545 rules and dated
+overrides into absolute intervals and gaps for one window, with exact
+provenance per span.
+
+- Public subpath: `react-native-roster/rrule`
+- Exports: `expandRuleSet`, `envelopeFor`, `clearExpandCache`, `expandStats`,
+  `resetExpandStats`, and the `RosterRule`, `RosterDate`, `RuleSet`,
+  `ExpandOptions`, `ExpandResult`, and `ExpandStats` types
+- Imports: `../../core` only; never components or another adapter
+- Owns: `rrule-temporal` and the Temporal polyfill; root and core never load them
+
+## Supported input
+
+`RosterRule` covers DAILY, WEEKLY, and MONTHLY with `interval`, `count`,
+`until`, `wkst`, `byweekday`, `bymonth`, `bymonthday`, and `bysetpos`, plus
+`hourstart`, `hourend`, and an IANA `timezone`. `RosterDate` is a single local
+date, whole day or with hours. Both are `include` or `exclude`. YEARLY and
+unbounded strings are rejected by validation.
+
+## File map
+
+| File | Role |
+| --- | --- |
+| `index.ts` | the entry point; the only barrel |
+| `types.ts` | input and result types |
+| `validate.ts` | input rejection before any engine work |
+| `envelope.ts` | widens a window to whole local days per rule zone |
+| `occurrences.ts` | drives the engine and applies every calendar correction |
+| `net.ts` | nets includes against excludes into intervals and gaps |
+| `cache.ts`, `hash.ts` | retained occurrences and envelopes keyed by content |
+| `expand.ts` | the orchestrator: validate, envelope, expand, cap, net, attach |
+
+## Reference
+
+- [Recurrence semantics](../../../docs/recurrence.md): the rules `occurrences.ts` follows
+- [Caches](../../../docs/caches.md): retention, keys, and counters
+- [Adapters guide](../../../docs/adapters.md): the consumer view for any upstream shape
+- [Adding an adapter](../../../docs/adding-an-adapter.md): the contributor recipe
+- Tests: `test/adapters/rrule`

package/src/adapters/rrule/cache.ts

@@ -0,0 +1,50 @@
+import type { Window } from '../../core';
+import { envelopeFor } from './envelope';
+import type { ExpandStats } from './types';
+
+export type Occurrences = { spans: Window[]; capped: boolean };
+export const occurrences = new Map<string, Occurrences>();
+const envelopes = new Map<string, Window>();
+const counts: ExpandStats = { rules: 0, dates: 0, expanded: 0, cacheHits: 0, cacheMisses: 0 };
+
+// Map insertion order is the LRU: reads move entries to the newest end.
+// Envelope retention selects bounds only; no netted result is retained.
+export function touch<T>(cache: Map<string, T>, key: string, value: T): T {
+  cache.delete(key);
+  cache.set(key, value);
+  return value;
+}
+
+export function trim<T>(cache: Map<string, T>, limit: number): void {
+  while (cache.size > limit) cache.delete(cache.keys().next().value as string);
+}
+
+export function retainedEnvelope(window: Window, limit: number): Window {
+  trim(envelopes, limit);
+  for (const [id, envelope] of [...envelopes].reverse()) {
+    if (envelope.start <= window.start && envelope.end >= window.end) {
+      return touch(envelopes, id, envelope);
+    }
+  }
+  const envelope = envelopeFor(window);
+  touch(envelopes, JSON.stringify(envelope), envelope);
+  trim(envelopes, limit);
+  return envelope;
+}
+
+export function recordStats(stats: ExpandStats): void {
+  for (const key of Object.keys(counts) as Array<keyof ExpandStats>) counts[key] += stats[key];
+}
+
+export function expandStats(): ExpandStats {
+  return { ...counts };
+}
+
+export function resetExpandStats(): void {
+  for (const key of Object.keys(counts) as Array<keyof ExpandStats>) counts[key] = 0;
+}
+
+export function clearExpandCache(): void {
+  occurrences.clear();
+  envelopes.clear();
+}

package/src/adapters/rrule/envelope.ts

@@ -0,0 +1,7 @@
+import type { Window } from '../../core';
+
+// Absolute 48-hour padding exceeds the 26-hour difference between view zones.
+// Includes, excludes, and dates share these bounds before subtraction.
+export function envelopeFor(window: Window): Window {
+  return { start: window.start - 48 * 3_600_000, end: window.end + 48 * 3_600_000 };
+}

package/src/adapters/rrule/expand.ts

@@ -0,0 +1,105 @@
+import type { Interval, Source, Window } from '../../core';
+import { occurrences, recordStats, retainedEnvelope, touch, trim } from './cache';
+import { envelopeFor } from './envelope';
+import { bodyKey } from './hash';
+import { net } from './net';
+import { enumerate, validateDates } from './occurrences';
+import type {
+  ExpandOptions,
+  ExpandResult,
+  ExpandStats,
+  RosterDate,
+  RosterRule,
+  RuleSet,
+} from './types';
+import { nonnegativeInteger, validateInput, validateWindow } from './validate';
+
+export function expandRuleSet(
+  set: RuleSet,
+  window: Window,
+  options: ExpandOptions = {},
+): ExpandResult {
+  validateWindow(window);
+  const maxEntries = nonnegativeInteger(options.cache?.maxEntries ?? 2000, 'cache.maxEntries');
+  const maxEnvelopes = nonnegativeInteger(options.cache?.maxEnvelopes ?? 4, 'cache.maxEnvelopes');
+  const cap = nonnegativeInteger(
+    options.caps?.perRuleOccurrences ?? 400,
+    'caps.perRuleOccurrences',
+  );
+  let remaining = nonnegativeInteger(
+    options.caps?.totalOccurrences ?? 10000,
+    'caps.totalOccurrences',
+  );
+  const rules = [...set.rules].sort(byId);
+  const dates = [...set.dates].sort(byId);
+  const ordered = [...rules, ...dates];
+  for (const input of ordered) {
+    validateInput(input);
+    validateDates(input);
+  }
+  const stats: ExpandStats = {
+    rules: set.rules.length,
+    dates: set.dates.length,
+    expanded: 0,
+    cacheHits: 0,
+    cacheMisses: 0,
+  };
+  if (window.start === window.end) {
+    recordStats(stats);
+    return {
+      intervals: [],
+      gaps: [],
+      envelope: envelopeFor(window),
+      complete: true,
+      truncated: [],
+      stats,
+    };
+  }
+  const envelope = retainedEnvelope(window, maxEnvelopes);
+  trim(occurrences, maxEntries);
+  const includes: Interval[] = [];
+  const excludes: Interval[] = [];
+  const truncated: ExpandResult['truncated'] = [];
+  let dropped = false;
+  for (const input of ordered) {
+    const key = JSON.stringify([bodyKey(input), envelope.start, envelope.end, cap]);
+    let list = occurrences.get(key);
+    if (list) {
+      touch(occurrences, key, list);
+      stats.cacheHits++;
+    } else {
+      list = enumerate(input, envelope, cap);
+      touch(occurrences, key, list);
+      trim(occurrences, maxEntries);
+      stats.expanded++;
+      stats.cacheMisses++;
+    }
+    // No partial admission: the first list that cannot fit ends the admitted
+    // prefix. Fetch all later lists anyway to report their exact retained counts.
+    dropped ||= list.spans.length > remaining;
+    if (dropped || list.capped) {
+      truncated.push({
+        id: input.id,
+        droppedAtLeast: list.capped ? 1 : list.spans.length,
+      });
+    }
+    if (dropped) continue;
+    remaining -= list.spans.length;
+    const source: Source = { kind: 'date' in input ? 'date' : 'rule', id: input.id };
+    if ('date' in input && input.note !== undefined) source.label = input.note;
+    const target = input.kind === 'include' ? includes : excludes;
+    for (const span of list.spans) target.push({ ...span, sources: [source] });
+  }
+  recordStats(stats);
+  return {
+    ...net(includes, excludes, window),
+    envelope: { ...envelope },
+    complete: truncated.length === 0,
+    truncated,
+    stats,
+  };
+}
+
+function byId(a: RosterRule | RosterDate, b: RosterRule | RosterDate): number {
+  return a.id < b.id ? -1 : a.id > b.id ? 1 : 0;
+}

package/src/adapters/rrule/hash.ts

@@ -0,0 +1,13 @@
+import { structuralKey } from '../../core/hash';
+import type { RosterDate, RosterRule } from './types';
+
+// Use the core's collision-free canonical encoding as the content hash.
+// Identity and display notes are attached fresh, never cached in occurrence lists.
+export function bodyKey(input: RosterRule | RosterDate): string {
+  const { id: _id, ...body } = input;
+  if ('date' in body) {
+    const { note: _note, ...date } = body;
+    return structuralKey(date);
+  }
+  return structuralKey(body);
+}

package/src/adapters/rrule/index.ts

@@ -0,0 +1,11 @@
+export { clearExpandCache, expandStats, resetExpandStats } from './cache';
+export { envelopeFor } from './envelope';
+export { expandRuleSet } from './expand';
+export type {
+  ExpandOptions,
+  ExpandResult,
+  ExpandStats,
+  RosterDate,
+  RosterRule,
+  RuleSet,
+} from './types';

package/src/adapters/rrule/net.ts

@@ -0,0 +1,30 @@
+import type { Gap, Interval, Window } from '../../core';
+import { sourceSpans } from '../../core/spans';
+
+export function net(
+  includes: Interval[],
+  excludes: Interval[],
+  window: Window,
+): { intervals: Interval[]; gaps: Gap[] } {
+  const covered = sourceSpans(includes, window);
+  const removed = sourceSpans(excludes, window);
+  const intervals: Interval[] = [];
+  const gaps: Gap[] = [];
+  let first = 0;
+  for (const include of covered) {
+    let start = include.start;
+    while (first < removed.length && (removed[first] as Gap).end <= start) first++;
+    for (let i = first; i < removed.length; i++) {
+      const exclude = removed[i] as Gap;
+      if (exclude.start >= include.end) break;
+      if (start < exclude.start)
+        intervals.push({ start, end: exclude.start, sources: include.sources });
+      const end = Math.min(include.end, exclude.end);
+      gaps.push({ start: Math.max(start, exclude.start), end, sources: exclude.sources });
+      start = end;
+    }
+    if (start < include.end) intervals.push({ start, end: include.end, sources: include.sources });
+  }
+  // Include source changes cannot split an otherwise identical removed span.
+  return { intervals, gaps: sourceSpans(gaps, window) };
+}

package/src/adapters/rrule/occurrences.ts

@@ -0,0 +1,288 @@
+import type * as RRuleModule from 'rrule-temporal' with { 'resolution-mode': 'import' };
+import type * as Spec from 'temporal-spec' with { 'resolution-mode': 'import' };
+import type { Weekday, Window } from '../../core';
+import type { Occurrences } from './cache';
+import type { RosterDate, RosterRule } from './types';
+
+// 1.6.0 is an ES module package with a CommonJS build under its require condition
+// and declarations resolved under import. Keep its actual types while selecting
+// the require export for our CJS build and Metro source entry.
+const { allowedWeekdays, RRuleTemporal } = require('rrule-temporal') as typeof RRuleModule;
+// Both engines must use the same polyfill export; mixed import/require copies
+// fail the recurrence engine's ZonedDateTime instanceof check.
+const { Temporal } = require('@js-temporal/polyfill') as { Temporal: typeof Spec.Temporal };
+
+type RuleDateTime = Spec.Temporal.PlainDateTime | Spec.Temporal.ZonedDateTime;
+
+export function enumerate(
+  input: RosterRule | RosterDate,
+  envelope: Window,
+  cap: number,
+  // Internal reference path for testing against original-anchor enumeration.
+  advanceAnchor = true,
+): Occurrences {
+  const result: Occurrences = { spans: [], capped: false };
+  const admit = (date: Spec.Temporal.PlainDate): boolean => {
+    const span = hoursFor(date, input);
+    if (span.start >= envelope.end || span.end <= envelope.start || span.start >= span.end)
+      return true;
+    if (result.spans.length === cap) {
+      result.capped = true;
+      return false;
+    }
+    result.spans.push(span);
+    return true;
+  };
+  if ('date' in input) {
+    admit(Temporal.PlainDate.from(input.date));
+    return result;
+  }
+  const original = dateTime(input.dtstart, input.timezone);
+  const originalWall = plain(original);
+  // A cross-date rollback can leave the end on the preceding wall date.
+  // Include the following date completely; envelope clipping discards extra candidates.
+  const upper = Temporal.Instant.fromEpochMilliseconds(envelope.end)
+    .toZonedDateTimeISO(input.timezone)
+    .add({ days: 2 })
+    .startOfDay();
+  const until =
+    input.until === undefined
+      ? upper.toPlainDateTime()
+      : dateTime(input.until, input.timezone, true);
+  const untilDate =
+    input.until !== undefined && /^\d{4}-\d{2}-\d{2}$/.test(input.until)
+      ? Temporal.PlainDate.from(input.until)
+      : undefined;
+  if (
+    !untilDate &&
+    (until instanceof Temporal.ZonedDateTime
+      ? Temporal.ZonedDateTime.compare(
+          until,
+          anchorFor(original.toPlainDate(), original, input.timezone),
+        ) < 0
+      : Temporal.PlainDateTime.compare(until, originalWall) < 0)
+  )
+    return result;
+  const anchorWallTime = original.toPlainTime();
+  // Iterate wall dates in UTC so zone skips cannot normalize a candidate date.
+  // The callback applies the original date cutoff or the exact datetime UNTIL.
+  const untilDateEnd = (untilDate ?? until.toPlainDate())
+    // An instant after a midnight rollback can have the preceding local date.
+    // Keep the later wall date available for the callback's exact-instant filter.
+    .add({ days: until instanceof Temporal.ZonedDateTime ? 1 : 0 })
+    .toPlainDateTime('23:59:59.999')
+    .toZonedDateTime('UTC');
+  const upperDate = upper.toPlainDateTime().toZonedDateTime('UTC');
+  // Only midnight anchors with interval 1 and no COUNT may skip periods.
+  const anchor =
+    advanceAnchor &&
+    (input.interval === undefined || input.interval === 1) &&
+    input.count === undefined &&
+    anchorWallTime.equals('00:00')
+      ? advance(originalWall, envelope, input)
+      : originalWall;
+  const positional = !!input.bysetpos?.length;
+  const unit = periodUnit(input);
+  const firstPeriod = periodStart(anchor.toPlainDate(), input);
+  const bound =
+    Temporal.ZonedDateTime.compare(untilDateEnd, upperDate) < 0 ? untilDateEnd : upperDate;
+  const lastPeriod = periodStart(bound.toPlainDate(), input);
+  if (Temporal.PlainDate.compare(firstPeriod, lastPeriod) > 0) return result;
+  // 1.5.2 tests UNTIL only while visiting candidates in its monthly loop.
+  // Every supported loop advances at least one authored period per iteration.
+  // Exhaustion after the final query period is complete, even with no candidates.
+  const maxIterations =
+    Math.floor(firstPeriod.until(lastPeriod, { largestUnit: unit })[unit] / (input.interval ?? 1)) +
+    1;
+  const engine = new RRuleTemporal({
+    freq: input.frequency,
+    dtstart: firstPeriod.toPlainDateTime(anchorWallTime).toZonedDateTime('UTC'),
+    // Positions must see the entire final period before UNTIL and envelope admission.
+    until: positional
+      ? lastPeriod
+          .add({ [unit]: 1 })
+          .toZonedDateTime('UTC')
+          .subtract({ milliseconds: 1 })
+      : bound,
+    interval: input.interval,
+    wkst: allowedWeekdays[input.wkst ?? 0],
+    byDay:
+      input.frequency !== 'DAILY' && input.byweekday?.length
+        ? input.byweekday.map((day) => allowedWeekdays[day])
+        : input.frequency === 'WEEKLY' && !input.bymonthday?.length
+          ? [allowedWeekdays[(original.dayOfWeek - 1) as Weekday]]
+          : undefined,
+    byMonth: input.bymonth,
+    // Explicitly preserve the implicit monthly day; 1.5.2's fallback otherwise
+    // constrains a 31st through February and drifts subsequent months.
+    byMonthDay: input.bymonthday?.length
+      ? input.bymonthday
+      : input.frequency === 'MONTHLY' && !input.byweekday?.length
+        ? [original.day]
+        : undefined,
+    tzid: 'UTC',
+    includeDtstart: false,
+    maxIterations,
+  });
+  // Version 1.5.2 can replay the iterator when applying its final count filter.
+  // Admit each local date once so replay cannot consume COUNT or the cap twice.
+  const visited = new Set<string>();
+  let admitted = 0;
+  const visit = (date: Spec.Temporal.PlainDate): boolean => {
+    if (result.capped || admitted === input.count) return false;
+    if (Temporal.PlainDate.compare(date, original.toPlainDate()) < 0) return true;
+    const key = date.toString();
+    if (visited.has(key)) return true;
+    visited.add(key);
+    if (untilDate) {
+      if (Temporal.PlainDate.compare(date, untilDate) > 0) return true;
+    } else if (
+      until instanceof Temporal.ZonedDateTime
+        ? Temporal.ZonedDateTime.compare(anchorFor(date, original, input.timezone), until) > 0
+        : Temporal.PlainDateTime.compare(date.toPlainDateTime(anchorWallTime), until) > 0
+    )
+      return true;
+    if (!date.toZonedDateTime(input.timezone).toPlainDate().equals(date)) return true;
+    // Lifetime COUNT includes existing dates before the envelope, but never skipped dates.
+    admitted++;
+    return admit(date);
+  };
+  let candidateCount = 0;
+  let period = '';
+  let candidates: Spec.Temporal.PlainDate[] = [];
+  const flush = (): boolean => {
+    const selected = candidates.filter((_, index) =>
+      input.bysetpos?.some((position) =>
+        position > 0 ? index === position - 1 : index === candidates.length + position,
+      ),
+    );
+    candidates = [];
+    return selected.every(visit);
+  };
+  try {
+    engine.all((occurrence, index) => {
+      const date = occurrence.toPlainDate();
+      // Replayed callback indices restart at zero. They must not enlarge a
+      // buffered period, especially when the whole query has only one candidate.
+      if (positional && index < candidateCount) return false;
+      candidateCount++;
+      // DAILY BYDAY re-anchors the engine; filter the authored sequence here.
+      if (
+        input.frequency === 'DAILY' &&
+        input.byweekday?.length &&
+        !input.byweekday.includes((date.dayOfWeek - 1) as Weekday)
+      )
+        return true;
+      if (!positional) return visit(date);
+      const key = periodStart(date, input).toString();
+      if (key !== period) {
+        if (!flush()) return false;
+        period = key;
+      }
+      candidates.push(date);
+      return true;
+    });
+  } catch (error) {
+    if (
+      !(error instanceof Error) ||
+      error.message !== `Maximum iterations (${maxIterations}) exceeded in all()`
+    )
+      throw error;
+  }
+  flush();
+  return result;
+}
+
+// Validate temporal fields even when the display window has no elapsed time.
+export function validateDates(input: RosterRule | RosterDate): void {
+  if ('date' in input) {
+    Temporal.PlainDate.from(input.date).toZonedDateTime(input.timezone);
+    return;
+  }
+  plain(dateTime(input.dtstart, input.timezone)).toZonedDateTime(input.timezone);
+  if (input.until !== undefined)
+    plain(dateTime(input.until, input.timezone, true)).toZonedDateTime(input.timezone);
+}
+
+function hoursFor(date: Spec.Temporal.PlainDate, input: RosterRule | RosterDate): Window {
+  const midnight = date.toPlainDateTime();
+  const dayStart = date.toZonedDateTime(input.timezone);
+  if (!dayStart.toPlainDate().equals(date)) {
+    return { start: dayStart.epochMilliseconds, end: dayStart.epochMilliseconds };
+  }
+  const wholeDay = input.hourstart === undefined && input.hourend === undefined;
+  // Whole-day bounds resolve PlainDates to first instants. Explicit hours use
+  // compatible wall time, choosing the earlier repeat and advancing skips.
+  const at = (hour: number) => {
+    const wall = midnight.add({ milliseconds: Math.round(hour * 3_600_000) });
+    return (wholeDay ? wall.toPlainDate() : wall).toZonedDateTime(input.timezone).epochMilliseconds;
+  };
+  return { start: at(input.hourstart ?? 0), end: at(input.hourend ?? 24) };
+}
+
+function dateTime(value: string, timezone: string, endOfDate = false): RuleDateTime {
+  if (/^\d{4}-\d{2}-\d{2}$/.test(value)) {
+    const date = Temporal.PlainDate.from(value);
+    return date.toPlainDateTime(endOfDate ? '23:59:59.999' : '00:00');
+  }
+  if (/(?:Z|[+-]\d{2}:?\d{2})(?:\[[^\]]*\])?$/i.test(value)) {
+    return Temporal.Instant.from(value).toZonedDateTimeISO(timezone);
+  }
+  return Temporal.PlainDateTime.from(value);
+}
+
+function plain(value: RuleDateTime): Spec.Temporal.PlainDateTime {
+  return value instanceof Temporal.ZonedDateTime ? value.toPlainDateTime() : value;
+}
+
+// Keep the original wall time and back up one period so WKST/BYDAY cannot lose
+// an earlier candidate. A monthly jump must never constrain the 31st to the 28th.
+function advance(
+  original: Spec.Temporal.PlainDateTime,
+  envelope: Window,
+  input: RosterRule,
+): Spec.Temporal.PlainDateTime {
+  // Include the local date crossing the left edge, regardless of anchor wall time.
+  const lower = Temporal.Instant.fromEpochMilliseconds(envelope.start)
+    .toZonedDateTimeISO(input.timezone)
+    .startOfDay();
+  const unit =
+    input.frequency === 'MONTHLY' ? 'months' : input.frequency === 'WEEKLY' ? 'weeks' : 'days';
+  const originalDate = original.toPlainDate();
+  const interval = input.interval ?? 1;
+  const distance = originalDate.until(lower.toPlainDate(), { largestUnit: unit })[unit];
+  let steps = Math.max(0, Math.floor(distance / interval) - 1);
+  while (steps > 0) {
+    const candidate = originalDate.add({ [unit]: steps * interval });
+    if (
+      (unit !== 'weeks' || candidate.dayOfWeek === originalDate.dayOfWeek) &&
+      (unit !== 'months' || candidate.day === originalDate.day) &&
+      candidate.toZonedDateTime(input.timezone).toPlainDate().equals(candidate)
+    )
+      return candidate.toPlainDateTime(original.toPlainTime());
+    steps--;
+  }
+  return original;
+}
+
+// Prefer the original offset in repeated time; otherwise resolve skips compatibly.
+function anchorFor(
+  date: Spec.Temporal.PlainDate,
+  original: RuleDateTime,
+  timezone: string,
+): Spec.Temporal.ZonedDateTime {
+  return original instanceof Temporal.ZonedDateTime
+    ? original.with({ year: date.year, month: date.month, day: date.day }, { offset: 'prefer' })
+    : date.toPlainDateTime(original.toPlainTime()).toZonedDateTime(timezone);
+}
+
+function periodUnit(input: RosterRule): 'days' | 'weeks' | 'months' {
+  return input.frequency === 'MONTHLY' ? 'months' : input.frequency === 'WEEKLY' ? 'weeks' : 'days';
+}
+
+function periodStart(date: Spec.Temporal.PlainDate, input: RosterRule): Spec.Temporal.PlainDate {
+  if (input.frequency === 'MONTHLY') return date.with({ day: 1 });
+  if (input.frequency === 'WEEKLY')
+    return date.subtract({ days: (date.dayOfWeek - 1 - (input.wkst ?? 0) + 7) % 7 });
+  return date;
+}

package/src/adapters/rrule/types.ts

@@ -0,0 +1,52 @@
+import type { Gap, Interval, Weekday, Window } from '../../core';
+
+export type RosterRule = {
+  id: string;
+  kind: 'include' | 'exclude';
+  frequency: 'DAILY' | 'WEEKLY' | 'MONTHLY';
+  dtstart: string;
+  until?: string;
+  count?: number;
+  interval?: number;
+  wkst?: Weekday;
+  byweekday?: Weekday[];
+  bymonth?: number[];
+  bymonthday?: number[];
+  bysetpos?: number[];
+  /** Local hours in timezone, end-exclusive; 24 means next local midnight. */
+  hourstart: number;
+  hourend: number;
+  timezone: string;
+};
+
+export type RosterDate = {
+  id: string;
+  kind: 'include' | 'exclude';
+  date: string;
+  timezone: string;
+  note?: string;
+  /** Both hours present for a partial day, or both absent for the whole day. */
+  hourstart?: number;
+  hourend?: number;
+};
+
+export type RuleSet = { rules: RosterRule[]; dates: RosterDate[] };
+export type ExpandOptions = {
+  cache?: { maxEntries?: number; maxEnvelopes?: number };
+  caps?: { perRuleOccurrences?: number; totalOccurrences?: number };
+};
+export type ExpandStats = {
+  rules: number;
+  dates: number;
+  expanded: number;
+  cacheHits: number;
+  cacheMisses: number;
+};
+export type ExpandResult = {
+  intervals: Interval[];
+  gaps: Gap[];
+  envelope: Window;
+  complete: boolean;
+  truncated: Array<{ id: string; droppedAtLeast: number }>;
+  stats: ExpandStats;
+};

package/src/adapters/rrule/validate.ts

@@ -0,0 +1,78 @@
+import type { Window } from '../../core';
+import type { RosterDate, RosterRule } from './types';
+
+export function validateWindow(window: Window): void {
+  if (
+    !Number.isSafeInteger(window.start) ||
+    !Number.isSafeInteger(window.end) ||
+    window.start > window.end
+  ) {
+    throw new RangeError('window must have integer epoch milliseconds with start <= end');
+  }
+}
+
+export function nonnegativeInteger(value: number, name: string): number {
+  if (!Number.isSafeInteger(value) || value < 0)
+    throw new RangeError(`${name} must be a nonnegative integer`);
+  return value;
+}
+
+export function validateInput(input: RosterRule | RosterDate): void {
+  if (!input.id || !['include', 'exclude'].includes(input.kind)) {
+    throw new RangeError('Each rule or date needs an id and an include or exclude kind');
+  }
+  // Bound date strings before any regex sees them; a full offset-and-zone
+  // form is under 50 characters, and unbounded input would scan quadratically.
+  for (const name of ['dtstart', 'until', 'date'] as const) {
+    const value =
+      name in input ? (input as Partial<Record<typeof name, unknown>>)[name] : undefined;
+    if (value !== undefined && (typeof value !== 'string' || value.length > 64))
+      throw new RangeError(`${input.id}: ${name} must be a string of at most 64 characters`);
+  }
+  const { hourstart, hourend } = input;
+  if ((hourstart === undefined) !== (hourend === undefined)) {
+    throw new RangeError(`${input.id}: hourstart and hourend must both be present or both absent`);
+  }
+  if ('frequency' in input) {
+    if (!['DAILY', 'WEEKLY', 'MONTHLY'].includes(input.frequency))
+      throw new RangeError('Unsupported frequency');
+    if (hourstart === undefined) throw new RangeError('Rules require hourstart and hourend');
+    for (const name of ['count', 'interval'] as const) {
+      const value = input[name];
+      if (value !== undefined && (!Number.isSafeInteger(value) || value <= 0))
+        throw new RangeError(`${name} must be a positive integer`);
+    }
+    validateNumbers(input.wkst === undefined ? undefined : [input.wkst], 'wkst', 0, 6);
+    validateNumbers(input.byweekday, 'byweekday', 0, 6);
+    validateNumbers(input.bymonth, 'bymonth', 1, 12);
+    validateNumbers(input.bymonthday, 'bymonthday', -31, 31, true);
+    validateNumbers(input.bysetpos, 'bysetpos', -366, 366, true);
+  }
+  if (
+    hourstart !== undefined &&
+    hourend !== undefined &&
+    (!Number.isFinite(hourstart) ||
+      !Number.isFinite(hourend) ||
+      hourstart < 0 ||
+      hourstart >= hourend ||
+      hourend > 24)
+  ) {
+    throw new RangeError(`${input.id}: hours must satisfy 0 <= hourstart < hourend <= 24`);
+  }
+}
+
+function validateNumbers(
+  values: number[] | undefined,
+  name: string,
+  min: number,
+  max: number,
+  nonzero = false,
+): void {
+  if (
+    values?.some(
+      (value) => !Number.isInteger(value) || value < min || value > max || (nonzero && value === 0),
+    )
+  ) {
+    throw new RangeError(`Invalid ${name}`);
+  }
+}