@tmlmobilidade/databases 20260323.400.54

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

@@ -0,0 +1,61 @@
+/* * */
+import { GOClickHouseClient } from '../../clients/go-clickhouse.js';
+import { ClickHouseInterfaceTemplate } from '../../templates/clickhouse.js';
+import { asyncSingletonProxy } from '@tmlmobilidade/utils';
+/* * */
+const tableSchema = [
+    // Required Fields
+    { name: '_id', type: 'String' },
+    { name: 'agency_id', type: 'String' },
+    { name: 'created_at', type: 'UInt64' },
+    { name: 'latitude', type: 'Float64' },
+    { name: 'longitude', type: 'Float64' },
+    { name: 'received_at', type: 'UInt64' },
+    { name: 'trip_id', type: 'String' },
+    { name: 'vehicle_id', type: 'String' },
+    // Optional Fields
+    { name: 'bearing', type: 'Nullable(Float64)' },
+    { name: 'current_status', type: 'Nullable(String)' },
+    { name: 'door', type: 'Nullable(String)' },
+    { name: 'driver_id', type: 'Nullable(String)' },
+    { name: 'extra_trip_id', type: 'Nullable(String)' },
+    { name: 'odometer', type: 'Nullable(Float64)' },
+    { name: 'pattern_id', type: 'Nullable(String)' },
+    { name: 'stop_id', type: 'Nullable(String)' },
+];
+/* * */
+class SimplifiedVehicleEventsNewClass extends ClickHouseInterfaceTemplate {
+    //
+    static _instance = null;
+    databaseName = 'operation';
+    schema = tableSchema;
+    tableName = 'simplified_vehicle_events';
+    /**
+     * Returns the singleton instance of the subclass.
+     */
+    static async getInstance() {
+        // If no instance exists, create one and store the promise.
+        // This ensures that if multiple calls to getInstance() happen concurrently,
+        // they will all await the same initialization process.
+        if (!this._instance) {
+            this._instance = (async () => {
+                const instance = new SimplifiedVehicleEventsNewClass();
+                // This behaves like the constructor,
+                // but allows for async initialization.
+                await instance.init();
+                return instance;
+            })();
+        }
+        // Await the instance if it's still initializing,
+        // or return it immediately if ready.
+        return await this._instance;
+    }
+    connectToClient() {
+        return GOClickHouseClient.getClient();
+    }
+    async postInit() {
+        console.log('Post init ClickHouse service for Simplified Vehicle Events...');
+    }
+}
+/* * */
+export const simplifiedVehicleEventsNew = asyncSingletonProxy(SimplifiedVehicleEventsNewClass);

package/dist/templates/clickhouse.d.ts

@@ -0,0 +1,107 @@
+import { type ClickHouseColumn, type ClickHouseTableEngine } from '../types/index.js';
+import { type ClickHouseClient, type DataFormat } from '@clickhouse/client';
+export declare abstract class ClickHouseInterfaceTemplate<T> {
+    abstract readonly databaseName: string;
+    readonly engine: ClickHouseTableEngine;
+    readonly orderBy: string;
+    abstract readonly schema: ClickHouseColumn<T>[];
+    abstract readonly tableName: string;
+    private client;
+    /**
+     * Disallow direct instantiation of the service.
+     * Use getClient() instead to ensure singleton behavior.
+     */
+    protected constructor();
+    /**
+     * 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>): 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, 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[]>;
+    /**
+     * Abstract method to establish a connection to ClickHouse.
+     * This method must be implemented by subclasses to define the specific connection logic,
+     * such as handling SSH tunneling or configuring connection parameters.
+     */
+    protected abstract connectToClient(): Promise<ClickHouseClient>;
+    /**
+     * 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>;
+    /**
+     * 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.
+     */
+    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;
+    /**
+     * Constructs the appropriate engine string based on the provided engine type.
+     * @throws Will throw an error if an unsupported engine type is provided.
+     */
+    private getEngineString;
+}

package/dist/templates/clickhouse.js

@@ -0,0 +1,201 @@
+/* * */
+import { preparePositionalQueryParams } from '../utils/prepare-positional-query-params.js';
+import { queryFromString } from '../utils/query-from-string.js';
+import { validateSqlParam } from '../utils/validate-sql-param.js';
+import { Logger } from '@tmlmobilidade/logger';
+/* * */
+export class ClickHouseInterfaceTemplate {
+    engine = 'ReplicatedMergeTree';
+    orderBy = '_id';
+    client;
+    /**
+     * Disallow direct instantiation of the service.
+     * Use getClient() instead to ensure singleton behavior.
+     */
+    constructor() { }
+    /**
+     * 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 ${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.schema || this.schema.length === 0)
+            throw new Error('CLICKHOUSE: schema is required and cannot be empty.');
+        // Connect to the ClickHouse client
+        this.client = await this.connectToClient();
+        // Ensure the database and table exist, and perform any additional setup
+        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
+    }
+    /**
+     * 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.
+     */
+    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}" on CLUSTER default_cluster;` });
+            Logger.info(`CLICKHOUSE [${this.databaseName}]: Database created.`);
+        }
+        catch (error) {
+            Logger.error(`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.`);
+        if (!validateSqlParam(this.engine, false))
+            throw new Error(`CLICKHOUSE [${this.engine}]: Unsafe engine type provided.`);
+        if (!validateSqlParam(this.orderBy, false))
+            throw new Error(`CLICKHOUSE [${this.orderBy}]: Unsafe orderBy clause provided.`);
+        // Validate the schema columns are safe identifiers
+        const unsafeColumns = this.schema.filter(column => !validateSqlParam(column.name, false)).map(column => column.name);
+        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}" ON CLUSTER default_cluster (
+				${this.schema.map(column => `${column.name} ${column.type}`).join(', ')}
+			) ENGINE = ${this.getEngineString()}
+			ORDER BY ${this.orderBy}
+		`;
+        // Perform the query to create the table
+        try {
+            await this.client.command({ query: createTableQuery });
+            Logger.info(`CLICKHOUSE [${this.tableName}]: Table created.`);
+        }
+        catch (error) {
+            Logger.error(`CLICKHOUSE [${this.tableName}]: Error @ createTable(): ${error.message}`);
+            throw error;
+        }
+    }
+    /**
+     * Constructs the appropriate engine string based on the provided engine type.
+     * @throws Will throw an error if an unsupported engine type is provided.
+     */
+    getEngineString() {
+        switch (this.engine) {
+            case 'ReplicatedMergeTree':
+                return `ReplicatedMergeTree('/clickhouse/tables/{shard}/${this.databaseName}/${this.tableName}', '{replica}')`;
+            default:
+                throw new Error(`CLICKHOUSE [${this.databaseName}/${this.tableName}]: Unsupported engine type: ${this.engine}`);
+        }
+    }
+}

package/dist/types/clickhouse/column.d.ts

@@ -0,0 +1,36 @@
+import { type ClickHouseDataType } from './data-types.js';
+/**
+ * Definition of a ClickHouse column,
+ * including its name, type, and various optional properties.
+ */
+export interface ClickHouseColumn<T> {
+    /** Alias expression (computed on read) */
+    alias?: string;
+    /** Column codec for compression */
+    codec?: string;
+    /** Comment for the column */
+    comment?: string;
+    /** Default value expression */
+    default?: string;
+    /** Create a secondary index (skipping index) on this column */
+    indexed?: boolean;
+    /** Granularity for the index. Default: 4 */
+    indexGranularity?: number;
+    /** Type of skipping index. Default: 'minmax' */
+    indexType?: 'bloom_filter' | 'minmax' | 'ngrambf_v1' | 'set' | 'tokenbf_v1';
+    /** Use LowCardinality wrapper for low-cardinality strings */
+    lowCardinality?: boolean;
+    /** Materialized value expression (computed on insert) */
+    materialized?: string;
+    name: Extract<keyof T, string>;
+    /** Whether the column can be null (wraps type in Nullable) */
+    nullable?: boolean;
+    /** Include this column in the ORDER BY clause (ClickHouse's primary index) */
+    primaryKey?: boolean;
+    /** Order of this column in the primary key (lower = first). Default: 0 */
+    primaryKeyOrder?: number;
+    /** TTL expression for this column */
+    ttl?: string;
+    /** The ClickHouse data type */
+    type: ClickHouseDataType;
+}

package/dist/types/clickhouse/column.js

@@ -0,0 +1,2 @@
+/* * */
+export {};

package/dist/types/clickhouse/data-types.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Supported ClickHouse data types that
+ * can be used in ClickHouse table schemas.
+ */
+export type ClickHouseDataType = 'Bool' | 'Boolean' | 'Date32' | 'Date' | 'DateTime' | 'Decimal' | 'Float32' | 'Float64' | 'Int8' | 'Int16' | 'Int32' | 'Int64' | 'Int128' | 'Int256' | 'String' | 'UInt8' | 'UInt16' | 'UInt32' | 'UInt64' | 'UInt128' | 'UInt256' | 'UUID' | `Array(${string})` | `DateTime64(${number})` | `Decimal(${number}, ${number})` | `Enum8(${string})` | `Enum16(${string})` | `FixedString(${number})` | `LowCardinality(${string})` | `Map(${string}, ${string})` | `Nullable(${string})`;

package/dist/types/clickhouse/data-types.js

@@ -0,0 +1 @@
+export {};

package/dist/types/clickhouse/index.d.ts

@@ -0,0 +1,3 @@
+export * from './column.js';
+export * from './data-types.js';
+export * from './table-engines.js';

package/dist/types/clickhouse/index.js

@@ -0,0 +1,3 @@
+export * from './column.js';
+export * from './data-types.js';
+export * from './table-engines.js';

package/dist/types/clickhouse/table-engines.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Definition for allowed ClickHouse table engines.
+ * Please avoid using other engines before consulting with the team
+ * as ClickHouse has many engines with different features and limitations.
+ * For example, only `ReplicatedMergeTree` supports automatic replication.
+ */
+export type ClickHouseTableEngine = 'ReplicatedMergeTree';

package/dist/types/clickhouse/table-engines.js

@@ -0,0 +1 @@
+export {};

package/dist/types/index.d.ts

@@ -0,0 +1 @@
+export * from './clickhouse/index.js';

package/dist/types/index.js

@@ -0,0 +1 @@
+export * from './clickhouse/index.js';

package/dist/utils/get-clickhouse-param-type.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Determines the appropriate ClickHouse parameter type based on the value's JavaScript type.
+ * This is used to convert untyped query placeholders into typed ClickHouse parameters.
+ * @param value
+ * @returns
+ */
+export declare function getClickHouseParamType(value: number | string): 'Float64' | 'Int64' | 'String';

package/dist/utils/get-clickhouse-param-type.js

@@ -0,0 +1,16 @@
+/* * */
+/**
+ * Determines the appropriate ClickHouse parameter type based on the value's JavaScript type.
+ * This is used to convert untyped query placeholders into typed ClickHouse parameters.
+ * @param value
+ * @returns
+ */
+export function getClickHouseParamType(value) {
+    if (typeof value === 'number') {
+        if (!Number.isFinite(value)) {
+            throw new Error('CLICKHOUSE: Query params do not support non-finite numbers.');
+        }
+        return Number.isInteger(value) ? 'Int64' : 'Float64';
+    }
+    return 'String';
+}

package/dist/utils/index.d.ts

@@ -0,0 +1,3 @@
+export * from './prepare-named-query-params.js';
+export * from './prepare-positional-query-params.js';
+export * from './validate-sql-param.js';

package/dist/utils/index.js

@@ -0,0 +1,3 @@
+export * from './prepare-named-query-params.js';
+export * from './prepare-positional-query-params.js';
+export * from './validate-sql-param.js';

package/dist/utils/prepare-named-query-params.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Prepares a SQL query with named parameters by validating the parameter keys
+ * and ensuring that all provided parameters are used in the query. It also converts untyped
+ * placeholders (e.g., {name}) into typed ClickHouse parameters (e.g., {name:Type}) based on
+ * the value type. This function is essential for safely constructing SQL queries with dynamic
+ * parameters while preventing SQL injection vulnerabilities.
+ * @param query The SQL query string containing named parameters in the format {paramName} or {paramName:Type}.
+ * @param params An optional object mapping parameter names to their values. The keys must be valid SQL parameter names.
+ * @param context An optional string providing context for error messages (e.g., the name of the query or operation).
+ * @throws Will throw an error if any parameter key is invalid, if there are missing parameters required by the query, or if there are unused parameters provided.
+ * @returns An object containing the normalized query string with typed parameters and a mapping of parameter names to their values.
+ */
+export declare function prepareNamedQueryParams(query: string, params?: Record<string, number | string>, context?: string): {
+    query: string;
+    queryParams: Record<string, number | string>;
+};

package/dist/utils/prepare-named-query-params.js

@@ -0,0 +1,47 @@
+/* * */
+import { validateSqlParam } from './validate-sql-param.js';
+/**
+ * Prepares a SQL query with named parameters by validating the parameter keys
+ * and ensuring that all provided parameters are used in the query. It also converts untyped
+ * placeholders (e.g., {name}) into typed ClickHouse parameters (e.g., {name:Type}) based on
+ * the value type. This function is essential for safely constructing SQL queries with dynamic
+ * parameters while preventing SQL injection vulnerabilities.
+ * @param query The SQL query string containing named parameters in the format {paramName} or {paramName:Type}.
+ * @param params An optional object mapping parameter names to their values. The keys must be valid SQL parameter names.
+ * @param context An optional string providing context for error messages (e.g., the name of the query or operation).
+ * @throws Will throw an error if any parameter key is invalid, if there are missing parameters required by the query, or if there are unused parameters provided.
+ * @returns An object containing the normalized query string with typed parameters and a mapping of parameter names to their values.
+ */
+export function prepareNamedQueryParams(query, params, context) {
+    const queryParams = {};
+    const providedParams = params ?? {};
+    const usedKeys = new Set();
+    for (const key of Object.keys(providedParams)) {
+        validateSqlParam(key);
+    }
+    // Backward compatibility: convert untyped placeholders ({name}) into typed ClickHouse params.
+    const normalizedQuery = query.replace(/\{([A-Za-z_][A-Za-z0-9_]*)\}/g, (_, key) => {
+        if (!(key in providedParams)) {
+            throw new Error(`CLICKHOUSE "${context ?? 'query'}": Missing query param: ${key}`);
+        }
+        usedKeys.add(key);
+        const value = providedParams[key];
+        queryParams[key] = value;
+        return `{${key}:${this.getClickHouseParamType(value)}}`;
+    });
+    // Also include explicitly typed placeholders already present in query (e.g. {id:UInt64}).
+    for (const match of normalizedQuery.matchAll(/\{([A-Za-z_][A-Za-z0-9_]*):[^}]+\}/g)) {
+        const key = match[1];
+        if (!(key in providedParams)) {
+            throw new Error(`CLICKHOUSE "${context ?? 'query'}": Missing query param: ${key}`);
+        }
+        usedKeys.add(key);
+        queryParams[key] = providedParams[key];
+    }
+    for (const key of Object.keys(providedParams)) {
+        if (!usedKeys.has(key)) {
+            throw new Error(`CLICKHOUSE "${context ?? 'query'}": Unused query param: ${key}`);
+        }
+    }
+    return { query: normalizedQuery, queryParams };
+}

package/dist/utils/prepare-positional-query-params.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Prepares a SQL query with positional parameters by replacing placeholders
+ * in the format of $1, $2, etc., with ClickHouse's named parameter syntax.
+ * It also validates that all provided parameters are used in the query and that their keys are valid.
+ * @param query The SQL query containing positional placeholders (e.g., $1, $2).
+ * @param params An optional object mapping parameter indices (as strings) to their values.
+ * @throws Will throw an error if a placeholder is missing a corresponding parameter, if there are unused parameters, or if any parameter keys are invalid.
+ * @returns An object containing the transformed query and a mapping of named parameters to their values.
+ */
+export declare function preparePositionalQueryParams(query: string, params?: Record<string, number | string>): {
+    query: string;
+    query_params: Record<string, number | string>;
+};

package/dist/utils/prepare-positional-query-params.js

@@ -0,0 +1,36 @@
+/* * */
+import { getClickHouseParamType } from './get-clickhouse-param-type.js';
+/**
+ * Prepares a SQL query with positional parameters by replacing placeholders
+ * in the format of $1, $2, etc., with ClickHouse's named parameter syntax.
+ * It also validates that all provided parameters are used in the query and that their keys are valid.
+ * @param query The SQL query containing positional placeholders (e.g., $1, $2).
+ * @param params An optional object mapping parameter indices (as strings) to their values.
+ * @throws Will throw an error if a placeholder is missing a corresponding parameter, if there are unused parameters, or if any parameter keys are invalid.
+ * @returns An object containing the transformed query and a mapping of named parameters to their values.
+ */
+export function preparePositionalQueryParams(query, params) {
+    const queryParams = {};
+    const providedParams = params ?? {};
+    const usedKeys = new Set();
+    const normalizedQuery = query.replace(/\$(\d+)/g, (_, index) => {
+        const key = String(index);
+        if (!(key in providedParams)) {
+            throw new Error(`CLICKHOUSE "${query}": Missing query param: $${key}`);
+        }
+        usedKeys.add(key);
+        const queryParamKey = `p${key}`;
+        const value = providedParams[key];
+        queryParams[queryParamKey] = value;
+        return `{${queryParamKey}:${getClickHouseParamType(value)}}`;
+    });
+    for (const key of Object.keys(providedParams)) {
+        if (!/^\d+$/.test(key)) {
+            throw new Error(`CLICKHOUSE "${query}": Invalid positional query param key: "${key}"`);
+        }
+        if (!usedKeys.has(key)) {
+            throw new Error(`CLICKHOUSE "${query}": Unused query param: $${key}`);
+        }
+    }
+    return { query: normalizedQuery, query_params: queryParams };
+}

package/dist/utils/query-from-file.d.ts

@@ -0,0 +1,17 @@
+import { type ClickHouseClient } from '@clickhouse/client';
+/**
+ * Executes a query from a .sql file with optional parameter substitutions.
+ * @param client The ClickHouse client to use for executing the query.
+ * @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',
+ * });
+ */
+export declare function queryFromFile<T>(client: ClickHouseClient, filePath: string, params?: Record<string, number | string>): Promise<T[]>;