@housekit/orm 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Pablo Fernandez Ruiz
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,224 @@
+# @housekit/orm 🏠⚡️
+
+**The high-performance, type-safe ClickHouse ORM for Node.js and Bun.**
+
+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)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+---
+
+## 🚀 Key Features
+
+- **🛡️ First-Class TypeScript**: Full type inference for every query. If it compiles, the schema matches your DB.
+- **🏎️ Automatic Turbo Mode**: Native `RowBinary` serialization by default. Bypasses the overhead of JSON parsing for **5-10x faster inserts**.
+- **🏗️ ClickHouse Native Engines**: Fluent DSL for `MergeTree`, `ReplacingMergeTree`, `SummingMergeTree`, `Distributed`, `Buffer`, and more.
+- **🔍 Advanced Analytics**: Specialized support for `ASOF JOIN`, `ARRAY JOIN`, `PREWHERE`, and complex Window Functions.
+- **🤝 Smart Relational API**: Query relations using `groupArray` internally, preventing row duplication and keeping data transfer lean.
+- **📦 Background Batching**: Built-in buffering to collect small inserts into high-performance batches automatically.
+
+---
+
+## 📦 Installation
+
+```bash
+# HouseKit requires the official ClickHouse client as a peer dependency
+npm install @housekit/orm @clickhouse/client
+# or
+bun add @housekit/orm @clickhouse/client
+```
+
+---
+
+## ⚡️ Quick Start
+
+### 1. Define your Table
+Use the fluent `defineTable` API. All columns are **NOT NULL** by default, following ClickHouse best practices.
+
+```typescript
+import { defineTable, t, Engine } from '@housekit/orm';
+
+export const webEvents = defineTable('web_events', {
+  id: t.uuid('id').primaryKey(),
+  eventType: t.string('event_type'),
+  url: t.string('url'),
+  revenue: t.decimal('revenue', 18, 4).default(0),
+  tags: t.array(t.string('tag')),
+  metadata: t.json('metadata'), // Native JSON type support
+  at: t.datetime('at').default('now()'),
+}, {
+  engine: Engine.MergeTree(),
+  orderBy: 'at',
+  partitionBy: 'toYYYYMM(at)',
+  ttl: 'at + INTERVAL 1 MONTH'
+});
+```
+
+### 2. Connect and Query
+HouseKit automatically picks up configuration from your environment or `housekit.config.ts`.
+
+```typescript
+import { createClient, eq, and, gte, sql } from '@housekit/orm';
+
+const db = await createClient();
+
+// Fully typed result inference
+const results = await db.select({
+    id: webEvents.id,
+    path: webEvents.url,
+    total: sql<number>`sum(${webEvents.revenue})`
+  })
+  .from(webEvents)
+  .where(and(
+    eq(webEvents.eventType, 'sale'),
+    gte(webEvents.at, new Date('2024-01-01'))
+  ))
+  .groupBy(webEvents.id, webEvents.url)
+  .limit(10);
+```
+
+---
+
+## 🧠 Advanced Schema Definitions
+
+### Complex Engines
+HouseKit supports specialized ClickHouse engines with strict type checking for their parameters.
+
+```typescript
+// SummingMergeTree: Automatically aggregates numeric columns
+export const dailyRevenue = defineTable('daily_revenue', {
+  day: t.date('day'),
+  revenue: t.float64('revenue'),
+}, {
+  engine: Engine.SummingMergeTree(['revenue']),
+  orderBy: 'day'
+});
+
+// ReplacingMergeTree: Deduplicates data by version
+export const users = defineTable('users', {
+  id: t.uint64('id'),
+  email: t.string('email'),
+  version: t.uint64('version'),
+}, {
+  engine: Engine.ReplacingMergeTree('version'),
+  
+  // Portability: '{cluster}' references the server-side macro.
+  // This allows your schema to be environment-agnostic.
+  onCluster: '{cluster}', 
+  
+  orderBy: 'id'
+});
+```
+
+### Dictionaries
+Map external data or internal tables to fast in-memory dictionaries for ultra-low latency lookups.
+
+```typescript
+import { defineDictionary } from '@housekit/orm';
+
+export const userCache = defineDictionary('user_dict', {
+  id: t.uint64('id'),
+  country: t.string('country')
+}, {
+  source: { table: users },
+  layout: { type: 'hashed' },
+  lifetime: 300
+});
+```
+
+---
+
+## 🚀 High-Performance Data Ingestion
+
+### Automatic Turbo Mode (RowBinary)
+When you call `db.insert()`, HouseKit analyzes your schema. If all types are compatible, it automatically switches to **Turbo Mode**, using native binary serialization instead of JSON.
+
+```typescript
+await db.insert(webEvents).values([
+  { id: '...', eventType: 'click', revenue: 0, metadata: { browser: 'chrome' } },
+  { id: '...', eventType: 'purchase', revenue: 99.90, metadata: { browser: 'safari' } },
+]);
+// Logic: Object -> Buffer (Binary) -> ClickHouse Stream (Zero-copy)
+```
+
+### Background Batching
+Collect small, frequent writes into large batches to prevent the "too many parts" error in ClickHouse.
+
+```typescript
+const builder = db.insert(webEvents)
+  .batch({ 
+    maxRows: 10000, 
+    flushIntervalMs: 5000 
+  });
+
+// These calls return immediately, flushing happens in the background
+builder.values(row1).execute();
+builder.values(row2).execute();
+```
+
+---
+
+## 🤝 Smart Relational API
+
+Traditional ORMs produce "Flat Joins" that duplicate data (the Cartesian Product problem). HouseKit's Relational API uses ClickHouse's `groupArray` internally to fetch related data as nested arrays in a single, efficient query.
+
+```typescript
+const usersWithData = await db.query.users.findMany({
+  with: {
+    posts: {
+      where: (p) => eq(p.published, true),
+      limit: 5
+    },
+    profile: true
+  },
+  limit: 10
+});
+
+// Result structure:
+// [{ id: 1, name: 'Alice', posts: [{ title: '...', ... }], profile: { bio: '...' } }]
+```
+
+---
+
+## 🔍 Specialized ClickHouse Joins
+
+### ASOF JOIN
+The industry standard for time-series matches (e.g., matching a trade with the closest price quote).
+
+```typescript
+const matched = await db.select()
+  .from(trades)
+  .asofJoin(quotes, sql`${trades.symbol} = ${quotes.symbol} AND ${trades.at} >= ${quotes.at}`)
+  .limit(100);
+```
+
+### GLOBAL JOIN
+Essential for distributed setups to avoid local-data-only results on sharded clusters.
+
+```typescript
+db.select().from(distributedTable).globalJoin(rightTable, condition);
+```
+
+---
+
+## 🛠 Observability & Logging
+
+Inject a custom logger to monitor query performance, throughput, and error rates.
+
+```typescript
+const db = await createClient({
+  logger: {
+    logQuery: (sql, params, duration, stats) => {
+      console.log(`[Query] ${duration}ms | Rows: ${stats.readRows}`);
+    },
+    logError: (err, sql) => console.error(`[Error] ${err.message}`)
+  }
+});
+```
+
+---
+
+## License
+
+MIT © [Pablo Fernandez Ruiz](https://github.com/pablofdezr)

package/dist/builders/delete.d.ts

@@ -0,0 +1,21 @@
+import type { ClickHouseClient } from '@clickhouse/client';
+import type { SQLExpression } from '../expressions';
+import type { TableDefinition, TableColumns } from '../core';
+export declare class ClickHouseDeleteBuilder<TTable extends TableDefinition<TableColumns>> {
+    private client;
+    private table;
+    private _where;
+    private _lastMutationId;
+    constructor(client: ClickHouseClient, table: TTable);
+    where(expression: SQLExpression): this;
+    toSQL(): {
+        query: string;
+        params: Record<string, unknown>;
+    };
+    execute(): Promise<void>;
+    wait(options?: {
+        pollIntervalMs?: number;
+        timeoutMs?: number;
+    }): Promise<void>;
+    then<TResult1 = void, TResult2 = never>(onfulfilled?: ((value: void) => TResult1 | PromiseLike<TResult1>) | null, onrejected?: ((reason: any) => TResult2 | PromiseLike<TResult2>) | null): Promise<TResult1 | TResult2>;
+}

package/dist/builders/insert.d.ts

@@ -0,0 +1,128 @@
+import type { ClickHouseClient } from '@clickhouse/client';
+import { type TableDefinition, type TableInsert, type TableColumns } from '../core';
+import { type BatchTransformOptions } from '../utils/batch-transform';
+import { Readable } from 'stream';
+import { type BatchConfig } from '../utils/background-batcher';
+/**
+ * Insert format strategy:
+ * - 'auto': Automatically choose best format (default - uses binary when possible)
+ * - 'binary': Force RowBinary format (fastest)
+ * - 'json': Force JSON format (for debugging/compatibility)
+ * - 'compact': Force JSONCompactEachRow (smaller than JSON, faster than JSON)
+ */
+type InsertFormat = 'auto' | 'binary' | 'json' | 'compact';
+export interface InsertOptions {
+    /**
+     * Format strategy for serialization.
+     * Default: 'auto' (uses RowBinary when possible, falls back to JSON)
+     */
+    format?: InsertFormat;
+    /** Rows per batch when streaming */
+    batchSize?: number;
+}
+export declare class ClickHouseInsertBuilder<TTable extends TableDefinition<TableColumns>> {
+    private client;
+    private table;
+    private _values;
+    private _async;
+    private _waitForAsync;
+    private _batchOptions;
+    private _format;
+    private _batchSize;
+    private _batchConfig;
+    private _forceJson;
+    constructor(client: ClickHouseClient, table: TTable);
+    values(value: TableInsert<TTable['$columns']> | Array<TableInsert<TTable['$columns']>> | Iterable<TableInsert<TTable['$columns']>> | AsyncIterable<TableInsert<TTable['$columns']>> | Readable): this;
+    /**
+     * Force synchronous insert (disables async_insert).
+     * Use when you need immediate durability guarantee.
+     *
+     * Note: By default, HouseKit uses async_insert for better performance.
+     * The data is still durable, but ClickHouse batches writes internally.
+     */
+    syncInsert(): this;
+    /**
+     * Enables asynchronous inserts on the server.
+     * ClickHouse will batch multiple small inserts into a single disk operation.
+     * Ideal for high-frequency logs or events.
+     */
+    asyncInsert(waitForCompletion?: boolean): this;
+    /**
+     * Activate Background Batching (Client-side buffering).
+     *
+     * Instead of sending request immediately, rows are buffered in memory
+     * and sent when limit is reached or interval passes.
+     *
+     * @param options Batch configuration
+     */
+    batch(options?: Partial<BatchConfig>): this;
+    /** Configure batch processing options */
+    batchOptions(options: BatchTransformOptions): this;
+    /**
+     * Set the batch size for streaming inserts.
+     * Larger batches = better throughput, higher memory usage.
+     * Default: 1000
+     */
+    batchSize(size: number): this;
+    /**
+     * Force JSON format (useful for debugging or compatibility).
+     *
+     * Note: HouseKit uses RowBinary by default for maximum performance.
+     * Only use this when you need human-readable output or debugging.
+     *
+     * @example
+     * ```typescript
+     * await db.insert(events)
+     *   .values(rows)
+     *   .useJsonFormat() // For debugging
+     *   .execute();
+     * ```
+     */
+    useJsonFormat(): this;
+    /**
+     * Force JSONCompactEachRow format (smaller than JSON, but slower than binary).
+     */
+    useCompactFormat(): this;
+    /**
+     * Force RowBinary format (this is already the default via 'auto').
+     * Explicit call for documentation purposes.
+     */
+    useBinaryFormat(): this;
+    /**
+     * Activates "Turbo Mode" (RowBinary).
+     * Sends data in native binary format, skipping JSON parsing on the server.
+     * Up to 5x faster than normal insertion.
+     */
+    turbo(): this;
+    execute(): Promise<void>;
+    /**
+     * Resolve the actual format to use based on settings and table capabilities.
+     *
+     * Binary is preferred when:
+     * - No columns require server-side UUID generation
+     * - All column types are supported by our binary encoder
+     *
+     * Falls back to JSON when:
+     * - Columns use server-side defaults (e.g., generateUUIDv4())
+     * - Unsupported types are detected
+     */
+    private resolveFormat;
+    /**
+     * Check if table and data are compatible with binary format
+     */
+    private canUseBinaryFormat;
+    /**
+     * Execute insert using JSON format
+     */
+    private executeJsonInsert;
+    /**
+     * Execute insert using RowBinary format (fastest)
+     */
+    private executeBinaryInsert;
+    /**
+     * Process rows and yield them with column names mapped and defaults applied
+     */
+    private processRows;
+    then<TResult1 = void, TResult2 = never>(onfulfilled?: ((value: void) => TResult1 | PromiseLike<TResult1>) | null, onrejected?: ((reason: any) => TResult2 | PromiseLike<TResult2>) | null): Promise<TResult1 | TResult2>;
+}
+export {};

package/dist/builders/prepared.d.ts

@@ -0,0 +1,11 @@
+export declare class PreparedQuery<TResult> {
+    private client;
+    readonly sql: string;
+    private paramKeys;
+    private querySuggestions;
+    private columnNames;
+    private columnTypes;
+    constructor(client: any, sql: string, paramKeys: string[], // The order of parameters (p_1, p_2...)
+    querySuggestions: string[], columnNames?: string[], columnTypes?: string[]);
+    execute(values: any[]): Promise<TResult[]>;
+}