Working with datetime types in dsl

Last modified: 19 December 2024

We are providing 3 main built-In functions for working with datetime type:

#getTimestamp - function for getting datetime object from provided string (with or without specified timezone), or the current datetime in the passed/UTC+0 timezone;
#changeTimestamp - function for modification datetime object. Supports such operations like changing timezone or change(add/subtract) datetime components;
#getTimestampInformation - function for getting specific datetime object information. Provides information like day of the week, month of the year, days in the year, days in the month, string formatted to ISO-8601, etc.

Built-in datetime types

This section describes types that are being accepted or returned in built-In functions. These types are not built into the DSL itself. They only specify returned or accepted objects.

DateTimestamp

A type that represents datetime by formatted string timestamp and an optional timezone

type DateTimestamp = {
	timestamp?: string?;
	timezone?: string?;
};

Rules

At least one of the fields must be defined:

Timestamp

timestamp - time in an ISO-8601(2024-10-04T12:31:25.231-05:00) format with or without a timezone. In addition, it can also accept partial or slightly different formats of the time.

Timezone

timezone - timezone in an ISO-8601 format such as (<+|->)?<0-9><0-9>(:<0-9><0-9>)?, which is an offset from the UTC time. It can also be represented in TZDB identified and UTC<+|-><0-9><0-9>(:<0-9><0-9>)? formats.

If the method that accepted DateTimestamp object doesn't have a passed timezone, UTC+0 is stated as a timezone by default.

Otherwise, passed timezone is used as a default one.

DateTime

A type that represents datetime by components.

type DateTime = {
	year: number;
	month: number;
	day: number;
	hour: number;
	minute: number;
	second: number;
	millisecond: number;
};

Rules

All fields must be an integer type. If the floating point number is passed, then it is truncated to an integer.

year - Year of the Datetime. Must be more than Zero.
month - Month of the year. Must be between 1 and 12 inclusively. 1 is January and 12 is December.
day - Day of the month. Restriction on the range of the days is determined by month and year. In February 2024, max amount of days is 29, because 2024 is a leap-year. In February 2025 max amount of days is 28, because 2025 is not a leap-year.
hour - Hour of the day. Must be between 0 and 23 inclusively.
minute - Minute of the hour. Must be between 0 and 59 inclusively.
second - Second of the minute. Must be between 0 and 59 inclusively.
millisecond - Millisecond of the second. Must be between 0 and 999 inclusively.

If the method that accepted DateTime object doesn't have a passed timezone, UTC+0 is stated as a timezone by default.

Otherwise, passed timezone is used as a default one.

DateTimeWithZone

A type that represents datetime by components and provides in which timezone it is defined.

type DateTimeWithZone = DateTime & { timezone: string };

Rules

It has same restrictions as the Datetime and same restrictions on timezone as the timezone.

DateTimeOffset

A type that is used to declare changes in a datetime object.

type DateTimeOffset = {
	year?: number?;
	month?: number?;
	day?: number?;
	hour?: number?;
	minute?: number?;
	second?: number?;
	millisecond?: number?;
};

Rules

At least one of the field must be declared. Fields can be negative, positive or zero integer.

DateTimeInformation

A type that represents some specific information about datetime and string representation of datetime.

type DateTimeInformation = { 
    localTime: string;
    ISO: string; 
    ISOUTC: string; 
    unixTimestamp: number; 
    timezone: string; 
    dayOfWeek: "Monday" | "Tuesday" | "Wednesday" | "Thursday" | "Friday" | "Saturday" | "Sunday";
    monthName: "January" | "February" | "March" | "April" | "May"| "June" | "July" | "August" | "September" | "October" | "November" | "December"; 
    daysInMonth: number; 
    daysInYear: number; 
}

localTime

Datetime string in ISO-8601 format without specified timezone (2024-10-04T12:31:25.231).

ISO

Datetime string in ISO-8601 format with timezone (2024-10-04T12:31:25.231-05:00).

ISOUTC

Datetime string in ISO-8601 format in UTC+0 timezone (2024-10-04T17:31:25.231Z)

unixTimestamp

Number representation of datetime in unix seconds

Result wrapper

All results of the datetime built-In functions are wrapped into the following object:

type ResultWrapper = {
    errorMessage: string?;
    value: T?;
};

Rules

T value depends on used built-In function:

for #getTimestamp it is a DateTimeWithZone;
for #changeTimestamp it is a DateTimeWithZone;
for #getTimestampInformation it is a DateTimeInformation;

errorMessage will be null, if correct arguments are passed into built-In functions. Otherwise it will output an error string.

Built-In functions

getTimestamp

This function is used for receiving current datetime in specified/UTC+0 timezone or parsing datetime string into DateTimeWithZone.

Parameters

Name	Type	Description
datetime	`DateTimestamp?`	see DateTimestamp

Returns

ResultWrapper with T is DateTimeWithZone.

Always returns a new object that does not reference an already passed object.

timestamp	timezone	result
not defined	not defined	current datetime in default timezone
not defined	Europe/Berlin	current datetime in Europe/Berlin timezone
2024-10-04T12:31:25.231-05:00	not defined	date and time UTC-05 in timezone
2024-10-04T12:31:25.231-05:00	Europe/Berlin	date and time (2024-10-04T12:31:25.231) with overrided timezone to Europe/Berlin
2024-10-04T12:31:25.231	not defined	date and time in default timezone
2024-10-04T12:31:25.231	Europe/Berlin	date and time (2024-10-04T12:31:25.231) with timezone to Europe/Berlin

Examples

    var current = #getTimestamp();
    #assert(current.errorMessage is null);
    #assert(current.value?.year == 2024, current.value?.year?.toString());
    #assert(current.value?.month == 4, current.value?.month?.toString());
    #assert(current.value?.day == 14, current.value?.day?.toString());
    #assert(current.value?.hour == 15, current.value?.hour?.toString());
    #assert(current.value?.minute == 23, current.value?.minute?.toString());
    #assert(current.value?.second == 35, current.value?.second?.toString());
    #assert(current.value?.millisecond == 99, current.value?.millisecond?.toString());
    #assert(current.value?.timezone == "UTC", current.value?.timezone?.toString());

    set current = #getTimestamp({timezone: "+01:00"});
    #assert(current.errorMessage is null);
    #assert(current.value?.year == 2024, current.value?.year?.toString());
    #assert(current.value?.month == 4, current.value?.month?.toString());
    #assert(current.value?.day == 14, current.value?.day?.toString());
    #assert(current.value?.hour == 16, current.value?.hour?.toString());
    #assert(current.value?.minute == 23, current.value?.minute?.toString());
    #assert(current.value?.second == 35, current.value?.second?.toString());
    #assert(current.value?.millisecond == 99, current.value?.millisecond?.toString());
    #assert(current.value?.timezone == "UTC+01", current.value?.timezone?.toString());

    set current = #getTimestamp({timezone: "Europe/Berlin"});
    #assert(current.errorMessage is null);
    #assert(current.value?.year == 2024, current.value?.year?.toString());
    #assert(current.value?.month == 4, current.value?.month?.toString());
    #assert(current.value?.day == 14, current.value?.day?.toString());
    #assert(current.value?.hour == 17, current.value?.hour?.toString());
    #assert(current.value?.minute == 23, current.value?.minute?.toString());
    #assert(current.value?.second == 35, current.value?.second?.toString());
    #assert(current.value?.millisecond == 99, current.value?.millisecond?.toString());
    #assert(current.value?.timezone == "Europe/Berlin", current.value?.timezone?.toString());

    set current = #getTimestamp({timestamp: "2024-04-14T18:23:35.099+02", timezone: "Europe/Berlin"});
    #assert(current.errorMessage is null);
    #assert(current.value?.year == 2024, current.value?.year?.toString());
    #assert(current.value?.month == 4, current.value?.month?.toString());
    #assert(current.value?.day == 14, current.value?.day?.toString());
    #assert(current.value?.hour == 18, current.value?.hour?.toString());
    #assert(current.value?.minute == 23, current.value?.minute?.toString());
    #assert(current.value?.second == 35, current.value?.second?.toString());
    #assert(current.value?.millisecond == 99, current.value?.millisecond?.toString());
    #assert(current.value?.timezone == "Europe/Berlin", current.value?.timezone?.toString());

    set current = #getTimestamp({timestamp: "2024-04-14T18:23:35.099", timezone: "Europe/Berlin"});
    #assert(current.errorMessage is null);
    #assert(current.value?.year == 2024, current.value?.year?.toString());
    #assert(current.value?.month == 4, current.value?.month?.toString());
    #assert(current.value?.day == 14, current.value?.day?.toString());
    #assert(current.value?.hour == 18, current.value?.hour?.toString());
    #assert(current.value?.minute == 23, current.value?.minute?.toString());
    #assert(current.value?.second == 35, current.value?.second?.toString());
    #assert(current.value?.millisecond == 99, current.value?.millisecond?.toString());
    #assert(current.value?.timezone == "Europe/Berlin", current.value?.timezone?.toString());

    set current = #getTimestamp({timestamp: "2024-04-14T18:23:35.099+02"});
    #assert(current.errorMessage is null);
    #assert(current.value?.year == 2024, current.value?.year?.toString());
    #assert(current.value?.month == 4, current.value?.month?.toString());
    #assert(current.value?.day == 14, current.value?.day?.toString());
    #assert(current.value?.hour == 18, current.value?.hour?.toString());
    #assert(current.value?.minute == 23, current.value?.minute?.toString());
    #assert(current.value?.second == 35, current.value?.second?.toString());
    #assert(current.value?.millisecond == 99, current.value?.millisecond?.toString());
    #assert(current.value?.timezone == "UTC+02", current.value?.timezone?.toString());

    set current = #getTimestamp({timestamp: "2024-04-14T18:23:35.099"});
    #assert(current.errorMessage is null);
    #assert(current.value?.year == 2024, current.value?.year?.toString());
    #assert(current.value?.month == 4, current.value?.month?.toString());
    #assert(current.value?.day == 14, current.value?.day?.toString());
    #assert(current.value?.hour == 18, current.value?.hour?.toString());
    #assert(current.value?.minute == 23, current.value?.minute?.toString());
    #assert(current.value?.second == 35, current.value?.second?.toString());
    #assert(current.value?.millisecond == 99, current.value?.millisecond?.toString());
    #assert(current.value?.timezone == "UTC", current.value?.timezone?.toString());

getTimestampInformation

This function is used to receive information about passed datetime or about current datetime in UTC+0 timezone.
This function can also be used to format datetime into an ISO-8601 string, with or without a timezone.

Parameters

Name	Type	Description
datetime	`<DateTimestamp`\|`DateTimeWithZone`\|`DateTime>?`	see DateTimestamp or DateTimeWithZone or DateTime

Returns

ResultWrapper with T is DateTimeInformation.

Always returns a new object that does not reference an already passed object.

If arguments are not passed, getTimestampInformation then returns information about current datetime in UTC+0 timezone.
If datetime argument is passed - returns parsed datetime from an argument, see DateTimestamp, DateTimeWithZone or DateTime (based on provided object).

If an invalid argument is passed - returns errorMessage wrapped in a result object, with a readable descriptional message.

Examples

    var current = #getTimestamp({timezone: "Europe/Berlin"});
    #assert(current.errorMessage is null);
    #assert(current.value?.year == 2024, current.value?.year?.toString());
    #assert(current.value?.month == 4, current.value?.month?.toString());
    #assert(current.value?.day == 14, current.value?.day?.toString());
    #assert(current.value?.hour == 17, current.value?.hour?.toString());
    #assert(current.value?.minute == 23, current.value?.minute?.toString());
    #assert(current.value?.second == 35, current.value?.second?.toString());
    #assert(current.value?.millisecond == 99, current.value?.millisecond?.toString());
    #assert(current.value?.timezone == "Europe/Berlin", current.value?.timezone?.toString());

    var info = #getTimestampInformation(current.value);
    #assert(info.errorMessage is null, info.errorMessage);
    #assert(info.value?.dayOfWeek == "Sunday", info.value?.dayOfWeek);
    #assert(info.value?.monthName == "April");
    #assert(info.value?.daysInMonth == 30);
    #assert(info.value?.daysInYear == 366);
    #assert(info.value?.ISO == "2024-04-14T17:23:35.099+02", info.value?.ISO);
    #assert(info.value?.ISOUTC == "2024-04-14T15:23:35.099Z", info.value?.ISOUTC);
    #assert(info.value?.localTime == "2024-04-14T17:23:35.099", info.value?.localTime);
    #assert(info.value?.timezone == "Europe/Berlin", info.value?.timezone?.toString());
    #assert(info.value?.unixTimestamp == 1713108215, info.value?.unixTimestamp?.toString());

changeTimestamp

This function is used to change an already passed datetime. If datetime arguments are not passed, the function will be applied to the current datetime in UTC+0 timezone.

Parameters

Name	Type	Description
datetime	`<DateTimestamp`\|`DateTimeWithZone`\|`DateTime>?`	see DateTimestamp or DateTimeWithZone or DateTime
plus	`DateTimeOffset?`	see DateTimeOffset
timezone	`string`	see timezone

Returns

ResultWrapper with T is DateTimeWithZone.

Always returns a new object that does not reference an already passed object.

Default timezone is UTC+0.
If timezone is passed - it is used as a default one.

If arguments are not passed, then changeTimestamp returns information about current datetime in UTC+0 timezone.
If datetime argument is passed - apllies modifications to an argument, see DateTimestamp, DateTimeWithZone or DateTime (based on provided object).
If only datetime argument is passed then returns parsed DateTimeWithZone.
If plus argument is passed then it is applied to the passed datetime or the current datetime in UTC+0 timezone, and returns changed date with correct shifts of year/month/day/hour/minute/second/millisecond. Shifts respect leap-years.
If timezone is passed then, after applying the plus object (when it is passed), converts passed/resulting datetime into the passed timezone.

If an invalid argument is passed - returns errorMessage wrapped in a result object, with a readable descriptional message.

Examples

    var current = #changeTimestamp();
    #assert(current.errorMessage is null);
    #assert(current.value?.year == 2024, current.value?.year?.toString());
    #assert(current.value?.month == 4, current.value?.month?.toString());
    #assert(current.value?.day == 14, current.value?.day?.toString());
    #assert(current.value?.hour == 15, current.value?.hour?.toString());
    #assert(current.value?.minute == 23, current.value?.minute?.toString());
    #assert(current.value?.second == 35, current.value?.second?.toString());
    #assert(current.value?.millisecond == 99, current.value?.millisecond?.toString());
    #assert(current.value?.timezone == "UTC", current.value?.timezone?.toString());

    set current = #changeTimestamp(timezone: "Europe/Berlin");
    #assert(current.errorMessage is null);
    #assert(current.value?.year == 2024, current.value?.year?.toString());
    #assert(current.value?.month == 4, current.value?.month?.toString());
    #assert(current.value?.day == 14, current.value?.day?.toString());
    #assert(current.value?.hour == 17, current.value?.hour?.toString());
    #assert(current.value?.minute == 23, current.value?.minute?.toString());
    #assert(current.value?.second == 35, current.value?.second?.toString());
    #assert(current.value?.millisecond == 99, current.value?.millisecond?.toString());
    #assert(current.value?.timezone == "Europe/Berlin", current.value?.timezone?.toString());

    set current = #changeTimestamp(datetime: current.value, timezone: "Europe/Berlin");
    #assert(current.errorMessage is null);
    #assert(current.value?.year == 2024, current.value?.year?.toString());
    #assert(current.value?.month == 4, current.value?.month?.toString());
    #assert(current.value?.day == 14, current.value?.day?.toString());
    #assert(current.value?.hour == 17, current.value?.hour?.toString());
    #assert(current.value?.minute == 23, current.value?.minute?.toString());
    #assert(current.value?.second == 35, current.value?.second?.toString());
    #assert(current.value?.millisecond == 99, current.value?.millisecond?.toString());
    #assert(current.value?.timezone == "Europe/Berlin", current.value?.timezone?.toString());

    set current = #changeTimestamp(datetime: current.value, plus: { hour: 14 });
    #assert(current.errorMessage is null);
    #assert(current.value?.year == 2024, current.value?.year?.toString());
    #assert(current.value?.month == 4, current.value?.month?.toString());
    #assert(current.value?.day == 15, current.value?.day?.toString());
    #assert(current.value?.hour == 7, current.value?.hour?.toString());
    #assert(current.value?.minute == 23, current.value?.minute?.toString());
    #assert(current.value?.second == 35, current.value?.second?.toString());
    #assert(current.value?.millisecond == 99, current.value?.millisecond?.toString());
    #assert(current.value?.timezone == "Europe/Berlin", current.value?.timezone?.toString());

    set current = #changeTimestamp(datetime: current.value, plus: { minute: -24 });
    #assert(current.errorMessage is null);
    #assert(current.value?.year == 2024, current.value?.year?.toString());
    #assert(current.value?.month == 4, current.value?.month?.toString());
    #assert(current.value?.day == 15, current.value?.day?.toString());
    #assert(current.value?.hour == 6, current.value?.hour?.toString());
    #assert(current.value?.minute == 59, current.value?.minute?.toString());
    #assert(current.value?.second == 35, current.value?.second?.toString());
    #assert(current.value?.millisecond == 99, current.value?.millisecond?.toString());
    #assert(current.value?.timezone == "Europe/Berlin", current.value?.timezone?.toString());

    if (current.value is not null) {
        set current.value.month = 13;
    }
    
    set current = #changeTimestamp(datetime: current.value);
    #assert(current.errorMessage is not null);

    set current = #changeTimestamp(datetime: { timestamp: "2024-02-28"} , plus: { day: 365 });

    #assert(current.value?.year == 2025, current.value?.year?.toString());
    #assert(current.value?.month == 2, current.value?.month?.toString());
    #assert(current.value?.day == 27, current.value?.day?.toString());
    #assert(current.value?.hour == 0, current.value?.hour?.toString());
    #assert(current.value?.minute == 0, current.value?.minute?.toString());
    #assert(current.value?.second == 0, current.value?.second?.toString());
    #assert(current.value?.millisecond == 0, current.value?.millisecond?.toString());
    #assert(current.value?.timezone == "UTC", current.value?.timezone?.toString());

Found a mistake? Let us know.

Working with datetime types in dsl

Built-in datetime types

DateTimestamp

Rules

Timestamp

Timezone

DateTime

Rules

DateTimeWithZone

Rules

DateTimeOffset

Rules

DateTimeInformation

localTime

ISO

ISOUTC

unixTimestamp

Result wrapper

Rules

Built-In functions

getTimestamp

Parameters

Returns

Examples

getTimestampInformation

Parameters

Returns

Examples

changeTimestamp

Parameters

Returns

Examples

Enroll in beta