index.d.ts 3.9 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144
  1. /**
  2. * Encode a string into another string.
  3. */
  4. export type Encode = (value: string) => string;
  5. /**
  6. * Decode a string into another string.
  7. */
  8. export type Decode = (value: string) => string;
  9. export interface ParseOptions {
  10. /**
  11. * A function for encoding input strings.
  12. */
  13. encodePath?: Encode;
  14. }
  15. export interface PathToRegexpOptions {
  16. /**
  17. * Matches the path completely without trailing characters. (default: `true`)
  18. */
  19. end?: boolean;
  20. /**
  21. * Allows optional trailing delimiter to match. (default: `true`)
  22. */
  23. trailing?: boolean;
  24. /**
  25. * Match will be case sensitive. (default: `false`)
  26. */
  27. sensitive?: boolean;
  28. /**
  29. * The default delimiter for segments. (default: `'/'`)
  30. */
  31. delimiter?: string;
  32. }
  33. export interface MatchOptions extends PathToRegexpOptions {
  34. /**
  35. * Function for decoding strings for params, or `false` to disable entirely. (default: `decodeURIComponent`)
  36. */
  37. decode?: Decode | false;
  38. }
  39. export interface CompileOptions {
  40. /**
  41. * Function for encoding input strings for output into the path, or `false` to disable entirely. (default: `encodeURIComponent`)
  42. */
  43. encode?: Encode | false;
  44. /**
  45. * The default delimiter for segments. (default: `'/'`)
  46. */
  47. delimiter?: string;
  48. }
  49. /**
  50. * Plain text.
  51. */
  52. export interface Text {
  53. type: "text";
  54. value: string;
  55. }
  56. /**
  57. * A parameter designed to match arbitrary text within a segment.
  58. */
  59. export interface Parameter {
  60. type: "param";
  61. name: string;
  62. }
  63. /**
  64. * A wildcard parameter designed to match multiple segments.
  65. */
  66. export interface Wildcard {
  67. type: "wildcard";
  68. name: string;
  69. }
  70. /**
  71. * A set of possible tokens to expand when matching.
  72. */
  73. export interface Group {
  74. type: "group";
  75. tokens: Token[];
  76. }
  77. /**
  78. * A token that corresponds with a regexp capture.
  79. */
  80. export type Key = Parameter | Wildcard;
  81. /**
  82. * A sequence of `path-to-regexp` keys that match capturing groups.
  83. */
  84. export type Keys = Array<Key>;
  85. /**
  86. * A sequence of path match characters.
  87. */
  88. export type Token = Text | Parameter | Wildcard | Group;
  89. /**
  90. * Tokenized path instance.
  91. */
  92. export declare class TokenData {
  93. readonly tokens: Token[];
  94. readonly originalPath?: string | undefined;
  95. constructor(tokens: Token[], originalPath?: string | undefined);
  96. }
  97. /**
  98. * ParseError is thrown when there is an error processing the path.
  99. */
  100. export declare class PathError extends TypeError {
  101. readonly originalPath: string | undefined;
  102. constructor(message: string, originalPath: string | undefined);
  103. }
  104. /**
  105. * Parse a string for the raw tokens.
  106. */
  107. export declare function parse(str: string, options?: ParseOptions): TokenData;
  108. /**
  109. * Compile a string to a template function for the path.
  110. */
  111. export declare function compile<P extends ParamData = ParamData>(path: Path, options?: CompileOptions & ParseOptions): (params?: P) => string;
  112. export type ParamData = Partial<Record<string, string | string[]>>;
  113. export type PathFunction<P extends ParamData> = (data?: P) => string;
  114. /**
  115. * A match result contains data about the path match.
  116. */
  117. export interface MatchResult<P extends ParamData> {
  118. path: string;
  119. params: P;
  120. }
  121. /**
  122. * A match is either `false` (no match) or a match result.
  123. */
  124. export type Match<P extends ParamData> = false | MatchResult<P>;
  125. /**
  126. * The match function takes a string and returns whether it matched the path.
  127. */
  128. export type MatchFunction<P extends ParamData> = (path: string) => Match<P>;
  129. /**
  130. * Supported path types.
  131. */
  132. export type Path = string | TokenData;
  133. /**
  134. * Transform a path into a match function.
  135. */
  136. export declare function match<P extends ParamData>(path: Path | Path[], options?: MatchOptions & ParseOptions): MatchFunction<P>;
  137. export declare function pathToRegexp(path: Path | Path[], options?: PathToRegexpOptions & ParseOptions): {
  138. regexp: RegExp;
  139. keys: Keys;
  140. };
  141. /**
  142. * Stringify token data into a path string.
  143. */
  144. export declare function stringify(data: TokenData): string;