Nomchy/discord.js
1
0
Fork 0
mirror of https://github.com/discordjs/discord.js.git synced 2026-03-11 17:13:31 +01:00
Code Issues Packages Projects Releases Wiki Activity

feat: add util package for generating search indices (#8571)

Browse Source
This commit is contained in:
Suneet Tipirneni
2022-08-29 15:41:51 -04:00
committed by GitHub
parent 40324574eb
commit d5dcddd350
55 changed files with 384 additions and 93 deletions
Download Patch File Download Diff File Expand all files Collapse all files

400
packages/website/src/DocModel/ApiNodeJSONEncoder.ts
View File

@@ -1,400 +0,0 @@
import {
type ApiModel,
ApiDeclaredItem,
type ApiPropertyItem,
type ApiMethod,
type ApiParameterListMixin,
type ApiTypeParameterListMixin,
type ApiClass,
type ApiFunction,
ApiItemKind,
type ApiTypeAlias,
type ApiEnum,
type ApiInterface,
type ApiMethodSignature,
type ApiPropertySignature,
type ApiVariable,
type ApiItem,
type ApiConstructor,
type ApiItemContainerMixin,
} from '@microsoft/api-extractor-model';
import { generateTypeParamData } from './TypeParameterMixin';
import { Visibility } from './Visibility';
import { createCommentNode } from './comment';
import type { DocBlockJSON } from './comment/CommentBlock';
import type { AnyDocNodeJSON } from './comment/CommentNode';
import { type DocNodeContainerJSON, nodeContainer } from './comment/CommentNodeContainer';
import {
generatePath,
genParameter,
genReference,
genToken,
resolveName,
type TokenDocumentation,
} from '~/util/parse.server';
export interface ReferenceData {
name: string;
path: string;
}
export interface InheritanceData {
parentName: string;
path: string;
parentKey: string;
}
export interface ApiInheritableJSON {
inheritanceData: InheritanceData | null;
}
export interface ApiItemJSON {
kind: string;
name: string;
referenceData: ReferenceData;
excerpt: string;
excerptTokens: TokenDocumentation[];
remarks: DocNodeContainerJSON | null;
summary: DocNodeContainerJSON | null;
deprecated: DocNodeContainerJSON | null;
comment: AnyDocNodeJSON | null;
containerKey: string;
path: string[];
}
export interface ApiPropertyItemJSON extends ApiItemJSON, ApiInheritableJSON {
propertyTypeTokens: TokenDocumentation[];
readonly: boolean;
optional: boolean;
}
export interface ApiTypeParameterListJSON {
typeParameters: ApiTypeParameterJSON[];
}
export interface ApiTypeParameterJSON {
name: string;
constraintTokens: TokenDocumentation[];
defaultTokens: TokenDocumentation[];
optional: boolean;
commentBlock: DocBlockJSON | null;
}
export interface ApiParameterListJSON {
parameters: ApiParameterJSON[];
}
export interface ApiMethodSignatureJSON
extends ApiItemJSON,
ApiTypeParameterListJSON,
ApiParameterListJSON,
ApiInheritableJSON {
returnTypeTokens: TokenDocumentation[];
optional: boolean;
overloadIndex: number;
}
export interface ApiMethodJSON extends ApiMethodSignatureJSON {
static: boolean;
visibility: Visibility;
}
export interface ApiParameterJSON {
name: string;
isOptional: boolean;
tokens: TokenDocumentation[];
paramCommentBlock: DocBlockJSON | null;
}
export interface ApiClassJSON extends ApiItemJSON, ApiTypeParameterListJSON {
constructor: ApiConstructorJSON | null;
properties: ApiPropertyItemJSON[];
methods: ApiMethodJSON[];
extendsTokens: TokenDocumentation[];
implementsTokens: TokenDocumentation[][];
}
export interface ApiTypeAliasJSON extends ApiItemJSON, ApiTypeParameterListJSON {
typeTokens: TokenDocumentation[];
}
export interface EnumMemberData {
name: string;
initializerTokens: TokenDocumentation[];
summary: DocNodeContainerJSON | null;
}
export interface ApiEnumJSON extends ApiItemJSON {
members: EnumMemberData[];
}
export interface ApiInterfaceJSON extends ApiItemJSON, ApiTypeParameterListJSON {
properties: ApiPropertyItemJSON[];
methods: ApiMethodSignatureJSON[];
extendsTokens: TokenDocumentation[][] | null;
}
export interface ApiVariableJSON extends ApiItemJSON {
typeTokens: TokenDocumentation[];
readonly: boolean;
}
export interface ApiFunctionJSON extends ApiItemJSON, ApiTypeParameterListJSON, ApiParameterListJSON {
returnTypeTokens: TokenDocumentation[];
overloadIndex: number;
}
export interface ApiConstructorJSON extends ApiItemJSON, ApiParameterListJSON {
protected: boolean;
}
// eslint-disable-next-line @typescript-eslint/no-extraneous-class
export class ApiNodeJSONEncoder {
public static encode(model: ApiModel, node: ApiItem, version: string) {
if (!(node instanceof ApiDeclaredItem)) {
console.log(`Cannot serialize node of type ${node.kind}`);
return undefined;
}
switch (node.kind) {
case ApiItemKind.Class:
return this.encodeClass(model, node as ApiClass, version);
case ApiItemKind.Function:
return this.encodeFunction(model, node as ApiFunction, version);
case ApiItemKind.Interface:
return this.encodeInterface(model, node as ApiInterface, version);
case ApiItemKind.TypeAlias:
return this.encodeTypeAlias(model, node as ApiTypeAlias, version);
case ApiItemKind.Enum:
return this.encodeEnum(model, node as ApiEnum, version);
case ApiItemKind.Variable:
return this.encodeVariable(model, node as ApiVariable, version);
default:
console.log(`Unknown API item kind: ${node.kind}`);
return undefined;
}
}
public static encodeItem(model: ApiModel, item: ApiDeclaredItem, version: string): ApiItemJSON {
const path = [];
for (const _item of item.getHierarchy()) {
switch (_item.kind) {
case 'None':
case 'EntryPoint':
case 'Model':
break;
default:
path.push(resolveName(_item));
}
}
return {
kind: item.kind,
name: resolveName(item),
referenceData: genReference(item, version),
excerpt: item.excerpt.text,
excerptTokens: item.excerpt.spannedTokens.map((token) => genToken(model, token, version)),
remarks: item.tsdocComment?.remarksBlock
? (createCommentNode(item.tsdocComment.remarksBlock, model, version, item.parent) as DocNodeContainerJSON)
: null,
summary: item.tsdocComment?.summarySection
? (createCommentNode(item.tsdocComment.summarySection, model, version, item.parent) as DocNodeContainerJSON)
: null,
deprecated: item.tsdocComment?.deprecatedBlock
? (createCommentNode(item.tsdocComment.deprecatedBlock, model, version, item.parent) as DocNodeContainerJSON)
: null,
path,
containerKey: item.containerKey,
comment: item.tsdocComment ? createCommentNode(item.tsdocComment, model, version, item.parent) : null,
};
}
public static encodeParameterList(
model: ApiModel,
item: ApiParameterListMixin & ApiDeclaredItem,
version: string,
): { parameters: ApiParameterJSON[] } {
return {
parameters: item.parameters.map((param) => genParameter(model, param, version)),
};
}
public static encodeTypeParameterList(
model: ApiModel,
item: ApiTypeParameterListMixin & ApiDeclaredItem,
version: string,
): ApiTypeParameterListJSON {
return {
typeParameters: item.typeParameters.map((param) => generateTypeParamData(model, param, version, item.parent)),
};
}
public static encodeProperty(
model: ApiModel,
item: ApiPropertyItem,
parent: ApiItemContainerMixin,
version: string,
): ApiPropertyItemJSON {
return {
...this.encodeItem(model, item, version),
...this.encodeInheritanceData(item, parent, version),
propertyTypeTokens: item.propertyTypeExcerpt.spannedTokens.map((token) => genToken(model, token, version)),
readonly: item.isReadonly,
optional: item.isOptional,
};
}
public static encodeInheritanceData(
item: ApiDeclaredItem,
parent: ApiItemContainerMixin,
version: string,
): ApiInheritableJSON {
return {
inheritanceData:
item.parent && item.parent.containerKey !== parent.containerKey
? {
parentKey: item.parent.containerKey,
parentName: item.parent.displayName,
path: generatePath(item.parent.getHierarchy(), version),
}
: null,
};
}
public static encodeFunction(model: ApiModel, item: ApiFunction, version: string): ApiFunctionJSON {
return {
...this.encodeItem(model, item, version),
...this.encodeParameterList(model, item, version),
...this.encodeTypeParameterList(model, item, version),
returnTypeTokens: item.returnTypeExcerpt.spannedTokens.map((token) => genToken(model, token, version)),
overloadIndex: item.overloadIndex,
};
}
public static encodeMethodSignature(
model: ApiModel,
item: ApiMethodSignature,
parent: ApiItemContainerMixin,
version: string,
): ApiMethodSignatureJSON {
return {
...this.encodeFunction(model, item, version),
...this.encodeInheritanceData(item, parent, version),
optional: item.isOptional,
};
}
public static encodeMethod(
model: ApiModel,
item: ApiMethod,
parent: ApiItemContainerMixin,
version: string,
): ApiMethodJSON {
return {
...this.encodeMethodSignature(model, item, parent, version),
static: item.isStatic,
visibility: item.isProtected ? Visibility.Protected : Visibility.Public,
};
}
public static encodeClass(model: ApiModel, item: ApiClass, version: string): ApiClassJSON {
const extendsExcerpt = item.extendsType?.excerpt;
const methods: ApiMethodJSON[] = [];
const properties: ApiPropertyItemJSON[] = [];
let constructor: ApiConstructor | undefined;
for (const member of item.findMembersWithInheritance().items) {
switch (member.kind) {
case ApiItemKind.Method:
methods.push(this.encodeMethod(model, member as ApiMethod, item, version));
break;
case ApiItemKind.Property:
properties.push(this.encodeProperty(model, member as ApiPropertyItem, item, version));
break;
case ApiItemKind.Constructor:
constructor = member as ApiConstructor;
break;
default:
break;
}
}
return {
...this.encodeItem(model, item, version),
...this.encodeTypeParameterList(model, item, version),
constructor: constructor ? this.encodeConstructor(model, constructor, version) : null,
extendsTokens: extendsExcerpt ? extendsExcerpt.spannedTokens.map((token) => genToken(model, token, version)) : [],
implementsTokens: item.implementsTypes.map((excerpt) =>
excerpt.excerpt.spannedTokens.map((token) => genToken(model, token, version)),
),
methods,
properties,
};
}
public static encodeTypeAlias(model: ApiModel, item: ApiTypeAlias, version: string): ApiTypeAliasJSON {
return {
...this.encodeItem(model, item, version),
...this.encodeTypeParameterList(model, item, version),
typeTokens: item.typeExcerpt.spannedTokens.map((token) => genToken(model, token, version)),
};
}
public static encodeEnum(model: ApiModel, item: ApiEnum, version: string): ApiEnumJSON {
return {
...this.encodeItem(model, item, version),
members: item.members.map((member) => ({
name: member.name,
initializerTokens:
member.initializerExcerpt?.spannedTokens.map((token) => genToken(model, token, version)) ?? [],
summary: member.tsdocComment ? nodeContainer(member.tsdocComment.summarySection, model, version, member) : null,
})),
};
}
public static encodeInterface(model: ApiModel, item: ApiInterface, version: string): ApiInterfaceJSON {
const methods: ApiMethodSignatureJSON[] = [];
const properties: ApiPropertyItemJSON[] = [];
for (const member of item.findMembersWithInheritance().items) {
switch (member.kind) {
case ApiItemKind.MethodSignature:
methods.push(this.encodeMethodSignature(model, member as ApiMethodSignature, item, version));
break;
case ApiItemKind.PropertySignature:
properties.push(this.encodeProperty(model, member as ApiPropertySignature, item, version));
break;
default:
break;
}
}
return {
...this.encodeItem(model, item, version),
...this.encodeTypeParameterList(model, item, version),
extendsTokens: item.extendsTypes.map((excerpt) =>
excerpt.excerpt.spannedTokens.map((token) => genToken(model, token, version)),
),
methods,
properties,
};
}
public static encodeVariable(model: ApiModel, item: ApiVariable, version: string): ApiVariableJSON {
return {
...this.encodeItem(model, item, version),
typeTokens: item.variableTypeExcerpt.spannedTokens.map((token) => genToken(model, token, version)),
readonly: item.isReadonly,
};
}
public static encodeConstructor(model: ApiModel, item: ApiConstructor, version: string): ApiConstructorJSON {
return {
...this.encodeItem(model, item, version),
...this.encodeParameterList(model, item, version),
protected: item.isProtected,
};
}
}

31
packages/website/src/DocModel/TypeParameterMixin.ts
View File

@@ -1,31 +0,0 @@
import type { ApiItem, ApiModel, TypeParameter } from '@microsoft/api-extractor-model';
import { block, type DocBlockJSON } from './comment/CommentBlock';
import { genToken, type TokenDocumentation } from '~/util/parse.server';
export interface TypeParameterData {
name: string;
constraintTokens: TokenDocumentation[];
defaultTokens: TokenDocumentation[];
optional: boolean;
commentBlock: DocBlockJSON | null;
}
export function generateTypeParamData(
model: ApiModel,
typeParam: TypeParameter,
version: string,
parentItem?: ApiItem,
): TypeParameterData {
const constraintTokens = typeParam.constraintExcerpt.spannedTokens.map((token) => genToken(model, token, version));
const defaultTokens = typeParam.defaultTypeExcerpt.spannedTokens.map((token) => genToken(model, token, version));
return {
name: typeParam.name,
constraintTokens,
defaultTokens,
optional: typeParam.isOptional,
commentBlock: typeParam.tsdocTypeParamBlock
? block(typeParam.tsdocTypeParamBlock, model, version, parentItem)
: null,
};
}

4
packages/website/src/DocModel/Visibility.ts
View File

@@ -1,4 +0,0 @@
export enum Visibility {
Public,
Protected,
}

18
packages/website/src/DocModel/comment/CommentBlock.ts
View File

@@ -1,18 +0,0 @@
import type { ApiModel, ApiItem } from '@microsoft/api-extractor-model';
import type { DocBlock } from '@microsoft/tsdoc';
import { createCommentNode } from '.';
import { blockTag, type DocBlockTagJSON } from './CommentBlockTag';
import { type AnyDocNodeJSON, type DocNodeJSON, node } from './CommentNode';
export interface DocBlockJSON extends DocNodeJSON {
content: AnyDocNodeJSON[];
tag: DocBlockTagJSON;
}
export function block(block: DocBlock, model: ApiModel, version: string, parentItem?: ApiItem) {
return {
...node(block),
content: block.content.nodes.map((node) => createCommentNode(node, model, version, parentItem)),
tag: blockTag(block.blockTag),
};
}

13
packages/website/src/DocModel/comment/CommentBlockTag.ts
View File

@@ -1,13 +0,0 @@
import type { DocBlockTag } from '@microsoft/tsdoc';
import { type DocNodeJSON, node } from './CommentNode';
export interface DocBlockTagJSON extends DocNodeJSON {
tagName: string;
}
export function blockTag(blockTag: DocBlockTag): DocBlockTagJSON {
return {
...node(blockTag),
tagName: blockTag.tagName,
};
}

13
packages/website/src/DocModel/comment/CommentCodeSpan.ts
View File

@@ -1,13 +0,0 @@
import type { DocCodeSpan } from '@microsoft/tsdoc';
import { type DocNodeJSON, node } from './CommentNode';
export interface DocCodeSpanJSON extends DocNodeJSON {
code: string;
}
export function codeSpan(codeSpan: DocCodeSpan): DocCodeSpanJSON {
return {
...node(codeSpan),
code: codeSpan.code,
};
}

28
packages/website/src/DocModel/comment/CommentNode.ts
View File

@@ -1,28 +0,0 @@
import type { DocNode, DocNodeKind } from '@microsoft/tsdoc';
import type { DocBlockJSON } from './CommentBlock';
import type { DocCodeSpanJSON } from './CommentCodeSpan';
import type { DocNodeContainerJSON } from './CommentNodeContainer';
import type { DocFencedCodeJSON } from './FencedCodeCommentNode';
import type { DocLinkTagJSON } from './LinkTagCommentNode';
import type { DocPlainTextJSON } from './PlainTextCommentNode';
import type { DocCommentJSON } from './RootComment';
export interface DocNodeJSON {
kind: DocNodeKind;
}
export type AnyDocNodeJSON =
| DocNodeJSON
| DocPlainTextJSON
| DocNodeContainerJSON
| DocLinkTagJSON
| DocFencedCodeJSON
| DocBlockJSON
| DocCommentJSON
| DocCodeSpanJSON;
export function node(node: DocNode): DocNodeJSON {
return {
kind: node.kind as DocNodeKind,
};
}

20
packages/website/src/DocModel/comment/CommentNodeContainer.ts
View File

@@ -1,20 +0,0 @@
import type { ApiItem, ApiModel } from '@microsoft/api-extractor-model';
import type { DocNodeContainer } from '@microsoft/tsdoc';
import { createCommentNode } from '.';
import { type AnyDocNodeJSON, type DocNodeJSON, node } from './CommentNode';
export interface DocNodeContainerJSON extends DocNodeJSON {
nodes: AnyDocNodeJSON[];
}
export function nodeContainer(
container: DocNodeContainer,
model: ApiModel,
version: string,
parentItem?: ApiItem,
): DocNodeContainerJSON {
return {
...node(container),
nodes: container.nodes.map((node) => createCommentNode(node, model, version, parentItem)),
};
}

15
packages/website/src/DocModel/comment/FencedCodeCommentNode.ts
View File

@@ -1,15 +0,0 @@
import type { DocFencedCode } from '@microsoft/tsdoc';
import { type DocNodeJSON, node } from './CommentNode';
export interface DocFencedCodeJSON extends DocNodeJSON {
code: string;
language: string;
}
export function fencedCode(fencedCode: DocFencedCode) {
return {
...node(fencedCode),
language: fencedCode.language,
code: fencedCode.code,
};
}

60
packages/website/src/DocModel/comment/LinkTagCommentNode.ts
View File

@@ -1,60 +0,0 @@
import type { ApiItem, ApiModel } from '@microsoft/api-extractor-model';
import type { DocDeclarationReference, DocLinkTag } from '@microsoft/tsdoc';
import { type DocNodeJSON, node } from './CommentNode';
import { generatePath, resolveName } from '~/util/parse.server';
interface LinkTagCodeLink {
name: string;
kind: string;
path: string;
}
export interface DocLinkTagJSON extends DocNodeJSON {
text: string | null;
codeDestination: LinkTagCodeLink | null;
urlDestination: string | null;
}
export function genToken(
model: ApiModel,
ref: DocDeclarationReference,
context: ApiItem | null,
version: string,
): LinkTagCodeLink | null {
const item = model.resolveDeclarationReference(ref, context ?? undefined).resolvedApiItem ?? null;
if (!item) {
return null;
}
return {
name: resolveName(item),
kind: item.kind,
path: generatePath(item.getHierarchy(), version),
};
}
export function linkTagNode(
linkNode: DocLinkTag,
model: ApiModel,
version: string,
parentItem?: ApiItem,
): DocLinkTagJSON {
// If we weren't provided a parent object, fallback to the package entrypoint.
const packageEntryPoint = linkNode.codeDestination?.importPath
? model.getAssociatedPackage()?.findEntryPointsByPath(linkNode.codeDestination.importPath)[0]
: null;
const codeDestination = linkNode.codeDestination
? genToken(model, linkNode.codeDestination, parentItem ?? packageEntryPoint ?? null, version)
: null;
const text = linkNode.linkText ?? null;
const urlDestination = linkNode.urlDestination ?? null;
return {
...node(linkNode),
text,
codeDestination,
urlDestination,
};
}

19
packages/website/src/DocModel/comment/ParamBlock.ts
View File

@@ -1,19 +0,0 @@
import type { ApiItem, ApiModel } from '@microsoft/api-extractor-model';
import type { DocParamBlock } from '@microsoft/tsdoc';
import { block, type DocBlockJSON } from './CommentBlock';
interface DocParamBlockJSON extends DocBlockJSON {
name: string;
}
export function paramBlock(
paramBlock: DocParamBlock,
model: ApiModel,
version: string,
parentItem?: ApiItem,
): DocParamBlockJSON {
return {
...block(paramBlock, model, version, parentItem),
name: paramBlock.parameterName,
};
}

13
packages/website/src/DocModel/comment/PlainTextCommentNode.ts
View File

@@ -1,13 +0,0 @@
import type { DocPlainText } from '@microsoft/tsdoc';
import { type DocNodeJSON, node } from './CommentNode';
export interface DocPlainTextJSON extends DocNodeJSON {
text: string;
}
export function plainTextNode(plainTextNode: DocPlainText): DocPlainTextJSON {
return {
...node(plainTextNode),
text: plainTextNode.text,
};
}

24
packages/website/src/DocModel/comment/RootComment.ts
View File

@@ -1,24 +0,0 @@
import type { ApiItem, ApiModel } from '@microsoft/api-extractor-model';
import type { DocComment } from '@microsoft/tsdoc';
import { createCommentNode } from '.';
import { block, type DocBlockJSON } from './CommentBlock';
import { type DocNodeJSON, node } from './CommentNode';
export interface DocCommentJSON extends DocNodeJSON {
summary: DocNodeJSON[];
remarks: DocNodeJSON[];
deprecated: DocNodeJSON[];
customBlocks: DocBlockJSON[];
}
export function comment(comment: DocComment, model: ApiModel, version: string, parentItem?: ApiItem): DocCommentJSON {
return {
...node(comment),
summary: comment.summarySection.nodes.map((node) => createCommentNode(node, model, version, parentItem)),
remarks:
comment.remarksBlock?.content.nodes.map((node) => createCommentNode(node, model, version, parentItem)) ?? [],
deprecated:
comment.deprecatedBlock?.content.nodes.map((node) => createCommentNode(node, model, version, parentItem)) ?? [],
customBlocks: comment.customBlocks.map((_block) => block(_block, model, version, parentItem)),
};
}

52
packages/website/src/DocModel/comment/index.ts
View File

@@ -1,52 +0,0 @@
import type { ApiModel, ApiItem } from '@microsoft/api-extractor-model';
import {
type DocNode,
type DocPlainText,
type DocLinkTag,
type DocParagraph,
type DocFencedCode,
DocNodeKind,
type DocBlock,
type DocComment,
type DocCodeSpan,
type DocParamBlock,
} from '@microsoft/tsdoc';
import { block } from './CommentBlock';
import { codeSpan } from './CommentCodeSpan';
import type { AnyDocNodeJSON } from './CommentNode';
import { node as _node } from './CommentNode';
import { nodeContainer } from './CommentNodeContainer';
import { fencedCode } from './FencedCodeCommentNode';
import { linkTagNode } from './LinkTagCommentNode';
import { paramBlock } from './ParamBlock';
import { plainTextNode } from './PlainTextCommentNode';
import { comment } from './RootComment';
export function createCommentNode(
node: DocNode,
model: ApiModel,
version: string,
parentItem?: ApiItem,
): AnyDocNodeJSON {
switch (node.kind) {
case DocNodeKind.PlainText:
return plainTextNode(node as DocPlainText);
case DocNodeKind.LinkTag:
return linkTagNode(node as DocLinkTag, model, version, parentItem);
case DocNodeKind.Paragraph:
case DocNodeKind.Section:
return nodeContainer(node as DocParagraph, model, version, parentItem);
case DocNodeKind.FencedCode:
return fencedCode(node as DocFencedCode);
case DocNodeKind.CodeSpan:
return codeSpan(node as DocCodeSpan);
case DocNodeKind.Block:
return block(node as DocBlock, model, version, parentItem);
case DocNodeKind.ParamBlock:
return paramBlock(node as DocParamBlock, model, version, parentItem);
case DocNodeKind.Comment:
return comment(node as DocComment, model, version, parentItem);
default:
return _node(node);
}
}

4
packages/website/src/components/CodeListing.tsx
View File

@@ -1,3 +1,4 @@
import type { TokenDocumentation, ApiItemJSON, AnyDocNodeJSON, InheritanceData } from '@discordjs/api-extractor-utils';
import { ActionIcon, Badge, Box, createStyles, Group, MediaQuery, Stack, Title } from '@mantine/core';
import { useMediaQuery } from '@mantine/hooks';
import type { PropsWithChildren } from 'react';
@@ -5,9 +6,6 @@ import { FiLink } from 'react-icons/fi';
import { HyperlinkedText } from './HyperlinkedText';
import { InheritanceText } from './InheritanceText';
import { TSDoc } from './tsdoc/TSDoc';
import type { ApiItemJSON, InheritanceData } from '~/DocModel/ApiNodeJSONEncoder';
import type { AnyDocNodeJSON } from '~/DocModel/comment/CommentNode';
import type { TokenDocumentation } from '~/util/parse.server';
export enum CodeListingSeparatorType {
Type = ':',

12
packages/website/src/components/DocContainer.tsx
View File

@@ -1,3 +1,11 @@
import type {
ApiItemJSON,
TokenDocumentation,
TypeParameterData,
AnyDocNodeJSON,
ApiClassJSON,
ApiInterfaceJSON,
} from '@discordjs/api-extractor-utils';
import {
Group,
Stack,
@@ -30,10 +38,6 @@ import { Section } from './Section';
import { TableOfContentItems } from './TableOfContentItems';
import { TypeParamTable } from './TypeParamTable';
import { TSDoc } from './tsdoc/TSDoc';
import type { ApiClassJSON, ApiInterfaceJSON, ApiItemJSON } from '~/DocModel/ApiNodeJSONEncoder';
import type { TypeParameterData } from '~/DocModel/TypeParameterMixin';
import type { AnyDocNodeJSON } from '~/DocModel/comment/CommentNode';
import type { TokenDocumentation } from '~/util/parse.server';
type DocContainerProps = PropsWithChildren<{
name: string;

2
packages/website/src/components/HyperlinkedText.tsx
View File

@@ -1,6 +1,6 @@
import type { TokenDocumentation } from '@discordjs/api-extractor-utils';
import { Anchor, Text } from '@mantine/core';
import Link from 'next/link';
import type { TokenDocumentation } from '~/util/parse.server';
/**
* Constructs a hyperlinked html node based on token type references

2
packages/website/src/components/InheritanceText.tsx
View File

@@ -1,6 +1,6 @@
import type { InheritanceData } from '@discordjs/api-extractor-utils';
import { Anchor, Text } from '@mantine/core';
import Link from 'next/link';
import type { InheritanceData } from '~/DocModel/ApiNodeJSONEncoder';
export function InheritanceText({ data }: { data: InheritanceData }) {
return (

9
packages/website/src/components/MethodItem.tsx
View File

@@ -1,3 +1,4 @@
import type { ApiMethodJSON, ApiMethodSignatureJSON } from '@discordjs/api-extractor-utils';
import { ActionIcon, Badge, Box, createStyles, Group, MediaQuery, Stack, Title } from '@mantine/core';
import { useMediaQuery } from '@mantine/hooks';
import { FiLink } from 'react-icons/fi';
@@ -5,8 +6,6 @@ import { HyperlinkedText } from './HyperlinkedText';
import { InheritanceText } from './InheritanceText';
import { ParameterTable } from './ParameterTable';
import { TSDoc } from './tsdoc/TSDoc';
import type { ApiMethodJSON, ApiMethodSignatureJSON } from '~/DocModel/ApiNodeJSONEncoder';
import { Visibility } from '~/DocModel/Visibility';
const useStyles = createStyles((theme) => ({
outer: {
@@ -48,7 +47,7 @@ export function MethodItem({ data }: { data: ApiMethodJSON | ApiMethodSignatureJ
</ActionIcon>
</MediaQuery>
{data.deprecated ||
(data.kind === 'Method' && method.visibility === Visibility.Protected) ||
(data.kind === 'Method' && method.protected) ||
(data.kind === 'Method' && method.static) ? (
<Group spacing={10} noWrap>
{data.deprecated ? (
@@ -56,9 +55,7 @@ export function MethodItem({ data }: { data: ApiMethodJSON | ApiMethodSignatureJ
Deprecated
</Badge>
) : null}
{data.kind === 'Method' && method.visibility === Visibility.Protected ? (
<Badge variant="filled">Protected</Badge>
) : null}
{data.kind === 'Method' && method.protected ? <Badge variant="filled">Protected</Badge> : null}
{data.kind === 'Method' && method.static ? <Badge variant="filled">Static</Badge> : null}
</Group>
) : null}

2
packages/website/src/components/MethodList.tsx
View File

@@ -1,7 +1,7 @@
import type { ApiMethodJSON, ApiMethodSignatureJSON } from '@discordjs/api-extractor-utils';
import { Divider, Stack } from '@mantine/core';
import { Fragment } from 'react';
import { MethodItem } from './MethodItem';
import type { ApiMethodJSON, ApiMethodSignatureJSON } from '~/DocModel/ApiNodeJSONEncoder';
export function MethodList({ data }: { data: (ApiMethodJSON | ApiMethodSignatureJSON)[] }) {
return (

2
packages/website/src/components/ParameterTable.tsx
View File

@@ -1,8 +1,8 @@
import type { ParameterDocumentation } from '@discordjs/api-extractor-utils';
import { Box, ScrollArea } from '@mantine/core';
import { HyperlinkedText } from './HyperlinkedText';
import { Table } from './Table';
import { TSDoc } from './tsdoc/TSDoc';
import type { ParameterDocumentation } from '~/util/parse.server';
const columnStyles = {
Name: 'font-mono whitespace-nowrap',

2
packages/website/src/components/PropertyList.tsx
View File

@@ -1,6 +1,6 @@
import type { ApiPropertyItemJSON } from '@discordjs/api-extractor-utils';
import { Stack } from '@mantine/core';
import { CodeListing } from './CodeListing';
import type { ApiPropertyItemJSON } from '~/DocModel/ApiNodeJSONEncoder';
export function PropertyList({ data }: { data: ApiPropertyItemJSON[] }) {
return (

8
packages/website/src/components/Sections.tsx
View File

@@ -1,3 +1,9 @@
import type {
ApiClassJSON,
ApiInterfaceJSON,
ParameterDocumentation,
ApiConstructorJSON,
} from '@discordjs/api-extractor-utils';
import { Stack, Group, Badge, Title } from '@mantine/core';
import { useMediaQuery } from '@mantine/hooks';
import { VscSymbolConstant, VscSymbolMethod, VscSymbolProperty } from 'react-icons/vsc';
@@ -6,8 +12,6 @@ import { ParameterTable } from './ParameterTable';
import { PropertyList } from './PropertyList';
import { Section } from './Section';
import { TSDoc } from './tsdoc/TSDoc';
import type { ApiClassJSON, ApiConstructorJSON, ApiInterfaceJSON } from '~/DocModel/ApiNodeJSONEncoder';
import type { ParameterDocumentation } from '~/util/parse.server';
export function PropertiesSection({ data }: { data: ApiClassJSON['properties'] | ApiInterfaceJSON['properties'] }) {
const matches = useMediaQuery('(max-width: 768px)');

3
packages/website/src/components/SidebarLayout.tsx
View File

@@ -1,3 +1,4 @@
import type { getMembers, ApiItemJSON } from '@discordjs/api-extractor-utils';
import {
useMantineTheme,
AppShell,
@@ -33,10 +34,8 @@ import { VscChevronDown, VscGithubInverted, VscPackage, VscVersions } from 'reac
import { WiDaySunny, WiNightClear } from 'react-icons/wi';
import useSWR from 'swr';
import { SidebarItems } from './SidebarItems';
import type { ApiItemJSON } from '~/DocModel/ApiNodeJSONEncoder';
import type { findMember } from '~/util/model.server';
import { PACKAGES } from '~/util/packages';
import type { getMembers } from '~/util/parse.server';
const fetcher = (url: string) => fetch(url).then((res) => res.json());

2
packages/website/src/components/TableOfContentItems.tsx
View File

@@ -1,7 +1,7 @@
import type { ApiClassJSON, ApiInterfaceJSON } from '@discordjs/api-extractor-utils';
import { createStyles, Group, Text, Box, Stack, ThemeIcon, useMantineColorScheme } from '@mantine/core';
import { useMemo } from 'react';
import { VscListSelection, VscSymbolMethod, VscSymbolProperty } from 'react-icons/vsc';
import type { ApiClassJSON, ApiInterfaceJSON } from '~/DocModel/ApiNodeJSONEncoder';
const useStyles = createStyles((theme) => ({
// eslint-disable-next-line @typescript-eslint/no-unsafe-assignment

2
packages/website/src/components/TypeParamTable.tsx
View File

@@ -1,8 +1,8 @@
import type { TypeParameterData } from '@discordjs/api-extractor-utils';
import { ScrollArea } from '@mantine/core';
import { HyperlinkedText } from './HyperlinkedText';
import { Table } from './Table';
import { TSDoc } from './tsdoc/TSDoc';
import type { TypeParameterData } from '~/DocModel/TypeParameterMixin';
const rowElements = {
Name: 'font-mono whitespace-nowrap',

2
packages/website/src/components/model/Class.tsx
View File

@@ -1,8 +1,8 @@
import type { ApiClassJSON } from '@discordjs/api-extractor-utils';
import { Skeleton } from '@mantine/core';
import { useRouter } from 'next/router';
import { DocContainer } from '../DocContainer';
import { ConstructorSection, MethodsSection, PropertiesSection } from '../Sections';
import type { ApiClassJSON } from '~/DocModel/ApiNodeJSONEncoder';
export function Class({ data }: { data: ApiClassJSON }) {
const router = useRouter();

2
packages/website/src/components/model/Enum.tsx
View File

@@ -1,3 +1,4 @@
import type { ApiEnumJSON } from '@discordjs/api-extractor-utils';
import { Skeleton, Stack } from '@mantine/core';
import { useMediaQuery } from '@mantine/hooks';
import { useRouter } from 'next/router';
@@ -5,7 +6,6 @@ import { VscSymbolEnumMember } from 'react-icons/vsc';
import { CodeListing, CodeListingSeparatorType } from '../CodeListing';
import { DocContainer } from '../DocContainer';
import { Section } from '../Section';
import type { ApiEnumJSON } from '~/DocModel/ApiNodeJSONEncoder';
export function Enum({ data }: { data: ApiEnumJSON }) {
const router = useRouter();

2
packages/website/src/components/model/Function.tsx
View File

@@ -1,8 +1,8 @@
import type { ApiFunctionJSON } from '@discordjs/api-extractor-utils';
import { Skeleton } from '@mantine/core';
import { useRouter } from 'next/router';
import { DocContainer } from '../DocContainer';
import { ParametersSection } from '../Sections';
import type { ApiFunctionJSON } from '~/DocModel/ApiNodeJSONEncoder';
export function Function({ data }: { data: ApiFunctionJSON }) {
const router = useRouter();

2
packages/website/src/components/model/Interface.tsx
View File

@@ -1,8 +1,8 @@
import type { ApiInterfaceJSON } from '@discordjs/api-extractor-utils';
import { Skeleton } from '@mantine/core';
import { useRouter } from 'next/router';
import { DocContainer } from '../DocContainer';
import { MethodsSection, PropertiesSection } from '../Sections';
import type { ApiInterfaceJSON } from '~/DocModel/ApiNodeJSONEncoder';
export function Interface({ data }: { data: ApiInterfaceJSON }) {
const router = useRouter();

2
packages/website/src/components/model/TypeAlias.tsx
View File

@@ -1,5 +1,5 @@
import type { ApiTypeAliasJSON } from '@discordjs/api-extractor-utils';
import { DocContainer } from '../DocContainer';
import type { ApiTypeAliasJSON } from '~/DocModel/ApiNodeJSONEncoder';
export function TypeAlias({ data }: { data: ApiTypeAliasJSON }) {
return (

2
packages/website/src/components/model/Variable.tsx
View File

@@ -1,5 +1,5 @@
import type { ApiVariableJSON } from '@discordjs/api-extractor-utils';
import { DocContainer } from '../DocContainer';
import type { ApiVariableJSON } from '~/DocModel/ApiNodeJSONEncoder';
export function Variable({ data }: { data: ApiVariableJSON }) {
return <DocContainer name={data.name} kind={data.kind} excerpt={data.excerpt} summary={data.summary} />;

16
packages/website/src/components/tsdoc/TSDoc.tsx
View File

@@ -1,3 +1,12 @@
import type {
AnyDocNodeJSON,
DocPlainTextJSON,
DocNodeContainerJSON,
DocLinkTagJSON,
DocFencedCodeJSON,
DocBlockJSON,
DocCommentJSON,
} from '@discordjs/api-extractor-utils';
import { Anchor, Box, Code, Text, useMantineColorScheme } from '@mantine/core';
import { DocNodeKind, StandardTags } from '@microsoft/tsdoc';
import Link from 'next/link';
@@ -5,13 +14,6 @@ import { Fragment, useCallback, type ReactNode } from 'react';
import { PrismAsyncLight as SyntaxHighlighter } from 'react-syntax-highlighter';
import { vscDarkPlus, ghcolors } from 'react-syntax-highlighter/dist/cjs/styles/prism';
import { BlockComment } from './BlockComment';
import type { DocBlockJSON } from '~/DocModel/comment/CommentBlock';
import type { AnyDocNodeJSON } from '~/DocModel/comment/CommentNode';
import type { DocNodeContainerJSON } from '~/DocModel/comment/CommentNodeContainer';
import type { DocFencedCodeJSON } from '~/DocModel/comment/FencedCodeCommentNode';
import type { DocLinkTagJSON } from '~/DocModel/comment/LinkTagCommentNode';
import type { DocPlainTextJSON } from '~/DocModel/comment/PlainTextCommentNode';
import type { DocCommentJSON } from '~/DocModel/comment/RootComment';
export function TSDoc({ node }: { node: AnyDocNodeJSON }): JSX.Element {
const { colorScheme } = useMantineColorScheme();

2
packages/website/src/contexts/member.tsx
View File

@@ -1,5 +1,5 @@
import type { ApiItemJSON } from '@discordjs/api-extractor-utils';
import { createContext, useContext, type ReactNode } from 'react';
import type { ApiItemJSON } from '~/DocModel/ApiNodeJSONEncoder';
export const MemberContext = createContext<ApiItemJSON | undefined>(undefined);

25
packages/website/src/pages/docs/[...slug].tsx
View File

@@ -1,6 +1,17 @@
import { readFile } from 'node:fs/promises';
import { join } from 'node:path';
import { cwd } from 'node:process';
import {
findPackage,
getMembers,
type ApiItemJSON,
type ApiClassJSON,
type ApiFunctionJSON,
type ApiInterfaceJSON,
type ApiTypeAliasJSON,
type ApiVariableJSON,
type ApiEnumJSON,
} from '@discordjs/api-extractor-utils';
import { ActionIcon, Affix, Box, LoadingOverlay, Transition } from '@mantine/core';
import { useMediaQuery, useWindowScroll } from '@mantine/hooks';
import { ApiFunction, ApiItemKind, type ApiPackage } from '@microsoft/api-extractor-model';
@@ -15,15 +26,6 @@ import rehypePrettyCode from 'rehype-pretty-code';
import rehypeRaw from 'rehype-raw';
import rehypeSlug from 'rehype-slug';
import remarkGfm from 'remark-gfm';
import type {
ApiClassJSON,
ApiEnumJSON,
ApiFunctionJSON,
ApiInterfaceJSON,
ApiItemJSON,
ApiTypeAliasJSON,
ApiVariableJSON,
} from '~/DocModel/ApiNodeJSONEncoder';
import { SidebarLayout, type SidebarLayoutProps } from '~/components/SidebarLayout';
import { Class } from '~/components/model/Class';
import { Enum } from '~/components/model/Enum';
@@ -35,7 +37,6 @@ import { MemberProvider } from '~/contexts/member';
import { createApiModel } from '~/util/api-model.server';
import { findMember, findMemberByKey } from '~/util/model.server';
import { PACKAGES } from '~/util/packages';
import { findPackage, getMembers } from '~/util/parse.server';
export const getStaticPaths: GetStaticPaths = async () => {
const pkgs = (
@@ -94,11 +95,11 @@ export const getStaticPaths: GetStaticPaths = async () => {
}
const model = createApiModel(data);
const pkg = findPackage(model, packageName);
const pkg = findPackage(model, packageName)!;
return [
{ params: { slug: ['packages', packageName, 'main'] } },
...getMembers(pkg!, 'main').map((member) => {
...getMembers(pkg, 'main').map((member) => {
if (member.kind === ApiItemKind.Function && member.overloadIndex && member.overloadIndex > 1) {
return {
params: {

1
packages/website/src/util/api-extractor.server.ts
View File

@@ -1 +0,0 @@
export * from '@microsoft/api-extractor-model';

7
packages/website/src/util/api-model.server.ts
View File

@@ -1,8 +1,9 @@
/* eslint-disable @typescript-eslint/no-unsafe-member-access */
/* eslint-disable @typescript-eslint/no-unsafe-assignment */
import { ApiItem, ApiModel, type ApiPackage } from '~/util/api-extractor.server';
import { TSDocConfigFile } from '~/util/tsdoc-config.server';
import { TSDocConfiguration } from '~/util/tsdoc.server';
import { ApiModel, ApiItem, type ApiPackage } from '@microsoft/api-extractor-model';
import { TSDocConfiguration } from '@microsoft/tsdoc';
import { TSDocConfigFile } from '@microsoft/tsdoc-config';
export function createApiModel(data: any) {
const model = new ApiModel();

3
packages/website/src/util/model.server.ts
View File

@@ -1,6 +1,5 @@
import { findPackage, ApiNodeJSONEncoder } from '@discordjs/api-extractor-utils';
import type { ApiEntryPoint, ApiModel } from '@microsoft/api-extractor-model';
import { findPackage } from './parse.server';
import { ApiNodeJSONEncoder } from '~/DocModel/ApiNodeJSONEncoder';
export function findMemberByKey(model: ApiModel, packageName: string, containerKey: string, version: string) {
const pkg = findPackage(model, packageName)!;

224
packages/website/src/util/parse.server.ts
View File

@@ -1,224 +0,0 @@
import {
type ApiModel,
type ApiPackage,
type ApiItem,
ApiItemKind,
ApiDocumentedItem,
type Excerpt,
ExcerptTokenKind,
ApiNameMixin,
type ApiPropertyItem,
type ExcerptToken,
type Parameter,
type ApiFunction,
} from '@microsoft/api-extractor-model';
import type { DocNode, DocParagraph, DocPlainText } from '@microsoft/tsdoc';
import { type Meaning, ModuleSource } from '@microsoft/tsdoc/lib-commonjs/beta/DeclarationReference';
import { createCommentNode } from '~/DocModel/comment';
import type { DocBlockJSON } from '~/DocModel/comment/CommentBlock';
export function findPackage(model: ApiModel, name: string): ApiPackage | undefined {
return (model.findMembersByName(name)[0] ?? model.findMembersByName(`@discordjs/${name}`)[0]) as
| ApiPackage
| undefined;
}
export function generatePath(items: readonly ApiItem[], version: string) {
let path = '/docs/packages';
for (const item of items) {
switch (item.kind) {
case ApiItemKind.Model:
case ApiItemKind.EntryPoint:
case ApiItemKind.EnumMember:
break;
case ApiItemKind.Package:
path += `/${item.displayName}`;
break;
case ApiItemKind.Function:
// eslint-disable-next-line no-case-declarations
const functionItem = item as ApiFunction;
path += `/${functionItem.displayName}${
functionItem.overloadIndex && functionItem.overloadIndex > 1 ? `:${functionItem.overloadIndex}` : ''
}:${item.kind}`;
break;
case ApiItemKind.Property:
case ApiItemKind.Method:
case ApiItemKind.MethodSignature:
case ApiItemKind.PropertySignature:
// TODO: Take overloads into account
path += `#${item.displayName}:${item.kind}`;
break;
default:
path += `/${item.displayName}:${item.kind}`;
}
}
return path.replace(/@discordjs\/(.*)\/(.*)?/, `$1/${version}/$2`);
}
export function resolveDocComment(item: ApiDocumentedItem) {
if (!(item instanceof ApiDocumentedItem)) {
return null;
}
const { tsdocComment } = item;
if (!tsdocComment) {
return null;
}
const { summarySection } = tsdocComment;
function recurseNodes(nodes: readonly DocNode[] | undefined): string | null {
if (!nodes) {
return null;
}
for (const node of nodes) {
switch (node.kind) {
case 'Paragraph':
return recurseNodes((node as DocParagraph).nodes);
case 'PlainText':
return (node as DocPlainText).text;
default:
return null;
}
}
return null;
}
return recurseNodes(summarySection.nodes);
}
export function findReferences(model: ApiModel, excerpt: Excerpt) {
const retVal: Set<ApiItem> = new Set();
for (const token of excerpt.spannedTokens) {
switch (token.kind) {
case ExcerptTokenKind.Reference: {
const item = model.resolveDeclarationReference(token.canonicalReference!, undefined).resolvedApiItem;
if (!item) {
break;
}
retVal.add(item);
break;
}
default:
break;
}
}
return retVal;
}
export function resolveName(item: ApiItem) {
if (ApiNameMixin.isBaseClassOf(item)) {
return item.name;
}
return item.displayName;
}
export function getProperties(item: ApiItem) {
const properties: ApiPropertyItem[] = [];
for (const member of item.members) {
switch (member.kind) {
case ApiItemKind.Property:
case ApiItemKind.PropertySignature:
case ApiItemKind.Method:
case ApiItemKind.MethodSignature:
properties.push(member as ApiPropertyItem);
break;
default:
break;
}
}
return properties;
}
export interface TokenDocumentation {
text: string;
path: string | null;
kind: string;
}
export interface ParameterDocumentation {
name: string;
isOptional: boolean;
tokens: TokenDocumentation[];
paramCommentBlock: DocBlockJSON | null;
}
function createDapiTypesURL(meaning: Meaning, name: string) {
const base = 'https://discord-api-types.dev/api/discord-api-types-v10';
switch (meaning) {
case 'type':
return `${base}#${name}`;
default:
return `${base}/${meaning}/${name}`;
}
}
export function genReference(item: ApiItem, version: string) {
return {
name: resolveName(item),
path: generatePath(item.getHierarchy(), version),
};
}
export function genToken(model: ApiModel, token: ExcerptToken, version: string) {
if (token.canonicalReference) {
// @ts-expect-error
token.canonicalReference._navigation = '.';
}
if (
token.canonicalReference?.source instanceof ModuleSource &&
token.canonicalReference.symbol &&
token.canonicalReference.source.packageName === 'discord-api-types' &&
token.canonicalReference.symbol.meaning
) {
return {
kind: token.kind,
text: token.text,
path: createDapiTypesURL(token.canonicalReference.symbol.meaning, token.text),
};
}
const item = token.canonicalReference
? model.resolveDeclarationReference(token.canonicalReference, undefined).resolvedApiItem ?? null
: null;
return {
kind: token.kind,
text: token.text,
path: item ? generatePath(item.getHierarchy(), version) : null,
};
}
export function genParameter(model: ApiModel, param: Parameter, version: string): ParameterDocumentation {
return {
name: param.name,
isOptional: param.isOptional,
tokens: param.parameterTypeExcerpt.spannedTokens.map((token) => genToken(model, token, version)),
paramCommentBlock: param.tsdocParamBlock
? (createCommentNode(param.tsdocParamBlock, model, version) as DocBlockJSON)
: null,
};
}
export function getMembers(pkg: ApiPackage, version: string) {
return pkg.members[0]!.members.map((member) => ({
name: member.displayName,
kind: member.kind as string,
path: generatePath(member.getHierarchy(), version),
containerKey: member.containerKey,
overloadIndex: member.kind === 'Function' ? (member as ApiFunction).overloadIndex : null,
}));
}

1
packages/website/src/util/tsdoc-config.server.ts
View File

@@ -1 +0,0 @@
export * from '@microsoft/tsdoc-config';

1
packages/website/src/util/tsdoc.server.tsx
View File

@@ -1 +0,0 @@
export * from '@microsoft/tsdoc';