katanakit-js / DatesService

Class: DatesService

Defined in: src/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.

Methods

useAddDays()

useAddDays(date, days): string;

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

Adds a number of days to a date.

Parameters

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

Returns

string

The resulting date as an ISO string.

Example

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

---

useDateAdd()

useDateAdd(
   date, 
   amount, 
   unit
): string;

Defined in: src/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.

Parameters

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.

Returns

string

Example

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()

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

Defined in: src/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.

Parameters

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.

Returns

number

Example

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()

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

Defined in: src/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.

Parameters

Parameter	Type
date1	TemporalInput
date2	TemporalInput

Returns

"before" | "after" | "same"

Example

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

---

useDateSubtract()

useDateSubtract(
   date, 
   amount, 
   unit
): string;

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

Subtracts units from a date. The mirror of useDateAdd.

Parameters

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

Returns

string

---

useDurationBetween()

useDurationBetween(start, end): Duration;

Defined in: src/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.

Parameters

Parameter	Type
start	TemporalInput
end	TemporalInput

Returns

Duration

Example

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

---

useFirstDayOfMonth()

useFirstDayOfMonth(date?): string;

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

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

Parameters

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

Returns

string

The first day of the month as an ISO string.

Example

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

---

useFormat()

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

Defined in: src/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.

Parameters

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 {}).

Returns

string

The formatted date string.

Throws

If the input cannot be parsed as a date.

Example

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

---

useIsAfter()

useIsAfter(date1, date2): boolean;

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

Checks whether date1 is after date2.

Parameters

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

Returns

boolean

true if date1 is strictly after date2.

Example

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

---

useIsBefore()

useIsBefore(date1, date2): boolean;

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

Checks whether date1 is before date2.

Parameters

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

Returns

boolean

true if date1 is strictly before date2.

Example

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

---

useIsEqual()

useIsEqual(date1, date2): boolean;

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

Checks whether two dates are equal.

Parameters

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

Returns

boolean

true if the dates represent the same day.

Example

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

---

useLastDayOfMonth()

useLastDayOfMonth(date?): string;

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

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

Parameters

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

Returns

string

The last day of the month as an ISO string.

Example

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

---

useNow()

useNow(): string;

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

Returns today's date as an ISO date string.

Returns

string

The current date in YYYY-MM-DD format.

Example

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

---

useNowDateTime()

useNowDateTime(): string;

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

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

Returns

string

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

Example

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

---

useSubtractDays()

useSubtractDays(date, days): string;

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

Subtracts a number of days from a date.

Parameters

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

Returns

string

The resulting date as an ISO string.

Example

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

---

getInstance()

static getInstance(): DatesService;

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

Obtiene la instancia única del DatesService (Singleton).

Returns

DatesService

La instancia única de DatesService.

Example

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