date-fns-utils

npm install date-fns-utils

Overview

A collection of lightweight utility functions for date manipulation, built on top of date-fns. Provides common date operations with a simple, functional API.

Installation

npm install date-fns-utils
# or
yarn add date-fns-utils

Quick Start

import { formatRelative, addBusinessDays, isWeekend } from 'date-fns-utils';

// Format relative time
formatRelative(new Date(), new Date('2026-08-01'));
// => "2 months ago"

// Add business days (skip weekends)
addBusinessDays(new Date(), 5);
// => Mon Sep 08 2026

// Check if weekend
isWeekend(new Date());
// => true/false

API Reference

formatRelative(date, baseDate)

Format a date relative to another date in human-readable form.

formatRelative(new Date('2026-09-01'), new Date('2026-08-15'));
// => "17 days from now"

addBusinessDays(date, amount)

Add business days to a date, skipping weekends.

addBusinessDays(new Date('2026-09-05'), 3);
// => Mon Sep 08 2026 (skips Sat/Sun)

getBusinessDaysBetween(startDate, endDate)

Count business days between two dates.

getBusinessDaysBetween(
  new Date('2026-09-01'),
  new Date('2026-09-15')
);
// => 10

isWeekend(date)

Check if a date falls on a weekend.

isWeekend(new Date('2026-09-06')); // Saturday
// => true

getQuarter(date)

Get the fiscal quarter (1-4) for a given date.

getQuarter(new Date('2026-08-15'));
// => 3

formatDuration(milliseconds)

Convert milliseconds to human-readable duration.

formatDuration(125000);
// => "2m 5s"

Options

Most functions accept an optional options object:

formatRelative(date, baseDate, {
  locale: 'es',           // Use Spanish locale
  addSuffix: true,        // Add "ago" or "from now"
  includeSeconds: false   // Round to nearest minute
});

TypeScript

This package includes TypeScript definitions.

import { formatRelative } from 'date-fns-utils';

const result: string = formatRelative(new Date(), new Date());

Browser Support

Works in all modern browsers and Node.js 14+. For IE11 support, include the appropriate polyfills.

Contributing

Pull requests welcome! Please ensure:

• All tests pass (npm test)
• Code follows ESLint rules (npm run lint)
• Add tests for new features
• Update README with API changes

License

MIT © 2026 DateFns Utils Contributors