Refactor app in JavaScript

Author: t-bowersox

.vscode/extensions.json

@@ -0,0 +1,3 @@
+{
+  "recommendations": ["dbaeumer.vscode-eslint", "esbenp.prettier-vscode"]
+}

.vscode/settings.json

@@ -0,0 +1,6 @@
+{
+  "editor.defaultFormatter": "esbenp.prettier-vscode",
+  "editor.codeActionsOnSave": {
+    "source.organizeImports": "always"
+  }
+}

README.md

@@ -2,21 +2,12 @@
 
 Returns the difference between two times.
 
-## System requirements
-
-* Ruby >= 3.3.0
-
 ## Installation
 
-To add a symlink to the `time-diff` program from your local bin:
-
 ```shell
-# From the project root directory
-./install.sh
+npm install -g @t-bowersox/time-diff
 ```
 
-You may be prompted for `sudo` permission to create the symlink.
-
 ## Usage
 
 ```
@@ -25,12 +16,10 @@ time-diff <start_time> <end_time>
 
 The program takes two arguments:
 
-* `start_time`: The starting time of the duration to measure.
-* `end_time`: The ending time of the duration to measure.
+- `start_time`: The starting time of the duration to measure.
+- `end_time`: The ending time of the duration to measure.
 
-The times provided must be date/time strings parseable by
-Ruby's [`Time::parse`](https://docs.ruby-lang.org/en/3.3/Time.html#method-c-parse) method, with the exception of a
-special `now` argument. When provided, the current time will be substituted.
+The times provided must be in a valid date/time format, with the exception of a special `now` argument. When provided, the current time will be substituted.
 
 ### Examples
 

bin/cli.js

@@ -0,0 +1,11 @@
+#!/usr/bin/env node
+
+import process from "node:process";
+import { main } from "../src/index.js";
+
+try {
+  main();
+} catch (error) {
+  process.exitCode = 1;
+  console.error(error.message);
+}

eslint.config.mjs

@@ -1,9 +1,8 @@
 import globals from "globals";
 import pluginJs from "@eslint/js";
 
-
 /** @type {import('eslint').Linter.Config[]} */
 export default [
-  {languageOptions: { globals: globals.node }},
+  { languageOptions: { globals: globals.node } },
   pluginJs.configs.recommended,
-];
+];

install.sh

@@ -1,13 +1,19 @@
 {
-  "name": "time-diff",
+  "name": "@t-bowersox/time-diff",
   "version": "2.0.0",
   "description": "A program that returns the difference between two times.",
-  "main": "index.js",
+  "main": "src/index.js",
+  "type": "module",
   "directories": {
     "test": "test"
   },
+  "bin": {
+    "time-diff": "bin/cli.js"
+  },
   "scripts": {
-    "test": "echo \"Error: no test specified\" && exit 1"
+    "format": "prettier . --write",
+    "lint": "eslint . --fix",
+    "test": "node --test test/"
   },
   "repository": {
     "type": "git",
@@ -29,5 +35,8 @@
     "eslint": "^9.14.0",
     "globals": "^15.12.0",
     "prettier": "3.3.3"
+  },
+  "engines": {
+    "node": ">=20.18.0"
   }
 }

package.json

@@ -0,0 +1,20 @@
+import { parseArgs } from "node:util";
+import { stringToDate } from "./lib/normalize.js";
+import { TimeDiff } from "./lib/time-diff.js";
+
+export function main() {
+  const { positionals } = parseArgs({ allowPositionals: true });
+
+  switch (positionals.length) {
+    case 0:
+      throw new Error("Usage: time-diff <start_time> <end_time>");
+    case 1:
+      throw new Error("An end time is required.");
+  }
+
+  const startTime = stringToDate(positionals[0]);
+  const endTime = stringToDate(positionals[1]);
+  const diff = new TimeDiff(startTime, endTime);
+
+  console.log(diff.toString());
+}

src/index.js

@@ -0,0 +1,62 @@
+//#region Types
+
+/**
+ * @typedef NormalizedTime
+ * @property {number} hour
+ * @property {number} min
+ * @property {number} sec
+ */
+
+//#endregion
+
+//#region Constants
+
+const TIME_REGEX =
+  /^(?<hour>\d{1,2})?:?(?<min>\d{1,2})?:?(?<sec>\d{1,2})?\s?(?<ord>am|pm)?$/i;
+
+//#endregion
+
+/**
+ * Normalizes the provirded hour, min, sec, and ordinal values.
+ * @param {string|undefined} hour
+ * @param {string|undefined} min
+ * @param {string|undefined} sec
+ * @param {string|undefined} ord
+ * @returns {NormalizedTime} The time normalized on a 24h clock.
+ */
+function getNormalizedTime(hour, min, sec, ord) {
+  hour = hour ? parseInt(hour) : 0;
+
+  if (ord?.toLowerCase() == "pm" && hour < 12) {
+    hour += 12;
+  }
+
+  min = min ? parseInt(min) : 0;
+  sec = sec ? parseInt(sec) : 0;
+
+  return { hour, min, sec };
+}
+
+/**
+ * Attempts to create a valid `Date` from the given date-time string.
+ * @param {string} dateTimeStr The date-time string to normalize.
+ * @returns {Date} A date parsed from the provided date-time string.
+ */
+export function stringToDate(dateTimeStr) {
+  if (dateTimeStr.toLowerCase() == "now") {
+    return new Date();
+  }
+
+  const timeMatch = dateTimeStr.match(TIME_REGEX);
+
+  if (timeMatch != null) {
+    const { hour, min, sec, ord } = timeMatch.groups;
+    const normalized = getNormalizedTime(hour, min, sec, ord);
+
+    const today = new Date();
+    today.setHours(normalized.hour, normalized.min, normalized.sec);
+    return today;
+  }
+
+  return new Date(dateTimeStr);
+}

src/lib/normalize.js

@@ -0,0 +1,157 @@
+"use strict";
+
+//#region Types
+
+/**
+ * @typedef {Object} TimeUnits
+ * @property {number} year
+ * @property {number} month
+ * @property {number} week
+ * @property {number} day
+ * @property {number} hour
+ * @property {number} minute
+ * @property {number} second
+ */
+
+//#endregion
+
+//#region Constants
+
+/** One minute in seconds. */
+const ONE_MIN = 60;
+
+/** One hour in seconds. */
+const ONE_HOUR = 60 * ONE_MIN;
+
+/** One day in seconds. */
+const ONE_DAY = 24 * ONE_HOUR;
+
+/** One week in seconds. */
+const ONE_WEEK = 7 * ONE_DAY;
+
+/** One month in seconds. */
+const ONE_MONTH = 4 * ONE_WEEK;
+
+/** One year in seconds. */
+const ONE_YEAR = 52 * ONE_WEEK;
+
+//#endregion
+
+//#region Classes
+
+/** Represents the difference between two times. */
+export class TimeDiff {
+  /** @type {Date} */
+  #endTime;
+
+  /** @type {Date} */
+  #startTime;
+
+  /** @type {Map<string, number>} */
+  #units = new Map([
+    ["year", ONE_YEAR],
+    ["month", ONE_MONTH],
+    ["week", ONE_WEEK],
+    ["day", ONE_DAY],
+    ["hour", ONE_HOUR],
+    ["minute", ONE_MIN],
+  ]);
+
+  //#region Public API
+
+  /**
+   * @param {Date} startTime The start of the date range.
+   * @param {Date} endTime The end of the date range.
+   */
+  constructor(startTime, endTime) {
+    this.#validateTimes(startTime, endTime);
+    this.#startTime = startTime;
+    this.#endTime = endTime;
+  }
+
+  toString() {
+    if (this.value == 0) {
+      return "No difference";
+    }
+
+    return Object.entries(this.#timeToUnits())
+      .filter((entry) => entry[1] > 0)
+      .map(this.#entryToString)
+      .join(", ");
+  }
+
+  /** The time difference rounded to the nearest second. */
+  get value() {
+    const diffMs = this.#endTime - this.#startTime;
+    return Math.round(diffMs / 1000);
+  }
+
+  //#endregion
+
+  /**
+   * Converts a `TimeUnits` value to a string.
+   * @param {[keyof TimeUnits, number]} entry
+   */
+  #entryToString(entry) {
+    const [unitName, value] = entry;
+    let str = `${value.toLocaleString()} ${unitName}`;
+
+    if (value != 1) {
+      str += "s";
+    }
+
+    return str;
+  }
+
+  /**
+   * Tests that a time is valid.
+   * @param {Date} time The time to validate.
+   */
+  #isValidTime(time) {
+    return time instanceof Date && !isNaN(time.valueOf());
+  }
+
+  /**
+   * Returns the time difference as a dictionary, with each key representing
+   * a unit of time (year, month, etc.).
+   * @returns {TimeUnits}
+   */
+  #timeToUnits() {
+    const units = {};
+    let diffSeconds = this.value;
+
+    this.#units.forEach((seconds, unit) => {
+      units[unit] = 0;
+
+      while (diffSeconds >= seconds) {
+        diffSeconds -= seconds;
+        units[unit] += 1;
+      }
+    });
+
+    units.second = diffSeconds >= 0 ? diffSeconds : 0;
+    return units;
+  }
+
+  /**
+   * Validates that the start and end times form a valid date range.
+   * @param {Date} startTime The start of the date range.
+   * @param {Date} endTime The end of the date range.
+   * @throws If either the `startTime` or `endTime` are invalid.
+   */
+  #validateTimes(startTime, endTime) {
+    if (!this.#isValidTime(startTime)) {
+      throw new Error("Start time is invalid.");
+    }
+
+    if (!this.#isValidTime(endTime)) {
+      throw new Error("End time is invalid.");
+    }
+
+    if (endTime < startTime) {
+      throw new Error("The end time must be greater than the start time.");
+    }
+  }
+}
+
+//#endregion