API-first time utilities for backend developers
npm install clockey{ success, code, msg, ... } shape for easy use in Express or serverless handlers.
bash
npm install clockey
`
---
⚙️ Quick Examples
CommonJS:
`js
const { formatCurrentTime, currentHour24Str } = require("clockey");
console.log(formatCurrentTime());
console.log(currentHour24Str()); // '09'
`
ESM / TypeScript:
`ts
import { getCurrentTimeResponse } from "clockey/response/timeResponse";
import { createTimer, isBefore, relativeTime } from "clockey";
console.log(getCurrentTimeResponse());
// Timer example
const timer = createTimer();
timer.start();
// ... some code ...
console.log(timer.end());
// Diff checker example
const pastDate = new Date("2025-12-25");
console.log(isBefore(pastDate)); // Check if date is before now
// Relative time example
console.log(relativeTime("2025-12-25")); // Human-readable relative time
`
Express example (route):
`js
const express = require("express");
const { getCurrentTimeResponse } = require("clockey/response/timeResponse");
const app = express();
app.get("/api/time", (req, res) => res.json(getCurrentTimeResponse()));
app.listen(3000);
`
---
📚 Methods (Quick usage)
Below are grouped, easy-to-read tables for the package exports. Each table shows usage and what the function returns.
$3
#### Timer
| Name | Example Usage | Output Format | Example Data |
| --------------- | ------------------------------ | ----------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- |
| createTimer() | const timer = createTimer(); | { start, end, lap } | Returns object with start(), end(), and lap() methods for performance timing |
| timer.start() | timer.start(); | void | Starts the timer |
| timer.end() | const result = timer.end(); | { elapsedMs, elapsedSec, elapsedMin, elapsedHrs, text } \| null | { elapsedMs: 1234.5, elapsedSec: 1.23, elapsedMin: 0.02, elapsedHrs: 0.0003, text: '1234.50 ms' } |
| timer.lap() | const result = timer.lap(); | { durationMs, durationSec, durationMin, durationHrs, text } \| null | { durationMs: 1234.5, durationSec: 1.23, durationMin: 0.02, durationHrs: 0.0003, text: '1234.50 ms' } |
#### Diff Checker
| Name | Example Usage | Output Format | Example Data |
| ------------ | ------------------------------------- | ------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------- |
| isBefore() | const result = isBefore(timestamp); | { isBefore, durationInMs, durationInSeconds, durationInMinutes, durationInHours, durationInDays } \| { error } | { isBefore: true, durationInMs: 5000, durationInSeconds: 5, durationInMinutes: 0.08, durationInHours: 0.001, durationInDays: 0.00006 } |
| isAfter() | const result = isAfter(timestamp); | { isAfter, durationInMs, durationInSeconds, durationInMinutes, durationInHours, durationInDays } \| { error } | { isAfter: false, durationInMs: 5000, durationInSeconds: 5, durationInMinutes: 0.08, durationInHours: 0.001, durationInDays: 0.00006 } |
#### Relative Time
| Name | Example Usage | Output Format | Example Data |
| ---------------- | ----------------------------------------- | ------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------- |
| relativeTime() | const result = relativeTime(timestamp); | { timestamp, timestampDate, humanReadable, isInFuture } \| { error } | { timestamp: 1735334400000, timestampDate: Date, humanReadable: '2 hours ago', isInFuture: false } |
$3
| Name | Example Usage | Output Format | Example Data |
| --------------------- | ----------------------------------- | ---------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| formatCurrentTime() | const time = formatCurrentTime(); | { hr24, hr12, min, sec, period, hr24Str, hr12Str, minStr, secStr, timeAsString24, timeAsString12 } | { hr24: 9, hr12: 9, min: 5, sec: 7, period: 'AM', hr24Str: '09', hr12Str: '09', minStr: '05', secStr: '07', timeAsString24: '09:05:07', timeAsString12: '09:05:07 AM' } |
| currentHour() | const hr = currentHour(); | { hour24, hour12, hour24Str, hour12Str } | { hour24: 9, hour12: 9, hour24Str: '09', hour12Str: '09' } |
| currentMinute() | const min = currentMinute(); | { minute, minuteStr } | { minute: 5, minuteStr: '05' } |
| currentSecond() | const sec = currentSecond(); | { second, secondStr } | { second: 7, secondStr: '07' } |
| currentHour24Str() | const h = currentHour24Str(); | string | '09' |
| currentHour12Str() | const h = currentHour12Str(); | string | '09' |
| currentMinuteStr() | const m = currentMinuteStr(); | string | '05' |
| currentSecondStr() | const s = currentSecondStr(); | string | '07' |
| currentPeriod() | const p = currentPeriod(); | { period } | { period: 'AM' } |
$3
| Name | Example Usage | Output Format | Example Data |
| ------------------------------- | ------------------------------------------ | ------------------------------------ | ----------------------------------------------------------------------------------------- |
| getCurrentTime() | const data = getCurrentTime(); | { timeAsString12, timeAsString24 } | { timeAsString12: '09:05:07 AM', timeAsString24: '09:05:07' } |
| getCurrentTimeResponse() | res.json(getCurrentTimeResponse()); | { success, code, msg, data } | { success: true, code: 200, msg: 'Current time fetched successfully', data: {...} } |
| getCurrentHr() | const hr = getCurrentHr(); | returns currentHour() | { hour24: 9, hour12: 9, hour24Str: '09', hour12Str: '09' } |
| getCurrentHrResponse() | res.json(getCurrentHrResponse()); | { success, code, msg, hour } | { success: true, code: 200, msg: 'Current hour fetched successfully', hour: {...} } |
| getCurrentMinute() | const min = getCurrentMinute(); | returns currentMinute() | { minute: 5, minuteStr: '05' } |
| getCurrentMinuteResponse() | res.json(getCurrentMinuteResponse()); | { success, code, msg, minute } | { success: true, code: 200, msg: 'Current minute fetched successfully', minute: {...} } |
| getCurrentSecond() | const sec = getCurrentSecond(); | returns currentSecond() | { second: 7, secondStr: '07' } |
| getCurrentSecondResponse() | res.json(getCurrentSecondResponse()); | { success, code, msg, second } | { success: true, code: 200, msg: 'Current second fetched successfully', second: {...} } |
| getCurrentHour24Str() | const h = getCurrentHour24Str(); | string | '09' |
| getCurrentHour24StrResponse() | res.json(getCurrentHour24StrResponse()); | { success, code, msg, value } | { success: true, code: 200, msg: 'Current hour24 string fetched', value: '09' } |
| getCurrentHour12Str() | const h = getCurrentHour12Str(); | string | '09' |
| getCurrentHour12StrResponse() | res.json(getCurrentHour12StrResponse()); | { success, code, msg, value } | { success: true, code: 200, msg: 'Current hour12 string fetched', value: '09' } |
| getCurrentMinuteStr() | const m = getCurrentMinuteStr(); | string | '05' |
| getCurrentMinuteStrResponse() | res.json(getCurrentMinuteStrResponse()); | { success, code, msg, value } | { success: true, code: 200, msg: 'Current minute string fetched', value: '05' } |
| getCurrentSecondStr() | const s = getCurrentSecondStr(); | string | '07' |
| getCurrentSecondStrResponse() | res.json(getCurrentSecondStrResponse()); | { success, code, msg, value } | { success: true, code: 200, msg: 'Current second string fetched', value: '07' } |
| getCurrentPeriod() | const p = getCurrentPeriod(); | { period } | { period: 'AM' } |
| getCurrentPeriodResponse() | res.json(getCurrentPeriodResponse()); | { success, code, msg, period } | { success: true, code: 200, msg: 'Current period fetched successfully', period: {...} } |
$3
| Name | Example Usage | Output Format | Example Data |
| --------------------- | ----------------------------------- | ------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| formatCurrentDate() | const date = formatCurrentDate(); | { date: { yr, month, day, date, ordinal, fullDate } } | { date: { yr: 2025, month: 'December', day: 'Wednesday', date: 24, ordinal: 'th', fullDate: 'December 24th, Wednesday, 2025' } } |
| currentYear() | const yr = currentYear(); | number | 2025 |
| currentMonth() | const mon = currentMonth(); | { monthNumber, monthName, monthStr } | { monthNumber: 12, monthName: 'December', monthStr: '12' } |
| currentDay() | const day = currentDay(); | { dayIndex, dayName } | { dayIndex: 3, dayName: 'Wednesday' } |
| currentDateNumber() | const d = currentDateNumber(); | { date, dateStr } | { date: 24, dateStr: '24' } |
| currentOrdinal() | const ord = currentOrdinal(); | { ordinal } | { ordinal: 'th' } |
| currentFullDate() | const full = currentFullDate(); | { fullDate } | { fullDate: 'December 24th, Wednesday, 2025' } |
$3
| Name | Example Usage | Output Format | Example Data |
| -------------------------------- | ------------------------------------------- | ------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
| getCurrentDate() | res.json(getCurrentDate()); | { success, code, msg, data } | { success: true, code: 200, msg: 'Current date fetched successfully', data: {...} } |
| getCurrentYearResponse() | res.json(getCurrentYearResponse()); | { success, code, msg, value } | { success: true, code: 200, msg: 'Current year fetched successfully', value: 2025 } |
| getCurrentMonthResponse() | res.json(getCurrentMonthResponse()); | { success, code, msg, value } | { success: true, code: 200, msg: 'Current month fetched successfully', value: {...} } |
| getCurrentDayResponse() | res.json(getCurrentDayResponse()); | { success, code, msg, value } | { success: true, code: 200, msg: 'Current day fetched successfully', value: {...} } |
| getCurrentDateNumberResponse() | res.json(getCurrentDateNumberResponse()); | { success, code, msg, value } | { success: true, code: 200, msg: 'Current date number fetched successfully', value: {...} } |
| getCurrentOrdinalResponse() | res.json(getCurrentOrdinalResponse()); | { success, code, msg, value } | { success: true, code: 200, msg: 'Current ordinal fetched successfully', value: {...} } |
| getCurrentFullDateResponse() | res.json(getCurrentFullDateResponse()); | { success, code, msg, value } | { success: true, code: 200, msg: 'Current full date fetched successfully', value: 'December 24th, Wednesday, 2025' } |
---
✅ Response shapes
Success (example):
`json
{
"success": true,
"code": 200,
"msg": "Current time fetched successfully",
"data": {
/ payload /
}
}
`
String only helper responses use value:
`json
{
"success": true,
"code": 200,
"msg": "Current hour string fetched",
"value": "09"
}
`
❌ Error Handling
Utility functions like isBefore(), isAfter(), and relativeTime() return error objects when invalid inputs are provided:
Error Response Format:
`json
{
"error": "invalid timestamp, please read documentation for more info"
}
`
Common Error Cases:
| Error Type | Example | How to Fix |
| ------------------- | ----------------------------------------- | ------------------------------------------------------------------ |
| Invalid Date String | isBefore('not-a-date') | Use valid ISO 8601 format: isBefore('2025-12-25') |
| Invalid Date Object | isBefore(new Date('invalid')) | Create valid Date: isBefore(new Date()) |
| NaN Number | isBefore(NaN) | Pass valid timestamp number: isBefore(1735334400000) |
| Null/Undefined | isBefore(null) or isBefore(undefined) | Ensure value is provided: isBefore(timestamp) |
| Invalid Type | isBefore({}) | Use Date, number (milliseconds), or string: isBefore(new Date()) |
Example Error Handling:
`ts
import { isBefore, relativeTime } from "clockey";
const result = isBefore("2025-12-25");
// Check for error
if ("error" in result) {
console.error("Error:", result.error);
// Handle the error appropriately
} else {
console.log("Duration:", result.durationInSeconds, "seconds");
}
`
Accepted Timestamp Formats:
`ts
// All of these are valid:
isBefore(new Date("2025-12-25")); // Date object
isBefore("2025-12-25"); // ISO 8601 string
isBefore("2025-12-25T10:30:00Z"); // ISO 8601 with time
isBefore(1735334400000); // Unix timestamp in milliseconds
isBefore(1735334400); // Unix timestamp in seconds (converted to ms)
``