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 📦

npm install @lmtuqs/lmtime

Quick Start 🚀

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 📖

LMTime Class

Constructor

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

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

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

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

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

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

Duration Class

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

Utility Functions

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 💡

Format Current Date

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'));

Calculate Age

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

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

Working with Durations

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

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

Date Range

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

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

Relative Time Display

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:

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!