Add jsdoc annotations to public api

[tannerlinsley]

Add JSDoc annotations to 20 core public API exports to improve code self-documentation.

---

 

Summary by CodeRabbit

Release Notes

• New Features

  • Added utility functions: exactPathTest for path comparison, getLocationChangeInfo for tracking location changes, and getMatchedRoutes for route matching.
  • Introduced error classes: SearchParamError and PathParamError.
  • Added defaultSerializeError for error serialization and getInitialRouterState for router initialization.
  • Enhanced lazy module imports with improved lazyFn function.
  • Added preserve option for trailing slash handling.
  • Added rootRouteId constant for stable root route identification.

• Documentation

  • Added comprehensive JSDoc comments throughout the core router package for improved API clarity.

[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

The changes add new public utilities, constants, and symbols across the router-core package, along with comprehensive JSDoc documentation. Key additions include TSR_DEFERRED_PROMISE symbol, exactPathTest function, rootRouteId constant, and utilities for error serialization, location change detection, route matching, and initial state creation. Mostly additive changes with no modifications to existing logic or behavior.

Changes

Cohort / File(s)	Summary
New public symbols and constants packages/router-core/src/defer.ts, packages/router-core/src/root.ts	Added TSR_DEFERRED_PROMISE as a well-known symbol; introduced rootRouteId constant and RootRouteId type alias for stable root route identification.
New router utilities and enhancements packages/router-core/src/router.ts	Added defaultSerializeError for error serialization, SearchParamError and PathParamError exception classes, getLocationChangeInfo for detecting location changes, reworked lazyFn for lazy module imports, getInitialRouterState for initial state creation, and getMatchedRoutes for building matched route chains. Added 'preserve' option to trailingSlashOptions.
New path utilities packages/router-core/src/path.ts	Added exactPathTest function to compare pathnames for exact equality after normalizing trailing slashes.
SSR serialization documentation packages/router-core/src/ssr/serializer/transformer.ts	Enhanced JSDoc comments for createSerializationAdapter, makeSsrSerovalPlugin, and makeSerovalPlugin describing their SSR hydration and serialization capabilities.
Documentation enhancements packages/router-core/src/process-route-tree.ts, packages/router-core/src/redirect.ts, packages/router-core/src/scroll-restoration.ts, packages/router-core/src/searchParams.ts	Added or clarified JSDoc comments for existing public utilities without modifying function signatures or behavior.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Multiple files contain new public APIs with logic requiring verification (particularly router.ts with several utility functions), while several files contain documentation-only changes. Heterogeneous mix of functional additions and documentation updates across the codebase demands separate reasoning for each new utility.

Possibly related PRs

• Add core api jsdoc annotations #5550: Modifies the same defer.ts file and implements the TSR_DEFERRED_PROMISE mechanism that this PR exports.
• Add jsdoc annotations to public api #5574: Overlapping documentation and JSDoc enhancements across identical router-core files including path.ts, router.ts, redirect.ts, and scroll-restoration.ts.

Suggested labels

documentation

Poem

🐰 Hop along with symbols bright,
New utilities take their flight,
Route ids marked with proud resolve,
JSDoc comments help us solve,
The API's clearer path shines clear!

✨ 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-jsdoc-annotations-to-public-api-16d2

---

📜 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 47bc1c3 and 116e4c0.

📒 Files selected for processing (9)

• packages/router-core/src/defer.ts (1 hunks)
• packages/router-core/src/path.ts (2 hunks)
• packages/router-core/src/process-route-tree.ts (1 hunks)
• packages/router-core/src/redirect.ts (2 hunks)
• packages/router-core/src/root.ts (1 hunks)
• packages/router-core/src/router.ts (7 hunks)
• packages/router-core/src/scroll-restoration.ts (3 hunks)
• packages/router-core/src/searchParams.ts (1 hunks)
• packages/router-core/src/ssr/serializer/transformer.ts (3 hunks)

---

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

[nx-cloud]

View your CI Pipeline Execution ↗ for commit 116e4c0

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

---

☁️ Nx Cloud last updated this comment at 2025-10-23 04:21:25 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-kitchen-sink-solid-query
• tanstack-router-solid-example-kitchen-sink-solid-query-file-based
• tanstack-router-solid-example-quickstart-file-based
• tanstack-solid-start-example-bare
• tanstack-solid-start-example-basic
• tanstack-solid-start-example-basic-auth
• tanstack-solid-start-example-basic-cloudflare
• tanstack-solid-start-example-basic-netlify
• tanstack-solid-start-example-basic-nitro
• tanstack-start-example-basic-solid-query
• 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@5587

@tanstack/directive-functions-plugin

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

@tanstack/eslint-plugin-router

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

@tanstack/history

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

@tanstack/nitro-v2-vite-plugin

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

@tanstack/react-router

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

@tanstack/react-router-devtools

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

@tanstack/react-router-ssr-query

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

@tanstack/react-start

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

@tanstack/react-start-client

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

@tanstack/react-start-server

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

@tanstack/router-cli

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

@tanstack/router-core

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

@tanstack/router-devtools

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

@tanstack/router-devtools-core

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

@tanstack/router-generator

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

@tanstack/router-plugin

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

@tanstack/router-ssr-query-core

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

@tanstack/router-utils

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

@tanstack/router-vite-plugin

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

@tanstack/server-functions-plugin

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

@tanstack/solid-router

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

@tanstack/solid-router-devtools

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

@tanstack/solid-router-ssr-query

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

@tanstack/solid-start

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

@tanstack/solid-start-client

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

@tanstack/solid-start-server

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

@tanstack/start-client-core

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

@tanstack/start-plugin-core

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

@tanstack/start-server-core

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

@tanstack/start-static-server-functions

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

@tanstack/start-storage-context

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

@tanstack/valibot-adapter

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

@tanstack/virtual-file-routes

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

@tanstack/zod-adapter

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

commit: 116e4c0