mdtg 4.0.0 → 4.1.0

package/README.md

@@ -46,7 +46,7 @@ formatMDTG(new Date(Date.UTC(2024, 7, 12, 11, 55, 30)), {
 // "12125530Aaug24"
 ```
 
-#### `parseMDTG(value)`
+#### `parseMDTG(value, options)`
 
 Parses short (`121155Z`), standard (`121155Zaug24`), and extended
 (`12115530Zaug24`) formats into a `Date`. Short values use the current UTC
@@ -61,16 +61,24 @@ 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 formats.
+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 {
@@ -78,6 +86,7 @@ import {
   isStandardFormat,
   isExtendedFormat,
   isMDTG,
+  isValidMDTG,
 } from "mdtg";
 
 isShortFormat("121155Z");          // true
@@ -85,4 +94,9 @@ 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": "4.0.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/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,5 +1,5 @@
 export { formatMDTG } from "./format.js";
-export { parseMDTG } from "./parse.js";
+export { isValidMDTG, parseMDTG } from "./parse.js";
 export {
   isExtendedFormat,
   isMDTG,

package/src/parse.js

@@ -1,37 +1,34 @@
 import { MONTHS, OFFSETS } from "./constants.js";
 import {
   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,8 +57,8 @@ const parseWithMonth = (value, { hasSeconds, timezoneIndex, monthStart }) => {
   return new Date(Date.UTC(...dateParts));
 };
 
-export const parseMDTG = (value) => {
-  if (isShortFormat(value)) return parseShort(value);
+export const parseMDTG = (value, { referenceDate = new Date() } = {}) => {
+  if (isShortFormat(value)) return parseShort(value, referenceDate);
   if (isStandardFormat(value)) {
     return parseWithMonth(value, {
       hasSeconds: false,
@@ -79,3 +76,15 @@ export const parseMDTG = (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

@@ -36,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 ||