@dereekb/date 13.2.0 → 13.2.2

package/index.esm.js

@@ -1,9 +1,10 @@
-import { MS_IN_HOUR, MS_IN_MINUTE, MINUTES_IN_DAY, isISO8601DateString, filterMaybeArrayValues, asArray, dayOfWeek, sortNumbersAscendingFunction, MS_IN_SECOND, SORT_VALUE_LESS_THAN, SORT_VALUE_GREATER_THAN, SORT_VALUE_EQUAL, copyArray, compareFnOrder, MS_IN_DAY, daysOfWeekArray, groupValues, minutesToFractionalHours, safeCompareEquality, DATE_NOW_VALUE, mapIdentityFunction, UTC_TIMEZONE_STRING, cachedGetter, parseISO8601DayStringToUTCDate, isConsideredUtcTimezoneString, isSameNonNullValue, replaceStringsFunction, repeatString, isEqualDate, startOfDayForUTCDateInUTC, range, pushArrayItemsIntoArray, sumOfIntegersBetween, makeValuesGroupMap, lastValue, sortAscendingIndexNumberRefFunction, indexRangeCheckFunction, asGetter, mergeFilterFunctions, isDate as isDate$2, HOURS_IN_DAY, getNextDay, iterablesAreSetEquivalent, daysOfWeekFromEnabledDays, forEachInIterable, enabledDaysFromDaysOfWeek, addToSet, invertFilter, firstValueFromIterable, HashSet, roundNumberUpToStep, protectedFactory, TimeAM, isLogicalDateStringCode as isLogicalDateStringCode$1, dateFromLogicalDate as dateFromLogicalDate$1, flattenArray, splitJoinRemainder } from '@dereekb/util';
+import { MS_IN_HOUR, MS_IN_MINUTE, MINUTES_IN_DAY, isISO8601DateString, filterMaybeArrayValues, asArray, dayOfWeek, sortNumbersAscendingFunction, MS_IN_SECOND, SORT_VALUE_LESS_THAN, SORT_VALUE_GREATER_THAN, SORT_VALUE_EQUAL, copyArray, compareFnOrder, MS_IN_DAY, daysOfWeekArray, groupValues, DATE_NOW_VALUE, mapIdentityFunction, UTC_TIMEZONE_STRING, cachedGetter, parseISO8601DayStringToUTCDate, isConsideredUtcTimezoneString, isSameNonNullValue, repeatString, isEqualDate, startOfDayForUTCDateInUTC, minutesToFractionalHours, range, pushArrayItemsIntoArray, sumOfIntegersBetween, makeValuesGroupMap, lastValue, sortAscendingIndexNumberRefFunction, indexRangeCheckFunction, asGetter, mergeFilterFunctions, isDate as isDate$2, HOURS_IN_DAY, safeCompareEquality, getNextDay, iterablesAreSetEquivalent, daysOfWeekFromEnabledDays, forEachInIterable, enabledDaysFromDaysOfWeek, addToSet, invertFilter, firstValueFromIterable, replaceStringsFunction, HashSet, roundNumberUpToStep, protectedFactory, TimeAM, isLogicalDateStringCode as isLogicalDateStringCode$1, dateFromLogicalDate as dateFromLogicalDate$1, flattenArray, splitJoinRemainder } from '@dereekb/util';
 export { dateFromDateOrTimeMillisecondsNumber, unixDateTimeSecondsNumberForNow, unixDateTimeSecondsNumberFromDate, unixDateTimeSecondsNumberFromDateOrTimeNumber, unixDateTimeSecondsNumberToDate } from '@dereekb/util';
-import { isEqual, isSameDay, isDate as isDate$1, startOfMinute, isValid, parseISO, min, max, isAfter as isAfter$1, isBefore as isBefore$1, set, addMilliseconds, startOfMonth, endOfWeek, startOfWeek, endOfMonth, addDays, addHours, addMinutes, differenceInDays, startOfDay, addMonths, addWeeks, endOfDay, endOfHour, startOfHour, endOfMinute, differenceInMinutes, differenceInHours, millisecondsToHours, millisecondsToMinutes, formatDistanceStrict, formatDistance, formatDistanceToNow, format as format$1, parse, differenceInMilliseconds, getMinutes, getSeconds, getMilliseconds, setWeek, getWeek, getYear, getDay, isPast, addSeconds } from 'date-fns';
-import { type } from 'arktype';
+import { isEqual, isSameDay, isDate as isDate$1, startOfMinute, isValid, parseISO, min, max, isAfter as isAfter$1, isBefore as isBefore$1, set, addMilliseconds, startOfMonth, endOfWeek, startOfWeek, endOfMonth, addDays, addHours, addMinutes, differenceInDays, startOfDay, addMonths, addWeeks, endOfDay, endOfHour, startOfHour, endOfMinute, differenceInHours, millisecondsToHours, millisecondsToMinutes, formatDistanceStrict, formatDistance, formatDistanceToNow, format as format$1, differenceInMinutes, parse, differenceInMilliseconds, getMinutes, getSeconds, getMilliseconds, setWeek, getWeek, getYear, getDay, isPast, addSeconds } from 'date-fns';
 import { toZonedTime, format, formatInTimeZone } from 'date-fns-tz';
+import { type } from 'arktype';
 import { timeZonesNames } from '@vvo/tzdb';
+import { ARKTYPE_DATE_DTO_TYPE } from '@dereekb/model';
 import { interval, startWith, map, distinctUntilChanged } from 'rxjs';
 import { RRule } from 'rrule';
 
@@ -686,13 +687,6 @@ function isDateRangeStart(value) {
  * ```
  */
 const sortDateRangeStartAscendingCompareFunction = sortByDateFunction((x) => x.start);
-/**
- * ArkType schema for {@link DateRange}.
- */
-const dateRangeType = type({
-    start: 'Date',
-    end: 'Date'
-});
 /**
  * Counts the total number of calendar days spanned by the range, inclusive of both endpoints.
  * Always returns at least 1, even for same-day ranges.
@@ -868,14 +862,6 @@ var DateRangeType;
      */
     DateRangeType["CALENDAR_MONTH"] = "calendar_month";
 })(DateRangeType || (DateRangeType = {}));
-/**
- * ArkType schema for {@link DateRangeParams}.
- */
-const dateRangeParamsType = type({
-    type: type.enumerated(...Object.values(DateRangeType)),
-    date: 'Date',
-    'distance?': 'number'
-});
 /**
  * Creates a {@link DateRange} from the given type and optional parameters. Supports many range
  * strategies including fixed periods (day, week, month), directional ranges, and radii.
@@ -1472,75 +1458,6 @@ function getDaysOfWeekInDateRange(dateRange) {
     return days;
 }
 
-/**
- * ArkType schema for {@link DateDurationSpan}.
- */
-const dateDurationSpanType = type({
-    startsAt: 'Date',
-    duration: 'number >= 0'
-});
-/**
- * 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
- *
- * @example
- * ```ts
- * const span = { startsAt: new Date('2024-01-01T10:00:00Z'), duration: 60 };
- * dateDurationSpanEndDate(span); // 2024-01-01T11:00:00Z
- * ```
- */
-function dateDurationSpanEndDate(span) {
-    return addMinutes(span.startsAt, span.duration);
-}
-/**
- * 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
- */
-function durationSpanToDateRange(span) {
-    return {
-        start: span.startsAt,
-        end: addMinutes(span.startsAt, span.duration)
-    };
-}
-/**
- * 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
- */
-function durationSpanFromDateRange(dateRange) {
-    return {
-        startsAt: dateRange.start,
-        duration: differenceInMinutes(dateRange.end, dateRange.start)
-    };
-}
-/**
- * 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'
- */
-function durationSpanDateRelativeState(span, now) {
-    return dateRangeRelativeState(durationSpanToDateRange(span), now);
-}
-/**
- * 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)
- */
-function fractionalHoursInDurationSpan(span) {
-    return minutesToFractionalHours(span.duration);
-}
-function isSameDurationSpan(a, b) {
-    return safeCompareEquality(a, b, (a, b) => a.duration === b.duration && isSameDate(a.startsAt, b.startsAt));
-}
-
 /**
  * String code for the start of the current day.
  */
@@ -2452,158 +2369,6 @@ function copyHoursAndMinutesFromDateWithTimezoneNormal(input, copyFrom, timezone
     return result;
 }
 
-/**
- * Returns all recognized IANA timezone strings, including the explicit UTC entry.
- *
- * @example
- * ```ts
- * const zones = allTimezoneStrings();
- * // ['Africa/Abidjan', ..., 'UTC']
- * ```
- */
-function allTimezoneStrings() {
-    return timeZonesNames.concat(UTC_TIMEZONE_STRING);
-}
-/**
- * Lazily-computed set of all known timezone strings for O(1) membership checks.
- *
- * @example
- * ```ts
- * allKnownTimezoneStrings().has('America/New_York'); // true
- * ```
- */
-const allKnownTimezoneStrings = cachedGetter(() => {
-    return new Set(allTimezoneStrings());
-});
-/**
- * Lazily-computed array of {@link TimezoneInfo} for every known timezone.
- *
- * Abbreviations are resolved at the time of first access, so results reflect
- * the DST state at that moment.
- */
-const allTimezoneInfos = cachedGetter(() => {
-    const now = new Date();
-    return allTimezoneStrings().map((x) => timezoneStringToTimezoneInfo(x, now));
-});
-/**
- * Returns the {@link TimezoneInfo} for the current system timezone, falling back to UTC.
- *
- * @example
- * ```ts
- * const info = timezoneInfoForSystem();
- * console.log(info.abbreviation); // e.g., 'CST'
- * ```
- */
-function timezoneInfoForSystem() {
-    return timezoneStringToTimezoneInfo(guessCurrentTimezone() ?? UTC_TIMEZONE_STRING);
-}
-/**
- * Returns the short abbreviation (e.g., `"EST"`, `"PDT"`) for the given timezone at the specified date.
- *
- * The date matters because abbreviations change with DST transitions.
- * Returns `"UKNOWN"` if no timezone is provided.
- *
- * @example
- * ```ts
- * getTimezoneAbbreviation('America/New_York'); // 'EST' or 'EDT'
- * ```
- */
-function getTimezoneAbbreviation(timezone, date = new Date()) {
-    return timezone === UTC_TIMEZONE_STRING ? UTC_TIMEZONE_STRING : timezone ? formatInTimeZone(date, timezone, 'zzz') : 'UKNOWN';
-}
-/**
- * Returns the full display name (e.g., `"Eastern Standard Time"`) for the given timezone.
- *
- * Returns `"Unknown Timezone"` if no timezone is provided.
- *
- * @example
- * ```ts
- * getTimezoneLongName('America/New_York'); // 'Eastern Standard Time'
- * ```
- */
-function getTimezoneLongName(timezone, date = new Date()) {
-    return timezone ? formatInTimeZone(date, timezone, 'zzzz') : 'Unknown Timezone';
-}
-/**
- * Builds a {@link TimezoneInfo} for the given timezone, computing abbreviation and search variants.
- *
- * @example
- * ```ts
- * const info = timezoneStringToTimezoneInfo('America/Chicago');
- * // info.abbreviation => 'CST' or 'CDT'
- * // info.search => 'america chicago'
- * ```
- */
-function timezoneStringToTimezoneInfo(timezone, date = new Date()) {
-    const abbreviation = getTimezoneAbbreviation(timezone, date);
-    const result = {
-        timezone,
-        search: timezoneStringToSearchableString(timezone),
-        lowercase: timezone.toLowerCase(),
-        abbreviation,
-        lowercaseAbbreviation: abbreviation.toLowerCase()
-    };
-    return result;
-}
-/**
- * Filters timezone infos by a search string, matching against the searchable name,
- * lowercase identifier, and abbreviation.
- *
- * For queries longer than 2 characters, substring matching on the searchable name is also used.
- *
- * @example
- * ```ts
- * const results = searchTimezoneInfos('eastern', allTimezoneInfos());
- * ```
- */
-function searchTimezoneInfos(search, infos) {
-    const searchString = search.toLocaleLowerCase();
-    return infos.filter((x) => (search.length > 2 && x.search.includes(searchString)) || x.lowercase.startsWith(searchString) || x.lowercaseAbbreviation.startsWith(searchString) || x.abbreviation.includes(search) || x.search === x.timezone);
-}
-const timezoneStringToSearchableStringReplace = replaceStringsFunction({
-    replace: ['/', '_'],
-    replaceWith: ' '
-});
-/**
- * Converts a timezone identifier into a lowercase, space-separated string for search indexing.
- *
- * Replaces `/` and `_` with spaces (e.g., `"America/New_York"` becomes `"america new york"`).
- *
- * @example
- * ```ts
- * timezoneStringToSearchableString('America/New_York'); // 'america new york'
- * ```
- */
-function timezoneStringToSearchableString(timezone) {
-    return timezoneStringToSearchableStringReplace(timezone.toLocaleLowerCase());
-}
-/**
- * Checks whether the input string is a recognized IANA timezone identifier.
- *
- * Uses the cached set from {@link allKnownTimezoneStrings} for O(1) lookup.
- *
- * @example
- * ```ts
- * isKnownTimezone('America/New_York'); // true
- * isKnownTimezone('Mars/Olympus');     // false
- * ```
- */
-function isKnownTimezone(input) {
-    return allKnownTimezoneStrings().has(input);
-}
-
-/**
- * ArkType schema that validates a string is a recognized IANA timezone.
- *
- * Delegates to {@link isKnownTimezone} for the actual check.
- *
- * @example
- * ```ts
- * const result = knownTimezoneType('America/Denver');
- * ```
- */
-const knownTimezoneType = type('string > 0').narrow((val, ctx) => (val != null && isKnownTimezone(val)) || ctx.mustBe('a known timezone'));
-
 /**
  * Creates a {@link FitDateRangeToDayPeriodFunction} that collapses a multi-day date range into a single-day period within the given timezone.
  *
@@ -3144,12 +2909,6 @@ function parseISO8601DayStringToDate(dayString) {
 function isValidDateCellIndex(input) {
     return input >= 0 && Number.isInteger(input);
 }
-/**
- * ArkType schema for {@link DateCell}.
- */
-const dateCellType = type({
-    i: 'number.integer >= 0'
-});
 /**
  * Normalizes a number or {@link DateCell} to a DateCell object.
  *
@@ -3190,13 +2949,6 @@ function dateCellTimingStartsAtForStartOfDay(input = {}) {
         timezone
     };
 }
-/**
- * ArkType schema for {@link DateCellTiming}.
- */
-const dateCellTimingType = dateDurationSpanType.merge({
-    end: 'Date',
-    timezone: knownTimezoneType
-});
 /**
  * Creates a {@link DateTimezoneUtcNormalInstance} from the input, guaranteeing that a timezone string is configured.
  *
@@ -3782,12 +3534,6 @@ function isValidFullDateCellTiming(timing) {
     return isValid;
 }
 
-/**
- * ArkType schema for {@link DateCellRange}.
- */
-const dateCellRangeType = dateCellType.merge({
-    'to?': 'number.integer >= 0'
-});
 /**
  * Returns true if the input is a DateCellRange.
  *
@@ -5241,16 +4987,78 @@ function isDateWithinDateCellRangeFunction(config) {
 }
 
 /**
- * Creates a filter that passes date cell duration spans whose start time is at or before the given reference time.
- *
- * Useful for identifying events or blocks that have already begun relative to a point in time.
+ * Computes the end date for a duration span by adding the duration to the start time.
  *
- * @param now - Reference time to compare against. Defaults to the current time.
+ * @param span - the duration span to compute the end for
+ * @returns the date when the span ends
  *
  * @example
  * ```ts
- * const hasStarted = dateCellDurationSpanHasStartedFilterFunction(new Date());
- * const startedSpans = allSpans.filter(hasStarted);
+ * const span = { startsAt: new Date('2024-01-01T10:00:00Z'), duration: 60 };
+ * dateDurationSpanEndDate(span); // 2024-01-01T11:00:00Z
+ * ```
+ */
+function dateDurationSpanEndDate(span) {
+    return addMinutes(span.startsAt, span.duration);
+}
+/**
+ * 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
+ */
+function durationSpanToDateRange(span) {
+    return {
+        start: span.startsAt,
+        end: addMinutes(span.startsAt, span.duration)
+    };
+}
+/**
+ * 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
+ */
+function durationSpanFromDateRange(dateRange) {
+    return {
+        startsAt: dateRange.start,
+        duration: differenceInMinutes(dateRange.end, dateRange.start)
+    };
+}
+/**
+ * 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'
+ */
+function durationSpanDateRelativeState(span, now) {
+    return dateRangeRelativeState(durationSpanToDateRange(span), now);
+}
+/**
+ * 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)
+ */
+function fractionalHoursInDurationSpan(span) {
+    return minutesToFractionalHours(span.duration);
+}
+function isSameDurationSpan(a, b) {
+    return safeCompareEquality(a, b, (a, b) => a.duration === b.duration && isSameDate(a.startsAt, b.startsAt));
+}
+
+/**
+ * Creates a filter that passes date cell duration spans whose start time is at or before the given reference time.
+ *
+ * Useful for identifying events or blocks that have already begun relative to a point in time.
+ *
+ * @param now - Reference time to compare against. Defaults to the current time.
+ *
+ * @example
+ * ```ts
+ * const hasStarted = dateCellDurationSpanHasStartedFilterFunction(new Date());
+ * const startedSpans = allSpans.filter(hasStarted);
  * ```
  */
 function dateCellDurationSpanHasStartedFilterFunction(now = new Date()) {
@@ -6059,14 +5867,6 @@ function isSameDateCellSchedule(a, b) {
         return a == b;
     }
 }
-/**
- * ArkType schema for {@link DateCellSchedule}.
- */
-const dateCellScheduleType = type({
-    w: [DATE_CELL_SCHEDULE_ENCODED_WEEK_REGEX, '&', 'string'],
-    'd?': 'number.integer >= 0 []',
-    'ex?': 'number.integer >= 0 []'
-});
 /**
  * Returns true if the input is possibly a DateCellScheduleDateRange (has schedule fields and valid start/end dates).
  *
@@ -6576,17 +6376,144 @@ function dateCellIndexsForDateCellScheduleDayCodes(sundayIndex, dayCodes) {
 }
 
 /**
- * ArkType schema that validates a value is a valid {@link DateCellTiming}.
+ * Returns all recognized IANA timezone strings, including the explicit UTC entry.
+ *
+ * @example
+ * ```ts
+ * const zones = allTimezoneStrings();
+ * // ['Africa/Abidjan', ..., 'UTC']
+ * ```
+ */
+function allTimezoneStrings() {
+    return timeZonesNames.concat(UTC_TIMEZONE_STRING);
+}
+/**
+ * Lazily-computed set of all known timezone strings for O(1) membership checks.
+ *
+ * @example
+ * ```ts
+ * allKnownTimezoneStrings().has('America/New_York'); // true
+ * ```
  */
-const validDateCellTimingType = dateCellTimingType.narrow((val, ctx) => (val != null && isValidDateCellTiming(val)) || ctx.mustBe('a valid DateCellTiming'));
+const allKnownTimezoneStrings = cachedGetter(() => {
+    return new Set(allTimezoneStrings());
+});
 /**
- * ArkType schema that validates a value is a valid {@link DateCellRange} (non-negative indexes, `to >= i`).
+ * Lazily-computed array of {@link TimezoneInfo} for every known timezone.
+ *
+ * Abbreviations are resolved at the time of first access, so results reflect
+ * the DST state at that moment.
  */
-const validDateCellRangeType = dateCellRangeType.narrow((val, ctx) => (val != null && isValidDateCellRange(val)) || ctx.mustBe('a valid DateCellRange'));
+const allTimezoneInfos = cachedGetter(() => {
+    const now = new Date();
+    return allTimezoneStrings().map((x) => timezoneStringToTimezoneInfo(x, now));
+});
 /**
- * ArkType schema that validates a value is a sorted array of non-overlapping {@link DateCellRange} values.
+ * Returns the {@link TimezoneInfo} for the current system timezone, falling back to UTC.
+ *
+ * @example
+ * ```ts
+ * const info = timezoneInfoForSystem();
+ * console.log(info.abbreviation); // e.g., 'CST'
+ * ```
  */
-const validDateCellRangeSeriesType = type(dateCellRangeType.array()).narrow((val, ctx) => (val != null && isValidDateCellRangeSeries(val)) || ctx.mustBe('a valid DateCellRange series with items sorted in ascending order and no repeat indexes'));
+function timezoneInfoForSystem() {
+    return timezoneStringToTimezoneInfo(guessCurrentTimezone() ?? UTC_TIMEZONE_STRING);
+}
+/**
+ * Returns the short abbreviation (e.g., `"EST"`, `"PDT"`) for the given timezone at the specified date.
+ *
+ * The date matters because abbreviations change with DST transitions.
+ * Returns `"UKNOWN"` if no timezone is provided.
+ *
+ * @example
+ * ```ts
+ * getTimezoneAbbreviation('America/New_York'); // 'EST' or 'EDT'
+ * ```
+ */
+function getTimezoneAbbreviation(timezone, date = new Date()) {
+    return timezone === UTC_TIMEZONE_STRING ? UTC_TIMEZONE_STRING : timezone ? formatInTimeZone(date, timezone, 'zzz') : 'UKNOWN';
+}
+/**
+ * Returns the full display name (e.g., `"Eastern Standard Time"`) for the given timezone.
+ *
+ * Returns `"Unknown Timezone"` if no timezone is provided.
+ *
+ * @example
+ * ```ts
+ * getTimezoneLongName('America/New_York'); // 'Eastern Standard Time'
+ * ```
+ */
+function getTimezoneLongName(timezone, date = new Date()) {
+    return timezone ? formatInTimeZone(date, timezone, 'zzzz') : 'Unknown Timezone';
+}
+/**
+ * Builds a {@link TimezoneInfo} for the given timezone, computing abbreviation and search variants.
+ *
+ * @example
+ * ```ts
+ * const info = timezoneStringToTimezoneInfo('America/Chicago');
+ * // info.abbreviation => 'CST' or 'CDT'
+ * // info.search => 'america chicago'
+ * ```
+ */
+function timezoneStringToTimezoneInfo(timezone, date = new Date()) {
+    const abbreviation = getTimezoneAbbreviation(timezone, date);
+    const result = {
+        timezone,
+        search: timezoneStringToSearchableString(timezone),
+        lowercase: timezone.toLowerCase(),
+        abbreviation,
+        lowercaseAbbreviation: abbreviation.toLowerCase()
+    };
+    return result;
+}
+/**
+ * Filters timezone infos by a search string, matching against the searchable name,
+ * lowercase identifier, and abbreviation.
+ *
+ * For queries longer than 2 characters, substring matching on the searchable name is also used.
+ *
+ * @example
+ * ```ts
+ * const results = searchTimezoneInfos('eastern', allTimezoneInfos());
+ * ```
+ */
+function searchTimezoneInfos(search, infos) {
+    const searchString = search.toLocaleLowerCase();
+    return infos.filter((x) => (search.length > 2 && x.search.includes(searchString)) || x.lowercase.startsWith(searchString) || x.lowercaseAbbreviation.startsWith(searchString) || x.abbreviation.includes(search) || x.search === x.timezone);
+}
+const timezoneStringToSearchableStringReplace = replaceStringsFunction({
+    replace: ['/', '_'],
+    replaceWith: ' '
+});
+/**
+ * Converts a timezone identifier into a lowercase, space-separated string for search indexing.
+ *
+ * Replaces `/` and `_` with spaces (e.g., `"America/New_York"` becomes `"america new york"`).
+ *
+ * @example
+ * ```ts
+ * timezoneStringToSearchableString('America/New_York'); // 'america new york'
+ * ```
+ */
+function timezoneStringToSearchableString(timezone) {
+    return timezoneStringToSearchableStringReplace(timezone.toLocaleLowerCase());
+}
+/**
+ * Checks whether the input string is a recognized IANA timezone identifier.
+ *
+ * Uses the cached set from {@link allKnownTimezoneStrings} for O(1) lookup.
+ *
+ * @example
+ * ```ts
+ * isKnownTimezone('America/New_York'); // true
+ * isKnownTimezone('Mars/Olympus');     // false
+ * ```
+ */
+function isKnownTimezone(input) {
+    return allKnownTimezoneStrings().has(input);
+}
 
 /**
  * Distinguishes between time-based calendar events and all-day/multi-day events.
@@ -6602,12 +6529,6 @@ var CalendarDateType;
      */
     CalendarDateType["DAYS"] = "days";
 })(CalendarDateType || (CalendarDateType = {}));
-/**
- * ArkType schema for {@link CalendarDate}.
- */
-const calendarDateType = dateDurationSpanType.merge({
-    type: type.enumerated(...Object.values(CalendarDateType))
-});
 /**
  * Creates a {@link CalendarDateFactory} that produces all-day calendar events with timezone-aware start times.
  *
@@ -6677,6 +6598,151 @@ function calendarDateForDateDurationSpan(dateDurationSpan) {
     };
 }
 
+// MARK: Timezone
+/**
+ * ArkType DTO schema that validates a string is a recognized IANA timezone.
+ *
+ * Delegates to {@link isKnownTimezone} for the actual check.
+ *
+ * Intended for validating and parsing DTO/JSON data where timezones arrive as strings.
+ *
+ * @example
+ * ```ts
+ * const result = knownTimezoneType('America/Denver');
+ * ```
+ */
+const knownTimezoneType = type('string > 0').narrow((val, ctx) => (val != null && isKnownTimezone(val)) || ctx.mustBe('a known timezone'));
+// MARK: DateDurationSpan
+/**
+ * ArkType DTO schema for {@link DateDurationSpan}.
+ *
+ * Accepts both Date objects and date strings (parsed via `string.date.parse`).
+ * Use this schema when validating and converting serialized data (e.g., API responses, JSON payloads)
+ * or runtime Date objects into the corresponding runtime types.
+ */
+const dateDurationSpanType = type({
+    startsAt: ARKTYPE_DATE_DTO_TYPE,
+    duration: 'number >= 0'
+});
+// MARK: DateRange
+/**
+ * ArkType DTO schema for {@link DateRange}.
+ *
+ * Accepts both Date objects and date strings (parsed via `string.date.parse`).
+ * Use this schema when validating and converting serialized data (e.g., API responses, JSON payloads)
+ * or runtime Date objects into the corresponding runtime types.
+ */
+const dateRangeType = type({
+    start: ARKTYPE_DATE_DTO_TYPE,
+    end: ARKTYPE_DATE_DTO_TYPE
+});
+// MARK: DateRangeParams
+/**
+ * ArkType DTO schema for {@link DateRangeParams}.
+ *
+ * Accepts both Date objects and date strings (parsed via `string.date.parse`).
+ * Use this schema when validating and converting serialized data (e.g., API responses, JSON payloads)
+ * or runtime Date objects into the corresponding runtime types.
+ */
+const dateRangeParamsType = type({
+    type: type.enumerated(...Object.values(DateRangeType)),
+    date: ARKTYPE_DATE_DTO_TYPE,
+    'distance?': 'number'
+});
+// MARK: DateCell
+/**
+ * ArkType DTO schema for {@link DateCell}.
+ *
+ * Validates a cell index from JSON/DTO input.
+ * Use this schema when validating and converting serialized data (e.g., API responses, JSON payloads)
+ * into the corresponding runtime types.
+ */
+const dateCellType = type({
+    i: 'number.integer >= 0'
+});
+// MARK: DateCellRange
+/**
+ * ArkType DTO schema for {@link DateCellRange}.
+ *
+ * Validates cell range indexes from JSON/DTO input.
+ * Use this schema when validating and converting serialized data (e.g., API responses, JSON payloads)
+ * into the corresponding runtime types.
+ */
+const dateCellRangeType = dateCellType.merge({
+    'to?': 'number.integer >= 0'
+});
+// MARK: DateCellTiming
+/**
+ * ArkType DTO schema for {@link DateCellTiming}.
+ *
+ * Accepts both Date objects and date strings (parsed via `string.date.parse`).
+ * Use this schema when validating and converting serialized data (e.g., API responses, JSON payloads)
+ * or runtime Date objects into the corresponding runtime types.
+ */
+const dateCellTimingType = dateDurationSpanType.merge({
+    end: ARKTYPE_DATE_DTO_TYPE,
+    timezone: knownTimezoneType
+});
+// MARK: CalendarDate
+/**
+ * ArkType DTO schema for {@link CalendarDate}.
+ *
+ * Accepts both Date objects and date strings (parsed via `string.date.parse`).
+ * Use this schema when validating and converting serialized data (e.g., API responses, JSON payloads)
+ * or runtime Date objects into the corresponding runtime types.
+ */
+const calendarDateType = dateDurationSpanType.merge({
+    type: type.enumerated(...Object.values(CalendarDateType))
+});
+// MARK: DateCellSchedule
+/**
+ * ArkType DTO schema for {@link DateCellSchedule}.
+ *
+ * Validates schedule data from JSON/DTO input.
+ * Use this schema when validating and converting serialized data (e.g., API responses, JSON payloads)
+ * into the corresponding runtime types.
+ */
+const dateCellScheduleType = type({
+    w: [DATE_CELL_SCHEDULE_ENCODED_WEEK_REGEX, '&', 'string'],
+    'd?': 'number.integer >= 0 []',
+    'ex?': 'number.integer >= 0 []'
+});
+// MARK: ModelRecurrenceInfo
+/**
+ * ArkType DTO schema for {@link ModelRecurrenceInfo}.
+ *
+ * Accepts both Date objects and date strings (parsed via `string.date.parse`).
+ * Use this schema when validating and converting serialized data (e.g., API responses, JSON payloads)
+ * or runtime Date objects into the corresponding runtime types.
+ */
+const modelRecurrenceInfoType = type({
+    'timezone?': 'string',
+    rrule: 'string',
+    start: ARKTYPE_DATE_DTO_TYPE,
+    end: ARKTYPE_DATE_DTO_TYPE,
+    'forever?': 'boolean'
+});
+// MARK: Validators
+/**
+ * ArkType DTO schema that validates a value is a valid {@link DateCellTiming}.
+ *
+ * Accepts both Date objects and date strings (parsed via `string.date.parse`), then validates the resulting timing
+ * using {@link isValidDateCellTiming}.
+ */
+const validDateCellTimingType = dateCellTimingType.narrow((val, ctx) => (val != null && isValidDateCellTiming(val)) || ctx.mustBe('a valid DateCellTiming'));
+/**
+ * ArkType DTO schema that validates a value is a valid {@link DateCellRange} (non-negative indexes, `to >= i`).
+ *
+ * Validates cell range data from JSON/DTO input.
+ */
+const validDateCellRangeType = dateCellRangeType.narrow((val, ctx) => (val != null && isValidDateCellRange(val)) || ctx.mustBe('a valid DateCellRange'));
+/**
+ * ArkType DTO schema that validates a value is a sorted array of non-overlapping {@link DateCellRange} values.
+ *
+ * Validates cell range series data from JSON/DTO input.
+ */
+const validDateCellRangeSeriesType = type(dateCellRangeType.array()).narrow((val, ctx) => (val != null && isValidDateCellRangeSeries(val)) || ctx.mustBe('a valid DateCellRange series with items sorted in ascending order and no repeat indexes'));
+
 /**
  * A {@link HashSet} specialized for Date values, using the millisecond timestamp as the hash key.
  *
@@ -8780,16 +8846,6 @@ class DateRRuleUtility {
     }
 }
 
-/**
- * ArkType schema for {@link ModelRecurrenceInfo}.
- */
-const modelRecurrenceInfoType = type({
-    'timezone?': 'string',
-    rrule: 'string',
-    start: 'Date',
-    end: 'Date',
-    'forever?': 'boolean'
-});
 /**
  * Stateless utility for converting between recurrence input
  * ({@link ModelRecurrenceStart}) and the indexed storage form