How izadoesdev/clickquery works
Project Type & Purpose
• ClickQuery is an open‑source TypeScript library (minimal ORM/query builder) for ClickHouse.
• It provides a fluent API to define schemas, build type‑safe SQL queries, and execute them via HTTP(S).
High‑Level Components
a. Developer Application
• Your application code that imports @clickquery/core.
• Defines models, invokes createClient, and issues queries/inserts.
b. ClickQuery Library (packages/core)
1. Client Module (src/client)
– createClient & HTTP transport layer: configures host, credentials, settings.
– Sends built SQL to ClickHouse’s REST API; parses responses.
2. Schema Definition (src/schema)
– defineModel: declarative table definitions (columns, engines, partitions).
– Types (types/*), validation, migrations scaffolding.
3. Fluent Query Builder (src/index.ts, part of core)
– Chainable methods: .select(), .where(), .insert(), etc.
– Produces SQL strings + parameter binding.
4. Type Inference (src/types + utility types)
– InferModelType: maps schema definitions to TypeScript row types.
5. Utilities (src/utils)
– Helpers (UUID generation, date formatting).
6. Tests (src/tests)
– Unit tests for each component (client, schema, migrations).
c. External Service
• ClickHouse Database
– Receives SQL via HTTP(S), executes queries, returns JSON/CSV.
Relationships & Data Flows
• Application → Client: calls createClient(config).
• Application → Schema API: defines models via defineModel(...).
• Application → Query Builder: chains calls (db.select(...), db.insert(...)).
• Query Builder → Client: hands off generated SQL + parameters.
• Client → ClickHouse: HTTP request with SQL payload.
• ClickHouse → Client: HTTP response (rows or insertion status).
• Client → Application: returns typed results (InferModelType<T>).
Architectural Patterns & Principles
• Layered Modular Design: separation between Client, Schema, Query Builder, Type System, Utilities.
• Monorepo Structure: packages/core houses the library; allows future packages (e.g., CLI, migrations).
• Type‑First Approach: heavy use of TypeScript’s type inference for end‑to‑end safety.
• Minimal Abstraction: keeps close to ClickHouse concepts (engines, data types).