@tmlmobilidade/databases 20260323.400.54

package/dist/utils/query-from-file.js

@@ -0,0 +1,42 @@
+/* * */
+import { prepareNamedQueryParams } from './prepare-named-query-params.js';
+import { Logger } from '@tmlmobilidade/logger';
+import { readFile } from 'node:fs/promises';
+/**
+ * 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 async function queryFromFile(client, filePath, params) {
+    let sql;
+    try {
+        sql = await readFile(filePath, { encoding: 'utf-8' });
+    }
+    catch (error) {
+        Logger.error(`CLICKHOUSE: Error @ queryFromFile(): Failed to read SQL file "${filePath}": ${error.message}`);
+        throw error;
+    }
+    const { query, queryParams } = prepareNamedQueryParams(sql, params, filePath);
+    try {
+        const result = await client.query({
+            format: 'JSONEachRow',
+            query,
+            query_params: queryParams,
+        });
+        return result.json();
+    }
+    catch (error) {
+        Logger.error(`CLICKHOUSE: Error @ queryFromFile(): Failed to execute query from file "${filePath}": ${error.message}`);
+        throw error;
+    }
+}

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

@@ -0,0 +1,14 @@
+import { type ClickHouseClient } from '@clickhouse/client';
+/**
+ * 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' }
+ * );
+ */
+export declare function queryFromString<T>(client: ClickHouseClient, query: string, params?: Record<string, number | string>): Promise<T[]>;

package/dist/utils/query-from-string.js

@@ -0,0 +1,31 @@
+/* * */
+import { preparePositionalQueryParams } from './prepare-positional-query-params.js';
+import { Logger } from '@tmlmobilidade/logger';
+/**
+ * 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' }
+ * );
+ */
+export async function queryFromString(client, query, params) {
+    // Validate query param keys and prepare the query statement
+    const preparedQuery = preparePositionalQueryParams(query, params);
+    try {
+        const result = await client.query({
+            format: 'JSONEachRow',
+            query: preparedQuery.query,
+            query_params: preparedQuery.query_params,
+        });
+        return result.json();
+    }
+    catch (error) {
+        Logger.error(`CLICKHOUSE: Error @ queryFromString(): Failed to execute query "${query}": ${error.message}`);
+        throw error;
+    }
+}

package/dist/utils/validate-sql-param.d.ts

@@ -0,0 +1,12 @@
+export declare const safeSqlParamRegex: RegExp;
+/**
+ * Validates that a given string is a safe SQL query parameter key,
+ * which must start with a letter or underscore and can only contain letters,
+ * numbers, or underscores. This is important to prevent SQL injection vulnerabilities
+ * when using dynamic query parameters.
+ * @param key The query parameter key to validate.
+ * @param throwOnInvalid Whether to throw an error if the key is invalid (default is true).
+ * @throws Will throw an error if the key is invalid and throwOnInvalid is true.
+ * @returns The validated query parameter key, or false if invalid and throwOnInvalid is false.
+ */
+export declare function validateSqlParam(key: string, throwOnInvalid?: boolean): false | string;

package/dist/utils/validate-sql-param.js

@@ -0,0 +1,23 @@
+/* * */
+export const safeSqlParamRegex = /^[a-zA-Z_][a-zA-Z0-9_]*$/;
+/**
+ * Validates that a given string is a safe SQL query parameter key,
+ * which must start with a letter or underscore and can only contain letters,
+ * numbers, or underscores. This is important to prevent SQL injection vulnerabilities
+ * when using dynamic query parameters.
+ * @param key The query parameter key to validate.
+ * @param throwOnInvalid Whether to throw an error if the key is invalid (default is true).
+ * @throws Will throw an error if the key is invalid and throwOnInvalid is true.
+ * @returns The validated query parameter key, or false if invalid and throwOnInvalid is false.
+ */
+export function validateSqlParam(key, throwOnInvalid = true) {
+    // Check if the key matches the safe SQL parameter regex
+    if (safeSqlParamRegex.test(key))
+        return key;
+    // If the key is invalid, either throw an error
+    // or return false based on the throwOnInvalid flag
+    if (throwOnInvalid)
+        throw new Error(`Invalid query parameter key: ${key}. Keys must start with a letter or underscore, followed by letters, numbers, or underscores.`);
+    else
+        return false;
+}

package/package.json

@@ -0,0 +1,53 @@
+{
+	"name": "@tmlmobilidade/databases",
+	"version": "20260323.400.54",
+	"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": {
+		"@clickhouse/client": "1.18.2",
+		"@tmlmobilidade/logger": "*",
+		"@tmlmobilidade/ssh": "*",
+		"@tmlmobilidade/types": "*",
+		"@tmlmobilidade/utils": "*",
+		"mongodb": "7.1.0"
+	},
+	"devDependencies": {
+		"@tmlmobilidade/tsconfig": "*",
+		"@types/node": "25.5.0",
+		"resolve-tspaths": "0.8.23",
+		"tsc-watch": "7.2.0",
+		"typescript": "5.9.3"
+	}
+}