@hypequery/clickhouse 0.0.0-canary-20260306132943

package/dist/core/cache/serialization.js

@@ -0,0 +1,166 @@
+const encoder = typeof TextEncoder !== 'undefined' ? new TextEncoder() : null;
+const decoder = typeof TextDecoder !== 'undefined' ? new TextDecoder() : null;
+const TYPE_KEY = '__hq_type';
+function hasBuffer() {
+    return typeof globalThis !== 'undefined' && typeof globalThis.Buffer !== 'undefined';
+}
+function bufferFrom(bytes) {
+    return globalThis.Buffer.from(bytes);
+}
+function bufferToUint8(buffer) {
+    return new Uint8Array(buffer.buffer, buffer.byteOffset, buffer.byteLength);
+}
+function toBase64(bytes) {
+    if (hasBuffer()) {
+        return bufferFrom(bytes).toString('base64');
+    }
+    let binary = '';
+    for (let i = 0; i < bytes.length; i++) {
+        binary += String.fromCharCode(bytes[i]);
+    }
+    if (typeof btoa !== 'undefined') {
+        return btoa(binary);
+    }
+    throw new Error('Base64 encoding not supported in this environment.');
+}
+function fromBase64(value) {
+    if (hasBuffer()) {
+        const buf = globalThis.Buffer.from(value, 'base64');
+        return bufferToUint8(buf);
+    }
+    if (typeof atob === 'undefined') {
+        throw new Error('Base64 decoding not supported in this environment.');
+    }
+    const binary = atob(value);
+    const bytes = new Uint8Array(binary.length);
+    for (let i = 0; i < binary.length; i++) {
+        bytes[i] = binary.charCodeAt(i);
+    }
+    return bytes;
+}
+function normalizeForStable(value) {
+    if (value === null || typeof value === 'number' || typeof value === 'boolean') {
+        return Number.isNaN(value)
+            ? { [TYPE_KEY]: 'nan', value: 'NaN' }
+            : value;
+    }
+    if (typeof value === 'string') {
+        return value;
+    }
+    if (typeof value === 'bigint') {
+        return { [TYPE_KEY]: 'bigint', value: value.toString() };
+    }
+    if (typeof value === 'undefined') {
+        return { [TYPE_KEY]: 'undefined' };
+    }
+    if (value instanceof Date) {
+        return { [TYPE_KEY]: 'date', value: value.toISOString() };
+    }
+    if (Array.isArray(value)) {
+        return value.map(item => normalizeForStable(item));
+    }
+    if (value instanceof Set) {
+        return Array.from(value.values())
+            .map(item => normalizeForStable(item))
+            .sort((a, b) => JSON.stringify(a).localeCompare(JSON.stringify(b)));
+    }
+    if (value instanceof Map) {
+        const entries = Array.from(value.entries()).sort(([a], [b]) => String(a).localeCompare(String(b)));
+        const normalized = {};
+        for (const [key, val] of entries) {
+            normalized[String(key)] = normalizeForStable(val);
+        }
+        return normalized;
+    }
+    if (typeof ArrayBuffer !== 'undefined' && ArrayBuffer.isView(value)) {
+        const uint8 = new Uint8Array(value.buffer, value.byteOffset, value.byteLength);
+        return { [TYPE_KEY]: 'u8', value: toBase64(uint8) };
+    }
+    if (value && typeof value === 'object') {
+        const raw = value;
+        const keys = Object.keys(raw).sort();
+        const normalized = {};
+        for (const key of keys) {
+            normalized[key] = normalizeForStable(raw[key]);
+        }
+        return normalized;
+    }
+    return { [TYPE_KEY]: 'unknown', value: String(value) };
+}
+export function stableStringify(value) {
+    return JSON.stringify(normalizeForStable(value));
+}
+function encodeSpecial(value) {
+    if (typeof value === 'bigint') {
+        return { [TYPE_KEY]: 'bigint', value: value.toString() };
+    }
+    if (value instanceof Date) {
+        return { [TYPE_KEY]: 'date', value: value.toISOString() };
+    }
+    if (typeof value === 'undefined') {
+        return { [TYPE_KEY]: 'undefined' };
+    }
+    if (typeof ArrayBuffer !== 'undefined' && ArrayBuffer.isView(value)) {
+        const uint8 = new Uint8Array(value.buffer, value.byteOffset, value.byteLength);
+        return { [TYPE_KEY]: 'u8', value: toBase64(uint8) };
+    }
+    return undefined;
+}
+function decodeSpecial(value) {
+    switch (value[TYPE_KEY]) {
+        case 'bigint':
+            return value.value !== undefined ? BigInt(value.value) : undefined;
+        case 'date':
+            return value.value ? new Date(value.value) : null;
+        case 'undefined':
+            return undefined;
+        case 'u8':
+            if (!value.value)
+                return new Uint8Array();
+            return fromBase64(value.value);
+        case 'nan':
+            return Number.NaN;
+        default:
+            return value.value;
+    }
+}
+function reviveSpecialValues(value) {
+    if (!value || typeof value !== 'object') {
+        return value;
+    }
+    if (value[TYPE_KEY]) {
+        return decodeSpecial(value);
+    }
+    if (Array.isArray(value)) {
+        return value.map(item => reviveSpecialValues(item));
+    }
+    const record = value;
+    for (const key of Object.keys(record)) {
+        record[key] = reviveSpecialValues(record[key]);
+    }
+    return record;
+}
+export function defaultSerialize(value) {
+    const json = JSON.stringify(value, (_key, val) => encodeSpecial(val) ?? val);
+    if (!encoder) {
+        return { payload: json, byteSize: json.length };
+    }
+    const bytes = encoder.encode(json);
+    return { payload: bytes, byteSize: bytes.byteLength };
+}
+export function defaultDeserialize(raw) {
+    const json = typeof raw === 'string'
+        ? raw
+        : encoder && decoder
+            ? decoder.decode(raw)
+            : new TextDecoder().decode(raw);
+    const parsed = JSON.parse(json);
+    return reviveSpecialValues(parsed);
+}
+export function estimateByteSize(value) {
+    const json = JSON.stringify(value);
+    if (!encoder) {
+        return json.length;
+    }
+    return encoder.encode(json).byteLength;
+}

package/dist/core/cache/types.d.ts

@@ -0,0 +1,52 @@
+export type hypequeryCacheMode = 'no-store' | 'cache-first' | 'network-first' | 'stale-while-revalidate';
+export interface CacheSerializationResult {
+    payload: string | Uint8Array;
+    byteSize: number;
+}
+export type CacheSerializeFn = (value: unknown) => CacheSerializationResult | Promise<CacheSerializationResult>;
+export type CacheDeserializeFn<T = unknown> = (raw: string | Uint8Array) => T | Promise<T>;
+export type CacheStatus = 'hit' | 'miss' | 'stale-hit' | 'revalidate' | 'bypass';
+export interface CacheOptions {
+    mode?: hypequeryCacheMode;
+    ttlMs?: number;
+    staleTtlMs?: number;
+    cacheTimeMs?: number;
+    staleIfError?: boolean;
+    dedupe?: boolean;
+    tags?: string[];
+    key?: string;
+    namespace?: string;
+    serialize?: CacheSerializeFn;
+    deserialize?: CacheDeserializeFn;
+}
+export interface CacheConfig extends CacheOptions {
+    provider?: CacheProvider;
+    versionTag?: string;
+}
+export interface CacheEntry<TSerialized = string | Uint8Array> {
+    value: TSerialized;
+    createdAt: number;
+    ttlMs: number;
+    staleTtlMs: number;
+    cacheTimeMs: number;
+    tags?: string[];
+    rowCount?: number;
+    byteSize?: number;
+    sqlFingerprint?: string;
+    metadata?: Record<string, unknown>;
+    status?: 'pending' | 'fulfilled' | 'revalidating' | 'error';
+}
+export interface CacheProvider<TSerialized = string | Uint8Array> {
+    get(key: string): Promise<CacheEntry<TSerialized> | null>;
+    set(key: string, entry: CacheEntry<TSerialized>): Promise<void>;
+    delete(key: string): Promise<void>;
+    deleteByTag?(namespace: string, tag: string): Promise<void>;
+    clearNamespace?(namespace: string): Promise<void>;
+}
+export interface CacheStats {
+    hits: number;
+    misses: number;
+    staleHits: number;
+    revalidations: number;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/core/cache/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/core/cache/types.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,kBAAkB,GAC1B,UAAU,GACV,aAAa,GACb,eAAe,GACf,wBAAwB,CAAC;AAE7B,MAAM,WAAW,wBAAwB;IACvC,OAAO,EAAE,MAAM,GAAG,UAAU,CAAC;IAC7B,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,MAAM,gBAAgB,GAAG,CAAC,KAAK,EAAE,OAAO,KAAK,wBAAwB,GAAG,OAAO,CAAC,wBAAwB,CAAC,CAAC;AAChH,MAAM,MAAM,kBAAkB,CAAC,CAAC,GAAG,OAAO,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,UAAU,KAAK,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;AAE3F,MAAM,MAAM,WAAW,GAAG,KAAK,GAAG,MAAM,GAAG,WAAW,GAAG,YAAY,GAAG,QAAQ,CAAC;AAEjF,MAAM,WAAW,YAAY;IAC3B,IAAI,CAAC,EAAE,kBAAkB,CAAC;IAC1B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,SAAS,CAAC,EAAE,gBAAgB,CAAC;IAC7B,WAAW,CAAC,EAAE,kBAAkB,CAAC;CAClC;AAED,MAAM,WAAW,WAAY,SAAQ,YAAY;IAC/C,QAAQ,CAAC,EAAE,aAAa,CAAC;IACzB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,UAAU,CAAC,WAAW,GAAG,MAAM,GAAG,UAAU;IAC3D,KAAK,EAAE,WAAW,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;IACpB,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACnC,MAAM,CAAC,EAAE,SAAS,GAAG,WAAW,GAAG,cAAc,GAAG,OAAO,CAAC;CAC7D;AAED,MAAM,WAAW,aAAa,CAAC,WAAW,GAAG,MAAM,GAAG,UAAU;IAC9D,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC,WAAW,CAAC,GAAG,IAAI,CAAC,CAAC;IAC1D,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,UAAU,CAAC,WAAW,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAChE,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACnC,WAAW,CAAC,CAAC,SAAS,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC5D,cAAc,CAAC,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACnD;AAED,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;IAClB,aAAa,EAAE,MAAM,CAAC;CACvB"}

package/dist/core/cache/types.js

@@ -0,0 +1 @@
+export {};

package/dist/core/cache/utils.d.ts

@@ -0,0 +1,9 @@
+import type { CacheConfig, CacheOptions } from './types.js';
+import type { QueryRuntimeContext } from './runtime-context.js';
+import { CacheController } from './controller.js';
+export declare function mergeCacheOptionsPartial(target: CacheOptions | undefined, update: CacheOptions): CacheOptions;
+export declare function initializeCacheRuntime(cacheConfig: CacheConfig | undefined, namespace: string): {
+    runtime: QueryRuntimeContext;
+    cacheController: CacheController;
+};
+//# sourceMappingURL=utils.d.ts.map

package/dist/core/cache/utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../../../src/core/cache/utils.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAC5D,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,sBAAsB,CAAC;AAChE,OAAO,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAIlD,wBAAgB,wBAAwB,CAAC,MAAM,EAAE,YAAY,GAAG,SAAS,EAAE,MAAM,EAAE,YAAY,GAAG,YAAY,CAgB7G;AAED,wBAAgB,sBAAsB,CACpC,WAAW,EAAE,WAAW,GAAG,SAAS,EACpC,SAAS,EAAE,MAAM,GAChB;IAAE,OAAO,EAAE,mBAAmB,CAAC;IAAC,eAAe,EAAE,eAAe,CAAA;CAAE,CASpE"}

package/dist/core/cache/utils.js

@@ -0,0 +1,30 @@
+import { CacheController } from './controller.js';
+import { buildRuntimeContext, resolveCacheConfig } from './runtime-context.js';
+import { MemoryCacheProvider } from './providers/memory-lru.js';
+export function mergeCacheOptionsPartial(target, update) {
+    const result = { ...(target || {}) };
+    for (const [key, value] of Object.entries(update)) {
+        if (key === 'tags') {
+            const existing = result.tags || [];
+            const incoming = value || [];
+            if (incoming.length) {
+                result.tags = Array.from(new Set([...existing, ...incoming]));
+            }
+            continue;
+        }
+        if (value !== undefined) {
+            result[key] = value;
+        }
+    }
+    return result;
+}
+export function initializeCacheRuntime(cacheConfig, namespace) {
+    const provider = cacheConfig?.provider ?? (cacheConfig ? new MemoryCacheProvider() : undefined);
+    const mergedCacheConfig = cacheConfig
+        ? { ...cacheConfig, namespace, provider }
+        : { namespace, provider };
+    const runtimeConfig = resolveCacheConfig(mergedCacheConfig, namespace);
+    const runtime = buildRuntimeContext(runtimeConfig);
+    const cacheController = new CacheController(runtime);
+    return { runtime, cacheController };
+}

package/dist/core/connection.d.ts

@@ -0,0 +1,112 @@
+import type { ClickHouseSettings } from '@clickhouse/client-common';
+import type { ClickHouseClient as NodeClickHouseClient } from '@clickhouse/client';
+import type { ClickHouseClient as WebClickHouseClient } from '@clickhouse/client-web';
+import type { ClickHouseConfig } from './query-builder.js';
+type ClickHouseClient = NodeClickHouseClient | WebClickHouseClient;
+/**
+ * The main entry point for connecting to a ClickHouse database.
+ * Provides static methods to initialize the connection and retrieve the client.
+ *
+ * Supports two modes of operation:
+ * 1. **Manual injection**: Provide a client instance via `config.client` (required for browser environments)
+ * 2. **Auto-detection**: Automatically uses @clickhouse/client for Node.js environments
+ *
+ * @category Core
+ * @example
+ * ```typescript
+ * // Method 1: Manual injection (required for browser environments)
+ * import { createClient } from '@clickhouse/client-web';
+ * const client = createClient({
+ *   host: 'http://localhost:8123',
+ *   username: 'default',
+ *   password: 'password'
+ * });
+ *
+ * ClickHouseConnection.initialize({
+ *   host: 'http://localhost:8123',
+ *   database: 'my_database',
+ *   client // Explicitly provide the client
+ * });
+ *
+ * // Method 2: Auto-detection (Node.js environments only)
+ * ClickHouseConnection.initialize({
+ *   host: 'http://localhost:8123',
+ *   username: 'default',
+ *   password: 'password',
+ *   database: 'my_database'
+ * });
+ *
+ * // Get the client to execute queries directly
+ * const client = ClickHouseConnection.getClient();
+ * const result = await client.query({
+ *   query: 'SELECT * FROM my_table',
+ *   format: 'JSONEachRow'
+ * });
+ * ```
+ *
+ * @note This library requires one of the following peer dependencies:
+ * - @clickhouse/client (for Node.js environments)
+ * - @clickhouse/client-web (for browser environments)
+ *
+ * **Important**: Browser environments require manual injection because `require()` calls don't work in browsers.
+ */
+export declare class ClickHouseConnection {
+    private static instance;
+    private static clientModule;
+    /**
+     * Initializes the ClickHouse connection with the provided configuration.
+     * This method must be called before any queries can be executed.
+     *
+     * **Priority order:**
+     * 1. If `config.client` is provided, use it directly (manual injection)
+     * 2. Otherwise, auto-detect @clickhouse/client for Node.js environments
+     *
+     * **Note**: Browser environments require manual injection because `require()` calls don't work in browsers.
+     *
+     * @param config - The connection configuration options
+     * @returns The ClickHouseConnection class for method chaining
+     * @throws Will throw an error if no ClickHouse client is available
+     *
+     * @example
+     * ```typescript
+     * // Manual injection (required for browser environments)
+     * import { createClient } from '@clickhouse/client-web';
+     * const client = createClient({ host: 'http://localhost:8123' });
+     * ClickHouseConnection.initialize({ host: 'http://localhost:8123', client });
+     *
+     * // Auto-detection (Node.js environments only)
+     * ClickHouseConnection.initialize({
+     *   host: 'http://localhost:8123',
+     *   username: 'default',
+     *   password: 'password',
+     *   database: 'my_database'
+     * });
+     * ```
+     */
+    static initialize(config: ClickHouseConfig): typeof ClickHouseConnection;
+    /**
+     * Retrieves the ClickHouse client instance for direct query execution.
+     *
+     * @returns The ClickHouse client instance
+     * @throws Will throw an error if the connection has not been initialized
+     *
+     * @example
+     * ```typescript
+     * const client = ClickHouseConnection.getClient();
+     * const result = await client.query({
+     *   query: 'SELECT * FROM my_table',
+     *   format: 'JSONEachRow'
+     * });
+     * ```
+     */
+    static getClient(): ClickHouseClient;
+    /**
+     * Gets the ClickHouseSettings type from the loaded client module.
+     * Only available when using auto-detection (not manual injection).
+     *
+     * @returns The ClickHouseSettings type or an empty object if not available
+     */
+    static getClickHouseSettings(): ClickHouseSettings;
+}
+export {};
+//# sourceMappingURL=connection.d.ts.map

package/dist/core/connection.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"connection.d.ts","sourceRoot":"","sources":["../../src/core/connection.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAC;AACpE,OAAO,KAAK,EAAE,gBAAgB,IAAI,oBAAoB,EAAE,MAAM,oBAAoB,CAAC;AACnF,OAAO,KAAK,EAAE,gBAAgB,IAAI,mBAAmB,EAAE,MAAM,wBAAwB,CAAC;AACtF,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAM3D,KAAK,gBAAgB,GAAG,oBAAoB,GAAG,mBAAmB,CAAC;AAsCnE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8CG;AACH,qBAAa,oBAAoB;IAC/B,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAiC;IACxD,OAAO,CAAC,MAAM,CAAC,YAAY,CAAuC;IAElE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA6BG;IACH,MAAM,CAAC,UAAU,CAAC,MAAM,EAAE,gBAAgB,GAAG,OAAO,oBAAoB;IAaxE;;;;;;;;;;;;;;OAcG;IACH,MAAM,CAAC,SAAS,IAAI,gBAAgB;IAOpC;;;;;OAKG;IACH,MAAM,CAAC,qBAAqB,IAAI,kBAAkB;CAGnD"}

package/dist/core/connection.js

@@ -0,0 +1,150 @@
+import { isClientConfig } from './query-builder.js';
+import { getAutoClientModule } from './env/auto-client.js';
+// Function to synchronously get the appropriate client
+function getClickHouseClientSync() {
+    const isDev = process.env.NODE_ENV === 'development';
+    const isNode = typeof process !== 'undefined' && process.versions && process.versions.node;
+    // In Node.js environment, use Node.js client only
+    if (isNode) {
+        if (isDev) {
+            console.log('hypequery: Using @clickhouse/client for Node.js environment');
+        }
+        const clientModule = getAutoClientModule();
+        return {
+            createClient: clientModule.createClient,
+            ClickHouseSettings: clientModule.ClickHouseSettings || {}
+        };
+    }
+    // For browser environments, require() doesn't work, so we can't auto-detect
+    // Users must use manual injection in browser environments
+    throw new Error('Unable to auto-detect ClickHouse client in browser environment. ' +
+        'Please use manual injection by providing a client instance:\n\n' +
+        '```typescript\n' +
+        'import { createClient } from \'@clickhouse/client-web\';\n' +
+        'const client = createClient({ host: \'http://localhost:8123\' });\n' +
+        'ClickHouseConnection.initialize({ host: \'http://localhost:8123\', client });\n' +
+        '```\n\n' +
+        'This is required because browser environments cannot use require() to load modules.');
+}
+/**
+ * The main entry point for connecting to a ClickHouse database.
+ * Provides static methods to initialize the connection and retrieve the client.
+ *
+ * Supports two modes of operation:
+ * 1. **Manual injection**: Provide a client instance via `config.client` (required for browser environments)
+ * 2. **Auto-detection**: Automatically uses @clickhouse/client for Node.js environments
+ *
+ * @category Core
+ * @example
+ * ```typescript
+ * // Method 1: Manual injection (required for browser environments)
+ * import { createClient } from '@clickhouse/client-web';
+ * const client = createClient({
+ *   host: 'http://localhost:8123',
+ *   username: 'default',
+ *   password: 'password'
+ * });
+ *
+ * ClickHouseConnection.initialize({
+ *   host: 'http://localhost:8123',
+ *   database: 'my_database',
+ *   client // Explicitly provide the client
+ * });
+ *
+ * // Method 2: Auto-detection (Node.js environments only)
+ * ClickHouseConnection.initialize({
+ *   host: 'http://localhost:8123',
+ *   username: 'default',
+ *   password: 'password',
+ *   database: 'my_database'
+ * });
+ *
+ * // Get the client to execute queries directly
+ * const client = ClickHouseConnection.getClient();
+ * const result = await client.query({
+ *   query: 'SELECT * FROM my_table',
+ *   format: 'JSONEachRow'
+ * });
+ * ```
+ *
+ * @note This library requires one of the following peer dependencies:
+ * - @clickhouse/client (for Node.js environments)
+ * - @clickhouse/client-web (for browser environments)
+ *
+ * **Important**: Browser environments require manual injection because `require()` calls don't work in browsers.
+ */
+export class ClickHouseConnection {
+    static instance = null;
+    static clientModule = null;
+    /**
+     * Initializes the ClickHouse connection with the provided configuration.
+     * This method must be called before any queries can be executed.
+     *
+     * **Priority order:**
+     * 1. If `config.client` is provided, use it directly (manual injection)
+     * 2. Otherwise, auto-detect @clickhouse/client for Node.js environments
+     *
+     * **Note**: Browser environments require manual injection because `require()` calls don't work in browsers.
+     *
+     * @param config - The connection configuration options
+     * @returns The ClickHouseConnection class for method chaining
+     * @throws Will throw an error if no ClickHouse client is available
+     *
+     * @example
+     * ```typescript
+     * // Manual injection (required for browser environments)
+     * import { createClient } from '@clickhouse/client-web';
+     * const client = createClient({ host: 'http://localhost:8123' });
+     * ClickHouseConnection.initialize({ host: 'http://localhost:8123', client });
+     *
+     * // Auto-detection (Node.js environments only)
+     * ClickHouseConnection.initialize({
+     *   host: 'http://localhost:8123',
+     *   username: 'default',
+     *   password: 'password',
+     *   database: 'my_database'
+     * });
+     * ```
+     */
+    static initialize(config) {
+        // If a client is explicitly provided, use it directly
+        if (isClientConfig(config)) {
+            this.instance = config.client;
+            return ClickHouseConnection;
+        }
+        // Otherwise, auto-detect the client (we know we have a host-based config)
+        this.clientModule = getClickHouseClientSync();
+        this.instance = this.clientModule.createClient(config);
+        return ClickHouseConnection;
+    }
+    /**
+     * Retrieves the ClickHouse client instance for direct query execution.
+     *
+     * @returns The ClickHouse client instance
+     * @throws Will throw an error if the connection has not been initialized
+     *
+     * @example
+     * ```typescript
+     * const client = ClickHouseConnection.getClient();
+     * const result = await client.query({
+     *   query: 'SELECT * FROM my_table',
+     *   format: 'JSONEachRow'
+     * });
+     * ```
+     */
+    static getClient() {
+        if (!this.instance) {
+            throw new Error('ClickHouse connection not initialized. Call ClickHouseConnection.initialize() first.');
+        }
+        return this.instance;
+    }
+    /**
+     * Gets the ClickHouseSettings type from the loaded client module.
+     * Only available when using auto-detection (not manual injection).
+     *
+     * @returns The ClickHouseSettings type or an empty object if not available
+     */
+    static getClickHouseSettings() {
+        return this.clientModule?.ClickHouseSettings || {};
+    }
+}

package/dist/core/cross-filter.d.ts

@@ -0,0 +1,73 @@
+import { FilterConditionInput, FilterOperator, OperatorValueMap } from '../types/index.js';
+import type { ColumnType, InferColumnType } from '../types/schema.js';
+import type { SchemaDefinition } from './types/builder-state.js';
+type GenericSchema = Record<string, Record<string, ColumnType>>;
+type GenericSchemaDefinition = SchemaDefinition<GenericSchema>;
+export interface FilterGroup<Schema extends SchemaDefinition<Schema> = GenericSchemaDefinition, OriginalT extends Record<string, any> = Record<string, any>> {
+    operator: 'AND' | 'OR';
+    conditions: Array<FilterConditionInput<any, Schema, OriginalT> | FilterGroup<Schema, OriginalT>>;
+    limit?: number;
+    orderBy?: {
+        column: keyof OriginalT;
+        direction: 'ASC' | 'DESC';
+    };
+}
+/**
+ * A type-safe filter builder supporting both simple conditions and complex nested groups.
+ * @template Schema - The full database schema type
+ * @template TableName - The specific table being filtered
+ */
+export declare class CrossFilter<Schema extends SchemaDefinition<Schema> = GenericSchemaDefinition, TableName extends keyof Schema & string = Extract<keyof Schema, string>> {
+    private rootGroup;
+    private schema?;
+    private targetTable?;
+    constructor();
+    constructor(schema: Schema);
+    constructor(schema: Schema, tableName: TableName);
+    /**
+     * Adds a single filter condition to the root group with an implicit AND conjunction.
+     * Performs type-safe validation if a schema is provided.
+     */
+    add<ColumnName extends Extract<keyof Schema[TableName], string>, Op extends FilterOperator>(condition: FilterConditionInput<OperatorValueMap<InferColumnType<Schema[TableName][ColumnName]>>[Op], Schema, Schema[TableName]>): this;
+    /**
+     * Adds multiple filter conditions to the root group.
+     */
+    addMultiple(conditions: Array<FilterConditionInput<any, Schema, Schema[TableName]>>): this;
+    /**
+     * Adds a nested group of filter conditions to the root group using the specified logical operator.
+     * @param groupConditions - Array of filter conditions or nested groups to be grouped together.
+     * @param operator - Logical operator ('AND' or 'OR') to combine the conditions in the group.
+     */
+    addGroup(groupConditions: Array<FilterConditionInput<any, Schema, Schema[TableName]> | FilterGroup<Schema, Schema[TableName]>>, operator: 'AND' | 'OR'): this;
+    /**
+     * Returns the current filter tree representing all conditions and groups.
+     */
+    getConditions(): FilterGroup<Schema, Schema[TableName]>;
+    /**
+     * Looks up a column's type from the schema.
+     * Defaults to 'String' if no schema is provided.
+     * @param column - The column name as a string.
+     */
+    private getColumnType;
+    /**
+     * Validates the value of a filter condition against its expected column type.
+     */
+    private validateValueType;
+    /**
+     * Recursively validates an array of filter conditions and nested groups.
+     */
+    private validateGroup;
+    /**
+     * Type guard to check if an item is a FilterGroup.
+     */
+    private isGroup;
+    /**
+     * Creates a filter for top N records by a value column
+     * @param valueColumn - The column to filter and order by
+     * @param n - Number of records to return
+     * @param orderBy - Sort direction, defaults to 'desc'
+     */
+    topN<K extends keyof Schema[TableName]>(valueColumn: K, n: number, orderBy?: 'desc' | 'asc'): this;
+}
+export {};
+//# sourceMappingURL=cross-filter.d.ts.map

package/dist/core/cross-filter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cross-filter.d.ts","sourceRoot":"","sources":["../../src/core/cross-filter.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,oBAAoB,EAAE,cAAc,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AAC3F,OAAO,KAAK,EAAE,UAAU,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AACtE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AAEjE,KAAK,aAAa,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC,CAAC;AAChE,KAAK,uBAAuB,GAAG,gBAAgB,CAAC,aAAa,CAAC,CAAC;AAG/D,MAAM,WAAW,WAAW,CAC1B,MAAM,SAAS,gBAAgB,CAAC,MAAM,CAAC,GAAG,uBAAuB,EACjE,SAAS,SAAS,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC;IAE3D,QAAQ,EAAE,KAAK,GAAG,IAAI,CAAC;IACvB,UAAU,EAAE,KAAK,CACf,oBAAoB,CAAC,GAAG,EAAE,MAAM,EAAE,SAAS,CAAC,GAAG,WAAW,CAAC,MAAM,EAAE,SAAS,CAAC,CAC9E,CAAC;IACF,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE;QACR,MAAM,EAAE,MAAM,SAAS,CAAC;QACxB,SAAS,EAAE,KAAK,GAAG,MAAM,CAAC;KAC3B,CAAC;CACH;AAED;;;;GAIG;AACH,qBAAa,WAAW,CACtB,MAAM,SAAS,gBAAgB,CAAC,MAAM,CAAC,GAAG,uBAAuB,EACjE,SAAS,SAAS,MAAM,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,MAAM,MAAM,EAAE,MAAM,CAAC;IAGvE,OAAO,CAAC,SAAS,CAAyC;IAC1D,OAAO,CAAC,MAAM,CAAC,CAAS;IACxB,OAAO,CAAC,WAAW,CAAC,CAAY;;gBAIpB,MAAM,EAAE,MAAM;gBACd,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,SAAS;IAOhD;;;OAGG;IACH,GAAG,CACD,UAAU,SAAS,OAAO,CAAC,MAAM,MAAM,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC,EAC3D,EAAE,SAAS,cAAc,EAEzB,SAAS,EAAE,oBAAoB,CAC7B,gBAAgB,CAAC,eAAe,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,EACpE,MAAM,EACN,MAAM,CAAC,SAAS,CAAC,CAClB,GACA,IAAI;IA0BP;;OAEG;IACH,WAAW,CACT,UAAU,EAAE,KAAK,CAAC,oBAAoB,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,SAAS,CAAC,CAAC,CAAC,GACtE,IAAI;IAQP;;;;OAIG;IACH,QAAQ,CACN,eAAe,EAAE,KAAK,CACpB,oBAAoB,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,SAAS,CAAC,CAAC,GAAG,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,SAAS,CAAC,CAAC,CAC9F,EACD,QAAQ,EAAE,KAAK,GAAG,IAAI,GACrB,IAAI;IAYP;;OAEG;IACH,aAAa,IAAI,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,SAAS,CAAC,CAAC;IAIvD;;;;OAIG;IACH,OAAO,CAAC,aAAa;IAerB;;OAEG;IACH,OAAO,CAAC,iBAAiB;IAazB;;OAEG;IACH,OAAO,CAAC,aAAa;IAqBrB;;OAEG;IACH,OAAO,CAAC,OAAO;IAMf;;;;;OAKG;IACH,IAAI,CAAC,CAAC,SAAS,MAAM,MAAM,CAAC,SAAS,CAAC,EACpC,WAAW,EAAE,CAAC,EACd,CAAC,EAAE,MAAM,EACT,OAAO,GAAE,MAAM,GAAG,KAAc,GAC/B,IAAI;CAmBR"}