🕒 disclock

disclock is a lightweight utility to convert JavaScript Date objects into Discord's dynamic timestamp format.

Make your Discord bot messages more human-friendly and time-zone aware using native Discord formatting.

✨ Features

• ✅ Supports all 7 Discord timestamp formats (t, T, d, D, f, F, R)
• ✅ Helpful input validation with error messages
• ✅ No dependencies
• ✅ Works with both CommonJS and ESM projects

📦 Installation

npm install disclock

📖 Documentation

| Name | Token | Description | Example Output | | -------------- | ----- | ------------------------ | -------------------------------- | | Short Time | t | Hours and minutes | 9:41 PM | | Long Time | T | Hours, minutes, seconds | 9:41:30 PM | | Short Date | d | Day, month, year | 17/07/2025 | | Long Date | D | Full date | 17 July 2025 | | Short DateTime | f | Full date and short time | 17 July 2025 9:41 PM | | Long DateTime | F | Full day, date and time | Thursday, 17 July 2025 9:41 PM | | Relative | R | Relative time | in 5 minutes, 2 hours ago |

🚀 Usage

ESM (ECMAScript Modules)

import { toDiscordTimestamp, FORMATS } from "disclock";

const date = new Date();
const timestamp = toDiscordTimestamp(date, FORMATS.RELATIVE);

console.log(timestamp); // <t:1721186545:R>

CommonJs (require syntax)

const { toDiscordTimestamp, FORMATS } = require("disclock");

const date = new Date();
const timestamp = toDiscordTimestamp(date, FORMATS.RELATIVE);

console.log(timestamp); // <t:1721186545:R>

🔧 API

toDiscordTimestamp(date, format?)

| Parameter | Type | Required | Description | | --------- | -------- | -------- | ---------------------------------------------- | | date | Date | ✅ | A valid JavaScript Date object | | format | string | ❌ | Format token, defaults to f (Short DateTime) |

Returns: A string like <t:1721186545:f> that you can embed in Discord messages.

FORMATS

An object containing all 7 Discord timestamp format tokens for easier access.

🤝 Contributing

Got ideas or suggestions? Open an issue or pull request — all contributions are welcome!