ref(platforms): Improve implementation of platformRegistry (getsentry#7505)

This change simplfies the PlatformRegistry

Author: evanpurkhiser

bin/lint-docs.ts

@@ -5,7 +5,7 @@
 
 import fs from 'fs';
 
-import PlatformRegistry from '../src/shared/platformRegistry';
+import {buildPlatformRegistry} from '../src/shared/platformRegistry';
 
 enum Level {
   error,
@@ -45,11 +45,10 @@ const testConfig = config => {
 };
 
 const main = async () => {
-  const platformRegistry = new PlatformRegistry();
-  await platformRegistry.init();
+  const {platforms} = await buildPlatformRegistry();
 
   const violations: Violation[] = [];
-  platformRegistry.platforms.forEach(platform => {
+  platforms.forEach(platform => {
     // test for wizard
     testConfig(platform).forEach(violation => {
       violations.push({...violation, context: platform.key});

src/components/__tests__/__snapshots__/configKey.test.js.snap

@@ -19,6 +19,8 @@ exports[`ConfigKey renders correctly 1`] = `
       />
     </svg>
   </a>
-  <code />
+  <code>
+    my_option_name
+  </code>
 </h3>
 `;

src/components/guideGrid.tsx

@@ -1,7 +1,7 @@
 import React from 'react';
 import {PlatformIcon} from 'platformicons';
 
-import {Platform, usePlatform} from './hooks/usePlatform';
+import {usePlatform} from './hooks/usePlatform';
 import {SmartLink} from './smartLink';
 
 type Props = {
@@ -11,14 +11,14 @@ type Props = {
 
 export function GuideGrid({platform, className}: Props) {
   const [currentPlatform] = usePlatform(platform);
-  // platform might actually not be a platform, so lets handle that case gracefully
-  if (!(currentPlatform as Platform).guides) {
+
+  if (currentPlatform.type === 'guide') {
     return null;
   }
 
   return (
     <ul className={className}>
-      {(currentPlatform as Platform).guides.map(guide => (
+      {currentPlatform.guides.map(guide => (
         <li key={guide.key}>
           <SmartLink to={guide.url}>
             <PlatformIcon

src/components/hooks/usePlatform.tsx

@@ -4,6 +4,7 @@ import {graphql, navigate, useStaticQuery} from 'gatsby';
 import {parse} from 'query-string';
 
 import {PageContext} from 'sentry-docs/components/pageContext';
+import {Platform, PlatformGuide} from 'sentry-docs/types';
 
 import {useLocalStorage} from './useLocalStorage';
 
@@ -34,62 +35,6 @@ const query = graphql`
   }
 `;
 
-export const formatCaseStyle = (style: string, value: string): string => {
-  switch (style) {
-    case 'snake_case':
-      return value.replace(/-/g, '_');
-    case 'camelCase':
-      return value
-        .split(/-/g)
-        .map((val, idx) =>
-          idx === 0 ? val : val.charAt(0).toUpperCase() + val.substring(1)
-        )
-        .join('');
-    case 'PascalCase':
-      return value
-        .split(/-/g)
-        .map(val => val.charAt(0).toUpperCase() + val.substring(1))
-        .join('');
-    default:
-      return value;
-  }
-};
-
-// export enum CaseStyle {
-//   canonical,
-//   camelCase,
-//   PascalCase,
-//   snake_case,
-// }
-
-// export enum SupportLevel {
-//   production,
-//   community,
-// }
-
-export type Guide = {
-  caseStyle: string;
-  fallbackPlatform: string;
-  key: string;
-  name: string;
-  sdk: string;
-  supportLevel: string;
-  title: string;
-  url: string;
-};
-
-export type Platform = {
-  caseStyle: string;
-  key: string;
-  name: string;
-  sdk: string;
-  supportLevel: string;
-  title: string;
-  url: string;
-  fallbackPlatform?: string;
-  guides?: Guide[];
-};
-
 export const DEFAULT_PLATFORM = 'javascript';
 
 const normalizeSlug = (name: string): string => {
@@ -161,8 +106,9 @@ const rebuildPathForPlatform = (key: string, currentPath?: string): string => {
 export const usePlatformList = (): Platform[] => {
   const {
     allPlatform: {nodes: platformList},
-  } = useStaticQuery(query);
-  return platformList.sort((a: Platform, b: Platform) => {
+  } = useStaticQuery<{allPlatform: {nodes: Platform[]}}>(query);
+
+  return platformList.sort((a, b) => {
     // Exclude leading non-alphanumeric characters to order .NET between Native and NodeJS instead of the beginning.
     const skippedPrefix = /^[^a-zA-Z]+/;
     return a.title
@@ -176,7 +122,7 @@ export const usePlatformList = (): Platform[] => {
 
  * @param value platform key in format of `platformName[.guideName]`
  */
-export const getPlatform = (key: string): Platform | Guide | null => {
+export const getPlatform = (key: string): Platform | PlatformGuide | null => {
   // XXX(epurkhiser): This is almost certinally a mistake, we should figure out
   // if `getPlatforms` should actually be something more like `useGetPlatforms`
   // or something
@@ -191,14 +137,13 @@ export const getPlatform = (key: string): Platform | Guide | null => {
   const [platformName, guideName] = key.split('.', 2);
   const activePlatform = platformList.find((p: Platform) => p.key === platformName);
   const activeGuide =
-    activePlatform &&
-    (activePlatform as Platform).guides.find((g: Guide) => g.name === guideName);
+    activePlatform && activePlatform.guides.find(g => g.name === guideName);
 
   return activeGuide ?? activePlatform ?? null;
 };
 
 type UsePlatform = [
-  Platform | Guide | null,
+  Platform | PlatformGuide | null,
   (value: string, options?: SetPlatformOptions) => void,
   boolean
 ];
@@ -207,7 +152,9 @@ type SetPlatformOptions = {
   noQueryString?: boolean;
 };
 
-export const getPlatformsWithFallback = (platform: Platform | Guide): string[] => {
+export const getPlatformsWithFallback = (
+  platform: Platform | PlatformGuide
+): string[] => {
   const result = [platform.key];
   let curPlatform = platform;
   while (curPlatform.fallbackPlatform) {
@@ -258,7 +205,7 @@ export function usePlatform(
 
   const [stateValue, setStateValue] = useState(currentValue);
 
-  const setValue = (newValue: string, options: SetPlatformOptions = {}) => {
+  const setPlatform = (newValue: string, options: SetPlatformOptions = {}) => {
     if (newValue === currentValue) {
       return;
     }
@@ -276,8 +223,8 @@ export function usePlatform(
     setStateValue(newValue);
   };
 
-  const activeValue: Platform | Guide | null =
+  const activePlatform: Platform | PlatformGuide | null =
     getPlatform(stateValue) ?? (useDefault ? getPlatform(defaultValue) : null);
 
-  return [activeValue, setValue, isFixed];
+  return [activePlatform, setPlatform, isFixed];
 }

src/components/platformContent.tsx

@@ -1,12 +1,9 @@
 import React, {Fragment, useState} from 'react';
 import {graphql, useStaticQuery} from 'gatsby';
 
-import {
-  getPlatform,
-  getPlatformsWithFallback,
-  Platform,
-  usePlatform,
-} from './hooks/usePlatform';
+import {Platform, PlatformGuide} from 'sentry-docs/types';
+
+import {getPlatform, getPlatformsWithFallback, usePlatform} from './hooks/usePlatform';
 import {Content} from './content';
 import {SmartLink} from './smartLink';
 
@@ -53,7 +50,7 @@ type Props = {
 
 const getFileForPlatform = (
   fileList: FileNode[],
-  platform: Platform
+  platform: Platform | PlatformGuide
 ): FileNode | null => {
   const platformsToSearch = getPlatformsWithFallback(platform);
   platformsToSearch.push('_default');

src/components/platformIdentifier.tsx

@@ -1,12 +1,35 @@
 import React from 'react';
 
-import {formatCaseStyle, usePlatform} from './hooks/usePlatform';
+import {PlatformCaseStyle} from 'sentry-docs/types';
+
+import {usePlatform} from './hooks/usePlatform';
 
 type Props = {
   name: string;
   platform?: string;
 };
 
+function formatCaseStyle(style: PlatformCaseStyle | undefined, value: string) {
+  switch (style) {
+    case 'snake_case':
+      return value.replace(/-/g, '_');
+    case 'camelCase':
+      return value
+        .split(/-/g)
+        .map((val, idx) =>
+          idx === 0 ? val : val.charAt(0).toUpperCase() + val.substring(1)
+        )
+        .join('');
+    case 'PascalCase':
+      return value
+        .split(/-/g)
+        .map(val => val.charAt(0).toUpperCase() + val.substring(1))
+        .join('');
+    default:
+      return value;
+  }
+}
+
 export function PlatformIdentifier({name, platform}: Props) {
   const [currentPlatform] = usePlatform(platform);
 

src/components/platformLinkWithLogo.tsx

@@ -1,7 +1,7 @@
 import React from 'react';
 import {PlatformIcon} from 'platformicons';
 
-import {Platform, usePlatform} from './hooks/usePlatform';
+import {usePlatform} from './hooks/usePlatform';
 import {SmartLink} from './smartLink';
 
 type Props = {
@@ -12,17 +12,11 @@ type Props = {
 
 export function PlatformLinkWithLogo({platform, label, url}: Props) {
   const [currentPlatform] = usePlatform(platform);
-  let linkText = currentPlatform.title;
 
-  // platform might actually not be a platform, so lets handle that case gracefully
-  if (!(currentPlatform as Platform).guides) {
+  if (currentPlatform.type !== 'platform') {
     return null;
   }
 
-  if (label) {
-    linkText = label;
-  }
-
   return (
     <SmartLink to={url}>
       <PlatformIcon
@@ -36,7 +30,7 @@ export function PlatformLinkWithLogo({platform, label, url}: Props) {
         }}
         format="sm"
       />
-      {linkText}
+      {label ?? currentPlatform.title}
     </SmartLink>
   );
 }

src/components/platformSection.tsx

@@ -1,6 +1,6 @@
 import React, {Fragment} from 'react';
 
-import {getPlatformsWithFallback, Platform, usePlatform} from './hooks/usePlatform';
+import {getPlatformsWithFallback, usePlatform} from './hooks/usePlatform';
 
 type Props = {
   children?: React.ReactNode;
@@ -37,7 +37,7 @@ export function PlatformSection({
     return null;
   }
 
-  if (noGuides && !(currentPlatform as Platform).guides) {
+  if (noGuides && currentPlatform.type !== 'platform') {
     return null;
   }
 

src/gatsby/createPages/createPlatformPages.ts

@@ -6,7 +6,8 @@ import nodePath from 'path';
 import {GatsbyNode, Node} from 'gatsby';
 import {createFilePath} from 'gatsby-source-filesystem';
 
-import PlatformRegistry, {Guide, Platform} from '../../shared/platformRegistry';
+import {buildPlatformRegistry} from '../../shared/platformRegistry';
+import {Platform, PlatformGuide} from '../../types';
 import {getChild, getDataOrPanic} from '../helpers';
 
 type CreatePageArgs = Parameters<GatsbyNode['createPages']>[0];
@@ -221,9 +222,6 @@ export const createPlatformPages = async ({
     reporter
   );
 
-  const platformRegistry = new PlatformRegistry();
-  await platformRegistry.init();
-
   // filter out nodes with no markdown content
   const {common, platforms} = buildPlatformPages(
     nodes.filter((n: FileNode) => getChild(n))
@@ -362,7 +360,7 @@ export const createPlatformPages = async ({
   const createPlatformGuidePages = (
     platform: Platform,
     platformData,
-    guide: Guide,
+    guide: PlatformGuide,
     guideData,
     sharedCommon: FileNode[],
     sharedContext: {[key: string]: any}
@@ -454,7 +452,9 @@ export const createPlatformPages = async ({
     });
   };
 
-  platformRegistry.platforms.forEach(platform => {
+  const registry = await buildPlatformRegistry();
+
+  registry.platforms.forEach(platform => {
     makePlatformPage(platform, platforms[platform.name], common);
   });
 

src/gatsby/onPostBuild.ts

@@ -6,7 +6,7 @@ import fs from 'fs';
 
 import jsdom from 'jsdom';
 
-import PlatformRegistry from '../shared/platformRegistry';
+import {buildPlatformRegistry, PlatformRegistry} from '../shared/platformRegistry';
 
 const rmDirSync = (dirPath: string) => {
   let files;
@@ -59,9 +59,6 @@ export default async function onPostBuild({graphql}) {
     }
   );
 
-  const platformRegistry = new PlatformRegistry();
-  await platformRegistry.init();
-
   const nodes = results.data.allFile.edges.map(e => e.node.childMarkdownRemark);
   if (!nodes.length) {
     const msg = 'No platform data found for wizard!';
@@ -73,6 +70,8 @@ export default async function onPostBuild({graphql}) {
     return;
   }
 
+  const platformRegistry = await buildPlatformRegistry();
+
   await writeJson(output, nodes, platformRegistry);
 }
 
@@ -160,7 +159,7 @@ const writeJson = (path: string, nodes, platformRegistry: PlatformRegistry) => {
       categories: [],
     };
 
-    const platform = platformRegistry.get(key);
+    const platform = platformRegistry.platformGuideMapping[key];
     if (platform) {
       data.name = platform.title;
       data.aliases = platform.aliases || [];