@tmlmobilidade/controllers 20260505.1315.54 → 20260505.2312.1

package/dist/index.d.ts

@@ -1,3 +1,3 @@
 export * from './agencies/index.js';
 export * from './exporter/index.js';
-export * from './rides/index.js';
+export * from './operation/index.js';

package/dist/index.js

@@ -1,3 +1,3 @@
 export * from './agencies/index.js';
 export * from './exporter/index.js';
-export * from './rides/index.js';
+export * from './operation/index.js';

package/dist/operation/hashed-trips/hashed-trips.d.ts

@@ -0,0 +1,12 @@
+import { type FastifyReply, type FastifyRequest } from '@tmlmobilidade/fastify';
+import { type ActionsOf, type GetRidesBatchQuery, type HashedTrip, type Permission } from '@tmlmobilidade/types';
+export declare class HashedTripsSharedController {
+    /**
+     * Gets a batch of HashedTrips built with an aggregation pipeline.
+     * @param request The Fastify request object.
+     * @param reply The Fastify reply object.
+     */
+    static getBatch<S extends Permission['scope']>(request: FastifyRequest<{
+        Querystring: GetRidesBatchQuery;
+    }>, reply: FastifyReply<HashedTrip[]>, scope: S, action: ActionsOf<S>): Promise<never>;
+}

package/dist/operation/hashed-trips/hashed-trips.js

@@ -0,0 +1,66 @@
+/* * */
+import { HTTP_STATUS } from '@tmlmobilidade/consts';
+import { hashedTrips, rides, ridesBatchAggregationPipeline } from '@tmlmobilidade/interfaces';
+import { Logger } from '@tmlmobilidade/logger';
+import { GetRidesBatchQuerySchema, PermissionCatalog } from '@tmlmobilidade/types';
+/* * */
+export class HashedTripsSharedController {
+    //
+    /**
+     * Gets a batch of HashedTrips built with an aggregation pipeline.
+     * @param request The Fastify request object.
+     * @param reply The Fastify reply object.
+     */
+    static async getBatch(request, reply, scope, action) {
+        //
+        //
+        // Validate the request query parameters
+        const parsedQuery = GetRidesBatchQuerySchema.parse(request.query);
+        //
+        // Detect which agency_ids the user has access to,
+        // based on their permissions. If none, return an empty array.
+        const ridesPermission = PermissionCatalog.get(request.permissions, scope, action);
+        if (!ridesPermission['resources']?.agency_ids?.length)
+            return reply.send({ data: [], error: null, statusCode: HTTP_STATUS.OK });
+        const allowAllAgencies = ridesPermission['resources'].agency_ids.includes(PermissionCatalog.ALLOW_ALL_FLAG);
+        //
+        // Get the rides batch using native MongoDB cursor
+        // with batchSize to prevent memory issues
+        const pipeline = ridesBatchAggregationPipeline({
+            acceptance_status: parsedQuery.acceptance_status,
+            agency_ids: parsedQuery.agency_ids?.filter(id => allowAllAgencies || ridesPermission['resources'].agency_ids.includes(id)) ?? [],
+            analysis_ended_at_last_stop_grade: parsedQuery.analysis_ended_at_last_stop_grade,
+            analysis_expected_apex_validation_interval: parsedQuery.analysis_expected_apex_validation_interval,
+            analysis_simple_three_vehicle_events_grade: parsedQuery.analysis_simple_three_vehicle_events_grade,
+            analysis_transaction_sequentiality: parsedQuery.analysis_transaction_sequentiality,
+            date_end: parsedQuery.date_end,
+            date_start: parsedQuery.date_start,
+            delay_statuses: parsedQuery.delay_statuses,
+            line_ids: parsedQuery.line_ids,
+            operational_statuses: parsedQuery.operational_statuses,
+            search: parsedQuery.search,
+            seen_statuses: parsedQuery.seen_statuses,
+            stop_ids: parsedQuery.stop_ids,
+        });
+        //
+        // Limit the number of rides to 2000 and sort by start_time_scheduled
+        pipeline.push({ $limit: 2000 }, { $project: { hashed_trip_id: 1 } }, { $sort: { start_time_scheduled: 1 } });
+        //
+        // Fetch the rides batch from the database
+        const ridesBatch = await rides.aggregate(pipeline);
+        Logger.info(`HashedTripsSharedController.getBatch - ridesBatch count: ${ridesBatch?.length ?? 0}`);
+        //
+        // From the given batch of hashed_trip_ids,
+        // fetch the full HashedTrip documents with a single query.
+        const hashedTripIds = ridesBatch.map(ride => ride.hashed_trip_id);
+        const hashedTripsBatch = await hashedTrips.findMany({ _id: { $in: hashedTripIds } });
+        //
+        // Send the response
+        reply.send({
+            data: hashedTripsBatch ?? [],
+            error: null,
+            statusCode: HTTP_STATUS.OK,
+        });
+        //
+    }
+}

package/dist/operation/hashed-trips/index.d.ts

@@ -0,0 +1 @@
+export * from './hashed-trips.js';

package/dist/operation/hashed-trips/index.js

@@ -0,0 +1 @@
+export * from './hashed-trips.js';

package/dist/operation/index.d.ts

@@ -0,0 +1,4 @@
+export * from './hashed-trips/index.js';
+export * from './lines/index.js';
+export * from './rides/index.js';
+export * from './stops/index.js';

package/dist/operation/index.js

@@ -0,0 +1,4 @@
+export * from './hashed-trips/index.js';
+export * from './lines/index.js';
+export * from './rides/index.js';
+export * from './stops/index.js';

package/dist/operation/lines/batch.d.ts

@@ -0,0 +1,2 @@
+import { type GetOperationalLinesBatchQuery, type OperationalLine } from '@tmlmobilidade/types';
+export declare function getOperationalLinesBatch(query: GetOperationalLinesBatchQuery): Promise<OperationalLine[]>;

package/dist/operation/lines/batch.js

@@ -0,0 +1,118 @@
+/* * */
+import { rides } from '@tmlmobilidade/interfaces';
+import { Logger } from '@tmlmobilidade/logger';
+/* * */
+export async function getOperationalLinesBatch(query) {
+    //
+    //
+    // Use Rides as the baseline to fetch distinct hashed_trip_ids matching the query parameters.
+    // Rides are the glue between the different entities (Patterns, Lines, Stops, etc...) that compose an Operation,
+    // Stream the rides to build the Operation Lines batch on the fly, avoiding loading everything in memory at once.
+    const pipeline = [
+        {
+            $match: {
+                agency_id: { $in: query.agency_ids ?? [] },
+                start_time_scheduled: { $gte: query.date_start, $lte: query.date_end },
+            },
+        },
+        {
+            $sort: {
+                start_time_scheduled: -1, // newest first
+            },
+        },
+        {
+            $group: {
+                _id: '$hashed_trip_id',
+                agency_id: { $first: '$agency_id' },
+                hashed_trip_id: { $first: '$hashed_trip_id' },
+                line_id: { $first: '$line_id' },
+                operational_date: { $first: '$operational_date' },
+                plan_id: { $first: '$plan_id' },
+                start_time_scheduled: { $first: '$start_time_scheduled' },
+            },
+        },
+        {
+            $sort: {
+                start_time_scheduled: -1,
+            },
+        },
+        {
+            $project: {
+                _id: 0,
+                agency_id: 1,
+                hashed_trip_id: 1,
+                line_id: 1,
+                operational_date: 1,
+                plan_id: 1,
+                start_time_scheduled: 1,
+            },
+        },
+        {
+            $lookup: {
+                as: 'hashed_trip_doc',
+                foreignField: '_id',
+                from: 'hashed_trips',
+                localField: 'hashed_trip_id',
+            },
+        },
+        {
+            $unwind: {
+                path: '$hashed_trip_doc',
+                preserveNullAndEmptyArrays: true,
+            },
+        },
+        {
+            $sort: {
+                start_time_scheduled: -1,
+            },
+        },
+        {
+            $project: {
+                _id: 0,
+                agency_id: 1,
+                hashed_trip_doc: 1, // full joined document
+                operational_date: 1,
+                plan_id: 1,
+            },
+        },
+    ];
+    const ridesCollection = await rides.getCollection();
+    const pipelineResult = await ridesCollection
+        .aggregate(pipeline)
+        .toArray();
+    Logger.info(`OperationalLinesController.getBatch - pipeline result count: ${pipelineResult?.length ?? 0}`);
+    //
+    // Setup the final Map to keep track of the Operation Lines,
+    // using the line_id as the key to avoid duplicates,
+    // since multiple hashed_trip_ids can belong to the same line_id.
+    const operationalLinesMap = new Map();
+    pipelineResult.forEach((item) => {
+        // Initialize the line in the map if it doesn't exist yet
+        if (!operationalLinesMap.has(item.hashed_trip_doc.line_id)) {
+            operationalLinesMap.set(item.hashed_trip_doc.line_id, {
+                agency_id: item.agency_id,
+                hashed_trips: [],
+                last_operational_date: item.operational_date,
+                last_plan_id: item.plan_id,
+                line_id: item.hashed_trip_doc.line_id,
+                line_long_name: item.hashed_trip_doc.line_long_name,
+                line_short_name: item.hashed_trip_doc.line_short_name,
+                pattern_ids: [],
+                route_color: item.hashed_trip_doc.route_color,
+                route_ids: [],
+                stop_ids: [],
+            });
+        }
+        // Get the saved line from the map
+        const savedOperationalLine = operationalLinesMap.get(item.hashed_trip_doc.line_id);
+        // Update the object with the latest fields
+        savedOperationalLine.route_ids = Array.from(new Set([...savedOperationalLine.route_ids, item.hashed_trip_doc.route_id]));
+        savedOperationalLine.pattern_ids = Array.from(new Set([...savedOperationalLine.pattern_ids, item.hashed_trip_doc.pattern_id]));
+        savedOperationalLine.stop_ids = Array.from(new Set([...savedOperationalLine.stop_ids, ...(item.hashed_trip_doc.path.map(stop => stop.stop_id) ?? [])]));
+        savedOperationalLine.hashed_trips.push(item.hashed_trip_doc);
+    });
+    //
+    // Send the response
+    return Array.from(operationalLinesMap.values());
+    //
+}

package/dist/operation/lines/controller.d.ts

@@ -0,0 +1,12 @@
+import { type FastifyReply, type FastifyRequest } from '@tmlmobilidade/fastify';
+import { type ActionsOf, type GetOperationalLinesBatchQuery, type OperationalLine, type Permission } from '@tmlmobilidade/types';
+export declare class OperationalLinesSharedController {
+    /**
+     * Gets a batch of Operation Lines built with an aggregation pipeline.
+     * @param request The Fastify request object.
+     * @param reply The Fastify reply object.
+     */
+    static getBatch<S extends Permission['scope']>(request: FastifyRequest<{
+        Querystring: GetOperationalLinesBatchQuery;
+    }>, reply: FastifyReply<OperationalLine[]>, scope: S, action: ActionsOf<S>): Promise<never>;
+}

package/dist/operation/lines/controller.js

@@ -0,0 +1,38 @@
+/* * */
+import { getOperationalLinesBatch } from './batch.js';
+import { HTTP_STATUS } from '@tmlmobilidade/consts';
+import { GetOperationalLinesBatchQuerySchema, PermissionCatalog } from '@tmlmobilidade/types';
+/* * */
+export class OperationalLinesSharedController {
+    //
+    /**
+     * Gets a batch of Operation Lines built with an aggregation pipeline.
+     * @param request The Fastify request object.
+     * @param reply The Fastify reply object.
+     */
+    static async getBatch(request, reply, scope, action) {
+        //
+        const parsedQuery = GetOperationalLinesBatchQuerySchema.parse(request.query);
+        //
+        // Detect which agency_ids the user has access to,
+        // based on their permissions. If none, return an empty array.
+        const ridesPermission = PermissionCatalog.get(request.permissions, scope, action);
+        if (!ridesPermission['resources']?.agency_ids?.length)
+            return reply.send({ data: [], error: null, statusCode: HTTP_STATUS.OK });
+        const allowAllAgencies = ridesPermission['resources'].agency_ids.includes(PermissionCatalog.ALLOW_ALL_FLAG);
+        //
+        // Run the query
+        const result = await getOperationalLinesBatch({
+            ...parsedQuery,
+            agency_ids: parsedQuery.agency_ids?.filter(id => allowAllAgencies || ridesPermission['resources'].agency_ids.includes(id)) ?? [],
+        });
+        //
+        // Send the response
+        reply.send({
+            data: result,
+            error: null,
+            statusCode: HTTP_STATUS.OK,
+        });
+        //
+    }
+}

package/dist/operation/lines/index.d.ts

@@ -0,0 +1,2 @@
+export * from './batch.js';
+export * from './controller.js';

package/dist/operation/lines/index.js

@@ -0,0 +1,2 @@
+export * from './batch.js';
+export * from './controller.js';

package/dist/{rides → operation/rides}/index.d.ts

@@ -1 +1,2 @@
 export * from './rides.js';
+export * from './watch.js';

package/dist/{rides → operation/rides}/index.js

@@ -1 +1,2 @@
 export * from './rides.js';
+export * from './watch.js';

package/dist/operation/stops/batch.d.ts

@@ -0,0 +1,2 @@
+import { type GetOperationalStopsBatchQuery, type OperationalStop } from '@tmlmobilidade/types';
+export declare function getOperationalStopsBatch(query: GetOperationalStopsBatchQuery): Promise<OperationalStop[]>;

package/dist/operation/stops/batch.js

@@ -0,0 +1,119 @@
+/* * */
+import { rides } from '@tmlmobilidade/interfaces';
+import { Logger } from '@tmlmobilidade/logger';
+/* * */
+export async function getOperationalStopsBatch(query) {
+    //
+    //
+    // Use Rides as the baseline to fetch distinct hashed_trip_ids matching the query parameters.
+    // Rides are the glue between the different entities (Patterns, Lines, Stops, etc...) that compose an Operation,
+    // Stream the rides to build the Operation Stops batch on the fly, avoiding loading everything in memory at once.
+    const pipeline = [
+        {
+            $match: {
+                agency_id: { $in: query.agency_ids ?? [] },
+                start_time_scheduled: { $gte: query.date_start, $lte: query.date_end },
+            },
+        },
+        {
+            $sort: {
+                start_time_scheduled: -1, // newest first
+            },
+        },
+        {
+            $group: {
+                _id: '$hashed_trip_id',
+                agency_id: { $first: '$agency_id' },
+                hashed_trip_id: { $first: '$hashed_trip_id' },
+                line_id: { $first: '$line_id' },
+                operational_date: { $first: '$operational_date' },
+                plan_id: { $first: '$plan_id' },
+                start_time_scheduled: { $first: '$start_time_scheduled' },
+            },
+        },
+        {
+            $sort: {
+                start_time_scheduled: -1,
+            },
+        },
+        {
+            $project: {
+                _id: 0,
+                agency_id: 1,
+                hashed_trip_id: 1,
+                line_id: 1,
+                operational_date: 1,
+                plan_id: 1,
+                start_time_scheduled: 1,
+            },
+        },
+        {
+            $lookup: {
+                as: 'hashed_trip_doc',
+                foreignField: '_id',
+                from: 'hashed_trips',
+                localField: 'hashed_trip_id',
+            },
+        },
+        {
+            $unwind: {
+                path: '$hashed_trip_doc',
+                preserveNullAndEmptyArrays: true,
+            },
+        },
+        {
+            $sort: {
+                start_time_scheduled: -1,
+            },
+        },
+        {
+            $project: {
+                _id: 0,
+                agency_id: 1,
+                hashed_trip_doc: 1, // full joined document
+                operational_date: 1,
+                plan_id: 1,
+            },
+        },
+    ];
+    const ridesCollection = await rides.getCollection();
+    const pipelineResult = await ridesCollection
+        .aggregate(pipeline)
+        .toArray();
+    Logger.info(`OperationalStopsController.getBatch - pipeline result count: ${pipelineResult?.length ?? 0}`);
+    //
+    // Setup the final Map to keep track of the Operation Stops,
+    // using the stop_id as the key to avoid duplicates,
+    // since multiple hashed_trip_ids can belong to the same stop_id.
+    const operationalStopsMap = new Map();
+    pipelineResult.forEach((item) => {
+        item.hashed_trip_doc.path.forEach((waypoint) => {
+            // Initialize the stop in the map if it doesn't exist yet
+            if (!operationalStopsMap.has(waypoint.stop_id)) {
+                operationalStopsMap.set(waypoint.stop_id, {
+                    agency_ids: [],
+                    hashed_trips: [],
+                    last_operational_date: item.operational_date,
+                    last_plan_id: item.plan_id,
+                    line_ids: [],
+                    pattern_ids: [],
+                    route_ids: [],
+                    stop_id: waypoint.stop_id,
+                    stop_name: waypoint.stop_name,
+                });
+            }
+            // Get the saved stop from the map
+            const savedOperationalStop = operationalStopsMap.get(waypoint.stop_id);
+            // Update the object with the latest fields
+            savedOperationalStop.agency_ids = Array.from(new Set([...savedOperationalStop.agency_ids, item.agency_id]));
+            savedOperationalStop.line_ids = Array.from(new Set([...savedOperationalStop.line_ids, item.hashed_trip_doc.line_id]));
+            savedOperationalStop.route_ids = Array.from(new Set([...savedOperationalStop.route_ids, item.hashed_trip_doc.route_id]));
+            savedOperationalStop.pattern_ids = Array.from(new Set([...savedOperationalStop.pattern_ids, item.hashed_trip_doc.pattern_id]));
+            savedOperationalStop.hashed_trips.push(item.hashed_trip_doc);
+        });
+    });
+    //
+    // Send the response
+    return Array.from(operationalStopsMap.values());
+    //
+}

package/dist/operation/stops/controller.d.ts

@@ -0,0 +1,12 @@
+import { type FastifyReply, type FastifyRequest } from '@tmlmobilidade/fastify';
+import { type ActionsOf, type GetOperationalStopsBatchQuery, type OperationalStop, type Permission } from '@tmlmobilidade/types';
+export declare class OperationalStopsSharedController {
+    /**
+     * Gets a batch of Operational Stops built with an aggregation pipeline.
+     * @param request The Fastify request object.
+     * @param reply The Fastify reply object.
+     */
+    static getBatch<S extends Permission['scope']>(request: FastifyRequest<{
+        Querystring: GetOperationalStopsBatchQuery;
+    }>, reply: FastifyReply<OperationalStop[]>, scope: S, action: ActionsOf<S>): Promise<never>;
+}

package/dist/operation/stops/controller.js

@@ -0,0 +1,38 @@
+/* * */
+import { getOperationalStopsBatch } from './batch.js';
+import { HTTP_STATUS } from '@tmlmobilidade/consts';
+import { GetOperationalStopsBatchQuerySchema, PermissionCatalog } from '@tmlmobilidade/types';
+/* * */
+export class OperationalStopsSharedController {
+    //
+    /**
+     * Gets a batch of Operational Stops built with an aggregation pipeline.
+     * @param request The Fastify request object.
+     * @param reply The Fastify reply object.
+     */
+    static async getBatch(request, reply, scope, action) {
+        //
+        const parsedQuery = GetOperationalStopsBatchQuerySchema.parse(request.query);
+        //
+        // Detect which agency_ids the user has access to,
+        // based on their permissions. If none, return an empty array.
+        const ridesPermission = PermissionCatalog.get(request.permissions, scope, action);
+        if (!ridesPermission['resources']?.agency_ids?.length)
+            return reply.send({ data: [], error: null, statusCode: HTTP_STATUS.OK });
+        const allowAllAgencies = ridesPermission['resources'].agency_ids.includes(PermissionCatalog.ALLOW_ALL_FLAG);
+        //
+        // Run the query
+        const result = await getOperationalStopsBatch({
+            ...parsedQuery,
+            agency_ids: parsedQuery.agency_ids?.filter(id => allowAllAgencies || ridesPermission['resources'].agency_ids.includes(id)) ?? [],
+        });
+        //
+        // Send the response
+        reply.send({
+            data: result,
+            error: null,
+            statusCode: HTTP_STATUS.OK,
+        });
+        //
+    }
+}

package/dist/operation/stops/index.d.ts

@@ -0,0 +1,2 @@
+export * from './batch.js';
+export * from './controller.js';

package/dist/operation/stops/index.js

@@ -0,0 +1,2 @@
+export * from './batch.js';
+export * from './controller.js';

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@tmlmobilidade/controllers",
-	"version": "20260505.1315.54",
+	"version": "20260505.2312.1",
 	"author": {
 		"email": "iso@tmlmobilidade.pt",
 		"name": "TML-ISO"
@@ -39,6 +39,7 @@
 		"@tmlmobilidade/consts": "*",
 		"@tmlmobilidade/fastify": "*",
 		"@tmlmobilidade/interfaces": "*",
+		"@tmlmobilidade/logger": "*",
 		"@tmlmobilidade/normalizers": "*",
 		"@tmlmobilidade/utils": "*"
 	},