@dereekb/date 13.3.1 → 13.4.1

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

@@ -30,24 +30,28 @@ export interface YearMonthDayCodePair {
  * Extracts the year component from a {@link YearMonthDayCode} by dividing out the month and day digits.
  *
  * @param yearMonthDayCode - Encoded YYYYMMDD value to extract the year from
+ * @returns the year component of the code
  */
 export declare function yearMonthDayCodeYear(yearMonthDayCode: YearMonthDayCode): YearNumber;
 /**
  * Extracts the month component (1-12) from a {@link YearMonthDayCode} by isolating the middle two digits.
  *
  * @param yearMonthDayCode - Encoded YYYYMMDD value to extract the month from
+ * @returns the month component (1-12) of the code
  */
 export declare function yearMonthDayCodeMonth(yearMonthDayCode: YearMonthDayCode): MonthOfYear;
 /**
  * Extracts the day-of-month component (1-31) from a {@link YearMonthDayCode} by isolating the last two digits.
  *
  * @param yearMonthDayCode - Encoded YYYYMMDD value to extract the day from
+ * @returns the day-of-month component (1-31) of the code
  */
 export declare function yearMonthDayCodeDay(yearMonthDayCode: YearMonthDayCode): DayOfMonth;
 /**
  * Decomposes a {@link YearMonthDayCode} into its individual year, month, and day components.
  *
  * @param yearMonthDayCode - Encoded YYYYMMDD value to decompose
+ * @returns a pair containing the individual year, month, and day components
  */
 export declare function yearMonthDayCodePair(yearMonthDayCode: YearMonthDayCode): YearMonthDayCodePair;
 /**
@@ -56,6 +60,7 @@ export declare function yearMonthDayCodePair(yearMonthDayCode: YearMonthDayCode)
  * that need timezone-aware conversion should use {@link yearMonthDayCodeFactory} instead.
  *
  * @param date - Date to extract components from using local timezone
+ * @returns a pair containing the year, month, and day from the date
  */
 export declare function yearMonthDayCodePairFromDate(date: Date): YearMonthDayCodePair;
 /**
@@ -63,6 +68,7 @@ export declare function yearMonthDayCodePairFromDate(date: Date): YearMonthDayCo
  * using the formula `year * 10000 + month * 100 + day`.
  *
  * @param pair - Decomposed date components to encode
+ * @returns the encoded YYYYMMDD integer
  */
 export declare function yearMonthDayCodeFromPair(pair: YearMonthDayCodePair): YearMonthDayCode;
 /**
@@ -70,6 +76,7 @@ export declare function yearMonthDayCodeFromPair(pair: YearMonthDayCodePair): Ye
  * using the system's local timezone. For timezone-aware conversion, use {@link yearMonthDayCodeFactory}.
  *
  * @param date - Date to encode using local timezone
+ * @returns the encoded YYYYMMDD integer for the given date
  */
 export declare function yearMonthDayCodeFromDate(date: Date): YearMonthDayCode;
 /**
@@ -94,13 +101,14 @@ export interface YearMonthDayCodeConfig {
      *
      * Configured to use the system timezone by default.
      */
-    timezone?: YearMonthDayCodeDateTimezoneInput;
+    readonly timezone?: YearMonthDayCodeDateTimezoneInput;
 }
 /**
  * Resolves a {@link YearMonthDayCodeDateTimezoneInput} into a {@link DateTimezoneUtcNormalInstance},
  * falling back to the system timezone when no input is provided.
  *
  * @param input - Timezone configuration or existing instance to resolve
+ * @returns a DateTimezoneUtcNormalInstance, falling back to the system timezone
  */
 export declare function yearMonthDayCodeDateTimezoneInstance(input: YearMonthDayCodeDateTimezoneInput): DateTimezoneUtcNormalInstance;
 /**
@@ -116,6 +124,12 @@ export declare function yearMonthDayCodeDateTimezoneInstance(input: YearMonthDay
  * // From explicit components (year, month 1-12, day)
  * const code2 = yearMonthDayCode(2022, 1, 15); // 20220115
  * ```
+ *
+ * @param date - a Date to encode (first overload)
+ * @param dateOrYear - a Date to encode, or a year number when used with month and day
+ * @param month - the month (1-12), required when dateOrYear is a number
+ * @param day - the day of month (1-31), required when dateOrYear is a number
+ * @returns the encoded YYYYMMDD integer
  */
 export declare function yearMonthDayCode(date: Date): YearMonthDayCode;
 export declare function yearMonthDayCode(year: number, month: MonthOfYear, day: DayOfMonth): YearMonthDayCode;
@@ -135,6 +149,7 @@ export declare function yearMonthDayCode(year: number, month: MonthOfYear, day:
  * ```
  *
  * @param config - Optional timezone configuration; defaults to system timezone
+ * @returns a reusable factory function that converts dates to YearMonthDayCode values
  */
 export declare function yearMonthDayCodeFactory(config?: YearMonthDayCodeConfig): YearMonthDayCodeFactory;
 /**
@@ -158,6 +173,7 @@ export type YearMonthDayCodesForDateRangeFactory = (dateOrDateRange: DateOrDateR
  * ```
  *
  * @param dateOrDateRange - A single Date (expanded to its calendar month) or an explicit date range
+ * @returns an array of YearMonthDayCode values, one per day in the range
  */
 export declare function yearMonthDayCodesForDateRange(dateOrDateRange: DateOrDateRange): YearMonthDayCode[];
 /**
@@ -166,6 +182,7 @@ export declare function yearMonthDayCodesForDateRange(dateOrDateRange: DateOrDat
  * Shares timezone normalization with the provided factory for consistent day boundaries.
  *
  * @param factory - YearMonthDayCodeFactory to use for encoding; defaults to system timezone
+ * @returns a factory that produces arrays of YearMonthDayCode values for date ranges
  */
 export declare function yearMonthDayCodesForDateRangeFactory(factory?: YearMonthDayCodeFactory): YearMonthDayCodesForDateRangeFactory;
 /**
@@ -191,6 +208,7 @@ export type YearMonthDayCodeDateConfig = Pick<YearMonthDayCodeConfig, 'timezone'
  * ```
  *
  * @param config - Optional timezone configuration; defaults to system timezone
+ * @returns a factory that decodes YearMonthDayCode values back into Dates
  */
 export declare function yearMonthDayCodeDateFactory(config?: YearMonthDayCodeDateConfig): YearMonthDayCodeDateFactory;
 /**
@@ -221,11 +239,11 @@ export interface YearMonthDayCodeGroupFactoryConfig<B> {
      * Factory or config used to convert dates to day codes. Accepts either a pre-built
      * {@link YearMonthDayCodeFactory} or raw {@link YearMonthDayCodeConfig} to create one.
      */
-    yearMonthDayCodeFactory?: YearMonthDayCodeFactory | YearMonthDayCodeConfig;
+    readonly yearMonthDayCodeFactory?: YearMonthDayCodeFactory | YearMonthDayCodeConfig;
     /**
      * Function that extracts the relevant Date from each item for day-code grouping.
      */
-    dateReader: YearMonthDayCodeDateReader<B>;
+    readonly dateReader: YearMonthDayCodeDateReader<B>;
 }
 /**
  * Creates a {@link YearMonthDayCodeGroupFactory} that partitions items into day-based groups.
@@ -246,5 +264,6 @@ export interface YearMonthDayCodeGroupFactoryConfig<B> {
  * ```
  *
  * @param config - Grouping configuration including the date reader and optional timezone
+ * @returns a factory that partitions items into day-based groups
  */
 export declare function yearMonthDayCodeGroupFactory<B>(config: YearMonthDayCodeGroupFactoryConfig<B>): YearMonthDayCodeGroupFactory<B>;

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

@@ -22,21 +22,21 @@ export interface FormatDateRangeFunctionConfig {
     /**
      * Function used to format each individual date in the range.
      */
-    format: FormatDateFunction;
+    readonly format: FormatDateFunction;
     /**
      * Whether to normalize dates to UTC before formatting.
      */
-    normalizeToUTC?: boolean;
+    readonly normalizeToUTC?: boolean;
     /**
      * Separator string placed between the formatted start and end dates. Defaults to `'-'`.
      */
-    separator?: string;
+    readonly separator?: string;
     /**
      * Whether to output a single formatted date when both dates fall on the same day.
      *
      * False by default.
      */
-    simplifySameDate?: boolean;
+    readonly simplifySameDate?: boolean;
 }
 export type FormatDateRangeFunctionConfigInput = FormatDateFunction | FormatDateRangeFunctionConfig;
 /**
@@ -45,6 +45,7 @@ export type FormatDateRangeFunctionConfigInput = FormatDateFunction | FormatDate
  * Useful when the same range formatting logic needs to be applied repeatedly with consistent settings.
  *
  * @param inputConfig - format function or full configuration
+ * @returns a reusable function that formats date ranges into strings
  *
  * @example
  * ```ts
@@ -67,6 +68,7 @@ export declare function formatDateRangeFunction(inputConfig: FormatDateRangeFunc
  * @param range - date range to format
  * @param inputConfig - format function or full configuration
  * @param separator - optional separator override when inputConfig is a function
+ * @returns the formatted date range string
  *
  * @example
  * ```ts
@@ -113,6 +115,7 @@ export type FormatDateRangeDistanceFunctionConfig = {
  * (e.g., "3 hours", "about 2 days"). Delegates to date-fns `formatDistance` or `formatDistanceStrict`.
  *
  * @param inputConfig - controls distance formatting, optional transforms, and same-day handling
+ * @returns a reusable function that computes and formats date range distances
  *
  * @example
  * ```ts
@@ -137,6 +140,7 @@ export declare const formatDateDistance: FormatDateRangeFunction;
  *
  * @param range - date range to compute distance for
  * @param inputConfig - optional distance formatting configuration
+ * @returns the human-readable distance string
  *
  * @example
  * ```ts
@@ -169,6 +173,11 @@ export declare function formatDateRangeDistance(range: DateRange, inputConfig?:
  * formatToTimeRangeString({ start: new Date('2024-01-15T09:00:00'), end: new Date('2024-01-16T17:00:00') });
  * // "01/15/2024 9:00 AM - 01/16/2024 5:00 PM"
  * ```
+ *
+ * @param startOrDateRange - date range object or start date
+ * @param end - optional end date when a start date is provided
+ * @param onlyTimeRange - whether to force time-only formatting regardless of date span
+ * @returns the formatted time or date+time range string
  */
 export declare function formatToTimeRangeString(startOrDateRange: DateRange): string;
 export declare function formatToTimeRangeString(start: Date, end?: Maybe<Date>): string;
@@ -186,6 +195,10 @@ export declare function formatToTimeRangeString(startOrDateRange: DateRange | Da
  * formatToDayTimeRangeString({ start: new Date('2024-01-15T09:00:00'), end: new Date('2024-01-16T17:00:00') });
  * // "01/15/2024 9:00 AM - 01/16/2024 5:00 PM"
  * ```
+ *
+ * @param startOrDateRange - date range object or start date
+ * @param end - optional end date when a start date is provided
+ * @returns the formatted date+time range string
  */
 export declare function formatToDayTimeRangeString(startOrDateRange: DateRange): string;
 export declare function formatToDayTimeRangeString(start: Date, end?: Maybe<Date>): string;
@@ -205,6 +218,12 @@ export declare function formatToDayTimeRangeString(start: Date, end?: Maybe<Date
  * formatToDayRangeString({ start: new Date('2024-01-15'), end: new Date('2024-01-15') });
  * // "01/15/2024"
  * ```
+ *
+ * @param startOrDateRange - date range object or start date
+ * @param format - optional custom format function (when called with a DateRange)
+ * @param endOrFormat - optional end date or custom format function
+ * @param inputFormat - optional custom format function when end date is provided separately
+ * @returns the formatted day range string
  */
 export declare function formatToDayRangeString(startOrDateRange: DateRange, format?: FormatDateFunction): string;
 export declare function formatToDayRangeString(start: Date, end?: Maybe<Date>, format?: FormatDateFunction): string;
@@ -213,6 +232,7 @@ export declare function formatToDayRangeString(start: Date, end?: Maybe<Date>, f
  * instead of throwing.
  *
  * @param input - date, date string, or nullish value
+ * @returns the ISO 8601 date string, or `undefined` if the input is invalid or nullish
  *
  * @example
  * ```ts
@@ -233,6 +253,7 @@ export declare function safeFormatToISO8601DateString(input: Maybe<DateOrDateStr
  * Formats a Date to a full ISO 8601 date-time string via `Date.toISOString()`. Defaults to the current date/time.
  *
  * @param date - date to format; defaults to `new Date()`
+ * @returns the full ISO 8601 date-time string
  *
  * @example
  * ```ts
@@ -250,6 +271,7 @@ export declare function formatToISO8601DateString(date?: Date): ISO8601DayString
  * Use {@link toISO8601DayStringForUTC} when the UTC date is needed instead.
  *
  * @param dateOrString - date or existing day string
+ * @returns the ISO 8601 day string in system timezone
  *
  * @example
  * ```ts
@@ -268,6 +290,7 @@ export declare function toISO8601DayStringForSystem(dateOrString: DateOrDayStrin
  * Defaults to the current date.
  *
  * @param date - date to format; defaults to `new Date()`
+ * @returns the ISO 8601 day string in system timezone
  *
  * @example
  * ```ts
@@ -285,6 +308,7 @@ export declare function formatToISO8601DayStringForSystem(date?: Date): ISO8601D
  * Use {@link toISO8601DayStringForSystem} when the system-local date is needed instead.
  *
  * @param dateOrString - date or existing day string
+ * @returns the ISO 8601 day string in UTC
  *
  * @example
  * ```ts
@@ -304,6 +328,7 @@ export declare function toISO8601DayStringForUTC(dateOrString: DateOrDayString):
  * Defaults to the current date.
  *
  * @param date - date to format; defaults to `new Date()`
+ * @returns the ISO 8601 day string using UTC date components
  *
  * @example
  * ```ts
@@ -314,12 +339,19 @@ export declare function toISO8601DayStringForUTC(dateOrString: DateOrDayString):
  * ```
  */
 export declare function formatToISO8601DayStringForUTC(date?: Date): ISO8601DayString;
-/** date-fns format string for `MM/dd/yyyy` (e.g., `"01/15/2024"`). */
+/**
+ * date-fns format string for `MM/dd/yyyy` (e.g., `"01/15/2024"`).
+ */
+export declare const MONTH_DAY_SLASH_DATE_STRING_FORMAT = "MM/dd/yyyy";
+/**
+ * @deprecated Use MONTH_DAY_SLASH_DATE_STRING_FORMAT instead.
+ */
 export declare const monthDaySlashDateStringFormat = "MM/dd/yyyy";
 /**
  * Formats a Date as a month/day/year slash-separated string (`MM/dd/yyyy`). Defaults to the current date.
  *
  * @param date - date to format; defaults to `new Date()`
+ * @returns the formatted `MM/dd/yyyy` string
  *
  * @example
  * ```ts
@@ -334,12 +366,19 @@ export declare function formatToMonthDaySlashDate(date?: Date): MonthDaySlashDat
  * @deprecated use formatToMonthDaySlashDate instead.
  */
 export declare const formatToShortDateString: typeof formatToMonthDaySlashDate;
-/** date-fns format string for `MM/dd` (e.g., `"01/15"`). */
+/**
+ * date-fns format string for `MM/dd` (e.g., `"01/15"`).
+ */
+export declare const DATE_MONTH_DAY_STRING_FORMAT = "MM/dd";
+/**
+ * @deprecated Use DATE_MONTH_DAY_STRING_FORMAT instead.
+ */
 export declare const dateMonthDayStringFormat = "MM/dd";
 /**
  * Formats a Date as a month/day string (`MM/dd`) without the year. Defaults to the current date.
  *
  * @param date - date to format; defaults to `new Date()`
+ * @returns the formatted `MM/dd` string
  *
  * @example
  * ```ts
@@ -354,6 +393,7 @@ export declare function formatToMonthDayString(date?: Date): ISO8601DayString;
  * Formats a Date as a human-friendly weekday and month/day string (e.g., `"Mon, Jan 15th"`).
  *
  * @param date - date to format
+ * @returns the formatted weekday and month/day string
  *
  * @example
  * ```ts
@@ -364,12 +404,19 @@ export declare function formatToMonthDayString(date?: Date): ISO8601DayString;
  * ```
  */
 export declare function formatToDateString(date: Date): string;
-/** date-fns format string for 12-hour time with AM/PM (e.g., `"9:00 AM"`). */
+/**
+ * date-fns format string for 12-hour time with AM/PM (e.g., `"9:00 AM"`).
+ */
+export declare const DATE_TIME_STRING_FORMAT = "h:mm a";
+/**
+ * @deprecated Use DATE_TIME_STRING_FORMAT instead.
+ */
 export declare const dateTimeStringFormat = "h:mm a";
 /**
  * Formats a Date as a 12-hour time string with AM/PM (e.g., `"9:00 AM"`).
  *
  * @param date - date to format
+ * @returns the formatted 12-hour time string with AM/PM
  *
  * @example
  * ```ts
@@ -380,12 +427,19 @@ export declare const dateTimeStringFormat = "h:mm a";
  * ```
  */
 export declare function formatToTimeString(date: Date): string;
-/** Combined date-fns format string for `MM/dd/yyyy h:mm a` (e.g., `"01/15/2024 9:00 AM"`). */
+/**
+ * Combined date-fns format string for `MM/dd/yyyy h:mm a` (e.g., `"01/15/2024 9:00 AM"`).
+ */
+export declare const DATE_SHORT_DATE_AND_TIME_STRING_FORMAT = "MM/dd/yyyy h:mm a";
+/**
+ * @deprecated Use DATE_SHORT_DATE_AND_TIME_STRING_FORMAT instead.
+ */
 export declare const dateShortDateAndTimeStringFormat = "MM/dd/yyyy h:mm a";
 /**
  * Formats a Date as a short date and time string (e.g., `"01/15/2024 9:00 AM"`).
  *
  * @param date - date to format
+ * @returns the formatted short date and time string
  *
  * @example
  * ```ts
@@ -402,6 +456,7 @@ export declare function formatToShortDateAndTimeString(date: Date): string;
  *
  * @param start - start date/time
  * @param end - end date/time
+ * @returns the formatted time string with an appended duration indicator
  *
  * @example
  * ```ts
@@ -436,6 +491,11 @@ export declare function formatToTimeAndDurationString(start: Date, end: Date): s
  * formatStartedEndedDistanceString(activeRange);
  * // "started about 1 hour ago"
  * ```
+ *
+ * @param dateRange - date range with start and end dates
+ * @param dateRange.start - the start date of the range
+ * @param dateRange.end - the end date of the range
+ * @returns the relative-time label describing the date range state
  */
 export declare function formatStartedEndedDistanceString({ start, end }: DateRange): string;
 /**
@@ -443,6 +503,7 @@ export declare function formatStartedEndedDistanceString({ start, end }: DateRan
  * Useful for converting heterogeneous date inputs into a consistent midnight-aligned Date.
  *
  * @param input - date or day string to normalize
+ * @returns a Date set to midnight of the corresponding day in the system timezone
  *
  * @example
  * ```ts
@@ -461,6 +522,7 @@ export declare function toJsDayDate(input: DateOrDayString): Date;
  * in the system timezone. Supports year formats with more than 4 digits but does not support negative years.
  *
  * @param dayString - ISO 8601 day or date string to parse
+ * @returns a Date at the start of the parsed day in the system timezone
  *
  * @example
  * ```ts