TinnovAce Time Module

GitHub

A lightweight time formatter with i18n support, future dates, real-time updates, and TypeScript types. Formats dates as "just now", "1h ago", or "in 5 minutes".

Features

14 Built-in Languages + Custom Language Support
Future Date Formatting ("in 5 minutes")
Real-Time Auto Updates (Perfect for UIs)
Customizable Thresholds (Control when units change)
TypeScript Ready with Full Type Definitions
Compact Mode ("1h" instead of "1 hour ago")
Smart Caching for High Performance

Installation

npm install cc-time-ago

Basic Usage

const { timeAgo } = require('cc-time-ago');

// Basic usage
console.log(timeAgo(Date.now() - 300000)); // "5 minutes ago"

// With options
console.log(timeAgo(Date.now() + 3600000, { 
  language: 'es',
  allowFuture: true
})); // "en 1 hora"

Advanced Usage

Custom Thresholds

timeAgo(date, {
  thresholds: {
    seconds: 120,  // Show seconds up to 2 minutes
    minutes: 3600  // Show minutes up to 1 hour
  }
});

Real-Time Updates (React/Vue/etc)

const { autoUpdate } = require('cc-time-ago');

const { stop } = autoUpdate(someDate, (formattedTime) => {
  console.log(formattedTime); // Updates every 30s
});

// Call stop() when done

Add Custom Languages

const { addLanguage } = require('cc-time-ago');

addLanguage('ko', {
  justNow: '방금',
  minuteAgo: '1분 전',
  // ...
});

Options

language (string, default: Auto-detected)
- Language code (e.g., 'es', 'fr')
compact (boolean, default: false)
- Compact format ("1h" vs "1 hour ago")
allowFuture (boolean, default: false)
- Format future dates ("in 5 minutes")
thresholds (object, default: See below)
- Custom unit thresholds

Default Thresholds

{
  seconds: 60,     // Show seconds until 1 minute
  minutes: 3600,   // Show minutes until 1 hour
  hours: 86400,    // Show hours until 1 day
  days: 604800,    // Show days until 1 week
  weeks: 2600640,  // Show weeks until ~1 month
  months: 31207680 // Show months until 1 year
}

Supported Languages

en - English
es - Spanish
fr - French
de - German
it - Italian
ar - Arabic
tr - Turkish
nl - Dutch
ja - Japanese
zh - Chinese
ru - Russian
pt - Portuguese
hi - Hindi

Missing a language?

Add it yourself or request it!

Contributing

1. Fork the repository

2. Add/Update languages in languages.js

3. Write tests for new features

4. Submit a PR

License

This project is licensed under the MIT License - see the LICENSE file for details.

3.0.0 - 2025-04-03

Added

Future Date Support: Format dates in the future ("in 5 minutes")

Threshold Customization: Control when time units switch (seconds→minutes→etc)

Real-Time Auto Updates: autoUpdate() for live-refreshing UIs

TypeScript Support: Full type definitions (index.d.ts)

Runtime Language Addition: addLanguage() method

Improved i18n: Use Intl.RelativeTimeFormat where available

Memoization Cache: 60s TTL for performance

Changed

Breaking: API now uses options object instead of positional args

// Old timeAgo(date, 'es', true); // New timeAgo(date, { language: 'es', compact: true });

Language Detection: More robust browser/Node.js environment checks

Documentation: Complete rewrite with interactive examples

Fixed

Proper pluralization for all languages

RTL support for Arabic

Timezone handling in Node.js

2.1.0 - 2024-07-13

Initial public release

Basic time formatting

14 language support

Compact mode

Key Documentation Updates

1. Modernized README: Interactive code samples, feature highlights, and options table

2. Clear Migration Guide: Breaking changes highlighted in CHANGELOG

3. TypeScript Support: Added badge and usage notes

4. Real-World Examples: React/Vue auto-update snippet

5. Contributor Focus: Simplified language addition process

Package detail

cc-time-ago

readme