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

ci: api-extractor support for docs

Browse Source
This commit is contained in:
iCrawl
2022-06-30 15:46:14 +02:00
parent 525bf031a5
commit b2776c22d4
54 changed files with 2608 additions and 343 deletions
Download Patch File Download Diff File Expand all files Collapse all files

376
packages/builders/api-extractor.json Normal file
View File

@@ -0,0 +1,376 @@
/**
* Config file for API Extractor. For more info, please visit: https://api-extractor.com
*/
{
"$schema": "https://developer.microsoft.com/json-schemas/api-extractor/v7/api-extractor.schema.json",
/**
* Optionally specifies another JSON config file that this file extends from. This provides a way for
* standard settings to be shared across multiple projects.
*
* If the path starts with "./" or "../", the path is resolved relative to the folder of the file that contains
* the "extends" field. Otherwise, the first path segment is interpreted as an NPM package name, and will be
* resolved using NodeJS require().
*
* SUPPORTED TOKENS: none
* DEFAULT VALUE: ""
*/
// "extends": "./shared/api-extractor-base.json"
// "extends": "my-package/include/api-extractor-base.json"
/**
* Determines the "<projectFolder>" token that can be used with other config file settings. The project folder
* typically contains the tsconfig.json and package.json config files, but the path is user-defined.
*
* The path is resolved relative to the folder of the config file that contains the setting.
*
* The default value for "projectFolder" is the token "<lookup>", which means the folder is determined by traversing
* parent folders, starting from the folder containing api-extractor.json, and stopping at the first folder
* that contains a tsconfig.json file. If a tsconfig.json file cannot be found in this way, then an error
* will be reported.
*
* SUPPORTED TOKENS: <lookup>
* DEFAULT VALUE: "<lookup>"
*/
// "projectFolder": "..",
/**
* (REQUIRED) Specifies the .d.ts file to be used as the starting point for analysis. API Extractor
* analyzes the symbols exported by this module.
*
* The file extension must be ".d.ts" and not ".ts".
*
* The path is resolved relative to the folder of the config file that contains the setting; to change this,
* prepend a folder token such as "<projectFolder>".
*
* SUPPORTED TOKENS: <projectFolder>, <packageName>, <unscopedPackageName>
*/
"mainEntryPointFilePath": "<projectFolder>/dist/index.d.ts",
/**
* A list of NPM package names whose exports should be treated as part of this package.
*
* For example, suppose that Webpack is used to generate a distributed bundle for the project "library1",
* and another NPM package "library2" is embedded in this bundle. Some types from library2 may become part
* of the exported API for library1, but by default API Extractor would generate a .d.ts rollup that explicitly
* imports library2. To avoid this, we can specify:
*
* "bundledPackages": [ "library2" ],
*
* This would direct API Extractor to embed those types directly in the .d.ts rollup, as if they had been
* local files for library1.
*/
"bundledPackages": [],
/**
* Determines how the TypeScript compiler engine will be invoked by API Extractor.
*/
"compiler": {
/**
* Specifies the path to the tsconfig.json file to be used by API Extractor when analyzing the project.
*
* The path is resolved relative to the folder of the config file that contains the setting; to change this,
* prepend a folder token such as "<projectFolder>".
*
* Note: This setting will be ignored if "overrideTsconfig" is used.
*
* SUPPORTED TOKENS: <projectFolder>, <packageName>, <unscopedPackageName>
* DEFAULT VALUE: "<projectFolder>/tsconfig.json"
*/
// "tsconfigFilePath": "<projectFolder>/tsconfig.json",
/**
* Provides a compiler configuration that will be used instead of reading the tsconfig.json file from disk.
* The object must conform to the TypeScript tsconfig schema:
*
* http://json.schemastore.org/tsconfig
*
* If omitted, then the tsconfig.json file will be read from the "projectFolder".
*
* DEFAULT VALUE: no overrideTsconfig section
*/
// "overrideTsconfig": {
// . . .
// }
/**
* This option causes the compiler to be invoked with the --skipLibCheck option. This option is not recommended
* and may cause API Extractor to produce incomplete or incorrect declarations, but it may be required when
* dependencies contain declarations that are incompatible with the TypeScript engine that API Extractor uses
* for its analysis. Where possible, the underlying issue should be fixed rather than relying on skipLibCheck.
*
* DEFAULT VALUE: false
*/
// "skipLibCheck": true,
},
/**
* Configures how the API report file (*.api.md) will be generated.
*/
"apiReport": {
/**
* (REQUIRED) Whether to generate an API report.
*/
"enabled": false
/**
* The filename for the API report files. It will be combined with "reportFolder" or "reportTempFolder" to produce
* a full file path.
*
* The file extension should be ".api.md", and the string should not contain a path separator such as "\" or "/".
*
* SUPPORTED TOKENS: <packageName>, <unscopedPackageName>
* DEFAULT VALUE: "<unscopedPackageName>.api.md"
*/
// "reportFileName": "<unscopedPackageName>.api.md",
/**
* Specifies the folder where the API report file is written. The file name portion is determined by
* the "reportFileName" setting.
*
* The API report file is normally tracked by Git. Changes to it can be used to trigger a branch policy,
* e.g. for an API review.
*
* The path is resolved relative to the folder of the config file that contains the setting; to change this,
* prepend a folder token such as "<projectFolder>".
*
* SUPPORTED TOKENS: <projectFolder>, <packageName>, <unscopedPackageName>
* DEFAULT VALUE: "<projectFolder>/temp/"
*/
// "reportFolder": "<projectFolder>/temp/",
/**
* Specifies the folder where the temporary report file is written. The file name portion is determined by
* the "reportFileName" setting.
*
* After the temporary file is written to disk, it is compared with the file in the "reportFolder".
* If they are different, a production build will fail.
*
* The path is resolved relative to the folder of the config file that contains the setting; to change this,
* prepend a folder token such as "<projectFolder>".
*
* SUPPORTED TOKENS: <projectFolder>, <packageName>, <unscopedPackageName>
* DEFAULT VALUE: "<projectFolder>/temp/"
*/
// "reportTempFolder": "<projectFolder>/temp/"
},
/**
* Configures how the doc model file (*.api.json) will be generated.
*/
"docModel": {
/**
* (REQUIRED) Whether to generate a doc model file.
*/
"enabled": true,
/**
* The output path for the doc model file. The file extension should be ".api.json".
*
* The path is resolved relative to the folder of the config file that contains the setting; to change this,
* prepend a folder token such as "<projectFolder>".
*
* SUPPORTED TOKENS: <projectFolder>, <packageName>, <unscopedPackageName>
* DEFAULT VALUE: "<projectFolder>/temp/<unscopedPackageName>.api.json"
*/
"apiJsonFilePath": "<projectFolder>/docs/docs.api.json"
},
/**
* Configures how the .d.ts rollup file will be generated.
*/
"dtsRollup": {
/**
* (REQUIRED) Whether to generate the .d.ts rollup file.
*/
"enabled": false
/**
* Specifies the output path for a .d.ts rollup file to be generated without any trimming.
* This file will include all declarations that are exported by the main entry point.
*
* If the path is an empty string, then this file will not be written.
*
* The path is resolved relative to the folder of the config file that contains the setting; to change this,
* prepend a folder token such as "<projectFolder>".
*
* SUPPORTED TOKENS: <projectFolder>, <packageName>, <unscopedPackageName>
* DEFAULT VALUE: "<projectFolder>/dist/<unscopedPackageName>.d.ts"
*/
// "untrimmedFilePath": "<projectFolder>/dist/<unscopedPackageName>.d.ts",
/**
* Specifies the output path for a .d.ts rollup file to be generated with trimming for an "alpha" release.
* This file will include only declarations that are marked as "@public", "@beta", or "@alpha".
*
* The path is resolved relative to the folder of the config file that contains the setting; to change this,
* prepend a folder token such as "<projectFolder>".
*
* SUPPORTED TOKENS: <projectFolder>, <packageName>, <unscopedPackageName>
* DEFAULT VALUE: ""
*/
// "alphaTrimmedFilePath": "<projectFolder>/dist/<unscopedPackageName>-alpha.d.ts",
/**
* Specifies the output path for a .d.ts rollup file to be generated with trimming for a "beta" release.
* This file will include only declarations that are marked as "@public" or "@beta".
*
* The path is resolved relative to the folder of the config file that contains the setting; to change this,
* prepend a folder token such as "<projectFolder>".
*
* SUPPORTED TOKENS: <projectFolder>, <packageName>, <unscopedPackageName>
* DEFAULT VALUE: ""
*/
// "betaTrimmedFilePath": "<projectFolder>/dist/<unscopedPackageName>-beta.d.ts",
/**
* Specifies the output path for a .d.ts rollup file to be generated with trimming for a "public" release.
* This file will include only declarations that are marked as "@public".
*
* If the path is an empty string, then this file will not be written.
*
* The path is resolved relative to the folder of the config file that contains the setting; to change this,
* prepend a folder token such as "<projectFolder>".
*
* SUPPORTED TOKENS: <projectFolder>, <packageName>, <unscopedPackageName>
* DEFAULT VALUE: ""
*/
// "publicTrimmedFilePath": "<projectFolder>/dist/<unscopedPackageName>-public.d.ts",
/**
* When a declaration is trimmed, by default it will be replaced by a code comment such as
* "Excluded from this release type: exampleMember". Set "omitTrimmingComments" to true to remove the
* declaration completely.
*
* DEFAULT VALUE: false
*/
// "omitTrimmingComments": true
},
/**
* Configures how the tsdoc-metadata.json file will be generated.
*/
"tsdocMetadata": {
/**
* Whether to generate the tsdoc-metadata.json file.
*
* DEFAULT VALUE: true
*/
// "enabled": true,
/**
* Specifies where the TSDoc metadata file should be written.
*
* The path is resolved relative to the folder of the config file that contains the setting; to change this,
* prepend a folder token such as "<projectFolder>".
*
* The default value is "<lookup>", which causes the path to be automatically inferred from the "tsdocMetadata",
* "typings" or "main" fields of the project's package.json. If none of these fields are set, the lookup
* falls back to "tsdoc-metadata.json" in the package folder.
*
* SUPPORTED TOKENS: <projectFolder>, <packageName>, <unscopedPackageName>
* DEFAULT VALUE: "<lookup>"
*/
// "tsdocMetadataFilePath": "<projectFolder>/dist/tsdoc-metadata.json"
},
/**
* Specifies what type of newlines API Extractor should use when writing output files. By default, the output files
* will be written with Windows-style newlines. To use POSIX-style newlines, specify "lf" instead.
* To use the OS's default newline kind, specify "os".
*
* DEFAULT VALUE: "crlf"
*/
"newlineKind": "lf",
/**
* Configures how API Extractor reports error and warning messages produced during analysis.
*
* There are three sources of messages: compiler messages, API Extractor messages, and TSDoc messages.
*/
"messages": {
/**
* Configures handling of diagnostic messages reported by the TypeScript compiler engine while analyzing
* the input .d.ts files.
*
* TypeScript message identifiers start with "TS" followed by an integer. For example: "TS2551"
*
* DEFAULT VALUE: A single "default" entry with logLevel=warning.
*/
"compilerMessageReporting": {
/**
* Configures the default routing for messages that don't match an explicit rule in this table.
*/
"default": {
/**
* Specifies whether the message should be written to the the tool's output log. Note that
* the "addToApiReportFile" property may supersede this option.
*
* Possible values: "error", "warning", "none"
*
* Errors cause the build to fail and return a nonzero exit code. Warnings cause a production build fail
* and return a nonzero exit code. For a non-production build (e.g. when "api-extractor run" includes
* the "--local" option), the warning is displayed but the build will not fail.
*
* DEFAULT VALUE: "warning"
*/
"logLevel": "warning"
/**
* When addToApiReportFile is true: If API Extractor is configured to write an API report file (.api.md),
* then the message will be written inside that file; otherwise, the message is instead logged according to
* the "logLevel" option.
*
* DEFAULT VALUE: false
*/
// "addToApiReportFile": false
}
// "TS2551": {
// "logLevel": "warning",
// "addToApiReportFile": true
// },
//
// . . .
},
/**
* Configures handling of messages reported by API Extractor during its analysis.
*
* API Extractor message identifiers start with "ae-". For example: "ae-extra-release-tag"
*
* DEFAULT VALUE: See api-extractor-defaults.json for the complete table of extractorMessageReporting mappings
*/
"extractorMessageReporting": {
"default": {
"logLevel": "warning"
// "addToApiReportFile": false
}
// "ae-extra-release-tag": {
// "logLevel": "warning",
// "addToApiReportFile": true
// },
//
// . . .
},
/**
* Configures handling of messages reported by the TSDoc parser when analyzing code comments.
*
* TSDoc message identifiers start with "tsdoc-". For example: "tsdoc-link-tag-unescaped-text"
*
* DEFAULT VALUE: A single "default" entry with logLevel=warning.
*/
"tsdocMessageReporting": {
"default": {
"logLevel": "warning"
// "addToApiReportFile": false
}
// "tsdoc-link-tag-unescaped-text": {
// "logLevel": "warning",
// "addToApiReportFile": true
// },
//
// . . .
}
}
}

3
packages/builders/package.json
View File

@@ -6,7 +6,7 @@
"build": "tsup",
"lint": "prettier --cache --check . && eslint src __tests__ --ext mjs,js,ts --cache",
"format": "prettier --cache --write . && eslint src __tests__ --ext mjs,js,ts --fix --cache",
"docs": "docgen -i src/index.ts -c docs/index.json -o docs/docs.json --typescript",
"docs": "docgen -i src/index.ts -c docs/index.json -o docs/docs.json --typescript && api-extractor run --local",
"prepack": "yarn build && yarn lint",
"changelog": "git cliff --prepend ./CHANGELOG.md -u -c ./cliff.toml -r ../../ --include-path 'packages/builders/*'",
"release": "cliff-jumper"
@@ -62,6 +62,7 @@
"@discordjs/docgen": "workspace:^",
"@discordjs/scripts": "workspace:^",
"@favware/cliff-jumper": "^1.8.3",
"@microsoft/api-extractor": "^7.28.2",
"@types/node": "^18.0.0",
"eslint": "^8.18.0",
"prettier": "^2.7.1",

7
packages/builders/src/components/ActionRow.ts
View File

@@ -36,8 +36,8 @@ export class ActionRowBuilder<T extends AnyComponentBuilder> extends ComponentBu
/**
* Adds components to this action row.
* @param components The components to add to this action row.
* @returns
*
* @param components - The components to add to this action row.
*/
public addComponents(...components: RestOrArray<T>) {
this.components.push(...normalizeArray(components));
@@ -46,7 +46,8 @@ export class ActionRowBuilder<T extends AnyComponentBuilder> extends ComponentBu
/**
* Sets the components in this action row
* @param components The components to set this row to
*
* @param components - The components to set this row to
*/
public setComponents(...components: RestOrArray<T>) {
this.components.splice(0, this.components.length, ...normalizeArray(components));

3
packages/builders/src/components/Components.ts
View File

@@ -11,7 +11,8 @@ export interface MappedComponentTypes {
/**
* Factory for creating components from API data
* @param data The api data to transform to a component class
*
* @param data - The api data to transform to a component class
*/
export function createComponentBuilder<T extends keyof MappedComponentTypes>(
data: (APIMessageComponent | APIModalComponent) & { type: T },

18
packages/builders/src/components/button/UnsafeButton.ts
View File

@@ -18,7 +18,8 @@ export class UnsafeButtonBuilder extends ComponentBuilder<APIButtonComponent> {
/**
* Sets the style of this button
* @param style The style of the button
*
* @param style - The style of the button
*/
public setStyle(style: ButtonStyle) {
this.data.style = style;
@@ -27,7 +28,8 @@ export class UnsafeButtonBuilder extends ComponentBuilder<APIButtonComponent> {
/**
* Sets the URL for this button
* @param url The URL to open when this button is clicked
*
* @param url - The URL to open when this button is clicked
*/
public setURL(url: string) {
(this.data as APIButtonComponentWithURL).url = url;
@@ -36,7 +38,8 @@ export class UnsafeButtonBuilder extends ComponentBuilder<APIButtonComponent> {
/**
* Sets the custom Id for this button
* @param customId The custom id to use for this button
*
* @param customId - The custom id to use for this button
*/
public setCustomId(customId: string) {
(this.data as APIButtonComponentWithCustomId).custom_id = customId;
@@ -45,7 +48,8 @@ export class UnsafeButtonBuilder extends ComponentBuilder<APIButtonComponent> {
/**
* Sets the emoji to display on this button
* @param emoji The emoji to display on this button
*
* @param emoji - The emoji to display on this button
*/
public setEmoji(emoji: APIMessageComponentEmoji) {
this.data.emoji = emoji;
@@ -54,7 +58,8 @@ export class UnsafeButtonBuilder extends ComponentBuilder<APIButtonComponent> {
/**
* Sets whether this button is disable or not
* @param disabled Whether or not to disable this button or not
*
* @param disabled - Whether or not to disable this button or not
*/
public setDisabled(disabled = true) {
this.data.disabled = disabled;
@@ -63,7 +68,8 @@ export class UnsafeButtonBuilder extends ComponentBuilder<APIButtonComponent> {
/**
* Sets the label for this button
* @param label The label to display on this button
*
* @param label - The label to display on this button
*/
public setLabel(label: string) {
this.data.label = label;

22
packages/builders/src/components/selectMenu/UnsafeSelectMenu.ts
View File

@@ -20,7 +20,8 @@ export class UnsafeSelectMenuBuilder extends ComponentBuilder<APISelectMenuCompo
/**
* Sets the placeholder for this select menu
* @param placeholder The placeholder to use for this select menu
*
* @param placeholder - The placeholder to use for this select menu
*/
public setPlaceholder(placeholder: string) {
this.data.placeholder = placeholder;
@@ -29,7 +30,8 @@ export class UnsafeSelectMenuBuilder extends ComponentBuilder<APISelectMenuCompo
/**
* Sets the minimum values that must be selected in the select menu
* @param minValues The minimum values that must be selected
*
* @param minValues - The minimum values that must be selected
*/
public setMinValues(minValues: number) {
this.data.min_values = minValues;
@@ -38,7 +40,8 @@ export class UnsafeSelectMenuBuilder extends ComponentBuilder<APISelectMenuCompo
/**
* Sets the maximum values that must be selected in the select menu
* @param minValues The maximum values that must be selected
*
* @param minValues - The maximum values that must be selected
*/
public setMaxValues(maxValues: number) {
this.data.max_values = maxValues;
@@ -47,7 +50,8 @@ export class UnsafeSelectMenuBuilder extends ComponentBuilder<APISelectMenuCompo
/**
* Sets the custom Id for this select menu
* @param customId The custom id to use for this select menu
*
* @param customId - The custom id to use for this select menu
*/
public setCustomId(customId: string) {
this.data.custom_id = customId;
@@ -56,7 +60,8 @@ export class UnsafeSelectMenuBuilder extends ComponentBuilder<APISelectMenuCompo
/**
* Sets whether or not this select menu is disabled
* @param disabled Whether or not this select menu is disabled
*
* @param disabled - Whether or not this select menu is disabled
*/
public setDisabled(disabled = true) {
this.data.disabled = disabled;
@@ -65,8 +70,8 @@ export class UnsafeSelectMenuBuilder extends ComponentBuilder<APISelectMenuCompo
/**
* Adds options to this select menu
* @param options The options to add to this select menu
* @returns
*
* @param options - The options to add to this select menu
*/
public addOptions(...options: RestOrArray<UnsafeSelectMenuOptionBuilder | APISelectMenuOption>) {
this.options.push(
@@ -79,7 +84,8 @@ export class UnsafeSelectMenuBuilder extends ComponentBuilder<APISelectMenuCompo
/**
* Sets the options on this select menu
* @param options The options to set on this select menu
*
* @param options - The options to set on this select menu
*/
public setOptions(...options: RestOrArray<UnsafeSelectMenuOptionBuilder | APISelectMenuOption>) {
this.options.splice(

15
packages/builders/src/components/selectMenu/UnsafeSelectMenuOption.ts
View File

@@ -8,7 +8,8 @@ export class UnsafeSelectMenuOptionBuilder {
/**
* Sets the label of this option
* @param label The label to show on this option
*
* @param label - The label to show on this option
*/
public setLabel(label: string) {
this.data.label = label;
@@ -17,7 +18,8 @@ export class UnsafeSelectMenuOptionBuilder {
/**
* Sets the value of this option
* @param value The value of this option
*
* @param value - The value of this option
*/
public setValue(value: string) {
this.data.value = value;
@@ -26,7 +28,8 @@ export class UnsafeSelectMenuOptionBuilder {
/**
* Sets the description of this option.
* @param description The description of this option
*
* @param description - The description of this option
*/
public setDescription(description: string) {
this.data.description = description;
@@ -35,7 +38,8 @@ export class UnsafeSelectMenuOptionBuilder {
/**
* Sets whether this option is selected by default
* @param isDefault Whether this option is selected by default
*
* @param isDefault - Whether this option is selected by default
*/
public setDefault(isDefault = true) {
this.data.default = isDefault;
@@ -44,7 +48,8 @@ export class UnsafeSelectMenuOptionBuilder {
/**
* Sets the emoji to display on this option
* @param emoji The emoji to display on this option
*
* @param emoji - The emoji to display on this option
*/
public setEmoji(emoji: APIMessageComponentEmoji) {
this.data.emoji = emoji;

24
packages/builders/src/components/textInput/UnsafeTextInput.ts
View File

@@ -9,7 +9,8 @@ export class UnsafeTextInputBuilder extends ComponentBuilder<APITextInputCompone
/**
* Sets the custom id for this text input
* @param customId The custom id of this text input
*
* @param customId - The custom id of this text input
*/
public setCustomId(customId: string) {
this.data.custom_id = customId;
@@ -18,7 +19,8 @@ export class UnsafeTextInputBuilder extends ComponentBuilder<APITextInputCompone
/**
* Sets the label for this text input
* @param label The label for this text input
*
* @param label - The label for this text input
*/
public setLabel(label: string) {
this.data.label = label;
@@ -27,7 +29,8 @@ export class UnsafeTextInputBuilder extends ComponentBuilder<APITextInputCompone
/**
* Sets the style for this text input
* @param style The style for this text input
*
* @param style - The style for this text input
*/
public setStyle(style: TextInputStyle) {
this.data.style = style;
@@ -36,7 +39,8 @@ export class UnsafeTextInputBuilder extends ComponentBuilder<APITextInputCompone
/**
* Sets the minimum length of text for this text input
* @param minLength The minimum length of text for this text input
*
* @param minLength - The minimum length of text for this text input
*/
public setMinLength(minLength: number) {
this.data.min_length = minLength;
@@ -45,7 +49,8 @@ export class UnsafeTextInputBuilder extends ComponentBuilder<APITextInputCompone
/**
* Sets the maximum length of text for this text input
* @param maxLength The maximum length of text for this text input
*
* @param maxLength - The maximum length of text for this text input
*/
public setMaxLength(maxLength: number) {
this.data.max_length = maxLength;
@@ -54,7 +59,8 @@ export class UnsafeTextInputBuilder extends ComponentBuilder<APITextInputCompone
/**
* Sets the placeholder of this text input
* @param placeholder The placeholder of this text input
*
* @param placeholder - The placeholder of this text input
*/
public setPlaceholder(placeholder: string) {
this.data.placeholder = placeholder;
@@ -63,7 +69,8 @@ export class UnsafeTextInputBuilder extends ComponentBuilder<APITextInputCompone
/**
* Sets the value of this text input
* @param value The value for this text input
*
* @param value - The value for this text input
*/
public setValue(value: string) {
this.data.value = value;
@@ -72,7 +79,8 @@ export class UnsafeTextInputBuilder extends ComponentBuilder<APITextInputCompone
/**
* Sets whether this text input is required or not
* @param required Whether this text input is required or not
*
* @param required - Whether this text input is required or not
*/
public setRequired(required = true) {
this.data.required = required;

16
packages/builders/src/interactions/contextMenuCommands/ContextMenuCommandBuilder.ts
View File

@@ -53,7 +53,7 @@ export class ContextMenuCommandBuilder {
/**
* Sets the name
*
* @param name The name
* @param name - The name
*/
public setName(name: string) {
// Assert the name matches the conditions
@@ -67,7 +67,7 @@ export class ContextMenuCommandBuilder {
/**
* Sets the type
*
* @param type The type
* @param type - The type
*/
public setType(type: ContextMenuCommandType) {
// Assert the type is valid
@@ -83,7 +83,7 @@ export class ContextMenuCommandBuilder {
*
* **Note**: If set to `false`, you will have to later `PUT` the permissions for this command.
*
* @param value Whether or not to enable this command by default
* @param value - Whether or not to enable this command by default
*
* @see https://discord.com/developers/docs/interactions/application-commands#permissions
* @deprecated Use `setDefaultMemberPermissions` or `setDMPermission` instead.
@@ -102,7 +102,7 @@ export class ContextMenuCommandBuilder {
*
* **Note:** You can set this to `'0'` to disable the command by default.
*
* @param permissions The permissions bit field to set
* @param permissions - The permissions bit field to set
*
* @see https://discord.com/developers/docs/interactions/application-commands#permissions
*/
@@ -119,7 +119,7 @@ export class ContextMenuCommandBuilder {
* Sets if the command is available in DMs with the application, only for globally-scoped commands.
* By default, commands are visible.
*
* @param enabled If the command should be enabled in DMs
* @param enabled - If the command should be enabled in DMs
*
* @see https://discord.com/developers/docs/interactions/application-commands#permissions
*/
@@ -135,8 +135,8 @@ export class ContextMenuCommandBuilder {
/**
* Sets a name localization
*
* @param locale The locale to set a description for
* @param localizedName The localized description for the given locale
* @param locale - The locale to set a description for
* @param localizedName - The localized description for the given locale
*/
public setNameLocalization(locale: LocaleString, localizedName: string | null) {
if (!this.name_localizations) {
@@ -159,7 +159,7 @@ export class ContextMenuCommandBuilder {
/**
* Sets the name localizations
*
* @param localizedNames The dictionary of localized descriptions to set
* @param localizedNames - The dictionary of localized descriptions to set
*/
public setNameLocalizations(localizedNames: LocalizationMap | null) {
if (localizedNames === null) {

12
packages/builders/src/interactions/modals/UnsafeModal.ts
View File

@@ -18,7 +18,8 @@ export class UnsafeModalBuilder implements JSONEncodable<APIModalInteractionResp
/**
* Sets the title of the modal
* @param title The title of the modal
*
* @param title - The title of the modal
*/
public setTitle(title: string) {
this.data.title = title;
@@ -27,7 +28,8 @@ export class UnsafeModalBuilder implements JSONEncodable<APIModalInteractionResp
/**
* Sets the custom id of the modal
* @param customId The custom id of this modal
*
* @param customId - The custom id of this modal
*/
public setCustomId(customId: string) {
this.data.custom_id = customId;
@@ -36,7 +38,8 @@ export class UnsafeModalBuilder implements JSONEncodable<APIModalInteractionResp
/**
* Adds components to this modal
* @param components The components to add to this modal
*
* @param components - The components to add to this modal
*/
public addComponents(
...components: RestOrArray<
@@ -55,7 +58,8 @@ export class UnsafeModalBuilder implements JSONEncodable<APIModalInteractionResp
/**
* Sets the components in this modal
* @param components The components to set this modal to
*
* @param components - The components to set this modal to
*/
public setComponents(...components: RestOrArray<ActionRowBuilder<ModalActionRowComponentBuilder>>) {
this.components.splice(0, this.components.length, ...normalizeArray(components));

10
packages/builders/src/interactions/slashCommands/SlashCommandBuilder.ts
View File

@@ -86,7 +86,7 @@ export class SlashCommandBuilder {
*
* **Note**: If set to `false`, you will have to later `PUT` the permissions for this command.
*
* @param value Whether or not to enable this command by default
* @param value - Whether or not to enable this command by default
*
* @see https://discord.com/developers/docs/interactions/application-commands#permissions
* @deprecated Use `setDefaultMemberPermissions` or `setDMPermission` instead.
@@ -105,7 +105,7 @@ export class SlashCommandBuilder {
*
* **Note:** You can set this to `'0'` to disable the command by default.
*
* @param permissions The permissions bit field to set
* @param permissions - The permissions bit field to set
*
* @see https://discord.com/developers/docs/interactions/application-commands#permissions
*/
@@ -122,7 +122,7 @@ export class SlashCommandBuilder {
* Sets if the command is available in DMs with the application, only for globally-scoped commands.
* By default, commands are visible.
*
* @param enabled If the command should be enabled in DMs
* @param enabled - If the command should be enabled in DMs
*
* @see https://discord.com/developers/docs/interactions/application-commands#permissions
*/
@@ -138,7 +138,7 @@ export class SlashCommandBuilder {
/**
* Adds a new subcommand group to this command
*
* @param input A function that returns a subcommand group builder, or an already built builder
* @param input - A function that returns a subcommand group builder, or an already built builder
*/
public addSubcommandGroup(
input:
@@ -164,7 +164,7 @@ export class SlashCommandBuilder {
/**
* Adds a new subcommand to this command
*
* @param input A function that returns a subcommand builder, or an already built builder
* @param input - A function that returns a subcommand builder, or an already built builder
*/
public addSubcommand(
input:

2
packages/builders/src/interactions/slashCommands/SlashCommandSubcommands.ts
View File

@@ -35,7 +35,7 @@ export class SlashCommandSubcommandGroupBuilder implements ToAPIApplicationComma
/**
* Adds a new subcommand to this group
*
* @param input A function that returns a subcommand builder, or an already built builder
* @param input - A function that returns a subcommand builder, or an already built builder
*/
public addSubcommand(
input:

6
packages/builders/src/interactions/slashCommands/mixins/ApplicationCommandNumericOptionMinMaxValueMixin.ts
View File

@@ -4,13 +4,15 @@ export abstract class ApplicationCommandNumericOptionMinMaxValueMixin {
/**
* Sets the maximum number value of this option
* @param max The maximum value this option can be
*
* @param max - The maximum value this option can be
*/
public abstract setMaxValue(max: number): this;
/**
* Sets the minimum number value of this option
* @param min The minimum value this option can be
*
* @param min - The minimum value this option can be
*/
public abstract setMinValue(min: number): this;
}

2
packages/builders/src/interactions/slashCommands/mixins/ApplicationCommandOptionBase.ts
View File

@@ -10,7 +10,7 @@ export abstract class ApplicationCommandOptionBase extends SharedNameAndDescript
/**
* Marks the option as required
*
* @param required If this option should be required
* @param required - If this option should be required
*/
public setRequired(required: boolean) {
// Assert that you actually passed a boolean

2
packages/builders/src/interactions/slashCommands/mixins/ApplicationCommandOptionChannelTypesMixin.ts
View File

@@ -23,7 +23,7 @@ export class ApplicationCommandOptionChannelTypesMixin {
/**
* Adds channel types to this option
*
* @param channelTypes The channel types to add
* @param channelTypes - The channel types to add
*/
public addChannelTypes(...channelTypes: ApplicationCommandOptionAllowedChannelTypes[]) {
if (this.channel_types === undefined) {

4
packages/builders/src/interactions/slashCommands/mixins/ApplicationCommandOptionWithChoicesAndAutocompleteMixin.ts
View File

@@ -21,7 +21,7 @@ export class ApplicationCommandOptionWithChoicesAndAutocompleteMixin<T extends s
/**
* Adds multiple choices for this option
*
* @param choices The choices to add
* @param choices - The choices to add
*/
public addChoices(...choices: APIApplicationCommandOptionChoice<T>[]): this {
if (choices.length > 0 && this.autocomplete) {
@@ -65,7 +65,7 @@ export class ApplicationCommandOptionWithChoicesAndAutocompleteMixin<T extends s
/**
* Marks the option as autocompletable
* @param autocomplete If this option should be autocompletable
* @param autocomplete - If this option should be autocompletable
*/
public setAutocomplete(autocomplete: boolean): this {
// Assert that you actually passed a boolean

16
packages/builders/src/interactions/slashCommands/mixins/NameAndDescription.ts
View File

@@ -10,7 +10,7 @@ export class SharedNameAndDescription {
/**
* Sets the name
*
* @param name The name
* @param name - The name
*/
public setName(name: string): this {
// Assert the name matches the conditions
@@ -24,7 +24,7 @@ export class SharedNameAndDescription {
/**
* Sets the description
*
* @param description The description
* @param description - The description
*/
public setDescription(description: string) {
// Assert the description matches the conditions
@@ -38,8 +38,8 @@ export class SharedNameAndDescription {
/**
* Sets a name localization
*
* @param locale The locale to set a description for
* @param localizedName The localized description for the given locale
* @param locale - The locale to set a description for
* @param localizedName - The localized description for the given locale
*/
public setNameLocalization(locale: LocaleString, localizedName: string | null) {
if (!this.name_localizations) {
@@ -62,7 +62,7 @@ export class SharedNameAndDescription {
/**
* Sets the name localizations
*
* @param localizedNames The dictionary of localized descriptions to set
* @param localizedNames - The dictionary of localized descriptions to set
*/
public setNameLocalizations(localizedNames: LocalizationMap | null) {
if (localizedNames === null) {
@@ -81,8 +81,8 @@ export class SharedNameAndDescription {
/**
* Sets a description localization
*
* @param locale The locale to set a description for
* @param localizedDescription The localized description for the given locale
* @param locale - The locale to set a description for
* @param localizedDescription - The localized description for the given locale
*/
public setDescriptionLocalization(locale: LocaleString, localizedDescription: string | null) {
if (!this.description_localizations) {
@@ -105,7 +105,7 @@ export class SharedNameAndDescription {
/**
* Sets the description localizations
*
* @param localizedDescriptions The dictionary of localized descriptions to set
* @param localizedDescriptions - The dictionary of localized descriptions to set
*/
public setDescriptionLocalizations(localizedDescriptions: LocalizationMap | null) {
if (localizedDescriptions === null) {

18
packages/builders/src/interactions/slashCommands/mixins/SharedSlashCommandOptions.ts
View File

@@ -17,7 +17,7 @@ export class SharedSlashCommandOptions<ShouldOmitSubcommandFunctions = true> {
/**
* Adds a boolean option
*
* @param input A function that returns an option builder, or an already built builder
* @param input - A function that returns an option builder, or an already built builder
*/
public addBooleanOption(
input: SlashCommandBooleanOption | ((builder: SlashCommandBooleanOption) => SlashCommandBooleanOption),
@@ -28,7 +28,7 @@ export class SharedSlashCommandOptions<ShouldOmitSubcommandFunctions = true> {
/**
* Adds a user option
*
* @param input A function that returns an option builder, or an already built builder
* @param input - A function that returns an option builder, or an already built builder
*/
public addUserOption(input: SlashCommandUserOption | ((builder: SlashCommandUserOption) => SlashCommandUserOption)) {
return this._sharedAddOptionMethod(input, SlashCommandUserOption);
@@ -37,7 +37,7 @@ export class SharedSlashCommandOptions<ShouldOmitSubcommandFunctions = true> {
/**
* Adds a channel option
*
* @param input A function that returns an option builder, or an already built builder
* @param input - A function that returns an option builder, or an already built builder
*/
public addChannelOption(
input: SlashCommandChannelOption | ((builder: SlashCommandChannelOption) => SlashCommandChannelOption),
@@ -48,7 +48,7 @@ export class SharedSlashCommandOptions<ShouldOmitSubcommandFunctions = true> {
/**
* Adds a role option
*
* @param input A function that returns an option builder, or an already built builder
* @param input - A function that returns an option builder, or an already built builder
*/
public addRoleOption(input: SlashCommandRoleOption | ((builder: SlashCommandRoleOption) => SlashCommandRoleOption)) {
return this._sharedAddOptionMethod(input, SlashCommandRoleOption);
@@ -57,7 +57,7 @@ export class SharedSlashCommandOptions<ShouldOmitSubcommandFunctions = true> {
/**
* Adds an attachment option
*
* @param input A function that returns an option builder, or an already built builder
* @param input - A function that returns an option builder, or an already built builder
*/
public addAttachmentOption(
input: SlashCommandAttachmentOption | ((builder: SlashCommandAttachmentOption) => SlashCommandAttachmentOption),
@@ -68,7 +68,7 @@ export class SharedSlashCommandOptions<ShouldOmitSubcommandFunctions = true> {
/**
* Adds a mentionable option
*
* @param input A function that returns an option builder, or an already built builder
* @param input - A function that returns an option builder, or an already built builder
*/
public addMentionableOption(
input: SlashCommandMentionableOption | ((builder: SlashCommandMentionableOption) => SlashCommandMentionableOption),
@@ -79,7 +79,7 @@ export class SharedSlashCommandOptions<ShouldOmitSubcommandFunctions = true> {
/**
* Adds a string option
*
* @param input A function that returns an option builder, or an already built builder
* @param input - A function that returns an option builder, or an already built builder
*/
public addStringOption(
input:
@@ -99,7 +99,7 @@ export class SharedSlashCommandOptions<ShouldOmitSubcommandFunctions = true> {
/**
* Adds an integer option
*
* @param input A function that returns an option builder, or an already built builder
* @param input - A function that returns an option builder, or an already built builder
*/
public addIntegerOption(
input:
@@ -119,7 +119,7 @@ export class SharedSlashCommandOptions<ShouldOmitSubcommandFunctions = true> {
/**
* Adds a number option
*
* @param input A function that returns an option builder, or an already built builder
* @param input - A function that returns an option builder, or an already built builder
*/
public addNumberOption(
input:

29
packages/builders/src/messages/embed/UnsafeEmbed.ts
View File

@@ -43,7 +43,7 @@ export class UnsafeEmbedBuilder {
/**
* Adds fields to the embed (max 25)
*
* @param fields The fields to add
* @param fields - The fields to add
*/
public addFields(...fields: RestOrArray<APIEmbedField>): this {
fields = normalizeArray(fields);
@@ -55,9 +55,9 @@ export class UnsafeEmbedBuilder {
/**
* Removes, replaces, or inserts fields in the embed (max 25)
*
* @param index The index to start at
* @param deleteCount The number of fields to remove
* @param fields The replacing field objects
* @param index - The index to start at
* @param deleteCount - The number of fields to remove
* @param fields - The replacing field objects
*/
public spliceFields(index: number, deleteCount: number, ...fields: APIEmbedField[]): this {
if (this.data.fields) this.data.fields.splice(index, deleteCount, ...fields);
@@ -67,7 +67,8 @@ export class UnsafeEmbedBuilder {
/**
* Sets the embed's fields (max 25).
* @param fields The fields to set
*
* @param fields - The fields to set
*/
public setFields(...fields: RestOrArray<APIEmbedField>) {
this.spliceFields(0, this.data.fields?.length ?? 0, ...normalizeArray(fields));
@@ -77,7 +78,7 @@ export class UnsafeEmbedBuilder {
/**
* Sets the author of this embed
*
* @param options The options for the author
* @param options - The options for the author
*/
public setAuthor(options: EmbedAuthorOptions | null): this {
if (options === null) {
@@ -92,7 +93,7 @@ export class UnsafeEmbedBuilder {
/**
* Sets the color of this embed
*
* @param color The color of the embed
* @param color - The color of the embed
*/
public setColor(color: number | RGBTuple | null): this {
if (Array.isArray(color)) {
@@ -107,7 +108,7 @@ export class UnsafeEmbedBuilder {
/**
* Sets the description of this embed
*
* @param description The description
* @param description - The description
*/
public setDescription(description: string | null): this {
this.data.description = description ?? undefined;
@@ -117,7 +118,7 @@ export class UnsafeEmbedBuilder {
/**
* Sets the footer of this embed
*
* @param options The options for the footer
* @param options - The options for the footer
*/
public setFooter(options: EmbedFooterOptions | null): this {
if (options === null) {
@@ -132,7 +133,7 @@ export class UnsafeEmbedBuilder {
/**
* Sets the image of this embed
*
* @param url The URL of the image
* @param url - The URL of the image
*/
public setImage(url: string | null): this {
this.data.image = url ? { url } : undefined;
@@ -142,7 +143,7 @@ export class UnsafeEmbedBuilder {
/**
* Sets the thumbnail of this embed
*
* @param url The URL of the thumbnail
* @param url - The URL of the thumbnail
*/
public setThumbnail(url: string | null): this {
this.data.thumbnail = url ? { url } : undefined;
@@ -152,7 +153,7 @@ export class UnsafeEmbedBuilder {
/**
* Sets the timestamp of this embed
*
* @param timestamp The timestamp or date
* @param timestamp - The timestamp or date
*/
public setTimestamp(timestamp: number | Date | null = Date.now()): this {
this.data.timestamp = timestamp ? new Date(timestamp).toISOString() : undefined;
@@ -162,7 +163,7 @@ export class UnsafeEmbedBuilder {
/**
* Sets the title of this embed
*
* @param title The title
* @param title - The title
*/
public setTitle(title: string | null): this {
this.data.title = title ?? undefined;
@@ -172,7 +173,7 @@ export class UnsafeEmbedBuilder {
/**
* Sets the URL of this embed
*
* @param url The URL
* @param url - The URL
*/
public setURL(url: string | null): this {
this.data.url = url ?? undefined;

74
packages/builders/src/messages/formatters.ts
View File

@@ -4,15 +4,15 @@ import type { Snowflake } from 'discord-api-types/globals';
/**
* Wraps the content inside a codeblock with no language
*
* @param content The content to wrap
* @param content - The content to wrap
*/
export function codeBlock<C extends string>(content: C): `\`\`\`\n${C}\`\`\``;
/**
* Wraps the content inside a codeblock with the specified language
*
* @param language The language for the codeblock
* @param content The content to wrap
* @param language - The language for the codeblock
* @param content - The content to wrap
*/
export function codeBlock<L extends string, C extends string>(language: L, content: C): `\`\`\`${L}\n${C}\`\`\``;
export function codeBlock(language: string, content?: string): string {
@@ -22,7 +22,7 @@ export function codeBlock(language: string, content?: string): string {
/**
* Wraps the content inside \`backticks\`, which formats it as inline code
*
* @param content The content to wrap
* @param content - The content to wrap
*/
export function inlineCode<C extends string>(content: C): `\`${C}\`` {
return `\`${content}\``;
@@ -31,7 +31,7 @@ export function inlineCode<C extends string>(content: C): `\`${C}\`` {
/**
* Formats the content into italic text
*
* @param content The content to wrap
* @param content - The content to wrap
*/
export function italic<C extends string>(content: C): `_${C}_` {
return `_${content}_`;
@@ -40,7 +40,7 @@ export function italic<C extends string>(content: C): `_${C}_` {
/**
* Formats the content into bold text
*
* @param content The content to wrap
* @param content - The content to wrap
*/
export function bold<C extends string>(content: C): `**${C}**` {
return `**${content}**`;
@@ -49,7 +49,7 @@ export function bold<C extends string>(content: C): `**${C}**` {
/**
* Formats the content into underscored text
*
* @param content The content to wrap
* @param content - The content to wrap
*/
export function underscore<C extends string>(content: C): `__${C}__` {
return `__${content}__`;
@@ -58,7 +58,7 @@ export function underscore<C extends string>(content: C): `__${C}__` {
/**
* Formats the content into strike-through text
*
* @param content The content to wrap
* @param content - The content to wrap
*/
export function strikethrough<C extends string>(content: C): `~~${C}~~` {
return `~~${content}~~`;
@@ -67,7 +67,7 @@ export function strikethrough<C extends string>(content: C): `~~${C}~~` {
/**
* Formats the content into a quote. This needs to be at the start of the line for Discord to format it
*
* @param content The content to wrap
* @param content - The content to wrap
*/
export function quote<C extends string>(content: C): `> ${C}` {
return `> ${content}`;
@@ -76,7 +76,7 @@ export function quote<C extends string>(content: C): `> ${C}` {
/**
* Formats the content into a block quote. This needs to be at the start of the line for Discord to format it
*
* @param content The content to wrap
* @param content - The content to wrap
*/
export function blockQuote<C extends string>(content: C): `>>> ${C}` {
return `>>> ${content}`;
@@ -85,14 +85,14 @@ export function blockQuote<C extends string>(content: C): `>>> ${C}` {
/**
* Wraps the URL into `<>`, which stops it from embedding
*
* @param url The URL to wrap
* @param url - The URL to wrap
*/
export function hideLinkEmbed<C extends string>(url: C): `<${C}>`;
/**
* Wraps the URL into `<>`, which stops it from embedding
*
* @param url The URL to wrap
* @param url - The URL to wrap
*/
export function hideLinkEmbed(url: URL): `<${string}>`;
export function hideLinkEmbed(url: string | URL) {
@@ -103,25 +103,25 @@ export function hideLinkEmbed(url: string | URL) {
/**
* Formats the content and the URL into a masked URL
*
* @param content The content to display
* @param url The URL the content links to
* @param content - The content to display
* @param url - The URL the content links to
*/
export function hyperlink<C extends string>(content: C, url: URL): `[${C}](${string})`;
/**
* Formats the content and the URL into a masked URL
*
* @param content The content to display
* @param url The URL the content links to
* @param content - The content to display
* @param url - The URL the content links to
*/
export function hyperlink<C extends string, U extends string>(content: C, url: U): `[${C}](${U})`;
/**
* Formats the content and the URL into a masked URL
*
* @param content The content to display
* @param url The URL the content links to
* @param title The title shown when hovering on the masked link
* @param content - The content to display
* @param url - The URL the content links to
* @param title - The title shown when hovering on the masked link
*/
export function hyperlink<C extends string, T extends string>(
content: C,
@@ -132,9 +132,9 @@ export function hyperlink<C extends string, T extends string>(
/**
* Formats the content and the URL into a masked URL
*
* @param content The content to display
* @param url The URL the content links to
* @param title The title shown when hovering on the masked link
* @param content - The content to display
* @param url - The URL the content links to
* @param title - The title shown when hovering on the masked link
*/
export function hyperlink<C extends string, U extends string, T extends string>(
content: C,
@@ -149,7 +149,7 @@ export function hyperlink(content: string, url: string | URL, title?: string) {
/**
* Wraps the content inside spoiler (hidden text)
*
* @param content The content to wrap
* @param content - The content to wrap
*/
export function spoiler<C extends string>(content: C): `||${C}||` {
return `||${content}||`;
@@ -158,7 +158,7 @@ export function spoiler<C extends string>(content: C): `||${C}||` {
/**
* Formats a user ID into a user mention
*
* @param userId The user ID to format
* @param userId - The user ID to format
*/
export function userMention<C extends Snowflake>(userId: C): `<@${C}>` {
return `<@${userId}>`;
@@ -167,7 +167,7 @@ export function userMention<C extends Snowflake>(userId: C): `<@${C}>` {
/**
* Formats a channel ID into a channel mention
*
* @param channelId The channel ID to format
* @param channelId - The channel ID to format
*/
export function channelMention<C extends Snowflake>(channelId: C): `<#${C}>` {
return `<#${channelId}>`;
@@ -176,7 +176,7 @@ export function channelMention<C extends Snowflake>(channelId: C): `<#${C}>` {
/**
* Formats a role ID into a role mention
*
* @param roleId The role ID to format
* @param roleId - The role ID to format
*/
export function roleMention<C extends Snowflake>(roleId: C): `<@&${C}>` {
return `<@&${roleId}>`;
@@ -185,23 +185,23 @@ export function roleMention<C extends Snowflake>(roleId: C): `<@&${C}>` {
/**
* Formats an emoji ID into a fully qualified emoji identifier
*
* @param emojiId The emoji ID to format
* @param emojiId - The emoji ID to format
*/
export function formatEmoji<C extends Snowflake>(emojiId: C, animated?: false): `<:_:${C}>`;
/**
* Formats an emoji ID into a fully qualified emoji identifier
*
* @param emojiId The emoji ID to format
* @param animated Whether the emoji is animated or not. Defaults to `false`
* @param emojiId - The emoji ID to format
* @param animated - Whether the emoji is animated or not. Defaults to `false`
*/
export function formatEmoji<C extends Snowflake>(emojiId: C, animated?: true): `<a:_:${C}>`;
/**
* Formats an emoji ID into a fully qualified emoji identifier
*
* @param emojiId The emoji ID to format
* @param animated Whether the emoji is animated or not. Defaults to `false`
* @param emojiId - The emoji ID to format
* @param animated - Whether the emoji is animated or not. Defaults to `false`
*/
export function formatEmoji<C extends Snowflake>(emojiId: C, animated = false): `<a:_:${C}>` | `<:_:${C}>` {
return `<${animated ? 'a' : ''}:_:${emojiId}>`;
@@ -210,30 +210,30 @@ export function formatEmoji<C extends Snowflake>(emojiId: C, animated = false):
/**
* Formats a date into a short date-time string
*
* @param date The date to format, defaults to the current time
* @param date - The date to format, defaults to the current time
*/
export function time(date?: Date): `<t:${bigint}>`;
/**
* Formats a date given a format style
*
* @param date The date to format
* @param style The style to use
* @param date - The date to format
* @param style - The style to use
*/
export function time<S extends TimestampStylesString>(date: Date, style: S): `<t:${bigint}:${S}>`;
/**
* Formats the given timestamp into a short date-time string
*
* @param seconds The time to format, represents an UNIX timestamp in seconds
* @param seconds - The time to format, represents an UNIX timestamp in seconds
*/
export function time<C extends number>(seconds: C): `<t:${C}>`;
/**
* Formats the given timestamp into a short date-time string
*
* @param seconds The time to format, represents an UNIX timestamp in seconds
* @param style The style to use
* @param seconds - The time to format, represents an UNIX timestamp in seconds
* @param style - The style to use
*/
export function time<C extends number, S extends TimestampStylesString>(seconds: C, style: S): `<t:${C}:${S}>`;
export function time(timeOrSeconds?: number | Date, style?: TimestampStylesString): string {

2
packages/builders/src/util/equatable.ts
View File

@@ -7,7 +7,7 @@ export interface Equatable<T> {
/**
* Indicates if an object is equatable or not.
* @param maybeEquatable The object to check against
* @param maybeEquatable - The object to check against
*/
export function isEquatable(maybeEquatable: unknown): maybeEquatable is Equatable<unknown> {
return maybeEquatable !== null && typeof maybeEquatable === 'object' && 'equals' in maybeEquatable;

2
packages/builders/src/util/jsonEncodable.ts
View File

@@ -7,7 +7,7 @@ export interface JSONEncodable<T> {
/**
* Indicates if an object is encodable or not.
* @param maybeEncodable The object to check against
* @param maybeEncodable - The object to check against
*/
export function isJSONEncodable(maybeEncodable: unknown): maybeEncodable is JSONEncodable<unknown> {
return maybeEncodable !== null && typeof maybeEncodable === 'object' && 'toJSON' in maybeEncodable;

376
packages/collection/api-extractor.json Normal file
View File

@@ -0,0 +1,376 @@
/**
* Config file for API Extractor. For more info, please visit: https://api-extractor.com
*/
{
"$schema": "https://developer.microsoft.com/json-schemas/api-extractor/v7/api-extractor.schema.json",
/**
* Optionally specifies another JSON config file that this file extends from. This provides a way for
* standard settings to be shared across multiple projects.
*
* If the path starts with "./" or "../", the path is resolved relative to the folder of the file that contains
* the "extends" field. Otherwise, the first path segment is interpreted as an NPM package name, and will be
* resolved using NodeJS require().
*
* SUPPORTED TOKENS: none
* DEFAULT VALUE: ""
*/
// "extends": "./shared/api-extractor-base.json"
// "extends": "my-package/include/api-extractor-base.json"
/**
* Determines the "<projectFolder>" token that can be used with other config file settings. The project folder
* typically contains the tsconfig.json and package.json config files, but the path is user-defined.
*
* The path is resolved relative to the folder of the config file that contains the setting.
*
* The default value for "projectFolder" is the token "<lookup>", which means the folder is determined by traversing
* parent folders, starting from the folder containing api-extractor.json, and stopping at the first folder
* that contains a tsconfig.json file. If a tsconfig.json file cannot be found in this way, then an error
* will be reported.
*
* SUPPORTED TOKENS: <lookup>
* DEFAULT VALUE: "<lookup>"
*/
// "projectFolder": "..",
/**
* (REQUIRED) Specifies the .d.ts file to be used as the starting point for analysis. API Extractor
* analyzes the symbols exported by this module.
*
* The file extension must be ".d.ts" and not ".ts".
*
* The path is resolved relative to the folder of the config file that contains the setting; to change this,
* prepend a folder token such as "<projectFolder>".
*
* SUPPORTED TOKENS: <projectFolder>, <packageName>, <unscopedPackageName>
*/
"mainEntryPointFilePath": "<projectFolder>/dist/index.d.ts",
/**
* A list of NPM package names whose exports should be treated as part of this package.
*
* For example, suppose that Webpack is used to generate a distributed bundle for the project "library1",
* and another NPM package "library2" is embedded in this bundle. Some types from library2 may become part
* of the exported API for library1, but by default API Extractor would generate a .d.ts rollup that explicitly
* imports library2. To avoid this, we can specify:
*
* "bundledPackages": [ "library2" ],
*
* This would direct API Extractor to embed those types directly in the .d.ts rollup, as if they had been
* local files for library1.
*/
"bundledPackages": [],
/**
* Determines how the TypeScript compiler engine will be invoked by API Extractor.
*/
"compiler": {
/**
* Specifies the path to the tsconfig.json file to be used by API Extractor when analyzing the project.
*
* The path is resolved relative to the folder of the config file that contains the setting; to change this,
* prepend a folder token such as "<projectFolder>".
*
* Note: This setting will be ignored if "overrideTsconfig" is used.
*
* SUPPORTED TOKENS: <projectFolder>, <packageName>, <unscopedPackageName>
* DEFAULT VALUE: "<projectFolder>/tsconfig.json"
*/
// "tsconfigFilePath": "<projectFolder>/tsconfig.json",
/**
* Provides a compiler configuration that will be used instead of reading the tsconfig.json file from disk.
* The object must conform to the TypeScript tsconfig schema:
*
* http://json.schemastore.org/tsconfig
*
* If omitted, then the tsconfig.json file will be read from the "projectFolder".
*
* DEFAULT VALUE: no overrideTsconfig section
*/
// "overrideTsconfig": {
// . . .
// }
/**
* This option causes the compiler to be invoked with the --skipLibCheck option. This option is not recommended
* and may cause API Extractor to produce incomplete or incorrect declarations, but it may be required when
* dependencies contain declarations that are incompatible with the TypeScript engine that API Extractor uses
* for its analysis. Where possible, the underlying issue should be fixed rather than relying on skipLibCheck.
*
* DEFAULT VALUE: false
*/
// "skipLibCheck": true,
},
/**
* Configures how the API report file (*.api.md) will be generated.
*/
"apiReport": {
/**
* (REQUIRED) Whether to generate an API report.
*/
"enabled": false
/**
* The filename for the API report files. It will be combined with "reportFolder" or "reportTempFolder" to produce
* a full file path.
*
* The file extension should be ".api.md", and the string should not contain a path separator such as "\" or "/".
*
* SUPPORTED TOKENS: <packageName>, <unscopedPackageName>
* DEFAULT VALUE: "<unscopedPackageName>.api.md"
*/
// "reportFileName": "<unscopedPackageName>.api.md",
/**
* Specifies the folder where the API report file is written. The file name portion is determined by
* the "reportFileName" setting.
*
* The API report file is normally tracked by Git. Changes to it can be used to trigger a branch policy,
* e.g. for an API review.
*
* The path is resolved relative to the folder of the config file that contains the setting; to change this,
* prepend a folder token such as "<projectFolder>".
*
* SUPPORTED TOKENS: <projectFolder>, <packageName>, <unscopedPackageName>
* DEFAULT VALUE: "<projectFolder>/temp/"
*/
// "reportFolder": "<projectFolder>/temp/",
/**
* Specifies the folder where the temporary report file is written. The file name portion is determined by
* the "reportFileName" setting.
*
* After the temporary file is written to disk, it is compared with the file in the "reportFolder".
* If they are different, a production build will fail.
*
* The path is resolved relative to the folder of the config file that contains the setting; to change this,
* prepend a folder token such as "<projectFolder>".
*
* SUPPORTED TOKENS: <projectFolder>, <packageName>, <unscopedPackageName>
* DEFAULT VALUE: "<projectFolder>/temp/"
*/
// "reportTempFolder": "<projectFolder>/temp/"
},
/**
* Configures how the doc model file (*.api.json) will be generated.
*/
"docModel": {
/**
* (REQUIRED) Whether to generate a doc model file.
*/
"enabled": true,
/**
* The output path for the doc model file. The file extension should be ".api.json".
*
* The path is resolved relative to the folder of the config file that contains the setting; to change this,
* prepend a folder token such as "<projectFolder>".
*
* SUPPORTED TOKENS: <projectFolder>, <packageName>, <unscopedPackageName>
* DEFAULT VALUE: "<projectFolder>/temp/<unscopedPackageName>.api.json"
*/
"apiJsonFilePath": "<projectFolder>/docs/docs.api.json"
},
/**
* Configures how the .d.ts rollup file will be generated.
*/
"dtsRollup": {
/**
* (REQUIRED) Whether to generate the .d.ts rollup file.
*/
"enabled": false
/**
* Specifies the output path for a .d.ts rollup file to be generated without any trimming.
* This file will include all declarations that are exported by the main entry point.
*
* If the path is an empty string, then this file will not be written.
*
* The path is resolved relative to the folder of the config file that contains the setting; to change this,
* prepend a folder token such as "<projectFolder>".
*
* SUPPORTED TOKENS: <projectFolder>, <packageName>, <unscopedPackageName>
* DEFAULT VALUE: "<projectFolder>/dist/<unscopedPackageName>.d.ts"
*/
// "untrimmedFilePath": "<projectFolder>/dist/<unscopedPackageName>.d.ts",
/**
* Specifies the output path for a .d.ts rollup file to be generated with trimming for an "alpha" release.
* This file will include only declarations that are marked as "@public", "@beta", or "@alpha".
*
* The path is resolved relative to the folder of the config file that contains the setting; to change this,
* prepend a folder token such as "<projectFolder>".
*
* SUPPORTED TOKENS: <projectFolder>, <packageName>, <unscopedPackageName>
* DEFAULT VALUE: ""
*/
// "alphaTrimmedFilePath": "<projectFolder>/dist/<unscopedPackageName>-alpha.d.ts",
/**
* Specifies the output path for a .d.ts rollup file to be generated with trimming for a "beta" release.
* This file will include only declarations that are marked as "@public" or "@beta".
*
* The path is resolved relative to the folder of the config file that contains the setting; to change this,
* prepend a folder token such as "<projectFolder>".
*
* SUPPORTED TOKENS: <projectFolder>, <packageName>, <unscopedPackageName>
* DEFAULT VALUE: ""
*/
// "betaTrimmedFilePath": "<projectFolder>/dist/<unscopedPackageName>-beta.d.ts",
/**
* Specifies the output path for a .d.ts rollup file to be generated with trimming for a "public" release.
* This file will include only declarations that are marked as "@public".
*
* If the path is an empty string, then this file will not be written.
*
* The path is resolved relative to the folder of the config file that contains the setting; to change this,
* prepend a folder token such as "<projectFolder>".
*
* SUPPORTED TOKENS: <projectFolder>, <packageName>, <unscopedPackageName>
* DEFAULT VALUE: ""
*/
// "publicTrimmedFilePath": "<projectFolder>/dist/<unscopedPackageName>-public.d.ts",
/**
* When a declaration is trimmed, by default it will be replaced by a code comment such as
* "Excluded from this release type: exampleMember". Set "omitTrimmingComments" to true to remove the
* declaration completely.
*
* DEFAULT VALUE: false
*/
// "omitTrimmingComments": true
},
/**
* Configures how the tsdoc-metadata.json file will be generated.
*/
"tsdocMetadata": {
/**
* Whether to generate the tsdoc-metadata.json file.
*
* DEFAULT VALUE: true
*/
// "enabled": true,
/**
* Specifies where the TSDoc metadata file should be written.
*
* The path is resolved relative to the folder of the config file that contains the setting; to change this,
* prepend a folder token such as "<projectFolder>".
*
* The default value is "<lookup>", which causes the path to be automatically inferred from the "tsdocMetadata",
* "typings" or "main" fields of the project's package.json. If none of these fields are set, the lookup
* falls back to "tsdoc-metadata.json" in the package folder.
*
* SUPPORTED TOKENS: <projectFolder>, <packageName>, <unscopedPackageName>
* DEFAULT VALUE: "<lookup>"
*/
// "tsdocMetadataFilePath": "<projectFolder>/dist/tsdoc-metadata.json"
},
/**
* Specifies what type of newlines API Extractor should use when writing output files. By default, the output files
* will be written with Windows-style newlines. To use POSIX-style newlines, specify "lf" instead.
* To use the OS's default newline kind, specify "os".
*
* DEFAULT VALUE: "crlf"
*/
"newlineKind": "lf",
/**
* Configures how API Extractor reports error and warning messages produced during analysis.
*
* There are three sources of messages: compiler messages, API Extractor messages, and TSDoc messages.
*/
"messages": {
/**
* Configures handling of diagnostic messages reported by the TypeScript compiler engine while analyzing
* the input .d.ts files.
*
* TypeScript message identifiers start with "TS" followed by an integer. For example: "TS2551"
*
* DEFAULT VALUE: A single "default" entry with logLevel=warning.
*/
"compilerMessageReporting": {
/**
* Configures the default routing for messages that don't match an explicit rule in this table.
*/
"default": {
/**
* Specifies whether the message should be written to the the tool's output log. Note that
* the "addToApiReportFile" property may supersede this option.
*
* Possible values: "error", "warning", "none"
*
* Errors cause the build to fail and return a nonzero exit code. Warnings cause a production build fail
* and return a nonzero exit code. For a non-production build (e.g. when "api-extractor run" includes
* the "--local" option), the warning is displayed but the build will not fail.
*
* DEFAULT VALUE: "warning"
*/
"logLevel": "warning"
/**
* When addToApiReportFile is true: If API Extractor is configured to write an API report file (.api.md),
* then the message will be written inside that file; otherwise, the message is instead logged according to
* the "logLevel" option.
*
* DEFAULT VALUE: false
*/
// "addToApiReportFile": false
}
// "TS2551": {
// "logLevel": "warning",
// "addToApiReportFile": true
// },
//
// . . .
},
/**
* Configures handling of messages reported by API Extractor during its analysis.
*
* API Extractor message identifiers start with "ae-". For example: "ae-extra-release-tag"
*
* DEFAULT VALUE: See api-extractor-defaults.json for the complete table of extractorMessageReporting mappings
*/
"extractorMessageReporting": {
"default": {
"logLevel": "warning"
// "addToApiReportFile": false
}
// "ae-extra-release-tag": {
// "logLevel": "warning",
// "addToApiReportFile": true
// },
//
// . . .
},
/**
* Configures handling of messages reported by the TSDoc parser when analyzing code comments.
*
* TSDoc message identifiers start with "tsdoc-". For example: "tsdoc-link-tag-unescaped-text"
*
* DEFAULT VALUE: A single "default" entry with logLevel=warning.
*/
"tsdocMessageReporting": {
"default": {
"logLevel": "warning"
// "addToApiReportFile": false
}
// "tsdoc-link-tag-unescaped-text": {
// "logLevel": "warning",
// "addToApiReportFile": true
// },
//
// . . .
}
}
}

3
packages/collection/package.json
View File

@@ -6,7 +6,7 @@
"build": "tsup",
"lint": "prettier --cache --check . && eslint src __tests__ --ext mjs,js,ts --cache",
"format": "prettier --cache --write . && eslint src __tests__ --ext mjs,js,ts --fix --cache",
"docs": "docgen -i src/index.ts -c docs/index.json -o docs/docs.json --typescript",
"docs": "docgen -i src/index.ts -c docs/index.json -o docs/docs.json --typescript && api-extractor run --local",
"prepack": "yarn build && yarn lint",
"changelog": "git cliff --prepend ./CHANGELOG.md -u -c ./cliff.toml -r ../../ --include-path 'packages/collection/*'",
"release": "cliff-jumper"
@@ -51,6 +51,7 @@
"@discordjs/docgen": "workspace:^",
"@discordjs/scripts": "workspace:^",
"@favware/cliff-jumper": "^1.8.3",
"@microsoft/api-extractor": "^7.28.2",
"@types/node": "^18.0.0",
"eslint": "^8.18.0",
"prettier": "^2.7.1",

97
packages/collection/src/index.ts
View File

@@ -33,8 +33,8 @@ export class Collection<K, V> extends Map<K, V> {
/**
* Obtains the value of the given key if it exists, otherwise sets and returns the value provided by the default value generator.
*
* @param key The key to get if it exists, or set otherwise
* @param defaultValueGenerator A function that generates the default value
* @param key - The key to get if it exists, or set otherwise
* @param defaultValueGenerator - A function that generates the default value
*
* @example
* collection.ensure(guildId, () => defaultGuildConfig);
@@ -72,7 +72,7 @@ export class Collection<K, V> extends Map<K, V> {
/**
* Obtains the first value(s) in this collection.
*
* @param amount Amount of values to obtain from the beginning
* @param amount - Amount of values to obtain from the beginning
*
* @returns A single value if no amount is provided or an array of values, starting from the end if amount is negative
*/
@@ -91,7 +91,7 @@ export class Collection<K, V> extends Map<K, V> {
/**
* Obtains the first key(s) in this collection.
*
* @param amount Amount of keys to obtain from the beginning
* @param amount - Amount of keys to obtain from the beginning
*
* @returns A single key if no amount is provided or an array of keys, starting from the end if
* amount is negative
@@ -111,7 +111,7 @@ export class Collection<K, V> extends Map<K, V> {
/**
* Obtains the last value(s) in this collection.
*
* @param amount Amount of values to obtain from the end
* @param amount - Amount of values to obtain from the end
*
* @returns A single value if no amount is provided or an array of values, starting from the start if
* amount is negative
@@ -129,7 +129,7 @@ export class Collection<K, V> extends Map<K, V> {
/**
* Obtains the last key(s) in this collection.
*
* @param amount Amount of keys to obtain from the end
* @param amount - Amount of keys to obtain from the end
*
* @returns A single key if no amount is provided or an array of keys, starting from the start if
* amount is negative
@@ -149,7 +149,7 @@ export class Collection<K, V> extends Map<K, V> {
* Returns the item at a given index, allowing for positive and negative integers.
* Negative integers count back from the last item in the collection.
*
* @param index The index of the element to obtain
* @param index - The index of the element to obtain
*/
public at(index: number) {
index = Math.floor(index);
@@ -162,7 +162,7 @@ export class Collection<K, V> extends Map<K, V> {
* Returns the key at a given index, allowing for positive and negative integers.
* Negative integers count back from the last item in the collection.
*
* @param index The index of the key to obtain
* @param index - The index of the key to obtain
*/
public keyAt(index: number) {
index = Math.floor(index);
@@ -173,7 +173,7 @@ export class Collection<K, V> extends Map<K, V> {
/**
* Obtains unique random value(s) from this collection.
*
* @param amount Amount of values to obtain randomly
* @param amount - Amount of values to obtain randomly
*
* @returns A single value if no amount is provided or an array of values
*/
@@ -192,7 +192,7 @@ export class Collection<K, V> extends Map<K, V> {
/**
* Obtains unique random key(s) from this collection.
*
* @param amount Amount of keys to obtain randomly
* @param amount - Amount of keys to obtain randomly
*
* @returns A single key if no amount is provided or an array
*/
@@ -226,8 +226,8 @@ export class Collection<K, V> extends Map<K, V> {
* should use the `get` method. See
* [MDN](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map/get) for details.</warn>
*
* @param fn The function to test with (should return boolean)
* @param thisArg Value to use as `this` when executing function
* @param fn - The function to test with (should return boolean)
* @param thisArg - Value to use as `this` when executing function
*
* @example
* collection.find(user => user.username === 'Bob');
@@ -253,8 +253,8 @@ export class Collection<K, V> extends Map<K, V> {
* [Array.findIndex()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/findIndex),
* but returns the key rather than the positional index.
*
* @param fn The function to test with (should return boolean)
* @param thisArg Value to use as `this` when executing function
* @param fn - The function to test with (should return boolean)
* @param thisArg - Value to use as `this` when executing function
*
* @example
* collection.findKey(user => user.username === 'Bob');
@@ -278,8 +278,8 @@ export class Collection<K, V> extends Map<K, V> {
/**
* Removes items that satisfy the provided filter function.
*
* @param fn Function used to test (should return a boolean)
* @param thisArg Value to use as `this` when executing function
* @param fn - Function used to test (should return a boolean)
* @param thisArg - Value to use as `this` when executing function
*
* @returns The number of removed entries
*/
@@ -300,8 +300,8 @@ export class Collection<K, V> extends Map<K, V> {
* [Array.filter()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/filter),
* but returns a Collection instead of an Array.
*
* @param fn The function to test with (should return boolean)
* @param thisArg Value to use as `this` when executing function
* @param fn - The function to test with (should return boolean)
* @param thisArg - Value to use as `this` when executing function
*
* @example
* collection.filter(user => user.username === 'Bob');
@@ -332,8 +332,8 @@ export class Collection<K, V> extends Map<K, V> {
* Partitions the collection into two collections where the first collection
* contains the items that passed and the second contains the items that failed.
*
* @param fn Function used to test (should return a boolean)
* @param thisArg Value to use as `this` when executing function
* @param fn - Function used to test (should return a boolean)
* @param thisArg - Value to use as `this` when executing function
*
* @example
* const [big, small] = collection.partition(guild => guild.memberCount > 250);
@@ -381,8 +381,8 @@ export class Collection<K, V> extends Map<K, V> {
* Maps each item into a Collection, then joins the results into a single Collection. Identical in behavior to
* [Array.flatMap()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/flatMap).
*
* @param fn Function that produces a new Collection
* @param thisArg Value to use as `this` when executing function
* @param fn - Function that produces a new Collection
* @param thisArg - Value to use as `this` when executing function
*
* @example
* collection.flatMap(guild => guild.members.cache);
@@ -401,8 +401,8 @@ export class Collection<K, V> extends Map<K, V> {
* Maps each item to another value into an array. Identical in behavior to
* [Array.map()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/map).
*
* @param fn Function that produces an element of the new array, taking three arguments
* @param thisArg Value to use as `this` when executing function
* @param fn - Function that produces an element of the new array, taking three arguments
* @param thisArg - Value to use as `this` when executing function
*
* @example
* collection.map(user => user.tag);
@@ -425,8 +425,8 @@ export class Collection<K, V> extends Map<K, V> {
* Maps each item to another value into a collection. Identical in behavior to
* [Array.map()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/map).
*
* @param fn Function that produces an element of the new collection, taking three arguments
* @param thisArg Value to use as `this` when executing function
* @param fn - Function that produces an element of the new collection, taking three arguments
* @param thisArg - Value to use as `this` when executing function
*
* @example
* collection.mapValues(user => user.tag);
@@ -445,8 +445,8 @@ export class Collection<K, V> extends Map<K, V> {
* Checks if there exists an item that passes a test. Identical in behavior to
* [Array.some()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/some).
*
* @param fn Function used to test (should return a boolean)
* @param thisArg Value to use as `this` when executing function
* @param fn - Function used to test (should return a boolean)
* @param thisArg - Value to use as `this` when executing function
*
* @example
* collection.some(user => user.discriminator === '0000');
@@ -466,8 +466,8 @@ export class Collection<K, V> extends Map<K, V> {
* Checks if all items passes a test. Identical in behavior to
* [Array.every()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/every).
*
* @param fn Function used to test (should return a boolean)
* @param thisArg Value to use as `this` when executing function
* @param fn - Function used to test (should return a boolean)
* @param thisArg - Value to use as `this` when executing function
*
* @example
* collection.every(user => !user.bot);
@@ -497,9 +497,9 @@ export class Collection<K, V> extends Map<K, V> {
* Applies a function to produce a single value. Identical in behavior to
* [Array.reduce()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/reduce).
*
* @param fn Function used to reduce, taking four arguments; `accumulator`, `currentValue`, `currentKey`,
* @param fn - Function used to reduce, taking four arguments; `accumulator`, `currentValue`, `currentKey`,
* and `collection`
* @param initialValue Starting value for the accumulator
* @param initialValue - Starting value for the accumulator
*
* @example
* collection.reduce((acc, guild) => acc + guild.memberCount, 0);
@@ -536,8 +536,8 @@ export class Collection<K, V> extends Map<K, V> {
* [Map.forEach()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map/forEach),
* but returns the collection instead of undefined.
*
* @param fn Function to execute for each element
* @param thisArg Value to use as `this` when executing function
* @param fn - Function to execute for each element
* @param thisArg - Value to use as `this` when executing function
*
* @example
* collection
@@ -556,8 +556,8 @@ export class Collection<K, V> extends Map<K, V> {
/**
* Runs a function on the collection and returns the collection.
*
* @param fn Function to execute
* @param thisArg Value to use as `this` when executing function
* @param fn - Function to execute
* @param thisArg - Value to use as `this` when executing function
*
* @example
* collection
@@ -587,7 +587,7 @@ export class Collection<K, V> extends Map<K, V> {
/**
* Combines this collection with others into a new collection. None of the source collections are modified.
*
* @param collections Collections to merge
* @param collections - Collections to merge
*
* @example
* const newColl = someColl.concat(someOtherColl, anotherColl, ohBoyAColl);
@@ -605,7 +605,7 @@ export class Collection<K, V> extends Map<K, V> {
* This is different to checking for equality using equal-signs, because
* the collections may be different objects, but contain the same data.
*
* @param collection Collection to compare with
* @param collection - Collection to compare with
*
* @returns Whether the collections have identical contents
*/
@@ -627,7 +627,7 @@ export class Collection<K, V> extends Map<K, V> {
* The sort is not necessarily stable in Node 10 or older.
* The default sort order is according to string Unicode code points.
*
* @param compareFunction Specifies a function that defines the sort order.
* @param compareFunction - Specifies a function that defines the sort order.
* If omitted, the collection is sorted according to each character's Unicode code point value, according to the string conversion of each element.
*
* @example
@@ -650,7 +650,7 @@ export class Collection<K, V> extends Map<K, V> {
/**
* The intersect method returns a new structure containing items where the keys and values are present in both original structures.
*
* @param other The other Collection to filter against
* @param other - The other Collection to filter against
*/
public intersect<T>(other: ReadonlyCollection<K, T>): Collection<K, T> {
const coll = new this.constructor[Symbol.species]<K, T>();
@@ -665,7 +665,7 @@ export class Collection<K, V> extends Map<K, V> {
/**
* The difference method returns a new structure containing items where the key is present in one of the original structures but not the other.
*
* @param other The other Collection to filter against
* @param other - The other Collection to filter against
*/
public difference<T>(other: ReadonlyCollection<K, T>): Collection<K, V | T> {
const coll = new this.constructor[Symbol.species]<K, V | T>();
@@ -680,10 +680,10 @@ export class Collection<K, V> extends Map<K, V> {
/**
* Merges two Collections together into a new Collection.
* @param other The other Collection to merge with
* @param whenInSelf Function getting the result if the entry only exists in this Collection
* @param whenInOther Function getting the result if the entry only exists in the other Collection
* @param whenInBoth Function getting the result if the entry exists in both Collections
* @param other - The other Collection to merge with
* @param whenInSelf - Function getting the result if the entry only exists in this Collection
* @param whenInOther - Function getting the result if the entry only exists in the other Collection
* @param whenInBoth - Function getting the result if the entry exists in both Collections
*
* @example
* // Sums up the entries in two collections.
@@ -734,7 +734,7 @@ export class Collection<K, V> extends Map<K, V> {
* The sort is not necessarily stable in Node 10 or older.
* The default sort order is according to string Unicode code points.
*
* @param compareFunction Specifies a function that defines the sort order.
* @param compareFunction - Specifies a function that defines the sort order.
* If omitted, the collection is sorted according to each character's Unicode code point value,
* according to the string conversion of each element.
*
@@ -756,8 +756,9 @@ export class Collection<K, V> extends Map<K, V> {
/**
* Creates a Collection from a list of entries.
* @param entries The list of entries
* @param combine Function to combine an existing entry with a new one
*
* @param entries - The list of entries
* @param combine - Function to combine an existing entry with a new one
*
* @example
* Collection.combineEntries([["a", 1], ["b", 2], ["a", 2]], (x, y) => x + y);

376
packages/proxy/api-extractor.json Normal file
View File

@@ -0,0 +1,376 @@
/**
* Config file for API Extractor. For more info, please visit: https://api-extractor.com
*/
{
"$schema": "https://developer.microsoft.com/json-schemas/api-extractor/v7/api-extractor.schema.json",
/**
* Optionally specifies another JSON config file that this file extends from. This provides a way for
* standard settings to be shared across multiple projects.
*
* If the path starts with "./" or "../", the path is resolved relative to the folder of the file that contains
* the "extends" field. Otherwise, the first path segment is interpreted as an NPM package name, and will be
* resolved using NodeJS require().
*
* SUPPORTED TOKENS: none
* DEFAULT VALUE: ""
*/
// "extends": "./shared/api-extractor-base.json"
// "extends": "my-package/include/api-extractor-base.json"
/**
* Determines the "<projectFolder>" token that can be used with other config file settings. The project folder
* typically contains the tsconfig.json and package.json config files, but the path is user-defined.
*
* The path is resolved relative to the folder of the config file that contains the setting.
*
* The default value for "projectFolder" is the token "<lookup>", which means the folder is determined by traversing
* parent folders, starting from the folder containing api-extractor.json, and stopping at the first folder
* that contains a tsconfig.json file. If a tsconfig.json file cannot be found in this way, then an error
* will be reported.
*
* SUPPORTED TOKENS: <lookup>
* DEFAULT VALUE: "<lookup>"
*/
// "projectFolder": "..",
/**
* (REQUIRED) Specifies the .d.ts file to be used as the starting point for analysis. API Extractor
* analyzes the symbols exported by this module.
*
* The file extension must be ".d.ts" and not ".ts".
*
* The path is resolved relative to the folder of the config file that contains the setting; to change this,
* prepend a folder token such as "<projectFolder>".
*
* SUPPORTED TOKENS: <projectFolder>, <packageName>, <unscopedPackageName>
*/
"mainEntryPointFilePath": "<projectFolder>/dist/index.d.ts",
/**
* A list of NPM package names whose exports should be treated as part of this package.
*
* For example, suppose that Webpack is used to generate a distributed bundle for the project "library1",
* and another NPM package "library2" is embedded in this bundle. Some types from library2 may become part
* of the exported API for library1, but by default API Extractor would generate a .d.ts rollup that explicitly
* imports library2. To avoid this, we can specify:
*
* "bundledPackages": [ "library2" ],
*
* This would direct API Extractor to embed those types directly in the .d.ts rollup, as if they had been
* local files for library1.
*/
"bundledPackages": [],
/**
* Determines how the TypeScript compiler engine will be invoked by API Extractor.
*/
"compiler": {
/**
* Specifies the path to the tsconfig.json file to be used by API Extractor when analyzing the project.
*
* The path is resolved relative to the folder of the config file that contains the setting; to change this,
* prepend a folder token such as "<projectFolder>".
*
* Note: This setting will be ignored if "overrideTsconfig" is used.
*
* SUPPORTED TOKENS: <projectFolder>, <packageName>, <unscopedPackageName>
* DEFAULT VALUE: "<projectFolder>/tsconfig.json"
*/
// "tsconfigFilePath": "<projectFolder>/tsconfig.json",
/**
* Provides a compiler configuration that will be used instead of reading the tsconfig.json file from disk.
* The object must conform to the TypeScript tsconfig schema:
*
* http://json.schemastore.org/tsconfig
*
* If omitted, then the tsconfig.json file will be read from the "projectFolder".
*
* DEFAULT VALUE: no overrideTsconfig section
*/
// "overrideTsconfig": {
// . . .
// }
/**
* This option causes the compiler to be invoked with the --skipLibCheck option. This option is not recommended
* and may cause API Extractor to produce incomplete or incorrect declarations, but it may be required when
* dependencies contain declarations that are incompatible with the TypeScript engine that API Extractor uses
* for its analysis. Where possible, the underlying issue should be fixed rather than relying on skipLibCheck.
*
* DEFAULT VALUE: false
*/
// "skipLibCheck": true,
},
/**
* Configures how the API report file (*.api.md) will be generated.
*/
"apiReport": {
/**
* (REQUIRED) Whether to generate an API report.
*/
"enabled": false
/**
* The filename for the API report files. It will be combined with "reportFolder" or "reportTempFolder" to produce
* a full file path.
*
* The file extension should be ".api.md", and the string should not contain a path separator such as "\" or "/".
*
* SUPPORTED TOKENS: <packageName>, <unscopedPackageName>
* DEFAULT VALUE: "<unscopedPackageName>.api.md"
*/
// "reportFileName": "<unscopedPackageName>.api.md",
/**
* Specifies the folder where the API report file is written. The file name portion is determined by
* the "reportFileName" setting.
*
* The API report file is normally tracked by Git. Changes to it can be used to trigger a branch policy,
* e.g. for an API review.
*
* The path is resolved relative to the folder of the config file that contains the setting; to change this,
* prepend a folder token such as "<projectFolder>".
*
* SUPPORTED TOKENS: <projectFolder>, <packageName>, <unscopedPackageName>
* DEFAULT VALUE: "<projectFolder>/temp/"
*/
// "reportFolder": "<projectFolder>/temp/",
/**
* Specifies the folder where the temporary report file is written. The file name portion is determined by
* the "reportFileName" setting.
*
* After the temporary file is written to disk, it is compared with the file in the "reportFolder".
* If they are different, a production build will fail.
*
* The path is resolved relative to the folder of the config file that contains the setting; to change this,
* prepend a folder token such as "<projectFolder>".
*
* SUPPORTED TOKENS: <projectFolder>, <packageName>, <unscopedPackageName>
* DEFAULT VALUE: "<projectFolder>/temp/"
*/
// "reportTempFolder": "<projectFolder>/temp/"
},
/**
* Configures how the doc model file (*.api.json) will be generated.
*/
"docModel": {
/**
* (REQUIRED) Whether to generate a doc model file.
*/
"enabled": true,
/**
* The output path for the doc model file. The file extension should be ".api.json".
*
* The path is resolved relative to the folder of the config file that contains the setting; to change this,
* prepend a folder token such as "<projectFolder>".
*
* SUPPORTED TOKENS: <projectFolder>, <packageName>, <unscopedPackageName>
* DEFAULT VALUE: "<projectFolder>/temp/<unscopedPackageName>.api.json"
*/
"apiJsonFilePath": "<projectFolder>/docs/docs.api.json"
},
/**
* Configures how the .d.ts rollup file will be generated.
*/
"dtsRollup": {
/**
* (REQUIRED) Whether to generate the .d.ts rollup file.
*/
"enabled": false
/**
* Specifies the output path for a .d.ts rollup file to be generated without any trimming.
* This file will include all declarations that are exported by the main entry point.
*
* If the path is an empty string, then this file will not be written.
*
* The path is resolved relative to the folder of the config file that contains the setting; to change this,
* prepend a folder token such as "<projectFolder>".
*
* SUPPORTED TOKENS: <projectFolder>, <packageName>, <unscopedPackageName>
* DEFAULT VALUE: "<projectFolder>/dist/<unscopedPackageName>.d.ts"
*/
// "untrimmedFilePath": "<projectFolder>/dist/<unscopedPackageName>.d.ts",
/**
* Specifies the output path for a .d.ts rollup file to be generated with trimming for an "alpha" release.
* This file will include only declarations that are marked as "@public", "@beta", or "@alpha".
*
* The path is resolved relative to the folder of the config file that contains the setting; to change this,
* prepend a folder token such as "<projectFolder>".
*
* SUPPORTED TOKENS: <projectFolder>, <packageName>, <unscopedPackageName>
* DEFAULT VALUE: ""
*/
// "alphaTrimmedFilePath": "<projectFolder>/dist/<unscopedPackageName>-alpha.d.ts",
/**
* Specifies the output path for a .d.ts rollup file to be generated with trimming for a "beta" release.
* This file will include only declarations that are marked as "@public" or "@beta".
*
* The path is resolved relative to the folder of the config file that contains the setting; to change this,
* prepend a folder token such as "<projectFolder>".
*
* SUPPORTED TOKENS: <projectFolder>, <packageName>, <unscopedPackageName>
* DEFAULT VALUE: ""
*/
// "betaTrimmedFilePath": "<projectFolder>/dist/<unscopedPackageName>-beta.d.ts",
/**
* Specifies the output path for a .d.ts rollup file to be generated with trimming for a "public" release.
* This file will include only declarations that are marked as "@public".
*
* If the path is an empty string, then this file will not be written.
*
* The path is resolved relative to the folder of the config file that contains the setting; to change this,
* prepend a folder token such as "<projectFolder>".
*
* SUPPORTED TOKENS: <projectFolder>, <packageName>, <unscopedPackageName>
* DEFAULT VALUE: ""
*/
// "publicTrimmedFilePath": "<projectFolder>/dist/<unscopedPackageName>-public.d.ts",
/**
* When a declaration is trimmed, by default it will be replaced by a code comment such as
* "Excluded from this release type: exampleMember". Set "omitTrimmingComments" to true to remove the
* declaration completely.
*
* DEFAULT VALUE: false
*/
// "omitTrimmingComments": true
},
/**
* Configures how the tsdoc-metadata.json file will be generated.
*/
"tsdocMetadata": {
/**
* Whether to generate the tsdoc-metadata.json file.
*
* DEFAULT VALUE: true
*/
// "enabled": true,
/**
* Specifies where the TSDoc metadata file should be written.
*
* The path is resolved relative to the folder of the config file that contains the setting; to change this,
* prepend a folder token such as "<projectFolder>".
*
* The default value is "<lookup>", which causes the path to be automatically inferred from the "tsdocMetadata",
* "typings" or "main" fields of the project's package.json. If none of these fields are set, the lookup
* falls back to "tsdoc-metadata.json" in the package folder.
*
* SUPPORTED TOKENS: <projectFolder>, <packageName>, <unscopedPackageName>
* DEFAULT VALUE: "<lookup>"
*/
// "tsdocMetadataFilePath": "<projectFolder>/dist/tsdoc-metadata.json"
},
/**
* Specifies what type of newlines API Extractor should use when writing output files. By default, the output files
* will be written with Windows-style newlines. To use POSIX-style newlines, specify "lf" instead.
* To use the OS's default newline kind, specify "os".
*
* DEFAULT VALUE: "crlf"
*/
"newlineKind": "lf",
/**
* Configures how API Extractor reports error and warning messages produced during analysis.
*
* There are three sources of messages: compiler messages, API Extractor messages, and TSDoc messages.
*/
"messages": {
/**
* Configures handling of diagnostic messages reported by the TypeScript compiler engine while analyzing
* the input .d.ts files.
*
* TypeScript message identifiers start with "TS" followed by an integer. For example: "TS2551"
*
* DEFAULT VALUE: A single "default" entry with logLevel=warning.
*/
"compilerMessageReporting": {
/**
* Configures the default routing for messages that don't match an explicit rule in this table.
*/
"default": {
/**
* Specifies whether the message should be written to the the tool's output log. Note that
* the "addToApiReportFile" property may supersede this option.
*
* Possible values: "error", "warning", "none"
*
* Errors cause the build to fail and return a nonzero exit code. Warnings cause a production build fail
* and return a nonzero exit code. For a non-production build (e.g. when "api-extractor run" includes
* the "--local" option), the warning is displayed but the build will not fail.
*
* DEFAULT VALUE: "warning"
*/
"logLevel": "warning"
/**
* When addToApiReportFile is true: If API Extractor is configured to write an API report file (.api.md),
* then the message will be written inside that file; otherwise, the message is instead logged according to
* the "logLevel" option.
*
* DEFAULT VALUE: false
*/
// "addToApiReportFile": false
}
// "TS2551": {
// "logLevel": "warning",
// "addToApiReportFile": true
// },
//
// . . .
},
/**
* Configures handling of messages reported by API Extractor during its analysis.
*
* API Extractor message identifiers start with "ae-". For example: "ae-extra-release-tag"
*
* DEFAULT VALUE: See api-extractor-defaults.json for the complete table of extractorMessageReporting mappings
*/
"extractorMessageReporting": {
"default": {
"logLevel": "warning"
// "addToApiReportFile": false
}
// "ae-extra-release-tag": {
// "logLevel": "warning",
// "addToApiReportFile": true
// },
//
// . . .
},
/**
* Configures handling of messages reported by the TSDoc parser when analyzing code comments.
*
* TSDoc message identifiers start with "tsdoc-". For example: "tsdoc-link-tag-unescaped-text"
*
* DEFAULT VALUE: A single "default" entry with logLevel=warning.
*/
"tsdocMessageReporting": {
"default": {
"logLevel": "warning"
// "addToApiReportFile": false
}
// "tsdoc-link-tag-unescaped-text": {
// "logLevel": "warning",
// "addToApiReportFile": true
// },
//
// . . .
}
}
}

3
packages/proxy/package.json
View File

@@ -6,7 +6,7 @@
"build": "tsup",
"lint": "prettier --cache --check . && eslint src __tests__ --ext mjs,js,ts --cache",
"format": "prettier --cache --write . && eslint src __tests__ --ext mjs,js,ts --fix --cache",
"docs": "docgen -i src/index.ts -c docs/index.json -o docs/docs.json --typescript",
"docs": "docgen -i src/index.ts -c docs/index.json -o docs/docs.json --typescript && api-extractor run --local",
"prepack": "yarn build && yarn lint",
"changelog": "git cliff --prepend ./CHANGELOG.md -u -c ./cliff.toml -r ../../ --include-path 'packages/proxy/*'",
"release": "cliff-jumper"
@@ -60,6 +60,7 @@
"@discordjs/docgen": "workspace:^",
"@discordjs/scripts": "workspace:^",
"@favware/cliff-jumper": "^1.8.3",
"@microsoft/api-extractor": "^7.28.2",
"@types/node": "^18.0.0",
"@types/supertest": "^2.0.12",
"eslint": "^8.18.0",

3
packages/proxy/src/handlers/proxyRequests.ts
View File

@@ -10,7 +10,8 @@ import type { RequestHandler } from '../util/util';
/**
* Creates an HTTP handler used to forward requests to Discord
* @param rest REST instance to use for the requests
*
* @param rest - REST instance to use for the requests
*/
export function proxyRequests(rest: REST): RequestHandler {
return async (req, res) => {

20
packages/proxy/src/util/responseHelpers.ts
View File

@@ -5,8 +5,9 @@ import type { Dispatcher } from 'undici';
/**
* Populates a server response with the data from a Discord 2xx REST response
* @param res The server response to populate
* @param data The data to populate the response with
*
* @param res - The server response to populate
* @param data - The data to populate the response with
*/
export async function populateSuccessfulResponse(res: ServerResponse, data: Dispatcher.ResponseData): Promise<void> {
res.statusCode = data.statusCode;
@@ -25,8 +26,9 @@ export async function populateSuccessfulResponse(res: ServerResponse, data: Disp
/**
* Populates a server response with the data from a Discord non-2xx REST response that is NOT a 429
* @param res The server response to populate
* @param error The error to populate the response with
*
* @param res - The server response to populate
* @param error - The error to populate the response with
*/
export function populateGeneralErrorResponse(res: ServerResponse, error: DiscordAPIError | HTTPError): void {
res.statusCode = error.status;
@@ -39,8 +41,9 @@ export function populateGeneralErrorResponse(res: ServerResponse, error: Discord
/**
* Populates a server response with the data from a Discord 429 REST response
* @param res The server response to populate
* @param error The error to populate the response with
*
* @param res - The server response to populate
* @param error - The error to populate the response with
*/
export function populateRatelimitErrorResponse(res: ServerResponse, error: RateLimitError): void {
res.statusCode = 429;
@@ -48,8 +51,9 @@ export function populateRatelimitErrorResponse(res: ServerResponse, error: RateL
}
/**
* Populates a server response with data relevant for a time out
* @param res The sever response to populate
* Populates a server response with data relevant for a timeout
*
* @param res - The sever response to populate
*/
export function populateAbortErrorResponse(res: ServerResponse): void {
res.statusCode = 504;

1
packages/proxy/src/util/util.ts
View File

@@ -4,6 +4,7 @@ import type { IncomingMessage, ServerResponse } from 'node:http';
* Represents a potentially awaitable value
*/
export type Awaitable<T> = T | PromiseLike<T>;
/**
* Represents a simple HTTP request handler
*/

376
packages/rest/api-extractor.json Normal file
View File

@@ -0,0 +1,376 @@
/**
* Config file for API Extractor. For more info, please visit: https://api-extractor.com
*/
{
"$schema": "https://developer.microsoft.com/json-schemas/api-extractor/v7/api-extractor.schema.json",
/**
* Optionally specifies another JSON config file that this file extends from. This provides a way for
* standard settings to be shared across multiple projects.
*
* If the path starts with "./" or "../", the path is resolved relative to the folder of the file that contains
* the "extends" field. Otherwise, the first path segment is interpreted as an NPM package name, and will be
* resolved using NodeJS require().
*
* SUPPORTED TOKENS: none
* DEFAULT VALUE: ""
*/
// "extends": "./shared/api-extractor-base.json"
// "extends": "my-package/include/api-extractor-base.json"
/**
* Determines the "<projectFolder>" token that can be used with other config file settings. The project folder
* typically contains the tsconfig.json and package.json config files, but the path is user-defined.
*
* The path is resolved relative to the folder of the config file that contains the setting.
*
* The default value for "projectFolder" is the token "<lookup>", which means the folder is determined by traversing
* parent folders, starting from the folder containing api-extractor.json, and stopping at the first folder
* that contains a tsconfig.json file. If a tsconfig.json file cannot be found in this way, then an error
* will be reported.
*
* SUPPORTED TOKENS: <lookup>
* DEFAULT VALUE: "<lookup>"
*/
// "projectFolder": "..",
/**
* (REQUIRED) Specifies the .d.ts file to be used as the starting point for analysis. API Extractor
* analyzes the symbols exported by this module.
*
* The file extension must be ".d.ts" and not ".ts".
*
* The path is resolved relative to the folder of the config file that contains the setting; to change this,
* prepend a folder token such as "<projectFolder>".
*
* SUPPORTED TOKENS: <projectFolder>, <packageName>, <unscopedPackageName>
*/
"mainEntryPointFilePath": "<projectFolder>/dist/index.d.ts",
/**
* A list of NPM package names whose exports should be treated as part of this package.
*
* For example, suppose that Webpack is used to generate a distributed bundle for the project "library1",
* and another NPM package "library2" is embedded in this bundle. Some types from library2 may become part
* of the exported API for library1, but by default API Extractor would generate a .d.ts rollup that explicitly
* imports library2. To avoid this, we can specify:
*
* "bundledPackages": [ "library2" ],
*
* This would direct API Extractor to embed those types directly in the .d.ts rollup, as if they had been
* local files for library1.
*/
"bundledPackages": [],
/**
* Determines how the TypeScript compiler engine will be invoked by API Extractor.
*/
"compiler": {
/**
* Specifies the path to the tsconfig.json file to be used by API Extractor when analyzing the project.
*
* The path is resolved relative to the folder of the config file that contains the setting; to change this,
* prepend a folder token such as "<projectFolder>".
*
* Note: This setting will be ignored if "overrideTsconfig" is used.
*
* SUPPORTED TOKENS: <projectFolder>, <packageName>, <unscopedPackageName>
* DEFAULT VALUE: "<projectFolder>/tsconfig.json"
*/
// "tsconfigFilePath": "<projectFolder>/tsconfig.json",
/**
* Provides a compiler configuration that will be used instead of reading the tsconfig.json file from disk.
* The object must conform to the TypeScript tsconfig schema:
*
* http://json.schemastore.org/tsconfig
*
* If omitted, then the tsconfig.json file will be read from the "projectFolder".
*
* DEFAULT VALUE: no overrideTsconfig section
*/
// "overrideTsconfig": {
// . . .
// }
/**
* This option causes the compiler to be invoked with the --skipLibCheck option. This option is not recommended
* and may cause API Extractor to produce incomplete or incorrect declarations, but it may be required when
* dependencies contain declarations that are incompatible with the TypeScript engine that API Extractor uses
* for its analysis. Where possible, the underlying issue should be fixed rather than relying on skipLibCheck.
*
* DEFAULT VALUE: false
*/
// "skipLibCheck": true,
},
/**
* Configures how the API report file (*.api.md) will be generated.
*/
"apiReport": {
/**
* (REQUIRED) Whether to generate an API report.
*/
"enabled": false
/**
* The filename for the API report files. It will be combined with "reportFolder" or "reportTempFolder" to produce
* a full file path.
*
* The file extension should be ".api.md", and the string should not contain a path separator such as "\" or "/".
*
* SUPPORTED TOKENS: <packageName>, <unscopedPackageName>
* DEFAULT VALUE: "<unscopedPackageName>.api.md"
*/
// "reportFileName": "<unscopedPackageName>.api.md",
/**
* Specifies the folder where the API report file is written. The file name portion is determined by
* the "reportFileName" setting.
*
* The API report file is normally tracked by Git. Changes to it can be used to trigger a branch policy,
* e.g. for an API review.
*
* The path is resolved relative to the folder of the config file that contains the setting; to change this,
* prepend a folder token such as "<projectFolder>".
*
* SUPPORTED TOKENS: <projectFolder>, <packageName>, <unscopedPackageName>
* DEFAULT VALUE: "<projectFolder>/temp/"
*/
// "reportFolder": "<projectFolder>/temp/",
/**
* Specifies the folder where the temporary report file is written. The file name portion is determined by
* the "reportFileName" setting.
*
* After the temporary file is written to disk, it is compared with the file in the "reportFolder".
* If they are different, a production build will fail.
*
* The path is resolved relative to the folder of the config file that contains the setting; to change this,
* prepend a folder token such as "<projectFolder>".
*
* SUPPORTED TOKENS: <projectFolder>, <packageName>, <unscopedPackageName>
* DEFAULT VALUE: "<projectFolder>/temp/"
*/
// "reportTempFolder": "<projectFolder>/temp/"
},
/**
* Configures how the doc model file (*.api.json) will be generated.
*/
"docModel": {
/**
* (REQUIRED) Whether to generate a doc model file.
*/
"enabled": true,
/**
* The output path for the doc model file. The file extension should be ".api.json".
*
* The path is resolved relative to the folder of the config file that contains the setting; to change this,
* prepend a folder token such as "<projectFolder>".
*
* SUPPORTED TOKENS: <projectFolder>, <packageName>, <unscopedPackageName>
* DEFAULT VALUE: "<projectFolder>/temp/<unscopedPackageName>.api.json"
*/
"apiJsonFilePath": "<projectFolder>/docs/docs.api.json"
},
/**
* Configures how the .d.ts rollup file will be generated.
*/
"dtsRollup": {
/**
* (REQUIRED) Whether to generate the .d.ts rollup file.
*/
"enabled": false
/**
* Specifies the output path for a .d.ts rollup file to be generated without any trimming.
* This file will include all declarations that are exported by the main entry point.
*
* If the path is an empty string, then this file will not be written.
*
* The path is resolved relative to the folder of the config file that contains the setting; to change this,
* prepend a folder token such as "<projectFolder>".
*
* SUPPORTED TOKENS: <projectFolder>, <packageName>, <unscopedPackageName>
* DEFAULT VALUE: "<projectFolder>/dist/<unscopedPackageName>.d.ts"
*/
// "untrimmedFilePath": "<projectFolder>/dist/<unscopedPackageName>.d.ts",
/**
* Specifies the output path for a .d.ts rollup file to be generated with trimming for an "alpha" release.
* This file will include only declarations that are marked as "@public", "@beta", or "@alpha".
*
* The path is resolved relative to the folder of the config file that contains the setting; to change this,
* prepend a folder token such as "<projectFolder>".
*
* SUPPORTED TOKENS: <projectFolder>, <packageName>, <unscopedPackageName>
* DEFAULT VALUE: ""
*/
// "alphaTrimmedFilePath": "<projectFolder>/dist/<unscopedPackageName>-alpha.d.ts",
/**
* Specifies the output path for a .d.ts rollup file to be generated with trimming for a "beta" release.
* This file will include only declarations that are marked as "@public" or "@beta".
*
* The path is resolved relative to the folder of the config file that contains the setting; to change this,
* prepend a folder token such as "<projectFolder>".
*
* SUPPORTED TOKENS: <projectFolder>, <packageName>, <unscopedPackageName>
* DEFAULT VALUE: ""
*/
// "betaTrimmedFilePath": "<projectFolder>/dist/<unscopedPackageName>-beta.d.ts",
/**
* Specifies the output path for a .d.ts rollup file to be generated with trimming for a "public" release.
* This file will include only declarations that are marked as "@public".
*
* If the path is an empty string, then this file will not be written.
*
* The path is resolved relative to the folder of the config file that contains the setting; to change this,
* prepend a folder token such as "<projectFolder>".
*
* SUPPORTED TOKENS: <projectFolder>, <packageName>, <unscopedPackageName>
* DEFAULT VALUE: ""
*/
// "publicTrimmedFilePath": "<projectFolder>/dist/<unscopedPackageName>-public.d.ts",
/**
* When a declaration is trimmed, by default it will be replaced by a code comment such as
* "Excluded from this release type: exampleMember". Set "omitTrimmingComments" to true to remove the
* declaration completely.
*
* DEFAULT VALUE: false
*/
// "omitTrimmingComments": true
},
/**
* Configures how the tsdoc-metadata.json file will be generated.
*/
"tsdocMetadata": {
/**
* Whether to generate the tsdoc-metadata.json file.
*
* DEFAULT VALUE: true
*/
// "enabled": true,
/**
* Specifies where the TSDoc metadata file should be written.
*
* The path is resolved relative to the folder of the config file that contains the setting; to change this,
* prepend a folder token such as "<projectFolder>".
*
* The default value is "<lookup>", which causes the path to be automatically inferred from the "tsdocMetadata",
* "typings" or "main" fields of the project's package.json. If none of these fields are set, the lookup
* falls back to "tsdoc-metadata.json" in the package folder.
*
* SUPPORTED TOKENS: <projectFolder>, <packageName>, <unscopedPackageName>
* DEFAULT VALUE: "<lookup>"
*/
// "tsdocMetadataFilePath": "<projectFolder>/dist/tsdoc-metadata.json"
},
/**
* Specifies what type of newlines API Extractor should use when writing output files. By default, the output files
* will be written with Windows-style newlines. To use POSIX-style newlines, specify "lf" instead.
* To use the OS's default newline kind, specify "os".
*
* DEFAULT VALUE: "crlf"
*/
"newlineKind": "lf",
/**
* Configures how API Extractor reports error and warning messages produced during analysis.
*
* There are three sources of messages: compiler messages, API Extractor messages, and TSDoc messages.
*/
"messages": {
/**
* Configures handling of diagnostic messages reported by the TypeScript compiler engine while analyzing
* the input .d.ts files.
*
* TypeScript message identifiers start with "TS" followed by an integer. For example: "TS2551"
*
* DEFAULT VALUE: A single "default" entry with logLevel=warning.
*/
"compilerMessageReporting": {
/**
* Configures the default routing for messages that don't match an explicit rule in this table.
*/
"default": {
/**
* Specifies whether the message should be written to the the tool's output log. Note that
* the "addToApiReportFile" property may supersede this option.
*
* Possible values: "error", "warning", "none"
*
* Errors cause the build to fail and return a nonzero exit code. Warnings cause a production build fail
* and return a nonzero exit code. For a non-production build (e.g. when "api-extractor run" includes
* the "--local" option), the warning is displayed but the build will not fail.
*
* DEFAULT VALUE: "warning"
*/
"logLevel": "warning"
/**
* When addToApiReportFile is true: If API Extractor is configured to write an API report file (.api.md),
* then the message will be written inside that file; otherwise, the message is instead logged according to
* the "logLevel" option.
*
* DEFAULT VALUE: false
*/
// "addToApiReportFile": false
}
// "TS2551": {
// "logLevel": "warning",
// "addToApiReportFile": true
// },
//
// . . .
},
/**
* Configures handling of messages reported by API Extractor during its analysis.
*
* API Extractor message identifiers start with "ae-". For example: "ae-extra-release-tag"
*
* DEFAULT VALUE: See api-extractor-defaults.json for the complete table of extractorMessageReporting mappings
*/
"extractorMessageReporting": {
"default": {
"logLevel": "warning"
// "addToApiReportFile": false
}
// "ae-extra-release-tag": {
// "logLevel": "warning",
// "addToApiReportFile": true
// },
//
// . . .
},
/**
* Configures handling of messages reported by the TSDoc parser when analyzing code comments.
*
* TSDoc message identifiers start with "tsdoc-". For example: "tsdoc-link-tag-unescaped-text"
*
* DEFAULT VALUE: A single "default" entry with logLevel=warning.
*/
"tsdocMessageReporting": {
"default": {
"logLevel": "warning"
// "addToApiReportFile": false
}
// "tsdoc-link-tag-unescaped-text": {
// "logLevel": "warning",
// "addToApiReportFile": true
// },
//
// . . .
}
}
}

3
packages/rest/package.json
View File

@@ -6,7 +6,7 @@
"build": "tsup",
"lint": "prettier --cache --check . && eslint src __tests__ --ext mjs,js,ts --cache",
"format": "prettier --cache --write . && eslint src __tests__ --ext mjs,js,ts --fix --cache",
"docs": "docgen -i src/index.ts -c docs/index.json -o docs/docs.json --typescript",
"docs": "docgen -i src/index.ts -c docs/index.json -o docs/docs.json --typescript && api-extractor run --local",
"prepack": "yarn build && yarn lint",
"changelog": "git cliff --prepend ./CHANGELOG.md -u -c ./cliff.toml -r ../../ --include-path 'packages/rest/*'",
"release": "cliff-jumper"
@@ -61,6 +61,7 @@
"@discordjs/docgen": "workspace:^",
"@discordjs/scripts": "workspace:^",
"@favware/cliff-jumper": "^1.8.3",
"@microsoft/api-extractor": "^7.28.2",
"eslint": "^8.18.0",
"prettier": "^2.7.1",
"tsup": "^6.1.2",

126
packages/rest/src/lib/CDN.ts
View File

@@ -14,6 +14,7 @@ import {
export interface BaseImageURLOptions {
/**
* The extension to use for the image URL
*
* @default 'webp'
*/
extension?: ImageExtension;
@@ -39,6 +40,7 @@ export interface ImageURLOptions extends BaseImageURLOptions {
export interface MakeURLOptions {
/**
* The extension to use for the image URL
*
* @default 'webp'
*/
extension?: string | undefined;
@@ -60,9 +62,10 @@ export class CDN {
/**
* Generates an app asset URL for a client's asset.
* @param clientId The client id that has the asset
* @param assetHash The hash provided by Discord for this asset
* @param options Optional options for the asset
*
* @param clientId - The client id that has the asset
* @param assetHash - The hash provided by Discord for this asset
* @param options - Optional options for the asset
*/
public appAsset(clientId: string, assetHash: string, options?: Readonly<BaseImageURLOptions>): string {
return this.makeURL(`/app-assets/${clientId}/${assetHash}`, options);
@@ -70,9 +73,10 @@ export class CDN {
/**
* Generates an app icon URL for a client's icon.
* @param clientId The client id that has the icon
* @param iconHash The hash provided by Discord for this icon
* @param options Optional options for the icon
*
* @param clientId - The client id that has the icon
* @param iconHash - The hash provided by Discord for this icon
* @param options - Optional options for the icon
*/
public appIcon(clientId: string, iconHash: string, options?: Readonly<BaseImageURLOptions>): string {
return this.makeURL(`/app-icons/${clientId}/${iconHash}`, options);
@@ -80,9 +84,10 @@ export class CDN {
/**
* Generates an avatar URL, e.g. for a user or a webhook.
* @param id The id that has the icon
* @param avatarHash The hash provided by Discord for this avatar
* @param options Optional options for the avatar
*
* @param id - The id that has the icon
* @param avatarHash - The hash provided by Discord for this avatar
* @param options - Optional options for the avatar
*/
public avatar(id: string, avatarHash: string, options?: Readonly<ImageURLOptions>): string {
return this.dynamicMakeURL(`/avatars/${id}/${avatarHash}`, avatarHash, options);
@@ -90,9 +95,10 @@ export class CDN {
/**
* Generates a banner URL, e.g. for a user or a guild.
* @param id The id that has the banner splash
* @param bannerHash The hash provided by Discord for this banner
* @param options Optional options for the banner
*
* @param id - The id that has the banner splash
* @param bannerHash - The hash provided by Discord for this banner
* @param options - Optional options for the banner
*/
public banner(id: string, bannerHash: string, options?: Readonly<ImageURLOptions>): string {
return this.dynamicMakeURL(`/banners/${id}/${bannerHash}`, bannerHash, options);
@@ -100,9 +106,10 @@ export class CDN {
/**
* Generates an icon URL for a channel, e.g. a group DM.
* @param channelId The channel id that has the icon
* @param iconHash The hash provided by Discord for this channel
* @param options Optional options for the icon
*
* @param channelId - The channel id that has the icon
* @param iconHash - The hash provided by Discord for this channel
* @param options - Optional options for the icon
*/
public channelIcon(channelId: string, iconHash: string, options?: Readonly<BaseImageURLOptions>): string {
return this.makeURL(`/channel-icons/${channelId}/${iconHash}`, options);
@@ -110,7 +117,8 @@ export class CDN {
/**
* Generates the default avatar URL for a discriminator.
* @param discriminator The discriminator modulo 5
*
* @param discriminator - The discriminator modulo 5
*/
public defaultAvatar(discriminator: number): string {
return this.makeURL(`/embed/avatars/${discriminator}`, { extension: 'png' });
@@ -118,9 +126,10 @@ export class CDN {
/**
* Generates a discovery splash URL for a guild's discovery splash.
* @param guildId The guild id that has the discovery splash
* @param splashHash The hash provided by Discord for this splash
* @param options Optional options for the splash
*
* @param guildId - The guild id that has the discovery splash
* @param splashHash - The hash provided by Discord for this splash
* @param options - Optional options for the splash
*/
public discoverySplash(guildId: string, splashHash: string, options?: Readonly<BaseImageURLOptions>): string {
return this.makeURL(`/discovery-splashes/${guildId}/${splashHash}`, options);
@@ -128,8 +137,9 @@ export class CDN {
/**
* Generates an emoji's URL for an emoji.
* @param emojiId The emoji id
* @param extension The extension of the emoji
*
* @param emojiId - The emoji id
* @param extension - The extension of the emoji
*/
public emoji(emojiId: string, extension?: ImageExtension): string {
return this.makeURL(`/emojis/${emojiId}`, { extension });
@@ -137,10 +147,11 @@ export class CDN {
/**
* Generates a guild member avatar URL.
* @param guildId The id of the guild
* @param userId The id of the user
* @param avatarHash The hash provided by Discord for this avatar
* @param options Optional options for the avatar
*
* @param guildId - The id of the guild
* @param userId - The id of the user
* @param avatarHash - The hash provided by Discord for this avatar
* @param options - Optional options for the avatar
*/
public guildMemberAvatar(
guildId: string,
@@ -153,10 +164,11 @@ export class CDN {
/**
* Generates a guild member banner URL.
* @param guildId The id of the guild
* @param userId The id of the user
* @param bannerHash The hash provided by Discord for this banner
* @param options Optional options for the banner
*
* @param guildId - The id of the guild
* @param userId - The id of the user
* @param bannerHash - The hash provided by Discord for this banner
* @param options - Optional options for the banner
*/
public guildMemberBanner(
guildId: string,
@@ -169,9 +181,10 @@ export class CDN {
/**
* Generates an icon URL, e.g. for a guild.
* @param id The id that has the icon splash
* @param iconHash The hash provided by Discord for this icon
* @param options Optional options for the icon
*
* @param id - The id that has the icon splash
* @param iconHash - The hash provided by Discord for this icon
* @param options - Optional options for the icon
*/
public icon(id: string, iconHash: string, options?: Readonly<ImageURLOptions>): string {
return this.dynamicMakeURL(`/icons/${id}/${iconHash}`, iconHash, options);
@@ -179,9 +192,9 @@ export class CDN {
/**
* Generates a URL for the icon of a role
* @param roleId The id of the role that has the icon
* @param roleIconHash The hash provided by Discord for this role icon
* @param options Optional options for the role icon
* @param roleId - The id of the role that has the icon
* @param roleIconHash - The hash provided by Discord for this role icon
* @param options - Optional options for the role icon
*/
public roleIcon(roleId: string, roleIconHash: string, options?: Readonly<BaseImageURLOptions>): string {
return this.makeURL(`/role-icons/${roleId}/${roleIconHash}`, options);
@@ -189,9 +202,10 @@ export class CDN {
/**
* Generates a guild invite splash URL for a guild's invite splash.
* @param guildId The guild id that has the invite splash
* @param splashHash The hash provided by Discord for this splash
* @param options Optional options for the splash
*
* @param guildId - The guild id that has the invite splash
* @param splashHash - The hash provided by Discord for this splash
* @param options - Optional options for the splash
*/
public splash(guildId: string, splashHash: string, options?: Readonly<BaseImageURLOptions>): string {
return this.makeURL(`/splashes/${guildId}/${splashHash}`, options);
@@ -199,8 +213,9 @@ export class CDN {
/**
* Generates a sticker URL.
* @param stickerId The sticker id
* @param extension The extension of the sticker
*
* @param stickerId - The sticker id
* @param extension - The extension of the sticker
*/
public sticker(stickerId: string, extension?: StickerExtension): string {
return this.makeURL(`/stickers/${stickerId}`, {
@@ -211,8 +226,9 @@ export class CDN {
/**
* Generates a sticker pack banner URL.
* @param bannerId The banner id
* @param options Optional options for the banner
*
* @param bannerId - The banner id
* @param options - Optional options for the banner
*/
public stickerPackBanner(bannerId: string, options?: Readonly<BaseImageURLOptions>): string {
return this.makeURL(`/app-assets/710982414301790216/store/${bannerId}`, options);
@@ -220,9 +236,10 @@ export class CDN {
/**
* Generates a team icon URL for a team's icon.
* @param teamId The team id that has the icon
* @param iconHash The hash provided by Discord for this icon
* @param options Optional options for the icon
*
* @param teamId - The team id that has the icon
* @param iconHash - The hash provided by Discord for this icon
* @param options - Optional options for the icon
*/
public teamIcon(teamId: string, iconHash: string, options?: Readonly<BaseImageURLOptions>): string {
return this.makeURL(`/team-icons/${teamId}/${iconHash}`, options);
@@ -230,9 +247,10 @@ export class CDN {
/**
* Generates a cover image for a guild scheduled event.
* @param scheduledEventId The scheduled event id
* @param coverHash The hash provided by discord for this cover image
* @param options Optional options for the cover image
*
* @param scheduledEventId - The scheduled event id
* @param coverHash - The hash provided by discord for this cover image
* @param options - Optional options for the cover image
*/
public guildScheduledEventCover(
scheduledEventId: string,
@@ -244,9 +262,10 @@ export class CDN {
/**
* Constructs the URL for the resource, checking whether or not `hash` starts with `a_` if `dynamic` is set to `true`.
* @param route The base cdn route
* @param hash The hash provided by Discord for this icon
* @param options Optional options for the link
*
* @param route - The base cdn route
* @param hash - The hash provided by Discord for this icon
* @param options - Optional options for the link
*/
private dynamicMakeURL(
route: string,
@@ -258,8 +277,9 @@ export class CDN {
/**
* Constructs the URL for the resource
* @param route The base cdn route
* @param options The extension/size options for the link
*
* @param route - The base cdn route
* @param options - The extension/size options for the link
*/
private makeURL(
route: string,

51
packages/rest/src/lib/REST.ts
View File

@@ -31,32 +31,38 @@ export interface RESTOptions {
/**
* The authorization prefix to use for requests, useful if you want to use
* bearer tokens
*
* @default 'Bot'
*/
authPrefix: 'Bot' | 'Bearer';
/**
* The cdn path
*
* @default 'https://cdn.discordapp.com'
*/
cdn: string;
/**
* Additional headers to send for all API requests
*
* @default {}
*/
headers: Record<string, string>;
/**
* The number of invalid REST requests (those that return 401, 403, or 429) in a 10 minute window between emitted warnings (0 for no warnings).
* That is, if set to 500, warnings will be emitted at invalid request number 500, 1000, 1500, and so on.
*
* @default 0
*/
invalidRequestWarningInterval: number;
/**
* How many requests to allow sending per second (Infinity for unlimited, 50 for the standard global limit used by Discord)
*
* @default 50
*/
globalRequestsPerSecond: number;
/**
* The extra offset to add to rate limits in milliseconds
*
* @default 50
*/
offset: number;
@@ -65,42 +71,50 @@ export interface RESTOptions {
* When an array of strings, each element is treated as a prefix for the request route
* (e.g. `/channels` to match any route starting with `/channels` such as `/channels/:id/messages`)
* for which to throw {@link RateLimitError}s. All other request routes will be queued normally
*
* @default null
*/
rejectOnRateLimit: string[] | RateLimitQueueFilter | null;
/**
* The number of retries for errors with the 500 code, or errors
* that timeout
*
* @default 3
*/
retries: number;
/**
* The time to wait in milliseconds before a request is aborted
*
* @default 15_000
*/
timeout: number;
/**
* Extra information to add to the user agent
*
* @default `Node.js ${process.version}`
*/
userAgentAppendix: string;
/**
* The version of the API to use
*
* @default '10'
*/
version: string;
/**
* The amount of time in milliseconds that passes between each hash sweep. (defaults to 4h)
*
* @default 14_400_000
*/
hashSweepInterval: number;
/**
* The maximum amount of time a hash can exist in milliseconds without being hit with a request (defaults to 24h)
*
* @default 86_400_000
*/
hashLifetime: number;
/**
* The amount of time in milliseconds that passes between each hash sweep. (defaults to 1h)
*
* @default 3_600_000
*/
handlerSweepInterval: number;
@@ -250,7 +264,8 @@ export class REST extends EventEmitter {
/**
* Sets the default agent to use for requests performed by this instance
* @param agent Sets the agent to use
*
* @param agent - Sets the agent to use
*/
public setAgent(agent: Dispatcher) {
this.requestManager.setAgent(agent);
@@ -259,7 +274,8 @@ export class REST extends EventEmitter {
/**
* Sets the authorization token that should be used for requests
* @param token The authorization token to use
*
* @param token - The authorization token to use
*/
public setToken(token: string) {
this.requestManager.setToken(token);
@@ -268,8 +284,9 @@ export class REST extends EventEmitter {
/**
* Runs a get request from the api
* @param fullRoute The full route to query
* @param options Optional request options
*
* @param fullRoute - The full route to query
* @param options - Optional request options
*/
public get(fullRoute: RouteLike, options: RequestData = {}) {
return this.request({ ...options, fullRoute, method: RequestMethod.Get });
@@ -277,8 +294,9 @@ export class REST extends EventEmitter {
/**
* Runs a delete request from the api
* @param fullRoute The full route to query
* @param options Optional request options
*
* @param fullRoute - The full route to query
* @param options - Optional request options
*/
public delete(fullRoute: RouteLike, options: RequestData = {}) {
return this.request({ ...options, fullRoute, method: RequestMethod.Delete });
@@ -286,8 +304,9 @@ export class REST extends EventEmitter {
/**
* Runs a post request from the api
* @param fullRoute The full route to query
* @param options Optional request options
*
* @param fullRoute - The full route to query
* @param options - Optional request options
*/
public post(fullRoute: RouteLike, options: RequestData = {}) {
return this.request({ ...options, fullRoute, method: RequestMethod.Post });
@@ -295,8 +314,9 @@ export class REST extends EventEmitter {
/**
* Runs a put request from the api
* @param fullRoute The full route to query
* @param options Optional request options
*
* @param fullRoute - The full route to query
* @param options - Optional request options
*/
public put(fullRoute: RouteLike, options: RequestData = {}) {
return this.request({ ...options, fullRoute, method: RequestMethod.Put });
@@ -304,8 +324,9 @@ export class REST extends EventEmitter {
/**
* Runs a patch request from the api
* @param fullRoute The full route to query
* @param options Optional request options
*
* @param fullRoute - The full route to query
* @param options - Optional request options
*/
public patch(fullRoute: RouteLike, options: RequestData = {}) {
return this.request({ ...options, fullRoute, method: RequestMethod.Patch });
@@ -313,7 +334,8 @@ export class REST extends EventEmitter {
/**
* Runs a request from the api
* @param options Request options
*
* @param options - Request options
*/
public async request(options: InternalRequest) {
const response = await this.raw(options);
@@ -322,7 +344,8 @@ export class REST extends EventEmitter {
/**
* Runs a request from the API, yielding the raw Response object
* @param options Request options
*
* @param options - Request options
*/
public raw(options: InternalRequest) {
return this.requestManager.queueRequest(options);

28
packages/rest/src/lib/RequestManager.ts
View File

@@ -39,11 +39,13 @@ export interface RequestData {
appendToFormData?: boolean;
/**
* If this request needs the `Authorization` header
*
* @default true
*/
auth?: boolean;
/**
* The authorization prefix to use for this request, useful if you use this with bearer tokens
*
* @default 'Bot'
*/
authPrefix?: 'Bot' | 'Bearer';
@@ -79,6 +81,7 @@ export interface RequestData {
reason?: string;
/**
* If this request should be versioned
*
* @default true
*/
versioned?: boolean;
@@ -273,7 +276,8 @@ export class RequestManager extends EventEmitter {
/**
* Sets the default agent to use for requests performed by this manager
* @param agent The agent to use
*
* @param agent - The agent to use
*/
public setAgent(agent: Dispatcher) {
this.agent = agent;
@@ -282,7 +286,8 @@ export class RequestManager extends EventEmitter {
/**
* Sets the authorization token that should be used for requests
* @param token The authorization token to use
*
* @param token - The authorization token to use
*/
public setToken(token: string) {
this.#token = token;
@@ -291,7 +296,9 @@ export class RequestManager extends EventEmitter {
/**
* Queues a request to be sent
* @param request All the information needed to make a request
*
* @param request - All the information needed to make a request
*
* @returns The response from the api request
*/
public async queueRequest(request: InternalRequest): Promise<Dispatcher.ResponseData> {
@@ -321,8 +328,10 @@ export class RequestManager extends EventEmitter {
/**
* Creates a new rate limit handler from a hash, based on the hash and the major parameter
* @param hash The hash for the route
* @param majorParameter The major parameter for this handler
*
* @param hash - The hash for the route
* @param majorParameter - The major parameter for this handler
*
* @private
*/
private createHandler(hash: string, majorParameter: string) {
@@ -336,7 +345,8 @@ export class RequestManager extends EventEmitter {
/**
* Formats the request data to a usable format for fetch
* @param request The request data
*
* @param request - The request data
*/
private async resolveRequest(request: InternalRequest): Promise<{ url: string; fetchOptions: RequestOptions }> {
const { options } = this;
@@ -460,8 +470,10 @@ export class RequestManager extends EventEmitter {
/**
* Generates route data for an endpoint:method
* @param endpoint The raw endpoint to generalize
* @param method The HTTP method this endpoint is called without
*
* @param endpoint - The raw endpoint to generalize
* @param method - The HTTP method this endpoint is called without
*
* @private
*/
private static generateRouteData(endpoint: RouteLike, method: RequestMethod): RouteData {

12
packages/rest/src/lib/errors/DiscordAPIError.ts
View File

@@ -43,12 +43,12 @@ export class DiscordAPIError extends Error {
public requestBody: RequestBody;
/**
* @param rawError The error reported by Discord
* @param code The error code reported by Discord
* @param status The status code of the response
* @param method The method of the request that erred
* @param url The url of the request that erred
* @param bodyData The unparsed data for the request that errored
* @param rawError - The error reported by Discord
* @param code - The error code reported by Discord
* @param status - The status code of the response
* @param method - The method of the request that erred
* @param url - The url of the request that erred
* @param bodyData - The unparsed data for the request that errored
*/
public constructor(
public rawError: DiscordErrorData | OAuthErrorData,

10
packages/rest/src/lib/errors/HTTPError.ts
View File

@@ -8,11 +8,11 @@ export class HTTPError extends Error {
public requestBody: RequestBody;
/**
* @param name The name of the error
* @param status The status code of the response
* @param method The method of the request that erred
* @param url The url of the request that erred
* @param bodyData The unparsed data for the request that errored
* @param name - The name of the error
* @param status - The status code of the response
* @param method - The method of the request that erred
* @param url - The url of the request that erred
* @param bodyData - The unparsed data for the request that errored
*/
public constructor(
public override name: string,

36
packages/rest/src/lib/handlers/SequentialHandler.ts
View File

@@ -10,7 +10,8 @@ import { RateLimitError } from '../errors/RateLimitError';
import { RESTEvents } from '../utils/constants';
import { hasSublimit, parseHeader, parseResponse } from '../utils/utils';
/* Invalid request limiting is done on a per-IP basis, not a per-token basis.
/**
* Invalid request limiting is done on a per-IP basis, not a per-token basis.
* The best we can do is track invalid counts process-wide (on the theory that
* users could have multiple bots run from one process) rather than per-bot.
* Therefore, store these at file scope here rather than in the client's
@@ -73,9 +74,9 @@ export class SequentialHandler implements IHandler {
#shiftSublimit = false;
/**
* @param manager The request manager
* @param hash The hash that this RequestHandler handles
* @param majorParameter The major parameter for this handler
* @param manager - The request manager
* @param hash - The hash that this RequestHandler handles
* @param majorParameter - The major parameter for this handler
*/
public constructor(
private readonly manager: RequestManager,
@@ -126,7 +127,8 @@ export class SequentialHandler implements IHandler {
/**
* Emits a debug message
* @param message The message to debug
*
* @param message - The message to debug
*/
private debug(message: string) {
this.manager.emit(RESTEvents.Debug, `[REST ${this.id}] ${message}`);
@@ -134,8 +136,8 @@ export class SequentialHandler implements IHandler {
/**
* Delay all requests for the specified amount of time, handling global rate limits
* @param time The amount of time to delay all requests for
* @returns
*
* @param time - The amount of time to delay all requests for
*/
private async globalDelayFor(time: number): Promise<void> {
await sleep(time, undefined, { ref: false });
@@ -160,10 +162,11 @@ export class SequentialHandler implements IHandler {
/**
* Queues a request to be sent
* @param routeId The generalized api route with literal ids for major parameters
* @param url The url to do the request on
* @param options All the information needed to make a request
* @param requestData Extra data from the user's request needed for errors and additional processing
*
* @param routeId - The generalized api route with literal ids for major parameters
* @param url - The url to do the request on
* @param options - All the information needed to make a request
* @param requestData - Extra data from the user's request needed for errors and additional processing
*/
public async queueRequest(
routeId: RouteData,
@@ -216,11 +219,12 @@ export class SequentialHandler implements IHandler {
/**
* The method that actually makes the request to the api, and updates info about the bucket accordingly
* @param routeId The generalized api route with literal ids for major parameters
* @param url The fully resolved url to make the request to
* @param options The fetch options needed to make the request
* @param requestData Extra data from the user's request needed for errors and additional processing
* @param retries The number of retries this request has already attempted (recursion)
*
* @param routeId - The generalized api route with literal ids for major parameters
* @param url - The fully resolved url to make the request to
* @param options - The fetch options needed to make the request
* @param requestData - Extra data from the user's request needed for errors and additional processing
* @param retries - The number of retries this request has already attempted (recursion)
*/
private async runRequest(
routeId: RouteData,

15
packages/rest/src/lib/utils/utils.ts
View File

@@ -40,7 +40,9 @@ function serializeSearchParam(value: unknown): string | null {
/**
* Creates and populates an URLSearchParams instance from an object, stripping
* out null and undefined values, while also coercing non-strings to strings.
* @param options The options to use
*
* @param options - The options to use
*
* @returns A populated URLSearchParams instance
*/
export function makeURLSearchParams(options?: Record<string, unknown>) {
@@ -57,7 +59,8 @@ export function makeURLSearchParams(options?: Record<string, unknown>) {
/**
* Converts the response to usable data
* @param res The fetch response
*
* @param res - The fetch response
*/
export function parseResponse(res: Dispatcher.ResponseData): Promise<unknown> {
const header = parseHeader(res.headers['content-type']);
@@ -70,9 +73,11 @@ export function parseResponse(res: Dispatcher.ResponseData): Promise<unknown> {
/**
* Check whether a request falls under a sublimit
* @param bucketRoute The buckets route identifier
* @param body The options provided as JSON data
* @param method The HTTP method that will be used to make the request
*
* @param bucketRoute - The buckets route identifier
* @param body - The options provided as JSON data
* @param method - The HTTP method that will be used to make the request
*
* @returns Whether the request falls under a sublimit
*/
export function hasSublimit(bucketRoute: string, body?: unknown, method?: string): boolean {

376
packages/voice/api-extractor.json Normal file
View File

@@ -0,0 +1,376 @@
/**
* Config file for API Extractor. For more info, please visit: https://api-extractor.com
*/
{
"$schema": "https://developer.microsoft.com/json-schemas/api-extractor/v7/api-extractor.schema.json",
/**
* Optionally specifies another JSON config file that this file extends from. This provides a way for
* standard settings to be shared across multiple projects.
*
* If the path starts with "./" or "../", the path is resolved relative to the folder of the file that contains
* the "extends" field. Otherwise, the first path segment is interpreted as an NPM package name, and will be
* resolved using NodeJS require().
*
* SUPPORTED TOKENS: none
* DEFAULT VALUE: ""
*/
// "extends": "./shared/api-extractor-base.json"
// "extends": "my-package/include/api-extractor-base.json"
/**
* Determines the "<projectFolder>" token that can be used with other config file settings. The project folder
* typically contains the tsconfig.json and package.json config files, but the path is user-defined.
*
* The path is resolved relative to the folder of the config file that contains the setting.
*
* The default value for "projectFolder" is the token "<lookup>", which means the folder is determined by traversing
* parent folders, starting from the folder containing api-extractor.json, and stopping at the first folder
* that contains a tsconfig.json file. If a tsconfig.json file cannot be found in this way, then an error
* will be reported.
*
* SUPPORTED TOKENS: <lookup>
* DEFAULT VALUE: "<lookup>"
*/
// "projectFolder": "..",
/**
* (REQUIRED) Specifies the .d.ts file to be used as the starting point for analysis. API Extractor
* analyzes the symbols exported by this module.
*
* The file extension must be ".d.ts" and not ".ts".
*
* The path is resolved relative to the folder of the config file that contains the setting; to change this,
* prepend a folder token such as "<projectFolder>".
*
* SUPPORTED TOKENS: <projectFolder>, <packageName>, <unscopedPackageName>
*/
"mainEntryPointFilePath": "<projectFolder>/dist/index.d.ts",
/**
* A list of NPM package names whose exports should be treated as part of this package.
*
* For example, suppose that Webpack is used to generate a distributed bundle for the project "library1",
* and another NPM package "library2" is embedded in this bundle. Some types from library2 may become part
* of the exported API for library1, but by default API Extractor would generate a .d.ts rollup that explicitly
* imports library2. To avoid this, we can specify:
*
* "bundledPackages": [ "library2" ],
*
* This would direct API Extractor to embed those types directly in the .d.ts rollup, as if they had been
* local files for library1.
*/
"bundledPackages": [],
/**
* Determines how the TypeScript compiler engine will be invoked by API Extractor.
*/
"compiler": {
/**
* Specifies the path to the tsconfig.json file to be used by API Extractor when analyzing the project.
*
* The path is resolved relative to the folder of the config file that contains the setting; to change this,
* prepend a folder token such as "<projectFolder>".
*
* Note: This setting will be ignored if "overrideTsconfig" is used.
*
* SUPPORTED TOKENS: <projectFolder>, <packageName>, <unscopedPackageName>
* DEFAULT VALUE: "<projectFolder>/tsconfig.json"
*/
// "tsconfigFilePath": "<projectFolder>/tsconfig.json",
/**
* Provides a compiler configuration that will be used instead of reading the tsconfig.json file from disk.
* The object must conform to the TypeScript tsconfig schema:
*
* http://json.schemastore.org/tsconfig
*
* If omitted, then the tsconfig.json file will be read from the "projectFolder".
*
* DEFAULT VALUE: no overrideTsconfig section
*/
// "overrideTsconfig": {
// . . .
// }
/**
* This option causes the compiler to be invoked with the --skipLibCheck option. This option is not recommended
* and may cause API Extractor to produce incomplete or incorrect declarations, but it may be required when
* dependencies contain declarations that are incompatible with the TypeScript engine that API Extractor uses
* for its analysis. Where possible, the underlying issue should be fixed rather than relying on skipLibCheck.
*
* DEFAULT VALUE: false
*/
// "skipLibCheck": true,
},
/**
* Configures how the API report file (*.api.md) will be generated.
*/
"apiReport": {
/**
* (REQUIRED) Whether to generate an API report.
*/
"enabled": false
/**
* The filename for the API report files. It will be combined with "reportFolder" or "reportTempFolder" to produce
* a full file path.
*
* The file extension should be ".api.md", and the string should not contain a path separator such as "\" or "/".
*
* SUPPORTED TOKENS: <packageName>, <unscopedPackageName>
* DEFAULT VALUE: "<unscopedPackageName>.api.md"
*/
// "reportFileName": "<unscopedPackageName>.api.md",
/**
* Specifies the folder where the API report file is written. The file name portion is determined by
* the "reportFileName" setting.
*
* The API report file is normally tracked by Git. Changes to it can be used to trigger a branch policy,
* e.g. for an API review.
*
* The path is resolved relative to the folder of the config file that contains the setting; to change this,
* prepend a folder token such as "<projectFolder>".
*
* SUPPORTED TOKENS: <projectFolder>, <packageName>, <unscopedPackageName>
* DEFAULT VALUE: "<projectFolder>/temp/"
*/
// "reportFolder": "<projectFolder>/temp/",
/**
* Specifies the folder where the temporary report file is written. The file name portion is determined by
* the "reportFileName" setting.
*
* After the temporary file is written to disk, it is compared with the file in the "reportFolder".
* If they are different, a production build will fail.
*
* The path is resolved relative to the folder of the config file that contains the setting; to change this,
* prepend a folder token such as "<projectFolder>".
*
* SUPPORTED TOKENS: <projectFolder>, <packageName>, <unscopedPackageName>
* DEFAULT VALUE: "<projectFolder>/temp/"
*/
// "reportTempFolder": "<projectFolder>/temp/"
},
/**
* Configures how the doc model file (*.api.json) will be generated.
*/
"docModel": {
/**
* (REQUIRED) Whether to generate a doc model file.
*/
"enabled": true,
/**
* The output path for the doc model file. The file extension should be ".api.json".
*
* The path is resolved relative to the folder of the config file that contains the setting; to change this,
* prepend a folder token such as "<projectFolder>".
*
* SUPPORTED TOKENS: <projectFolder>, <packageName>, <unscopedPackageName>
* DEFAULT VALUE: "<projectFolder>/temp/<unscopedPackageName>.api.json"
*/
"apiJsonFilePath": "<projectFolder>/docs/docs.api.json"
},
/**
* Configures how the .d.ts rollup file will be generated.
*/
"dtsRollup": {
/**
* (REQUIRED) Whether to generate the .d.ts rollup file.
*/
"enabled": false
/**
* Specifies the output path for a .d.ts rollup file to be generated without any trimming.
* This file will include all declarations that are exported by the main entry point.
*
* If the path is an empty string, then this file will not be written.
*
* The path is resolved relative to the folder of the config file that contains the setting; to change this,
* prepend a folder token such as "<projectFolder>".
*
* SUPPORTED TOKENS: <projectFolder>, <packageName>, <unscopedPackageName>
* DEFAULT VALUE: "<projectFolder>/dist/<unscopedPackageName>.d.ts"
*/
// "untrimmedFilePath": "<projectFolder>/dist/<unscopedPackageName>.d.ts",
/**
* Specifies the output path for a .d.ts rollup file to be generated with trimming for an "alpha" release.
* This file will include only declarations that are marked as "@public", "@beta", or "@alpha".
*
* The path is resolved relative to the folder of the config file that contains the setting; to change this,
* prepend a folder token such as "<projectFolder>".
*
* SUPPORTED TOKENS: <projectFolder>, <packageName>, <unscopedPackageName>
* DEFAULT VALUE: ""
*/
// "alphaTrimmedFilePath": "<projectFolder>/dist/<unscopedPackageName>-alpha.d.ts",
/**
* Specifies the output path for a .d.ts rollup file to be generated with trimming for a "beta" release.
* This file will include only declarations that are marked as "@public" or "@beta".
*
* The path is resolved relative to the folder of the config file that contains the setting; to change this,
* prepend a folder token such as "<projectFolder>".
*
* SUPPORTED TOKENS: <projectFolder>, <packageName>, <unscopedPackageName>
* DEFAULT VALUE: ""
*/
// "betaTrimmedFilePath": "<projectFolder>/dist/<unscopedPackageName>-beta.d.ts",
/**
* Specifies the output path for a .d.ts rollup file to be generated with trimming for a "public" release.
* This file will include only declarations that are marked as "@public".
*
* If the path is an empty string, then this file will not be written.
*
* The path is resolved relative to the folder of the config file that contains the setting; to change this,
* prepend a folder token such as "<projectFolder>".
*
* SUPPORTED TOKENS: <projectFolder>, <packageName>, <unscopedPackageName>
* DEFAULT VALUE: ""
*/
// "publicTrimmedFilePath": "<projectFolder>/dist/<unscopedPackageName>-public.d.ts",
/**
* When a declaration is trimmed, by default it will be replaced by a code comment such as
* "Excluded from this release type: exampleMember". Set "omitTrimmingComments" to true to remove the
* declaration completely.
*
* DEFAULT VALUE: false
*/
// "omitTrimmingComments": true
},
/**
* Configures how the tsdoc-metadata.json file will be generated.
*/
"tsdocMetadata": {
/**
* Whether to generate the tsdoc-metadata.json file.
*
* DEFAULT VALUE: true
*/
// "enabled": true,
/**
* Specifies where the TSDoc metadata file should be written.
*
* The path is resolved relative to the folder of the config file that contains the setting; to change this,
* prepend a folder token such as "<projectFolder>".
*
* The default value is "<lookup>", which causes the path to be automatically inferred from the "tsdocMetadata",
* "typings" or "main" fields of the project's package.json. If none of these fields are set, the lookup
* falls back to "tsdoc-metadata.json" in the package folder.
*
* SUPPORTED TOKENS: <projectFolder>, <packageName>, <unscopedPackageName>
* DEFAULT VALUE: "<lookup>"
*/
// "tsdocMetadataFilePath": "<projectFolder>/dist/tsdoc-metadata.json"
},
/**
* Specifies what type of newlines API Extractor should use when writing output files. By default, the output files
* will be written with Windows-style newlines. To use POSIX-style newlines, specify "lf" instead.
* To use the OS's default newline kind, specify "os".
*
* DEFAULT VALUE: "crlf"
*/
"newlineKind": "lf",
/**
* Configures how API Extractor reports error and warning messages produced during analysis.
*
* There are three sources of messages: compiler messages, API Extractor messages, and TSDoc messages.
*/
"messages": {
/**
* Configures handling of diagnostic messages reported by the TypeScript compiler engine while analyzing
* the input .d.ts files.
*
* TypeScript message identifiers start with "TS" followed by an integer. For example: "TS2551"
*
* DEFAULT VALUE: A single "default" entry with logLevel=warning.
*/
"compilerMessageReporting": {
/**
* Configures the default routing for messages that don't match an explicit rule in this table.
*/
"default": {
/**
* Specifies whether the message should be written to the the tool's output log. Note that
* the "addToApiReportFile" property may supersede this option.
*
* Possible values: "error", "warning", "none"
*
* Errors cause the build to fail and return a nonzero exit code. Warnings cause a production build fail
* and return a nonzero exit code. For a non-production build (e.g. when "api-extractor run" includes
* the "--local" option), the warning is displayed but the build will not fail.
*
* DEFAULT VALUE: "warning"
*/
"logLevel": "warning"
/**
* When addToApiReportFile is true: If API Extractor is configured to write an API report file (.api.md),
* then the message will be written inside that file; otherwise, the message is instead logged according to
* the "logLevel" option.
*
* DEFAULT VALUE: false
*/
// "addToApiReportFile": false
}
// "TS2551": {
// "logLevel": "warning",
// "addToApiReportFile": true
// },
//
// . . .
},
/**
* Configures handling of messages reported by API Extractor during its analysis.
*
* API Extractor message identifiers start with "ae-". For example: "ae-extra-release-tag"
*
* DEFAULT VALUE: See api-extractor-defaults.json for the complete table of extractorMessageReporting mappings
*/
"extractorMessageReporting": {
"default": {
"logLevel": "warning"
// "addToApiReportFile": false
}
// "ae-extra-release-tag": {
// "logLevel": "warning",
// "addToApiReportFile": true
// },
//
// . . .
},
/**
* Configures handling of messages reported by the TSDoc parser when analyzing code comments.
*
* TSDoc message identifiers start with "tsdoc-". For example: "tsdoc-link-tag-unescaped-text"
*
* DEFAULT VALUE: A single "default" entry with logLevel=warning.
*/
"tsdocMessageReporting": {
"default": {
"logLevel": "warning"
// "addToApiReportFile": false
}
// "tsdoc-link-tag-unescaped-text": {
// "logLevel": "warning",
// "addToApiReportFile": true
// },
//
// . . .
}
}
}

3
packages/voice/package.json
View File

@@ -7,7 +7,7 @@
"test": "jest --coverage",
"lint": "prettier --cache --check . && eslint src __tests__ --ext mjs,js,ts --cache",
"format": "prettier --cache --write . && eslint src __tests__ --ext mjs,js,ts --fix --cache",
"docs": "docgen -i src/index.ts -c docs/index.json -o docs/docs.json --typescript",
"docs": "docgen -i src/index.ts -c docs/index.json -o docs/docs.json --typescript && api-extractor run --local",
"prepack": "yarn build && yarn lint && yarn test",
"changelog": "git cliff --prepend ./CHANGELOG.md -u -c ./cliff.toml -r ../../ --include-path 'packages/voice/*'",
"release": "cliff-jumper"
@@ -64,6 +64,7 @@
"@discordjs/docgen": "workspace:^",
"@discordjs/scripts": "workspace:^",
"@favware/cliff-jumper": "^1.8.3",
"@microsoft/api-extractor": "^7.28.2",
"@types/jest": "^28.1.2",
"eslint": "^8.18.0",
"jest": "^28.1.1",

2
packages/voice/src/networking/VoiceUDPSocket.ts
View File

@@ -125,7 +125,7 @@ export class VoiceUDPSocket extends EventEmitter {
/**
* Called when a message is received on the UDP socket.
*
* @param buffer The received buffer
* @param buffer - The received buffer
*/
private onMessage(buffer: Buffer): void {
// Handle keep alive message

6
packages/voice/src/receive/SSRCMap.ts
View File

@@ -45,7 +45,7 @@ export class SSRCMap extends EventEmitter {
/**
* Updates the map with new user data
*
* @param data The data to update with
* @param data - The data to update with
*/
public update(data: VoiceUserData) {
const existing = this.map.get(data.audioSSRC);
@@ -63,7 +63,7 @@ export class SSRCMap extends EventEmitter {
/**
* Gets the stored voice data of a user.
*
* @param target The target, either their user id or audio SSRC
* @param target - The target, either their user id or audio SSRC
*/
public get(target: number | string) {
if (typeof target === 'number') {
@@ -82,7 +82,7 @@ export class SSRCMap extends EventEmitter {
/**
* Deletes the stored voice data about a user.
*
* @param target The target of the delete operation, either their audio SSRC or user id
* @param target - The target of the delete operation, either their audio SSRC or user id
*
* @returns The data that was deleted, if any
*/

14
packages/voice/src/receive/VoiceReceiver.ts
View File

@@ -58,7 +58,7 @@ export class VoiceReceiver {
/**
* Called when a packet is received on the attached connection's WebSocket.
*
* @param packet The received packet
* @param packet - The received packet
*
* @internal
*/
@@ -118,10 +118,10 @@ export class VoiceReceiver {
/**
* Parses an audio packet, decrypting it to yield an Opus packet.
*
* @param buffer The buffer to parse
* @param mode The encryption mode
* @param nonce The nonce buffer used by the connection for encryption
* @param secretKey The secret key used by the connection for encryption
* @param buffer - The buffer to parse
* @param mode - The encryption mode
* @param nonce - The nonce buffer used by the connection for encryption
* @param secretKey - The secret key used by the connection for encryption
*
* @returns The parsed Opus packet
*/
@@ -152,7 +152,7 @@ export class VoiceReceiver {
/**
* Called when the UDP socket of the attached connection receives a message.
*
* @param msg The received message
* @param msg - The received message
*
* @internal
*/
@@ -186,7 +186,7 @@ export class VoiceReceiver {
/**
* Creates a subscription for the given user id.
*
* @param target The id of the user to subscribe to
* @param target - The id of the user to subscribe to
*
* @returns A readable stream of Opus packets received from the target
*/

8
packages/voice/src/util/demuxProbe.ts
View File

@@ -6,7 +6,7 @@ import { StreamType } from '..';
/**
* Takes an Opus Head, and verifies whether the associated Opus audio is suitable to play in a Discord voice channel.
*
* @param opusHead The Opus Head to validate
* @param opusHead - The Opus Head to validate
*
* @returns `true` if suitable to play in a Discord voice channel, otherwise `false`
*/
@@ -35,9 +35,9 @@ export interface ProbeInfo {
/**
* Attempt to probe a readable stream to figure out whether it can be demuxed using an Ogg or WebM Opus demuxer.
*
* @param stream The readable stream to probe
* @param probeSize The number of bytes to attempt to read before giving up on the probe
* @param validator The Opus Head validator function
* @param stream - The readable stream to probe
* @param probeSize - The number of bytes to attempt to read before giving up on the probe
* @param validator - The Opus Head validator function
*
* @experimental
*/