@hypequery/clickhouse 1.4.0-beta.2 → 1.4.0

package/README.md

@@ -95,6 +95,39 @@ const results = await db
   .execute();
 ```
 
+## Caching (Experimental)
+
+The query builder can cache results with deterministic keys, stale-while-revalidate behavior, and pluggable providers.
+
+```typescript
+import { createQueryBuilder, MemoryCacheProvider } from '@hypequery/clickhouse';
+
+const db = createQueryBuilder<IntrospectedSchema>({
+  host: 'your-clickhouse-host',
+  username: 'default',
+  password: '',
+  database: 'default',
+  cache: {
+    mode: 'stale-while-revalidate',
+    ttlMs: 2_000,
+    staleTtlMs: 30_000,
+    provider: new MemoryCacheProvider({ maxEntries: 5_000 })
+  }
+});
+
+const rows = await db
+  .table('users')
+  .select(['id', 'email'])
+  .where('active', '=', true)
+  .cache({ tags: ['users'] })
+  .execute();
+
+// Programmatic invalidation
+await db.cache.invalidateTags(['users']);
+```
+
+Use `.cache()` to attach defaults to a fluent chain, pass `execute({ cache: { ... } })` for one-off overrides, or call `db.cache.*` for manual invalidation. For a deep dive on cache modes, invalidation, advanced serialization, and bring-your-own-provider recipes (Redis/Upstash, compression, etc.), see the [Caching guide](https://hypequery.com/docs/features/caching).
+
 ## Schema Generation
 
 hypequery provides a CLI tool to generate TypeScript types from your ClickHouse schema:
@@ -184,8 +217,25 @@ const tripsWithDrivers = await db.table('trips')
   .join('drivers', 'trips.driver_id', 'drivers.id')
   .execute();
 
+// After joining, TypeScript understands the expanded scope
+const tripsWithUsers = await db.table('trips')
+  .innerJoin('users', 'trips.user_id', 'users.id')
+  .select(['users.email', 'trips.trip_id'])
+  .where('users.email', 'like', '%@example.com')
+  .execute();
+
+// Keep literal column inference with selectConst and reuse joined columns in ORDER BY / HAVING
+const sortedTrips = await db.table('trips')
+  .innerJoin('users', 'trips.user_id', 'users.id')
+  .selectConst('users.email', 'trips.trip_id')
+  .groupBy(['users.email', 'trips.trip_id'])
+  .having('COUNT(*) > 1')
+  .orderBy('users.email', 'DESC')
+  .execute();
+
 ```
 
+`selectConst()` preserves literal column names (including aliases like `users.email`), which means TypeScript keeps those identifiers available for downstream `orderBy`, `groupBy`, and `having` calls.
 
 **Benefits:**
 - ✅ Works in all environments (Node.js, browser, bundlers)
@@ -205,6 +255,20 @@ const db = createQueryBuilder<IntrospectedSchema>({
 ```
 
 
+## Testing
+
+Run the fast feedback loop with:
+
+```bash
+npm run test
+```
+
+This command runs type checks + unit tests only. To exercise the ClickHouse-backed integration suite, ensure a test ClickHouse instance is available (or set the required env vars) and run:
+
+```bash
+npm run test:integration
+```
+
 ## Versioning and Release Channels
 
 hypequery follows semantic versioning and provides multiple release channels:
@@ -219,7 +283,6 @@ For detailed documentation and examples, visit our [documentation site](https://
 - [Getting Started](https://hypequery.com/docs/installation)
 - [Query Building](https://hypequery.com/docs/guides/query-building)
 - [Filtering](https://hypequery.com/docs/guides/filtering)
-- [Pagination](https://hypequery.com/docs/features/pagination)
 - [API Reference](https://hypequery.com/docs/reference/api)
 
 
@@ -250,4 +313,4 @@ This project is licensed under the Apache-2.0 License - see the [LICENSE](LICENS
 
 <div align="center">
   <sub>Built with ❤️ by the hypequery team</sub>
-</div> 
+</div> 

package/dist/cli/bin.js

@@ -50,6 +50,8 @@ ${colors.bright}Options:${colors.reset}
   --secure                   Use HTTPS/TLS for connection
   --help, -h                 Show this help text
 
+${colors.dim}Note: All options support both formats: --option=value or --option value${colors.reset}
+
 ${colors.bright}Environment variables:${colors.reset}
   CLICKHOUSE_HOST            ClickHouse server URL
   VITE_CLICKHOUSE_HOST       Alternative variable for Vite projects
@@ -70,9 +72,11 @@ ${colors.bright}Environment variables:${colors.reset}
 ${colors.bright}Examples:${colors.reset}
   npx hypequery-generate-types
   npx hypequery-generate-types --output=./src/types/db-schema.ts
+  npx hypequery-generate-types --output ./src/types/db-schema.ts
   npx hypequery-generate-types --host=https://your-instance.clickhouse.cloud:8443 --secure
-  npx hypequery-generate-types --host=http://localhost:8123 --username=default --password=password --database=my_db
+  npx hypequery-generate-types --host http://localhost:8123 --username default --password password --database my_db
   npx hypequery-generate-types --include-tables=users,orders,products
+  npx hypequery-generate-types --include-tables users,orders,products
   `);
 }
 
@@ -87,28 +91,66 @@ function parseArguments(args) {
     secure: false
   };
 
-  for (const arg of args) {
-    if (arg.startsWith('--output=')) {
-      config.output = arg.substring('--output='.length);
-    } else if (arg.startsWith('--host=')) {
-      config.host = arg.substring('--host='.length);
-    } else if (arg.startsWith('--username=')) {
-      config.username = arg.substring('--username='.length);
-    } else if (arg.startsWith('--password=')) {
-      config.password = arg.substring('--password='.length);
-    } else if (arg.startsWith('--database=')) {
-      config.database = arg.substring('--database='.length);
-    } else if (arg.startsWith('--include-tables=')) {
-      config.includeTables = arg.substring('--include-tables='.length).split(',');
-    } else if (arg.startsWith('--exclude-tables=')) {
-      config.excludeTables = arg.substring('--exclude-tables='.length).split(',');
-    } else if (arg === '--secure') {
-      config.secure = true;
-    } else if (arg === '--help' || arg === '-h') {
-      config.showHelp = true;
-    } else if (!arg.startsWith('-') && !config.output) {
-      // For backwards compatibility, treat the first non-flag argument as the output path
-      config.output = arg;
+  // Helper function to extract value from --param=value format
+  function getParamValue(arg, paramName) {
+    if (arg.startsWith(`${paramName}=`)) {
+      return arg.substring(paramName.length + 1); // +1 for the '=' character
+    }
+    return null;
+  }
+
+  // Helper function to get next argument as value
+  function getNextArgValue(args, index) {
+    return args[index + 1];
+  }
+
+  // Parameter handlers map
+  const paramHandlers = {
+    '--output': (value) => config.output = value,
+    '--host': (value) => config.host = value,
+    '--username': (value) => config.username = value,
+    '--password': (value) => config.password = value,
+    '--database': (value) => config.database = value,
+    '--include-tables': (value) => config.includeTables = value.split(','),
+    '--exclude-tables': (value) => config.excludeTables = value.split(',')
+  };
+
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    let handled = false;
+
+    // Handle parameters with values
+    for (const [paramName, handler] of Object.entries(paramHandlers)) {
+      // Check for --param=value format
+      const value = getParamValue(arg, paramName);
+      if (value !== null) {
+        handler(value);
+        handled = true;
+        break;
+      }
+
+      // Check for --param value format
+      if (arg === paramName) {
+        const nextValue = getNextArgValue(args, i);
+        if (nextValue && !nextValue.startsWith('-')) {
+          handler(nextValue);
+          i++; // Skip the next argument since we consumed it
+          handled = true;
+          break;
+        }
+      }
+    }
+
+    // Handle boolean flags
+    if (!handled) {
+      if (arg === '--secure') {
+        config.secure = true;
+      } else if (arg === '--help' || arg === '-h') {
+        config.showHelp = true;
+      } else if (!arg.startsWith('-') && !config.output) {
+        // For backwards compatibility, treat the first non-flag argument as the output path
+        config.output = arg;
+      }
     }
   }
 

package/dist/cli/generate-types.js

@@ -35,6 +35,40 @@ const clickhouseToTsType = (type) => {
     return `${clickhouseToTsType(innerType)} | null`;
   }
 
+  // Handle Map types
+  if (type.startsWith('Map(')) {
+    // Extract key and value types from Map(KeyType, ValueType)
+    const mapContent = type.slice(4, -1); // Remove 'Map(' and ')'
+    const commaIndex = mapContent.lastIndexOf(',');
+    if (commaIndex !== -1) {
+      const keyType = mapContent.substring(0, commaIndex).trim();
+      const valueType = mapContent.substring(commaIndex + 1).trim();
+
+      // Handle different key types
+      let keyTsType = 'string';
+      if (keyType === 'LowCardinality(String)') {
+        keyTsType = 'string';
+      } else if (keyType.includes('Int') || keyType.includes('UInt')) {
+        keyTsType = 'number';
+      }
+
+      // Handle different value types
+      let valueTsType = 'unknown';
+      if (valueType.startsWith('Array(')) {
+        const innerType = valueType.slice(6, -1);
+        valueTsType = `Array<${clickhouseToTsType(innerType)}>`;
+      } else if (valueType.startsWith('Nullable(')) {
+        const innerType = valueType.slice(9, -1);
+        valueTsType = `${clickhouseToTsType(innerType)} | null`;
+      } else {
+        valueTsType = clickhouseToTsType(valueType);
+      }
+
+      return `Record<${keyTsType}, ${valueTsType}>`;
+    }
+    return 'Record<string, unknown>';
+  }
+
   switch (type.toLowerCase()) {
     case 'string':
     case 'fixedstring':
@@ -43,12 +77,16 @@ const clickhouseToTsType = (type) => {
     case 'int16':
     case 'int32':
     case 'uint8':
+    case 'int64':
     case 'uint16':
     case 'uint32':
-      return 'number';
-    case 'int64':
     case 'uint64':
-      return 'string'; // Use string for 64-bit integers to avoid precision loss
+      return 'number';
+    case 'uint128':
+    case 'uint256':
+    case 'int128':
+    case 'int256':
+      return 'string';
     case 'float32':
     case 'float64':
     case 'decimal':

package/dist/core/cache/cache-manager.d.ts

@@ -0,0 +1,4 @@
+import type { QueryBuilder, ExecuteOptions } from '../query-builder.js';
+import type { AnyBuilderState, SchemaDefinition } from '../types/builder-state.js';
+export declare function executeWithCache<Schema extends SchemaDefinition<Schema>, State extends AnyBuilderState>(builder: QueryBuilder<Schema, State>, options?: ExecuteOptions): Promise<State['output'][]>;
+//# sourceMappingURL=cache-manager.d.ts.map

package/dist/core/cache/cache-manager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache-manager.d.ts","sourceRoot":"","sources":["../../../src/core/cache/cache-manager.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AACxE,OAAO,KAAK,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,2BAA2B,CAAC;AA6DnF,wBAAsB,gBAAgB,CACpC,MAAM,SAAS,gBAAgB,CAAC,MAAM,CAAC,EACvC,KAAK,SAAS,eAAe,EAE7B,OAAO,EAAE,YAAY,CAAC,MAAM,EAAE,KAAK,CAAC,EACpC,OAAO,CAAC,EAAE,cAAc,GACvB,OAAO,CAAC,KAAK,CAAC,QAAQ,CAAC,EAAE,CAAC,CA0J5B"}

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