Add core api jsdoc annotations

[tannerlinsley]

Add JSDoc annotations to core public APIs (defer, redirect, isRedirect, retainSearchParams, stripSearchParams) and fix related documentation links to improve clarity.

---

Summary by CodeRabbit

• New Features

  • Added a new defer utility for handling deferred promises with state tracking.

• Improvements

  • Enhanced type inference for redirect functionality with improved generic parameter ordering.
  • Clarified documentation for search parameter retention and removal behavior across navigations.

[cursor]

Cursor Agent can help with this pull request. Just @cursor in comments and I'll start working on changes in this branch.
_{Learn more about Cursor Agents}

[coderabbitai]

Caution

Review failed

The pull request is closed.

Walkthrough

Added a new defer function to track Promise states with serialized error handling, reordered generic type parameters in the redirect function signature with const qualifiers, and updated documentation for search parameter utilities and redirect behavior.

Changes

Cohort / File(s)	Summary
Core routing utilities packages/router-core/src/defer.ts	New exported defer<T> function that wraps promises with TSR_DEFERRED_PROMISE state tracking, transitioning from pending to success/error states with optional error serialization
Redirect function refactoring packages/router-core/src/redirect.ts	Generic type parameters reordered (TTo before TFrom) with const qualifiers; JSDoc updated to clarify redirect behavior, status codes, and usage context; added documentation header for isRedirect helper
Search parameter documentation packages/router-core/src/searchMiddleware.ts	Updated JSDoc for retainSearchParams and stripSearchParams to clarify behavior and parameter handling; no logic changes
Documentation link updates packages/router-core/src/searchParams.ts	Updated JSDoc references in parseSearchWith and stringifySearchWith to current framework paths

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

The PR introduces a new function with state-management logic (defer), modifies generic type signatures in an exported API (redirect—potentially affecting type inference), and includes heterogeneous changes across documentation and links. The defer logic and signature reordering require careful review despite documentation-only changes in other files.

Possibly related PRs

• fix: correctly handle client-side vs server-side redirects with rewrites #5330: Modifies redirect handling in RouterCore.resolveRedirect, directly related to the redirect function signature and behavior changes in this PR.

Suggested labels

documentation

Poem

🐰 Promises deferred, now tracked with care,
Generic types shuffled, reordered with flair,
Search params documented, links freshly repaired,
Redirects refined—a router rebuild shared! ✨

✨ Finishing touches

• 📝 Generate docstrings

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch cursor/add-core-api-jsdoc-annotations-9d87

---

📜 Recent review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 1ed3c92 and a708973.

📒 Files selected for processing (4)

• packages/router-core/src/defer.ts (1 hunks)
• packages/router-core/src/redirect.ts (2 hunks)
• packages/router-core/src/searchMiddleware.ts (2 hunks)
• packages/router-core/src/searchParams.ts (2 hunks)

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[nx-cloud]

View your CI Pipeline Execution ↗ for commit a708973

Command	Status	Duration	Result
nx affected --targets=test:eslint,test:unit,tes...	✅ Succeeded	5m 11s	View ↗
nx run-many --target=build --exclude=examples/*...	✅ Succeeded	1m 24s	View ↗

---

☁️ Nx Cloud last updated this comment at 2025-10-20 18:43:41 UTC

[pkg-pr-new]

More templates

• tanstack-router-solid-example-basic
• tanstack-router-solid-example-basic-devtools-panel
• tanstack-router-solid-example-basic-file-based
• tanstack-router-solid-example-basic-non-nested-devtools
• tanstack-router-solid-example-basic-solid-query
• tanstack-router-solid-example-basic-solid-query-file-based
• tanstack-router-solid-example-basic-ssr-streaming-file-based
• tanstack-router-solid-example-kitchen-sink-file-based
• tanstack-router-solid-example-quickstart-file-based
• tanstack-solid-start-example-bare
• tanstack-solid-start-example-basic
• tanstack-solid-start-example-basic-static
• tanstack-router-react-example-authenticated-routes
• tanstack-router-react-example-authenticated-routes-firebase
• tanstack-router-react-example-basic
• tanstack-router-react-example-basic-default-search-params
• tanstack-router-react-example-basic-devtools-panel
• tanstack-router-react-example-basic-file-based
• tanstack-router-react-example-basic-non-nested-devtools
• tanstack-router-react-example-react-query
• tanstack-router-react-example-basic-react-query-file-based
• tanstack-router-react-example-basic-ssr-file-based
• tanstack-router-react-example-basic-ssr-streaming-file-based
• tanstack-router-react-example-basic-virtual-file-based
• tanstack-router-react-example-basic-virtual-inside-file-based
• tanstack-router-react-example-deferred-data
• tanstack-router-i18n-paraglide
• tanstack-router-react-example-kitchen-sink
• tanstack-router-react-example-kitchen-sink-file-based
• tanstack-router-react-example-kitchen-sink-react-query
• tanstack-router-react-example-kitchen-sink-react-query-file-based
• tanstack-router-react-example-large-file-based
• tanstack-router-react-example-location-masking
• tanstack-router-react-example-navigation-blocking
• tanstack-router-react-example-quickstart
• tanstack-router-react-example-quickstart-esbuild-file-based
• tanstack-router-react-example-quickstart-file-based
• tanstack-router-react-example-quickstart-rspack-file-based
• tanstack-router-react-example-quickstart-webpack-file-based
• router-monorepo-react-query
• router-mono-simple
• router-mono-simple-lazy
• tanstack-router-react-example-scroll-restoration
• tanstack-search-validator-adapters
• tanstack-start-example-bare
• tanstack-start-example-basic
• tanstack-start-example-basic-auth
• tanstack-start-example-basic-cloudflare
• tanstack-start-example-basic-react-query
• tanstack-start-example-basic-static
• tanstack-start-bun-hosting
• tanstack-start-example-clerk-basic
• tanstack-start-example-convex-trellaux
• tanstack-start-example-counter
• tanstack-start-i18n-paraglide
• tanstack-start-example-large
• tanstack-start-example-material-ui
• tanstack-start-streaming-data-from-server-functions
• tanstack-start-example-supabase-basic
• tanstack-start-tailwind-v4
• tanstack-start-example-trellaux
• tanstack-start-example-workos
• tanstack-router-react-example-view-transitions
• tanstack-router-react-example-with-framer-motion
• tanstack-router-react-example-with-trpc
• tanstack-router-react-example-with-trpc-react-query

@tanstack/arktype-adapter

npm i https://pkg.pr.new/TanStack/router/@tanstack/arktype-adapter@5550

@tanstack/directive-functions-plugin

npm i https://pkg.pr.new/TanStack/router/@tanstack/directive-functions-plugin@5550

@tanstack/eslint-plugin-router

npm i https://pkg.pr.new/TanStack/router/@tanstack/eslint-plugin-router@5550

@tanstack/history

npm i https://pkg.pr.new/TanStack/router/@tanstack/history@5550

@tanstack/nitro-v2-vite-plugin

npm i https://pkg.pr.new/TanStack/router/@tanstack/nitro-v2-vite-plugin@5550

@tanstack/react-router

npm i https://pkg.pr.new/TanStack/router/@tanstack/react-router@5550

@tanstack/react-router-devtools

npm i https://pkg.pr.new/TanStack/router/@tanstack/react-router-devtools@5550

@tanstack/react-router-ssr-query

npm i https://pkg.pr.new/TanStack/router/@tanstack/react-router-ssr-query@5550

@tanstack/react-start

npm i https://pkg.pr.new/TanStack/router/@tanstack/react-start@5550

@tanstack/react-start-client

npm i https://pkg.pr.new/TanStack/router/@tanstack/react-start-client@5550

@tanstack/react-start-server

npm i https://pkg.pr.new/TanStack/router/@tanstack/react-start-server@5550

@tanstack/router-cli

npm i https://pkg.pr.new/TanStack/router/@tanstack/router-cli@5550

@tanstack/router-core

npm i https://pkg.pr.new/TanStack/router/@tanstack/router-core@5550

@tanstack/router-devtools

npm i https://pkg.pr.new/TanStack/router/@tanstack/router-devtools@5550

@tanstack/router-devtools-core

npm i https://pkg.pr.new/TanStack/router/@tanstack/router-devtools-core@5550

@tanstack/router-generator

npm i https://pkg.pr.new/TanStack/router/@tanstack/router-generator@5550

@tanstack/router-plugin

npm i https://pkg.pr.new/TanStack/router/@tanstack/router-plugin@5550

@tanstack/router-ssr-query-core

npm i https://pkg.pr.new/TanStack/router/@tanstack/router-ssr-query-core@5550

@tanstack/router-utils

npm i https://pkg.pr.new/TanStack/router/@tanstack/router-utils@5550

@tanstack/router-vite-plugin

npm i https://pkg.pr.new/TanStack/router/@tanstack/router-vite-plugin@5550

@tanstack/server-functions-plugin

npm i https://pkg.pr.new/TanStack/router/@tanstack/server-functions-plugin@5550

@tanstack/solid-router

npm i https://pkg.pr.new/TanStack/router/@tanstack/solid-router@5550

@tanstack/solid-router-devtools

npm i https://pkg.pr.new/TanStack/router/@tanstack/solid-router-devtools@5550

@tanstack/solid-start

npm i https://pkg.pr.new/TanStack/router/@tanstack/solid-start@5550

@tanstack/solid-start-client

npm i https://pkg.pr.new/TanStack/router/@tanstack/solid-start-client@5550

@tanstack/solid-start-server

npm i https://pkg.pr.new/TanStack/router/@tanstack/solid-start-server@5550

@tanstack/start-client-core

npm i https://pkg.pr.new/TanStack/router/@tanstack/start-client-core@5550

@tanstack/start-plugin-core

npm i https://pkg.pr.new/TanStack/router/@tanstack/start-plugin-core@5550

@tanstack/start-server-core

npm i https://pkg.pr.new/TanStack/router/@tanstack/start-server-core@5550

@tanstack/start-static-server-functions

npm i https://pkg.pr.new/TanStack/router/@tanstack/start-static-server-functions@5550

@tanstack/start-storage-context

npm i https://pkg.pr.new/TanStack/router/@tanstack/start-storage-context@5550

@tanstack/valibot-adapter

npm i https://pkg.pr.new/TanStack/router/@tanstack/valibot-adapter@5550

@tanstack/virtual-file-routes

npm i https://pkg.pr.new/TanStack/router/@tanstack/virtual-file-routes@5550

@tanstack/zod-adapter

npm i https://pkg.pr.new/TanStack/router/@tanstack/zod-adapter@5550

commit: a708973