mdtg 3.2.0 → 4.0.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,57 @@ 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)`
 
-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
+```
 
 Invalid calendar dates and times, such as `310224Zfeb24` or `126155Z`, throw a
 `RangeError`. Other invalid values throw an `Error`.
+
+#### 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.
+
+```js
+import {
+  isShortFormat,
+  isStandardFormat,
+  isExtendedFormat,
+  isMDTG,
+} from "mdtg";
+
+isShortFormat("121155Z");          // true
+isStandardFormat("121155Zaug24"); // true
+isExtendedFormat("12115530Zaug24"); // true
+isMDTG("121155Zaug24");      // true
+isMDTG("invalid");           // false
+```

package/package.json

@@ -1,13 +1,13 @@
 {
   "name": "mdtg",
-  "version": "3.2.0",
+  "version": "4.0.0",
   "main": "src/index.js",
   "type": "module",
   "exports": {
     ".": "./src/index.js"
   },
   "engines": {
-    "node": ">=22.0.0",
+    "node": ">=24.0.0",
     "npm": ">=10.0.0"
   },
   "scripts": {
@@ -16,6 +16,7 @@
     "format": "biome check .",
     "prelint": "npm run format && npm run prettier",
     "lint": "biome lint .",
+    "knip": "knip",
     "prettier": "prettier **/*.yml",
     "test": "vitest run"
   },
@@ -30,7 +31,8 @@
   "devDependencies": {
     "@biomejs/biome": "2.5.14",
     "@vitest/coverage-v8": "5.0.1",
-    "prettier": "3.9.8",
+    "knip": "6.38.0",
+    "prettier": "3.9.9",
     "vitest": "5.0.1"
   }
 }

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.js

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

package/src/parse.js

@@ -1,8 +1,8 @@
 import { MONTHS, OFFSETS } from "./constants.js";
 import {
-  isLongFormat,
-  isShortenedFormat,
+  isExtendedFormat,
   isShortFormat,
+  isStandardFormat,
   validateDateTime,
 } from "./validation.js";
 
@@ -60,16 +60,16 @@ const parseWithMonth = (value, { hasSeconds, timezoneIndex, monthStart }) => {
   return new Date(Date.UTC(...dateParts));
 };
 
-export const parse = (value) => {
+export const parseMDTG = (value) => {
   if (isShortFormat(value)) return parseShort(value);
-  if (isShortenedFormat(value)) {
+  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,

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())) {