@tmlmobilidade/dates 20260302.1453.8 → 20260305.1602.46

package/dist/calendar/index.d.ts

@@ -0,0 +1,4 @@
+export * from './parameters/index.js';
+export * from './periods/index.js';
+export * from './rules/index.js';
+export * from './utils/index.js';

package/dist/calendar/index.js

@@ -0,0 +1,4 @@
+export * from './parameters/index.js';
+export * from './periods/index.js';
+export * from './rules/index.js';
+export * from './utils/index.js';

package/dist/calendar/parameters/index.d.ts

@@ -0,0 +1 @@
+export * from './stops-parameters.js';

package/dist/calendar/parameters/index.js

@@ -0,0 +1 @@
+export * from './stops-parameters.js';

package/dist/calendar/parameters/stops-parameters.d.ts

@@ -0,0 +1,28 @@
+import { type Path, type StopsParameter } from '@tmlmobilidade/types';
+export type MergedPathItem = Path & {
+    avg_speed?: null | number;
+    dwell_time?: null | number;
+};
+export interface SegmentTravelTimes {
+    segmentTravelSeconds: {
+        formatted: Array<string>;
+        raw: Array<null | number>;
+    };
+    stopDwellSeconds: {
+        formatted: Array<string>;
+        raw: Array<null | number>;
+    };
+    totalTripSecondsWithoutStops: {
+        formatted: string;
+        raw: number;
+    };
+    totalTripSecondsWithStops: {
+        formatted: string;
+        raw: number;
+    };
+}
+export declare function toNumberOrNull(value: unknown): null | number;
+export declare function computeSegmentSeconds(distanceMeters: null | number, speedKmh: null | number): number;
+export declare function formatSecondsToTime(timeInSeconds: null | number): string;
+export declare function computeSegmentTravelTimes(mergedPath: MergedPathItem[]): SegmentTravelTimes;
+export declare function getMergedPath(basePath: Path[], newPath: StopsParameter['path']): MergedPathItem[];

package/dist/calendar/parameters/stops-parameters.js

@@ -0,0 +1,80 @@
+/* * */
+/* * */
+export function toNumberOrNull(value) {
+    if (value === null || value === undefined)
+        return null;
+    if (typeof value === 'number')
+        return Number.isFinite(value) ? value : null;
+    if (typeof value === 'string') {
+        const v = Number(value.replace(',', '.'));
+        return Number.isFinite(v) ? v : null;
+    }
+    return null;
+}
+export function computeSegmentSeconds(distanceMeters, speedKmh) {
+    if (!distanceMeters || !speedKmh)
+        return 0;
+    // km/h -> m/s
+    const speedMs = speedKmh * 1000 / 3600;
+    return Math.round(distanceMeters / speedMs) || 0;
+}
+export function formatSecondsToTime(timeInSeconds) {
+    if (timeInSeconds === null || timeInSeconds === undefined)
+        return '•••';
+    if (timeInSeconds < 60) {
+        return timeInSeconds + ' seg';
+    }
+    if (timeInSeconds < 3600) {
+        const minutes = Math.floor(timeInSeconds / 60);
+        const seconds = timeInSeconds % 60;
+        return `${minutes} min ${seconds} seg`;
+    }
+    const hours = Math.floor(timeInSeconds / 3600);
+    const minutes = Math.floor((timeInSeconds % 3600) / 60);
+    const seconds = timeInSeconds % 60;
+    return `${hours} h ${minutes} min ${seconds} seg`;
+}
+export function computeSegmentTravelTimes(mergedPath) {
+    const segmentTravelSeconds = [];
+    const stopDwellSeconds = [];
+    for (let i = 0; i < mergedPath.length; i++) {
+        const row = mergedPath[i];
+        // Dwell applies at the stop itself
+        const dwell = toNumberOrNull(row.dwell_time);
+        stopDwellSeconds.push(dwell && dwell > 0 ? Math.round(dwell) : null);
+        // Segment travel time applies from previous stop -> current stop
+        if (i === 0) {
+            segmentTravelSeconds.push(null);
+            continue;
+        }
+        const distanceMeters = toNumberOrNull(row.distance_delta);
+        const speedKmh = toNumberOrNull(row.avg_speed);
+        segmentTravelSeconds.push(computeSegmentSeconds(distanceMeters, speedKmh));
+    }
+    const totalTripSecondsWithoutStops = segmentTravelSeconds
+        .filter((v) => typeof v === 'number')
+        .reduce((a, b) => a + b, 0);
+    const totalStopSeconds = stopDwellSeconds
+        .filter((v) => typeof v === 'number')
+        .reduce((a, b) => a + b, 0);
+    const totalTripSecondsWithStops = totalTripSecondsWithoutStops + totalStopSeconds;
+    return {
+        segmentTravelSeconds: { formatted: segmentTravelSeconds.map(s => formatSecondsToTime(s)), raw: segmentTravelSeconds },
+        stopDwellSeconds: { formatted: stopDwellSeconds.map(s => formatSecondsToTime(s)), raw: stopDwellSeconds },
+        totalTripSecondsWithoutStops: { formatted: formatSecondsToTime(totalTripSecondsWithoutStops), raw: totalTripSecondsWithoutStops },
+        totalTripSecondsWithStops: { formatted: formatSecondsToTime(totalTripSecondsWithStops), raw: totalTripSecondsWithStops },
+    };
+}
+export function getMergedPath(basePath, newPath) {
+    const editedByStopId = new Map((newPath || [])
+        .filter(p => p?.stop_id)
+        .map(p => [p.stop_id, p]));
+    return basePath.map((baseItem) => {
+        const edit = editedByStopId.get(baseItem.stop_id);
+        return {
+            ...baseItem,
+            avg_speed: edit?.avg_speed,
+            dwell_time: edit?.dwell_time,
+        };
+    });
+}

package/dist/{period-utils.d.ts → calendar/periods/index.d.ts}

@@ -1,5 +1,5 @@
+import { CalendarKey } from '../utils/index.js';
 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).

package/dist/{period-utils.js → calendar/periods/index.js}

@@ -1,5 +1,5 @@
 /* * */
-import { calendarKey, datesFromCalendarKey, keyToYYYYMMDD } from './calendar.js';
+import { calendarKey, datesFromCalendarKey, keyToYYYYMMDD } from '../utils/index.js';
 /* * */
 /**
  * Converts a date range into an array of CalendarKey strings (YYYY-MM-DD).

package/dist/calendar/rules/calculation/collectors.d.ts

@@ -0,0 +1,47 @@
+import type { DayContext } from './types.js';
+import { EventReplacementRule, ManualRule } from '@tmlmobilidade/types';
+/**
+ * Collects time points from manual INCLUDE rules that match a given day context.
+ *
+ * This is the first phase of rule application for normal (non-replacement) days.
+ * Finds all manual rules with operating_mode='include' that match both the weekday
+ * and period ID, then aggregates their time points.
+ *
+ * @param manualRules - Array of all manual rules to check
+ * @param ctx - The day context (weekday + period) to match against
+ * @returns Object containing the applied rule IDs and the collected time points
+ *
+ * @example
+ * ```ts
+ * const result = collectManualIncludes(rules, { weekday: 1, yearPeriodId: 'school' });
+ * // result = { appliedRuleIds: ['rule1', 'rule2'], timepoints: Set(['08:00', '09:00']) }
+ * ```
+ */
+export declare function collectManualIncludes(manualRules: ManualRule[], ctx: DayContext): {
+    appliedRuleIds: string[];
+    timepoints: Set<string>;
+};
+/**
+ * Collects time points from manual INCLUDE rules that intersect with a replacement rule.
+ *
+ * This is the first phase of rule application for days controlled by an event replacement.
+ * Uses intersection-based matching: if a manual rule matches ANY of the weekdays/periods
+ * targeted by the replacement, its time points are included.
+ *
+ * The replacement rule itself is always marked as applied (if it has an ID).
+ *
+ * @param replacement - The event replacement rule controlling this date
+ * @param manualRules - Array of all manual rules to check for intersection
+ * @returns Object containing the applied rule IDs (including replacement) and collected time points
+ *
+ * @example
+ * ```ts
+ * const replacement = { weekdays: [1], year_period_ids: ['school'], _id: 'event1' };
+ * const result = collectReplacementManualIncludes(replacement, manualRules);
+ * // result.appliedRuleIds will always include 'event1'
+ * ```
+ */
+export declare function collectReplacementManualIncludes(replacement: EventReplacementRule, manualRules: ManualRule[]): {
+    appliedRuleIds: string[];
+    timepoints: Set<string>;
+};

package/dist/calendar/rules/calculation/collectors.js

@@ -0,0 +1,70 @@
+import { manualRuleMatchesContext, manualRuleMatchesReplacement } from './matchers.js';
+/**
+ * Collects time points from manual INCLUDE rules that match a given day context.
+ *
+ * This is the first phase of rule application for normal (non-replacement) days.
+ * Finds all manual rules with operating_mode='include' that match both the weekday
+ * and period ID, then aggregates their time points.
+ *
+ * @param manualRules - Array of all manual rules to check
+ * @param ctx - The day context (weekday + period) to match against
+ * @returns Object containing the applied rule IDs and the collected time points
+ *
+ * @example
+ * ```ts
+ * const result = collectManualIncludes(rules, { weekday: 1, yearPeriodId: 'school' });
+ * // result = { appliedRuleIds: ['rule1', 'rule2'], timepoints: Set(['08:00', '09:00']) }
+ * ```
+ */
+export function collectManualIncludes(manualRules, ctx) {
+    const timepoints = new Set();
+    const appliedRuleIds = [];
+    for (const r of manualRules) {
+        if (r.operating_mode !== 'include')
+            continue;
+        if (!manualRuleMatchesContext(r, ctx))
+            continue;
+        appliedRuleIds.push(r._id);
+        for (const tp of r.timepoints ?? [])
+            timepoints.add(tp);
+    }
+    return { appliedRuleIds, timepoints };
+}
+/**
+ * Collects time points from manual INCLUDE rules that intersect with a replacement rule.
+ *
+ * This is the first phase of rule application for days controlled by an event replacement.
+ * Uses intersection-based matching: if a manual rule matches ANY of the weekdays/periods
+ * targeted by the replacement, its time points are included.
+ *
+ * The replacement rule itself is always marked as applied (if it has an ID).
+ *
+ * @param replacement - The event replacement rule controlling this date
+ * @param manualRules - Array of all manual rules to check for intersection
+ * @returns Object containing the applied rule IDs (including replacement) and collected time points
+ *
+ * @example
+ * ```ts
+ * const replacement = { weekdays: [1], year_period_ids: ['school'], _id: 'event1' };
+ * const result = collectReplacementManualIncludes(replacement, manualRules);
+ * // result.appliedRuleIds will always include 'event1'
+ * ```
+ */
+export function collectReplacementManualIncludes(replacement, manualRules) {
+    const timepoints = new Set();
+    const appliedRuleIds = [];
+    // Always mark replacement as applied if it has an id (optional in schema)
+    if (replacement._id)
+        appliedRuleIds.push(replacement._id);
+    for (const r of manualRules) {
+        if (r.operating_mode !== 'include')
+            continue;
+        if (!manualRuleMatchesReplacement(r, replacement))
+            continue;
+        if (r._id)
+            appliedRuleIds.push(r._id);
+        for (const tp of r.timepoints)
+            timepoints.add(tp);
+    }
+    return { appliedRuleIds, timepoints };
+}

package/dist/calendar/rules/calculation/filters.d.ts

@@ -0,0 +1,66 @@
+import type { DayContext } from './types.js';
+import { type EventReplacementRule, type ManualRule, type OperationalDate, type ScheduleRule } from '@tmlmobilidade/types';
+/**
+ * Removes time points based on manual EXCLUDE rules that match a given day context.
+ *
+ * This is the second phase of rule application for normal days. Finds all manual rules
+ * with operating_mode='exclude' that match the weekday and period, then removes their
+ * time points from the collected set.
+ *
+ * Mutates the timepoints Set and appliedRuleIds array in place.
+ *
+ * @param timepoints - Set of time points to filter (mutated in place)
+ * @param appliedRuleIds - Array to track which rules were applied (mutated in place)
+ * @param manualRules - Array of all manual rules to check
+ * @param ctx - The day context (weekday + period) to match against
+ *
+ * @example
+ * ```ts
+ * const timepoints = new Set(['08:00', '09:00', '10:00']);
+ * const appliedRuleIds = ['rule1'];
+ * applyManualExcludes(timepoints, appliedRuleIds, rules, { weekday: 1, yearPeriodId: 'school' });
+ * // timepoints might now be Set(['08:00', '10:00']) if a rule excluded '09:00'
+ * ```
+ */
+export declare function applyManualExcludes(timepoints: Set<string>, appliedRuleIds: string[], manualRules: ManualRule[], ctx: DayContext): void;
+/**
+ * Removes time points based on manual EXCLUDE rules that intersect with a replacement rule.
+ *
+ * This is the second phase of rule application for replacement days. Uses intersection
+ * matching: if an exclude rule matches ANY of the weekdays/periods targeted by the
+ * replacement, its time points are removed.
+ *
+ * Mutates the timepoints Set and appliedRuleIds array in place.
+ *
+ * @param timepoints - Set of time points to filter (mutated in place)
+ * @param appliedRuleIds - Array to track which rules were applied (mutated in place)
+ * @param replacement - The event replacement rule controlling this date
+ * @param manualRules - Array of all manual rules to check for intersection
+ */
+export declare function applyReplacementManualExcludes(timepoints: Set<string>, appliedRuleIds: string[], replacement: EventReplacementRule, manualRules: ManualRule[]): void;
+/**
+ * Applies event restriction rules to remove time points for a specific date.
+ *
+ * Event restrictions can work in three modes:
+ * 1. all_day: Removes all time points (complete service suspension)
+ * 2. explicit timepoints: Removes only the specified times (UI-generated)
+ * 3. time window: Removes times within start_time to end_time range (supports midnight crossing)
+ *
+ * This is the final filtering phase after manual includes/excludes have been processed.
+ *
+ * Mutates the timepoints Set and appliedRuleIds array in place.
+ *
+ * @param date - The operational date to check restrictions for
+ * @param timepoints - Set of time points to filter (mutated in place)
+ * @param appliedRuleIds - Array to track which rules were applied (mutated in place)
+ * @param rules - Array of all schedule rules (filters for event_restriction type)
+ *
+ * @example
+ * ```ts
+ * const timepoints = new Set(['08:00', '09:00', '10:00']);
+ * const appliedRuleIds = [];
+ * applyEventRestrictions('2026-12-25', timepoints, appliedRuleIds, rules);
+ * // If there's an all_day restriction, timepoints is now Set()
+ * ```
+ */
+export declare function applyEventRestrictions(date: OperationalDate, timepoints: Set<string>, appliedRuleIds: string[], rules: ScheduleRule[]): void;

package/dist/calendar/rules/calculation/filters.js

@@ -0,0 +1,162 @@
+import { manualRuleMatchesContext, manualRuleMatchesReplacement } from './matchers.js';
+/**
+ * Removes time points based on manual EXCLUDE rules that match a given day context.
+ *
+ * This is the second phase of rule application for normal days. Finds all manual rules
+ * with operating_mode='exclude' that match the weekday and period, then removes their
+ * time points from the collected set.
+ *
+ * Mutates the timepoints Set and appliedRuleIds array in place.
+ *
+ * @param timepoints - Set of time points to filter (mutated in place)
+ * @param appliedRuleIds - Array to track which rules were applied (mutated in place)
+ * @param manualRules - Array of all manual rules to check
+ * @param ctx - The day context (weekday + period) to match against
+ *
+ * @example
+ * ```ts
+ * const timepoints = new Set(['08:00', '09:00', '10:00']);
+ * const appliedRuleIds = ['rule1'];
+ * applyManualExcludes(timepoints, appliedRuleIds, rules, { weekday: 1, yearPeriodId: 'school' });
+ * // timepoints might now be Set(['08:00', '10:00']) if a rule excluded '09:00'
+ * ```
+ */
+export function applyManualExcludes(timepoints, appliedRuleIds, manualRules, ctx) {
+    for (const r of manualRules) {
+        if (r.operating_mode !== 'exclude')
+            continue;
+        if (!manualRuleMatchesContext(r, ctx))
+            continue;
+        appliedRuleIds.push(r._id);
+        // If exclude rule has no timepoints, treat as "exclude nothing"
+        // (If you want "exclude whole day", add an explicit flag later.)
+        for (const tp of r.timepoints ?? [])
+            timepoints.delete(tp);
+    }
+}
+/**
+ * Removes time points based on manual EXCLUDE rules that intersect with a replacement rule.
+ *
+ * This is the second phase of rule application for replacement days. Uses intersection
+ * matching: if an exclude rule matches ANY of the weekdays/periods targeted by the
+ * replacement, its time points are removed.
+ *
+ * Mutates the timepoints Set and appliedRuleIds array in place.
+ *
+ * @param timepoints - Set of time points to filter (mutated in place)
+ * @param appliedRuleIds - Array to track which rules were applied (mutated in place)
+ * @param replacement - The event replacement rule controlling this date
+ * @param manualRules - Array of all manual rules to check for intersection
+ */
+export function applyReplacementManualExcludes(timepoints, appliedRuleIds, replacement, manualRules) {
+    for (const r of manualRules) {
+        if (r.operating_mode !== 'exclude')
+            continue;
+        if (!manualRuleMatchesReplacement(r, replacement))
+            continue;
+        if (r._id)
+            appliedRuleIds.push(r._id);
+        for (const tp of r.timepoints)
+            timepoints.delete(tp);
+    }
+}
+/**
+ * Converts HH:MM time string to total minutes since midnight.
+ * Helper function for time window calculations.
+ *
+ * @param hhmm - Time string in HH:MM format (validated by Zod)
+ * @returns Total minutes (e.g., "09:30" → 570)
+ */
+function hhmmToMinutes(hhmm) {
+    const [h, m] = hhmm.split(':');
+    return Number(h) * 60 + Number(m);
+}
+/**
+ * Removes all time points that fall within a specified time window.
+ *
+ * Handles midnight crossing: if end < start, the window wraps around midnight
+ * and removes times in [start, 24:00) ∪ [00:00, end).
+ *
+ * Window is inclusive of start, exclusive of end: [start, end)
+ *
+ * Mutates the timepoints Set in place.
+ *
+ * @param timepoints - Set of time points to filter (mutated in place)
+ * @param startHHMM - Window start time in HH:MM format
+ * @param endHHMM - Window end time in HH:MM format
+ *
+ * @example
+ * ```ts
+ * const times = new Set(['08:00', '12:00', '22:00', '01:00']);
+ * // Remove times between 22:00 and 02:00 (crosses midnight)
+ * removeTimePointsByWindow(times, '22:00', '02:00');
+ * // times is now Set(['08:00', '12:00'])
+ * ```
+ */
+function removeTimePointsByWindow(timepoints, startHHMM, endHHMM) {
+    const start = hhmmToMinutes(startHHMM);
+    const end = hhmmToMinutes(endHHMM);
+    const crossesMidnight = end < start;
+    for (const tp of Array.from(timepoints)) {
+        const t = hhmmToMinutes(tp);
+        const inWindow = crossesMidnight
+            ? (t >= start || t < end)
+            : (t >= start && t < end);
+        if (inWindow)
+            timepoints.delete(tp);
+    }
+}
+/**
+ * Applies event restriction rules to remove time points for a specific date.
+ *
+ * Event restrictions can work in three modes:
+ * 1. all_day: Removes all time points (complete service suspension)
+ * 2. explicit timepoints: Removes only the specified times (UI-generated)
+ * 3. time window: Removes times within start_time to end_time range (supports midnight crossing)
+ *
+ * This is the final filtering phase after manual includes/excludes have been processed.
+ *
+ * Mutates the timepoints Set and appliedRuleIds array in place.
+ *
+ * @param date - The operational date to check restrictions for
+ * @param timepoints - Set of time points to filter (mutated in place)
+ * @param appliedRuleIds - Array to track which rules were applied (mutated in place)
+ * @param rules - Array of all schedule rules (filters for event_restriction type)
+ *
+ * @example
+ * ```ts
+ * const timepoints = new Set(['08:00', '09:00', '10:00']);
+ * const appliedRuleIds = [];
+ * applyEventRestrictions('2026-12-25', timepoints, appliedRuleIds, rules);
+ * // If there's an all_day restriction, timepoints is now Set()
+ * ```
+ */
+export function applyEventRestrictions(date, timepoints, appliedRuleIds, rules) {
+    for (const r of rules) {
+        if (r.kind !== 'event_restriction')
+            continue;
+        if (!r.dates?.includes(date))
+            continue;
+        if (r._id)
+            appliedRuleIds.push(r._id);
+        // 1) all day kills everything
+        if (r?.all_day) {
+            timepoints.clear();
+            continue;
+        }
+        // 2) explicit timepoints removal (UI generated)
+        if (r.timepoints?.length) {
+            for (const tp of r.timepoints)
+                timepoints.delete(tp);
+            continue;
+        }
+        // 3) fallback: compute from window
+        // If start/end exist, remove anything within that time window.
+        // If somehow missing, do nothing.
+        const start = r?.start_time;
+        const end = r?.end_time;
+        if (start && end) {
+            removeTimePointsByWindow(timepoints, start, end);
+        }
+    }
+}

package/dist/calendar/rules/calculation/index.d.ts

@@ -0,0 +1,41 @@
+import type { RuleApplication } from './types.js';
+import type { Event, OperationalDate, ScheduleRule, YearPeriod } from '@tmlmobilidade/types';
+/**
+ * Calculates which time points are active for each date in a range, based on scheduling rules.
+ *
+ * This is the core scheduling algorithm that processes three types of rules:
+ * 1. Manual rules (include/exclude) - Define base schedules for weekday/period combinations
+ * 2. Event replacement rules - Override base schedules for specific dates
+ * 3. Event restriction rules - Remove specific time points or time windows from schedules
+ *
+ * Algorithm flow for each date:
+ * - Check for event replacement rule
+ *   - If found: Use intersection-based matching with manual rules
+ *   - Otherwise: Use context-based matching (weekday + period)
+ * - Collect INCLUDE time points
+ * - Apply EXCLUDE time points
+ * - Apply event restrictions (by date)
+ * - Return final time points and applied rule IDs
+ *
+ * @param rules - All scheduling rules to process (manual, replacement, restriction)
+ * @param dateRange - Array of operational dates to calculate schedules for
+ * @param periods - YearPeriod definitions (school term, summer, etc.) for context resolution
+ * @returns Map from CalendarKey to RuleApplication with active time points and metadata
+ *
+ * @example
+ * ```ts
+ * const rules = [...]; // Manual, replacement, and restriction rules
+ * const dates = ['2026-02-01', '2026-02-02', ...];
+ * const periods = [...]; // YearPeriod definitions
+ *
+ * const result = computeActiveTimePoints(rules, dates, periods);
+ * const feb1 = result.get(calendarKey(Dates.fromOperationalDate('2026-02-01')));
+ * // feb1 = {
+ * //   timepoints: ['08:00', '09:00', '10:00'],
+ * //   appliedRuleIds: ['rule1', 'rule2']
+ * // }
+ * ```
+ */
+export declare function computeActiveRules(date: OperationalDate, rules: ScheduleRule[], periods: YearPeriod[], options?: {
+    events?: Event[];
+}): RuleApplication;

package/dist/calendar/rules/calculation/index.js

@@ -0,0 +1,87 @@
+import { calendarKey, calendarWeekday } from '../../utils/index.js';
+import { Dates } from '../../../dates.js';
+import { findReplacementForDate, getActivePeriodId } from '../utils/date.js';
+import { collectManualIncludes, collectReplacementManualIncludes } from './collectors.js';
+import { applyEventRestrictions, applyManualExcludes, applyReplacementManualExcludes } from './filters.js';
+/* * */
+/**
+ * Calculates which time points are active for each date in a range, based on scheduling rules.
+ *
+ * This is the core scheduling algorithm that processes three types of rules:
+ * 1. Manual rules (include/exclude) - Define base schedules for weekday/period combinations
+ * 2. Event replacement rules - Override base schedules for specific dates
+ * 3. Event restriction rules - Remove specific time points or time windows from schedules
+ *
+ * Algorithm flow for each date:
+ * - Check for event replacement rule
+ *   - If found: Use intersection-based matching with manual rules
+ *   - Otherwise: Use context-based matching (weekday + period)
+ * - Collect INCLUDE time points
+ * - Apply EXCLUDE time points
+ * - Apply event restrictions (by date)
+ * - Return final time points and applied rule IDs
+ *
+ * @param rules - All scheduling rules to process (manual, replacement, restriction)
+ * @param dateRange - Array of operational dates to calculate schedules for
+ * @param periods - YearPeriod definitions (school term, summer, etc.) for context resolution
+ * @returns Map from CalendarKey to RuleApplication with active time points and metadata
+ *
+ * @example
+ * ```ts
+ * const rules = [...]; // Manual, replacement, and restriction rules
+ * const dates = ['2026-02-01', '2026-02-02', ...];
+ * const periods = [...]; // YearPeriod definitions
+ *
+ * const result = computeActiveTimePoints(rules, dates, periods);
+ * const feb1 = result.get(calendarKey(Dates.fromOperationalDate('2026-02-01')));
+ * // feb1 = {
+ * //   timepoints: ['08:00', '09:00', '10:00'],
+ * //   appliedRuleIds: ['rule1', 'rule2']
+ * // }
+ * ```
+ */
+export function computeActiveRules(date, rules, periods, options) {
+    const manualRules = rules.filter((r) => r.kind === 'manual');
+    const restrictionRules = rules.filter(r => r.kind === 'event_restriction');
+    const replacementRules = rules.filter((r) => r.kind === 'event_replacement');
+    const filteredManualRules = manualRules.filter((rule) => {
+        if (!rule.event_id)
+            return true;
+        const event = options?.events?.find(e => e._id === rule.event_id);
+        if (!event?.dates?.length)
+            return false;
+        return event.dates.includes(date);
+    });
+    const key = calendarKey(Dates.fromOperationalDate(date, 'Europe/Lisbon'));
+    const replacement = findReplacementForDate(date, replacementRules);
+    // 1) Base timepoints
+    let timepoints;
+    let appliedRuleIds;
+    if (replacement) {
+        // Replacement mode: match manuals by intersection (Option A)
+        const base = collectReplacementManualIncludes(replacement, filteredManualRules);
+        timepoints = base.timepoints;
+        appliedRuleIds = base.appliedRuleIds;
+        // Apply manual excludes *also* by intersection with replacement targets
+        applyReplacementManualExcludes(timepoints, appliedRuleIds, replacement, filteredManualRules);
+    }
+    else {
+        // Normal mode: day resolves to a single weekday + single yearPeriodId
+        const ctx = {
+            weekday: calendarWeekday(key),
+            yearPeriodId: getActivePeriodId(date, periods),
+        };
+        const base = collectManualIncludes(filteredManualRules, ctx);
+        timepoints = base.timepoints;
+        appliedRuleIds = base.appliedRuleIds;
+        applyManualExcludes(timepoints, appliedRuleIds, filteredManualRules, ctx);
+    }
+    // 2) Event restrictions always apply by date
+    applyEventRestrictions(date, timepoints, appliedRuleIds, restrictionRules);
+    const result = {
+        appliedRuleIds,
+        timepoints: Array.from(timepoints).sort() || [],
+    };
+    return result;
+}
+/* * */

package/dist/calendar/rules/calculation/matchers.d.ts

@@ -0,0 +1,39 @@
+import type { DayContext } from './types.js';
+import { EventReplacementRule, ManualRule } from '@tmlmobilidade/types';
+/**
+ * Determines if a manual rule matches the given day context.
+ *
+ * Uses strict AND logic: the rule must include BOTH the specified weekday
+ * AND the period ID to match. This is used for normal (non-replacement) days.
+ *
+ * @param rule - The manual rule to check
+ * @param ctx - The day context containing the weekday and period ID
+ * @returns True if the rule applies to this day context
+ *
+ * @example
+ * ```ts
+ * const rule = { weekdays: [1, 2, 3], year_period_ids: ['school'], ... };
+ * const ctx = { weekday: 1, yearPeriodId: 'school' };
+ * manualRuleMatchesContext(rule, ctx); // true
+ * ```
+ */
+export declare function manualRuleMatchesContext(rule: ManualRule, ctx: DayContext): boolean;
+/**
+ * Determines if a manual rule intersects with an event replacement rule's targets.
+ *
+ * Uses OR logic via set intersection: if the rule matches ANY weekday or period
+ * that the replacement targets, it's considered a match. This is used when a
+ * replacement rule overrides the normal schedule for certain weekdays/periods.
+ *
+ * @param rule - The manual rule to check
+ * @param replacement - The event replacement rule defining override targets
+ * @returns True if the rule intersects with the replacement's targets
+ *
+ * @example
+ * ```ts
+ * const rule = { weekdays: [1, 2], year_period_ids: ['school'], ... };
+ * const replacement = { weekdays: [1], year_period_ids: ['school', 'summer'], ... };
+ * manualRuleMatchesReplacement(rule, replacement); // true (weekday 1 matches)
+ * ```
+ */
+export declare function manualRuleMatchesReplacement(rule: ManualRule, replacement: EventReplacementRule): boolean;