Usage

import { formatTimestamp } from "little-timestamp";

const today = new Date("2025-06-02T12:00:00.000Z"); // For testing purposes
const timestamp = new Date("2025-06-02T06:00:00.000Z"); // 6am

console.log(formatTimestamp(timestamp, { today })); // Outputs: "6h ago"

Installation

With Bun

bun add little-timestamp

With NPM

npm i little-timestamp

Formatting Examples

| Description | Output | | ------------------- | --------------- | | Past | | | <1s | Just now | | 1-59s | "N"s ago | | 1-59m | "N"m ago | | 1-23h | "N"h ago | | >24h | Jun 1 | | >24h different year | Jun 1, 2024 | | Future | | | 1-59s | "N"s from now | | 1-59m | "N"m from now | | 1-23h | "N"h from now | | >24h | Jun 1 | | >24h different year | Jun 1, 2026 |

Advanced Options

Most of the formatting behavior is opinionated and can't be changed. However, there are some options that can be used to customize the output.

import { formatTimestamp } from "little-timestamp";

// ...

formatTimestamp(timestamp, {
  locale: "es-ES", // Overwrite the default date locale
  today: new Date(), // Overwrite the default "today" date, useful for testing purposes
});

Contribute

We welcome contributions! If you'd like to improve little-timestamp or have any feedback, feel free to open an issue or submit a pull request.

License

MIT