carbondate

A simple DateTime Package based on dayjs. Also supports timezone. Developer friendly syntax.

Installation

npm i carbondate

Uses

import this in your project

import CarbonDate from "carbondate";

Or

const CarbonDate = require('carbondate');

Initialization

CarbonDate.init().now().format().value;
// 2024-05-27 13:09:59

Or

const datetime = new CarbonDate();
datetime.now().format().value;
// 2024-05-27 13:09:59

Or

CarbonDate.init().createFromObject({year: new Date().getFullYear(), month: (new Date().getMonth() + 1), day: new Date().getDate(), hour: '00', minute: '00', second: '00'}).toDateTimeString().value
// 2024-10-22 00:00:00

Getters

CarbonDate.init().getYear().value
// 24

Method	Example	Description
getYear	24	Two-digit year
getFullYear	2024	Four-digit year
getMonth	01-12	Month, 2-digits
getMonthName	Jan-Dec	The abbreviated month name
getFullMonthName	January-December	The full month name
getDay	01-31	The day of the month, 2-digits
getDayName	Sun-Sat	The short name of the day of the week
getFullDayName	Sunday-Saturday	The name of the day of the week
getHour	01-12	The hour, 12-hour clock, 2-digits
getHourIn24	00-23	The hour, 2-digits
getMinute	00-59	The minute, 2-digits
getSecond	00-59	The second, 2-digits

Fluent Setters

CarbonDate.init().setYear(2001).setMonth(12).setDay(12).setHour(11).setMinute(45).setSecond(50).toDateTimeString().value
// 2001-12-12 11:45:50

List of all available formats

CarbonDate.init().now().format('YYYY-MM-DD hh:mm:ss A').value
// 2024-05-27 02:06:21 PM

Format	Output	Description
YY	18	Two-digit year
YYYY	2018	Four-digit year
M	1-12	The month, beginning at 1
MM	01-12	The month, 2-digits
MMM	Jan-Dec	The abbreviated month name
MMMM	January-December	The full month name
D	1-31	The day of the month
DD	01-31	The day of the month, 2-digits
d	0-6	The day of the week, with Sunday as 0
dd	Su-Sa	The min name of the day of the week
ddd	Sun-Sat	The short name of the day of the week
dddd	Sunday-Saturday	The name of the day of the week
H	0-23	The hour
HH	00-23	The hour, 2-digits
h	1-12	The hour, 12-hour clock
hh	01-12	The hour, 12-hour clock, 2-digits
m	0-59	The minute
mm	00-59	The minute, 2-digits
s	0-59	The second
ss	00-59	The second, 2-digits
SSS	000-999	The millisecond, 3-digits
A	AM PM
a	am pm

Parsing

CarbonDate.init().parse(new Date()).format().value
// 2024-05-27 13:10:11

Or

CarbonDate.init().parse(CarbonDate.init().now().value).format().value
// 2024-05-27 13:10:20

Or

CarbonDate.init().parse('2022').format().value
// 2022-01-01 00:00:00

Or

CarbonDate.init().parse('2022-05').format().value
// 2022-05-01 00:00:00

Or

CarbonDate.init().parse('2022-05-08').format().value
// 2022-05-08 00:00:00

Or

CarbonDate.init().parse('10:55:10').format().value
// 2024-05-27 10:55:10

Or

CarbonDate.init().parse('20:55:10').format('YYYY-MM-DD hh:mm:ss A').value
// 2024-05-27 08:55:10 PM

Or

CarbonDate.init().parse('2023-05-04 20:55:10').format('YYYY-MM-DD hh:mm:ss A').value
// 2023-05-04 08:55:10 PM

String Formatting

CarbonDate.init().now().toDateTimeString().value
// 2024-10-18 04:33:07

Method	Example
toDateString	2024-12-25
toFormattedDateString	Dec 25, 2024
toFormattedDayDateString	Thu, Dec 25, 1975
toTimeString	14:15:16
toDateTimeString	2024-12-25 14:15:16
toDayDateTimeString	Thu, Dec 25, 2024 2:15 PM
toIso	2024-10-22T11:27:10.757Z
toUTC	Convert Date TIme into UTC

Addition

Add One Day

CarbonDate.init().now().addDay().format().value
// 2024-05-28 13:19:59

Add More than one Day

CarbonDate.init().now().addDays(2).format().value
// 2024-05-29 13:20:50

List of all methods

Method	Params	Description
addDay	--	Add One Day to a date
addDays	count as integer: example addDays(5)	Add custom day count to a date
addWeek	--	Add One Week to a date
addWeeks	count as integer: example addWeeks(5)	Add custom week count to a date
addMonth	--	Add One month to a date
addMonths	count as integer: example addMonths(5)	Add custom month count to a date
addYear	--	Add One year to a date
addYears	count as integer: example addYears(5)	Add custom year count to a date
addHour	--	Add One hour to a time
addHours	count as integer: example addHours(5)	Add custom hour count to a time
addMinute	--	Add One minute to a time
addMinutes	count as integer: example addMinutes(5)	Add custom minute count to a time
addSecond	--	Add One second to a time
addSeconds	count as integer: example addSeconds(5)	Add custom second count to a time

Subtract

Subtract One Day

CarbonDate.init().now().subDay().format().value
// 2024-05-26 13:19:59

Subtract More than one Day

CarbonDate.init().now().subDays(2).format().value
// 2024-05-25 13:20:50

List of all methods

Method	Params	Description
subDay	--	Subtract One Day to a date
subDays	count as integer: example subDays(5)	Subtract custom day count to a date
subWeek	--	Subtract One Week to a date
subWeeks	count as integer: example subWeeks(5)	Subtract custom week count to a date
subMonth	--	Subtract One month to a date
subMonths	count as integer: example subMonths(5)	Subtract custom month count to a date
subYear	--	Subtract One year to a date
subYears	count as integer: example subYears(5)	Subtract custom year count to a date
subHour	--	Subtract One hour to a time
subHours	count as integer: example subHours(5)	Subtract custom hour count to a time
subMinute	--	Subtract One minute to a time
subMinutes	count as integer: example subMinutes(5)	Subtract custom minute count to a time
subSecond	--	Subtract One second to a time
subSeconds	count as integer: example subSeconds(5)	Subtract custom second count to a time

Difference

Difference in day between two days

CarbonDate.init().now().diffInDays(CarbonDate.init().now().subDay().value).value
// 1

OR

CarbonDate.init().parse('2024-05-01').diffInDays(CarbonDate.init().parse('2024-05-05').value).value
// 4

List of all methods

Method	Params	Description
diffInDays	Valid date time string or Date Object	return day count
diffInWeeks	Valid date time string or Date Object	return week count
diffInMonths	Valid date time string or Date Object	return month count
diffInYears	Valid date time string or Date Object	return year count
diffInHours	Valid date time string or Date Object	return hour count
diffInMinutes	Valid date time string or Date Object	return minute count
diffInSeconds	Valid date time string or Date Object	return second count

Comparison

Comparing two dates

CarbonDate.init().parse('2024-05-01').lessThan(CarbonDate.init().parse('2024-05-05').value).value
// true

OR

CarbonDate.init().now().lessThan(CarbonDate.init().parse('2024-05-05').value).value
// false

List of all methods

Method	Params	Description
lessThan	Valid date time string or Date Object	return Boolean
lessThanOrEqual	Valid date time string or Date Object	return Boolean
greaterThan	Valid date time string or Date Object	return Boolean
greaterThanOrEqual	Valid date time string or Date Object	return Boolean
equalTo	Valid date time string or Date Object	return Boolean
notEqualTo	Valid date time string or Date Object	return Boolean
inBetween	Valid date time string or Date Object	return Boolean
isSameMonth	Valid date time string or Date Object	return Boolean
isSameDay	Valid date time string or Date Object	return Boolean
isSameYear	Valid date time string or Date Object	return Boolean
isMonday	--	return Boolean
isTuesday	--	return Boolean
isWednesday	--	return Boolean
isThursday	--	return Boolean
isFriday	--	return Boolean
isSaturday	--	return Boolean
isSunday	--	return Boolean
isWeekday	--	return Boolean
isWeekend	--	return Boolean

Constants

CarbonDate.init().SUNDAY
// 0

OR

let instance = new CarbonDate();
instance.SUNDAY
// 0

Name	Value
SUNDAY	0
MONDAY	1
TUESDAY	2
WEDNESDAY	3
THURSDAY	4
FRIDAY	5
SATURDAY	6
YEARS_PER_CENTURY	100
YEARS_PER_DECADE	10
MONTHS_PER_YEAR	12
WEEKS_PER_YEAR	52
DAYS_PER_WEEK	7
HOURS_PER_DAY	24
MINUTES_PER_HOUR	60
SECONDS_PER_MINUTE	60

Common Functions

CarbonDate.init().yesterday().toDateTimeString().value
// 2024-10-21 04:30:05

Method
startOfYear
startOfMonth
startOfDay
endOfYear
endOfMonth
endOfDay
checkLeapYear
dayCountInMonth
diffForHumans
monthNumber
currentTimezone

Leap Year

CarbonDate.init().yesterday().checkLeapYear().value
// true

Days in month

CarbonDate.init().now().dayCountInMonth().value
// as now is May so output is: 31

Start of month

CarbonDate.init().now().startOfMonth().format('YYYY-MM-DD').value
// 2024-05-01

End of month

CarbonDate.init().now().endOfMonth().format('YYYY-MM-DD').value
// 2024-05-31

Diff for human

CarbonDate.init().now().diffForHumans().value
// a few seconds ago

Or

CarbonDate.init().now().diffForHumans(CarbonDate.init().now().subHour().value).value
// in an hour

Month Number

• be careful with the month name spelling

CarbonDate.init().monthNumber('January').value
// 01

OR

CarbonDate.init().monthNumber('jan').value
// 01

dayOfYear

• get date from day number

CarbonDate.init().now().dateFromDayNumber(300).format('YYYY-MM-DD HH:mm:ss').value
// 2024-10-26 21:20:30

OR

CarbonDate.init().parse('2024-09-05').dateFromDayNumber(300).format('YYYY-MM-DD HH:mm:ss').value
// 2024-10-26 21:20:30

• get day number of year

CarbonDate.init().now().dayNumberOfYear().value
// as now is 09-12-2024 output is: 344

OR

CarbonDate.init().parse('2024-09-05').dayNumberOfYear().value
// 249

Timezone

List of all available timezones.

Set your own Timezone

CarbonDate.init('America/Los_Angeles').now().format().value;
// 2024-05-28 06:12:26

Or

const datetime = new CarbonDate('America/Los_Angeles');
datetime.now().format().value;
// 2024-05-28 06:12:26

if you are not using any timezone. then it will take system timezone by default.

Current Timezone

CarbonDate.init('America/Los_Angeles').currentTimezone().value
// America/Los_Angeles

CarbonDate.init().currentTimezone().value
// Asia/Dhaka my current timezone

Convert date time to a specific timezone

CarbonDate.init('America/Los_Angeles').parse('2024-05-10 10:00:50').format('YYYY-MM-DD hh:ss:mm A').value
// 2024-05-09 09:50:00 PM