/**
 * @file Core Path Utilities
 * @description Framework-agnostic path building, parameter extraction, and pattern matching utilities.
 * This module provides reusable functions for working with URL paths and route patterns
 * that can be used in any JavaScript/TypeScript project.
 *
 * @module @/lib/routing/core/path-utils
 *
 * @example
 * ```typescript
 * import {
 *   buildPath,
 *   extractParamNames,
 *   matchPathPattern,
 *   parsePathParams,
 * } from '@/lib/routing/core/path-utils';
 *
 * // Build a path with parameters
 * buildPath('/users/:id', { id: '123' }); // '/users/123'
 *
 * // Extract parameter names from a pattern
 * extractParamNames('/users/:id/posts/:postId'); // ['id', 'postId']
 *
 * // Check if a path matches a pattern
 * matchPathPattern('/users/:id', '/users/123'); // true
 *
 * // Parse parameters from a matched path
 * parsePathParams('/users/:id', '/users/123'); // { id: '123' }
 * ```
 */
/**
 * Build a URL path from a pattern and parameters
 *
 * Supports:
 * - Required parameters: `:id`
 * - Optional parameters: `:id?`
 * - Query string parameters
 *
 * @param pattern - Route pattern with parameter placeholders
 * @param params - Object containing parameter values
 * @param query - Optional query string parameters
 * @returns The built URL path
 *
 * @example
 * ```typescript
 * buildPath('/users/:id', { id: '123' }); // '/users/123'
 * buildPath('/users/:id?', {}); // '/users'
 * buildPath('/users/:id', { id: '123' }, { tab: 'settings' }); // '/users/123?tab=settings'
 * ```
 */
export declare function buildPath(pattern: string, params?: Record<string, string | number | undefined>, query?: Record<string, string | number | undefined>): string;
/**
 * Build a query string from parameters
 *
 * @param query - Query parameters object
 * @returns Query string (without leading ?)
 *
 * @example
 * ```typescript
 * buildQueryString({ page: 1, sort: 'name' }); // 'page=1&sort=name'
 * buildQueryString({ filter: undefined, sort: 'name' }); // 'sort=name'
 * ```
 */
export declare function buildQueryString(query: Record<string, string | number | boolean | undefined>): string;
/**
 * Parse query string into parameters object
 *
 * @param queryString - Query string to parse (with or without leading ?)
 * @returns Parsed query parameters
 *
 * @example
 * ```typescript
 * parseQueryString('?page=1&sort=name'); // { page: '1', sort: 'name' }
 * parseQueryString('page=1&sort=name'); // { page: '1', sort: 'name' }
 * ```
 */
export declare function parseQueryString(queryString: string): Record<string, string>;
/**
 * Extract parameter names from a route pattern
 *
 * @param pattern - Route pattern with parameter placeholders
 * @returns Array of parameter names (without : prefix)
 *
 * @example
 * ```typescript
 * extractParamNames('/users/:id'); // ['id']
 * extractParamNames('/users/:id/posts/:postId'); // ['id', 'postId']
 * extractParamNames('/search/:query?'); // ['query']
 * ```
 */
export declare function extractParamNames(pattern: string): string[];
/**
 * Extract required parameter names from a route pattern
 *
 * @param pattern - Route pattern with parameter placeholders
 * @returns Array of required parameter names
 *
 * @example
 * ```typescript
 * extractRequiredParams('/users/:id/:tab?'); // ['id']
 * ```
 */
export declare function extractRequiredParams(pattern: string): string[];
/**
 * Extract optional parameter names from a route pattern
 *
 * @param pattern - Route pattern with parameter placeholders
 * @returns Array of optional parameter names
 *
 * @example
 * ```typescript
 * extractOptionalParams('/users/:id/:tab?'); // ['tab']
 * ```
 */
export declare function extractOptionalParams(pattern: string): string[];
/**
 * Check if a route pattern has any parameters
 *
 * @param pattern - Route pattern to check
 * @returns True if the pattern contains parameters
 *
 * @example
 * ```typescript
 * hasParams('/users/:id'); // true
 * hasParams('/about'); // false
 * ```
 */
export declare function hasParams(pattern: string): boolean;
/**
 * Check if a route pattern has any dynamic segments
 * (alias for hasParams for clarity)
 *
 * @param pattern - Route pattern to check
 * @returns True if the pattern contains dynamic segments
 */
export declare function hasDynamicSegments(pattern: string): boolean;
/**
 * Check if a route pattern has a catch-all segment
 *
 * @param pattern - Route pattern to check
 * @returns True if the pattern contains a catch-all segment
 *
 * @example
 * ```typescript
 * hasCatchAll('/docs/*'); // true
 * hasCatchAll('/users/:id'); // false
 * ```
 */
export declare function hasCatchAll(pattern: string): boolean;
/**
 * Check if a path matches a route pattern
 *
 * @param pattern - Route pattern with parameter placeholders
 * @param path - Actual path to match
 * @returns True if the path matches the pattern
 *
 * @example
 * ```typescript
 * matchPathPattern('/users/:id', '/users/123'); // true
 * matchPathPattern('/users/:id', '/posts/123'); // false
 * matchPathPattern('/docs/*', '/docs/getting-started/installation'); // true
 * ```
 */
export declare function matchPathPattern(pattern: string, path: string): boolean;
/**
 * Parse path parameters from a path using a pattern
 *
 * @param pattern - Route pattern with parameter placeholders
 * @param path - Actual path to parse
 * @returns Object containing parsed parameters, or null if no match
 *
 * @example
 * ```typescript
 * parsePathParams('/users/:id', '/users/123'); // { id: '123' }
 * parsePathParams('/users/:id/posts/:postId', '/users/123/posts/456'); // { id: '123', postId: '456' }
 * parsePathParams('/users/:id', '/posts/123'); // null
 * ```
 */
export declare function parsePathParams(pattern: string, path: string): Record<string, string> | null;
/**
 * Get the static prefix of a path (before first dynamic segment)
 *
 * @param pattern - Route pattern
 * @returns Static prefix of the path
 *
 * @example
 * ```typescript
 * getStaticPrefix('/users/:id/posts'); // '/users'
 * getStaticPrefix('/about'); // '/about'
 * ```
 */
export declare function getStaticPrefix(pattern: string): string;
/**
 * Normalize a path by removing trailing slashes and ensuring leading slash
 *
 * @param path - Path to normalize
 * @returns Normalized path
 *
 * @example
 * ```typescript
 * normalizePath('users/123/'); // '/users/123'
 * normalizePath('/users/123/'); // '/users/123'
 * ```
 */
export declare function normalizePath(path: string): string;
/**
 * Join path segments into a single path
 *
 * @param segments - Path segments to join
 * @returns Joined path
 *
 * @example
 * ```typescript
 * joinPath('/users', '123', 'posts'); // '/users/123/posts'
 * joinPath('users/', '/123/', '/posts'); // '/users/123/posts'
 * ```
 */
export declare function joinPath(...segments: string[]): string;
/**
 * Split a path into segments
 *
 * @param path - Path to split
 * @returns Array of path segments
 *
 * @example
 * ```typescript
 * splitPath('/users/123/posts'); // ['users', '123', 'posts']
 * ```
 */
export declare function splitPath(path: string): string[];
/**
 * Get the depth (number of segments) of a path
 *
 * @param path - Path to measure
 * @returns Number of path segments
 *
 * @example
 * ```typescript
 * getPathDepth('/users/123/posts'); // 3
 * getPathDepth('/'); // 0
 * ```
 */
export declare function getPathDepth(path: string): number;
/**
 * Check if a path is a child of another path
 *
 * @param childPath - Potential child path
 * @param parentPath - Potential parent path
 * @returns True if childPath is a child of parentPath
 *
 * @example
 * ```typescript
 * isChildPath('/users/123', '/users'); // true
 * isChildPath('/posts/123', '/users'); // false
 * ```
 */
export declare function isChildPath(childPath: string, parentPath: string): boolean;
/**
 * Get the parent path of a given path
 *
 * @param path - Path to get parent of
 * @returns Parent path
 *
 * @example
 * ```typescript
 * getParentPath('/users/123/posts'); // '/users/123'
 * getParentPath('/users'); // '/'
 * ```
 */
export declare function getParentPath(path: string): string;
/**
 * Get the last segment of a path
 *
 * @param path - Path to get last segment of
 * @returns Last path segment
 *
 * @example
 * ```typescript
 * getLastSegment('/users/123/posts'); // 'posts'
 * getLastSegment('/users'); // 'users'
 * ```
 */
export declare function getLastSegment(path: string): string;
/**
 * Calculate the specificity score of a route pattern
 *
 * Higher specificity = more specific route = should be matched first
 *
 * @param pattern - Route pattern to calculate specificity for
 * @returns Specificity score
 *
 * @example
 * ```typescript
 * getPatternSpecificity('/users/new'); // Higher
 * getPatternSpecificity('/users/:id'); // Lower
 * getPatternSpecificity('/users/*'); // Lowest
 * ```
 */
export declare function getPatternSpecificity(pattern: string): number;
/**
 * Compare two route patterns by specificity
 *
 * @param a - First pattern
 * @param b - Second pattern
 * @returns Negative if a is more specific, positive if b is more specific
 *
 * @example
 * ```typescript
 * ['/users/:id', '/users/new'].sort(comparePatternSpecificity);
 * // ['/users/new', '/users/:id']
 * ```
 */
export declare function comparePatternSpecificity(a: string, b: string): number;