refactor(content-docs): make readVersionsMetadata async (#6277)

* refactor(content-docs): make readVersionsMetadata async * fix tests
2025-04-29 18:27:56 +02:00 · 2022-01-06 21:46:08 +08:00 · 2022-01-06 21:46:08 +08:00 · edab7e07ed
commit edab7e07ed
parent 1d957d97e8
5 changed files with 87 additions and 83 deletions
--- a/packages/docusaurus-plugin-content-docs/src/tests/docs.test.ts
+++ b/packages/docusaurus-plugin-content-docs/src/tests/docs.test.ts
@ -166,7 +166,7 @@ describe('simple site', () => {
      ...DEFAULT_OPTIONS,
      ...loadSiteOptions.options,
    };
-    const versionsMetadata = readVersionsMetadata({
+    const versionsMetadata = await readVersionsMetadata({
      context,
      options,
    });
@ -523,7 +523,7 @@ describe('versioned site', () => {
      ...DEFAULT_OPTIONS,
      ...loadSiteOptions.options,
    };
-    const versionsMetadata = readVersionsMetadata({
+    const versionsMetadata = await readVersionsMetadata({
      context,
      options,
    });
--- a/packages/docusaurus-plugin-content-docs/src/tests/index.test.ts
+++ b/packages/docusaurus-plugin-content-docs/src/tests/index.test.ts
@ -141,7 +141,7 @@ describe('sidebar', () => {
            Please set the docs \\"sidebarPath\\" field in your config file to:
            - a sidebars path that exists
            - false: to disable the sidebar
-            - undefined: for Docusaurus generates it automatically"
+            - undefined: for Docusaurus to generate it automatically"
          `);
  });

--- a/packages/docusaurus-plugin-content-docs/src/tests/versions.test.ts
+++ b/packages/docusaurus-plugin-content-docs/src/tests/versions.test.ts
@ -91,7 +91,7 @@ describe('simple site', () => {
  test('readVersionsMetadata simple site', async () => {
    const {defaultOptions, defaultContext, vCurrent} = await loadSite();

-    const versionsMetadata = readVersionsMetadata({
+    const versionsMetadata = await readVersionsMetadata({
      options: defaultOptions,
      context: defaultContext,
    });
@ -102,7 +102,7 @@ describe('simple site', () => {
  test('readVersionsMetadata simple site with base url', async () => {
    const {defaultOptions, defaultContext, vCurrent} = await loadSite();

-    const versionsMetadata = readVersionsMetadata({
+    const versionsMetadata = await readVersionsMetadata({
      options: defaultOptions,
      context: {
        ...defaultContext,
@ -122,7 +122,7 @@ describe('simple site', () => {
  test('readVersionsMetadata simple site with current version config', async () => {
    const {defaultOptions, defaultContext, vCurrent} = await loadSite();

-    const versionsMetadata = readVersionsMetadata({
+    const versionsMetadata = await readVersionsMetadata({
      options: {
        ...defaultOptions,
        versions: {
@ -155,20 +155,20 @@ describe('simple site', () => {
  test('readVersionsMetadata simple site with unknown lastVersion should throw', async () => {
    const {defaultOptions, defaultContext} = await loadSite();

-    expect(() =>
+    await expect(
      readVersionsMetadata({
        options: {...defaultOptions, lastVersion: 'unknownVersionName'},
        context: defaultContext,
      }),
-    ).toThrowErrorMatchingInlineSnapshot(
-      `"Docs option lastVersion=unknownVersionName is invalid. Available version names are: current"`,
+    ).rejects.toThrowErrorMatchingInlineSnapshot(
+      `"Docs option lastVersion: unknownVersionName is invalid. Available version names are: current"`,
    );
  });

  test('readVersionsMetadata simple site with unknown version configurations should throw', async () => {
    const {defaultOptions, defaultContext} = await loadSite();

-    expect(() =>
+    await expect(
      readVersionsMetadata({
        options: {
          ...defaultOptions,
@ -180,7 +180,7 @@ describe('simple site', () => {
        },
        context: defaultContext,
      }),
-    ).toThrowErrorMatchingInlineSnapshot(
+    ).rejects.toThrowErrorMatchingInlineSnapshot(
      `"Invalid docs option \\"versions\\": unknown versions (unknownVersionName1,unknownVersionName2) found. Available version names are: current"`,
    );
  });
@ -188,26 +188,26 @@ describe('simple site', () => {
  test('readVersionsMetadata simple site with disableVersioning while single version should throw', async () => {
    const {defaultOptions, defaultContext} = await loadSite();

-    expect(() =>
+    await expect(
      readVersionsMetadata({
        options: {...defaultOptions, disableVersioning: true},
        context: defaultContext,
      }),
-    ).toThrowErrorMatchingInlineSnapshot(
-      `"Docs: using \\"disableVersioning=true\\" option on a non-versioned site does not make sense."`,
+    ).rejects.toThrowErrorMatchingInlineSnapshot(
+      `"Docs: using \\"disableVersioning: true\\" option on a non-versioned site does not make sense."`,
    );
  });

  test('readVersionsMetadata simple site without including current version should throw', async () => {
    const {defaultOptions, defaultContext} = await loadSite();

-    expect(() =>
+    await expect(
      readVersionsMetadata({
        options: {...defaultOptions, includeCurrentVersion: false},
        context: defaultContext,
      }),
-    ).toThrowErrorMatchingInlineSnapshot(
-      `"It is not possible to use docs without any version. Please check the configuration of these options: \\"includeCurrentVersion=false\\", \\"disableVersioning=false\\"."`,
+    ).rejects.toThrowErrorMatchingInlineSnapshot(
+      `"It is not possible to use docs without any version. Please check the configuration of these options: \\"includeCurrentVersion: false\\", \\"disableVersioning: false\\"."`,
    );
  });
 });
@ -327,7 +327,7 @@ describe('versioned site, pluginId=default', () => {
    const {defaultOptions, defaultContext, vCurrent, v101, v100, vwithSlugs} =
      await loadSite();

-    const versionsMetadata = readVersionsMetadata({
+    const versionsMetadata = await readVersionsMetadata({
      options: defaultOptions,
      context: defaultContext,
    });
@ -339,7 +339,7 @@ describe('versioned site, pluginId=default', () => {
    const {defaultOptions, defaultContext, v101, v100, vwithSlugs} =
      await loadSite();

-    const versionsMetadata = readVersionsMetadata({
+    const versionsMetadata = await readVersionsMetadata({
      options: {...defaultOptions, includeCurrentVersion: false},
      context: defaultContext,
    });
@ -356,7 +356,7 @@ describe('versioned site, pluginId=default', () => {
    const {defaultOptions, defaultContext, vCurrent, v101, v100, vwithSlugs} =
      await loadSite();

-    const versionsMetadata = readVersionsMetadata({
+    const versionsMetadata = await readVersionsMetadata({
      options: {
        ...defaultOptions,
        lastVersion: '1.0.0',
@ -410,7 +410,7 @@ describe('versioned site, pluginId=default', () => {
    const {defaultOptions, defaultContext, vCurrent, v101, v100, vwithSlugs} =
      await loadSite();

-    const versionsMetadata = readVersionsMetadata({
+    const versionsMetadata = await readVersionsMetadata({
      options: {
        ...defaultOptions,
        editUrl: 'https://github.com/facebook/docusaurus/edit/main/website/',
@ -454,7 +454,7 @@ describe('versioned site, pluginId=default', () => {
    const {defaultOptions, defaultContext, vCurrent, v101, v100, vwithSlugs} =
      await loadSite();

-    const versionsMetadata = readVersionsMetadata({
+    const versionsMetadata = await readVersionsMetadata({
      options: {
        ...defaultOptions,
        editUrl: 'https://github.com/facebook/docusaurus/edit/main/website/',
@ -498,7 +498,7 @@ describe('versioned site, pluginId=default', () => {
  test('readVersionsMetadata versioned site with onlyIncludeVersions option', async () => {
    const {defaultOptions, defaultContext, v101, vwithSlugs} = await loadSite();

-    const versionsMetadata = readVersionsMetadata({
+    const versionsMetadata = await readVersionsMetadata({
      options: {
        ...defaultOptions,
        // Order reversed on purpose: should not have any impact
@ -513,7 +513,7 @@ describe('versioned site, pluginId=default', () => {
  test('readVersionsMetadata versioned site with disableVersioning', async () => {
    const {defaultOptions, defaultContext, vCurrent} = await loadSite();

-    const versionsMetadata = readVersionsMetadata({
+    const versionsMetadata = await readVersionsMetadata({
      options: {...defaultOptions, disableVersioning: true},
      context: defaultContext,
    });
@ -534,7 +534,7 @@ describe('versioned site, pluginId=default', () => {
  test('readVersionsMetadata versioned site with all versions disabled', async () => {
    const {defaultOptions, defaultContext} = await loadSite();

-    expect(() =>
+    await expect(
      readVersionsMetadata({
        options: {
          ...defaultOptions,
@ -543,15 +543,15 @@ describe('versioned site, pluginId=default', () => {
        },
        context: defaultContext,
      }),
-    ).toThrowErrorMatchingInlineSnapshot(
-      `"It is not possible to use docs without any version. Please check the configuration of these options: \\"includeCurrentVersion=false\\", \\"disableVersioning=true\\"."`,
+    ).rejects.toThrowErrorMatchingInlineSnapshot(
+      `"It is not possible to use docs without any version. Please check the configuration of these options: \\"includeCurrentVersion: false\\", \\"disableVersioning: true\\"."`,
    );
  });

  test('readVersionsMetadata versioned site with empty onlyIncludeVersions', async () => {
    const {defaultOptions, defaultContext} = await loadSite();

-    expect(() =>
+    await expect(
      readVersionsMetadata({
        options: {
          ...defaultOptions,
@ -559,7 +559,7 @@ describe('versioned site, pluginId=default', () => {
        },
        context: defaultContext,
      }),
-    ).toThrowErrorMatchingInlineSnapshot(
+    ).rejects.toThrowErrorMatchingInlineSnapshot(
      `"Invalid docs option \\"onlyIncludeVersions\\": an empty array is not allowed, at least one version is needed."`,
    );
  });
@ -567,7 +567,7 @@ describe('versioned site, pluginId=default', () => {
  test('readVersionsMetadata versioned site with unknown versions in onlyIncludeVersions', async () => {
    const {defaultOptions, defaultContext} = await loadSite();

-    expect(() =>
+    await expect(
      readVersionsMetadata({
        options: {
          ...defaultOptions,
@ -575,7 +575,7 @@ describe('versioned site, pluginId=default', () => {
        },
        context: defaultContext,
      }),
-    ).toThrowErrorMatchingInlineSnapshot(
+    ).rejects.toThrowErrorMatchingInlineSnapshot(
      `"Invalid docs option \\"onlyIncludeVersions\\": unknown versions (unknownVersion1,unknownVersion2) found. Available version names are: current, 1.0.1, 1.0.0, withSlugs"`,
    );
  });
@ -583,7 +583,7 @@ describe('versioned site, pluginId=default', () => {
  test('readVersionsMetadata versioned site with lastVersion not in onlyIncludeVersions', async () => {
    const {defaultOptions, defaultContext} = await loadSite();

-    expect(() =>
+    await expect(
      readVersionsMetadata({
        options: {
          ...defaultOptions,
@ -592,7 +592,7 @@ describe('versioned site, pluginId=default', () => {
        },
        context: defaultContext,
      }),
-    ).toThrowErrorMatchingInlineSnapshot(
+    ).rejects.toThrowErrorMatchingInlineSnapshot(
      `"Invalid docs option \\"lastVersion\\": if you use both the \\"onlyIncludeVersions\\" and \\"lastVersion\\" options, then \\"lastVersion\\" must be present in the provided \\"onlyIncludeVersions\\" array."`,
    );
  });
@ -604,12 +604,12 @@ describe('versioned site, pluginId=default', () => {
      invalid: 'json',
    }));

-    expect(() => {
+    await expect(
      readVersionsMetadata({
        options: defaultOptions,
        context: defaultContext,
-      });
-    }).toThrowErrorMatchingInlineSnapshot(
+      }),
+    ).rejects.toThrowErrorMatchingInlineSnapshot(
      `"The versions file should contain an array of versions! Found content: {\\"invalid\\":\\"json\\"}"`,
    );
    mock.mockRestore();
@ -682,7 +682,7 @@ describe('versioned site, pluginId=community', () => {
  test('readVersionsMetadata versioned site (community)', async () => {
    const {defaultOptions, defaultContext, vCurrent, v100} = await loadSite();

-    const versionsMetadata = readVersionsMetadata({
+    const versionsMetadata = await readVersionsMetadata({
      options: defaultOptions,
      context: defaultContext,
    });
@ -693,7 +693,7 @@ describe('versioned site, pluginId=community', () => {
  test('readVersionsMetadata versioned site (community) with includeCurrentVersion=false', async () => {
    const {defaultOptions, defaultContext, v100} = await loadSite();

-    const versionsMetadata = readVersionsMetadata({
+    const versionsMetadata = await readVersionsMetadata({
      options: {...defaultOptions, includeCurrentVersion: false},
      context: defaultContext,
    });
@ -707,7 +707,7 @@ describe('versioned site, pluginId=community', () => {
  test('readVersionsMetadata versioned site (community) with disableVersioning', async () => {
    const {defaultOptions, defaultContext, vCurrent} = await loadSite();

-    const versionsMetadata = readVersionsMetadata({
+    const versionsMetadata = await readVersionsMetadata({
      options: {...defaultOptions, disableVersioning: true},
      context: defaultContext,
    });
@ -728,7 +728,7 @@ describe('versioned site, pluginId=community', () => {
  test('readVersionsMetadata versioned site (community) with all versions disabled', async () => {
    const {defaultOptions, defaultContext} = await loadSite();

-    expect(() =>
+    await expect(
      readVersionsMetadata({
        options: {
          ...defaultOptions,
@ -737,8 +737,8 @@ describe('versioned site, pluginId=community', () => {
        },
        context: defaultContext,
      }),
-    ).toThrowErrorMatchingInlineSnapshot(
-      `"It is not possible to use docs without any version. Please check the configuration of these options: \\"includeCurrentVersion=false\\", \\"disableVersioning=true\\"."`,
+    ).rejects.toThrowErrorMatchingInlineSnapshot(
+      `"It is not possible to use docs without any version. Please check the configuration of these options: \\"includeCurrentVersion: false\\", \\"disableVersioning: true\\"."`,
    );
  });
 });
--- a/packages/docusaurus-plugin-content-docs/src/index.ts
+++ b/packages/docusaurus-plugin-content-docs/src/index.ts
@ -64,7 +64,7 @@ export default async function pluginContentDocs(
 ): Promise<Plugin<LoadedContent>> {
  const {siteDir, generatedFilesDir, baseUrl, siteConfig} = context;

-  const versionsMetadata = readVersionsMetadata({context, options});
+  const versionsMetadata = await readVersionsMetadata({context, options});

  const pluginId = options.id ?? DEFAULT_PLUGIN_ID;

--- a/packages/docusaurus-plugin-content-docs/src/versions.ts
+++ b/packages/docusaurus-plugin-content-docs/src/versions.ts
@ -87,11 +87,13 @@ function ensureValidVersionArray(
  versionArray.forEach(ensureValidVersionString);
 }

-// TODO not easy to make async due to many deps
-function readVersionsFile(siteDir: string, pluginId: string): string[] | null {
+async function readVersionsFile(
+  siteDir: string,
+  pluginId: string,
+): Promise<string[] | null> {
  const versionsFilePath = getVersionsFilePath(siteDir, pluginId);
-  if (fs.existsSync(versionsFilePath)) {
-    const content = JSON.parse(fs.readFileSync(versionsFilePath, 'utf8'));
+  if (await fs.pathExists(versionsFilePath)) {
+    const content = JSON.parse(await fs.readFile(versionsFilePath, 'utf8'));
    ensureValidVersionArray(content);
    return content;
  } else {
@ -99,27 +101,26 @@ function readVersionsFile(siteDir: string, pluginId: string): string[] | null {
  }
 }

-// TODO not easy to make async due to many deps
-function readVersionNames(
+async function readVersionNames(
  siteDir: string,
  options: Pick<
    PluginOptions,
    'id' | 'disableVersioning' | 'includeCurrentVersion'
  >,
-): string[] {
-  const versionFileContent = readVersionsFile(siteDir, options.id);
+): Promise<string[]> {
+  const versionFileContent = await readVersionsFile(siteDir, options.id);

  if (!versionFileContent && options.disableVersioning) {
    throw new Error(
-      `Docs: using "disableVersioning=${options.disableVersioning}" option on a non-versioned site does not make sense.`,
+      `Docs: using "disableVersioning: ${options.disableVersioning}" option on a non-versioned site does not make sense.`,
    );
  }

  const versions = options.disableVersioning ? [] : versionFileContent ?? [];

-  // We add the current version at the beginning, unless
-  // - user don't want to
-  // - it's been explicitly added to versions.json
+  // We add the current version at the beginning, unless:
+  // - user don't want to; or
+  // - it's already been explicitly added to versions.json
  if (
    options.includeCurrentVersion &&
    !versions.includes(CURRENT_VERSION_NAME)
@ -129,7 +130,7 @@ function readVersionNames(

  if (versions.length === 0) {
    throw new Error(
-      `It is not possible to use docs without any version. Please check the configuration of these options: "includeCurrentVersion=${options.includeCurrentVersion}", "disableVersioning=${options.disableVersioning}".`,
+      `It is not possible to use docs without any version. Please check the configuration of these options: "includeCurrentVersion: ${options.includeCurrentVersion}", "disableVersioning: ${options.disableVersioning}".`,
    );
  }

@ -174,13 +175,6 @@ function getVersionMetadataPaths({
 > {
  const isCurrentVersion = versionName === CURRENT_VERSION_NAME;

-  const contentPath = isCurrentVersion
-    ? path.resolve(context.siteDir, options.path)
-    : path.join(
-        getVersionedDocsDirPath(context.siteDir, options.id),
-        `version-${versionName}`,
-      );
-
  const contentPathLocalized = getDocsDirPathLocalized({
    siteDir: context.siteDir,
    locale: context.i18n.currentLocale,
@ -188,21 +182,27 @@ function getVersionMetadataPaths({
    versionName,
  });

-  function getSidebarFilePath() {
-    if (isCurrentVersion) {
-      return resolveSidebarPathOption(context.siteDir, options.sidebarPath);
-    } else {
-      return path.join(
-        getVersionedSidebarsDirPath(context.siteDir, options.id),
-        `version-${versionName}-sidebars.json`,
-      );
-    }
+  if (isCurrentVersion) {
+    return {
+      contentPath: path.resolve(context.siteDir, options.path),
+      contentPathLocalized,
+      sidebarFilePath: resolveSidebarPathOption(
+        context.siteDir,
+        options.sidebarPath,
+      ),
+    };
  }

  return {
-    contentPath,
+    contentPath: path.join(
+      getVersionedDocsDirPath(context.siteDir, options.id),
+      `version-${versionName}`,
+    ),
    contentPathLocalized,
-    sidebarFilePath: getSidebarFilePath(),
+    sidebarFilePath: path.join(
+      getVersionedSidebarsDirPath(context.siteDir, options.id),
+      `version-${versionName}-sidebars.json`,
+    ),
  };
 }

@ -459,7 +459,7 @@ function checkVersionMetadataPaths({
 Please set the docs "sidebarPath" field in your config file to:
 - a sidebars path that exists
 - false: to disable the sidebar
- undefined: for Docusaurus generates it automatically`);
+- undefined: for Docusaurus to generate it automatically`);
  }
 }

@ -488,7 +488,7 @@ function checkVersionsOptions(
    !availableVersionNames.includes(options.lastVersion)
  ) {
    throw new Error(
-      `Docs option lastVersion=${options.lastVersion} is invalid. ${availableVersionNamesMsg}`,
+      `Docs option lastVersion: ${options.lastVersion} is invalid. ${availableVersionNamesMsg}`,
    );
  }
  const unknownVersionConfigNames = difference(
@ -531,9 +531,11 @@ function checkVersionsOptions(
  }
 }

-// Filter versions according to provided options
-// Note: we preserve the order in which versions are provided
-// the order of the onlyIncludeVersions array does not matter
+/**
+ * Filter versions according to provided options.
+ * Note: we preserve the order in which versions are provided;
+ * the order of the onlyIncludeVersions array does not matter
+ */
 function filterVersions(
  versionNamesUnfiltered: string[],
  options: Pick<PluginOptions, 'onlyIncludeVersions'>,
@ -547,8 +549,7 @@ function filterVersions(
  }
 }

-// TODO make this async (requires plugin init to be async)
-export function readVersionsMetadata({
+export async function readVersionsMetadata({
  context,
  options,
 }: {
@ -568,8 +569,11 @@ export function readVersionsMetadata({
    | 'editUrl'
    | 'editCurrentVersion'
  >;
-}): VersionMetadata[] {
-  const versionNamesUnfiltered = readVersionNames(context.siteDir, options);
+}): Promise<VersionMetadata[]> {
+  const versionNamesUnfiltered = await readVersionNames(
+    context.siteDir,
+    options,
+  );

  checkVersionsOptions(versionNamesUnfiltered, options);