/********************************************************************************
 * Cache Key Utilities
 *
 * Parsing, filtering, and normalization functions for cache keys.
 *
 * @module core/cache/keys/utils
 ********************************************************************************/
import { type QueryParamCacheOptions } from "./prefixes.js";
export declare function parseRenderCacheKey(cacheKey: string): {
    projectId: string;
    environment: string;
    releaseKey: string;
    version: string;
    /** Compile mode segment, absent on keys written before it existed. */
    compileMode?: string;
    contentKey: string;
} | null;
/**
 * Create a portable key from a path string.
 * Combines a hash (for uniqueness) with the folder name (for readability).
 * Example: "/Users/alice/projects/my-app" -> "local-7a3b2f1c-my-app"
 *
 * This ensures cache keys are:
 * - Portable across different machines and environments
 * - Debuggable (folder name visible at a glance)
 * - Unique (hash prevents collisions for same folder name in different locations)
 */
export declare function hashPathWithName(path: string): string;
/**
 * Normalize a file path for use in cache keys.
 * Converts absolute paths to portable format: hash + filename for uniqueness and debuggability.
 *
 * Examples:
 * - "/Users/alice/project/components/Button.tsx" -> "a3f2b1c4-Button.tsx"
 * - "components/Button.tsx" -> "components/Button.tsx" (already relative)
 */
export declare function normalizeFilePath(filePath: string): string;
/**
 * Filter query params based on the specified policy.
 *
 * @param params - URLSearchParams to filter
 * @param options - Query param handling options
 * @returns Filtered entries array
 */
export declare function filterQueryParams(params: URLSearchParams, options?: QueryParamCacheOptions): Array<[string, string]>;
/**
 * Encode query params for use in internal cache-key construction.
 *
 * This encoding uses `*HH` byte escapes to avoid collisions between query
 * values. A key containing these escapes is not a valid concrete API cache key;
 * ApiCacheBackend maps the completed key to the API schema at its boundary.
 *
 * @param url - URL or URLSearchParams to extract query params from
 * @param options - Query param handling options
 * @returns Encoded query string for cache-key construction, or an empty string
 */
export declare function sanitizeQueryParamsForCacheKey(url: URL | URLSearchParams, options?: QueryParamCacheOptions): string;
export declare const CACHE_KEY_ALLOWED_PATTERN: RegExp;
export declare const CACHE_PATTERN_ALLOWED_PATTERN: RegExp;
/**
 * True when a concrete cache key is valid for the API cache backend (non-empty
 * and within the key character set, with no `*`).
 */
export declare function isValidCacheKey(key: string): boolean;
/**
 * True when a del-pattern is valid for the API cache backend (non-empty and
 * within the key character set plus the `*` glob wildcard).
 */
export declare function isValidCachePattern(pattern: string): boolean;
/**
 * Guarantee a concrete cache key only contains characters the API cache backend
 * accepts, so a malformed key can never reach the backend and trigger an
 * `HTTP 400: Cache key contains invalid characters` (which, on the control-plane
 * `/execute` path, loops until the request is flagged stuck; see veryfront
 * issues #162 / #175).
 *
 * Ordinary valid keys are returned unchanged. Malformed, empty, overlong, and
 * reserved-namespace keys become a deterministic SHA-256 fallback. No part of
 * the unsafe key is retained because it may contain a credential or other
 * sensitive path data. A separately supplied trusted backend prefix can be
 * retained so prefix-based invalidation still reaches the fallback entry.
 * Reserving the namespace prevents a valid raw key from being mistaken for a
 * generated fallback key.
 *
 * Intended for concrete keys only. Delete patterns are validated and rejected
 * separately because rewriting a glob could broaden its deletion scope.
 */
export declare function sanitizeCacheKey(key: string, trustedPrefix?: string): Promise<string>;
export declare function createCacheKeyFilter(options: {
    projectId?: string;
    environment?: "production" | "preview";
    version?: string;
    prefix?: string;
}): (key: string) => boolean;
export declare function getCacheKeyVersion(): string;
export declare function getAllKeysForProject(projectId: string): Map<string, string[]>;
export declare function getAllKeysForProjectAsync(projectId: string, includeRedis?: boolean): Promise<{
    memory: Map<string, string[]>;
    redis: Map<string, string[]>;
}>;
export declare function deleteAllKeysForProject(projectId: string): number;
export declare function deleteAllKeysForProjectAsync(projectId: string): Promise<{
    memoryDeleted: number;
    redisDeleted: number;
}>;
//# sourceMappingURL=utils.d.ts.map