route-pattern: better types (#10881)

Author: pcattori

packages/route-pattern/src/lib/href.ts

@@ -1,6 +1,7 @@
 import type { RequiredParams, OptionalParams } from './params.ts'
 import { parse, type ParseResult, type Token } from './parse.ts'
 import type { RoutePattern } from './route-pattern.ts'
+import type { UnknownArgs } from './type-utils.ts'
 import type { Variant } from './variant.ts'
 
 /**
@@ -28,7 +29,7 @@ export class MissingParamError extends Error {
  * @return A function that builds hrefs from patterns and parameters
  */
 export function createHrefBuilder<T extends string | RoutePattern = string>(): HrefBuilder<T> {
-  return (pattern: string | RoutePattern, ...args: any) =>
+  return (pattern: string | RoutePattern, ...args: UnknownArgs) =>
     formatHref(parse(typeof pattern === 'string' ? pattern : pattern.source), ...args)
 }
 

packages/route-pattern/src/lib/matcher.ts

@@ -3,28 +3,28 @@ import type { RoutePattern } from './route-pattern.ts'
 /**
  * An interface for matching URLs against patterns.
  */
-export interface Matcher<T = any> {
+export interface Matcher<data = unknown> {
   /**
    * Add a pattern to the matcher.
    *
    * @param pattern The pattern to add
    * @param data The data to associate with the pattern
    */
-  add<P extends string>(pattern: P | RoutePattern<P>, data: T): void
+  add<source extends string>(pattern: source | RoutePattern<source>, data: data): void
   /**
    * Find the best match for a URL.
    *
    * @param url The URL to match
    * @return The match result, or `null` if no match was found
    */
-  match(url: string | URL): MatchResult<T> | null
+  match(url: string | URL): MatchResult<data> | null
   /**
    * Find all matches for a URL.
    *
    * @param url The URL to match
    * @return A generator that yields all matches
    */
-  matchAll(url: string | URL): Generator<MatchResult<T>>
+  matchAll(url: string | URL): Generator<MatchResult<data>>
   /**
    * The number of patterns in the matcher.
    */
@@ -34,11 +34,11 @@ export interface Matcher<T = any> {
 /**
  * The result of matching a URL against a pattern.
  */
-export interface MatchResult<T = any> {
+export interface MatchResult<data = unknown> {
   /**
    * The data associated with the matched pattern.
    */
-  data: T
+  data: data
   /**
    * The parameters extracted from the URL.
    */

packages/route-pattern/src/lib/matchers/array.ts

@@ -10,15 +10,15 @@ import { RoutePattern } from '../route-pattern.ts'
  * - Pattern set changes frequently (cheap to rebuild)
  * - Memory footprint needs to be minimal
  */
-export class ArrayMatcher<T = any> implements Matcher<T> {
-  #pairs: { pattern: RoutePattern; data: T }[] = []
+export class ArrayMatcher<data = unknown> implements Matcher<data> {
+  #pairs: { pattern: RoutePattern; data: data }[] = []
   #count = 0
 
   /**
    * @param pattern The pattern to add
    * @param data The data to associate with the pattern
    */
-  add<P extends string>(pattern: P | RoutePattern<P>, data: T): void {
+  add<source extends string>(pattern: source | RoutePattern<source>, data: data): void {
     let routePattern = typeof pattern === 'string' ? new RoutePattern(pattern) : pattern
     this.#pairs.push({ pattern: routePattern, data })
     this.#count++
@@ -28,7 +28,7 @@ export class ArrayMatcher<T = any> implements Matcher<T> {
    * @param url The URL to match
    * @return The match result, or `null` if no match was found
    */
-  match(url: string | URL): MatchResult<T> | null {
+  match(url: string | URL): MatchResult<data> | null {
     if (typeof url === 'string') url = new URL(url)
 
     for (let { pattern, data } of this.#pairs) {
@@ -45,7 +45,7 @@ export class ArrayMatcher<T = any> implements Matcher<T> {
    * @param url The URL to match
    * @return A generator that yields all matches
    */
-  *matchAll(url: string | URL): Generator<MatchResult<T>> {
+  *matchAll(url: string | URL): Generator<MatchResult<data>> {
     if (typeof url === 'string') url = new URL(url)
 
     for (let { pattern, data } of this.#pairs) {

packages/route-pattern/src/lib/matchers/trie.ts

@@ -158,7 +158,7 @@ export interface TrieMatcherOptions {
  * - Match performance matters more than build time
  * - You need exhaustive matching via `matchAll()`
  */
-export class TrieMatcher<T = any> implements Matcher<T> {
+export class TrieMatcher<data = unknown> implements Matcher<data> {
   #pathnameOnlyRoot: TrieNode
   #originRoot: OriginTrieNode
   #patternCount = 0
@@ -183,7 +183,7 @@ export class TrieMatcher<T = any> implements Matcher<T> {
    * @param pattern The pattern to add
    * @param node The data to associate with the pattern
    */
-  add(pattern: string | RoutePattern, node: T): void {
+  add(pattern: string | RoutePattern, node: data): void {
     let routePattern = typeof pattern === 'string' ? new RoutePattern(pattern) : pattern
     let parsed = parse(routePattern.source)
 
@@ -299,7 +299,7 @@ export class TrieMatcher<T = any> implements Matcher<T> {
    * @param url The URL to match
    * @return The match result, or `null` if no match was found
    */
-  match(url: string | URL): MatchResult<T> | null {
+  match(url: string | URL): MatchResult<data> | null {
     let urlObj = typeof url === 'string' ? new URL(url) : url
 
     let parsedUrl: ParsedURL = {
@@ -343,7 +343,7 @@ export class TrieMatcher<T = any> implements Matcher<T> {
    * @param url The URL to match
    * @return A generator that yields all matches
    */
-  *matchAll(url: string | URL): Generator<MatchResult<T>> {
+  *matchAll(url: string | URL): Generator<MatchResult<data>> {
     let urlObj = typeof url === 'string' ? new URL(url) : url
     let pathname = urlObj.pathname
 
@@ -477,7 +477,7 @@ export class TrieMatcher<T = any> implements Matcher<T> {
     port: string | undefined,
     pathnameTokens: Token[] | undefined,
     pattern: RoutePattern,
-    userNode: T,
+    userNode: data,
     searchConstraints?: SearchConstraints,
     parsed?: ParseResult,
   ): void {
@@ -579,7 +579,7 @@ export class TrieMatcher<T = any> implements Matcher<T> {
     node: TrieNode,
     tokens: Token[],
     pattern: RoutePattern,
-    userNode: T,
+    userNode: data,
     searchConstraints?: SearchConstraints,
     parsed?: ParseResult,
   ): void {
@@ -818,7 +818,7 @@ export class TrieMatcher<T = any> implements Matcher<T> {
   #addPatternMatch(
     node: TrieNode,
     pattern: RoutePattern,
-    userNode: T,
+    userNode: data,
     paramNames: string[],
     matchOrigin: boolean,
     searchConstraints?: SearchConstraints,
@@ -1499,7 +1499,7 @@ export class TrieMatcher<T = any> implements Matcher<T> {
     }
   }
 
-  #tryOriginMatch(parsedUrl: ParsedURL, segments: string[], urlObj: URL): MatchResult<T> | null {
+  #tryOriginMatch(parsedUrl: ParsedURL, segments: string[], urlObj: URL): MatchResult<data> | null {
     let results = this.#findOriginMatches(urlObj, segments, parsedUrl.search, true)
     if (results.length > 0) {
       let best = results[0]
@@ -1514,7 +1514,7 @@ export class TrieMatcher<T = any> implements Matcher<T> {
     baseParams: Record<string, string>,
     search: string,
     urlObj: URL,
-  ): MatchResult<T> | null {
+  ): MatchResult<data> | null {
     let initialState: MatchState = {
       segments,
       segmentIndex: 0,
@@ -1530,7 +1530,7 @@ export class TrieMatcher<T = any> implements Matcher<T> {
     return null
   }
 
-  #tryStaticPathMatch(segments: string[], search: string, url: URL): MatchResult<T> | null {
+  #tryStaticPathMatch(segments: string[], search: string, url: URL): MatchResult<data> | null {
     let results = this.#walkStaticPath(segments, search, false)
     if (results.length > 0) {
       let best = results[0]

packages/route-pattern/src/lib/parse.ts

@@ -1,5 +1,6 @@
 import { split, type SplitPattern, type Split } from './split.ts'
 import { parseSearchConstraints, type SearchConstraints } from './search-constraints.ts'
+import type { ForceDistributive } from './type-utils.ts'
 
 /**
  * An error thrown when a pattern fails to parse.
@@ -176,7 +177,7 @@ export interface ParsedPattern {
 
 // prettier-ignore
 export type Parse<T extends string> =
-  T extends any ?
+  T extends ForceDistributive ?
     Split<T> extends infer S extends SplitPattern ?
       {
         protocol: S['protocol'] extends string ? ParsePart<S['protocol']> : undefined

packages/route-pattern/src/lib/type-utils.ts

@@ -4,3 +4,34 @@ export type IsEqual<A, B> =
   (<T>() => T extends A ? 1 : 2) extends <T>() => T extends B ? 1 : 2 ? true : false
 
 export type Simplify<T> = { [K in keyof T]: T[K] } & {}
+
+/**
+ * Function arguments are contravariant, so unknown args must be typed as `Array<any>`
+ *
+ * Usage:
+ *
+ * ```ts
+ * type UnknownFunction = (args: UnknownArgs) => unknown
+ * ```
+ */
+export type UnknownArgs = Array<any>
+
+/**
+ * Force TS to distribute a union with `T extends ForceDistributeUnion ? ... : ...`
+ * as a more explicit alias of the common `T extends any ? ... : ...` pattern.
+ *
+ * See: https://www.typescriptlang.org/docs/handbook/2/conditional-types.html#distributive-conditional-types
+ *
+ * Usage:
+ *
+ * ```ts
+ * type Stuff<T> =
+ *   T extends ForceDistributive ?
+ *     // Now, operate on each member of the union separately
+ *     string extends T ? 'string' :
+ *     T
+ *   :
+ *   never
+ * ```
+ */
+export type ForceDistributive = any