@tmlmobilidade/databases 20260330.1756.23 → 20260331.1620.53

package/dist/interfaces/vehicle-events/simplified-vehicle-events.d.ts

@@ -5,6 +5,7 @@ declare class SimplifiedVehicleEventsNewClass extends ClickHouseInterfaceTemplat
     private static _instance;
     readonly databaseName = "operation";
     readonly orderBy = "(created_at, trip_id)";
+    readonly partitionBy = "toYYYYMMDD(fromUnixTimestamp64Milli(created_at))";
     readonly schema: ClickHouseSchema<{
         _id: string;
         created_at: number & {
@@ -13,10 +14,10 @@ declare class SimplifiedVehicleEventsNewClass extends ClickHouseInterfaceTemplat
         latitude: number;
         longitude: number;
         agency_id: string;
-        pattern_id: string | null;
         received_at: number & {
             __brand: "UnixTimestamp";
         };
+        pattern_id: string | null;
         stop_id: string | null;
         trip_id: string;
         vehicle_id: string;
@@ -29,6 +30,22 @@ declare class SimplifiedVehicleEventsNewClass extends ClickHouseInterfaceTemplat
         extra_trip_id: string | null;
     }>;
     readonly tableName = "simplified_vehicle_events";
+    /**
+     * Returns the last event for a given vehicle.
+     * @param vehicleId - The ID of the vehicle.
+     * @returns The last event for the vehicle.
+     */
+    getLastEvent(vehicleId: string, agencyId: string): Promise<null | SimplifiedVehicleEvent>;
+    /**
+     * Retrieves the most recent event per vehicle within the given time window.
+     *
+     * @param secondsAgo - The number of seconds in the past to consider for retrieving recent positions. Defaults to 90 seconds.
+     * @returns A promise resolving to an array of SimplifiedVehicleEvent objects, each representing the latest event for a vehicle within the specified period.
+     *
+     * The method filters out events where any of vehicle_id, agency_id, or trip_id are empty or null,
+     * and also ensures latitude and longitude are not zero. Only the most recent event per vehicle is returned.
+     */
+    getPositions(secondsAgo?: number): Promise<SimplifiedVehicleEvent[]>;
     /**
      * Returns the singleton instance of the subclass.
      */

package/dist/interfaces/vehicle-events/simplified-vehicle-events.js

@@ -29,8 +29,46 @@ class SimplifiedVehicleEventsNewClass extends ClickHouseInterfaceTemplate {
     static _instance = null;
     databaseName = 'operation';
     orderBy = '(created_at, trip_id)';
+    partitionBy = 'toYYYYMMDD(fromUnixTimestamp64Milli(created_at))';
     schema = tableSchema;
     tableName = 'simplified_vehicle_events';
+    /**
+     * Returns the last event for a given vehicle.
+     * @param vehicleId - The ID of the vehicle.
+     * @returns The last event for the vehicle.
+     */
+    async getLastEvent(vehicleId, agencyId) {
+        const query = `
+			SELECT *
+			FROM "${this.databaseName}"."${this.tableName}"
+			WHERE vehicle_id = '${vehicleId}'
+			AND agency_id = '${agencyId}'
+			ORDER BY created_at DESC
+			LIMIT 1
+		`;
+        const result = await this.queryFromString(query);
+        return result.length > 0 ? result[0] : null;
+    }
+    /**
+     * Retrieves the most recent event per vehicle within the given time window.
+     *
+     * @param secondsAgo - The number of seconds in the past to consider for retrieving recent positions. Defaults to 90 seconds.
+     * @returns A promise resolving to an array of SimplifiedVehicleEvent objects, each representing the latest event for a vehicle within the specified period.
+     *
+     * The method filters out events where any of vehicle_id, agency_id, or trip_id are empty or null,
+     * and also ensures latitude and longitude are not zero. Only the most recent event per vehicle is returned.
+     */
+    async getPositions(secondsAgo = 90) {
+        const query = `
+			SELECT *
+			FROM "${this.databaseName}"."${this.tableName}"
+			WHERE created_at > toUnixTimestamp64Milli(now64(3) - INTERVAL ${secondsAgo} SECOND)
+			ORDER BY created_at DESC
+			LIMIT 1 BY vehicle_id, agency_id
+		`;
+        const result = await this.queryFromString(query);
+        return result;
+    }
     /**
      * Returns the singleton instance of the subclass.
      */

package/dist/templates/clickhouse.d.ts

@@ -1,4 +1,6 @@
 import { type ClickHouseSchema, type ClickHouseTableEngine } from '../types/index.js';
+import { queryFromFile } from '../utils/clickhouse/query-from-file.js';
+import { queryFromString } from '../utils/clickhouse/query-from-string.js';
 import { type ClickHouseClient, type DataFormat } from '@clickhouse/client';
 export declare abstract class ClickHouseInterfaceTemplate<T> {
     protected readonly abstract databaseName: string;
@@ -6,6 +8,7 @@ export declare abstract class ClickHouseInterfaceTemplate<T> {
     protected readonly abstract tableName: string;
     protected readonly engine: ClickHouseTableEngine;
     protected readonly orderBy: string;
+    protected readonly partitionBy: null | string;
     private client;
     /**
      * Disallow direct instantiation of the service.
@@ -85,11 +88,32 @@ export declare abstract class ClickHouseInterfaceTemplate<T> {
      */
     protected postInit(): Promise<void>;
     /**
-     * Ensures that the specified database exists in ClickHouse, creating it if it does not already exist.
-     * This method performs input validation to prevent SQL injection and logs the outcome of the operation.
-     * @throws Will throw an error if the database name is unsafe or if the database creation query fails.
-     * @returns A promise that resolves when the database is ensured to exist.
-     */
+     * Executes a query from a .sql file with optional parameter substitutions.
+     * @param filePath Absolute or relative path to the .sql file.
+     * @param params Optional key-value substitutions applied to the query (replaces {key} placeholders).
+     * @returns Query result rows typed as `T`.
+     * @example
+     * // Given a SQL file "get_users.sql" with the content:
+     * // SELECT * FROM users WHERE created_at >= {start_date} AND created_at <= {end_date}
+     * const users = await clickhouseService.queryFromFile<User>('get_users.sql', {
+     *   start_date: '2024-01-01',
+     *   end_date: '2024-12-31',
+     * });
+    */
+    queryFromFile<T>(filePath: string, params?: Record<string, number | string>): ReturnType<typeof queryFromFile<T>>;
+    /**
+     * Executes a query from a string.
+     * @param client The ClickHouse client to use for executing the query.
+     * @param query The SQL query to execute, with optional {key} placeholders for parameters.
+     * @param params Optional key-value substitutions applied to the query (replaces {key} placeholders).
+     * @returns Query result rows typed as `T`.
+     * @example
+     * const users = await queryFromString<User>(clickhouseClient,
+     *   'SELECT * FROM users WHERE created_at >= {start_date} AND created_at <= {end_date}',
+     *   { start_date: '2024-01-01', end_date: '2024-12-31' }
+     * );
+    */
+    queryFromString<T>(query: string, params?: Record<string, number | string>): ReturnType<typeof queryFromString<T>>;
     private ensureDatabase;
     /**
      * Ensures that the specified table exists in ClickHouse, creating it if it does not already exist.

package/dist/templates/clickhouse.js

@@ -1,5 +1,6 @@
 /* * */
 import { preparePositionalQueryParams } from '../utils/clickhouse/prepare-positional-query-params.js';
+import { queryFromFile } from '../utils/clickhouse/query-from-file.js';
 import { queryFromString } from '../utils/clickhouse/query-from-string.js';
 import { validateSqlParam } from '../utils/clickhouse/validate-sql-param.js';
 import { Logger } from '@tmlmobilidade/logger';
@@ -7,6 +8,7 @@ import { Logger } from '@tmlmobilidade/logger';
 export class ClickHouseInterfaceTemplate {
     engine = 'ReplicatedMergeTree';
     orderBy = '_id';
+    partitionBy = null;
     client;
     /**
      * Disallow direct instantiation of the service.
@@ -127,11 +129,36 @@ export class ClickHouseInterfaceTemplate {
         // no-op by default
     }
     /**
-     * Ensures that the specified database exists in ClickHouse, creating it if it does not already exist.
-     * This method performs input validation to prevent SQL injection and logs the outcome of the operation.
-     * @throws Will throw an error if the database name is unsafe or if the database creation query fails.
-     * @returns A promise that resolves when the database is ensured to exist.
-     */
+     * Executes a query from a .sql file with optional parameter substitutions.
+     * @param filePath Absolute or relative path to the .sql file.
+     * @param params Optional key-value substitutions applied to the query (replaces {key} placeholders).
+     * @returns Query result rows typed as `T`.
+     * @example
+     * // Given a SQL file "get_users.sql" with the content:
+     * // SELECT * FROM users WHERE created_at >= {start_date} AND created_at <= {end_date}
+     * const users = await clickhouseService.queryFromFile<User>('get_users.sql', {
+     *   start_date: '2024-01-01',
+     *   end_date: '2024-12-31',
+     * });
+    */
+    async queryFromFile(filePath, params) {
+        return await queryFromFile(this.client, filePath, params);
+    }
+    /**
+     * Executes a query from a string.
+     * @param client The ClickHouse client to use for executing the query.
+     * @param query The SQL query to execute, with optional {key} placeholders for parameters.
+     * @param params Optional key-value substitutions applied to the query (replaces {key} placeholders).
+     * @returns Query result rows typed as `T`.
+     * @example
+     * const users = await queryFromString<User>(clickhouseClient,
+     *   'SELECT * FROM users WHERE created_at >= {start_date} AND created_at <= {end_date}',
+     *   { start_date: '2024-01-01', end_date: '2024-12-31' }
+     * );
+    */
+    async queryFromString(query, params) {
+        return await queryFromString(this.client, query, params);
+    }
     async ensureDatabase() {
         // Validate the inputs are safe identifiers to prevent SQL injection
         if (!validateSqlParam(this.databaseName, false))
@@ -159,8 +186,6 @@ export class ClickHouseInterfaceTemplate {
             throw new Error(`CLICKHOUSE [${this.databaseName}]: Unsafe database name provided.`);
         if (!validateSqlParam(this.tableName, false))
             throw new Error(`CLICKHOUSE [${this.tableName}]: Unsafe table name provided.`);
-        if (!validateSqlParam(this.engine, false))
-            throw new Error(`CLICKHOUSE [${this.engine}]: Unsafe engine type provided.`);
         // Validate the schema columns are safe identifiers
         const unsafeColumns = Object.keys(this.schema).filter(key => !validateSqlParam(key, false));
         if (unsafeColumns.length > 0)
@@ -172,7 +197,8 @@ export class ClickHouseInterfaceTemplate {
 			CREATE TABLE IF NOT EXISTS "${this.databaseName}"."${this.tableName}" ON CLUSTER default_cluster (
 				${Object.entries(this.schema).map(([key, column]) => `${key} ${column.type}`).join(', ')}
 			) ENGINE = ${this.getEngineString()}
-			ORDER BY ${this.orderBy}
+			${this.orderBy ? `ORDER BY ${this.orderBy}` : ''}
+			${this.partitionBy ? `PARTITION BY ${this.partitionBy}` : ''}
 		`;
         // Perform the query to create the table
         try {

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@tmlmobilidade/databases",
-	"version": "20260330.1756.23",
+	"version": "20260331.1620.53",
 	"author": {
 		"email": "iso@tmlmobilidade.pt",
 		"name": "TML-ISO"