@tmlmobilidade/go-interfaces-labdb 20260717.1316.58

package/dist/databases/operation.d.ts

@@ -0,0 +1,8 @@
+import { ClickHouseInterfaceTemplate } from '../interface.template.js';
+import { ClickHouseClient } from '@tmlmobilidade/go-clients-clickhouse';
+import { type SimplifiedVehicleEvent } from '@tmlmobilidade/types';
+export declare class OperationDatabase {
+    readonly vehicleEvents: ClickHouseInterfaceTemplate<SimplifiedVehicleEvent>;
+    private readonly databaseName;
+    constructor(instance: ClickHouseClient);
+}

package/dist/databases/operation.js

@@ -0,0 +1,21 @@
+/* * */
+import { ClickHouseInterfaceTemplate } from '../interface.template.js';
+import { simplifiedVehicleEventSchema } from '../types/operation.js';
+/* * */
+export class OperationDatabase {
+    //
+    //
+    // Collections
+    vehicleEvents;
+    //
+    databaseName = 'operation';
+    constructor(instance) {
+        // Create collection interfaces
+        this.vehicleEvents = new ClickHouseInterfaceTemplate(instance, this.databaseName, 'simplified_vehicle_events', simplifiedVehicleEventSchema, {
+            engine: 'ReplacingMergeTree(created_at)',
+            orderBy: ['operational_date', 'trip_id', 'vehicle_id', 'agency_id', 'created_at'],
+            partitionBy: 'toYYYYMM(fromUnixTimestamp64Milli(created_at))',
+            primaryKey: ['operational_date', 'trip_id', 'vehicle_id'],
+        });
+    }
+}

package/dist/databases/performance.d.ts

@@ -0,0 +1,8 @@
+import { ClickHouseInterfaceTemplate } from '../interface.template.js';
+import { ClickHouseClient } from '@tmlmobilidade/go-clients-clickhouse';
+import { type DemandByAgencyByOperationalDate } from '@tmlmobilidade/go-types-performance';
+export declare class PerformanceDatabase {
+    readonly demandByAgencyByOperationalDate: ClickHouseInterfaceTemplate<DemandByAgencyByOperationalDate>;
+    private readonly databaseName;
+    constructor(instance: ClickHouseClient);
+}

package/dist/databases/performance.js

@@ -0,0 +1,21 @@
+/* * */
+import { ClickHouseInterfaceTemplate } from '../interface.template.js';
+import { demandByAgencyByOperationalDateSchema } from '../types/performance.js';
+/* * */
+export class PerformanceDatabase {
+    //
+    //
+    // Tables
+    demandByAgencyByOperationalDate;
+    //
+    databaseName = 'performance';
+    constructor(instance) {
+        //
+        // Create the table interfaces
+        this.demandByAgencyByOperationalDate = new ClickHouseInterfaceTemplate(instance, this.databaseName, 'demand_by_agency_by_operational_date', demandByAgencyByOperationalDateSchema, {
+            engine: 'ReplacingMergeTree(updated_at)',
+            orderBy: ['operational_date', 'agency_id'],
+            partitionBy: 'intDiv(operational_date, 100)',
+        });
+    }
+}

package/dist/databases/simplified-apex.d.ts

@@ -0,0 +1,14 @@
+import { ClickHouseInterfaceTemplate } from '../interface.template.js';
+import { ClickHouseClient } from '@tmlmobilidade/go-clients-clickhouse';
+import { type SimplifiedApexBankingTap, SimplifiedApexInspection, SimplifiedApexInspectionDecision, SimplifiedApexLocation, SimplifiedApexOnBoardRefund, SimplifiedApexOnBoardSale, SimplifiedApexValidation } from '@tmlmobilidade/go-types-apex';
+export declare class SimplifiedApexDatabase {
+    readonly bankingTaps: ClickHouseInterfaceTemplate<SimplifiedApexBankingTap>;
+    readonly inspectionDecisions: ClickHouseInterfaceTemplate<SimplifiedApexInspectionDecision>;
+    readonly inspections: ClickHouseInterfaceTemplate<SimplifiedApexInspection>;
+    readonly locations: ClickHouseInterfaceTemplate<SimplifiedApexLocation>;
+    readonly refunds: ClickHouseInterfaceTemplate<SimplifiedApexOnBoardRefund>;
+    readonly sales: ClickHouseInterfaceTemplate<SimplifiedApexOnBoardSale>;
+    readonly validations: ClickHouseInterfaceTemplate<SimplifiedApexValidation>;
+    private readonly databaseName;
+    constructor(instance: ClickHouseClient);
+}

package/dist/databases/simplified-apex.js

@@ -0,0 +1,35 @@
+/* * */
+import { ClickHouseInterfaceTemplate } from '../interface.template.js';
+import { simplifiedApexBankingTapSchema, simplifiedApexInspectionDecisionSchema, simplifiedApexInspectionSchema, simplifiedApexLocationSchema, simplifiedApexOnBoardRefundSchema, simplifiedApexOnBoardSaleSchema, simplifiedApexValidationSchema } from '../types/simplified-apex.js';
+/* * */
+export class SimplifiedApexDatabase {
+    //
+    //
+    // Tables
+    bankingTaps;
+    inspectionDecisions;
+    inspections;
+    locations;
+    refunds;
+    sales;
+    validations;
+    //
+    databaseName = 'simplified_apex';
+    constructor(instance) {
+        //
+        // Setup the table options, as they are the same for all simplified APEX tables
+        const simplifiedTableOptions = {
+            engine: 'ReplacingMergeTree(updated_at)',
+            orderBy: ['agency_id', 'operational_date', 'created_at', '_id'],
+            partitionBy: 'intDiv(operational_date, 100)',
+        };
+        // Create the table interfaces
+        this.bankingTaps = new ClickHouseInterfaceTemplate(instance, this.databaseName, 'banking_taps', simplifiedApexBankingTapSchema, simplifiedTableOptions);
+        this.inspectionDecisions = new ClickHouseInterfaceTemplate(instance, this.databaseName, 'inspection_decisions', simplifiedApexInspectionDecisionSchema, simplifiedTableOptions);
+        this.inspections = new ClickHouseInterfaceTemplate(instance, this.databaseName, 'inspections', simplifiedApexInspectionSchema, simplifiedTableOptions);
+        this.locations = new ClickHouseInterfaceTemplate(instance, this.databaseName, 'locations', simplifiedApexLocationSchema, simplifiedTableOptions);
+        this.refunds = new ClickHouseInterfaceTemplate(instance, this.databaseName, 'refunds', simplifiedApexOnBoardRefundSchema, simplifiedTableOptions);
+        this.sales = new ClickHouseInterfaceTemplate(instance, this.databaseName, 'sales', simplifiedApexOnBoardSaleSchema, simplifiedTableOptions);
+        this.validations = new ClickHouseInterfaceTemplate(instance, this.databaseName, 'validations', simplifiedApexValidationSchema, simplifiedTableOptions);
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,47 @@
+import { queryFromFile, queryFromString } from '@tmlmobilidade/go-clients-clickhouse';
+import { OperationDatabase } from './databases/operation.js';
+import { PerformanceDatabase } from './databases/performance.js';
+import { SimplifiedApexDatabase } from './databases/simplified-apex.js';
+declare class LabDbClass {
+    private static _instance;
+    private readonly clickhouseClient;
+    readonly operation: OperationDatabase;
+    readonly performance: PerformanceDatabase;
+    readonly simplifiedApex: SimplifiedApexDatabase;
+    /**
+     * Establishes a connection to the Mongo database and initializes the collection.
+     * @param options Optional Mongo client connection options.
+     * @throws Error if the environment variable for the database URI is missing or if the connection fails.
+     */
+    static getInstance(): Promise<LabDbClass>;
+    private constructor();
+    /**
+     * 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>>;
+}
+export declare const labDb: LabDbClass;
+export {};

package/dist/index.js

@@ -0,0 +1,73 @@
+/* * */
+import { ClickHouseDatabaseClient, queryFromFile, queryFromString } from '@tmlmobilidade/go-clients-clickhouse';
+import { asyncSingletonProxy } from '@tmlmobilidade/utils';
+import { OperationDatabase } from './databases/operation.js';
+import { PerformanceDatabase } from './databases/performance.js';
+import { SimplifiedApexDatabase } from './databases/simplified-apex.js';
+/* * */
+class LabDbClass {
+    //
+    //
+    //
+    static _instance;
+    clickhouseClient;
+    //
+    // Databases
+    operation;
+    performance;
+    simplifiedApex;
+    /**
+     * Establishes a connection to the Mongo database and initializes the collection.
+     * @param options Optional Mongo client connection options.
+     * @throws Error if the environment variable for the database URI is missing or if the connection fails.
+     */
+    static async getInstance() {
+        if (!LabDbClass._instance) {
+            const clickhouseClient = await ClickHouseDatabaseClient.getClient({ prefix: 'LABDB' });
+            LabDbClass._instance = new LabDbClass(clickhouseClient);
+        }
+        return LabDbClass._instance;
+    }
+    //
+    // Constructor
+    constructor(clickhouseClient) {
+        this.clickhouseClient = clickhouseClient;
+        this.operation = new OperationDatabase(this.clickhouseClient);
+        this.performance = new PerformanceDatabase(this.clickhouseClient);
+        this.simplifiedApex = new SimplifiedApexDatabase(this.clickhouseClient);
+    }
+    //
+    // Queries
+    /**
+     * 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.clickhouseClient, 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.clickhouseClient, query, params);
+    }
+}
+export const labDb = asyncSingletonProxy(LabDbClass);

package/dist/interface.template.d.ts

@@ -0,0 +1,125 @@
+import type { ClickHouseClient, ClickhouseField, ClickHouseTableEngine, ClickHouseTableSchema, DataFormat } from '@tmlmobilidade/go-clients-clickhouse';
+import { queryFromFile, queryFromString } from '@tmlmobilidade/go-clients-clickhouse';
+export interface ClickhouseInterfaceTableOptions<T extends object> {
+    engine?: ClickHouseTableEngine<T>;
+    manageSchema?: boolean;
+    orderBy?: Array<ClickhouseField<T>> | ClickhouseField<T>;
+    partitionBy?: string;
+    primaryKey?: Array<ClickhouseField<T>> | ClickhouseField<T>;
+}
+export declare class ClickHouseInterfaceTemplate<T extends object> {
+    private readonly databaseName;
+    private readonly schema;
+    private readonly tableName;
+    private readonly tableOptions;
+    private client;
+    /**
+     * @param databaseName - The name of the database to create the interface for.
+     * @param engine - The engine of the table to create the interface for.
+     * @param schema - The schema of the table to create the interface for.
+     * @param tableName - The name of the table to create the interface for.
+     */
+    constructor(client: ClickHouseClient, databaseName: string, tableName: string, schema: ClickHouseTableSchema<T>, options?: ClickhouseInterfaceTableOptions<T>);
+    /**
+     * Executes a COUNT query on the ClickHouse table using the service's client.
+     * @param select The columns to select in the query (e.g., `"*"`, `"column1, column2"`).
+     * @param where The WHERE clause to filter the results (e.g., `"id = 1"`).
+     * @param params Optional key-value substitutions applied to the WHERE clause (replaces $1, $2, etc.).
+     * @returns A promise that resolves to an array of results matching the query.
+     */
+    count(select: string, where: string, params?: Record<string, number | string>): Promise<number>;
+    /**
+     * Executes a DELETE query on the ClickHouse table using the service's client.
+     * @param where The WHERE clause to filter the results (e.g., `"id = 1"`).
+     * @param params Optional key-value substitutions applied to the WHERE clause (replaces $1, $2, etc.).
+     * @returns A promise that resolves when the delete operation is complete.
+     */
+    delete(where: string, params?: Record<string, number | string | string[]>): Promise<void>;
+    /**
+     * Executes a DISTINCT query on the ClickHouse table using the service's client.
+     * @param select The columns to select in the query (e.g., `"*"`, `"column1, column2"`).
+     * @param where The WHERE clause to filter the results (e.g., `"id = 1"`).
+     * @param params Optional key-value substitutions applied to the WHERE clause (replaces $1, $2, etc.).
+     * @returns A promise that resolves to an array of distinct values matching the query.
+     */
+    distinct<T>(field: keyof T, where: string, params?: Record<string, number | string>): Promise<T[keyof T][]>;
+    /**
+     * Provides access to the ClickHouse client instance,
+     * initializing it if it has not already been created.
+     * @returns A promise that resolves to the ClickHouse client instance.
+     * @warning Use with caution: direct access to the client allows for executing arbitrary queries.
+     */
+    getClient(): Promise<ClickHouseClient>;
+    /**
+     * Returns the name of the database used by this service.
+     */
+    getDatabaseName(): Promise<string>;
+    /**
+     * Returns the name of the table used by this service.
+     */
+    getTableName(): Promise<string>;
+    /**
+     * Inserts data into a specified ClickHouse table using the service's client.
+     * @param format The format of the data being inserted (default is 'JSONEachRow').
+     * @param values An array of data objects to insert into the table.
+     * @returns A promise that resolves when the data is inserted successfully.
+     */
+    insert<T>(format: DataFormat | undefined, values: T[]): Promise<import("@clickhouse/client").InsertResult>;
+    /**
+     * Executes a simple SELECT query on the ClickHouse table using the service's client.
+     * @param select The columns to select in the query (e.g., `"*"`, `"column1, column2"`).
+     * @param where The WHERE clause to filter the results (e.g., `"id = 1"`).
+     * @param params Optional key-value substitutions applied to the WHERE clause (replaces $1, $2, etc.).
+     * @returns A promise that resolves to an array of results matching the query.
+     */
+    select(select: string, where: string, params?: Record<string, number | string>): Promise<T[]>;
+    /**
+     * Initializes the ClickHouse client and ensures that the specified database and table exist.
+     * This method should be called before performing any operations on the database or table.
+     * It handles the asynchronous setup process and logs any errors that occur during initialization.
+     * @throws Will throw an error if the client initialization or database/table setup fails.
+     * @returns A promise that resolves when the initialization process is complete.
+     */
+    protected init(): Promise<void>;
+    /**
+     * Optional override for custom setup logic:
+     * indexes, materialized views, constraints, etc.
+     */
+    protected postInit(): Promise<void>;
+    /**
+     * 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.
+     * This method performs input validation to prevent SQL injection and logs the outcome of the operation.
+     * It constructs a CREATE TABLE query based on the provided schema and engine type, and executes it using the client.
+     * @throws Will throw an error if any of the inputs are unsafe or if the table creation query fails.
+     * @returns A promise that resolves when the table is ensured to exist.
+     */
+    private ensureTable;
+}

package/dist/interface.template.js

@@ -0,0 +1,252 @@
+/* * */
+import { ClickHouseError, preparePositionalQueryParams, queryFromFile, queryFromString, validateSqlParam } from '@tmlmobilidade/go-clients-clickhouse';
+import { Logger } from '@tmlmobilidade/logger';
+export class ClickHouseInterfaceTemplate {
+    //
+    databaseName;
+    schema;
+    tableName;
+    tableOptions = {};
+    client;
+    /**
+     * @param databaseName - The name of the database to create the interface for.
+     * @param engine - The engine of the table to create the interface for.
+     * @param schema - The schema of the table to create the interface for.
+     * @param tableName - The name of the table to create the interface for.
+     */
+    constructor(client, databaseName, tableName, schema, options = {}) {
+        this.client = client;
+        this.databaseName = databaseName;
+        this.schema = schema;
+        this.tableName = tableName;
+        this.tableOptions = {
+            engine: options.engine ?? 'MergeTree()',
+            manageSchema: options.manageSchema ?? true,
+            orderBy: options.orderBy ?? '_id',
+            partitionBy: options.partitionBy ?? undefined,
+            primaryKey: options.primaryKey ?? undefined,
+        };
+        this.init().catch((error) => {
+            Logger.error({ error, message: `CLICKHOUSE [${this.databaseName}."${this.tableName}"]: Error @ constructor(): ${error.message}` });
+            throw error;
+        });
+    }
+    /**
+     * Executes a COUNT query on the ClickHouse table using the service's client.
+     * @param select The columns to select in the query (e.g., `"*"`, `"column1, column2"`).
+     * @param where The WHERE clause to filter the results (e.g., `"id = 1"`).
+     * @param params Optional key-value substitutions applied to the WHERE clause (replaces $1, $2, etc.).
+     * @returns A promise that resolves to an array of results matching the query.
+     */
+    async count(select, where, params) {
+        const result = await queryFromString(this.client, `SELECT COUNT(${select}) AS count FROM "${this.databaseName}"."${this.tableName}" WHERE ${where}`, params);
+        return result.length > 0 ? result[0].count : 0;
+    }
+    /**
+     * Executes a DELETE query on the ClickHouse table using the service's client.
+     * @param where The WHERE clause to filter the results (e.g., `"id = 1"`).
+     * @param params Optional key-value substitutions applied to the WHERE clause (replaces $1, $2, etc.).
+     * @returns A promise that resolves when the delete operation is complete.
+     */
+    async delete(where, params) {
+        const preparedQuery = preparePositionalQueryParams(`DELETE FROM "${this.databaseName}"."${this.tableName}" WHERE ${where}`, params);
+        await this.client.command({
+            query: preparedQuery.query,
+            query_params: preparedQuery.query_params,
+        });
+    }
+    /**
+     * Executes a DISTINCT query on the ClickHouse table using the service's client.
+     * @param select The columns to select in the query (e.g., `"*"`, `"column1, column2"`).
+     * @param where The WHERE clause to filter the results (e.g., `"id = 1"`).
+     * @param params Optional key-value substitutions applied to the WHERE clause (replaces $1, $2, etc.).
+     * @returns A promise that resolves to an array of distinct values matching the query.
+     */
+    async distinct(field, where, params) {
+        const result = await queryFromString(this.client, `SELECT DISTINCT ${String(field)} FROM "${this.databaseName}"."${this.tableName}" WHERE ${where}`, params);
+        return result.map(doc => doc[field]);
+    }
+    /**
+     * Provides access to the ClickHouse client instance,
+     * initializing it if it has not already been created.
+     * @returns A promise that resolves to the ClickHouse client instance.
+     * @warning Use with caution: direct access to the client allows for executing arbitrary queries.
+     */
+    async getClient() {
+        if (!this.client)
+            await this.init();
+        return this.client;
+    }
+    /**
+     * Returns the name of the database used by this service.
+     */
+    async getDatabaseName() {
+        return this.databaseName;
+    }
+    /**
+     * Returns the name of the table used by this service.
+     */
+    async getTableName() {
+        return this.tableName;
+    }
+    /**
+     * Inserts data into a specified ClickHouse table using the service's client.
+     * @param format The format of the data being inserted (default is 'JSONEachRow').
+     * @param values An array of data objects to insert into the table.
+     * @returns A promise that resolves when the data is inserted successfully.
+     */
+    async insert(format = 'JSONEachRow', values) {
+        return this.client.insert({
+            format: format,
+            table: `"${this.databaseName}"."${this.tableName}"`,
+            values: values,
+        });
+    }
+    /**
+     * Executes a simple SELECT query on the ClickHouse table using the service's client.
+     * @param select The columns to select in the query (e.g., `"*"`, `"column1, column2"`).
+     * @param where The WHERE clause to filter the results (e.g., `"id = 1"`).
+     * @param params Optional key-value substitutions applied to the WHERE clause (replaces $1, $2, etc.).
+     * @returns A promise that resolves to an array of results matching the query.
+     */
+    async select(select, where, params) {
+        return await queryFromString(this.client, `SELECT ${select} FROM "${this.databaseName}"."${this.tableName}" WHERE ${where}`, params);
+    }
+    /**
+     * Initializes the ClickHouse client and ensures that the specified database and table exist.
+     * This method should be called before performing any operations on the database or table.
+     * It handles the asynchronous setup process and logs any errors that occur during initialization.
+     * @throws Will throw an error if the client initialization or database/table setup fails.
+     * @returns A promise that resolves when the initialization process is complete.
+     */
+    async init() {
+        // Skip if already initialized
+        if (this.client)
+            return;
+        // Validate required properties before attempting to connect
+        if (!this.databaseName)
+            throw new Error('CLICKHOUSE: databaseName is required.');
+        if (!this.tableName)
+            throw new Error('CLICKHOUSE: tableName is required.');
+        if (this.tableOptions.manageSchema && (!this.schema || Object.entries(this.schema).length === 0)) {
+            throw new Error('CLICKHOUSE: schema is required and cannot be empty.');
+        }
+        // Only own the schema when this interface is the source of truth.
+        // External DDL owners (see `manageSchema`) skip this entirely.
+        if (this.tableOptions.manageSchema) {
+            await this.ensureDatabase();
+            await this.ensureTable();
+        }
+        await this.postInit();
+    }
+    /**
+     * Optional override for custom setup logic:
+     * indexes, materialized views, constraints, etc.
+     */
+    async postInit() {
+        // no-op by default
+    }
+    /**
+     * 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))
+            throw new Error(`CLICKHOUSE [${this.databaseName}]: Unsafe database name provided.`);
+        // Perform the query to create the database if it does not exist
+        try {
+            await this.client.command({ query: `CREATE DATABASE IF NOT EXISTS "${this.databaseName}"` });
+            Logger.info({ message: `CLICKHOUSE [${this.databaseName}]: Database created.` });
+        }
+        catch (error) {
+            Logger.error({ error, message: `CLICKHOUSE [${this.databaseName}]: Error @ createDatabase(): ${error.message}` });
+            throw error;
+        }
+    }
+    /**
+     * Ensures that the specified table 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.
+     * It constructs a CREATE TABLE query based on the provided schema and engine type, and executes it using the client.
+     * @throws Will throw an error if any of the inputs are unsafe or if the table creation query fails.
+     * @returns A promise that resolves when the table is ensured to exist.
+     */
+    async ensureTable() {
+        // Validate the inputs are safe identifiers to prevent SQL injection
+        if (!validateSqlParam(this.databaseName, false))
+            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.`);
+        // Validate the schema columns are safe identifiers
+        const unsafeColumns = Object.keys(this.schema).filter(key => !validateSqlParam(key, false));
+        if (unsafeColumns.length > 0)
+            throw new Error(`CLICKHOUSE [${this.tableName}]: Unsafe column names provided: ${unsafeColumns.join(', ')}.`);
+        // Ensure the database exists before creating the table
+        await this.ensureDatabase();
+        // Setup the full CREATE TABLE query
+        const createTableQuery = `
+			CREATE TABLE IF NOT EXISTS "${this.databaseName}"."${this.tableName}" (
+				${Object.entries(this.schema).map(([key, column]) => `${key} ${column.type}`).join(', ')}
+			) ENGINE = ${this.tableOptions.engine}
+			${this.tableOptions.primaryKey ? `PRIMARY KEY (${Array.isArray(this.tableOptions.primaryKey) ? this.tableOptions.primaryKey.join(', ') : this.tableOptions.primaryKey})` : ''}
+			${this.tableOptions.orderBy ? `ORDER BY (${Array.isArray(this.tableOptions.orderBy) ? this.tableOptions.orderBy.join(', ') : this.tableOptions.orderBy})` : ''}
+			${this.tableOptions.partitionBy ? `PARTITION BY (${this.tableOptions.partitionBy})` : ''}
+		`;
+        // Perform the query to create the table
+        try {
+            await this.client.command({ query: createTableQuery });
+            Logger.info({ message: `CLICKHOUSE [${this.tableName}]: Table created.` });
+        }
+        catch (error) {
+            // If the error is not an ACCESS_DENIED, throw it right away
+            if (!(error instanceof ClickHouseError) || error.code !== '497') {
+                Logger.error({ error, message: `CLICKHOUSE [${this.tableName}]: Error @ createTable(): ${error.message}` });
+                throw error;
+            }
+            // If the error is an ACCESS_DENIED, check if the table exists
+            try {
+                const resultSet = await this.client.query({
+                    format: 'JSONEachRow',
+                    query: `SHOW TABLES FROM "${this.databaseName}" LIKE '${this.tableName}'`,
+                });
+                const tables = await resultSet.json();
+                if (Array.isArray(tables) && tables.length > 0)
+                    return;
+                Logger.error({ error, message: `CLICKHOUSE [${this.tableName}]: ACCESS_DENIED and table does not exist. ${error.message}` });
+                throw error;
+            }
+            catch (verifyError) {
+                //
+                Logger.error({ error: verifyError, message: `CLICKHOUSE [${this.tableName}]: Failed to verify table existence after ACCESS_DENIED: ${verifyError.message}` });
+                throw verifyError;
+            }
+        }
+    }
+}

package/dist/types/operation.d.ts

@@ -0,0 +1,3 @@
+import { type ClickHouseTableSchema } from '@tmlmobilidade/go-clients-clickhouse';
+import { type SimplifiedVehicleEvent } from '@tmlmobilidade/types';
+export declare const simplifiedVehicleEventSchema: ClickHouseTableSchema<SimplifiedVehicleEvent>;

package/dist/types/operation.js

@@ -0,0 +1,24 @@
+/* * */
+/* * */
+export const simplifiedVehicleEventSchema = {
+    _id: { type: 'String' },
+    agency_id: { type: 'String' },
+    created_at: { type: 'Int64' },
+    geohash: { default: 'geohashEncode(longitude, latitude, 7)', type: 'String' },
+    latitude: { type: 'Float64' },
+    longitude: { type: 'Float64' },
+    operational_date: { type: 'Date' },
+    received_at: { type: 'Int64' },
+    trip_id: { type: 'String' },
+    vehicle_id: { type: 'String' },
+    // Optional Fields
+    bearing: { type: 'Nullable(Int64)' },
+    current_status: { type: 'Nullable(String)' },
+    door: { type: 'Nullable(String)' },
+    driver_id: { type: 'Nullable(String)' },
+    extra_trip_id: { type: 'Nullable(String)' },
+    odometer: { type: 'Nullable(Int64)' },
+    pattern_id: { type: 'Nullable(String)' },
+    speed: { type: 'Nullable(Int64)' },
+    stop_id: { type: 'Nullable(String)' },
+};

package/dist/types/performance.d.ts

@@ -0,0 +1,3 @@
+import { type ClickHouseTableSchema } from '@tmlmobilidade/go-clients-clickhouse';
+import { type DemandByAgencyByOperationalDate } from '@tmlmobilidade/go-types-performance';
+export declare const demandByAgencyByOperationalDateSchema: ClickHouseTableSchema<DemandByAgencyByOperationalDate>;

package/dist/types/performance.js

@@ -0,0 +1,8 @@
+/* * */
+/* * */
+export const demandByAgencyByOperationalDateSchema = {
+    agency_id: { type: 'LowCardinality(String)' },
+    operational_date: { type: 'UInt32' },
+    qty: { type: 'UInt64' },
+    updated_at: { type: 'Int64' },
+};

package/dist/types/simplified-apex.d.ts

@@ -0,0 +1,9 @@
+import { type ClickHouseTableSchema } from '@tmlmobilidade/go-clients-clickhouse';
+import { type SimplifiedApexBankingTap, SimplifiedApexInspection, SimplifiedApexInspectionDecision, SimplifiedApexLocation, SimplifiedApexOnBoardRefund, SimplifiedApexOnBoardSale, SimplifiedApexValidation } from '@tmlmobilidade/go-types-apex';
+export declare const simplifiedApexBankingTapSchema: ClickHouseTableSchema<SimplifiedApexBankingTap>;
+export declare const simplifiedApexInspectionDecisionSchema: ClickHouseTableSchema<SimplifiedApexInspectionDecision>;
+export declare const simplifiedApexInspectionSchema: ClickHouseTableSchema<SimplifiedApexInspection>;
+export declare const simplifiedApexLocationSchema: ClickHouseTableSchema<SimplifiedApexLocation>;
+export declare const simplifiedApexOnBoardRefundSchema: ClickHouseTableSchema<SimplifiedApexOnBoardRefund>;
+export declare const simplifiedApexOnBoardSaleSchema: ClickHouseTableSchema<SimplifiedApexOnBoardSale>;
+export declare const simplifiedApexValidationSchema: ClickHouseTableSchema<SimplifiedApexValidation>;

package/dist/types/simplified-apex.js

@@ -0,0 +1,170 @@
+/* * */
+/* * */
+export const simplifiedApexBankingTapSchema = {
+    _id: { type: 'UUID' },
+    agency_id: { type: 'LowCardinality(String)' },
+    apex_version: { type: 'LowCardinality(String)' },
+    banking_token: { type: 'String' },
+    card_brand: { type: 'UInt8' },
+    card_pan: { type: 'String' },
+    created_at: { type: 'Int64' },
+    device_id: { type: 'LowCardinality(String)' },
+    event_type: { type: 'UInt8' },
+    group_dimension: { type: 'Int32' },
+    is_ok: { type: 'Bool' },
+    is_ok_pcgi: { type: 'Bool' },
+    line_id: { type: 'LowCardinality(String)' },
+    mac_ase_counter_value: { type: 'UInt64' },
+    mac_sam_serial_number: { type: 'UInt64' },
+    operational_date: { type: 'UInt32' },
+    pattern_id: { type: 'LowCardinality(String)' },
+    product_id: { type: 'LowCardinality(String)' },
+    received_at: { type: 'Int64' },
+    stop_id: { type: 'LowCardinality(String)' },
+    trip_id: { type: 'Nullable(String)' },
+    updated_at: { type: 'Int64' },
+    vehicle_id: { type: 'LowCardinality(Nullable(String))' },
+};
+export const simplifiedApexInspectionDecisionSchema = {
+    _id: { type: 'UUID' },
+    agency_id: { type: 'LowCardinality(String)' },
+    apex_version: { type: 'LowCardinality(String)' },
+    created_at: { type: 'Int64' },
+    device_id: { type: 'LowCardinality(String)' },
+    final_control_status: { type: 'UInt8' },
+    inspection_id: { type: 'Nullable(UUID)' },
+    is_ok: { type: 'Bool' },
+    is_ok_pcgi: { type: 'Bool' },
+    mac_ase_counter_value: { type: 'UInt64' },
+    mac_sam_serial_number: { type: 'UInt64' },
+    operational_date: { type: 'UInt32' },
+    received_at: { type: 'Int64' },
+    updated_at: { type: 'Int64' },
+};
+export const simplifiedApexInspectionSchema = {
+    _id: { type: 'UUID' },
+    agency_id: { type: 'LowCardinality(String)' },
+    apex_version: { type: 'LowCardinality(String)' },
+    card_serial_number: { type: 'Nullable(UInt64)' },
+    control_destination_stop_id: { type: 'LowCardinality(Nullable(String))' },
+    control_origin_stop_id: { type: 'LowCardinality(Nullable(String))' },
+    control_status: { type: 'UInt8' },
+    created_at: { type: 'Int64' },
+    device_id: { type: 'LowCardinality(String)' },
+    environment_status: { type: 'UInt8' },
+    inspection_id: { type: 'Nullable(UUID)' },
+    is_ok: { type: 'Bool' },
+    is_ok_pcgi: { type: 'Bool' },
+    line_id: { type: 'LowCardinality(Nullable(String))' },
+    mac_ase_counter_value: { type: 'UInt64' },
+    mac_sam_serial_number: { type: 'UInt64' },
+    operational_date: { type: 'UInt32' },
+    pattern_id: { type: 'LowCardinality(Nullable(String))' },
+    product_id: { type: 'LowCardinality(Nullable(String))' },
+    received_at: { type: 'Int64' },
+    trip_id: { type: 'Nullable(String)' },
+    updated_at: { type: 'Int64' },
+    vehicle_id: { type: 'LowCardinality(Nullable(String))' },
+};
+export const simplifiedApexLocationSchema = {
+    _id: { type: 'UUID' },
+    agency_id: { type: 'LowCardinality(String)' },
+    apex_version: { type: 'LowCardinality(String)' },
+    created_at: { type: 'Int64' },
+    device_id: { type: 'LowCardinality(String)' },
+    is_ok: { type: 'Bool' },
+    is_ok_pcgi: { type: 'Bool' },
+    line_id: { type: 'LowCardinality(Nullable(String))' },
+    mac_ase_counter_value: { type: 'UInt64' },
+    mac_sam_serial_number: { type: 'UInt64' },
+    operational_date: { type: 'UInt32' },
+    pattern_id: { type: 'LowCardinality(Nullable(String))' },
+    received_at: { type: 'Int64' },
+    stop_id: { type: 'LowCardinality(Nullable(String))' },
+    trip_id: { type: 'Nullable(String)' },
+    updated_at: { type: 'Int64' },
+    vehicle_id: { type: 'LowCardinality(Nullable(String))' },
+};
+export const simplifiedApexOnBoardRefundSchema = {
+    _id: { type: 'UUID' },
+    agency_id: { type: 'LowCardinality(String)' },
+    apex_version: { type: 'LowCardinality(String)' },
+    card_physical_type: { type: 'UInt8' },
+    card_serial_number: { type: 'Nullable(UInt64)' },
+    created_at: { type: 'Int64' },
+    device_id: { type: 'LowCardinality(String)' },
+    is_ok: { type: 'Bool' },
+    is_ok_pcgi: { type: 'Bool' },
+    line_id: { type: 'LowCardinality(Nullable(String))' },
+    mac_ase_counter_value: { type: 'UInt64' },
+    mac_sam_serial_number: { type: 'UInt64' },
+    on_board_sale_id: { type: 'Nullable(UUID)' },
+    operational_date: { type: 'UInt32' },
+    pattern_id: { type: 'LowCardinality(Nullable(String))' },
+    payment_method: { type: 'UInt8' },
+    price: { type: 'Int32' },
+    product_id: { type: 'LowCardinality(Nullable(String))' },
+    product_quantity: { type: 'Int32' },
+    received_at: { type: 'Int64' },
+    stop_id: { type: 'LowCardinality(Nullable(String))' },
+    trip_id: { type: 'Nullable(String)' },
+    updated_at: { type: 'Int64' },
+    validation_id: { type: 'Nullable(UUID)' },
+    vehicle_id: { type: 'LowCardinality(Nullable(String))' },
+};
+export const simplifiedApexOnBoardSaleSchema = {
+    _id: { type: 'UUID' },
+    agency_id: { type: 'LowCardinality(String)' },
+    apex_version: { type: 'LowCardinality(String)' },
+    card_physical_type: { type: 'UInt8' },
+    card_serial_number: { type: 'Nullable(UInt64)' },
+    created_at: { type: 'Int64' },
+    device_id: { type: 'LowCardinality(String)' },
+    is_ok: { type: 'Bool' },
+    is_ok_pcgi: { type: 'Bool' },
+    is_passenger: { type: 'Bool' },
+    line_id: { type: 'LowCardinality(Nullable(String))' },
+    mac_ase_counter_value: { type: 'UInt64' },
+    mac_sam_serial_number: { type: 'UInt64' },
+    on_board_refund_id: { type: 'Nullable(UUID)' },
+    operational_date: { type: 'UInt32' },
+    pattern_id: { type: 'LowCardinality(Nullable(String))' },
+    payment_method: { type: 'UInt8' },
+    price: { type: 'Int32' },
+    product_id: { type: 'LowCardinality(Nullable(String))' },
+    product_quantity: { type: 'Int32' },
+    received_at: { type: 'Int64' },
+    stop_id: { type: 'LowCardinality(Nullable(String))' },
+    trip_id: { type: 'Nullable(String)' },
+    updated_at: { type: 'Int64' },
+    validation_id: { type: 'Nullable(UUID)' },
+    vehicle_id: { type: 'LowCardinality(Nullable(String))' },
+};
+export const simplifiedApexValidationSchema = {
+    _id: { type: 'UUID' },
+    agency_id: { type: 'LowCardinality(String)' },
+    apex_version: { type: 'LowCardinality(String)' },
+    card_serial_number: { type: 'Nullable(UInt64)' },
+    category: { type: 'LowCardinality(String)' },
+    created_at: { type: 'Int64' },
+    device_id: { type: 'LowCardinality(String)' },
+    event_type: { type: 'UInt8' },
+    is_ok: { type: 'Bool' },
+    is_ok_pcgi: { type: 'Bool' },
+    is_passenger: { type: 'Bool' },
+    line_id: { type: 'LowCardinality(Nullable(String))' },
+    mac_ase_counter_value: { type: 'UInt64' },
+    mac_sam_serial_number: { type: 'UInt64' },
+    on_board_refund_id: { type: 'Nullable(UUID)' },
+    on_board_sale_id: { type: 'Nullable(UUID)' },
+    operational_date: { type: 'UInt32' },
+    pattern_id: { type: 'LowCardinality(Nullable(String))' },
+    product_id: { type: 'LowCardinality(Nullable(String))' },
+    received_at: { type: 'Int64' },
+    stop_id: { type: 'LowCardinality(Nullable(String))' },
+    trip_id: { type: 'Nullable(String)' },
+    units_qty: { type: 'Nullable(Int32)' },
+    updated_at: { type: 'Int64' },
+    validation_status: { type: 'LowCardinality(String)' },
+    vehicle_id: { type: 'LowCardinality(Nullable(String))' },
+};

package/package.json

@@ -0,0 +1,56 @@
+{
+	"name": "@tmlmobilidade/go-interfaces-labdb",
+	"version": "20260717.1316.58",
+	"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-clients-clickhouse": "*",
+		"@tmlmobilidade/go-types-apex": "*",
+		"@tmlmobilidade/go-types-performance": "*",
+		"@tmlmobilidade/logger": "*",
+		"@tmlmobilidade/types": "*",
+		"@tmlmobilidade/utils": "*",
+		"luxon": "3.7.2",
+		"zod": "3.25.76"
+	},
+	"devDependencies": {
+		"@tmlmobilidade/tsconfig": "*",
+		"@types/luxon": "3.7.2",
+		"@types/node": "26.1.1",
+		"resolve-tspaths": "0.8.23",
+		"tsc-watch": "7.2.1",
+		"typescript": "6.0.3"
+	}
+}