Beautiful, tiny utilities for working with current time and date in Node.js with ready-to-use API response wrappers for servers and lambdas.
{ success, code, msg, ... } shape for easy use in Express or serverless handlers.npm install clockey
CommonJS:
const { formatCurrentTime, currentHour24Str } = require("clockey");
console.log(formatCurrentTime());
console.log(currentHour24Str()); // '09'
ESM / TypeScript:
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):
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);
Below are grouped, easy-to-read tables for the package exports. Each table shows usage and what the function returns.
| 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' } |
| 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 } |
| 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 } |
| 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' } |
| 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: {...} } |
| 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' } |
| 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' } |
Success (example):
{
"success": true,
"code": 200,
"msg": "Current time fetched successfully",
"data": {
/* payload */
}
}
String only helper responses use value:
{
"success": true,
"code": 200,
"msg": "Current hour string fetched",
"value": "09"
}
Utility functions like isBefore(), isAfter(), and relativeTime() return error objects when invalid inputs are provided:
Error Response Format:
{
"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:
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:
// 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)