@dereekb/date 13.4.0 → 13.4.1

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

@@ -7,9 +7,13 @@ import { type TimezoneString } from '@dereekb/util';
  * {@link ModelRecurrenceInfo} and a convenience boolean flag.
  */
 export interface RecurrenceModel {
-    /** Detailed recurrence metadata; undefined when the model does not recur. */
+    /**
+     * Detailed recurrence metadata; undefined when the model does not recur.
+     */
     recur?: ModelRecurrenceInfo;
-    /** Quick check for whether this model has active recurrence rules. */
+    /**
+     * Quick check for whether this model has active recurrence rules.
+     */
     recurs: boolean;
 }
 /**
@@ -19,15 +23,25 @@ export interface RecurrenceModel {
  * date-range utilities.
  */
 export interface ModelRecurrenceInfo extends DateRange {
-    /** Timezone the rule is a part of. Required for RRules that have timezone-sensitive implementations. */
+    /**
+     * 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;
 }
 /**

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

@@ -191,6 +191,8 @@ export declare class DateRRuleInstance {
     /**
      * Returns `true` when the underlying RRule has neither a `count` nor an
      * `until` constraint, meaning it recurs indefinitely.
+     *
+     * @returns `true` if the rule recurs indefinitely.
      */
     hasForeverRange(): boolean;
 }

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

@@ -39,6 +39,8 @@ export declare class DateRRule extends RRule {
      * const rule = new DateRRule({ freq: RRule.DAILY, count: 5, dtstart: startDate });
      * const lastDate = rule.last(); // fifth occurrence
      * ```
+     *
+     * @returns The last occurrence date, or `undefined` if there are none.
      */
     last(): Maybe<Date>;
     /**
@@ -49,6 +51,9 @@ export declare class DateRRule extends RRule {
      * const rule = new DateRRule({ freq: RRule.WEEKLY, dtstart: startDate });
      * const nextDate = rule.next(new Date());
      * ```
+     *
+     * @param minDate - The earliest date to consider.
+     * @returns The first occurrence on or after `minDate`, or `undefined` if none.
      */
     next(minDate: Date): Maybe<Date>;
     /**
@@ -59,6 +64,11 @@ export declare class DateRRule extends RRule {
      * const rule = new DateRRule({ freq: RRule.DAILY, dtstart: startDate });
      * const exists = rule.any({ minDate: rangeStart, maxDate: rangeEnd });
      * ```
+     *
+     * @param filter - Optional date bounds with `minDate` and `maxDate`.
+     * @param filter.minDate - Optional minimum date bound.
+     * @param filter.maxDate - Optional maximum date bound.
+     * @returns `true` if at least one recurrence falls within the bounds.
      */
     any(filter?: {
         minDate?: Maybe<Date>;

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

@@ -103,7 +103,9 @@ export interface RRuleExdateAttribute {
  * Delimiter separating the property name/params from values in an RRule line.
  */
 export declare const RRULE_STRING_SPLITTER = ":";
-/** @deprecated use RRULE_STRING_SPLITTER instead. */
+/**
+ * @deprecated use RRULE_STRING_SPLITTER instead.
+ */
 export declare const RRuleStringSplitter = ":";
 /**
  * Utility class for parsing and manipulating RFC 5545 RRule strings.
@@ -130,21 +132,32 @@ export declare class DateRRuleParseUtility {
      * // result.basic = ['RRULE:FREQ=DAILY']
      * // result.exdates contains the parsed exclusion dates
      * ```
+     *
+     * @param input - The RRule string line set to separate.
+     * @returns The separated basic rules and parsed EXDATE exclusion dates.
      */
     static separateRRuleStringSetValues(input: RRuleStringLineSet): RRuleStringSetSeparation;
     /**
      * Parses an EXDATE line into its timezone and date components.
      *
+     * @param line - The raw EXDATE line string to parse.
+     * @returns The parsed EXDATE attribute with timezone and dates.
      * @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.
+     *
+     * @param property - The parsed EXDATE property to extract from.
+     * @returns The EXDATE attribute containing timezone and UTC-normalized dates.
      */
     static parseExdateAttributeFromProperty(property: RRuleProperty): RRuleExdateAttribute;
     /**
      * Convenience wrapper that creates a timezone converter and delegates to {@link parseDateTimeString}.
      *
+     * @param rfcDateString - The RFC 5545 date or date-time string to parse.
+     * @param timezone - Optional timezone for non-UTC date strings.
+     * @returns The parsed JavaScript Date.
      * @throws Error if the date string is not UTC and no timezone is provided.
      */
     static parseDateTimeStringWithTimezone(rfcDateString: RFC5545DateString | RFC5545DateTimeString, timezone: Maybe<string>): Date;
@@ -154,6 +167,9 @@ export declare class DateRRuleParseUtility {
      * 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.
      *
+     * @param rfcDateString - The RFC 5545 date or date-time string to parse.
+     * @param converter - Optional timezone converter for non-UTC date strings.
+     * @returns The parsed JavaScript Date.
      * @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;
@@ -165,36 +181,59 @@ export declare class DateRRuleParseUtility {
      * DateRRuleParseUtility.formatDateTimeString(new Date('2021-06-11T11:00:00Z'));
      * // => '20210611T110000Z'
      * ```
+     *
+     * @param date - The date to format.
+     * @returns The RFC 5545 UTC date-time string representation.
      */
     static formatDateTimeString(date: Date): RFC5545DateTimeString;
     /**
      * Parses a full RRule line string into a structured {@link RRuleProperty}.
+     *
+     * @param line - The raw RRule line string to parse.
+     * @returns The structured property with type, params, and values.
      */
     static parseProperty(line: RRuleLineString): RRuleProperty;
     /**
      * Converts an {@link RRuleRawLine} into a structured {@link RRuleProperty} by splitting the type and params.
+     *
+     * @param rawLine - The raw line to convert.
+     * @returns The structured property with separated type, params, and values.
      */
     static propertyFromRawLine(rawLine: RRuleRawLine): RRuleProperty;
     /**
      * Splits a raw param string (e.g., `"TZID=America/New_York"`) into key-value form.
+     *
+     * @param param - The raw param string to split.
+     * @returns The parsed key-value param.
      */
     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.
+     *
+     * @param line - The raw RRule line string to split.
+     * @returns The raw line with separated params and values.
      */
     static parseRawLine(line: RRuleLineString): RRuleRawLine;
     /**
      * Splits a newline-delimited RRule string into individual line strings.
+     *
+     * @param lines - The newline-delimited RRule string to split.
+     * @returns An array of individual RRule line strings.
      */
     static toRRuleStringSet(lines: RRuleLines): RRuleStringLineSet;
     /**
      * Joins an array of RRule line strings into a single newline-delimited string.
+     *
+     * @param rruleStringSet - The array of RRule line strings to join.
+     * @returns A single newline-delimited RRule string.
      */
     static toRRuleLines(rruleStringSet: RRuleStringLineSet): RRuleLines;
     /**
      * Asserts that the property has the expected type, throwing if it does not match.
      *
+     * @param type - The expected property type.
+     * @param property - The property to check.
      * @throws Error if the property type does not match the expected type.
      */
     static assertPropertyType(type: RRulePropertyType, property: RRuleProperty): void;

package/src/lib/timezone/index.d.ts

@@ -1,2 +1 @@
 export * from './timezone';
-export * from './timezone.validator';

package/src/lib/timezone/timezone.d.ts

@@ -2,6 +2,8 @@ import { type Maybe, type TimezoneAbbreviation, type TimezoneString, type Timezo
 /**
  * Returns all recognized IANA timezone strings, including the explicit UTC entry.
  *
+ * @returns all known IANA timezone strings plus UTC
+ *
  * @example
  * ```ts
  * const zones = allTimezoneStrings();
@@ -32,18 +34,28 @@ export declare const allTimezoneInfos: import("@dereekb/util").CachedFactoryWith
  * {@link searchTimezoneInfos} can perform fast case-insensitive matching.
  */
 export interface TimezoneInfo extends TimezoneStringRef {
-    /** Searchable form with slashes/underscores replaced by spaces and lowercased. */
+    /**
+     * Searchable form with slashes/underscores replaced by spaces and lowercased.
+     */
     readonly search: string;
-    /** Lowercased IANA timezone identifier. */
+    /**
+     * Lowercased IANA timezone identifier.
+     */
     readonly lowercase: string;
-    /** Short abbreviation (e.g., `"EST"`, `"PDT"`). */
+    /**
+     * Short abbreviation (e.g., `"EST"`, `"PDT"`).
+     */
     readonly abbreviation: string;
-    /** Lowercased abbreviation for case-insensitive matching. */
+    /**
+     * Lowercased abbreviation for case-insensitive matching.
+     */
     readonly lowercaseAbbreviation: string;
 }
 /**
  * Returns the {@link TimezoneInfo} for the current system timezone, falling back to UTC.
  *
+ * @returns timezone info for the current system timezone
+ *
  * @example
  * ```ts
  * const info = timezoneInfoForSystem();
@@ -57,6 +69,10 @@ export declare function timezoneInfoForSystem(): TimezoneInfo;
  * The date matters because abbreviations change with DST transitions.
  * Returns `"UKNOWN"` if no timezone is provided.
  *
+ * @param timezone - the IANA timezone string (or UTC abbreviation) to get the abbreviation for
+ * @param date - the date at which to evaluate the abbreviation (defaults to now)
+ * @returns the short timezone abbreviation
+ *
  * @example
  * ```ts
  * getTimezoneAbbreviation('America/New_York'); // 'EST' or 'EDT'
@@ -68,6 +84,10 @@ export declare function getTimezoneAbbreviation(timezone: Maybe<TimezoneString |
  *
  * Returns `"Unknown Timezone"` if no timezone is provided.
  *
+ * @param timezone - the IANA timezone string to get the long name for
+ * @param date - the date at which to evaluate the name (defaults to now)
+ * @returns the full timezone display name
+ *
  * @example
  * ```ts
  * getTimezoneLongName('America/New_York'); // 'Eastern Standard Time'
@@ -77,6 +97,10 @@ export declare function getTimezoneLongName(timezone: Maybe<TimezoneString>, dat
 /**
  * Builds a {@link TimezoneInfo} for the given timezone, computing abbreviation and search variants.
  *
+ * @param timezone - the IANA timezone string to build info for
+ * @param date - the date at which to evaluate the abbreviation (defaults to now)
+ * @returns the computed TimezoneInfo
+ *
  * @example
  * ```ts
  * const info = timezoneStringToTimezoneInfo('America/Chicago');
@@ -91,6 +115,10 @@ export declare function timezoneStringToTimezoneInfo(timezone: TimezoneString, d
  *
  * For queries longer than 2 characters, substring matching on the searchable name is also used.
  *
+ * @param search - the search query string
+ * @param infos - the array of TimezoneInfo objects to filter
+ * @returns the matching TimezoneInfo entries
+ *
  * @example
  * ```ts
  * const results = searchTimezoneInfos('eastern', allTimezoneInfos());
@@ -102,6 +130,9 @@ export declare function searchTimezoneInfos(search: string, infos: TimezoneInfo[
  *
  * Replaces `/` and `_` with spaces (e.g., `"America/New_York"` becomes `"america new york"`).
  *
+ * @param timezone - the IANA timezone string to convert
+ * @returns the searchable lowercase string
+ *
  * @example
  * ```ts
  * timezoneStringToSearchableString('America/New_York'); // 'america new york'
@@ -113,6 +144,9 @@ export declare function timezoneStringToSearchableString(timezone: TimezoneStrin
  *
  * Uses the cached set from {@link allKnownTimezoneStrings} for O(1) lookup.
  *
+ * @param input - the string to check
+ * @returns whether the input is a known timezone
+ *
  * @example
  * ```ts
  * isKnownTimezone('America/New_York'); // true