@nixat/chronos

A lightweight, type-safe date manipulation library for modern JavaScript and TypeScript projects.

Features

• 🚀 Lightweight - Zero dependencies, small bundle size
• 🔒 Type-safe - Written in TypeScript with comprehensive type definitions
• 📚 Well documented - Clear examples and API documentation
• ✅ Well tested - Comprehensive test suite with high coverage
• 🔧 Tree-shakable - Import only what you need
• 🌐 Universal - Works in Node.js and browsers

Installation

# Using npm
npm install @nixat/chronos

# Using yarn
yarn add @nixat/chronos

# Using pnpm
pnpm add @nixat/chronos

Usage

import { parse, format, add, subtract, relative } from '@nixat/chronos';

// Parse dates from various formats
const date = parse('2023-04-15');
const timestamp = parse(1681516800000);

// Format dates
const formatted = format(date, 'YYYY-MM-DD'); // '2023-04-15'
const readable = format(date, 'MMMM D, YYYY'); // 'April 15, 2023'

// Add time to dates
const nextWeek = add(date, { days: 7 });
const nextYear = add(date, { years: 1 });

// Subtract time from dates
const lastWeek = subtract(date, { days: 7 });
const lastYear = subtract(date, { years: 1 });

// Get relative time
const relativeTime = relative(date); // e.g., '2 months ago'

API

Date Parsing and Validation

• parse(input) - Parses a date from various input formats
• isValid(date) - Checks if a date is valid
• isBefore(date1, date2) - Checks if date1 is before date2
• isAfter(date1, date2) - Checks if date1 is after date2

Date Formatting

• format(date, formatString, options) - Formats a date according to the format string
• relative(date, baseDate, options) - Returns a string representing the relative time

Date Manipulation

• add(date, duration) - Adds time to a date
• subtract(date, duration) - Subtracts time from a date
• diff(date1, date2, unit) - Gets the difference between two dates in the specified unit

Format Tokens

| Token | Output | |-------|--------| | YYYY | 2023 | | YY | 23 | | MMMM | January | | MMM | Jan | | MM | 01 | | M | 1 | | DD | 01 | | D | 1 | | HH | 13 | | H | 13 | | hh | 01 | | h | 1 | | mm | 05 | | m | 5 | | ss | 09 | | s | 9 | | A | AM/PM | | a | am/pm |

Namespace

All functions are also available through the chronos namespace:

import { chronos } from '@nixat/chronos';

const date = chronos.parse('2023-04-15');
const formatted = chronos.format(date, 'YYYY-MM-DD');

License

MIT