Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/sebamar88/bytekit/llms.txt

Use this file to discover all available pages before exploring further.

​
Overview

DateUtils provides comprehensive date manipulation utilities including parsing, formatting, date arithmetic, comparisons, and duration calculations. All methods safely handle various input formats.

​
Import

import { DateUtils } from '@bytekit/utils/helpers';

​
Methods

​
parse

Parses various date formats into a Date object.
​
value
Date | string | number | null | undefined
The date input to parse
Returns: Date | null - Parsed Date object or null if invalid 
DateUtils.parse('2024-03-15');
// Returns: Date object for March 15, 2024

DateUtils.parse(1710460800000);
// Returns: Date object from timestamp

DateUtils.parse(new Date());
// Returns: New Date object with same time

DateUtils.parse('invalid');
// Returns: null

DateUtils.parse(null);
// Returns: null
Input Formats:
  • Date objects
  • ISO date strings
  • Unix timestamps (milliseconds)
  • Any valid date string

​
isValid

Checks if a date input is valid.
​
value
Date | string | number | null | undefined
The date input to validate
Returns: boolean - True if valid date 
DateUtils.isValid('2024-03-15');
// Returns: true

DateUtils.isValid('invalid-date');
// Returns: false

DateUtils.isValid(null);
// Returns: false

DateUtils.isValid(new Date());
// Returns: true

​
toISODate

Formats a date as YYYY-MM-DD.
​
value
Date | string | number | null | undefined
The date input to format
Returns: string - ISO date string (YYYY-MM-DD) Throws: TypeError if date is invalid 
DateUtils.toISODate('2024-03-15T10:30:00Z');
// Returns: '2024-03-15'

DateUtils.toISODate(new Date(2024, 2, 15));
// Returns: '2024-03-15'

DateUtils.toISODate(1710460800000);
// Returns: '2024-03-15'

​
startOfDay

Returns a date set to the start of the day (00:00:00.000).
​
value
Date | string | number | null | undefined
The date input
Returns: Date - Date at midnight Throws: TypeError if date is invalid 
const date = DateUtils.startOfDay('2024-03-15T14:30:00');
// Returns: Date for 2024-03-15 00:00:00.000

date.getHours(); // 0
date.getMinutes(); // 0
date.getSeconds(); // 0
date.getMilliseconds(); // 0

​
endOfDay

Returns a date set to the end of the day (23:59:59.999).
​
value
Date | string | number | null | undefined
The date input
Returns: Date - Date at last millisecond of day Throws: TypeError if date is invalid 
const date = DateUtils.endOfDay('2024-03-15T10:00:00');
// Returns: Date for 2024-03-15 23:59:59.999

date.getHours(); // 23
date.getMinutes(); // 59
date.getSeconds(); // 59
date.getMilliseconds(); // 999

​
add

Adds a duration to a date.
​
value
Date | string | number | null | undefined
The base date
​
duration
AddDurationOptions
Duration to add
​
days
number
Number of days to add
​
hours
number
Number of hours to add
​
minutes
number
Number of minutes to add
​
seconds
number
Number of seconds to add
​
milliseconds
number
Number of milliseconds to add
Returns: Date - New date with duration added Throws: TypeError if date is invalid 
DateUtils.add('2024-03-15', { days: 5 });
// Returns: Date for 2024-03-20

DateUtils.add('2024-03-15T10:00:00', { hours: 2, minutes: 30 });
// Returns: Date for 2024-03-15 12:30:00

DateUtils.add('2024-03-15', { 
  days: 1, 
  hours: 12, 
  minutes: 30 
});
// Returns: Date for 2024-03-16 12:30:00

// Negative values for subtraction
DateUtils.add('2024-03-15', { days: -7 });
// Returns: Date for 2024-03-08

​
diff

Calculates the difference between two dates.
​
a
Date | string | number | null | undefined
The first date (start)
​
b
Date | string | number | null | undefined
The second date (end)
​
options
DiffOptions
Optional configuration
​
unit
'milliseconds' | 'seconds' | 'minutes' | 'hours' | 'days'
default:"milliseconds"
Unit for the difference
​
absolute
boolean
default:"false"
Return absolute value
​
rounding
'floor' | 'ceil' | 'round' | 'trunc'
default:"floor"
Rounding method
Returns: number - Difference in specified unit Throws: TypeError if either date is invalid 
DateUtils.diff('2024-03-15', '2024-03-20', { unit: 'days' });
// Returns: 5

DateUtils.diff('2024-03-20', '2024-03-15', { unit: 'days' });
// Returns: -5

DateUtils.diff('2024-03-20', '2024-03-15', { 
  unit: 'days', 
  absolute: true 
});
// Returns: 5

DateUtils.diff('2024-03-15T10:00:00', '2024-03-15T12:30:00', { 
  unit: 'hours' 
});
// Returns: 2

DateUtils.diff('2024-03-15', '2024-03-15T12:30:00', { 
  unit: 'hours',
  rounding: 'ceil'
});
// Returns: 13

​
diffInDays

Calculates the difference between two dates in days.
​
a
Date | string | number | null | undefined
The first date (start)
​
b
Date | string | number | null | undefined
The second date (end)
​
options
Omit<DiffOptions, 'unit'>
Optional configuration (absolute, rounding)
Returns: number - Difference in days (rounded up by default) Throws: TypeError if either date is invalid 
DateUtils.diffInDays('2024-03-15', '2024-03-20');
// Returns: 5

DateUtils.diffInDays('2024-03-15T00:00:00', '2024-03-15T12:00:00');
// Returns: 1 (rounded up by default)

DateUtils.diffInDays('2024-03-15', '2024-03-15T12:00:00', { 
  rounding: 'floor' 
});
// Returns: 0
Note: Defaults to ‘ceil’ rounding for day calculations

​
isSameDay

Checks if two dates are on the same calendar day.
​
a
Date | string | number | null | undefined
The first date
​
b
Date | string | number | null | undefined
The second date
Returns: boolean - True if same day Throws: TypeError if either date is invalid 
DateUtils.isSameDay('2024-03-15T10:00:00', '2024-03-15T18:00:00');
// Returns: true

DateUtils.isSameDay('2024-03-15', '2024-03-16');
// Returns: false

DateUtils.isSameDay(
  new Date(2024, 2, 15, 0, 0),
  new Date(2024, 2, 15, 23, 59)
);
// Returns: true

​
isBefore

Checks if the first date is before the second date.
​
a
Date | string | number | null | undefined
The first date
​
b
Date | string | number | null | undefined
The second date
Returns: boolean - True if a is before b Throws: TypeError if either date is invalid 
DateUtils.isBefore('2024-03-15', '2024-03-20');
// Returns: true

DateUtils.isBefore('2024-03-20', '2024-03-15');
// Returns: false

DateUtils.isBefore('2024-03-15T10:00:00', '2024-03-15T10:00:00');
// Returns: false (equal times)

​
isAfter

Checks if the first date is after the second date.
​
a
Date | string | number | null | undefined
The first date
​
b
Date | string | number | null | undefined
The second date
Returns: boolean - True if a is after b Throws: TypeError if either date is invalid 
DateUtils.isAfter('2024-03-20', '2024-03-15');
// Returns: true

DateUtils.isAfter('2024-03-15', '2024-03-20');
// Returns: false

DateUtils.isAfter('2024-03-15T10:00:00', '2024-03-15T10:00:00');
// Returns: false (equal times)

​
format

Formats a date using custom format string or locale.
​
dateInput
Date | string | number | null | undefined
The date to format
​
formatOrLocale
string
default:"es-AR"
Custom format string (e.g., ‘YYYY-MM-DD’) or locale (e.g., ‘en-US’)
Returns: string - Formatted date string Throws: TypeError if date is invalid 
// Custom format strings
DateUtils.format('2024-03-15T14:30:45', 'YYYY-MM-DD');
// Returns: '2024-03-15'

DateUtils.format('2024-03-15T14:30:45', 'DD/MM/YYYY HH:mm');
// Returns: '15/03/2024 14:30'

DateUtils.format('2024-03-15', 'YYYY-MM-DD HH:mm:ss');
// Returns: '2024-03-15 00:00:00'

// Locale-based formatting
DateUtils.format('2024-03-15', 'en-US');
// Returns: 'Mar 15, 2024'

DateUtils.format('2024-03-15', 'es-AR');
// Returns: '15 mar 2024'

DateUtils.format('2024-03-15', 'de-DE');
// Returns: '15. März 2024'
Format Tokens:
  • YYYY - Full year (e.g., 2024)
  • MM - Month (01-12)
  • DD - Day of month (01-31)
  • HH - Hour (00-23)
  • mm - Minute (00-59)
  • ss - Second (00-59)
Edge Cases:
  • Invalid locales fallback to ISO string
  • Custom formats require exact token matches

​
Type Definitions

type DateInput = Date | string | number | null | undefined;

type DiffUnit = 'milliseconds' | 'seconds' | 'minutes' | 'hours' | 'days';

type RoundingMode = 'floor' | 'ceil' | 'round' | 'trunc';

interface DiffOptions {
  unit?: DiffUnit;
  absolute?: boolean;
  rounding?: RoundingMode;
}

interface AddDurationOptions {
  days?: number;
  hours?: number;
  minutes?: number;
  seconds?: number;
  milliseconds?: number;
}

​
Best Practices

​
Error Handling

Most methods throw TypeError for invalid dates. Use parse or isValid first: 
const input = userInput;
if (DateUtils.isValid(input)) {
  const formatted = DateUtils.format(input, 'YYYY-MM-DD');
} else {
  console.error('Invalid date');
}

​
Date Comparisons

const start = '2024-03-15';
const end = '2024-03-20';

if (DateUtils.isAfter(end, start)) {
  const days = DateUtils.diffInDays(start, end);
  console.log(`${days} days between dates`);
}

​
Date Range Queries

const startOfToday = DateUtils.startOfDay(new Date());
const endOfToday = DateUtils.endOfDay(new Date());

// Use for filtering records
const todayRecords = records.filter(r => {
  const date = DateUtils.parse(r.createdAt);
  return date && 
    !DateUtils.isBefore(date, startOfToday) &&
    !DateUtils.isAfter(date, endOfToday);
});

​
Duration Calculations

const deadline = DateUtils.add(new Date(), { 
  days: 7, 
  hours: 12 
});

const timeLeft = DateUtils.diff(
  new Date(), 
  deadline, 
  { unit: 'hours' }
);

Build docs developers (and LLMs) love

Get started for freeTalk to us