clockey 1.2.0 → 1.4.1

package/dist/index.d.mts

@@ -406,6 +406,87 @@ declare function createTimer(): {
         elapsedHrs: number;
         text: string;
     } | null;
+    lap: () => {
+        durationMs: number;
+        durationSec: number;
+        durationMin: number;
+        durationHrs: number;
+        text: string;
+    } | null;
+};
+
+declare function isBefore(timestamp: Date | number | string): {
+    error: string;
+    isBefore?: undefined;
+    durationInMs?: undefined;
+    durationInSeconds?: undefined;
+    durationInMinutes?: undefined;
+    durationInHours?: undefined;
+    durationInDays?: undefined;
+} | {
+    isBefore: boolean;
+    durationInMs: number;
+    durationInSeconds: number;
+    durationInMinutes: number;
+    durationInHours: number;
+    durationInDays: number;
+    error?: undefined;
+};
+declare function isAfter(timestamp: Date | number | string): {
+    error: string;
+    isAfter?: undefined;
+    durationInMs?: undefined;
+    durationInSeconds?: undefined;
+    durationInMinutes?: undefined;
+    durationInHours?: undefined;
+    durationInDays?: undefined;
+} | {
+    isAfter: boolean;
+    durationInMs: number;
+    durationInSeconds: number;
+    durationInMinutes: number;
+    durationInHours: number;
+    durationInDays: number;
+    error?: undefined;
+};
+
+declare function relativeTime(timestamp: Date | number | string): {
+    error: string;
+    isBefore?: undefined;
+    durationInMs?: undefined;
+    durationInSeconds?: undefined;
+    durationInMinutes?: undefined;
+    durationInHours?: undefined;
+    durationInDays?: undefined;
+} | {
+    isBefore: boolean;
+    durationInMs: number;
+    durationInSeconds: number;
+    durationInMinutes: number;
+    durationInHours: number;
+    durationInDays: number;
+    error?: undefined;
+} | {
+    error: string;
+    isAfter?: undefined;
+    durationInMs?: undefined;
+    durationInSeconds?: undefined;
+    durationInMinutes?: undefined;
+    durationInHours?: undefined;
+    durationInDays?: undefined;
+} | {
+    isAfter: boolean;
+    durationInMs: number;
+    durationInSeconds: number;
+    durationInMinutes: number;
+    durationInHours: number;
+    durationInDays: number;
+    error?: undefined;
+} | {
+    timestamp: number;
+    timestampDate: Date;
+    humanReadable: string;
+    isInFuture: true;
 };
 
-export { createTimer, getCurrenHrResponse, getCurrentDate, getCurrentDateNumber, getCurrentDateNumberResponse, getCurrentDateNumberUTC, getCurrentDateNumberUTCResponse, getCurrentDateUTC, getCurrentDateUnixMilliseconds, getCurrentDateUnixMillisecondsResponse, getCurrentDateUnixSeconds, getCurrentDateUnixSecondsResponse, getCurrentDay, getCurrentDayResponse, getCurrentDayUTC, getCurrentDayUTCResponse, getCurrentFullDate, getCurrentFullDateResponse, getCurrentFullDateUTC, getCurrentFullDateUTCResponse, getCurrentHour12Str, getCurrentHour12StrResponse, getCurrentHour12StrUTC, getCurrentHour12StrUTCResponse, getCurrentHour24Str, getCurrentHour24StrResponse, getCurrentHour24StrUTC, getCurrentHour24StrUTCResponse, getCurrentHr, getCurrentHrUTC, getCurrentHrUTCResponse, getCurrentMinute, getCurrentMinuteResponse, getCurrentMinuteStr, getCurrentMinuteStrResponse, getCurrentMinuteStrUTC, getCurrentMinuteStrUTCResponse, getCurrentMinuteUTC, getCurrentMinuteUTCResponse, getCurrentMonth, getCurrentMonthResponse, getCurrentMonthUTC, getCurrentMonthUTCResponse, getCurrentOrdinal, getCurrentOrdinalResponse, getCurrentOrdinalUTC, getCurrentOrdinalUTCResponse, getCurrentPeriod, getCurrentPeriodResponse, getCurrentPeriodUTC, getCurrentPeriodUTCResponse, getCurrentSecond, getCurrentSecondResponse, getCurrentSecondStr, getCurrentSecondStrResponse, getCurrentSecondStrUTC, getCurrentSecondStrUTCResponse, getCurrentSecondUTC, getCurrentSecondUTCResponse, getCurrentTime, getCurrentTimeResponse, getCurrentTimeUTC, getCurrentTimeUTCResponse, getCurrentTimeUnixMilliseconds, getCurrentTimeUnixMillisecondsResponse, getCurrentTimeUnixSeconds, getCurrentTimeUnixSecondsResponse, getCurrentYear, getCurrentYearResponse, getCurrentYearUTC, getCurrentYearUTCResponse, getcurrentDateISO, getcurrentDateISOResponse, getcurrentTimeISO, getcurrentTimeISOResponse };
+export { createTimer, getCurrenHrResponse, getCurrentDate, getCurrentDateNumber, getCurrentDateNumberResponse, getCurrentDateNumberUTC, getCurrentDateNumberUTCResponse, getCurrentDateUTC, getCurrentDateUnixMilliseconds, getCurrentDateUnixMillisecondsResponse, getCurrentDateUnixSeconds, getCurrentDateUnixSecondsResponse, getCurrentDay, getCurrentDayResponse, getCurrentDayUTC, getCurrentDayUTCResponse, getCurrentFullDate, getCurrentFullDateResponse, getCurrentFullDateUTC, getCurrentFullDateUTCResponse, getCurrentHour12Str, getCurrentHour12StrResponse, getCurrentHour12StrUTC, getCurrentHour12StrUTCResponse, getCurrentHour24Str, getCurrentHour24StrResponse, getCurrentHour24StrUTC, getCurrentHour24StrUTCResponse, getCurrentHr, getCurrentHrUTC, getCurrentHrUTCResponse, getCurrentMinute, getCurrentMinuteResponse, getCurrentMinuteStr, getCurrentMinuteStrResponse, getCurrentMinuteStrUTC, getCurrentMinuteStrUTCResponse, getCurrentMinuteUTC, getCurrentMinuteUTCResponse, getCurrentMonth, getCurrentMonthResponse, getCurrentMonthUTC, getCurrentMonthUTCResponse, getCurrentOrdinal, getCurrentOrdinalResponse, getCurrentOrdinalUTC, getCurrentOrdinalUTCResponse, getCurrentPeriod, getCurrentPeriodResponse, getCurrentPeriodUTC, getCurrentPeriodUTCResponse, getCurrentSecond, getCurrentSecondResponse, getCurrentSecondStr, getCurrentSecondStrResponse, getCurrentSecondStrUTC, getCurrentSecondStrUTCResponse, getCurrentSecondUTC, getCurrentSecondUTCResponse, getCurrentTime, getCurrentTimeResponse, getCurrentTimeUTC, getCurrentTimeUTCResponse, getCurrentTimeUnixMilliseconds, getCurrentTimeUnixMillisecondsResponse, getCurrentTimeUnixSeconds, getCurrentTimeUnixSecondsResponse, getCurrentYear, getCurrentYearResponse, getCurrentYearUTC, getCurrentYearUTCResponse, getcurrentDateISO, getcurrentDateISOResponse, getcurrentTimeISO, getcurrentTimeISOResponse, isAfter, isBefore, relativeTime };

package/dist/index.d.ts

@@ -406,6 +406,87 @@ declare function createTimer(): {
         elapsedHrs: number;
         text: string;
     } | null;
+    lap: () => {
+        durationMs: number;
+        durationSec: number;
+        durationMin: number;
+        durationHrs: number;
+        text: string;
+    } | null;
+};
+
+declare function isBefore(timestamp: Date | number | string): {
+    error: string;
+    isBefore?: undefined;
+    durationInMs?: undefined;
+    durationInSeconds?: undefined;
+    durationInMinutes?: undefined;
+    durationInHours?: undefined;
+    durationInDays?: undefined;
+} | {
+    isBefore: boolean;
+    durationInMs: number;
+    durationInSeconds: number;
+    durationInMinutes: number;
+    durationInHours: number;
+    durationInDays: number;
+    error?: undefined;
+};
+declare function isAfter(timestamp: Date | number | string): {
+    error: string;
+    isAfter?: undefined;
+    durationInMs?: undefined;
+    durationInSeconds?: undefined;
+    durationInMinutes?: undefined;
+    durationInHours?: undefined;
+    durationInDays?: undefined;
+} | {
+    isAfter: boolean;
+    durationInMs: number;
+    durationInSeconds: number;
+    durationInMinutes: number;
+    durationInHours: number;
+    durationInDays: number;
+    error?: undefined;
+};
+
+declare function relativeTime(timestamp: Date | number | string): {
+    error: string;
+    isBefore?: undefined;
+    durationInMs?: undefined;
+    durationInSeconds?: undefined;
+    durationInMinutes?: undefined;
+    durationInHours?: undefined;
+    durationInDays?: undefined;
+} | {
+    isBefore: boolean;
+    durationInMs: number;
+    durationInSeconds: number;
+    durationInMinutes: number;
+    durationInHours: number;
+    durationInDays: number;
+    error?: undefined;
+} | {
+    error: string;
+    isAfter?: undefined;
+    durationInMs?: undefined;
+    durationInSeconds?: undefined;
+    durationInMinutes?: undefined;
+    durationInHours?: undefined;
+    durationInDays?: undefined;
+} | {
+    isAfter: boolean;
+    durationInMs: number;
+    durationInSeconds: number;
+    durationInMinutes: number;
+    durationInHours: number;
+    durationInDays: number;
+    error?: undefined;
+} | {
+    timestamp: number;
+    timestampDate: Date;
+    humanReadable: string;
+    isInFuture: true;
 };
 
-export { createTimer, getCurrenHrResponse, getCurrentDate, getCurrentDateNumber, getCurrentDateNumberResponse, getCurrentDateNumberUTC, getCurrentDateNumberUTCResponse, getCurrentDateUTC, getCurrentDateUnixMilliseconds, getCurrentDateUnixMillisecondsResponse, getCurrentDateUnixSeconds, getCurrentDateUnixSecondsResponse, getCurrentDay, getCurrentDayResponse, getCurrentDayUTC, getCurrentDayUTCResponse, getCurrentFullDate, getCurrentFullDateResponse, getCurrentFullDateUTC, getCurrentFullDateUTCResponse, getCurrentHour12Str, getCurrentHour12StrResponse, getCurrentHour12StrUTC, getCurrentHour12StrUTCResponse, getCurrentHour24Str, getCurrentHour24StrResponse, getCurrentHour24StrUTC, getCurrentHour24StrUTCResponse, getCurrentHr, getCurrentHrUTC, getCurrentHrUTCResponse, getCurrentMinute, getCurrentMinuteResponse, getCurrentMinuteStr, getCurrentMinuteStrResponse, getCurrentMinuteStrUTC, getCurrentMinuteStrUTCResponse, getCurrentMinuteUTC, getCurrentMinuteUTCResponse, getCurrentMonth, getCurrentMonthResponse, getCurrentMonthUTC, getCurrentMonthUTCResponse, getCurrentOrdinal, getCurrentOrdinalResponse, getCurrentOrdinalUTC, getCurrentOrdinalUTCResponse, getCurrentPeriod, getCurrentPeriodResponse, getCurrentPeriodUTC, getCurrentPeriodUTCResponse, getCurrentSecond, getCurrentSecondResponse, getCurrentSecondStr, getCurrentSecondStrResponse, getCurrentSecondStrUTC, getCurrentSecondStrUTCResponse, getCurrentSecondUTC, getCurrentSecondUTCResponse, getCurrentTime, getCurrentTimeResponse, getCurrentTimeUTC, getCurrentTimeUTCResponse, getCurrentTimeUnixMilliseconds, getCurrentTimeUnixMillisecondsResponse, getCurrentTimeUnixSeconds, getCurrentTimeUnixSecondsResponse, getCurrentYear, getCurrentYearResponse, getCurrentYearUTC, getCurrentYearUTCResponse, getcurrentDateISO, getcurrentDateISOResponse, getcurrentTimeISO, getcurrentTimeISOResponse };
+export { createTimer, getCurrenHrResponse, getCurrentDate, getCurrentDateNumber, getCurrentDateNumberResponse, getCurrentDateNumberUTC, getCurrentDateNumberUTCResponse, getCurrentDateUTC, getCurrentDateUnixMilliseconds, getCurrentDateUnixMillisecondsResponse, getCurrentDateUnixSeconds, getCurrentDateUnixSecondsResponse, getCurrentDay, getCurrentDayResponse, getCurrentDayUTC, getCurrentDayUTCResponse, getCurrentFullDate, getCurrentFullDateResponse, getCurrentFullDateUTC, getCurrentFullDateUTCResponse, getCurrentHour12Str, getCurrentHour12StrResponse, getCurrentHour12StrUTC, getCurrentHour12StrUTCResponse, getCurrentHour24Str, getCurrentHour24StrResponse, getCurrentHour24StrUTC, getCurrentHour24StrUTCResponse, getCurrentHr, getCurrentHrUTC, getCurrentHrUTCResponse, getCurrentMinute, getCurrentMinuteResponse, getCurrentMinuteStr, getCurrentMinuteStrResponse, getCurrentMinuteStrUTC, getCurrentMinuteStrUTCResponse, getCurrentMinuteUTC, getCurrentMinuteUTCResponse, getCurrentMonth, getCurrentMonthResponse, getCurrentMonthUTC, getCurrentMonthUTCResponse, getCurrentOrdinal, getCurrentOrdinalResponse, getCurrentOrdinalUTC, getCurrentOrdinalUTCResponse, getCurrentPeriod, getCurrentPeriodResponse, getCurrentPeriodUTC, getCurrentPeriodUTCResponse, getCurrentSecond, getCurrentSecondResponse, getCurrentSecondStr, getCurrentSecondStrResponse, getCurrentSecondStrUTC, getCurrentSecondStrUTCResponse, getCurrentSecondUTC, getCurrentSecondUTCResponse, getCurrentTime, getCurrentTimeResponse, getCurrentTimeUTC, getCurrentTimeUTCResponse, getCurrentTimeUnixMilliseconds, getCurrentTimeUnixMillisecondsResponse, getCurrentTimeUnixSeconds, getCurrentTimeUnixSecondsResponse, getCurrentYear, getCurrentYearResponse, getCurrentYearUTC, getCurrentYearUTCResponse, getcurrentDateISO, getcurrentDateISOResponse, getcurrentTimeISO, getcurrentTimeISOResponse, isAfter, isBefore, relativeTime };

package/dist/index.js

@@ -94,7 +94,10 @@ __export(index_exports, {
   getcurrentDateISO: () => getcurrentDateISO,
   getcurrentDateISOResponse: () => getcurrentDateISOResponse,
   getcurrentTimeISO: () => getcurrentTimeISO,
-  getcurrentTimeISOResponse: () => getcurrentTimeISOResponse
+  getcurrentTimeISOResponse: () => getcurrentTimeISOResponse,
+  isAfter: () => isAfter,
+  isBefore: () => isBefore,
+  relativeTime: () => relativeTime
 });
 module.exports = __toCommonJS(index_exports);
 
@@ -890,7 +893,169 @@ function createTimer() {
         elapsedHrs: elapsed / 36e5,
         text: `${elapsed.toFixed(2)} ms`
       };
+    },
+    lap: () => {
+      if (startTime === null) {
+        return null;
+      }
+      const duration = performance.now() - startTime;
+      return {
+        durationMs: duration,
+        durationSec: duration / 1e3,
+        durationMin: duration / 6e4,
+        durationHrs: duration / 36e5,
+        text: `${duration.toFixed(2)} ms`
+      };
+    }
+  };
+}
+
+// src/utilities/diffChecker.ts
+function isBefore(timestamp) {
+  if (timestamp instanceof Date) {
+    if (isNaN(timestamp.getTime())) {
+      return {
+        error: "invalid timestamp (date), please read documentation for more info"
+      };
+    }
+  } else if (typeof timestamp === "string") {
+    const tsDate = new Date(timestamp);
+    if (isNaN(tsDate.getTime())) {
+      return {
+        error: "invalid timestamp (string), please read documentation for more info"
+      };
+    }
+  } else if (typeof timestamp === "number") {
+    if (isNaN(timestamp)) {
+      return {
+        error: "invalid timestamp (number), please read documentation for more info"
+      };
+    }
+  } else {
+    return {
+      error: "invalid timestamp, please read documentation for more info"
+    };
+  }
+  const date = /* @__PURE__ */ new Date();
+  let isBefore2;
+  let duration;
+  if (timestamp instanceof Date) {
+    isBefore2 = date.getTime() > timestamp.getTime();
+    duration = date.getTime() - timestamp.getTime();
+  } else if (typeof timestamp === "string") {
+    const tsDate = new Date(timestamp);
+    isBefore2 = date.getTime() > tsDate.getTime();
+    duration = date.getTime() - tsDate.getTime();
+  } else {
+    isBefore2 = Date.now() > timestamp;
+    duration = Date.now() - timestamp;
+  }
+  return {
+    isBefore: isBefore2,
+    durationInMs: Math.abs(duration),
+    durationInSeconds: Math.abs(duration) / 1e3,
+    durationInMinutes: Math.abs(duration) / (1e3 * 60),
+    durationInHours: Math.abs(duration) / (1e3 * 60 * 60),
+    durationInDays: Math.abs(duration) / (1e3 * 60 * 60 * 24)
+  };
+}
+function isAfter(timestamp) {
+  if (timestamp instanceof Date) {
+    if (isNaN(timestamp.getTime())) {
+      return {
+        error: "invalid timestamp (date), please read documentation for more info"
+      };
+    }
+  } else if (typeof timestamp === "string") {
+    const tsDate = new Date(timestamp);
+    if (isNaN(tsDate.getTime())) {
+      return {
+        error: "invalid timestamp (string), please read documentation for more info"
+      };
     }
+  } else if (typeof timestamp === "number") {
+    if (isNaN(timestamp)) {
+      return {
+        error: "invalid timestamp (number), please read documentation for more info"
+      };
+    }
+  } else {
+    return {
+      error: "invalid timestamp, please read documentation for more info"
+    };
+  }
+  const date = /* @__PURE__ */ new Date();
+  let isAfter2;
+  let duration;
+  if (timestamp instanceof Date) {
+    isAfter2 = date.getTime() < timestamp.getTime();
+    duration = timestamp.getTime() - date.getTime();
+  } else if (typeof timestamp === "string") {
+    const tsDate = new Date(timestamp);
+    isAfter2 = date.getTime() < tsDate.getTime();
+    duration = tsDate.getTime() - date.getTime();
+  } else {
+    isAfter2 = Date.now() < timestamp;
+    duration = timestamp - Date.now();
+  }
+  return {
+    isAfter: isAfter2,
+    durationInMs: Math.abs(duration),
+    durationInSeconds: Math.abs(duration) / 1e3,
+    durationInMinutes: Math.abs(duration) / (1e3 * 60),
+    durationInHours: Math.abs(duration) / (1e3 * 60 * 60),
+    durationInDays: Math.abs(duration) / (1e3 * 60 * 60 * 24)
+  };
+}
+
+// src/utilities/relativeTime.ts
+function relativeTime(timestamp) {
+  if (timestamp === null || timestamp === void 0) {
+    return {
+      error: "timestamp is either null or undefined, please read documentation for more info"
+    };
+  }
+  const timestampDate = timestamp instanceof Date ? timestamp : new Date(timestamp);
+  if (timestampDate.toString() === "Invalid Date") {
+    return {
+      error: "invalid timestamp, please read documentation for more info"
+    };
+  }
+  let humanTxt;
+  const afterResult = isAfter(timestamp);
+  if ("error" in afterResult) {
+    return afterResult;
+  }
+  const durationType = afterResult.isAfter ? afterResult : isBefore(timestamp);
+  if ("error" in durationType) {
+    return durationType;
+  }
+  if (afterResult.isAfter) {
+    if (durationType.durationInSeconds < 60) {
+      humanTxt = `${Math.round(durationType.durationInSeconds)} second(s) ago`;
+    } else if (durationType.durationInMinutes < 60) {
+      humanTxt = `${Math.round(durationType.durationInMinutes)} minute(s) ago`;
+    } else if (durationType.durationInHours < 24) {
+      humanTxt = `${Math.round(durationType.durationInHours)} hour(s) ago`;
+    } else {
+      const months = Math.round(durationType.durationInDays / 30);
+      if (months < 12) {
+        humanTxt = `${months} month(s) ago`;
+      } else {
+        const years = Math.round(months / 12);
+        humanTxt = `${years} year(s) ago`;
+      }
+    }
+  } else {
+    return {
+      error: "invalid timestamp, please read documentation for more info"
+    };
+  }
+  return {
+    timestamp: Date.parse(timestampDate.toString()),
+    timestampDate,
+    humanReadable: humanTxt,
+    isInFuture: afterResult.isAfter
   };
 }
 // Annotate the CommonJS export names for ESM import in node:
@@ -969,5 +1134,8 @@ function createTimer() {
   getcurrentDateISO,
   getcurrentDateISOResponse,
   getcurrentTimeISO,
-  getcurrentTimeISOResponse
+  getcurrentTimeISOResponse,
+  isAfter,
+  isBefore,
+  relativeTime
 });

package/dist/index.mjs

@@ -790,9 +790,171 @@ function createTimer() {
         elapsedHrs: elapsed / 36e5,
         text: `${elapsed.toFixed(2)} ms`
       };
+    },
+    lap: () => {
+      if (startTime === null) {
+        return null;
+      }
+      const duration = performance.now() - startTime;
+      return {
+        durationMs: duration,
+        durationSec: duration / 1e3,
+        durationMin: duration / 6e4,
+        durationHrs: duration / 36e5,
+        text: `${duration.toFixed(2)} ms`
+      };
     }
   };
 }
+
+// src/utilities/diffChecker.ts
+function isBefore(timestamp) {
+  if (timestamp instanceof Date) {
+    if (isNaN(timestamp.getTime())) {
+      return {
+        error: "invalid timestamp (date), please read documentation for more info"
+      };
+    }
+  } else if (typeof timestamp === "string") {
+    const tsDate = new Date(timestamp);
+    if (isNaN(tsDate.getTime())) {
+      return {
+        error: "invalid timestamp (string), please read documentation for more info"
+      };
+    }
+  } else if (typeof timestamp === "number") {
+    if (isNaN(timestamp)) {
+      return {
+        error: "invalid timestamp (number), please read documentation for more info"
+      };
+    }
+  } else {
+    return {
+      error: "invalid timestamp, please read documentation for more info"
+    };
+  }
+  const date = /* @__PURE__ */ new Date();
+  let isBefore2;
+  let duration;
+  if (timestamp instanceof Date) {
+    isBefore2 = date.getTime() > timestamp.getTime();
+    duration = date.getTime() - timestamp.getTime();
+  } else if (typeof timestamp === "string") {
+    const tsDate = new Date(timestamp);
+    isBefore2 = date.getTime() > tsDate.getTime();
+    duration = date.getTime() - tsDate.getTime();
+  } else {
+    isBefore2 = Date.now() > timestamp;
+    duration = Date.now() - timestamp;
+  }
+  return {
+    isBefore: isBefore2,
+    durationInMs: Math.abs(duration),
+    durationInSeconds: Math.abs(duration) / 1e3,
+    durationInMinutes: Math.abs(duration) / (1e3 * 60),
+    durationInHours: Math.abs(duration) / (1e3 * 60 * 60),
+    durationInDays: Math.abs(duration) / (1e3 * 60 * 60 * 24)
+  };
+}
+function isAfter(timestamp) {
+  if (timestamp instanceof Date) {
+    if (isNaN(timestamp.getTime())) {
+      return {
+        error: "invalid timestamp (date), please read documentation for more info"
+      };
+    }
+  } else if (typeof timestamp === "string") {
+    const tsDate = new Date(timestamp);
+    if (isNaN(tsDate.getTime())) {
+      return {
+        error: "invalid timestamp (string), please read documentation for more info"
+      };
+    }
+  } else if (typeof timestamp === "number") {
+    if (isNaN(timestamp)) {
+      return {
+        error: "invalid timestamp (number), please read documentation for more info"
+      };
+    }
+  } else {
+    return {
+      error: "invalid timestamp, please read documentation for more info"
+    };
+  }
+  const date = /* @__PURE__ */ new Date();
+  let isAfter2;
+  let duration;
+  if (timestamp instanceof Date) {
+    isAfter2 = date.getTime() < timestamp.getTime();
+    duration = timestamp.getTime() - date.getTime();
+  } else if (typeof timestamp === "string") {
+    const tsDate = new Date(timestamp);
+    isAfter2 = date.getTime() < tsDate.getTime();
+    duration = tsDate.getTime() - date.getTime();
+  } else {
+    isAfter2 = Date.now() < timestamp;
+    duration = timestamp - Date.now();
+  }
+  return {
+    isAfter: isAfter2,
+    durationInMs: Math.abs(duration),
+    durationInSeconds: Math.abs(duration) / 1e3,
+    durationInMinutes: Math.abs(duration) / (1e3 * 60),
+    durationInHours: Math.abs(duration) / (1e3 * 60 * 60),
+    durationInDays: Math.abs(duration) / (1e3 * 60 * 60 * 24)
+  };
+}
+
+// src/utilities/relativeTime.ts
+function relativeTime(timestamp) {
+  if (timestamp === null || timestamp === void 0) {
+    return {
+      error: "timestamp is either null or undefined, please read documentation for more info"
+    };
+  }
+  const timestampDate = timestamp instanceof Date ? timestamp : new Date(timestamp);
+  if (timestampDate.toString() === "Invalid Date") {
+    return {
+      error: "invalid timestamp, please read documentation for more info"
+    };
+  }
+  let humanTxt;
+  const afterResult = isAfter(timestamp);
+  if ("error" in afterResult) {
+    return afterResult;
+  }
+  const durationType = afterResult.isAfter ? afterResult : isBefore(timestamp);
+  if ("error" in durationType) {
+    return durationType;
+  }
+  if (afterResult.isAfter) {
+    if (durationType.durationInSeconds < 60) {
+      humanTxt = `${Math.round(durationType.durationInSeconds)} second(s) ago`;
+    } else if (durationType.durationInMinutes < 60) {
+      humanTxt = `${Math.round(durationType.durationInMinutes)} minute(s) ago`;
+    } else if (durationType.durationInHours < 24) {
+      humanTxt = `${Math.round(durationType.durationInHours)} hour(s) ago`;
+    } else {
+      const months = Math.round(durationType.durationInDays / 30);
+      if (months < 12) {
+        humanTxt = `${months} month(s) ago`;
+      } else {
+        const years = Math.round(months / 12);
+        humanTxt = `${years} year(s) ago`;
+      }
+    }
+  } else {
+    return {
+      error: "invalid timestamp, please read documentation for more info"
+    };
+  }
+  return {
+    timestamp: Date.parse(timestampDate.toString()),
+    timestampDate,
+    humanReadable: humanTxt,
+    isInFuture: afterResult.isAfter
+  };
+}
 export {
   createTimer,
   getCurrenHrResponse,
@@ -868,5 +1030,8 @@ export {
   getcurrentDateISO,
   getcurrentDateISOResponse,
   getcurrentTimeISO,
-  getcurrentTimeISOResponse
+  getcurrentTimeISOResponse,
+  isAfter,
+  isBefore,
+  relativeTime
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "clockey",
-  "version": "1.2.0",
+  "version": "1.4.1",
   "description": "API-first time utilities for backend developers",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",