@tanstack/eslint-plugin-router 1.154.7 → 1.161.2

package/src/rules/route-param-names/route-param-names.rule.ts

@@ -0,0 +1,127 @@
+import { AST_NODE_TYPES, ESLintUtils } from '@typescript-eslint/utils'
+
+import { getDocsUrl } from '../../utils/get-docs-url'
+import { detectTanstackRouterImports } from '../../utils/detect-router-imports'
+import { getInvalidParams } from './route-param-names.utils'
+import { pathAsFirstArgFunctions, pathAsPropertyFunctions } from './constants'
+import type { TSESTree } from '@typescript-eslint/utils'
+import type { ExtraRuleDocs } from '../../types'
+
+const createRule = ESLintUtils.RuleCreator<ExtraRuleDocs>(getDocsUrl)
+
+const pathAsFirstArgSet = new Set<string>(pathAsFirstArgFunctions)
+const pathAsPropertySet = new Set<string>(pathAsPropertyFunctions)
+
+export const name = 'route-param-names'
+
+export const rule = createRule({
+  name,
+  meta: {
+    type: 'problem',
+    docs: {
+      description: 'Ensure route param names are valid JavaScript identifiers',
+      recommended: 'error',
+    },
+    messages: {
+      invalidParamName:
+        'Invalid param name "{{paramName}}" in route path. Param names must be valid JavaScript identifiers (match /[a-zA-Z_$][a-zA-Z0-9_$]*/).',
+    },
+    schema: [],
+  },
+  defaultOptions: [],
+
+  create: detectTanstackRouterImports((context, _, helpers) => {
+    function reportInvalidParams(node: TSESTree.Node, path: string) {
+      const invalidParams = getInvalidParams(path)
+
+      for (const param of invalidParams) {
+        context.report({
+          node,
+          messageId: 'invalidParamName',
+          data: { paramName: param.paramName },
+        })
+      }
+    }
+
+    function getStringLiteralValue(node: TSESTree.Node): string | null {
+      if (
+        node.type === AST_NODE_TYPES.Literal &&
+        typeof node.value === 'string'
+      ) {
+        return node.value
+      }
+      if (
+        node.type === AST_NODE_TYPES.TemplateLiteral &&
+        node.quasis.length === 1
+      ) {
+        const cooked = node.quasis[0]?.value.cooked
+        if (cooked != null) {
+          return cooked
+        }
+      }
+      return null
+    }
+
+    return {
+      CallExpression(node) {
+        // Handle direct function call: createRoute({ path: '...' })
+        if (node.callee.type === AST_NODE_TYPES.Identifier) {
+          const funcName = node.callee.name
+
+          // Skip if not imported from TanStack Router
+          if (!helpers.isTanstackRouterImport(node.callee)) {
+            return
+          }
+
+          // Case: createRoute({ path: '/path/$param' }) or createRoute({ 'path': '/path/$param' })
+          if (pathAsPropertySet.has(funcName)) {
+            const arg = node.arguments[0]
+            if (arg?.type === AST_NODE_TYPES.ObjectExpression) {
+              for (const prop of arg.properties) {
+                if (prop.type === AST_NODE_TYPES.Property) {
+                  const isPathKey =
+                    (prop.key.type === AST_NODE_TYPES.Identifier &&
+                      prop.key.name === 'path') ||
+                    (prop.key.type === AST_NODE_TYPES.Literal &&
+                      prop.key.value === 'path')
+                  if (isPathKey) {
+                    const pathValue = getStringLiteralValue(prop.value)
+                    if (pathValue) {
+                      reportInvalidParams(prop.value, pathValue)
+                    }
+                  }
+                }
+              }
+            }
+            return
+          }
+        }
+
+        // Handle curried function call: createFileRoute('/path')({ ... })
+        if (node.callee.type === AST_NODE_TYPES.CallExpression) {
+          const innerCall = node.callee
+
+          if (innerCall.callee.type === AST_NODE_TYPES.Identifier) {
+            const funcName = innerCall.callee.name
+
+            // Skip if not imported from TanStack Router
+            if (!helpers.isTanstackRouterImport(innerCall.callee)) {
+              return
+            }
+
+            // Case: createFileRoute('/path/$param')(...) or similar
+            if (pathAsFirstArgSet.has(funcName)) {
+              const pathArg = innerCall.arguments[0]
+              if (pathArg) {
+                const pathValue = getStringLiteralValue(pathArg)
+                if (pathValue) {
+                  reportInvalidParams(pathArg, pathValue)
+                }
+              }
+            }
+          }
+        }
+      },
+    }
+  }),
+})

package/src/rules/route-param-names/route-param-names.utils.ts

@@ -0,0 +1,122 @@
+import { VALID_PARAM_NAME_REGEX } from './constants'
+
+export interface ExtractedParam {
+  /** The full param string including $ prefix (e.g., "$userId", "-$optional") */
+  fullParam: string
+  /** The param name without $ prefix (e.g., "userId", "optional") */
+  paramName: string
+  /** Whether this is an optional param (prefixed with -$) */
+  isOptional: boolean
+  /** Whether this param name is valid */
+  isValid: boolean
+}
+
+/**
+ * Extracts param names from a route path segment.
+ *
+ * Handles these patterns:
+ * - $paramName                     -> extract "paramName"
+ * - {$paramName}                   -> extract "paramName"
+ * - prefix{$paramName}suffix       -> extract "paramName"
+ * - {-$paramName}                  -> extract "paramName" (optional)
+ * - prefix{-$paramName}suffix      -> extract "paramName" (optional)
+ * - $ or {$}                       -> wildcard, skip validation
+ */
+export function extractParamsFromSegment(
+  segment: string,
+): Array<ExtractedParam> {
+  const params: Array<ExtractedParam> = []
+
+  // Skip empty segments
+  if (!segment || !segment.includes('$')) {
+    return params
+  }
+
+  // Check for wildcard ($ alone or {$})
+  if (segment === '$' || segment === '{$}') {
+    return params // Wildcard, no param name to validate
+  }
+
+  // Pattern 1: Simple $paramName (entire segment starts with $)
+  if (segment.startsWith('$') && !segment.includes('{')) {
+    const paramName = segment.slice(1)
+    if (paramName) {
+      params.push({
+        fullParam: segment,
+        paramName,
+        isOptional: false,
+        isValid: VALID_PARAM_NAME_REGEX.test(paramName),
+      })
+    }
+    return params
+  }
+
+  // Pattern 2: Braces pattern {$paramName} or {-$paramName} with optional prefix/suffix
+  // Match patterns like: prefix{$param}suffix, {$param}, {-$param}
+  const bracePattern = /\{(-?\$)([^}]*)\}/g
+  let match
+
+  while ((match = bracePattern.exec(segment)) !== null) {
+    const prefix = match[1] // "$" or "-$"
+    const paramName = match[2] // The param name after $ or -$
+
+    if (!paramName) {
+      // This is a wildcard {$} or {-$}, skip
+      continue
+    }
+
+    const isOptional = prefix === '-$'
+
+    params.push({
+      fullParam: `${prefix}${paramName}`,
+      paramName,
+      isOptional,
+      isValid: VALID_PARAM_NAME_REGEX.test(paramName),
+    })
+  }
+
+  return params
+}
+
+/**
+ * Extracts all params from a route path.
+ *
+ * @param path - The route path (e.g., "/users/$userId/posts/$postId")
+ * @returns Array of extracted params with validation info
+ */
+export function extractParamsFromPath(path: string): Array<ExtractedParam> {
+  if (!path || !path.includes('$')) {
+    return []
+  }
+
+  const segments = path.split('/')
+  const allParams: Array<ExtractedParam> = []
+
+  for (const segment of segments) {
+    const params = extractParamsFromSegment(segment)
+    allParams.push(...params)
+  }
+
+  return allParams
+}
+
+/**
+ * Validates a single param name.
+ *
+ * @param paramName - The param name to validate (without $ prefix)
+ * @returns Whether the param name is valid
+ */
+export function isValidParamName(paramName: string): boolean {
+  return VALID_PARAM_NAME_REGEX.test(paramName)
+}
+
+/**
+ * Gets all invalid params from a route path.
+ *
+ * @param path - The route path
+ * @returns Array of invalid param info
+ */
+export function getInvalidParams(path: string): Array<ExtractedParam> {
+  const params = extractParamsFromPath(path)
+  return params.filter((p) => !p.isValid)
+}

package/src/rules.ts

@@ -1,4 +1,5 @@
 import * as createRoutePropertyOrder from './rules/create-route-property-order/create-route-property-order.rule'
+import * as routeParamNames from './rules/route-param-names/route-param-names.rule'
 import type { ESLintUtils } from '@typescript-eslint/utils'
 import type { ExtraRuleDocs } from './types'
 
@@ -12,4 +13,5 @@ export const rules: Record<
   >
 > = {
   [createRoutePropertyOrder.name]: createRoutePropertyOrder.rule,
+  [routeParamNames.name]: routeParamNames.rule,
 }

package/src/utils/detect-router-imports.ts

@@ -55,7 +55,8 @@ export function detectTanstackRouterImports(create: EnhancedCreate): Create {
       ImportDeclaration(node) {
         if (
           node.specifiers.length > 0 &&
-          node.importKind === 'value' &&
+          // `importKind` is parser-dependent and can be undefined (eg. Espree)
+          node.importKind !== 'type' &&
           node.source.value.startsWith('@tanstack/') &&
           node.source.value.endsWith('-router')
         ) {