Documentation keyboard_arrow_right Helpers

Helpers

Date utility functions for common date operations.

Documentation

Installation

npm install @calendarjs/ce

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

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/ce';

// 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/ce';

// 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/ce';

// 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 = {
    just_now: 'agora',
    m_ago: 'm atrás',
    h_ago: 'h atrás',
    d_ago: 'd atrás'
};
Helpers.prettify('2024-05-15 14:28:00', customTexts); // "2m atrás"

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

Validation

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

// 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/ce';

// 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

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

// Build an event display component
function formatEventDate(startDate, endDate) {
    // Validate inputs
    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();

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

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

formatEventDate(new Date('2024-05-15'), new Date('2024-05-17'));
// "May 15 - May 17"

Related

Edit this page on GitHub