@northguild/gmt 1.14.2

package/dist/plain/parse/parseMonthFromDateTime.js

@@ -0,0 +1,25 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { isValidDateTime } from "../validate/index.js";
+/**
+ * Return the month (1-12) for a given ISO 8601 datetime string.
+ *
+ * - Returns zero-padded string for month.
+ * - Returns "" for invalid input.
+ *
+ * @param value ISO datetime string
+ * @returns Month (01-12) or "" on invalid input
+ *
+ * @example parseMonthFromDateTime("2024-03-15T12:30:00") // "03"
+ * @example parseMonthFromDateTime("invalid") // ""
+ */
+export function parseMonthFromDateTime(value) {
+    if (!isValidDateTime(value))
+        return "";
+    try {
+        const dateTime = Temporal.PlainDateTime.from(value);
+        return dateTime.month.toString().padStart(2, "0");
+    }
+    catch {
+        return "";
+    }
+}

package/dist/plain/parse/parseNanosecondFromDateTime.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Return the nanosecond (0-999) for a given ISO 8601 datetime string.
+ *
+ * - Returns zero-padded string for nanosecond.
+ * - Returns "" for invalid input.
+ *
+ * @param value ISO datetime string
+ * @returns Nanosecond (000-999) or "" on invalid input
+ *
+ * @example parseNanosecondFromDateTime("2024-03-15T14:30:45.123") // "123"
+ * @example parseNanosecondFromDateTime("2024-03-15T14:30:45.000") // "000"
+ * @example parseNanosecondFromDateTime("invalid") // ""
+ */
+export declare function parseNanosecondFromDateTime(value: string): string;

package/dist/plain/parse/parseNanosecondFromDateTime.js

@@ -0,0 +1,26 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { isValidDateTime } from "../validate/index.js";
+/**
+ * Return the nanosecond (0-999) for a given ISO 8601 datetime string.
+ *
+ * - Returns zero-padded string for nanosecond.
+ * - Returns "" for invalid input.
+ *
+ * @param value ISO datetime string
+ * @returns Nanosecond (000-999) or "" on invalid input
+ *
+ * @example parseNanosecondFromDateTime("2024-03-15T14:30:45.123") // "123"
+ * @example parseNanosecondFromDateTime("2024-03-15T14:30:45.000") // "000"
+ * @example parseNanosecondFromDateTime("invalid") // ""
+ */
+export function parseNanosecondFromDateTime(value) {
+    if (!isValidDateTime(value))
+        return "";
+    try {
+        const dateTime = Temporal.PlainDateTime.from(value);
+        return dateTime.nanosecond.toString().padStart(3, "0");
+    }
+    catch {
+        return "";
+    }
+}

package/dist/plain/parse/parseNanosecondFromTime.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Return the nanosecond (0-999) for a given ISO 8601 time string.
+ *
+ * - Returns zero-padded string for nanosecond.
+ * - Returns "" for invalid input.
+ *
+ * @param value ISO time string
+ * @returns Nanosecond (000-999) or "" on invalid input
+ *
+ * @example parseNanosecondFromTime("12:30:45.123") // "123"
+ * @example parseNanosecondFromTime("12:30:45.000") // "000"
+ * @example parseNanosecondFromTime("invalid") // ""
+ */
+export declare function parseNanosecondFromTime(value: string): string;

package/dist/plain/parse/parseNanosecondFromTime.js

@@ -0,0 +1,26 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { isValidTime } from "../validate/index.js";
+/**
+ * Return the nanosecond (0-999) for a given ISO 8601 time string.
+ *
+ * - Returns zero-padded string for nanosecond.
+ * - Returns "" for invalid input.
+ *
+ * @param value ISO time string
+ * @returns Nanosecond (000-999) or "" on invalid input
+ *
+ * @example parseNanosecondFromTime("12:30:45.123") // "123"
+ * @example parseNanosecondFromTime("12:30:45.000") // "000"
+ * @example parseNanosecondFromTime("invalid") // ""
+ */
+export function parseNanosecondFromTime(value) {
+    if (!isValidTime(value))
+        return "";
+    try {
+        const time = Temporal.PlainTime.from(value);
+        return time.nanosecond.toString().padStart(3, "0");
+    }
+    catch {
+        return "";
+    }
+}

package/dist/plain/parse/parseSecondFromDateTime.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Return the second (0-59) for a given ISO 8601 datetime string.
+ *
+ * - Returns zero-padded string for second.
+ * - Returns "" for invalid input.
+ *
+ * @param value ISO datetime string
+ * @returns Second (00-59) or "" on invalid input
+ *
+ * @example parseSecondFromDateTime("2024-03-15T14:30:45") // "45"
+ * @example parseSecondFromDateTime("2024-03-15T14:30:00") // "00"
+ * @example parseSecondFromDateTime("invalid") // ""
+ */
+export declare function parseSecondFromDateTime(value: string): string;

package/dist/plain/parse/parseSecondFromDateTime.js

@@ -0,0 +1,26 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { isValidDateTime } from "../validate/index.js";
+/**
+ * Return the second (0-59) for a given ISO 8601 datetime string.
+ *
+ * - Returns zero-padded string for second.
+ * - Returns "" for invalid input.
+ *
+ * @param value ISO datetime string
+ * @returns Second (00-59) or "" on invalid input
+ *
+ * @example parseSecondFromDateTime("2024-03-15T14:30:45") // "45"
+ * @example parseSecondFromDateTime("2024-03-15T14:30:00") // "00"
+ * @example parseSecondFromDateTime("invalid") // ""
+ */
+export function parseSecondFromDateTime(value) {
+    if (!isValidDateTime(value))
+        return "";
+    try {
+        const dateTime = Temporal.PlainDateTime.from(value);
+        return dateTime.second.toString().padStart(2, "0");
+    }
+    catch {
+        return "";
+    }
+}

package/dist/plain/parse/parseSecondFromTime.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Return the second (0-59) for a given ISO 8601 time string.
+ *
+ * - Returns zero-padded string for second.
+ * - Returns "" for invalid input.
+ *
+ * @param value ISO time string
+ * @returns Second (00-59) or "" on invalid input
+ *
+ * @example parseSecondFromTime("12:30:45") // "45"
+ * @example parseSecondFromTime("12:00:00") // "00"
+ * @example parseSecondFromTime("invalid") // ""
+ */
+export declare function parseSecondFromTime(value: string): string;

package/dist/plain/parse/parseSecondFromTime.js

@@ -0,0 +1,26 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { isValidTime } from "../validate/index.js";
+/**
+ * Return the second (0-59) for a given ISO 8601 time string.
+ *
+ * - Returns zero-padded string for second.
+ * - Returns "" for invalid input.
+ *
+ * @param value ISO time string
+ * @returns Second (00-59) or "" on invalid input
+ *
+ * @example parseSecondFromTime("12:30:45") // "45"
+ * @example parseSecondFromTime("12:00:00") // "00"
+ * @example parseSecondFromTime("invalid") // ""
+ */
+export function parseSecondFromTime(value) {
+    if (!isValidTime(value))
+        return "";
+    try {
+        const time = Temporal.PlainTime.from(value);
+        return time.second.toString().padStart(2, "0");
+    }
+    catch {
+        return "";
+    }
+}

package/dist/plain/parse/parseSql.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Parse an ANSI SQL / ODBC datetime literal — the `YYYY-MM-DD HH:MM:SS` form
+ * MySQL, SQLite, and standard SQL `DATETIME`/`TIMESTAMP` columns (without a
+ * time zone) use — into a plain ISO 8601 datetime string.
+ *
+ * - **Plain only.** SQL's offset-carrying `TIMESTAMPTZ` literal is out of
+ *   scope; see `formatSql`'s JSDoc.
+ * - Requires the space separator and 2-digit zero-padded month/day/hour;
+ *   unlike `parseRfc2822`'s lenient 1-2 digit day, a single-digit field is
+ *   rejected — SQL's literal grammar has no variable-width form to accept.
+ * - Fractional seconds, when present, are preserved as-is; the regex only
+ *   proves shape — `Temporal.PlainDateTime.from` proves the value is a real
+ *   calendar date/time.
+ *
+ * @param value SQL datetime literal (e.g. "2024-03-15 14:30:00")
+ * @returns plain ISO 8601 datetime string, or "" on invalid input
+ *
+ * @example parseSql("2024-03-15 14:30:00") // "2024-03-15T14:30:00"
+ * @example parseSql("2024-03-15 14:30:00.5") // "2024-03-15T14:30:00.5"
+ * @example parseSql("2024-03-15T14:30:00") // "" (wrong separator)
+ * @example parseSql("not a date") // ""
+ */
+export declare function parseSql(value: string): string;

package/dist/plain/parse/parseSql.js

@@ -0,0 +1,36 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { sqlDateTime } from "../../regex/index.js";
+/**
+ * Parse an ANSI SQL / ODBC datetime literal — the `YYYY-MM-DD HH:MM:SS` form
+ * MySQL, SQLite, and standard SQL `DATETIME`/`TIMESTAMP` columns (without a
+ * time zone) use — into a plain ISO 8601 datetime string.
+ *
+ * - **Plain only.** SQL's offset-carrying `TIMESTAMPTZ` literal is out of
+ *   scope; see `formatSql`'s JSDoc.
+ * - Requires the space separator and 2-digit zero-padded month/day/hour;
+ *   unlike `parseRfc2822`'s lenient 1-2 digit day, a single-digit field is
+ *   rejected — SQL's literal grammar has no variable-width form to accept.
+ * - Fractional seconds, when present, are preserved as-is; the regex only
+ *   proves shape — `Temporal.PlainDateTime.from` proves the value is a real
+ *   calendar date/time.
+ *
+ * @param value SQL datetime literal (e.g. "2024-03-15 14:30:00")
+ * @returns plain ISO 8601 datetime string, or "" on invalid input
+ *
+ * @example parseSql("2024-03-15 14:30:00") // "2024-03-15T14:30:00"
+ * @example parseSql("2024-03-15 14:30:00.5") // "2024-03-15T14:30:00.5"
+ * @example parseSql("2024-03-15T14:30:00") // "" (wrong separator)
+ * @example parseSql("not a date") // ""
+ */
+export function parseSql(value) {
+    if (typeof value !== "string")
+        return "";
+    if (!sqlDateTime.test(value))
+        return "";
+    try {
+        return Temporal.PlainDateTime.from(value.replace(" ", "T")).toString();
+    }
+    catch {
+        return "";
+    }
+}

package/dist/plain/parse/parseTimeWithPattern.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Parse a time string against a caller-supplied token pattern (e.g.
+ * `"HH:mm:ss"`, `"h:mm a"`) and return it as an ISO `PlainTime` string.
+ *
+ * - **Decoding, not display.** This is for consuming a *known, fixed*
+ *   producer format — a CSV column, a legacy API field, a partially-typed
+ *   form value — not for generating locale-correct output. For display,
+ *   use `formatTime`/`formatDateToParts`, which order fields per locale
+ *   instead of hard-coding a field order (see roadmap Decision 1 — a
+ *   token *formatter*, the inverse of this function, is deliberately out
+ *   of scope for GMT).
+ * - `pattern` accepts only time-shaped tokens. A pattern containing a
+ *   date-only token (`y M d E G`) is malformed for this function and
+ *   returns `""` — use `parseDateTimeWithPattern` for combined input.
+ *
+ * ### Token table
+ * | Token | Field | Width | Range | Notes |
+ * |---|---|---|---|---|
+ * | `HH` | hour (24h) | 2 digits | 00–23 | |
+ * | `H` | hour (24h) | 1-2 digits | 0–23 | |
+ * | `hh` | hour (12h) | 2 digits | 01–12 | needs `a` to resolve to 24h — see below |
+ * | `h` | hour (12h) | 1-2 digits | 1–12 | same |
+ * | `mm` | minute | 2 digits | 00–59 | |
+ * | `m` | minute | 1-2 digits | 0–59 | |
+ * | `ss` | second | 2 digits | 00–59 | |
+ * | `s` | second | 1-2 digits | 0–59 | |
+ * | `SSS` | millisecond | 3 digits | 000–999 | |
+ * | `a` | meridiem | locale | — | `getLocaleMeridiems(locale)` → `[AM-label, PM-label]` |
+ *
+ * - Text in `'single quotes'` is a literal; a doubled `''` inside a
+ *   quoted segment is a literal `'`. Any other character (`: , space`,
+ *   literal digits, etc.) outside a quote/letter-run is automatically a
+ *   literal — no explicit quoting required.
+ * - `a` is locale-aware. If `locale` is omitted and the pattern uses
+ *   `a`, GMT defaults to `"en-US"` rather than returning `""` for every
+ *   caller who didn't have another locale in mind.
+ * - `h`/`hh` resolve to 24-hour using a matched `a` token: if the label
+ *   is the PM label and hour !== 12, add 12; if the AM label and hour
+ *   === 12, set hour to 0. With no `a` token in the pattern at all, the
+ *   pattern is still valid but the hour stays ambiguous — GMT resolves
+ *   it as if AM had matched (12 → 0, otherwise unchanged).
+ * - A shape-valid match does not by itself prove a real time: extracted
+ *   fields are always handed to `Temporal.PlainTime.from(fields, {
+ *   overflow: "reject" })` — the regex only proves the shape, Temporal
+ *   proves the time is real.
+ *
+ * @param value The string to decode (e.g. "02:30:45 PM")
+ * @param pattern The token pattern describing `value`'s shape (e.g. "hh:mm:ss a")
+ * @param locale Optional BCP 47 locale for the meridiem token (default "en-US")
+ * @returns ISO `PlainTime` string, or "" on no match, malformed pattern, or invalid input
+ *
+ * @example parseTimeWithPattern("14:30:45", "HH:mm:ss") // "14:30:45"
+ * @example parseTimeWithPattern("02:30:45 PM", "hh:mm:ss a") // "14:30:45"
+ * @example parseTimeWithPattern("25:00", "HH:mm") // "" (shape-valid, not a real time)
+ * @example parseTimeWithPattern("2024-03-15", "yyyy-MM-dd") // "" (date token in a time-only pattern)
+ */
+export declare function parseTimeWithPattern(value: string, pattern: string, locale?: string): string;

package/dist/plain/parse/parseTimeWithPattern.js

@@ -0,0 +1,85 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { parseValueWithPattern, TIME_PATTERN_FIELDS } from "../../internal/index.js";
+/**
+ * Parse a time string against a caller-supplied token pattern (e.g.
+ * `"HH:mm:ss"`, `"h:mm a"`) and return it as an ISO `PlainTime` string.
+ *
+ * - **Decoding, not display.** This is for consuming a *known, fixed*
+ *   producer format — a CSV column, a legacy API field, a partially-typed
+ *   form value — not for generating locale-correct output. For display,
+ *   use `formatTime`/`formatDateToParts`, which order fields per locale
+ *   instead of hard-coding a field order (see roadmap Decision 1 — a
+ *   token *formatter*, the inverse of this function, is deliberately out
+ *   of scope for GMT).
+ * - `pattern` accepts only time-shaped tokens. A pattern containing a
+ *   date-only token (`y M d E G`) is malformed for this function and
+ *   returns `""` — use `parseDateTimeWithPattern` for combined input.
+ *
+ * ### Token table
+ * | Token | Field | Width | Range | Notes |
+ * |---|---|---|---|---|
+ * | `HH` | hour (24h) | 2 digits | 00–23 | |
+ * | `H` | hour (24h) | 1-2 digits | 0–23 | |
+ * | `hh` | hour (12h) | 2 digits | 01–12 | needs `a` to resolve to 24h — see below |
+ * | `h` | hour (12h) | 1-2 digits | 1–12 | same |
+ * | `mm` | minute | 2 digits | 00–59 | |
+ * | `m` | minute | 1-2 digits | 0–59 | |
+ * | `ss` | second | 2 digits | 00–59 | |
+ * | `s` | second | 1-2 digits | 0–59 | |
+ * | `SSS` | millisecond | 3 digits | 000–999 | |
+ * | `a` | meridiem | locale | — | `getLocaleMeridiems(locale)` → `[AM-label, PM-label]` |
+ *
+ * - Text in `'single quotes'` is a literal; a doubled `''` inside a
+ *   quoted segment is a literal `'`. Any other character (`: , space`,
+ *   literal digits, etc.) outside a quote/letter-run is automatically a
+ *   literal — no explicit quoting required.
+ * - `a` is locale-aware. If `locale` is omitted and the pattern uses
+ *   `a`, GMT defaults to `"en-US"` rather than returning `""` for every
+ *   caller who didn't have another locale in mind.
+ * - `h`/`hh` resolve to 24-hour using a matched `a` token: if the label
+ *   is the PM label and hour !== 12, add 12; if the AM label and hour
+ *   === 12, set hour to 0. With no `a` token in the pattern at all, the
+ *   pattern is still valid but the hour stays ambiguous — GMT resolves
+ *   it as if AM had matched (12 → 0, otherwise unchanged).
+ * - A shape-valid match does not by itself prove a real time: extracted
+ *   fields are always handed to `Temporal.PlainTime.from(fields, {
+ *   overflow: "reject" })` — the regex only proves the shape, Temporal
+ *   proves the time is real.
+ *
+ * @param value The string to decode (e.g. "02:30:45 PM")
+ * @param pattern The token pattern describing `value`'s shape (e.g. "hh:mm:ss a")
+ * @param locale Optional BCP 47 locale for the meridiem token (default "en-US")
+ * @returns ISO `PlainTime` string, or "" on no match, malformed pattern, or invalid input
+ *
+ * @example parseTimeWithPattern("14:30:45", "HH:mm:ss") // "14:30:45"
+ * @example parseTimeWithPattern("02:30:45 PM", "hh:mm:ss a") // "14:30:45"
+ * @example parseTimeWithPattern("25:00", "HH:mm") // "" (shape-valid, not a real time)
+ * @example parseTimeWithPattern("2024-03-15", "yyyy-MM-dd") // "" (date token in a time-only pattern)
+ */
+export function parseTimeWithPattern(value, pattern, locale) {
+    if (typeof value !== "string")
+        return "";
+    if (typeof pattern !== "string")
+        return "";
+    if (locale !== undefined && typeof locale !== "string")
+        return "";
+    const fields = parseValueWithPattern(value, pattern, locale, TIME_PATTERN_FIELDS);
+    if (fields === null)
+        return "";
+    try {
+        // The regex only proved `value` has the right *shape* for `pattern`
+        // (e.g. "25:00" matches "HH:mm") — Temporal is what proves the time
+        // is real: `overflow: "reject"` throws instead of silently clamping
+        // an out-of-range field, which is what the default "constrain" would
+        // do.
+        return Temporal.PlainTime.from({
+            hour: fields.hour,
+            minute: fields.minute,
+            second: fields.second,
+            millisecond: fields.millisecond,
+        }, { overflow: "reject" }).toString();
+    }
+    catch {
+        return "";
+    }
+}

package/dist/plain/parse/parseUnitFromDate.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Return a specific date unit extracted from a PlainDate string.
+ *
+ * - Extracts "year", "month", "day", "week", or "dayOfWeek" from a PlainDate.
+ * - Returns zero-padded string for month and day.
+ * - Returns "" for invalid input.
+ *
+ * @param value ISO PlainDate string
+ * @param unit unit to extract from the date
+ * @param optionsArg optional: weekStartsOn ("monday" | "sunday") for week calculations
+ * @returns string representation of the requested unit or "" on invalid input
+ *
+ * @example parseUnitFromDate("2024-03-15", "year") // "2024"
+ * @example parseUnitFromDate("2024-03-15", "month") // "03"
+ * @example parseUnitFromDate("2024-03-15", "day") // "15"
+ * @example parseUnitFromDate("2024-03-15", "week") // "11"
+ * @example parseUnitFromDate("2024-03-15", "dayOfWeek") // "5"
+ * @example parseUnitFromDate("invalid", "year") // ""
+ * @example parseUnitFromDate("2024-01-01", "week", { weekStartsOn: "sunday" }) // "1"
+ */
+export declare function parseUnitFromDate(value: string, unit: "year" | "month" | "day" | "week" | "dayOfWeek", optionsArg?: {
+    weekStartsOn?: "monday" | "sunday";
+}): string;

package/dist/plain/parse/parseUnitFromDate.js

@@ -0,0 +1,49 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { getWeekNumber } from "../calculate/getWeekNumber.js";
+import { isValidDate } from "../validate/index.js";
+/**
+ * Return a specific date unit extracted from a PlainDate string.
+ *
+ * - Extracts "year", "month", "day", "week", or "dayOfWeek" from a PlainDate.
+ * - Returns zero-padded string for month and day.
+ * - Returns "" for invalid input.
+ *
+ * @param value ISO PlainDate string
+ * @param unit unit to extract from the date
+ * @param optionsArg optional: weekStartsOn ("monday" | "sunday") for week calculations
+ * @returns string representation of the requested unit or "" on invalid input
+ *
+ * @example parseUnitFromDate("2024-03-15", "year") // "2024"
+ * @example parseUnitFromDate("2024-03-15", "month") // "03"
+ * @example parseUnitFromDate("2024-03-15", "day") // "15"
+ * @example parseUnitFromDate("2024-03-15", "week") // "11"
+ * @example parseUnitFromDate("2024-03-15", "dayOfWeek") // "5"
+ * @example parseUnitFromDate("invalid", "year") // ""
+ * @example parseUnitFromDate("2024-01-01", "week", { weekStartsOn: "sunday" }) // "1"
+ */
+export function parseUnitFromDate(value, unit, optionsArg) {
+    if (!isValidDate(value)) {
+        return "";
+    }
+    const weekStartsOn = optionsArg?.weekStartsOn ?? "monday";
+    try {
+        const date = Temporal.PlainDate.from(value);
+        switch (unit) {
+            case "year":
+                return date.year.toString();
+            case "month":
+                return date.month.toString().padStart(2, "0");
+            case "day":
+                return date.day.toString().padStart(2, "0");
+            case "week":
+                return (getWeekNumber(value, weekStartsOn) ?? 0).toString();
+            case "dayOfWeek":
+                return date.dayOfWeek.toString();
+            default:
+                return "";
+        }
+    }
+    catch {
+        return "";
+    }
+}

package/dist/plain/parse/parseUnitFromDateTime.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Return a specific unit extracted from a PlainDateTime string.
+ *
+ * - Extracts "year", "month", "day", "week", "dayOfWeek", "hour", "minute", "second", or "millisecond" from a PlainDateTime.
+ * - Returns zero-padded string for most units.
+ * - Returns "" for invalid input.
+ *
+ * @param value ISO PlainDateTime string
+ * @param unit unit to extract from the datetime
+ * @param optionsArg optional: weekStartsOn ("monday" | "sunday") for week calculations
+ * @returns string representation of the requested unit or "" on invalid input
+ *
+ * @example parseUnitFromDateTime("2024-03-15T14:30:45.123", "year") // "2024"
+ * @example parseUnitFromDateTime("2024-03-15T14:30:45.123", "week") // "11"
+ * @example parseUnitFromDateTime("2024-03-15T14:30:45.123", "hour") // "14"
+ * @example parseUnitFromDateTime("2024-03-15T14:30:45.123", "millisecond") // "123"
+ * @example parseUnitFromDateTime("invalid", "year") // ""
+ * @example parseUnitFromDateTime("2024-01-01T00:00:00", "week", { weekStartsOn: "sunday" }) // "1"
+ */
+export declare function parseUnitFromDateTime(value: string, unit: "year" | "month" | "day" | "week" | "dayOfWeek" | "hour" | "minute" | "second" | "millisecond", optionsArg?: {
+    weekStartsOn?: "monday" | "sunday";
+}): string;

package/dist/plain/parse/parseUnitFromDateTime.js

@@ -0,0 +1,56 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { getWeekNumber } from "../calculate/getWeekNumber.js";
+import { isValidDateTime } from "../validate/index.js";
+/**
+ * Return a specific unit extracted from a PlainDateTime string.
+ *
+ * - Extracts "year", "month", "day", "week", "dayOfWeek", "hour", "minute", "second", or "millisecond" from a PlainDateTime.
+ * - Returns zero-padded string for most units.
+ * - Returns "" for invalid input.
+ *
+ * @param value ISO PlainDateTime string
+ * @param unit unit to extract from the datetime
+ * @param optionsArg optional: weekStartsOn ("monday" | "sunday") for week calculations
+ * @returns string representation of the requested unit or "" on invalid input
+ *
+ * @example parseUnitFromDateTime("2024-03-15T14:30:45.123", "year") // "2024"
+ * @example parseUnitFromDateTime("2024-03-15T14:30:45.123", "week") // "11"
+ * @example parseUnitFromDateTime("2024-03-15T14:30:45.123", "hour") // "14"
+ * @example parseUnitFromDateTime("2024-03-15T14:30:45.123", "millisecond") // "123"
+ * @example parseUnitFromDateTime("invalid", "year") // ""
+ * @example parseUnitFromDateTime("2024-01-01T00:00:00", "week", { weekStartsOn: "sunday" }) // "1"
+ */
+export function parseUnitFromDateTime(value, unit, optionsArg) {
+    if (!isValidDateTime(value)) {
+        return "";
+    }
+    const weekStartsOn = optionsArg?.weekStartsOn ?? "monday";
+    try {
+        const dateTime = Temporal.PlainDateTime.from(value);
+        switch (unit) {
+            case "year":
+                return dateTime.year.toString();
+            case "month":
+                return dateTime.month.toString().padStart(2, "0");
+            case "day":
+                return dateTime.day.toString().padStart(2, "0");
+            case "week":
+                return (getWeekNumber(value, weekStartsOn) ?? 0).toString();
+            case "dayOfWeek":
+                return dateTime.dayOfWeek.toString();
+            case "hour":
+                return dateTime.hour.toString().padStart(2, "0");
+            case "minute":
+                return dateTime.minute.toString().padStart(2, "0");
+            case "second":
+                return dateTime.second.toString().padStart(2, "0");
+            case "millisecond":
+                return dateTime.millisecond.toString().padStart(3, "0");
+            default:
+                return "";
+        }
+    }
+    catch {
+        return "";
+    }
+}

package/dist/plain/parse/parseUnitFromTime.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Return a specific time unit extracted from a PlainTime string.
+ *
+ * - Extracts "hour", "minute", "second", or "millisecond" from a PlainTime.
+ * - Returns zero-padded string for hour, minute, second (2 digits) and millisecond (3 digits).
+ * - Returns "" for invalid input.
+ *
+ * @param value ISO PlainTime string
+ * @param unit unit to extract from the time
+ * @returns string representation of the requested unit or "" on invalid input
+ *
+ * @example parseUnitFromTime("14:30:45.123", "hour") // "14"
+ * @example parseUnitFromTime("14:30:45.123", "minute") // "30"
+ * @example parseUnitFromTime("14:30:45.123", "second") // "45"
+ * @example parseUnitFromTime("14:30:45.123", "millisecond") // "123"
+ * @example parseUnitFromTime("invalid", "hour") // ""
+ */
+export declare function parseUnitFromTime(value: string, unit: "hour" | "minute" | "second" | "millisecond"): string;

package/dist/plain/parse/parseUnitFromTime.js

@@ -0,0 +1,42 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { isValidTime } from "../validate/index.js";
+/**
+ * Return a specific time unit extracted from a PlainTime string.
+ *
+ * - Extracts "hour", "minute", "second", or "millisecond" from a PlainTime.
+ * - Returns zero-padded string for hour, minute, second (2 digits) and millisecond (3 digits).
+ * - Returns "" for invalid input.
+ *
+ * @param value ISO PlainTime string
+ * @param unit unit to extract from the time
+ * @returns string representation of the requested unit or "" on invalid input
+ *
+ * @example parseUnitFromTime("14:30:45.123", "hour") // "14"
+ * @example parseUnitFromTime("14:30:45.123", "minute") // "30"
+ * @example parseUnitFromTime("14:30:45.123", "second") // "45"
+ * @example parseUnitFromTime("14:30:45.123", "millisecond") // "123"
+ * @example parseUnitFromTime("invalid", "hour") // ""
+ */
+export function parseUnitFromTime(value, unit) {
+    if (!isValidTime(value)) {
+        return "";
+    }
+    try {
+        const time = Temporal.PlainTime.from(value);
+        switch (unit) {
+            case "hour":
+                return time.hour.toString().padStart(2, "0");
+            case "minute":
+                return time.minute.toString().padStart(2, "0");
+            case "second":
+                return time.second.toString().padStart(2, "0");
+            case "millisecond":
+                return time.millisecond.toString().padStart(3, "0");
+            default:
+                return "";
+        }
+    }
+    catch {
+        return "";
+    }
+}

package/dist/plain/parse/parseWeekFromDate.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Return the week number for a given ISO 8601 date string.
+ *
+ * - By default uses ISO weeks (Monday-based).
+ * - Returns null for invalid input.
+ *
+ * @param value ISO date string
+ * @param optionsArg optional: weekStartsOn ("monday" | "sunday") for week calculations
+ * @returns Week number (1-53) or null on invalid input
+ *
+ * @example parseWeekFromDate("2024-01-01") // 1
+ * @example parseWeekFromDate("2024-01-08") // 2
+ * @example parseWeekFromDate("2024-12-31") // 1
+ * @example parseWeekFromDate("2024-01-01", { weekStartsOn: "sunday" }) // 1
+ * @example parseWeekFromDate("invalid") // null
+ */
+export declare function parseWeekFromDate(value: string, optionsArg?: {
+    weekStartsOn?: "monday" | "sunday";
+}): number | null;