refactor: move the RoutePath logic to RoutePage class (#2334)

SoonIter · web-flow · commit ca36e2e57365 · 2025-06-27T09:46:19.000Z
diff --git a/packages/core/src/node/auto-nav-sidebar/normalize.ts b/packages/core/src/node/auto-nav-sidebar/normalize.ts
@@ -9,7 +9,7 @@ import {
   slash,
 } from '@rspress/shared';
 import { logger } from '@rspress/shared/logger';
-import { absolutePathToLink, addRoutePrefix } from '../utils/normalizePath';
+import { absolutePathToRoutePath, addRoutePrefix } from '../route/RoutePage';
 import type {
   CustomLinkMeta,
   DividerSideMeta,
@@ -271,7 +271,7 @@ async function metaFileItemToSidebarItem(
     );
   }
 
-  const link = absolutePathToLink(absolutePathWithExt, docsDir);
+  const link = absolutePathToRoutePath(absolutePathWithExt, docsDir);
   const info = await extractInfoFromFrontmatterWithAbsolutePath(
     absolutePathWithExt,
     docsDir,
diff --git a/packages/core/src/node/auto-nav-sidebar/walk.ts b/packages/core/src/node/auto-nav-sidebar/walk.ts
@@ -3,7 +3,8 @@ import path from 'node:path';
 import { type NavItem, type Sidebar, isExternalUrl } from '@rspress/shared';
 import { logger } from '@rspress/shared/logger';
 import { hintNavJsonChangeThenPanic } from '../logger/hint';
-import { addRoutePrefix, pathExists } from '../utils';
+import { addRoutePrefix } from '../route/RoutePage';
+import { pathExists } from '../utils';
 import { scanSideMeta } from './normalize';
 import { readJson } from './utils';
 
diff --git a/packages/core/src/node/route/RoutePage.ts b/packages/core/src/node/route/RoutePage.ts
@@ -1,15 +1,110 @@
+import path from 'node:path';
 import type { RouteMeta } from '@rspress/shared';
+import { getPageKey } from '../utils/getPageKey';
+import { normalizePath, slash } from '../utils/normalizePath';
+import { RouteService } from './RouteService';
 
 export class RoutePage {
   routeMeta: RouteMeta;
+  // @ts-ignore use this field in the future
+  #docDir: string;
+
   // TODO: add pageIndexInfo
   // pageIndexInfo: PageIndexInfo;
 
-  static create(routeMeta: RouteMeta) {
-    return new RoutePage(routeMeta);
+  static create(absolutePath: string, docsDir: string): RoutePage {
+    const routeMeta = absolutePathToRouteMeta(absolutePath, docsDir);
+    return new RoutePage(routeMeta, docsDir);
+  }
+
+  static createFromExternal(
+    routePath: string,
+    filepath: string,
+    docDir: string,
+  ): RoutePage {
+    const routeMeta = RoutePage.generateRouteMeta(routePath, filepath, docDir);
+    return new RoutePage(routeMeta, path.dirname(filepath));
   }
 
-  constructor(routeMeta: RouteMeta) {
+  private constructor(routeMeta: RouteMeta, docDir: string) {
     this.routeMeta = routeMeta;
+    this.#docDir = docDir;
   }
+
+  static generateRouteMeta(
+    routePath: string,
+    filepath: string,
+    docDir: string,
+  ): RouteMeta {
+    const routeService = RouteService.getInstance();
+    const {
+      routePath: normalizedPath,
+      lang,
+      version,
+    } = routeService.normalizeRoutePath(routePath);
+    return {
+      routePath: normalizedPath,
+      absolutePath: normalizePath(filepath),
+      relativePath: normalizePath(path.relative(docDir, filepath)),
+      pageName: getPageKey(routePath),
+      lang,
+      version,
+    };
+  }
+}
+
+function absolutePathToRouteMeta(
+  absolutePath: string,
+  docsDir: string,
+): RouteMeta {
+  const relativePath = slash(path.relative(docsDir, absolutePath));
+  const routeService = RouteService.getInstance();
+
+  const { lang, routePath, version } = routeService.normalizeRoutePath(
+    relativePath.replace(path.extname(relativePath), ''),
+  );
+  return {
+    pageName: getPageKey(relativePath),
+    absolutePath,
+    lang,
+    version,
+    routePath,
+    relativePath,
+  };
+}
+
+/**
+ *
+ * @returns runtime cleanUrl like "/api/guide"
+ */
+export function absolutePathToRoutePath(
+  absolutePath: string,
+  docsDir: string,
+): string {
+  return absolutePathToRouteMeta(absolutePath, docsDir).routePath;
+}
+
+function absolutePathToRoutePrefix(
+  absolutePath: string,
+  docsDir: string,
+): string {
+  const relativePath = slash(
+    path.relative(
+      docsDir,
+      absolutePath.replace(path.extname(absolutePath), ''),
+    ),
+  );
+  const routeService = RouteService.getInstance();
+  const [versionPrefix, langPrefix] =
+    routeService.getRoutePathParts(relativePath);
+  return `${versionPrefix ? `/${versionPrefix}` : ''}${langPrefix ? `/${langPrefix}` : ''}`;
+}
+
+export function addRoutePrefix(
+  workDir: string,
+  docsDir: string,
+  link: string,
+): string {
+  const routePrefix = absolutePathToRoutePrefix(workDir, docsDir);
+  return `${routePrefix.replace(/\/$/, '')}/${link.replace(/^\//, '')}`;
 }
diff --git a/packages/core/src/node/route/RouteService.ts b/packages/core/src/node/route/RouteService.ts
@@ -6,7 +6,6 @@ import type { ComponentType } from 'react';
 import { glob } from 'tinyglobby';
 import type { PluginDriver } from '../PluginDriver';
 import { PUBLIC_DIR } from '../constants';
-import { getPageKey, normalizePath } from '../utils';
 import { RoutePage } from './RoutePage';
 import { getRoutePathParts, normalizeRoutePath } from './normalizeRoutePath';
 
@@ -69,13 +68,13 @@ export class RouteService {
       runtimeTempDir,
       pluginDriver,
     );
+    RouteService.__instance__ = routeService;
     await routeService.#init();
     await pluginDriver.routeServiceGenerated(routeService);
-    RouteService.__instance__ = routeService;
     return routeService;
   }
 
-  constructor(
+  private constructor(
     scanDir: string,
     userConfig: UserConfig,
     tempDir: string,
@@ -127,23 +126,10 @@ export class RouteService {
     ).sort();
 
     files.forEach(filePath => {
-      const fileRelativePath = normalizePath(
-        path.relative(this.#scanDir, filePath),
-      );
-      const { routePath, lang, version } =
-        this.normalizeRoutePath(fileRelativePath);
-      const absolutePath = path.join(this.#scanDir, fileRelativePath);
-
-      const routeMeta = {
-        routePath,
-        absolutePath: normalizePath(absolutePath),
-        relativePath: fileRelativePath,
-        pageName: getPageKey(fileRelativePath),
-        lang,
-        version,
-      };
-      this.addRoute(routeMeta);
+      const routePage = RoutePage.create(filePath, this.#scanDir);
+      this.addRoute(routePage);
     });
+
     // 2. external pages added by plugins
     const externalPages = await this.#pluginDriver.addPages();
 
@@ -152,38 +138,40 @@ export class RouteService {
         const { routePath, content, filepath } = route;
         // case1: specify the filepath
         if (filepath) {
-          const routeMeta = this.#generateRouteMeta(routePath, filepath);
-          this.addRoute(routeMeta);
+          const routePage = RoutePage.createFromExternal(
+            routePath,
+            filepath,
+            this.#scanDir,
+          );
+          this.addRoute(routePage);
           return;
         }
         // case2: specify the content
         if (content) {
           const filepath = await this.#writeTempFile(index, content);
-          const routeMeta = this.#generateRouteMeta(routePath, filepath);
-          this.addRoute(routeMeta);
+          const routePage = RoutePage.createFromExternal(
+            routePath,
+            filepath,
+            this.#scanDir,
+          );
+          this.addRoute(routePage);
         }
       }),
     );
 
     await this.#pluginDriver.routeGenerated(this.getRoutes());
   }
 
-  async addRoute(routeMeta: RouteMeta) {
-    const { routePath } = routeMeta;
+  async addRoute(routePage: RoutePage): Promise<void> {
+    const {
+      routeMeta: { routePath },
+    } = routePage;
     if (this.routeData.has(routePath)) {
       throw new Error(`routePath ${routePath} has already been added`);
     }
-
-    const routePage = RoutePage.create(routeMeta);
     this.routeData.set(routePath, routePage);
   }
 
-  removeRoute(filePath: string): void {
-    const fileRelativePath = path.relative(this.#scanDir, filePath);
-    const { routePath } = this.normalizeRoutePath(fileRelativePath);
-    this.routeData.delete(routePath);
-  }
-
   getRoutes(): RouteMeta[] {
     return Array.from(this.routeData.values()).map(i => i.routeMeta);
   }
@@ -260,22 +248,6 @@ ${routeMeta
     return tempFilePath;
   }
 
-  #generateRouteMeta(routePath: string, filepath: string): RouteMeta {
-    const {
-      routePath: normalizedPath,
-      lang,
-      version,
-    } = this.normalizeRoutePath(routePath);
-    return {
-      routePath: normalizedPath,
-      absolutePath: normalizePath(filepath),
-      relativePath: normalizePath(path.relative(this.#scanDir, filepath)),
-      pageName: getPageKey(routePath),
-      lang,
-      version,
-    };
-  }
-
   getRoutePageByRoutePath(routePath: string) {
     return this.routeData.get(routePath);
   }
diff --git a/packages/core/src/node/route/normalizeRoutePath.ts b/packages/core/src/node/route/normalizeRoutePath.ts
@@ -2,19 +2,19 @@ import { addLeadingSlash, addTrailingSlash } from '@rspress/shared';
 import { DEFAULT_PAGE_EXTENSIONS } from '@rspress/shared/constants';
 
 export const getRoutePathParts = (
-  routePath: string,
+  relativePath: string,
   lang: string,
   version: string,
   langs: string[],
   versions: string[],
 ) => {
-  const hasTrailSlash = routePath.endsWith('/');
+  const hasTrailSlash = relativePath.endsWith('/');
 
   let versionPart = '';
   let langPart = '';
   let purePathPart = '';
 
-  const parts: string[] = routePath.split('/').filter(Boolean);
+  const parts: string[] = relativePath.split('/').filter(Boolean);
 
   if (version) {
     const versionToMatch = parts[0];
@@ -47,15 +47,15 @@ export const getRoutePathParts = (
 };
 
 export const normalizeRoutePath = (
-  routePath: string,
+  relativePath: string,
   lang: string,
   version: string,
   langs: string[],
   versions: string[],
   extensions: string[] = DEFAULT_PAGE_EXTENSIONS,
 ) => {
   const [versionPart, langPart, purePathPart] = getRoutePathParts(
-    routePath,
+    relativePath,
     lang,
     version,
     langs,
diff --git a/packages/core/src/node/utils/normalizePath.ts b/packages/core/src/node/utils/normalizePath.ts
@@ -1,6 +1,5 @@
 import os from 'node:os';
 import path from 'node:path';
-import { RouteService } from '../route/RouteService';
 
 export const isWindows = os.platform() === 'win32';
 
@@ -11,46 +10,3 @@ export function slash(p: string): string {
 export function normalizePath(id: string): string {
   return path.posix.normalize(isWindows ? slash(id) : id);
 }
-
-/**
- *
- * @returns runtime cleanUrl like "/api/guide"
- */
-export function absolutePathToLink(
-  absolutePath: string,
-  docsDir: string,
-): string {
-  const relativePath = slash(
-    path.relative(
-      docsDir,
-      absolutePath.replace(path.extname(absolutePath), ''),
-    ),
-  );
-  const routeService = RouteService.getInstance();
-  return routeService.normalizeRoutePath(relativePath).routePath;
-}
-
-function absolutePathToRoutePrefix(
-  absolutePath: string,
-  docsDir: string,
-): string {
-  const relativePath = slash(
-    path.relative(
-      docsDir,
-      absolutePath.replace(path.extname(absolutePath), ''),
-    ),
-  );
-  const routeService = RouteService.getInstance();
-  const [versionPrefix, langPrefix] =
-    routeService.getRoutePathParts(relativePath);
-  return `${versionPrefix ? `/${versionPrefix}` : ''}${langPrefix ? `/${langPrefix}` : ''}`;
-}
-
-export function addRoutePrefix(
-  workDir: string,
-  docsDir: string,
-  link: string,
-): string {
-  const routePrefix = absolutePathToRoutePrefix(workDir, docsDir);
-  return `${routePrefix.replace(/\/$/, '')}/${link.replace(/^\//, '')}`;
-}
