This week I saw some people fighting on Twitter (where else, right?) about typed routing and typed query parameters. So I thought this would be a fun opportunity to do a little step-by-step introduction on creating a recursive generic type, while creating your own type-safe query parameters.
Our example
We’re going to work with the following url:
https://www.hero.com?superman=clark_kent&spiderman=peter_parker&batman=bruce_wayne
The problem
To get query parameters from a URL, we can do something like this:
function getQueryParams(url: string) {
const entries = new URL(url).searchParams.entries();
return Object.fromEntries(entries);
}
But this results in a very wide return type. So wide, you could call it untyped.
const url = 'https://www.hero.com?superman=clark_kent&spiderman=peter_parker&batman=bruce_wayne';
const params = getQueryParams(url);
// ^? const params: {[k: string]: string}
It would be way cooler to get a narrowly typed result:
// ^? const params: { superman: 'clark_kent', spiderman: 'peter_parker', batman: 'bruce_wayne' }
In order to get there we’ll refactor the function to add a type parameter, so we can use the url to infer the type parameters. We’ll cast the end result with as, because Typescript is unable to infer, and/or match the result of our runtime code to our generic type result.
type UrlToParams<T> = any;
function getQueryParams<T extends string>(url: T) {
const entries = new URL(url).searchParams.entries();
return Object.fromEntries(entries) as UrlToParams<T>;
}
Building out our generic type
First, we’ll split the url (T) by the ? character and take the second part of the string that will have the query parameters.
type UrlToParams<T extends string> = T extends `${string}?${infer Params}` ? Params : never;
// const params: "superman=clark_kent&spiderman=peter_parker&batman=bruce_wayne"
But this generic needs to do more than just split the string (T). We’ll need to do something with the result of that split as well. This is where our recursion first comes in, because we’ll need to call UrlToParams again, but with the rest (Params) of the string.
type UrlToParams<T extends string> = T extends `${string}?${infer Params}`
? UrlToParams<Params>
: Params; // We can now work with the parameters
We’ve now handled our first problem; separating the parameters from the url. That wasn’t too bad, right?
Extracting key-value pairs
We need a way to find the key-value pairs and turn these into a Record (or an object).
A suboptimal approach
One (suboptimal) approach could be to split the rest string (T) by the & character, run another conditional to split the key-value pairs, and work from there.
type UrlToParams<T extends string> = T extends `${string}?${infer Params}`
? UrlToParams<Params>
: T extends `${infer KeyValuePair}&${infer Rest}`
? KeyValuePair extends `${infer Key}=${infer Value}`
? { [K in Key]: Value }
: {}
: {};
But KeyValuePair is a string that already contains the Key and the Value, so we can simplify this by directly extracting the key-value pair from the string instead of adding a redundant conditional.
A good approach would be to optimize our matching pattern: {Key}={Value}&{Rest} and get the key-value pair in one go:
type UrlToParams<T extends string> = T extends `${string}?${infer Params}`
? UrlToParams<Params>
: T extends `${infer Key}=${Value}&${infer Rest}`
? { [K in Key]: Value }
: {};
// ^? const params: "{ superman: "clark_kent" }
Nice. Now we’re getting somewhere.
One problem: our code only returns the first key-value pair of the inserted string T.
Adding more recursion
In order to get the rest of the key-value pairs, we need to keep calling UrlToParams, until the complete string is processed. Let’s update our generic by calling it again from itself (recursion, yay).
type UrlToParams<T extends string> = T extends `${string}?${infer Params}`
? UrlToParams<Params>
: T extends `${infer Key}=${infer Value}&${infer Rest}`
? { [K in Key]: Value } & UrlToParams<Rest>
: {};
// ^? const params: "{ superman: "clark_kent" } & { spiderman: "peter_parker" }
We’ve now returned the found key-value pair, and combined it with the execution of our generic (again) that takes in the remainder string, which will yield the next key-value pair, and so forth. This creates an intersection of all key-value pairs, which eventually results in our wanted end result.
Great! But we’re only getting two key-value pairs? So it’s still not working as intended?
Catching the last key-value pair
The string (T) that remains after the last & character will be batman=bruce_wayne. It does not have a & character, so our current check for
T extends `${infer Key}=${infer Value}&${infer Rest}`
will never match on that last key-value pair. We can handle that by adding another conditional that checks for a single key-value pair, which, of course, does not have an & character:
type UrlToParams<T extends string> = T extends `${string}?${infer Params}`
? UrlToParams<Params>
: T extends `${infer Key}=${infer Value}&${infer Rest}`
? { [K in Key]: Value } & UrlToParams<Rest>
: T extends `${infer Key}=${infer Value}`
? { [K in Key]: Value }
: {};
And voila, we have our first naive implementation of a recursive generic that can parse query parameters from a URL and return a typed object. We can now use this generic to get the query parameters from the URL:
const params = getQueryParams(url);
// ^? const params: { superman: 'clark_kent' } & { spiderman: 'peter_parker' } & { batman: 'bruce_wayne' }
Making it more robust
You could argue that parsing values is up to the client. Query parameter syntax isn’t standardized, so for a generic solution, you’d have to handle a lot of cases like malformed URLs, custom array syntax or encoding. Preferably you’d be in strict control on how parameters get pushed to the URL.
Making a simplistic attempt at parsing the values on type-level
For the sake of this article, we’ll assume arrays are comma-separated, and booleans are either "true" or "false".
type UrlToParams<T extends string> = T extends `${string}?${infer Params}`
? UrlToParams<Params>
: T extends `${infer Key}=${infer Value}&${infer Rest}`
? { [K in Key]: ParseValue<Value> } & UrlToParams<Rest>
: T extends `${infer Key}=${infer Value}`
? { [K in Key]: ParseValue<Value> }
: {};
type ParseValue<T extends string> = T extends `${string},${string}`
? ParseArray<T>
: T extends 'true'
? true
: T extends 'false'
? false
: T extends `${infer N extends number}`
? N
: T;
type ParseArray<
T extends string,
Result extends any[] = [],
> = T extends `${infer First},${infer Rest}`
? ParseArray<Rest, [...Result, ParseValue<First>]>
: [...Result, ParseValue<T>];
Make the result more readable
You did the hard work. You made it production-ready. But still, it’s essentially an ugly looking intersection of all key-value pairs, which aesthetically kinda looks like a bit of typescript vomit. You can lighten the strain on your eyes a bit by using a Prettify helper.
Conclusion
Recursive types can help perform iterations over a type. They might seem scary at first, but once you get the hang of it you can create some really powerful types. This is your way into maybe experimenting with re-creating runtime methods on type level. How about a Join<T>? Or a Split<T>? Maybe a ReplaceAll<T> type?