@tmlmobilidade/dates 20260121.2332.6 → 20260128.2248.28

package/dist/calendar.d.ts

@@ -0,0 +1,81 @@
+import { Dates } from './dates.js';
+import { IsoWeekday } from '@tmlmobilidade/types';
+import { TimezoneIdentified } from './types.js';
+export declare const DEFAULT_CAL_TZ = "Europe/Lisbon";
+export type CalendarKey = `${number}-${number}-${number}`;
+export interface CalendarDay {
+    calendarKey: CalendarKey;
+    date: Dates;
+    dayOfMonth: number;
+    dayOfWeek: number;
+    isCurrentMonth: boolean;
+    isToday: boolean;
+    isWeekend: boolean;
+}
+export interface MonthGrid {
+    days: CalendarDay[];
+    month: number;
+    monthName: string;
+    weeks: CalendarDay[][];
+    year: number;
+}
+/**
+ * Canonical calendar day key (civil date) in a timezone.
+ * This is the ONE key you should use for calendar UI, selections, holidays, event mapping, etc.
+ */
+export declare function calendarKey(d: Dates, tz?: TimezoneIdentified): CalendarKey;
+/**
+ * CalendarKey -> Dates at noon Lisbon (stable for civil-day iteration)
+ */
+export declare function datesFromCalendarKey(key: CalendarKey): Dates;
+/**
+ * Extracts the month and year from a given calendar key string.
+ *
+ * @param key - The calendar key in the format 'YYYY-MM' or similar.
+ * @returns An object containing the numeric `month` and `year` extracted from the key.
+ */
+export declare function monthYearFromKey(key: CalendarKey): {
+    month: number;
+    year: number;
+};
+/**
+ * Parse a string/Date/Dates into a calendar key.
+ * - "YYYY-MM-DD" is parsed at 12:00 in tz (avoids DST edge cases + avoids operational cutoff semantics)
+ * - ISO strings keep their offset and are then represented in tz
+ */
+export declare function parseCalendarKey(input: Date | Dates | string, tz?: TimezoneIdentified): CalendarKey;
+/**
+ * Convert CalendarKey "YYYY-MM-DD" to "YYYYMMDD" (useful for comparing with period.dates that are stored as yyyyMMdd,
+ * but semantically represent civil days).
+ */
+export declare function keyToYYYYMMDD(key: CalendarKey): string;
+/**
+ * Convert "YYYYMMDD" to CalendarKey "YYYY-MM-DD".
+ */
+export declare function yyyymmddToKey(yyyymmdd: string): CalendarKey;
+/**
+ * ISO weekday (1..7 Mon..Sun) for a calendar key or Dates (civil day).
+ */
+export declare function calendarWeekday(input: CalendarKey | Dates, tz?: TimezoneIdentified): IsoWeekday;
+export declare function isWeekend(input: CalendarKey | Dates, tz?: TimezoneIdentified): boolean;
+/**
+ * Iterate calendar day keys from start to end inclusive (civil days).
+ */
+export declare function eachCalendarDay(start: CalendarKey, end: CalendarKey, tz?: TimezoneIdentified): CalendarKey[];
+/**
+ * Inclusive range check for civil calendar days.
+ */
+export declare function isKeyInRange(key: CalendarKey, start: CalendarKey, end?: CalendarKey): boolean;
+/**
+ * Generates a calendar grid for a specific month, including overflow days from previous and next months.
+ * IMPORTANT: This grid is based on civil days, not operational days.
+ */
+export declare function generateMonthGrid(year: number, month: number, fixedWeeks?: boolean, tz?: TimezoneIdentified): MonthGrid;
+export declare function getNextMonth(year: number, month: number): {
+    month: number;
+    year: number;
+};
+export declare function getPreviousMonth(year: number, month: number): {
+    month: number;
+    year: number;
+};

package/dist/calendar.js

@@ -0,0 +1,169 @@
+/* * */
+import { Dates } from './dates.js';
+/* * */
+export const DEFAULT_CAL_TZ = 'Europe/Lisbon';
+/* * */
+/* Calendar day helpers (civil days, not operational days) */
+/* * */
+/**
+ * Canonical calendar day key (civil date) in a timezone.
+ * This is the ONE key you should use for calendar UI, selections, holidays, event mapping, etc.
+ */
+export function calendarKey(d, tz = DEFAULT_CAL_TZ) {
+    return d.setZone(tz, 'offset_only').toFormat('yyyy-MM-dd');
+}
+/**
+ * CalendarKey -> Dates at noon Lisbon (stable for civil-day iteration)
+ */
+export function datesFromCalendarKey(key) {
+    return Dates.fromFormat(`${key} 12:00`, 'yyyy-MM-dd HH:mm', DEFAULT_CAL_TZ);
+}
+/**
+ * Extracts the month and year from a given calendar key string.
+ *
+ * @param key - The calendar key in the format 'YYYY-MM' or similar.
+ * @returns An object containing the numeric `month` and `year` extracted from the key.
+ */
+export function monthYearFromKey(key) {
+    return { month: Number(key.slice(5, 7)), year: Number(key.slice(0, 4)) };
+}
+/**
+ * Parse a string/Date/Dates into a calendar key.
+ * - "YYYY-MM-DD" is parsed at 12:00 in tz (avoids DST edge cases + avoids operational cutoff semantics)
+ * - ISO strings keep their offset and are then represented in tz
+ */
+export function parseCalendarKey(input, tz = DEFAULT_CAL_TZ) {
+    if (input instanceof Dates)
+        return calendarKey(input, tz);
+    if (input instanceof Date) {
+        return calendarKey(Dates.fromJSDate(input).setZone(tz, 'offset_only'), tz);
+    }
+    if (/^\d{4}-\d{2}-\d{2}$/.test(input)) {
+        return calendarKey(Dates.fromFormat(`${input} 12:00`, 'yyyy-MM-dd HH:mm', tz), tz);
+    }
+    return calendarKey(Dates.fromISO(input).setZone(tz, 'offset_only'), tz);
+}
+/**
+ * Convert CalendarKey "YYYY-MM-DD" to "YYYYMMDD" (useful for comparing with period.dates that are stored as yyyyMMdd,
+ * but semantically represent civil days).
+ */
+export function keyToYYYYMMDD(key) {
+    return key.replace(/-/g, '');
+}
+/**
+ * Convert "YYYYMMDD" to CalendarKey "YYYY-MM-DD".
+ */
+export function yyyymmddToKey(yyyymmdd) {
+    return `${yyyymmdd.slice(0, 4)}-${yyyymmdd.slice(4, 6)}-${yyyymmdd.slice(6, 8)}`;
+}
+/**
+ * ISO weekday (1..7 Mon..Sun) for a calendar key or Dates (civil day).
+ */
+export function calendarWeekday(input, tz = DEFAULT_CAL_TZ) {
+    const key = input instanceof Dates ? calendarKey(input, tz) : input;
+    const d = Dates.fromFormat(`${key} 12:00`, 'yyyy-MM-dd HH:mm', tz);
+    return Number(d.toFormat('E'));
+}
+export function isWeekend(input, tz = DEFAULT_CAL_TZ) {
+    const wd = calendarWeekday(input, tz);
+    return wd === 6 || wd === 7;
+}
+/**
+ * Iterate calendar day keys from start to end inclusive (civil days).
+ */
+export function eachCalendarDay(start, end, tz = DEFAULT_CAL_TZ) {
+    const out = [];
+    let current = Dates.fromFormat(`${start} 12:00`, 'yyyy-MM-dd HH:mm', tz);
+    const last = Dates.fromFormat(`${end} 12:00`, 'yyyy-MM-dd HH:mm', tz);
+    while (current.unix_timestamp <= last.unix_timestamp) {
+        out.push(calendarKey(current, tz));
+        current = current.plus({ days: 1 });
+    }
+    return out;
+}
+/**
+ * Inclusive range check for civil calendar days.
+ */
+export function isKeyInRange(key, start, end) {
+    if (!end)
+        return key === start;
+    return key >= start && key <= end;
+}
+/* * */
+/* Month grid generation (Monday-first, civil calendar) */
+/* * */
+/**
+ * Generates a calendar grid for a specific month, including overflow days from previous and next months.
+ * IMPORTANT: This grid is based on civil days, not operational days.
+ */
+export function generateMonthGrid(year, month, fixedWeeks = false, tz = DEFAULT_CAL_TZ) {
+    // Create the first day of the target month at noon in tz to avoid DST edge cases
+    const firstDayOfMonth = Dates.fromFormat(`${year}-${String(month).padStart(2, '0')}-01 12:00`, 'yyyy-MM-dd HH:mm', tz);
+    const lastDayOfMonth = firstDayOfMonth.endOf('month');
+    // Today (civil)
+    const todayKey = calendarKey(Dates.now(tz), tz);
+    // ISO weekday for first day (1=Mon..7=Sun)
+    const firstDayOfWeekNumber = Number(firstDayOfMonth.toFormat('c'));
+    const daysFromPrevMonth = firstDayOfWeekNumber - 1; // Monday-first
+    // Trailing days
+    const lastDayOfWeekNumber = Number(lastDayOfMonth.toFormat('c')); // 1..7
+    const naturalDaysFromNextMonth = (7 - lastDayOfWeekNumber) % 7; // Sunday -> 0
+    const days = [];
+    const pushDay = (date, isCurrentMonth) => {
+        const key = calendarKey(date, tz);
+        const dow = Number(date.toFormat('c')); // 1..7
+        days.push({
+            calendarKey: key,
+            date,
+            dayOfMonth: Number(date.toFormat('d')),
+            dayOfWeek: dow,
+            isCurrentMonth,
+            isToday: key === todayKey,
+            isWeekend: dow === 6 || dow === 7,
+        });
+    };
+    // Previous month overflow
+    if (daysFromPrevMonth > 0) {
+        const prevMonthLastDay = firstDayOfMonth.minus({ days: 1 });
+        const prevMonthStart = prevMonthLastDay.minus({ days: daysFromPrevMonth - 1 });
+        for (let i = 0; i < daysFromPrevMonth; i++) {
+            pushDay(prevMonthStart.plus({ days: i }), false);
+        }
+    }
+    // Current month
+    const daysInMonth = Number(lastDayOfMonth.toFormat('d'));
+    for (let d = 1; d <= daysInMonth; d++) {
+        pushDay(firstDayOfMonth.plus({ days: d - 1 }), true);
+    }
+    // Next month overflow
+    const daysFromNextMonth = fixedWeeks ? 42 - days.length : naturalDaysFromNextMonth;
+    for (let i = 1; i <= daysFromNextMonth; i++) {
+        pushDay(lastDayOfMonth.plus({ days: i }), false);
+    }
+    // Weeks (rows)
+    const weeks = [];
+    for (let i = 0; i < days.length; i += 7) {
+        weeks.push(days.slice(i, i + 7));
+    }
+    const monthName = firstDayOfMonth.toFormat('MMMM');
+    return {
+        days,
+        month,
+        monthName: monthName.charAt(0).toUpperCase() + monthName.slice(1),
+        weeks,
+        year,
+    };
+}
+/* * */
+/* Navigation helpers */
+/* * */
+export function getNextMonth(year, month) {
+    if (month === 12)
+        return { month: 1, year: year + 1 };
+    return { month: month + 1, year };
+}
+export function getPreviousMonth(year, month) {
+    if (month === 1)
+        return { month: 12, year: year - 1 };
+    return { month: month - 1, year };
+}

package/dist/dates.d.ts

@@ -155,9 +155,12 @@ export declare class Dates {
     /**
      * 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): string;
+    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)

package/dist/dates.js

@@ -327,13 +327,14 @@ export class Dates {
     /**
      * 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) {
+    toFormat(format, opts) {
         if (!this.iso)
             throw new Error('ISO date is not set.');
         const dateTime = DateTime.fromISO(this.iso, { setZone: true });
-        return dateTime.toFormat(format);
+        return dateTime.setLocale(opts?.locale || 'pt').toFormat(format);
     }
     /**
      * Returns the date as a string in the specified format.

package/dist/index.d.ts

@@ -1,4 +1,6 @@
+export * from './calendar.js';
 export * from './dates.js';
 export * from './format.js';
+export * from './period-utils.js';
 export * from './types.js';
 export * from './utils.js';

package/dist/index.js

@@ -1,4 +1,6 @@
+export * from './calendar.js';
 export * from './dates.js';
 export * from './format.js';
+export * from './period-utils.js';
 export * from './types.js';
 export * from './utils.js';

package/dist/period-utils.d.ts

@@ -0,0 +1,41 @@
+import { OperationalDate } from '@tmlmobilidade/types';
+import { CalendarKey } from './calendar.js';
+/**
+ * Converts a date range into an array of CalendarKey strings (YYYY-MM-DD).
+ * Returned in sorted order (ascending).
+ *
+ * @param start - Start day (inclusive) as CalendarKey
+ * @param end - End day (inclusive) as CalendarKey
+ */
+export declare function convertRangeToKeysArray(start: CalendarKey, end: CalendarKey): CalendarKey[];
+/**
+ * Merges two date arrays and returns a sorted, unique array.
+ * Duplicates are automatically removed.
+ *
+ * @param existing - Existing array of operational_date strings
+ * @param newDates - New array of operational_date strings to merge
+ * @returns Sorted array of unique operational_date strings
+ *
+ */
+export declare function mergeDateArrays(existing: OperationalDate[], newDates: OperationalDate[]): OperationalDate[];
+/**
+ * Removes specified dates from an array.
+ * Returns a sorted array with the dates removed.
+ *
+ * @param array - Original array of operational_date strings
+ * @param datesToRemove - Array of operational_date strings to remove
+ * @returns Sorted array with specified dates removed
+ *
+ */
+export declare function removeDatesFromArray(array: OperationalDate[], datesToRemove: OperationalDate[]): OperationalDate[];
+/**
+ * Finds common dates between two arrays (intersection).
+ * Returns a sorted array of dates that exist in both arrays.
+ *
+ * @param array1 - First array of operational_date strings
+ * @param array2 - Second array of operational_date strings
+ * @returns Sorted array of dates found in both arrays
+ *
+ */
+export declare function findCommonDates(array1: OperationalDate[], array2: OperationalDate[]): OperationalDate[];
+export declare function convertKeysToOperationalDates(keys: CalendarKey[]): OperationalDate[];

package/dist/period-utils.js

@@ -0,0 +1,64 @@
+/* * */
+import { calendarKey, datesFromCalendarKey, keyToYYYYMMDD } from './calendar.js';
+/* * */
+/**
+ * Converts a date range into an array of CalendarKey strings (YYYY-MM-DD).
+ * Returned in sorted order (ascending).
+ *
+ * @param start - Start day (inclusive) as CalendarKey
+ * @param end - End day (inclusive) as CalendarKey
+ */
+export function convertRangeToKeysArray(start, end) {
+    const keys = [];
+    const from = start < end ? start : end;
+    const to = start < end ? end : start;
+    let current = datesFromCalendarKey(from);
+    const endDate = datesFromCalendarKey(to);
+    while (current.unix_timestamp <= endDate.unix_timestamp) {
+        keys.push(calendarKey(current));
+        current = current.plus({ days: 1 });
+    }
+    return keys;
+}
+/**
+ * Merges two date arrays and returns a sorted, unique array.
+ * Duplicates are automatically removed.
+ *
+ * @param existing - Existing array of operational_date strings
+ * @param newDates - New array of operational_date strings to merge
+ * @returns Sorted array of unique operational_date strings
+ *
+ */
+export function mergeDateArrays(existing, newDates) {
+    const uniqueDates = new Set([...existing, ...newDates]);
+    return Array.from(uniqueDates).sort();
+}
+/**
+ * Removes specified dates from an array.
+ * Returns a sorted array with the dates removed.
+ *
+ * @param array - Original array of operational_date strings
+ * @param datesToRemove - Array of operational_date strings to remove
+ * @returns Sorted array with specified dates removed
+ *
+ */
+export function removeDatesFromArray(array, datesToRemove) {
+    const removeSet = new Set(datesToRemove);
+    return array.filter(date => !removeSet.has(date)).sort();
+}
+/**
+ * Finds common dates between two arrays (intersection).
+ * Returns a sorted array of dates that exist in both arrays.
+ *
+ * @param array1 - First array of operational_date strings
+ * @param array2 - Second array of operational_date strings
+ * @returns Sorted array of dates found in both arrays
+ *
+ */
+export function findCommonDates(array1, array2) {
+    const set1 = new Set(array1);
+    return array2.filter(date => set1.has(date)).sort();
+}
+export function convertKeysToOperationalDates(keys) {
+    return keys.map(k => keyToYYYYMMDD(k));
+}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@tmlmobilidade/dates",
-	"version": "20260121.2332.6",
+	"version": "20260128.2248.28",
 	"author": {
 		"email": "iso@tmlmobilidade.pt",
 		"name": "TML-ISO"
@@ -42,7 +42,7 @@
 	"devDependencies": {
 		"@tmlmobilidade/tsconfig": "*",
 		"@tmlmobilidade/types": "*",
-		"@types/node": "25.0.3",
+		"@types/node": "25.1.0",
 		"resolve-tspaths": "0.8.23",
 		"tsc-watch": "7.2.0",
 		"typescript": "5.9.3"