@hypequery/clickhouse 1.4.0-beta.2 → 1.4.0

package/dist/core/cache/providers/memory-lru.js

@@ -0,0 +1,156 @@
+function extractNamespace(key) {
+    const parts = key.split(':');
+    if (parts.length < 4) {
+        return 'default';
+    }
+    if (parts.length === 4) {
+        return parts[2];
+    }
+    // Namespace may contain additional ':' (e.g., protocol prefixes); rejoin everything
+    // between the version segment and the trailing table/digest tokens.
+    const namespace = parts.slice(2, -2).join(':');
+    return namespace || 'default';
+}
+export class MemoryCacheProvider {
+    entries = new Map();
+    tagIndex = new Map();
+    currentBytes = 0;
+    maxEntries;
+    maxBytes;
+    cleanupIntervalMs;
+    cleanupTimer;
+    constructor(options = {}) {
+        this.maxEntries = options.maxEntries ?? 1000;
+        this.maxBytes = options.maxBytes ?? 50 * 1024 * 1024;
+        this.cleanupIntervalMs = options.cleanupIntervalMs ?? 30_000;
+        if (this.cleanupIntervalMs > 0 && typeof setInterval !== 'undefined') {
+            this.cleanupTimer = setInterval(() => this.cleanup(), this.cleanupIntervalMs);
+            const timer = this.cleanupTimer;
+            if (typeof timer.unref === 'function') {
+                timer.unref();
+            }
+        }
+    }
+    dispose() {
+        if (this.cleanupTimer) {
+            clearInterval(this.cleanupTimer);
+            this.cleanupTimer = undefined;
+        }
+    }
+    async get(key) {
+        this.cleanup();
+        const entry = this.entries.get(key);
+        if (!entry)
+            return null;
+        if (entry.cacheTimeMs > 0 && Date.now() > entry.createdAt + entry.cacheTimeMs) {
+            await this.delete(key);
+            return null;
+        }
+        this.touch(key, entry);
+        return entry;
+    }
+    async set(key, entry) {
+        const existing = this.entries.get(key);
+        if (existing) {
+            this.currentBytes -= existing.byteSize || 0;
+            this.unindexTags(key, existing.tags);
+        }
+        this.entries.set(key, entry);
+        this.currentBytes += entry.byteSize || 0;
+        this.indexTags(key, entry.tags);
+        this.enforceLimits();
+    }
+    async delete(key) {
+        const entry = this.entries.get(key);
+        if (!entry)
+            return;
+        this.entries.delete(key);
+        this.currentBytes -= entry.byteSize || 0;
+        this.unindexTags(key, entry.tags);
+    }
+    async deleteByTag(namespace, tag) {
+        const indexKey = this.getTagIndexKey(namespace, tag);
+        const keys = this.tagIndex.get(indexKey);
+        if (!keys)
+            return;
+        for (const key of keys) {
+            await this.delete(key);
+        }
+        this.tagIndex.delete(indexKey);
+    }
+    async clearNamespace(namespace) {
+        const keys = Array.from(this.entries.keys());
+        await Promise.all(keys.map(key => {
+            if (extractNamespace(key) === namespace) {
+                return this.delete(key);
+            }
+            return Promise.resolve();
+        }));
+    }
+    touch(key, entry) {
+        this.entries.delete(key);
+        this.entries.set(key, entry);
+    }
+    enforceLimits() {
+        while (this.entries.size > this.maxEntries || this.currentBytes > this.maxBytes) {
+            const oldestKey = this.entries.keys().next().value;
+            if (!oldestKey)
+                break;
+            this.delete(oldestKey);
+        }
+    }
+    cleanup() {
+        if (!this.entries.size)
+            return;
+        const now = Date.now();
+        for (const [key, entry] of this.entries) {
+            if (entry.cacheTimeMs > 0 && now > entry.createdAt + entry.cacheTimeMs) {
+                this.delete(key);
+            }
+        }
+        this.cleanupTagIndex();
+    }
+    indexTags(key, tags) {
+        if (!tags || !tags.length)
+            return;
+        const namespace = extractNamespace(key);
+        tags.forEach(tag => {
+            const indexKey = this.getTagIndexKey(namespace, tag);
+            if (!this.tagIndex.has(indexKey)) {
+                this.tagIndex.set(indexKey, new Set());
+            }
+            this.tagIndex.get(indexKey).add(key);
+        });
+    }
+    unindexTags(key, tags) {
+        if (!tags || !tags.length)
+            return;
+        const namespace = extractNamespace(key);
+        tags.forEach(tag => {
+            const indexKey = this.getTagIndexKey(namespace, tag);
+            const bucket = this.tagIndex.get(indexKey);
+            if (!bucket)
+                return;
+            bucket.delete(key);
+            if (!bucket.size) {
+                this.tagIndex.delete(indexKey);
+            }
+        });
+    }
+    getTagIndexKey(namespace, tag) {
+        return `${namespace}:${tag}`;
+    }
+    cleanupTagIndex() {
+        for (const [indexKey, keys] of this.tagIndex) {
+            for (const key of keys) {
+                if (!this.entries.has(key)) {
+                    keys.delete(key);
+                }
+            }
+            if (!keys.size) {
+                this.tagIndex.delete(indexKey);
+            }
+        }
+    }
+}
+export { MemoryCacheProvider as MemoryLRUCacheProvider };

package/dist/core/cache/providers/noop.d.ts

@@ -0,0 +1,7 @@
+import type { CacheEntry, CacheProvider } from '../types.js';
+export declare class NoopCacheProvider implements CacheProvider {
+    get(_key: string): Promise<CacheEntry | null>;
+    set(_key: string, _entry: CacheEntry): Promise<void>;
+    delete(_key: string): Promise<void>;
+}
+//# sourceMappingURL=noop.d.ts.map

package/dist/core/cache/providers/noop.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"noop.d.ts","sourceRoot":"","sources":["../../../../src/core/cache/providers/noop.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAE7D,qBAAa,iBAAkB,YAAW,aAAa;IAC/C,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC;IAI7C,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC;IAIpD,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;CAG1C"}

package/dist/core/cache/providers/noop.js

@@ -0,0 +1,11 @@
+export class NoopCacheProvider {
+    async get(_key) {
+        return null;
+    }
+    async set(_key, _entry) {
+        return;
+    }
+    async delete(_key) {
+        return;
+    }
+}

package/dist/core/cache/runtime-context.d.ts

@@ -0,0 +1,30 @@
+import type { CacheConfig, CacheOptions, CacheProvider, CacheSerializeFn, CacheDeserializeFn, CacheStats } from './types.js';
+export interface QueryRuntimeContext {
+    provider?: CacheProvider;
+    defaults: CacheOptions;
+    namespace: string;
+    versionTag: string;
+    serialize: CacheSerializeFn;
+    deserialize: CacheDeserializeFn;
+    inFlight: Map<string, Promise<unknown>>;
+    stats: CacheStats;
+    parsedValues: Map<string, ParsedValueEntry>;
+}
+export interface ParsedValueEntry {
+    createdAt: number;
+    rows: unknown;
+    tags?: string[];
+}
+export declare function createCacheStats(): CacheStats;
+export declare function mergeCacheOptions(...candidates: Array<CacheOptions | undefined>): CacheOptions;
+export interface CacheRuntimeConfig {
+    namespace: string;
+    versionTag: string;
+    provider?: CacheProvider;
+    defaults: CacheOptions;
+    serialize: CacheSerializeFn;
+    deserialize: CacheDeserializeFn;
+}
+export declare function buildRuntimeContext(config: CacheRuntimeConfig): QueryRuntimeContext;
+export declare function resolveCacheConfig(config: CacheConfig | undefined, fallbackNamespace: string): CacheRuntimeConfig;
+//# sourceMappingURL=runtime-context.d.ts.map

package/dist/core/cache/runtime-context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime-context.d.ts","sourceRoot":"","sources":["../../../src/core/cache/runtime-context.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,WAAW,EACX,YAAY,EACZ,aAAa,EACb,gBAAgB,EAChB,kBAAkB,EAClB,UAAU,EACX,MAAM,YAAY,CAAC;AAWpB,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,EAAE,aAAa,CAAC;IACzB,QAAQ,EAAE,YAAY,CAAC;IACvB,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,gBAAgB,CAAC;IAC5B,WAAW,EAAE,kBAAkB,CAAC;IAChC,QAAQ,EAAE,GAAG,CAAC,MAAM,EAAE,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC;IACxC,KAAK,EAAE,UAAU,CAAC;IAClB,YAAY,EAAE,GAAG,CAAC,MAAM,EAAE,gBAAgB,CAAC,CAAC;CAC7C;AAED,MAAM,WAAW,gBAAgB;IAC/B,SAAS,EAAE,MAAM,CAAC;IAClB,IAAI,EAAE,OAAO,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;CACjB;AAED,wBAAgB,gBAAgB,IAAI,UAAU,CAE7C;AAQD,wBAAgB,iBAAiB,CAAC,GAAG,UAAU,EAAE,KAAK,CAAC,YAAY,GAAG,SAAS,CAAC,GAAG,YAAY,CAe9F;AAED,MAAM,WAAW,kBAAkB;IACjC,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,EAAE,aAAa,CAAC;IACzB,QAAQ,EAAE,YAAY,CAAC;IACvB,SAAS,EAAE,gBAAgB,CAAC;IAC5B,WAAW,EAAE,kBAAkB,CAAC;CACjC;AAED,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,kBAAkB,GAAG,mBAAmB,CAYnF;AAED,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,WAAW,GAAG,SAAS,EAAE,iBAAiB,EAAE,MAAM,GAAG,kBAAkB,CAUjH"}

package/dist/core/cache/runtime-context.js

@@ -0,0 +1,58 @@
+import { defaultSerialize, defaultDeserialize } from './serialization.js';
+const DEFAULT_CACHE_OPTIONS = {
+    mode: 'no-store',
+    ttlMs: 0,
+    staleTtlMs: 0,
+    staleIfError: false,
+    dedupe: true
+};
+export function createCacheStats() {
+    return { hits: 0, misses: 0, staleHits: 0, revalidations: 0 };
+}
+function uniqueTags(left, right) {
+    const combined = [...(left || []), ...(right || [])];
+    if (!combined.length)
+        return undefined;
+    return Array.from(new Set(combined));
+}
+export function mergeCacheOptions(...candidates) {
+    return candidates.reduce((acc, candidate) => {
+        if (!candidate)
+            return acc;
+        const next = { ...acc };
+        for (const [key, value] of Object.entries(candidate)) {
+            if (key === 'tags') {
+                next.tags = uniqueTags(next.tags, value);
+                continue;
+            }
+            if (value !== undefined) {
+                next[key] = value;
+            }
+        }
+        return next;
+    }, { ...DEFAULT_CACHE_OPTIONS });
+}
+export function buildRuntimeContext(config) {
+    return {
+        provider: config.provider,
+        defaults: { ...config.defaults },
+        namespace: config.namespace,
+        versionTag: config.versionTag,
+        serialize: config.serialize,
+        deserialize: config.deserialize,
+        inFlight: new Map(),
+        stats: createCacheStats(),
+        parsedValues: new Map()
+    };
+}
+export function resolveCacheConfig(config, fallbackNamespace) {
+    const defaults = mergeCacheOptions(config);
+    return {
+        namespace: config?.namespace || fallbackNamespace,
+        versionTag: config?.versionTag || 'v1',
+        provider: config?.provider,
+        defaults,
+        serialize: config?.serialize || ((value) => defaultSerialize(value)),
+        deserialize: config?.deserialize || ((raw) => defaultDeserialize(raw))
+    };
+}

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

@@ -0,0 +1,6 @@
+import type { CacheSerializationResult } from './types.js';
+export declare function stableStringify(value: unknown): string;
+export declare function defaultSerialize(value: unknown): CacheSerializationResult;
+export declare function defaultDeserialize<T = unknown>(raw: string | Uint8Array): T;
+export declare function estimateByteSize(value: unknown): number;
+//# sourceMappingURL=serialization.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"serialization.d.ts","sourceRoot":"","sources":["../../../src/core/cache/serialization.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,YAAY,CAAC;AAiH3D,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAEtD;AAyDD,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,OAAO,GAAG,wBAAwB,CAOzE;AAED,wBAAgB,kBAAkB,CAAC,CAAC,GAAG,OAAO,EAAE,GAAG,EAAE,MAAM,GAAG,UAAU,GAAG,CAAC,CAQ3E;AAED,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAMvD"}

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.map

@@ -1 +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;AAEtF,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAI3D,KAAK,gBAAgB,GAAG,oBAAoB,GAAG,mBAAmB,CAAC;AAqCnE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;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"}
+{"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

@@ -1,5 +1,5 @@
-import { createClient as createNodeClient } from '@clickhouse/client';
 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';
@@ -9,9 +9,10 @@ function getClickHouseClientSync() {
         if (isDev) {
             console.log('hypequery: Using @clickhouse/client for Node.js environment');
         }
+        const clientModule = getAutoClientModule();
         return {
-            createClient: createNodeClient,
-            ClickHouseSettings: {}
+            createClient: clientModule.createClient,
+            ClickHouseSettings: clientModule.ClickHouseSettings || {}
         };
     }
     // For browser environments, require() doesn't work, so we can't auto-detect

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

@@ -1,6 +1,9 @@
 import { FilterConditionInput, FilterOperator, OperatorValueMap } from '../types/index.js';
-import type { ColumnType, InferColumnType } from '../types/index.js';
-export interface FilterGroup<Schema extends Record<string, Record<string, any>> = any, OriginalT extends Record<string, any> = any> {
+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;
@@ -14,14 +17,13 @@ export interface FilterGroup<Schema extends Record<string, Record<string, any>>
  * @template Schema - The full database schema type
  * @template TableName - The specific table being filtered
  */
-export declare class CrossFilter<Schema extends {
-    [tableName: string]: {
-        [columnName: string]: ColumnType;
-    };
-} = any, TableName extends keyof Schema = Extract<keyof Schema, string>> {
-    private schema?;
+export declare class CrossFilter<Schema extends SchemaDefinition<Schema> = GenericSchemaDefinition, TableName extends keyof Schema & string = Extract<keyof Schema, string>> {
     private rootGroup;
-    constructor(schema?: Schema | undefined);
+    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.
@@ -67,4 +69,5 @@ export declare class CrossFilter<Schema extends {
      */
     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

@@ -1 +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,mBAAmB,CAAC;AAGrE,MAAM,WAAW,WAAW,CAC1B,MAAM,SAAS,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC,GAAG,GAAG,EACxD,SAAS,SAAS,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,GAAG;IAE3C,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;IAAE,CAAC,SAAS,EAAE,MAAM,GAAG;QAAE,CAAC,UAAU,EAAE,MAAM,GAAG,UAAU,CAAA;KAAE,CAAA;CAAE,GAAG,GAAG,EAClF,SAAS,SAAS,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,MAAM,EAAE,MAAM,CAAC;IAMlD,OAAO,CAAC,MAAM,CAAC;IAH3B,OAAO,CAAC,SAAS,CAAyC;gBAGtC,MAAM,CAAC,EAAE,MAAM,YAAA;IAInC;;;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;IAarB;;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"}
+{"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"}