@housekit/orm 0.1.3 → 0.1.5

package/README.md

@@ -2,6 +2,8 @@
 
 **The high-performance, type-safe ClickHouse ORM for Node.js and Bun.**
 
+> ⚠️ **Public Beta**: This package is currently in public beta. Feedback is highly appreciated as we polish the API for v1.0.
+
 HouseKit ORM is a modern database toolkit designed specifically for ClickHouse. It bridges the gap between ergonomic developer experiences and the extreme performance requirements of high-volume OLAP workloads.
 
 [![npm version](https://img.shields.io/npm/v/@housekit/orm.svg)](https://www.npmjs.com/package/@housekit/orm)
@@ -180,6 +182,30 @@ const usersWithData = await db.query.users.findMany({
 // [{ id: 1, name: 'Alice', posts: [{ title: '...', ... }], profile: { bio: '...' } }]
 ```
 
+### Advanced Relational Engine
+HouseKit's relational API is optimized for ClickHouse:
+- **Filtered Relations**: Where clauses in `with` blocks are executed server-side using `groupUniqArrayIf`.
+- **Nested Pagination**: Control the size of related collections with `limit` and `offset` directly in the relation config.
+- **Smart Deduplication**: Merges results in-memory to handle row multiplication from complex joins.
+
+---
+
+## 🛠 SQL Utilities
+
+### Dynamic Queries with `sql.join`
+Easily build complex queries by joining SQL fragments with separators.
+
+```typescript
+const conditions = [
+  eq(users.active, true),
+  gte(users.age, 18)
+];
+
+const query = db.select()
+  .from(users)
+  .where(sql.join(conditions, sql` AND `));
+```
+
 ---
 
 ## 🔍 Specialized ClickHouse Joins

package/dist/relational.d.ts

@@ -1,33 +1,61 @@
 import { type TableDefinition } from './core';
 import type { SQLExpression } from './expressions';
 /**
- * Join strategy for relational queries
+ * Join strategy for relational queries.
+ *
+ * ClickHouse performance varies significantly depending on the join strategy used,
+ * especially in distributed environments.
  */
 export type JoinStrategy = 'auto' | 'standard' | 'global' | 'any' | 'global_any';
+/**
+ * Configuration options for the Relational Query API (`findMany`, `findFirst`).
+ */
 export type RelationalFindOptions<TTable = any> = {
+    /**
+     * Filter conditions for the main query.
+     * Can be a SQL expression or a callback receiving the table columns.
+     *
+     * @example where: (users) => eq(users.active, true)
+     */
     where?: SQLExpression | ((columns: TTable extends TableDefinition<infer TCols> ? TCols : any) => SQLExpression);
+    /**
+     * Maximum number of records to return from the primary table.
+     */
     limit?: number;
+    /**
+     * Number of records to skip from the primary table.
+     */
     offset?: number;
+    /**
+     * Nested relations to include in the result set.
+     * Set to `true` for all columns or provide a `RelationalFindOptions` object for nested filtering/limiting.
+     *
+     * @example with: { posts: { limit: 5 }, profile: true }
+     */
     with?: Record<string, boolean | RelationalFindOptions>;
     /**
      * Join strategy for related data.
      *
-     * - 'auto': Automatically uses GLOBAL when table has onCluster option
-     * - 'standard': Regular LEFT JOIN
-     * - 'global': Force GLOBAL JOIN (for clusters)
-     * - 'any': Use ANY JOIN (faster, single match)
-     * - 'global_any': Combine GLOBAL and ANY
+     * - 'auto': Automatically uses GLOBAL when table has onCluster option.
+     * - 'standard': Regular LEFT JOIN.
+     * - 'global': Force GLOBAL JOIN (for sharded clusters).
+     * - 'any': Use ANY JOIN (faster, optimized for 1:1 relations).
+     * - 'global_any': Combine GLOBAL and ANY.
      *
      * @default 'auto'
      */
     joinStrategy?: JoinStrategy;
 };
 /**
- * Build a modern relational API with ClickHouse optimizations.
+ * Build a modern relational API with ClickHouse-specific optimizations.
+ *
+ * Key architectural features:
+ * - **groupUniqArray Optimization**: Instead of flat-joining which causes row explosion,
+ *   HouseKit uses ClickHouse aggregation to fetch nested relations as arrays of tuples.
+ * - **Automatic Cluster Handling**: Detects sharded tables and applies GLOBAL JOINs.
+ * - **Smart Deduplication**: Merges results in-memory when flat joins are unavoidable.
  *
- * Key improvements over standard ORMs:
- * - Automatic GLOBAL JOIN detection for distributed tables
- * - Join strategy selection for performance tuning
- * - Support for dictionary lookups as alternative to JOINs
+ * @param client - The ClickHouse client instance.
+ * @param schema - The shared schema definition containing all table and relation metadata.
  */
 export declare function buildRelationalAPI(client: any, schema?: Record<string, TableDefinition<any>>): Record<string, any> | undefined;

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@housekit/orm",
-    "version": "0.1.3",
+    "version": "0.1.5",
     "description": "Type-safe ClickHouse ORM with modern DX and ClickHouse-specific optimizations. Features Turbo Mode (RowBinary), full engine support, and advanced query capabilities.",
     "type": "module",
     "main": "./dist/index.js",