@hypequery/clickhouse 2.5.4 → 2.5.5

package/README-CLI.md

@@ -1,50 +1,34 @@
-# hypequery Type Generator
+# ClickHouse TypeScript schema generator
 
-`hypequery-generate-types` introspects your ClickHouse schema and writes a TypeScript interface you can use with `createQueryBuilder()`.
+`hypequery-generate-types` reads a live ClickHouse schema and writes the `IntrospectedSchema` TypeScript interface used by `@hypequery/clickhouse`. Generated types keep table names, column names, nullable values, arrays, dates, and large integers aligned with what ClickHouse returns over HTTP.
 
-Most users should prefer:
+Most projects should use the friendlier main CLI:
 
 ```bash
+npm install -D @hypequery/cli
 npx hypequery generate
 ```
 
-This file documents the lower-level binary that ships with `@hypequery/clickhouse`.
+Use the lower-level binary when you only installed `@hypequery/clickhouse` or want direct control over the output path.
 
-## Install
+## Run it
 
 ```bash
 npm install @hypequery/clickhouse
+npx hypequery-generate-types ./analytics/schema.ts
 ```
 
-## Usage
-
-```bash
-npx hypequery-generate-types
-```
-
-By default it:
-
-- reads ClickHouse connection details from environment variables
-- introspects tables in the target database
-- writes `generated-schema.ts` in the current working directory
+With no path, the command writes `generated-schema.ts` in the current directory.
 
-Custom output path:
+## Connection settings
 
-```bash
-npx hypequery-generate-types ./src/types/db-schema.ts
-```
-
-## Environment Variables
-
-| Variable | Description |
+| Variable | Purpose |
 | --- | --- |
-| `CLICKHOUSE_URL` | Preferred ClickHouse URL |
+| `CLICKHOUSE_URL` | ClickHouse HTTP URL |
 | `CLICKHOUSE_HOST` | Deprecated alias for `CLICKHOUSE_URL` |
-| `CLICKHOUSE_USER` | ClickHouse username |
-| `CLICKHOUSE_PASSWORD` | ClickHouse password |
-| `CLICKHOUSE_DATABASE` | ClickHouse database |
-
-Example:
+| `CLICKHOUSE_USER` | Username |
+| `CLICKHOUSE_PASSWORD` | Password |
+| `CLICKHOUSE_DATABASE` | Database to introspect |
 
 ```bash
 CLICKHOUSE_URL=http://localhost:8123 \
@@ -54,7 +38,7 @@ CLICKHOUSE_DATABASE=analytics \
 npx hypequery-generate-types ./analytics/schema.ts
 ```
 
-## Using The Generated Types
+## Use the result
 
 ```ts
 import { createQueryBuilder } from '@hypequery/clickhouse';
@@ -68,10 +52,13 @@ const db = createQueryBuilder<IntrospectedSchema>({
 });
 ```
 
-## Docs
+Regenerate after schema changes so TypeScript catches application queries that need updating.
+
+## Documentation
 
 - [Quick start](https://hypequery.com/docs/quick-start)
-- [CLI reference](https://hypequery.com/docs/reference/api/cli)
+- [Connection reference](https://hypequery.com/docs/reference/connection)
+- [Query builder](https://hypequery.com/clickhouse-query-builder)
 
 ## License
 

package/README.md

@@ -1,26 +1,18 @@
 # @hypequery/clickhouse
 
-Typed query builder for ClickHouse.
+The type-safe ClickHouse query builder for TypeScript.
 
-Use it when you want schema-aware queries, typed results, and a fluent API that stays close to how ClickHouse actually works.
+Generate types from your live ClickHouse schema, write fluent analytics queries, and catch broken table names, columns, joins, filters, and result shapes before production. `@hypequery/clickhouse` keeps the power of ClickHouse without the `any[]`, drifting interfaces, and stringly typed application SQL.
 
 ## Install
 
-Node:
-
 ```bash
 npm install @hypequery/clickhouse
+npm install -D @hypequery/cli
+npx hypequery generate
 ```
 
-Browser or shared client setup:
-
-```bash
-npm install @hypequery/clickhouse @clickhouse/client-web
-```
-
-`url` is the preferred connection field. `host` is still supported as a deprecated alias.
-
-## Quick Start
+## Your first typed query
 
 ```ts
 import { createQueryBuilder } from '@hypequery/clickhouse';
@@ -33,119 +25,49 @@ const db = createQueryBuilder<IntrospectedSchema>({
   database: process.env.CLICKHOUSE_DATABASE!,
 });
 
-const recentOrders = await db
-  .table('orders')
-  .select(['id', 'user_id', 'total', 'created_at'])
-  .where('created_at', 'gte', '2026-01-01')
-  .orderBy('created_at', 'DESC')
-  .limit(20)
-  .execute();
-```
-
-## Main Path
-
-1. Generate schema types with the CLI
-2. Create a typed `db`
-3. Write and execute queries locally
-4. Promote important queries into `@hypequery/serve` when they need a shared contract or HTTP surface
-
-## Common Patterns
-
-### Aggregation
-
-```ts
 const revenueByRegion = await db
   .table('orders')
   .select(['region'])
-  .sum('total', 'revenue')
+  .where('status', 'eq', 'completed')
+  .sum('amount', 'revenue')
   .groupBy('region')
   .orderBy('revenue', 'DESC')
   .execute();
 ```
 
-### Joins
+The result type is inferred from your real ClickHouse schema and the query itself. Rename a column, regenerate types, and affected queries fail at compile time.
 
-```ts
-const ordersWithUsers = await db
-  .table('orders')
-  .innerJoin('users', 'user_id', 'users.id')
-  .select(['orders.id', 'users.email', 'orders.total'])
-  .where('users.status', 'eq', 'active')
-  .execute();
-```
+## ClickHouse-first, not lowest-common-denominator SQL
 
-### ClickHouse-specific features
+- native `PREWHERE`, `FINAL`, `LIMIT BY`, array joins, totals, settings, and CTEs;
+- typed joins, filters, groups, ordering, pagination, and streaming;
+- sums, distinct counts, percentiles, `argMax`, `argMin`, standard deviation, and variance;
+- explicit expression helpers for window functions and specialised ClickHouse SQL;
+- correct runtime types for dates, large integers, nullable values, and arrays.
 
 ```ts
-const topProductsPerCategory = await db
+const topProducts = await db
   .table('products')
+  .final()
   .select(['category', 'id', 'score'])
   .orderBy('score', 'DESC')
   .limitBy(3, 'category')
   .execute();
 ```
 
-```ts
-const explodedTags = await db
-  .table('products')
-  .select(['id', 'tags'])
-  .arrayJoin('tags')
-  .execute();
-```
-
-`arrayJoin()` and `leftArrayJoin()` only accept array-typed columns.
-
-## Browser Use
-
-In browser environments, create the ClickHouse client explicitly and inject it:
-
-```ts
-import { createClient } from '@clickhouse/client-web';
-import { createQueryBuilder } from '@hypequery/clickhouse';
-import type { IntrospectedSchema } from './analytics/schema.js';
-
-const client = createClient({
-  url: process.env.NEXT_PUBLIC_CLICKHOUSE_URL!,
-  username: process.env.NEXT_PUBLIC_CLICKHOUSE_USERNAME!,
-  password: process.env.NEXT_PUBLIC_CLICKHOUSE_PASSWORD ?? '',
-  database: process.env.NEXT_PUBLIC_CLICKHOUSE_DATABASE!,
-});
-
-const db = createQueryBuilder<IntrospectedSchema>({
-  client,
-});
-```
-
-## Schema Generation
-
-The usual path is through the CLI:
-
-```bash
-npm install -D @hypequery/cli
-npx hypequery generate
-```
-
-The package also ships the lower-level generator binary:
-
-```bash
-npx hypequery-generate-types
-```
-
-More details: [README-CLI.md](./README-CLI.md)
+See [what hypequery supports today](https://hypequery.com/docs/capabilities) for the exact public surface.
 
-## Useful Exports
+## Grow beyond one query
 
-- SQL helpers like `raw`, `rawAs`, `selectExpr`, and `toDateTime`
-- exported time helpers like `toStartOfMinute`, `toStartOfHour`, `toStartOfDay`, `toStartOfWeek`, `toStartOfMonth`, `toStartOfQuarter`, and `toStartOfYear`
-- cache primitives like `MemoryCacheProvider`
+When analytics meaning needs to be shared, add `@hypequery/datasets` for a code-first semantic layer, `@hypequery/serve` for validated APIs, `@hypequery/react` for typed hooks, and `@hypequery/mcp` for governed AI-agent access. They all build on this query layer.
 
-## Docs
+## Learn more
 
-- [Query builder basics](https://hypequery.com/docs/query-building/basics)
+- [Quick start](https://hypequery.com/docs/quick-start)
+- [Query builder guide](https://hypequery.com/clickhouse-query-builder)
 - [Filtering](https://hypequery.com/docs/query-building/where)
-- [Joins](https://hypequery.com/docs/query-building/joins)
 - [Aggregation](https://hypequery.com/docs/query-building/aggregation)
-- [Connection reference](https://hypequery.com/docs/reference/connection)
+- [Schema generation](./README-CLI.md)
 
 ## License
 

package/package.json

@@ -1,7 +1,19 @@
 {
   "name": "@hypequery/clickhouse",
-  "version": "2.5.4",
-  "description": "ClickHouse typescript query builder",
+  "version": "2.5.5",
+  "description": "Type-safe ClickHouse query builder and schema generator for TypeScript analytics",
+  "keywords": [
+    "clickhouse",
+    "typescript",
+    "query-builder",
+    "type-safe",
+    "analytics",
+    "semantic-layer",
+    "orm",
+    "olap",
+    "sql",
+    "schema-generation"
+  ],
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "type": "module",
@@ -36,7 +48,7 @@
   "dependencies": {
     "@clickhouse/client": "^1.18.3",
     "dotenv": "^16.0.0",
-    "@hypequery/protocol": "0.10.1"
+    "@hypequery/protocol": "0.10.2"
   },
   "peerDependencies": {
     "@clickhouse/client-web": "^0.2.0 || ^1.0.0",
@@ -62,7 +74,7 @@
     "typescript": "^5.7.3",
     "@vitest/coverage-v8": "^3.2.6",
     "vitest": "^3.2.6",
-    "@hypequery/datasets": "0.13.2"
+    "@hypequery/datasets": "0.13.3"
   },
   "ts-node": {
     "esm": true,
@@ -70,7 +82,8 @@
   },
   "repository": {
     "type": "git",
-    "url": "https://github.com/hypequery/hypequery.git"
+    "url": "git+https://github.com/hypequery/hypequery.git",
+    "directory": "packages/clickhouse"
   },
   "homepage": "https://hypequery.com",
   "bugs": {