@hypequery/clickhouse 0.2.1 → 0.2.2

package/dist/cli/bin.js

@@ -37,27 +37,84 @@ ${colors.dim}Generate TypeScript types from your ClickHouse database schema${col
 function showHelp() {
   console.log(`
 ${colors.bright}Usage:${colors.reset}
-  npx hypequery-generate-types [output-path] [options]
+  npx hypequery-generate-types [options]
 
-${colors.bright}Arguments:${colors.reset}
-  output-path                Path where TypeScript definitions will be saved (default: "./generated-schema.ts")
+${colors.bright}Options:${colors.reset}
+  --output=<path>            Path where TypeScript definitions will be saved (default: "./generated-schema.ts")
+  --host=<url>               ClickHouse server URL (default: http://localhost:8123)
+  --username=<user>          ClickHouse username (default: default)
+  --password=<password>      ClickHouse password
+  --database=<db>            ClickHouse database name (default: default)
+  --include-tables=<tables>  Comma-separated list of tables to include (default: all)
+  --exclude-tables=<tables>  Comma-separated list of tables to exclude (default: none)
+  --secure                   Use HTTPS/TLS for connection
+  --help, -h                 Show this help text
 
 ${colors.bright}Environment variables:${colors.reset}
-  CLICKHOUSE_HOST            ClickHouse server URL (default: http://localhost:8123)
-  CLICKHOUSE_USER            ClickHouse username (default: default)
+  CLICKHOUSE_HOST            ClickHouse server URL
+  VITE_CLICKHOUSE_HOST       Alternative variable for Vite projects
+  NEXT_PUBLIC_CLICKHOUSE_HOST Alternative variable for Next.js projects
+  
+  CLICKHOUSE_USER            ClickHouse username
+  VITE_CLICKHOUSE_USER       Alternative variable for Vite projects
+  NEXT_PUBLIC_CLICKHOUSE_USER Alternative variable for Next.js projects
+  
   CLICKHOUSE_PASSWORD        ClickHouse password
-  CLICKHOUSE_DATABASE        ClickHouse database name (default: default)
+  VITE_CLICKHOUSE_PASSWORD   Alternative variable for Vite projects
+  NEXT_PUBLIC_CLICKHOUSE_PASSWORD Alternative variable for Next.js projects
+  
+  CLICKHOUSE_DATABASE        ClickHouse database name
+  VITE_CLICKHOUSE_DATABASE   Alternative variable for Vite projects
+  NEXT_PUBLIC_CLICKHOUSE_DATABASE Alternative variable for Next.js projects
 
 ${colors.bright}Examples:${colors.reset}
   npx hypequery-generate-types
-  npx hypequery-generate-types ./src/types/db-schema.ts
-  CLICKHOUSE_HOST=http://my-clickhouse:8123 npx hypequery-generate-types
-
-${colors.bright}Options:${colors.reset}
-  --help, -h                 Show this help text
+  npx hypequery-generate-types --output=./src/types/db-schema.ts
+  npx hypequery-generate-types --host=https://your-instance.clickhouse.cloud:8443 --secure
+  npx hypequery-generate-types --host=http://localhost:8123 --username=default --password=password --database=my_db
+  npx hypequery-generate-types --include-tables=users,orders,products
   `);
 }
 
+/**
+ * Parse command line arguments into a configuration object
+ */
+function parseArguments(args) {
+  const config = {
+    output: './generated-schema.ts',
+    includeTables: [],
+    excludeTables: [],
+    secure: false
+  };
+
+  for (const arg of args) {
+    if (arg.startsWith('--output=')) {
+      config.output = arg.substring('--output='.length);
+    } else if (arg.startsWith('--host=')) {
+      config.host = arg.substring('--host='.length);
+    } else if (arg.startsWith('--username=')) {
+      config.username = arg.substring('--username='.length);
+    } else if (arg.startsWith('--password=')) {
+      config.password = arg.substring('--password='.length);
+    } else if (arg.startsWith('--database=')) {
+      config.database = arg.substring('--database='.length);
+    } else if (arg.startsWith('--include-tables=')) {
+      config.includeTables = arg.substring('--include-tables='.length).split(',');
+    } else if (arg.startsWith('--exclude-tables=')) {
+      config.excludeTables = arg.substring('--exclude-tables='.length).split(',');
+    } else if (arg === '--secure') {
+      config.secure = true;
+    } else if (arg === '--help' || arg === '-h') {
+      config.showHelp = true;
+    } else if (!arg.startsWith('-') && !config.output) {
+      // For backwards compatibility, treat the first non-flag argument as the output path
+      config.output = arg;
+    }
+  }
+
+  return config;
+}
+
 /**
  * Main CLI function
  */
@@ -66,55 +123,82 @@ async function main() {
 
   // Process command line arguments
   const args = process.argv.slice(2);
+  const config = parseArguments(args);
 
   // Check for help flag
-  if (args.includes('--help') || args.includes('-h')) {
+  if (config.showHelp) {
     showHelp();
     return;
   }
 
-  // Get output path (default or from args)
-  const outputPath = args.length > 0 && !args[0].startsWith('-')
-    ? args[0]
-    : './generated-schema.ts';
-
   try {
-    // Display connection info
-    const host = process.env.VITE_CLICKHOUSE_HOST || process.env.CLICKHOUSE_HOST || 'http://localhost:8123';
-    const database = process.env.VITE_CLICKHOUSE_DATABASE || process.env.CLICKHOUSE_DATABASE || 'default';
+    // Get connection parameters from args and environment variables
+    const host = config.host ||
+      process.env.CLICKHOUSE_HOST ||
+      process.env.VITE_CLICKHOUSE_HOST ||
+      process.env.NEXT_PUBLIC_CLICKHOUSE_HOST ||
+      'http://localhost:8123';
+
+    const username = config.username ||
+      process.env.CLICKHOUSE_USER ||
+      process.env.VITE_CLICKHOUSE_USER ||
+      process.env.NEXT_PUBLIC_CLICKHOUSE_USER ||
+      'default';
+
+    const password = config.password ||
+      process.env.CLICKHOUSE_PASSWORD ||
+      process.env.VITE_CLICKHOUSE_PASSWORD ||
+      process.env.NEXT_PUBLIC_CLICKHOUSE_PASSWORD;
+
+    const database = config.database ||
+      process.env.CLICKHOUSE_DATABASE ||
+      process.env.VITE_CLICKHOUSE_DATABASE ||
+      process.env.NEXT_PUBLIC_CLICKHOUSE_DATABASE ||
+      'default';
 
     console.log(`${colors.dim}Connecting to ClickHouse at ${colors.reset}${colors.bright}${host}${colors.reset}`);
     console.log(`${colors.dim}Database: ${colors.reset}${colors.bright}${database}${colors.reset}`);
 
-    // Initialize connection from env vars
-    ClickHouseConnection.initialize({
+    // Configure connection
+    const connectionConfig = {
       host,
-      username: process.env.VITE_CLICKHOUSE_USER || process.env.CLICKHOUSE_USER || 'default',
-      password: process.env.VITE_CLICKHOUSE_PASSWORD || process.env.CLICKHOUSE_PASSWORD,
+      username,
+      password,
       database,
-    });
+    };
+
+    // Add secure connection options if needed
+    if (config.secure || host.startsWith('https://')) {
+      connectionConfig.secure = true;
+    }
+
+    // Initialize connection
+    ClickHouseConnection.initialize(connectionConfig);
 
     console.log(`${colors.dim}Generating TypeScript definitions...${colors.reset}`);
 
     // Ensure directory exists
-    const dir = path.dirname(path.resolve(outputPath));
+    const dir = path.dirname(path.resolve(config.output));
     await fs.mkdir(dir, { recursive: true });
 
     // Generate types
-    await generateTypes(outputPath);
+    await generateTypes(config.output, {
+      includeTables: config.includeTables.length > 0 ? config.includeTables : undefined,
+      excludeTables: config.excludeTables.length > 0 ? config.excludeTables : undefined
+    });
 
-    console.log(`${colors.green}✓ Success! ${colors.reset}Types generated at ${colors.bright}${path.resolve(outputPath)}${colors.reset}`);
+    console.log(`${colors.green}✓ Success! ${colors.reset}Types generated at ${colors.bright}${path.resolve(config.output)}${colors.reset}`);
     console.log(`
 ${colors.dim}To use these types in your project:${colors.reset}
 
 import { createQueryBuilder } from '@hypequery/clickhouse';
-import { IntrospectedSchema } from '${outputPath.replace(/\.ts$/, '')}';
+import { IntrospectedSchema } from '${config.output.replace(/\.ts$/, '')}';
 
 const db = createQueryBuilder<IntrospectedSchema>({
-  host: process.env.CLICKHOUSE_HOST,
-  username: process.env.CLICKHOUSE_USER,
-  password: process.env.CLICKHOUSE_PASSWORD,
-  database: process.env.CLICKHOUSE_DATABASE,
+  host: '${host}',
+  username: '${username}',
+  password: '********',
+  database: '${database}'
 });
 `);
   } catch (error) {
@@ -124,21 +208,29 @@ const db = createQueryBuilder<IntrospectedSchema>({
     if (error.message && error.message.includes('ECONNREFUSED')) {
       console.error(`
 ${colors.yellow}Connection refused.${colors.reset} Please check:
-- Is ClickHouse running at ${process.env.CLICKHOUSE_HOST || 'http://localhost:8123'}?
+- Is ClickHouse running at the specified host?
 - Do you need to provide authentication credentials?
 - Are there any network/firewall restrictions?
+- For cloud instances, did you include the port (usually 8443) and use HTTPS?
 `);
     } else if (error.message && error.message.includes('Authentication failed')) {
       console.error(`
 ${colors.yellow}Authentication failed.${colors.reset} Please check:
-- Are your CLICKHOUSE_USER and CLICKHOUSE_PASSWORD environment variables set correctly?
+- Are your username and password correct?
+- For ClickHouse Cloud, did you use the correct credentials from your cloud dashboard?
 - Does the user have sufficient permissions?
 `);
     } else if (error.message && error.message.includes('database does not exist')) {
       console.error(`
 ${colors.yellow}Database not found.${colors.reset} Please check:
-- Is the CLICKHOUSE_DATABASE environment variable set correctly?
+- Is the database name correct?
 - Does the database exist in your ClickHouse instance?
+`);
+    } else if (error.message && error.message.includes('certificate')) {
+      console.error(`
+${colors.yellow}SSL/TLS certificate issue.${colors.reset} For secure connections:
+- Try adding the --secure flag
+- For ClickHouse Cloud, make sure you're using https:// and port 8443
 `);
     }
 

package/dist/cli/generate-types.js

@@ -12,6 +12,12 @@ dotenv.config();
  * @property {string} type - The ClickHouse type of the column
  */
 
+/**
+ * @typedef {Object} GenerateTypesOptions
+ * @property {string[]} [includeTables] - List of tables to include
+ * @property {string[]} [excludeTables] - List of tables to exclude
+ */
+
 /**
  * Converts ClickHouse types to TypeScript types
  * @param {string} type - The ClickHouse type to convert
@@ -20,55 +26,92 @@ dotenv.config();
 const clickhouseToTsType = (type) => {
   if (type.startsWith('Array(')) {
     const innerType = type.slice(6, -1);
-    return `Array(${clickhouseToTsType(innerType)})`;
+    return `Array<${clickhouseToTsType(innerType)}>`;
+  }
+
+  // Handle Nullable types
+  if (type.startsWith('Nullable(')) {
+    const innerType = type.slice(9, -1);
+    return `${clickhouseToTsType(innerType)} | null`;
   }
 
   switch (type.toLowerCase()) {
     case 'string':
     case 'fixedstring':
-      return 'String';
+      return 'string';
     case 'int8':
     case 'int16':
     case 'int32':
-      return 'Int32';
+    case 'uint8':
+    case 'uint16':
+    case 'uint32':
+      return 'number';
     case 'int64':
-      return 'Int64';
+    case 'uint64':
+      return 'string'; // Use string for 64-bit integers to avoid precision loss
     case 'float32':
     case 'float64':
-      return 'Float64';
+    case 'decimal':
+      return 'number';
     case 'datetime':
-      return 'DateTime';
+    case 'datetime64':
+      return 'string'; // Use string for datetime
     case 'date':
-      return 'Date';
+    case 'date32':
+      return 'string'; // Use string for date
+    case 'bool':
+    case 'boolean':
+      return 'boolean';
     default:
-      return 'String';
+      // For complex types or unknown types, return string as a safe default
+      return 'string';
   }
 };
 
 /**
  * Generates TypeScript type definitions from the ClickHouse database schema
  * @param {string} outputPath - The file path where the type definitions will be written
+ * @param {GenerateTypesOptions} [options] - Options for type generation
  * @returns {Promise<void>}
  */
-export async function generateTypes(outputPath) {
+export async function generateTypes(outputPath, options = {}) {
   const client = ClickHouseConnection.getClient();
+  const { includeTables = [], excludeTables = [] } = options;
 
   // Get all tables
   const tablesQuery = await client.query({
     query: 'SHOW TABLES',
     format: 'JSONEachRow'
   });
-  const tables = await tablesQuery.json();
+  let tables = await tablesQuery.json();
+
+  // Filter tables if includeTables or excludeTables are specified
+  if (includeTables.length > 0) {
+    tables = tables.filter(table => includeTables.includes(table.name));
+  }
+
+  if (excludeTables.length > 0) {
+    tables = tables.filter(table => !excludeTables.includes(table.name));
+  }
+
+  // If no tables remain after filtering, log a warning
+  if (tables.length === 0) {
+    console.warn('Warning: No tables match the filter criteria. Check your include/exclude options.');
+  }
 
   let typeDefinitions = `// Generated by @hypequery/clickhouse
-import { ColumnType } from '@hypequery/clickhouse';
+// This file defines TypeScript types based on your ClickHouse database schema
 
+/**
+ * Schema interface for use with createQueryBuilder<IntrospectedSchema>()
+ * The string literals represent ClickHouse data types for each column
+ */
 export interface IntrospectedSchema {`;
 
   // Get columns for each table
   for (const table of tables) {
     const columnsQuery = await client.query({
-      query: `DESCRIBE ${table.name}`,
+      query: `DESCRIBE TABLE ${table.name}`,
       format: 'JSONEachRow'
     });
     const columns = await columnsQuery.json();
@@ -82,10 +125,56 @@ export interface IntrospectedSchema {`;
 
   typeDefinitions += '\n}\n';
 
+  // Also generate a type-safe record type for each table
+  typeDefinitions += `\n// Type-safe record types for each table\n`;
+  for (const table of tables) {
+    const columnsQuery = await client.query({
+      query: `DESCRIBE TABLE ${table.name}`,
+      format: 'JSONEachRow'
+    });
+    const columns = await columnsQuery.json();
+
+    typeDefinitions += `export interface ${capitalizeFirstLetter(table.name)}Record {`;
+    for (const column of columns) {
+      const tsType = clickhouseToTsType(column.type).replace(/'/g, '');
+      typeDefinitions += `\n  ${column.name}: ${tsType};`;
+    }
+    typeDefinitions += '\n}\n\n';
+  }
+
+  // Add a usage example
+  typeDefinitions += `
+/**
+ * Usage example:
+ * 
+ * import { createQueryBuilder } from '@hypequery/clickhouse';
+ * import { IntrospectedSchema } from './path-to-this-file';
+ * 
+ * // Create a type-safe query builder
+ * const db = createQueryBuilder<IntrospectedSchema>();
+ * 
+ * // Now you have full type safety and autocomplete
+ * const results = await db
+ *   .from('${tables.length > 0 ? tables[0].name : 'table_name'}')
+ *   .select(['column1', 'column2'])
+ *   .where('column1', 'eq', 'value')
+ *   .execute();
+ */
+`;
+
   // Ensure the output directory exists
   const outputDir = path.dirname(path.resolve(outputPath));
   await fs.mkdir(outputDir, { recursive: true });
 
   // Write the file
   await fs.writeFile(path.resolve(outputPath), typeDefinitions);
+}
+
+/**
+ * Capitalize the first letter of a string
+ * @param {string} str - The string to capitalize
+ * @returns {string} - The capitalized string
+ */
+function capitalizeFirstLetter(str) {
+  return str.charAt(0).toUpperCase() + str.slice(1);
 } 

package/dist/core/connection.d.ts

@@ -0,0 +1,145 @@
+import { createClient } from '@clickhouse/client-web';
+import type { ClickHouseSettings } from '@clickhouse/client-web';
+/**
+ * Configuration options for the ClickHouse connection.
+ *
+ * @category Core
+ * @example
+ * ```typescript
+ * const config = {
+ *   host: 'http://localhost:8123',
+ *   username: 'default',
+ *   password: 'password',
+ *   database: 'my_database'
+ * };
+ * ```
+ */
+export interface ClickHouseConnectionOptions {
+    /**
+     * The URL of the ClickHouse server, including protocol and port.
+     * Example: 'http://localhost:8123' or 'https://your-instance.clickhouse.cloud:8443'
+     */
+    host: string;
+    /**
+     * Username for authentication. Defaults to 'default' if not provided.
+     */
+    username?: string;
+    /**
+     * Password for authentication.
+     */
+    password?: string;
+    /**
+     * The database to connect to. Defaults to 'default' if not provided.
+     */
+    database?: string;
+    /**
+     * Enable secure connection (TLS/SSL).
+     * This is automatically set to true if the host URL starts with https://
+     */
+    secure?: boolean;
+    /**
+     * Custom HTTP headers to include with each request.
+     */
+    http_headers?: Record<string, string>;
+    /**
+     * Request timeout in milliseconds.
+     */
+    request_timeout?: number;
+    /**
+     * Compression options for the connection.
+     */
+    compression?: {
+        response?: boolean;
+        request?: boolean;
+    };
+    /**
+     * Application name to identify in ClickHouse server logs.
+     */
+    application?: string;
+    /**
+     * Keep-alive connection settings.
+     */
+    keep_alive?: {
+        enabled: boolean;
+    };
+    /**
+     * Logger configuration.
+     */
+    log?: any;
+    /**
+     * Additional ClickHouse-specific settings.
+     */
+    clickhouse_settings?: ClickHouseSettings;
+}
+/**
+ * The main entry point for connecting to a ClickHouse database.
+ * Provides static methods to initialize the connection and retrieve the client.
+ *
+ * @category Core
+ * @example
+ * ```typescript
+ * // Initialize the connection
+ * ClickHouseConnection.initialize({
+ *   host: 'http://localhost:8123',
+ *   username: 'default',
+ *   password: 'password',
+ *   database: 'my_database'
+ * });
+ *
+ * // Get the client to execute queries directly
+ * const client = ClickHouseConnection.getClient();
+ * const result = await client.query({
+ *   query: 'SELECT * FROM my_table',
+ *   format: 'JSONEachRow'
+ * });
+ * ```
+ */
+export declare class ClickHouseConnection {
+    private static instance;
+    /**
+     * Initializes the ClickHouse connection with the provided configuration.
+     * This method must be called before any queries can be executed.
+     *
+     * @param config - The connection configuration options
+     * @returns The ClickHouseConnection class for method chaining
+     * @throws Will throw an error if the connection cannot be established
+     *
+     * @example
+     * ```typescript
+     * // For a local ClickHouse instance
+     * ClickHouseConnection.initialize({
+     *   host: 'http://localhost:8123',
+     *   username: 'default',
+     *   password: 'password',
+     *   database: 'my_database'
+     * });
+     *
+     * // For a ClickHouse Cloud instance
+     * ClickHouseConnection.initialize({
+     *   host: 'https://your-instance.clickhouse.cloud:8443',
+     *   username: 'default',
+     *   password: 'your-password',
+     *   database: 'my_database',
+     *   secure: true
+     * });
+     * ```
+     */
+    static initialize(config: ClickHouseConnectionOptions): typeof ClickHouseConnection;
+    /**
+     * Retrieves the ClickHouse client instance for direct query execution.
+     *
+     * @returns The ClickHouse client instance
+     * @throws Will throw an error if the connection has not been initialized
+     *
+     * @example
+     * ```typescript
+     * const client = ClickHouseConnection.getClient();
+     * const result = await client.query({
+     *   query: 'SELECT * FROM my_table',
+     *   format: 'JSONEachRow'
+     * });
+     * ```
+     */
+    static getClient(): ReturnType<typeof createClient>;
+}
+//# sourceMappingURL=connection.d.ts.map

package/dist/core/connection.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"connection.d.ts","sourceRoot":"","sources":["../../src/core/connection.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AACtD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,wBAAwB,CAAC;AAWjE,MAAM,WAAW,2BAA2B;IAC1C,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACtC,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,WAAW,CAAC,EAAE;QACZ,QAAQ,CAAC,EAAE,OAAO,CAAC;QACnB,OAAO,CAAC,EAAE,OAAO,CAAC;KACnB,CAAC;IACF,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,UAAU,CAAC,EAAE;QACX,OAAO,EAAE,OAAO,CAAC;KAClB,CAAC;IAEF,GAAG,CAAC,EAAE,GAAG,CAAC;IACV,mBAAmB,CAAC,EAAE,kBAAkB,CAAC;CAC1C;AAED,qBAAa,oBAAoB;IAC/B,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAkC;IAEzD,MAAM,CAAC,UAAU,CAAC,MAAM,EAAE,2BAA2B,GAAG,IAAI;IAqB5D,MAAM,CAAC,SAAS,IAAI,UAAU,CAAC,OAAO,YAAY,CAAC;CAMpD"}
+{"version":3,"file":"connection.d.ts","sourceRoot":"","sources":["../../src/core/connection.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AACtD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,wBAAwB,CAAC;AAGjE;;;;;;;;;;;;;GAaG;AACH,MAAM,WAAW,2BAA2B;IAC1C;;;OAGG;IACH,IAAI,EAAE,MAAM,CAAC;IAEb;;OAEG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAElB;;OAEG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAElB;;OAEG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAElB;;;OAGG;IACH,MAAM,CAAC,EAAE,OAAO,CAAC;IAEjB;;OAEG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAEtC;;OAEG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC;IAEzB;;OAEG;IACH,WAAW,CAAC,EAAE;QACZ,QAAQ,CAAC,EAAE,OAAO,CAAC;QACnB,OAAO,CAAC,EAAE,OAAO,CAAC;KACnB,CAAC;IAEF;;OAEG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IAErB;;OAEG;IACH,UAAU,CAAC,EAAE;QACX,OAAO,EAAE,OAAO,CAAC;KAClB,CAAC;IAEF;;OAEG;IACH,GAAG,CAAC,EAAE,GAAG,CAAC;IAEV;;OAEG;IACH,mBAAmB,CAAC,EAAE,kBAAkB,CAAC;CAC1C;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,qBAAa,oBAAoB;IAC/B,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAkC;IAEzD;;;;;;;;;;;;;;;;;;;;;;;;;;;OA2BG;IACH,MAAM,CAAC,UAAU,CAAC,MAAM,EAAE,2BAA2B,GAAG,OAAO,oBAAoB;IA+BnF;;;;;;;;;;;;;;OAcG;IACH,MAAM,CAAC,SAAS,IAAI,UAAU,CAAC,OAAO,YAAY,CAAC;CAMpD"}

package/dist/core/connection.js

@@ -1,5 +1,56 @@
 import { createClient } from '@clickhouse/client-web';
+/**
+ * The main entry point for connecting to a ClickHouse database.
+ * Provides static methods to initialize the connection and retrieve the client.
+ *
+ * @category Core
+ * @example
+ * ```typescript
+ * // Initialize the connection
+ * ClickHouseConnection.initialize({
+ *   host: 'http://localhost:8123',
+ *   username: 'default',
+ *   password: 'password',
+ *   database: 'my_database'
+ * });
+ *
+ * // Get the client to execute queries directly
+ * const client = ClickHouseConnection.getClient();
+ * const result = await client.query({
+ *   query: 'SELECT * FROM my_table',
+ *   format: 'JSONEachRow'
+ * });
+ * ```
+ */
 export class ClickHouseConnection {
+    /**
+     * Initializes the ClickHouse connection with the provided configuration.
+     * This method must be called before any queries can be executed.
+     *
+     * @param config - The connection configuration options
+     * @returns The ClickHouseConnection class for method chaining
+     * @throws Will throw an error if the connection cannot be established
+     *
+     * @example
+     * ```typescript
+     * // For a local ClickHouse instance
+     * ClickHouseConnection.initialize({
+     *   host: 'http://localhost:8123',
+     *   username: 'default',
+     *   password: 'password',
+     *   database: 'my_database'
+     * });
+     *
+     * // For a ClickHouse Cloud instance
+     * ClickHouseConnection.initialize({
+     *   host: 'https://your-instance.clickhouse.cloud:8443',
+     *   username: 'default',
+     *   password: 'your-password',
+     *   database: 'my_database',
+     *   secure: true
+     * });
+     * ```
+     */
     static initialize(config) {
         // Create a client config object with only the standard options
         const clientConfig = {
@@ -8,6 +59,14 @@ export class ClickHouseConnection {
             password: config.password,
             database: config.database,
         };
+        // Automatically enable secure mode for HTTPS URLs
+        const isSecure = config.secure || config.host.startsWith('https://');
+        if (isSecure) {
+            clientConfig.tls = {
+                ca_cert: undefined, // Use system CA certificates
+                verify: true,
+            };
+        }
         // Add the extended options if provided
         if (config.http_headers)
             clientConfig.http_headers = config.http_headers;
@@ -24,7 +83,23 @@ export class ClickHouseConnection {
         if (config.clickhouse_settings)
             clientConfig.clickhouse_settings = config.clickhouse_settings;
         this.instance = createClient(clientConfig);
+        return ClickHouseConnection;
     }
+    /**
+     * Retrieves the ClickHouse client instance for direct query execution.
+     *
+     * @returns The ClickHouse client instance
+     * @throws Will throw an error if the connection has not been initialized
+     *
+     * @example
+     * ```typescript
+     * const client = ClickHouseConnection.getClient();
+     * const result = await client.query({
+     *   query: 'SELECT * FROM my_table',
+     *   format: 'JSONEachRow'
+     * });
+     * ```
+     */
     static getClient() {
         if (!this.instance) {
             throw new Error('ClickHouse connection not initialized');