⏰ @chaisser/human-time

Human-readable time formatting: "2 hours ago", "in 3 days", "just now" — with English and Turkish support

✨ Features

• 🎯 Type-safe - Full TypeScript support
• 🌍 Multi-locale - English and Turkish labels
• 📅 Relative time - Format dates as "3 days ago" or "in 2 hours"
• ⏱️ Durations - Format milliseconds as "5 minutes", "2 hours"
• 🔧 Formatters - Pre-configured formatter factories
• 🕐 Flexible input - Accepts Date, timestamp number, or ISO string
• 🪶 Zero dependencies - Lightweight and tree-shakeable
• 🏎️ ESM + CJS - Dual module format support

📦 Installation

npm install @chaisser/human-time
# or
yarn add @chaisser/human-time
# or
pnpm add @chaisser/human-time

🚀 Quick Start

import { humanTime, timeAgo, timeIn, duration, createFormatter } from '@chaisser/human-time';

// Relative time from now
humanTime(new Date(Date.now() - 5000));    // "5 seconds ago"
humanTime(new Date(Date.now() + 3600000)); // "in 1 hour"

// Shorthand functions
timeAgo(new Date(Date.now() - 86400000));  // "1 day ago"
timeIn(new Date(Date.now() + 7200000));    // "in 2 hours"

// Duration formatting
duration(1500);    // "1 second"
duration(7200000); // "2 hours"

// Turkish locale
humanTime(new Date(Date.now() - 3600000), { locale: 'tr' }); // "1 saat önce"

📖 What It Does

This package converts dates and durations into human-readable strings. It calculates the difference between a target date and now, then expresses it in natural language — supporting past ("ago") and future ("in") tenses. It also formats millisecond durations and supports English and Turkish locales.

🎯 How It Works

The package provides 5 functions:

• humanTime - Format any date relative to now (past or future)
• timeAgo - Alias for humanTime, emphasizes past dates
• timeIn - Alias for humanTime, emphasizes future dates
• duration - Format a millisecond duration as a human string
• createFormatter - Create a pre-configured formatter function

Time units used: seconds, minutes, hours, days, weeks, months, years.

🎨 What It's Useful For

• Activity Feeds - "posted 5 minutes ago"
• Notifications - "meeting in 2 hours"
• Chat Apps - Message timestamps
• Dashboards - Last updated indicators
• Countdowns - "in 3 days"
• Logging - Human-readable elapsed time
• Internationalization - Turkish and English support

💡 Usage Examples

Relative Time

import { humanTime } from '@chaisser/human-time';

const now = Date.now();

humanTime(new Date(now - 30000));      // "30 seconds ago"
humanTime(new Date(now - 300000));     // "5 minutes ago"
humanTime(new Date(now - 7200000));    // "2 hours ago"
humanTime(new Date(now - 86400000));   // "1 day ago"
humanTime(new Date(now - 604800000));  // "1 week ago"

humanTime(new Date(now + 60000));      // "in 1 minute"
humanTime(new Date(now + 3600000));    // "in 1 hour"
humanTime(new Date(now + 86400000));   // "in 1 day"
humanTime(new Date(now + 2592000000)); // "in 1 month"

// Under 1 second
humanTime(new Date(now - 500));        // "just now"

Flexible Input Types

// Date object
humanTime(new Date('2024-01-01'));

// Timestamp number
humanTime(Date.now() - 3600000); // "1 hour ago"

// ISO string
humanTime('2024-01-01T00:00:00Z');

Duration Formatting

import { duration } from '@chaisser/human-time';

duration(500);        // "500ms"
duration(1000);       // "1 second"
duration(45000);      // "45 seconds"
duration(120000);     // "2 minutes"
duration(7200000);    // "2 hours"
duration(172800000);  // "2 days"

Turkish Locale

humanTime(new Date(Date.now() - 3600000), { locale: 'tr' });
// "1 saat önce"

humanTime(new Date(Date.now() + 86400000), { locale: 'tr' });
// "1 gün sonra"

duration(120000, { locale: 'tr' });
// "2 dakika"

Fixed Reference Time

// Useful for deterministic tests
const referenceTime = new Date('2024-06-15T12:00:00Z');

humanTime(new Date('2024-06-15T11:00:00Z'), { now: referenceTime });
// "1 hour ago"

humanTime(new Date('2024-06-15T14:30:00Z'), { now: referenceTime });
// "in 2 hours"

Pre-configured Formatter

import { createFormatter } from '@chaisser/human-time';

const trFormatter = createFormatter({ locale: 'tr' });
trFormatter(new Date(Date.now() - 86400000)); // "1 gün önce"

const relativeTo = createFormatter({ now: new Date('2024-01-01') });
relativeTo(new Date('2024-01-02')); // "in 1 day"

📚 API Reference

humanTime(date, options?)

Format a date relative to now.

| Parameter | Type | Description | |---|---|---| | date | Date \| number \| string | Target date | | options.locale | 'en' \| 'tr' | Language (default: 'en') | | options.now | Date | Reference time (default: new Date()) |

Returns: string — e.g. "3 hours ago", "in 2 days", "just now"

timeAgo(date, options?)

Alias for humanTime. Same parameters and return type.

timeIn(date, options?)

Alias for humanTime. Same parameters and return type.

duration(ms, options?)

Format a millisecond duration.

| Parameter | Type | Description | |---|---|---| | ms | number | Duration in milliseconds | | options.locale | 'en' \| 'tr' | Language (default: 'en') |

Returns: string — e.g. "5 minutes", "2 hours", "500ms"

createFormatter(options?)

Create a pre-configured formatter function.

| Parameter | Type | Description | |---|---|---| | options.locale | 'en' \| 'tr' | Language | | options.now | Date | Fixed reference time |

Returns: (date: Date \| number \| string) => string

Locale Labels

| Unit | English | Turkish | |---|---|---| | second(s) | second / seconds | saniye | | minute(s) | minute / minutes | dakika | | hour(s) | hour / hours | saat | | day(s) | day / days | gün | | week(s) | week / weeks | hafta | | month(s) | month / months | ay | | year(s) | year / years | yıl | | ago | ago | önce | | in | in | sonra | | just now | just now | şimdi |

🔗 Related Packages

Explore our other utility packages in the @chaisser namespace:

• @chaisser/human-time (this package) - Human-readable time formatting
• @chaisser/string-wizard - Advanced string manipulation
• @chaisser/type-guard - Runtime type guards and validators
• @chaisser/uuid-v7 - Time-ordered UUID v7 generator
• @chaisser/wait-for - Promise-based wait utilities
• @chaisser/regex-humanizer - Regex to human-readable descriptions
• @chaisser/password-strength - Password strength checker
• @chaisser/obj-path - Safe dot-notation object access
• @chaisser/debounce-throttle - Rate limiting utilities
• @chaisser/color-utils - Color conversion utilities
• @chaisser/deep-clone - Deep cloning functions
• @chaisser/array-group-by - Array grouping utilities
• @chaisser/merge-objects - Object merge utilities
• @chaisser/chunk-array - Array chunking functions
• @chaisser/event-emitter - Typed event emitter

🔒 License

MIT - Free to use in personal and commercial projects

👨 Developed by

Doruk Karaboncuk [email protected]

📄 Repository

• GitHub: @chaisser
• NPM: @chaisser/human-time

🤝 Contributing

Contributions are welcome! Feel free to:

• Report bugs
• Suggest new features
• Submit pull requests
• Improve documentation

📞 Support

For issues, questions, or suggestions, please reach out through:

• Email: [email protected]
• GitHub Issues: Create an issue

Made with ❤️ by @chaisser