@hypequery/clickhouse 0.0.0-canary-20260306132943

package/dist/cli/bin.js

@@ -0,0 +1,285 @@
+#!/usr/bin/env node
+
+import { ClickHouseConnection } from '../core/connection.js';
+import { generateTypes } from './generate-types.js';
+import path from 'path';
+import dotenv from 'dotenv';
+import fs from 'fs/promises';
+
+// Load environment variables from the current directory
+dotenv.config();
+
+// ANSI color codes for prettier output
+const colors = {
+  reset: '\x1b[0m',
+  bright: '\x1b[1m',
+  dim: '\x1b[2m',
+  green: '\x1b[32m',
+  yellow: '\x1b[33m',
+  blue: '\x1b[34m',
+  red: '\x1b[31m',
+  cyan: '\x1b[36m'
+};
+
+/**
+ * Display a colorful banner with the tool name
+ */
+function showBanner() {
+  console.log(`
+${colors.bright}${colors.cyan}hypequery TypeScript Generator${colors.reset}
+${colors.dim}Generate TypeScript types from your ClickHouse database schema${colors.reset}
+  `);
+}
+
+/**
+ * Show help information for the CLI
+ */
+function showHelp() {
+  console.log(`
+${colors.bright}Usage:${colors.reset}
+  npx hypequery-generate-types [options]
+
+${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.dim}Note: All options support both formats: --option=value or --option value${colors.reset}
+
+${colors.bright}Environment variables:${colors.reset}
+  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
+  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 --output=./src/types/db-schema.ts
+  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
+  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
+  };
+
+  // Helper function to extract value from --param=value format
+  function getParamValue(arg, paramName) {
+    if (arg.startsWith(`${paramName}=`)) {
+      return arg.substring(paramName.length + 1); // +1 for the '=' character
+    }
+    return null;
+  }
+
+  // Helper function to get next argument as value
+  function getNextArgValue(args, index) {
+    return args[index + 1];
+  }
+
+  // Parameter handlers map
+  const paramHandlers = {
+    '--output': (value) => config.output = value,
+    '--host': (value) => config.host = value,
+    '--username': (value) => config.username = value,
+    '--password': (value) => config.password = value,
+    '--database': (value) => config.database = value,
+    '--include-tables': (value) => config.includeTables = value.split(','),
+    '--exclude-tables': (value) => config.excludeTables = value.split(',')
+  };
+
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    let handled = false;
+
+    // Handle parameters with values
+    for (const [paramName, handler] of Object.entries(paramHandlers)) {
+      // Check for --param=value format
+      const value = getParamValue(arg, paramName);
+      if (value !== null) {
+        handler(value);
+        handled = true;
+        break;
+      }
+
+      // Check for --param value format
+      if (arg === paramName) {
+        const nextValue = getNextArgValue(args, i);
+        if (nextValue && !nextValue.startsWith('-')) {
+          handler(nextValue);
+          i++; // Skip the next argument since we consumed it
+          handled = true;
+          break;
+        }
+      }
+    }
+
+    // Handle boolean flags
+    if (!handled) {
+      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
+ */
+async function main() {
+  showBanner();
+
+  // Process command line arguments
+  const args = process.argv.slice(2);
+  const config = parseArguments(args);
+
+  // Check for help flag
+  if (config.showHelp) {
+    showHelp();
+    return;
+  }
+
+  try {
+    // 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}`);
+
+    // Configure connection
+    const connectionConfig = {
+      host,
+      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(config.output));
+    await fs.mkdir(dir, { recursive: true });
+
+    // Generate types
+    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(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 '${config.output.replace(/\.ts$/, '')}';
+
+const db = createQueryBuilder<IntrospectedSchema>({
+  host: '${host}',
+  username: '${username}',
+  password: '********',
+  database: '${database}'
+});
+`);
+  } catch (error) {
+    console.error(`${colors.red}✗ Error generating types: ${colors.reset}${error.message}`);
+
+    // Provide more helpful error messages for common issues
+    if (error.message && error.message.includes('ECONNREFUSED')) {
+      console.error(`
+${colors.yellow}Connection refused.${colors.reset} Please check:
+- 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 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 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
+`);
+    }
+
+    console.error(`${colors.dim}For more information, use --help flag.${colors.reset}`);
+    process.exit(1);
+  }
+}
+
+// Execute the main function
+main(); 

package/dist/cli/generate-types.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Generates TypeScript type definitions from the ClickHouse database schema
+ * @param outputPath - The file path where the type definitions will be written
+ */
+export declare function generateTypes(outputPath: string): Promise<void>; 

package/dist/cli/generate-types.js

@@ -0,0 +1,218 @@
+import { ClickHouseConnection } from '../core/connection.js';
+import fs from 'fs/promises';
+import path from 'path';
+import dotenv from 'dotenv';
+
+// Load environment variables from the current directory
+dotenv.config();
+
+/**
+ * @typedef {Object} ColumnInfo
+ * @property {string} name - The name of the column
+ * @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
+ * @returns {string} - The corresponding TypeScript type
+ */
+const clickhouseToTsType = (type) => {
+  if (type.startsWith('Array(')) {
+    const innerType = type.slice(6, -1);
+    return `Array<${clickhouseToTsType(innerType)}>`;
+  }
+
+  // Handle Nullable types
+  if (type.startsWith('Nullable(')) {
+    const innerType = type.slice(9, -1);
+    return `${clickhouseToTsType(innerType)} | null`;
+  }
+
+  // Handle Map types
+  if (type.startsWith('Map(')) {
+    // Extract key and value types from Map(KeyType, ValueType)
+    const mapContent = type.slice(4, -1); // Remove 'Map(' and ')'
+    const commaIndex = mapContent.lastIndexOf(',');
+    if (commaIndex !== -1) {
+      const keyType = mapContent.substring(0, commaIndex).trim();
+      const valueType = mapContent.substring(commaIndex + 1).trim();
+
+      // Handle different key types
+      let keyTsType = 'string';
+      if (keyType === 'LowCardinality(String)') {
+        keyTsType = 'string';
+      } else if (keyType.includes('Int') || keyType.includes('UInt')) {
+        keyTsType = 'number';
+      }
+
+      // Handle different value types
+      let valueTsType = 'unknown';
+      if (valueType.startsWith('Array(')) {
+        const innerType = valueType.slice(6, -1);
+        valueTsType = `Array<${clickhouseToTsType(innerType)}>`;
+      } else if (valueType.startsWith('Nullable(')) {
+        const innerType = valueType.slice(9, -1);
+        valueTsType = `${clickhouseToTsType(innerType)} | null`;
+      } else {
+        valueTsType = clickhouseToTsType(valueType);
+      }
+
+      return `Record<${keyTsType}, ${valueTsType}>`;
+    }
+    return 'Record<string, unknown>';
+  }
+
+  switch (type.toLowerCase()) {
+    case 'string':
+    case 'fixedstring':
+      return 'string';
+    case 'int8':
+    case 'int16':
+    case 'int32':
+    case 'uint8':
+    case 'int64':
+    case 'uint16':
+    case 'uint32':
+    case 'uint64':
+      return 'number';
+    case 'uint128':
+    case 'uint256':
+    case 'int128':
+    case 'int256':
+      return 'string';
+    case 'float32':
+    case 'float64':
+    case 'decimal':
+      return 'number';
+    case 'datetime':
+    case 'datetime64':
+      return 'string'; // Use string for datetime
+    case 'date':
+    case 'date32':
+      return 'string'; // Use string for date
+    case 'bool':
+    case 'boolean':
+      return 'boolean';
+    default:
+      // 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, options = {}) {
+  const client = ClickHouseConnection.getClient();
+  const { includeTables = [], excludeTables = [] } = options;
+
+  // Get all tables
+  const tablesQuery = await client.query({
+    query: 'SHOW TABLES',
+    format: 'JSONEachRow'
+  });
+  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
+// 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 ${table.name}`,
+      format: 'JSONEachRow'
+    });
+    const columns = await columnsQuery.json();
+    typeDefinitions += `\n  ${table.name}: {`;
+    for (const column of columns) {
+      const clickHouseType = column.type.replace(/'/g, "\\'"); // Escape single quotes, e.g. `DateTime('UTC')`
+      typeDefinitions += `\n    '${column.name}': '${clickHouseType}';`;
+    }
+    typeDefinitions += '\n  };';
+  }
+
+  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
+ *   .table('${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/cli/index.d.ts

@@ -0,0 +1,2 @@
+// CLI module type declarations
+export { generateTypes } from './generate-types'; 

package/dist/cli/index.js

@@ -0,0 +1,2 @@
+// CLI module exports
+export { generateTypes } from './generate-types.js'; 

package/dist/core/cache/cache-manager.d.ts

@@ -0,0 +1,4 @@
+import type { QueryBuilder, ExecuteOptions } from '../query-builder.js';
+import type { AnyBuilderState, SchemaDefinition } from '../types/builder-state.js';
+export declare function executeWithCache<Schema extends SchemaDefinition<Schema>, State extends AnyBuilderState>(builder: QueryBuilder<Schema, State>, options?: ExecuteOptions): Promise<State['output'][]>;
+//# sourceMappingURL=cache-manager.d.ts.map

package/dist/core/cache/cache-manager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache-manager.d.ts","sourceRoot":"","sources":["../../../src/core/cache/cache-manager.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AACxE,OAAO,KAAK,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,2BAA2B,CAAC;AA6DnF,wBAAsB,gBAAgB,CACpC,MAAM,SAAS,gBAAgB,CAAC,MAAM,CAAC,EACvC,KAAK,SAAS,eAAe,EAE7B,OAAO,EAAE,YAAY,CAAC,MAAM,EAAE,KAAK,CAAC,EACpC,OAAO,CAAC,EAAE,cAAc,GACvB,OAAO,CAAC,KAAK,CAAC,QAAQ,CAAC,EAAE,CAAC,CA0J5B"}