@northguild/gmt 1.14.2

package/dist/plain/calculate/nextWeekday.js

@@ -0,0 +1,47 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { advanceToWeekday, isValidDayOfWeek } from "../../internal/index.js";
+import { isValidDate } from "../validate/index.js";
+/**
+ * Return a PlainDate ISO string for the next occurrence of `dayOfWeek` on or after `value`.
+ *
+ * - `dayOfWeek` uses Temporal's ISO numbering: 1 (Monday) through 7 (Sunday), consistent with
+ *   `getDayOfWeek`/`parseDayOfWeekFromDate`.
+ * - `options.inclusive` (default `false`) controls what happens when `value` already falls on
+ *   `dayOfWeek`: `false` advances a full week (matching date-fns), `true` returns `value` as-is.
+ * - Returns "" on invalid input.
+ *
+ * Replaces date-fns's sixteen `next*` functions with one parameterized call:
+ *
+ * | date-fns          | gmt                          |
+ * | ----------------- | ----------------------------- |
+ * | `nextMonday`      | `nextWeekday(value, 1)`      |
+ * | `nextTuesday`     | `nextWeekday(value, 2)`      |
+ * | `nextWednesday`   | `nextWeekday(value, 3)`      |
+ * | `nextThursday`    | `nextWeekday(value, 4)`      |
+ * | `nextFriday`      | `nextWeekday(value, 5)`      |
+ * | `nextSaturday`    | `nextWeekday(value, 6)`      |
+ * | `nextSunday`      | `nextWeekday(value, 7)`      |
+ * | `nextDay(v, n)`   | `nextWeekday(value, n)`      |
+ *
+ * @param value ISO PlainDate string
+ * @param dayOfWeek target ISO day of week (1-7, Monday-Sunday)
+ * @param options optional: inclusive (boolean, default false)
+ * @returns ISO PlainDate string for the next occurrence of `dayOfWeek`, or "" on invalid input
+ *
+ * @example nextWeekday("2024-03-15", 5) // "2024-03-22" (2024-03-15 is already a Friday, so it advances a full week)
+ * @example nextWeekday("2024-03-15", 5, { inclusive: true }) // "2024-03-15"
+ * @example nextWeekday("2024-03-13", 5) // "2024-03-15" (Wednesday -> next Friday)
+ * @example nextWeekday("invalid", 5) // ""
+ * @example nextWeekday("2024-03-15", 8) // "" (dayOfWeek out of range)
+ */
+export function nextWeekday(value, dayOfWeek, options) {
+    if (!isValidDate(value) || !isValidDayOfWeek(dayOfWeek))
+        return "";
+    try {
+        const date = Temporal.PlainDate.from(value);
+        return advanceToWeekday(date, dayOfWeek, 1, options?.inclusive ?? false).toString();
+    }
+    catch {
+        return "";
+    }
+}

package/dist/plain/calculate/previousWeekday.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Return a PlainDate ISO string for the previous occurrence of `dayOfWeek` on or before `value`.
+ *
+ * - `dayOfWeek` uses Temporal's ISO numbering: 1 (Monday) through 7 (Sunday), consistent with
+ *   `getDayOfWeek`/`parseDayOfWeekFromDate`.
+ * - `options.inclusive` (default `false`) controls what happens when `value` already falls on
+ *   `dayOfWeek`: `false` goes back a full week (matching date-fns), `true` returns `value` as-is.
+ * - Returns "" on invalid input.
+ *
+ * Replaces date-fns's sixteen `previous*` functions with one parameterized call:
+ *
+ * | date-fns              | gmt                              |
+ * | ---------------------- | --------------------------------- |
+ * | `previousMonday`      | `previousWeekday(value, 1)`      |
+ * | `previousTuesday`     | `previousWeekday(value, 2)`      |
+ * | `previousWednesday`   | `previousWeekday(value, 3)`      |
+ * | `previousThursday`    | `previousWeekday(value, 4)`      |
+ * | `previousFriday`      | `previousWeekday(value, 5)`      |
+ * | `previousSaturday`    | `previousWeekday(value, 6)`      |
+ * | `previousSunday`      | `previousWeekday(value, 7)`      |
+ * | `previousDay(v, n)`   | `previousWeekday(value, n)`      |
+ *
+ * @param value ISO PlainDate string
+ * @param dayOfWeek target ISO day of week (1-7, Monday-Sunday)
+ * @param options optional: inclusive (boolean, default false)
+ * @returns ISO PlainDate string for the previous occurrence of `dayOfWeek`, or "" on invalid input
+ *
+ * @example previousWeekday("2024-03-15", 5) // "2024-03-08" (2024-03-15 is already a Friday, so it goes back a full week)
+ * @example previousWeekday("2024-03-15", 5, { inclusive: true }) // "2024-03-15"
+ * @example previousWeekday("2024-03-13", 5) // "2024-03-08" (Wednesday -> previous Friday)
+ * @example previousWeekday("invalid", 5) // ""
+ * @example previousWeekday("2024-03-15", 0) // "" (dayOfWeek out of range)
+ */
+export declare function previousWeekday(value: string, dayOfWeek: number, options?: {
+    inclusive?: boolean;
+}): string;

package/dist/plain/calculate/previousWeekday.js

@@ -0,0 +1,47 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { advanceToWeekday, isValidDayOfWeek } from "../../internal/index.js";
+import { isValidDate } from "../validate/index.js";
+/**
+ * Return a PlainDate ISO string for the previous occurrence of `dayOfWeek` on or before `value`.
+ *
+ * - `dayOfWeek` uses Temporal's ISO numbering: 1 (Monday) through 7 (Sunday), consistent with
+ *   `getDayOfWeek`/`parseDayOfWeekFromDate`.
+ * - `options.inclusive` (default `false`) controls what happens when `value` already falls on
+ *   `dayOfWeek`: `false` goes back a full week (matching date-fns), `true` returns `value` as-is.
+ * - Returns "" on invalid input.
+ *
+ * Replaces date-fns's sixteen `previous*` functions with one parameterized call:
+ *
+ * | date-fns              | gmt                              |
+ * | ---------------------- | --------------------------------- |
+ * | `previousMonday`      | `previousWeekday(value, 1)`      |
+ * | `previousTuesday`     | `previousWeekday(value, 2)`      |
+ * | `previousWednesday`   | `previousWeekday(value, 3)`      |
+ * | `previousThursday`    | `previousWeekday(value, 4)`      |
+ * | `previousFriday`      | `previousWeekday(value, 5)`      |
+ * | `previousSaturday`    | `previousWeekday(value, 6)`      |
+ * | `previousSunday`      | `previousWeekday(value, 7)`      |
+ * | `previousDay(v, n)`   | `previousWeekday(value, n)`      |
+ *
+ * @param value ISO PlainDate string
+ * @param dayOfWeek target ISO day of week (1-7, Monday-Sunday)
+ * @param options optional: inclusive (boolean, default false)
+ * @returns ISO PlainDate string for the previous occurrence of `dayOfWeek`, or "" on invalid input
+ *
+ * @example previousWeekday("2024-03-15", 5) // "2024-03-08" (2024-03-15 is already a Friday, so it goes back a full week)
+ * @example previousWeekday("2024-03-15", 5, { inclusive: true }) // "2024-03-15"
+ * @example previousWeekday("2024-03-13", 5) // "2024-03-08" (Wednesday -> previous Friday)
+ * @example previousWeekday("invalid", 5) // ""
+ * @example previousWeekday("2024-03-15", 0) // "" (dayOfWeek out of range)
+ */
+export function previousWeekday(value, dayOfWeek, options) {
+    if (!isValidDate(value) || !isValidDayOfWeek(dayOfWeek))
+        return "";
+    try {
+        const date = Temporal.PlainDate.from(value);
+        return advanceToWeekday(date, dayOfWeek, -1, options?.inclusive ?? false).toString();
+    }
+    catch {
+        return "";
+    }
+}

package/dist/plain/calculate/roundDate.d.ts

@@ -0,0 +1,26 @@
+import { Temporal } from "@js-temporal/polyfill";
+import type { DateUnit } from "../../types/index.js";
+/**
+ * Round an ISO 8601 date string to the specified date unit.
+ *
+ * - Returns "" for invalid inputs.
+ * - Accepts date units: "year", "month", "week", "day".
+ * - Time units ("hour", "minute", etc.) are rejected and return "".
+ * - All date units use manual start-of-unit rounding.
+ * - Wraps all Temporal calls in try-catch; returns "" on any error.
+ *
+ * @param value ISO 8601 date string
+ * @param options Rounding options: smallestUnit, optional roundingIncrement and roundingMode
+ * @returns Rounded ISO 8601 date string, or "" on invalid input
+ *
+ * @example roundDate("2024-06-15", { smallestUnit: "year" }) // "2024-01-01"
+ * @example roundDate("2024-06-15", { smallestUnit: "month" }) // "2024-07-01"
+ * @example roundDate("2024-06-15", { smallestUnit: "week" }) // "2024-06-16"
+ * @example roundDate("2024-06-15", { smallestUnit: "day" }) // "2024-06-15"
+ * @example roundDate("invalid", { smallestUnit: "year" }) // ""
+ */
+export declare function roundDate(value: string, options: {
+    smallestUnit: DateUnit;
+    roundingIncrement?: number;
+    roundingMode?: Temporal.RoundingMode;
+}): string;

package/dist/plain/calculate/roundDate.js

@@ -0,0 +1,72 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { addDateUnit, getStartOfDateUnit, } from "../../internal/dateUnitHelpers.js";
+import { isValidDate, isValidDateUnit } from "../validate/index.js";
+/**
+ * Round an ISO 8601 date string to the specified date unit.
+ *
+ * - Returns "" for invalid inputs.
+ * - Accepts date units: "year", "month", "week", "day".
+ * - Time units ("hour", "minute", etc.) are rejected and return "".
+ * - All date units use manual start-of-unit rounding.
+ * - Wraps all Temporal calls in try-catch; returns "" on any error.
+ *
+ * @param value ISO 8601 date string
+ * @param options Rounding options: smallestUnit, optional roundingIncrement and roundingMode
+ * @returns Rounded ISO 8601 date string, or "" on invalid input
+ *
+ * @example roundDate("2024-06-15", { smallestUnit: "year" }) // "2024-01-01"
+ * @example roundDate("2024-06-15", { smallestUnit: "month" }) // "2024-07-01"
+ * @example roundDate("2024-06-15", { smallestUnit: "week" }) // "2024-06-16"
+ * @example roundDate("2024-06-15", { smallestUnit: "day" }) // "2024-06-15"
+ * @example roundDate("invalid", { smallestUnit: "year" }) // ""
+ */
+export function roundDate(value, options) {
+    const { smallestUnit, roundingIncrement, roundingMode } = options;
+    if (!isValidDate(value) || !isValidDateUnit(smallestUnit))
+        return "";
+    try {
+        const source = Temporal.PlainDate.from(value);
+        // Manual rounding for all date units (year, month, week, day)
+        const startOfCurrent = getStartOfDateUnit(source, smallestUnit);
+        const increment = roundingIncrement ?? 1;
+        if (increment <= 0)
+            return "";
+        const startOfNext = addDateUnit(startOfCurrent, smallestUnit, increment);
+        const elapsed = source.since(startOfCurrent);
+        const total = startOfNext.since(startOfCurrent);
+        const fraction = elapsed.total("days") / total.total("days");
+        let rounded;
+        const mode = roundingMode ?? "halfExpand";
+        switch (mode) {
+            case "ceil":
+            case "expand":
+                rounded =
+                    Temporal.PlainDate.compare(source, startOfCurrent) > 0
+                        ? startOfNext
+                        : startOfCurrent;
+                break;
+            case "floor":
+            case "trunc":
+                rounded = startOfCurrent;
+                break;
+            case "halfExpand":
+            case "halfCeil":
+                rounded = fraction >= 0.5 ? startOfNext : startOfCurrent;
+                break;
+            case "halfTrunc":
+            case "halfFloor":
+                rounded = fraction > 0.5 ? startOfNext : startOfCurrent;
+                break;
+            case "halfEven":
+                // Simplified: use halfExpand behavior
+                rounded = fraction >= 0.5 ? startOfNext : startOfCurrent;
+                break;
+            default:
+                rounded = startOfCurrent;
+        }
+        return rounded.toString();
+    }
+    catch {
+        return "";
+    }
+}

package/dist/plain/calculate/roundDateTime.d.ts

@@ -0,0 +1,26 @@
+import { Temporal } from "@js-temporal/polyfill";
+import type { DateTimeUnit } from "../../types/index.js";
+/**
+ * Round an ISO 8601 datetime string to the specified date-time unit.
+ *
+ * - Returns "" for invalid inputs.
+ * - Accepts all date and time units: "year", "month", "week", "day", "hour", "minute", "second", "millisecond", "microsecond", "nanosecond".
+ * - Time units use Temporal.PlainDateTime.round() directly.
+ * - Date units (year, month, week) use manual start-of-unit rounding.
+ * - Wraps all Temporal calls in try-catch; returns "" on any error.
+ *
+ * @param value ISO 8601 datetime string
+ * @param options Rounding options: smallestUnit, optional roundingIncrement and roundingMode
+ * @returns Rounded ISO 8601 datetime string, or "" on invalid input
+ *
+ * @example roundDateTime("2024-06-15T12:34:56", { smallestUnit: "year" }) // "2024-01-01T00:00:00"
+ * @example roundDateTime("2024-06-15T12:34:56", { smallestUnit: "month" }) // "2024-07-01T00:00:00"
+ * @example roundDateTime("2024-06-15T12:34:56", { smallestUnit: "day" }) // "2024-06-16T00:00:00"
+ * @example roundDateTime("2024-06-15T12:34:56", { smallestUnit: "hour" }) // "2024-06-15T13:00:00"
+ * @example roundDateTime("invalid", { smallestUnit: "year" }) // ""
+ */
+export declare function roundDateTime(value: string, options: {
+    smallestUnit: DateTimeUnit;
+    roundingIncrement?: number;
+    roundingMode?: Temporal.RoundingMode;
+}): string;

package/dist/plain/calculate/roundDateTime.js

@@ -0,0 +1,98 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { addDateTimeUnit, getStartOfDateTimeUnit, } from "../../internal/dateTimeUnitHelpers.js";
+import { isValidDateTime, isValidDateTimeUnit } from "../validate/index.js";
+/**
+ * Round an ISO 8601 datetime string to the specified date-time unit.
+ *
+ * - Returns "" for invalid inputs.
+ * - Accepts all date and time units: "year", "month", "week", "day", "hour", "minute", "second", "millisecond", "microsecond", "nanosecond".
+ * - Time units use Temporal.PlainDateTime.round() directly.
+ * - Date units (year, month, week) use manual start-of-unit rounding.
+ * - Wraps all Temporal calls in try-catch; returns "" on any error.
+ *
+ * @param value ISO 8601 datetime string
+ * @param options Rounding options: smallestUnit, optional roundingIncrement and roundingMode
+ * @returns Rounded ISO 8601 datetime string, or "" on invalid input
+ *
+ * @example roundDateTime("2024-06-15T12:34:56", { smallestUnit: "year" }) // "2024-01-01T00:00:00"
+ * @example roundDateTime("2024-06-15T12:34:56", { smallestUnit: "month" }) // "2024-07-01T00:00:00"
+ * @example roundDateTime("2024-06-15T12:34:56", { smallestUnit: "day" }) // "2024-06-16T00:00:00"
+ * @example roundDateTime("2024-06-15T12:34:56", { smallestUnit: "hour" }) // "2024-06-15T13:00:00"
+ * @example roundDateTime("invalid", { smallestUnit: "year" }) // ""
+ */
+export function roundDateTime(value, options) {
+    const { smallestUnit, roundingIncrement, roundingMode } = options;
+    if (!isValidDateTime(value) || !isValidDateTimeUnit(smallestUnit))
+        return "";
+    try {
+        const source = Temporal.PlainDateTime.from(value);
+        // PlainDateTime.round() in this polyfill supports day and time units
+        const timeUnits = [
+            "day",
+            "hour",
+            "minute",
+            "second",
+            "millisecond",
+            "microsecond",
+            "nanosecond",
+        ];
+        if (timeUnits.includes(smallestUnit)) {
+            const timeUnit = smallestUnit;
+            const result = source.round({
+                smallestUnit: timeUnit,
+                roundingIncrement,
+                roundingMode,
+            });
+            // Handle default precision: 0 for > sec, 3 for ms, 6 for µs, 9 for ns
+            const precisionMap = {
+                millisecond: 3,
+                microsecond: 6,
+                nanosecond: 9,
+            };
+            const fractionalDigits = precisionMap[smallestUnit] || 0;
+            return result.toString({ fractionalSecondDigits: fractionalDigits });
+        }
+        // Manual rounding for date units (year, month, week)
+        const startOfCurrent = getStartOfDateTimeUnit(source, smallestUnit);
+        const increment = roundingIncrement ?? 1;
+        if (increment <= 0)
+            return "";
+        const startOfNext = addDateTimeUnit(startOfCurrent, smallestUnit, increment);
+        const elapsed = source.since(startOfCurrent);
+        const total = startOfNext.since(startOfCurrent);
+        const fraction = elapsed.total("milliseconds") / total.total("milliseconds");
+        let rounded;
+        const mode = roundingMode ?? "halfExpand";
+        switch (mode) {
+            case "ceil":
+            case "expand":
+                rounded =
+                    Temporal.PlainDateTime.compare(source, startOfCurrent) > 0
+                        ? startOfNext
+                        : startOfCurrent;
+                break;
+            case "floor":
+            case "trunc":
+                rounded = startOfCurrent;
+                break;
+            case "halfExpand":
+            case "halfCeil":
+                rounded = fraction >= 0.5 ? startOfNext : startOfCurrent;
+                break;
+            case "halfTrunc":
+            case "halfFloor":
+                rounded = fraction > 0.5 ? startOfNext : startOfCurrent;
+                break;
+            case "halfEven":
+                // Simplified: use halfExpand behavior
+                rounded = fraction >= 0.5 ? startOfNext : startOfCurrent;
+                break;
+            default:
+                rounded = startOfCurrent;
+        }
+        return rounded.toString();
+    }
+    catch {
+        return "";
+    }
+}

package/dist/plain/calculate/roundTime.d.ts

@@ -0,0 +1,22 @@
+import { Temporal } from "@js-temporal/polyfill";
+/**
+ * Round an ISO 8601 time string to the specified time unit.
+ *
+ * - Returns "" for invalid inputs.
+ * - Only time units are accepted: "hour", "minute", "second", "millisecond", "microsecond", "nanosecond".
+ * - Wraps Temporal.PlainTime.round() which throws on invalid options.
+ *
+ * @param value ISO 8601 time string
+ * @param options Rounding options: smallestUnit, optional roundingIncrement and roundingMode
+ * @returns Rounded ISO 8601 time string, or "" on invalid input
+ *
+ * @example roundTime("12:34:56", { smallestUnit: "hour" }) // "13:00:00"
+ * @example roundTime("12:34:56", { smallestUnit: "minute" }) // "12:35:00"
+ * @example roundTime("12:34:56", { smallestUnit: "second", roundingMode: "floor" }) // "12:34:56"
+ * @example roundTime("invalid", { smallestUnit: "hour" }) // ""
+ */
+export declare function roundTime(value: string, options: {
+    smallestUnit: Temporal.SmallestUnit<"hour">;
+    roundingIncrement?: number;
+    roundingMode?: Temporal.RoundingMode;
+}): string;

package/dist/plain/calculate/roundTime.js

@@ -0,0 +1,42 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { isValidTime, isValidTimeUnit } from "../validate/index.js";
+/**
+ * Round an ISO 8601 time string to the specified time unit.
+ *
+ * - Returns "" for invalid inputs.
+ * - Only time units are accepted: "hour", "minute", "second", "millisecond", "microsecond", "nanosecond".
+ * - Wraps Temporal.PlainTime.round() which throws on invalid options.
+ *
+ * @param value ISO 8601 time string
+ * @param options Rounding options: smallestUnit, optional roundingIncrement and roundingMode
+ * @returns Rounded ISO 8601 time string, or "" on invalid input
+ *
+ * @example roundTime("12:34:56", { smallestUnit: "hour" }) // "13:00:00"
+ * @example roundTime("12:34:56", { smallestUnit: "minute" }) // "12:35:00"
+ * @example roundTime("12:34:56", { smallestUnit: "second", roundingMode: "floor" }) // "12:34:56"
+ * @example roundTime("invalid", { smallestUnit: "hour" }) // ""
+ */
+export function roundTime(value, options) {
+    const { smallestUnit, roundingIncrement, roundingMode } = options;
+    if (!isValidTime(value) || !isValidTimeUnit(smallestUnit))
+        return "";
+    try {
+        const source = Temporal.PlainTime.from(value);
+        const result = source.round({
+            smallestUnit,
+            roundingIncrement,
+            roundingMode,
+        });
+        // Handle default precision: 0 for > sec, 3 for ms, 6 for µs, 9 for ns
+        const precisionMap = {
+            millisecond: 3,
+            microsecond: 6,
+            nanosecond: 9,
+        };
+        const fractionalDigits = precisionMap[smallestUnit] || 0;
+        return result.toString({ fractionalSecondDigits: fractionalDigits });
+    }
+    catch {
+        return "";
+    }
+}

package/dist/plain/calculate/setDate.d.ts

@@ -0,0 +1,32 @@
+import { Temporal } from "@js-temporal/polyfill";
+import type { Overflow } from "../../types/index.js";
+/**
+ * Return a PlainDate ISO string with the given `fields` set on `value`.
+ *
+ * - Wraps `Temporal.PlainDate.prototype.with()`, which resolves every supplied field in a
+ *   single atomic overflow pass. This is the safe alternative to composing `addDate()` calls
+ *   field-by-field: each sequential `.add()` resolves overflow against its own intermediate
+ *   value, so setting month-then-day vs. day-then-month on the same target can silently
+ *   diverge — `.with()` has no such order-dependence.
+ * - `fields` may set `year`, `month`, `monthCode`, `day`, `era`, and/or `eraYear`; omitted
+ *   fields keep their current value. An empty object is a no-op.
+ * - Returns "" for invalid input.
+ *
+ * `overflow` ("constrain" (default) | "reject") controls out-of-range results, e.g. setting
+ * `month: 2` on a date whose `day` is 31: "constrain" clamps to Feb 29/28, "reject" throws
+ * (resulting in "").
+ *
+ * @param value ISO PlainDate string
+ * @param fields Partial<Temporal.PlainDateLike> object specifying fields to set
+ * @param options optional: overflow ("constrain" | "reject")
+ * @returns ISO PlainDate string with fields set, or "" on invalid input
+ *
+ * @example setDate("2024-03-10", { year: 2025 }) // "2025-03-10"
+ * @example setDate("2024-01-31", { month: 2 }) // "2024-02-29" (constrain clamps to the last valid day)
+ * @example setDate("2024-01-31", { month: 2 }, { overflow: "reject" }) // ""
+ * @example setDate("2024-03-10", {}) // "2024-03-10" (empty fields object is a no-op)
+ * @example setDate("invalid", { year: 2025 }) // ""
+ */
+export declare function setDate(value: string, fields: Omit<Temporal.PlainDateLike, "calendar">, options?: {
+    overflow?: Overflow;
+}): string;

package/dist/plain/calculate/setDate.js

@@ -0,0 +1,47 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { resolveOverflow } from "../../internal/index.js";
+import { isValidDate } from "../validate/index.js";
+/**
+ * Return a PlainDate ISO string with the given `fields` set on `value`.
+ *
+ * - Wraps `Temporal.PlainDate.prototype.with()`, which resolves every supplied field in a
+ *   single atomic overflow pass. This is the safe alternative to composing `addDate()` calls
+ *   field-by-field: each sequential `.add()` resolves overflow against its own intermediate
+ *   value, so setting month-then-day vs. day-then-month on the same target can silently
+ *   diverge — `.with()` has no such order-dependence.
+ * - `fields` may set `year`, `month`, `monthCode`, `day`, `era`, and/or `eraYear`; omitted
+ *   fields keep their current value. An empty object is a no-op.
+ * - Returns "" for invalid input.
+ *
+ * `overflow` ("constrain" (default) | "reject") controls out-of-range results, e.g. setting
+ * `month: 2` on a date whose `day` is 31: "constrain" clamps to Feb 29/28, "reject" throws
+ * (resulting in "").
+ *
+ * @param value ISO PlainDate string
+ * @param fields Partial<Temporal.PlainDateLike> object specifying fields to set
+ * @param options optional: overflow ("constrain" | "reject")
+ * @returns ISO PlainDate string with fields set, or "" on invalid input
+ *
+ * @example setDate("2024-03-10", { year: 2025 }) // "2025-03-10"
+ * @example setDate("2024-01-31", { month: 2 }) // "2024-02-29" (constrain clamps to the last valid day)
+ * @example setDate("2024-01-31", { month: 2 }, { overflow: "reject" }) // ""
+ * @example setDate("2024-03-10", {}) // "2024-03-10" (empty fields object is a no-op)
+ * @example setDate("invalid", { year: 2025 }) // ""
+ */
+export function setDate(value, fields, options) {
+    if (!isValidDate(value))
+        return "";
+    try {
+        const date = Temporal.PlainDate.from(value);
+        // Temporal.PlainDate.prototype.with() throws on an empty fields object ("no supported
+        // properties found") rather than treating it as a no-op, so short-circuit here.
+        if (Object.keys(fields).length === 0)
+            return date.toString();
+        return date
+            .with(fields, { overflow: resolveOverflow(options?.overflow) })
+            .toString();
+    }
+    catch {
+        return "";
+    }
+}

package/dist/plain/calculate/setDateTime.d.ts

@@ -0,0 +1,31 @@
+import { Temporal } from "@js-temporal/polyfill";
+import type { Overflow } from "../../types/index.js";
+/**
+ * Return a PlainDateTime ISO string with the given `fields` set on `value`.
+ *
+ * - Wraps `Temporal.PlainDateTime.prototype.with()`, which resolves every supplied field in a
+ *   single atomic overflow pass — see `setDate`'s doc for why that matters over composing
+ *   `addDateTime()` calls field-by-field.
+ * - `fields` may set any of `year`, `month`, `monthCode`, `day`, `hour`, `minute`, `second`,
+ *   `millisecond`, `microsecond`, `nanosecond`, `era`, and/or `eraYear`; omitted fields keep
+ *   their current value. An empty object is a no-op.
+ * - Returns "" for invalid input.
+ *
+ * `overflow` ("constrain" (default) | "reject") controls out-of-range results, e.g. setting
+ * `month: 2` on a datetime whose `day` is 31: "constrain" clamps to Feb 29/28, "reject" throws
+ * (resulting in "").
+ *
+ * @param value ISO PlainDateTime string
+ * @param fields Partial<Temporal.PlainDateTimeLike> object specifying fields to set
+ * @param options optional: overflow ("constrain" | "reject")
+ * @returns ISO PlainDateTime string with fields set, or "" on invalid input
+ *
+ * @example setDateTime("2024-03-10T12:00:00", { hour: 9 }) // "2024-03-10T09:00:00"
+ * @example setDateTime("2024-01-31T12:00:00", { month: 2 }) // "2024-02-29T12:00:00" (constrain clamps to the last valid day)
+ * @example setDateTime("2024-01-31T12:00:00", { month: 2 }, { overflow: "reject" }) // ""
+ * @example setDateTime("2024-03-10T12:00:00", {}) // "2024-03-10T12:00:00" (empty fields object is a no-op)
+ * @example setDateTime("invalid", { hour: 9 }) // ""
+ */
+export declare function setDateTime(value: string, fields: Omit<Temporal.PlainDateTimeLike, "calendar">, options?: {
+    overflow?: Overflow;
+}): string;

package/dist/plain/calculate/setDateTime.js

@@ -0,0 +1,46 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { resolveOverflow } from "../../internal/index.js";
+import { isValidDateTime } from "../validate/index.js";
+/**
+ * Return a PlainDateTime ISO string with the given `fields` set on `value`.
+ *
+ * - Wraps `Temporal.PlainDateTime.prototype.with()`, which resolves every supplied field in a
+ *   single atomic overflow pass — see `setDate`'s doc for why that matters over composing
+ *   `addDateTime()` calls field-by-field.
+ * - `fields` may set any of `year`, `month`, `monthCode`, `day`, `hour`, `minute`, `second`,
+ *   `millisecond`, `microsecond`, `nanosecond`, `era`, and/or `eraYear`; omitted fields keep
+ *   their current value. An empty object is a no-op.
+ * - Returns "" for invalid input.
+ *
+ * `overflow` ("constrain" (default) | "reject") controls out-of-range results, e.g. setting
+ * `month: 2` on a datetime whose `day` is 31: "constrain" clamps to Feb 29/28, "reject" throws
+ * (resulting in "").
+ *
+ * @param value ISO PlainDateTime string
+ * @param fields Partial<Temporal.PlainDateTimeLike> object specifying fields to set
+ * @param options optional: overflow ("constrain" | "reject")
+ * @returns ISO PlainDateTime string with fields set, or "" on invalid input
+ *
+ * @example setDateTime("2024-03-10T12:00:00", { hour: 9 }) // "2024-03-10T09:00:00"
+ * @example setDateTime("2024-01-31T12:00:00", { month: 2 }) // "2024-02-29T12:00:00" (constrain clamps to the last valid day)
+ * @example setDateTime("2024-01-31T12:00:00", { month: 2 }, { overflow: "reject" }) // ""
+ * @example setDateTime("2024-03-10T12:00:00", {}) // "2024-03-10T12:00:00" (empty fields object is a no-op)
+ * @example setDateTime("invalid", { hour: 9 }) // ""
+ */
+export function setDateTime(value, fields, options) {
+    if (!isValidDateTime(value))
+        return "";
+    try {
+        const dateTime = Temporal.PlainDateTime.from(value);
+        // Temporal.PlainDateTime.prototype.with() throws on an empty fields object ("no supported
+        // properties found") rather than treating it as a no-op, so short-circuit here.
+        if (Object.keys(fields).length === 0)
+            return dateTime.toString();
+        return dateTime
+            .with(fields, { overflow: resolveOverflow(options?.overflow) })
+            .toString();
+    }
+    catch {
+        return "";
+    }
+}

package/dist/plain/calculate/setTime.d.ts

@@ -0,0 +1,31 @@
+import { Temporal } from "@js-temporal/polyfill";
+import type { Overflow } from "../../types/index.js";
+/**
+ * Return a PlainTime ISO string with the given `fields` set on `value`.
+ *
+ * - Wraps `Temporal.PlainTime.prototype.with()`, which resolves every supplied field in a
+ *   single atomic overflow pass — see `setDate`'s doc for why that matters over composing
+ *   `addTime()` calls field-by-field.
+ * - `fields` may set any of `hour`, `minute`, `second`, `millisecond`, `microsecond`, and/or
+ *   `nanosecond`; omitted fields keep their current value. An empty object is a no-op.
+ * - Returns "" for invalid input.
+ *
+ * `overflow` ("constrain" (default) | "reject") controls out-of-range field values, e.g.
+ * `hour: 25`: "constrain" clamps to 23, "reject" throws (resulting in ""). Unlike `addTime`
+ * (where `overflow` is inert because addition always wraps around the clock), `overflow` has
+ * a real effect here because `.with()` assigns fixed field values rather than adding a delta.
+ *
+ * @param value ISO PlainTime string
+ * @param fields Partial<Temporal.PlainTimeLike> object specifying fields to set
+ * @param options optional: overflow ("constrain" | "reject")
+ * @returns ISO PlainTime string with fields set, or "" on invalid input
+ *
+ * @example setTime("12:00:00", { hour: 9 }) // "09:00:00"
+ * @example setTime("12:00:00", { hour: 25 }) // "23:00:00" (constrain clamps to the max valid hour)
+ * @example setTime("12:00:00", { hour: 25 }, { overflow: "reject" }) // ""
+ * @example setTime("12:00:00", {}) // "12:00:00" (empty fields object is a no-op)
+ * @example setTime("invalid", { hour: 9 }) // ""
+ */
+export declare function setTime(value: string, fields: Temporal.PlainTimeLike, options?: {
+    overflow?: Overflow;
+}): string;