feat: mainlib docs on new website (#9930)

* fix(ExceptText): don't display import("d..-types/v10"). in return type

* Squashed 'packages/api-extractor-model/' content from commit 39ecb196c

git-subtree-dir: packages/api-extractor-model
git-subtree-split: 39ecb196ca210bdf84ba6c9cadb1bb93571849d7

* Squashed 'packages/api-extractor/' content from commit 341ad6c51

git-subtree-dir: packages/api-extractor
git-subtree-split: 341ad6c51b01656d4f73b74ad4bdb3095f9262c4

* feat(api-extractor): add api-extractor and -model

* fix: package.json docs script

* fix(SourcLink): use <> instead of function syntax

* fix: make packages private

* fix: rest params showing in docs, added labels

* fix: missed two files

* feat: merge docs.json from docgen and docs.api.json

* fix: cpy-cli & pnpm-lock

* fix: increase icon size

* fix: icon size again

* feat: run both docs on mainlib

* chore: website fixes

* fix: more website fixes

* fix: tests and dev database script

* chore: comment out old docs

* fix: increase max fetch cache

* fix: env should always be a string

* fix: try to reapply patches

* fix: remove prepare for docgen

* fix: temporary cosmetic fixes

* fix: horizontal scroll

* feat: generate index for new docs

---------

Co-authored-by: Noel <buechler.noel@outlook.com>

.github/workflows/documentation.yml

@@ -88,6 +88,7 @@ jobs:
           mkdir -p "out/${PACKAGE}"
           if [[ "${PACKAGE}" == "discord.js" ]]; then
             mv "packages/${PACKAGE}/docs/docs.json" "out/${PACKAGE}/${SEMVER}.json"
+            mv "packages/${PACKAGE}/docs/docs.api.json" "out/${PACKAGE}/${SEMVER}.api.json"
           else
             mv "packages/${PACKAGE}/docs/docs.api.json" "out/${PACKAGE}/${SEMVER}.api.json"
           fi
@@ -106,6 +107,7 @@ jobs:
             if [[ "${PACKAGE}" == "discord.js" ]]; then
               mkdir -p "out/${PACKAGE}"
               mv "packages/${PACKAGE}/docs/docs.json" "out/${PACKAGE}/${GITHUB_REF_NAME}.json"
+              mv "packages/${PACKAGE}/docs/docs.api.json" "out/${PACKAGE}/${GITHUB_REF_NAME}.api.json"
             else
               mkdir -p "out/${PACKAGE}"
               mv "packages/${PACKAGE}/docs/docs.api.json" "out/${PACKAGE}/${GITHUB_REF_NAME}.api.json"

apps/guide/package.json

@@ -54,7 +54,7 @@
 		"ariakit": "2.0.0-next.44",
 		"cmdk": "^0.2.0",
 		"contentlayer": "^0.3.4",
-		"next": "^14.0.2-canary.14",
+		"next": "14.0.2-canary.20",
 		"next-contentlayer": "^0.3.4",
 		"next-themes": "^0.2.1",
 		"react": "^18.2.0",
@@ -66,7 +66,7 @@
 		"sharp": "^0.32.6"
 	},
 	"devDependencies": {
-		"@next/bundle-analyzer": "^14.0.1",
+		"@next/bundle-analyzer": "14.0.2-canary.20",
 		"@testing-library/react": "^14.0.0",
 		"@testing-library/user-event": "^14.5.1",
 		"@types/html-escaper": "^3.0.1",

apps/guide/src/util/constants.ts

@@ -26,7 +26,7 @@ export const PACKAGES = [
 /**
  * The stable version of discord.js.
  */
-export const VERSION = '14.11.0' as const;
+export const VERSION = '14.13.0' as const;
 
 /**
  * The API version (for discord-api-types). This is prefixed with a "v".

apps/website/next.config.js

@@ -16,6 +16,9 @@ export default withBundleAnalyzer({
 		contentSecurityPolicy: "default-src 'self'; frame-src 'none'; sandbox;",
 	},
 	poweredByHeader: false,
+	env: {
+		MAX_FETCH_SIZE: '5',
+	},
 	async redirects() {
 		return [
 			{

apps/website/package.json

@@ -63,7 +63,7 @@
 		"class-variance-authority": "^0.7.0",
 		"cmdk": "^0.2.0",
 		"meilisearch": "^0.35.0",
-		"next": "^14.0.2-canary.14",
+		"next": "14.0.2-canary.20",
 		"next-mdx-remote": "^4.4.1",
 		"next-themes": "^0.2.1",
 		"react": "^18.2.0",
@@ -75,7 +75,7 @@
 		"sharp": "^0.32.6"
 	},
 	"devDependencies": {
-		"@next/bundle-analyzer": "^14.0.1",
+		"@next/bundle-analyzer": "14.0.2-canary.20",
 		"@testing-library/react": "^14.0.0",
 		"@testing-library/user-event": "^14.5.1",
 		"@types/node": "18.18.8",

apps/website/scripts/generateAllIndices.js

@@ -1,5 +1,15 @@
+import { readFile } from 'node:fs/promises';
 import { generateAllIndices } from '@discordjs/scripts';
 
 console.log('Generating all indices...');
-await generateAllIndices();
+await generateAllIndices({
+	fetchPackageVersions: async (pkg) => {
+		console.log(`Fetching versions for ${pkg}...`);
+		return ['main'];
+	},
+	fetchPackageVersionDocs: async (pkg, version) => {
+		console.log(`Fetching data for ${pkg} ${version}...`);
+		return JSON.parse(await readFile(`${process.cwd()}/../../packages/${pkg}/docs/docs.api.json`, 'utf8'));
+	},
+});
 console.log('Generated all indices.');

apps/website/src/app/docAPI.ts

@@ -23,7 +23,7 @@ export async function fetchVersions(packageName: string): Promise<string[]> {
 	return rows.map((row) => row.version);
 }
 
-export async function fetchModelJSON(packageName: string, version: string): Promise<unknown> {
+export async function fetchModelJSON(packageName: string, version: string): Promise<unknown | null> {
 	if (process.env.NEXT_PUBLIC_LOCAL_DEV) {
 		const res = await readFile(
 			join(process.cwd(), '..', '..', 'packages', packageName, 'docs', 'docs.api.json'),

apps/website/src/app/docs/packages/[package]/[version]/[item]/page.tsx

@@ -32,9 +32,15 @@ import { findMember } from '~/util/model';
 
 async function fetchHeadMember({ package: packageName, version, item }: ItemRouteParams) {
 	const modelJSON = await fetchModelJSON(packageName, version);
+
+	if (!modelJSON) {
+		return undefined;
+	}
+
 	const model = addPackageToModel(new ApiModel(), modelJSON);
 	const pkg = model.tryGetPackageByName(packageName);
 	const entry = pkg?.entryPoints[0];
+
 	if (!entry) {
 		return undefined;
 	}
@@ -88,7 +94,11 @@ export async function generateMetadata({ params }: { params: ItemRouteParams })
 	const searchParams = resolveMemberSearchParams(params.package, member);
 	url.search = searchParams.toString();
 	const ogImage = url.toString();
-	const description = tryResolveSummaryText(member as ApiDeclaredItem);
+	let description;
+
+	if (member) {
+		description = tryResolveSummaryText(member as ApiDeclaredItem);
+	}
 
 	return {
 		title: name,

apps/website/src/app/docs/packages/[package]/[version]/layout.tsx

@@ -4,7 +4,7 @@ import dynamic from 'next/dynamic';
 import { notFound } from 'next/navigation';
 import type { PropsWithChildren } from 'react';
 import { fetchModelJSON, fetchVersions } from '~/app/docAPI';
-import { Banner } from '~/components/Banner';
+// import { Banner } from '~/components/Banner';
 import { CmdKDialog } from '~/components/CmdK';
 import { Nav } from '~/components/Nav';
 import type { SidebarSectionItemData } from '~/components/Sidebar';
@@ -46,6 +46,11 @@ function serializeIntoSidebarItemData(item: ApiItem): SidebarSectionItemData {
 
 export default async function PackageLayout({ children, params }: PropsWithChildren<{ params: VersionRouteParams }>) {
 	const modelJSON = await fetchModelJSON(params.package, params.version);
+
+	if (!modelJSON) {
+		notFound();
+	}
+
 	const model = addPackageToModel(new ApiModel(), modelJSON);
 
 	const pkg = model.tryGetPackageByName(params.package);
@@ -72,7 +77,7 @@ export default async function PackageLayout({ children, params }: PropsWithChild
 
 	return (
 		<Providers>
-			<Banner className="mb-6" />
+			{/* <Banner className="mb-6" /> */}
 			<main className="mx-auto max-w-7xl px-4 lg:max-w-full">
 				<Header />
 				<div className="relative top-2.5 mx-auto max-w-7xl gap-6 lg:max-w-full lg:flex">

apps/website/src/app/docs/packages/[package]/page.tsx

@@ -7,22 +7,12 @@ import { fetchVersions } from '~/app/docAPI';
 import { buttonVariants } from '~/styles/Button';
 import { PACKAGES } from '~/util/constants';
 
-async function getData(pkg: string) {
+export default async function Page({ params }: { params: { package: string } }) {
-	if (!PACKAGES.includes(pkg)) {
+	if (!PACKAGES.includes(params.package)) {
 		notFound();
 	}
 
-	const data = await fetchVersions(pkg);
+	const data = await fetchVersions(params.package);
-
-	if (!data.length) {
-		throw new Error('Failed to fetch data');
-	}
-
-	return data;
-}
-
-export default async function Page({ params }: { params: { package: string } }) {
-	const data = await getData(params.package);
 
 	return (
 		<div className="mx-auto min-h-screen min-w-xs flex flex-col gap-8 px-4 py-6 sm:w-md lg:px-6 lg:py-6">

apps/website/src/app/docs/packages/page.tsx

@@ -11,7 +11,7 @@ export default function Page() {
 		<div className="mx-auto min-h-screen min-w-xs flex flex-col gap-8 px-4 py-6 sm:w-md lg:px-6 lg:py-6">
 			<h1 className="text-2xl font-semibold">Select a package:</h1>
 			<div className="flex flex-col gap-4">
-				<a className={buttonVariants({ variant: 'secondary' })} href="https://old.discordjs.dev/#/docs/discord.js">
+				{/* <a className={buttonVariants({ variant: 'secondary' })} href="https://old.discordjs.dev/#/docs/discord.js">
 					<div className="flex grow flex-row place-content-between place-items-center gap-4">
 						<div className="flex flex-row place-content-between place-items-center gap-4">
 							<VscPackage size={25} />
@@ -19,7 +19,7 @@ export default function Page() {
 						</div>
 						<VscArrowRight size={20} />
 					</div>
-				</a>
+				</a> */}
 				{PACKAGES.map((pkg, idx) => (
 					<Link
 						className={buttonVariants({ variant: 'secondary' })}

apps/website/src/app/page.tsx

@@ -4,7 +4,7 @@ import Image from 'next/image';
 import Link from 'next/link';
 import vercelLogo from '~/assets/powered-by-vercel.svg';
 import workersLogo from '~/assets/powered-by-workers.png';
-import { Banner } from '~/components/Banner';
+// import { Banner } from '~/components/Banner';
 import { InstallButton } from '~/components/InstallButton';
 import { buttonVariants } from '~/styles/Button';
 import { DESCRIPTION } from '~/util/constants';
@@ -12,7 +12,7 @@ import { DESCRIPTION } from '~/util/constants';
 export default function Page() {
 	return (
 		<div className="min-h-screen">
-			<Banner />
+			{/* <Banner /> */}
 			<div className="mx-auto max-w-6xl flex flex-col place-items-center gap-24 px-8 pb-16 pt-12 lg:min-h-[calc(100vh_-_40px)] lg:place-content-center lg:py-10">
 				<div className="flex flex-col place-items-center gap-10 lg:flex-row lg:gap-6">
 					<div className="flex flex-col place-items-center gap-10 text-center">
@@ -22,11 +22,11 @@ export default function Page() {
 						</h1>
 						<p className="my-6 leading-normal text-neutral-700 dark:text-neutral-300">{DESCRIPTION}</p>
 						<div className="flex flex-wrap place-content-center gap-4 md:flex-row">
-							<a className={buttonVariants()} href="https://old.discordjs.dev/#/docs" rel="noopener noreferrer">
+							{/* <a className={buttonVariants()} href="https://old.discordjs.dev/#/docs" rel="noopener noreferrer">
 								Docs
-							</a>
+							</a> */}
 							<Link className={buttonVariants()} href={'/docs' as Route}>
-								Module docs
+								Docs
 							</Link>
 							<a
 								className={buttonVariants({ variant: 'secondary' })}

apps/website/src/components/ExcerptText.tsx

@@ -22,6 +22,8 @@ export function ExcerptText({ model, excerpt }: ExcerptTextProps) {
 	return (
 		<span>
 			{excerpt.spannedTokens.map((token, idx) => {
+				// TODO: Real fix in api-extractor needed
+				const text = token.text.replaceAll('\n', '').replaceAll(/\s{2}$/g, '');
 				if (token.kind === ExcerptTokenKind.Reference) {
 					const source = token.canonicalReference?.source;
 					const symbol = token.canonicalReference?.symbol;
@@ -32,12 +34,12 @@ export function ExcerptText({ model, excerpt }: ExcerptTextProps) {
 						// dapi-types doesn't have routes for class members
 						// so we can assume this member is for an enum
 						if (meaning === 'member' && path && 'parent' in path) href += `/enum/${path.parent}#${path.component}`;
-						else if (meaning === 'type') href += `#${token.text}`;
+						else if (meaning === 'type') href += `#${text}`;
-						else href += `/${meaning}/${token.text}`;
+						else href += `/${meaning}/${text}`;
 
 						return (
 							<a className="text-blurple" href={href} key={idx} rel="external noreferrer noopener" target="_blank">
-								{token.text}
+								{text}
 							</a>
 						);
 					}
@@ -45,7 +47,7 @@ export function ExcerptText({ model, excerpt }: ExcerptTextProps) {
 					const item = model.resolveDeclarationReference(token.canonicalReference!, model).resolvedApiItem;
 
 					if (!item) {
-						return token.text;
+						return text;
 					}
 
 					return (
@@ -55,12 +57,12 @@ export function ExcerptText({ model, excerpt }: ExcerptTextProps) {
 							key={`${item.displayName}-${item.containerKey}-${idx}`}
 							packageName={item.getAssociatedPackage()?.displayName.replace('@discordjs/', '')}
 						>
-							{token.text}
+							{text}
 						</ItemLink>
 					);
 				}
 
-				return token.text.replace(/import\("discord-api-types(?:\/v\d+)?"\)\./, '');
+				return text.replace(/import\("discord-api-types(?:\/v\d+)?"\)\./, '');
 			})}
 		</span>
 	);

apps/website/src/components/PackageSelect.tsx

@@ -15,18 +15,18 @@ export default function PackageSelect() {
 	const packageMenu = useMenuState({ gutter: 8, sameWidth: true, fitViewport: true });
 
 	const packageMenuItems = useMemo(
-		() => [
+		() =>
-			<a href="https://old.discordjs.dev/#/docs/discord.js" key="discord.js">
+			// <a href="https://old.discordjs.dev/#/docs/discord.js" key="discord.js">
-				<MenuItem
+			// 	<MenuItem
-					className="my-0.5 rounded bg-white p-3 text-sm outline-none active:bg-light-800 dark:bg-dark-600 hover:bg-light-700 focus:ring focus:ring-width-2 focus:ring-blurple dark:active:bg-dark-400 dark:hover:bg-dark-500"
+			// 		className="my-0.5 rounded bg-white p-3 text-sm outline-none active:bg-light-800 dark:bg-dark-600 hover:bg-light-700 focus:ring focus:ring-width-2 focus:ring-blurple dark:active:bg-dark-400 dark:hover:bg-dark-500"
-					id="discord-js"
+			// 		id="discord-js"
-					onClick={() => packageMenu.setOpen(false)}
+			// 		onClick={() => packageMenu.setOpen(false)}
-					state={packageMenu}
+			// 		state={packageMenu}
-				>
+			// 	>
-					discord.js
+			// 		discord.js
-				</MenuItem>
+			// 	</MenuItem>
-			</a>,
+			// </a>,
-			...PACKAGES.map((pkg, idx) => (
+			PACKAGES.map((pkg, idx) => (
 				<Link href={`/docs/packages/${pkg}/main`} key={`${pkg}-${idx}`}>
 					<MenuItem
 						className="my-0.5 rounded bg-white p-3 text-sm outline-none active:bg-light-800 dark:bg-dark-600 hover:bg-light-700 focus:ring focus:ring-width-2 focus:ring-blurple dark:active:bg-dark-400 dark:hover:bg-dark-500"
@@ -38,7 +38,6 @@ export default function PackageSelect() {
 					</MenuItem>
 				</Link>
 			)),
-		],
 		[packageMenu],
 	);
 

apps/website/src/components/Property.tsx

@@ -38,7 +38,7 @@ export function Property({
 				</CodeHeading>
 			</div>
 			{hasSummary || inheritedFrom ? (
-				<div className="mb-4 flex flex-col gap-4">
+				<div className="mb-4 w-full flex flex-col gap-4">
 					{item.tsdocComment ? <TSDoc item={item} tsdoc={item.tsdocComment} /> : null}
 					{inheritedFrom ? <InheritanceText parent={inheritedFrom} /> : null}
 					{children}

apps/website/src/components/TableOfContentItems.tsx

@@ -1,6 +1,7 @@
 'use client';
 
 import { VscListSelection } from '@react-icons/all-files/vsc/VscListSelection';
+import { VscSymbolEvent } from '@react-icons/all-files/vsc/VscSymbolEvent';
 import { VscSymbolMethod } from '@react-icons/all-files/vsc/VscSymbolMethod';
 import { VscSymbolProperty } from '@react-icons/all-files/vsc/VscSymbolProperty';
 import { useMemo } from 'react';
@@ -16,7 +17,15 @@ export interface TableOfContentsSerializedProperty {
 	name: string;
 }
 
-export type TableOfContentsSerialized = TableOfContentsSerializedMethod | TableOfContentsSerializedProperty;
+export interface TableOfContentsSerializedEvent {
+	kind: 'Event';
+	name: string;
+}
+
+export type TableOfContentsSerialized =
+	| TableOfContentsSerializedEvent
+	| TableOfContentsSerializedMethod
+	| TableOfContentsSerializedProperty;
 
 export interface TableOfContentsItemProps {
 	readonly serializedMembers: TableOfContentsSerialized[];
@@ -57,6 +66,19 @@ export function TableOfContentsMethodItem({ method }: { readonly method: TableOf
 	);
 }
 
+export function TableOfContentsEventItem({ event }: { readonly event: TableOfContentsSerializedEvent }) {
+	return (
+		<a
+			className="ml-[10px] border-l border-light-800 p-[5px] pl-6.5 text-sm outline-none focus:border-0 dark:border-dark-100 focus:rounded active:bg-light-800 hover:bg-light-700 focus:ring focus:ring-width-2 focus:ring-blurple dark:active:bg-dark-100 dark:hover:bg-dark-200"
+			href={`#${event.name}`}
+			key={`${event.name}-${event.kind}`}
+			title={event.name}
+		>
+			<span className="line-clamp-1">{event.name}</span>
+		</a>
+	);
+}
+
 export function TableOfContentItems({ serializedMembers }: TableOfContentsItemProps) {
 	const propertyItems = useMemo(
 		() =>
@@ -85,6 +107,14 @@ export function TableOfContentItems({ serializedMembers }: TableOfContentsItemPr
 		[serializedMembers],
 	);
 
+	const eventItems = useMemo(
+		() =>
+			serializedMembers
+				.filter((member): member is TableOfContentsSerializedEvent => member.kind === 'Event')
+				.map((event, idx) => <TableOfContentsEventItem key={`${event.name}-${event.kind}-${idx}`} event={event} />),
+		[serializedMembers],
+	);
+
 	return (
 		<div className="flex flex-col break-all p-3 pb-8">
 			<div className="ml-2 mt-4 flex flex-row gap-2">
@@ -92,6 +122,17 @@ export function TableOfContentItems({ serializedMembers }: TableOfContentsItemPr
 				<span className="font-semibold">Contents</span>
 			</div>
 			<div className="ml-2 mt-5.5 flex flex-col gap-2">
+				{eventItems.length ? (
+					<div className="flex flex-col">
+						<div className="flex flex-row place-items-center gap-4">
+							<VscSymbolEvent size={20} />
+							<div className="p-3 pl-0">
+								<span className="font-semibold">Properties</span>
+							</div>
+						</div>
+						{eventItems}
+					</div>
+				) : null}
 				{propertyItems.length ? (
 					<div className="flex flex-col">
 						<div className="flex flex-row place-items-center gap-4">

apps/website/src/components/documentation/Members.tsx

@@ -1,11 +1,13 @@
 import type { ApiDeclaredItem, ApiItemContainerMixin } from '@discordjs/api-extractor-model';
+import { EventsSection } from './section/EventsSection';
 import { MethodsSection } from './section/MethodsSection';
 import { PropertiesSection } from './section/PropertiesSection';
-import { hasProperties, hasMethods } from './util';
+import { hasEvents, hasProperties, hasMethods } from './util';
 
 export function Members({ item }: { readonly item: ApiDeclaredItem & ApiItemContainerMixin }) {
 	return (
 		<>
+			{hasEvents(item) ? <EventsSection item={item} /> : null}
 			{hasProperties(item) ? <PropertiesSection item={item} /> : null}
 			{hasMethods(item) ? <MethodsSection item={item} /> : null}
 		</>

apps/website/src/components/documentation/section/EventsSection.tsx

@@ -0,0 +1,42 @@
+import {
+	ApiItemKind,
+	type ApiEvent,
+	type ApiItem,
+	type ApiItemContainerMixin,
+	type ApiDeclaredItem,
+} from '@discordjs/api-extractor-model';
+import { VscSymbolEvent } from '@react-icons/all-files/vsc/VscSymbolEvent';
+import { Fragment, useMemo } from 'react';
+import { Event } from '~/components/model/Event';
+import { resolveMembers } from '~/util/members';
+import { DocumentationSection } from './DocumentationSection';
+
+function isEventLike(item: ApiItem): item is ApiEvent {
+	return item.kind === ApiItemKind.Event;
+}
+
+export function EventsSection({ item }: { readonly item: ApiItemContainerMixin }) {
+	const members = resolveMembers(item, isEventLike);
+
+	const eventItems = useMemo(
+		() =>
+			members.map((event, idx) => {
+				return (
+					<Fragment key={`${event.item.displayName}-${idx}`}>
+						<Event
+							inheritedFrom={event.inherited as ApiDeclaredItem & ApiItemContainerMixin}
+							item={event.item as ApiEvent}
+						/>
+						<div className="border-t-2 border-light-900 dark:border-dark-100" />
+					</Fragment>
+				);
+			}),
+		[members],
+	);
+
+	return (
+		<DocumentationSection icon={<VscSymbolEvent size={20} />} padded title="Events">
+			<div className="flex flex-col gap-4">{eventItems}</div>
+		</DocumentationSection>
+	);
+}

apps/website/src/components/documentation/tsdoc/TSDoc.tsx

@@ -32,7 +32,9 @@ export function TSDoc({ item, tsdoc }: { readonly item: ApiItem; readonly tsdoc:
 					const { codeDestination, urlDestination, linkText } = tsdoc as DocLinkTag;
 
 					if (codeDestination) {
-						const foundItem = item.getAssociatedModel()?.resolveDeclarationReference(codeDestination, item)
+						// TODO: Real fix in api-extractor needed
+						const currentItem = item.getAssociatedPackage();
+						const foundItem = item.getAssociatedModel()?.resolveDeclarationReference(codeDestination, currentItem)
 							.resolvedApiItem;
 
 						if (!foundItem) return null;

apps/website/src/components/documentation/util.ts

@@ -8,6 +8,7 @@ import type {
 	ApiPropertySignature,
 	ApiDocumentedItem,
 	ApiParameterListMixin,
+	ApiEvent,
 } from '@discordjs/api-extractor-model';
 import { METHOD_SEPARATOR, OVERLOAD_SEPARATOR } from '~/util/constants';
 import { resolveMembers } from '~/util/members';
@@ -26,6 +27,10 @@ export function hasMethods(item: ApiItemContainerMixin) {
 	);
 }
 
+export function hasEvents(item: ApiItemContainerMixin) {
+	return resolveMembers(item, memberPredicate).some(({ item: member }) => member.kind === ApiItemKind.Event);
+}
+
 export function resolveItemURI(item: ApiItem): string {
 	return !item.parent || item.parent.kind === ApiItemKind.EntryPoint
 		? `${item.displayName}${OVERLOAD_SEPARATOR}${item.kind}`
@@ -34,12 +39,13 @@ export function resolveItemURI(item: ApiItem): string {
 
 export function memberPredicate(
 	item: ApiItem,
-): item is ApiMethod | ApiMethodSignature | ApiProperty | ApiPropertySignature {
+): item is ApiEvent | ApiMethod | ApiMethodSignature | ApiProperty | ApiPropertySignature {
 	return (
 		item.kind === ApiItemKind.Property ||
 		item.kind === ApiItemKind.PropertySignature ||
 		item.kind === ApiItemKind.Method ||
-		item.kind === ApiItemKind.MethodSignature
+		item.kind === ApiItemKind.MethodSignature ||
+		item.kind === ApiItemKind.Event
 	);
 }
 
@@ -50,6 +56,11 @@ export function serializeMembers(clazz: ApiItemContainerMixin): TableOfContentsS
 				kind: member.kind as 'Method' | 'MethodSignature',
 				name: member.displayName,
 			};
+		} else if (member.kind === 'Event') {
+			return {
+				kind: member.kind as 'Event',
+				name: member.displayName,
+			};
 		} else {
 			return {
 				kind: member.kind as 'Property' | 'PropertySignature',

apps/website/src/components/model/Event.tsx

@@ -0,0 +1,39 @@
+import type { ApiDeclaredItem, ApiItemContainerMixin, ApiEvent } from '@discordjs/api-extractor-model';
+import { Badges } from '../Badges';
+import { CodeHeading } from '../CodeHeading';
+import { InheritanceText } from '../InheritanceText';
+import { ParameterTable } from '../ParameterTable';
+import { TSDoc } from '../documentation/tsdoc/TSDoc';
+import { parametersString } from '../documentation/util';
+
+export function Event({
+	item,
+	inheritedFrom,
+}: {
+	readonly inheritedFrom?: (ApiDeclaredItem & ApiItemContainerMixin) | undefined;
+	readonly item: ApiEvent;
+}) {
+	const hasSummary = Boolean(item.tsdocComment?.summarySection);
+
+	return (
+		<div className="flex flex-col scroll-mt-30 gap-4" id={item.displayName}>
+			<div className="flex flex-col gap-2 md:-ml-9">
+				<Badges item={item} />
+				<CodeHeading
+					href={`#${item.displayName}`}
+					sourceURL={item.sourceLocation.fileUrl}
+					sourceLine={item.sourceLocation.fileLine}
+				>
+					{`${item.name}(${parametersString(item)})`}
+				</CodeHeading>
+			</div>
+			{hasSummary || inheritedFrom ? (
+				<div className="mb-4 w-full flex flex-col gap-4">
+					{item.tsdocComment ? <TSDoc item={item} tsdoc={item.tsdocComment} /> : null}
+					{item.parameters.length ? <ParameterTable item={item} /> : null}
+					{inheritedFrom ? <InheritanceText parent={inheritedFrom} /> : null}
+				</div>
+			) : null}
+		</div>
+	);
+}

apps/website/src/components/model/method/Method.tsx

@@ -1,8 +1,9 @@
-import type {
+import {
-	ApiDeclaredItem,
+	ApiItemKind,
-	ApiItemContainerMixin,
+	type ApiDeclaredItem,
-	ApiMethod,
+	type ApiItemContainerMixin,
-	ApiMethodSignature,
+	type ApiMethod,
+	type ApiMethodSignature,
 } from '@discordjs/api-extractor-model';
 import dynamic from 'next/dynamic';
 import { Fragment } from 'react';
@@ -18,15 +19,23 @@ export function Method({
 	readonly inheritedFrom?: (ApiDeclaredItem & ApiItemContainerMixin) | undefined;
 	readonly method: ApiMethod | ApiMethodSignature;
 }) {
-	if (method.getMergedSiblings().length > 1) {
+	if (
+		method
+			.getMergedSiblings()
+			.filter((sibling) => sibling.kind === ApiItemKind.Method || sibling.kind === ApiItemKind.MethodSignature).length >
+		1
+	) {
 		// We have overloads, use the overload switcher, but render
 		// each overload node on the server.
-		const overloads = method.getMergedSiblings().map((sibling, idx) => (
+		const overloads = method
-			<Fragment key={`${sibling.displayName}-${idx}`}>
+			.getMergedSiblings()
-				<MethodHeader method={sibling as ApiMethod | ApiMethodSignature} />
+			.filter((sibling) => sibling.kind === ApiItemKind.Method || sibling.kind === ApiItemKind.MethodSignature)
-				<MethodDocumentation method={sibling as ApiMethod | ApiMethodSignature} />
+			.map((sibling, idx) => (
-			</Fragment>
+				<Fragment key={`${sibling.displayName}-${idx}`}>
-		));
+					<MethodHeader method={sibling as ApiMethod | ApiMethodSignature} />
+					<MethodDocumentation method={sibling as ApiMethod | ApiMethodSignature} />
+				</Fragment>
+			));
 
 		return <OverloadSwitcher methodName={method.displayName} overloads={overloads} />;
 	}

apps/website/src/components/model/method/MethodDocumentation.tsx

@@ -21,7 +21,7 @@ export function MethodDocumentation({ method, inheritedFrom }: MethodDocumentati
 	}
 
 	return (
-		<div className="mb-4 flex flex-col gap-4">
+		<div className="mb-4 w-full flex flex-col gap-4">
 			{method.tsdocComment ? <TSDoc item={method} tsdoc={method.tsdocComment} /> : null}
 			{method.parameters.length ? <ParameterTable item={method} /> : null}
 			{inheritedFrom && parent ? <InheritanceText parent={inheritedFrom} /> : null}

apps/website/src/components/model/method/MethodHeader.tsx

@@ -12,7 +12,7 @@ export function MethodHeader({ method }: { readonly method: ApiMethod | ApiMetho
 	);
 
 	return (
-		<div className="flex flex-col scroll-mt-30" id={key}>
+		<div className="w-full flex flex-col scroll-mt-30" id={key}>
 			<div className="flex flex-col gap-2 md:-ml-9">
 				<Badges item={method} />
 				<CodeHeading

apps/website/src/middleware.ts

@@ -21,7 +21,7 @@ async function fetchLatestVersion(packageName: string) {
 	]);
 
 	// @ts-expect-error: https://github.com/planetscale/database-js/issues/71
-	return rows[0].data.at(1);
+	return rows.map((row) => row.version).at(1);
 }
 
 export default async function middleware(request: NextRequest) {
@@ -35,9 +35,9 @@ export default async function middleware(request: NextRequest) {
 		} catch {}
 	}
 
-	if (request.nextUrl.pathname.includes('discord.js')) {
+	/* if (request.nextUrl.pathname.includes('discord.js')) {
 		return NextResponse.redirect('https://old.discordjs.dev/#/docs/discord.js');
-	}
+	} */
 
 	if (PACKAGES.some((pkg) => request.nextUrl.pathname.includes(pkg))) {
 		// eslint-disable-next-line prefer-named-capture-group
@@ -52,5 +52,5 @@ export default async function middleware(request: NextRequest) {
 }
 
 export const config = {
-	matcher: ['/docs', '/docs/packages/discord.js(.*)?', '/docs/packages/:package/stable/:member*'],
+	matcher: ['/docs', /* '/docs/packages/discord.js(.*)?',*/ '/docs/packages/:package/stable/:member*'],
 };

apps/website/src/util/addPackageToModel.ts

@@ -4,17 +4,23 @@ import { TSDocConfiguration } from '@microsoft/tsdoc';
 import { TSDocConfigFile } from '@microsoft/tsdoc-config';
 
 export function addPackageToModel(model: ApiModel, data: any) {
-	const tsdocConfiguration = new TSDocConfiguration();
+	let apiPackage: ApiPackage;
-	const tsdocConfigFile = TSDocConfigFile.loadFromObject(data.metadata.tsdocConfig);
+	if (data.metadata) {
-	tsdocConfigFile.configureParser(tsdocConfiguration);
+		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 = ApiItem.deserialize(data, {
-		apiJsonFilename: '',
-		toolPackage: data.metadata.toolPackage,
-		toolVersion: data.metadata.toolVersion,
-		versionToDeserialize: data.metadata.schemaVersion,
-		tsdocConfiguration,
-	}) as ApiPackage;
 	model.addMember(apiPackage);
 	return model;
 }

apps/website/src/util/constants.ts

@@ -1,4 +1,5 @@
 export const PACKAGES = [
+	'discord.js',
 	'brokers',
 	'builders',
 	'collection',

apps/website/src/util/fetchMember.ts

@@ -1,5 +1,4 @@
 import { ApiModel, ApiFunction } from '@discordjs/api-extractor-model';
-import { notFound } from 'next/navigation';
 import { fetchModelJSON } from '~/app/docAPI';
 import { addPackageToModel } from './addPackageToModel';
 import { OVERLOAD_SEPARATOR, PACKAGES } from './constants';
@@ -13,7 +12,7 @@ export interface ItemRouteParams {
 
 export async function fetchMember({ package: packageName, version: branchName = 'main', item }: ItemRouteParams) {
 	if (!PACKAGES.includes(packageName)) {
-		notFound();
+		return null;
 	}
 
 	const model = new ApiModel();
@@ -22,10 +21,19 @@ export async function fetchMember({ package: packageName, version: branchName =
 		const modelJSONFiles = await Promise.all(PACKAGES.map(async (pkg) => fetchModelJSON(pkg, branchName)));
 
 		for (const modelJSONFile of modelJSONFiles) {
+			if (!modelJSONFile) {
+				continue;
+			}
+
 			addPackageToModel(model, modelJSONFile);
 		}
 	} else {
 		const modelJSON = await fetchModelJSON(packageName, branchName);
+
+		if (!modelJSON) {
+			return null;
+		}
+
 		addPackageToModel(model, modelJSON);
 	}
 

apps/website/src/util/model.ts

@@ -8,7 +8,7 @@ import type {
 import type { DocSection } from '@microsoft/tsdoc';
 
 export function findMemberByKey(model: ApiModel, packageName: string, containerKey: string) {
-	const pkg = model.tryGetPackageByName(`@discordjs/${packageName}`)!;
+	const pkg = model.tryGetPackageByName(packageName === 'discord.js' ? packageName : `@discordjs/${packageName}`)!;
 	return (pkg.members[0] as ApiEntryPoint).tryGetMemberByKey(containerKey);
 }
 
@@ -17,7 +17,7 @@ export function findMember(model: ApiModel, packageName: string, memberName: str
 		return undefined;
 	}
 
-	const pkg = model.tryGetPackageByName(`@discordjs/${packageName}`)!;
+	const pkg = model.tryGetPackageByName(packageName === 'discord.js' ? packageName : `@discordjs/${packageName}`)!;
 	return pkg.entryPoints[0]?.findMembersByName(memberName)[0];
 }
 

eslint.config.js

@@ -75,7 +75,7 @@ export default [
 		rules: { 'jsdoc/no-undefined-types': 0 },
 	},
 	{
-		files: [`packages/{brokers,create-discord-bot,docgen,ws}/**/*${commonFiles}`],
+		files: [`packages/{api-extractor,brokers,create-discord-bot,docgen,ws}/**/*${commonFiles}`],
 		rules: { 'n/no-sync': 0 },
 	},
 	{

package.json

@@ -85,7 +85,8 @@
 			"@contentlayer/utils>@opentelemetry/semantic-conventions": "^1.15.1"
 		},
 		"patchedDependencies": {
-			"@microsoft/tsdoc-config@0.16.2": "patches/@microsoft__tsdoc-config@0.16.2.patch"
+			"@microsoft/tsdoc-config@0.16.2": "patches/@microsoft__tsdoc-config@0.16.2.patch",
+			"next@14.0.2-canary.20": "patches/next@14.0.2-canary.20.patch"
 		}
 	},
 	"engines": {

packages/api-extractor-model/README.md

@@ -1,4 +1,4 @@
-# @microsoft/api-extractor-model
+# @discordjs/api-extractor-model
 
 Use this library to read and write \*.api.json files as defined by the [API Extractor](https://api-extractor.com/) tool.
 These files are used to generate a documentation website for your TypeScript package. The files store the
@@ -60,7 +60,7 @@ a namespace containing static members of the class.
 
 ## Links
 
-- [CHANGELOG.md](https://github.com/microsoft/rushstack/blob/main/libraries/api-extractor-model/CHANGELOG.md) - Find
+- [CHANGELOG.md](https://github.com/discordjs/discord.js/blob/main/packages/api-extractor-model/CHANGELOG.md) - Find
   out what's new in the latest version
 - [API Reference](https://rushstack.io/pages/api/api-extractor-model/)
 

packages/api-extractor-model/src/index.ts

@@ -58,12 +58,13 @@ export type { Constructor, PropertiesOf } from './mixins/Mixin.js';
 
 // model
 export { type IApiCallSignatureOptions, ApiCallSignature } from './model/ApiCallSignature.js';
-export { type IApiClassOptions, ApiClass } from './model/ApiClass.js';
+export { type IApiClassOptions, ApiClass, type IExcerptTokenRangeWithTypeParameters } from './model/ApiClass.js';
 export { type IApiConstructorOptions, ApiConstructor } from './model/ApiConstructor.js';
 export { type IApiConstructSignatureOptions, ApiConstructSignature } from './model/ApiConstructSignature.js';
 export { type IApiEntryPointOptions, ApiEntryPoint } from './model/ApiEntryPoint.js';
 export { type IApiEnumOptions, ApiEnum } from './model/ApiEnum.js';
 export { type IApiEnumMemberOptions, ApiEnumMember, EnumMemberOrder } from './model/ApiEnumMember.js';
+export { type IApiEventOptions, ApiEvent } from './model/ApiEvent.js';
 export { type IApiFunctionOptions, ApiFunction } from './model/ApiFunction.js';
 export { type IApiIndexSignatureOptions, ApiIndexSignature } from './model/ApiIndexSignature.js';
 export { type IApiInterfaceOptions, ApiInterface } from './model/ApiInterface.js';

packages/api-extractor-model/src/items/ApiItem.ts

@@ -8,6 +8,7 @@ import { ApiParameterListMixin } from '../mixins/ApiParameterListMixin.js';
 import type { Constructor, PropertiesOf } from '../mixins/Mixin.js';
 import type { ApiModel } from '../model/ApiModel.js';
 import type { ApiPackage } from '../model/ApiPackage.js';
+import type { DocgenJson } from '../model/Deserializer';
 import type { DeserializerContext } from '../model/DeserializerContext.js';
 
 /**
@@ -24,6 +25,7 @@ export enum ApiItemKind {
 	EntryPoint = 'EntryPoint',
 	Enum = 'Enum',
 	EnumMember = 'EnumMember',
+	Event = 'Event',
 	Function = 'Function',
 	IndexSignature = 'IndexSignature',
 	Interface = 'Interface',
@@ -111,6 +113,12 @@ export class ApiItem {
 		return deserializerModule.Deserializer.deserialize(context, jsonObject);
 	}
 
+	public static deserializeDocgen(jsonObject: DocgenJson, _package: string): ApiItem {
+		// eslint-disable-next-line @typescript-eslint/consistent-type-imports, @typescript-eslint/no-require-imports, @typescript-eslint/no-var-requires
+		const deserializerModule: typeof import('../model/Deserializer') = require('../model/Deserializer');
+		return deserializerModule.Deserializer.deserializeDocgen(jsonObject, _package);
+	}
+
 	/**
 	 * @virtual
 	 */

packages/api-extractor-model/src/mixins/ApiItemContainerMixin.ts

@@ -3,6 +3,7 @@
 
 import type { DeclarationReference } from '@microsoft/tsdoc/lib-commonjs/beta/DeclarationReference.js';
 import { InternalError } from '@rushstack/node-core-library';
+import type { ApiDeclaredItem } from '../index.js';
 import {
 	ApiItem,
 	apiItem_onParentChanged,
@@ -36,6 +37,11 @@ export interface IApiItemContainerJson extends IApiItemJson {
 	preserveMemberOrder?: boolean;
 }
 
+interface IMappedTypeParameters {
+	item: ApiItem;
+	mappedTypeParameters: Map<string, string>;
+}
+
 const _members: unique symbol = Symbol('ApiItemContainerMixin._members');
 const _membersSorted: unique symbol = Symbol('ApiItemContainerMixin._membersSorted');
 const _membersByContainerKey: unique symbol = Symbol('ApiItemContainerMixin._membersByContainerKey');
@@ -299,23 +305,76 @@ export function ApiItemContainerMixin<TBaseClass extends IApiItemConstructor>(
 				}
 			}
 
+			// The Deserializer class is coupled with a ton of other classes, so  we delay loading it
+			// to avoid ES5 circular imports.
+			// *eslint-disable-next-line @typescript-eslint/consistent-type-imports, @typescript-eslint/no-require-imports, @typescript-eslint/no-var-requires
+			// const deserializerModule: typeof import('../model/Deserializer') = require('../model/Deserializer');
+
 			const membersByName: Map<string, ApiItem[]> = new Map();
 			const membersByKind: Map<ApiItemKind, ApiItem[]> = new Map();
 
-			const toVisit: ApiItem[] = [];
+			const toVisit: IMappedTypeParameters[] = [];
-			let next: ApiItem | undefined = this;
+			let next: IMappedTypeParameters | undefined = { item: this, mappedTypeParameters: new Map() };
 
-			while (next) {
+			while (next?.item) {
-				const membersToAdd: ApiItem[] = [];
+				const membersToAdd: ApiItem[] = []; /*
+				const typeParams = next.mappedTypeParameters;
+				const context: DeserializerContext = {
+					apiJsonFilename: '',
+					toolPackage: '',
+					toolVersion: '',
+					versionToDeserialize: ApiJsonSchemaVersion.LATEST,
+					tsdocConfiguration: new TSDocConfiguration(),
+				}; */
 
 				// For each member, check to see if we've already seen a member with the same name
 				// previously in the inheritance tree. If so, we know we won't inherit it, and thus
 				// do not add it to our `membersToAdd` array.
-				for (const member of next.members) {
+				for (const member of next.item.members) {
 					// We add the to-be-added members to an intermediate array instead of immediately
 					// to the maps themselves to support method overloads with the same name.
 					if (ApiNameMixin.isBaseClassOf(member)) {
 						if (!membersByName.has(member.name)) {
+							// This was supposed to replace type parameters with their assigned values in inheritance, but doesn't work yet
+							/*
+							if (
+								ApiTypeParameterListMixin.isBaseClassOf(member) &&
+								member.typeParameters.some((param) => typeParams.has(param.name))
+							) {
+								const jsonObject: Partial<IApiItemJson> = {};
+								member.serializeInto(jsonObject);
+								member = deserializerModule.Deserializer.deserialize(context, {
+									...jsonObject,
+									typeParameters: (jsonObject as IApiTypeParameterListMixinJson).typeParameters.map(
+										({ typeParameterName, constraintTokenRange, defaultTypeTokenRange }) => ({
+											typeParameterName: typeParams.get(typeParameterName) ?? typeParameterName,
+											defaultTypeTokenRange,
+											constraintTokenRange,
+										}),
+									),
+								} as IApiTypeParameterListMixinJson);
+							}
+
+							if (ApiReturnTypeMixin.isBaseClassOf(member)) {
+								const jsonObject: Partial<IApiItemJson> = {};
+								member.serializeInto(jsonObject);
+								member = deserializerModule.Deserializer.deserialize(context, {
+									...(jsonObject as IApiReturnTypeMixinJson),
+									excerptTokens: (jsonObject as IApiDeclaredItemJson).excerptTokens.map((token) =>
+										token.kind === ExcerptTokenKind.Content
+											? {
+													kind: ExcerptTokenKind.Content,
+													text: [...typeParams.keys()].reduce(
+														(tok, typ) => tok.replaceAll(new RegExp(`\b${typ}\b`, 'g'), typeParams.get(typ)!),
+														token.text,
+													),
+											  }
+											: token,
+									),
+								} as IApiReturnTypeMixinJson);
+								member[apiItem_onParentChanged](next.item);
+							} // */
+
 							membersToAdd.push(member);
 						}
 					} else if (!membersByKind.has(member.kind)) {
@@ -336,18 +395,18 @@ export function ApiItemContainerMixin<TBaseClass extends IApiItemConstructor>(
 				}
 
 				// Interfaces can extend multiple interfaces, so iterate through all of them.
-				const extendedItems: ApiItem[] = [];
+				const extendedItems: IMappedTypeParameters[] = [];
 				let extendsTypes: readonly HeritageType[] | undefined;
 
-				switch (next.kind) {
+				switch (next.item.kind) {
 					case ApiItemKind.Class: {
-						const apiClass: ApiClass = next as ApiClass;
+						const apiClass: ApiClass = next.item as ApiClass;
 						extendsTypes = apiClass.extendsType ? [apiClass.extendsType] : [];
 						break;
 					}
 
 					case ApiItemKind.Interface: {
-						const apiInterface: ApiInterface = next as ApiInterface;
+						const apiInterface: ApiInterface = next.item as ApiInterface;
 						extendsTypes = apiInterface.extendsTypes;
 						break;
 					}
@@ -359,7 +418,7 @@ export function ApiItemContainerMixin<TBaseClass extends IApiItemConstructor>(
 				if (extendsTypes === undefined) {
 					messages.push({
 						messageId: FindApiItemsMessageId.UnsupportedKind,
-						text: `Unable to analyze references of API item ${next.displayName} because it is of unsupported kind ${next.kind}`,
+						text: `Unable to analyze references of API item ${next.item.displayName} because it is of unsupported kind ${next.item.kind}`,
 					});
 					maybeIncompleteResult = true;
 					next = toVisit.shift();
@@ -387,7 +446,7 @@ export function ApiItemContainerMixin<TBaseClass extends IApiItemConstructor>(
 					if (!firstReferenceToken) {
 						messages.push({
 							messageId: FindApiItemsMessageId.ExtendsClauseMissingReference,
-							text: `Unable to analyze extends clause ${extendsType.excerpt.text} of API item ${next.displayName} because no canonical reference was found`,
+							text: `Unable to analyze extends clause ${extendsType.excerpt.text} of API item ${next.item.displayName} because no canonical reference was found`,
 						});
 						maybeIncompleteResult = true;
 						continue;
@@ -397,7 +456,7 @@ export function ApiItemContainerMixin<TBaseClass extends IApiItemConstructor>(
 					if (!apiModel) {
 						messages.push({
 							messageId: FindApiItemsMessageId.NoAssociatedApiModel,
-							text: `Unable to analyze references of API item ${next.displayName} because it is not associated with an ApiModel`,
+							text: `Unable to analyze references of API item ${next.item.displayName} because it is not associated with an ApiModel`,
 						});
 						maybeIncompleteResult = true;
 						continue;
@@ -413,13 +472,24 @@ export function ApiItemContainerMixin<TBaseClass extends IApiItemConstructor>(
 					if (!apiItem) {
 						messages.push({
 							messageId: FindApiItemsMessageId.DeclarationResolutionFailed,
-							text: `Unable to resolve declaration reference within API item ${next.displayName}: ${apiItemResult.errorMessage}`,
+							text: `Unable to resolve declaration reference within API item ${next.item.displayName}: ${apiItemResult.errorMessage}`,
 						});
 						maybeIncompleteResult = true;
 						continue;
 					}
 
-					extendedItems.push(apiItem);
+					const mappedTypeParameters: Map<string, string> = new Map();
+					if (
+						(apiItem.kind === ApiItemKind.Class || apiItem.kind === ApiItemKind.Interface) &&
+						next.item.kind === ApiItemKind.Class
+					) {
+						for (const [index, typeParameter] of extendsType.typeParameters.entries()) {
+							const key = (apiItem as ApiClass | ApiInterface).typeParameters[index]?.name ?? '';
+							mappedTypeParameters.set(key, typeParameter);
+						}
+					}
+
+					extendedItems.push({ item: apiItem, mappedTypeParameters });
 				}
 
 				// For classes, this array will only have one item. For interfaces, there may be multiple items. Sort the array
@@ -440,7 +510,9 @@ export function ApiItemContainerMixin<TBaseClass extends IApiItemConstructor>(
 				//
 				// interface FooBar extends Foo, Bar {}
 				// ```
-				extendedItems.sort((x: ApiItem, y: ApiItem) => x.getSortKey().localeCompare(y.getSortKey()));
+				extendedItems.sort((x: IMappedTypeParameters, y: IMappedTypeParameters) =>
+					x.item.getSortKey().localeCompare(y.item.getSortKey()),
+				);
 
 				toVisit.push(...extendedItems);
 				next = toVisit.shift();

packages/api-extractor-model/src/mixins/Excerpt.ts

@@ -147,7 +147,11 @@ export class Excerpt {
 			this.tokenRange.endIndex > this.tokens.length ||
 			this.tokenRange.startIndex > this.tokenRange.endIndex
 		) {
-			throw new Error('Invalid token range');
+			throw new Error(
+				`Invalid token range. length:${this.tokens.length}, start:${this.tokenRange.startIndex}, end:${
+					this.tokenRange.endIndex
+				}, ${this.tokens.map((token) => token.text)}`,
+			);
 		}
 
 		this.spannedTokens = this.tokens.slice(this.tokenRange.startIndex, this.tokenRange.endIndex);

packages/api-extractor-model/src/model/ApiClass.ts

@@ -39,8 +39,12 @@ export interface IApiClassOptions
 		IApiDeclaredItemOptions,
 		IApiTypeParameterListMixinOptions,
 		IApiExportedMixinOptions {
-	extendsTokenRange: IExcerptTokenRange | undefined;
+	extendsTokenRange: IExcerptTokenRangeWithTypeParameters | undefined;
-	implementsTokenRanges: IExcerptTokenRange[];
+	implementsTokenRanges: IExcerptTokenRangeWithTypeParameters[];
+}
+
+export interface IExcerptTokenRangeWithTypeParameters extends IExcerptTokenRange {
+	typeParameters: string[];
 }
 
 export interface IApiClassJson
@@ -48,8 +52,8 @@ export interface IApiClassJson
 		IApiAbstractMixinJson,
 		IApiTypeParameterListMixinJson,
 		IApiExportedMixinJson {
-	extendsTokenRange?: IExcerptTokenRange;
+	extendsTokenRange?: IExcerptTokenRangeWithTypeParameters | undefined;
-	implementsTokenRanges: IExcerptTokenRange[];
+	implementsTokenRanges: IExcerptTokenRangeWithTypeParameters[];
 }
 
 /**
@@ -81,13 +85,18 @@ export class ApiClass extends ApiItemContainerMixin(
 		super(options);
 
 		if (options.extendsTokenRange) {
-			this.extendsType = new HeritageType(this.buildExcerpt(options.extendsTokenRange));
+			this.extendsType = new HeritageType(
+				this.buildExcerpt(options.extendsTokenRange),
+				options.extendsTokenRange.typeParameters,
+			);
 		} else {
 			this.extendsType = undefined;
 		}
 
 		for (const implementsTokenRange of options.implementsTokenRanges) {
-			this._implementsTypes.push(new HeritageType(this.buildExcerpt(implementsTokenRange)));
+			this._implementsTypes.push(
+				new HeritageType(this.buildExcerpt(implementsTokenRange), implementsTokenRange.typeParameters),
+			);
 		}
 	}
 
@@ -138,10 +147,16 @@ export class ApiClass extends ApiItemContainerMixin(
 
 		// Note that JSON does not support the "undefined" value, so we simply omit the field entirely if it is undefined
 		if (this.extendsType) {
-			jsonObject.extendsTokenRange = this.extendsType.excerpt.tokenRange;
+			jsonObject.extendsTokenRange = {
+				...this.extendsType.excerpt.tokenRange,
+				typeParameters: this.extendsType.typeParameters,
+			};
 		}
 
-		jsonObject.implementsTokenRanges = this.implementsTypes.map((x) => x.excerpt.tokenRange);
+		jsonObject.implementsTokenRanges = this.implementsTypes.map((x) => ({
+			...x.excerpt.tokenRange,
+			typeParameters: x.typeParameters,
+		}));
 	}
 
 	/**

packages/api-extractor-model/src/model/ApiEvent.ts

@@ -0,0 +1,72 @@
+// Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license.
+// See LICENSE in the project root for license information.
+
+import { DeclarationReference, type Component } from '@microsoft/tsdoc/lib-commonjs/beta/DeclarationReference.js';
+import { type IApiDeclaredItemOptions, ApiDeclaredItem } from '../items/ApiDeclaredItem.js';
+import { ApiItemKind, Navigation, Meaning } from '../items/ApiItem.js';
+import { type IApiNameMixinOptions, ApiNameMixin } from '../mixins/ApiNameMixin.js';
+import { type IApiParameterListMixinOptions, ApiParameterListMixin } from '../mixins/ApiParameterListMixin.js';
+import { type IApiReleaseTagMixinOptions, ApiReleaseTagMixin } from '../mixins/ApiReleaseTagMixin.js';
+
+/**
+ * Constructor options for {@link ApiEvent}.
+ *
+ * @public
+ */
+export interface IApiEventOptions
+	extends IApiNameMixinOptions,
+		IApiParameterListMixinOptions,
+		IApiReleaseTagMixinOptions,
+		IApiDeclaredItemOptions {}
+
+/**
+ * Represents a TypeScript event declaration that belongs to an `ApiClass`.
+ *
+ * @remarks
+ *
+ * This is part of the {@link ApiModel} hierarchy of classes, which are serializable representations of
+ * API declarations.
+ *
+ * `ApiEvent` represents a emittable event such as the `ready` event in this example:
+ *
+ * ```ts
+ * export class Cliet extends EventEmitter {
+ *   on(event: 'ready', ...args: [Client]): this { }
+ * }
+ * ```
+ * @public
+ */
+export class ApiEvent extends ApiNameMixin(ApiParameterListMixin(ApiReleaseTagMixin(ApiDeclaredItem))) {
+	public constructor(options: IApiEventOptions) {
+		super(options);
+	}
+
+	public static getContainerKey(name: string, overloadIndex: number): string {
+		return `${name}|${ApiItemKind.Event}|${overloadIndex}`;
+	}
+
+	/**
+	 * @override
+	 */
+	public override get kind(): ApiItemKind {
+		return ApiItemKind.Event;
+	}
+
+	/**
+	 * @override
+	 */
+	public override get containerKey(): string {
+		return ApiEvent.getContainerKey(this.name, this.overloadIndex);
+	}
+
+	/**
+	 * @beta @override
+	 */
+	public override buildCanonicalReference(): DeclarationReference {
+		const nameComponent: Component = DeclarationReference.parseComponent(this.name);
+		return (this.parent ? this.parent.canonicalReference : DeclarationReference.empty())
+			.addNavigationStep(Navigation.Members as any, nameComponent)
+			.withMeaning(Meaning.Member as any)
+			.withOverloadIndex(this.overloadIndex);
+	}
+}

packages/api-extractor-model/src/model/ApiInterface.ts

@@ -25,7 +25,7 @@ import {
 	type IApiTypeParameterListMixinJson,
 	ApiTypeParameterListMixin,
 } from '../mixins/ApiTypeParameterListMixin.js';
-import type { IExcerptTokenRange } from '../mixins/Excerpt.js';
+import type { IExcerptTokenRangeWithTypeParameters } from './ApiClass.js';
 import type { DeserializerContext } from './DeserializerContext.js';
 import { HeritageType } from './HeritageType.js';
 
@@ -41,7 +41,7 @@ export interface IApiInterfaceOptions
 		IApiReleaseTagMixinOptions,
 		IApiDeclaredItemOptions,
 		IApiExportedMixinOptions {
-	extendsTokenRanges: IExcerptTokenRange[];
+	extendsTokenRanges: IExcerptTokenRangeWithTypeParameters[];
 }
 
 export interface IApiInterfaceJson
@@ -51,7 +51,7 @@ export interface IApiInterfaceJson
 		IApiReleaseTagMixinJson,
 		IApiDeclaredItemJson,
 		IApiExportedMixinJson {
-	extendsTokenRanges: IExcerptTokenRange[];
+	extendsTokenRanges: IExcerptTokenRangeWithTypeParameters[];
 }
 
 /**
@@ -79,7 +79,7 @@ export class ApiInterface extends ApiItemContainerMixin(
 		super(options);
 
 		for (const extendsTokenRange of options.extendsTokenRanges) {
-			this._extendsTypes.push(new HeritageType(this.buildExcerpt(extendsTokenRange)));
+			this._extendsTypes.push(new HeritageType(this.buildExcerpt(extendsTokenRange), extendsTokenRange.typeParameters));
 		}
 	}
 
@@ -127,7 +127,10 @@ export class ApiInterface extends ApiItemContainerMixin(
 	public override serializeInto(jsonObject: Partial<IApiInterfaceJson>): void {
 		super.serializeInto(jsonObject);
 
-		jsonObject.extendsTokenRanges = this.extendsTypes.map((x) => x.excerpt.tokenRange);
+		jsonObject.extendsTokenRanges = this.extendsTypes.map((x) => ({
+			...x.excerpt.tokenRange,
+			typeParameters: x.typeParameters,
+		}));
 	}
 
 	/**

packages/api-extractor-model/src/model/Deserializer.ts

@@ -1,9 +1,24 @@
 // Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license.
 // See LICENSE in the project root for license information.
 
+import { TSDocConfiguration } from '@microsoft/tsdoc';
+import type { IExcerptToken } from '../index.js';
+import { ExcerptTokenKind } from '../index.js';
 import type { IApiDeclaredItemJson } from '../items/ApiDeclaredItem.js';
+import type { IApiDocumentedItemJson } from '../items/ApiDocumentedItem.js';
 import { type IApiItemJson, type IApiItemOptions, type ApiItem, ApiItemKind } from '../items/ApiItem.js';
 import type { IApiPropertyItemJson } from '../items/ApiPropertyItem.js';
+import type { IApiAbstractMixinJson } from '../mixins/ApiAbstractMixin.js';
+import type { IApiItemContainerJson } from '../mixins/ApiItemContainerMixin.js';
+import type { IApiNameMixinJson } from '../mixins/ApiNameMixin.js';
+import type { IApiOptionalMixinJson } from '../mixins/ApiOptionalMixin.js';
+import type { IApiParameterListJson, IApiParameterOptions } from '../mixins/ApiParameterListMixin.js';
+import type { IApiProtectedMixinJson } from '../mixins/ApiProtectedMixin.js';
+import type { IApiReadonlyMixinJson } from '../mixins/ApiReadonlyMixin.js';
+import type { IApiReleaseTagMixinJson } from '../mixins/ApiReleaseTagMixin.js';
+import type { IApiReturnTypeMixinJson } from '../mixins/ApiReturnTypeMixin.js';
+import type { IApiStaticMixinJson } from '../mixins/ApiStaticMixin.js';
+import type { IApiTypeParameterListMixinJson } from '../mixins/ApiTypeParameterListMixin.js';
 import { ApiCallSignature, type IApiCallSignatureOptions } from './ApiCallSignature.js';
 import { ApiClass, type IApiClassOptions, type IApiClassJson } from './ApiClass.js';
 import { ApiConstructSignature, type IApiConstructSignatureOptions } from './ApiConstructSignature.js';
@@ -11,6 +26,8 @@ import { ApiConstructor, type IApiConstructorOptions } from './ApiConstructor.js
 import { ApiEntryPoint, type IApiEntryPointOptions } from './ApiEntryPoint.js';
 import { ApiEnum, type IApiEnumOptions } from './ApiEnum.js';
 import { ApiEnumMember, type IApiEnumMemberOptions } from './ApiEnumMember.js';
+import type { IApiEventOptions } from './ApiEvent.js';
+import { ApiEvent } from './ApiEvent.js';
 import { ApiFunction, type IApiFunctionOptions } from './ApiFunction.js';
 import { ApiIndexSignature, type IApiIndexSignatureOptions } from './ApiIndexSignature.js';
 import { ApiInterface, type IApiInterfaceOptions, type IApiInterfaceJson } from './ApiInterface.js';
@@ -23,7 +40,313 @@ import { ApiProperty, type IApiPropertyOptions } from './ApiProperty.js';
 import { ApiPropertySignature, type IApiPropertySignatureOptions } from './ApiPropertySignature.js';
 import { ApiTypeAlias, type IApiTypeAliasOptions, type IApiTypeAliasJson } from './ApiTypeAlias.js';
 import { ApiVariable, type IApiVariableOptions, type IApiVariableJson } from './ApiVariable.js';
-import type { DeserializerContext } from './DeserializerContext.js';
+import { ApiJsonSchemaVersion, type DeserializerContext } from './DeserializerContext.js';
+
+type DocgenAccess = 'private' | 'protected' | 'public';
+type DocgenScope = 'global' | 'instance' | 'static';
+type DocgenDeprecated = boolean | string;
+
+interface DocgenMetaJson {
+	file: string;
+	line: number;
+	path: string;
+}
+
+interface DocgenTypeJson {
+	names?: string[] | undefined;
+}
+
+interface DocgenVarJson {
+	description?: string;
+	nullable?: boolean;
+	types?: string[][][];
+}
+type DocgenVarTypeJson = DocgenVarJson | string[][][];
+interface DocgenExceptionJson {
+	description?: string;
+	nullable?: boolean;
+	type: DocgenTypeJson;
+}
+
+interface DocgenExternalJson {
+	description: string;
+	meta: DocgenMetaJson;
+	name: string;
+	see?: string[];
+}
+
+interface DocgenTypedefJson {
+	access?: DocgenAccess;
+	deprecated?: DocgenDeprecated;
+	description: string;
+	meta: DocgenMetaJson;
+	name: string;
+	params?: DocgenParamJson[];
+	props?: DocgenParamJson[];
+	returns?: DocgenVarTypeJson[];
+	see?: string[];
+	type: DocgenVarTypeJson;
+}
+
+interface DocgenEventJson {
+	deprecated?: DocgenDeprecated;
+	description: string;
+	meta: DocgenMetaJson;
+	name: string;
+	params?: DocgenParamJson[];
+	see?: string[];
+}
+
+interface DocgenParamJson {
+	default?: string;
+	description: string;
+	name: string;
+	nullable?: boolean;
+	optional?: boolean;
+	type: DocgenVarTypeJson;
+	variable?: string;
+}
+
+interface DocgenConstructorJson {
+	access?: DocgenAccess;
+	description: string;
+	name: string;
+	params?: DocgenParamJson[];
+	see?: string[];
+}
+
+interface DocgenMethodJson {
+	abstract: boolean;
+	access?: DocgenAccess;
+	async?: boolean;
+	deprecated?: DocgenDeprecated;
+	description: string;
+	emits?: string[];
+	examples?: string[];
+	generator?: boolean;
+	implements?: string[];
+	inherited?: boolean;
+	inherits?: string;
+	meta: DocgenMetaJson;
+	name: string;
+	params?: DocgenParamJson[];
+	returns?: DocgenVarTypeJson[];
+	scope: DocgenScope;
+	see?: string[];
+	throws?: DocgenExceptionJson[];
+}
+
+interface DocgenPropertyJson {
+	abstract?: boolean;
+	access?: DocgenAccess;
+	default?: string;
+	deprecated?: DocgenDeprecated;
+	description: string;
+	meta: DocgenMetaJson;
+	name: string;
+	nullable?: boolean;
+	props?: DocgenPropertyJson[];
+	readonly?: boolean;
+	scope: DocgenScope;
+	see?: string[];
+	type: DocgenVarTypeJson;
+}
+interface DocgenClassJson {
+	abstract?: boolean;
+	access?: DocgenAccess;
+	construct: DocgenConstructorJson;
+	deprecated?: DocgenDeprecated | string;
+	description: string;
+	events?: DocgenEventJson[];
+	extends?: DocgenVarTypeJson;
+	implements?: DocgenVarTypeJson;
+	meta: DocgenMetaJson;
+	methods?: DocgenMethodJson[];
+	name: string;
+	props?: DocgenPropertyJson[];
+	see?: string[];
+}
+type DocgenInterfaceJson = DocgenClassJson;
+
+export interface DocgenJson {
+	classes: DocgenClassJson[];
+	externals: DocgenExternalJson[];
+	functions: DocgenMethodJson[];
+	interfaces: DocgenInterfaceJson[];
+	meta: {
+		date: number;
+		format: number;
+		generator: string;
+	};
+	typedefs: DocgenTypedefJson[];
+}
+
+function formatVarType(type: DocgenVarTypeJson): string {
+	return (Array.isArray(type) ? type : type.types ?? []).map((t1) => t1.map((t2) => t2.join('')).join('')).join(' | ');
+}
+
+function getFirstType(type: DocgenVarTypeJson): string {
+	return (Array.isArray(type) ? type[0]?.[0]?.[0] : type.types?.[0]?.[0]?.[0]) ?? 'unknown';
+}
+
+// function mapEvent(_event: DocgenEventJson, _package: string, _parent: DocgenClassJson): void {}
+
+function mapVarType(type: DocgenVarTypeJson, _package: string): IExcerptToken[] {
+	const mapper = Array.isArray(type) ? type : type.types ?? [];
+	return mapper.flatMap((typ) =>
+		typ.reduce<IExcerptToken[]>(
+			(arr, [_class, symbol]) => [
+				...arr,
+				{
+					kind: ExcerptTokenKind.Reference,
+					text: _class ?? 'unknown',
+					canonicalReference: `${_package}!${_class}:class`,
+				},
+				{ kind: ExcerptTokenKind.Content, text: symbol ?? '' },
+			],
+			[],
+		),
+	);
+}
+
+function mapProp(
+	prop: DocgenPropertyJson,
+	_package: string,
+	parent: DocgenClassJson | DocgenInterfaceJson,
+): IApiNameMixinJson & IApiOptionalMixinJson & IApiPropertyItemJson & IApiReadonlyMixinJson & IApiReleaseTagMixinJson {
+	const mappedVarType = mapVarType(prop.type, _package);
+	return {
+		kind: ApiItemKind.Property,
+		name: prop.name,
+		isOptional: Boolean(prop.nullable),
+		isReadonly: Boolean(prop.readonly),
+		docComment: `/**\n * ${prop.description}\n${prop.see?.map((see) => ` * @see ${see}\n`).join('') ?? ''}${
+			prop.readonly ? ' * @readonly\n' : ''
+		} */`,
+		excerptTokens: [
+			{
+				kind: ExcerptTokenKind.Content,
+				text: `${prop.access} ${prop.scope === 'static' ? 'static ' : ''}${prop.readonly ? 'readonly ' : ''}${
+					prop.name
+				} :`,
+			},
+			...mappedVarType,
+			{
+				kind: ExcerptTokenKind.Reference,
+				text: formatVarType(prop.type),
+				canonicalReference: `${_package}!${getFirstType(prop.type)}:class`,
+			},
+			{ kind: ExcerptTokenKind.Content, text: ';' },
+		],
+		propertyTypeTokenRange: { startIndex: 1, endIndex: 1 + mappedVarType.length },
+		canonicalReference: `${_package}!${parent.name}#${prop.name}:member`,
+		releaseTag: prop.access === 'public' ? 'Public' : 'Internal',
+		fileLine: prop.meta.line,
+		fileUrlPath: `${prop.meta.path.slice(`packages/${_package}/`.length)}/${prop.meta.file}`,
+	};
+}
+
+function mapParam(
+	param: DocgenParamJson,
+	index: number,
+	_package: string,
+	paramTokens: number[],
+): IApiParameterOptions {
+	return {
+		parameterName: param.name.startsWith('...') ? param.name.slice(3) : param.name,
+		isOptional: Boolean(param.optional),
+		isRest: param.name.startsWith('...'),
+		parameterTypeTokenRange: {
+			startIndex: 1 + index + paramTokens.slice(0, index).reduce((akk, num) => akk + num, 0),
+			endIndex: 1 + index + paramTokens.slice(0, index + 1).reduce((akk, num) => akk + num, 0),
+		},
+	};
+}
+
+interface IApiMethodJson
+	extends IApiAbstractMixinJson,
+		IApiDeclaredItemJson,
+		IApiNameMixinJson,
+		IApiOptionalMixinJson,
+		IApiParameterListJson,
+		IApiProtectedMixinJson,
+		IApiReleaseTagMixinJson,
+		IApiReturnTypeMixinJson,
+		IApiStaticMixinJson,
+		IApiTypeParameterListMixinJson {}
+
+interface IApiConstructorJson
+	extends IApiParameterListJson,
+		IApiProtectedMixinJson,
+		IApiReleaseTagMixinJson,
+		IApiDeclaredItemJson {}
+
+function mapMethod(method: DocgenMethodJson, _package: string, parent?: DocgenClassJson): IApiMethodJson {
+	const excerptTokens: IExcerptToken[] = [];
+	excerptTokens.push({
+		kind: ExcerptTokenKind.Content,
+		text: `${
+			method.scope === 'global'
+				? `export function ${method.name}(`
+				: `${method.access}${method.scope === 'static' ? ' static' : ''} ${method.name}(`
+		}${
+			method.params?.length
+				? `${method.params[0]!.name}${method.params[0]!.nullable || method.params[0]!.optional ? '?' : ''}`
+				: '): '
+		}`,
+	});
+	const paramTokens: number[] = [];
+	for (let index = 0; index < (method.params?.length ?? 0) - 1; index++) {
+		const newTokens = mapVarType(method.params![index]!.type, _package);
+		paramTokens.push(newTokens.length);
+		excerptTokens.push(...newTokens);
+		excerptTokens.push({
+			kind: ExcerptTokenKind.Content,
+			text: `, ${method.params![index + 1]!.name}${
+				method.params![index + 1]!.nullable || method.params![index + 1]!.optional ? '?' : ''
+			}: `,
+		});
+	}
+
+	if (method.params?.length) {
+		const newTokens = mapVarType(method.params[method.params.length - 1]!.type, _package);
+		paramTokens.push(newTokens.length);
+		excerptTokens.push(...newTokens);
+		excerptTokens.push({ kind: ExcerptTokenKind.Content, text: `): ` });
+	}
+
+	const returnTokens = mapVarType(method.returns?.[0] ?? [], _package);
+	excerptTokens.push(...returnTokens);
+
+	excerptTokens.push({ kind: ExcerptTokenKind.Content, text: ';' });
+
+	return {
+		kind: parent ? ApiItemKind.Method : ApiItemKind.Function,
+		name: method.name,
+		isAbstract: method.abstract,
+		isOptional: false,
+		isProtected: method.access === 'protected',
+		isStatic: method.scope === 'static',
+		canonicalReference: `${_package}!${parent ? `${parent.name}!${method.name}:member` : `${method.name}:function`}`,
+		overloadIndex: 1,
+		parameters: method.params?.map((param, index) => mapParam(param, index, _package, paramTokens)) ?? [],
+		releaseTag: method.access === 'public' ? 'Public' : 'Internal',
+		returnTypeTokenRange: method.returns?.length
+			? method.params?.length
+				? { startIndex: 2 + 2 * method.params.length, endIndex: 3 + 2 * method.params.length }
+				: { startIndex: 1, endIndex: 2 }
+			: { startIndex: 0, endIndex: 0 },
+		typeParameters: [],
+		docComment: `/**\n * ${method.description}\n${
+			method.params?.map((param) => ` * @param ${param.name} - ${param.description}\n`).join('') ?? ''
+		}${
+			method.returns?.length && !Array.isArray(method.returns[0]) ? ` * @returns ${method.returns[0]!.description}` : ''
+		} */`,
+		excerptTokens,
+		fileLine: method.meta.line,
+		fileUrlPath: `${method.meta.path.slice(`packages/${_package}/`.length)}/${method.meta.file}`,
+	};
+}
 
 export class Deserializer {
 	public static deserialize(context: DeserializerContext, jsonObject: IApiItemJson): ApiItem {
@@ -51,6 +374,9 @@ export class Deserializer {
 			case ApiItemKind.EnumMember:
 				ApiEnumMember.onDeserializeInto(options, context, jsonObject as IApiDeclaredItemJson);
 				return new ApiEnumMember(options as IApiEnumMemberOptions);
+			case ApiItemKind.Event:
+				ApiEvent.onDeserializeInto(options, context, jsonObject as IApiDeclaredItemJson);
+				return new ApiEvent(options as IApiEventOptions);
 			case ApiItemKind.Function:
 				ApiFunction.onDeserializeInto(options, context, jsonObject as IApiDeclaredItemJson);
 				return new ApiFunction(options as IApiFunctionOptions);
@@ -90,4 +416,162 @@ export class Deserializer {
 				throw new Error(`Failed to deserialize unsupported API item type ${JSON.stringify(jsonObject.kind)}`);
 		}
 	}
+
+	public static deserializeDocgen(jsonObject: DocgenJson, _package: string) {
+		const context: DeserializerContext = {
+			apiJsonFilename: 'docs.json',
+			tsdocConfiguration: new TSDocConfiguration(),
+			versionToDeserialize: ApiJsonSchemaVersion.V_1011,
+			toolPackage: jsonObject.meta.generator,
+			toolVersion: jsonObject.meta.format.toString(),
+		};
+
+		let members: (IApiClassJson | IApiInterfaceJson | IApiMethodJson | IApiTypeAliasJson)[] = [];
+
+		for (const _class of jsonObject.classes) {
+			const classMembers: (IApiConstructorJson | IApiMethodJson | IApiPropertyItemJson)[] = [
+				// ..._class.events.map((event) => mapEvent(event, _package, _class)),
+				...(_class.props?.map((prop) => mapProp(prop, _package, _class)) ?? []),
+				...(_class.methods?.map((method) => mapMethod(method, _package, _class)) ?? []),
+			];
+			if (_class.construct) {
+				const excerptTokens: IExcerptToken[] = [
+					{
+						kind: ExcerptTokenKind.Content,
+						text: `${_class.construct.access} constructor(${
+							_class.construct.params?.length ? `${_class.construct.params[0]?.name}: ` : ');'
+						}`,
+					},
+				];
+
+				const paramTokens: number[] = [];
+				for (let index = 0; index < (_class.construct.params?.length ?? 0) - 1; index++) {
+					const newTokens = mapVarType(_class.construct.params![index]!.type, _package);
+					paramTokens.push(newTokens.length);
+					excerptTokens.push(...newTokens);
+					excerptTokens.push({
+						kind: ExcerptTokenKind.Content,
+						text: `, ${_class.construct.params![index + 1]?.name}: `,
+					});
+				}
+
+				if (_class.construct.params?.length) {
+					const newTokens = mapVarType(_class.construct.params[_class.construct.params.length - 1]!.type, _package);
+					paramTokens.push(newTokens.length);
+					excerptTokens.push(...newTokens);
+					excerptTokens.push({ kind: ExcerptTokenKind.Content, text: ');' });
+				}
+
+				classMembers.unshift({
+					parameters:
+						_class.construct.params?.map((param, index) => mapParam(param, index, _package, paramTokens)) ?? [],
+					isProtected: _class.construct.access === 'protected',
+					releaseTag: _class.construct.access === 'public' ? 'Public' : 'Internal',
+					docComment: `/*+\n * ${_class.construct.description}\n${
+						_class.construct.params?.map((param) => ` * @param ${param.name} - ${param.description}\n`).join('') ?? ''
+					} */`,
+					excerptTokens,
+					kind: ApiItemKind.Constructor,
+					canonicalReference: `${_package}!${_class.name}:constructor`,
+					overloadIndex: 0,
+				});
+			}
+
+			const excerptTokens: IExcerptToken[] = [
+				{
+					kind: ExcerptTokenKind.Content,
+					text: `${_class.access === 'public' ? 'export ' : ''}declare class ${_class.name}${
+						_class.extends ? ' extends ' : _class.implements ? ' implements ' : ''
+					}`,
+				},
+			];
+
+			if (_class.extends)
+				excerptTokens.push({
+					kind: ExcerptTokenKind.Reference,
+					text: formatVarType(_class.extends) ?? '',
+					canonicalReference: `${_package}!${getFirstType(_class.extends) ?? ''}:class`,
+				});
+
+			if (_class.extends && _class.implements)
+				excerptTokens.push({ kind: ExcerptTokenKind.Content, text: ' implements ' });
+
+			if (_class.implements)
+				excerptTokens.push({
+					kind: ExcerptTokenKind.Reference,
+					text: formatVarType(_class.implements) ?? '',
+					canonicalReference: `${_package}!${getFirstType(_class.implements) ?? ''}:class`,
+				});
+
+			members.push({
+				members: classMembers,
+				kind: ApiItemKind.Class,
+				canonicalReference: `${_package}!${_class.name}:class`,
+				name: _class.name,
+				extendsTokenRange: _class.extends ? { startIndex: 1, endIndex: 2, typeParameters: [] } : undefined,
+				excerptTokens,
+				implementsTokenRanges: _class.implements
+					? [{ startIndex: _class.extends ? 3 : 1, endIndex: _class.extends ? 4 : 2, typeParameters: [] }]
+					: [],
+				typeParameters: [],
+				releaseTag: _class.access === 'public' ? 'Public' : 'Internal',
+				docComment: `/**\n * ${_class.description}\n${_class.see?.map((see) => ` * @see ${see}\n`).join('') ?? ''} */`,
+				isExported: _class.access === 'public',
+				isAbstract: Boolean(_class.abstract),
+				fileLine: _class.meta.line,
+				fileUrlPath: `${_class.meta.path.slice(`packages/${_package}/`.length)}/${_class.meta.file}`,
+			});
+		}
+
+		members = [
+			...members,
+			...jsonObject.functions.map((_func) => mapMethod(_func, _package)),
+			...jsonObject.interfaces.map((_interface) => ({
+				members: [
+					...(_interface.props?.map((prop) => mapProp(prop, _package, _interface)) ?? []),
+					...(_interface.methods?.map((method) => mapMethod(method, _package, _interface)) ?? []),
+				],
+				kind: ApiItemKind.Interface,
+				canonicalReference: `${_package}!${_interface.name}:interface`,
+				name: _interface.name,
+				extendsTokenRanges: [{ startIndex: 0, endIndex: 0, typeParameters: [] }],
+				excerptTokens: [
+					{
+						kind: ExcerptTokenKind.Content,
+						text: `${_interface.access === 'public' ? 'export ' : ''}interface ${_interface.name}`,
+					},
+				],
+				typeParameters: [],
+				releaseTag: _interface.access === 'public' ? 'Public' : 'Internal',
+				docComment: `/**\n * ${_interface.description}\n${
+					_interface.see?.map((see) => ` * @see ${see}\n`).join('') ?? ''
+				} */`,
+				isExported: _interface.access === 'public',
+				fileLine: _interface.meta.line,
+				fileUrlPath: `${_interface.meta.path.slice(`packages/${_package}/`.length)}/${_interface.meta.file}`,
+			})),
+		];
+
+		const reworkedJson: IApiDocumentedItemJson &
+			IApiItemContainerJson &
+			IApiNameMixinJson &
+			IApiPackageJson & { members: (IApiItemContainerJson & IApiNameMixinJson)[] } = {
+			projectFolderUrl: `https://github.com/discordjs/discord.js/tree/main/packages/${_package}`,
+			metadata: { ...context, tsdocConfig: context.tsdocConfiguration, schemaVersion: context.versionToDeserialize },
+			canonicalReference: `!${_package}`,
+			kind: ApiItemKind.Package,
+			name: _package,
+			members: [
+				{
+					members,
+					name: _package,
+					kind: ApiItemKind.EntryPoint,
+					canonicalReference: `${_package}!`,
+				},
+			],
+			docComment: '',
+		};
+
+		return Deserializer.deserialize(context, reworkedJson);
+	}
 }

packages/api-extractor-model/src/model/HeritageType.ts

@@ -38,7 +38,10 @@ export class HeritageType {
 	 */
 	public readonly excerpt: Excerpt;
 
-	public constructor(excerpt: Excerpt) {
+	public readonly typeParameters: string[];
+
+	public constructor(excerpt: Excerpt, typeParameters: string[]) {
 		this.excerpt = excerpt;
+		this.typeParameters = typeParameters;
 	}
 }

packages/api-extractor/README.md

@@ -1,4 +1,4 @@
-# @microsoft/api-extractor
+# @discordjs/api-extractor
 
 ![API Extractor](https://github.com/microsoft/rushstack/raw/main/common/wiki-images/api-extractor-title.png?raw=true)
 <br />
@@ -42,7 +42,7 @@ For more details and support resources, please visit: https://api-extractor.com/
 
 ## Links
 
-- [CHANGELOG.md](https://github.com/microsoft/rushstack/blob/main/apps/api-extractor/CHANGELOG.md) - Find
+- [CHANGELOG.md](https://github.com/discordjs/discord.js/blob/main/packages/api-extractor/CHANGELOG.md) - Find
   out what's new in the latest version
 - [API Reference](https://rushstack.io/pages/api/api-extractor/)
 

packages/api-extractor/extends/tsdoc-base.json

@@ -7,7 +7,7 @@
  * ```
  * {
  *   "$schema": "https://developer.microsoft.com/json-schemas/tsdoc/v0/tsdoc.schema.json",
- *   "extends": [ "@microsoft/api-extractor/extends/tsdoc-config.json" ],
+ *   "extends": [ "@discordjs/api-extractor/extends/tsdoc-config.json" ],
  *   . . .
  * }
  * ```

packages/api-extractor/src/analyzer/PackageMetadataManager.ts

@@ -131,7 +131,7 @@ export class PackageMetadataManager {
 			tsdocVersion: '0.12',
 			toolPackages: [
 				{
-					packageName: '@microsoft/api-extractor',
+					packageName: '@discordjs/api-extractor',
 					packageVersion: Extractor.version,
 				},
 			],

packages/api-extractor/src/analyzer/test/PackageMetadataManager.test.ts

@@ -121,5 +121,3 @@ describe(PackageMetadataManager.name, () => {
 		});
 	});
 });
-
-/* eslint-enable @typescript-eslint/typedef */

packages/api-extractor/src/api/ExtractorConfig.ts

@@ -142,7 +142,7 @@ export interface IExtractorConfigPrepareOptions {
 	/**
 	 * Allow customization of the tsdoc.json config file.  If omitted, this file will be loaded from its default
 	 * location.  If the file does not exist, then the standard definitions will be used from
-	 * `@microsoft/api-extractor/extends/tsdoc-base.json`.
+	 * `@discordjs/api-extractor/extends/tsdoc-base.json`.
 	 */
 	tsdocConfigFile?: TSDocConfigFile;
 }

packages/api-extractor/src/generators/ApiModelGenerator.ts

@@ -1,12 +1,14 @@
 // Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license.
 // See LICENSE in the project root for license information.
 
+import { existsSync } from 'node:fs';
 import * as path from 'node:path';
 import {
 	ApiModel,
 	ApiClass,
 	ApiPackage,
 	ApiEntryPoint,
+	ApiEvent,
 	ApiMethod,
 	ApiNamespace,
 	ApiInterface,
@@ -19,6 +21,7 @@ import {
 	ApiEnum,
 	ApiEnumMember,
 	type IExcerptTokenRange,
+	type IExcerptTokenRangeWithTypeParameters,
 	type IExcerptToken,
 	ApiConstructor,
 	ApiConstructSignature,
@@ -29,12 +32,17 @@ import {
 	ApiCallSignature,
 	type IApiTypeParameterOptions,
 	EnumMemberOrder,
+	ExcerptTokenKind,
+	Navigation,
 } from '@discordjs/api-extractor-model';
 import type * as tsdoc from '@microsoft/tsdoc';
-import { Path } from '@rushstack/node-core-library';
+import { TSDocParser } from '@microsoft/tsdoc';
+import { DeclarationReference } from '@microsoft/tsdoc/lib-commonjs/beta/DeclarationReference.js';
+import { JsonFile, Path } from '@rushstack/node-core-library';
 import * as ts from 'typescript';
 import type { AstDeclaration } from '../analyzer/AstDeclaration.js';
 import type { AstEntity } from '../analyzer/AstEntity.js';
+import type { AstImport } from '../analyzer/AstImport.js';
 import type { AstModule } from '../analyzer/AstModule.js';
 import { AstNamespaceImport } from '../analyzer/AstNamespaceImport.js';
 import { AstSymbol } from '../analyzer/AstSymbol.js';
@@ -46,10 +54,165 @@ import type { ISourceLocation } from '../collector/SourceMapper.js';
 import { DeclarationReferenceGenerator } from './DeclarationReferenceGenerator.js';
 import { ExcerptBuilder, type IExcerptBuilderNodeToCapture } from './ExcerptBuilder.js';
 
+type DocgenAccess = 'private' | 'protected' | 'public';
+type DocgenScope = 'global' | 'instance' | 'static';
+type DocgenDeprecated = boolean | string;
+
+interface DocgenMetaJson {
+	file: string;
+	line: number;
+	path: string;
+}
+
+interface DocgenTypeJson {
+	names?: string[] | undefined;
+}
+
+interface DocgenVarJson {
+	description?: string;
+	nullable?: boolean;
+	types?: string[][][];
+}
+type DocgenVarTypeJson = DocgenVarJson | string[][][];
+interface DocgenExceptionJson {
+	description?: string;
+	nullable?: boolean;
+	type: DocgenTypeJson;
+}
+
+interface DocgenExternalJson {
+	description: string;
+	meta: DocgenMetaJson;
+	name: string;
+	see?: string[];
+}
+
+interface DocgenTypedefJson {
+	access?: DocgenAccess;
+	deprecated?: DocgenDeprecated;
+	description: string;
+	meta: DocgenMetaJson;
+	name: string;
+	params?: DocgenParamJson[];
+	props?: DocgenParamJson[];
+	returns?: DocgenVarTypeJson[];
+	see?: string[];
+	type: DocgenVarTypeJson;
+}
+
+interface DocgenEventJson {
+	deprecated?: DocgenDeprecated;
+	description: string;
+	meta: DocgenMetaJson;
+	name: string;
+	params?: DocgenParamJson[];
+	see?: string[];
+}
+
+interface DocgenParamJson {
+	default?: string;
+	description: string;
+	name: string;
+	nullable?: boolean;
+	optional?: boolean;
+	type: DocgenVarTypeJson;
+	variable?: string;
+}
+
+interface DocgenConstructorJson {
+	access?: DocgenAccess;
+	description: string;
+	name: string;
+	params?: DocgenParamJson[];
+	see?: string[];
+}
+
+interface DocgenMethodJson {
+	abstract: boolean;
+	access?: DocgenAccess;
+	async?: boolean;
+	deprecated?: DocgenDeprecated;
+	description: string;
+	emits?: string[];
+	examples?: string[];
+	generator?: boolean;
+	implements?: string[];
+	inherited?: boolean;
+	inherits?: string;
+	meta: DocgenMetaJson;
+	name: string;
+	params?: DocgenParamJson[];
+	returns?: DocgenVarTypeJson[];
+	scope: DocgenScope;
+	see?: string[];
+	throws?: DocgenExceptionJson[];
+}
+
+interface DocgenPropertyJson {
+	abstract?: boolean;
+	access?: DocgenAccess;
+	default?: string;
+	deprecated?: DocgenDeprecated;
+	description: string;
+	meta: DocgenMetaJson;
+	name: string;
+	nullable?: boolean;
+	props?: DocgenPropertyJson[];
+	readonly?: boolean;
+	scope: DocgenScope;
+	see?: string[];
+	type: DocgenVarTypeJson;
+}
+interface DocgenClassJson {
+	abstract?: boolean;
+	access?: DocgenAccess;
+	construct: DocgenConstructorJson;
+	deprecated?: DocgenDeprecated | string;
+	description: string;
+	events?: DocgenEventJson[];
+	extends?: DocgenVarTypeJson;
+	implements?: DocgenVarTypeJson;
+	meta: DocgenMetaJson;
+	methods?: DocgenMethodJson[];
+	name: string;
+	props?: DocgenPropertyJson[];
+	see?: string[];
+}
+type DocgenInterfaceJson = DocgenClassJson;
+type DocgenContainerJson =
+	| DocgenClassJson
+	| DocgenConstructorJson
+	| DocgenInterfaceJson
+	| DocgenJson
+	| DocgenMethodJson
+	| DocgenTypedefJson;
+
+export interface DocgenJson {
+	classes: DocgenClassJson[];
+	externals: DocgenExternalJson[];
+	functions: DocgenMethodJson[];
+	interfaces: DocgenInterfaceJson[];
+	meta: {
+		date: number;
+		format: number;
+		generator: string;
+	};
+	typedefs: DocgenTypedefJson[];
+}
 interface IProcessAstEntityContext {
 	isExported: boolean;
 	name: string;
 	parentApiItem: ApiItemContainerMixin;
+	parentDocgenJson?: DocgenContainerJson | undefined;
+}
+
+const linkRegEx = /{@link\s(?<class>\w+)#(?<event>event:)?(?<prop>[\w()]+)(?<name>\s[^}]*)?}/g;
+function fixLinkTags(input?: string): string | undefined {
+	return input?.replaceAll(linkRegEx, '{@link $<class>.$<prop>$<name>}');
+}
+
+function filePathFromJson(meta: DocgenMetaJson): string {
+	return `${meta.path.slice('packages/discord.js/'.length)}/${meta.file}`;
 }
 
 export class ApiModelGenerator {
@@ -71,6 +234,12 @@ export class ApiModelGenerator {
 
 	public buildApiPackage(): ApiPackage {
 		const packageDocComment: tsdoc.DocComment | undefined = this._collector.workingPackage.tsdocComment;
+		let jsDocJson: DocgenJson | undefined;
+
+		const jsDocFilepath = `${this._collector.extractorConfig.apiJsonFilePath.slice(0, -8)}json`;
+		if (existsSync(jsDocFilepath)) {
+			jsDocJson = JsonFile.load(jsDocFilepath);
+		}
 
 		const apiPackage: ApiPackage = new ApiPackage({
 			name: this._collector.workingPackage.name,
@@ -92,6 +261,7 @@ export class ApiModelGenerator {
 					name: entity.nameForEmit!,
 					isExported: entity.exportedFromEntryPoint,
 					parentApiItem: apiEntryPoint,
+					parentDocgenJson: jsDocJson,
 				});
 			}
 		}
@@ -320,6 +490,7 @@ export class ApiModelGenerator {
 			const constructorDeclaration: ts.ConstructorDeclaration = astDeclaration.declaration as ts.ConstructorDeclaration;
 
 			const nodesToCapture: IExcerptBuilderNodeToCapture[] = [];
+			const parent = context.parentDocgenJson as DocgenClassJson | DocgenInterfaceJson | undefined;
 
 			const parameters: IApiParameterOptions[] = this._captureParameters(
 				nodesToCapture,
@@ -328,7 +499,15 @@ export class ApiModelGenerator {
 
 			const excerptTokens: IExcerptToken[] = this._buildExcerptTokens(astDeclaration, nodesToCapture);
 			const apiItemMetadata: ApiItemMetadata = this._collector.fetchApiItemMetadata(astDeclaration);
-			const docComment: tsdoc.DocComment | undefined = apiItemMetadata.tsdocComment;
+			const docComment: tsdoc.DocComment | undefined = parent?.construct
+				? new TSDocParser().parseString(
+						`/*+\n * ${fixLinkTags(parent.construct.description)}\n${
+							parent.construct.params
+								?.map((param) => ` * @param ${param.name} - ${fixLinkTags(param.description)}\n`)
+								.join('') ?? ''
+						} */`,
+				  ).docComment
+				: apiItemMetadata.tsdocComment;
 			const releaseTag: ReleaseTag = apiItemMetadata.effectiveReleaseTag;
 			const isProtected: boolean = (astDeclaration.modifierFlags & ts.ModifierFlags.Protected) !== 0;
 			const sourceLocation: ISourceLocation = this._getSourceLocation(constructorDeclaration);
@@ -340,8 +519,8 @@ export class ApiModelGenerator {
 				parameters,
 				overloadIndex,
 				excerptTokens,
-				fileUrlPath: sourceLocation.sourceFilePath,
+				fileUrlPath: parent ? filePathFromJson(parent.meta) : sourceLocation.sourceFilePath,
-				fileLine: sourceLocation.sourceFileLine,
+				fileLine: parent?.meta.line ?? sourceLocation.sourceFileLine,
 				fileColumn: sourceLocation.sourceFileColumn,
 			});
 
@@ -354,9 +533,14 @@ export class ApiModelGenerator {
 		const containerKey: string = ApiClass.getContainerKey(name);
 
 		let apiClass: ApiClass | undefined = parentApiItem.tryGetMemberByKey(containerKey) as ApiClass;
+		const parent = context.parentDocgenJson as DocgenJson | undefined;
+		const jsDoc = parent?.classes.find((_class) => _class.name === name);
 
 		if (apiClass === undefined) {
 			const classDeclaration: ts.ClassDeclaration = astDeclaration.declaration as ts.ClassDeclaration;
+			if (name === 'ActionRow') {
+				console.dir(classDeclaration.heritageClauses?.[0]?.types[0]?.typeArguments, { depth: 3 });
+			}
 
 			const nodesToCapture: IExcerptBuilderNodeToCapture[] = [];
 
@@ -365,18 +549,29 @@ export class ApiModelGenerator {
 				classDeclaration.typeParameters,
 			);
 
-			let extendsTokenRange: IExcerptTokenRange | undefined;
+			let extendsTokenRange: IExcerptTokenRangeWithTypeParameters | undefined;
-			const implementsTokenRanges: IExcerptTokenRange[] = [];
+			const implementsTokenRanges: IExcerptTokenRangeWithTypeParameters[] = [];
 
 			for (const heritageClause of classDeclaration.heritageClauses ?? []) {
 				if (heritageClause.token === ts.SyntaxKind.ExtendsKeyword) {
-					extendsTokenRange = ExcerptBuilder.createEmptyTokenRange();
+					extendsTokenRange = ExcerptBuilder.createEmptyTokenRangeWithTypeParameters();
 					if (heritageClause.types.length > 0) {
+						extendsTokenRange.typeParameters.push(
+							...(heritageClause.types[0]?.typeArguments?.map((typeArgument) =>
+								ts.isTypeReferenceNode(typeArgument) ? typeArgument.typeName.getText() : '',
+							) ?? []),
+						);
 						nodesToCapture.push({ node: heritageClause.types[0], tokenRange: extendsTokenRange });
 					}
 				} else if (heritageClause.token === ts.SyntaxKind.ImplementsKeyword) {
 					for (const heritageType of heritageClause.types) {
-						const implementsTokenRange: IExcerptTokenRange = ExcerptBuilder.createEmptyTokenRange();
+						const implementsTokenRange: IExcerptTokenRangeWithTypeParameters =
+							ExcerptBuilder.createEmptyTokenRangeWithTypeParameters();
+						implementsTokenRange.typeParameters.push(
+							...(heritageClause.types[0]?.typeArguments?.map((typeArgument) =>
+								ts.isTypeReferenceNode(typeArgument) ? typeArgument.typeName.getText() : '',
+							) ?? []),
+						);
 						implementsTokenRanges.push(implementsTokenRange);
 						nodesToCapture.push({ node: heritageType, tokenRange: implementsTokenRange });
 					}
@@ -385,7 +580,17 @@ export class ApiModelGenerator {
 
 			const excerptTokens: IExcerptToken[] = this._buildExcerptTokens(astDeclaration, nodesToCapture);
 			const apiItemMetadata: ApiItemMetadata = this._collector.fetchApiItemMetadata(astDeclaration);
-			const docComment: tsdoc.DocComment | undefined = apiItemMetadata.tsdocComment;
+			const docComment: tsdoc.DocComment | undefined = jsDoc
+				? new TSDocParser().parseString(
+						`/**\n * ${fixLinkTags(jsDoc.description)}\n${jsDoc.see?.map((see) => ` * @see ${see}\n`).join('') ?? ''}${
+							jsDoc.deprecated
+								? ` * @deprecated ${
+										typeof jsDoc.deprecated === 'string' ? fixLinkTags(jsDoc.deprecated) : jsDoc.deprecated
+								  }\n`
+								: ''
+						} */`,
+				  ).docComment
+				: apiItemMetadata.tsdocComment;
 			const releaseTag: ReleaseTag = apiItemMetadata.effectiveReleaseTag;
 			const isAbstract: boolean = (ts.getCombinedModifierFlags(classDeclaration) & ts.ModifierFlags.Abstract) !== 0;
 			const sourceLocation: ISourceLocation = this._getSourceLocation(classDeclaration);
@@ -400,8 +605,8 @@ export class ApiModelGenerator {
 				extendsTokenRange,
 				implementsTokenRanges,
 				isExported,
-				fileUrlPath: sourceLocation.sourceFilePath,
+				fileUrlPath: jsDoc ? filePathFromJson(jsDoc.meta) : sourceLocation.sourceFilePath,
-				fileLine: sourceLocation.sourceFileLine,
+				fileLine: jsDoc?.meta.line ?? sourceLocation.sourceFileLine,
 				fileColumn: sourceLocation.sourceFileColumn,
 			});
 
@@ -411,7 +616,12 @@ export class ApiModelGenerator {
 		this._processChildDeclarations(astDeclaration, {
 			...context,
 			parentApiItem: apiClass,
+			parentDocgenJson: jsDoc,
 		});
+
+		for (const event of jsDoc?.events ?? []) {
+			this._processApiEvent({ ...context, name: event.name, parentApiItem: apiClass, parentDocgenJson: jsDoc });
+		}
 	}
 
 	private _processApiConstructSignature(astDeclaration: AstDeclaration, context: IProcessAstEntityContext): void {
@@ -428,6 +638,7 @@ export class ApiModelGenerator {
 				astDeclaration.declaration as ts.ConstructSignatureDeclaration;
 
 			const nodesToCapture: IExcerptBuilderNodeToCapture[] = [];
+			const parent = context.parentDocgenJson as DocgenClassJson | DocgenInterfaceJson | undefined;
 
 			const returnTypeTokenRange: IExcerptTokenRange = ExcerptBuilder.createEmptyTokenRange();
 			nodesToCapture.push({ node: constructSignature.type, tokenRange: returnTypeTokenRange });
@@ -441,7 +652,15 @@ export class ApiModelGenerator {
 
 			const excerptTokens: IExcerptToken[] = this._buildExcerptTokens(astDeclaration, nodesToCapture);
 			const apiItemMetadata: ApiItemMetadata = this._collector.fetchApiItemMetadata(astDeclaration);
-			const docComment: tsdoc.DocComment | undefined = apiItemMetadata.tsdocComment;
+			const docComment: tsdoc.DocComment | undefined = parent?.construct
+				? new TSDocParser().parseString(
+						`/*+\n * ${fixLinkTags(parent.construct.description)}\n${
+							parent.construct.params
+								?.map((param) => ` * @param ${param.name} - ${fixLinkTags(param.description)}\n`)
+								.join('') ?? ''
+						} */`,
+				  ).docComment
+				: apiItemMetadata.tsdocComment;
 			const releaseTag: ReleaseTag = apiItemMetadata.effectiveReleaseTag;
 			const sourceLocation: ISourceLocation = this._getSourceLocation(constructSignature);
 
@@ -453,8 +672,8 @@ export class ApiModelGenerator {
 				overloadIndex,
 				excerptTokens,
 				returnTypeTokenRange,
-				fileUrlPath: sourceLocation.sourceFilePath,
+				fileUrlPath: parent ? filePathFromJson(parent.meta) : sourceLocation.sourceFilePath,
-				fileLine: sourceLocation.sourceFileLine,
+				fileLine: parent?.meta.line ?? sourceLocation.sourceFileLine,
 				fileColumn: sourceLocation.sourceFileColumn,
 			});
 
@@ -541,6 +760,8 @@ export class ApiModelGenerator {
 		const containerKey: string = ApiFunction.getContainerKey(name, overloadIndex);
 
 		let apiFunction: ApiFunction | undefined = parentApiItem.tryGetMemberByKey(containerKey) as ApiFunction;
+		const parent = context.parentDocgenJson as DocgenJson | undefined;
+		const jsDoc = parent?.functions.find((fun) => fun.name === name);
 
 		if (apiFunction === undefined) {
 			const functionDeclaration: ts.FunctionDeclaration = astDeclaration.declaration as ts.FunctionDeclaration;
@@ -562,7 +783,24 @@ export class ApiModelGenerator {
 
 			const excerptTokens: IExcerptToken[] = this._buildExcerptTokens(astDeclaration, nodesToCapture);
 			const apiItemMetadata: ApiItemMetadata = this._collector.fetchApiItemMetadata(astDeclaration);
-			const docComment: tsdoc.DocComment | undefined = apiItemMetadata.tsdocComment;
+			const docComment: tsdoc.DocComment | undefined = jsDoc
+				? new TSDocParser().parseString(
+						`/**\n * ${fixLinkTags(jsDoc.description)}\n${
+							jsDoc.params?.map((param) => ` * @param ${param.name} - ${fixLinkTags(param.description)}\n`).join('') ??
+							''
+						}${
+							jsDoc.returns?.length && !Array.isArray(jsDoc.returns[0])
+								? ` * @returns ${fixLinkTags(jsDoc.returns[0]!.description ?? '')}`
+								: ''
+						}${
+							jsDoc.deprecated
+								? ` * @deprecated ${
+										typeof jsDoc.deprecated === 'string' ? fixLinkTags(jsDoc.deprecated) : jsDoc.deprecated
+								  }\n`
+								: ''
+						} */`,
+				  ).docComment
+				: apiItemMetadata.tsdocComment;
 			const releaseTag: ReleaseTag = apiItemMetadata.effectiveReleaseTag;
 			const sourceLocation: ISourceLocation = this._getSourceLocation(functionDeclaration);
 
@@ -576,8 +814,8 @@ export class ApiModelGenerator {
 				excerptTokens,
 				returnTypeTokenRange,
 				isExported,
-				fileUrlPath: sourceLocation.sourceFilePath,
+				fileUrlPath: jsDoc ? filePathFromJson(jsDoc.meta) : sourceLocation.sourceFilePath,
-				fileLine: sourceLocation.sourceFileLine,
+				fileLine: jsDoc?.meta.line ?? sourceLocation.sourceFileLine,
 				fileColumn: sourceLocation.sourceFileColumn,
 			});
 
@@ -633,6 +871,9 @@ export class ApiModelGenerator {
 		const containerKey: string = ApiInterface.getContainerKey(name);
 
 		let apiInterface: ApiInterface | undefined = parentApiItem.tryGetMemberByKey(containerKey) as ApiInterface;
+		const parent = context.parentDocgenJson as DocgenJson | undefined;
+		const jsDoc =
+			parent?.interfaces.find((int) => int.name === name) ?? parent?.typedefs.find((int) => int.name === name);
 
 		if (apiInterface === undefined) {
 			const interfaceDeclaration: ts.InterfaceDeclaration = astDeclaration.declaration as ts.InterfaceDeclaration;
@@ -644,12 +885,18 @@ export class ApiModelGenerator {
 				interfaceDeclaration.typeParameters,
 			);
 
-			const extendsTokenRanges: IExcerptTokenRange[] = [];
+			const extendsTokenRanges: IExcerptTokenRangeWithTypeParameters[] = [];
 
 			for (const heritageClause of interfaceDeclaration.heritageClauses ?? []) {
 				if (heritageClause.token === ts.SyntaxKind.ExtendsKeyword) {
 					for (const heritageType of heritageClause.types) {
-						const extendsTokenRange: IExcerptTokenRange = ExcerptBuilder.createEmptyTokenRange();
+						const extendsTokenRange: IExcerptTokenRangeWithTypeParameters =
+							ExcerptBuilder.createEmptyTokenRangeWithTypeParameters();
+						extendsTokenRange.typeParameters.push(
+							...(heritageClause.types[0]?.typeArguments?.map((typeArgument) =>
+								ts.isTypeReferenceNode(typeArgument) ? typeArgument.typeName.getText() : '',
+							) ?? []),
+						);
 						extendsTokenRanges.push(extendsTokenRange);
 						nodesToCapture.push({ node: heritageType, tokenRange: extendsTokenRange });
 					}
@@ -658,7 +905,17 @@ export class ApiModelGenerator {
 
 			const excerptTokens: IExcerptToken[] = this._buildExcerptTokens(astDeclaration, nodesToCapture);
 			const apiItemMetadata: ApiItemMetadata = this._collector.fetchApiItemMetadata(astDeclaration);
-			const docComment: tsdoc.DocComment | undefined = apiItemMetadata.tsdocComment;
+			const docComment: tsdoc.DocComment | undefined = jsDoc
+				? new TSDocParser().parseString(
+						`/**\n * ${fixLinkTags(jsDoc.description)}\n${jsDoc.see?.map((see) => ` * @see ${see}\n`).join('') ?? ''}${
+							jsDoc.deprecated
+								? ` * @deprecated ${
+										typeof jsDoc.deprecated === 'string' ? fixLinkTags(jsDoc.deprecated) : jsDoc.deprecated
+								  }\n`
+								: ''
+						} */`,
+				  ).docComment
+				: apiItemMetadata.tsdocComment;
 			const releaseTag: ReleaseTag = apiItemMetadata.effectiveReleaseTag;
 			const sourceLocation: ISourceLocation = this._getSourceLocation(interfaceDeclaration);
 
@@ -670,8 +927,8 @@ export class ApiModelGenerator {
 				typeParameters,
 				extendsTokenRanges,
 				isExported,
-				fileUrlPath: sourceLocation.sourceFilePath,
+				fileUrlPath: jsDoc ? filePathFromJson(jsDoc.meta) : sourceLocation.sourceFilePath,
-				fileLine: sourceLocation.sourceFileLine,
+				fileLine: jsDoc?.meta.line ?? sourceLocation.sourceFileLine,
 				fileColumn: sourceLocation.sourceFileColumn,
 			});
 
@@ -681,6 +938,7 @@ export class ApiModelGenerator {
 		this._processChildDeclarations(astDeclaration, {
 			...context,
 			parentApiItem: apiInterface,
+			parentDocgenJson: jsDoc,
 		});
 	}
 
@@ -691,6 +949,8 @@ export class ApiModelGenerator {
 		const containerKey: string = ApiMethod.getContainerKey(name, isStatic, overloadIndex);
 
 		let apiMethod: ApiMethod | undefined = parentApiItem.tryGetMemberByKey(containerKey) as ApiMethod;
+		const parent = context.parentDocgenJson as DocgenClassJson | DocgenInterfaceJson | undefined;
+		const jsDoc = parent?.methods?.find((method) => method.name === name);
 
 		if (apiMethod === undefined) {
 			const methodDeclaration: ts.MethodDeclaration = astDeclaration.declaration as ts.MethodDeclaration;
@@ -709,7 +969,24 @@ export class ApiModelGenerator {
 
 			const excerptTokens: IExcerptToken[] = this._buildExcerptTokens(astDeclaration, nodesToCapture);
 			const apiItemMetadata: ApiItemMetadata = this._collector.fetchApiItemMetadata(astDeclaration);
-			const docComment: tsdoc.DocComment | undefined = apiItemMetadata.tsdocComment;
+			const docComment: tsdoc.DocComment | undefined = jsDoc
+				? new TSDocParser().parseString(
+						`/**\n * ${fixLinkTags(jsDoc.description)}\n${
+							jsDoc.params?.map((param) => ` * @param ${param.name} - ${fixLinkTags(param.description)}\n`).join('') ??
+							''
+						}${
+							jsDoc.returns?.length && !Array.isArray(jsDoc.returns[0])
+								? ` * @returns ${fixLinkTags(jsDoc.returns[0]!.description ?? '')}`
+								: ''
+						}${
+							jsDoc.deprecated
+								? ` * @deprecated ${
+										typeof jsDoc.deprecated === 'string' ? fixLinkTags(jsDoc.deprecated) : jsDoc.deprecated
+								  }\n`
+								: ''
+						} */`,
+				  ).docComment
+				: apiItemMetadata.tsdocComment;
 			const releaseTag: ReleaseTag = apiItemMetadata.effectiveReleaseTag;
 			if (releaseTag === ReleaseTag.Internal || releaseTag === ReleaseTag.Alpha) {
 				return; // trim out items marked as "@internal" or "@alpha"
@@ -733,8 +1010,8 @@ export class ApiModelGenerator {
 				overloadIndex,
 				excerptTokens,
 				returnTypeTokenRange,
-				fileUrlPath: sourceLocation.sourceFilePath,
+				fileUrlPath: jsDoc ? filePathFromJson(jsDoc.meta) : sourceLocation.sourceFilePath,
-				fileLine: sourceLocation.sourceFileLine,
+				fileLine: jsDoc?.meta.line ?? sourceLocation.sourceFileLine,
 				fileColumn: sourceLocation.sourceFileColumn,
 			});
 
@@ -750,6 +1027,8 @@ export class ApiModelGenerator {
 		let apiMethodSignature: ApiMethodSignature | undefined = parentApiItem.tryGetMemberByKey(
 			containerKey,
 		) as ApiMethodSignature;
+		const parent = context.parentDocgenJson as DocgenClassJson | DocgenInterfaceJson | undefined;
+		const jsDoc = parent?.methods?.find((method) => method.name === name);
 
 		if (apiMethodSignature === undefined) {
 			const methodSignature: ts.MethodSignature = astDeclaration.declaration as ts.MethodSignature;
@@ -768,7 +1047,24 @@ export class ApiModelGenerator {
 
 			const excerptTokens: IExcerptToken[] = this._buildExcerptTokens(astDeclaration, nodesToCapture);
 			const apiItemMetadata: ApiItemMetadata = this._collector.fetchApiItemMetadata(astDeclaration);
-			const docComment: tsdoc.DocComment | undefined = apiItemMetadata.tsdocComment;
+			const docComment: tsdoc.DocComment | undefined = jsDoc
+				? new TSDocParser().parseString(
+						`/**\n * ${fixLinkTags(jsDoc.description)}\n${
+							jsDoc.params?.map((param) => ` * @param ${param.name} - ${fixLinkTags(param.description)}\n`).join('') ??
+							''
+						}${
+							jsDoc.returns?.length && !Array.isArray(jsDoc.returns[0])
+								? ` * @returns ${fixLinkTags(jsDoc.returns[0]!.description ?? '')}`
+								: ''
+						}${
+							jsDoc.deprecated
+								? ` * @deprecated ${
+										typeof jsDoc.deprecated === 'string' ? fixLinkTags(jsDoc.deprecated) : jsDoc.deprecated
+								  }\n`
+								: ''
+						} */`,
+				  ).docComment
+				: apiItemMetadata.tsdocComment;
 			const releaseTag: ReleaseTag = apiItemMetadata.effectiveReleaseTag;
 			const isOptional: boolean = (astDeclaration.astSymbol.followedSymbol.flags & ts.SymbolFlags.Optional) !== 0;
 			const sourceLocation: ISourceLocation = this._getSourceLocation(methodSignature);
@@ -783,8 +1079,8 @@ export class ApiModelGenerator {
 				overloadIndex,
 				excerptTokens,
 				returnTypeTokenRange,
-				fileUrlPath: sourceLocation.sourceFilePath,
+				fileUrlPath: jsDoc ? filePathFromJson(jsDoc.meta) : sourceLocation.sourceFilePath,
-				fileLine: sourceLocation.sourceFileLine,
+				fileLine: jsDoc?.meta.line ?? sourceLocation.sourceFileLine,
 				fileColumn: sourceLocation.sourceFileColumn,
 			});
 
@@ -830,6 +1126,8 @@ export class ApiModelGenerator {
 		const containerKey: string = ApiProperty.getContainerKey(name, isStatic);
 
 		let apiProperty: ApiProperty | undefined = parentApiItem.tryGetMemberByKey(containerKey) as ApiProperty;
+		const parent = context.parentDocgenJson as DocgenClassJson | DocgenInterfaceJson | DocgenTypedefJson | undefined;
+		const jsDoc = parent?.props?.find((prop) => prop.name === name);
 
 		if (apiProperty === undefined) {
 			const declaration: ts.Declaration = astDeclaration.declaration;
@@ -857,7 +1155,19 @@ export class ApiModelGenerator {
 
 			const excerptTokens: IExcerptToken[] = this._buildExcerptTokens(astDeclaration, nodesToCapture);
 			const apiItemMetadata: ApiItemMetadata = this._collector.fetchApiItemMetadata(astDeclaration);
-			const docComment: tsdoc.DocComment | undefined = apiItemMetadata.tsdocComment;
+			const docComment: tsdoc.DocComment | undefined = jsDoc
+				? new TSDocParser().parseString(
+						`/**\n * ${fixLinkTags(jsDoc.description)}\n${
+							'see' in jsDoc ? jsDoc.see.map((see) => ` * @see ${see}\n`).join('') : ''
+						}${'readonly' in jsDoc && jsDoc.readonly ? ' * @readonly\n' : ''}${
+							'deprecated' in jsDoc && jsDoc.deprecated
+								? ` * @deprecated ${
+										typeof jsDoc.deprecated === 'string' ? fixLinkTags(jsDoc.deprecated) : jsDoc.deprecated
+								  }\n`
+								: ''
+						} */`,
+				  ).docComment
+				: apiItemMetadata.tsdocComment;
 			const releaseTag: ReleaseTag = apiItemMetadata.effectiveReleaseTag;
 			const isOptional: boolean = (astDeclaration.astSymbol.followedSymbol.flags & ts.SymbolFlags.Optional) !== 0;
 			const isProtected: boolean = (astDeclaration.modifierFlags & ts.ModifierFlags.Protected) !== 0;
@@ -877,8 +1187,8 @@ export class ApiModelGenerator {
 				excerptTokens,
 				propertyTypeTokenRange,
 				initializerTokenRange,
-				fileUrlPath: sourceLocation.sourceFilePath,
+				fileUrlPath: jsDoc && 'meta' in jsDoc ? filePathFromJson(jsDoc.meta) : sourceLocation.sourceFilePath,
-				fileLine: sourceLocation.sourceFileLine,
+				fileLine: jsDoc && 'meta' in jsDoc ? jsDoc.meta.line : sourceLocation.sourceFileLine,
 				fileColumn: sourceLocation.sourceFileColumn,
 			});
 			parentApiItem.addMember(apiProperty);
@@ -895,6 +1205,8 @@ export class ApiModelGenerator {
 		let apiPropertySignature: ApiPropertySignature | undefined = parentApiItem.tryGetMemberByKey(
 			containerKey,
 		) as ApiPropertySignature;
+		const parent = context.parentDocgenJson as DocgenInterfaceJson | DocgenPropertyJson | DocgenTypedefJson | undefined;
+		const jsDoc = parent?.props?.find((prop) => prop.name === name);
 
 		if (apiPropertySignature === undefined) {
 			const propertySignature: ts.PropertySignature = astDeclaration.declaration as ts.PropertySignature;
@@ -906,7 +1218,15 @@ export class ApiModelGenerator {
 
 			const excerptTokens: IExcerptToken[] = this._buildExcerptTokens(astDeclaration, nodesToCapture);
 			const apiItemMetadata: ApiItemMetadata = this._collector.fetchApiItemMetadata(astDeclaration);
-			const docComment: tsdoc.DocComment | undefined = apiItemMetadata.tsdocComment;
+			const docComment: tsdoc.DocComment | undefined = jsDoc
+				? new TSDocParser().parseString(
+						`/**\n * ${fixLinkTags(jsDoc.description)}\n${
+							'see' in jsDoc ? jsDoc.see.map((see) => ` * @see ${see}\n`).join('') : ''
+						}${'readonly' in jsDoc && jsDoc.readonly ? ' * @readonly\n' : ''}${
+							'deprecated' in jsDoc && jsDoc.deprecated ? ` * @deprecated ${jsDoc.deprecated}\n` : ''
+						} */`,
+				  ).docComment
+				: apiItemMetadata.tsdocComment;
 			const releaseTag: ReleaseTag = apiItemMetadata.effectiveReleaseTag;
 			const isOptional: boolean = (astDeclaration.astSymbol.followedSymbol.flags & ts.SymbolFlags.Optional) !== 0;
 			const isReadonly: boolean = this._isReadonly(astDeclaration);
@@ -920,8 +1240,8 @@ export class ApiModelGenerator {
 				excerptTokens,
 				propertyTypeTokenRange,
 				isReadonly,
-				fileUrlPath: sourceLocation.sourceFilePath,
+				fileUrlPath: jsDoc && 'meta' in jsDoc ? filePathFromJson(jsDoc.meta) : sourceLocation.sourceFilePath,
-				fileLine: sourceLocation.sourceFileLine,
+				fileLine: jsDoc && 'meta' in jsDoc ? jsDoc.meta.line : sourceLocation.sourceFileLine,
 				fileColumn: sourceLocation.sourceFileColumn,
 			});
 
@@ -938,6 +1258,11 @@ export class ApiModelGenerator {
 		const containerKey: string = ApiTypeAlias.getContainerKey(name);
 
 		let apiTypeAlias: ApiTypeAlias | undefined = parentApiItem.tryGetMemberByKey(containerKey) as ApiTypeAlias;
+		const parent = context.parentDocgenJson as DocgenJson | undefined;
+		const jsDoc =
+			parent?.typedefs.find((type) => type.name === name) ??
+			parent?.functions.find((func) => func.name === name) ??
+			parent?.interfaces.find((clas) => clas.name === name);
 
 		if (apiTypeAlias === undefined) {
 			const typeAliasDeclaration: ts.TypeAliasDeclaration = astDeclaration.declaration as ts.TypeAliasDeclaration;
@@ -954,7 +1279,19 @@ export class ApiModelGenerator {
 
 			const excerptTokens: IExcerptToken[] = this._buildExcerptTokens(astDeclaration, nodesToCapture);
 			const apiItemMetadata: ApiItemMetadata = this._collector.fetchApiItemMetadata(astDeclaration);
-			const docComment: tsdoc.DocComment | undefined = apiItemMetadata.tsdocComment;
+			const docComment: tsdoc.DocComment | undefined = jsDoc
+				? new TSDocParser().parseString(
+						`/**\n * ${fixLinkTags(jsDoc.description) ?? ''}\n${
+							'params' in jsDoc
+								? jsDoc.params.map((param) => ` * @param ${param.name} - ${fixLinkTags(param.description)}\n`).join('')
+								: ''
+						}${
+							'returns' in jsDoc
+								? jsDoc.returns.map((ret) => ` * @returns ${Array.isArray(ret) ? '' : fixLinkTags(ret.description)}\n`)
+								: ''
+						} */`,
+				  ).docComment
+				: apiItemMetadata.tsdocComment;
 			const releaseTag: ReleaseTag = apiItemMetadata.effectiveReleaseTag;
 			const sourceLocation: ISourceLocation = this._getSourceLocation(typeAliasDeclaration);
 
@@ -966,8 +1303,8 @@ export class ApiModelGenerator {
 				excerptTokens,
 				typeTokenRange,
 				isExported,
-				fileUrlPath: sourceLocation.sourceFilePath,
+				fileUrlPath: jsDoc ? filePathFromJson(jsDoc.meta) : sourceLocation.sourceFilePath,
-				fileLine: sourceLocation.sourceFileLine,
+				fileLine: jsDoc?.meta.line ?? sourceLocation.sourceFileLine,
 				fileColumn: sourceLocation.sourceFileColumn,
 			});
 
@@ -1021,6 +1358,94 @@ export class ApiModelGenerator {
 		}
 	}
 
+	// events aren't part of typescript, we only get them from docgen JSON here
+	private _processApiEvent(context: IProcessAstEntityContext): void {
+		const { name, parentApiItem } = context;
+		const containerKey: string = ApiProperty.getContainerKey(name, false);
+
+		let apiEvent: ApiEvent | undefined = parentApiItem.tryGetMemberByKey(containerKey) as ApiEvent;
+		const parent = context.parentDocgenJson as DocgenClassJson | DocgenInterfaceJson | undefined;
+		const jsDoc = parent?.events?.find((prop) => prop.name === name);
+
+		if (apiEvent === undefined && jsDoc) {
+			const excerptTokens: IExcerptToken[] = [
+				{
+					kind: ExcerptTokenKind.Content,
+					text: `on('${name}', (${
+						jsDoc.params?.length ? `${jsDoc.params[0]?.name}${jsDoc.params[0]?.nullable ? '?' : ''}: ` : ') => {})'
+					}`,
+				},
+			];
+			const parameters: IApiParameterOptions[] = [];
+			for (let index = 0; index < (jsDoc.params?.length ?? 0) - 1; index++) {
+				const parameter = jsDoc.params![index]!;
+				const newTokens = this._mapVarType(parameter.type);
+				parameters.push({
+					parameterName: parameter.name,
+					parameterTypeTokenRange: {
+						startIndex: excerptTokens.length,
+						endIndex: excerptTokens.length + newTokens.length,
+					},
+					isOptional: Boolean(parameter.optional),
+					isRest: parameter.name.startsWith('...'),
+				});
+				excerptTokens.push(...newTokens);
+				excerptTokens.push({
+					kind: ExcerptTokenKind.Content,
+					text: `, ${jsDoc.params![index + 1]?.name}${jsDoc.params![index + 1]!.optional ? '?' : ''}: `,
+				});
+			}
+
+			if (jsDoc.params?.length) {
+				const parameter = jsDoc.params![jsDoc.params.length - 1]!;
+				const newTokens = this._mapVarType(parameter.type);
+				parameters.push({
+					parameterName: parameter.name,
+					parameterTypeTokenRange: {
+						startIndex: excerptTokens.length,
+						endIndex: excerptTokens.length + newTokens.length,
+					},
+					isOptional: Boolean(parameter.optional),
+					isRest: parameter.name.startsWith('...'),
+				});
+				excerptTokens.push(...newTokens);
+				excerptTokens.push({
+					kind: ExcerptTokenKind.Content,
+					text: `) => {})`,
+				});
+			}
+
+			const docComment: tsdoc.DocComment | undefined = new TSDocParser().parseString(
+				`/**\n * ${fixLinkTags(jsDoc.description)}\n${
+					jsDoc.params?.map((param) => ` * @param ${param.name} - ${fixLinkTags(param.description)}\n`).join('') ?? ''
+				}${'see' in jsDoc ? jsDoc.see.map((see) => ` * @see ${see}\n`).join('') : ''}${
+					'deprecated' in jsDoc && jsDoc.deprecated
+						? ` * @deprecated ${
+								typeof jsDoc.deprecated === 'string' ? fixLinkTags(jsDoc.deprecated) : jsDoc.deprecated
+						  }\n`
+						: ''
+				} */`,
+			).docComment;
+			const releaseTag: ReleaseTag = ReleaseTag.Public;
+
+			apiEvent = new ApiEvent({
+				name,
+				docComment,
+				releaseTag,
+				excerptTokens,
+				overloadIndex: 0,
+				parameters,
+				fileUrlPath: filePathFromJson(jsDoc.meta),
+				fileLine: jsDoc.meta.line,
+				fileColumn: 0,
+			});
+			parentApiItem.addMember(apiEvent);
+		} else {
+			// If the event was already declared before (via a merged interface declaration),
+			// we assume its signature is identical, because the language requires that.
+		}
+	}
+
 	/**
 	 * @param astDeclaration - The declaration
 	 * @param nodesToCapture - A list of child nodes whose token ranges we want to capture
@@ -1131,4 +1556,43 @@ export class ApiModelGenerator {
 		);
 		return sourceLocation;
 	}
+
+	private _mapVarType(typey: DocgenVarTypeJson): IExcerptToken[] {
+		const mapper = Array.isArray(typey) ? typey : typey.types ?? [];
+		const lookup: { [K in ts.SyntaxKind]?: string } = {
+			[ts.SyntaxKind.ClassDeclaration]: 'class',
+			[ts.SyntaxKind.InterfaceDeclaration]: 'interface',
+			[ts.SyntaxKind.TypeAliasDeclaration]: 'type',
+		};
+		return mapper.flatMap((typ) =>
+			typ.reduce<IExcerptToken[]>(
+				(arr, [type, symbol]) => [
+					...arr,
+					{
+						kind: ExcerptTokenKind.Reference,
+						text: type ?? 'unknown',
+						canonicalReference: DeclarationReference.package(this._apiModel.packages[0]!.name)
+							.addNavigationStep(Navigation.Members as any, DeclarationReference.parseComponent(type ?? 'unknown'))
+							.withMeaning(
+								lookup[
+									(
+										(this._collector.entities.find(
+											(entity) => entity.nameForEmit === type && 'astDeclarations' in entity.astEntity,
+										)?.astEntity as AstSymbol | undefined) ??
+										(
+											this._collector.entities.find(
+												(entity) => entity.nameForEmit === type && 'astSymbol' in entity.astEntity,
+											)?.astEntity as AstImport | undefined
+										)?.astSymbol
+									)?.astDeclarations[0]?.declaration.kind ?? ts.SyntaxKind.ClassDeclaration
+								] ?? ('class' as any),
+							)
+							.toString(),
+					},
+					{ kind: ExcerptTokenKind.Content, text: symbol ?? '' },
+				],
+				[],
+			),
+		);
+	}
 }

packages/api-extractor/src/generators/ExcerptBuilder.ts

@@ -1,7 +1,12 @@
 // Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license.
 // See LICENSE in the project root for license information.
 
-import { ExcerptTokenKind, type IExcerptToken, type IExcerptTokenRange } from '@discordjs/api-extractor-model';
+import {
+	ExcerptTokenKind,
+	type IExcerptToken,
+	type IExcerptTokenRange,
+	type IExcerptTokenRangeWithTypeParameters,
+} from '@discordjs/api-extractor-model';
 import type { DeclarationReference } from '@microsoft/tsdoc/lib-commonjs/beta/DeclarationReference';
 import * as ts from 'typescript';
 import type { AstDeclaration } from '../analyzer/AstDeclaration.js';
@@ -126,6 +131,10 @@ export class ExcerptBuilder {
 		return { startIndex: 0, endIndex: 0 };
 	}
 
+	public static createEmptyTokenRangeWithTypeParameters(): IExcerptTokenRangeWithTypeParameters {
+		return { startIndex: 0, endIndex: 0, typeParameters: [] };
+	}
+
 	private static _buildSpan(excerptTokens: IExcerptToken[], span: Span, state: IBuildSpanState): boolean {
 		if (span.kind === ts.SyntaxKind.JSDocComment) {
 			// Discard any comments

packages/api-extractor/src/index.ts

@@ -3,7 +3,7 @@
 
 /**
  * API Extractor helps with validation, documentation, and reviewing of the exported API for a TypeScript library.
- * The `@microsoft/api-extractor` package provides the command-line tool.  It also exposes a developer API that you
+ * The `@discordjs/api-extractor` package provides the command-line tool.  It also exposes a developer API that you
  * can use to invoke API Extractor programmatically.
  *
  * @packageDocumentation

packages/discord.js/api-extractor.json

@@ -0,0 +1,7 @@
+{
+  "extends": "../../api-extractor.json",
+  "mainEntryPointFilePath": "<projectFolder>/typings/index.d.ts",
+  "docModel": {
+    "projectFolderUrl": "https://github.com/discordjs/discord.js/tree/main/packages/discord.js"
+  }
+}

packages/discord.js/package.json

@@ -9,8 +9,9 @@
     "lint": "prettier --check . && tslint typings/index.d.ts && cross-env ESLINT_USE_FLAT_CONFIG=false eslint --format=pretty src",
     "format": "prettier --write . && cross-env ESLINT_USE_FLAT_CONFIG=false eslint --fix --format=pretty src",
     "fmt": "pnpm run format",
-    "docs": "docgen -i './src/*.js' './src/**/*.js' -c ./docs/index.json -r ../../ -o ./docs/docs.json",
+    "docs": "docgen -i './src/*.js' './src/**/*.js' -c ./docs/index.json -r ../../ -o ./docs/docs.json && pnpm run docs:new",
     "docs:test": "docgen -i './src/*.js' './src/**/*.js' -c ./docs/index.json -r ../../",
+    "docs:new": "api-extractor -d run --local",
     "prepack": "pnpm run lint && pnpm run test",
     "changelog": "git cliff --prepend ./CHANGELOG.md -u -c ./cliff.toml -r ../../ --include-path 'packages/discord.js/*'",
     "release": "cliff-jumper"
@@ -68,6 +69,7 @@
   },
   "devDependencies": {
     "@discordjs/docgen": "workspace:^",
+    "@discordjs/api-extractor": "workspace:^",
     "@favware/cliff-jumper": "2.2.1",
     "@types/node": "16.18.60",
     "cross-env": "^7.0.3",

packages/discord.js/typings/tsdoc-metadata.json

@@ -0,0 +1,11 @@
+// This file is read by tools that parse documentation comments conforming to the TSDoc standard.
+// It should be published with your NPM package.  It should not be tracked by Git.
+{
+  "tsdocVersion": "0.12",
+  "toolPackages": [
+    {
+      "packageName": "@discordjs/api-extractor",
+      "packageVersion": "7.38.1"
+    }
+  ]
+}

packages/docgen/bin/index.js

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+require('../dist/bin/index.js');

packages/docgen/bin/index.ts

@@ -8,6 +8,7 @@ import { build } from '../src/index.js';
 export interface CLIOptions {
 	custom: string;
 	input: string[];
+	newOutput: string;
 	output: string;
 	root: string;
 	typescript: boolean;

packages/docgen/package.json

@@ -8,10 +8,9 @@
 		"lint": "prettier --check . && cross-env TIMING=1 eslint --format=pretty src",
 		"format": "prettier --write . && cross-env TIMING=1 eslint --fix --format=pretty src",
 		"fmt": "pnpm run format",
-		"prepare": "pnpm run build",
 		"prepack": "pnpm run format && pnpm run build"
 	},
-	"bin": "./dist/bin/index.js",
+	"bin": "./bin/index.js",
 	"exports": {
 		".": {
 			"require": {

packages/docgen/src/documentation.ts

@@ -268,5 +268,185 @@ export class Documentation {
 		};
 	}
 
+	public serializeNew() {
+		return {
+			metadata: {
+				toolPackage: '@discordjs/docgen',
+				toolVersion: Documentation.FORMAT_VERSION,
+				schemaVersion: 1_011,
+				oldestForwardsCompatibleVersion: 1_001,
+				tsdocConfig: {
+					$schema: 'https://developer.microsoft.com/json-schemas/tsdoc/v0/tsdoc.schema.json',
+					noStandardTags: true,
+					tagDefinitions: [
+						{
+							tagName: '@alpha',
+							syntaxKind: 'modifier',
+						},
+						{
+							tagName: '@beta',
+							syntaxKind: 'modifier',
+						},
+						{
+							tagName: '@defaultValue',
+							syntaxKind: 'block',
+						},
+						{
+							tagName: '@decorator',
+							syntaxKind: 'block',
+							allowMultiple: true,
+						},
+						{
+							tagName: '@deprecated',
+							syntaxKind: 'block',
+						},
+						{
+							tagName: '@eventProperty',
+							syntaxKind: 'modifier',
+						},
+						{
+							tagName: '@example',
+							syntaxKind: 'block',
+							allowMultiple: true,
+						},
+						{
+							tagName: '@experimental',
+							syntaxKind: 'modifier',
+						},
+						{
+							tagName: '@inheritDoc',
+							syntaxKind: 'inline',
+						},
+						{
+							tagName: '@internal',
+							syntaxKind: 'modifier',
+						},
+						{
+							tagName: '@label',
+							syntaxKind: 'inline',
+						},
+						{
+							tagName: '@link',
+							syntaxKind: 'inline',
+							allowMultiple: true,
+						},
+						{
+							tagName: '@override',
+							syntaxKind: 'modifier',
+						},
+						{
+							tagName: '@packageDocumentation',
+							syntaxKind: 'modifier',
+						},
+						{
+							tagName: '@param',
+							syntaxKind: 'block',
+							allowMultiple: true,
+						},
+						{
+							tagName: '@privateRemarks',
+							syntaxKind: 'block',
+						},
+						{
+							tagName: '@public',
+							syntaxKind: 'modifier',
+						},
+						{
+							tagName: '@readonly',
+							syntaxKind: 'modifier',
+						},
+						{
+							tagName: '@remarks',
+							syntaxKind: 'block',
+						},
+						{
+							tagName: '@returns',
+							syntaxKind: 'block',
+						},
+						{
+							tagName: '@sealed',
+							syntaxKind: 'modifier',
+						},
+						{
+							tagName: '@see',
+							syntaxKind: 'block',
+						},
+						{
+							tagName: '@throws',
+							syntaxKind: 'block',
+							allowMultiple: true,
+						},
+						{
+							tagName: '@typeParam',
+							syntaxKind: 'block',
+							allowMultiple: true,
+						},
+						{
+							tagName: '@virtual',
+							syntaxKind: 'modifier',
+						},
+						{
+							tagName: '@betaDocumentation',
+							syntaxKind: 'modifier',
+						},
+						{
+							tagName: '@internalRemarks',
+							syntaxKind: 'block',
+						},
+						{
+							tagName: '@preapproved',
+							syntaxKind: 'modifier',
+						},
+					],
+					supportForTags: {
+						'@alpha': true,
+						'@beta': true,
+						'@defaultValue': true,
+						'@decorator': true,
+						'@deprecated': true,
+						'@eventProperty': true,
+						'@example': true,
+						'@experimental': true,
+						'@inheritDoc': true,
+						'@internal': true,
+						'@label': true,
+						'@link': true,
+						'@override': true,
+						'@packageDocumentation': true,
+						'@param': true,
+						'@privateRemarks': true,
+						'@public': true,
+						'@readonly': true,
+						'@remarks': true,
+						'@returns': true,
+						'@sealed': true,
+						'@see': true,
+						'@throws': true,
+						'@typeParam': true,
+						'@virtual': true,
+						'@betaDocumentation': true,
+						'@internalRemarks': true,
+						'@preapproved': true,
+					},
+					reportUnsupportedHtmlElements: false,
+				},
+			},
+			projectFolderUrl: 'https://github.com/discordjs/discord.js/tree/main/packages/discord.js',
+			kind: 'Package',
+			canonicalReference: 'discord.js!',
+			docComment: '',
+			name: 'discord.js',
+			preserveMemberOrder: false,
+			members: [
+				...[...this.classes.values()].map((_class) => _class.serialize()),
+				...[...this.functions.values()].map((_function) => _function.serialize()),
+				...[...this.interfaces.values()].map((_interface) => _interface.serialize()),
+				...[...this.typedefs.values()].map((_typedef) => _typedef.serialize()),
+				...[...this.externals.values()].map((_external) => _external.serialize()),
+			],
+			custom: this.custom,
+		};
+	}
+
 	public static readonly FORMAT_VERSION = 30;
 }

packages/docgen/src/index.ts

@@ -17,7 +17,7 @@ interface CustomFiles {
 	path?: string;
 }
 
-export async function build({ input, custom: customDocs, root, output, typescript }: CLIOptions) {
+export async function build({ input, custom: customDocs, root, output, newOutput, typescript }: CLIOptions) {
 	let data: (ChildTypes & RootTypes)[] | DeclarationReflection[] = [];
 	if (typescript) {
 		console.log('Parsing Typescript in source files...');
@@ -82,5 +82,10 @@ export async function build({ input, custom: customDocs, root, output, typescrip
 		writeFileSync(output, JSON.stringify(docs.serialize()));
 	}
 
+	if (newOutput) {
+		console.log(`Writing to ${newOutput}...`);
+		writeFileSync(newOutput, JSON.stringify(docs.serializeNew()));
+	}
+
 	console.log('Done!');
 }

packages/scripts/package.json

@@ -5,7 +5,7 @@
 	"description": "A set of scripts that we use for our workflows",
 	"private": true,
 	"scripts": {
-		"build": "tsc --noEmit && tsup",
+		"build": "tsc --noEmit --skipLibCheck && tsup",
 		"lint": "prettier --check . && cross-env TIMING=1 eslint --format=pretty src turbo",
 		"format": "prettier --write . && cross-env TIMING=1 eslint --fix --format=pretty src turbo",
 		"fmt": "pnpm run format"
@@ -53,10 +53,12 @@
 	},
 	"homepage": "https://discord.js.org",
 	"dependencies": {
-		"@discordjs/api-extractor-utils": "workspace:^",
+		"@actions/glob": "^0.4.0",
 		"@discordjs/api-extractor-model": "workspace:^",
+		"@discordjs/api-extractor-utils": "workspace:^",
 		"@microsoft/tsdoc": "0.14.2",
 		"@microsoft/tsdoc-config": "0.16.2",
+		"@planetscale/database": "^1.11.0",
 		"tslib": "^2.6.2",
 		"undici": "5.27.2",
 		"yaml": "2.3.4"
@@ -66,6 +68,7 @@
 		"@types/node": "18.18.8",
 		"@vitest/coverage-v8": "^0.34.6",
 		"cross-env": "^7.0.3",
+		"env-cmd": "^10.1.0",
 		"eslint": "^8.53.0",
 		"eslint-config-neon": "^0.1.57",
 		"eslint-formatter-pretty": "^5.0.0",

packages/scripts/src/generateIndex.ts

@@ -1,23 +1,11 @@
 import { stat, mkdir, writeFile } from 'node:fs/promises';
 import { join } from 'node:path';
 import { cwd } from 'node:process';
-import {
+import type { ApiPackage } from '@discordjs/api-extractor-model';
-	ApiModel,
+import { ApiItem, ApiModel, ApiDeclaredItem, ApiItemContainerMixin, ApiItemKind } from '@discordjs/api-extractor-model';
-	ApiDeclaredItem,
-	ApiItemContainerMixin,
-	ApiItem,
-	type ApiPackage,
-	ApiItemKind,
-} from '@discordjs/api-extractor-model';
 import { generatePath } from '@discordjs/api-extractor-utils';
-import {
+import { DocNodeKind, TSDocConfiguration } from '@microsoft/tsdoc';
-	DocNodeKind,
+import type { DocLinkTag, DocCodeSpan, DocNode, DocParagraph, DocPlainText } from '@microsoft/tsdoc';
-	type DocCodeSpan,
-	type DocNode,
-	type DocParagraph,
-	type DocPlainText,
-	TSDocConfiguration,
-} from '@microsoft/tsdoc';
 import { TSDocConfigFile } from '@microsoft/tsdoc-config';
 import { request } from 'undici';
 
@@ -29,6 +17,7 @@ export interface MemberJSON {
 }
 
 export const PACKAGES = [
+	'discord.js',
 	'brokers',
 	'builders',
 	'collection',
@@ -44,17 +33,23 @@ export const PACKAGES = [
 let idx = 0;
 
 export function addPackageToModel(model: ApiModel, data: any) {
-	const tsdocConfiguration = new TSDocConfiguration();
+	let apiPackage: ApiPackage;
-	const tsdocConfigFile = TSDocConfigFile.loadFromObject(data.metadata.tsdocConfig);
+	if (data.metadata) {
-	tsdocConfigFile.configureParser(tsdocConfiguration);
+		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 = ApiItem.deserialize(data, {
-		apiJsonFilename: '',
-		toolPackage: data.metadata.toolPackage,
-		toolVersion: data.metadata.toolVersion,
-		versionToDeserialize: data.metadata.schemaVersion,
-		tsdocConfiguration,
-	}) as ApiPackage;
 	model.addMember(apiPackage);
 	return model;
 }
@@ -82,6 +77,9 @@ export function tryResolveSummaryText(item: ApiDeclaredItem): string | null {
 			case DocNodeKind.PlainText:
 				retVal += (node as DocPlainText).text;
 				break;
+			case DocNodeKind.LinkTag:
+				retVal += (node as DocLinkTag).urlDestination;
+				break;
 			case DocNodeKind.Section:
 			case DocNodeKind.Paragraph: {
 				for (const child of (node as DocParagraph).nodes) {

packages/scripts/src/populateDevDatabaseBranch.ts

@@ -0,0 +1,32 @@
+import { readFile } from 'node:fs/promises';
+import process, { cwd } from 'node:process';
+import { create } from '@actions/glob';
+import { connect } from '@planetscale/database';
+
+const sql = connect({
+	url: process.env.DATABASE_URL!,
+});
+
+process.chdir(`${cwd()}/../../`);
+const globber = await create(`packages/*/docs/*.api.json`);
+// const globber2 = await create(`discord.js/*.json`);
+for await (const file of globber.globGenerator()) {
+	const parsed = /(?<semver>\d+.\d+.\d+)-?.*/.exec(file);
+	const data = await readFile(file, 'utf8');
+
+	if (parsed?.groups) {
+		console.log(parsed.groups.semver, file);
+		try {
+			await sql.execute('replace into documentation (version, data) values (?, ?)', [parsed.groups.semver, data]);
+		} catch (error) {
+			console.error(error);
+		}
+	} else {
+		console.log('main', file);
+		try {
+			await sql.execute('replace into documentation (version, data) values (?, ?)', ['main', data]);
+		} catch (error) {
+			console.error(error);
+		}
+	}
+}

packages/scripts/tsup.config.ts

@@ -1,5 +1,12 @@
 import { createTsupConfig } from '../../tsup.config.js';
 
-export default createTsupConfig({
+export default [
-	minify: 'terser',
+	createTsupConfig({
-});
+		minify: 'terser',
+	}),
+	createTsupConfig({
+		entry: ['src/populateDevDatabaseBranch.ts'],
+		format: 'esm',
+		minify: 'terser',
+	}),
+];

patches/next@14.0.2-canary.20.patch

@@ -0,0 +1,36 @@
+diff --git a/dist/esm/server/lib/incremental-cache/index.js b/dist/esm/server/lib/incremental-cache/index.js
+index 93519fc1e45361f153edd1f4496ca4a006745e8f..8d603be638c297db9593ae9fa92ec5359d38f823 100644
+--- a/dist/esm/server/lib/incremental-cache/index.js
++++ b/dist/esm/server/lib/incremental-cache/index.js
+@@ -348,10 +348,11 @@ export class IncrementalCache {
+             });
+         }
+         if (this.dev && !ctx.fetchCache) return;
++        const max_fetch_size = Number(process.env.MAX_FETCH_SIZE) || 5 // gets value set in next.config
+         // fetchCache has upper limit of 2MB per-entry currently
+-        if (ctx.fetchCache && JSON.stringify(data).length > 2 * 1024 * 1024) {
++        if (ctx.fetchCache && JSON.stringify(data).length > max_fetch_size * 1024 * 1024) {
+             if (this.dev) {
+-                throw new Error(`fetch for over 2MB of data can not be cached`);
++                throw new Error(`fetch for over ${max_fetch_size}MB of data can not be cached`);
+             }
+             return;
+         }
+diff --git a/dist/server/lib/incremental-cache/index.js b/dist/server/lib/incremental-cache/index.js
+index 83e061e5a072d253c2db7ea5e796307070cb1f81..5f9a462e3e12965a49ab6419b19ef2fa0aae7fe6 100644
+--- a/dist/server/lib/incremental-cache/index.js
++++ b/dist/server/lib/incremental-cache/index.js
+@@ -375,10 +375,11 @@ class IncrementalCache {
+             });
+         }
+         if (this.dev && !ctx.fetchCache) return;
++        const max_fetch_size = Number(process.env.MAX_FETCH_SIZE) || 5 //gets value set in next.config
+         // fetchCache has upper limit of 2MB per-entry currently
+-        if (ctx.fetchCache && JSON.stringify(data).length > 2 * 1024 * 1024) {
++        if (ctx.fetchCache && JSON.stringify(data).length > max_fetch_size * 1024 * 1024) {
+             if (this.dev) {
+-                throw new Error(`fetch for over 2MB of data can not be cached`);
++                throw new Error(`fetch for over ${max_fetch_size}MB of data can not be cached`);
+             }
+             return;
+         }

pnpm-lock.yaml

@@ -16,6 +16,9 @@ patchedDependencies:
   '@microsoft/tsdoc-config@0.16.2':
     hash: 35av6rrndvjtr2u2jso66jatbu
     path: patches/@microsoft__tsdoc-config@0.16.2.patch
+  next@14.0.2-canary.20:
+    hash: 3u4mq7bxekreeqimcfnpxiw27y
+    path: patches/next@14.0.2-canary.20.patch
 
 importers:
 
@@ -112,14 +115,14 @@ importers:
         specifier: ^0.3.4
         version: 0.3.4
       next:
-        specifier: ^14.0.2-canary.14
+        specifier: 14.0.2-canary.20
-        version: 14.0.2-canary.14(react-dom@18.2.0)(react@18.2.0)
+        version: 14.0.2-canary.20(patch_hash=3u4mq7bxekreeqimcfnpxiw27y)(react-dom@18.2.0)(react@18.2.0)
       next-contentlayer:
         specifier: ^0.3.4
-        version: 0.3.4(contentlayer@0.3.4)(next@14.0.2-canary.14)(react-dom@18.2.0)(react@18.2.0)
+        version: 0.3.4(contentlayer@0.3.4)(next@14.0.2-canary.20)(react-dom@18.2.0)(react@18.2.0)
       next-themes:
         specifier: ^0.2.1
-        version: 0.2.1(next@14.0.2-canary.14)(react-dom@18.2.0)(react@18.2.0)
+        version: 0.2.1(next@14.0.2-canary.20)(react-dom@18.2.0)(react@18.2.0)
       react:
         specifier: ^18.2.0
         version: 18.2.0
@@ -143,8 +146,8 @@ importers:
         version: 0.32.6
     devDependencies:
       '@next/bundle-analyzer':
-        specifier: ^14.0.1
+        specifier: 14.0.2-canary.20
-        version: 14.0.1
+        version: 14.0.2-canary.20
       '@testing-library/react':
         specifier: ^14.0.0
         version: 14.0.0(react-dom@18.2.0)(react@18.2.0)
@@ -278,14 +281,14 @@ importers:
         specifier: ^0.35.0
         version: 0.35.0
       next:
-        specifier: ^14.0.2-canary.14
+        specifier: 14.0.2-canary.20
-        version: 14.0.2-canary.14(react-dom@18.2.0)(react@18.2.0)
+        version: 14.0.2-canary.20(patch_hash=3u4mq7bxekreeqimcfnpxiw27y)(react-dom@18.2.0)(react@18.2.0)
       next-mdx-remote:
         specifier: ^4.4.1
         version: 4.4.1(react-dom@18.2.0)(react@18.2.0)
       next-themes:
         specifier: ^0.2.1
-        version: 0.2.1(next@14.0.2-canary.14)(react-dom@18.2.0)(react@18.2.0)
+        version: 0.2.1(next@14.0.2-canary.20)(react-dom@18.2.0)(react@18.2.0)
       react:
         specifier: ^18.2.0
         version: 18.2.0
@@ -309,8 +312,8 @@ importers:
         version: 0.32.6
     devDependencies:
       '@next/bundle-analyzer':
-        specifier: ^14.0.1
+        specifier: 14.0.2-canary.20
-        version: 14.0.1
+        version: 14.0.2-canary.20
       '@testing-library/react':
         specifier: ^14.0.0
         version: 14.0.0(react-dom@18.2.0)(react@18.2.0)
@@ -941,6 +944,9 @@ importers:
         specifier: 8.14.2
         version: 8.14.2
     devDependencies:
+      '@discordjs/api-extractor':
+        specifier: workspace:^
+        version: link:../api-extractor
       '@discordjs/docgen':
         specifier: workspace:^
         version: link:../docgen
@@ -1322,6 +1328,9 @@ importers:
 
   packages/scripts:
     dependencies:
+      '@actions/glob':
+        specifier: ^0.4.0
+        version: 0.4.0
       '@discordjs/api-extractor-model':
         specifier: workspace:^
         version: link:../api-extractor-model
@@ -1334,6 +1343,9 @@ importers:
       '@microsoft/tsdoc-config':
         specifier: 0.16.2
         version: 0.16.2(patch_hash=35av6rrndvjtr2u2jso66jatbu)
+      '@planetscale/database':
+        specifier: ^1.11.0
+        version: 1.11.0
       tslib:
         specifier: ^2.6.2
         version: 2.6.2
@@ -1356,6 +1368,9 @@ importers:
       cross-env:
         specifier: ^7.0.3
         version: 7.0.3
+      env-cmd:
+        specifier: ^10.1.0
+        version: 10.1.0
       eslint:
         specifier: ^8.53.0
         version: 8.53.0
@@ -4784,8 +4799,8 @@ packages:
       tar-fs: 2.1.1
     dev: true
 
-  /@next/bundle-analyzer@14.0.1:
+  /@next/bundle-analyzer@14.0.2-canary.20:
-    resolution: {integrity: sha512-AbZZnj4gZ1ZQFppZxAC9e8+skj0rFiSvY6E6Ut+ydS1r6oizR7PMu/7o02psIm4ekAsmp2O1Eq8IowHQgPWPCQ==}
+    resolution: {integrity: sha512-8hqQkCSVI2QJXEcCIZj+xbSHP5Gv9vSAkm66CY8x09SfrYAUPGkSj+KrqbjzQ++A6sSFG2/E1INudWdTl80eRA==}
     dependencies:
       webpack-bundle-analyzer: 4.7.0
     transitivePeerDependencies:
@@ -4793,8 +4808,8 @@ packages:
       - utf-8-validate
     dev: true
 
-  /@next/env@14.0.2-canary.14:
+  /@next/env@14.0.2-canary.20:
-    resolution: {integrity: sha512-XBCanDyEL36mcVlmnjLXjEEHiQmuZf0L5ddNbJpjAPcsQ6fp/IMZszVk4380DAFWuGr0+ozH8cGpheGlHHlmhQ==}
+    resolution: {integrity: sha512-WToL6j4EPN3Upfo4X4XGfBCKPA+5e3Lsq56imOfq33hag1iBa0OBTfU2eRVJE2W7YIECSm0hFzQiZF5OaYTgdg==}
     dev: false
 
   /@next/eslint-plugin-next@13.5.6:
@@ -4803,8 +4818,8 @@ packages:
       glob: 7.1.7
     dev: true
 
-  /@next/swc-darwin-arm64@14.0.2-canary.14:
+  /@next/swc-darwin-arm64@14.0.2-canary.20:
-    resolution: {integrity: sha512-7OYCeqXTAiaODsP5ENfPsu3NGpi9NrbFZnG7Y7CrsCsMpnfJ62mPR3XTRuMVS7oDcsbky+9J7zXxSo49OCJkEw==}
+    resolution: {integrity: sha512-Vf1rrBRd2iTsoOa0icTr7nMVpex8iA+looWnBGPm5K+9yCvD23alETQ+pjAEGUPec98wPj2mTUfZzBU8rsZANw==}
     engines: {node: '>= 10'}
     cpu: [arm64]
     os: [darwin]
@@ -4812,8 +4827,8 @@ packages:
     dev: false
     optional: true
 
-  /@next/swc-darwin-x64@14.0.2-canary.14:
+  /@next/swc-darwin-x64@14.0.2-canary.20:
-    resolution: {integrity: sha512-ZYnV2riRc6+ojxyLsIO0h6mZwrlBnY+cUbisvCnnt5NiFnMXRNNQYLDQ+d4/T4mOMPQvLUfIqKAPaOgT4OgWLw==}
+    resolution: {integrity: sha512-fuN29g3jd9g8De3MIFEpVzhWQ9BUwTorDuIrW5rbsD6lZCasKDVk4eYJ8zeOf7nQrqjRCVOb9a8JteYJsGj/nQ==}
     engines: {node: '>= 10'}
     cpu: [x64]
     os: [darwin]
@@ -4821,8 +4836,8 @@ packages:
     dev: false
     optional: true
 
-  /@next/swc-linux-arm64-gnu@14.0.2-canary.14:
+  /@next/swc-linux-arm64-gnu@14.0.2-canary.20:
-    resolution: {integrity: sha512-m5r8JqtWnrTqkalJV1N/mkfuTwFZojPxbnlNtivilj4aiqMq81obgQ2i6a3dXvIF5UZIwkR33aMDbTZI6swaEA==}
+    resolution: {integrity: sha512-M+JsTvZqgW0DVPqk0IAShWWrvshCruuoabVeBpMeRxTGSfzgYzf3SP9GB2XEd8gfEWJn+P+xB7zXbT8WaNxGTw==}
     engines: {node: '>= 10'}
     cpu: [arm64]
     os: [linux]
@@ -4830,8 +4845,8 @@ packages:
     dev: false
     optional: true
 
-  /@next/swc-linux-arm64-musl@14.0.2-canary.14:
+  /@next/swc-linux-arm64-musl@14.0.2-canary.20:
-    resolution: {integrity: sha512-VWQ6jz3RMARElYcIXC7TxAwmS6MCYowgXUthdDJtwaeUfgSp14S4fg3e2NHsveI1VPvUABBJ16DIpLHUxsk9sw==}
+    resolution: {integrity: sha512-dgQ0i7arRBKVzsWV6ioOUWxaCIho8MKLeSsgXPBCgbBtX4TscJrrfcLh9lFmvrlMj7CwM+eAhrVNrRcOb5mncw==}
     engines: {node: '>= 10'}
     cpu: [arm64]
     os: [linux]
@@ -4839,8 +4854,8 @@ packages:
     dev: false
     optional: true
 
-  /@next/swc-linux-x64-gnu@14.0.2-canary.14:
+  /@next/swc-linux-x64-gnu@14.0.2-canary.20:
-    resolution: {integrity: sha512-pxvwxNMSr9MKlSMzgj544oCyHe4iwZz3XVZnBaYIS4V0hcQDL5NOPVnYYkaYomlwy8fg26UOTkhfIaxeQN6Q1w==}
+    resolution: {integrity: sha512-6t7sQaCgjdnocMoP1TzGi2PDf1qPtVQpDMbqx52V38kR30dlc1S3EvwAmReSzuWlfqwRpYtwJ79O9F7KzvCbDA==}
     engines: {node: '>= 10'}
     cpu: [x64]
     os: [linux]
@@ -4848,8 +4863,8 @@ packages:
     dev: false
     optional: true
 
-  /@next/swc-linux-x64-musl@14.0.2-canary.14:
+  /@next/swc-linux-x64-musl@14.0.2-canary.20:
-    resolution: {integrity: sha512-j+tyC9byzdX0AC92TZT2wDRiKzPYpyUk0EPsb6vVUY4nsAH5oJfASof9hWWpQkAf1REa6PJFJUAnQmDyAYkBNw==}
+    resolution: {integrity: sha512-Ub/3n3ZkjdpcnD1ZdCblS6s7zplT1TTO45RmZKWKpJRKv/5vttrZ8P4xuaklvJSaLlHVEzv8wxU/xuAPHM/q0A==}
     engines: {node: '>= 10'}
     cpu: [x64]
     os: [linux]
@@ -4857,8 +4872,8 @@ packages:
     dev: false
     optional: true
 
-  /@next/swc-win32-arm64-msvc@14.0.2-canary.14:
+  /@next/swc-win32-arm64-msvc@14.0.2-canary.20:
-    resolution: {integrity: sha512-m/SXCsFvJxzgVFhHyJTIzqOtQwpFCVZvO/LphGVRz+8sVGKJYn/xtV87Q/g3mvXzsfRE3vs6VfDUubz+ZNlpSQ==}
+    resolution: {integrity: sha512-4C1r+h8qfWIYy7350ExcjWFCwx4sKASE0IwkGpZez8m6MPnKpCyz3Tr/1QJZ15N8ZVPB0IHf+LcPDZR5xyRO4A==}
     engines: {node: '>= 10'}
     cpu: [arm64]
     os: [win32]
@@ -4866,8 +4881,8 @@ packages:
     dev: false
     optional: true
 
-  /@next/swc-win32-ia32-msvc@14.0.2-canary.14:
+  /@next/swc-win32-ia32-msvc@14.0.2-canary.20:
-    resolution: {integrity: sha512-r9v0J88eOd3vhlSrn7V7rfu4gSWaqAyZuXyoE0MTFAOsfeOYwQwJ3vKbr82/560zLQ1rgfaUuA68JPrSNyHL1g==}
+    resolution: {integrity: sha512-GaaGR4O2dH0/c1gZ4c/3rgaSYvioo8V1mjdGrJuSYohPW+UL11yHMBqfBxOfNNlaRDV/qZHcT6J4A/MHmy7liQ==}
     engines: {node: '>= 10'}
     cpu: [ia32]
     os: [win32]
@@ -4875,8 +4890,8 @@ packages:
     dev: false
     optional: true
 
-  /@next/swc-win32-x64-msvc@14.0.2-canary.14:
+  /@next/swc-win32-x64-msvc@14.0.2-canary.20:
-    resolution: {integrity: sha512-l3OnTrRhXZS4vcDA0BWcq9u8AtBA6nHDbuZjW0GCiUlzl/B6MIegUEsXw5uXU32O0VBArI3xB4BCuQANQBSzrw==}
+    resolution: {integrity: sha512-R36N7/cdW/dk/0w5T7wmH90HdzfpErn9xuQ73oEz2GX7yc1iUhSBMiM6HjzomZWfXbQ57W0d0BmQYFmbVAeWug==}
     engines: {node: '>= 10'}
     cpu: [x64]
     os: [win32]
@@ -11686,6 +11701,15 @@ packages:
     engines: {node: '>=0.12'}
     dev: true
 
+  /env-cmd@10.1.0:
+    resolution: {integrity: sha512-mMdWTT9XKN7yNth/6N6g2GuKuJTsKMDHlQFUDacb/heQRRWOTIZ42t1rMHnQu4jYxU1ajdTeJM+9eEETlqToMA==}
+    engines: {node: '>=8.0.0'}
+    hasBin: true
+    dependencies:
+      commander: 4.1.1
+      cross-spawn: 7.0.3
+    dev: true
+
   /envinfo@7.11.0:
     resolution: {integrity: sha512-G9/6xF1FPbIw0TtalAMaVPpiq2aDEuKLXM314jPVAO9r2fo2a4BLqMNkmRS7O/xPPZ+COAhGIz3ETvHEV3eUcg==}
     engines: {node: '>=4'}
@@ -17389,7 +17413,7 @@ packages:
     engines: {node: '>= 0.4.0'}
     dev: true
 
-  /next-contentlayer@0.3.4(contentlayer@0.3.4)(next@14.0.2-canary.14)(react-dom@18.2.0)(react@18.2.0):
+  /next-contentlayer@0.3.4(contentlayer@0.3.4)(next@14.0.2-canary.20)(react-dom@18.2.0)(react@18.2.0):
     resolution: {integrity: sha512-UtUCwgAl159KwfhNaOwyiI7Lg6sdioyKMeh+E7jxx0CJ29JuXGxBEYmCI6+72NxFGIFZKx8lvttbbQhbnYWYSw==}
     peerDependencies:
       contentlayer: 0.3.4
@@ -17409,7 +17433,7 @@ packages:
       '@contentlayer/core': 0.3.4
       '@contentlayer/utils': 0.3.4
       contentlayer: 0.3.4
-      next: 14.0.2-canary.14(react-dom@18.2.0)(react@18.2.0)
+      next: 14.0.2-canary.20(patch_hash=3u4mq7bxekreeqimcfnpxiw27y)(react-dom@18.2.0)(react@18.2.0)
       react: 18.2.0
       react-dom: 18.2.0(react@18.2.0)
     transitivePeerDependencies:
@@ -17440,7 +17464,7 @@ packages:
       - supports-color
     dev: false
 
-  /next-themes@0.2.1(next@14.0.2-canary.14)(react-dom@18.2.0)(react@18.2.0):
+  /next-themes@0.2.1(next@14.0.2-canary.20)(react-dom@18.2.0)(react@18.2.0):
     resolution: {integrity: sha512-B+AKNfYNIzh0vqQQKqQItTS8evEouKD7H5Hj3kmuPERwddR2TxvDSFZuTj6T7Jfn1oyeUyJMydPl1Bkxkh0W7A==}
     peerDependencies:
       next: '*'
@@ -17454,13 +17478,13 @@ packages:
       react-dom:
         optional: true
     dependencies:
-      next: 14.0.2-canary.14(react-dom@18.2.0)(react@18.2.0)
+      next: 14.0.2-canary.20(patch_hash=3u4mq7bxekreeqimcfnpxiw27y)(react-dom@18.2.0)(react@18.2.0)
       react: 18.2.0
       react-dom: 18.2.0(react@18.2.0)
     dev: false
 
-  /next@14.0.2-canary.14(react-dom@18.2.0)(react@18.2.0):
+  /next@14.0.2-canary.20(patch_hash=3u4mq7bxekreeqimcfnpxiw27y)(react-dom@18.2.0)(react@18.2.0):
-    resolution: {integrity: sha512-+7w8b5o08OQoGBglTXpruuYqyomhwMsBlHPwDsq9DeHFtsDeXOLrrll5vGITH/4RYTsPxwvQ9nngN1EIXGWKYA==}
+    resolution: {integrity: sha512-8fRym/rsqDEGxy0LNDYeVdvzfIBh4mzfIBTtN5lPraftZlknobkyVXOwkQKleG9pu3ml8AloJDj/lKiaLWvzBQ==}
     engines: {node: '>=18.17.0'}
     hasBin: true
     peerDependencies:
@@ -17478,7 +17502,7 @@ packages:
       sass:
         optional: true
     dependencies:
-      '@next/env': 14.0.2-canary.14
+      '@next/env': 14.0.2-canary.20
       '@swc/helpers': 0.5.2
       busboy: 1.6.0
       caniuse-lite: 1.0.30001561
@@ -17488,19 +17512,20 @@ packages:
       styled-jsx: 5.1.1(react@18.2.0)
       watchpack: 2.4.0
     optionalDependencies:
-      '@next/swc-darwin-arm64': 14.0.2-canary.14
+      '@next/swc-darwin-arm64': 14.0.2-canary.20
-      '@next/swc-darwin-x64': 14.0.2-canary.14
+      '@next/swc-darwin-x64': 14.0.2-canary.20
-      '@next/swc-linux-arm64-gnu': 14.0.2-canary.14
+      '@next/swc-linux-arm64-gnu': 14.0.2-canary.20
-      '@next/swc-linux-arm64-musl': 14.0.2-canary.14
+      '@next/swc-linux-arm64-musl': 14.0.2-canary.20
-      '@next/swc-linux-x64-gnu': 14.0.2-canary.14
+      '@next/swc-linux-x64-gnu': 14.0.2-canary.20
-      '@next/swc-linux-x64-musl': 14.0.2-canary.14
+      '@next/swc-linux-x64-musl': 14.0.2-canary.20
-      '@next/swc-win32-arm64-msvc': 14.0.2-canary.14
+      '@next/swc-win32-arm64-msvc': 14.0.2-canary.20
-      '@next/swc-win32-ia32-msvc': 14.0.2-canary.14
+      '@next/swc-win32-ia32-msvc': 14.0.2-canary.20
-      '@next/swc-win32-x64-msvc': 14.0.2-canary.14
+      '@next/swc-win32-x64-msvc': 14.0.2-canary.20
     transitivePeerDependencies:
       - '@babel/core'
       - babel-plugin-macros
     dev: false
+    patched: true
 
   /no-case@2.3.2:
     resolution: {integrity: sha512-rmTZ9kz+f3rCvK2TD1Ue/oZlns7OGoIWP4fc3llxxRXlOkHKoWPPWJOfFYpITabSow43QJbRIoHQXtt10VldyQ==}