@dereekb/date 13.0.7 → 13.2.0

package/src/lib/rrule/date.recurrence.d.ts

@@ -2,38 +2,48 @@ import { type CalendarDate, type DateRange } from '../date';
 import { type DateRRuleInstance } from './date.rrule';
 import { type RRuleLines, type RRuleStringLineSet } from './date.rrule.parse';
 import { type TimezoneString } from '@dereekb/util';
+/**
+ * Marks an entity as potentially recurring by carrying optional
+ * {@link ModelRecurrenceInfo} and a convenience boolean flag.
+ */
 export interface RecurrenceModel {
+    /** Detailed recurrence metadata; undefined when the model does not recur. */
     recur?: ModelRecurrenceInfo;
+    /** Quick check for whether this model has active recurrence rules. */
     recurs: boolean;
 }
 /**
- * Indexed recurrence information for a model with recurrence information.
+ * Serializable recurrence metadata stored alongside a model, containing the
+ * RRule string, the computed start/end of the recurrence window, and a
+ * "forever" flag. Implements {@link DateRange} for easy integration with
+ * date-range utilities.
  */
-export declare class ModelRecurrenceInfo implements DateRange {
-    /**
-     * Timezone the rule is a part of.
-     *
-     * Required for RRules that have timezone-sensitive implementations.
-     */
+export interface ModelRecurrenceInfo extends DateRange {
+    /** Timezone the rule is a part of. Required for RRules that have timezone-sensitive implementations. */
     timezone?: TimezoneString;
-    /**
-     * RRules for this recurrence.
-     */
+    /** RRules for this recurrence. */
     rrule: RRuleLines;
-    /**
-     * First instance of the recurrence.
-     */
+    /** First instance of the recurrence. */
     start: Date;
-    /**
-     * Final instance of the recurrence.
-     */
+    /** Final instance of the recurrence. */
     end: Date;
-    /**
-     * True if the recurrence has no end.
-     */
+    /** True if the recurrence has no end. */
     forever?: boolean;
-    constructor(template?: ModelRecurrenceInfo);
 }
+/**
+ * ArkType schema for {@link ModelRecurrenceInfo}.
+ */
+export declare const modelRecurrenceInfoType: import("arktype/internal/variants/object.ts").ObjectType<{
+    rrule: string;
+    start: Date;
+    end: Date;
+    timezone?: string | undefined;
+    forever?: boolean | undefined;
+}, {}>;
+/**
+ * Input used to create or update recurrence on a model, before it is
+ * expanded into a full {@link ModelRecurrenceInfo}.
+ */
 export interface ModelRecurrenceStart {
     /**
      * Lines/set of rules to follow.
@@ -49,12 +59,46 @@ export interface ModelRecurrenceStart {
     timezone?: TimezoneString;
 }
 /**
- * Used for expanding a ModelRecurrenceUpdate into ModelRecurrenceInfo.
+ * Stateless utility for converting between recurrence input
+ * ({@link ModelRecurrenceStart}) and the indexed storage form
+ * ({@link ModelRecurrenceInfo}).
  */
 export declare class ModelRecurrenceInfoUtility {
     /**
-     * Creates a ModelRecurrenceInfo instance from the input ModelRecurrenceStart.
+     * Expands a {@link ModelRecurrenceStart} into a fully resolved
+     * {@link ModelRecurrenceInfo} by parsing the RRule, computing the
+     * recurrence date range, and populating the `forever` flag.
+     *
+     * @example
+     * ```ts
+     * const info = ModelRecurrenceInfoUtility.expandModelRecurrenceStartToModelRecurrenceInfo({
+     *   rrule: ['FREQ=WEEKLY;COUNT=10'],
+     *   date: { startsAt: new Date(), duration: 3600000 },
+     *   timezone: 'America/Chicago'
+     * });
+     * ```
+     *
+     * @param update - The recurrence start input to expand.
+     * @returns A new {@link ModelRecurrenceInfo} with computed start, end, and forever fields.
      */
     static expandModelRecurrenceStartToModelRecurrenceInfo(update: ModelRecurrenceStart): ModelRecurrenceInfo;
+    /**
+     * Creates a {@link DateRRuleInstance} from stored {@link ModelRecurrenceInfo}
+     * and a reference {@link CalendarDate}, allowing further expansion or
+     * recurrence queries.
+     *
+     * @example
+     * ```ts
+     * const instance = ModelRecurrenceInfoUtility.makeDateRRuleInstance(
+     *   model.recur,
+     *   { startsAt: new Date(), duration: 3600000 }
+     * );
+     * const nextDate = instance.nextRecurrenceDate();
+     * ```
+     *
+     * @param info - Stored recurrence metadata.
+     * @param date - Reference calendar date providing startsAt and duration.
+     * @returns A new {@link DateRRuleInstance} ready for expansion.
+     */
     static makeDateRRuleInstance(info: ModelRecurrenceInfo, date: CalendarDate): DateRRuleInstance;
 }

package/src/lib/rrule/date.rrule.d.ts

@@ -5,9 +5,15 @@ import { type BaseDateAsUTC, DateTimezoneUtcNormalInstance } from '../date/date.
 import { DateRRule } from './date.rrule.extension';
 import { type RRuleLines, type RRuleStringLineSet, type RRuleStringSetSeparation } from './date.rrule.parse';
 /**
- * Since RRule only deals with UTC date/times, dates going into it must always be in UTC.
+ * Alias emphasizing that dates passed to the RRule library must be expressed
+ * in UTC, since RRule internally treats all timestamps as UTC.
  */
 export type RRuleBaseDateAsUTC = BaseDateAsUTC;
+/**
+ * Options controlling which portion of a recurrence rule is expanded into
+ * concrete dates. Provide either a resolved {@link DateRange} or
+ * {@link DateRangeParams} to limit the expansion window.
+ */
 export interface DateRRuleExpansionOptions {
     /**
      * Start/End Dates to get the range between.
@@ -18,6 +24,10 @@ export interface DateRRuleExpansionOptions {
      */
     rangeParams?: DateRangeParams;
 }
+/**
+ * Parameters for constructing a {@link DateRRuleInstance}. Exactly one of
+ * `rruleLines` or `rruleStringLineSet` must be provided.
+ */
 export interface MakeDateRRuleInstance {
     /**
      * Lines string to build an RRule from.
@@ -32,6 +42,10 @@ export interface MakeDateRRuleInstance {
      */
     options: DateRRuleInstanceOptions;
 }
+/**
+ * Expansion options accepted by the static {@link DateRRuleUtility.expand}
+ * method. Provide either a pre-built instance or parameters to build one.
+ */
 export interface DateRRuleStaticExpansionOptions extends DateRRuleExpansionOptions {
     /**
      * DateRRuleInstanceInstance to use for expansion.
@@ -42,6 +56,10 @@ export interface DateRRuleStaticExpansionOptions extends DateRRuleExpansionOptio
      */
     instanceFrom?: MakeDateRRuleInstance;
 }
+/**
+ * Result of expanding a recurrence rule, containing the resolved dates and
+ * the optional range that was used to bound the expansion.
+ */
 export interface DateRRuleExpansion {
     /**
      * Range used for expansion, if applicable.
@@ -49,6 +67,10 @@ export interface DateRRuleExpansion {
     between?: Maybe<DateRange>;
     dates: CalendarDate[];
 }
+/**
+ * Configuration supplied when constructing a {@link DateRRuleInstance},
+ * including the reference date, optional timezone, and dates to exclude.
+ */
 export interface DateRRuleInstanceOptions {
     /**
      * Start reference/date. Required if DTSTART is not provided.
@@ -65,6 +87,10 @@ export interface DateRRuleInstanceOptions {
      */
     exclude?: DateSet;
 }
+/**
+ * A {@link DateRange} extended with recurrence-specific metadata, indicating
+ * whether the recurrence runs indefinitely and when the last occurrence ends.
+ */
 export interface RecurrenceDateRange extends DateRange {
     /**
      * True if the recurrence never ends.
@@ -77,49 +103,146 @@ export interface RecurrenceDateRange extends DateRange {
      */
     finalRecurrenceEndsAt?: Maybe<Date>;
 }
+/**
+ * Narrowed variant of {@link RecurrenceDateRange} for rules with no end
+ * (`forever: true`), guaranteeing `finalRecurrenceEndsAt` is undefined.
+ */
 export interface ForeverRecurrenceDateRange extends RecurrenceDateRange {
     forever: true;
     finalRecurrenceEndsAt?: undefined;
 }
+/**
+ * Wraps an RRule with timezone-aware date normalization so that recurrence
+ * expansion, next-date lookups, and range checks all work correctly across
+ * timezones.
+ *
+ * Use the static {@link DateRRuleInstance.make} factory or
+ * {@link DateRRuleUtility.makeInstance} to create instances.
+ */
 export declare class DateRRuleInstance {
     readonly options: DateRRuleInstanceOptions;
     readonly rrule: DateRRule;
     readonly normalInstance: DateTimezoneUtcNormalInstance;
     /**
-     * Creates a new DateRRuleInstance from the input.
+     * Factory that parses the RRule string, merges excluded dates, and builds
+     * a fully configured instance.
+     *
+     * @example
+     * ```ts
+     * const instance = DateRRuleInstance.make({
+     *   rruleLines: 'FREQ=DAILY;COUNT=5',
+     *   options: { date: { startsAt: new Date(), duration: 3600000 }, timezone: 'America/Chicago' }
+     * });
+     * ```
+     *
+     * @param params - RRule source and instance options.
+     * @throws Error if neither `rruleLines` nor `rruleStringLineSet` is provided.
+     * @returns A new {@link DateRRuleInstance}.
      */
     static make(params: MakeDateRRuleInstance): DateRRuleInstance;
     constructor(rrule: RRule, options: DateRRuleInstanceOptions);
     get timezone(): TimezoneString;
+    /**
+     * Returns the next recurrence date on or after the given reference date,
+     * or `undefined` if the recurrence has ended.
+     *
+     * @example
+     * ```ts
+     * const next = instance.nextRecurrenceDate(new Date());
+     * ```
+     *
+     * @param from - Reference point; defaults to now.
+     * @returns The next occurrence date, or `undefined`.
+     */
     nextRecurrenceDate(from?: Date): Maybe<Date>;
     /**
-     * Expands the input DateRRuleExpansionOptions to a DateRRuleExpansion.
+     * Expands the recurrence rule into concrete {@link CalendarDate} instances,
+     * optionally bounded by a date range.
+     *
+     * @example
+     * ```ts
+     * const expansion = instance.expand({
+     *   range: { start: new Date('2026-01-01'), end: new Date('2026-12-31') }
+     * });
+     * console.log(expansion.dates.length);
+     * ```
      *
-     * @param options
-     * @returns
+     * @param options - Range constraints for the expansion.
+     * @throws Error when the rule expands infinitely and no range is provided.
+     * @returns The expanded dates and the resolved range used.
      */
     expand(options: DateRRuleExpansionOptions): DateRRuleExpansion;
     /**
-     * Returns true if there is a single date within the range.
+     * Checks whether at least one recurrence falls within the given date range.
+     *
+     * @param dateRange - The range to test against.
+     * @returns `true` if any occurrence exists within the range.
      */
     haveRecurrenceInDateRange(dateRange: DateRange): boolean;
     /**
-     * Returns the date range from when the recurrence starts, to the end date.
+     * Computes the full date range spanned by this recurrence, from its first
+     * occurrence to the end of its last occurrence (accounting for event
+     * duration). Returns a {@link ForeverRecurrenceDateRange} when the rule
+     * has no count or until constraint.
+     *
+     * @returns The recurrence date range with `forever` flag and optional `finalRecurrenceEndsAt`.
      */
     getRecurrenceDateRange(): RecurrenceDateRange | ForeverRecurrenceDateRange;
+    /**
+     * Returns `true` when the underlying RRule has neither a `count` nor an
+     * `until` constraint, meaning it recurs indefinitely.
+     */
     hasForeverRange(): boolean;
 }
+/**
+ * Parsed RRule options combining the separated string components with the
+ * native `rrule` library's partial {@link Options}.
+ */
 export interface RRuleOptions extends RRuleStringSetSeparation {
     /**
      * Options for an RRule instance
      */
     options: Partial<Options>;
 }
+/**
+ * Stateless utility providing convenience factory and expansion methods for
+ * {@link DateRRuleInstance}. Prefer these static methods over constructing
+ * instances manually.
+ */
 export declare class DateRRuleUtility {
     /**
-     * Creates the expansion item results based on the input.
+     * Expands a recurrence rule into concrete dates using either a pre-built
+     * instance or parameters to build one on-the-fly.
+     *
+     * @example
+     * ```ts
+     * const result = DateRRuleUtility.expand({
+     *   instanceFrom: {
+     *     rruleLines: 'FREQ=WEEKLY;COUNT=4',
+     *     options: { date: { startsAt: new Date(), duration: 3600000 } }
+     *   },
+     *   range: { start: new Date('2026-01-01'), end: new Date('2026-03-01') }
+     * });
+     * ```
+     *
+     * @param options - Instance (or parameters to create one) and optional range.
+     * @throws Error if neither `instance` nor `instanceFrom` is provided.
+     * @returns The expansion result containing resolved dates.
      */
     static expand(options: DateRRuleStaticExpansionOptions): DateRRuleExpansion;
+    /**
+     * Convenience alias for {@link DateRRuleInstance.make}.
+     *
+     * @param params - RRule source and instance options.
+     * @returns A new {@link DateRRuleInstance}.
+     */
     static makeInstance(params: MakeDateRRuleInstance): DateRRuleInstance;
+    /**
+     * Parses an {@link RRuleStringLineSet} into native {@link RRuleOptions}
+     * that can be fed into the `rrule` library.
+     *
+     * @param rruleStringLineSet - The raw RRule string set to parse.
+     * @returns Parsed options including separated EXDATE and basic rule components.
+     */
     static toRRuleOptions(rruleStringLineSet: RRuleStringLineSet): RRuleOptions;
 }

package/src/lib/rrule/date.rrule.extension.d.ts

@@ -1,5 +1,10 @@
 import { type Maybe } from '@dereekb/util';
 import { RRule } from 'rrule';
+/**
+ * Internal iteration arguments used by the RRule iteration engine.
+ *
+ * Mirrors the shape expected by RRule's `_iter` method for custom iteration control.
+ */
 export interface IterArgs {
     inc: boolean;
     before: Date;
@@ -7,26 +12,53 @@ export interface IterArgs {
     dt: Date;
     _value: Date | Date[] | null;
 }
+/**
+ * Safety limit to prevent infinite iteration over unbounded recurrence rules.
+ */
 export declare const DEFAULT_LAST_ITER_RESULT_MAX_ITERATIONS_ALLOWED = 10000;
+/**
+ * Extended RRule that adds convenience methods for querying recurrence dates
+ * using custom iteration strategies (`last`, `next`, `any`).
+ *
+ * Works around missing typings in the upstream RRule library.
+ *
+ * @example
+ * ```ts
+ * const rule = new DateRRule({ freq: RRule.DAILY, dtstart: new Date() });
+ * const lastDate = rule.last();
+ * const nextDate = rule.next(new Date());
+ * const hasAny = rule.any({ minDate: startDate, maxDate: endDate });
+ * ```
+ */
 export declare class DateRRule extends RRule {
     /**
-     * Returns the last occurence that occurs in the rule chain.
+     * Returns the last occurrence in the rule chain, up to the configured max iteration limit.
      *
-     * @returns
+     * @example
+     * ```ts
+     * const rule = new DateRRule({ freq: RRule.DAILY, count: 5, dtstart: startDate });
+     * const lastDate = rule.last(); // fifth occurrence
+     * ```
      */
     last(): Maybe<Date>;
     /**
-     * Returns the next recurrence that occurs on/after the input date.
+     * Returns the first recurrence that occurs on or after the given date.
      *
-     * @returns
+     * @example
+     * ```ts
+     * const rule = new DateRRule({ freq: RRule.WEEKLY, dtstart: startDate });
+     * const nextDate = rule.next(new Date());
+     * ```
      */
     next(minDate: Date): Maybe<Date>;
     /**
-     * Returns any recurrence between the input min and max dates, if specified.
+     * Checks whether any recurrence falls within the optional date bounds.
      *
-     * @param minDate
-     * @param maxDate
-     * @returns
+     * @example
+     * ```ts
+     * const rule = new DateRRule({ freq: RRule.DAILY, dtstart: startDate });
+     * const exists = rule.any({ minDate: rangeStart, maxDate: rangeEnd });
+     * ```
      */
     any(filter?: {
         minDate?: Maybe<Date>;
@@ -47,7 +79,8 @@ declare abstract class BaseRRuleIter {
     getValue(): Date | null;
 }
 /**
- * Used by DateRRule to find the last result.
+ * Iterator result that captures the last date encountered before reaching the max future date
+ * or the iteration limit. Used by {@link DateRRule.last}.
  */
 export declare class LastIterResult extends BaseRRuleIter {
     private readonly _maxIterationsAllowed;
@@ -58,6 +91,10 @@ export declare class LastIterResult extends BaseRRuleIter {
     add(date: Date): boolean;
     clone(): LastIterResult;
 }
+/**
+ * Iterator result that finds the first recurrence on or after a minimum date.
+ * Stops iteration as soon as a qualifying date is found. Used by {@link DateRRule.next}.
+ */
 export declare class NextIterResult extends BaseRRuleIter {
     readonly minDate: Date;
     readonly maxIterationsAllowed: number;
@@ -67,6 +104,10 @@ export declare class NextIterResult extends BaseRRuleIter {
     add(date: Date): boolean;
     clone(): NextIterResult;
 }
+/**
+ * Iterator result that checks whether any recurrence falls within an optional date range.
+ * Stops as soon as one qualifying date is found. Used by {@link DateRRule.any}.
+ */
 export declare class AnyIterResult extends BaseRRuleIter {
     readonly maxIterationsAllowed: number;
     readonly minDate: Date | null;

package/src/lib/rrule/date.rrule.parse.d.ts

@@ -23,6 +23,9 @@ export type RRuleRawParamString = string;
  * Set of values.
  */
 export type RRuleRawValueSetString = CommaSeparatedString;
+/**
+ * A single raw value from an RRule value set.
+ */
 export type RRuleRawValueString = string;
 /**
  * RRule line broken into a name and value.
@@ -66,6 +69,9 @@ export type RFC5545DateString = string;
  * https://datatracker.ietf.org/doc/html/rfc5545#section-3.3.5
  */
 export type RFC5545DateTimeString = string;
+/**
+ * Result of separating an RRule string set into basic rules and parsed EXDATE exclusions.
+ */
 export interface RRuleStringSetSeparation {
     /**
      * All of the original input.
@@ -93,24 +99,101 @@ export interface RRuleExdateAttribute {
      */
     dates: Date[];
 }
+/**
+ * Delimiter separating the property name/params from values in an RRule line.
+ */
 export declare const RRuleStringSplitter = ":";
+/**
+ * Utility class for parsing and manipulating RFC 5545 RRule strings.
+ *
+ * Provides static methods for separating EXDATE rules, parsing RFC 5545 date-time strings,
+ * and converting between raw line formats and structured property representations.
+ *
+ * @example
+ * ```ts
+ * const lines = DateRRuleParseUtility.toRRuleStringSet(rruleString);
+ * const { basic, exdates } = DateRRuleParseUtility.separateRRuleStringSetValues(lines);
+ * ```
+ */
 export declare class DateRRuleParseUtility {
+    /**
+     * Splits an RRule line set into basic rules and parsed EXDATE exclusion dates.
+     *
+     * @example
+     * ```ts
+     * const result = DateRRuleParseUtility.separateRRuleStringSetValues([
+     *   'RRULE:FREQ=DAILY',
+     *   'EXDATE:20210611T110000Z'
+     * ]);
+     * // result.basic = ['RRULE:FREQ=DAILY']
+     * // result.exdates contains the parsed exclusion dates
+     * ```
+     */
     static separateRRuleStringSetValues(input: RRuleStringLineSet): RRuleStringSetSeparation;
+    /**
+     * Parses an EXDATE line into its timezone and date components.
+     *
+     * @throws Error if the line is not an EXDATE property.
+     */
     static parseExdateAttributeFromLine(line: RRuleLineString): RRuleExdateAttribute;
+    /**
+     * Extracts timezone and UTC-normalized dates from an already-parsed EXDATE property.
+     */
     static parseExdateAttributeFromProperty(property: RRuleProperty): RRuleExdateAttribute;
+    /**
+     * Convenience wrapper that creates a timezone converter and delegates to {@link parseDateTimeString}.
+     *
+     * @throws Error if the date string is not UTC and no timezone is provided.
+     */
     static parseDateTimeStringWithTimezone(rfcDateString: RFC5545DateString | RFC5545DateTimeString, timezone: Maybe<string>): Date;
     /**
-     * Parses the input Date-Time string.
+     * Parses an RFC 5545 date or date-time string into a JavaScript Date.
+     *
+     * If the string does not end in `Z` (indicating UTC), the converter is used to normalize
+     * the local date representation to its true UTC equivalent.
      *
-     * Timezone used to convert date to UTC if date is not specified in UTC (ends in Z).
+     * @throws Error if the string cannot be parsed or a non-UTC string lacks a converter.
      */
     static parseDateTimeString(rfcDateString: RFC5545DateString | RFC5545DateTimeString, converter: Maybe<DateTimezoneBaseDateConverter>): Date;
+    /**
+     * Formats a Date as an RFC 5545 UTC date-time string (e.g., `"20210611T110000Z"`).
+     *
+     * @example
+     * ```ts
+     * DateRRuleParseUtility.formatDateTimeString(new Date('2021-06-11T11:00:00Z'));
+     * // => '20210611T110000Z'
+     * ```
+     */
     static formatDateTimeString(date: Date): RFC5545DateTimeString;
+    /**
+     * Parses a full RRule line string into a structured {@link RRuleProperty}.
+     */
     static parseProperty(line: RRuleLineString): RRuleProperty;
+    /**
+     * Converts an {@link RRuleRawLine} into a structured {@link RRuleProperty} by splitting the type and params.
+     */
     static propertyFromRawLine(rawLine: RRuleRawLine): RRuleProperty;
+    /**
+     * Splits a raw param string (e.g., `"TZID=America/New_York"`) into key-value form.
+     */
     static parseRawParam(param: RRuleRawParamString): RRuleParam;
+    /**
+     * Splits a raw line at the colon delimiter into params and values portions.
+     * Falls back to treating a single-segment line as an RRULE value.
+     */
     static parseRawLine(line: RRuleLineString): RRuleRawLine;
+    /**
+     * Splits a newline-delimited RRule string into individual line strings.
+     */
     static toRRuleStringSet(lines: RRuleLines): RRuleStringLineSet;
+    /**
+     * Joins an array of RRule line strings into a single newline-delimited string.
+     */
     static toRRuleLines(rruleStringSet: RRuleStringLineSet): RRuleLines;
+    /**
+     * Asserts that the property has the expected type, throwing if it does not match.
+     *
+     * @throws Error if the property type does not match the expected type.
+     */
     static assertPropertyType(type: RRulePropertyType, property: RRuleProperty): void;
 }