@dereekb/date 13.0.7 → 13.2.0

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

@@ -2,18 +2,24 @@ import { type DayOfMonth, type MapFunction, type Maybe, type MonthOfYear, type Y
 import { type DateOrDateRange } from './date.range';
 import { DateTimezoneUtcNormalInstance, type DateTimezoneUtcNormalInstanceInput } from './date.timezone';
 /**
- * A Day/Month/Year number combination used to refer to a specific Day on a specific Year.
+ * Encodes a calendar date as a single YYYYMMDD integer for efficient date-day comparisons and grouping.
  *
- * 20220101 is January 1st 2022
+ * The encoding uses `year * 10000 + month * 100 + day`, so January 1st 2022 becomes `20220101`.
+ * This allows simple numeric comparisons to determine chronological order between dates.
  */
 export type YearMonthDayCode = number;
 /**
- * Used for default YearMonthDay values
+ * Sentinel value representing an unset or unknown date. Used as a default/fallback
+ * when a valid YearMonthDayCode is not available.
  */
 export declare const UNKNOWN_YEAR_MONTH_DAY_CODE = 0;
+/**
+ * Type representing the sentinel unknown/unset YearMonthDayCode value (0).
+ */
 export type UnknownYearMonthDayCode = typeof UNKNOWN_YEAR_MONTH_DAY_CODE;
 /**
- * YearMonthDay values in an object.
+ * Decomposed representation of a {@link YearMonthDayCode} as individual year, month, and day fields.
+ * Useful when the individual date components need to be accessed or manipulated independently.
  */
 export interface YearMonthDayCodePair {
     day: number;
@@ -21,61 +27,67 @@ export interface YearMonthDayCodePair {
     year: number;
 }
 /**
- * Returns the YearNumber for the YearMonthDayCode.
+ * Extracts the year component from a {@link YearMonthDayCode} by dividing out the month and day digits.
  *
- * @param yearMonthDayCode
- * @returns
+ * @param yearMonthDayCode - Encoded YYYYMMDD value to extract the year from
  */
 export declare function yearMonthDayCodeYear(yearMonthDayCode: YearMonthDayCode): YearNumber;
 /**
- * Returns the MonthOfYear for the YearMonthDayCode.
+ * Extracts the month component (1-12) from a {@link YearMonthDayCode} by isolating the middle two digits.
  *
- * @param yearMonthDayCode
- * @returns
+ * @param yearMonthDayCode - Encoded YYYYMMDD value to extract the month from
  */
 export declare function yearMonthDayCodeMonth(yearMonthDayCode: YearMonthDayCode): MonthOfYear;
 /**
- * Returns the DayOfMonth for the YearMonthDayCode.
+ * Extracts the day-of-month component (1-31) from a {@link YearMonthDayCode} by isolating the last two digits.
  *
- * @param yearMonthDayCode
- * @returns
+ * @param yearMonthDayCode - Encoded YYYYMMDD value to extract the day from
  */
 export declare function yearMonthDayCodeDay(yearMonthDayCode: YearMonthDayCode): DayOfMonth;
 /**
- * Returns the YearMonthDayCodePair for the YearMonthDayCode.
+ * Decomposes a {@link YearMonthDayCode} into its individual year, month, and day components.
  *
- * @param yearMonthDayCode
- * @returns
+ * @param yearMonthDayCode - Encoded YYYYMMDD value to decompose
  */
 export declare function yearMonthDayCodePair(yearMonthDayCode: YearMonthDayCode): YearMonthDayCodePair;
 /**
- * Creates a YearMonthDayCodePair using the input date and the current timezone.
+ * Creates a {@link YearMonthDayCodePair} by reading year, month, and day directly from the Date
+ * using the system's local timezone. No timezone normalization is applied here; callers
+ * that need timezone-aware conversion should use {@link yearMonthDayCodeFactory} instead.
  *
- * @param date
- * @returns
+ * @param date - Date to extract components from using local timezone
  */
 export declare function yearMonthDayCodePairFromDate(date: Date): YearMonthDayCodePair;
 /**
- * Creates a YearMonthDayCode from the input pair.
+ * Encodes a {@link YearMonthDayCodePair} into a single {@link YearMonthDayCode} integer
+ * using the formula `year * 10000 + month * 100 + day`.
  *
- * @param pair
- * @returns
+ * @param pair - Decomposed date components to encode
  */
 export declare function yearMonthDayCodeFromPair(pair: YearMonthDayCodePair): YearMonthDayCode;
 /**
- * Creates a YearMonthDayCode from the input Date.
+ * Convenience function that converts a Date directly to a {@link YearMonthDayCode}
+ * using the system's local timezone. For timezone-aware conversion, use {@link yearMonthDayCodeFactory}.
  *
- * @param date
- * @returns
+ * @param date - Date to encode using local timezone
  */
 export declare function yearMonthDayCodeFromDate(date: Date): YearMonthDayCode;
 /**
- * Used to convert the input to a YearMonthDayCode.
+ * Timezone-aware function that converts either a Date or explicit year/month/day components
+ * into a {@link YearMonthDayCode}. Exposes its internal {@link DateTimezoneUtcNormalInstance}
+ * via `_normal` so related utilities can share the same timezone configuration.
  */
 export type YearMonthDayCodeFactory = ((dateOrYear: Date | number, month?: MonthOfYear, day?: DayOfMonth) => YearMonthDayCode) & {
     _normal: DateTimezoneUtcNormalInstance;
 };
+/**
+ * Accepted timezone input for YearMonthDayCode utilities. Can be either raw configuration
+ * for creating a {@link DateTimezoneUtcNormalInstance} or an existing instance to reuse.
+ */
 export type YearMonthDayCodeDateTimezoneInput = DateTimezoneUtcNormalInstanceInput | DateTimezoneUtcNormalInstance;
+/**
+ * Configuration for creating timezone-aware YearMonthDayCode utilities.
+ */
 export interface YearMonthDayCodeConfig {
     /**
      * (Optional) Input timezone configuration for a DateTimezoneUtcNormalInstance.
@@ -84,77 +96,155 @@ export interface YearMonthDayCodeConfig {
      */
     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
+ */
 export declare function yearMonthDayCodeDateTimezoneInstance(input: YearMonthDayCodeDateTimezoneInput): DateTimezoneUtcNormalInstance;
 /**
- * Returns the yearMonthDayCode for the input Date or Year/Month/Day combo.
+ * Converts a Date or explicit year/month/day components into a {@link YearMonthDayCode}
+ * using the system timezone. This is the simplest entry point for one-off conversions;
+ * for repeated conversions or custom timezones, prefer {@link yearMonthDayCodeFactory}.
  *
- * The date is expected to be relative to UTC.
+ * @example
+ * ```ts
+ * // From a Date
+ * const code = yearMonthDayCode(new Date(2022, 0, 1)); // 20220101
  *
- * @param date
+ * // From explicit components (year, month 1-12, day)
+ * const code2 = yearMonthDayCode(2022, 1, 15); // 20220115
+ * ```
  */
 export declare function yearMonthDayCode(date: Date): YearMonthDayCode;
 export declare function yearMonthDayCode(year: number, month: MonthOfYear, day: DayOfMonth): YearMonthDayCode;
 /**
- * Creates a YearMonthDayCodeFactory using the optional input config.
+ * Creates a reusable, timezone-aware {@link YearMonthDayCodeFactory}. The factory normalizes
+ * dates to the configured timezone before encoding, ensuring consistent day boundaries
+ * regardless of the system's local timezone.
  *
- * @param config
- * @returns
+ * @example
+ * ```ts
+ * // Factory for America/Denver timezone
+ * const toCode = yearMonthDayCodeFactory({ timezone: { timezone: 'America/Denver' } });
+ * const code = toCode(new Date('2022-01-02T01:00:00Z')); // 20220101 (still Jan 1 in Denver)
+ *
+ * // From explicit components (no timezone normalization needed)
+ * const code2 = toCode(2022, 6, 15); // 20220615
+ * ```
+ *
+ * @param config - Optional timezone configuration; defaults to system timezone
  */
 export declare function yearMonthDayCodeFactory(config?: YearMonthDayCodeConfig): YearMonthDayCodeFactory;
 /**
- * Used for returning an array of YearMonthDayCode values for a pre-configured date range.
+ * Pre-configured function that produces an array of {@link YearMonthDayCode} values
+ * for every day within a given date range, using consistent timezone normalization.
  */
 export type YearMonthDayCodesForDateRangeFactory = (dateOrDateRange: DateOrDateRange) => YearMonthDayCode[];
 /**
- * Returns the yearMonthDayCodes for the input Date's calendar month.
+ * Returns a {@link YearMonthDayCode} for every day in the given date range using the system timezone.
+ * For a single Date input, the range covers that date's full calendar month.
+ * For repeated use or custom timezones, prefer {@link yearMonthDayCodesForDateRangeFactory}.
  *
- * The date is expected to be relative to UTC.
+ * @example
+ * ```ts
+ * // Get codes for a 3-day range
+ * const codes = yearMonthDayCodesForDateRange({
+ *   start: new Date(2022, 0, 1),
+ *   end: new Date(2022, 0, 3)
+ * });
+ * // [20220101, 20220102, 20220103]
+ * ```
  *
- * @param date
+ * @param dateOrDateRange - A single Date (expanded to its calendar month) or an explicit date range
  */
 export declare function yearMonthDayCodesForDateRange(dateOrDateRange: DateOrDateRange): YearMonthDayCode[];
 /**
- * Create a YearMonthDayCodesForDateRangeFactory.
+ * Creates a reusable {@link YearMonthDayCodesForDateRangeFactory} that enumerates every day
+ * in a date range and returns the corresponding {@link YearMonthDayCode} values.
+ * Shares timezone normalization with the provided factory for consistent day boundaries.
  *
- * @param factory
- * @returns
+ * @param factory - YearMonthDayCodeFactory to use for encoding; defaults to system timezone
  */
 export declare function yearMonthDayCodesForDateRangeFactory(factory?: YearMonthDayCodeFactory): YearMonthDayCodesForDateRangeFactory;
 /**
- * Used to convert the input to a YearMonthDayCode.
+ * Converts a {@link YearMonthDayCode} back into a Date, applying timezone normalization
+ * to produce a Date representing midnight of that day in the configured timezone.
  */
 export type YearMonthDayCodeDateFactory = (yearMonthDayCode: YearMonthDayCode) => Date;
+/**
+ * Configuration for {@link yearMonthDayCodeDateFactory}, controlling which timezone
+ * the resulting Date objects are normalized to.
+ */
 export type YearMonthDayCodeDateConfig = Pick<YearMonthDayCodeConfig, 'timezone'>;
 /**
- * Creates a YearMonthDayCodeDateFactory using the optional input config.
+ * Creates a {@link YearMonthDayCodeDateFactory} that decodes a {@link YearMonthDayCode} back
+ * into a Date at midnight in the configured timezone. This is the inverse of
+ * {@link yearMonthDayCodeFactory}: `yearMonthDayCodeDateFactory(cfg)(yearMonthDayCodeFactory(cfg)(date))`
+ * returns a Date representing midnight of the original date's day.
+ *
+ * @example
+ * ```ts
+ * const toDate = yearMonthDayCodeDateFactory({ timezone: { timezone: 'America/Denver' } });
+ * const date = toDate(20220115); // Date representing Jan 15, 2022 midnight in Denver
+ * ```
  *
- * @param config
- * @returns
+ * @param config - Optional timezone configuration; defaults to system timezone
  */
 export declare function yearMonthDayCodeDateFactory(config?: YearMonthDayCodeDateConfig): YearMonthDayCodeDateFactory;
 /**
- *
+ * A group of items that share the same {@link YearMonthDayCode}, produced by
+ * {@link yearMonthDayCodeGroupFactory}. Useful for rendering day-based groupings
+ * such as activity feeds or calendar views.
  */
 export interface YearMonthDayCodeGroup<B> {
     readonly items: B[];
     readonly dayCode: YearMonthDayCode;
 }
 /**
- * Used to group the input items into an array of YearMonthDayCodeGroup values.
+ * Groups an array of items by their associated day, returning an array of
+ * {@link YearMonthDayCodeGroup} entries. Items whose date is null/undefined
+ * are grouped under {@link UNKNOWN_YEAR_MONTH_DAY_CODE}.
  */
 export type YearMonthDayCodeGroupFactory<B> = (items: B[]) => YearMonthDayCodeGroup<B>[];
 /**
- * MapFunction that reads the relevant date to use for the YearMonthDayCode calculation from the input item.
+ * Extracts the Date to use for {@link YearMonthDayCode} grouping from an item.
+ * Returning null/undefined causes the item to be placed in the unknown group.
  */
 export type YearMonthDayCodeDateReader<B> = MapFunction<B, Maybe<Date>>;
+/**
+ * Configuration for {@link yearMonthDayCodeGroupFactory}.
+ */
 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;
+    /**
+     * Function that extracts the relevant Date from each item for day-code grouping.
+     */
     dateReader: YearMonthDayCodeDateReader<B>;
 }
 /**
- * Creates a YearMonthDayCodeGroupFactory.
+ * Creates a {@link YearMonthDayCodeGroupFactory} that partitions items into day-based groups.
+ * Each item's date is read via the configured `dateReader`, converted to a {@link YearMonthDayCode},
+ * and used as the grouping key. Items with no date fall into the `0` (unknown) group.
+ *
+ * @example
+ * ```ts
+ * interface Event { name: string; date: Date }
+ *
+ * const groupByDay = yearMonthDayCodeGroupFactory<Event>({
+ *   dateReader: (event) => event.date,
+ *   yearMonthDayCodeFactory: { timezone: { timezone: 'America/Denver' } }
+ * });
+ *
+ * const groups = groupByDay(events);
+ * // [{ dayCode: 20220115, items: [...] }, { dayCode: 20220116, items: [...] }]
+ * ```
  *
- * @param config
- * @returns
+ * @param config - Grouping configuration including the date reader and optional timezone
  */
 export declare function yearMonthDayCodeGroupFactory<B>(config: YearMonthDayCodeGroupFactoryConfig<B>): YearMonthDayCodeGroupFactory<B>;

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

@@ -1,31 +1,69 @@
 import { type DateRelativeState, type FractionalHour, type Minutes, type Maybe } from '@dereekb/util';
 import { type DateRange } from './date.range';
+/**
+ * Represents a time span with a start date and a duration in minutes.
+ *
+ * Used throughout the date cell system to define when events begin and how long they last.
+ */
 export interface DateDurationSpan {
     startsAt: Date;
     duration: Minutes;
 }
-export declare class DateDurationSpan {
+/**
+ * ArkType schema for {@link DateDurationSpan}.
+ */
+export declare const dateDurationSpanType: import("arktype/internal/variants/object.ts").ObjectType<{
     startsAt: Date;
-    duration: Minutes;
-    constructor(template?: DateDurationSpan);
-}
+    duration: number;
+}, {}>;
 /**
- * Returns the Date for the end time for the input DateDurationSpan.
+ * Computes the end date for a duration span by adding the duration to the start time.
+ *
+ * @param span - the duration span to compute the end for
+ * @returns the date when the span ends
  *
- * @param span
- * @returns
+ * @example
+ * ```ts
+ * const span = { startsAt: new Date('2024-01-01T10:00:00Z'), duration: 60 };
+ * dateDurationSpanEndDate(span); // 2024-01-01T11:00:00Z
+ * ```
  */
 export declare function dateDurationSpanEndDate(span: DateDurationSpan): Date;
+/**
+ * Converts a {@link DateDurationSpan} to a {@link DateRange} with start and end dates.
+ *
+ * @param span - the duration span to convert
+ * @returns a date range from startsAt to startsAt + duration
+ */
 export declare function durationSpanToDateRange(span: DateDurationSpan): DateRange;
+/**
+ * Creates a {@link DateDurationSpan} from a {@link DateRange} by computing the duration in minutes between start and end.
+ *
+ * @param dateRange - the date range to convert
+ * @returns a duration span with the range's start as startsAt
+ */
 export declare function durationSpanFromDateRange(dateRange: DateRange): DateDurationSpan;
+/**
+ * Determines whether a duration span is in the past, present, or future relative to the given time.
+ *
+ * @param span - the duration span to check
+ * @param now - reference time (defaults to current time)
+ * @returns 'past', 'present', or 'future'
+ */
 export declare function durationSpanDateRelativeState(span: DateDurationSpan, now?: Date): DateRelativeState;
+/**
+ * Converts a duration span's duration from minutes to fractional hours.
+ *
+ * @param span - the duration span to measure
+ * @returns the duration expressed as fractional hours (e.g. 90 minutes = 1.5)
+ */
 export declare function fractionalHoursInDurationSpan(span: DateDurationSpan): FractionalHour;
 /**
- * EqualityComparatorFunction for two input DateDurationSpan values.
+ * Null-safe equality check for two {@link DateDurationSpan} values, comparing both startsAt and duration.
  *
- * @param a
- * @param b
- * @returns
+ * @param a - first span
+ * @param b - second span
+ * @returns whether the spans are equal (or both nullish)
  */
 export declare function isSameDurationSpan(a: DateDurationSpan, b: DateDurationSpan): boolean;
 export declare function isSameDurationSpan(a: Maybe<DateDurationSpan>, b: Maybe<DateDurationSpan>): boolean;