Date Helper

A TypeScript date manipulation library built on top of Day.js, providing a fluent API for working with dates, times, and locales.

Installation

npm install @connect-soft/date-helper dayjs

pnpm add @connect-soft/date-helper dayjs

yarn add @connect-soft/date-helper dayjs

Note: dayjs is a peer dependency and must be installed separately.

Features

• Fluent API for date manipulation
• Immutable or mutable operations (configurable)
• Timezone support
• Locale-aware formatting
• Type-safe with TypeScript
• Lightweight wrapper around Day.js
• Support for both ESM and CommonJS

Basic Usage

import { DateHelper } from '@connect-soft/date-helper';

// Create from current time
const now = DateHelper.now();

// Create from Date object
const date = DateHelper.from(new Date());

// Create from string
const parsed = DateHelper.fromDateTimeString('2024-10-02T08:11:00Z');

// Create from null (safe handling)
const nullable = DateHelper.from(null);

API Reference

Static Methods

DateHelper.now()

Creates a DateHelper instance with the current date and time.

const now = DateHelper.now();

DateHelper.from(source)

Creates a DateHelper instance from a Date, Dayjs object, or null.

const date = DateHelper.from(new Date());
const fromDayjs = DateHelper.from(dayjs());
const fromNull = DateHelper.from(null); // Returns DateHelper with null instance

DateHelper.fromDateTimeString(source)

Creates a DateHelper instance from a date-time string.

const date = DateHelper.fromDateTimeString('2024-10-02T08:11:00Z');

DateHelper.addHours(source, hours)

Static utility to add hours to a date.

const result = DateHelper.addHours(new Date(), 2);

Instance Methods

Date Manipulation

// Add days (immutable by default)
const tomorrow = DateHelper.now().addDays(1, false);

// Add hours (mutable if update=true)
const later = DateHelper.now().addHours(2, true);

// Get start of day
const startOfDay = DateHelper.now().getStartOfDay();

// Get end of day
const endOfDay = DateHelper.now().getEndOfDay();

Comparison

const date1 = DateHelper.now();
const date2 = DateHelper.now().addDays(1);

// Check if after
if (date2.isAfter(date1)) {
  console.log('date2 is after date1');
}

// Check if equal
if (date1.isEqual(date1, 'day')) {
  console.log('Same day');
}

// Calculate difference
const hoursDiff = date2.diff(date1, 'hours'); // Returns number

Formatting

const date = DateHelper.now();

// Custom format using Day.js format
const formatted = date.format('YYYY-MM-DD HH:mm:ss');

// Locale-aware date formatting
const localDate = date.formatLocalDate('en-US'); // "1/15/2024"
const czechDate = date.formatLocalDate('cs'); // "15. 1. 2024"

// Locale-aware time formatting
const time = date.formatLocalTime('en-US'); // "2:30 PM"

// Locale-aware date-time formatting
const dateTime = date.formatLocalDateTime('cs'); // "15. 1. 2024 14:30"

// Custom locale options
const customFormat = date.formatLocalDate('en-US', {
  weekday: 'long',
  year: 'numeric',
  month: 'long',
  day: 'numeric'
}); // "Monday, January 15, 2024"

Locale Management

// Get current locale
const locale = DateHelper.now().getLocale(); // "en"

// Set locale (requires importing locale first)
import 'dayjs/locale/cs';
const czechDate = DateHelper.now().setLocale('cs');

Conversion

// Convert to Date object
const dateObj = DateHelper.now().toDate();

// Get underlying Day.js instance
const dayjsObj = DateHelper.now().getObj();

Advanced Examples

Working with Timezones

import { DateHelper } from '@connect-soft/date-helper';

// The library includes timezone plugin by default
const date = DateHelper.fromDateTimeString('2024-01-15T14:30:00Z');

Null-Safe Operations

// All methods handle null gracefully
const nullable = DateHelper.from(null);
nullable.addDays(5).toDate(); // Returns null
nullable.format('YYYY-MM-DD', 'N/A'); // Returns 'N/A'
nullable.formatLocalDate('en-US'); // Returns ""

Chaining Operations

const result = DateHelper.now()
  .addDays(7)
  .getStartOfDay()
  .addHours(9)
  .format('YYYY-MM-DD HH:mm');

TypeScript Support

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

import { DateHelper, IDateTimeType } from '@connect-soft/date-helper';

// IDateTimeType is an alias for Day.js Dayjs type
const dayjs: IDateTimeType = DateHelper.now().getObj();

License

MIT

Contributing

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

Repository

GitLab Repository