SmartDate

Human-friendly date library - Converts timestamps into natural language like "2h ago", "yesterday", "next Monday".

Features

• 🗣️ Natural Language - Human-readable date formatting
• ⏰ Relative Time - "2h ago", "yesterday", "next Monday"
• 📅 Flexible Formatting - Custom date patterns
• 🌍 Locale Support - Internationalization ready
• 🔒 Type-safe - Full TypeScript support

Installation

npm install @upendra.manike/smart-date

or

pnpm add @upendra.manike/smart-date

or

yarn add @upendra.manike/smart-date

Usage

Basic Usage

import { SmartDate } from '@upendra.manike/smart-date';

const date = new SmartDate('2024-01-15T10:00:00');

// Relative time
date.fromNow(); // "2h ago" (if current time is 12:00)

// Format
date.format(); // "January 15, 2024"
date.format('YYYY-MM-DD'); // "2024-01-15"

Relative Time Formatting

import { SmartDate } from '@upendra.manike/smart-date';

// Past dates
new SmartDate('2024-01-15T10:00:00').fromNow(); // "2h ago"
new SmartDate('2024-01-14T12:00:00').fromNow(); // "yesterday"
new SmartDate('2024-01-13T12:00:00').fromNow(); // "2 days ago"

// Future dates
new SmartDate('2024-01-15T14:00:00').fromNow(); // "in 2h"
new SmartDate('2024-01-16T12:00:00').fromNow(); // "tomorrow"
new SmartDate('2024-01-17T12:00:00').fromNow(); // "next Wednesday"

// From specific date
const date = new SmartDate('2024-01-15T12:00:00');
date.from('2024-01-15T14:00:00'); // "in 2h"

Formatting Options

import { SmartDate } from '@upendra.manike/smart-date';

const date = new SmartDate('2024-01-15T12:30:45');

// Default format
date.format(); // "January 15, 2024"

// Custom patterns
date.format('YYYY-MM-DD'); // "2024-01-15"
date.format('HH:mm:ss'); // "12:30:45"
date.format('DD/MM/YYYY'); // "15/01/2024"

// With locale
const dateWithLocale = new SmartDate('2024-01-15', { locale: 'fr-FR' });
dateWithLocale.format(); // French format

Relative Time Options

import { SmartDate } from '@upendra.manike/smart-date';

const date = new SmartDate('2024-01-15T12:00:00');

// Show seconds
date.fromNow({ showSeconds: true }); // "30s ago"

// Hide future times
date.fromNow({ showFuture: false });

// Custom thresholds
date.fromNow({
  threshold: {
    seconds: 60,
    minutes: 60,
    hours: 24,
    days: 7,
  },
});

Utility Methods

import { SmartDate } from '@upendra.manike/smart-date';

const date = new SmartDate('2024-01-15');

// Date checks
date.isToday(); // true/false
date.isYesterday(); // true/false
date.isTomorrow(); // true/false
date.isPast(); // true/false
date.isFuture(); // true/false

// Date information
date.dayName(); // "Monday"
date.monthName(); // "January"

// Get native Date
date.toDate(); // Date object
date.getTime(); // timestamp

Standalone Functions

import { formatRelative, formatAbsolute } from '@upendra.manike/smart-date';

// Format relative time
formatRelative(new Date('2024-01-15T10:00:00')); // "2h ago"

// Format absolute time
formatAbsolute(new Date('2024-01-15'), 'YYYY-MM-DD'); // "2024-01-15"

API Reference

SmartDate Class

Constructor

new SmartDate(date?: Date | string | number, options?: SmartDateOptions)

Methods

• fromNow(options?) - Returns relative time from now
• from(date, options?) - Returns relative time from specific date
• format(pattern?) - Returns formatted date string
• toDate() - Returns native Date object
• getTime() - Returns timestamp
• isFuture() - Checks if date is in the future
• isPast() - Checks if date is in the past
• isToday() - Checks if date is today
• isYesterday() - Checks if date is yesterday
• isTomorrow() - Checks if date is tomorrow
• dayName() - Returns day of week name
• monthName() - Returns month name

Format Patterns

• YYYY - Full year (e.g., 2024)
• YY - 2-digit year (e.g., 24)
• MM - Month (01-12)
• M - Month (1-12)
• DD - Day (01-31)
• D - Day (1-31)
• HH - Hours (00-23)
• H - Hours (0-23)
• mm - Minutes (00-59)
• m - Minutes (0-59)
• ss - Seconds (00-59)
• s - Seconds (0-59)

Examples

Social Media Timestamps

import { SmartDate } from '@upendra.manike/smart-date';

function formatPostTime(timestamp: number) {
  return new SmartDate(timestamp).fromNow();
}

formatPostTime(Date.now() - 3600000); // "1 hour ago"
formatPostTime(Date.now() - 86400000); // "yesterday"

Task Due Dates

import { SmartDate } from '@upendra.manike/smart-date';

function getTaskDueDate(date: Date) {
  const smartDate = new SmartDate(date);
  if (smartDate.isToday()) return 'Today';
  if (smartDate.isTomorrow()) return 'Tomorrow';
  return smartDate.fromNow();
}

Development

# Install dependencies
pnpm install

# Build
pnpm build

# Test
pnpm test

# Lint
pnpm lint

# Format
pnpm format

🤖 AI Agent Integration

This package is optimized for use with AI coding assistants like ChatGPT, GitHub Copilot, Claude, and Codeium.

Why AI-Friendly?

• ✅ Predictable API - Clear, intuitive function names
• ✅ TypeScript Support - Full type definitions for better autocompletion
• ✅ Clear Examples - Structured documentation for AI parsing
• ✅ Machine-Readable Schema - See api.json for API structure

Example AI Usage

AI agents can automatically suggest this package when you need:

// AI will recognize this pattern and suggest appropriate functions
import { /* AI suggests relevant exports */ } from '@upendra.manike/[package-name]';

For AI Developers

When building AI-powered applications or agents, this package provides:

• Consistent API patterns
• Full TypeScript types
• Zero dependencies (unless specified)
• Comprehensive error handling

License

MIT

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

🔗 Explore All JSLib Libraries

• JSLib Usage Guide