@northguild/gmt 1.14.2

package/dist/plain/calculate/setTime.js

@@ -0,0 +1,46 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { resolveOverflow } from "../../internal/index.js";
+import { isValidTime } from "../validate/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 function setTime(value, fields, options) {
+    if (!isValidTime(value))
+        return "";
+    try {
+        const time = Temporal.PlainTime.from(value);
+        // Temporal.PlainTime.prototype.with() throws on an empty fields object ("invalid time-like")
+        // rather than treating it as a no-op, so short-circuit here.
+        if (Object.keys(fields).length === 0)
+            return time.toString();
+        return time
+            .with(fields, { overflow: resolveOverflow(options?.overflow) })
+            .toString();
+    }
+    catch {
+        return "";
+    }
+}

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

@@ -0,0 +1,14 @@
+/**
+ * Sort an array of PlainDateTime values in ascending or descending order.
+ *
+ * - Returns empty array if no valid datetimes.
+ * - Validation is performed on each item in the array.
+ *
+ * @param dateTimes Array of ISO PlainDateTime strings (e.g. "2024-03-10T12:00:00")
+ * @param order "asc" for ascending (earliest first) | "desc" for descending (latest first)
+ * @returns Sorted array of datetime strings
+ *
+ * @example sortDateTimes(["2024-03-10T12:00:00", "2024-01-01T08:00:00", "2024-02-15T15:30:00"]) // ["2024-01-01T08:00:00", "2024-02-15T15:30:00", "2024-03-10T12:00:00"]
+ * @example sortDateTimes([]) // []
+ */
+export declare function sortDateTimes(dateTimes: string[], order?: "asc" | "desc"): string[];

package/dist/plain/calculate/sortDateTimes.js

@@ -0,0 +1,33 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { isValidDateTime } from "../validate/index.js";
+/**
+ * Sort an array of PlainDateTime values in ascending or descending order.
+ *
+ * - Returns empty array if no valid datetimes.
+ * - Validation is performed on each item in the array.
+ *
+ * @param dateTimes Array of ISO PlainDateTime strings (e.g. "2024-03-10T12:00:00")
+ * @param order "asc" for ascending (earliest first) | "desc" for descending (latest first)
+ * @returns Sorted array of datetime strings
+ *
+ * @example sortDateTimes(["2024-03-10T12:00:00", "2024-01-01T08:00:00", "2024-02-15T15:30:00"]) // ["2024-01-01T08:00:00", "2024-02-15T15:30:00", "2024-03-10T12:00:00"]
+ * @example sortDateTimes([]) // []
+ */
+export function sortDateTimes(dateTimes, order = "asc") {
+    if (!dateTimes.length)
+        return [];
+    const valid = dateTimes.filter(isValidDateTime);
+    if (!valid.length)
+        return [];
+    try {
+        const comparables = valid.map((d) => Temporal.PlainDateTime.from(d));
+        comparables.sort(Temporal.PlainDateTime.compare);
+        if (order === "desc") {
+            return comparables.reverse().map((d) => d.toString());
+        }
+        return comparables.map((d) => d.toString());
+    }
+    catch {
+        return [];
+    }
+}

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

@@ -0,0 +1,14 @@
+/**
+ * Sort an array of PlainDate values in ascending or descending order.
+ *
+ * - Returns empty array if no valid dates.
+ * - Validation is performed on each item in the array.
+ *
+ * @param dates Array of ISO PlainDate strings (e.g. "2024-03-10")
+ * @param order "asc" for ascending (earliest first) | "desc" for descending (latest first)
+ * @returns Sorted array of date strings
+ *
+ * @example sortDates(["2024-03-10", "2024-01-01", "2024-02-15"]) // ["2024-01-01", "2024-02-15", "2024-03-10"]
+ * @example sortDates([]) // []
+ */
+export declare function sortDates(dates: string[], order?: "asc" | "desc"): string[];

package/dist/plain/calculate/sortDates.js

@@ -0,0 +1,33 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { isValidDate } from "../validate/index.js";
+/**
+ * Sort an array of PlainDate values in ascending or descending order.
+ *
+ * - Returns empty array if no valid dates.
+ * - Validation is performed on each item in the array.
+ *
+ * @param dates Array of ISO PlainDate strings (e.g. "2024-03-10")
+ * @param order "asc" for ascending (earliest first) | "desc" for descending (latest first)
+ * @returns Sorted array of date strings
+ *
+ * @example sortDates(["2024-03-10", "2024-01-01", "2024-02-15"]) // ["2024-01-01", "2024-02-15", "2024-03-10"]
+ * @example sortDates([]) // []
+ */
+export function sortDates(dates, order = "asc") {
+    if (!dates.length)
+        return [];
+    const valid = dates.filter(isValidDate);
+    if (!valid.length)
+        return [];
+    try {
+        const comparables = valid.map((d) => Temporal.PlainDate.from(d));
+        comparables.sort(Temporal.PlainDate.compare);
+        if (order === "desc") {
+            return comparables.reverse().map((d) => d.toString());
+        }
+        return comparables.map((d) => d.toString());
+    }
+    catch {
+        return [];
+    }
+}

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

@@ -0,0 +1,14 @@
+/**
+ * Sort an array of PlainTime values in ascending or descending order.
+ *
+ * - Returns empty array if no valid times.
+ * - Validation is performed on each item in the array.
+ *
+ * @param times Array of ISO PlainTime strings (e.g. "14:30:00")
+ * @param order "asc" for ascending (earliest first) | "desc" for descending (latest first)
+ * @returns Sorted array of time strings
+ *
+ * @example sortTimes(["14:30:00", "09:00:00", "20:45:00"]) // ["09:00:00", "14:30:00", "20:45:00"]
+ * @example sortTimes([]) // []
+ */
+export declare function sortTimes(times: string[], order?: "asc" | "desc"): string[];

package/dist/plain/calculate/sortTimes.js

@@ -0,0 +1,33 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { isValidTime } from "../validate/index.js";
+/**
+ * Sort an array of PlainTime values in ascending or descending order.
+ *
+ * - Returns empty array if no valid times.
+ * - Validation is performed on each item in the array.
+ *
+ * @param times Array of ISO PlainTime strings (e.g. "14:30:00")
+ * @param order "asc" for ascending (earliest first) | "desc" for descending (latest first)
+ * @returns Sorted array of time strings
+ *
+ * @example sortTimes(["14:30:00", "09:00:00", "20:45:00"]) // ["09:00:00", "14:30:00", "20:45:00"]
+ * @example sortTimes([]) // []
+ */
+export function sortTimes(times, order = "asc") {
+    if (!times.length)
+        return [];
+    const valid = times.filter(isValidTime);
+    if (!valid.length)
+        return [];
+    try {
+        const comparables = valid.map((t) => Temporal.PlainTime.from(t));
+        comparables.sort(Temporal.PlainTime.compare);
+        if (order === "desc") {
+            return comparables.reverse().map((t) => t.toString());
+        }
+        return comparables.map((t) => t.toString());
+    }
+    catch {
+        return [];
+    }
+}

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

@@ -0,0 +1,17 @@
+import { Temporal } from "@js-temporal/polyfill";
+/**
+ * Return the start of the specified date `unit` for a given ISO 8601 date string.
+ *
+ * - Returns "" for invalid inputs.
+ *
+ * @param value ISO 8601 date string
+ * @param unit Temporal.DateUnit to specify the unit for the start
+ * @param optionsArg optional: weekStartsOn ("monday" | "sunday")
+ * @returns ISO 8601 string representing the start of the specified unit, or "" on invalid input
+ *
+ * @example startOfDate("2024-02-29", "month") // "2024-02-01"
+ * @example startOfDate("invalid-date", "month") // ""
+ */
+export declare function startOfDate(value: string, unit: Temporal.DateUnit, optionsArg?: {
+    weekStartsOn?: "monday" | "sunday";
+}): string;

package/dist/plain/calculate/startOfDate.js

@@ -0,0 +1,50 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { isValidDate } from "../validate/index.js";
+const supported = ["year", "month", "week"];
+/**
+ * Return the start of the specified date `unit` for a given ISO 8601 date string.
+ *
+ * - Returns "" for invalid inputs.
+ *
+ * @param value ISO 8601 date string
+ * @param unit Temporal.DateUnit to specify the unit for the start
+ * @param optionsArg optional: weekStartsOn ("monday" | "sunday")
+ * @returns ISO 8601 string representing the start of the specified unit, or "" on invalid input
+ *
+ * @example startOfDate("2024-02-29", "month") // "2024-02-01"
+ * @example startOfDate("invalid-date", "month") // ""
+ */
+export function startOfDate(value, unit, optionsArg) {
+    const weekStartsOn = optionsArg?.weekStartsOn ?? "monday";
+    if (!isValidDate(value) || !supported.includes(unit))
+        return "";
+    try {
+        const source = Temporal.PlainDate.from(value);
+        let result;
+        switch (unit) {
+            case "year":
+                result = source.with({ month: 1, day: 1 });
+                break;
+            case "month":
+                result = source.with({ day: 1 });
+                break;
+            case "week": {
+                // Week start: compute how many days to subtract to reach Monday.
+                // Temporal: 1 (Mon) to 7 (Sun)
+                // If Monday start: Monday(1) subtracts 0, Sunday(7) subtracts 6.
+                // If Sunday start: Sunday(7) subtracts 0, Monday(1) subtracts 1.
+                const daysToSubtract = weekStartsOn === "monday"
+                    ? source.dayOfWeek - 1
+                    : source.dayOfWeek % 7;
+                result = source.subtract({ days: daysToSubtract });
+                break;
+            }
+            default:
+                return "";
+        }
+        return result.toString();
+    }
+    catch {
+        return "";
+    }
+}

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

@@ -0,0 +1,19 @@
+import { Temporal } from "@js-temporal/polyfill";
+import type { FractionalDigit } from "../../types/index.js";
+/**
+ * Return the start of the specified date-time `unit` for a given ISO 8601 datetime string.
+ *
+ * - Returns "" for invalid inputs.
+ *
+ * @param value ISO 8601 datetime string
+ * @param unit Temporal.DateUnit|Temporal.TimeUnit to specify the unit for the start
+ * @param optionsArg optional: weekStartsOn ("monday" | "sunday"), fractionalSecondDigits (number)
+ * @returns ISO 8601 string representing the start of the specified unit, or "" on invalid input
+ *
+ * @example startOfDateTime("2024-02-29T12:34:56", "month") // "2024-02-01T00:00:00"
+ * @example startOfDateTime("invalid-datetime", "month") // ""
+ */
+export declare function startOfDateTime(value: string, unit: Temporal.DateUnit | Temporal.TimeUnit, optionsArg?: {
+    weekStartsOn?: "monday" | "sunday";
+    fractionalSecondDigits?: FractionalDigit;
+}): string;

package/dist/plain/calculate/startOfDateTime.js

@@ -0,0 +1,85 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { isValidDateTime, isValidDateTimeUnit } from "../validate/index.js";
+/**
+ * Return the start of the specified date-time `unit` for a given ISO 8601 datetime string.
+ *
+ * - Returns "" for invalid inputs.
+ *
+ * @param value ISO 8601 datetime string
+ * @param unit Temporal.DateUnit|Temporal.TimeUnit to specify the unit for the start
+ * @param optionsArg optional: weekStartsOn ("monday" | "sunday"), fractionalSecondDigits (number)
+ * @returns ISO 8601 string representing the start of the specified unit, or "" on invalid input
+ *
+ * @example startOfDateTime("2024-02-29T12:34:56", "month") // "2024-02-01T00:00:00"
+ * @example startOfDateTime("invalid-datetime", "month") // ""
+ */
+export function startOfDateTime(value, unit, optionsArg) {
+    const weekStartsOn = optionsArg?.weekStartsOn ?? "monday";
+    const fractionalSecondDigits = optionsArg?.fractionalSecondDigits;
+    if (!isValidDateTime(value) || !isValidDateTimeUnit(unit))
+        return "";
+    try {
+        const source = Temporal.PlainDateTime.from(value);
+        let result;
+        switch (unit) {
+            case "year":
+                result = source.with({ month: 1, day: 1 }).withPlainTime();
+                break;
+            case "month":
+                result = source.with({ day: 1 }).withPlainTime();
+                break;
+            case "week": {
+                const daysToSubtract = weekStartsOn === "monday"
+                    ? source.dayOfWeek - 1
+                    : source.dayOfWeek % 7;
+                result = source.subtract({ days: daysToSubtract }).withPlainTime();
+                break;
+            }
+            case "day":
+                result = source.withPlainTime();
+                break;
+            case "hour":
+                result = source.with({
+                    minute: 0,
+                    second: 0,
+                    millisecond: 0,
+                    microsecond: 0,
+                    nanosecond: 0,
+                });
+                break;
+            case "minute":
+                result = source.with({
+                    second: 0,
+                    millisecond: 0,
+                    microsecond: 0,
+                    nanosecond: 0,
+                });
+                break;
+            case "second":
+                result = source.with({ millisecond: 0, microsecond: 0, nanosecond: 0 });
+                break;
+            case "millisecond":
+                result = source.with({ microsecond: 0, nanosecond: 0 });
+                break;
+            case "microsecond":
+                result = source.with({ nanosecond: 0 });
+                break;
+            case "nanosecond":
+                result = source; // Smallest unit, nothing to reset
+                break;
+            default:
+                return "";
+        }
+        // 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 = fractionalSecondDigits ?? (precisionMap[unit] || 0);
+        return result.toString({ fractionalSecondDigits: fractionalDigits });
+    }
+    catch {
+        return "";
+    }
+}

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

@@ -0,0 +1,17 @@
+/**
+ * Return the first day of the quarter for a given ISO date.
+ *
+ * - Returns the first day (month and day set to 1) of the quarter containing the input date.
+ * - Q1 returns "01-01", Q2 returns "04-01", Q3 returns "07-01", Q4 returns "10-01".
+ * - Validates input using isValidDate.
+ *
+ * @param value ISO PlainDate string
+ * @returns ISO PlainDate string for the first day of the quarter, or "" on invalid input
+ *
+ * @example startOfQuarterForDate("2024-03-15") // "2024-01-01"
+ * @example startOfQuarterForDate("2024-06-15") // "2024-04-01"
+ * @example startOfQuarterForDate("2024-09-15") // "2024-07-01"
+ * @example startOfQuarterForDate("2024-12-15") // "2024-10-01"
+ * @example startOfQuarterForDate("invalid") // ""
+ */
+export declare function startOfQuarterForDate(value: string): string;

package/dist/plain/calculate/startOfQuarterForDate.js

@@ -0,0 +1,32 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { isValidDate } from "../validate/index.js";
+/**
+ * Return the first day of the quarter for a given ISO date.
+ *
+ * - Returns the first day (month and day set to 1) of the quarter containing the input date.
+ * - Q1 returns "01-01", Q2 returns "04-01", Q3 returns "07-01", Q4 returns "10-01".
+ * - Validates input using isValidDate.
+ *
+ * @param value ISO PlainDate string
+ * @returns ISO PlainDate string for the first day of the quarter, or "" on invalid input
+ *
+ * @example startOfQuarterForDate("2024-03-15") // "2024-01-01"
+ * @example startOfQuarterForDate("2024-06-15") // "2024-04-01"
+ * @example startOfQuarterForDate("2024-09-15") // "2024-07-01"
+ * @example startOfQuarterForDate("2024-12-15") // "2024-10-01"
+ * @example startOfQuarterForDate("invalid") // ""
+ */
+export function startOfQuarterForDate(value) {
+    if (!isValidDate(value)) {
+        return "";
+    }
+    try {
+        const date = Temporal.PlainDate.from(value);
+        const month = date.month;
+        const quarterStartMonth = Math.floor((month - 1) / 3) * 3 + 1;
+        return date.with({ month: quarterStartMonth, day: 1 }).toString();
+    }
+    catch {
+        return "";
+    }
+}

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

@@ -0,0 +1,15 @@
+/**
+ * Return the start of the quarter for a given ISO datetime.
+ *
+ * - Returns the first day of the quarter with time set to 00:00:00.
+ * - Q1 returns "01-01T00:00:00", Q2 returns "04-01T00:00:00", etc.
+ * - Validates input using isValidDateTime.
+ *
+ * @param value ISO PlainDateTime string
+ * @returns ISO PlainDateTime string for the start of the quarter, or "" on invalid input
+ *
+ * @example startOfQuarterForDateTime("2024-03-15T12:00:00") // "2024-01-01T00:00:00"
+ * @example startOfQuarterForDateTime("2024-06-15T12:00:00") // "2024-04-01T00:00:00"
+ * @example startOfQuarterForDateTime("invalid") // ""
+ */
+export declare function startOfQuarterForDateTime(value: string): string;

package/dist/plain/calculate/startOfQuarterForDateTime.js

@@ -0,0 +1,32 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { isValidDateTime } from "../validate/index.js";
+/**
+ * Return the start of the quarter for a given ISO datetime.
+ *
+ * - Returns the first day of the quarter with time set to 00:00:00.
+ * - Q1 returns "01-01T00:00:00", Q2 returns "04-01T00:00:00", etc.
+ * - Validates input using isValidDateTime.
+ *
+ * @param value ISO PlainDateTime string
+ * @returns ISO PlainDateTime string for the start of the quarter, or "" on invalid input
+ *
+ * @example startOfQuarterForDateTime("2024-03-15T12:00:00") // "2024-01-01T00:00:00"
+ * @example startOfQuarterForDateTime("2024-06-15T12:00:00") // "2024-04-01T00:00:00"
+ * @example startOfQuarterForDateTime("invalid") // ""
+ */
+export function startOfQuarterForDateTime(value) {
+    if (!isValidDateTime(value)) {
+        return "";
+    }
+    try {
+        const dateTime = Temporal.PlainDateTime.from(value);
+        const month = dateTime.month;
+        const quarterStartMonth = Math.floor((month - 1) / 3) * 3 + 1;
+        return dateTime
+            .with({ month: quarterStartMonth, day: 1, hour: 0, minute: 0, second: 0 })
+            .toString();
+    }
+    catch {
+        return "";
+    }
+}

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

@@ -0,0 +1,20 @@
+import { Temporal } from "@js-temporal/polyfill";
+import type { FractionalDigit } from "../../types/index.js";
+type StartOfTimeUnit = Temporal.TimeUnit | "day";
+/**
+ * Return the start of the specified time `unit` for a given ISO 8601 time string.
+ *
+ * - Returns "" for invalid inputs.
+ *
+ * @param value ISO 8601 time string
+ * @param unit StartOfTimeUnit to specify the unit for the start
+ * @param optionsArg optional: fractionalSecondDigits (number)
+ * @returns ISO 8601 string representing the start of the specified unit, or "" on invalid input
+ *
+ * @example startOfTime("12:34:56", "hour") // "12:00:00"
+ * @example startOfTime("invalid", "hour") // ""
+ */
+export declare function startOfTime(value: string, unit: StartOfTimeUnit, optionsArg?: {
+    fractionalSecondDigits?: FractionalDigit;
+}): string;
+export {};

package/dist/plain/calculate/startOfTime.js

@@ -0,0 +1,69 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { isValidTime } from "../validate/index.js";
+const supported = [
+    "day",
+    "hour",
+    "minute",
+    "second",
+    "millisecond",
+    "microsecond",
+    "nanosecond",
+];
+/**
+ * Return the start of the specified time `unit` for a given ISO 8601 time string.
+ *
+ * - Returns "" for invalid inputs.
+ *
+ * @param value ISO 8601 time string
+ * @param unit StartOfTimeUnit to specify the unit for the start
+ * @param optionsArg optional: fractionalSecondDigits (number)
+ * @returns ISO 8601 string representing the start of the specified unit, or "" on invalid input
+ *
+ * @example startOfTime("12:34:56", "hour") // "12:00:00"
+ * @example startOfTime("invalid", "hour") // ""
+ */
+export function startOfTime(value, unit, optionsArg) {
+    const fractionalSecondDigits = optionsArg?.fractionalSecondDigits;
+    if (!isValidTime(value) || !supported.includes(unit))
+        return "";
+    try {
+        const source = Temporal.PlainTime.from(value);
+        let result;
+        switch (unit) {
+            case "day":
+                result = source.with({ hour: 0, minute: 0, second: 0 });
+                break;
+            case "hour":
+                result = source.with({ minute: 0, second: 0 });
+                break;
+            case "minute":
+                result = source.with({ second: 0 });
+                break;
+            case "second":
+                result = source.with({ millisecond: 0, microsecond: 0, nanosecond: 0 });
+                break;
+            case "millisecond":
+                result = source.with({ millisecond: 0, microsecond: 0, nanosecond: 0 });
+                break;
+            case "microsecond":
+                result = source.with({ microsecond: 0, nanosecond: 0 });
+                break;
+            case "nanosecond":
+                result = source.with({ nanosecond: 0 });
+                break;
+            default:
+                return "";
+        }
+        // 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 = fractionalSecondDigits ?? (precisionMap[unit] || 0);
+        return result.toString({ fractionalSecondDigits: fractionalDigits });
+    }
+    catch {
+        return "";
+    }
+}

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

@@ -0,0 +1,18 @@
+/**
+ * Return a PlainDate ISO string with `amount` business days subtracted from `value`.
+ *
+ * - Uses fixed ISO Monday–Friday business days (no locale awareness).
+ * - Saturday and Sunday are skipped during the count.
+ * - Negative `amount` behaves identically to `addBusinessDays(value, Math.abs(amount))`.
+ * - Returns "" on invalid input.
+ *
+ * @param value ISO PlainDate string
+ * @param amount number of business days to subtract
+ * @returns ISO PlainDate string after subtracting business days, or "" on invalid input
+ *
+ * @example subtractBusinessDays("2024-03-18", 1) // "2024-03-15"
+ * @example subtractBusinessDays("2024-03-17", 1) // "2024-03-15"
+ * @example subtractBusinessDays("2024-03-18", 0) // "2024-03-18"
+ * @example subtractBusinessDays("invalid", 1) // ""
+ */
+export declare function subtractBusinessDays(value: string, amount: number): string;

package/dist/plain/calculate/subtractBusinessDays.js

@@ -0,0 +1,36 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { advanceBusinessDays, isValidAmount } from "../../internal/index.js";
+import { isValidDate } from "../validate/index.js";
+/**
+ * Return a PlainDate ISO string with `amount` business days subtracted from `value`.
+ *
+ * - Uses fixed ISO Monday–Friday business days (no locale awareness).
+ * - Saturday and Sunday are skipped during the count.
+ * - Negative `amount` behaves identically to `addBusinessDays(value, Math.abs(amount))`.
+ * - Returns "" on invalid input.
+ *
+ * @param value ISO PlainDate string
+ * @param amount number of business days to subtract
+ * @returns ISO PlainDate string after subtracting business days, or "" on invalid input
+ *
+ * @example subtractBusinessDays("2024-03-18", 1) // "2024-03-15"
+ * @example subtractBusinessDays("2024-03-17", 1) // "2024-03-15"
+ * @example subtractBusinessDays("2024-03-18", 0) // "2024-03-18"
+ * @example subtractBusinessDays("invalid", 1) // ""
+ */
+export function subtractBusinessDays(value, amount) {
+    if (!isValidDate(value) || !isValidAmount(amount)) {
+        return "";
+    }
+    if (amount === 0) {
+        return value;
+    }
+    try {
+        const date = Temporal.PlainDate.from(value);
+        const direction = amount > 0 ? -1 : 1;
+        return advanceBusinessDays(date, direction, Math.abs(amount)).toString();
+    }
+    catch {
+        return "";
+    }
+}

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

@@ -0,0 +1,27 @@
+import type { DateDurationUnit, Overflow } from "../../types/index.js";
+/**
+ * Return a PlainDate ISO string with `units` subtracted from `value`.
+ *
+ * - Validates `value`, `units`, and `amount` before performing the subtract.
+ * - Accepts a GMT calendar-annotated PlainDate string (as produced by `convertDateToCalendar`),
+ *   not just a bare ISO string — E5 (issue #78). See `addDate`'s JSDoc for the full calendar-unit
+ *   arithmetic rationale (leap months/years, era transitions, the `overflow` asymmetry); this
+ *   function is the mirror image (`.subtract` instead of `.add`).
+ * - Returns "" for invalid inputs.
+ *
+ * `overflow` ("constrain" (default) | "reject") controls out-of-range results, e.g. subtracting
+ * 1 month from Mar 31: "constrain" clamps to Feb 29/28, "reject" throws (resulting in "").
+ *
+ * @param value ISO PlainDate string, optionally calendar-annotated
+ * @param units Partial<Record<DateDurationUnit, number>> object specifying units to subtract
+ * @param options optional: overflow ("constrain" | "reject")
+ * @returns ISO PlainDate string after subtraction, or "" on invalid input
+ *
+ * @example subtractDate("2024-03-15", { day: 5 }) // "2024-03-10"
+ * @example subtractDate("invalid", { day: 5 }) // ""
+ * @example subtractDate("2024-03-31", { months: 1 }, { overflow: "reject" }) // ""
+ * @example subtractDate("5784-07-15[u-ca=hebrew]", { months: 1 }) // "5784-06-15[u-ca=hebrew]" (Adar -> Adar I)
+ */
+export declare function subtractDate(value: string, units: Partial<Record<DateDurationUnit, number>>, options?: {
+    overflow?: Overflow;
+}): string;