mdtg 4.2.2 → 5.0.1

package/README.md

@@ -73,6 +73,47 @@ Invalid calendar dates and times, such as `310224Zfeb24` or `126155Z`, throw a
 `referenceDate` is an optional valid `Date` used only for short values that omit
 the month and year. If omitted, the current UTC month and year are used.
 
+#### Temporal API
+
+`formatTemporalMDTG` and `parseTemporalMDTG` provide a separate API for the
+native Temporal objects. They require a runtime with `globalThis.Temporal`
+(available by default in Node.js 26 and newer); the existing `Date` API remains
+available on older runtimes. Calling either Temporal function when Temporal is
+unavailable throws an `Error`.
+
+`formatTemporalMDTG` accepts `Temporal.PlainDate`, `Temporal.PlainDateTime`, or
+`Temporal.ZonedDateTime`. A `PlainDate` is formatted at midnight UTC. A
+`PlainDateTime` uses the `timezone` option (a NATO letter, defaulting to `Z`)
+for its wall-clock time. A `ZonedDateTime` uses its own wall-clock time and
+offset; the offset must be a whole number of hours supported by an MDTG
+timezone letter.
+
+```js
+import { formatTemporalMDTG, parseTemporalMDTG } from "mdtg";
+
+formatTemporalMDTG(Temporal.PlainDate.from("2024-08-12"));
+// "12000000Zaug24"
+
+formatTemporalMDTG(Temporal.PlainDateTime.from("2024-08-12T11:55:30"), {
+  timezone: "A",
+});
+// "12115530Aaug24"
+
+parseTemporalMDTG("121155Aaug24", { type: "zonedDateTime" }).toString();
+// "2024-08-12T11:55:00+01:00[+01:00]"
+
+parseTemporalMDTG("121155Zaug24", { type: "plainDate" }).toString();
+// "2024-08-12"
+```
+
+Parsing requires `type`: `"plainDate"`, `"plainDateTime"`, or
+`"zonedDateTime"`. The returned `PlainDate` discards the MDTG time and zone;
+`PlainDateTime` retains the wall-clock date/time but discards the zone. A
+`ZonedDateTime` uses the fixed offset represented by the MDTG timezone letter.
+For short values, `referenceDate` can be a `Temporal.PlainDate`; if omitted,
+the current UTC month and year are used. Temporal-specific tests are skipped
+when the runtime does not provide `globalThis.Temporal`.
+
 #### Format checks
 
 `isShortFormat`, `isStandardFormat`, and `isExtendedFormat` check whether a string

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mdtg",
-  "version": "4.2.2",
+  "version": "5.0.1",
   "main": "src/index.js",
   "types": "src/index.d.ts",
   "type": "module",
@@ -40,12 +40,12 @@
   "description": "This package offers you methods to convert Date Objects to military date time group and vice versa",
   "devDependencies": {
     "@amiceli/vitest-cucumber": "8.0.0",
-    "@biomejs/biome": "2.6.4",
+    "@biomejs/biome": "2.6.6",
     "@systemfsoftware/stryker-js": "17.0.2",
     "@systemfsoftware/stryker-js-vitest-runner": "8.1.1",
     "@vitest/coverage-v8": "5.1.0",
     "fast-check": "4.10.2",
-    "knip": "6.44.1",
+    "knip": "6.44.2",
     "prettier": "3.9.10",
     "vitest": "5.1.0"
   }

package/src/index.d.ts

@@ -1,26 +1,47 @@
 type MDTGFormat = "short" | "extended" | "standard";
+type MDTGTemporalType = "plainDate" | "plainDateTime" | "zonedDateTime";
 
 declare function formatMDTG(
   date?: Date,
   options?: { form?: MDTGFormat; timezone?: string },
 ): string;
 
+declare function formatTemporalMDTG(
+  date: Temporal.PlainDate | Temporal.PlainDateTime | Temporal.ZonedDateTime,
+  options?: { form?: MDTGFormat; timezone?: string },
+): string;
+
 declare function isValidMDTG(mdtg: string, options?: { referenceDate?: Date }): boolean;
 declare function parseMDTG(mdtg: string, options?: { referenceDate?: Date }): Date;
 
+declare function parseTemporalMDTG(
+  mdtg: string,
+  options: { type: "plainDate"; referenceDate?: Temporal.PlainDate },
+): Temporal.PlainDate;
+declare function parseTemporalMDTG(
+  mdtg: string,
+  options: { type: "plainDateTime"; referenceDate?: Temporal.PlainDate },
+): Temporal.PlainDateTime;
+declare function parseTemporalMDTG(
+  mdtg: string,
+  options: { type: "zonedDateTime"; referenceDate?: Temporal.PlainDate },
+): Temporal.ZonedDateTime;
+
 declare function isExtendedFormat(mdtg: string): boolean;
 declare function isMDTG(mdtg: string): boolean;
 declare function isShortFormat(mdtg: string): boolean;
 declare function isStandardFormat(mdtg: string): boolean;
 
-export type { MDTGFormat };
+export type { MDTGFormat, MDTGTemporalType };
 
 export {
   formatMDTG,
+  formatTemporalMDTG,
   isExtendedFormat,
   isMDTG,
   isShortFormat,
   isStandardFormat,
   isValidMDTG,
   parseMDTG,
+  parseTemporalMDTG,
 };

package/src/index.js

@@ -1,5 +1,6 @@
 export { formatMDTG } from "./format.js";
 export { isValidMDTG, parseMDTG } from "./parse.js";
+export { formatTemporalMDTG, parseTemporalMDTG } from "./temporal.js";
 export {
   isExtendedFormat,
   isMDTG,

package/src/temporal.js

@@ -0,0 +1,131 @@
+import { OFFSETS } from "./constants.js";
+import { formatMDTG } from "./format.js";
+import { parseMDTG } from "./parse.js";
+import {
+  isExtendedFormat,
+  isShortFormat,
+  isStandardFormat,
+  validateTimezone,
+} from "./validation.js";
+
+const HOUR_IN_NANOSECONDS = 3_600_000_000_000;
+
+const getTemporal = () => {
+  if (!globalThis.Temporal) {
+    throw new Error("The Temporal API is not available in this runtime");
+  }
+
+  return globalThis.Temporal;
+};
+
+const createUTCDate = (year, month, day, hours = 0, minutes = 0, seconds = 0) => {
+  const date = new Date(0);
+  date.setUTCFullYear(year, month - 1, day);
+  date.setUTCHours(hours, minutes, seconds, 0);
+  return date;
+};
+
+const getTimezoneForOffset = (offsetNanoseconds) => {
+  if (offsetNanoseconds % HOUR_IN_NANOSECONDS !== 0) {
+    throw new RangeError("MDTG timezone letters only support whole-hour offsets");
+  }
+
+  const offsetHours = offsetNanoseconds / HOUR_IN_NANOSECONDS;
+  const entry = Object.entries(OFFSETS).find(([, offset]) => offset === -offsetHours);
+
+  if (!entry) {
+    throw new RangeError("ZonedDateTime offset has no corresponding MDTG timezone letter");
+  }
+
+  return entry[0];
+};
+
+const getTimezoneOffset = (timezone) => {
+  const offsetHours = -OFFSETS[timezone];
+  const sign = offsetHours < 0 ? "-" : "+";
+  const hours = String(Math.abs(offsetHours)).padStart(2, "0");
+
+  return `${sign}${hours}:00`;
+};
+
+const getTimezoneFromMDTG = (value) => {
+  if (isShortFormat(value) || isStandardFormat(value)) return value[6].toUpperCase();
+  if (isExtendedFormat(value)) return value[8].toUpperCase();
+  return undefined;
+};
+
+export const formatTemporalMDTG = (value, { form, timezone: timezoneInput } = {}) => {
+  const Temporal = getTemporal();
+  let date;
+  let timezone;
+
+  if (value instanceof Temporal.PlainDate) {
+    const plainDate = value.withCalendar("iso8601");
+    timezone = "Z";
+    date = createUTCDate(plainDate.year, plainDate.month, plainDate.day);
+  } else if (value instanceof Temporal.PlainDateTime) {
+    const plainDateTime = value.withCalendar("iso8601");
+    timezone = validateTimezone(timezoneInput);
+    date = createUTCDate(
+      plainDateTime.year,
+      plainDateTime.month,
+      plainDateTime.day,
+      plainDateTime.hour + OFFSETS[timezone],
+      plainDateTime.minute,
+      plainDateTime.second,
+    );
+  } else if (value instanceof Temporal.ZonedDateTime) {
+    const zonedDateTime = value.withCalendar("iso8601");
+    timezone = getTimezoneForOffset(zonedDateTime.offsetNanoseconds);
+    date = createUTCDate(
+      zonedDateTime.year,
+      zonedDateTime.month,
+      zonedDateTime.day,
+      zonedDateTime.hour + OFFSETS[timezone],
+      zonedDateTime.minute,
+      zonedDateTime.second,
+    );
+  } else {
+    throw new TypeError(
+      "Expected a Temporal.PlainDate, Temporal.PlainDateTime, or Temporal.ZonedDateTime",
+    );
+  }
+
+  return formatMDTG(date, { form, timezone });
+};
+
+export const parseTemporalMDTG = (value, { type, referenceDate } = {}) => {
+  const Temporal = getTemporal();
+
+  if (!["plainDate", "plainDateTime", "zonedDateTime"].includes(type)) {
+    throw new TypeError('Expected type to be "plainDate", "plainDateTime", or "zonedDateTime"');
+  }
+
+  let parseOptions;
+  if (referenceDate !== undefined) {
+    if (!(referenceDate instanceof Temporal.PlainDate)) {
+      throw new TypeError("Expected referenceDate to be a Temporal.PlainDate");
+    }
+
+    const plainDate = referenceDate.withCalendar("iso8601");
+    parseOptions = {
+      referenceDate: createUTCDate(plainDate.year, plainDate.month, 1),
+    };
+  }
+
+  const parsedDate = parseMDTG(value, parseOptions);
+  const timezone = getTimezoneFromMDTG(value);
+  const offset = getTimezoneOffset(timezone);
+  const zonedDateTime = Temporal.Instant.fromEpochMilliseconds(
+    parsedDate.getTime(),
+  ).toZonedDateTimeISO(offset);
+
+  switch (type) {
+    case "plainDate":
+      return zonedDateTime.toPlainDate();
+    case "plainDateTime":
+      return zonedDateTime.toPlainDateTime();
+    default:
+      return zonedDateTime;
+  }
+};