TimelyDiff Javascript Package

Author: artisticLogicMK

README.md

@@ -0,0 +1,71 @@
+# TimelyDiff
+
+TimelyDiff is a JavaScript package that converts Unix timestamps into human-readable time differences. It allows you to easily display the time difference between two points in time in a user-friendly manner.
+
+[Installation](#installation) | [Usage](#usage) | [API](#API) | [Contribution](#Contribution)
+
+### Installation
+To install TimelyDiff, you can use NPM:
+```shell
+npm i timelydiff
+```
+
+Or, you can add it to your project's dependencies in your package.json file:
+```json
+"dependencies": {
+    "timelydiff": "^1.0.0"
+}
+```
+<br>
+
+### Usage
+To use TimelyDiff, you need to require it in your JavaScript file:
+```javascript
+const timelydiff = require('timelydiff').timelydiff;
+```
+Once you've required the function, you can use it to convert a Unix timestamp into a human-readable time difference:
+```javascript
+const timestamp = 1708868951000; // February 25th, 2024 08:24:36 AM UTC
+const timeDiff = timelydiff(timestamp);
+console.log(timeDiff); // "in 1 year"
+
+const timestamp2 = 1667499433271;
+console.log(timelydiff(timestamp2)); // "4 months ago"
+```
+
+> To generate a timestamp at the current moment and store it for later use, you can use the built-in JavaScript function Date.now(), which returns the number of milliseconds since January 1, 1970, 00:00:00 UTC (Unix timestamp).
+
+<br>
+
+Optionally, you can pass a second parameter to the function to specify the length of the output string. By default, the function will return a string in the format of x [unit] ago/in [x] [unit], but you can choose to return a shorter string by setting the length parameter to "short" or "shorter".
+
+```javascript
+const timestamp = 1667499433271;
+const timeDiffShort = timelydiff(timestamp, "short");
+console.log(timeDiffShort); // "4mo ago"
+
+//timelydiff(timestamp, "shorter") -> 4mo
+```
+
+<br>
+
+### API
+**`timelydiff(timestamp, length)`**
+Converts a Unix timestamp into a human-readable time difference.
+
+Parameters
+- **`timestamp (number)`** - The Unix timestamp to convert.
+- **`length (string)`** - Optional. The length of the output string. Can be set to **`"short"`** or **`"shorter"`** to return a shorter string. Defaults to **`null`**.
+
+Returns
+A string representing the time difference between the current time and the given timestamp.
+
+<br>
+
+### License
+TimelyDiff is released under the **MIT License**.
+
+<br>
+
+### Contribution
+Contributions are welcome and appreciated! If you have an idea for an improvement or a bug fix, please feel free to open an issue or submit a pull request. Before submitting a pull request, please ensure that your code follows the existing code style and has been thoroughly tested. Thank you for helping to make TimelyDiff even better!

index.js

@@ -0,0 +1,77 @@
+//This function takes a Unix timestamp and an optional length parameter,
+//and returns a human-readable time difference in the past or future.
+function timelydiff(timestamp, length = null) {
+
+    //Calculate the time difference between the current time and the timestamp, in seconds.
+    let timeDifference = (Date.now() - timestamp) / 1000;
+    let timeDirection = null;
+
+
+    //Determine whether the time difference is in the past or future (is negative)
+    //and sets the timeDirection variable accordingly.
+    //It also takes the absolute value of timeDifference in case it's negative.
+    if (timeDifference < 0) {
+        timeDifference = Math.abs(timeDifference);
+        timeDirection = 'future';
+    }
+    else {
+        timeDirection = 'past';
+    }
+
+
+    //This is an array of arrays, each containing three elements:
+    //a unit of time (short and default),
+    //the calculated value of that unit based on the timeDifference,
+    //and the maximum value that unit can have 
+    //(i.e. 60 seconds in a minute, 24 hours in a day, etc.).
+    const timeUnits = [
+        [{ short: 's', def: 'second' }, timeDifference, 60],
+        [{ short: 'm', def: 'minute' }, Math.round(timeDifference / 60), 60],
+        [{ short: 'h', def: 'hour' }, Math.round(timeDifference / 3600), 24],
+        [{ short: 'd', def: 'day' }, Math.round(timeDifference / 86400), 7],
+        [{ short: 'w', def: 'week' }, Math.round(timeDifference / 604800), 4],
+        [{ short: 'mo', def: 'month' }, Math.round(timeDifference / 2419200), 12],
+        [{ short: 'y', def: 'year' }, Math.round(timeDifference / 29030400), 10],
+        [{ short: 'dcd', def: 'decade' }, Math.round(timeDifference / 290304000), Infinity]
+    ];
+
+
+    //this helper function returns the time string with "in" or "ago" depending on the time direction.
+    function positionTime(timeString) {
+        if (timeDirection === 'future') {
+            return `in ${timeString}`;
+        } else {
+            return `${timeString}${length === 'shorter' ? '' : ' ago'}`;
+        }
+    }
+
+
+    //This is a for loop that iterates over each element in the timeUnits array.
+    //It checks if the calculated value for that unit is less than the maximum value for that unit.
+    //If so, it formats the output string using the positionTime helper function and the length parameter.
+    //If the length parameter is null or longer, it returns the default format (e.g. "2 hours ago"),
+    //and if the length parameter is "short" or "shorter",
+    //it returns a shorter format (e.g. "2h" or "2 hours").
+    for (const [name, value, range] of timeUnits) {
+
+        if (value < range) {
+            let trunc = Math.trunc(value);
+            
+            //if value > 1, pluralize by adding 's'
+            let pluralize = trunc > 1 ? 's' : '';
+
+            if (length === null) {
+                return positionTime(`${trunc} ${name.def}${pluralize}`);
+            }
+
+            if (length === 'short' || length === 'shorter') {
+                return positionTime(`${trunc}${name.short}`);
+            }
+
+            break;
+        }
+    }
+
+}
+
+module.exports.timelydiff = timelydiff;

package.json

@@ -0,0 +1,28 @@
+{
+  "name": "timelydiff",
+  "version": "1.0.0",
+  "description": "A JavaScript package that converts Unix timestamps into human-readable time differences.",
+  "main": "index.js",
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/artisticLogicMK/timelydiff.git"
+  },
+  "keywords": [
+    "timelydiff",
+    "time",
+    "unix",
+    "timestamp",
+    "time",
+    "difference",
+    "date"
+  ],
+  "author": "MK",
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/artisticLogicMK/timelydiff/issues"
+  },
+  "homepage": "https://github.com/artisticLogicMK/timelydiff#readme"
+}