Skip to content

DatesService

katanakit-js / DatesService

Defined in: core/services/dates.service.ts:72

DatesService - Singleton para operaciones de fechas.

Aplica el patrón Singleton: una única instancia reutilizable que centraliza toda la lógica de fechas (diferencias, formateo, aritmética y comparaciones). Puro, sin I/O, seguro para SSR.

useAddDays(date, days): string;

Defined in: core/services/dates.service.ts:395

Adds a number of days to a date.

Parameter Type Description
date string | PlainDate Base date (ISO string or PlainDate).
days number Number of days to add (can be negative).

string

The resulting date as an ISO string.

useAddDays("2024-01-01", 10); // "2024-01-11"

useDateAdd(
date,
amount,
unit
): string;

Defined in: core/services/dates.service.ts:244

Returns the date a given number of units away, preserving calendar semantics — adding one month to the 31st lands on the 31st of a shorter month, not on an overflow.

Parameter Type Description
date TemporalInput Starting date.
amount number Signed amount; negative moves backwards.
unit "years" | "quarters" | "months" | "weeks" | "days" | "hours" | "minutes" Granularity to move by.

string

useDateAdd("2026-01-31", 1, "months"); // "2026-02-28"
useDateAdd(useNow(), 14, "days"); // two weeks out
useDateAdd("2026-01-01", 2, "quarters");// "2026-07-01"

useDateBetween(
start,
end,
unit?
): number;

Defined in: core/services/dates.service.ts:184

Returns the whole number of units between two dates.

Signed, like Notion’s dateBetween: a later end is positive, an earlier one negative. Never fractional — total() reports 0.0849 years across a month because a year is not a whole number of months, and a fractional year count is noise for a calendar API.

Parameter Type Default value Description
start TemporalInput undefined Range start (any TemporalInput).
end TemporalInput undefined Range end (any TemporalInput).
unit? "years" | "quarters" | "months" | "weeks" | "days" | "hours" | "minutes" "days" Granularity to report; defaults to days.

number

useDateBetween("2020-01-01", "2022-04-16"); // 836
useDateBetween("2020-01-01", "2022-04-16", "months"); // 27
useDateBetween("2022-04-16", "2020-01-01", "days"); // -836

useDateOrder(date1, date2): "before" | "after" | "same";

Defined in: core/services/dates.service.ts:294

Returns which of two dates comes first.

A three-way comparison is what a date range filter actually needs — before and after answer different queries, and collapsing them into a boolean loses the direction you were asked about.

Parameter Type
date1 TemporalInput
date2 TemporalInput

"before" | "after" | "same"

useDateOrder(deadline, useNow()); // "before" | "after" | "same"

useDateSubtract(
date,
amount,
unit
): string;

Defined in: core/services/dates.service.ts:249

Subtracts units from a date. The mirror of useDateAdd.

Parameter Type
date TemporalInput
amount number
unit "years" | "quarters" | "months" | "weeks" | "days" | "hours" | "minutes"

string


useDurationBetween(start, end): Duration;

Defined in: core/services/dates.service.ts:222

Returns the balanced breakdown of the span between two dates, without collapsing it to prose or to a single number.

The shape is Temporal’s own, so .years, .months and .days are available separately — which a single formatted string cannot give you without parsing English out of it.

Parameter Type
start TemporalInput
end TemporalInput

Duration

const span = useDurationBetween("2020-01-01", "2022-04-16");
span.years; // 2
span.months; // 3
span.days; // 15

useFirstDayOfMonth(date?): string;

Defined in: core/services/dates.service.ts:477

Returns the first day of the month for a given date.

Parameter Type Description
date? string | PlainDate Base date (defaults to today).

string

The first day of the month as an ISO string.

useFirstDayOfMonth("2024-06-15"); // "2024-06-01"

useFormat(
dateInput,
locale?,
options?
): string;

Defined in: core/services/dates.service.ts:320

Formats a date input into a localised string using Intl.DateTimeFormat.

Accepts epoch milliseconds, ISO strings, native Date objects, Temporal.Instant, or any Temporal date/time type.

Parameter Type Default value Description
dateInput TemporalInput undefined The value to format.
locale? "en" | "es" | "fr" | "de" | "it" | "pt" | "ja" | "zh" "en" BCP 47 locale tag (defaults to "en").
options? DateTimeFormatOptions {} Intl.DateTimeFormatOptions (defaults to {}).

string

The formatted date string.

If the input cannot be parsed as a date.

useFormat("2024-06-15"); // "6/15/2024" (en-US)
useFormat(Date.now(), "es", { dateStyle: "full" }); // "sábado, 15 de junio de 2024"

useIsAfter(date1, date2): boolean;

Defined in: core/services/dates.service.ts:462

Checks whether date1 is after date2.

Parameter Type Description
date1 string | PlainDate First date (ISO string or PlainDate).
date2 string | PlainDate Second date (ISO string or PlainDate).

boolean

true if date1 is strictly after date2.

useIsAfter("2024-06-15", "2024-01-01"); // true
useIsAfter("2024-06-15", "2024-06-15"); // false

useIsBefore(date1, date2): boolean;

Defined in: core/services/dates.service.ts:445

Checks whether date1 is before date2.

Parameter Type Description
date1 string | PlainDate First date (ISO string or PlainDate).
date2 string | PlainDate Second date (ISO string or PlainDate).

boolean

true if date1 is strictly before date2.

useIsBefore("2024-01-01", "2024-06-15"); // true
useIsBefore("2024-06-15", "2024-06-15"); // false

useIsEqual(date1, date2): boolean;

Defined in: core/services/dates.service.ts:428

Checks whether two dates are equal.

Parameter Type Description
date1 string | PlainDate First date (ISO string or PlainDate).
date2 string | PlainDate Second date (ISO string or PlainDate).

boolean

true if the dates represent the same day.

useIsEqual("2024-06-15", "2024-06-15"); // true
useIsEqual("2024-06-15", "2024-06-16"); // false

useLastDayOfMonth(date?): string;

Defined in: core/services/dates.service.ts:493

Returns the last day of the month for a given date.

Parameter Type Description
date? string | PlainDate Base date (defaults to today).

string

The last day of the month as an ISO string.

useLastDayOfMonth("2024-02-10"); // "2024-02-29" (leap year)
useLastDayOfMonth("2024-06-15"); // "2024-06-30"

useNow(): string;

Defined in: core/services/dates.service.ts:365

Returns today’s date as an ISO date string.

string

The current date in YYYY-MM-DD format.

useNow(); // "2024-06-15"

useNowDateTime(): string;

Defined in: core/services/dates.service.ts:379

Returns the current date and time as an ISO string (no timezone offset).

string

The current date-time in YYYY-MM-DDTHH:MM:SS format.

useNowDateTime(); // "2024-06-15T14:30:00"

useSubtractDays(date, days): string;

Defined in: core/services/dates.service.ts:411

Subtracts a number of days from a date.

Parameter Type Description
date string | PlainDate Base date (ISO string or PlainDate).
days number Number of days to subtract.

string

The resulting date as an ISO string.

useSubtractDays("2024-01-11", 10); // "2024-01-01"

static getInstance(): DatesService;

Defined in: core/services/dates.service.ts:91

Obtiene la instancia única del DatesService (Singleton).

DatesService

La instancia única de DatesService.

const dates = DatesService.getInstance();
dates.useNow();