Class AppDate

AppDate: A timezone-aware date and time abstraction.

IMPORTANT: Always use this wrapped abstraction instead of moment or new Date directly. You should not polute the application with randomly used date methods.

This class wraps the dayjs library to provide a consistent interface for working with dates and times in a specific timezone. It offers methods for date manipulation, comparison, and formatting, while maintaining timezone context.

Key features:

Timezone awareness: All operations respect the specified timezone.
Immutability: Operations return new instances, preserving the original.
Consistent API: Provides a uniform interface for date operations.
Error handling: Gracefully handles invalid dates and parsing errors.

Use AppDate to ensure consistent date handling across your application, especially when dealing with different timezones or complex date logic.

Example

const today = AppDate.now();
const futureDate = today.add(5, 'days');
console.log(futureDate.toLocalizedDateString());

Properties

`Readonly`dayjsDate

dayjsDate: Dayjs

`Readonly`timezone

timezone: string

Methods

add

add(value: number, unit?: ManipulateType): AppDate
Parameters
- value: number
- Optionalunit: ManipulateType
Returns AppDate
- Defined in index.ts:271

addWorkingDays

addWorkingDays(days: number): AppDate
Parameters
- days: number
Returns AppDate
- Defined in index.ts:350

endOf

endOf(unit: OpUnitType): AppDate
Parameters
- unit: OpUnitType
Returns AppDate
- Defined in index.ts:286

format

format(template?: FormatTemplate): string
Get the formatted date according to the string of tokens passed in.

To escape characters, wrap them in square brackets (e.g. [MM]).
Parameters
- template: FormatTemplate = "YYYY-MM-DDTHH:mm:ssZ[Z]"
Returns string
See
format documentation

TODO: Support date-fns/Unicode format tokens (e.g. EEEE for day of week) or warn when unrecognized tokens are used instead of printing them literally. Currently uses dayjs tokens: dddd = day of week, not EEEE.
- Defined in index.ts:448

formatDateTime

formatDateTime(__namedParameters?: LocalizedFormatOptions): string
Parameters
- __namedParameters: LocalizedFormatOptions = {}
Returns string
- Defined in index.ts:467

formatShort

formatShort(options?: LocalizedFormatOptions): string
Parameters
- options: LocalizedFormatOptions = {}
  Optional settings for short formatting.
Returns string
The short formatted date string.
Example
```
const date = AppDate.now();
console.log(date.formatShort({ includeDayOfWeek: true })); // "Su, 04.01."
console.log(date.formatShort({ includeDayOfWeek: false })); // "04.01."
```
- Defined in index.ts:463

isAfter

isAfter(other: AppDate, unit?: OpUnitType): boolean
Parameters
- other: AppDate
- Optionalunit: OpUnitType
Returns boolean
- Defined in index.ts:314

isBefore

isBefore(other: AppDate, unit?: OpUnitType): boolean
Parameters
- other: AppDate
- Optionalunit: OpUnitType
Returns boolean
- Defined in index.ts:299

isBetween

isBetween(
    from?: AppDate,
    to?: AppDate,
    unit?: OpUnitType,
    inclusivity?: "()" | "(]" | "[)" | "[]",
): boolean
Parameters
- from: AppDate = ...
- to: AppDate = ...
- Optionalunit: OpUnitType
- Optionalinclusivity: "()" | "(]" | "[)" | "[]"
Returns boolean
- Defined in index.ts:318

isFirstDayOfWeek

isFirstDayOfWeek(): boolean
Returns boolean
- Defined in index.ts:331

isSame

isSame(other: AppDate, unit?: OpUnitType): boolean
Parameters
- other: AppDate
- Optionalunit: OpUnitType
Returns boolean
- Defined in index.ts:303

isToday

isToday(): boolean
returns true if date is current day

Returns boolean
- Defined in index.ts:310

isValid

isValid(): boolean
Returns boolean
- Defined in index.ts:295

isWorkingDay

isWorkingDay(): boolean
Returns boolean
- Defined in index.ts:336

nextWorkingDay

nextWorkingDay(): AppDate
Returns AppDate
- Defined in index.ts:340

previousWorkingDay

previousWorkingDay(): AppDate
Returns AppDate
- Defined in index.ts:345

startOf

startOf(unit: OpUnitType): AppDate
Parameters
- unit: OpUnitType
Returns AppDate
- Defined in index.ts:281

subtract

subtract(value: number, unit?: ManipulateType): AppDate
Parameters
- value: number
- Optionalunit: ManipulateType
Returns AppDate
- Defined in index.ts:276

toDateString

toDateString(): `${string}-${string}-${string}`
Converts the current date to a string: YYYY-MM-DD

Returns `${string}-${string}-${string}`
A string representing the current date in "YYYY-MM-DD" format.
Example
```
const date = AppDate.now();
console.log(date.toDateString()); // "2026-01-04"
```
- Defined in index.ts:383

toEpochMillis

toEpochMillis(): number
Converts the current date to a epoch milliseconds (timestamp in milliseconds).

Returns number
The epoch milliseconds.
Example
```
const date = AppDate.now();
console.log(date.toEpochMillis()); // 1714732800000
```
- Defined in index.ts:434

toEpochSeconds

toEpochSeconds(): number
Converts the current date to a epoch seconds (unix timestamp).

Returns number
The epoch seconds.
Example
```
const date = AppDate.now();
console.log(date.toEpochSeconds()); // 1714732800
```
- Defined in index.ts:421

toLocalizedDateString

toLocalizedDateString(__namedParameters?: LocalizedFormatOptions): string
Locale friendly format:
```
de, ch = 20.10.1985
us     = 10/20/1985
{includeDayOfWeek: true}
de, ch = Son, 20.10.1985
us     = Sun, 10/20/1985
```
Parameters
- __namedParameters: LocalizedFormatOptions = {}
Returns string
- Defined in index.ts:397

toLocalTime

toLocalTime(): string
Converts Date in following string format: HH:mm (20:10)

Returns string
- Defined in index.ts:363

tomorrow

tomorrow(): AppDate
Returns AppDate
- Defined in index.ts:291

toRelative

toRelative(options?: RelativeTimeOptions): string
Returns a localized string representing the relative time from now. Automatically handles past and future dates.
Parameters
- Optionaloptions: RelativeTimeOptions
  Optional settings for capping and fallback behavior
  - Optionalcap?: number
    Cap the relative time at this many days. Shows "X+" format after this threshold.
  - Optionalfallback?: (date: AppDate) => string
    Custom formatter function called when fallbackAfterDays is exceeded. Defaults to toLocalizedDateString().
  - OptionalfallbackAfterDays?: number
    After this many days, use the fallback formatter instead of relative time.
Returns string
A localized string like "2 days ago" or "in 3 hours"
Example
```
await setAppDateLanguage('sr');
AppDate.now().subtract(2, 'day').toRelative(); // "pre 2 dana"
AppDate.now().add(3, 'hour').toRelative();     // "za 3 sata"

// With cap at 9 days
AppDate.now().subtract(15, 'day').toRelative({ cap: 9 }); // "pre 9+ dana"

// With fallback to date after 14 days
AppDate.now().subtract(20, 'day').toRelative({
  cap: 9,
  fallbackAfterDays: 14,
  fallback: (d) => d.toLocalizedDateString()
}); // "20.12.2025"
```
- Defined in index.ts:501

toUtcDateString

toUtcDateString(): `${string}-${string}-${string}`
Returns `${string}-${string}-${string}`
- Defined in index.ts:403

toUtcString

toUtcString(): string
Returns string
- Defined in index.ts:407

toUtcTime

toUtcTime(): string
Returns time in UTC format: HH:mm:ssZ

Returns string
- Defined in index.ts:369

`Static`fromDateString

fromDateString(date: string): AppDate
Creates a AppDate instance from a date string.
Parameters
- date: string
  A string representing a date in "YYYY-MM-DD" format.
Returns AppDate
A new AppDate instance set to the given date.

If the date string is invalid or cannot be parsed, it returns an invalid AppDate instance. The time part of the created AppDate will be set to midnight in the local timezone.
Example
```
const date = AppDate.fromDateString("2023-05-21");
```
- Defined in index.ts:152

`Static`fromEpochMillis

fromEpochMillis(ms: number): AppDate
Creates a AppDate instance from a epoch milliseconds.
Parameters
- ms: number
  A number representing a epoch milliseconds.
Returns AppDate
A new AppDate instance set to the given epoch milliseconds.
Example
```
const date = AppDate.fromEpochMillis(1714732800000);
console.log(date.toLocalizedDateString()); // "04.01.2026"
```
}
- Defined in index.ts:186

`Static`fromEpochSeconds

fromEpochSeconds(seconds: number): AppDate
Creates a AppDate instance from a epoch seconds.
Parameters
- seconds: number
  A number representing a epoch seconds.
Returns AppDate
A new AppDate instance set to the given epoch seconds.
Example
```
const date = AppDate.fromEpochSeconds(1714732800);
console.log(date.toLocalizedDateString()); // "04.01.2026"
```
- Defined in index.ts:168

`Static`fromLocalTime

fromLocalTime(time: string): AppDate
Creates a AppDate instance from a local time string.
Parameters
- time: string
  A string representing a local time in any valid (24h) time format.
Returns AppDate
A new AppDate instance set to the given time on the todays date.

If the time string is invalid, it returns an invalid AppDate instance. The date part defaults to the current date in the local timezone.
Example
```
const date = AppDate.fromLocalTime("14:30"); Today's date, 14:30 or (02:30 PM)
```
- Defined in index.ts:202

`Static`fromUtcString

fromUtcString(date?: string): AppDate
Parameters
- Optionaldate: string
  A string representing a UTC date in "YYYY-MM-DD" format.
Returns AppDate
A new AppDate instance set to the given UTC date.
Example
```
const date = AppDate.fromUtcString("2026-01-04");
console.log(date.toLocalizedDateString()); // "04.01.2026"
```
- Defined in index.ts:224

`Static`fromUtcTime

fromUtcTime(time: string): AppDate
Creates a AppDate instance from a UTC time string.
Parameters
- time: string
  A string representing a UTC time in "HH:mm:ssZ" format.
Returns AppDate
A new AppDate instance set to the given UTC time.
Example
```
const time = AppDate.fromUtcTime("14:30:00+00:00");
console.log(time.toLocalizedDateString()); // "04.01.2026"
```
- Defined in index.ts:240

`Static`invalid

invalid(): AppDate
Creates an invalid AppDate instance. Usiful for: Error handeling, default values, avoids null object pattern and plays nicely with validation

Returns AppDate
- Defined in index.ts:132

`Static`maxDate

maxDate(): AppDate
Returns the maximum supported date (2200-12-31).

Returns AppDate
A new AppDate instance set to the maximum supported date.
Example
```
const maxDate = AppDate.maxDate();
console.log(maxDate.toLocalizedDateString()); // "31.12.2200"
```
- Defined in index.ts:267

`Static`minDate

minDate(): AppDate
Returns AppDate
A new AppDate instance set to the minimum supported date (1900-01-01).
Example
```
const minDate = AppDate.minDate();
console.log(minDate.toLocalizedDateString()); // "01.01.1900"
```
- Defined in index.ts:253

`Static`now

now(): AppDate
Returns AppDate
- Defined in index.ts:136

Class AppDate

Example

Index

Properties

Methods

Properties

ReadonlydayjsDate

Readonlytimezone

Methods

add

Parameters

Returns AppDate

addWorkingDays

Parameters

Returns AppDate

endOf

Parameters

Returns AppDate

format

Parameters

Returns string

See

formatDateTime

Parameters

Returns string

formatShort

Parameters

Returns string

Example

isAfter

Parameters

Returns boolean

isBefore

Parameters

Returns boolean

isBetween

Parameters

Returns boolean

isFirstDayOfWeek

Returns boolean

isSame

Parameters

Returns boolean

isToday

Returns boolean

isValid

Returns boolean

isWorkingDay

Returns boolean

nextWorkingDay

Returns AppDate

previousWorkingDay

Returns AppDate

startOf

Parameters

Returns AppDate

subtract

Parameters

Returns AppDate

toDateString

Returns `${string}-${string}-${string}`

Example

toEpochMillis

Returns number

Example

toEpochSeconds

Returns number

Example

toLocalizedDateString

Parameters

Returns string

toLocalTime

Returns string

tomorrow

Returns AppDate

toRelative

Parameters

Optionalcap?: number

Optionalfallback?: (date: AppDate) => string

OptionalfallbackAfterDays?: number

`Readonly`dayjsDate

`Readonly`timezone

`Optional`cap?: number

`Optional`fallback?: (date: AppDate) => string

`Optional`fallbackAfterDays?: number

`Static`fromDateString

`Static`fromEpochMillis

`Static`fromEpochSeconds

`Static`fromLocalTime

`Static`fromUtcString

`Static`fromUtcTime

`Static`invalid

`Static`maxDate

`Static`minDate

`Static`now