refactor: minify api.json by shortening keys (#9971)

* refactor: minify api.json by shortening keys * fix: links to other packages * refactor: get doclink from canonicalReference, not model * fix: types * fix: again * fix: @link tags with alt texts
2026-03-09 16:13:31 +01:00 · 2023-11-17 23:26:48 +01:00
parent 9868772b64
commit 492f86af39
13 changed files with 239 additions and 61 deletions
--- a/apps/website/src/components/ExcerptText.tsx
+++ b/apps/website/src/components/ExcerptText.tsx
@@ -1,26 +1,22 @@
-import type { ApiModel, Excerpt } from '@discordjs/api-extractor-model';
+import type { Excerpt } from '@discordjs/api-extractor-model';
 import { ExcerptTokenKind } from '@discordjs/api-extractor-model';
 import { BuiltinDocumentationLinks } from '~/util/builtinDocumentationLinks';
 import { DISCORD_API_TYPES_DOCS_URL } from '~/util/constants';
 import { DocumentationLink } from './DocumentationLink';
 import { ItemLink } from './ItemLink';
-import { resolveItemURI } from './documentation/util';
+import { resolveCanonicalReference, resolveItemURI } from './documentation/util';

 export interface ExcerptTextProps {
 	/**
 	 * The tokens to render.
 	 */
 	readonly excerpt: Excerpt;
-	/**
-	 * The model to resolve item references from.
-	 */
-	readonly model: ApiModel;
 }

 /**
 * A component that renders excerpt tokens from an api item.
 */
-export function ExcerptText({ model, excerpt }: ExcerptTextProps) {
+export function ExcerptText({ excerpt }: ExcerptTextProps) {
 	return (
 		<span>
 			{excerpt.spannedTokens.map((token, idx) => {
@@ -53,20 +49,18 @@ export function ExcerptText({ model, excerpt }: ExcerptTextProps) {
 						);
 					}

-					const item = token.canonicalReference
-						? model.resolveDeclarationReference(token.canonicalReference!, model).resolvedApiItem
-						: null;
+					const resolved = token.canonicalReference ? resolveCanonicalReference(token.canonicalReference) : null;

-					if (!item) {
+					if (!resolved) {
 						return token.text;
 					}

 					return (
 						<ItemLink
 							className="text-blurple"
-							itemURI={resolveItemURI(item)}
-							key={`${item.displayName}-${item.containerKey}-${idx}`}
-							packageName={item.getAssociatedPackage()?.displayName.replace('@discordjs/', '')}
+							itemURI={resolveItemURI(resolved.item)}
+							key={`${resolved.item.displayName}-${resolved.item.containerKey}-${idx}`}
+							packageName={resolved.package}
 						>
 							{token.text}
 						</ItemLink>
--- a/apps/website/src/components/ParameterTable.tsx
+++ b/apps/website/src/components/ParameterTable.tsx
@@ -17,7 +17,7 @@ export function ParameterTable({ item }: { readonly item: ApiDocumentedItem & Ap
 		() =>
 			params.map((param) => ({
 				Name: param.isRest ? `...${param.name}` : param.name,
-				Type: <ExcerptText excerpt={param.parameterTypeExcerpt} model={item.getAssociatedModel()!} />,
+				Type: <ExcerptText excerpt={param.parameterTypeExcerpt} />,
 				Optional: param.isOptional ? 'Yes' : 'No',
 				Description: param.description ? <TSDoc item={item} tsdoc={param.description} /> : 'None',
 			})),
--- a/apps/website/src/components/Property.tsx
+++ b/apps/website/src/components/Property.tsx
@@ -32,9 +32,7 @@ export function Property({
 				>
 					{`${item.displayName}${item.isOptional ? '?' : ''}`}
 					<span>:</span>
-					{item.propertyTypeExcerpt.text ? (
-						<ExcerptText excerpt={item.propertyTypeExcerpt} model={item.getAssociatedModel()!} />
-					) : null}
+					{item.propertyTypeExcerpt.text ? <ExcerptText excerpt={item.propertyTypeExcerpt} /> : null}
 				</CodeHeading>
 			</div>
 			{hasSummary || inheritedFrom ? (
--- a/apps/website/src/components/SignatureText.tsx
+++ b/apps/website/src/components/SignatureText.tsx
@@ -1,10 +1,10 @@
-import type { ApiModel, Excerpt } from '@discordjs/api-extractor-model';
+import type { Excerpt } from '@discordjs/api-extractor-model';
 import { ExcerptText } from './ExcerptText';

-export function SignatureText({ excerpt, model }: { readonly excerpt: Excerpt; readonly model: ApiModel }) {
+export function SignatureText({ excerpt }: { readonly excerpt: Excerpt }) {
 	return (
 		<h4 className="break-all text-lg font-bold font-mono">
-			<ExcerptText excerpt={excerpt} model={model} />
+			<ExcerptText excerpt={excerpt} />
 		</h4>
 	);
 }
--- a/apps/website/src/components/TypeParamTable.tsx
+++ b/apps/website/src/components/TypeParamTable.tsx
@@ -11,21 +11,20 @@ const rowElements = {
 };

 export function TypeParamTable({ item }: { readonly item: ApiTypeParameterListMixin }) {
-	const model = item.getAssociatedModel()!;
 	const rows = useMemo(
 		() =>
 			item.typeParameters.map((typeParam) => ({
 				Name: typeParam.name,
-				Constraints: <ExcerptText excerpt={typeParam.constraintExcerpt} model={model} />,
+				Constraints: <ExcerptText excerpt={typeParam.constraintExcerpt} />,
 				Optional: typeParam.isOptional ? 'Yes' : 'No',
-				Default: <ExcerptText excerpt={typeParam.defaultTypeExcerpt} model={model} />,
+				Default: <ExcerptText excerpt={typeParam.defaultTypeExcerpt} />,
 				Description: typeParam.tsdocTypeParamBlock ? (
 					<TSDoc item={item} tsdoc={typeParam.tsdocTypeParamBlock.content} />
 				) : (
 					'None'
 				),
 			})),
-		[item, model],
+		[item],
 	);

 	return (
--- a/apps/website/src/components/documentation/HierarchyText.tsx
+++ b/apps/website/src/components/documentation/HierarchyText.tsx
@@ -9,8 +9,6 @@ export function HierarchyText({
 	readonly item: ApiClass | ApiInterface;
 	readonly type: 'Extends' | 'Implements';
 }) {
-	const model = item.getAssociatedModel()!;
-
 	if (
 		(item.kind === ApiItemKind.Class &&
 			(item as ApiClass).extendsType === undefined &&
@@ -50,7 +48,7 @@ export function HierarchyText({
 				<div className="flex flex-row place-items-center gap-4" key={`${type}-${idx}`}>
 					<h3 className="text-xl font-bold">{type}</h3>
 					<span className="break-all font-mono space-y-2">
-						<ExcerptText excerpt={excerpt} model={model} />
+						<ExcerptText excerpt={excerpt} />
 					</span>
 				</div>
 			))}
--- a/apps/website/src/components/documentation/util.ts
+++ b/apps/website/src/components/documentation/util.ts
@@ -1,4 +1,4 @@
-import { ApiItemKind } from '@discordjs/api-extractor-model';
+import { ApiItemKind, Meaning } from '@discordjs/api-extractor-model';
 import type {
 	ApiItem,
 	ApiItemContainerMixin,
@@ -10,11 +10,25 @@ import type {
 	ApiParameterListMixin,
 	ApiEvent,
 } from '@discordjs/api-extractor-model';
+import type { DeclarationReference } from '@microsoft/tsdoc/lib-commonjs/beta/DeclarationReference';
 import { METHOD_SEPARATOR, OVERLOAD_SEPARATOR } from '~/util/constants';
 import { resolveMembers } from '~/util/members';
 import { resolveParameters } from '~/util/model';
 import type { TableOfContentsSerialized } from '../TableOfContentItems';

+export type ApiItemLike = {
+	[K in keyof ApiItem]?: K extends 'displayName' | 'kind'
+		? ApiItem[K]
+		: K extends 'parent'
+		  ? ApiItemLike | undefined
+		  : ApiItem[K] | undefined;
+};
+
+interface ResolvedCanonicalReference {
+	item: ApiItemLike;
+	package: string;
+}
+
 export function hasProperties(item: ApiItemContainerMixin) {
 	return resolveMembers(item, memberPredicate).some(
 		({ item: member }) => member.kind === ApiItemKind.Property || member.kind === ApiItemKind.PropertySignature,
@@ -31,12 +45,65 @@ export function hasEvents(item: ApiItemContainerMixin) {
 	return resolveMembers(item, memberPredicate).some(({ item: member }) => member.kind === ApiItemKind.Event);
 }

-export function resolveItemURI(item: ApiItem): string {
+export function resolveItemURI(item: ApiItemLike): string {
 	return !item.parent || item.parent.kind === ApiItemKind.EntryPoint
 		? `${item.displayName}${OVERLOAD_SEPARATOR}${item.kind}`
 		: `${item.parent.displayName}${OVERLOAD_SEPARATOR}${item.parent.kind}${METHOD_SEPARATOR}${item.displayName}`;
 }

+export function resolveCanonicalReference(canonicalReference: DeclarationReference): ResolvedCanonicalReference | null {
+	if (
+		canonicalReference.source &&
+		'packageName' in canonicalReference.source &&
+		canonicalReference.symbol?.componentPath &&
+		canonicalReference.symbol.meaning
+	)
+		return {
+			package: canonicalReference.source.unscopedPackageName,
+			item: {
+				kind: mapMeaningToKind(canonicalReference.symbol.meaning as unknown as Meaning),
+				displayName: canonicalReference.symbol.componentPath.component.toString(),
+				containerKey: `|${
+					canonicalReference.symbol.meaning
+				}|${canonicalReference.symbol.componentPath.component.toString()}`,
+			},
+		};
+	return null;
+}
+
+function mapMeaningToKind(meaning: Meaning): ApiItemKind {
+	switch (meaning) {
+		case Meaning.CallSignature:
+			return ApiItemKind.CallSignature;
+		case Meaning.Class:
+			return ApiItemKind.Class;
+		case Meaning.ComplexType:
+			throw new Error('Not a valid canonicalReference: Meaning.ComplexType');
+		case Meaning.ConstructSignature:
+			return ApiItemKind.ConstructSignature;
+		case Meaning.Constructor:
+			return ApiItemKind.Constructor;
+		case Meaning.Enum:
+			return ApiItemKind.Enum;
+		case Meaning.Event:
+			return ApiItemKind.Event;
+		case Meaning.Function:
+			return ApiItemKind.Function;
+		case Meaning.IndexSignature:
+			return ApiItemKind.IndexSignature;
+		case Meaning.Interface:
+			return ApiItemKind.Interface;
+		case Meaning.Member:
+			return ApiItemKind.Property;
+		case Meaning.Namespace:
+			return ApiItemKind.Namespace;
+		case Meaning.TypeAlias:
+			return ApiItemKind.TypeAlias;
+		case Meaning.Variable:
+			return ApiItemKind.Variable;
+	}
+}
+
 export function memberPredicate(
 	item: ApiItem,
 ): item is ApiEvent | ApiMethod | ApiMethodSignature | ApiProperty | ApiPropertySignature {
--- a/apps/website/src/components/model/enum/EnumMember.tsx
+++ b/apps/website/src/components/model/enum/EnumMember.tsx
@@ -14,9 +14,7 @@ export function EnumMember({ member }: { readonly member: ApiEnumMember }) {
 			>
 				{member.name}
 				<span>=</span>
-				{member.initializerExcerpt ? (
-					<SignatureText excerpt={member.initializerExcerpt} model={member.getAssociatedModel()!} />
-				) : null}
+				{member.initializerExcerpt ? <SignatureText excerpt={member.initializerExcerpt} /> : null}
 			</CodeHeading>
 			{member.tsdocComment ? <TSDoc item={member} tsdoc={member.tsdocComment.summarySection} /> : null}
 		</div>
--- a/apps/website/src/components/model/method/MethodHeader.tsx
+++ b/apps/website/src/components/model/method/MethodHeader.tsx
@@ -22,7 +22,7 @@ export function MethodHeader({ method }: { readonly method: ApiMethod | ApiMetho
 				>
 					{`${method.name}(${parametersString(method)})`}
 					<span>:</span>
-					<ExcerptText excerpt={method.returnTypeExcerpt} model={method.getAssociatedModel()!} />
+					<ExcerptText excerpt={method.returnTypeExcerpt} />
 				</CodeHeading>
 			</div>
 		</div>
--- a/apps/website/src/util/addPackageToModel.ts
+++ b/apps/website/src/util/addPackageToModel.ts
@@ -1,25 +1,8 @@
-import type { ApiModel, ApiPackage } from '@discordjs/api-extractor-model';
-import { ApiItem } from '@discordjs/api-extractor-model';
-import { TSDocConfiguration } from '@microsoft/tsdoc';
-import { TSDocConfigFile } from '@microsoft/tsdoc-config';
+import { ApiPackage } from '@discordjs/api-extractor-model';
+import type { ApiModel } from '@discordjs/api-extractor-model';

 export const addPackageToModel = (model: ApiModel, data: any) => {
-	let apiPackage: ApiPackage;
-	if (data.metadata) {
-		const tsdocConfiguration = new TSDocConfiguration();
-		const tsdocConfigFile = TSDocConfigFile.loadFromObject(data.metadata.tsdocConfig);
-		tsdocConfigFile.configureParser(tsdocConfiguration);
-
-		apiPackage = ApiItem.deserialize(data, {
-			apiJsonFilename: '',
-			toolPackage: data.metadata.toolPackage,
-			toolVersion: data.metadata.toolVersion,
-			versionToDeserialize: data.metadata.schemaVersion,
-			tsdocConfiguration,
-		}) as ApiPackage;
-	} else {
-		apiPackage = ApiItem.deserializeDocgen(data, 'discord.js') as ApiPackage;
-	}
+	const apiPackage = ApiPackage.loadFromJson(data);

 	model.addMember(apiPackage);
 	return model;