Tickgow

Date comparison and human-readable time formatting.

Overview

Tickgow lets you compare two dates, giving you detailed calculated outputs on exactly how much time has passed.

• Get both normalized and raw time differences between two dates.
• Easily convert dates into relative strings like "5 months ago", "in 2 days", or "just now".
• Work Node.js and the browser.

Installation & Usage

Installation

Browser

Include the script tag:

<script src="https://cdn.jsdelivr.net/gh/rezzvy/tickgow@2a4bd62/dist/tickgow.min.js"></script>

Node

Install via npm:

npm install tickgow

const Tickgow = require("tickgow");

Usage

Tickgow.compare("2020-01-01", "2026-01-01");
Tickgow.now(Date.now());

Examples

Human-Readable Time

// Assuming today is April 2026
const past = Tickgow.now("2026-04-01");
// "1 week ago"

const future = Tickgow.now("2028-01-01");
// "in 1 year"

const rightNow = Tickgow.now(Date.now());
// "just now"

Date Comparison

const comparison = Tickgow.compare("2020-01-01", "2026-01-01");
console.log(comparison.years); // 6
console.log(comparison.isFuture); // false
console.log(comparison.raw.days); // 2192

Custom Labels

Note

Baru saja is Indonesian meaning "just now"

Tickgow.defaultLabels.now = "Baru saja";

const rightNow = Tickgow.now(Date.now());
// "Baru saja"

Documentation

API Reference

Tickgow.now(date)

Calculates the difference between the provided date and the current time (Date.now()), returning a human-readable string based on the largest unit of time passed.

Parameter	Type	Description
date	String | Number | Date	The target date to compare against the current time.

Returns: String (e.g., "2 years ago", "in 5 minutes", "just now")

Tickgow.compare(date1, date2)

Compares two dates and returns a detailed object containing both normalized calendar units and raw total units.

Parameter	Type	Description
date1	String | Number | Date	The first date for comparison.
date2	String | Number | Date	The second date for comparison.

Returns: Object

Property	Type	Description
isFuture	Boolean	true if date1 is further in the future than date2.
years	Number	Normalized years difference.
months	Number	Normalized months difference.
days	Number	Normalized days difference.
hours	Number	Normalized hours difference.
minutes	Number	Normalized minutes difference.
seconds	Number	Normalized seconds difference.
raw	Object	Contains the raw total differences between the dates.
raw.ms	Number	Total difference in milliseconds.
raw.seconds	Number	Total difference in seconds.
raw.minutes	Number	Total difference in minutes.
raw.hours	Number	Total difference in hours.
raw.days	Number	Total difference in days.
raw.months	Number	Total difference in decimal months.
raw.years	Number	Total difference in decimal years.

Tickgow.defaultLabels

A static object containing the default vocabulary used by the now() method to format relative time strings. You can modify this object to customize the output or localize the strings into different languages.

Default Value:

Tickgow.defaultLabels = {
  year: { singular: "year", plural: "years", past: "ago", future: "in" },
  month: { singular: "month", plural: "months", past: "ago", future: "in" },
  day: { singular: "day", plural: "days", past: "ago", future: "in" },
  hour: { singular: "hour", plural: "hours", past: "ago", future: "in" },
  min: { singular: "minute", plural: "minutes", past: "ago", future: "in" },
  sec: { singular: "second", plural: "seconds", past: "ago", future: "in" },
  now: "just now",
};

Contributing

There's always room for improvement. Feel free to contribute!

Licensing

The project is licensed under the MIT License. Check the license file for more details.