@hypequery/clickhouse 0.0.0-canary-20260306132943

package/dist/core/cache/cache-manager.js

@@ -0,0 +1,176 @@
+import { computeCacheKey } from './key.js';
+import { mergeCacheOptions } from './runtime-context.js';
+import { logger } from '../utils/logger.js';
+import { substituteParameters } from '../utils.js';
+function isCacheable(options) {
+    const ttl = options.ttlMs ?? 0;
+    const stale = options.staleTtlMs ?? 0;
+    return ttl > 0 || stale > 0;
+}
+function deriveTags(builder) {
+    const tags = new Set();
+    tags.add(builder.getTableName());
+    const joins = builder.getConfig().joins || [];
+    joins.forEach(join => tags.add(join.table));
+    return Array.from(tags);
+}
+async function logCacheHit({ sql, parameters, status, cacheKey, options, rowCount, ageMs, queryId }) {
+    const finalSQL = substituteParameters(sql, parameters);
+    const timestamp = Date.now();
+    logger.logQuery({
+        query: finalSQL,
+        parameters,
+        startTime: timestamp,
+        endTime: timestamp,
+        duration: 0,
+        status: 'completed',
+        rowCount,
+        queryId,
+        cacheStatus: status,
+        cacheKey,
+        cacheMode: options.mode,
+        cacheAgeMs: ageMs,
+        cacheRowCount: rowCount
+    });
+}
+export async function executeWithCache(builder, options) {
+    const runtime = builder.getRuntimeContext();
+    const provider = runtime.provider;
+    const normalizedExecuteCache = options?.cache === false
+        ? { mode: 'no-store' }
+        : options?.cache;
+    const mergedOptions = mergeCacheOptions(runtime.defaults, builder.getCacheOptions(), normalizedExecuteCache);
+    const mode = mergedOptions.mode ?? 'no-store';
+    if (!provider || mode === 'no-store' || !isCacheable(mergedOptions)) {
+        return runWithoutCache('bypass');
+    }
+    const activeProvider = provider;
+    const { sql, parameters } = builder.toSQLWithParams();
+    const tableName = builder.getTableName();
+    const namespace = mergedOptions.namespace || runtime.namespace;
+    const key = mergedOptions.key || computeCacheKey({
+        namespace,
+        sql,
+        parameters,
+        settings: builder.getConfig().settings ? { settings: builder.getConfig().settings } : undefined,
+        version: runtime.versionTag,
+        tableName
+    });
+    const entry = await activeProvider.get(key);
+    if (!entry) {
+        runtime.parsedValues.delete(key);
+    }
+    const fresh = entry ? Date.now() < entry.createdAt + entry.ttlMs : false;
+    const staleAcceptable = entry ? Date.now() < entry.createdAt + entry.ttlMs + entry.staleTtlMs : false;
+    const deserialize = mergedOptions.deserialize || runtime.deserialize;
+    const serialize = mergedOptions.serialize || runtime.serialize;
+    const respondFromCache = async (cacheEntry, status) => {
+        const memoized = runtime.parsedValues.get(key);
+        let rows;
+        if (memoized && memoized.createdAt === cacheEntry.createdAt) {
+            rows = memoized.rows;
+        }
+        else {
+            rows = await deserialize(cacheEntry.value);
+            runtime.parsedValues.set(key, { createdAt: cacheEntry.createdAt, rows, tags: cacheEntry.tags });
+        }
+        const cacheAge = Date.now() - cacheEntry.createdAt;
+        if (status === 'hit') {
+            runtime.stats.hits += 1;
+        }
+        else if (status === 'stale-hit') {
+            runtime.stats.staleHits += 1;
+        }
+        await logCacheHit({
+            sql,
+            parameters,
+            status,
+            cacheKey: key,
+            options: mergedOptions,
+            rowCount: cacheEntry.rowCount ?? rows.length,
+            ageMs: cacheAge,
+            queryId: options?.queryId
+        });
+        return rows;
+    };
+    if (mode === 'cache-first') {
+        if (entry && fresh) {
+            return respondFromCache(entry, 'hit');
+        }
+        runtime.stats.misses += 1;
+        return fetchAndStore('miss');
+    }
+    if (mode === 'stale-while-revalidate') {
+        if (entry && fresh) {
+            return respondFromCache(entry, 'hit');
+        }
+        if (entry && staleAcceptable) {
+            scheduleRevalidation();
+            return respondFromCache(entry, 'stale-hit');
+        }
+        runtime.stats.misses += 1;
+        return fetchAndStore('miss');
+    }
+    if (mode === 'network-first') {
+        try {
+            runtime.stats.misses += 1;
+            return await fetchAndStore('miss');
+        }
+        catch (error) {
+            if (mergedOptions.staleIfError && entry && staleAcceptable) {
+                return respondFromCache(entry, 'stale-hit');
+            }
+            throw error;
+        }
+    }
+    return runWithoutCache('bypass');
+    async function fetchAndStore(cacheStatus) {
+        if (mergedOptions.dedupe !== false && runtime.inFlight.has(key)) {
+            return runtime.inFlight.get(key);
+        }
+        const promise = (async () => {
+            const rows = await builder.getExecutor().execute({
+                queryId: options?.queryId,
+                logContext: { cacheStatus, cacheKey: key, cacheMode: mode }
+            });
+            const encoded = await serialize(rows);
+            const ttlMs = mergedOptions.ttlMs ?? 0;
+            const staleTtlMs = mergedOptions.staleTtlMs ?? 0;
+            const cacheTimeMs = mergedOptions.cacheTimeMs ?? ttlMs + staleTtlMs;
+            const derivedTags = deriveTags(builder);
+            const tagSet = new Set([...(mergedOptions.tags || []), ...derivedTags]);
+            const newEntry = {
+                value: encoded.payload,
+                createdAt: Date.now(),
+                ttlMs,
+                staleTtlMs,
+                cacheTimeMs,
+                tags: Array.from(tagSet),
+                rowCount: rows.length,
+                byteSize: encoded.byteSize,
+                sqlFingerprint: key
+            };
+            await activeProvider.set(key, newEntry);
+            runtime.parsedValues.set(key, { createdAt: newEntry.createdAt, rows, tags: newEntry.tags });
+            return rows;
+        })();
+        if (mergedOptions.dedupe !== false) {
+            runtime.inFlight.set(key, promise);
+            promise.finally(() => runtime.inFlight.delete(key));
+        }
+        return promise;
+    }
+    function scheduleRevalidation() {
+        runtime.stats.revalidations += 1;
+        fetchAndStore('revalidate').catch(() => undefined);
+    }
+    function runWithoutCache(cacheStatus) {
+        if (provider) {
+            runtime.stats.misses += 1;
+        }
+        return builder.getExecutor().execute({
+            queryId: options?.queryId,
+            logContext: { cacheStatus, cacheMode: mode }
+        });
+    }
+}

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

@@ -0,0 +1,15 @@
+import type { QueryRuntimeContext } from './runtime-context.js';
+import type { CacheStats } from './types.js';
+export declare class CacheController {
+    private context;
+    constructor(context: QueryRuntimeContext);
+    invalidateKey(key: string): Promise<void>;
+    invalidateTags(tags: string[]): Promise<void>;
+    clear(): Promise<void>;
+    warm(queries: Array<() => Promise<unknown>>): Promise<void>;
+    getStats(): CacheStats & {
+        hitRate: number;
+    };
+    private removeParsedValuesByTags;
+}
+//# sourceMappingURL=controller.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"controller.d.ts","sourceRoot":"","sources":["../../../src/core/cache/controller.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,sBAAsB,CAAC;AAChE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAG7C,qBAAa,eAAe;IACd,OAAO,CAAC,OAAO;gBAAP,OAAO,EAAE,mBAAmB;IAE1C,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAMzC,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAe7C,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAOtB,IAAI,CAAC,OAAO,EAAE,KAAK,CAAC,MAAM,OAAO,CAAC,OAAO,CAAC,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;IAKjE,QAAQ,IAAI,UAAU,GAAG;QAAE,OAAO,EAAE,MAAM,CAAA;KAAE;IAO5C,OAAO,CAAC,wBAAwB;CAWjC"}

package/dist/core/cache/controller.js

@@ -0,0 +1,58 @@
+import { logger } from '../utils/logger.js';
+export class CacheController {
+    context;
+    constructor(context) {
+        this.context = context;
+    }
+    async invalidateKey(key) {
+        this.context.parsedValues.delete(key);
+        if (!this.context.provider)
+            return;
+        await this.context.provider.delete(key);
+    }
+    async invalidateTags(tags) {
+        if (!tags.length)
+            return;
+        const deleteByTag = this.context.provider?.deleteByTag;
+        if (!deleteByTag) {
+            logger.warn('Cache provider does not support tag invalidation. Tags ignored.', {
+                namespace: this.context.namespace,
+                tags
+            });
+            this.removeParsedValuesByTags(tags);
+            return;
+        }
+        await Promise.all(tags.map(tag => deleteByTag.call(this.context.provider, this.context.namespace, tag)));
+        this.removeParsedValuesByTags(tags);
+    }
+    async clear() {
+        if (this.context.provider?.clearNamespace) {
+            await this.context.provider.clearNamespace(this.context.namespace);
+        }
+        this.context.parsedValues.clear();
+    }
+    async warm(queries) {
+        if (!queries.length)
+            return;
+        await Promise.all(queries.map(query => query()));
+    }
+    getStats() {
+        const stats = { ...this.context.stats };
+        const total = stats.hits + stats.misses + stats.staleHits;
+        const hitRate = total > 0 ? (stats.hits + stats.staleHits) / total : 0;
+        return { ...stats, hitRate };
+    }
+    removeParsedValuesByTags(tags) {
+        if (!tags.length)
+            return;
+        const target = new Set(tags);
+        for (const [key, record] of this.context.parsedValues) {
+            if (!record.tags?.length)
+                continue;
+            const intersects = record.tags.some(tag => target.has(tag));
+            if (intersects) {
+                this.context.parsedValues.delete(key);
+            }
+        }
+    }
+}

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

@@ -0,0 +1,11 @@
+interface CacheKeyInput {
+    namespace: string;
+    sql: string;
+    parameters: unknown[];
+    settings?: Record<string, unknown> | undefined;
+    version?: string;
+    tableName?: string;
+}
+export declare function computeCacheKey({ namespace, sql, parameters, settings, version, tableName }: CacheKeyInput): string;
+export {};
+//# sourceMappingURL=key.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"key.d.ts","sourceRoot":"","sources":["../../../src/core/cache/key.ts"],"names":[],"mappings":"AAEA,UAAU,aAAa;IACrB,SAAS,EAAE,MAAM,CAAC;IAClB,GAAG,EAAE,MAAM,CAAC;IACZ,UAAU,EAAE,OAAO,EAAE,CAAC;IACtB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAAC;IAC/C,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAqBD,wBAAgB,eAAe,CAAC,EAC9B,SAAS,EACT,GAAG,EACH,UAAU,EACV,QAAQ,EACR,OAAc,EACd,SAAS,EACV,EAAE,aAAa,GAAG,MAAM,CAOxB"}

package/dist/core/cache/key.js

@@ -0,0 +1,26 @@
+import { stableStringify } from './serialization.js';
+const FNV_OFFSET = BigInt('0xcbf29ce484222325');
+const FNV_PRIME = BigInt('0x100000001b3');
+const FNV_MOD = BigInt('0x10000000000000000');
+function fnv1a64(value) {
+    let hash = FNV_OFFSET;
+    for (let i = 0; i < value.length; i++) {
+        hash ^= BigInt(value.charCodeAt(i));
+        hash = (hash * FNV_PRIME) % FNV_MOD;
+    }
+    return hash.toString(16);
+}
+function formatSegment(segment) {
+    if (!segment)
+        return 'query';
+    const sanitized = segment.replace(/[^a-zA-Z0-9_-]/g, '-');
+    return sanitized.slice(0, 48) || 'query';
+}
+export function computeCacheKey({ namespace, sql, parameters, settings, version = 'v1', tableName }) {
+    const serializedParams = stableStringify(parameters);
+    const serializedSettings = stableStringify(settings || null);
+    const material = `${sql}\n${serializedParams}\n${serializedSettings}`;
+    const digest = fnv1a64(material);
+    const tableSegment = formatSegment(tableName);
+    return `hq:${version}:${namespace}:${tableSegment}:${digest}`;
+}

package/dist/core/cache/providers/memory-lru.d.ts

@@ -0,0 +1,31 @@
+import type { CacheEntry, CacheProvider } from '../types.js';
+export interface MemoryLRUCacheOptions {
+    maxEntries?: number;
+    maxBytes?: number;
+    cleanupIntervalMs?: number;
+}
+export declare class MemoryCacheProvider implements CacheProvider {
+    private entries;
+    private tagIndex;
+    private currentBytes;
+    private maxEntries;
+    private maxBytes;
+    private cleanupIntervalMs;
+    private cleanupTimer?;
+    constructor(options?: MemoryLRUCacheOptions);
+    dispose(): void;
+    get(key: string): Promise<CacheEntry | null>;
+    set(key: string, entry: CacheEntry): Promise<void>;
+    delete(key: string): Promise<void>;
+    deleteByTag(namespace: string, tag: string): Promise<void>;
+    clearNamespace(namespace: string): Promise<void>;
+    private touch;
+    private enforceLimits;
+    private cleanup;
+    private indexTags;
+    private unindexTags;
+    private getTagIndexKey;
+    private cleanupTagIndex;
+}
+export { MemoryCacheProvider as MemoryLRUCacheProvider };
+//# sourceMappingURL=memory-lru.d.ts.map

package/dist/core/cache/providers/memory-lru.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory-lru.d.ts","sourceRoot":"","sources":["../../../../src/core/cache/providers/memory-lru.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAE7D,MAAM,WAAW,qBAAqB;IACpC,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,iBAAiB,CAAC,EAAE,MAAM,CAAC;CAC5B;AAgBD,qBAAa,mBAAoB,YAAW,aAAa;IACvD,OAAO,CAAC,OAAO,CAAiC;IAChD,OAAO,CAAC,QAAQ,CAAkC;IAClD,OAAO,CAAC,YAAY,CAAK;IACzB,OAAO,CAAC,UAAU,CAAS;IAC3B,OAAO,CAAC,QAAQ,CAAS;IACzB,OAAO,CAAC,iBAAiB,CAAS;IAClC,OAAO,CAAC,YAAY,CAAC,CAAiC;gBAE1C,OAAO,GAAE,qBAA0B;IAa/C,OAAO,IAAI,IAAI;IAOT,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC;IAY5C,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC;IAYlD,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAQlC,WAAW,CAAC,SAAS,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAU1D,cAAc,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAUtD,OAAO,CAAC,KAAK;IAKb,OAAO,CAAC,aAAa;IAQrB,OAAO,CAAC,OAAO;IAWf,OAAO,CAAC,SAAS;IAYjB,OAAO,CAAC,WAAW;IAcnB,OAAO,CAAC,cAAc;IAItB,OAAO,CAAC,eAAe;CAYxB;AAED,OAAO,EAAE,mBAAmB,IAAI,sBAAsB,EAAE,CAAC"}

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"}