date-vir 8.5.1 → 8.6.0

package/dist/date-operations/date-position.js

@@ -4,6 +4,7 @@ import { DateUnit, oneIndexedDateUnits } from '@date-vir/duration';
 import { checkValidShape, defineShape, exactShape, unionShape } from 'object-shape-tester';
 import { createFullDate } from '../full-date/create-full-date.js';
 import { toLuxonDateTime } from '../full-date/luxon-date-time-conversion.js';
+import { utcTimezone } from '../timezone/timezones.js';
 import { calculateRelativeDate } from './calculate-relative-date.js';
 import { diffDates } from './diff-dates.js';
 /**
@@ -79,6 +80,24 @@ export function getStartDate(date, unit) {
             days: -1,
         });
     }
+    else if (unit === DateUnit.Day && date.timezone === utcTimezone) {
+        /**
+         * Fast path for UTC: UTC never observes DST, so midnight always exists and the start of the
+         * day is simply the same calendar date with all time fields zeroed. This avoids a
+         * comparatively expensive Luxon round-trip.
+         *
+         * Non-UTC zones fall through to the Luxon path below because a few zones have had DST
+         * transitions at midnight (e.g. `America/Asuncion` on 2020-10-04, where midnight did not
+         * exist and `startOf('day')` is 01:00, not 00:00).
+         */
+        return {
+            ...date,
+            hour: 0,
+            minute: 0,
+            second: 0,
+            millisecond: 0,
+        };
+    }
     else {
         return createFullDate(toLuxonDateTime(date).startOf(unit), date.timezone);
     }

package/dist/extra-utils/js-date-conversion.js

@@ -1,4 +1,5 @@
 import { toTimestamp } from '../formatting/timestamp.js';
+import { userTimezone } from '../timezone/timezones.js';
 /**
  * Convert a {@link FullDate} from a built-in JS
  * [`Date`](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Date).
@@ -24,5 +25,20 @@ import { toTimestamp } from '../formatting/timestamp.js';
  * ```
  */
 export function toJsDate(fullDate) {
+    /**
+     * Fast path: when the FullDate is already in the host environment's timezone, the JS `Date`
+     * local-time constructor produces the exact same instant as the Luxon round-trip (verified to
+     * agree even across DST gaps and overlaps) at a fraction of the cost. `userTimezone` is derived
+     * from the host environment, so it is the zone the `Date` constructor interprets its arguments
+     * in.
+     *
+     * The `year >= 100` guard avoids the `Date` constructor's legacy two-digit-year behavior (years
+     * 0-99 are mapped to 1900-1999); such dates fall through to the Luxon path, which handles them
+     * correctly.
+     */
+    if (fullDate.timezone === userTimezone && fullDate.year >= 100) {
+        return new Date(fullDate.year, fullDate.month - 1, // JS Date months are 0-indexed
+        fullDate.day, fullDate.hour, fullDate.minute, fullDate.second, fullDate.millisecond);
+    }
     return new Date(toTimestamp(fullDate));
 }

package/dist/formatting/string-format-types.d.ts

@@ -63,3 +63,47 @@ export declare const utcIsoStringShape: (defaultValue?: `${number}-${number}-${n
  * ```
  */
 export declare function isValidIsoString(input: unknown): input is UtcIsoString;
+/**
+ * The abbreviated day-of-week names used by the RFC 1123 / HTTP-date format.
+ *
+ * @category Internal
+ */
+export type HttpDateDayName = 'Mon' | 'Tue' | 'Wed' | 'Thu' | 'Fri' | 'Sat' | 'Sun';
+/**
+ * The abbreviated month names used by the RFC 1123 / HTTP-date format.
+ *
+ * @category Internal
+ */
+export type HttpDateMonthName = 'Jan' | 'Feb' | 'Mar' | 'Apr' | 'May' | 'Jun' | 'Jul' | 'Aug' | 'Sep' | 'Oct' | 'Nov' | 'Dec';
+/**
+ * A full RFC 1123 / HTTP-date string in GMT: `Wed, 21 Oct 2015 07:28:00 GMT`. This is the format
+ * used by HTTP headers (per RFC 9110) and produced by `Date.prototype.toUTCString()`. It is the RFC
+ * 1123 counterpart to {@link UtcIsoString}.
+ *
+ * @category Formatting
+ * @see
+ * - https://www.rfc-editor.org/rfc/rfc9110#section-5.6.7
+ * - https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/toUTCString
+ */
+export type HttpDateString = `${HttpDateDayName}, ${number} ${HttpDateMonthName} ${number} ${JustTimeWithSecondsString} GMT`;
+/**
+ * A shape definition for {@link HttpDateString}.
+ *
+ * @category Formatting
+ */
+export declare const httpDateStringShape: (defaultValue?: `Mon, ${number} Jan ${number} ${number}:${number}:${number} GMT` | `Mon, ${number} Feb ${number} ${number}:${number}:${number} GMT` | `Mon, ${number} Mar ${number} ${number}:${number}:${number} GMT` | `Mon, ${number} Apr ${number} ${number}:${number}:${number} GMT` | `Mon, ${number} May ${number} ${number}:${number}:${number} GMT` | `Mon, ${number} Jun ${number} ${number}:${number}:${number} GMT` | `Mon, ${number} Jul ${number} ${number}:${number}:${number} GMT` | `Mon, ${number} Aug ${number} ${number}:${number}:${number} GMT` | `Mon, ${number} Sep ${number} ${number}:${number}:${number} GMT` | `Mon, ${number} Oct ${number} ${number}:${number}:${number} GMT` | `Mon, ${number} Nov ${number} ${number}:${number}:${number} GMT` | `Mon, ${number} Dec ${number} ${number}:${number}:${number} GMT` | `Tue, ${number} Jan ${number} ${number}:${number}:${number} GMT` | `Tue, ${number} Feb ${number} ${number}:${number}:${number} GMT` | `Tue, ${number} Mar ${number} ${number}:${number}:${number} GMT` | `Tue, ${number} Apr ${number} ${number}:${number}:${number} GMT` | `Tue, ${number} May ${number} ${number}:${number}:${number} GMT` | `Tue, ${number} Jun ${number} ${number}:${number}:${number} GMT` | `Tue, ${number} Jul ${number} ${number}:${number}:${number} GMT` | `Tue, ${number} Aug ${number} ${number}:${number}:${number} GMT` | `Tue, ${number} Sep ${number} ${number}:${number}:${number} GMT` | `Tue, ${number} Oct ${number} ${number}:${number}:${number} GMT` | `Tue, ${number} Nov ${number} ${number}:${number}:${number} GMT` | `Tue, ${number} Dec ${number} ${number}:${number}:${number} GMT` | `Wed, ${number} Jan ${number} ${number}:${number}:${number} GMT` | `Wed, ${number} Feb ${number} ${number}:${number}:${number} GMT` | `Wed, ${number} Mar ${number} ${number}:${number}:${number} GMT` | `Wed, ${number} Apr ${number} ${number}:${number}:${number} GMT` | `Wed, ${number} May ${number} ${number}:${number}:${number} GMT` | `Wed, ${number} Jun ${number} ${number}:${number}:${number} GMT` | `Wed, ${number} Jul ${number} ${number}:${number}:${number} GMT` | `Wed, ${number} Aug ${number} ${number}:${number}:${number} GMT` | `Wed, ${number} Sep ${number} ${number}:${number}:${number} GMT` | `Wed, ${number} Oct ${number} ${number}:${number}:${number} GMT` | `Wed, ${number} Nov ${number} ${number}:${number}:${number} GMT` | `Wed, ${number} Dec ${number} ${number}:${number}:${number} GMT` | `Thu, ${number} Jan ${number} ${number}:${number}:${number} GMT` | `Thu, ${number} Feb ${number} ${number}:${number}:${number} GMT` | `Thu, ${number} Mar ${number} ${number}:${number}:${number} GMT` | `Thu, ${number} Apr ${number} ${number}:${number}:${number} GMT` | `Thu, ${number} May ${number} ${number}:${number}:${number} GMT` | `Thu, ${number} Jun ${number} ${number}:${number}:${number} GMT` | `Thu, ${number} Jul ${number} ${number}:${number}:${number} GMT` | `Thu, ${number} Aug ${number} ${number}:${number}:${number} GMT` | `Thu, ${number} Sep ${number} ${number}:${number}:${number} GMT` | `Thu, ${number} Oct ${number} ${number}:${number}:${number} GMT` | `Thu, ${number} Nov ${number} ${number}:${number}:${number} GMT` | `Thu, ${number} Dec ${number} ${number}:${number}:${number} GMT` | `Fri, ${number} Jan ${number} ${number}:${number}:${number} GMT` | `Fri, ${number} Feb ${number} ${number}:${number}:${number} GMT` | `Fri, ${number} Mar ${number} ${number}:${number}:${number} GMT` | `Fri, ${number} Apr ${number} ${number}:${number}:${number} GMT` | `Fri, ${number} May ${number} ${number}:${number}:${number} GMT` | `Fri, ${number} Jun ${number} ${number}:${number}:${number} GMT` | `Fri, ${number} Jul ${number} ${number}:${number}:${number} GMT` | `Fri, ${number} Aug ${number} ${number}:${number}:${number} GMT` | `Fri, ${number} Sep ${number} ${number}:${number}:${number} GMT` | `Fri, ${number} Oct ${number} ${number}:${number}:${number} GMT` | `Fri, ${number} Nov ${number} ${number}:${number}:${number} GMT` | `Fri, ${number} Dec ${number} ${number}:${number}:${number} GMT` | `Sat, ${number} Jan ${number} ${number}:${number}:${number} GMT` | `Sat, ${number} Feb ${number} ${number}:${number}:${number} GMT` | `Sat, ${number} Mar ${number} ${number}:${number}:${number} GMT` | `Sat, ${number} Apr ${number} ${number}:${number}:${number} GMT` | `Sat, ${number} May ${number} ${number}:${number}:${number} GMT` | `Sat, ${number} Jun ${number} ${number}:${number}:${number} GMT` | `Sat, ${number} Jul ${number} ${number}:${number}:${number} GMT` | `Sat, ${number} Aug ${number} ${number}:${number}:${number} GMT` | `Sat, ${number} Sep ${number} ${number}:${number}:${number} GMT` | `Sat, ${number} Oct ${number} ${number}:${number}:${number} GMT` | `Sat, ${number} Nov ${number} ${number}:${number}:${number} GMT` | `Sat, ${number} Dec ${number} ${number}:${number}:${number} GMT` | `Sun, ${number} Jan ${number} ${number}:${number}:${number} GMT` | `Sun, ${number} Feb ${number} ${number}:${number}:${number} GMT` | `Sun, ${number} Mar ${number} ${number}:${number}:${number} GMT` | `Sun, ${number} Apr ${number} ${number}:${number}:${number} GMT` | `Sun, ${number} May ${number} ${number}:${number}:${number} GMT` | `Sun, ${number} Jun ${number} ${number}:${number}:${number} GMT` | `Sun, ${number} Jul ${number} ${number}:${number}:${number} GMT` | `Sun, ${number} Aug ${number} ${number}:${number}:${number} GMT` | `Sun, ${number} Sep ${number} ${number}:${number}:${number} GMT` | `Sun, ${number} Oct ${number} ${number}:${number}:${number} GMT` | `Sun, ${number} Nov ${number} ${number}:${number}:${number} GMT` | `Sun, ${number} Dec ${number} ${number}:${number}:${number} GMT` | undefined) => import("object-shape-tester").Shape<import("@sinclair/typebox").TUnsafe<`Mon, ${number} Jan ${number} ${number}:${number}:${number} GMT` | `Mon, ${number} Feb ${number} ${number}:${number}:${number} GMT` | `Mon, ${number} Mar ${number} ${number}:${number}:${number} GMT` | `Mon, ${number} Apr ${number} ${number}:${number}:${number} GMT` | `Mon, ${number} May ${number} ${number}:${number}:${number} GMT` | `Mon, ${number} Jun ${number} ${number}:${number}:${number} GMT` | `Mon, ${number} Jul ${number} ${number}:${number}:${number} GMT` | `Mon, ${number} Aug ${number} ${number}:${number}:${number} GMT` | `Mon, ${number} Sep ${number} ${number}:${number}:${number} GMT` | `Mon, ${number} Oct ${number} ${number}:${number}:${number} GMT` | `Mon, ${number} Nov ${number} ${number}:${number}:${number} GMT` | `Mon, ${number} Dec ${number} ${number}:${number}:${number} GMT` | `Tue, ${number} Jan ${number} ${number}:${number}:${number} GMT` | `Tue, ${number} Feb ${number} ${number}:${number}:${number} GMT` | `Tue, ${number} Mar ${number} ${number}:${number}:${number} GMT` | `Tue, ${number} Apr ${number} ${number}:${number}:${number} GMT` | `Tue, ${number} May ${number} ${number}:${number}:${number} GMT` | `Tue, ${number} Jun ${number} ${number}:${number}:${number} GMT` | `Tue, ${number} Jul ${number} ${number}:${number}:${number} GMT` | `Tue, ${number} Aug ${number} ${number}:${number}:${number} GMT` | `Tue, ${number} Sep ${number} ${number}:${number}:${number} GMT` | `Tue, ${number} Oct ${number} ${number}:${number}:${number} GMT` | `Tue, ${number} Nov ${number} ${number}:${number}:${number} GMT` | `Tue, ${number} Dec ${number} ${number}:${number}:${number} GMT` | `Wed, ${number} Jan ${number} ${number}:${number}:${number} GMT` | `Wed, ${number} Feb ${number} ${number}:${number}:${number} GMT` | `Wed, ${number} Mar ${number} ${number}:${number}:${number} GMT` | `Wed, ${number} Apr ${number} ${number}:${number}:${number} GMT` | `Wed, ${number} May ${number} ${number}:${number}:${number} GMT` | `Wed, ${number} Jun ${number} ${number}:${number}:${number} GMT` | `Wed, ${number} Jul ${number} ${number}:${number}:${number} GMT` | `Wed, ${number} Aug ${number} ${number}:${number}:${number} GMT` | `Wed, ${number} Sep ${number} ${number}:${number}:${number} GMT` | `Wed, ${number} Oct ${number} ${number}:${number}:${number} GMT` | `Wed, ${number} Nov ${number} ${number}:${number}:${number} GMT` | `Wed, ${number} Dec ${number} ${number}:${number}:${number} GMT` | `Thu, ${number} Jan ${number} ${number}:${number}:${number} GMT` | `Thu, ${number} Feb ${number} ${number}:${number}:${number} GMT` | `Thu, ${number} Mar ${number} ${number}:${number}:${number} GMT` | `Thu, ${number} Apr ${number} ${number}:${number}:${number} GMT` | `Thu, ${number} May ${number} ${number}:${number}:${number} GMT` | `Thu, ${number} Jun ${number} ${number}:${number}:${number} GMT` | `Thu, ${number} Jul ${number} ${number}:${number}:${number} GMT` | `Thu, ${number} Aug ${number} ${number}:${number}:${number} GMT` | `Thu, ${number} Sep ${number} ${number}:${number}:${number} GMT` | `Thu, ${number} Oct ${number} ${number}:${number}:${number} GMT` | `Thu, ${number} Nov ${number} ${number}:${number}:${number} GMT` | `Thu, ${number} Dec ${number} ${number}:${number}:${number} GMT` | `Fri, ${number} Jan ${number} ${number}:${number}:${number} GMT` | `Fri, ${number} Feb ${number} ${number}:${number}:${number} GMT` | `Fri, ${number} Mar ${number} ${number}:${number}:${number} GMT` | `Fri, ${number} Apr ${number} ${number}:${number}:${number} GMT` | `Fri, ${number} May ${number} ${number}:${number}:${number} GMT` | `Fri, ${number} Jun ${number} ${number}:${number}:${number} GMT` | `Fri, ${number} Jul ${number} ${number}:${number}:${number} GMT` | `Fri, ${number} Aug ${number} ${number}:${number}:${number} GMT` | `Fri, ${number} Sep ${number} ${number}:${number}:${number} GMT` | `Fri, ${number} Oct ${number} ${number}:${number}:${number} GMT` | `Fri, ${number} Nov ${number} ${number}:${number}:${number} GMT` | `Fri, ${number} Dec ${number} ${number}:${number}:${number} GMT` | `Sat, ${number} Jan ${number} ${number}:${number}:${number} GMT` | `Sat, ${number} Feb ${number} ${number}:${number}:${number} GMT` | `Sat, ${number} Mar ${number} ${number}:${number}:${number} GMT` | `Sat, ${number} Apr ${number} ${number}:${number}:${number} GMT` | `Sat, ${number} May ${number} ${number}:${number}:${number} GMT` | `Sat, ${number} Jun ${number} ${number}:${number}:${number} GMT` | `Sat, ${number} Jul ${number} ${number}:${number}:${number} GMT` | `Sat, ${number} Aug ${number} ${number}:${number}:${number} GMT` | `Sat, ${number} Sep ${number} ${number}:${number}:${number} GMT` | `Sat, ${number} Oct ${number} ${number}:${number}:${number} GMT` | `Sat, ${number} Nov ${number} ${number}:${number}:${number} GMT` | `Sat, ${number} Dec ${number} ${number}:${number}:${number} GMT` | `Sun, ${number} Jan ${number} ${number}:${number}:${number} GMT` | `Sun, ${number} Feb ${number} ${number}:${number}:${number} GMT` | `Sun, ${number} Mar ${number} ${number}:${number}:${number} GMT` | `Sun, ${number} Apr ${number} ${number}:${number}:${number} GMT` | `Sun, ${number} May ${number} ${number}:${number}:${number} GMT` | `Sun, ${number} Jun ${number} ${number}:${number}:${number} GMT` | `Sun, ${number} Jul ${number} ${number}:${number}:${number} GMT` | `Sun, ${number} Aug ${number} ${number}:${number}:${number} GMT` | `Sun, ${number} Sep ${number} ${number}:${number}:${number} GMT` | `Sun, ${number} Oct ${number} ${number}:${number}:${number} GMT` | `Sun, ${number} Nov ${number} ${number}:${number}:${number} GMT` | `Sun, ${number} Dec ${number} ${number}:${number}:${number} GMT`>>;
+/**
+ * Checks if the input is a valid RFC 1123 / HTTP-date string and type guards the input.
+ *
+ * @category Formatting
+ * @category Assertion
+ * @example
+ *
+ * ```ts
+ * import {isValidHttpDateString} from 'date-vir';
+ *
+ * isValidHttpDateString('no'); // `false`
+ * isValidHttpDateString('Wed, 21 Oct 2015 07:28:00 GMT'); // `true`
+ * ```
+ */
+export declare function isValidHttpDateString(input: unknown): input is HttpDateString;

package/dist/formatting/string-format-types.js

@@ -30,3 +30,33 @@ export function isValidIsoString(input) {
     const datetime = DateTime.fromISO(input);
     return datetime.toUTC().toISO() === input;
 }
+/**
+ * A shape definition for {@link HttpDateString}.
+ *
+ * @category Formatting
+ */
+export const httpDateStringShape = createCustomShape({
+    default: new Date().toUTCString(),
+    name: 'HttpDateString',
+    checkValue(value) {
+        return isValidHttpDateString(value);
+    },
+});
+/**
+ * Checks if the input is a valid RFC 1123 / HTTP-date string and type guards the input.
+ *
+ * @category Formatting
+ * @category Assertion
+ * @example
+ *
+ * ```ts
+ * import {isValidHttpDateString} from 'date-vir';
+ *
+ * isValidHttpDateString('no'); // `false`
+ * isValidHttpDateString('Wed, 21 Oct 2015 07:28:00 GMT'); // `true`
+ * ```
+ */
+export function isValidHttpDateString(input) {
+    const datetime = DateTime.fromHTTP(input);
+    return datetime.toUTC().toHTTP() === input;
+}

package/dist/formatting/timestamp.d.ts

@@ -1,5 +1,6 @@
+import { type DateLike } from '../full-date/date-like.js';
 import { type FullDate } from '../full-date/full-date-shape.js';
-import { type UtcIsoString } from './string-format-types.js';
+import { type HttpDateString, type UtcIsoString } from './string-format-types.js';
 /**
  * Convert a FullDate into a unix timestamp with milliseconds.
  *
@@ -25,7 +26,11 @@ import { type UtcIsoString } from './string-format-types.js';
  */
 export declare function toTimestamp(fullDate: FullDate): number;
 /**
- * Convert a FullDate into a UTC ISO string, always ending in Z.
+ * Convert a FullDate into a UTC ISO 8601 string, always ending in Z (for example
+ * `'2024-01-05T01:01:01.001Z'`). This is the machine-readable counterpart to
+ * {@link toHttpDateString}, which produces the human/HTTP-readable RFC 1123 format (`'Fri, 05 Jan
+ * 2024 01:01:01 GMT'`). Both represent the same instant in UTC; pick the one whose format your
+ * consumer expects.
  *
  * @category ISO
  * @category Formatting
@@ -47,5 +52,65 @@ export declare function toTimestamp(fullDate: FullDate): number;
  *
  * toUtcIsoString(exampleDate); // `'2024-01-05T01:01:01.001Z'`
  * ```
+ *
+ * @see {@link toHttpDateString} for the RFC 1123 / HTTP-date format.
  */
 export declare function toUtcIsoString(fullDate: FullDate): UtcIsoString;
+/**
+ * Parse the given {@link DateLike} (interpreted in the given timezone) and convert it directly into
+ * a UTC ISO 8601 string, always ending in Z (for example `'2024-01-05T01:01:01.001Z'`). This is a
+ * shorthand for `toUtcIsoString(createFullDate(dateLike, timezone))`.
+ *
+ * @category ISO
+ * @category Formatting
+ * @example
+ *
+ * ```ts
+ * import {createUtcIsoString, utcTimezone} from 'date-vir';
+ *
+ * createUtcIsoString('June 1, 2024', utcTimezone);
+ * createUtcIsoString(new Date());
+ * ```
+ *
+ * @throws Error: if a valid date cannot be created.
+ * @see {@link toUtcIsoString} for converting an existing {@link FullDate}.
+ */
+export declare function createUtcIsoString(
+/** The original date representation to be converted into a UTC ISO string. */
+dateLike: Readonly<DateLike>, 
+/** The timezone that this date/time is meant for / originated from. */
+timezone?: string): UtcIsoString;
+/**
+ * Convert a FullDate into an RFC 1123 / HTTP-date string in GMT (for example `'Fri, 05 Jan 2024
+ * 01:01:01 GMT'`). This is the format used by HTTP headers (per RFC 9110), and is identical to what
+ * `Date.prototype.toUTCString()` produces for the same instant.
+ *
+ * This is distinct from {@link toUtcIsoString}, which produces the ISO 8601 format
+ * (`'2024-01-05T01:01:01.001Z'`). Both represent the same instant in UTC, but they are not
+ * interchangeable: use this RFC 1123 form wherever an HTTP date is expected (e.g. `Date`,
+ * `Last-Modified`, `Expires`, or `Retry-After` headers), and use {@link toUtcIsoString} where ISO
+ * 8601 is expected. The output is always rendered in GMT regardless of the input's timezone.
+ *
+ * @category Formatting
+ * @example
+ *
+ * ```ts
+ * import {toHttpDateString} from 'date-vir';
+ *
+ * const exampleDate: FullDate = {
+ *     year: 2024,
+ *     month: 1,
+ *     day: 5,
+ *     hour: 1,
+ *     minute: 1,
+ *     second: 1,
+ *     millisecond: 1,
+ *     timezone: 'UTC',
+ * };
+ *
+ * toHttpDateString(exampleDate); // `'Fri, 05 Jan 2024 01:01:01 GMT'`
+ * ```
+ *
+ * @see {@link toUtcIsoString} for the ISO 8601 format.
+ */
+export declare function toHttpDateString(fullDate: FullDate): HttpDateString;

package/dist/formatting/timestamp.js

@@ -1,5 +1,6 @@
+import { createFullDate } from '../full-date/create-full-date.js';
 import { toLuxonDateTime } from '../full-date/luxon-date-time-conversion.js';
-import { utcTimezone } from '../timezone/timezones.js';
+import { userTimezone, utcTimezone } from '../timezone/timezones.js';
 /**
  * Convert a FullDate into a unix timestamp with milliseconds.
  *
@@ -27,7 +28,11 @@ export function toTimestamp(fullDate) {
     return toLuxonDateTime(fullDate).toMillis();
 }
 /**
- * Convert a FullDate into a UTC ISO string, always ending in Z.
+ * Convert a FullDate into a UTC ISO 8601 string, always ending in Z (for example
+ * `'2024-01-05T01:01:01.001Z'`). This is the machine-readable counterpart to
+ * {@link toHttpDateString}, which produces the human/HTTP-readable RFC 1123 format (`'Fri, 05 Jan
+ * 2024 01:01:01 GMT'`). Both represent the same instant in UTC; pick the one whose format your
+ * consumer expects.
  *
  * @category ISO
  * @category Formatting
@@ -49,6 +54,8 @@ export function toTimestamp(fullDate) {
  *
  * toUtcIsoString(exampleDate); // `'2024-01-05T01:01:01.001Z'`
  * ```
+ *
+ * @see {@link toHttpDateString} for the RFC 1123 / HTTP-date format.
  */
 export function toUtcIsoString(fullDate) {
     const isoString = toLuxonDateTime(fullDate).setZone(utcTimezone).toISO();
@@ -59,3 +66,65 @@ export function toUtcIsoString(fullDate) {
     }
     return isoString;
 }
+/**
+ * Parse the given {@link DateLike} (interpreted in the given timezone) and convert it directly into
+ * a UTC ISO 8601 string, always ending in Z (for example `'2024-01-05T01:01:01.001Z'`). This is a
+ * shorthand for `toUtcIsoString(createFullDate(dateLike, timezone))`.
+ *
+ * @category ISO
+ * @category Formatting
+ * @example
+ *
+ * ```ts
+ * import {createUtcIsoString, utcTimezone} from 'date-vir';
+ *
+ * createUtcIsoString('June 1, 2024', utcTimezone);
+ * createUtcIsoString(new Date());
+ * ```
+ *
+ * @throws Error: if a valid date cannot be created.
+ * @see {@link toUtcIsoString} for converting an existing {@link FullDate}.
+ */
+export function createUtcIsoString(
+/** The original date representation to be converted into a UTC ISO string. */
+dateLike, 
+/** The timezone that this date/time is meant for / originated from. */
+timezone = userTimezone) {
+    return toUtcIsoString(createFullDate(dateLike, timezone));
+}
+/**
+ * Convert a FullDate into an RFC 1123 / HTTP-date string in GMT (for example `'Fri, 05 Jan 2024
+ * 01:01:01 GMT'`). This is the format used by HTTP headers (per RFC 9110), and is identical to what
+ * `Date.prototype.toUTCString()` produces for the same instant.
+ *
+ * This is distinct from {@link toUtcIsoString}, which produces the ISO 8601 format
+ * (`'2024-01-05T01:01:01.001Z'`). Both represent the same instant in UTC, but they are not
+ * interchangeable: use this RFC 1123 form wherever an HTTP date is expected (e.g. `Date`,
+ * `Last-Modified`, `Expires`, or `Retry-After` headers), and use {@link toUtcIsoString} where ISO
+ * 8601 is expected. The output is always rendered in GMT regardless of the input's timezone.
+ *
+ * @category Formatting
+ * @example
+ *
+ * ```ts
+ * import {toHttpDateString} from 'date-vir';
+ *
+ * const exampleDate: FullDate = {
+ *     year: 2024,
+ *     month: 1,
+ *     day: 5,
+ *     hour: 1,
+ *     minute: 1,
+ *     second: 1,
+ *     millisecond: 1,
+ *     timezone: 'UTC',
+ * };
+ *
+ * toHttpDateString(exampleDate); // `'Fri, 05 Jan 2024 01:01:01 GMT'`
+ * ```
+ *
+ * @see {@link toUtcIsoString} for the ISO 8601 format.
+ */
+export function toHttpDateString(fullDate) {
+    return toLuxonDateTime(fullDate).toHTTP();
+}

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "date-vir",
-    "version": "8.5.1",
+    "version": "8.6.0",
     "description": "Easy and explicit dates and times.",
     "keywords": [
         "date",
@@ -36,7 +36,7 @@
     "dependencies": {
         "@augment-vir/assert": "^31.73.1",
         "@augment-vir/common": "^31.73.1",
-        "@date-vir/duration": "^8.5.1",
+        "@date-vir/duration": "^8.6.0",
         "@types/luxon": "^3.7.1",
         "luxon": "^3.7.2",
         "object-shape-tester": "^6.14.0",