@tanstack/eslint-plugin-router 1.58.0

package/src/rules/create-route-property-order/constants.ts

@@ -0,0 +1,24 @@
+export const createRouteFunctionsIndirect = [
+  'createFileRoute',
+  'createRootRouteWithContext',
+] as const
+export const createRouteFunctionsDirect = [
+  'createRootRoute',
+  'createRoute',
+] as const
+
+export const createRouteFunctions = [
+  ...createRouteFunctionsDirect,
+  ...createRouteFunctionsIndirect,
+] as const
+
+export type CreateRouteFunction = (typeof createRouteFunctions)[number]
+
+export const checkedProperties = [
+  'params',
+  'validateSearch',
+  'context',
+  'beforeLoad',
+  'loaderDeps',
+  'loader',
+] as const

package/src/rules/create-route-property-order/create-route-property-order.rule.ts

@@ -0,0 +1,125 @@
+import { AST_NODE_TYPES, ESLintUtils } from '@typescript-eslint/utils'
+
+import { getDocsUrl } from '../../utils/get-docs-url'
+import { detectTanstackRouterImports } from '../../utils/detect-router-imports'
+import { sortDataByOrder } from './create-route-property-order.utils'
+import {
+  checkedProperties,
+  createRouteFunctions,
+  createRouteFunctionsIndirect,
+} from './constants'
+import type { CreateRouteFunction } from './constants'
+import type { ExtraRuleDocs } from '../../types'
+
+const createRule = ESLintUtils.RuleCreator<ExtraRuleDocs>(getDocsUrl)
+
+const createRouteFunctionSet = new Set(createRouteFunctions)
+function isCreateRouteFunction(node: any): node is CreateRouteFunction {
+  return createRouteFunctionSet.has(node)
+}
+
+export const name = 'create-route-property-order'
+
+export const rule = createRule({
+  name,
+  meta: {
+    type: 'problem',
+    docs: {
+      description:
+        'Ensure correct order of inference sensitive properties for createRoute functions',
+      recommended: 'error',
+    },
+    messages: {
+      invalidOrder: 'Invalid order of properties for `{{function}}`.',
+    },
+    schema: [],
+    hasSuggestions: true,
+    fixable: 'code',
+  },
+  defaultOptions: [],
+
+  create: detectTanstackRouterImports((context) => {
+    return {
+      CallExpression(node) {
+        if (node.callee.type !== AST_NODE_TYPES.Identifier) {
+          return
+        }
+        const createRouteFunction = node.callee.name
+        if (!isCreateRouteFunction(createRouteFunction)) {
+          return
+        }
+        let args = node.arguments
+        if (createRouteFunctionsIndirect.includes(createRouteFunction as any)) {
+          if (node.parent.type === AST_NODE_TYPES.CallExpression) {
+            args = node.parent.arguments
+          } else {
+            return
+          }
+        }
+
+        const argument = args[0]
+        if (argument === undefined || argument.type !== 'ObjectExpression') {
+          return
+        }
+
+        const allProperties = argument.properties
+
+        // TODO we need to support spread elements, they would be discarded here
+        const properties = allProperties.flatMap((p) => {
+          if (
+            p.type === AST_NODE_TYPES.Property &&
+            p.key.type === AST_NODE_TYPES.Identifier
+          ) {
+            return { name: p.key.name, property: p }
+          } else if (p.type === AST_NODE_TYPES.SpreadElement) {
+            if (p.argument.type === AST_NODE_TYPES.Identifier) {
+              return { name: p.argument.name, property: p }
+            } else {
+              throw new Error('Unsupported spread element')
+            }
+          }
+          return []
+        })
+
+        const sortedProperties = sortDataByOrder(
+          properties,
+          checkedProperties,
+          'name',
+        )
+        if (sortedProperties === null) {
+          return
+        }
+        context.report({
+          node: argument,
+          data: { function: node.callee.name },
+          messageId: 'invalidOrder',
+          fix(fixer) {
+            const sourceCode = context.sourceCode
+
+            const text = sortedProperties.reduce(
+              (sourceText, specifier, index) => {
+                let text = ''
+                if (index < allProperties.length - 1) {
+                  text = sourceCode
+                    .getText()
+                    .slice(
+                      allProperties[index]!.range[1],
+                      allProperties[index + 1]!.range[0],
+                    )
+                }
+                return (
+                  sourceText + sourceCode.getText(specifier.property) + text
+                )
+              },
+              '',
+            )
+            return fixer.replaceTextRange(
+              [allProperties[0]!.range[0], allProperties.at(-1)!.range[1]],
+              text,
+            )
+          },
+        })
+      },
+    }
+  }),
+})

package/src/rules/create-route-property-order/create-route-property-order.utils.ts

@@ -0,0 +1,38 @@
+export function sortDataByOrder<T, TKey extends keyof T>(
+  data: Array<T> | ReadonlyArray<T>,
+  orderArray: Array<T[TKey]> | ReadonlyArray<T[TKey]>,
+  key: TKey,
+): Array<T> | null {
+  const orderMap = new Map(orderArray.map((item, index) => [item, index]))
+
+  // Separate items that are in orderArray from those that are not
+  const inOrderArray = data
+    .filter((item) => orderMap.has(item[key]))
+    .sort((a, b) => {
+      const indexA = orderMap.get(a[key])!
+      const indexB = orderMap.get(b[key])!
+
+      return indexA - indexB
+    })
+
+  const inOrderIterator = inOrderArray.values()
+
+  // `as boolean` is needed to avoid TS incorrectly inferring that wasResorted is always `true`
+  let wasResorted = false as boolean
+
+  const result = data.map((item) => {
+    if (orderMap.has(item[key])) {
+      const sortedItem = inOrderIterator.next().value!
+      if (sortedItem[key] !== item[key]) {
+        wasResorted = true
+      }
+      return sortedItem
+    }
+    return item
+  })
+
+  if (!wasResorted) {
+    return null
+  }
+  return result
+}

package/src/rules.ts

@@ -0,0 +1,15 @@
+import * as createRoutePropertyOrder from './rules/create-route-property-order/create-route-property-order.rule'
+import type { ESLintUtils } from '@typescript-eslint/utils'
+import type { ExtraRuleDocs } from './types'
+
+export const rules: Record<
+  string,
+  ESLintUtils.RuleModule<
+    string,
+    ReadonlyArray<unknown>,
+    ExtraRuleDocs,
+    ESLintUtils.RuleListener
+  >
+> = {
+  [createRoutePropertyOrder.name]: createRoutePropertyOrder.rule,
+}

package/src/types.ts

@@ -0,0 +1,3 @@
+export type ExtraRuleDocs = {
+  recommended: 'strict' | 'error' | 'warn'
+}

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

@@ -0,0 +1,94 @@
+import { TSESTree } from '@typescript-eslint/utils'
+import type { ESLintUtils, TSESLint } from '@typescript-eslint/utils'
+
+type Create = Parameters<
+  ReturnType<typeof ESLintUtils.RuleCreator>
+>[0]['create']
+
+type Context = Parameters<Create>[0]
+type Options = Parameters<Create>[1]
+type Helpers = {
+  isSpecificTanstackRouterImport: (
+    node: TSESTree.Identifier,
+    source: string,
+  ) => boolean
+  isTanstackRouterImport: (node: TSESTree.Identifier) => boolean
+}
+
+type EnhancedCreate = (
+  context: Context,
+  options: Options,
+  helpers: Helpers,
+) => ReturnType<Create>
+
+export function detectTanstackRouterImports(create: EnhancedCreate): Create {
+  return (context, optionsWithDefault) => {
+    const tanstackRouterImportSpecifiers: Array<TSESTree.ImportClause> = []
+
+    const helpers: Helpers = {
+      isSpecificTanstackRouterImport(node, source) {
+        return !!tanstackRouterImportSpecifiers.find((specifier) => {
+          if (
+            specifier.type === TSESTree.AST_NODE_TYPES.ImportSpecifier &&
+            specifier.parent.type ===
+              TSESTree.AST_NODE_TYPES.ImportDeclaration &&
+            specifier.parent.source.value === source
+          ) {
+            return node.name === specifier.local.name
+          }
+
+          return false
+        })
+      },
+      isTanstackRouterImport(node) {
+        return !!tanstackRouterImportSpecifiers.find((specifier) => {
+          if (specifier.type === TSESTree.AST_NODE_TYPES.ImportSpecifier) {
+            return node.name === specifier.local.name
+          }
+
+          return false
+        })
+      },
+    }
+
+    const detectionInstructions: TSESLint.RuleListener = {
+      ImportDeclaration(node) {
+        if (
+          node.specifiers.length > 0 &&
+          node.importKind === 'value' &&
+          node.source.value.startsWith('@tanstack/') &&
+          node.source.value.endsWith('-router')
+        ) {
+          tanstackRouterImportSpecifiers.push(...node.specifiers)
+        }
+      },
+    }
+
+    // Call original rule definition
+    const ruleInstructions = create(context, optionsWithDefault, helpers)
+    const enhancedRuleInstructions: TSESLint.RuleListener = {}
+
+    const allKeys = new Set(
+      Object.keys(detectionInstructions).concat(Object.keys(ruleInstructions)),
+    )
+
+    // Iterate over ALL instructions keys so we can override original rule instructions
+    // to prevent their execution if conditions to report errors are not met.
+    allKeys.forEach((instruction) => {
+      enhancedRuleInstructions[instruction] = (node) => {
+        if (instruction in detectionInstructions) {
+          detectionInstructions[instruction]?.(node)
+        }
+
+        const ruleFunction = ruleInstructions[instruction]
+        if (ruleFunction !== undefined) {
+          return ruleFunction(node)
+        }
+
+        return undefined
+      }
+    })
+
+    return enhancedRuleInstructions
+  }
+}

package/src/utils/get-docs-url.ts

@@ -0,0 +1,2 @@
+export const getDocsUrl = (ruleName: string): string =>
+  `https://tanstack.com/router/latest/docs/eslint/${ruleName}`