Documentation

Documentation / @zerotal/core / datetime / Carbon

Class: Carbon

Defined in: datetime/Carbon.ts:151

An immutable date-time value backed by Temporal.ZonedDateTime. Every modifier returns a new instance — the original is never mutated. Defaults to the system local timezone unless overridden, and formats via Intl.DateTimeFormat/token templates with no external dependencies.

Examples

Construction and formatting

import { Carbon } from "@zerotal/core/carbon";

Carbon.now();                           // current instant, system tz
Carbon.create("2024-01-01T12:00:00Z");  // parse any supported input
Carbon.now().format("YYYY-MM-DD HH:mm"); // "2024-06-09 14:30"

Arithmetic, comparison and human diffs

const start = Carbon.now();
const later = start.addDays(3).subtractHours(2);

later.isAfter(start);              // true
later.diffInHours(start);          // 70
later.diffForHumans(start);        // "in 2 days"
later.inTimezone("Europe/Paris");  // same instant, different zone

Constructors

Constructor

new Carbon(input?, timezone?): Carbon

Defined in: datetime/Carbon.ts:164

Construct a Carbon from any supported input.

Parameters

input?

CarbonInput = ...

Value to parse or wrap; defaults to the current instant.

timezone?

string

Timezone to interpret the value in; inferred from the input's own zone or the system zone when omitted.

Returns

Carbon

Throws

When a string input cannot be parsed.

Arithmetic

addNanoseconds()

addNanoseconds(amount): Carbon

Defined in: datetime/Carbon.ts:516

Return a copy advanced by amount nanoseconds.

Parameters

amount

number

Returns

Carbon

addMicroseconds()

addMicroseconds(amount): Carbon

Defined in: datetime/Carbon.ts:520

Return a copy advanced by amount microseconds.

Parameters

amount

number

Returns

Carbon

addMilliseconds()

addMilliseconds(amount): Carbon

Defined in: datetime/Carbon.ts:524

Return a copy advanced by amount milliseconds.

Parameters

amount

number

Returns

Carbon

addSeconds()

addSeconds(amount): Carbon

Defined in: datetime/Carbon.ts:528

Return a copy advanced by amount seconds.

Parameters

amount

number

Returns

Carbon

addMinutes()

addMinutes(amount): Carbon

Defined in: datetime/Carbon.ts:532

Return a copy advanced by amount minutes.

Parameters

amount

number

Returns

Carbon

addHours()

addHours(amount): Carbon

Defined in: datetime/Carbon.ts:536

Return a copy advanced by amount hours.

Parameters

amount

number

Returns

Carbon

addDays()

addDays(amount): Carbon

Defined in: datetime/Carbon.ts:540

Return a copy advanced by amount days.

Parameters

amount

number

Returns

Carbon

addWeeks()

addWeeks(amount): Carbon

Defined in: datetime/Carbon.ts:544

Return a copy advanced by amount weeks.

Parameters

amount

number

Returns

Carbon

addMonths()

addMonths(amount): Carbon

Defined in: datetime/Carbon.ts:548

Return a copy advanced by amount calendar months.

Parameters

amount

number

Returns

Carbon

addYears()

addYears(amount): Carbon

Defined in: datetime/Carbon.ts:552

Return a copy advanced by amount calendar years.

Parameters

amount

number

Returns

Carbon

addDecades()

addDecades(amount): Carbon

Defined in: datetime/Carbon.ts:556

Return a copy advanced by amount decades (10 years).

Parameters

amount

number

Returns

Carbon

addCenturies()

addCenturies(amount): Carbon

Defined in: datetime/Carbon.ts:560

Return a copy advanced by amount centuries (100 years).

Parameters

amount

number

Returns

Carbon

addMillennia()

addMillennia(amount): Carbon

Defined in: datetime/Carbon.ts:564

Return a copy advanced by amount millennia (1000 years).

Parameters

amount

number

Returns

Carbon

subtractNanoseconds()

subtractNanoseconds(amount): Carbon

Defined in: datetime/Carbon.ts:571

Return a copy moved back by amount nanoseconds.

Parameters

amount

number

Returns

Carbon

subtractMicroseconds()

subtractMicroseconds(amount): Carbon

Defined in: datetime/Carbon.ts:575

Return a copy moved back by amount microseconds.

Parameters

amount

number

Returns

Carbon

subtractMilliseconds()

subtractMilliseconds(amount): Carbon

Defined in: datetime/Carbon.ts:579

Return a copy moved back by amount milliseconds.

Parameters

amount

number

Returns

Carbon

subtractSeconds()

subtractSeconds(amount): Carbon

Defined in: datetime/Carbon.ts:583

Return a copy moved back by amount seconds.

Parameters

amount

number

Returns

Carbon

subtractMinutes()

subtractMinutes(amount): Carbon

Defined in: datetime/Carbon.ts:587

Return a copy moved back by amount minutes.

Parameters

amount

number

Returns

Carbon

subtractHours()

subtractHours(amount): Carbon

Defined in: datetime/Carbon.ts:591

Return a copy moved back by amount hours.

Parameters

amount

number

Returns

Carbon

subtractDays()

subtractDays(amount): Carbon

Defined in: datetime/Carbon.ts:595

Return a copy moved back by amount days.

Parameters

amount

number

Returns

Carbon

subtractWeeks()

subtractWeeks(amount): Carbon

Defined in: datetime/Carbon.ts:599

Return a copy moved back by amount weeks.

Parameters

amount

number

Returns

Carbon

subtractMonths()

subtractMonths(amount): Carbon

Defined in: datetime/Carbon.ts:603

Return a copy moved back by amount calendar months.

Parameters

amount

number

Returns

Carbon

subtractYears()

subtractYears(amount): Carbon

Defined in: datetime/Carbon.ts:607

Return a copy moved back by amount calendar years.

Parameters

amount

number

Returns

Carbon

subtractDecades()

subtractDecades(amount): Carbon

Defined in: datetime/Carbon.ts:611

Return a copy moved back by amount decades.

Parameters

amount

number

Returns

Carbon

subtractCenturies()

subtractCenturies(amount): Carbon

Defined in: datetime/Carbon.ts:615

Return a copy moved back by amount centuries.

Parameters

amount

number

Returns

Carbon

subtractMillennia()

subtractMillennia(amount): Carbon

Defined in: datetime/Carbon.ts:619

Return a copy moved back by amount millennia.

Parameters

amount

number

Returns

Carbon

subNanoseconds()

subNanoseconds(amount): Carbon

Defined in: datetime/Carbon.ts:625

Short alias of subtractNanoseconds.

Parameters

amount

number

Returns

Carbon

subMicroseconds()

subMicroseconds(amount): Carbon

Defined in: datetime/Carbon.ts:629

Short alias of subtractMicroseconds.

Parameters

amount

number

Returns

Carbon

subMilliseconds()

subMilliseconds(amount): Carbon

Defined in: datetime/Carbon.ts:633

Short alias of subtractMilliseconds.

Parameters

amount

number

Returns

Carbon

subSeconds()

subSeconds(amount): Carbon

Defined in: datetime/Carbon.ts:637

Short alias of subtractSeconds.

Parameters

amount

number

Returns

Carbon

subMinutes()

subMinutes(amount): Carbon

Defined in: datetime/Carbon.ts:641

Short alias of subtractMinutes.

Parameters

amount

number

Returns

Carbon

subHours()

subHours(amount): Carbon

Defined in: datetime/Carbon.ts:645

Short alias of subtractHours.

Parameters

amount

number

Returns

Carbon

subDays()

subDays(amount): Carbon

Defined in: datetime/Carbon.ts:649

Short alias of subtractDays.

Parameters

amount

number

Returns

Carbon

subWeeks()

subWeeks(amount): Carbon

Defined in: datetime/Carbon.ts:653

Short alias of subtractWeeks.

Parameters

amount

number

Returns

Carbon

subMonths()

subMonths(amount): Carbon

Defined in: datetime/Carbon.ts:657

Short alias of subtractMonths.

Parameters

amount

number

Returns

Carbon

subYears()

subYears(amount): Carbon

Defined in: datetime/Carbon.ts:661

Short alias of subtractYears.

Parameters

amount

number

Returns

Carbon

subDecades()

subDecades(amount): Carbon

Defined in: datetime/Carbon.ts:665

Short alias of subtractDecades.

Parameters

amount

number

Returns

Carbon

add()

add(interval): Carbon

Defined in: datetime/Carbon.ts:680

Add a CarbonInterval to this instance.

Parameters

interval

_duration

Duration

Returns

Carbon

Example

Carbon.now().add(CarbonInterval.days(3).andHours(6));

subtract()

subtract(interval): Carbon

Defined in: datetime/Carbon.ts:693

Subtract a CarbonInterval from this instance.

Parameters

interval

_duration

Duration

Returns

Carbon

Example

Carbon.now().subtract(CarbonInterval.weeks(1));

Boundaries

startOfDay()

startOfDay(): Carbon

Defined in: datetime/Carbon.ts:709

Copy set to the first moment of the day (00:00:00.000).

disambiguation: "earlier" matters on a fall-back day in a zone that repeats midnight (Santiago and Havana do). Temporal's default there is the second occurrence, so a startOfDay()…endOfDay() range silently began an hour late and lost every row in the first hour of the day.

Returns

Carbon

endOfDay()

endOfDay(): Carbon

Defined in: datetime/Carbon.ts:726

Copy set to the last moment of the day (23:59:59.999999999).

Returns

Carbon

startOfHour()

startOfHour(): Carbon

Defined in: datetime/Carbon.ts:740

Copy set to the first moment of the hour.

Returns

Carbon

endOfHour()

endOfHour(): Carbon

Defined in: datetime/Carbon.ts:747

Copy set to the last moment of the hour.

Returns

Carbon

startOfMinute()

startOfMinute(): Carbon

Defined in: datetime/Carbon.ts:760

Copy set to the first moment of the minute.

Returns

Carbon

endOfMinute()

endOfMinute(): Carbon

Defined in: datetime/Carbon.ts:765

Copy set to the last moment of the minute.

Returns

Carbon

startOfMonth()

startOfMonth(): Carbon

Defined in: datetime/Carbon.ts:772

Copy set to the first moment of the first day of the month.

Returns

Carbon

endOfMonth()

endOfMonth(): Carbon

Defined in: datetime/Carbon.ts:787

Copy set to the last moment of the last day of the month.

Returns

Carbon

startOfWeek()

startOfWeek(): Carbon

Defined in: datetime/Carbon.ts:805

Start of ISO week (Monday 00:00:00).

Returns

Carbon

endOfWeek()

endOfWeek(): Carbon

Defined in: datetime/Carbon.ts:815

End of ISO week (Sunday 23:59:59.999999999).

Returns

Carbon

startOfYear()

startOfYear(): Carbon

Defined in: datetime/Carbon.ts:820

Copy set to the first moment of January 1st.

Returns

Carbon

endOfYear()

endOfYear(): Carbon

Defined in: datetime/Carbon.ts:836

Copy set to the last moment of December 31st.

Returns

Carbon

startOfDecade()

startOfDecade(): Carbon

Defined in: datetime/Carbon.ts:852

Copy set to the first moment of the decade (year ending in 0).

Returns

Carbon

endOfDecade()

endOfDecade(): Carbon

Defined in: datetime/Carbon.ts:857

Copy set to the last moment of the decade (year ending in 9).

Returns

Carbon

startOfCentury()

startOfCentury(): Carbon

Defined in: datetime/Carbon.ts:862

Copy set to the first moment of the century.

Returns

Carbon

endOfCentury()

endOfCentury(): Carbon

Defined in: datetime/Carbon.ts:867

Copy set to the last moment of the century.

Returns

Carbon

Comparison

isToday()

isToday(): boolean

Defined in: datetime/Carbon.ts:927

Whether this date falls on the current calendar day.

Returns

boolean

isTomorrow()

isTomorrow(): boolean

Defined in: datetime/Carbon.ts:933

Whether this date falls on tomorrow's calendar day.

Returns

boolean

isYesterday()

isYesterday(): boolean

Defined in: datetime/Carbon.ts:939

Whether this date falls on yesterday's calendar day.

Returns

boolean

isPast()

isPast(): boolean

Defined in: datetime/Carbon.ts:945

Whether this instant is before now.

Returns

boolean

isFuture()

isFuture(): boolean

Defined in: datetime/Carbon.ts:949

Whether this instant is after now.

Returns

boolean

isWeekend()

isWeekend(): boolean

Defined in: datetime/Carbon.ts:957

Weekend: Saturday (6) or Sunday (7) in ISO dayOfWeek.

Returns

boolean

isWeekday()

isWeekday(): boolean

Defined in: datetime/Carbon.ts:961

Whether this date is Monday–Friday.

Returns

boolean

isLeapYear()

isLeapYear(): boolean

Defined in: datetime/Carbon.ts:966

Whether this date's year is a leap year.

Returns

boolean

isSameDay()

isSameDay(other): boolean

Defined in: datetime/Carbon.ts:971

Whether both fall on the same calendar day.

Parameters

other

Carbon

Returns

boolean

isSameMonth()

isSameMonth(other): boolean

Defined in: datetime/Carbon.ts:976

Whether both fall in the same calendar month and year.

Parameters

other

Carbon

Returns

boolean

isSameYear()

isSameYear(other): boolean

Defined in: datetime/Carbon.ts:981

Whether both fall in the same calendar year.

Parameters

other

Carbon

Returns

boolean

isBefore()

isBefore(other): boolean

Defined in: datetime/Carbon.ts:986

Whether this instant is strictly before other.

Parameters

other

Carbon

Returns

boolean

isAfter()

isAfter(other): boolean

Defined in: datetime/Carbon.ts:991

Whether this instant is strictly after other.

Parameters

other

Carbon

Returns

boolean

isEqual()

isEqual(other): boolean

Defined in: datetime/Carbon.ts:996

Whether this instant equals other.

Parameters

other

Carbon

Returns

boolean

isBetween()

isBetween(start, end, inclusive?): boolean

Defined in: datetime/Carbon.ts:1006

Whether this instant lies between start and end.

Parameters

start

Carbon

end

Carbon

inclusive?

boolean = true

Include the endpoints when true (default).

Returns

boolean

Construction

now()

static now(timezone?): Carbon

Defined in: datetime/Carbon.ts:190

Current date-time in the system (or given) timezone.

Parameters

timezone?

string

Returns

Carbon

create()

static create(input?, timezone?): Carbon

Defined in: datetime/Carbon.ts:314

Parse / wrap any supported input into a Carbon.

Accepts ISO 8601 strings (zoned, instant, plain date-time, or plain date), "YYYY-MM-DD HH:mm:ss" with a space separator, epoch numbers (ms), native Date, another Carbon, or a Temporal value; falls back to native Date parsing as a last resort.

Parameters

input?

CarbonInput = ...

The value to parse or wrap. Defaults to now.

timezone?

string

Timezone to interpret the value in; defaults to the input's own zone (for zoned inputs) or the system zone.

Returns

Carbon

A new Carbon instance.

Throws

When a string input cannot be parsed by any strategy.

today()

static today(timezone?): Carbon

Defined in: datetime/Carbon.ts:322

Today at midnight in the system timezone.

Parameters

timezone?

string

Returns

Carbon

tomorrow()

static tomorrow(timezone?): Carbon

Defined in: datetime/Carbon.ts:330

Tomorrow at midnight in the system (or given) timezone.

Parameters

timezone?

string

Returns

Carbon

yesterday()

static yesterday(timezone?): Carbon

Defined in: datetime/Carbon.ts:338

Yesterday at midnight in the system (or given) timezone.

Parameters

timezone?

string

Returns

Carbon

startOfMonth()

static startOfMonth(timezone?): Carbon

Defined in: datetime/Carbon.ts:346

First moment of the current month.

Parameters

timezone?

string

Returns

Carbon

endOfMonth()

static endOfMonth(timezone?): Carbon

Defined in: datetime/Carbon.ts:354

Last moment of the current month.

Parameters

timezone?

string

Returns

Carbon

startOfWeek()

static startOfWeek(timezone?): Carbon

Defined in: datetime/Carbon.ts:362

First moment of the current ISO week (Monday 00:00).

Parameters

timezone?

string

Returns

Carbon

endOfWeek()

static endOfWeek(timezone?): Carbon

Defined in: datetime/Carbon.ts:370

Last moment of the current ISO week (Sunday 23:59:59.999).

Parameters

timezone?

string

Returns

Carbon

startOfYear()

static startOfYear(timezone?): Carbon

Defined in: datetime/Carbon.ts:378

First moment of the current year.

Parameters

timezone?

string

Returns

Carbon

endOfYear()

static endOfYear(timezone?): Carbon

Defined in: datetime/Carbon.ts:386

Last moment of the current year.

Parameters

timezone?

string

Returns

Carbon

fromTimestamp()

static fromTimestamp(ts, timezone?): Carbon

Defined in: datetime/Carbon.ts:394

Create a Carbon from a Unix timestamp (seconds).

Parameters

ts

number

timezone?

string

Returns

Carbon

fromMilliseconds()

static fromMilliseconds(ms, timezone?): Carbon

Defined in: datetime/Carbon.ts:402

Create a Carbon from a Unix timestamp in milliseconds.

Parameters

ms

number

timezone?

string

Returns

Carbon

Conversion

toDate()

toDate(): Date

Defined in: datetime/Carbon.ts:1253

Return a native JS Date.

Returns

Date

toISOString()

toISOString(): string

Defined in: datetime/Carbon.ts:1258

ISO 8601 string with UTC offset, e.g. "2024-01-01T12:00:00+00:00".

Returns

string

toZonedDateTime()

toZonedDateTime(): ZonedDateTime

Defined in: datetime/Carbon.ts:1263

Return the backing Temporal.ZonedDateTime.

Returns

ZonedDateTime

toInstant()

toInstant(): Instant

Defined in: datetime/Carbon.ts:1268

Return a Temporal.Instant for this point in time.

Returns

Instant

toPlainDateTime()

toPlainDateTime(): PlainDateTime

Defined in: datetime/Carbon.ts:1273

Return a Temporal.PlainDateTime (loses timezone info).

Returns

PlainDateTime

toPlainDate()

toPlainDate(): PlainDate

Defined in: datetime/Carbon.ts:1278

Return a Temporal.PlainDate (loses time and timezone info).

Returns

PlainDate

toUnix()

toUnix(): number

Defined in: datetime/Carbon.ts:1283

Unix timestamp in seconds.

Returns

number

toMilliseconds()

toMilliseconds(): number

Defined in: datetime/Carbon.ts:1288

Unix timestamp in milliseconds.

Returns

number

valueOf()

valueOf(): number

Defined in: datetime/Carbon.ts:1293

Epoch milliseconds — enables numeric coercion and </> comparison.

Returns

number

toDateString()

toDateString(): string

Defined in: datetime/Carbon.ts:1298

"YYYY-MM-DD" date string.

Returns

string

toDateTimeString()

toDateTimeString(): string

Defined in: datetime/Carbon.ts:1302

"YYYY-MM-DD HH:mm:ss" date-time string.

Returns

string

toTimeString()

toTimeString(): string

Defined in: datetime/Carbon.ts:1306

"HH:mm:ss" time string.

Returns

string

toShortDate()

toShortDate(): string

Defined in: datetime/Carbon.ts:1310

Short date string, e.g. "Jun 09, 2026".

Returns

string

toLongDate()

toLongDate(): string

Defined in: datetime/Carbon.ts:1314

Long date string, e.g. "09 June 2026".

Returns

string

toJSON()

toJSON(): string

Defined in: datetime/Carbon.ts:1319

ISO string returned when JSON.stringify is called.

Returns

string

toString()

toString(): string

Defined in: datetime/Carbon.ts:1324

"YYYY-MM-DD HH:mm:ss" string used for string coercion.

Returns

string

toDatabase()

toDatabase(): string

Defined in: datetime/Carbon.ts:1329

ISO 8601 string — compatible with most database datetime columns.

Returns

string

Difference

diffInMilliseconds()

diffInMilliseconds(other): number

Defined in: datetime/Carbon.ts:1038

Raw millisecond difference: this - other. Positive when this is later.

Parameters

other

Carbon

Returns

number

diffInSeconds()

diffInSeconds(other): number

Defined in: datetime/Carbon.ts:1043

Signed difference in seconds (fractional).

Parameters

other

Carbon

Returns

number

diffInMinutes()

diffInMinutes(other): number

Defined in: datetime/Carbon.ts:1047

Signed difference in minutes (fractional).

Parameters

other

Carbon

Returns

number

diffInHours()

diffInHours(other): number

Defined in: datetime/Carbon.ts:1051

Signed difference in hours (fractional).

Parameters

other

Carbon

Returns

number

diffInDays()

diffInDays(other): number

Defined in: datetime/Carbon.ts:1055

Signed difference in days (fractional).

Parameters

other

Carbon

Returns

number

diffInWeeks()

diffInWeeks(other): number

Defined in: datetime/Carbon.ts:1059

Signed difference in weeks (fractional).

Parameters

other

Carbon

Returns

number

diffInMonths()

diffInMonths(other): number

Defined in: datetime/Carbon.ts:1064

Signed whole-month difference by calendar year/month fields.

Parameters

other

Carbon

Returns

number

diffInYears()

diffInYears(other): number

Defined in: datetime/Carbon.ts:1080

Signed difference in whole years — the number a person would call an age.

Derived from Temporal's calendar arithmetic rather than from subtracted year/month fields, because the day matters: a Feb-29 birthday measured on 28 February 2024 subtracts to a whole number of months and reports the birthday as already passed. The result truncates toward zero, so a birthday one day away is still the lower age.

Parameters

other

Carbon

The date to measure from.

Returns

number

Whole years from other to this instant; negative when other is later.

diffAsCarbonInterval()

diffAsCarbonInterval(other, largestUnit?): CarbonInterval

Defined in: datetime/Carbon.ts:1098

Return the difference as a CarbonInterval (backed by Temporal.Duration).

Uses Temporal's until() with the given largest unit so the result is calendar-aware (months and years are counted properly).

Parameters

other

Carbon

largestUnit?

DateTimeUnit = "day"

Returns

CarbonInterval

Example

const interval = birthday.diffAsCarbonInterval(Carbon.now(), "year");
console.log(interval.years); // → 28

diffForHumans()

Call Signature

diffForHumans(): string

Defined in: datetime/Carbon.ts:1124

Human-readable relative phrasing via Intl.RelativeTimeFormat.

With no argument, compares against now; pass another date to compare against it. The largest matching unit is used by default; raise options.parts for finer granularity.

Returns

string

A phrase such as "3 days ago", "in 2 hours", or "just now".

Example

Carbon.now().subtractDays(3).diffForHumans();          // "3 days ago"
Carbon.now().addHours(2).diffForHumans();              // "in 2 hours"
a.diffForHumans(b, { parts: 2, absolute: true });      // "1 day, 4 hours"

Call Signature

diffForHumans(options): string

Defined in: datetime/Carbon.ts:1125

Human-readable relative phrasing via Intl.RelativeTimeFormat.

With no argument, compares against now; pass another date to compare against it. The largest matching unit is used by default; raise options.parts for finer granularity.

Parameters

options

DiffForHumansOptions

Formatting options (syntax, parts, absolute, join, locale, intl).

Returns

string

A phrase such as "3 days ago", "in 2 hours", or "just now".

Example

Carbon.now().subtractDays(3).diffForHumans();          // "3 days ago"
Carbon.now().addHours(2).diffForHumans();              // "in 2 hours"
a.diffForHumans(b, { parts: 2, absolute: true });      // "1 day, 4 hours"

Call Signature

diffForHumans(other, options?): string

Defined in: datetime/Carbon.ts:1126

Human-readable relative phrasing via Intl.RelativeTimeFormat.

With no argument, compares against now; pass another date to compare against it. The largest matching unit is used by default; raise options.parts for finer granularity.

Parameters

other

string | Date | Carbon

A date/Carbon/string to compare against, or the options object.

options?

DiffForHumansOptions

Formatting options (syntax, parts, absolute, join, locale, intl).

Returns

string

A phrase such as "3 days ago", "in 2 hours", or "just now".

Example

Carbon.now().subtractDays(3).diffForHumans();          // "3 days ago"
Carbon.now().addHours(2).diffForHumans();              // "in 2 hours"
a.diffForHumans(b, { parts: 2, absolute: true });      // "1 day, 4 hours"

Formatting

format()

format(template?): string

Defined in: datetime/Carbon.ts:1227

Token-based formatting:

Parameters

template?

string = "YYYY-MM-DD HH:mm:ss"

Token string; defaults to "YYYY-MM-DD HH:mm:ss".

Returns

string

Example

Carbon.now().format("MMM DD, YYYY"); // "Jun 09, 2026"
Carbon.now().format("HH:mm");        // "14:30"

intlFormat()

intlFormat(locale?, options?): string

Defined in: datetime/Carbon.ts:1241

Format using native Intl.DateTimeFormat (locale-aware).

Parameters

locale?

string = "en-US"

options?

DateTimeFormatOptions = {}

Returns

string

Example

Carbon.now().intlFormat("en-US", { dateStyle: "long" });
// → "June 9, 2026"

Getters

year

Get Signature

get year(): number

Defined in: datetime/Carbon.ts:427

Full year (e.g. 2024).

Returns

number

month

Get Signature

get month(): number

Defined in: datetime/Carbon.ts:431

Month of year, 1–12.

Returns

number

day

Get Signature

get day(): number

Defined in: datetime/Carbon.ts:435

Day of month, 1–31.

Returns

number

hour

Get Signature

get hour(): number

Defined in: datetime/Carbon.ts:439

Hour of day, 0–23.

Returns

number

minute

Get Signature

get minute(): number

Defined in: datetime/Carbon.ts:443

Minute, 0–59.

Returns

number

second

Get Signature

get second(): number

Defined in: datetime/Carbon.ts:447

Second, 0–59.

Returns

number

millisecond

Get Signature

get millisecond(): number

Defined in: datetime/Carbon.ts:451

Millisecond, 0–999.

Returns

number

microsecond

Get Signature

get microsecond(): number

Defined in: datetime/Carbon.ts:455

Microsecond component, 0–999.

Returns

number

nanosecond

Get Signature

get nanosecond(): number

Defined in: datetime/Carbon.ts:459

Nanosecond component, 0–999.

Returns

number

dayOfWeek

Get Signature

get dayOfWeek(): number

Defined in: datetime/Carbon.ts:468

Day of week: 1 = Monday … 7 = Sunday (ISO 8601). Note: differs from JS Date.getDay() which uses 0 = Sunday.

Returns

number

dayOfYear

Get Signature

get dayOfYear(): number

Defined in: datetime/Carbon.ts:476

Day of year (1–366).

Returns

number

weekOfYear

Get Signature

get weekOfYear(): number

Defined in: datetime/Carbon.ts:484

Week of year (ISO 8601).

Returns

number

monthName

Get Signature

get monthName(): string

Defined in: datetime/Carbon.ts:498

Full English month name (e.g. "January"), in this instance's timezone.

toDate() yields a bare instant, and Intl.DateTimeFormat with no timeZone formats it in the system zone — so a Tokyo Carbon whose .month is 1 reported "December" on a machine running behind it. Every field getter on this class answers in the instance's zone; these have to agree with them.

Returns

string

dayName

Get Signature

get dayName(): string

Defined in: datetime/Carbon.ts:506

Full English weekday name (e.g. "Monday"), in this instance's timezone.

Returns

string

daysInMonth()

daysInMonth(): number

Defined in: datetime/Carbon.ts:1014

Number of days in this date's month (28–31).

Returns

number

daysInYear()

daysInYear(): number

Defined in: datetime/Carbon.ts:1018

Number of days in this date's year (365 or 366).

Returns

number

weeksInYear()

weeksInYear(): number

Defined in: datetime/Carbon.ts:1022

Number of ISO weeks in this date's year (52 or 53).

Returns

number

Setters

withYear()

withYear(amount): Carbon

Defined in: datetime/Carbon.ts:874

Copy with the year replaced.

Parameters

amount

number

Returns

Carbon

withMonth()

withMonth(amount): Carbon

Defined in: datetime/Carbon.ts:878

Copy with the month (1–12) replaced.

Parameters

amount

number

Returns

Carbon

withDay()

withDay(amount): Carbon

Defined in: datetime/Carbon.ts:882

Copy with the day of month replaced.

Parameters

amount

number

Returns

Carbon

withHour()

withHour(amount): Carbon

Defined in: datetime/Carbon.ts:886

Copy with the hour (0–23) replaced.

Parameters

amount

number

Returns

Carbon

withMinute()

withMinute(amount): Carbon

Defined in: datetime/Carbon.ts:890

Copy with the minute replaced.

Parameters

amount

number

Returns

Carbon

withSecond()

withSecond(amount): Carbon

Defined in: datetime/Carbon.ts:894

Copy with the second replaced.

Parameters

amount

number

Returns

Carbon

withMillisecond()

withMillisecond(amount): Carbon

Defined in: datetime/Carbon.ts:898

Copy with the millisecond replaced.

Parameters

amount

number

Returns

Carbon

withMicrosecond()

withMicrosecond(amount): Carbon

Defined in: datetime/Carbon.ts:902

Copy with the microsecond replaced.

Parameters

amount

number

Returns

Carbon

withNanosecond()

withNanosecond(amount): Carbon

Defined in: datetime/Carbon.ts:906

Copy with the nanosecond replaced.

Parameters

amount

number

Returns

Carbon

withTime()

withTime(hours, minutes, seconds?, ms?): Carbon

Defined in: datetime/Carbon.ts:911

Copy with the time-of-day replaced (microsecond/nanosecond zeroed).

Parameters

hours

number

minutes

number

seconds?

number = 0

ms?

number = 0

Returns

Carbon

Testing

setTestNow()

static setTestNow(value): void

Defined in: datetime/Carbon.ts:216

Freeze "now" at a fixed point, so behaviour that depends on the passage of time can be tested instead of waited out. Pass null to release it.

Everything built on Carbon.now moves with it — isPast, isToday, diffForHumans, a model's timestamps. A raw Date.now() does not: this moves Carbon's clock, not the process's.

Always release it, in an afterEach. A frozen clock that outlives its test makes the next one fail somewhere unrelated.

Parameters

value

CarbonInput | null

The instant to freeze at, in any form Carbon parses.

Returns

void

Example

Carbon.setTestNow('2025-01-01T00:00:00Z');
expect(token.isExpired()).toBe(false);
Carbon.setTestNow(null);

freeze()

static freeze(value?): Carbon

Defined in: datetime/Carbon.ts:231

Freeze the clock — at value when given, otherwise at the current instant. Returns the frozen Carbon so the test can assert against it.

Parameters

value?

CarbonInput

Returns

Carbon

Example

const start = Carbon.freeze();
await service.run();
expect(job.startedAt.equalTo(start)).toBe(true);

travelTo()

static travelTo(value): Carbon

Defined in: datetime/Carbon.ts:245

Jump the clock to an absolute point. Identical to Carbon.setTestNow with a value, and reads better at a call site that is moving through time.

Parameters

value

CarbonInput

Returns

Carbon

Example

Carbon.travelTo('2026-01-01');

travel()

static travel(amount): Carbon

Defined in: datetime/Carbon.ts:261

Move the clock relative to where it is now, freezing it if it was running.

Parameters

amount

TravelAmount

Units to move by; negative values go backwards.

Returns

Carbon

Example

Carbon.freeze();
Carbon.travel({ days: 8 });
expect(invitation.isExpired()).toBe(true);

release()

static release(): void

Defined in: datetime/Carbon.ts:268

Let the clock run normally again. Call it in afterEach.

Returns

void

isFrozen()

static isFrozen(): boolean

Defined in: datetime/Carbon.ts:273

Whether the clock is currently frozen.

Returns

boolean

withTestNow()

static withTestNow<T>(value, fn): Promise<T>

Defined in: datetime/Carbon.ts:289

Freeze the clock for the duration of fn, then release it — whether fn returns or throws. The scoped form, for when a test must not leak a frozen clock into the next one.

Type Parameters

T

T

Parameters

value

CarbonInput

fn

() => T | Promise<T>

Returns

Promise<T>

Example

await Carbon.withTestNow('2025-06-01', async () => {
  await service.expireStaleCarts();
});

Timezone

timezone

Get Signature

get timezone(): string

Defined in: datetime/Carbon.ts:412

Return the timezone ID (e.g. 'America/New_York').

Returns

string

inTimezone()

inTimezone(tz): Carbon

Defined in: datetime/Carbon.ts:420

Return a new Carbon representing the same instant in a different timezone.

Parameters

tz

string

Returns

Carbon