LMTime ⏰

A powerful and lightweight TypeScript library for time, date formatting, and calculations.

Features ✨

- 🎯 Simple API - Easy to use and intuitive
- 📅 Date Formatting - Flexible date/time formatting with custom tokens
- ⏱️ Duration Handling - Work with time durations effortlessly
- 🔄 Date Calculations - Add, subtract, and compare dates
- 🌍 Timezone Support - Built-in timezone utilities
- 📊 Relative Time - "2 hours ago", "in 3 days", etc.
- 🎨 TypeScript - Full TypeScript support with type definitions
- 🪶 Lightweight - Zero dependencies

Installation 📦

``bash
npm install @lmtuqs/lmtime
`

Quick Start 🚀

`typescript
import lmtime, { duration, timeAgo } from '@lmtuqs/lmtime';

// Create a new time instance
const now = lmtime();
console.log(now.format('YYYY-MM-DD HH:mm:ss'));
// Output: 2026-01-27 09:57:56

// Format dates
const date = lmtime('2026-01-27');
console.log(date.format('DD/MM/YYYY')); // 27/01/2026
console.log(date.format('MMMM DD, YYYY')); // January 27, 2026

// Add/subtract time
const tomorrow = lmtime().add(1, 'day');
const lastWeek = lmtime().subtract(1, 'week');

// Compare dates
const isBefore = date.isBefore(tomorrow); // true
const isAfter = date.isAfter(lastWeek); // true

// Relative time
console.log(timeAgo('2026-01-26')); // "1 day ago"
console.log(timeAgo('2026-01-28')); // "in 1 day"

// Duration
const dur = duration(90, 'minutes');
console.log(dur.asHours()); // 1.5
console.log(dur.humanize()); // "1 hour, 30 minutes"
`

API Documentation 📖

$3

#### Constructor

`typescript
import lmtime from '@lmtuqs/lmtime';

// Current time
const now = lmtime();

// From date string
const date1 = lmtime('2026-01-27');

// From timestamp
const date2 = lmtime(1706342400000);

// From Date object
const date3 = lmtime(new Date());
`

#### Formatting

`typescript
const time = lmtime('2026-01-27 15:30:45');

time.format('YYYY-MM-DD'); // "2026-01-27"
time.format('DD/MM/YYYY'); // "27/01/2026"
time.format('HH:mm:ss'); // "15:30:45"
time.format('hh:mm A'); // "03:30 PM"
time.format('YYYY-MM-DD HH:mm:ss'); // "2026-01-27 15:30:45"
`

Format Tokens:
- YYYY - 4-digit year (2026)
- YY - 2-digit year (26)
- MM - 2-digit month (01-12)
- M - Month without leading zero (1-12)
- DD - 2-digit day (01-31)
- D - Day without leading zero (1-31)
- HH - 2-digit hour, 24h format (00-23)
- hh - 2-digit hour, 12h format (01-12)
- h - Hour without leading zero, 12h format (1-12)
- mm - 2-digit minute (00-59)
- m - Minute without leading zero (0-59)
- ss - 2-digit second (00-59)
- s - Second without leading zero (0-59)
- SSS - Milliseconds (000-999)
- A - AM/PM
- a - am/pm

#### Date Manipulation

`typescript
const date = lmtime('2026-01-27');

// Add time
date.add(1, 'day');
date.add(2, 'week');
date.add(3, 'month');
date.add(1, 'year');

// Subtract time
date.subtract(1, 'hour');
date.subtract(30, 'minute');
date.subtract(5, 'second');

// Start/End of time unit
date.startOf('day'); // 2026-01-27 00:00:00
date.endOf('day'); // 2026-01-27 23:59:59
date.startOf('month'); // 2026-01-01 00:00:00
date.endOf('year'); // 2026-12-31 23:59:59
`

#### Comparison

`typescript
const date1 = lmtime('2026-01-27');
const date2 = lmtime('2026-01-28');

date1.isBefore(date2); // true
date1.isAfter(date2); // false
date1.isSame(date2); // false
date1.isSame(date1); // true

// Compare by unit
date1.isSame(date2, 'month'); // true
date1.isSame(date2, 'year'); // true
`

#### Difference

`typescript
const date1 = lmtime('2026-01-27');
const date2 = lmtime('2026-01-28');

date2.diff(date1, 'day'); // 1
date2.diff(date1, 'hour'); // 24
date2.diff(date1, 'minute'); // 1440
`

#### Utilities

`typescript
const date = lmtime('2026-01-27');

date.isLeapYear(); // false
date.daysInMonth(); // 31
date.dayOfWeek(); // 1 (Monday)
date.dayOfYear(); // 27
date.weekOfYear(); // 5

date.toDate(); // Native Date object
date.valueOf(); // Timestamp in milliseconds
date.unix(); // Unix timestamp in seconds
date.toISOString(); // ISO 8601 string
`

$3

`typescript
import { duration } from '@lmtuqs/lmtime';

// Create duration
const dur1 = duration(2, 'hours');
const dur2 = duration({ hours: 2, minutes: 30 });

// Convert to different units
dur1.asMilliseconds(); // 7200000
dur1.asSeconds(); // 7200
dur1.asMinutes(); // 120
dur1.asHours(); // 2
dur1.asDays(); // 0.083...

// Format duration
dur1.format('HH:mm:ss'); // "02:00:00"
dur2.format('HH:mm'); // "02:30"

// Humanize
dur1.humanize(); // "2 hours"
dur2.humanize(); // "2 hours, 30 minutes"
dur1.humanize(true); // "2h" (short format)

// Arithmetic
const dur3 = dur1.add(dur2); // 4.5 hours
const dur4 = dur2.subtract(dur1); // 0.5 hours
`

$3

`typescript
import {
timeAgo,
fromNow,
isToday,
isYesterday,
isTomorrow,
isWeekend,
daysBetween,
getAge,
sleep
} from '@lmtuqs/lmtime';

// Relative time
timeAgo('2026-01-26'); // "1 day ago"
fromNow('2026-01-28'); // "in 1 day"

// Date checking
isToday(new Date()); // true
isYesterday('2026-01-26'); // true
isTomorrow('2026-01-28'); // true
isWeekend('2026-01-25'); // true (Saturday)

// Calculations
daysBetween('2026-01-01', '2026-01-31'); // 30
getAge('1990-01-01'); // 36

// Async utilities
await sleep(1000); // Sleep for 1 second

// Measure execution time
const { result, duration } = await measureTime(async () => {
// Your code here
return 'done';
});
console.log(Took ${duration.humanize()});

// Countdown timer
const stop = countdown('2026-12-31', (remaining) => {
console.log(Time left: ${remaining.humanize()});
});
// Call stop() to cancel the countdown
`

Examples 💡

$3

`typescript
import lmtime from '@lmtuqs/lmtime';

const now = lmtime();
console.log(now.format('YYYY-MM-DD HH:mm:ss'));
console.log(now.format('DD/MM/YYYY'));
console.log(now.format('hh:mm A'));
`

$3

`typescript
import { getAge } from '@lmtuqs/lmtime';

const age = getAge('1990-05-15');
console.log(You are ${age} years old);
`

$3

`typescript
import { duration } from '@lmtuqs/lmtime';

const meeting = duration({ hours: 1, minutes: 30 });
console.log(Meeting duration: ${meeting.humanize()});
console.log(In minutes: ${meeting.asMinutes()});
`

$3

`typescript
import { dateRange } from '@lmtuqs/lmtime';

const dates = dateRange('2026-01-01', '2026-01-07');
dates.forEach(date => {
console.log(date.toISOString());
});
`

$3

`typescript
import { timeAgo } from '@lmtuqs/lmtime';

const posts = [
{ title: 'Post 1', createdAt: '2026-01-27 08:00:00' },
{ title: 'Post 2', createdAt: '2026-01-26 15:30:00' },
{ title: 'Post 3', createdAt: '2026-01-25 10:00:00' }
];

posts.forEach(post => {
console.log(${post.title} - ${timeAgo(post.createdAt)});
});
`

TypeScript Support 🔷

This library is written in TypeScript and includes full type definitions:

`typescript
import lmtime, { LMTime, Duration, TimeUnit } from '@lmtuqs/lmtime';

const date: LMTime = lmtime();
const unit: TimeUnit = 'day';
const future: LMTime = date.add(1, unit);
``

License 📄

ISC

Author 👨‍💻

lmtuqs

Contributing 🤝

Contributions, issues, and feature requests are welcome!

Support ⭐

If you like this project, please give it a star on GitHub!