Unified withParams utility to replace individual path, query, and host utilities

[stackoverfloweth]

We ship separate utilities for assigning params for each of the different parts of the url. For the most part these all worked exactly the same (Hash was a little different, more on that later). This PR introduces a single, unified utility withParams to replace them all.

import { withParams } from '@kitbag/router'

const events = createRoute({
  name: 'events',
  path: withParams('/events/[year]/[?month]', {
    year: Number,
    month: withDefault(monthParam, 'january'),
  }),
  query: withParams('enabled=[?enabled]', {
    enabled: true,
  }),
})

I really didn't like the fact that hash didn't quite fit but still had extremely similar types. The biggest difference is that hash stored the value as string | undefined, but the others always store string. Hence our empty paths being defined as Path<'', {}>. I actually prefer the idea of undefined so withParams stores value as possibly undefined. It has an overload that takes zero arguments and a separate property toString: () => string for instances where we need to normalize to a string.

Additionally, I decided to support params in the hash because it works exactly like path and I assumed it would be a small change. It's a bit bigger than I expected but still small enough that I feel like it was the right call.

Hash also had some logic for stripping a leading "#" when it's created but I just moved that so it would work like the other utilities.

To be kind to our current user base I've exported path, query, and host utilities but marked them as deprecated.

[netlify]

✅ Deploy Preview for kitbag-router ready!

Name	Link
🔨 Latest commit	b25e1c8
🔍 Latest deploy log	https://app.netlify.com/sites/kitbag-router/deploys/679bc99c0f913e00085099f6
😎 Deploy Preview	https://deploy-preview-447--kitbag-router.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify site configuration.

[stackoverfloweth]

pretty sure this is a bug in production right now, host advertises support for params but doesn't validate them when matching

[pleek91]

Should this be getHostParams?

[stackoverfloweth]

if we reuse "path" functions, rename without the word "path".

[stackoverfloweth]

investigate if we actually need a "query" version as well

[stackoverfloweth]

I chose not to duplicate all the tests from path, host, query, etc since the specific formats aren't expected to make a difference

[pleek91]

I feel like the combinePath naming doesn't make sense now that its used for all the different pieces. Its also kinda interesting that since it accepts WithParams that there's no type safety preventing us from accidentally doing WithParams<TParent['path'], TQuery> 🤔

[stackoverfloweth]

I don't think we have that protection today, but it might be worth exploring. Something like assigning an internal kind (tagged type) to ensure wires don't get crossed

[pleek91]

Do we gain something from the undefined vs {} change?

[stackoverfloweth]

if we just assume hash '' (empty string) is the same as undefined we could remove all the toStrings(). See if you can remember why hash was special and expected undefined separately from empty string

[pleek91]

Should this be getHostParams?

[pleek91]

Why did we go back to having a toString method? Just for my own understanding.