@northguild/gmt 1.17.0 → 1.19.0

package/dist/unix/parse/parseMonthFromUnix.d.ts

@@ -3,11 +3,11 @@ import type { UnixUnit } from "../validate/index.js";
  * Return the month (1-12) from a unix epoch value.
  *
  * - Delegates to {@link parseUnitFromUnix} with unit "month".
- * - `value` is a safe integer or a digit string; an omitted `timeZone` is UTC.
+ * - `value` is a safe integer or a digit string.
  * - Returns "" for invalid input.
  *
  * @param value unix epoch in milliseconds or seconds: a safe integer, or a string of optionally negative ASCII digits
- * @param options optional: epochUnit ("seconds" | "milliseconds", singular accepted; default "milliseconds"), timeZone (IANA, or "local" for the system zone; default "UTC"; an unknown zone is invalid)
+ * @param options optional: how `value` is read and the zone its wall clock is read in
  * @returns Month (01-12) or "" on invalid input
  *
  * @example parseMonthFromUnix(1700000000000, { timeZone: "UTC" }) // "11"
@@ -16,6 +16,20 @@ import type { UnixUnit } from "../validate/index.js";
  * @example parseMonthFromUnix("") // "" (a blank string is not epoch 0)
  */
 export declare function parseMonthFromUnix(value: number | string, options?: {
+    /**
+     * The unit the epoch values are counted in: `"seconds"` or `"milliseconds"`, singular or
+     * plural. Any other value returns `""`.
+     *
+     * @defaultValue `"milliseconds"`
+     */
     epochUnit?: UnixUnit;
+    /**
+     * The time zone the wall-clock fields are read in: an IANA name, a UTC offset (a time zone
+     * identifier such as `+05:30`, `+0530` or `-08`, or a stored offset `±HH:MM[:SS]`, what
+     * `getTimeZoneOffset` returns), or `"local"` for the system time zone. An unknown zone returns
+     * `""`.
+     *
+     * @defaultValue `"UTC"`
+     */
     timeZone?: string;
 }): string;

package/dist/unix/parse/parseMonthFromUnix.js

@@ -4,11 +4,11 @@ import { isOptionsArgument } from "../../internal/isObject.js";
  * Return the month (1-12) from a unix epoch value.
  *
  * - Delegates to {@link parseUnitFromUnix} with unit "month".
- * - `value` is a safe integer or a digit string; an omitted `timeZone` is UTC.
+ * - `value` is a safe integer or a digit string.
  * - Returns "" for invalid input.
  *
  * @param value unix epoch in milliseconds or seconds: a safe integer, or a string of optionally negative ASCII digits
- * @param options optional: epochUnit ("seconds" | "milliseconds", singular accepted; default "milliseconds"), timeZone (IANA, or "local" for the system zone; default "UTC"; an unknown zone is invalid)
+ * @param options optional: how `value` is read and the zone its wall clock is read in
  * @returns Month (01-12) or "" on invalid input
  *
  * @example parseMonthFromUnix(1700000000000, { timeZone: "UTC" }) // "11"

package/dist/unix/parse/parseNanosecondFromUnix.d.ts

@@ -3,11 +3,11 @@ import type { UnixUnit } from "../validate/index.js";
  * Return the nanosecond (0-999) from a unix epoch value.
  *
  * - Delegates to {@link parseUnitFromUnix} with unit "nanosecond".
- * - `value` is a safe integer or a digit string; an omitted `timeZone` is UTC.
+ * - `value` is a safe integer or a digit string.
  * - Returns "" for invalid input.
  *
  * @param value unix epoch in milliseconds or seconds: a safe integer, or a string of optionally negative ASCII digits
- * @param options optional: epochUnit ("seconds" | "milliseconds", singular accepted; default "milliseconds"), timeZone (IANA, or "local" for the system zone; default "UTC"; an unknown zone is invalid)
+ * @param options optional: how `value` is read and the zone its wall clock is read in
  * @returns Nanosecond field (0-999), zero-padded to 3 digits ("000") as Temporal's `nanosecond` field, or "" on invalid input
  *
  * @example parseNanosecondFromUnix(1700000000000) // "000"
@@ -16,6 +16,20 @@ import type { UnixUnit } from "../validate/index.js";
  * @example parseNanosecondFromUnix("") // "" (a blank string is not epoch 0)
  */
 export declare function parseNanosecondFromUnix(value: number | string, options?: {
+    /**
+     * The unit the epoch values are counted in: `"seconds"` or `"milliseconds"`, singular or
+     * plural. Any other value returns `""`.
+     *
+     * @defaultValue `"milliseconds"`
+     */
     epochUnit?: UnixUnit;
+    /**
+     * The time zone the wall-clock fields are read in: an IANA name, a UTC offset (a time zone
+     * identifier such as `+05:30`, `+0530` or `-08`, or a stored offset `±HH:MM[:SS]`, what
+     * `getTimeZoneOffset` returns), or `"local"` for the system time zone. An unknown zone returns
+     * `""`.
+     *
+     * @defaultValue `"UTC"`
+     */
     timeZone?: string;
 }): string;

package/dist/unix/parse/parseNanosecondFromUnix.js

@@ -4,11 +4,11 @@ import { isOptionsArgument } from "../../internal/isObject.js";
  * Return the nanosecond (0-999) from a unix epoch value.
  *
  * - Delegates to {@link parseUnitFromUnix} with unit "nanosecond".
- * - `value` is a safe integer or a digit string; an omitted `timeZone` is UTC.
+ * - `value` is a safe integer or a digit string.
  * - Returns "" for invalid input.
  *
  * @param value unix epoch in milliseconds or seconds: a safe integer, or a string of optionally negative ASCII digits
- * @param options optional: epochUnit ("seconds" | "milliseconds", singular accepted; default "milliseconds"), timeZone (IANA, or "local" for the system zone; default "UTC"; an unknown zone is invalid)
+ * @param options optional: how `value` is read and the zone its wall clock is read in
  * @returns Nanosecond field (0-999), zero-padded to 3 digits ("000") as Temporal's `nanosecond` field, or "" on invalid input
  *
  * @example parseNanosecondFromUnix(1700000000000) // "000"

package/dist/unix/parse/parseSecondFromUnix.d.ts

@@ -3,11 +3,11 @@ import type { UnixUnit } from "../validate/index.js";
  * Return the second (0-59) from a unix epoch value.
  *
  * - Delegates to {@link parseUnitFromUnix} with unit "second".
- * - `value` is a safe integer or a digit string; an omitted `timeZone` is UTC.
+ * - `value` is a safe integer or a digit string.
  * - Returns "" for invalid input.
  *
  * @param value unix epoch in milliseconds or seconds: a safe integer, or a string of optionally negative ASCII digits
- * @param options optional: epochUnit ("seconds" | "milliseconds", singular accepted; default "milliseconds"), timeZone (IANA, or "local" for the system zone; default "UTC"; an unknown zone is invalid)
+ * @param options optional: how `value` is read and the zone its wall clock is read in
  * @returns Second (00-59) or "" on invalid input
  *
  * @example parseSecondFromUnix(1700000000000, { timeZone: "UTC" }) // "20"
@@ -15,6 +15,20 @@ import type { UnixUnit } from "../validate/index.js";
  * @example parseSecondFromUnix("") // "" (a blank string is not epoch 0)
  */
 export declare function parseSecondFromUnix(value: number | string, options?: {
+    /**
+     * The unit the epoch values are counted in: `"seconds"` or `"milliseconds"`, singular or
+     * plural. Any other value returns `""`.
+     *
+     * @defaultValue `"milliseconds"`
+     */
     epochUnit?: UnixUnit;
+    /**
+     * The time zone the wall-clock fields are read in: an IANA name, a UTC offset (a time zone
+     * identifier such as `+05:30`, `+0530` or `-08`, or a stored offset `±HH:MM[:SS]`, what
+     * `getTimeZoneOffset` returns), or `"local"` for the system time zone. An unknown zone returns
+     * `""`.
+     *
+     * @defaultValue `"UTC"`
+     */
     timeZone?: string;
 }): string;

package/dist/unix/parse/parseSecondFromUnix.js

@@ -4,11 +4,11 @@ import { isOptionsArgument } from "../../internal/isObject.js";
  * Return the second (0-59) from a unix epoch value.
  *
  * - Delegates to {@link parseUnitFromUnix} with unit "second".
- * - `value` is a safe integer or a digit string; an omitted `timeZone` is UTC.
+ * - `value` is a safe integer or a digit string.
  * - Returns "" for invalid input.
  *
  * @param value unix epoch in milliseconds or seconds: a safe integer, or a string of optionally negative ASCII digits
- * @param options optional: epochUnit ("seconds" | "milliseconds", singular accepted; default "milliseconds"), timeZone (IANA, or "local" for the system zone; default "UTC"; an unknown zone is invalid)
+ * @param options optional: how `value` is read and the zone its wall clock is read in
  * @returns Second (00-59) or "" on invalid input
  *
  * @example parseSecondFromUnix(1700000000000, { timeZone: "UTC" }) // "20"

package/dist/unix/parse/parseTimeFromUnix.d.ts

@@ -3,11 +3,10 @@ import type { UnixUnit } from "../validate/index.js";
  * Extract the time portion from a unix epoch value.
  *
  * - Converts to ZonedDateTime then extracts the PlainTime.
- * - Uses UTC if `timeZone` is not specified; `"local"` is the system time zone.
  * - Returns "" for invalid input.
  *
  * @param value unix epoch in milliseconds or seconds: a safe integer, or a string of optionally negative ASCII digits
- * @param options optional: epochUnit ("seconds" | "milliseconds", singular accepted; default "milliseconds"), timeZone (IANA, or "local" for the system zone; default "UTC"; an unknown zone is invalid)
+ * @param options optional: how `value` is read and the zone its wall clock is read in
  * @returns ISO time string (e.g., "14:30:45") or "" on invalid input
  *
  * @example parseTimeFromUnix(1700000000000, { timeZone: "UTC" }) // "22:13:20"
@@ -15,8 +14,23 @@ import type { UnixUnit } from "../validate/index.js";
  * @example parseTimeFromUnix(-86400, { epochUnit: "seconds", timeZone: "UTC" }) // "00:00:00"
  * @example parseTimeFromUnix("1700000000", { epochUnit: "second" }) // "22:13:20" (digit string, UTC by default)
  * @example parseTimeFromUnix(1.5) // "" (not an integer epoch)
+ * @example parseTimeFromUnix(45870000, { timeZone: "-00:44:30" }) // "12:00:00" (a stored offset with seconds)
  */
 export declare function parseTimeFromUnix(value: number | string, options?: {
+    /**
+     * The unit the epoch values are counted in: `"seconds"` or `"milliseconds"`, singular or
+     * plural. Any other value returns `""`.
+     *
+     * @defaultValue `"milliseconds"`
+     */
     epochUnit?: UnixUnit;
+    /**
+     * The time zone the wall-clock fields are read in: an IANA name, a UTC offset (a time zone
+     * identifier such as `+05:30`, `+0530` or `-08`, or a stored offset `±HH:MM[:SS]`, what
+     * `getTimeZoneOffset` returns), or `"local"` for the system time zone. An unknown zone returns
+     * `""`.
+     *
+     * @defaultValue `"UTC"`
+     */
     timeZone?: string;
 }): string;

package/dist/unix/parse/parseTimeFromUnix.js

@@ -1,14 +1,13 @@
-import { unixZonedDateTime } from "../../internal/unixZonedDateTime.js";
+import { unixWallClock } from "../../internal/unixWallClock.js";
 import { isOptionsArgument } from "../../internal/isObject.js";
 /**
  * Extract the time portion from a unix epoch value.
  *
  * - Converts to ZonedDateTime then extracts the PlainTime.
- * - Uses UTC if `timeZone` is not specified; `"local"` is the system time zone.
  * - Returns "" for invalid input.
  *
  * @param value unix epoch in milliseconds or seconds: a safe integer, or a string of optionally negative ASCII digits
- * @param options optional: epochUnit ("seconds" | "milliseconds", singular accepted; default "milliseconds"), timeZone (IANA, or "local" for the system zone; default "UTC"; an unknown zone is invalid)
+ * @param options optional: how `value` is read and the zone its wall clock is read in
  * @returns ISO time string (e.g., "14:30:45") or "" on invalid input
  *
  * @example parseTimeFromUnix(1700000000000, { timeZone: "UTC" }) // "22:13:20"
@@ -16,14 +15,15 @@ import { isOptionsArgument } from "../../internal/isObject.js";
  * @example parseTimeFromUnix(-86400, { epochUnit: "seconds", timeZone: "UTC" }) // "00:00:00"
  * @example parseTimeFromUnix("1700000000", { epochUnit: "second" }) // "22:13:20" (digit string, UTC by default)
  * @example parseTimeFromUnix(1.5) // "" (not an integer epoch)
+ * @example parseTimeFromUnix(45870000, { timeZone: "-00:44:30" }) // "12:00:00" (a stored offset with seconds)
  */
 export function parseTimeFromUnix(value, options) {
     try {
         if (!isOptionsArgument(options)) {
             return "";
         }
-        const zdt = unixZonedDateTime(value, options);
-        return zdt === null ? "" : zdt.toPlainTime().toString();
+        const wallClock = unixWallClock(value, options);
+        return wallClock === null ? "" : wallClock.toPlainTime().toString();
     }
     catch {
         // Never throws (Core Rule 3): a hostile

package/dist/unix/parse/parseUnitFromUnix.d.ts

@@ -8,7 +8,7 @@ import type { UnixUnit } from "../validate/index.js";
  *
  * | Member | Description |
  * | --- | --- |
- * | `year` | Full year, no padding (e.g. `2024`). |
+ * | `year` | Four digits (e.g. `2024`, `0005`); a sign and six digits outside 0000–9999 (e.g. `+010000`). |
  * | `month` | Zero-padded 2 (e.g. `03`). |
  * | `week` | Week-of-year, 1–53: ISO 8601 for `weekStartsOn: "monday"`, UTS #35 (minimal days 1) for `"sunday"`, so late-December days can be week 1. |
  * | `day` | Zero-padded 2. |
@@ -29,18 +29,20 @@ export type PlainNowUnit = "year" | "month" | "week" | "day" | "dayOfWeek" | "ho
  * Extract a unit from a unix epoch value.
  *
  * - Valid units: "year", "month", "week", "day", "dayOfWeek", "hour", "minute", "second", "millisecond", "microsecond", "nanosecond". Temporal units may also be plural ("hours").
- * - `value` is a safe integer or a string of optionally negative ASCII digits; an omitted `timeZone` is UTC and `"local"` is the system zone.
+ * - `value` is a safe integer or a string of optionally negative ASCII digits.
  * - `microsecond` and `nanosecond` are the 0–999 Temporal fields, zero-padded to 3 digits.
  * - Converts to ZonedDateTime then extracts the unit.
- * - `weekStartsOn` other than `"monday"` or `"sunday"` returns "", for every unit.
  * - Returns "" for invalid input.
+ * - The `"year"` unit is written as Temporal writes a year: four digits (`"2024"`, `"0005"`), or a
+ *   sign and six digits outside 0000–9999 (`"+010000"`, `"-000005"`).
  *
  * @param value unix epoch in milliseconds or seconds: a safe integer, or a string of optionally negative ASCII digits
  * @param unit unit to extract (e.g. "year", "month", "hour")
- * @param options optional: epochUnit ("seconds" | "milliseconds", singular accepted; default "milliseconds"), timeZone (IANA, or "local" for the system zone; default "UTC"; an unknown zone is invalid), weekStartsOn ("monday" | "sunday"); a non-object value (such as `null`) is invalid
+ * @param options optional: how `value` is read, the zone its wall clock is read in and the first day of the week; a non-object value (such as `null`) is invalid
  * @returns extracted unit value as string, or "" on invalid input
  *
  * @example parseUnitFromUnix(1700000000000, "year") // "2023"
+ * @example parseUnitFromUnix(-61996320000000, "year") // "0005" (1 June of year 5)
  * @example parseUnitFromUnix(1700000000, "hour", { epochUnit: "seconds", timeZone: "UTC" }) // "22"
  * @example parseUnitFromUnix(1704067200000, "week", { timeZone: "UTC" }) // "1"
  * @example parseUnitFromUnix(1704067200000, "week", { weekStartsOn: "sunday", timeZone: "UTC" }) // "1"
@@ -48,9 +50,32 @@ export type PlainNowUnit = "year" | "month" | "week" | "day" | "dayOfWeek" | "ho
  * @example parseUnitFromUnix("1709217045123", "hours") // "14" (digit string, plural unit, UTC by default)
  * @example parseUnitFromUnix(1709217045123, "nanosecond") // "000"
  * @example parseUnitFromUnix("", "year") // "" (a blank string is not epoch 0)
+ * @example parseUnitFromUnix(45870000, "minute", { timeZone: "-00:44:30" }) // "00" (a stored offset with seconds)
  */
 export declare function parseUnitFromUnix(value: number | string, unit: PlainNowUnit | Temporal.PluralUnit<Temporal.DateTimeUnit>, options?: {
+    /**
+     * The unit the epoch values are counted in: `"seconds"` or `"milliseconds"`, singular or
+     * plural. Any other value returns `""`.
+     *
+     * @defaultValue `"milliseconds"`
+     */
     epochUnit?: UnixUnit;
+    /**
+     * The time zone the wall-clock fields are read in: an IANA name, a UTC offset (a time zone
+     * identifier such as `+05:30`, `+0530` or `-08`, or a stored offset `±HH:MM[:SS]`, what
+     * `getTimeZoneOffset` returns), or `"local"` for the system time zone. An unknown zone returns
+     * `""`.
+     *
+     * @defaultValue `"UTC"`
+     */
     timeZone?: string;
+    /**
+     * 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/unix/parse/parseUnitFromUnix.js

@@ -1,24 +1,27 @@
 import { resolveDateTimeUnit } from "../../internal/resolveDateTimeUnit.js";
 import { resolveWeekStartsOn } from "../../internal/resolveWeekStartsOn.js";
-import { unixZonedDateTime } from "../../internal/unixZonedDateTime.js";
+import { unixWallClock } from "../../internal/unixWallClock.js";
 import { getWeekNumber } from "../../plain/calculate/getWeekNumber.js";
 import { isOptionsArgument } from "../../internal/isObject.js";
+import { isoYearString } from "../../internal/isoYearString.js";
 /**
  * Extract a unit from a unix epoch value.
  *
  * - Valid units: "year", "month", "week", "day", "dayOfWeek", "hour", "minute", "second", "millisecond", "microsecond", "nanosecond". Temporal units may also be plural ("hours").
- * - `value` is a safe integer or a string of optionally negative ASCII digits; an omitted `timeZone` is UTC and `"local"` is the system zone.
+ * - `value` is a safe integer or a string of optionally negative ASCII digits.
  * - `microsecond` and `nanosecond` are the 0–999 Temporal fields, zero-padded to 3 digits.
  * - Converts to ZonedDateTime then extracts the unit.
- * - `weekStartsOn` other than `"monday"` or `"sunday"` returns "", for every unit.
  * - Returns "" for invalid input.
+ * - The `"year"` unit is written as Temporal writes a year: four digits (`"2024"`, `"0005"`), or a
+ *   sign and six digits outside 0000–9999 (`"+010000"`, `"-000005"`).
  *
  * @param value unix epoch in milliseconds or seconds: a safe integer, or a string of optionally negative ASCII digits
  * @param unit unit to extract (e.g. "year", "month", "hour")
- * @param options optional: epochUnit ("seconds" | "milliseconds", singular accepted; default "milliseconds"), timeZone (IANA, or "local" for the system zone; default "UTC"; an unknown zone is invalid), weekStartsOn ("monday" | "sunday"); a non-object value (such as `null`) is invalid
+ * @param options optional: how `value` is read, the zone its wall clock is read in and the first day of the week; a non-object value (such as `null`) is invalid
  * @returns extracted unit value as string, or "" on invalid input
  *
  * @example parseUnitFromUnix(1700000000000, "year") // "2023"
+ * @example parseUnitFromUnix(-61996320000000, "year") // "0005" (1 June of year 5)
  * @example parseUnitFromUnix(1700000000, "hour", { epochUnit: "seconds", timeZone: "UTC" }) // "22"
  * @example parseUnitFromUnix(1704067200000, "week", { timeZone: "UTC" }) // "1"
  * @example parseUnitFromUnix(1704067200000, "week", { weekStartsOn: "sunday", timeZone: "UTC" }) // "1"
@@ -26,6 +29,7 @@ import { isOptionsArgument } from "../../internal/isObject.js";
  * @example parseUnitFromUnix("1709217045123", "hours") // "14" (digit string, plural unit, UTC by default)
  * @example parseUnitFromUnix(1709217045123, "nanosecond") // "000"
  * @example parseUnitFromUnix("", "year") // "" (a blank string is not epoch 0)
+ * @example parseUnitFromUnix(45870000, "minute", { timeZone: "-00:44:30" }) // "00" (a stored offset with seconds)
  */
 export function parseUnitFromUnix(value, unit, options) {
     try {
@@ -33,36 +37,38 @@ export function parseUnitFromUnix(value, unit, options) {
         if (!isOptionsArgument(options)) {
             return "";
         }
-        const zdt = unixZonedDateTime(value, options);
+        const wallClock = unixWallClock(value, options);
         const weekStartsOn = resolveWeekStartsOn(options?.weekStartsOn);
-        if (zdt === null || typeof unit !== "string" || weekStartsOn === null) {
+        if (wallClock === null ||
+            typeof unit !== "string" ||
+            weekStartsOn === null) {
             return "";
         }
         try {
             switch (resolveDateTimeUnit(unit)) {
                 case "year":
-                    return zdt.year.toString();
+                    return isoYearString(wallClock.year);
                 case "month":
-                    return zdt.month.toString().padStart(2, "0");
+                    return wallClock.month.toString().padStart(2, "0");
                 case "week": {
-                    return (getWeekNumber(zdt.toPlainDate().toString(), weekStartsOn) ?? 0).toString();
+                    return (getWeekNumber(wallClock.toPlainDate().toString(), weekStartsOn) ?? 0).toString();
                 }
                 case "day":
-                    return zdt.day.toString().padStart(2, "0");
+                    return wallClock.day.toString().padStart(2, "0");
                 case "dayOfWeek":
-                    return zdt.dayOfWeek.toString();
+                    return wallClock.dayOfWeek.toString();
                 case "hour":
-                    return zdt.hour.toString().padStart(2, "0");
+                    return wallClock.hour.toString().padStart(2, "0");
                 case "minute":
-                    return zdt.minute.toString().padStart(2, "0");
+                    return wallClock.minute.toString().padStart(2, "0");
                 case "second":
-                    return zdt.second.toString().padStart(2, "0");
+                    return wallClock.second.toString().padStart(2, "0");
                 case "millisecond":
-                    return zdt.millisecond.toString().padStart(3, "0");
+                    return wallClock.millisecond.toString().padStart(3, "0");
                 case "microsecond":
-                    return zdt.microsecond.toString().padStart(3, "0");
+                    return wallClock.microsecond.toString().padStart(3, "0");
                 case "nanosecond":
-                    return zdt.nanosecond.toString().padStart(3, "0");
+                    return wallClock.nanosecond.toString().padStart(3, "0");
                 default:
                     return "";
             }

package/dist/unix/parse/parseWeekFromUnix.d.ts

@@ -2,16 +2,12 @@ import type { UnixUnit } from "../validate/index.js";
 /**
  * Return the week number from a unix epoch value.
  *
- * - `"monday"` (default) is the ISO 8601 week of the week-year: week 1 is the week containing the
- *   first Thursday, so late-December days can be week 1 of the next year. The result is 1–53.
- * - `"sunday"` is the UTS #35 week of the week-year with a Sunday first day and minimal days 1:
- *   week 1 is the Sunday-first week holding 1 January, so late-December days can be week 1 of the
- *   next year. The result is 1–53 — see `getWeekNumber`.
- * - `weekStartsOn` other than `"monday"` or `"sunday"` returns null.
+ * - Returns the week of the week-year, 1–53, so late-December days can be week 1 of the next
+ *   year — see `getWeekNumber`.
  * - Returns null for invalid input.
  *
  * @param value unix epoch in milliseconds or seconds: a safe integer, or a string of optionally negative ASCII digits
- * @param options optional: epochUnit ("seconds" | "milliseconds", singular accepted; default "milliseconds"), timeZone (IANA, or "local" for the system zone; default "UTC"; an unknown zone is invalid), weekStartsOn ("monday" | "sunday"); a non-object value (such as `null`) is invalid
+ * @param options optional: how `value` is read, the zone its date is read in and the first day of the week; a non-object value (such as `null`) is invalid
  * @returns Week number (1-53 for "monday" and for "sunday") or null on invalid input
  *
  * @example parseWeekFromUnix(1704067200000, { timeZone: "UTC" }) // 1
@@ -22,7 +18,28 @@ import type { UnixUnit } from "../validate/index.js";
  * @example parseWeekFromUnix(1735646400000, { weekStartsOn: "sunday", timeZone: "UTC" }) // 1 (2024-12-31T12:00:00Z; its Sunday-first week holds 1 January 2025)
  */
 export declare function parseWeekFromUnix(value: number | string, options?: {
+    /**
+     * The unit the epoch values are counted in: `"seconds"` or `"milliseconds"`, singular or
+     * plural. Any other value returns `null`.
+     *
+     * @defaultValue `"milliseconds"`
+     */
     epochUnit?: UnixUnit;
+    /**
+     * The time zone the date is read in: an IANA name, a UTC offset (a time zone identifier such as
+     * `+05:30`, `+0530` or `-08`, or a stored offset `±HH:MM[:SS]`, what `getTimeZoneOffset`
+     * returns), or `"local"` for the system time zone. An unknown zone returns `null`.
+     *
+     * @defaultValue `"UTC"`
+     */
     timeZone?: string;
+    /**
+     * The first day of the week, which sets how the week 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 `null`.
+     *
+     * @defaultValue `"monday"`
+     */
     weekStartsOn?: "monday" | "sunday";
 }): number | null;

package/dist/unix/parse/parseWeekFromUnix.js

@@ -1,20 +1,16 @@
 import { getWeekNumber } from "../../plain/calculate/getWeekNumber.js";
 import { resolveWeekStartsOn } from "../../internal/resolveWeekStartsOn.js";
-import { unixZonedDateTime } from "../../internal/unixZonedDateTime.js";
+import { unixWallClock } from "../../internal/unixWallClock.js";
 import { isOptionsArgument } from "../../internal/isObject.js";
 /**
  * Return the week number from a unix epoch value.
  *
- * - `"monday"` (default) is the ISO 8601 week of the week-year: week 1 is the week containing the
- *   first Thursday, so late-December days can be week 1 of the next year. The result is 1–53.
- * - `"sunday"` is the UTS #35 week of the week-year with a Sunday first day and minimal days 1:
- *   week 1 is the Sunday-first week holding 1 January, so late-December days can be week 1 of the
- *   next year. The result is 1–53 — see `getWeekNumber`.
- * - `weekStartsOn` other than `"monday"` or `"sunday"` returns null.
+ * - Returns the week of the week-year, 1–53, so late-December days can be week 1 of the next
+ *   year — see `getWeekNumber`.
  * - Returns null for invalid input.
  *
  * @param value unix epoch in milliseconds or seconds: a safe integer, or a string of optionally negative ASCII digits
- * @param options optional: epochUnit ("seconds" | "milliseconds", singular accepted; default "milliseconds"), timeZone (IANA, or "local" for the system zone; default "UTC"; an unknown zone is invalid), weekStartsOn ("monday" | "sunday"); a non-object value (such as `null`) is invalid
+ * @param options optional: how `value` is read, the zone its date is read in and the first day of the week; a non-object value (such as `null`) is invalid
  * @returns Week number (1-53 for "monday" and for "sunday") or null on invalid input
  *
  * @example parseWeekFromUnix(1704067200000, { timeZone: "UTC" }) // 1
@@ -30,12 +26,12 @@ export function parseWeekFromUnix(value, options) {
         if (!isOptionsArgument(options)) {
             return null;
         }
-        const zdt = unixZonedDateTime(value, options);
+        const wallClock = unixWallClock(value, options);
         const weekStartsOn = resolveWeekStartsOn(options?.weekStartsOn);
-        if (zdt === null || weekStartsOn === null)
+        if (wallClock === null || weekStartsOn === null)
             return null;
         try {
-            return getWeekNumber(zdt.toPlainDate().toString(), weekStartsOn);
+            return getWeekNumber(wallClock.toPlainDate().toString(), weekStartsOn);
         }
         catch {
             return null;

package/dist/unix/parse/parseYearFromUnix.d.ts

@@ -3,19 +3,36 @@ import type { UnixUnit } from "../validate/index.js";
  * Return the year from a unix epoch value.
  *
  * - Delegates to {@link parseUnitFromUnix} with unit "year".
- * - `value` is a safe integer or a digit string; an omitted `timeZone` is UTC.
+ * - `value` is a safe integer or a digit string.
  * - Returns "" for invalid input.
+ * - The year is written as Temporal writes it: four digits (`"2024"`, `"0005"`), or a sign and six
+ *   digits outside 0000–9999 (`"+010000"`, `"-000005"`).
  *
  * @param value unix epoch in milliseconds or seconds: a safe integer, or a string of optionally negative ASCII digits
- * @param options optional: epochUnit ("seconds" | "milliseconds", singular accepted; default "milliseconds"), timeZone (IANA, or "local" for the system zone; default "UTC"; an unknown zone is invalid)
- * @returns Year (YYYY) or "" on invalid input
+ * @param options optional: how `value` is read and the zone its wall clock is read in
+ * @returns the year as four digits, or a sign and six digits outside 0000–9999, or "" on invalid input
  *
  * @example parseYearFromUnix(1700000000000) // "2023"
+ * @example parseYearFromUnix(-61996320000000) // "0005" (1 June of year 5)
  * @example parseYearFromUnix(1704067200000, { epochUnit: "milliseconds", timeZone: "UTC" }) // "2024"
  * @example parseYearFromUnix(-86400, { epochUnit: "seconds" }) // "1969"
  * @example parseYearFromUnix("") // "" (a blank string is not epoch 0)
  */
 export declare function parseYearFromUnix(value: number | string, options?: {
+    /**
+     * The unit the epoch values are counted in: `"seconds"` or `"milliseconds"`, singular or
+     * plural. Any other value returns `""`.
+     *
+     * @defaultValue `"milliseconds"`
+     */
     epochUnit?: UnixUnit;
+    /**
+     * The time zone the wall-clock fields are read in: an IANA name, a UTC offset (a time zone
+     * identifier such as `+05:30`, `+0530` or `-08`, or a stored offset `±HH:MM[:SS]`, what
+     * `getTimeZoneOffset` returns), or `"local"` for the system time zone. An unknown zone returns
+     * `""`.
+     *
+     * @defaultValue `"UTC"`
+     */
     timeZone?: string;
 }): string;

package/dist/unix/parse/parseYearFromUnix.js

@@ -4,14 +4,17 @@ import { isOptionsArgument } from "../../internal/isObject.js";
  * Return the year from a unix epoch value.
  *
  * - Delegates to {@link parseUnitFromUnix} with unit "year".
- * - `value` is a safe integer or a digit string; an omitted `timeZone` is UTC.
+ * - `value` is a safe integer or a digit string.
  * - Returns "" for invalid input.
+ * - The year is written as Temporal writes it: four digits (`"2024"`, `"0005"`), or a sign and six
+ *   digits outside 0000–9999 (`"+010000"`, `"-000005"`).
  *
  * @param value unix epoch in milliseconds or seconds: a safe integer, or a string of optionally negative ASCII digits
- * @param options optional: epochUnit ("seconds" | "milliseconds", singular accepted; default "milliseconds"), timeZone (IANA, or "local" for the system zone; default "UTC"; an unknown zone is invalid)
- * @returns Year (YYYY) or "" on invalid input
+ * @param options optional: how `value` is read and the zone its wall clock is read in
+ * @returns the year as four digits, or a sign and six digits outside 0000–9999, or "" on invalid input
  *
  * @example parseYearFromUnix(1700000000000) // "2023"
+ * @example parseYearFromUnix(-61996320000000) // "0005" (1 June of year 5)
  * @example parseYearFromUnix(1704067200000, { epochUnit: "milliseconds", timeZone: "UTC" }) // "2024"
  * @example parseYearFromUnix(-86400, { epochUnit: "seconds" }) // "1969"
  * @example parseYearFromUnix("") // "" (a blank string is not epoch 0)

package/dist/unix/validate/isValidUnixRange.d.ts

@@ -7,11 +7,8 @@
  * - Fractional values, `NaN`, `±Infinity` and anything beyond ±(2^53 − 1) return `false`.
  * - Strings with whitespace, `+`, a decimal point, an exponent or hex digits return `false`, and an
  *   empty string is not epoch 0.
- * - Equal `value1 === value2` is valid only when `options.allowEqual` is true.
  *
- * @param value1 first Unix epoch value (seconds or milliseconds)
- * @param value2 second Unix epoch value (seconds or milliseconds)
- * @param options optional allowEqual flag
+ * @param props the two epoch values and the settings for the check
  * @returns boolean indicating whether the Unix range is valid
  *
  * @example isValidUnixRange({ value1: 0, value2: 1700000000 }) // true
@@ -22,9 +19,28 @@
  * @example isValidUnixRange({ value1: "0", value2: "1e3" }) // false (exponent notation is not an epoch)
  */
 export declare function isValidUnixRange(props: {
+    /**
+     * The start of the range: a Unix epoch in seconds or milliseconds, as a safe integer or a digit
+     * string.
+     */
     value1: number | string;
+    /**
+     * The end of the range, in the same form and unit as `value1`.
+     */
     value2: number | string;
+    /**
+     * The settings for the comparison. It must be an object or omitted; any other value, `null`
+     * included, returns `false`.
+     *
+     * @defaultValue None. Equal values are not a valid range.
+     */
     options?: {
+        /**
+         * Whether `value1` equal to `value2` is a valid range. `false` requires `value1` to be
+         * before `value2`.
+         *
+         * @defaultValue `false`
+         */
         allowEqual?: boolean;
     };
 }): boolean;

package/dist/unix/validate/isValidUnixRange.js

@@ -8,11 +8,8 @@ import { isObject, isOptionsArgument, parseUnixEpochValue, } from "../../interna
  * - Fractional values, `NaN`, `±Infinity` and anything beyond ±(2^53 − 1) return `false`.
  * - Strings with whitespace, `+`, a decimal point, an exponent or hex digits return `false`, and an
  *   empty string is not epoch 0.
- * - Equal `value1 === value2` is valid only when `options.allowEqual` is true.
  *
- * @param value1 first Unix epoch value (seconds or milliseconds)
- * @param value2 second Unix epoch value (seconds or milliseconds)
- * @param options optional allowEqual flag
+ * @param props the two epoch values and the settings for the check
  * @returns boolean indicating whether the Unix range is valid
  *
  * @example isValidUnixRange({ value1: 0, value2: 1700000000 }) // true

package/dist/unix/validate/isValidUnixUnit.d.ts

@@ -15,7 +15,7 @@
  * import { isValidUnixUnit } from "@northguild/gmt/unix";
  * isValidUnixUnit("milliseconds"); // true
  */
-export type UnixUnit = "seconds" | "second" | "milliseconds" | "millisecond";
+export type UnixUnit = "seconds" | "milliseconds" | "second" | "millisecond";
 /**
  * Return true when `unit` is a valid UnixUnit.
  *