@northguild/gmt 1.17.0 → 1.18.0

package/dist/plain/interval/splitIntervalByUnitDate.d.ts

@@ -7,9 +7,12 @@
  *   there, so the pieces share no value and together cover the interval exactly once (the rule
  *   CORE-6's `splitIntervalAt` uses).
  * - The final sub-interval is trimmed so its `end` never exceeds the original `end`.
- * - Each boundary is computed from `start` (`start + k × amount`, as Temporal and Luxon's
- *   `Interval.splitBy` do), not by stepping from the previous boundary, so month-end starts
- *   don't drift: a monthly split from January 31 lands on February 29, March 31, April 30.
+ * - Each boundary is computed from `start` (`start + k × amount`), not by stepping from the
+ *   previous boundary, so month-end starts don't drift: a monthly split from January 31 lands
+ *   on February 29, March 31, April 30. Temporal's `add` constrains a day the month lacks to
+ *   the month's last day, and stepping from that boundary would keep the shortened day
+ *   (February 29, then March 29).
+ * - Comparison: Luxon's `Interval.splitBy` computes each boundary from the start the same way.
  * - A step that resolves to the same date as the previous boundary is skipped, so no empty
  *   slice is produced. A step that goes backwards returns `[]`.
  * - Returns `[{ start, end }]` when `start === end` (zero-length interval).
@@ -22,9 +25,6 @@
  *   when `CalendarEquals` is false (before 1.16.0 it stepped in ISO). Each boundary's tag is
  *   re-derived from the actual stepped date, never copied — a month-by-month step can cross a
  *   leap-month or era boundary mid-split.
- * - `options.maxPieces` (positive safe integer, default `1_000_000`) bounds the output: a split
- *   into more slices returns `[]`, decided from the span before stepping where it can be, and
- *   otherwise as soon as slice `maxPieces + 1` is due. An invalid `maxPieces` also returns `[]`.
  * - Compatibility: since 1.16.0 calendar strings are RFC 9557 (ISO digits, `[u-ca=<id>]`, canonical
  *   calendar ids); see `isValidCalendarDate`.
  *
@@ -32,7 +32,7 @@
  * @param end ISO PlainDate string for the interval end, optionally calendar-annotated
  * @param unit duration unit string — `"years" | "months" | "weeks" | "days"` (time units are ignored by PlainDate and return [])
  * @param amount positive number of units per step
- * @param options optional: `maxPieces` (positive safe integer, default `1_000_000`)
+ * @param options The limit on the size of the result
  * @returns array of `{ start, end }` records, or [] on invalid input
  *
  * @example splitIntervalByUnitDate("2024-01-01", "2024-01-10", "day", 2) // [{ start: "2024-01-01", end: "2024-01-03" }, { start: "2024-01-03", end: "2024-01-05" }, { start: "2024-01-05", end: "2024-01-07" }, { start: "2024-01-07", end: "2024-01-09" }, { start: "2024-01-09", end: "2024-01-10" }]
@@ -45,8 +45,24 @@
  * @example splitIntervalByUnitDate("2024-01-01", "2024-01-10", "day", 2, { maxPieces: 5 }) // [{ start: "2024-01-01", end: "2024-01-03" }, { start: "2024-01-03", end: "2024-01-05" }, { start: "2024-01-05", end: "2024-01-07" }, { start: "2024-01-07", end: "2024-01-09" }, { start: "2024-01-09", end: "2024-01-10" }]
  */
 export declare function splitIntervalByUnitDate(start: string, end: string, unit: string, amount: number, options?: {
+    /**
+     * The most records the result may hold. A result that would hold more, or more than the longest
+     * possible array (2^32 - 1 elements), returns `[]` and none is built. A value that is not a
+     * positive safe integer also returns `[]`.
+     *
+     * @defaultValue `1_000_000`
+     */
     maxPieces?: number;
 }): Array<{
+    /**
+     * The date the interval begins on, as an ISO 8601 date (`YYYY-MM-DD`). It keeps a calendar
+     * annotation such as `[u-ca=hebrew]` when the inputs carry one.
+     */
     start: string;
+    /**
+     * The first date after the interval, in the same format as `start`. It is exclusive: the interval
+     * holds everything from `start` up to but not including this value. It can equal `start`, which
+     * makes the interval empty.
+     */
     end: string;
 }>;

package/dist/plain/interval/splitIntervalByUnitDate.js

@@ -13,9 +13,12 @@ import { minSlicesForSpan } from "../../internal/splitStep.js";
  *   there, so the pieces share no value and together cover the interval exactly once (the rule
  *   CORE-6's `splitIntervalAt` uses).
  * - The final sub-interval is trimmed so its `end` never exceeds the original `end`.
- * - Each boundary is computed from `start` (`start + k × amount`, as Temporal and Luxon's
- *   `Interval.splitBy` do), not by stepping from the previous boundary, so month-end starts
- *   don't drift: a monthly split from January 31 lands on February 29, March 31, April 30.
+ * - Each boundary is computed from `start` (`start + k × amount`), not by stepping from the
+ *   previous boundary, so month-end starts don't drift: a monthly split from January 31 lands
+ *   on February 29, March 31, April 30. Temporal's `add` constrains a day the month lacks to
+ *   the month's last day, and stepping from that boundary would keep the shortened day
+ *   (February 29, then March 29).
+ * - Comparison: Luxon's `Interval.splitBy` computes each boundary from the start the same way.
  * - A step that resolves to the same date as the previous boundary is skipped, so no empty
  *   slice is produced. A step that goes backwards returns `[]`.
  * - Returns `[{ start, end }]` when `start === end` (zero-length interval).
@@ -28,9 +31,6 @@ import { minSlicesForSpan } from "../../internal/splitStep.js";
  *   when `CalendarEquals` is false (before 1.16.0 it stepped in ISO). Each boundary's tag is
  *   re-derived from the actual stepped date, never copied — a month-by-month step can cross a
  *   leap-month or era boundary mid-split.
- * - `options.maxPieces` (positive safe integer, default `1_000_000`) bounds the output: a split
- *   into more slices returns `[]`, decided from the span before stepping where it can be, and
- *   otherwise as soon as slice `maxPieces + 1` is due. An invalid `maxPieces` also returns `[]`.
  * - Compatibility: since 1.16.0 calendar strings are RFC 9557 (ISO digits, `[u-ca=<id>]`, canonical
  *   calendar ids); see `isValidCalendarDate`.
  *
@@ -38,7 +38,7 @@ import { minSlicesForSpan } from "../../internal/splitStep.js";
  * @param end ISO PlainDate string for the interval end, optionally calendar-annotated
  * @param unit duration unit string — `"years" | "months" | "weeks" | "days"` (time units are ignored by PlainDate and return [])
  * @param amount positive number of units per step
- * @param options optional: `maxPieces` (positive safe integer, default `1_000_000`)
+ * @param options The limit on the size of the result
  * @returns array of `{ start, end }` records, or [] on invalid input
  *
  * @example splitIntervalByUnitDate("2024-01-01", "2024-01-10", "day", 2) // [{ start: "2024-01-01", end: "2024-01-03" }, { start: "2024-01-03", end: "2024-01-05" }, { start: "2024-01-05", end: "2024-01-07" }, { start: "2024-01-07", end: "2024-01-09" }, { start: "2024-01-09", end: "2024-01-10" }]

package/dist/plain/interval/splitIntervalByUnitDateTime.d.ts

@@ -8,8 +8,11 @@
  *   CORE-6's `splitIntervalAt` uses).
  * - The final sub-interval is trimmed so its `end` never exceeds the original `end`.
  * - Calendar-unit boundaries (years, months, weeks, days) are computed from `start`
- *   (`start + k × amount`, as Temporal and Luxon's `Interval.splitBy` do), so month-end starts
- *   don't drift: a monthly split from January 31 lands on February 29, March 31, April 30.
+ *   (`start + k × amount`), so month-end starts don't drift: a monthly split from January 31
+ *   lands on February 29, March 31, April 30. Temporal's `add` constrains a day the month lacks
+ *   to the month's last day, and stepping from that boundary would keep the shortened day
+ *   (February 29, then March 29).
+ * - Comparison: Luxon's `Interval.splitBy` computes each boundary from the start the same way.
  * - Exact-unit boundaries (hours and smaller) step from the previous boundary. Exact units never
  *   clamp, and stepping keeps nanosecond precision where `k × amount` would pass
  *   `Number.MAX_SAFE_INTEGER`.
@@ -17,15 +20,12 @@
  *   slice is produced. A step that goes backwards returns `[]`.
  * - Returns `[{ start, end }]` when `start === end` (zero-length interval).
  * - Returns `[]` on invalid input (unparseable start/end, unsupported unit, non-positive amount).
- * - `options.maxPieces` (positive safe integer, default `1_000_000`) bounds the output: a split
- *   into more slices returns `[]`, decided from the span before stepping where it can be, and
- *   otherwise as soon as slice `maxPieces + 1` is due. An invalid `maxPieces` also returns `[]`.
  *
  * @param start ISO PlainDateTime string for the interval start
  * @param end ISO PlainDateTime string for the interval end
  * @param unit duration unit string — any `DateTimeDurationUnit`
  * @param amount positive number of units per step
- * @param options optional: `maxPieces` (positive safe integer, default `1_000_000`)
+ * @param options The limit on the size of the result
  * @returns array of `{ start, end }` records, or [] on invalid input
  *
  * @example splitIntervalByUnitDateTime("2024-01-01T12:00:00", "2024-01-01T14:00:00", "hour", 1) // [{ start: "2024-01-01T12:00:00", end: "2024-01-01T13:00:00" }, { start: "2024-01-01T13:00:00", end: "2024-01-01T14:00:00" }]
@@ -37,8 +37,24 @@
  * @example splitIntervalByUnitDateTime("2024-01-01T12:00:00", "2024-01-01T14:00:00", "hour", 1, { maxPieces: 2 }) // [{ start: "2024-01-01T12:00:00", end: "2024-01-01T13:00:00" }, { start: "2024-01-01T13:00:00", end: "2024-01-01T14:00:00" }]
  */
 export declare function splitIntervalByUnitDateTime(start: string, end: string, unit: string, amount: number, options?: {
+    /**
+     * The most records the result may hold. A result that would hold more, or more than the longest
+     * possible array (2^32 - 1 elements), returns `[]` and none is built. A value that is not a
+     * positive safe integer also returns `[]`.
+     *
+     * @defaultValue `1_000_000`
+     */
     maxPieces?: number;
 }): Array<{
+    /**
+     * The date-time the interval begins at, as an ISO 8601 date-time string with no offset or time
+     * zone.
+     */
     start: string;
+    /**
+     * The first date-time after the interval, in the same format as `start`. It is exclusive: the
+     * interval holds everything from `start` up to but not including this value. It can equal
+     * `start`, which makes the interval empty.
+     */
     end: string;
 }>;

package/dist/plain/interval/splitIntervalByUnitDateTime.js

@@ -14,8 +14,11 @@ import { minSlicesForSpan } from "../../internal/splitStep.js";
  *   CORE-6's `splitIntervalAt` uses).
  * - The final sub-interval is trimmed so its `end` never exceeds the original `end`.
  * - Calendar-unit boundaries (years, months, weeks, days) are computed from `start`
- *   (`start + k × amount`, as Temporal and Luxon's `Interval.splitBy` do), so month-end starts
- *   don't drift: a monthly split from January 31 lands on February 29, March 31, April 30.
+ *   (`start + k × amount`), so month-end starts don't drift: a monthly split from January 31
+ *   lands on February 29, March 31, April 30. Temporal's `add` constrains a day the month lacks
+ *   to the month's last day, and stepping from that boundary would keep the shortened day
+ *   (February 29, then March 29).
+ * - Comparison: Luxon's `Interval.splitBy` computes each boundary from the start the same way.
  * - Exact-unit boundaries (hours and smaller) step from the previous boundary. Exact units never
  *   clamp, and stepping keeps nanosecond precision where `k × amount` would pass
  *   `Number.MAX_SAFE_INTEGER`.
@@ -23,15 +26,12 @@ import { minSlicesForSpan } from "../../internal/splitStep.js";
  *   slice is produced. A step that goes backwards returns `[]`.
  * - Returns `[{ start, end }]` when `start === end` (zero-length interval).
  * - Returns `[]` on invalid input (unparseable start/end, unsupported unit, non-positive amount).
- * - `options.maxPieces` (positive safe integer, default `1_000_000`) bounds the output: a split
- *   into more slices returns `[]`, decided from the span before stepping where it can be, and
- *   otherwise as soon as slice `maxPieces + 1` is due. An invalid `maxPieces` also returns `[]`.
  *
  * @param start ISO PlainDateTime string for the interval start
  * @param end ISO PlainDateTime string for the interval end
  * @param unit duration unit string — any `DateTimeDurationUnit`
  * @param amount positive number of units per step
- * @param options optional: `maxPieces` (positive safe integer, default `1_000_000`)
+ * @param options The limit on the size of the result
  * @returns array of `{ start, end }` records, or [] on invalid input
  *
  * @example splitIntervalByUnitDateTime("2024-01-01T12:00:00", "2024-01-01T14:00:00", "hour", 1) // [{ start: "2024-01-01T12:00:00", end: "2024-01-01T13:00:00" }, { start: "2024-01-01T13:00:00", end: "2024-01-01T14:00:00" }]

package/dist/plain/interval/splitIntervalByUnitTime.d.ts

@@ -13,15 +13,12 @@
  * - Returns `[{ start, end }]` when `start === end` (zero-length interval).
  * - Returns `[]` on invalid input (unparseable start/end, unsupported unit, non-positive amount,
  *   or a unit that has no effect on `PlainTime`, e.g. `"days"`).
- * - `options.maxPieces` (positive safe integer, default `1_000_000`) bounds the output: a split
- *   into more slices returns `[]`, decided from the span before stepping. An invalid
- *   `maxPieces` also returns `[]`.
  *
  * @param start ISO PlainTime string for the interval start
  * @param end ISO PlainTime string for the interval end
  * @param unit duration unit string — `"hours" | "minutes" | "seconds" | "milliseconds" | "microseconds" | "nanoseconds"` (calendar units are ignored by PlainTime and return [])
  * @param amount positive number of units per step
- * @param options optional: `maxPieces` (positive safe integer, default `1_000_000`)
+ * @param options The limit on the size of the result
  * @returns array of `{ start, end }` records, or [] on invalid input
  *
  * @example splitIntervalByUnitTime("12:00:00", "14:00:00", "hour", 1) // [{ start: "12:00:00", end: "13:00:00" }, { start: "13:00:00", end: "14:00:00" }]
@@ -34,8 +31,24 @@
  * @example splitIntervalByUnitTime("12:00:00", "14:30:00", "hour", 1, { maxPieces: 3 }) // [{ start: "12:00:00", end: "13:00:00" }, { start: "13:00:00", end: "14:00:00" }, { start: "14:00:00", end: "14:30:00" }]
  */
 export declare function splitIntervalByUnitTime(start: string, end: string, unit: string, amount: number, options?: {
+    /**
+     * The most records the result may hold. A result that would hold more, or more than the longest
+     * possible array (2^32 - 1 elements), returns `[]` and none is built. A value that is not a
+     * positive safe integer also returns `[]`.
+     *
+     * @defaultValue `1_000_000`
+     */
     maxPieces?: number;
 }): Array<{
+    /**
+     * The clock time the interval begins at, as an ISO 8601 time string with no date, offset or time
+     * zone.
+     */
     start: string;
+    /**
+     * The first clock time after the interval, in the same format as `start`. It is exclusive: the
+     * interval holds everything from `start` up to but not including this value. It can equal
+     * `start`, which makes the interval empty.
+     */
     end: string;
 }>;

package/dist/plain/interval/splitIntervalByUnitTime.js

@@ -19,15 +19,12 @@ import { isExactDurationUnit, minSlicesForSpan, } from "../../internal/splitStep
  * - Returns `[{ start, end }]` when `start === end` (zero-length interval).
  * - Returns `[]` on invalid input (unparseable start/end, unsupported unit, non-positive amount,
  *   or a unit that has no effect on `PlainTime`, e.g. `"days"`).
- * - `options.maxPieces` (positive safe integer, default `1_000_000`) bounds the output: a split
- *   into more slices returns `[]`, decided from the span before stepping. An invalid
- *   `maxPieces` also returns `[]`.
  *
  * @param start ISO PlainTime string for the interval start
  * @param end ISO PlainTime string for the interval end
  * @param unit duration unit string — `"hours" | "minutes" | "seconds" | "milliseconds" | "microseconds" | "nanoseconds"` (calendar units are ignored by PlainTime and return [])
  * @param amount positive number of units per step
- * @param options optional: `maxPieces` (positive safe integer, default `1_000_000`)
+ * @param options The limit on the size of the result
  * @returns array of `{ start, end }` records, or [] on invalid input
  *
  * @example splitIntervalByUnitTime("12:00:00", "14:00:00", "hour", 1) // [{ start: "12:00:00", end: "13:00:00" }, { start: "13:00:00", end: "14:00:00" }]

package/dist/plain/map/mapDatesInRange.d.ts

@@ -3,9 +3,6 @@
  *
  * - Generates dates with optional step (default 1 day).
  * - Returns [] if start > end, invalid inputs, or step <= 0.
- * - `options.maxPieces` (positive safe integer, default `1_000_000`) bounds the output: when the
- *   range holds more dates than that, it returns `[]` without generating any. An invalid
- *   `maxPieces` also returns `[]`.
  * - An explicit `undefined` `stepDays` is the default step, so `(start, end, undefined, options)`
  *   reaches `options`. **Compatibility:** before 1.16.0 it returned `[]`.
  * - **End-inclusive, where the `interval*` functions are half-open.** This enumerates the dates a
@@ -17,7 +14,7 @@
  * @param startDate ISO PlainDate string for the first date
  * @param endDate ISO PlainDate string for the last date (inclusive)
  * @param stepDays optional number of days to step between results
- * @param options optional: `maxPieces` (positive safe integer, default `1_000_000`)
+ * @param options The limit on the size of the result
  * @returns array of ISO PlainDate strings, or [] on invalid input
  *
  * @example mapDatesInRange("2024-03-01", "2024-03-05") // ["2024-03-01", "2024-03-02", "2024-03-03", "2024-03-04", "2024-03-05"]
@@ -32,5 +29,12 @@
  * @example mapDatesInRange("2024-03-01", "2024-03-05", 1, { maxPieces: 10 }) // ["2024-03-01", "2024-03-02", "2024-03-03", "2024-03-04", "2024-03-05"]
  */
 export declare function mapDatesInRange(startDate: string, endDate: string, stepDays?: number, options?: {
+    /**
+     * The most dates the result may hold. A result that would hold more, or more than the longest
+     * possible array (2^32 - 1 elements), returns `[]` and none is built. A value that is not a
+     * positive safe integer also returns `[]`.
+     *
+     * @defaultValue `1_000_000`
+     */
     maxPieces?: number;
 }): string[];

package/dist/plain/map/mapDatesInRange.js

@@ -7,9 +7,6 @@ import { exceedsPieceLimit, resolveMaxPieces } from "../../internal/maxPieces.js
  *
  * - Generates dates with optional step (default 1 day).
  * - Returns [] if start > end, invalid inputs, or step <= 0.
- * - `options.maxPieces` (positive safe integer, default `1_000_000`) bounds the output: when the
- *   range holds more dates than that, it returns `[]` without generating any. An invalid
- *   `maxPieces` also returns `[]`.
  * - An explicit `undefined` `stepDays` is the default step, so `(start, end, undefined, options)`
  *   reaches `options`. **Compatibility:** before 1.16.0 it returned `[]`.
  * - **End-inclusive, where the `interval*` functions are half-open.** This enumerates the dates a
@@ -21,7 +18,7 @@ import { exceedsPieceLimit, resolveMaxPieces } from "../../internal/maxPieces.js
  * @param startDate ISO PlainDate string for the first date
  * @param endDate ISO PlainDate string for the last date (inclusive)
  * @param stepDays optional number of days to step between results
- * @param options optional: `maxPieces` (positive safe integer, default `1_000_000`)
+ * @param options The limit on the size of the result
  * @returns array of ISO PlainDate strings, or [] on invalid input
  *
  * @example mapDatesInRange("2024-03-01", "2024-03-05") // ["2024-03-01", "2024-03-02", "2024-03-03", "2024-03-04", "2024-03-05"]

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

@@ -7,9 +7,8 @@
  *   producer format — a CSV column, a legacy API field, a partially-typed
  *   form value — not for generating locale-correct output. For display,
  *   use `formatDateTime`/`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).
+ *   locale instead of hard-coding a field order (a token *formatter*,
+ *   the inverse of this function, is deliberately out of scope for GMT).
  * - Accepts the full combined date + time token set (unlike
  *   `parseDateWithPattern`/`parseTimeWithPattern`, which each reject the
  *   other's tokens).
@@ -40,10 +39,13 @@
  * | `GGGG` | era name (long) | locale | — | BCE label ⇒ final year = 1 − parsed year |
  * | `GG` | era name (short) | locale | — | same resolution |
  *
- * - 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.
+ * - Literal text follows the Unicode UTS #35 date format pattern rules.
+ *   Text in `'single quotes'` is a literal, letters included. Two
+ *   adjacent quotes `''` are one literal `'`, inside or outside quoted
+ *   text: `"yyyy''MM"` reads `"2024'03"`, and `"'o''clock'"` reads
+ *   `"o'clock"`. A quote that never closes makes the pattern malformed
+ *   (`""`). Any other character that is not a letter (`/ - , space :`,
+ *   digits and so on) is a literal with no quoting.
  * - `MMMM`/`MMM`/`EEEE`/`EEE`/`a`/`GGGG`/`GG` are locale-aware. If
  *   `locale` is omitted and the pattern uses any of them, GMT defaults
  *   to `"en-US"` rather than returning `""` for every caller who didn't
@@ -79,6 +81,7 @@
  *
  * @example parseDateTimeWithPattern("03/15/2024 14:30:00", "MM/dd/yyyy HH:mm:ss") // "2024-03-15T14:30:00"
  * @example parseDateTimeWithPattern("15-Mar-2024 02:30 PM", "dd-MMM-yyyy hh:mm a") // "2024-03-15T14:30:00"
+ * @example parseDateTimeWithPattern("Mar 15, '24 at 14:30", "MMM d, ''yy 'at' HH:mm") // "2024-03-15T14:30:00" ('' is one literal quote)
  * @example parseDateTimeWithPattern("02/31/2024 14:30:00", "MM/dd/yyyy HH:mm:ss") // "" (shape-valid, not a real date)
  * @example parseDateTimeWithPattern("not a date", "MM/dd/yyyy HH:mm:ss") // ""
  * @example parseDateTimeWithPattern("19 mai 2024 10:20", "d MMMM yyyy HH:mm", ["fr-FR", "en-US"]) // "2024-05-19T10:20:00"

package/dist/plain/parse/parseDateTimeWithPattern.js

@@ -9,9 +9,8 @@ import { DATE_TIME_PATTERN_FIELDS, parseValueWithPattern, } from "../../internal
  *   producer format — a CSV column, a legacy API field, a partially-typed
  *   form value — not for generating locale-correct output. For display,
  *   use `formatDateTime`/`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).
+ *   locale instead of hard-coding a field order (a token *formatter*,
+ *   the inverse of this function, is deliberately out of scope for GMT).
  * - Accepts the full combined date + time token set (unlike
  *   `parseDateWithPattern`/`parseTimeWithPattern`, which each reject the
  *   other's tokens).
@@ -42,10 +41,13 @@ import { DATE_TIME_PATTERN_FIELDS, parseValueWithPattern, } from "../../internal
  * | `GGGG` | era name (long) | locale | — | BCE label ⇒ final year = 1 − parsed year |
  * | `GG` | era name (short) | locale | — | same resolution |
  *
- * - 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.
+ * - Literal text follows the Unicode UTS #35 date format pattern rules.
+ *   Text in `'single quotes'` is a literal, letters included. Two
+ *   adjacent quotes `''` are one literal `'`, inside or outside quoted
+ *   text: `"yyyy''MM"` reads `"2024'03"`, and `"'o''clock'"` reads
+ *   `"o'clock"`. A quote that never closes makes the pattern malformed
+ *   (`""`). Any other character that is not a letter (`/ - , space :`,
+ *   digits and so on) is a literal with no quoting.
  * - `MMMM`/`MMM`/`EEEE`/`EEE`/`a`/`GGGG`/`GG` are locale-aware. If
  *   `locale` is omitted and the pattern uses any of them, GMT defaults
  *   to `"en-US"` rather than returning `""` for every caller who didn't
@@ -81,6 +83,7 @@ import { DATE_TIME_PATTERN_FIELDS, parseValueWithPattern, } from "../../internal
  *
  * @example parseDateTimeWithPattern("03/15/2024 14:30:00", "MM/dd/yyyy HH:mm:ss") // "2024-03-15T14:30:00"
  * @example parseDateTimeWithPattern("15-Mar-2024 02:30 PM", "dd-MMM-yyyy hh:mm a") // "2024-03-15T14:30:00"
+ * @example parseDateTimeWithPattern("Mar 15, '24 at 14:30", "MMM d, ''yy 'at' HH:mm") // "2024-03-15T14:30:00" ('' is one literal quote)
  * @example parseDateTimeWithPattern("02/31/2024 14:30:00", "MM/dd/yyyy HH:mm:ss") // "" (shape-valid, not a real date)
  * @example parseDateTimeWithPattern("not a date", "MM/dd/yyyy HH:mm:ss") // ""
  * @example parseDateTimeWithPattern("19 mai 2024 10:20", "d MMMM yyyy HH:mm", ["fr-FR", "en-US"]) // "2024-05-19T10:20:00"

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

@@ -7,9 +7,8 @@
  *   producer format — a CSV column, a legacy API field, a partially-typed
  *   form value — not for generating locale-correct output. For display,
  *   use `formatDate`/`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).
+ *   instead of hard-coding a field order (a token *formatter*, the
+ *   inverse of this function, is deliberately out of scope for GMT).
  * - `pattern` accepts only date-shaped tokens. A pattern containing a
  *   time-only token (`H h m s S a`) is malformed for this function and
  *   returns `""` — use `parseDateTimeWithPattern` for combined input.
@@ -30,10 +29,13 @@
  * | `GGGG` | era name (long) | locale | — | BCE label ⇒ final year = 1 − parsed year |
  * | `GG` | era name (short) | locale | — | same resolution |
  *
- * - 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.
+ * - Literal text follows the Unicode UTS #35 date format pattern rules.
+ *   Text in `'single quotes'` is a literal, letters included. Two
+ *   adjacent quotes `''` are one literal `'`, inside or outside quoted
+ *   text: `"yyyy''MM"` reads `"2024'03"`, and `"'o''clock'"` reads
+ *   `"o'clock"`. A quote that never closes makes the pattern malformed
+ *   (`""`). Any other character that is not a letter (`/ - , space`,
+ *   digits and so on) is a literal with no quoting.
  * - `MMMM`/`MMM`/`EEEE`/`EEE`/`GGGG`/`GG` are locale-aware. If `locale`
  *   is omitted and the pattern uses any of them, GMT defaults to
  *   `"en-US"` rather than returning `""` for every caller who didn't
@@ -62,6 +64,7 @@
  *
  * @example parseDateWithPattern("03/15/2024", "MM/dd/yyyy") // "2024-03-15"
  * @example parseDateWithPattern("15-Mar-2024", "dd-MMM-yyyy") // "2024-03-15"
+ * @example parseDateWithPattern("Mar 15, '24", "MMM d, ''yy") // "2024-03-15" ('' is one literal quote)
  * @example parseDateWithPattern("02/31/2024", "MM/dd/yyyy") // "" (shape-valid, not a real date)
  * @example parseDateWithPattern("14:30", "HH:mm") // "" (time token in a date-only pattern)
  * @example parseDateWithPattern("19 mai 2024", "d MMMM yyyy", ["fr-FR", "en-US"]) // "2024-05-19"

package/dist/plain/parse/parseDateWithPattern.js

@@ -9,9 +9,8 @@ import { DATE_PATTERN_FIELDS, parseValueWithPattern } from "../../internal/index
  *   producer format — a CSV column, a legacy API field, a partially-typed
  *   form value — not for generating locale-correct output. For display,
  *   use `formatDate`/`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).
+ *   instead of hard-coding a field order (a token *formatter*, the
+ *   inverse of this function, is deliberately out of scope for GMT).
  * - `pattern` accepts only date-shaped tokens. A pattern containing a
  *   time-only token (`H h m s S a`) is malformed for this function and
  *   returns `""` — use `parseDateTimeWithPattern` for combined input.
@@ -32,10 +31,13 @@ import { DATE_PATTERN_FIELDS, parseValueWithPattern } from "../../internal/index
  * | `GGGG` | era name (long) | locale | — | BCE label ⇒ final year = 1 − parsed year |
  * | `GG` | era name (short) | locale | — | same resolution |
  *
- * - 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.
+ * - Literal text follows the Unicode UTS #35 date format pattern rules.
+ *   Text in `'single quotes'` is a literal, letters included. Two
+ *   adjacent quotes `''` are one literal `'`, inside or outside quoted
+ *   text: `"yyyy''MM"` reads `"2024'03"`, and `"'o''clock'"` reads
+ *   `"o'clock"`. A quote that never closes makes the pattern malformed
+ *   (`""`). Any other character that is not a letter (`/ - , space`,
+ *   digits and so on) is a literal with no quoting.
  * - `MMMM`/`MMM`/`EEEE`/`EEE`/`GGGG`/`GG` are locale-aware. If `locale`
  *   is omitted and the pattern uses any of them, GMT defaults to
  *   `"en-US"` rather than returning `""` for every caller who didn't
@@ -64,6 +66,7 @@ import { DATE_PATTERN_FIELDS, parseValueWithPattern } from "../../internal/index
  *
  * @example parseDateWithPattern("03/15/2024", "MM/dd/yyyy") // "2024-03-15"
  * @example parseDateWithPattern("15-Mar-2024", "dd-MMM-yyyy") // "2024-03-15"
+ * @example parseDateWithPattern("Mar 15, '24", "MMM d, ''yy") // "2024-03-15" ('' is one literal quote)
  * @example parseDateWithPattern("02/31/2024", "MM/dd/yyyy") // "" (shape-valid, not a real date)
  * @example parseDateWithPattern("14:30", "HH:mm") // "" (time token in a date-only pattern)
  * @example parseDateWithPattern("19 mai 2024", "d MMMM yyyy", ["fr-FR", "en-US"]) // "2024-05-19"

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

@@ -6,9 +6,8 @@
  *   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).
+ *   instead of hard-coding a field order (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.
@@ -27,10 +26,13 @@
  * | `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.
+ * - Literal text follows the Unicode UTS #35 date format pattern rules.
+ *   Text in `'single quotes'` is a literal, letters included. Two
+ *   adjacent quotes `''` are one literal `'`, inside or outside quoted
+ *   text: `"HH''mm"` reads `"14'30"`, and `"'o''clock'"` reads
+ *   `"o'clock"`. A quote that never closes makes the pattern malformed
+ *   (`""`). Any other character that is not a letter (`: , space`,
+ *   digits and so on) is a literal with no quoting.
  * - `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.
@@ -51,6 +53,7 @@
  *
  * @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("2 o'clock PM", "h 'o''clock' a") // "14:00:00" ('' is one literal quote)
  * @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)
  * @example parseTimeWithPattern("午後 10:20", "a h:mm", ["ja-JP", "en-US"]) // "22:20:00"

package/dist/plain/parse/parseTimeWithPattern.js

@@ -8,9 +8,8 @@ import { parseValueWithPattern, TIME_PATTERN_FIELDS } from "../../internal/index
  *   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).
+ *   instead of hard-coding a field order (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.
@@ -29,10 +28,13 @@ import { parseValueWithPattern, TIME_PATTERN_FIELDS } from "../../internal/index
  * | `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.
+ * - Literal text follows the Unicode UTS #35 date format pattern rules.
+ *   Text in `'single quotes'` is a literal, letters included. Two
+ *   adjacent quotes `''` are one literal `'`, inside or outside quoted
+ *   text: `"HH''mm"` reads `"14'30"`, and `"'o''clock'"` reads
+ *   `"o'clock"`. A quote that never closes makes the pattern malformed
+ *   (`""`). Any other character that is not a letter (`: , space`,
+ *   digits and so on) is a literal with no quoting.
  * - `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.
@@ -53,6 +55,7 @@ import { parseValueWithPattern, TIME_PATTERN_FIELDS } from "../../internal/index
  *
  * @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("2 o'clock PM", "h 'o''clock' a") // "14:00:00" ('' is one literal quote)
  * @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)
  * @example parseTimeWithPattern("午後 10:20", "a h:mm", ["ja-JP", "en-US"]) // "22:20:00"

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

@@ -6,13 +6,13 @@ import { Temporal } from "@js-temporal/polyfill";
  * - Returns zero-padded string for month and day.
  * - `unit` accepts the singular or plural name of a Temporal unit (`"hour"` or `"hours"`), as Temporal
  *   does; `"dayOfWeek"` has no plural.
- * - `weekStartsOn: "sunday"` numbers weeks by UTS #35 (week 1 holds 1 January, so late-December
- *   days can be week 1); any value other than `"monday"` or `"sunday"` returns "".
+ * - `optionsArg` must be an object or omitted: `null` or any other primitive returns "", as
+ *   Temporal's GetOptionsObject rejects it.
  * - 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; a non-object value (such as `null`) is invalid
+ * @param optionsArg How weeks are numbered
  * @returns string representation of the requested unit or "" on invalid input
  *
  * @example parseUnitFromDate("2024-03-15", "year") // "2024"
@@ -26,5 +26,13 @@ import { Temporal } from "@js-temporal/polyfill";
  * @example parseUnitFromDate("2024-01-01", "week", { weekStartsOn: "sunday" }) // "1"
  */
 export declare function parseUnitFromDate(value: string, unit: Temporal.SmallestUnit<"year" | "month" | "day" | "week"> | "dayOfWeek", optionsArg?: {
+    /**
+     * The first day of the week, which sets how the `"week"` unit is numbered. `"monday"` gives the
+     * ISO 8601 week number, where week 1 holds the year's first Thursday; `"sunday"` gives the UTS
+     * #35 week number with a Sunday first day and one minimal day, where week 1 holds 1 January.
+     * Any other value returns `""`, whatever the unit.
+     *
+     * @defaultValue `"monday"`
+     */
     weekStartsOn?: "monday" | "sunday";
 }): string;

package/dist/plain/parse/parseUnitFromDate.js

@@ -11,13 +11,13 @@ import { isOptionsArgument } from "../../internal/isObject.js";
  * - Returns zero-padded string for month and day.
  * - `unit` accepts the singular or plural name of a Temporal unit (`"hour"` or `"hours"`), as Temporal
  *   does; `"dayOfWeek"` has no plural.
- * - `weekStartsOn: "sunday"` numbers weeks by UTS #35 (week 1 holds 1 January, so late-December
- *   days can be week 1); any value other than `"monday"` or `"sunday"` returns "".
+ * - `optionsArg` must be an object or omitted: `null` or any other primitive returns "", as
+ *   Temporal's GetOptionsObject rejects it.
  * - 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; a non-object value (such as `null`) is invalid
+ * @param optionsArg How weeks are numbered
  * @returns string representation of the requested unit or "" on invalid input
  *
  * @example parseUnitFromDate("2024-03-15", "year") // "2024"