mdtg 3.3.0 → 4.1.0

package/README.md

@@ -11,18 +11,20 @@ npm install mdtg
 ### Usage
 
 ```js
-import { parse, formatMDTG } from "mdtg";
+import { formatMDTG, parseMDTG } from "mdtg";
 
-const date = new Date();
+const date = new Date(Date.UTC(2024, 7, 12, 11, 55, 30));
 
-console.log(formatMDTG(date, { form: "short" }));
-console.log(formatMDTG(date, { form: "shortened" }));
-console.log(formatMDTG(date, { form: "long" }));
+formatMDTG(date, { form: "short" });      // "121155Z"
+formatMDTG(date, { form: "standard" });   // "121155Zaug24"
+formatMDTG(date);                         // "12115530Zaug24" (extended by default)
 
-console.log(parse("12135530Zaug24"));
-console.log(parse("12135530Asep24"));
-console.log(parse("121355LOCT24"));
-console.log(parse("121355M"));
+// A is UTC+1, so local time is one hour ahead of UTC.
+const value = formatMDTG(date, { timezone: "A" }); // "12125530Aaug24"
+parseMDTG(value).toISOString();                       // "2024-08-12T11:55:30.000Z"
+
+parseMDTG("121155Zaug24").toISOString(); // "2024-08-12T11:55:00.000Z"
+parseMDTG("121155Z");                    // month and year are current UTC month/year
 ```
 
 ### API
@@ -30,23 +32,71 @@ console.log(parse("121355M"));
 #### `formatMDTG(date, options)`
 
 Converts a valid `Date` to a date-time group. `date` defaults to the current
-date. `options.form` is `"short"`, `"shortened"`, or `"long"` (the default).
+date. `options.form` is `"short"`, `"standard"`, or `"extended"` (the default).
 `options.timezone` accepts the NATO time-zone letters `A` through `Z`;
-lowercase letters are accepted and unknown values default to `Z`.
+lowercase letters are accepted and unknown values default to `Z`. The timezone
+letter determines the displayed local time; parsing converts it back to a UTC
+`Date`.
 
 ```js
 formatMDTG(new Date(Date.UTC(2024, 7, 12, 11, 55, 30)), {
-  form: "long",
+  form: "extended",
   timezone: "A",
 });
 // "12125530Aaug24"
 ```
 
-#### `parse(value)`
+#### `parseMDTG(value, options)`
 
-Parses short (`121155Z`), shortened (`121155Zaug24`), and long
+Parses short (`121155Z`), standard (`121155Zaug24`), and extended
 (`12115530Zaug24`) formats into a `Date`. Short values use the current UTC
-month and year. Years are interpreted as `2000` through `2099`.
+month and year and have no seconds. Years are interpreted as `2000` through
+`2099`.
+
+```js
+import { parseMDTG } from "mdtg";
+
+parseMDTG("121155Zaug24").toISOString();   // "2024-08-12T11:55:00.000Z"
+parseMDTG("12115530Zaug24").toISOString(); // "2024-08-12T11:55:30.000Z"
+parseMDTG("12125530Aaug24").toISOString(); // "2024-08-12T11:55:30.000Z"
+
+parseMDTG("121155Z"); // uses the current UTC month and year
+
+parseMDTG("121155Z", {
+  referenceDate: new Date(Date.UTC(2024, 7, 1)),
+}); // uses August 2024, independent of the system date
+```
 
 Invalid calendar dates and times, such as `310224Zfeb24` or `126155Z`, throw a
 `RangeError`. Other invalid values throw an `Error`.
+
+`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.
+
+#### Format checks
+
+`isShortFormat`, `isStandardFormat`, and `isExtendedFormat` check whether a string
+matches the structure of the corresponding format. `isMDTG` checks whether a
+string matches any of the three structures. These checks do not validate
+calendar dates or times; use `isValidMDTG` when semantic validity is needed.
+
+```js
+import {
+  isShortFormat,
+  isStandardFormat,
+  isExtendedFormat,
+  isMDTG,
+  isValidMDTG,
+} from "mdtg";
+
+isShortFormat("121155Z");          // true
+isStandardFormat("121155Zaug24"); // true
+isExtendedFormat("12115530Zaug24"); // true
+isMDTG("121155Zaug24");      // true
+isMDTG("invalid");           // false
+isMDTG("310224Zfeb24");      // true: structurally valid
+isValidMDTG("310224Zfeb24"); // false: invalid calendar date
+```
+
+For short values, `isValidMDTG` also accepts the same optional `referenceDate`
+as `parseMDTG`.

package/package.json

@@ -1,10 +1,14 @@
 {
   "name": "mdtg",
-  "version": "3.3.0",
+  "version": "4.1.0",
   "main": "src/index.js",
+  "types": "src/index.d.ts",
   "type": "module",
   "exports": {
-    ".": "./src/index.js"
+    ".": {
+      "types": "./src/index.d.ts",
+      "import": "./src/index.js"
+    }
   },
   "engines": {
     "node": ">=24.0.0",
@@ -29,10 +33,10 @@
   "license": "MIT",
   "description": "This package offers you methods to convert Date Objects to military date time and vice versa",
   "devDependencies": {
-    "@biomejs/biome": "2.5.14",
-    "@vitest/coverage-v8": "5.0.1",
-    "knip": "6.38.0",
+    "@biomejs/biome": "2.5.15",
+    "@vitest/coverage-v8": "5.0.3",
+    "knip": "6.39.0",
     "prettier": "3.9.9",
-    "vitest": "5.0.1"
+    "vitest": "5.0.3"
   }
 }

package/src/constants.js

@@ -43,13 +43,13 @@ export const OFFSETS = Object.freeze({
 });
 
 export const SHORT_FORMAT_REGEX = /^[0-9]{6}[A-Z]$/;
-export const SHORTENED_FORMAT_REGEX =
+export const STANDARD_FORMAT_REGEX =
   /^[0-9]{6}[A-Z](jan|feb|mar|apr|may|jun|jul|aug|sep|oct|nov|dec)[0-9]{2}$/i;
-export const LONG_FORMAT_REGEX =
+export const EXTENDED_FORMAT_REGEX =
   /^[0-9]{8}[A-Z](jan|feb|mar|apr|may|jun|jul|aug|sep|oct|nov|dec)[0-9]{2}$/i;
 
 export const FORM = Object.freeze({
   SHORT: "short",
-  SHORTENED: "shortened",
-  LONG: "long",
+  STANDARD: "standard",
+  EXTENDED: "extended",
 });

package/src/format.js

@@ -1,8 +1,8 @@
 import { FORM, MONTHS, OFFSETS } from "./constants.js";
 import {
-  isLongFormat,
-  isShortenedFormat,
+  isExtendedFormat,
   isShortFormat,
+  isStandardFormat,
   validateDate,
   validateTimezone,
 } from "./validation.js";
@@ -25,7 +25,7 @@ const buildShort = (date, timezone) => {
   return result;
 };
 
-const buildLong = (date, timezone) => {
+const buildExtended = (date, timezone) => {
   const result = [
     date.getUTCDate(),
     date.getUTCHours(),
@@ -40,22 +40,22 @@ const buildLong = (date, timezone) => {
     )
     .join("");
 
-  if (!isLongFormat(result)) {
-    throw new Error("Failed to build long MDTG");
+  if (!isExtendedFormat(result)) {
+    throw new Error("Failed to build extended MDTG");
   }
 
   return result;
 };
 
-const buildShortened = (date, timezone) => {
+const buildStandard = (date, timezone) => {
   const result = [
     buildShort(date, timezone),
     MONTHS[date.getUTCMonth()],
     normalizeNumber(date.getUTCFullYear() % 100),
   ].join("");
 
-  if (!isShortenedFormat(result)) {
-    throw new Error("Failed to build shortened MDTG");
+  if (!isStandardFormat(result)) {
+    throw new Error("Failed to build standard MDTG");
   }
 
   return result;
@@ -63,7 +63,7 @@ const buildShortened = (date, timezone) => {
 
 export const formatMDTG = (
   date = new Date(),
-  { form = FORM.LONG, timezone: timezoneInput = "Z" } = {},
+  { form = FORM.EXTENDED, timezone: timezoneInput = "Z" } = {},
 ) => {
   validateDate(date);
 
@@ -73,9 +73,9 @@ export const formatMDTG = (
   switch (form) {
     case FORM.SHORT:
       return buildShort(adjustedDate, timezone);
-    case FORM.SHORTENED:
-      return buildShortened(adjustedDate, timezone);
+    case FORM.STANDARD:
+      return buildStandard(adjustedDate, timezone);
     default:
-      return buildLong(adjustedDate, timezone);
+      return buildExtended(adjustedDate, timezone);
   }
 };

package/src/index.d.ts

@@ -0,0 +1,28 @@
+declare function formatMDTG(
+  date?: Date,
+  options?: { form?: "short" | "extended" | "standard"; timezone?: string },
+): string;
+
+declare function isValidMDTG(
+  mdtg: string,
+  options?: { referenceDate?: Date },
+): boolean;
+declare function parseMDTG(
+  mdtg: string,
+  options?: { referenceDate?: Date },
+): Date;
+
+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 {
+  formatMDTG,
+  isExtendedFormat,
+  isMDTG,
+  isShortFormat,
+  isStandardFormat,
+  isValidMDTG,
+  parseMDTG,
+};

package/src/index.js

@@ -1,8 +1,8 @@
-export { FORM } from "./constants.js";
 export { formatMDTG } from "./format.js";
-export { parse } from "./parse.js";
+export { isValidMDTG, parseMDTG } from "./parse.js";
 export {
-  isLongFormat,
-  isShortenedFormat,
+  isExtendedFormat,
+  isMDTG,
   isShortFormat,
+  isStandardFormat,
 } from "./validation.js";

package/src/parse.js

@@ -1,37 +1,34 @@
 import { MONTHS, OFFSETS } from "./constants.js";
 import {
-  isLongFormat,
-  isShortenedFormat,
+  isExtendedFormat,
+  isMDTG,
   isShortFormat,
+  isStandardFormat,
+  validateDate,
   validateDateTime,
 } from "./validation.js";
 
 const parseInteger = (input) => Number.parseInt(input, 10);
 
-const parseShort = (value) => {
+const parseShort = (value, referenceDate) => {
   const day = parseInteger(value.slice(0, 2));
   const hours = parseInteger(value.slice(2, 4));
   const minutes = parseInteger(value.slice(4, 6));
   const timezone = value.slice(6, 7).toUpperCase();
-  const now = new Date();
+  validateDate(referenceDate);
 
   validateDateTime({
-    year: now.getUTCFullYear(),
-    month: now.getUTCMonth(),
+    year: referenceDate.getUTCFullYear(),
+    month: referenceDate.getUTCMonth(),
     day,
     hours,
     minutes,
   });
 
-  return new Date(
-    Date.UTC(
-      now.getUTCFullYear(),
-      now.getUTCMonth(),
-      day,
-      hours + OFFSETS[timezone],
-      minutes,
-    ),
-  );
+  const result = new Date(referenceDate);
+  result.setUTCDate(day);
+  result.setUTCHours(hours + OFFSETS[timezone], minutes, 0, 0);
+  return result;
 };
 
 const parseWithMonth = (value, { hasSeconds, timezoneIndex, monthStart }) => {
@@ -60,16 +57,16 @@ const parseWithMonth = (value, { hasSeconds, timezoneIndex, monthStart }) => {
   return new Date(Date.UTC(...dateParts));
 };
 
-export const parse = (value) => {
-  if (isShortFormat(value)) return parseShort(value);
-  if (isShortenedFormat(value)) {
+export const parseMDTG = (value, { referenceDate = new Date() } = {}) => {
+  if (isShortFormat(value)) return parseShort(value, referenceDate);
+  if (isStandardFormat(value)) {
     return parseWithMonth(value, {
       hasSeconds: false,
       timezoneIndex: 6,
       monthStart: 7,
     });
   }
-  if (isLongFormat(value)) {
+  if (isExtendedFormat(value)) {
     return parseWithMonth(value, {
       hasSeconds: true,
       timezoneIndex: 8,
@@ -79,3 +76,15 @@ export const parse = (value) => {
 
   throw new Error(`Invalid MDTG string "${value}"`);
 };
+
+export const isValidMDTG = (value, options) => {
+  if (!isMDTG(value)) return false;
+
+  try {
+    parseMDTG(value, options);
+    return true;
+  } catch (error) {
+    if (error instanceof RangeError) return false;
+    throw error;
+  }
+};

package/src/validation.js

@@ -1,18 +1,21 @@
 import {
-  LONG_FORMAT_REGEX,
+  EXTENDED_FORMAT_REGEX,
   OFFSETS,
   SHORT_FORMAT_REGEX,
-  SHORTENED_FORMAT_REGEX,
+  STANDARD_FORMAT_REGEX,
 } from "./constants.js";
 
 export const isShortFormat = (value) =>
   typeof value === "string" && SHORT_FORMAT_REGEX.test(value);
 
-export const isShortenedFormat = (value) =>
-  typeof value === "string" && SHORTENED_FORMAT_REGEX.test(value);
+export const isStandardFormat = (value) =>
+  typeof value === "string" && STANDARD_FORMAT_REGEX.test(value);
 
-export const isLongFormat = (value) =>
-  typeof value === "string" && LONG_FORMAT_REGEX.test(value);
+export const isExtendedFormat = (value) =>
+  typeof value === "string" && EXTENDED_FORMAT_REGEX.test(value);
+
+export const isMDTG = (value) =>
+  isShortFormat(value) || isStandardFormat(value) || isExtendedFormat(value);
 
 export const validateDate = (date) => {
   if (!(date instanceof Date) || Number.isNaN(date.getTime())) {
@@ -33,9 +36,9 @@ export const validateDateTime = ({
   minutes,
   seconds,
 }) => {
-  const candidate = new Date(
-    Date.UTC(year, month, day, hours, minutes, seconds ?? 0),
-  );
+  const candidate = new Date(0);
+  candidate.setUTCFullYear(year, month, day);
+  candidate.setUTCHours(hours, minutes, seconds ?? 0, 0);
 
   if (
     candidate.getUTCFullYear() !== year ||