@hypequery/clickhouse 0.2.1

package/README-CLI.md

@@ -0,0 +1,123 @@
+# HypeQuery TypeScript Generator
+
+This tool automatically generates TypeScript type definitions from your ClickHouse database schema.
+
+## Installation
+
+The TypeScript generator is included with the `@hypequery/clickhouse` package:
+
+```bash
+npm install @hypequery/clickhouse
+```
+
+## Quick Start
+
+Generate TypeScript types for your ClickHouse database:
+
+```bash
+npx hypequery-generate-types
+```
+
+This will:
+1. Connect to your ClickHouse database using environment variables
+2. Introspect all tables in your database
+3. Generate TypeScript definitions in `./generated-schema.ts`
+
+## Example Usage
+
+**Generate types with a custom output path:**
+
+```bash
+npx hypequery-generate-types ./src/types/db-schema.ts
+```
+
+**Specify database connection directly:**
+
+```bash
+CLICKHOUSE_HOST=http://clickhouse.example.com:8123 \
+CLICKHOUSE_USER=myuser \
+CLICKHOUSE_PASSWORD=mypassword \
+CLICKHOUSE_DATABASE=analytics \
+npx hypequery-generate-types
+```
+
+## Configuration
+
+Configure the connection using environment variables:
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `CLICKHOUSE_HOST` | ClickHouse server URL | `http://localhost:8123` |
+| `CLICKHOUSE_USER` | ClickHouse username | `default` |
+| `CLICKHOUSE_PASSWORD` | ClickHouse password | _(empty)_ |
+| `CLICKHOUSE_DATABASE` | ClickHouse database name | `default` |
+
+You can set these in:
+- A `.env` file in your project root
+- Your system environment
+- Directly when running the command
+
+## Using Generated Types
+
+Import the generated types in your code:
+
+```typescript
+import { createQueryBuilder } from '@hypequery/clickhouse';
+import { IntrospectedSchema } from './generated-schema';
+
+// Create a type-safe query builder
+const db = createQueryBuilder<IntrospectedSchema>({
+  host: process.env.CLICKHOUSE_HOST,
+  username: process.env.CLICKHOUSE_USER,
+  password: process.env.CLICKHOUSE_PASSWORD,
+  database: process.env.CLICKHOUSE_DATABASE,
+});
+
+// Enjoy complete type safety!
+const results = await db
+  .table('users')          // TypeScript checks table exists
+  .select(['id', 'name'])  // TypeScript checks columns exist
+  .where('id', 'gt', 10)   // TypeScript validates types
+  .execute();
+
+// Results are properly typed
+results.forEach(user => {
+  console.log(user.name);  // TypeScript knows this is a string
+});
+```
+
+## Adding to Your Workflow
+
+Add it to your npm scripts:
+
+```json
+{
+  "scripts": {
+    "generate-types": "hypequery-generate-types ./src/types/db-schema.ts",
+    "prebuild": "npm run generate-types",
+    "build": "tsc"
+  }
+}
+```
+
+## Troubleshooting
+
+If you encounter issues:
+
+1. **Connection problems**
+   - Make sure ClickHouse is running and accessible
+   - Check your firewall settings
+
+2. **Authentication failures**
+   - Verify your username and password
+   - Ensure the user has sufficient permissions
+
+3. **Missing tables**
+   - Confirm you're connecting to the correct database
+   - Verify the tables exist in your ClickHouse instance
+
+For more help, run:
+
+```bash
+npx hypequery-generate-types --help
+``` 

package/README.md

@@ -0,0 +1,276 @@
+# HypeQuery
+
+<div align="center">
+  <img src="https://hypequery.dev/img/logo.svg" alt="HypeQuery Logo" width="200"/>
+  <h1>@hypequery/clickhouse</h1>
+  <p>A typescript-first library for building type-safe dashboards with ClickHouse</p>
+  
+  [![GitHub license](https://img.shields.io/github/license/lukejreilly/hypequery)](https://github.com/lukejreilly/hypequery/blob/main/LICENSE)
+  [![npm version](https://badge.fury.io/js/@hypequery%2Fcore.svg)](https://badge.fury.io/js/@hypequery%2Fcore)
+  [![GitHub stars](https://img.shields.io/github/stars/lukejreilly/hypequery)](https://github.com/lukejreilly/hypequery/stargazers)
+</div>
+
+> **Note:** This package is published on npm as `@hypequery/core`. The unscoped package `hypequery-core` is unrelated and should not be used.
+
+## Overview
+
+hypequery is a typescript-first query builder for ClickHouse designed specifically for building real-time, type-safe analytics dashboards. Unlike generic SQL query builders, HypeQuery understands your ClickHouse schema and provides full type checking throughout your codebase, making it ideal for data-intensive applications.
+
+## Features
+
+- 🎯 **Type-Safe**: Full TypeScript support with inferred types from your ClickHouse schema
+- 🚀 **Performant**: Built for real-time analytics with optimized query generation
+- 🔍 **Cross Filtering**: Powerful cross-filtering capabilities for interactive dashboards
+- 📊 **Dashboard Ready**: Built-in support for pagination, sorting, and filtering
+- 🛠️ **Developer Friendly**: Fluent API design for an intuitive development experience
+- 📱 **Platform Agnostic**: Works in both Node.js and browser environments
+- 🔄 **Schema Generation**: CLI tool to generate TypeScript types from your ClickHouse schema
+
+## Installation
+
+```bash
+# npm
+npm install @hypequery/core
+
+# yarn
+yarn add @hypequery/core
+
+# pnpm
+pnpm add @hypequery/core
+```
+
+## Quick Start
+
+```typescript
+import { createQueryBuilder } from '@hypequery/core';
+import type { Schema } from './generated-schema';
+
+// Initialize the query builder
+const db = createQueryBuilder<Schema>({
+  host: 'your-clickhouse-host',
+  username: 'default',
+  password: '',
+  database: 'default'
+});
+
+// Build and execute a query
+const results = await db
+  .table('trips')
+  .select(['pickup_datetime', 'dropoff_datetime', 'total_amount'])
+  .where('total_amount', '>', 50)
+  .orderBy('pickup_datetime', 'DESC')
+  .limit(10)
+  .execute();
+```
+
+## Schema Generation
+
+HypeQuery provides a CLI tool to generate TypeScript types from your ClickHouse schema:
+
+```bash
+# Install globally (optional)
+npm install -g @hypequery/core
+
+# Generate schema types
+npx hypequery-generate --host your-clickhouse-host --database your-database
+```
+
+This creates a `generated-schema.ts` file that you can import in your application:
+
+```typescript
+import { createQueryBuilder } from '@hypequery/core';
+import type { IntrospectedSchema } from './generated-schema';
+
+const db = createQueryBuilder<IntrospectedSchema>({
+  // connection details
+});
+```
+
+## Core Features
+
+### Type-Safe Queries
+
+HypeQuery provides full TypeScript support, ensuring your queries are type-safe:
+
+```typescript
+// Column names are type-checked
+const query = db.table('trips')
+  .select(['pickup_datetime', 'total_amount']) 
+  .where('total_amount', '>', 50)
+  .execute();
+
+// Type error if column doesn't exist
+db.table('trips').select(['non_existent_column']); // TypeScript error
+```
+
+### Cross Filtering
+
+Implement interactive dashboards with cross-filtering support:
+
+```typescript
+import { CrossFilter } from '@hypequery/core';
+
+// Create a filter
+const filter = new CrossFilter()
+  .add({
+    column: 'pickup_datetime',
+    operator: 'gte',
+    value: '2024-01-01'
+  })
+  .add({
+    column: 'total_amount',
+    operator: 'gt',
+    value: 20
+  });
+
+// Apply to multiple queries
+const query1 = db.table('trips')
+  .applyCrossFilters(filter)
+  .execute();
+
+const query2 = db.table('drivers')
+  .applyCrossFilters(filter)
+  .execute();
+```
+
+### Pagination
+
+Built-in cursor-based pagination for efficient data loading:
+
+```typescript
+// First page
+const firstPage = await db.table('trips')
+  .select(['pickup_datetime', 'total_amount'])
+  .orderBy('pickup_datetime', 'DESC')
+  .paginate({
+    pageSize: 10
+  });
+
+// Next page
+const nextPage = await db.table('trips')
+  .select(['pickup_datetime', 'total_amount'])
+  .orderBy('pickup_datetime', 'DESC')
+  .paginate({
+    pageSize: 10,
+    after: firstPage.pageInfo.endCursor
+  });
+
+// Previous page
+const prevPage = await db.table('trips')
+  .select(['pickup_datetime', 'total_amount'])
+  .orderBy('pickup_datetime', 'DESC')
+  .paginate({
+    pageSize: 10,
+    before: nextPage.pageInfo.startCursor
+  });
+```
+
+### Advanced Queries
+
+HypeQuery supports complex queries including joins, aggregations, and subqueries:
+
+```typescript
+// Aggregations
+const stats = await db.table('trips')
+  .avg('total_amount')
+  .max('trip_distance')
+  .count('trip_id')
+  .where('pickup_datetime', '>=', '2024-01-01')
+  .execute();
+
+// Joins
+const tripsWithDrivers = await db.table('trips')
+  .select(['trips.trip_id', 'trips.total_amount', 'drivers.name'])
+  .join('drivers', 'trips.driver_id', '=', 'drivers.id')
+  .execute();
+
+// Raw SQL when needed
+const customQuery = await db.table('trips')
+  .select([
+    db.raw('toStartOfDay(pickup_datetime) as day'),
+    'count() as trip_count'
+  ])
+  .groupBy(db.raw('toStartOfDay(pickup_datetime)'))
+  .execute();
+```
+
+## Environment Support
+
+### Browser Environment
+
+For browser usage, you'll typically need to set up a proxy server to avoid CORS issues:
+
+```typescript
+const db = createQueryBuilder<Schema>({
+  host: '/api/clickhouse', // Proxy through your API route
+  username: 'default',
+  password: '',
+  database: 'default'
+});
+```
+
+### Node.js Environment
+
+For server-side applications, you can connect directly to ClickHouse:
+
+```typescript
+const db = createQueryBuilder<Schema>({
+  host: 'http://your-clickhouse-server:8123',
+  username: 'default',
+  password: 'your-password',
+  database: 'default'
+});
+```
+
+## Versioning and Release Channels
+
+HypeQuery follows semantic versioning and provides multiple release channels:
+
+- **Latest**: Stable releases (`npm install @hypequery/core`)
+- **Beta**: Pre-release versions (`npm install @hypequery/core@beta`)
+
+## Documentation
+
+For detailed documentation and examples, visit our [documentation site](https://hypequery.dev/docs).
+
+- [Getting Started](https://hypequery.dev/docs/installation)
+- [Query Building](https://hypequery.dev/docs/guides/query-building)
+- [Filtering](https://hypequery.dev/docs/guides/filtering)
+- [Pagination](https://hypequery.dev/docs/features/pagination)
+- [API Reference](https://hypequery.dev/docs/reference/api)
+
+## Examples
+
+Check out our example implementations:
+
+- [Example Dashboard](https://github.com/lukejreilly/hypequery/tree/main/examples/example-dashboard): A complete Next.js dashboard with HypeQuery
+- [React Query Integration](https://hypequery.dev/docs/guides/integrations/react-query): Using HypeQuery with React Query
+- [Time Series Analysis](https://hypequery.dev/docs/guides/timeseries): Building time series analytics
+
+## Troubleshooting
+
+### Common Issues
+
+- **Connection Errors**: Ensure your ClickHouse server is running and accessible
+- **CORS Issues**: Use a proxy server for browser environments
+- **Type Errors**: Make sure to regenerate your schema types after schema changes
+
+## Contributing
+
+We welcome contributions! Please see our [contributing guide](CONTRIBUTING.md) for details.
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+
+## Support
+
+- 📚 [Documentation](https://hypequery.dev/docs)
+- 🐛 [Issue Tracker](https://github.com/lukejreilly/hypequery/issues)
+- 💬 [Discussions](https://github.com/lukejreilly/hypequery/discussions)
+
+---
+
+<div align="center">
+  <sub>Built with ❤️ by the HypeQuery team</sub>
+</div> 

package/dist/cli/bin.js

@@ -0,0 +1,151 @@
+#!/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 [output-path] [options]
+
+${colors.bright}Arguments:${colors.reset}
+  output-path                Path where TypeScript definitions will be saved (default: "./generated-schema.ts")
+
+${colors.bright}Environment variables:${colors.reset}
+  CLICKHOUSE_HOST            ClickHouse server URL (default: http://localhost:8123)
+  CLICKHOUSE_USER            ClickHouse username (default: default)
+  CLICKHOUSE_PASSWORD        ClickHouse password
+  CLICKHOUSE_DATABASE        ClickHouse database name (default: default)
+
+${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
+  `);
+}
+
+/**
+ * Main CLI function
+ */
+async function main() {
+  showBanner();
+
+  // Process command line arguments
+  const args = process.argv.slice(2);
+
+  // Check for help flag
+  if (args.includes('--help') || args.includes('-h')) {
+    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';
+
+    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({
+      host,
+      username: process.env.VITE_CLICKHOUSE_USER || process.env.CLICKHOUSE_USER || 'default',
+      password: process.env.VITE_CLICKHOUSE_PASSWORD || process.env.CLICKHOUSE_PASSWORD,
+      database,
+    });
+
+    console.log(`${colors.dim}Generating TypeScript definitions...${colors.reset}`);
+
+    // Ensure directory exists
+    const dir = path.dirname(path.resolve(outputPath));
+    await fs.mkdir(dir, { recursive: true });
+
+    // Generate types
+    await generateTypes(outputPath);
+
+    console.log(`${colors.green}✓ Success! ${colors.reset}Types generated at ${colors.bright}${path.resolve(outputPath)}${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$/, '')}';
+
+const db = createQueryBuilder<IntrospectedSchema>({
+  host: process.env.CLICKHOUSE_HOST,
+  username: process.env.CLICKHOUSE_USER,
+  password: process.env.CLICKHOUSE_PASSWORD,
+  database: process.env.CLICKHOUSE_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 ${process.env.CLICKHOUSE_HOST || 'http://localhost:8123'}?
+- Do you need to provide authentication credentials?
+- Are there any network/firewall restrictions?
+`);
+    } 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?
+- 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?
+- Does the database exist in your ClickHouse instance?
+`);
+    }
+
+    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,91 @@
+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
+ */
+
+/**
+ * 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)})`;
+  }
+
+  switch (type.toLowerCase()) {
+    case 'string':
+    case 'fixedstring':
+      return 'String';
+    case 'int8':
+    case 'int16':
+    case 'int32':
+      return 'Int32';
+    case 'int64':
+      return 'Int64';
+    case 'float32':
+    case 'float64':
+      return 'Float64';
+    case 'datetime':
+      return 'DateTime';
+    case 'date':
+      return 'Date';
+    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
+ * @returns {Promise<void>}
+ */
+export async function generateTypes(outputPath) {
+  const client = ClickHouseConnection.getClient();
+
+  // Get all tables
+  const tablesQuery = await client.query({
+    query: 'SHOW TABLES',
+    format: 'JSONEachRow'
+  });
+  const tables = await tablesQuery.json();
+
+  let typeDefinitions = `// Generated by @hypequery/clickhouse
+import { ColumnType } from '@hypequery/clickhouse';
+
+export interface IntrospectedSchema {`;
+
+  // Get columns for each table
+  for (const table of tables) {
+    const columnsQuery = await client.query({
+      query: `DESCRIBE ${table.name}`,
+      format: 'JSONEachRow'
+    });
+    const columns = await columnsQuery.json();
+
+    typeDefinitions += `\n  ${table.name}: {`;
+    for (const column of columns) {
+      typeDefinitions += `\n    ${column.name}: '${clickhouseToTsType(column.type)}';`;
+    }
+    typeDefinitions += '\n  };';
+  }
+
+  typeDefinitions += '\n}\n';
+
+  // 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);
+} 

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/connection.d.ts.map

@@ -0,0 +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"}

package/dist/core/connection.js

@@ -0,0 +1,34 @@
+import { createClient } from '@clickhouse/client-web';
+export class ClickHouseConnection {
+    static initialize(config) {
+        // Create a client config object with only the standard options
+        const clientConfig = {
+            host: config.host,
+            username: config.username,
+            password: config.password,
+            database: config.database,
+        };
+        // Add the extended options if provided
+        if (config.http_headers)
+            clientConfig.http_headers = config.http_headers;
+        if (config.request_timeout)
+            clientConfig.request_timeout = config.request_timeout;
+        if (config.compression)
+            clientConfig.compression = config.compression;
+        if (config.application)
+            clientConfig.application = config.application;
+        if (config.keep_alive)
+            clientConfig.keep_alive = config.keep_alive;
+        if (config.log)
+            clientConfig.log = config.log;
+        if (config.clickhouse_settings)
+            clientConfig.clickhouse_settings = config.clickhouse_settings;
+        this.instance = createClient(clientConfig);
+    }
+    static getClient() {
+        if (!this.instance) {
+            throw new Error('ClickHouse connection not initialized');
+        }
+        return this.instance;
+    }
+}