@tmlmobilidade/go-utils-dates 20260828.1636.54

package/dist/date-format.d.ts

@@ -0,0 +1,15 @@
+import { type DateFormat } from '@tmlmobilidade/go-types-shared';
+export interface DateFormatConfig {
+    day?: '2-digit' | 'numeric';
+    hour?: '2-digit' | 'numeric';
+    minute?: '2-digit' | 'numeric';
+    month?: '2-digit' | 'long' | 'numeric' | 'short';
+    second?: '2-digit' | 'numeric';
+    timeZoneName?: 'long' | 'short';
+    weekday?: 'long' | 'narrow' | 'short';
+    year?: '2-digit' | 'numeric';
+}
+/**
+ * A map of date formats to their corresponding config.
+ */
+export declare const DateFormatConfigMap: Record<DateFormat, DateFormatConfig>;

package/dist/date-format.js

@@ -0,0 +1,35 @@
+/* * */
+/**
+ * A map of date formats to their corresponding config.
+ */
+export const DateFormatConfigMap = {
+    full: {
+        day: 'numeric',
+        month: 'long',
+        year: 'numeric',
+    },
+    iso: {
+        day: 'numeric',
+        month: 'numeric',
+        year: 'numeric',
+    },
+    only_date: {
+        day: 'numeric',
+        month: 'numeric',
+        year: 'numeric',
+    },
+    only_time: {
+        hour: 'numeric',
+        minute: 'numeric',
+    },
+    only_time_with_seconds: {
+        hour: 'numeric',
+        minute: 'numeric',
+        second: 'numeric',
+    },
+    short: {
+        day: 'numeric',
+        month: 'numeric',
+        year: 'numeric',
+    },
+};

package/dist/dates.d.ts

@@ -0,0 +1,161 @@
+import { type CalendarDate, DateFormat, type OperationalDateInt, type TimezoneIdentified, type UnixTimestamp } from '@tmlmobilidade/go-types-shared';
+import { type DateObjectUnits, type DateTimeUnit, type DurationObjectUnits } from 'luxon';
+interface DatesConstructor {
+    calendar_date: CalendarDate;
+    iso: null | string;
+    js_date: Date;
+    operational_date_int: OperationalDateInt;
+    std_window: {
+        end: UnixTimestamp;
+        start: UnixTimestamp;
+    };
+    unix_timestamp: UnixTimestamp;
+}
+export declare class Dates {
+    static readonly standardWindowHours = 10;
+    static readonly standardWindowMilliseconds: number;
+    calendar_date: CalendarDate;
+    iso: null | string;
+    js_date: Date;
+    operational_date_int: OperationalDateInt;
+    std_window: {
+        end: UnixTimestamp;
+        start: UnixTimestamp;
+    };
+    unix_timestamp: UnixTimestamp;
+    constructor(params: DatesConstructor);
+    /**
+     * Creates a Dates object from a date/time string in a specific format.
+     * @param text The date/time string to parse.
+     * @param format The format string to use for parsing the date/time.
+     *   See Luxon documentation for format tokens: https://moment.github.io/luxon/#/formatting?id=table-of-tokens
+     * @param timezone The timezone to set for the Dates object.
+     * @returns A new Dates object parsed from the string.
+     */
+    static fromFormat(text: string, format: string, timezone: 'local' | 'utc' | TimezoneIdentified): Dates;
+    /**
+     * Creates a Dates object from an ISO 8601 date/time string.
+     * This method assumes the string has a timezone offset.
+     * @param isoText The ISO 8601 date/time string to parse.
+     * @returns A new Dates object created from the ISO string.
+     */
+    static fromISO(isoText: string): Dates;
+    /**
+     * Creates a Dates object from a JavaScript Date object.
+     * @param date The JavaScript Date object to convert. It is assumed that the date is in UTC.
+     * @returns A new Dates object created from the JavaScript Date.
+     */
+    static fromJSDate(date: Date): Dates;
+    /**
+     * Creates a Dates object from an operational date integer.
+     * @param date The operational date integer in 'yyyyMMdd' format.
+     * @param timezone The timezone to set for the Dates object.
+     * @returns A new Dates object created from the operational date.
+     */
+    static fromOperationalDateInt(date: OperationalDateInt | string, timezone: 'local' | 'utc' | TimezoneIdentified): Dates;
+    /**
+     * Creates a Dates object from Unix epoch seconds
+     * @param seconds The number of seconds since Unix epoch
+     * @returns A new Dates object created from the seconds timestamp
+     */
+    static fromSeconds(seconds: number): Dates;
+    /**
+     * Creates a Dates object from Unix epoch in milliseconds.
+     * @param millis The number of milliseconds since Unix epoch. Unix timestamp is always in UTC.
+     * @returns A new Dates object created from the milliseconds timestamp.
+     */
+    static fromUnixTimestamp(millis: number | UnixTimestamp): Dates;
+    /**
+     * Creates a Dates object with the current date and time.
+     * @param timezone The timezone to set for the Dates object.
+     * @returns A new Dates object with the current date and time in the specified timezone.
+     */
+    static now(timezone: 'local' | 'utc' | TimezoneIdentified): Dates;
+    /**
+     * Returns the difference between this date and another date.
+     * @param other The other Dates object to compare with
+     * @param unit The unit of time to return the difference in (defaults to 'day')
+     * @returns The difference as a number in the specified unit
+     */
+    diff(other: Dates, unit?: DateTimeUnit): number;
+    /**
+     * Returns a new Dates object with the end of the specified unit.
+     * @param unit The unit to set the end of, e.g., 'day', 'month', 'year', etc.
+     * @returns A new Dates object with the end of the specified unit.
+     */
+    endOf(unit: DateTimeUnit): Dates;
+    /**
+     * Returns a new Dates object with the current date and time minus a duration.
+     * @param duration The duration to subtract
+     * @returns A new Dates object with the current date and time minus a duration
+     */
+    minus(duration: DurationObjectUnits): Dates;
+    /**
+     * Returns a new Dates object with the current date and time plus a duration
+     * @param duration The duration to add
+     * @returns A new Dates object with the current date and time plus a duration
+     */
+    plus(duration: DurationObjectUnits): Dates;
+    /**
+     * Sets the date and time for the Dates object.
+     * @param dateOrTime The date or time to set, can be an object with DateObjectUnits or a string in ISO format.
+     * @returns The Dates object
+     */
+    set(dateOrTime: DateObjectUnits): Dates;
+    /**
+     * Sets the timezone for the Dates object.
+     * @param timezone The timezone to set in the format of an IANA timezone.
+     * @param method The method to use for updating the timezone information.
+     *   - `offset_only` Updates only offset setting to the new timezone. The ISO string will show adjusted time components (hour, minutes, etc.) to their equivalent in the new timezone. The UTC value in milliseconds stays the same. The UNIX timestamp is the source of truth.
+     *   - `rebase_utc` Keeps the individual time components (hour, minutes, etc.) and updates the internal UTC value in milliseconds to reflect the change. The ISO string will show the same time components as before, but the UTC value in milliseconds will be adjusted to match the new timezone. The ISO string is the source of truth.
+     * @returns The Dates object
+     */
+    setZone(timezone: 'local' | 'utc' | TimezoneIdentified, method: 'offset_only' | 'rebase_utc'): Dates;
+    /**
+     * Returns a new Dates object with the start of the specified unit.
+     * @param unit The unit to set the start of, e.g., 'day', 'month', 'year', etc.
+     * @returns A new Dates object with the start of the specified unit.
+     */
+    startOf(unit: DateTimeUnit): Dates;
+    /**
+     * Returns the time remaining until a given unix_timestamp (in ms) from now,
+     * as an object with minutes, hours, and days (all as floats, not rounded).
+     * @param unixTimestamp The target timestamp in milliseconds
+     * @returns { minutes: number, hours: number, days: number }
+     */
+    timeUntil(unixTimestamp: UnixTimestamp): {
+        days: number;
+        hours: number;
+        minutes: number;
+    };
+    /**
+     * Returns the date as a string in the specified format.
+     * @param format The format string (see Luxon tokens documentation)
+     * @param opts Optional formatting options (e.g., { locale: 'pt' })
+     * @returns The date as a string in the specified format
+     */
+    toFormat(format: string, opts?: {
+        locale?: string;
+    }): string;
+    /**
+     * Returns the date as a string in the specified format.
+     * @param format The format string (see Luxon tokens documentation)
+     * @returns The date as a string in the specified format
+     */
+    toLocaleString(format: DateFormat, locale?: string): string;
+    /**
+     * Returns the operational date based on the provided timestamp and format.
+     * @param isoDate The ISO date string to calculate the operational date.
+     * @returns The operational date in the yyyyLLdd format.
+     */
+    private getOperationalDateInt;
+    /**
+     * This function returns the start and end of the standard window interval for a given timestamp.
+     * The standard window interval is the period in which is possible to receive data for a given ride.
+     * Currently, the standard window starts 10 hours before and ends 10 hours after the scheduled ride start.
+     * @param isoDate The ISO date string to calculate the standard window interval.
+     * @returns An object containing the start and end of the standard window interval.
+     */
+    private getStandardWindowInterval;
+}
+export {};

package/dist/dates.js

@@ -0,0 +1,378 @@
+/* eslint-disable @typescript-eslint/naming-convention */
+import { CALENDAR_DATE_FORMAT, OPERATIONAL_DATE_FORMAT } from '@tmlmobilidade/go-types-shared';
+import { DateTime } from 'luxon';
+import { DateFormatConfigMap } from './date-format.js';
+/* * */
+export class Dates {
+    //
+    static standardWindowHours = 10;
+    static standardWindowMilliseconds = this.standardWindowHours * 1000 * 60 * 60;
+    calendar_date;
+    iso;
+    js_date;
+    operational_date_int;
+    std_window;
+    unix_timestamp;
+    constructor(params) {
+        this.calendar_date = params.calendar_date;
+        this.iso = params.iso ?? null;
+        this.js_date = params.js_date;
+        this.operational_date_int = params.operational_date_int;
+        this.std_window = params.std_window;
+        this.unix_timestamp = params.unix_timestamp;
+    }
+    /**
+     * Creates a Dates object from a date/time string in a specific format.
+     * @param text The date/time string to parse.
+     * @param format The format string to use for parsing the date/time.
+     *   See Luxon documentation for format tokens: https://moment.github.io/luxon/#/formatting?id=table-of-tokens
+     * @param timezone The timezone to set for the Dates object.
+     * @returns A new Dates object parsed from the string.
+     */
+    static fromFormat(text, format, timezone) {
+        const dateTime = DateTime
+            .fromFormat(text, format, { setZone: true })
+            .setZone(timezone, { keepLocalTime: true });
+        return new Dates({
+            calendar_date: dateTime.toFormat(CALENDAR_DATE_FORMAT),
+            iso: dateTime.toISO(),
+            js_date: dateTime.toJSDate(),
+            operational_date_int: this.prototype.getOperationalDateInt(dateTime.toISO()),
+            std_window: this.prototype.getStandardWindowInterval(dateTime.toISO()),
+            unix_timestamp: dateTime.toMillis(),
+        });
+    }
+    /**
+     * Creates a Dates object from an ISO 8601 date/time string.
+     * This method assumes the string has a timezone offset.
+     * @param isoText The ISO 8601 date/time string to parse.
+     * @returns A new Dates object created from the ISO string.
+     */
+    static fromISO(isoText) {
+        const dateTime = DateTime.fromISO(isoText, { setZone: true });
+        return new Dates({
+            calendar_date: dateTime.toFormat(CALENDAR_DATE_FORMAT),
+            iso: dateTime.toISO(),
+            js_date: dateTime.toJSDate(),
+            operational_date_int: this.prototype.getOperationalDateInt(dateTime.toISO()),
+            std_window: this.prototype.getStandardWindowInterval(dateTime.toISO()),
+            unix_timestamp: dateTime.toMillis(),
+        });
+    }
+    /**
+     * Creates a Dates object from a JavaScript Date object.
+     * @param date The JavaScript Date object to convert. It is assumed that the date is in UTC.
+     * @returns A new Dates object created from the JavaScript Date.
+     */
+    static fromJSDate(date) {
+        const dateTime = DateTime
+            .fromJSDate(date)
+            .setZone('utc', { keepLocalTime: false });
+        return new Dates({
+            calendar_date: dateTime.toFormat(CALENDAR_DATE_FORMAT),
+            iso: dateTime.toISO(),
+            js_date: dateTime.toJSDate(),
+            operational_date_int: this.prototype.getOperationalDateInt(dateTime.toISO()),
+            std_window: this.prototype.getStandardWindowInterval(dateTime.toISO()),
+            unix_timestamp: dateTime.toMillis(),
+        });
+    }
+    /**
+     * Creates a Dates object from an operational date integer.
+     * @param date The operational date integer in 'yyyyMMdd' format.
+     * @param timezone The timezone to set for the Dates object.
+     * @returns A new Dates object created from the operational date.
+     */
+    static fromOperationalDateInt(date, timezone) {
+        const dateTime = DateTime
+            .fromFormat(String(date), OPERATIONAL_DATE_FORMAT)
+            .setZone(timezone, { keepLocalTime: true })
+            .set({ hour: 4, millisecond: 0, minute: 0, second: 0 }); // Start of the operational date
+        return new Dates({
+            calendar_date: dateTime.toFormat(CALENDAR_DATE_FORMAT),
+            iso: dateTime.toISO(),
+            js_date: dateTime.toJSDate(),
+            operational_date_int: this.prototype.getOperationalDateInt(dateTime.toISO()),
+            std_window: this.prototype.getStandardWindowInterval(dateTime.toISO()),
+            unix_timestamp: dateTime.toMillis(),
+        });
+    }
+    /**
+     * Creates a Dates object from Unix epoch seconds
+     * @param seconds The number of seconds since Unix epoch
+     * @returns A new Dates object created from the seconds timestamp
+     */
+    static fromSeconds(seconds) {
+        const dateTime = DateTime
+            .fromSeconds(seconds)
+            .setZone('utc', { keepLocalTime: false });
+        return new Dates({
+            calendar_date: dateTime.toFormat(CALENDAR_DATE_FORMAT),
+            iso: dateTime.toISO(),
+            js_date: dateTime.toJSDate(),
+            operational_date_int: this.prototype.getOperationalDateInt(dateTime.toISO()),
+            std_window: this.prototype.getStandardWindowInterval(dateTime.toISO()),
+            unix_timestamp: dateTime.toMillis(),
+        });
+    }
+    /**
+     * Creates a Dates object from Unix epoch in milliseconds.
+     * @param millis The number of milliseconds since Unix epoch. Unix timestamp is always in UTC.
+     * @returns A new Dates object created from the milliseconds timestamp.
+     */
+    static fromUnixTimestamp(millis) {
+        const dateTime = DateTime
+            .fromMillis(millis)
+            .setZone('utc', { keepLocalTime: false });
+        return new Dates({
+            calendar_date: dateTime.toFormat(CALENDAR_DATE_FORMAT),
+            iso: dateTime.toISO(),
+            js_date: dateTime.toJSDate(),
+            operational_date_int: this.prototype.getOperationalDateInt(dateTime.toISO()),
+            std_window: this.prototype.getStandardWindowInterval(dateTime.toISO()),
+            unix_timestamp: dateTime.toMillis(),
+        });
+    }
+    /**
+     * Creates a Dates object with the current date and time.
+     * @param timezone The timezone to set for the Dates object.
+     * @returns A new Dates object with the current date and time in the specified timezone.
+     */
+    static now(timezone) {
+        const dateTime = DateTime
+            .now()
+            .setZone(timezone, { keepLocalTime: false });
+        return new Dates({
+            calendar_date: dateTime.toFormat(CALENDAR_DATE_FORMAT),
+            iso: dateTime.toISO(),
+            js_date: dateTime.toJSDate(),
+            operational_date_int: this.prototype.getOperationalDateInt(dateTime.toISO()),
+            std_window: this.prototype.getStandardWindowInterval(dateTime.toISO()),
+            unix_timestamp: dateTime.toMillis(),
+        });
+    }
+    /**
+     * Returns the difference between this date and another date.
+     * @param other The other Dates object to compare with
+     * @param unit The unit of time to return the difference in (defaults to 'day')
+     * @returns The difference as a number in the specified unit
+     */
+    diff(other, unit = 'day') {
+        if (!this.iso || !other.iso)
+            throw new Error('ISO date is not set.');
+        const thisDateTime = DateTime.fromISO(this.iso, { setZone: true });
+        const otherDateTime = DateTime.fromISO(other.iso, { setZone: true });
+        return thisDateTime.diff(otherDateTime, unit).as(unit);
+    }
+    /**
+     * Returns a new Dates object with the end of the specified unit.
+     * @param unit The unit to set the end of, e.g., 'day', 'month', 'year', etc.
+     * @returns A new Dates object with the end of the specified unit.
+     */
+    endOf(unit) {
+        if (!this.iso)
+            throw new Error('ISO date is not set.');
+        const dateTime = DateTime
+            .fromISO(this.iso, { setZone: true })
+            .endOf(unit);
+        return new Dates({
+            calendar_date: dateTime.toFormat(CALENDAR_DATE_FORMAT),
+            iso: dateTime.toISO(),
+            js_date: dateTime.toJSDate(),
+            operational_date_int: this.getOperationalDateInt(dateTime.toISO()),
+            std_window: this.getStandardWindowInterval(dateTime.toISO()),
+            unix_timestamp: dateTime.toMillis(),
+        });
+    }
+    /**
+     * Returns a new Dates object with the current date and time minus a duration.
+     * @param duration The duration to subtract
+     * @returns A new Dates object with the current date and time minus a duration
+     */
+    minus(duration) {
+        if (!this.iso)
+            throw new Error('ISO date is not set.');
+        const dateTime = DateTime
+            .fromISO(this.iso, { setZone: true })
+            .minus(duration);
+        return new Dates({
+            calendar_date: dateTime.toFormat(CALENDAR_DATE_FORMAT),
+            iso: dateTime.toISO(),
+            js_date: dateTime.toJSDate(),
+            operational_date_int: this.getOperationalDateInt(dateTime.toISO()),
+            std_window: this.getStandardWindowInterval(dateTime.toISO()),
+            unix_timestamp: dateTime.toMillis(),
+        });
+    }
+    /**
+     * Returns a new Dates object with the current date and time plus a duration
+     * @param duration The duration to add
+     * @returns A new Dates object with the current date and time plus a duration
+     */
+    plus(duration) {
+        if (!this.iso)
+            throw new Error('ISO date is not set.');
+        const dateTime = DateTime
+            .fromISO(this.iso, { setZone: true })
+            .plus(duration);
+        return new Dates({
+            calendar_date: dateTime.toFormat(CALENDAR_DATE_FORMAT),
+            iso: dateTime.toISO(),
+            js_date: dateTime.toJSDate(),
+            operational_date_int: this.getOperationalDateInt(dateTime.toISO()),
+            std_window: this.getStandardWindowInterval(dateTime.toISO()),
+            unix_timestamp: dateTime.toMillis(),
+        });
+    }
+    /**
+     * Sets the date and time for the Dates object.
+     * @param dateOrTime The date or time to set, can be an object with DateObjectUnits or a string in ISO format.
+     * @returns The Dates object
+     */
+    set(dateOrTime) {
+        if (!this.iso)
+            throw new Error('ISO date is not set.');
+        const dateTime = DateTime
+            .fromISO(this.iso, { setZone: true })
+            .set(dateOrTime);
+        return new Dates({
+            calendar_date: dateTime.toFormat(CALENDAR_DATE_FORMAT),
+            iso: dateTime.toISO(),
+            js_date: dateTime.toJSDate(),
+            operational_date_int: this.getOperationalDateInt(dateTime.toISO()),
+            std_window: this.getStandardWindowInterval(dateTime.toISO()),
+            unix_timestamp: dateTime.toMillis(),
+        });
+    }
+    /**
+     * Sets the timezone for the Dates object.
+     * @param timezone The timezone to set in the format of an IANA timezone.
+     * @param method The method to use for updating the timezone information.
+     *   - `offset_only` Updates only offset setting to the new timezone. The ISO string will show adjusted time components (hour, minutes, etc.) to their equivalent in the new timezone. The UTC value in milliseconds stays the same. The UNIX timestamp is the source of truth.
+     *   - `rebase_utc` Keeps the individual time components (hour, minutes, etc.) and updates the internal UTC value in milliseconds to reflect the change. The ISO string will show the same time components as before, but the UTC value in milliseconds will be adjusted to match the new timezone. The ISO string is the source of truth.
+     * @returns The Dates object
+     */
+    setZone(timezone, method) {
+        if (!this.iso)
+            throw new Error('ISO date is not set.');
+        const dateTime = DateTime
+            .fromISO(this.iso, { setZone: true })
+            .setZone(timezone, { keepLocalTime: method === 'rebase_utc' });
+        return new Dates({
+            calendar_date: dateTime.toFormat(CALENDAR_DATE_FORMAT),
+            iso: dateTime.toISO(),
+            js_date: dateTime.toJSDate(),
+            operational_date_int: this.getOperationalDateInt(dateTime.toISO()),
+            std_window: this.getStandardWindowInterval(dateTime.toISO()),
+            unix_timestamp: dateTime.toMillis(),
+        });
+    }
+    /**
+     * Returns a new Dates object with the start of the specified unit.
+     * @param unit The unit to set the start of, e.g., 'day', 'month', 'year', etc.
+     * @returns A new Dates object with the start of the specified unit.
+     */
+    startOf(unit) {
+        if (!this.iso)
+            throw new Error('ISO date is not set.');
+        const dateTime = DateTime
+            .fromISO(this.iso, { setZone: true })
+            .startOf(unit);
+        return new Dates({
+            calendar_date: dateTime.toFormat(CALENDAR_DATE_FORMAT),
+            iso: dateTime.toISO(),
+            js_date: dateTime.toJSDate(),
+            operational_date_int: this.getOperationalDateInt(dateTime.toISO()),
+            std_window: this.getStandardWindowInterval(dateTime.toISO()),
+            unix_timestamp: dateTime.toMillis(),
+        });
+    }
+    /**
+     * Returns the time remaining until a given unix_timestamp (in ms) from now,
+     * as an object with minutes, hours, and days (all as floats, not rounded).
+     * @param unixTimestamp The target timestamp in milliseconds
+     * @returns { minutes: number, hours: number, days: number }
+     */
+    timeUntil(unixTimestamp) {
+        // Calculate the difference in milliseconds
+        const now = Date.now();
+        const diffMs = unixTimestamp - now;
+        // Calculate the time remaining
+        const minutes = diffMs / (1000 * 60);
+        const hours = diffMs / (1000 * 60 * 60);
+        const days = diffMs / (1000 * 60 * 60 * 24);
+        // Return the time components
+        return { days, hours, minutes };
+    }
+    /**
+     * Returns the date as a string in the specified format.
+     * @param format The format string (see Luxon tokens documentation)
+     * @param opts Optional formatting options (e.g., { locale: 'pt' })
+     * @returns The date as a string in the specified format
+     */
+    toFormat(format, opts) {
+        if (!this.iso)
+            throw new Error('ISO date is not set.');
+        const dateTime = DateTime.fromISO(this.iso, { setZone: true });
+        return dateTime.setLocale(opts?.locale || 'pt').toFormat(format);
+    }
+    /**
+     * Returns the date as a string in the specified format.
+     * @param format The format string (see Luxon tokens documentation)
+     * @returns The date as a string in the specified format
+     */
+    toLocaleString(format, locale) {
+        if (!this.iso)
+            throw new Error('ISO date is not set.');
+        const dateTime = DateTime.fromISO(this.iso, { setZone: true });
+        if (locale)
+            dateTime.setLocale(locale);
+        const dateFormatConfig = DateFormatConfigMap[format];
+        if (!dateFormatConfig)
+            throw new Error(`Invalid date format: ${format}`);
+        return dateTime.toLocaleString(dateFormatConfig, { locale: locale });
+    }
+    /**
+     * Returns the operational date based on the provided timestamp and format.
+     * @param isoDate The ISO date string to calculate the operational date.
+     * @returns The operational date in the yyyyLLdd format.
+     */
+    getOperationalDateInt(isoDate) {
+        // Skip if the ISO date is not set
+        if (!isoDate)
+            throw new Error('ISO date is not set.');
+        // Get the date object
+        const dateObject = DateTime.fromISO(isoDate, { setZone: true });
+        // Check if the time is between 00:00 and 03:59.
+        // The operational date is between 04:00 and 03:59 of the following day.
+        let operationalDate;
+        if (dateObject.hour < 4) {
+            // If true, unwind the clock by 12 hours to
+            // return the previous day in the yyyyLLdd format
+            const previousDay = dateObject.minus({ hours: 12 });
+            operationalDate = previousDay.toFormat(OPERATIONAL_DATE_FORMAT);
+        }
+        else {
+            // Else, return the current day in the yyyyLLdd format
+            operationalDate = dateObject.toFormat(OPERATIONAL_DATE_FORMAT);
+        }
+        // Return the date as an operational date
+        return Number(operationalDate);
+    }
+    /**
+     * This function returns the start and end of the standard window interval for a given timestamp.
+     * The standard window interval is the period in which is possible to receive data for a given ride.
+     * Currently, the standard window starts 10 hours before and ends 10 hours after the scheduled ride start.
+     * @param isoDate The ISO date string to calculate the standard window interval.
+     * @returns An object containing the start and end of the standard window interval.
+     */
+    getStandardWindowInterval(isoDate) {
+        if (!isoDate)
+            throw new Error('ISO date is not set.');
+        const dateTime = DateTime.fromISO(isoDate, { setZone: true });
+        return {
+            end: dateTime.plus({ hours: Dates.standardWindowHours }).toMillis(),
+            start: dateTime.minus({ hours: Dates.standardWindowHours }).toMillis(),
+        };
+    }
+}

package/dist/helpers/dates-from-range.d.ts

@@ -0,0 +1,8 @@
+import { type OperationalDateInt } from '@tmlmobilidade/go-types-shared';
+/**
+ * Returns an array of individual dates from a given range of operational dates.
+ * @param start The start date of the range, in OperationalDate format.
+ * @param end The end date of the range, in OperationalDate format.
+ * @returns An array of OperationalDate objects representing each date in the range.
+ */
+export declare function getOperationalDatesFromRange(start: OperationalDateInt, end: OperationalDateInt): OperationalDateInt[];

package/dist/helpers/dates-from-range.js

@@ -0,0 +1,30 @@
+/* * */
+import { Dates } from '../dates.js';
+/**
+ * Returns an array of individual dates from a given range of operational dates.
+ * @param start The start date of the range, in OperationalDate format.
+ * @param end The end date of the range, in OperationalDate format.
+ * @returns An array of OperationalDate objects representing each date in the range.
+ */
+export function getOperationalDatesFromRange(start, end) {
+    //
+    //
+    // Validate the start and end dates
+    if (end < start) {
+        throw new Error(`End date "${end}" must be after start date "${start}"`);
+    }
+    //
+    // Parse the start and end dates to ensure they are in the correct format
+    const startDate = Dates.fromOperationalDateInt(start, 'Europe/Lisbon');
+    const endDate = Dates.fromOperationalDateInt(end, 'Europe/Lisbon');
+    //
+    // Create an array to hold the individual dates and iterate
+    // from the start date to the end date, adding each date to the array
+    const dates = [];
+    let current = startDate;
+    while (current.operational_date_int <= endDate.operational_date_int) {
+        dates.push(current.operational_date_int);
+        current = current.plus({ days: 1 });
+    }
+    return dates;
+}

package/dist/helpers/index.d.ts

@@ -0,0 +1,2 @@
+export * from './dates-from-range.js';
+export * from './split-time-intervals.js';

package/dist/helpers/index.js

@@ -0,0 +1,2 @@
+export * from './dates-from-range.js';
+export * from './split-time-intervals.js';

package/dist/helpers/split-time-intervals.d.ts

@@ -0,0 +1,16 @@
+import { type UnixTimestamp } from '@tmlmobilidade/go-types-shared';
+/**
+ * Splits a time interval into smaller intervals of a given duration.
+ * @param from The start timestamp of the interval.
+ * @param to The end timestamp of the interval.
+ * @param intervalHrs The duration of the intervals in hours.
+ * @returns An array of intervals.
+ */
+export declare function splitTimeIntervals(from: UnixTimestamp, to: UnixTimestamp, intervalHrs: number): {
+    end: number & {
+        __brand: "UnixTimestamp";
+    };
+    start: number & {
+        __brand: "UnixTimestamp";
+    };
+}[];

package/dist/helpers/split-time-intervals.js

@@ -0,0 +1,47 @@
+/* * */
+import { UnixTimestampSchema } from '@tmlmobilidade/go-types-shared';
+/**
+ * Splits a time interval into smaller intervals of a given duration.
+ * @param from The start timestamp of the interval.
+ * @param to The end timestamp of the interval.
+ * @param intervalHrs The duration of the intervals in hours.
+ * @returns An array of intervals.
+ */
+export function splitTimeIntervals(from, to, intervalHrs) {
+    //
+    //
+    // Validate the input timestamps
+    if (from > to)
+        throw new Error('The start timestamp must be before the end timestamp');
+    //
+    // Convert the interval duration in hours to milliseconds,
+    // and calculate how much time is left until the next clean interval step.
+    // This is so the intervals are allways of the full duration, starting at 00 hours.
+    const intervalMs = intervalHrs * 60 * 60 * 1000;
+    const remainder = to % intervalMs;
+    //
+    // Store the intervals in an array and
+    // initialize the end timestamp with the most recent timestamp.
+    const finalIntervals = [];
+    let endTimestamp = to;
+    //
+    // Handle the first, potentially shorter interval.
+    // If there is a remainder, create an interval with the remainder as the duration.
+    if (remainder > 0) {
+        const startTimestamp = UnixTimestampSchema.parse(Math.max(from, endTimestamp - remainder));
+        finalIntervals.push({ end: endTimestamp, start: startTimestamp });
+        endTimestamp = startTimestamp;
+    }
+    //
+    // Handle the regular intervals.
+    // If the end timestamp is greater than the start timestamp,
+    // create an interval with the duration of the interval.
+    while (endTimestamp > from) {
+        const startTimestamp = UnixTimestampSchema.parse(Math.max(from, endTimestamp - intervalMs));
+        finalIntervals.push({ end: endTimestamp, start: startTimestamp });
+        endTimestamp = startTimestamp;
+    }
+    //
+    // Return the intervals in reverse order.
+    return finalIntervals.reverse();
+}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export * from './dates.js';
+export * from './helpers/index.js';

package/dist/index.js

@@ -0,0 +1,2 @@
+export * from './dates.js';
+export * from './helpers/index.js';

package/package.json

@@ -0,0 +1,49 @@
+{
+	"name": "@tmlmobilidade/go-utils-dates",
+	"version": "20260828.1636.54",
+	"author": {
+		"email": "iso@tmlmobilidade.pt",
+		"name": "TML-ISO"
+	},
+	"license": "AGPL-3.0-or-later",
+	"homepage": "https://go.tmlmobilidade.pt",
+	"bugs": {
+		"url": "https://github.com/tmlmobilidade/go/issues"
+	},
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/tmlmobilidade/go.git"
+	},
+	"keywords": [
+		"public transit",
+		"tml",
+		"transportes metropolitanos de lisboa",
+		"go"
+	],
+	"publishConfig": {
+		"access": "public"
+	},
+	"type": "module",
+	"files": [
+		"dist"
+	],
+	"main": "./dist/index.js",
+	"types": "./dist/index.d.ts",
+	"scripts": {
+		"build": "tsc && resolve-tspaths",
+		"lint": "eslint ./src/ && tsc --noEmit",
+		"lint:fix": "eslint ./src/ --fix",
+		"watch": "tsc-watch --onSuccess 'resolve-tspaths'"
+	},
+	"dependencies": {
+		"@tmlmobilidade/go-types-shared": "*",
+		"luxon": "3.7.2"
+	},
+	"devDependencies": {
+		"@tmlmobilidade/go-utils-tsconfig": "*",
+		"@types/node": "26.1.2",
+		"resolve-tspaths": "0.8.23",
+		"tsc-watch": "7.2.1",
+		"typescript": "6.0.3"
+	}
+}