Helpers

Date utility functions shared by all CalendarJS React components. Framework-agnostic — safe to use in hooks, server-side logic, or plain JS.

Installation

npm install @calendarjs/react

import { Helpers } from '@calendarjs/react';

Conversion Methods

Method	Description
`dateToNum(date: Date): number`	Convert JS Date to Excel serial number
`numToDate(serial: number, asArray?: boolean): string \| number[]`	Convert Excel serial to date string or array
`now(date?: Date): string`	Get formatted datetime string (YYYY-MM-DD HH:MM:SS)
`toString(date: Date, dateOnly?: boolean): string`	Format date. Use `dateOnly: true` for YYYY-MM-DD
`toArray(value: string): number[]`	Convert ISO string to array `[year, month, day, h, m, s]`
`arrayToStringDate(arr: number[]): string`	Convert date array to string

Formatting Methods

Method	Description
`two(value: number): string`	Pad single digit with zero. `5` → `"05"`
`prettify(date: string, texts?: object): string`	Get relative time: "2h ago", "3d ago", "Just now"
`prettifyAll(): void`	Convert all `.prettydate` elements to relative time

Validation Methods

Method	Description
`isValidDate(date: any): boolean`	Check if value is valid Date object
`isValidDateFormat(dateString: string): boolean`	Validate YYYY-MM-DD format

Localization Arrays

Property	Description
`months`	Full month names: January, February...
`monthsShort`	Short month names: Jan, Feb...
`weekdays`	Full day names: Sunday, Monday...
`weekdaysShort`	Short day names: Sun, Mon...

Examples

Date Conversion

import { Helpers } from '@calendarjs/react';

// Convert JavaScript Date to Excel serial number
const today = new Date('2024-05-15');
const serial = Helpers.dateToNum(today);
console.log(serial); // 45427

// Convert Excel serial back to date string
Helpers.numToDate(45427);           // "2024-05-15"
Helpers.numToDate(45427, true);     // [2024, 5, 15, 0, 0, 0]

// Convert ISO string to array
Helpers.toArray('2024-05-15 14:30:00'); // [2024, 5, 15, 14, 30, 0]

// Convert array back to string
Helpers.arrayToStringDate([2024, 5, 15]); // "2024-05-15"

Date Formatting

import { Helpers } from '@calendarjs/react';

// Get current datetime
Helpers.now();                        // "2024-05-15 14:30:00"
Helpers.now(new Date('2024-01-01'));  // "2024-01-01 00:00:00"

// Format Date objects
const date = new Date('2024-05-15T14:30:00');
Helpers.toString(date);         // "2024-05-15 14:30:00"
Helpers.toString(date, true);   // "2024-05-15" (date only)

// Pad numbers with leading zero
Helpers.two(5);   // "05"
Helpers.two(12);  // "12"

Relative Time (Prettify)

import { Helpers } from '@calendarjs/react';

// Get relative time strings
Helpers.prettify('2024-05-15 14:28:00'); // "2m ago"
Helpers.prettify('2024-05-15 12:30:00'); // "2h ago"
Helpers.prettify('2024-05-14 14:30:00'); // "1d ago"
Helpers.prettify('2024-05-10 14:30:00'); // "5d ago"

// Custom text labels
const customTexts = {
    justNow: 'agora',
    xMinutesAgo: 'm atrás',
    xHoursAgo: 'h atrás',
    xDaysAgo: 'd atrás',
};
Helpers.prettify('2024-05-15 14:28:00', customTexts); // "2m atrás"

// Auto-update all elements with class "prettydate"
// <span className="prettydate">2024-05-15 12:00:00</span>
Helpers.prettifyAll(); // Updates to "2h ago"

Validation

import { Helpers } from '@calendarjs/react';

// Validate Date objects
Helpers.isValidDate(new Date());              // true
Helpers.isValidDate(new Date('invalid'));     // false
Helpers.isValidDate('2024-05-15');            // false (string, not Date)
Helpers.isValidDate(null);                    // false

// Validate date string format (YYYY-MM-DD)
Helpers.isValidDateFormat('2024-05-15');      // true
Helpers.isValidDateFormat('2024-13-40');      // false (invalid month/day)
Helpers.isValidDateFormat('05-15-2024');      // false (wrong format)
Helpers.isValidDateFormat('2024/05/15');      // false (wrong separator)

Localization Arrays

import { Helpers } from '@calendarjs/react';

// Access month names
console.log(Helpers.months);      // ["January", "February", ...]
console.log(Helpers.monthsShort); // ["Jan", "Feb", ...]

// Access weekday names
console.log(Helpers.weekdays);      // ["Sunday", "Monday", ...]
console.log(Helpers.weekdaysShort); // ["Sun", "Mon", ...]

// Practical example: format a date with month name
const date = new Date('2024-05-15');
const formatted = `${Helpers.months[date.getMonth()]} ${date.getDate()}, ${date.getFullYear()}`;
console.log(formatted); // "May 15, 2024"

Real-World Example — React component

import React from 'react';
import { Helpers } from '@calendarjs/react';

function formatEventDate(startDate, endDate) {
    if (!Helpers.isValidDate(startDate)) {
        throw new Error('Invalid start date');
    }

    const start = Helpers.toString(startDate, true);
    const month = Helpers.months[startDate.getMonth()];
    const day = startDate.getDate();

    if (!endDate || start === Helpers.toString(endDate, true)) {
        return `${month} ${day}`;
    }

    const endMonth = Helpers.months[endDate.getMonth()];
    const endDay = endDate.getDate();
    return `${month} ${day} - ${endMonth} ${endDay}`;
}

export function EventBadge({ start, end }) {
    return <span className="event-date">{formatEventDate(start, end)}</span>;
}