@dereekb/dbx-components-mcp 13.11.2 → 13.11.4

package/generated/dereekb-date.utils.mcp.generated.json

@@ -5,6 +5,1215 @@
   "generatedAt": "1970-01-01T00:00:00.000Z",
   "generator": "@dereekb/dbx-components-mcp/scripts/generate-manifests.mjs",
   "entries": [
+    {
+      "slug": "date-cell-range-of-timing-factory",
+      "name": "dateCellRangeOfTimingFactory",
+      "kind": "function",
+      "category": "date",
+      "module": "@dereekb/date",
+      "subpath": "date/date.cell.factory",
+      "signature": "dateCellRangeOfTimingFactory(config: DateCallIndexRangeFromDatesFactoryConfig): DateCellRangeOfTimingFactory",
+      "description": "Creates a {@link DateCellRangeOfTimingFactory} that converts dates or indexes into a clamped\n{@link DateCellRangeWithRange} relative to the configured timing.\n\nWhen `fitToTimingRange` is true (default), the returned range is clamped to the timing's valid index bounds.\nWhen `limitToCompletedIndexes` is true, only indexes whose timing duration has fully elapsed are included,\nwith the max boundary lazily refreshed as time passes.",
+      "params": [
+        {
+          "name": "config",
+          "type": "DateCallIndexRangeFromDatesFactoryConfig",
+          "description": "- Configuration specifying the timing, range fit, and completion constraints.",
+          "optional": false
+        }
+      ],
+      "returns": "A factory function that produces a clamped {@link DateCellRangeWithRange } from optional start/end input.",
+      "tags": [
+        "date",
+        "cell",
+        "range",
+        "timing",
+        "factory",
+        "clamp",
+        "completed",
+        "index",
+        "of",
+        "datecellrangeoftimingfactory"
+      ],
+      "example": "const timing = dateCellTiming({ startsAt, duration: 60 }, 5);\nconst factory = dateCellRangeOfTimingFactory({ timing });\n\n// Clamp an arbitrary range to the timing's bounds (0..4)\nconst range = factory({ i: -10, to: 10 });\n// range.i === 0, range.to === 4\n\n// With no input, defaults to 0..now\nconst defaultRange = factory();",
+      "relatedSlugs": [
+        "date-cell-range-of-timing",
+        "date-cell-timing-completed-time-range",
+        "date-cell-index-range"
+      ]
+    },
+    {
+      "slug": "date-cell-range-of-timing",
+      "name": "dateCellRangeOfTiming",
+      "kind": "function",
+      "category": "date",
+      "module": "@dereekb/date",
+      "subpath": "date/date.cell.factory",
+      "signature": "dateCellRangeOfTiming(config: DateCellTiming | DateCallIndexRangeFromDatesFactoryConfig, input?: Maybe<DateCellRangeOfTimingInput>): DateCellRangeWithRange",
+      "description": "Computes a {@link DateCellRangeWithRange} from a timing and optional start/end input.\n\nShorthand for creating a {@link dateCellRangeOfTimingFactory} and immediately invoking it.",
+      "params": [
+        {
+          "name": "config",
+          "type": "DateCellTiming | DateCallIndexRangeFromDatesFactoryConfig",
+          "description": "- A {@link DateCellTiming } or full factory configuration.",
+          "optional": false
+        },
+        {
+          "name": "input",
+          "type": "Maybe<DateCellRangeOfTimingInput>",
+          "description": "- Optional start/end boundaries for the range.",
+          "optional": true
+        }
+      ],
+      "returns": "A clamped {@link DateCellRangeWithRange } derived from the timing and input.",
+      "tags": [
+        "date",
+        "cell",
+        "range",
+        "timing",
+        "clamp",
+        "shorthand",
+        "of",
+        "datecellrangeoftiming"
+      ],
+      "relatedSlugs": [
+        "date-cell-range-of-timing-factory",
+        "date-cell-timing-completed-time-range"
+      ]
+    },
+    {
+      "slug": "date-cell-timing-completed-time-range",
+      "name": "dateCellTimingCompletedTimeRange",
+      "kind": "function",
+      "category": "date",
+      "module": "@dereekb/date",
+      "subpath": "date/date.cell.factory",
+      "signature": "dateCellTimingCompletedTimeRange(timing: DateCellTiming, config?: DateCellTimingCompleteTimeRangeConfig): DateCellRangeWithRange",
+      "description": "Returns a {@link DateCellRangeWithRange} representing only the completed (fully elapsed) portion\nof the timing schedule. Useful for determining which days have already finished.\n\nBy default fitToTimingRange is true.",
+      "params": [
+        {
+          "name": "timing",
+          "type": "DateCellTiming",
+          "description": "- The timing schedule to evaluate.",
+          "optional": false
+        },
+        {
+          "name": "config",
+          "type": "DateCellTimingCompleteTimeRangeConfig",
+          "description": "- Optional configuration for the current time reference and range fitting.",
+          "optional": true
+        }
+      ],
+      "returns": "A {@link DateCellRangeWithRange } covering only the completed day indexes.",
+      "tags": [
+        "date",
+        "cell",
+        "timing",
+        "completed",
+        "range",
+        "elapsed",
+        "index",
+        "time",
+        "datecelltimingcompletedtimerange"
+      ],
+      "relatedSlugs": [
+        "date-cell-timing-latest-completed-index",
+        "date-cell-range-of-timing-factory"
+      ]
+    },
+    {
+      "slug": "date-cell-timing-latest-completed-index",
+      "name": "dateCellTimingLatestCompletedIndex",
+      "kind": "function",
+      "category": "date",
+      "module": "@dereekb/date",
+      "subpath": "date/date.cell.factory",
+      "signature": "dateCellTimingLatestCompletedIndex(timing: DateCellTiming, now?: Date): IndexNumber",
+      "description": "Returns the latest completed day index for a {@link DateCellTiming}.\n\nReturns -1 if no days have been completed yet.",
+      "params": [
+        {
+          "name": "timing",
+          "type": "DateCellTiming",
+          "description": "- The timing schedule to evaluate.",
+          "optional": false
+        },
+        {
+          "name": "now",
+          "type": "Date",
+          "description": "- Optional reference time; defaults to the current time.",
+          "optional": true
+        }
+      ],
+      "returns": "The zero-based index of the last fully completed day, or -1 if none.",
+      "tags": [
+        "date",
+        "cell",
+        "timing",
+        "latest",
+        "completed",
+        "index",
+        "elapsed",
+        "datecelltiminglatestcompletedindex"
+      ],
+      "relatedSlugs": [
+        "date-cell-timing-completed-time-range",
+        "date-cell-timing-end-index"
+      ]
+    },
+    {
+      "slug": "date-cell-range-to-date-cell-index-range",
+      "name": "dateCellRangeToDateCellIndexRange",
+      "kind": "function",
+      "category": "date",
+      "module": "@dereekb/date",
+      "subpath": "date/date.cell.factory",
+      "signature": "dateCellRangeToDateCellIndexRange(range: DateCellRange): DateCellIndexRange",
+      "description": "Converts a {@link DateCellRange} (inclusive `to`) to a {@link DateCellIndexRange} (exclusive `maxIndex`).",
+      "params": [
+        {
+          "name": "range",
+          "type": "DateCellRange",
+          "description": "- The inclusive date cell range to convert.",
+          "optional": false
+        }
+      ],
+      "returns": "A {@link DateCellIndexRange } with exclusive `maxIndex`.",
+      "tags": [
+        "date",
+        "cell",
+        "range",
+        "index-range",
+        "convert",
+        "inclusive",
+        "exclusive",
+        "to",
+        "index",
+        "datecellrangetodatecellindexrange"
+      ],
+      "relatedSlugs": [
+        "date-cell-index-range-to-date-cell-range",
+        "date-cell-index-range"
+      ]
+    },
+    {
+      "slug": "date-cell-index-range-to-date-cell-range",
+      "name": "dateCellIndexRangeToDateCellRange",
+      "kind": "function",
+      "category": "date",
+      "module": "@dereekb/date",
+      "subpath": "date/date.cell.factory",
+      "signature": "dateCellIndexRangeToDateCellRange(range: DateCellIndexRange): DateCellRangeWithRange",
+      "description": "Converts a {@link DateCellIndexRange} (exclusive `maxIndex`) back to a {@link DateCellRangeWithRange} (inclusive `to`).",
+      "params": [
+        {
+          "name": "range",
+          "type": "DateCellIndexRange",
+          "description": "- The exclusive date cell index range to convert.",
+          "optional": false
+        }
+      ],
+      "returns": "A {@link DateCellRangeWithRange } with inclusive `to`.",
+      "tags": [
+        "date",
+        "cell",
+        "range",
+        "index-range",
+        "convert",
+        "exclusive",
+        "inclusive",
+        "index",
+        "to",
+        "datecellindexrangetodatecellrange"
+      ],
+      "relatedSlugs": [
+        "date-cell-range-to-date-cell-index-range",
+        "date-cell-index-range"
+      ]
+    },
+    {
+      "slug": "date-cell-index-range",
+      "name": "dateCellIndexRange",
+      "kind": "function",
+      "category": "date",
+      "module": "@dereekb/date",
+      "subpath": "date/date.cell.factory",
+      "signature": "dateCellIndexRange(timing: DateCellTiming, limit?: DateCellTimingRangeInput, fitToTimingRange?: boolean): DateCellIndexRange",
+      "description": "Generates a {@link DateCellIndexRange} based on the input timing.\n\nAn arbitrary limit can also be applied. When `fitToTimingRange` is true (default),\nthe limit is intersected with the timing's own range; otherwise the limit is used as-is.",
+      "params": [
+        {
+          "name": "timing",
+          "type": "DateCellTiming",
+          "description": "- The timing schedule to derive the range from.",
+          "optional": false
+        },
+        {
+          "name": "limit",
+          "type": "DateCellTimingRangeInput",
+          "description": "- Optional range input to constrain the output.",
+          "optional": true
+        },
+        {
+          "name": "fitToTimingRange",
+          "type": "boolean",
+          "description": "- Whether to intersect the limit with the timing's own range. Defaults to true.",
+          "optional": true
+        }
+      ],
+      "returns": "A {@link DateCellIndexRange } representing the computed index bounds.",
+      "tags": [
+        "date",
+        "cell",
+        "index-range",
+        "timing",
+        "bounds",
+        "limit",
+        "intersect",
+        "index",
+        "range",
+        "datecellindexrange"
+      ],
+      "relatedSlugs": [
+        "date-cell-range-to-date-cell-index-range",
+        "date-cell-index-range-to-date-cell-range"
+      ]
+    },
+    {
+      "slug": "expand-date-cell-collection",
+      "name": "expandDateCellCollection",
+      "kind": "function",
+      "category": "date",
+      "module": "@dereekb/date",
+      "subpath": "date/date.cell.factory",
+      "signature": "expandDateCellCollection(collection: DateCellCollection<B>): DateCellDurationSpan<B>[]",
+      "description": "Expands a {@link DateCellCollection} into an array of {@link DateCellDurationSpan} values\nby combining its timing and blocks.\n\nShorthand for calling {@link expandDateCellTiming} with `collection.timing` and `collection.blocks`.",
+      "params": [
+        {
+          "name": "collection",
+          "type": "DateCellCollection<B>",
+          "description": "- The date cell collection containing timing and blocks to expand.",
+          "optional": false
+        }
+      ],
+      "returns": "An array of {@link DateCellDurationSpan } values with concrete start times and durations.",
+      "tags": [
+        "date",
+        "cell",
+        "collection",
+        "expand",
+        "duration-span",
+        "blocks",
+        "expanddatecellcollection"
+      ],
+      "relatedSlugs": [
+        "expand-date-cell-timing",
+        "date-cell-timing-expansion-factory"
+      ]
+    },
+    {
+      "slug": "expand-date-cell-timing",
+      "name": "expandDateCellTiming",
+      "kind": "function",
+      "category": "date",
+      "module": "@dereekb/date",
+      "subpath": "date/date.cell.factory",
+      "signature": "expandDateCellTiming(timing: DateCellTiming, blocks: B[]): DateCellDurationSpan<B>[]",
+      "description": "Expands the given blocks into {@link DateCellDurationSpan} values using the provided timing.\n\nShorthand for creating a {@link dateCellTimingExpansionFactory} and immediately invoking it.",
+      "params": [
+        {
+          "name": "timing",
+          "type": "DateCellTiming",
+          "description": "- The timing schedule providing start times and duration.",
+          "optional": false
+        },
+        {
+          "name": "blocks",
+          "type": "B[]",
+          "description": "- The date cell blocks to expand into duration spans.",
+          "optional": false
+        }
+      ],
+      "returns": "An array of {@link DateCellDurationSpan } values with concrete start times.",
+      "tags": [
+        "date",
+        "cell",
+        "timing",
+        "expand",
+        "duration-span",
+        "blocks",
+        "shorthand",
+        "expanddatecelltiming"
+      ],
+      "relatedSlugs": [
+        "expand-date-cell-collection",
+        "date-cell-timing-expansion-factory"
+      ]
+    },
+    {
+      "slug": "date-cell-timing-expansion-factory",
+      "name": "dateCellTimingExpansionFactory",
+      "kind": "function",
+      "category": "date",
+      "module": "@dereekb/date",
+      "subpath": "date/date.cell.factory",
+      "signature": "dateCellTimingExpansionFactory(config: DateCellTimingExpansionFactoryConfig): DateCellTimingExpansionFactory<B>",
+      "description": "Creates a {@link DateCellTimingExpansionFactory} that expands date cell blocks into\n{@link DateCellDurationSpan} values with concrete start times and durations.\n\nBlocks with a range (`i` to `to`) are expanded into individual single-index entries.\nFiltering is applied both at the block level and at the computed duration span level,\nand evaluation can be capped for performance with large datasets.",
+      "params": [
+        {
+          "name": "config",
+          "type": "DateCellTimingExpansionFactoryConfig",
+          "description": "- Configuration specifying the timing, range limits, filters, and output caps.",
+          "optional": false
+        }
+      ],
+      "returns": "A factory function that expands date cell blocks into {@link DateCellDurationSpan } arrays.",
+      "tags": [
+        "date",
+        "cell",
+        "timing",
+        "expansion",
+        "factory",
+        "blocks",
+        "duration-span",
+        "filter",
+        "datecelltimingexpansionfactory"
+      ],
+      "example": "const timing = dateCellTiming({ startsAt, duration: 60 }, 5);\nconst expand = dateCellTimingExpansionFactory({ timing });\n\nconst blocks: DateCell[] = [{ i: 0 }, { i: 1 }, { i: 2 }];\nconst spans = expand(blocks);\n// Each span has { i, startsAt, duration } with the concrete start time for that day\n\n// With range blocks:\nconst rangeBlocks = [{ i: 0, to: 2 }];\nconst expandedSpans = expand(rangeBlocks);\n// Produces 3 spans, one for each index 0, 1, 2",
+      "relatedSlugs": [
+        "expand-date-cell-collection",
+        "expand-date-cell-timing",
+        "date-cell-day-timing-info-factory"
+      ]
+    },
+    {
+      "slug": "date-cell-day-timing-info-factory",
+      "name": "dateCellDayTimingInfoFactory",
+      "kind": "function",
+      "category": "date",
+      "module": "@dereekb/date",
+      "subpath": "date/date.cell.factory",
+      "signature": "dateCellDayTimingInfoFactory(config: DateCellDayTimingInfoFactoryConfig): DateCellDayTimingInfoFactory",
+      "description": "Creates a {@link DateCellDayTimingInfoFactory} that computes detailed timing information\n(progress state, start/end times, range membership) for any given date or day index.\n\nThe factory handles timezone normalization internally and accounts for edge cases\nwhere a timing window spans midnight into the next day.",
+      "params": [
+        {
+          "name": "config",
+          "type": "DateCellDayTimingInfoFactoryConfig",
+          "description": "- Configuration providing the timing and optional range limit.",
+          "optional": false
+        }
+      ],
+      "returns": "A factory that computes {@link DateCellDayTimingInfo } for any date or day index.",
+      "tags": [
+        "date",
+        "cell",
+        "day",
+        "timing",
+        "info",
+        "factory",
+        "progress",
+        "in-progress",
+        "complete",
+        "datecelldaytiminginfofactory"
+      ],
+      "example": "const timing = dateCellTiming({ startsAt, duration: 60 }, 5);\nconst infoFactory = dateCellDayTimingInfoFactory({ timing });\n\n// Get info for day index 2\nconst info = infoFactory(2, new Date());\nconsole.log(info.isInProgress);    // whether day 2's window is currently active\nconsole.log(info.startsAtOnDay);   // concrete start time for day 2\nconsole.log(info.isInRange);       // whether index 2 is within the timing's range\n\n// Get info for a specific date\nconst dateInfo = infoFactory(someDate);\nconsole.log(dateInfo.dayIndex);    // which day index this date falls on",
+      "relatedSlugs": [
+        "date-cell-timing-relative-index-factory",
+        "date-cell-timing-expansion-factory",
+        "date-cell-timing-completed-time-range"
+      ]
+    },
+    {
+      "slug": "is-date-cell-timing-relative-index-factory",
+      "name": "isDateCellTimingRelativeIndexFactory",
+      "kind": "function",
+      "category": "date",
+      "module": "@dereekb/date",
+      "subpath": "date/date.cell.factory",
+      "signature": "isDateCellTimingRelativeIndexFactory(input: unknown): input is DateCellTimingRelativeIndexFactory<T>",
+      "description": "Type guard that returns true if the input is a {@link DateCellTimingRelativeIndexFactory}.\n\nChecks for the presence of `_timing` and `_normalInstance` properties on a function.",
+      "params": [
+        {
+          "name": "input",
+          "type": "unknown",
+          "description": "- The value to check.",
+          "optional": false
+        }
+      ],
+      "returns": "True if the input is a {@link DateCellTimingRelativeIndexFactory }.",
+      "tags": [
+        "date",
+        "cell",
+        "timing",
+        "relative-index",
+        "factory",
+        "type-guard",
+        "check",
+        "is",
+        "relative",
+        "index",
+        "isdatecelltimingrelativeindexfactory"
+      ],
+      "relatedSlugs": [
+        "date-cell-timing-relative-index-factory"
+      ]
+    },
+    {
+      "slug": "date-cell-timing-relative-index-factory",
+      "name": "dateCellTimingRelativeIndexFactory",
+      "kind": "function",
+      "category": "date",
+      "module": "@dereekb/date",
+      "subpath": "date/date.cell.factory",
+      "signature": "dateCellTimingRelativeIndexFactory(input: T | DateCellTimingRelativeIndexFactory<T>): DateCellTimingRelativeIndexFactory<T>",
+      "description": "Creates a {@link DateCellTimingRelativeIndexFactory} that converts dates, ISO8601 day strings,\nor indexes into a zero-based day index relative to the timing's start date.\n\nIf an existing factory is passed, it is returned as-is (idempotent). The factory normalizes\nall date inputs through UTC to handle timezone offsets correctly, computing the floor\nof the hour difference divided by 24 to determine the day offset.",
+      "params": [
+        {
+          "name": "input",
+          "type": "T | DateCellTimingRelativeIndexFactory<T>",
+          "description": "- A timing configuration or an existing factory (returned as-is).",
+          "optional": false
+        }
+      ],
+      "returns": "A factory that converts dates, ISO8601 day strings, or indexes to zero-based day offsets.",
+      "tags": [
+        "date",
+        "cell",
+        "timing",
+        "relative-index",
+        "factory",
+        "day-offset",
+        "iso8601",
+        "timezone",
+        "relative",
+        "index",
+        "datecelltimingrelativeindexfactory"
+      ],
+      "example": "const timing = dateCellTiming({ startsAt, duration: 60 }, 5);\nconst indexFactory = dateCellTimingRelativeIndexFactory(timing);\n\n// Numeric indexes pass through unchanged\nindexFactory(3); // 3\n\n// Dates are converted to their day offset from timing start\nindexFactory(addDays(startsAt, 2)); // 2\n\n// ISO8601 day strings are also supported\nindexFactory('2024-01-15'); // day offset from timing start\n\n// Access the underlying timing and normalizer\nindexFactory._timing;         // the original timing\nindexFactory._normalInstance;  // timezone normalizer",
+      "relatedSlugs": [
+        "is-date-cell-timing-relative-index-factory",
+        "get-relative-index-for-date-cell-timing",
+        "date-cell-timing-relative-index-array-factory"
+      ]
+    },
+    {
+      "slug": "date-cell-timing-relative-index-array-factory",
+      "name": "dateCellTimingRelativeIndexArrayFactory",
+      "kind": "function",
+      "category": "date",
+      "module": "@dereekb/date",
+      "subpath": "date/date.cell.factory",
+      "signature": "dateCellTimingRelativeIndexArrayFactory(indexFactory: DateCellTimingRelativeIndexFactory<T>): DateCellTimingRelativeIndexArrayFactory<T>",
+      "description": "Creates a {@link DateCellTimingRelativeIndexArrayFactory} that converts mixed arrays of\ndates, date ranges, and cell ranges into a flat array of day indexes.\n\nDate ranges and cell ranges are expanded to include every index within the range.",
+      "params": [
+        {
+          "name": "indexFactory",
+          "type": "DateCellTimingRelativeIndexFactory<T>",
+          "description": "- The relative index factory used for date-to-index conversion.",
+          "optional": false
+        }
+      ],
+      "returns": "A factory that flattens mixed date/range arrays into day index arrays.",
+      "tags": [
+        "date",
+        "cell",
+        "timing",
+        "relative-index",
+        "array",
+        "factory",
+        "expand",
+        "range",
+        "relative",
+        "index",
+        "datecelltimingrelativeindexarrayfactory"
+      ],
+      "relatedSlugs": [
+        "date-cell-timing-relative-index-factory",
+        "date-cell-index-range"
+      ]
+    },
+    {
+      "slug": "get-relative-index-for-date-cell-timing",
+      "name": "getRelativeIndexForDateCellTiming",
+      "kind": "function",
+      "category": "date",
+      "module": "@dereekb/date",
+      "subpath": "date/date.cell.factory",
+      "signature": "getRelativeIndexForDateCellTiming(timing: DateCellTimingStartsAt, date?: DateOrDateCellIndex): DateCellIndex",
+      "description": "Convenience function that returns the zero-based day index for a date (or index)\nrelative to the given timing's start.\n\nDefaults to the current date/time if no date is provided.",
+      "params": [
+        {
+          "name": "timing",
+          "type": "DateCellTimingStartsAt",
+          "description": "- The timing providing the start date and timezone context.",
+          "optional": false
+        },
+        {
+          "name": "date",
+          "type": "DateOrDateCellIndex",
+          "description": "- A date or index to convert; defaults to the current date/time.",
+          "optional": true
+        }
+      ],
+      "returns": "The zero-based day index relative to the timing's start.",
+      "tags": [
+        "date",
+        "cell",
+        "timing",
+        "relative-index",
+        "day-offset",
+        "shorthand",
+        "get",
+        "relative",
+        "index",
+        "for",
+        "getrelativeindexfordatecelltiming"
+      ],
+      "example": "const timing: DateCellTimingStartsAt = { startsAt, timezone: 'America/Denver' };\n\n// Get today's index relative to the timing\nconst todayIndex = getRelativeIndexForDateCellTiming(timing);\n\n// Get the index for a specific date\nconst index = getRelativeIndexForDateCellTiming(timing, someDate);",
+      "relatedSlugs": [
+        "date-cell-timing-relative-index-factory",
+        "get-relative-date-for-date-cell-timing"
+      ]
+    },
+    {
+      "slug": "date-cell-timing-date-factory",
+      "name": "dateCellTimingDateFactory",
+      "kind": "function",
+      "category": "date",
+      "module": "@dereekb/date",
+      "subpath": "date/date.cell.factory",
+      "signature": "dateCellTimingDateFactory(timing: T): DateCellTimingDateFactory<T>",
+      "description": "Creates a {@link DateCellTimingDateFactory} that maps day indexes to calendar dates\nwhile preserving the current time-of-day.\n\nThis is useful when you need the actual Date for a given index (e.g., for display or\ndate arithmetic) but want to retain the hours/minutes of \"now\" rather than using\nthe timing's startsAt time.",
+      "params": [
+        {
+          "name": "timing",
+          "type": "T",
+          "description": "- The timing providing the start date and timezone context.",
+          "optional": false
+        }
+      ],
+      "returns": "A factory that maps day indexes to calendar dates preserving the current time-of-day.",
+      "tags": [
+        "date",
+        "cell",
+        "timing",
+        "factory",
+        "day-index",
+        "calendar",
+        "time-of-day",
+        "datecelltimingdatefactory"
+      ],
+      "example": "const timing = dateCellTiming({ startsAt, duration: 60 }, 5);\nconst dateFactory = dateCellTimingDateFactory(timing);\n\n// Pass through dates unchanged\ndateFactory(someDate); // returns someDate\n\n// Convert index 3 to a date with current time-of-day\nconst dateForDay3 = dateFactory(3);\n\n// Convert index 3 to a date with a specific reference time\nconst dateForDay3AtNoon = dateFactory(3, noonDate);",
+      "relatedSlugs": [
+        "date-cell-timing-start-date-factory",
+        "date-cell-timing-starts-at-date-factory",
+        "get-relative-date-for-date-cell-timing"
+      ]
+    },
+    {
+      "slug": "date-cell-timing-end-index",
+      "name": "dateCellTimingEndIndex",
+      "kind": "function",
+      "category": "date",
+      "module": "@dereekb/date",
+      "subpath": "date/date.cell.factory",
+      "signature": "dateCellTimingEndIndex(input: DateCellTiming | DateCellTimingRelativeIndexFactory<DateCellTiming>): IndexNumber",
+      "description": "Returns the last (maximum) day index for a {@link DateCellTiming} schedule.\n\nThis is the index corresponding to the timing's `end` date, representing the final\nday in the schedule.",
+      "params": [
+        {
+          "name": "input",
+          "type": "DateCellTiming | DateCellTimingRelativeIndexFactory<DateCellTiming>",
+          "description": "- A timing or an existing relative index factory.",
+          "optional": false
+        }
+      ],
+      "returns": "The zero-based index of the last day in the schedule.",
+      "tags": [
+        "date",
+        "cell",
+        "timing",
+        "end",
+        "index",
+        "last",
+        "datecelltimingendindex"
+      ],
+      "example": "const timing = dateCellTiming({ startsAt, duration: 60 }, 5);\nconst lastIndex = dateCellTimingEndIndex(timing); // 4 (zero-based, 5 days)",
+      "relatedSlugs": [
+        "date-cell-timing-relative-index-factory",
+        "date-cell-timing-end-date-factory",
+        "date-cell-timing-latest-completed-index"
+      ]
+    },
+    {
+      "slug": "date-cell-timing-start-date-factory",
+      "name": "dateCellTimingStartDateFactory",
+      "kind": "function",
+      "category": "date",
+      "module": "@dereekb/date",
+      "subpath": "date/date.cell.factory",
+      "signature": "dateCellTimingStartDateFactory(input: T | DateCellTimingRelativeIndexFactory<T>): DateCellTimingStartDateFactory<T>",
+      "description": "Creates a {@link DateCellTimingStartDateFactory} that computes the calendar start-of-day date\nfor any day index relative to the timing's start.\n\nThe returned date represents the beginning of the day in the timing's timezone context.",
+      "params": [
+        {
+          "name": "input",
+          "type": "T | DateCellTimingRelativeIndexFactory<T>",
+          "description": "- A timing or an existing relative index factory.",
+          "optional": false
+        }
+      ],
+      "returns": "A factory that maps day indexes to the start-of-day date in the timing's timezone.",
+      "tags": [
+        "date",
+        "cell",
+        "timing",
+        "start-of-day",
+        "factory",
+        "day-index",
+        "calendar",
+        "timezone",
+        "start",
+        "datecelltimingstartdatefactory"
+      ],
+      "relatedSlugs": [
+        "date-cell-timing-starts-at-date-factory",
+        "date-cell-timing-end-date-factory",
+        "date-cell-timing-date-factory"
+      ]
+    },
+    {
+      "slug": "date-cell-timing-starts-at-date-factory",
+      "name": "dateCellTimingStartsAtDateFactory",
+      "kind": "function",
+      "category": "date",
+      "module": "@dereekb/date",
+      "subpath": "date/date.cell.factory",
+      "signature": "dateCellTimingStartsAtDateFactory(input: T | DateCellTimingRelativeIndexFactory<T>): DateCellTimingStartsAtDateFactory<T>",
+      "description": "Creates a {@link DateCellTimingStartsAtDateFactory} that computes the concrete event start time\nfor any day index relative to the timing's schedule.\n\nThe returned date reflects the actual `startsAt` time-of-day offset to the correct calendar date\nfor the requested index, with proper timezone normalization.",
+      "params": [
+        {
+          "name": "input",
+          "type": "T | DateCellTimingRelativeIndexFactory<T>",
+          "description": "- A timing or an existing relative index factory.",
+          "optional": false
+        }
+      ],
+      "returns": "A factory that computes the concrete event start time for any day index.",
+      "tags": [
+        "date",
+        "cell",
+        "timing",
+        "starts-at",
+        "factory",
+        "day-index",
+        "event-time",
+        "calendar",
+        "starts",
+        "at",
+        "datecelltimingstartsatdatefactory"
+      ],
+      "example": "const timing = dateCellTiming({ startsAt, duration: 60 }, 5);\nconst startsAtFactory = dateCellTimingStartsAtDateFactory(timing);\n\n// Get the exact start time for day 3\nconst day3Start = startsAtFactory(3);\n// Returns a Date with the same time-of-day as startsAt but on day 3's calendar date\n\n// Also works with dates\nconst startForDate = startsAtFactory(someDate);",
+      "relatedSlugs": [
+        "date-cell-timing-start-date-factory",
+        "date-cell-timing-end-date-factory",
+        "date-cell-timing-date-factory"
+      ]
+    },
+    {
+      "slug": "date-cell-timing-end-date-factory",
+      "name": "dateCellTimingEndDateFactory",
+      "kind": "function",
+      "category": "date",
+      "module": "@dereekb/date",
+      "subpath": "date/date.cell.factory",
+      "signature": "dateCellTimingEndDateFactory(input: T | DateCellTimingRelativeIndexFactory<T>): DateCellTimingEndDateFactory<T>",
+      "description": "Creates a {@link DateCellTimingEndDateFactory} that computes the end time\n(startsAt + duration) for any day index relative to the timing's schedule.",
+      "params": [
+        {
+          "name": "input",
+          "type": "T | DateCellTimingRelativeIndexFactory<T>",
+          "description": "- A timing or an existing relative index factory.",
+          "optional": false
+        }
+      ],
+      "returns": "A factory that computes the end time (startsAt + duration) for any day index.",
+      "tags": [
+        "date",
+        "cell",
+        "timing",
+        "end",
+        "factory",
+        "day-index",
+        "duration",
+        "event-time",
+        "datecelltimingenddatefactory"
+      ],
+      "example": "const timing = dateCellTiming({ startsAt, duration: 60 }, 5);\nconst endFactory = dateCellTimingEndDateFactory(timing);\n\n// Get the end time for day 2 (startsAt time + 60 minutes on day 2)\nconst day2End = endFactory(2);",
+      "relatedSlugs": [
+        "date-cell-timing-starts-at-date-factory",
+        "date-cell-timing-start-date-factory"
+      ]
+    },
+    {
+      "slug": "get-relative-date-for-date-cell-timing",
+      "name": "getRelativeDateForDateCellTiming",
+      "kind": "function",
+      "category": "date",
+      "module": "@dereekb/date",
+      "subpath": "date/date.cell.factory",
+      "signature": "getRelativeDateForDateCellTiming(timing: DateCellTimingStartsAt, input: DateOrDateCellIndex): Date",
+      "description": "Convenience function that returns the calendar date for a given day index or date\nrelative to the timing. Shorthand for creating a {@link dateCellTimingDateFactory} and invoking it.",
+      "params": [
+        {
+          "name": "timing",
+          "type": "DateCellTimingStartsAt",
+          "description": "- The timing providing the start date and timezone context.",
+          "optional": false
+        },
+        {
+          "name": "input",
+          "type": "DateOrDateCellIndex",
+          "description": "- A date or day index to convert.",
+          "optional": false
+        }
+      ],
+      "returns": "The calendar date corresponding to the input, preserving current time-of-day.",
+      "tags": [
+        "date",
+        "cell",
+        "timing",
+        "relative-date",
+        "day-index",
+        "calendar",
+        "shorthand",
+        "get",
+        "relative",
+        "for",
+        "getrelativedatefordatecelltiming"
+      ],
+      "relatedSlugs": [
+        "date-cell-timing-date-factory",
+        "get-relative-index-for-date-cell-timing"
+      ]
+    },
+    {
+      "slug": "update-date-cell-timing-with-date-cell-timing-event",
+      "name": "updateDateCellTimingWithDateCellTimingEvent",
+      "kind": "function",
+      "category": "date",
+      "module": "@dereekb/date",
+      "subpath": "date/date.cell.factory",
+      "signature": "updateDateCellTimingWithDateCellTimingEvent(input: UpdateDateCellTimingWithDateCellTimingEventInput): FullDateCellTiming",
+      "description": "Produces a new {@link FullDateCellTiming} by selectively replacing parts of an existing timing\nwith values from a {@link DateCellTimingEvent}.\n\nThis is the primary mechanism for updating a timing schedule in response to user edits.\nThe `replaceStartDay`, `replaceStartsAt`, `endOnEvent`, and `replaceDuration` flags\nindependently control which aspects of the timing are modified, and can be combined.\n\nWhen both `replaceStartDay` and `replaceStartsAt` are true, the event's startsAt is used directly.\nWhen only `replaceStartDay` is true, the day changes but the time-of-day is preserved.\nWhen only `replaceStartsAt` is true, the time-of-day changes but the calendar date is preserved.",
+      "params": [
+        {
+          "name": "input",
+          "type": "UpdateDateCellTimingWithDateCellTimingEventInput",
+          "description": "- Configuration specifying the timing to update, the event source, and which aspects to replace.",
+          "optional": false
+        }
+      ],
+      "returns": "A new {@link FullDateCellTiming } with the requested aspects replaced.",
+      "tags": [
+        "date",
+        "cell",
+        "timing",
+        "event",
+        "update",
+        "replace",
+        "modify",
+        "edit",
+        "with",
+        "updatedatecelltimingwithdatecelltimingevent"
+      ],
+      "example": "const result = updateDateCellTimingWithDateCellTimingEvent({\n  timing: existingTiming,\n  event: { startsAt: newStartTime, duration: 90 },\n  replaceStartsAt: true,\n  replaceDuration: true\n});\n// result has the same start day and end day, but new time-of-day and 90-minute duration",
+      "relatedSlugs": [
+        "date-cell-timing-starts-at-date-factory",
+        "date-cell-timing-start-date-factory"
+      ]
+    },
+    {
+      "slug": "is-date-within-date-cell-range-function",
+      "name": "isDateWithinDateCellRangeFunction",
+      "kind": "function",
+      "category": "date",
+      "module": "@dereekb/date",
+      "subpath": "date/date.cell.factory",
+      "signature": "isDateWithinDateCellRangeFunction(config: IsDateWithinDateCellRangeConfig): IsDateWithinDateCellRangeFunction",
+      "description": "Creates a predicate that checks whether a date, index, or range falls within\nthe configured reference range.\n\nConverts all date-based inputs to cell indexes using the configured (or inferred) timezone\nbefore performing the containment check.",
+      "params": [
+        {
+          "name": "config",
+          "type": "IsDateWithinDateCellRangeConfig",
+          "description": "- Configuration specifying the reference range and optional timezone context.",
+          "optional": false
+        }
+      ],
+      "returns": "A predicate function that checks containment within the configured range.",
+      "tags": [
+        "date",
+        "cell",
+        "range",
+        "contains",
+        "within",
+        "predicate",
+        "factory",
+        "check",
+        "is",
+        "function",
+        "isdatewithindatecellrangefunction"
+      ],
+      "example": "const isInRange = isDateWithinDateCellRangeFunction({\n  startsAt: timing,\n  range: { i: 2, to: 5 }\n});\n\nisInRange(3);        // true - index 3 is within [2, 5]\nisInRange(6);        // false - index 6 is outside [2, 5]\nisInRange(someDate); // converts date to index, then checks containment",
+      "relatedSlugs": [
+        "date-cell-timing-relative-index-factory",
+        "date-cell-index-range"
+      ]
+    },
+    {
+      "slug": "time-duration-data-is-empty",
+      "name": "timeDurationDataIsEmpty",
+      "kind": "function",
+      "category": "date",
+      "module": "@dereekb/date",
+      "subpath": "date/date.duration.data",
+      "signature": "timeDurationDataIsEmpty(data: TimeDurationData): boolean",
+      "description": "Returns true if the input TimeDurationData has no meaningful values (all zero or undefined).",
+      "params": [
+        {
+          "name": "data",
+          "type": "TimeDurationData",
+          "description": "- The duration data to check",
+          "optional": false
+        }
+      ],
+      "returns": "True if empty",
+      "tags": [
+        "date",
+        "duration",
+        "empty",
+        "check",
+        "time",
+        "zero",
+        "data",
+        "is",
+        "timedurationdataisempty"
+      ],
+      "example": "timeDurationDataIsEmpty({}); // true\ntimeDurationDataIsEmpty({ hours: 0, minutes: 0 }); // true\ntimeDurationDataIsEmpty({ hours: 1 }); // false",
+      "relatedSlugs": [
+        "duration-data-to-milliseconds",
+        "milliseconds-to-duration-data"
+      ]
+    },
+    {
+      "slug": "duration-data-to-milliseconds",
+      "name": "durationDataToMilliseconds",
+      "kind": "function",
+      "category": "date",
+      "module": "@dereekb/date",
+      "subpath": "date/date.duration.data",
+      "signature": "durationDataToMilliseconds(data: TimeDurationData): Milliseconds",
+      "description": "Converts a TimeDurationData to total milliseconds by summing all fields.",
+      "params": [
+        {
+          "name": "data",
+          "type": "TimeDurationData",
+          "description": "- The duration data to convert",
+          "optional": false
+        }
+      ],
+      "returns": "Total milliseconds",
+      "tags": [
+        "date",
+        "duration",
+        "milliseconds",
+        "convert",
+        "sum",
+        "time",
+        "total",
+        "data",
+        "to",
+        "durationdatatomilliseconds"
+      ],
+      "example": "durationDataToMilliseconds({ hours: 1, minutes: 30 }); // 5400000\ndurationDataToMilliseconds({ days: 1, hours: 2 }); // 93600000",
+      "relatedSlugs": [
+        "milliseconds-to-duration-data",
+        "parse-duration-string-to-milliseconds",
+        "time-duration-data-is-empty"
+      ]
+    },
+    {
+      "slug": "milliseconds-to-duration-data",
+      "name": "millisecondsToDurationData",
+      "kind": "function",
+      "category": "date",
+      "module": "@dereekb/date",
+      "subpath": "date/date.duration.data",
+      "signature": "millisecondsToDurationData(ms: Milliseconds, units?: readonly TimeUnit[]): TimeDurationData",
+      "description": "Decomposes milliseconds into a TimeDurationData object using the specified units.\n\nBreaks down from largest to smallest unit, only using units in the provided list.",
+      "params": [
+        {
+          "name": "ms",
+          "type": "Milliseconds",
+          "description": "- The total milliseconds to decompose",
+          "optional": false
+        },
+        {
+          "name": "units",
+          "type": "readonly TimeUnit[]",
+          "description": "- Which units to decompose into (defaults to days, hours, minutes, seconds)",
+          "optional": true
+        }
+      ],
+      "returns": "A TimeDurationData with the decomposed values",
+      "tags": [
+        "date",
+        "duration",
+        "milliseconds",
+        "decompose",
+        "convert",
+        "breakdown",
+        "units",
+        "time",
+        "to",
+        "data",
+        "millisecondstodurationdata"
+      ],
+      "example": "millisecondsToDurationData(5400000); // { days: 0, hours: 1, minutes: 30, seconds: 0 }\nmillisecondsToDurationData(90000, ['min', 's']); // { minutes: 1, seconds: 30 }",
+      "relatedSlugs": [
+        "duration-data-to-milliseconds",
+        "parse-duration-string",
+        "format-duration-string"
+      ]
+    },
+    {
+      "slug": "get-duration-data-value",
+      "name": "getDurationDataValue",
+      "kind": "function",
+      "category": "date",
+      "module": "@dereekb/date",
+      "subpath": "date/date.duration.data",
+      "signature": "getDurationDataValue(data: TimeDurationData, unit: TimeUnit): number",
+      "description": "Reads a specific time unit value from a TimeDurationData object.",
+      "params": [
+        {
+          "name": "data",
+          "type": "TimeDurationData",
+          "description": "- The duration data",
+          "optional": false
+        },
+        {
+          "name": "unit",
+          "type": "TimeUnit",
+          "description": "- The time unit to read",
+          "optional": false
+        }
+      ],
+      "returns": "The value for that unit, or 0 if not set",
+      "tags": [
+        "date",
+        "duration",
+        "get",
+        "read",
+        "value",
+        "unit",
+        "time",
+        "field",
+        "data",
+        "getdurationdatavalue"
+      ],
+      "relatedSlugs": [
+        "set-duration-data-value",
+        "duration-data-to-milliseconds"
+      ]
+    },
+    {
+      "slug": "set-duration-data-value",
+      "name": "setDurationDataValue",
+      "kind": "function",
+      "category": "date",
+      "module": "@dereekb/date",
+      "subpath": "date/date.duration.data",
+      "signature": "setDurationDataValue(data: TimeDurationData, unit: TimeUnit, value: number): TimeDurationData",
+      "description": "Returns a new TimeDurationData with the specified unit set to the given value.",
+      "params": [
+        {
+          "name": "data",
+          "type": "TimeDurationData",
+          "description": "- The original duration data",
+          "optional": false
+        },
+        {
+          "name": "unit",
+          "type": "TimeUnit",
+          "description": "- The time unit to set",
+          "optional": false
+        },
+        {
+          "name": "value",
+          "type": "number",
+          "description": "- The new value",
+          "optional": false
+        }
+      ],
+      "returns": "A new TimeDurationData with the updated value",
+      "tags": [
+        "date",
+        "duration",
+        "set",
+        "update",
+        "value",
+        "unit",
+        "time",
+        "field",
+        "immutable",
+        "data",
+        "setdurationdatavalue"
+      ],
+      "relatedSlugs": [
+        "get-duration-data-value",
+        "duration-data-to-milliseconds"
+      ]
+    },
+    {
+      "slug": "parse-duration-string",
+      "name": "parseDurationString",
+      "kind": "function",
+      "category": "date",
+      "module": "@dereekb/date",
+      "subpath": "date/date.duration.data",
+      "signature": "parseDurationString(input: string): TimeDurationData",
+      "description": "Parses a human-readable duration string into a TimeDurationData object.\n\nSupports compact formats (\"3d10h5m8s\"), spaced formats (\"3d 10h 5m 8s\"),\nand long formats (\"3 days 10 hours 5 minutes 8 seconds\"). Mixed formats\nare also supported. If the same unit appears multiple times, values are summed.\n\nIf the string contains only a number with no unit, it is treated as the\nsmallest unit that would make sense (milliseconds by default).",
+      "params": [
+        {
+          "name": "input",
+          "type": "string",
+          "description": "- The duration string to parse",
+          "optional": false
+        }
+      ],
+      "returns": "A TimeDurationData object with the parsed values",
+      "tags": [
+        "date",
+        "duration",
+        "parse",
+        "string",
+        "time",
+        "human-readable",
+        "decode",
+        "parsedurationstring"
+      ],
+      "example": "parseDurationString('3d10h5m8s'); // { days: 3, hours: 10, minutes: 5, seconds: 8 }\nparseDurationString('2 hours 30 minutes'); // { hours: 2, minutes: 30 }\nparseDurationString('1w 2d'); // { weeks: 1, days: 2 }\nparseDurationString('500ms'); // { milliseconds: 500 }",
+      "relatedSlugs": [
+        "parse-duration-string-to-milliseconds",
+        "format-duration-string",
+        "format-duration-string-long",
+        "milliseconds-to-duration-data"
+      ]
+    },
+    {
+      "slug": "parse-duration-string-to-milliseconds",
+      "name": "parseDurationStringToMilliseconds",
+      "kind": "function",
+      "category": "date",
+      "module": "@dereekb/date",
+      "subpath": "date/date.duration.data",
+      "signature": "parseDurationStringToMilliseconds(input: string): Milliseconds",
+      "description": "Parses a duration string directly to milliseconds.",
+      "params": [
+        {
+          "name": "input",
+          "type": "string",
+          "description": "- The duration string to parse",
+          "optional": false
+        }
+      ],
+      "returns": "Total milliseconds",
+      "tags": [
+        "date",
+        "duration",
+        "parse",
+        "string",
+        "milliseconds",
+        "convert",
+        "decode",
+        "to",
+        "parsedurationstringtomilliseconds"
+      ],
+      "example": "parseDurationStringToMilliseconds('1h30m'); // 5400000",
+      "relatedSlugs": [
+        "parse-duration-string",
+        "duration-data-to-milliseconds",
+        "format-duration-string"
+      ]
+    },
+    {
+      "slug": "format-duration-string",
+      "name": "formatDurationString",
+      "kind": "function",
+      "category": "date",
+      "module": "@dereekb/date",
+      "subpath": "date/date.duration.data",
+      "signature": "formatDurationString(data: TimeDurationData): string",
+      "description": "Formats a TimeDurationData to a compact string like \"3d10h5m8s\".\n\nOmits zero-value units. Returns \"0s\" if all fields are zero or empty.",
+      "params": [
+        {
+          "name": "data",
+          "type": "TimeDurationData",
+          "description": "- The duration data to format",
+          "optional": false
+        }
+      ],
+      "returns": "A compact duration string",
+      "tags": [
+        "date",
+        "duration",
+        "format",
+        "string",
+        "compact",
+        "encode",
+        "time",
+        "formatdurationstring"
+      ],
+      "example": "formatDurationString({ days: 3, hours: 10, minutes: 5, seconds: 8 }); // \"3d10h5m8s\"\nformatDurationString({ hours: 2, minutes: 30 }); // \"2h30m\"\nformatDurationString({}); // \"0s\"",
+      "relatedSlugs": [
+        "format-duration-string-long",
+        "parse-duration-string",
+        "duration-data-to-milliseconds"
+      ]
+    },
+    {
+      "slug": "format-duration-string-long",
+      "name": "formatDurationStringLong",
+      "kind": "function",
+      "category": "date",
+      "module": "@dereekb/date",
+      "subpath": "date/date.duration.data",
+      "signature": "formatDurationStringLong(data: TimeDurationData): string",
+      "description": "Formats a TimeDurationData to a long human-readable string.\n\nOmits zero-value units. Returns \"0 seconds\" if all fields are zero or empty.",
+      "params": [
+        {
+          "name": "data",
+          "type": "TimeDurationData",
+          "description": "- The duration data to format",
+          "optional": false
+        }
+      ],
+      "returns": "A human-readable duration string",
+      "tags": [
+        "date",
+        "duration",
+        "format",
+        "string",
+        "long",
+        "human-readable",
+        "encode",
+        "time",
+        "formatdurationstringlong"
+      ],
+      "example": "formatDurationStringLong({ days: 3, hours: 10 }); // \"3 days 10 hours\"\nformatDurationStringLong({ hours: 1, minutes: 1 }); // \"1 hour 1 minute\"",
+      "relatedSlugs": [
+        "format-duration-string",
+        "parse-duration-string",
+        "duration-data-to-milliseconds"
+      ]
+    },
     {
       "slug": "date-duration-span-end-date",
       "name": "dateDurationSpanEndDate",
@@ -221,6 +1430,52 @@
         "format-date-distance"
       ]
     },
+    {
+      "slug": "format-to-time-range-string",
+      "name": "formatToTimeRangeString",
+      "kind": "function",
+      "category": "date",
+      "module": "@dereekb/date",
+      "subpath": "date/date.format",
+      "signature": "formatToTimeRangeString(startOrDateRange: DateRange | Date, end?: Maybe<Date>, onlyTimeRange?: boolean): string",
+      "description": "Formats a date range as a time-only range string when both dates are on the same day,\nor falls back to a full date+time range when they span multiple days.\n\nSame day: `\"12:00 AM - 4:00 PM\"`\nDifferent days: `\"01/01/2001 12:00 AM - 01/02/2001 4:00 PM\"`",
+      "params": [
+        {
+          "name": "startOrDateRange",
+          "type": "DateRange | Date",
+          "description": "- date range object or start date",
+          "optional": false
+        },
+        {
+          "name": "end",
+          "type": "Maybe<Date>",
+          "description": "- optional end date when a start date is provided",
+          "optional": true
+        },
+        {
+          "name": "onlyTimeRange",
+          "type": "boolean",
+          "description": "- whether to force time-only formatting regardless of date span",
+          "optional": true
+        }
+      ],
+      "returns": "the formatted time or date+time range string",
+      "tags": [
+        "date",
+        "format",
+        "time",
+        "range",
+        "string",
+        "day-aware",
+        "to",
+        "formattotimerangestring"
+      ],
+      "example": "import { formatToTimeRangeString } from '@dereekb/date';\n\n// Same day - time only\nformatToTimeRangeString({ start: new Date('2024-01-15T09:00:00'), end: new Date('2024-01-15T17:00:00') });\n// \"9:00 AM - 5:00 PM\"\n\n// Different days - includes date\nformatToTimeRangeString({ start: new Date('2024-01-15T09:00:00'), end: new Date('2024-01-16T17:00:00') });\n// \"01/15/2024 9:00 AM - 01/16/2024 5:00 PM\"",
+      "relatedSlugs": [
+        "format-to-day-time-range-string",
+        "format-date-range"
+      ]
+    },
     {
       "slug": "date-range-days-count",
       "name": "dateRangeDaysCount",
@@ -788,6 +2043,276 @@
         "safe-to-js-date"
       ]
     },
+    {
+      "slug": "earliest-date",
+      "name": "earliestDate",
+      "kind": "function",
+      "category": "date",
+      "module": "@dereekb/date",
+      "subpath": "date/date",
+      "signature": "earliestDate(dates: Maybe<Date>[], defaultDate?: Maybe<Date>): Maybe<Date>",
+      "description": "Returns the earliest (minimum) date from the input array, ignoring null/undefined entries.",
+      "params": [
+        {
+          "name": "dates",
+          "type": "Maybe<Date>[]",
+          "description": "- array of dates that may contain null/undefined",
+          "optional": false
+        },
+        {
+          "name": "defaultDate",
+          "type": "Maybe<Date>",
+          "description": "- fallback if no valid dates exist",
+          "optional": true
+        }
+      ],
+      "returns": "the earliest date, or the default if the array has no valid dates",
+      "tags": [
+        "date",
+        "min",
+        "earliest",
+        "oldest",
+        "before",
+        "compare",
+        "sort",
+        "earliestdate"
+      ],
+      "example": "const a = new Date('2024-01-01');\nconst b = new Date('2024-06-01');\nearliestDate([a, b]); // a\nearliestDate([null, undefined], new Date()); // falls back to default",
+      "relatedSlugs": [
+        "latest-date",
+        "is-before"
+      ]
+    },
+    {
+      "slug": "latest-date",
+      "name": "latestDate",
+      "kind": "function",
+      "category": "date",
+      "module": "@dereekb/date",
+      "subpath": "date/date",
+      "signature": "latestDate(dates: Maybe<Date>[], defaultDate?: Maybe<Date>): Maybe<Date>",
+      "description": "Returns the latest (maximum) date from the input array, ignoring null/undefined entries.",
+      "params": [
+        {
+          "name": "dates",
+          "type": "Maybe<Date>[]",
+          "description": "- array of dates that may contain null/undefined",
+          "optional": false
+        },
+        {
+          "name": "defaultDate",
+          "type": "Maybe<Date>",
+          "description": "- fallback if no valid dates exist",
+          "optional": true
+        }
+      ],
+      "returns": "the latest date, or the default if the array has no valid dates",
+      "tags": [
+        "date",
+        "max",
+        "latest",
+        "newest",
+        "after",
+        "compare",
+        "sort",
+        "latestdate"
+      ],
+      "example": "const a = new Date('2024-01-01');\nconst b = new Date('2024-06-01');\nlatestDate([a, b]); // b\nlatestDate([null], new Date()); // falls back to default",
+      "relatedSlugs": [
+        "earliest-date",
+        "is-after"
+      ]
+    },
+    {
+      "slug": "is-after",
+      "name": "isAfter",
+      "kind": "function",
+      "category": "date",
+      "module": "@dereekb/date",
+      "subpath": "date/date",
+      "signature": "isAfter(a: Maybe<Date>, b: Maybe<Date>, defaultValue?: Maybe<boolean>): Maybe<boolean>",
+      "description": "Null-safe date comparison that returns true when `a` is chronologically after `b`.\n\nIf either date is null/undefined, returns the default value instead.",
+      "params": [
+        {
+          "name": "a",
+          "type": "Maybe<Date>",
+          "description": "- first date",
+          "optional": false
+        },
+        {
+          "name": "b",
+          "type": "Maybe<Date>",
+          "description": "- second date to compare against",
+          "optional": false
+        },
+        {
+          "name": "defaultValue",
+          "type": "Maybe<boolean>",
+          "description": "- returned when either date is nullish",
+          "optional": true
+        }
+      ],
+      "returns": "whether `a` is after `b`, or the default",
+      "tags": [
+        "date",
+        "after",
+        "compare",
+        "gt",
+        "greater",
+        "maybe",
+        "safe",
+        "is",
+        "isafter"
+      ],
+      "example": "const jan = new Date('2024-01-01');\nconst feb = new Date('2024-02-01');\nisAfter(feb, jan); // true\nisAfter(null, jan); // undefined\nisAfter(null, jan, false); // false",
+      "relatedSlugs": [
+        "is-before",
+        "is-same-date",
+        "latest-date"
+      ]
+    },
+    {
+      "slug": "is-before",
+      "name": "isBefore",
+      "kind": "function",
+      "category": "date",
+      "module": "@dereekb/date",
+      "subpath": "date/date",
+      "signature": "isBefore(a: Maybe<Date>, b: Maybe<Date>, defaultValue?: Maybe<boolean>): Maybe<boolean>",
+      "description": "Null-safe date comparison that returns true when `a` is chronologically before `b`.\n\nIf either date is null/undefined, returns the default value instead.",
+      "params": [
+        {
+          "name": "a",
+          "type": "Maybe<Date>",
+          "description": "- first date",
+          "optional": false
+        },
+        {
+          "name": "b",
+          "type": "Maybe<Date>",
+          "description": "- second date to compare against",
+          "optional": false
+        },
+        {
+          "name": "defaultValue",
+          "type": "Maybe<boolean>",
+          "description": "- returned when either date is nullish",
+          "optional": true
+        }
+      ],
+      "returns": "whether `a` is before `b`, or the default",
+      "tags": [
+        "date",
+        "before",
+        "compare",
+        "lt",
+        "less",
+        "maybe",
+        "safe",
+        "is",
+        "isbefore"
+      ],
+      "example": "const jan = new Date('2024-01-01');\nconst feb = new Date('2024-02-01');\nisBefore(jan, feb); // true\nisBefore(null, feb); // undefined\nisBefore(null, feb, false); // false",
+      "relatedSlugs": [
+        "is-after",
+        "is-same-date",
+        "earliest-date"
+      ]
+    },
+    {
+      "slug": "is-same-date",
+      "name": "isSameDate",
+      "kind": "function",
+      "category": "date",
+      "module": "@dereekb/date",
+      "subpath": "date/date",
+      "signature": "isSameDate(a: Maybe<Date>, b: Maybe<Date>, defaultValue?: Maybe<boolean>): Maybe<boolean>",
+      "description": "Null-safe exact date equality check (millisecond precision).\n\nWhen both dates are null/undefined and no default is provided, returns true (treating two absent values as equal).",
+      "params": [
+        {
+          "name": "a",
+          "type": "Maybe<Date>",
+          "description": "- first date",
+          "optional": false
+        },
+        {
+          "name": "b",
+          "type": "Maybe<Date>",
+          "description": "- second date",
+          "optional": false
+        },
+        {
+          "name": "defaultValue",
+          "type": "Maybe<boolean>",
+          "description": "- returned when either date is nullish (defaults to `a == b` if not provided)",
+          "optional": true
+        }
+      ],
+      "returns": "whether the dates are exactly equal",
+      "tags": [
+        "date",
+        "equal",
+        "equality",
+        "same",
+        "compare",
+        "exact",
+        "is",
+        "issamedate"
+      ],
+      "example": "const d = new Date('2024-01-01T00:00:00.000Z');\nisSameDate(d, new Date(d.getTime())); // true\nisSameDate(null, null); // true\nisSameDate(null, d); // false",
+      "relatedSlugs": [
+        "is-same-day",
+        "is-same-date-hours-and-minutes",
+        "is-after",
+        "is-before"
+      ]
+    },
+    {
+      "slug": "is-same-date-day",
+      "name": "isSameDateDay",
+      "kind": "function",
+      "category": "date",
+      "module": "@dereekb/date",
+      "subpath": "date/date",
+      "signature": "isSameDateDay(a: Maybe<Date>, b: Maybe<Date>, defaultValue?: Maybe<boolean>): Maybe<boolean>",
+      "description": "Null-safe day-level date equality check (same year, month, and day, ignoring time).\n\nWhen both dates are null/undefined and no default is provided, returns true (treating two absent values as equal).",
+      "params": [
+        {
+          "name": "a",
+          "type": "Maybe<Date>",
+          "description": "- first date",
+          "optional": false
+        },
+        {
+          "name": "b",
+          "type": "Maybe<Date>",
+          "description": "- second date",
+          "optional": false
+        },
+        {
+          "name": "defaultValue",
+          "type": "Maybe<boolean>",
+          "description": "- returned when either date is nullish",
+          "optional": true
+        }
+      ],
+      "returns": "whether both dates fall on the same calendar day",
+      "tags": [
+        "date",
+        "day",
+        "same",
+        "equal",
+        "calendar",
+        "compare",
+        "is",
+        "issamedateday"
+      ],
+      "example": "const morning = new Date('2024-01-01T08:00:00.000Z');\nconst evening = new Date('2024-01-01T20:00:00.000Z');\nisSameDateDay(morning, evening); // true\nisSameDateDay(null, null); // true",
+      "relatedSlugs": [
+        "is-same-date",
+        "is-same-date-hours-and-minutes"
+      ]
+    },
     {
       "slug": "round-down-to-minute",
       "name": "roundDownToMinute",
@@ -859,6 +2384,55 @@
         "round-date-down-to",
         "round-date-to"
       ]
+    },
+    {
+      "slug": "round-date-to",
+      "name": "roundDateTo",
+      "kind": "function",
+      "category": "date",
+      "module": "@dereekb/date",
+      "subpath": "date/date",
+      "signature": "roundDateTo(date: DateOrUnixDateTimeMillisecondsNumber, roundToUnit: DateHourMinuteOrSecond, roundType?: FloorOrCeilRounding): DateOrUnixDateTimeMillisecondsNumber",
+      "description": "Rounds a date or unix timestamp to the nearest unit boundary using the specified rounding direction.\n\nPreserves the input type: Date inputs return Date, number inputs return number.",
+      "params": [
+        {
+          "name": "date",
+          "type": "DateOrUnixDateTimeMillisecondsNumber",
+          "description": "- date or unix millisecond timestamp to round",
+          "optional": false
+        },
+        {
+          "name": "roundToUnit",
+          "type": "DateHourMinuteOrSecond",
+          "description": "- time unit to round to ('hour', 'minute', or 'second')",
+          "optional": false
+        },
+        {
+          "name": "roundType",
+          "type": "FloorOrCeilRounding",
+          "description": "- rounding direction ('floor' or 'ceil', defaults to 'floor')",
+          "optional": true
+        }
+      ],
+      "returns": "the rounded value in the same type as the input",
+      "tags": [
+        "date",
+        "round",
+        "floor",
+        "ceil",
+        "unit",
+        "hour",
+        "minute",
+        "second",
+        "truncate",
+        "to",
+        "rounddateto"
+      ],
+      "relatedSlugs": [
+        "round-date-down-to",
+        "round-down-to-minute",
+        "round-down-to-hour"
+      ]
     }
   ]
 }