@housekit/orm 0.1.2 → 0.1.4

package/README.md

@@ -152,9 +152,10 @@ const builder = db.insert(webEvents)
     flushIntervalMs: 5000 
   });
 
-// These calls return immediately, flushing happens in the background
-builder.values(row1).execute();
-builder.values(row2).execute();
+// Add rows to the background queue.
+// Proccessing and flushing happen automatically.
+await builder.append(row1);
+await builder.append(row2);
 ```
 
 ---

package/dist/builders/insert.d.ts

@@ -64,6 +64,16 @@ export declare class ClickHouseInsertBuilder<TTable extends TableDefinition<Tabl
      * Default: 1000
      */
     batchSize(size: number): this;
+    /**
+     * Add a row to the background batcher.
+     *
+     * If batching is not yet configured, it will use default settings
+     * (10,000 rows or 5 seconds).
+     *
+     * Note: This method is "fire-and-forget" and does not wait for
+     * the database to acknowledge the insert.
+     */
+    append(row: TableInsert<TTable['$columns']>): Promise<void>;
     /**
      * Force JSON format (useful for debugging or compatibility).
      *

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.2",
+    "version": "0.1.4",
     "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",