little-timestamp

A small & opinionated timestamp formatting library

_{Built by Matt Simpson | Inspired by Steven Tey & Timo Lins}

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