Brand RouteUrl type to distinguish it from plain strings

[pataar]

Summary

The RouteUrl branded type I added a while ago used a plain alias. I've since learned that using a unique symbol is the recommended approach, so this PR improves the branding.

• Now RouteUrl uses a unique symbol brand — still assignable to string, but a plain string can't be assigned to RouteUrl
• Added a type test verifying that a plain string is not assignable to RouteUrl

Why unique symbol?

Using unique symbol as the brand key is the recommended pattern for branded types in TypeScript because:

• Each brand is globally unique, even across modules — no risk of accidental type collisions
• The brand property is hidden from IntelliSense, keeping autocomplete clean
• Zero runtime overhead — declare const only exists in the type system

See also: Preventing Accidental Interchangeability in TypeScript

Example

const url: RouteUrl = route('posts.show', 1); // ✅ works
const url: RouteUrl = '/posts/1';             // ❌ type error

const str: string = route('posts.show', 1);   // ✅ still works, RouteUrl extends string

Test plan

• Existing type tests pass
• New @ts-expect-error test confirms a plain string is not assignable to RouteUrl
• All runtime tests pass (npx vitest --typecheck)

[bakerkretzmar]

Very cool. Re-explaining your code example for my own understanding, and for when I inevitably come back to this to remind myself how it works: now, anything explicitly typed as RouteUrl must come from route(). If I have a variable that's usually a Ziggy-generated route URL but might also be a manually constructed URL string, I have to use string, if I use RouteUrl that means I'm intentionally restricting that value to something that came from Ziggy. (Right?)

Thanks!

[pataar]

Very cool. Re-explaining your code example for my own understanding, and for when I inevitably come back to this to remind myself how it works: now, anything explicitly typed as RouteUrl must come from route(). If I have a variable that's usually a Ziggy-generated route URL but might also be a manually constructed URL string, I have to use string, if I use RouteUrl that means I'm intentionally restricting that value to something that came from Ziggy. (Right?)

Thanks!

Exactly, that way you can validate that your variable must be a validated RouteUrl. This is useful for Link components or custom fetch functions for example.

[pataar]

Thanks for the merge :)