refactor(router-core): strip internal types from public build (#4907)

This PR proposes we use the `@internal` JSDoc tag, and `--stripInternal`
typescript compiler option to remove internal keys from the public
`.d.ts` files.

Docs for `stripInternal`:
https://www.typescriptlang.org/tsconfig/#stripInternal

This helps ensuring internal values aren't considered as part of the
*public API surface* by users, allowing us more flexibility in
refactoring.

> [!WARNING]
> This PR proposes we add `stripInternal` to the entire repo, not just
`router-core`. However there are already some values marked as internal
that weren't added by this PR:
> - `InferStructuralSharing` in `react-router`
> - `handleHashScroll` in `router-core > scrollRestoration`
> - many `InferFoo` types in `router-core > typePrimitives`
>
> as a result of this, we might have to switch some of those `@internal`
tags to something else (like `@private` maybe?) because they are, in
fact, necessary for the build to be correct.

Example:
```ts
export type Foo = {
  a: number,
  /** @internal */
  b: number,
}

/** @internal */
export function hello() {
  return 'world'
}

export const answer = 42
```
gets compiled as `.d.ts` to
```ts
export type Foo = {
  a: number
}
export const answer = 42
```

---------

Co-authored-by: autofix-ci[bot] <114827586+autofix-ci[bot]@users.noreply.github.com>

Author: Sheraff

packages/router-core/src/Matches.ts

@@ -137,10 +137,14 @@ export interface RouteMatch<
   searchError: unknown
   updatedAt: number
   loadPromise?: ControlledPromise<void>
+  /** @internal */
   beforeLoadPromise?: ControlledPromise<void>
+  /** @internal */
   loaderPromise?: ControlledPromise<void>
   loaderData?: TLoaderData
+  /** @internal */
   __routeContext: Record<string, unknown>
+  /** @internal */
   __beforeLoadContext?: Record<string, unknown>
   context: TAllContext
   search: TFullSearchSchema

packages/router-core/src/typePrimitives.ts

@@ -36,7 +36,7 @@ export type ValidateParams<
 > = PathParamOptions<TRouter, TFrom, TTo>
 
 /**
- * @internal
+ * @private
  */
 export type InferFrom<
   TOptions,
@@ -48,7 +48,7 @@ export type InferFrom<
   : TDefaultFrom
 
 /**
- * @internal
+ * @private
  */
 export type InferTo<TOptions> = TOptions extends {
   to: infer TTo extends string
@@ -57,7 +57,7 @@ export type InferTo<TOptions> = TOptions extends {
   : undefined
 
 /**
- * @internal
+ * @private
  */
 export type InferMaskTo<TOptions> = TOptions extends {
   mask: { to: infer TTo extends string }
@@ -131,7 +131,7 @@ export type ValidateId<
 > = ConstrainLiteral<TId, RouteIds<TRouter['routeTree']>>
 
 /**
- * @internal
+ * @private
  */
 export type InferStrict<TOptions> = TOptions extends {
   strict: infer TStrict extends boolean
@@ -140,7 +140,7 @@ export type InferStrict<TOptions> = TOptions extends {
   : true
 
 /**
- * @internal
+ * @private
  */
 export type InferShouldThrow<TOptions> = TOptions extends {
   shouldThrow: infer TShouldThrow extends boolean
@@ -149,7 +149,7 @@ export type InferShouldThrow<TOptions> = TOptions extends {
   : true
 
 /**
- * @internal
+ * @private
  */
 export type InferSelected<TOptions> = TOptions extends {
   select: (...args: Array<any>) => infer TSelected

tsconfig.json

@@ -21,6 +21,7 @@
     "resolveJsonModule": true,
     "skipLibCheck": true,
     "strict": true,
+    "stripInternal": true,
     "target": "ES2020"
   },
   "include": ["eslint.config.js", "prettier.config.js", "scripts"]