@wroud/navigation/lib/pattern-matching/types.d.ts

A flexible, pattern-matching navigation system for JavaScript applications with built-in routing, browser integration, and navigation state management

/**
 * Types for the Trie-based pattern matching system
 */
import type { RouteParams } from "../IRouteMatcher.js";
import type { IRouteState } from "../IRouteState.js";
/**
 * Extracts parameter names from a pattern string using template literal types
 */
type Split<S extends string, D extends string> = S extends `${infer T}${D}${infer U}` ? [T, ...Split<U, D>] : [S];
type TrimSlashes<S extends string> = S extends `/${infer T}` ? T extends `${infer U}/` ? TrimSlashes<U> : T : S extends `${infer U}/` ? TrimSlashes<U> : S;
type PatternPath<S extends string> = S extends `${infer Path}?${string}` ? Path : S;
type PatternQuery<S extends string> = S extends `${string}?${infer Query}` ? Query : "";
type SplitAmpersand<S extends string> = S extends `${infer First}&${infer Rest}` ? [First, ...SplitAmpersand<Rest>] : S extends "" ? [] : [S];
type QueryParamSegment<S extends string> = S extends `${string}=:${infer Param}` ? `:${Param}` : never;
type StripWildcard<S extends string> = S extends `${infer R}*` ? R : S;
type StripParam<S extends string> = S extends `:${infer R}` ? R : S;
type StripType<S extends string> = S extends `${infer N}<${string}>${string}` ? N : S;
type StripRequired<S extends string> = S extends `${infer R}!` ? R : S;
type ExtractName<S extends string> = StripRequired<StripType<StripWildcard<StripParam<S>>>>;
type ExtractType<S extends string> = S extends `${string}<${infer T}>${string}` ? T : "string";
type IsWildcard<S extends string> = S extends `${string}*` ? true : false;
type ParamInfo<S extends string> = {
    name: ExtractName<S>;
    type: ExtractType<S>;
    wildcard: IsWildcard<S>;
};
type PrimitiveFromType<T extends string> = T extends "number" ? number : T extends "boolean" ? boolean : T extends "date" ? Date : T extends "json" ? object : string;
type ParamToValue<P extends {
    type: string;
    wildcard: boolean;
}> = P["wildcard"] extends true ? PrimitiveFromType<P["type"]>[] : PrimitiveFromType<P["type"]>;
type Simplify<T> = {
    [K in keyof T]: T[K];
};
type ToParamInfo<S> = S extends string ? ParamInfo<S> : never;
type PathParams<Pattern extends string> = ToParamInfo<Extract<Split<TrimSlashes<PatternPath<Pattern>>, "/">[number], `:${string}`>>;
type QuerySegments<Pattern extends string> = QueryParamSegment<SplitAmpersand<PatternQuery<Pattern>>[number]>;
type RequiredQueryParams<Pattern extends string> = ToParamInfo<Extract<QuerySegments<Pattern>, `${string}!`>>;
type OptionalQueryParams<Pattern extends string> = ToParamInfo<Exclude<QuerySegments<Pattern>, `${string}!`>>;
/**
 * Extract route parameters from a pattern string.
 * Path params and query params with `!` suffix are required.
 * Query params without `!` are optional.
 *
 * @template Pattern - The URL pattern to extract parameters from
 * @example
 * type Params = ExtractRouteParams<"/user/:id">; // { id: string }
 * type QueryParams = ExtractRouteParams<"/search?q=:q!&page=:page<number>">; // { q: string; page?: number }
 * type FileParams = ExtractRouteParams<"/files/:path*">; // { path: string[] }
 */
export type ExtractRouteParams<Pattern extends string> = Pattern extends "/" | "" ? {} : Simplify<{
    [P in PathParams<Pattern> | RequiredQueryParams<Pattern> as P["name"]]: ParamToValue<P>;
} & {
    [P in OptionalQueryParams<Pattern> as P["name"]]?: ParamToValue<P>;
}>;
/**
 * Type-safe TriePatternMatching methods
 */
export interface TypedPatternMatcher {
    /**
     * Decode URL parameters based on a pattern
     */
    decode<Pattern extends string>(pattern: Pattern, url: string): ExtractRouteParams<Pattern> | null;
    /**
     * Encode parameters into a URL based on a pattern
     */
    encode<Pattern extends string>(pattern: Pattern, params: ExtractRouteParams<Pattern>): string;
    /**
     * Match a URL against the patterns in the trie
     */
    match<Pattern extends string>(url: string): IPatternRouteState<Pattern> | null;
}
export interface IPatternRouteState<Pattern extends string> extends IRouteState {
    id: Pattern;
    params: ExtractRouteParams<this["id"]>;
}
/**
 * Types of nodes in the trie structure
 * - static: regular path segment that matches exactly (e.g., "user", "posts")
 * - param: named parameter segment (e.g., ":id", ":action")
 * - wildcard: captures multiple segments (e.g., ":path*")
 */
export type NodeType = "static" | "param" | "wildcard";
/**
 * Result of a matching operation
 */
export interface MatchResult {
    matched: boolean;
    params: RouteParams;
}
/**
 * Extended match result with the matched pattern
 */
export interface ExtendedMatchResult extends MatchResult {
    pattern?: string;
}
export {};
//# sourceMappingURL=types.d.ts.map