From b2776c22d4991d0d61386d7d7d85a6a9ba28e2bb Mon Sep 17 00:00:00 2001 From: iCrawl Date: Thu, 30 Jun 2022 15:46:14 +0200 Subject: [PATCH] ci: api-extractor support for docs --- .github/workflows/auto-deprecate.yml | 4 +- .github/workflows/documentation.yml | 40 +- .github/workflows/labelsync.yml | 4 +- .github/workflows/pr-automation.yml | 2 +- .github/workflows/publish-dev-docker.yml | 4 +- .github/workflows/publish-dev.yml | 6 +- .github/workflows/publish-docker.yml | 4 +- .github/workflows/test.yml | 6 +- packages/builders/api-extractor.json | 376 ++++++++++++++++++ packages/builders/package.json | 3 +- packages/builders/src/components/ActionRow.ts | 7 +- .../builders/src/components/Components.ts | 3 +- .../src/components/button/UnsafeButton.ts | 18 +- .../components/selectMenu/UnsafeSelectMenu.ts | 22 +- .../selectMenu/UnsafeSelectMenuOption.ts | 15 +- .../components/textInput/UnsafeTextInput.ts | 24 +- .../ContextMenuCommandBuilder.ts | 16 +- .../src/interactions/modals/UnsafeModal.ts | 12 +- .../slashCommands/SlashCommandBuilder.ts | 10 +- .../slashCommands/SlashCommandSubcommands.ts | 2 +- ...ionCommandNumericOptionMinMaxValueMixin.ts | 6 +- .../mixins/ApplicationCommandOptionBase.ts | 2 +- ...plicationCommandOptionChannelTypesMixin.ts | 2 +- ...ndOptionWithChoicesAndAutocompleteMixin.ts | 4 +- .../mixins/NameAndDescription.ts | 16 +- .../mixins/SharedSlashCommandOptions.ts | 18 +- .../src/messages/embed/UnsafeEmbed.ts | 29 +- packages/builders/src/messages/formatters.ts | 74 ++-- packages/builders/src/util/equatable.ts | 2 +- packages/builders/src/util/jsonEncodable.ts | 2 +- packages/collection/api-extractor.json | 376 ++++++++++++++++++ packages/collection/package.json | 3 +- packages/collection/src/index.ts | 97 ++--- packages/proxy/api-extractor.json | 376 ++++++++++++++++++ packages/proxy/package.json | 3 +- packages/proxy/src/handlers/proxyRequests.ts | 3 +- packages/proxy/src/util/responseHelpers.ts | 20 +- packages/proxy/src/util/util.ts | 1 + packages/rest/api-extractor.json | 376 ++++++++++++++++++ packages/rest/package.json | 3 +- packages/rest/src/lib/CDN.ts | 126 +++--- packages/rest/src/lib/REST.ts | 51 ++- packages/rest/src/lib/RequestManager.ts | 28 +- .../rest/src/lib/errors/DiscordAPIError.ts | 12 +- packages/rest/src/lib/errors/HTTPError.ts | 10 +- .../src/lib/handlers/SequentialHandler.ts | 36 +- packages/rest/src/lib/utils/utils.ts | 15 +- packages/voice/api-extractor.json | 376 ++++++++++++++++++ packages/voice/package.json | 3 +- .../voice/src/networking/VoiceUDPSocket.ts | 2 +- packages/voice/src/receive/SSRCMap.ts | 6 +- packages/voice/src/receive/VoiceReceiver.ts | 14 +- packages/voice/src/util/demuxProbe.ts | 8 +- yarn.lock | 273 ++++++++++++- 54 files changed, 2608 insertions(+), 343 deletions(-) create mode 100644 packages/builders/api-extractor.json create mode 100644 packages/collection/api-extractor.json create mode 100644 packages/proxy/api-extractor.json create mode 100644 packages/rest/api-extractor.json create mode 100644 packages/voice/api-extractor.json diff --git a/.github/workflows/auto-deprecate.yml b/.github/workflows/auto-deprecate.yml index f2e2a9354..0b12fba5c 100644 --- a/.github/workflows/auto-deprecate.yml +++ b/.github/workflows/auto-deprecate.yml @@ -10,10 +10,10 @@ jobs: if: github.repository_owner == 'discordjs' steps: - name: Checkout repository - uses: actions/checkout@v2 + uses: actions/checkout@v3 - name: Install node.js v16 - uses: actions/setup-node@v2 + uses: actions/setup-node@v3 with: node-version: 16 cache: 'yarn' diff --git a/.github/workflows/documentation.yml b/.github/workflows/documentation.yml index d494d81c6..0e4fe5d39 100644 --- a/.github/workflows/documentation.yml +++ b/.github/workflows/documentation.yml @@ -23,12 +23,12 @@ jobs: SHA: ${{ steps.env.outputs.SHA }} steps: - name: Checkout repository - uses: actions/checkout@v2 + uses: actions/checkout@v3 with: ref: ${{ github.event.inputs.ref || '' }} - name: Install node.js v16 - uses: actions/setup-node@v2 + uses: actions/setup-node@v3 with: node-version: 16 cache: 'yarn' @@ -36,7 +36,7 @@ jobs: - name: Turbo cache id: turbo-cache - uses: actions/cache@v2 + uses: actions/cache@v3 with: path: .turbo key: turbo-${{ github.job }}-${{ github.ref_name }}-${{ github.sha }} @@ -49,12 +49,18 @@ jobs: - name: Build docs run: yarn docs --cache-dir=".turbo" - - name: Upload artifacts - uses: actions/upload-artifact@v2 + - name: Upload docgen artifacts + uses: actions/upload-artifact@v3 with: - name: docs + name: docgen path: packages/*/docs/docs.json + - name: Upload api-extractor artifacts + uses: actions/upload-artifact@v3 + with: + name: api-extractor + path: packages/*/docs/docs.api.json + - name: Set outputs for upload job id: env run: | @@ -77,10 +83,10 @@ jobs: SHA: ${{ needs.build.outputs.SHA }} steps: - name: Checkout repository - uses: actions/checkout@v2 + uses: actions/checkout@v3 - name: Install node.js v16 - uses: actions/setup-node@v2 + uses: actions/setup-node@v3 with: node-version: 16 cache: 'yarn' @@ -88,7 +94,7 @@ jobs: - name: Turbo cache id: turbo-cache - uses: actions/cache@v2 + uses: actions/cache@v3 with: path: .turbo key: turbo-${{ github.job }}-${{ github.ref_name }}-${{ github.sha }} @@ -101,14 +107,20 @@ jobs: - name: Build actions run: yarn build --cache-dir=".turbo" - - name: Download artifacts - uses: actions/download-artifact@v2 + - name: Download docgen artifacts + uses: actions/download-artifact@v3 with: - name: docs + name: docgen + path: docs + + - name: Download api-extractor artifacts + uses: actions/download-artifact@v3 + with: + name: api-extractor path: docs - name: Checkout docs repository - uses: actions/checkout@v2 + uses: actions/checkout@v3 with: repository: 'discordjs/docs' token: ${{ secrets.DJS_DOCS }} @@ -129,6 +141,7 @@ jobs: run: | mkdir -p out/${PACKAGE} mv docs/${PACKAGE}/docs/docs.json out/${PACKAGE}/${SEMVER}.json + mv docs/${PACKAGE}/docs/docs.api.json out/${PACKAGE}/${SEMVER}.api.json - name: Move docs to correct directory if: ${{ !github.event.inputs.ref && env.BRANCH_OR_TAG == 'branch' }} @@ -137,6 +150,7 @@ jobs: run: | mkdir -p out/${PACKAGE} mv docs/${PACKAGE}/docs/docs.json out/${PACKAGE}/${BRANCH_NAME}.json + mv docs/${PACKAGE}/docs/docs.api.json out/${PACKAGE}/${BRANCH_NAME}.api.json - name: Commit and push run: | diff --git a/.github/workflows/labelsync.yml b/.github/workflows/labelsync.yml index 62e05a54d..78637829f 100644 --- a/.github/workflows/labelsync.yml +++ b/.github/workflows/labelsync.yml @@ -14,9 +14,9 @@ jobs: runs-on: ubuntu-latest steps: - name: Checkout repository - uses: actions/checkout@v2 + uses: actions/checkout@v3 - name: Label sync - uses: crazy-max/ghaction-github-labeler@v3 + uses: crazy-max/ghaction-github-labeler@v4 with: github-token: ${{ secrets.GITHUB_TOKEN }} diff --git a/.github/workflows/pr-automation.yml b/.github/workflows/pr-automation.yml index cc225f8ec..2780283fb 100644 --- a/.github/workflows/pr-automation.yml +++ b/.github/workflows/pr-automation.yml @@ -6,7 +6,7 @@ jobs: runs-on: ubuntu-latest steps: - name: Automatically label PR - uses: actions/labeler@v3 + uses: actions/labeler@v4 with: repo-token: '${{ secrets.GITHUB_TOKEN }}' sync-labels: true diff --git a/.github/workflows/publish-dev-docker.yml b/.github/workflows/publish-dev-docker.yml index c41920395..10ebb13f8 100644 --- a/.github/workflows/publish-dev-docker.yml +++ b/.github/workflows/publish-dev-docker.yml @@ -11,10 +11,10 @@ jobs: steps: - name: Checkout repository - uses: actions/checkout@v2 + uses: actions/checkout@v3 - name: Set up Docker Buildx - uses: docker/setup-buildx-action@v1 + uses: docker/setup-buildx-action@v2 - name: Login to DockerHub run: echo ${{ secrets.DOCKER_ACCESS_TOKEN }} | docker login -u ${{ secrets.DOCKER_USERNAME }} --password-stdin diff --git a/.github/workflows/publish-dev.yml b/.github/workflows/publish-dev.yml index ba9c1ccdd..f329777f4 100644 --- a/.github/workflows/publish-dev.yml +++ b/.github/workflows/publish-dev.yml @@ -26,10 +26,10 @@ jobs: if: github.repository_owner == 'discordjs' steps: - name: Checkout repository - uses: actions/checkout@v2 + uses: actions/checkout@v3 - name: Install node.js v16 - uses: actions/setup-node@v2 + uses: actions/setup-node@v3 with: node-version: 16 registry-url: https://registry.npmjs.org/ @@ -38,7 +38,7 @@ jobs: - name: Turbo cache id: turbo-cache - uses: actions/cache@v2 + uses: actions/cache@v3 with: path: .turbo key: turbo-${{ github.job }}-${{ github.ref_name }}-${{ github.sha }} diff --git a/.github/workflows/publish-docker.yml b/.github/workflows/publish-docker.yml index d2168b354..82a424dc3 100644 --- a/.github/workflows/publish-docker.yml +++ b/.github/workflows/publish-docker.yml @@ -8,10 +8,10 @@ jobs: steps: - name: Checkout repository - uses: actions/checkout@v2 + uses: actions/checkout@v3 - name: Set up Docker Buildx - uses: docker/setup-buildx-action@v1 + uses: docker/setup-buildx-action@v2 - name: Login to DockerHub run: echo ${{ secrets.DOCKER_ACCESS_TOKEN }} | docker login -u ${{ secrets.DOCKER_USERNAME }} --password-stdin diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml index 4ba47481f..662aff7a2 100644 --- a/.github/workflows/test.yml +++ b/.github/workflows/test.yml @@ -6,10 +6,10 @@ jobs: runs-on: ubuntu-latest steps: - name: Checkout repository - uses: actions/checkout@v2 + uses: actions/checkout@v3 - name: Install node.js v16 - uses: actions/setup-node@v2 + uses: actions/setup-node@v3 with: node-version: 16 cache: 'yarn' @@ -17,7 +17,7 @@ jobs: - name: Turbo cache id: turbo-cache - uses: actions/cache@v2 + uses: actions/cache@v3 with: path: .turbo key: turbo-${{ github.job }}-${{ github.ref_name }}-${{ github.sha }} diff --git a/packages/builders/api-extractor.json b/packages/builders/api-extractor.json new file mode 100644 index 000000000..3845fd481 --- /dev/null +++ b/packages/builders/api-extractor.json @@ -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 "" 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 "", 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: + * DEFAULT VALUE: "" + */ + // "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 "". + * + * SUPPORTED TOKENS: , , + */ + "mainEntryPointFilePath": "/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 "". + * + * Note: This setting will be ignored if "overrideTsconfig" is used. + * + * SUPPORTED TOKENS: , , + * DEFAULT VALUE: "/tsconfig.json" + */ + // "tsconfigFilePath": "/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: , + * DEFAULT VALUE: ".api.md" + */ + // "reportFileName": ".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 "". + * + * SUPPORTED TOKENS: , , + * DEFAULT VALUE: "/temp/" + */ + // "reportFolder": "/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 "". + * + * SUPPORTED TOKENS: , , + * DEFAULT VALUE: "/temp/" + */ + // "reportTempFolder": "/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 "". + * + * SUPPORTED TOKENS: , , + * DEFAULT VALUE: "/temp/.api.json" + */ + "apiJsonFilePath": "/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 "". + * + * SUPPORTED TOKENS: , , + * DEFAULT VALUE: "/dist/.d.ts" + */ + // "untrimmedFilePath": "/dist/.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 "". + * + * SUPPORTED TOKENS: , , + * DEFAULT VALUE: "" + */ + // "alphaTrimmedFilePath": "/dist/-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 "". + * + * SUPPORTED TOKENS: , , + * DEFAULT VALUE: "" + */ + // "betaTrimmedFilePath": "/dist/-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 "". + * + * SUPPORTED TOKENS: , , + * DEFAULT VALUE: "" + */ + // "publicTrimmedFilePath": "/dist/-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 "". + * + * The default value is "", 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: , , + * DEFAULT VALUE: "" + */ + // "tsdocMetadataFilePath": "/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 + // }, + // + // . . . + } + } +} diff --git a/packages/builders/package.json b/packages/builders/package.json index 83cfc6df7..f886feee6 100644 --- a/packages/builders/package.json +++ b/packages/builders/package.json @@ -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", diff --git a/packages/builders/src/components/ActionRow.ts b/packages/builders/src/components/ActionRow.ts index b04636c8c..52ba0455e 100644 --- a/packages/builders/src/components/ActionRow.ts +++ b/packages/builders/src/components/ActionRow.ts @@ -36,8 +36,8 @@ export class ActionRowBuilder 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) { this.components.push(...normalizeArray(components)); @@ -46,7 +46,8 @@ export class ActionRowBuilder 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) { this.components.splice(0, this.components.length, ...normalizeArray(components)); diff --git a/packages/builders/src/components/Components.ts b/packages/builders/src/components/Components.ts index a4bbdd01d..13a1b1603 100644 --- a/packages/builders/src/components/Components.ts +++ b/packages/builders/src/components/Components.ts @@ -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( data: (APIMessageComponent | APIModalComponent) & { type: T }, diff --git a/packages/builders/src/components/button/UnsafeButton.ts b/packages/builders/src/components/button/UnsafeButton.ts index 0a9950b2c..19d722db2 100644 --- a/packages/builders/src/components/button/UnsafeButton.ts +++ b/packages/builders/src/components/button/UnsafeButton.ts @@ -18,7 +18,8 @@ export class UnsafeButtonBuilder extends ComponentBuilder { /** * 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 { /** * 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 { /** * 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 { /** * 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 { /** * 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 { /** * 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; diff --git a/packages/builders/src/components/selectMenu/UnsafeSelectMenu.ts b/packages/builders/src/components/selectMenu/UnsafeSelectMenu.ts index 65e645749..3329d74b3 100644 --- a/packages/builders/src/components/selectMenu/UnsafeSelectMenu.ts +++ b/packages/builders/src/components/selectMenu/UnsafeSelectMenu.ts @@ -20,7 +20,8 @@ export class UnsafeSelectMenuBuilder extends ComponentBuilder) { this.options.push( @@ -79,7 +84,8 @@ export class UnsafeSelectMenuBuilder extends ComponentBuilder) { this.options.splice( diff --git a/packages/builders/src/components/selectMenu/UnsafeSelectMenuOption.ts b/packages/builders/src/components/selectMenu/UnsafeSelectMenuOption.ts index 6115fd377..5b065c0bd 100644 --- a/packages/builders/src/components/selectMenu/UnsafeSelectMenuOption.ts +++ b/packages/builders/src/components/selectMenu/UnsafeSelectMenuOption.ts @@ -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; diff --git a/packages/builders/src/components/textInput/UnsafeTextInput.ts b/packages/builders/src/components/textInput/UnsafeTextInput.ts index cc85d65b1..437d4253c 100644 --- a/packages/builders/src/components/textInput/UnsafeTextInput.ts +++ b/packages/builders/src/components/textInput/UnsafeTextInput.ts @@ -9,7 +9,8 @@ export class UnsafeTextInputBuilder extends ComponentBuilder>) { this.components.splice(0, this.components.length, ...normalizeArray(components)); diff --git a/packages/builders/src/interactions/slashCommands/SlashCommandBuilder.ts b/packages/builders/src/interactions/slashCommands/SlashCommandBuilder.ts index 43af72e61..13cc21678 100644 --- a/packages/builders/src/interactions/slashCommands/SlashCommandBuilder.ts +++ b/packages/builders/src/interactions/slashCommands/SlashCommandBuilder.ts @@ -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: diff --git a/packages/builders/src/interactions/slashCommands/SlashCommandSubcommands.ts b/packages/builders/src/interactions/slashCommands/SlashCommandSubcommands.ts index b7cd1b269..369c3556a 100644 --- a/packages/builders/src/interactions/slashCommands/SlashCommandSubcommands.ts +++ b/packages/builders/src/interactions/slashCommands/SlashCommandSubcommands.ts @@ -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: diff --git a/packages/builders/src/interactions/slashCommands/mixins/ApplicationCommandNumericOptionMinMaxValueMixin.ts b/packages/builders/src/interactions/slashCommands/mixins/ApplicationCommandNumericOptionMinMaxValueMixin.ts index c68aec4ad..ae107058b 100644 --- a/packages/builders/src/interactions/slashCommands/mixins/ApplicationCommandNumericOptionMinMaxValueMixin.ts +++ b/packages/builders/src/interactions/slashCommands/mixins/ApplicationCommandNumericOptionMinMaxValueMixin.ts @@ -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; } diff --git a/packages/builders/src/interactions/slashCommands/mixins/ApplicationCommandOptionBase.ts b/packages/builders/src/interactions/slashCommands/mixins/ApplicationCommandOptionBase.ts index ecefc88ca..beba4af33 100644 --- a/packages/builders/src/interactions/slashCommands/mixins/ApplicationCommandOptionBase.ts +++ b/packages/builders/src/interactions/slashCommands/mixins/ApplicationCommandOptionBase.ts @@ -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 diff --git a/packages/builders/src/interactions/slashCommands/mixins/ApplicationCommandOptionChannelTypesMixin.ts b/packages/builders/src/interactions/slashCommands/mixins/ApplicationCommandOptionChannelTypesMixin.ts index 78643eba9..847b7a844 100644 --- a/packages/builders/src/interactions/slashCommands/mixins/ApplicationCommandOptionChannelTypesMixin.ts +++ b/packages/builders/src/interactions/slashCommands/mixins/ApplicationCommandOptionChannelTypesMixin.ts @@ -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) { diff --git a/packages/builders/src/interactions/slashCommands/mixins/ApplicationCommandOptionWithChoicesAndAutocompleteMixin.ts b/packages/builders/src/interactions/slashCommands/mixins/ApplicationCommandOptionWithChoicesAndAutocompleteMixin.ts index 43f1137f7..76a2dcb40 100644 --- a/packages/builders/src/interactions/slashCommands/mixins/ApplicationCommandOptionWithChoicesAndAutocompleteMixin.ts +++ b/packages/builders/src/interactions/slashCommands/mixins/ApplicationCommandOptionWithChoicesAndAutocompleteMixin.ts @@ -21,7 +21,7 @@ export class ApplicationCommandOptionWithChoicesAndAutocompleteMixin[]): this { if (choices.length > 0 && this.autocomplete) { @@ -65,7 +65,7 @@ export class ApplicationCommandOptionWithChoicesAndAutocompleteMixin { /** * 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 { /** * 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 { /** * 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 { /** * 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 { /** * 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 { /** * 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 { /** * 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 { /** * 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 { /** * 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: diff --git a/packages/builders/src/messages/embed/UnsafeEmbed.ts b/packages/builders/src/messages/embed/UnsafeEmbed.ts index 1e68d0f9b..f2ef5de34 100644 --- a/packages/builders/src/messages/embed/UnsafeEmbed.ts +++ b/packages/builders/src/messages/embed/UnsafeEmbed.ts @@ -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): 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) { 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; diff --git a/packages/builders/src/messages/formatters.ts b/packages/builders/src/messages/formatters.ts index 0a81f3a58..4b3b3fdad 100644 --- a/packages/builders/src/messages/formatters.ts +++ b/packages/builders/src/messages/formatters.ts @@ -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(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(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(content: C): `\`${C}\`` { return `\`${content}\``; @@ -31,7 +31,7 @@ export function inlineCode(content: C): `\`${C}\`` { /** * Formats the content into italic text * - * @param content The content to wrap + * @param content - The content to wrap */ export function italic(content: C): `_${C}_` { return `_${content}_`; @@ -40,7 +40,7 @@ export function italic(content: C): `_${C}_` { /** * Formats the content into bold text * - * @param content The content to wrap + * @param content - The content to wrap */ export function bold(content: C): `**${C}**` { return `**${content}**`; @@ -49,7 +49,7 @@ export function bold(content: C): `**${C}**` { /** * Formats the content into underscored text * - * @param content The content to wrap + * @param content - The content to wrap */ export function underscore(content: C): `__${C}__` { return `__${content}__`; @@ -58,7 +58,7 @@ export function underscore(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(content: C): `~~${C}~~` { return `~~${content}~~`; @@ -67,7 +67,7 @@ export function strikethrough(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(content: C): `> ${C}` { return `> ${content}`; @@ -76,7 +76,7 @@ export function quote(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(content: C): `>>> ${C}` { return `>>> ${content}`; @@ -85,14 +85,14 @@ export function blockQuote(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(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(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(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( content: C, @@ -132,9 +132,9 @@ export function hyperlink( /** * 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( 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(content: C): `||${C}||` { return `||${content}||`; @@ -158,7 +158,7 @@ export function spoiler(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(userId: C): `<@${C}>` { return `<@${userId}>`; @@ -167,7 +167,7 @@ export function userMention(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(channelId: C): `<#${C}>` { return `<#${channelId}>`; @@ -176,7 +176,7 @@ export function channelMention(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(roleId: C): `<@&${C}>` { return `<@&${roleId}>`; @@ -185,23 +185,23 @@ export function roleMention(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(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(emojiId: C, animated?: true): ``; /** * 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(emojiId: C, animated = false): `` | `<:_:${C}>` { return `<${animated ? 'a' : ''}:_:${emojiId}>`; @@ -210,30 +210,30 @@ export function formatEmoji(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): ``; /** * 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(date: Date, style: 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(seconds: 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(seconds: C, style: S): ``; export function time(timeOrSeconds?: number | Date, style?: TimestampStylesString): string { diff --git a/packages/builders/src/util/equatable.ts b/packages/builders/src/util/equatable.ts index 98a92af45..af1c6e665 100644 --- a/packages/builders/src/util/equatable.ts +++ b/packages/builders/src/util/equatable.ts @@ -7,7 +7,7 @@ export interface Equatable { /** * 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 { return maybeEquatable !== null && typeof maybeEquatable === 'object' && 'equals' in maybeEquatable; diff --git a/packages/builders/src/util/jsonEncodable.ts b/packages/builders/src/util/jsonEncodable.ts index 78f422dd7..8e8273c38 100644 --- a/packages/builders/src/util/jsonEncodable.ts +++ b/packages/builders/src/util/jsonEncodable.ts @@ -7,7 +7,7 @@ export interface JSONEncodable { /** * 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 { return maybeEncodable !== null && typeof maybeEncodable === 'object' && 'toJSON' in maybeEncodable; diff --git a/packages/collection/api-extractor.json b/packages/collection/api-extractor.json new file mode 100644 index 000000000..3845fd481 --- /dev/null +++ b/packages/collection/api-extractor.json @@ -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 "" 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 "", 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: + * DEFAULT VALUE: "" + */ + // "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 "". + * + * SUPPORTED TOKENS: , , + */ + "mainEntryPointFilePath": "/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 "". + * + * Note: This setting will be ignored if "overrideTsconfig" is used. + * + * SUPPORTED TOKENS: , , + * DEFAULT VALUE: "/tsconfig.json" + */ + // "tsconfigFilePath": "/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: , + * DEFAULT VALUE: ".api.md" + */ + // "reportFileName": ".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 "". + * + * SUPPORTED TOKENS: , , + * DEFAULT VALUE: "/temp/" + */ + // "reportFolder": "/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 "". + * + * SUPPORTED TOKENS: , , + * DEFAULT VALUE: "/temp/" + */ + // "reportTempFolder": "/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 "". + * + * SUPPORTED TOKENS: , , + * DEFAULT VALUE: "/temp/.api.json" + */ + "apiJsonFilePath": "/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 "". + * + * SUPPORTED TOKENS: , , + * DEFAULT VALUE: "/dist/.d.ts" + */ + // "untrimmedFilePath": "/dist/.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 "". + * + * SUPPORTED TOKENS: , , + * DEFAULT VALUE: "" + */ + // "alphaTrimmedFilePath": "/dist/-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 "". + * + * SUPPORTED TOKENS: , , + * DEFAULT VALUE: "" + */ + // "betaTrimmedFilePath": "/dist/-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 "". + * + * SUPPORTED TOKENS: , , + * DEFAULT VALUE: "" + */ + // "publicTrimmedFilePath": "/dist/-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 "". + * + * The default value is "", 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: , , + * DEFAULT VALUE: "" + */ + // "tsdocMetadataFilePath": "/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 + // }, + // + // . . . + } + } +} diff --git a/packages/collection/package.json b/packages/collection/package.json index 996904a72..ce29541bc 100644 --- a/packages/collection/package.json +++ b/packages/collection/package.json @@ -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", diff --git a/packages/collection/src/index.ts b/packages/collection/src/index.ts index 1f5380d0d..8a6aaea6a 100644 --- a/packages/collection/src/index.ts +++ b/packages/collection/src/index.ts @@ -33,8 +33,8 @@ export class Collection extends Map { /** * 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 extends Map { /** * 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 extends Map { /** * 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 extends Map { /** * 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 extends Map { /** * 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 extends Map { * 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 extends Map { * 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 extends Map { /** * 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 extends Map { /** * 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 extends Map { * should use the `get` method. See * [MDN](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map/get) for details. * - * @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 extends Map { * [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 extends Map { /** * 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 extends Map { * [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 extends Map { * 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 extends Map { * 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 extends Map { * 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 extends Map { * 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 extends Map { * 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 extends Map { * 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 extends Map { * 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 extends Map { * [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 extends Map { /** * 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 extends Map { /** * 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 extends Map { * 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 extends Map { * 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 extends Map { /** * 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(other: ReadonlyCollection): Collection { const coll = new this.constructor[Symbol.species](); @@ -665,7 +665,7 @@ export class Collection extends Map { /** * 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(other: ReadonlyCollection): Collection { const coll = new this.constructor[Symbol.species](); @@ -680,10 +680,10 @@ export class Collection extends Map { /** * 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 extends Map { * 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 extends Map { /** * 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); diff --git a/packages/proxy/api-extractor.json b/packages/proxy/api-extractor.json new file mode 100644 index 000000000..3845fd481 --- /dev/null +++ b/packages/proxy/api-extractor.json @@ -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 "" 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 "", 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: + * DEFAULT VALUE: "" + */ + // "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 "". + * + * SUPPORTED TOKENS: , , + */ + "mainEntryPointFilePath": "/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 "". + * + * Note: This setting will be ignored if "overrideTsconfig" is used. + * + * SUPPORTED TOKENS: , , + * DEFAULT VALUE: "/tsconfig.json" + */ + // "tsconfigFilePath": "/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: , + * DEFAULT VALUE: ".api.md" + */ + // "reportFileName": ".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 "". + * + * SUPPORTED TOKENS: , , + * DEFAULT VALUE: "/temp/" + */ + // "reportFolder": "/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 "". + * + * SUPPORTED TOKENS: , , + * DEFAULT VALUE: "/temp/" + */ + // "reportTempFolder": "/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 "". + * + * SUPPORTED TOKENS: , , + * DEFAULT VALUE: "/temp/.api.json" + */ + "apiJsonFilePath": "/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 "". + * + * SUPPORTED TOKENS: , , + * DEFAULT VALUE: "/dist/.d.ts" + */ + // "untrimmedFilePath": "/dist/.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 "". + * + * SUPPORTED TOKENS: , , + * DEFAULT VALUE: "" + */ + // "alphaTrimmedFilePath": "/dist/-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 "". + * + * SUPPORTED TOKENS: , , + * DEFAULT VALUE: "" + */ + // "betaTrimmedFilePath": "/dist/-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 "". + * + * SUPPORTED TOKENS: , , + * DEFAULT VALUE: "" + */ + // "publicTrimmedFilePath": "/dist/-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 "". + * + * The default value is "", 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: , , + * DEFAULT VALUE: "" + */ + // "tsdocMetadataFilePath": "/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 + // }, + // + // . . . + } + } +} diff --git a/packages/proxy/package.json b/packages/proxy/package.json index 75a2cf223..37582b168 100644 --- a/packages/proxy/package.json +++ b/packages/proxy/package.json @@ -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", diff --git a/packages/proxy/src/handlers/proxyRequests.ts b/packages/proxy/src/handlers/proxyRequests.ts index b617c1fd6..e5f5afd53 100644 --- a/packages/proxy/src/handlers/proxyRequests.ts +++ b/packages/proxy/src/handlers/proxyRequests.ts @@ -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) => { diff --git a/packages/proxy/src/util/responseHelpers.ts b/packages/proxy/src/util/responseHelpers.ts index 3ee294afd..638ed92a9 100644 --- a/packages/proxy/src/util/responseHelpers.ts +++ b/packages/proxy/src/util/responseHelpers.ts @@ -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 { 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; diff --git a/packages/proxy/src/util/util.ts b/packages/proxy/src/util/util.ts index 41ae5f92e..79e06a9ee 100644 --- a/packages/proxy/src/util/util.ts +++ b/packages/proxy/src/util/util.ts @@ -4,6 +4,7 @@ import type { IncomingMessage, ServerResponse } from 'node:http'; * Represents a potentially awaitable value */ export type Awaitable = T | PromiseLike; + /** * Represents a simple HTTP request handler */ diff --git a/packages/rest/api-extractor.json b/packages/rest/api-extractor.json new file mode 100644 index 000000000..3845fd481 --- /dev/null +++ b/packages/rest/api-extractor.json @@ -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 "" 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 "", 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: + * DEFAULT VALUE: "" + */ + // "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 "". + * + * SUPPORTED TOKENS: , , + */ + "mainEntryPointFilePath": "/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 "". + * + * Note: This setting will be ignored if "overrideTsconfig" is used. + * + * SUPPORTED TOKENS: , , + * DEFAULT VALUE: "/tsconfig.json" + */ + // "tsconfigFilePath": "/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: , + * DEFAULT VALUE: ".api.md" + */ + // "reportFileName": ".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 "". + * + * SUPPORTED TOKENS: , , + * DEFAULT VALUE: "/temp/" + */ + // "reportFolder": "/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 "". + * + * SUPPORTED TOKENS: , , + * DEFAULT VALUE: "/temp/" + */ + // "reportTempFolder": "/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 "". + * + * SUPPORTED TOKENS: , , + * DEFAULT VALUE: "/temp/.api.json" + */ + "apiJsonFilePath": "/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 "". + * + * SUPPORTED TOKENS: , , + * DEFAULT VALUE: "/dist/.d.ts" + */ + // "untrimmedFilePath": "/dist/.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 "". + * + * SUPPORTED TOKENS: , , + * DEFAULT VALUE: "" + */ + // "alphaTrimmedFilePath": "/dist/-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 "". + * + * SUPPORTED TOKENS: , , + * DEFAULT VALUE: "" + */ + // "betaTrimmedFilePath": "/dist/-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 "". + * + * SUPPORTED TOKENS: , , + * DEFAULT VALUE: "" + */ + // "publicTrimmedFilePath": "/dist/-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 "". + * + * The default value is "", 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: , , + * DEFAULT VALUE: "" + */ + // "tsdocMetadataFilePath": "/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 + // }, + // + // . . . + } + } +} diff --git a/packages/rest/package.json b/packages/rest/package.json index 4c3d71a44..be8f420e3 100644 --- a/packages/rest/package.json +++ b/packages/rest/package.json @@ -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", diff --git a/packages/rest/src/lib/CDN.ts b/packages/rest/src/lib/CDN.ts index e28fdbeb6..3f03c1aa5 100644 --- a/packages/rest/src/lib/CDN.ts +++ b/packages/rest/src/lib/CDN.ts @@ -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): 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): 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): 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): 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): 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): 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): 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): 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): 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): 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): 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, diff --git a/packages/rest/src/lib/REST.ts b/packages/rest/src/lib/REST.ts index a045641cd..d7ffadd26 100644 --- a/packages/rest/src/lib/REST.ts +++ b/packages/rest/src/lib/REST.ts @@ -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; /** * 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); diff --git a/packages/rest/src/lib/RequestManager.ts b/packages/rest/src/lib/RequestManager.ts index 1bd10f016..fb2e8df2f 100644 --- a/packages/rest/src/lib/RequestManager.ts +++ b/packages/rest/src/lib/RequestManager.ts @@ -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 { @@ -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 { diff --git a/packages/rest/src/lib/errors/DiscordAPIError.ts b/packages/rest/src/lib/errors/DiscordAPIError.ts index e8a9caca1..395516a84 100644 --- a/packages/rest/src/lib/errors/DiscordAPIError.ts +++ b/packages/rest/src/lib/errors/DiscordAPIError.ts @@ -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, diff --git a/packages/rest/src/lib/errors/HTTPError.ts b/packages/rest/src/lib/errors/HTTPError.ts index a7653dfa5..b356bd191 100644 --- a/packages/rest/src/lib/errors/HTTPError.ts +++ b/packages/rest/src/lib/errors/HTTPError.ts @@ -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, diff --git a/packages/rest/src/lib/handlers/SequentialHandler.ts b/packages/rest/src/lib/handlers/SequentialHandler.ts index f6de02fe6..c7afe833d 100644 --- a/packages/rest/src/lib/handlers/SequentialHandler.ts +++ b/packages/rest/src/lib/handlers/SequentialHandler.ts @@ -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 { 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, diff --git a/packages/rest/src/lib/utils/utils.ts b/packages/rest/src/lib/utils/utils.ts index 3b3778705..1b437ecd3 100644 --- a/packages/rest/src/lib/utils/utils.ts +++ b/packages/rest/src/lib/utils/utils.ts @@ -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) { @@ -57,7 +59,8 @@ export function makeURLSearchParams(options?: Record) { /** * Converts the response to usable data - * @param res The fetch response + * + * @param res - The fetch response */ export function parseResponse(res: Dispatcher.ResponseData): Promise { const header = parseHeader(res.headers['content-type']); @@ -70,9 +73,11 @@ export function parseResponse(res: Dispatcher.ResponseData): Promise { /** * 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 { diff --git a/packages/voice/api-extractor.json b/packages/voice/api-extractor.json new file mode 100644 index 000000000..3845fd481 --- /dev/null +++ b/packages/voice/api-extractor.json @@ -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 "" 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 "", 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: + * DEFAULT VALUE: "" + */ + // "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 "". + * + * SUPPORTED TOKENS: , , + */ + "mainEntryPointFilePath": "/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 "". + * + * Note: This setting will be ignored if "overrideTsconfig" is used. + * + * SUPPORTED TOKENS: , , + * DEFAULT VALUE: "/tsconfig.json" + */ + // "tsconfigFilePath": "/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: , + * DEFAULT VALUE: ".api.md" + */ + // "reportFileName": ".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 "". + * + * SUPPORTED TOKENS: , , + * DEFAULT VALUE: "/temp/" + */ + // "reportFolder": "/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 "". + * + * SUPPORTED TOKENS: , , + * DEFAULT VALUE: "/temp/" + */ + // "reportTempFolder": "/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 "". + * + * SUPPORTED TOKENS: , , + * DEFAULT VALUE: "/temp/.api.json" + */ + "apiJsonFilePath": "/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 "". + * + * SUPPORTED TOKENS: , , + * DEFAULT VALUE: "/dist/.d.ts" + */ + // "untrimmedFilePath": "/dist/.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 "". + * + * SUPPORTED TOKENS: , , + * DEFAULT VALUE: "" + */ + // "alphaTrimmedFilePath": "/dist/-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 "". + * + * SUPPORTED TOKENS: , , + * DEFAULT VALUE: "" + */ + // "betaTrimmedFilePath": "/dist/-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 "". + * + * SUPPORTED TOKENS: , , + * DEFAULT VALUE: "" + */ + // "publicTrimmedFilePath": "/dist/-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 "". + * + * The default value is "", 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: , , + * DEFAULT VALUE: "" + */ + // "tsdocMetadataFilePath": "/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 + // }, + // + // . . . + } + } +} diff --git a/packages/voice/package.json b/packages/voice/package.json index bbd6240dd..096886284 100644 --- a/packages/voice/package.json +++ b/packages/voice/package.json @@ -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", diff --git a/packages/voice/src/networking/VoiceUDPSocket.ts b/packages/voice/src/networking/VoiceUDPSocket.ts index d42d962ee..070422b91 100644 --- a/packages/voice/src/networking/VoiceUDPSocket.ts +++ b/packages/voice/src/networking/VoiceUDPSocket.ts @@ -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 diff --git a/packages/voice/src/receive/SSRCMap.ts b/packages/voice/src/receive/SSRCMap.ts index 4933e4fa3..1bf8e3630 100644 --- a/packages/voice/src/receive/SSRCMap.ts +++ b/packages/voice/src/receive/SSRCMap.ts @@ -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 */ diff --git a/packages/voice/src/receive/VoiceReceiver.ts b/packages/voice/src/receive/VoiceReceiver.ts index 1d1b5b9fe..b06e2c785 100644 --- a/packages/voice/src/receive/VoiceReceiver.ts +++ b/packages/voice/src/receive/VoiceReceiver.ts @@ -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 */ diff --git a/packages/voice/src/util/demuxProbe.ts b/packages/voice/src/util/demuxProbe.ts index 8b496a776..3607e51aa 100644 --- a/packages/voice/src/util/demuxProbe.ts +++ b/packages/voice/src/util/demuxProbe.ts @@ -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 */ diff --git a/yarn.lock b/yarn.lock index 6fdda4a25..3175b9527 100644 --- a/yarn.lock +++ b/yarn.lock @@ -1826,6 +1826,7 @@ __metadata: "@discordjs/docgen": "workspace:^" "@discordjs/scripts": "workspace:^" "@favware/cliff-jumper": ^1.8.3 + "@microsoft/api-extractor": ^7.28.2 "@sapphire/shapeshift": ^3.2.0 "@types/node": ^18.0.0 discord-api-types: ^0.33.5 @@ -1853,6 +1854,7 @@ __metadata: "@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 @@ -1931,6 +1933,7 @@ __metadata: "@discordjs/rest": ^0.5.0 "@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 @@ -1965,6 +1968,7 @@ __metadata: "@discordjs/docgen": "workspace:^" "@discordjs/scripts": "workspace:^" "@favware/cliff-jumper": ^1.8.3 + "@microsoft/api-extractor": ^7.28.2 "@sapphire/async-queue": ^1.3.1 "@sapphire/snowflake": ^3.2.2 discord-api-types: ^0.33.5 @@ -2001,6 +2005,7 @@ __metadata: "@discordjs/docgen": "workspace:^" "@discordjs/scripts": "workspace:^" "@favware/cliff-jumper": ^1.8.3 + "@microsoft/api-extractor": ^7.28.2 "@types/jest": ^28.1.2 "@types/ws": ^8.5.3 discord-api-types: ^0.33.5 @@ -2508,6 +2513,58 @@ __metadata: languageName: node linkType: hard +"@microsoft/api-extractor-model@npm:7.21.0": + version: 7.21.0 + resolution: "@microsoft/api-extractor-model@npm:7.21.0" + dependencies: + "@microsoft/tsdoc": 0.14.1 + "@microsoft/tsdoc-config": ~0.16.1 + "@rushstack/node-core-library": 3.49.0 + checksum: 9e0cb0cd2d344ee23f32294103856e413fd998ceefc5ea26427b603ef7a6dc155ff6710bf3a30d0c426b9928118e8f56e080f0c0aa9685f3e825e7e154340f62 + languageName: node + linkType: hard + +"@microsoft/api-extractor@npm:^7.28.2": + version: 7.28.2 + resolution: "@microsoft/api-extractor@npm:7.28.2" + dependencies: + "@microsoft/api-extractor-model": 7.21.0 + "@microsoft/tsdoc": 0.14.1 + "@microsoft/tsdoc-config": ~0.16.1 + "@rushstack/node-core-library": 3.49.0 + "@rushstack/rig-package": 0.3.13 + "@rushstack/ts-command-line": 4.12.1 + colors: ~1.2.1 + lodash: ~4.17.15 + resolve: ~1.17.0 + semver: ~7.3.0 + source-map: ~0.6.1 + typescript: ~4.6.3 + bin: + api-extractor: bin/api-extractor + checksum: ba32ce0c8466c09f43d65a32bf57046a7d36216781851bcab339b99b094c66e9beba209b714a9fda41c524e9372aeb686293a0dddb927f71d478f7d3df574861 + languageName: node + linkType: hard + +"@microsoft/tsdoc-config@npm:~0.16.1": + version: 0.16.1 + resolution: "@microsoft/tsdoc-config@npm:0.16.1" + dependencies: + "@microsoft/tsdoc": 0.14.1 + ajv: ~6.12.6 + jju: ~1.4.0 + resolve: ~1.19.0 + checksum: 2b2121803caf6584fe0264ad16f8fa10de68438c0b82bd25f918606052af5312050f38b6abd4bcf3d40f120713aab144762a7a280fa22dd12e5571cd08e348e1 + languageName: node + linkType: hard + +"@microsoft/tsdoc@npm:0.14.1": + version: 0.14.1 + resolution: "@microsoft/tsdoc@npm:0.14.1" + checksum: e4ad038ccff2cd96e0d53ee42e2136f0f5a925b16cfda14261f1c2eb55ba0088a0e3b08ff819b476ddc69b2242a391925fab7f6ae2afabb19b96f87e19c114fc + languageName: node + linkType: hard + "@mswjs/cookies@npm:^0.2.0": version: 0.2.1 resolution: "@mswjs/cookies@npm:0.2.1" @@ -2818,6 +2875,45 @@ __metadata: languageName: node linkType: hard +"@rushstack/node-core-library@npm:3.49.0": + version: 3.49.0 + resolution: "@rushstack/node-core-library@npm:3.49.0" + dependencies: + "@types/node": 12.20.24 + colors: ~1.2.1 + fs-extra: ~7.0.1 + import-lazy: ~4.0.0 + jju: ~1.4.0 + resolve: ~1.17.0 + semver: ~7.3.0 + timsort: ~0.3.0 + z-schema: ~5.0.2 + checksum: 6ac8247a466faebc242cf8ca6a9960d78dee305482358cca15e9a9ba22f775c18d4f857a9dfcad4c03853d4a6fde768d142a794b6af2baa6aecd5f8faee989a2 + languageName: node + linkType: hard + +"@rushstack/rig-package@npm:0.3.13": + version: 0.3.13 + resolution: "@rushstack/rig-package@npm:0.3.13" + dependencies: + resolve: ~1.17.0 + strip-json-comments: ~3.1.1 + checksum: 98c0b7dbefe6ae169745d065d696fbef5d07e71bae5146e070a2e37de82c5625752865c54f12bba6b002868fcb27a1d2d098a19b0a5d20a1dfacaa002c81c13d + languageName: node + linkType: hard + +"@rushstack/ts-command-line@npm:4.12.1": + version: 4.12.1 + resolution: "@rushstack/ts-command-line@npm:4.12.1" + dependencies: + "@types/argparse": 1.0.38 + argparse: ~1.0.9 + colors: ~1.2.1 + string-argv: ~0.3.1 + checksum: e9479bd001f4f206d207c867ec7b91444727cf8a1c685dac7589c6a33b54f47200deabc450d6831a1cc38501f0322eb7003c1f78f1fa43230541c4b7ddc4718d + languageName: node + linkType: hard + "@sapphire/async-queue@npm:^1.3.1": version: 1.3.1 resolution: "@sapphire/async-queue@npm:1.3.1" @@ -3032,6 +3128,13 @@ __metadata: languageName: node linkType: hard +"@types/argparse@npm:1.0.38": + version: 1.0.38 + resolution: "@types/argparse@npm:1.0.38" + checksum: 26ed7e3f1e3595efdb883a852f5205f971b798e4c28b7e30a32c5298eee596e8b45834ce831f014d250b9730819ab05acff5b31229666d3af4ba465b4697d0eb + languageName: node + linkType: hard + "@types/aria-query@npm:^4.2.0": version: 4.2.2 resolution: "@types/aria-query@npm:4.2.2" @@ -3374,6 +3477,13 @@ __metadata: languageName: node linkType: hard +"@types/node@npm:12.20.24": + version: 12.20.24 + resolution: "@types/node@npm:12.20.24" + checksum: e7a13460e2f5b0b5a32c0f3af7daf1a05201552a66d542d3cc3b1ea8b52d4730250f9eb1961d755e31cfe5d03c78340911a6242657a0a9a17d6f7e341fc9f366 + languageName: node + linkType: hard + "@types/node@npm:>=12": version: 17.0.17 resolution: "@types/node@npm:17.0.17" @@ -4173,7 +4283,7 @@ __metadata: languageName: node linkType: hard -"ajv@npm:^6.10.0, ajv@npm:^6.12.3, ajv@npm:^6.12.4, ajv@npm:^6.12.6": +"ajv@npm:^6.10.0, ajv@npm:^6.12.3, ajv@npm:^6.12.4, ajv@npm:^6.12.6, ajv@npm:~6.12.6": version: 6.12.6 resolution: "ajv@npm:6.12.6" dependencies: @@ -4321,7 +4431,7 @@ __metadata: languageName: node linkType: hard -"argparse@npm:^1.0.7": +"argparse@npm:^1.0.7, argparse@npm:~1.0.9": version: 1.0.10 resolution: "argparse@npm:1.0.10" dependencies: @@ -5627,6 +5737,13 @@ __metadata: languageName: node linkType: hard +"colors@npm:~1.2.1": + version: 1.2.5 + resolution: "colors@npm:1.2.5" + checksum: b6e23de735f68b72d5cdf6fd854ca43d1b66d82dcf54bda0b788083b910164a040f2c4edf23c670d36a7a2d8f1b7d6e62e3292703e4642691e6ccaa1c62d8f74 + languageName: node + linkType: hard + "combined-stream@npm:^1.0.6, combined-stream@npm:^1.0.8, combined-stream@npm:~1.0.6": version: 1.0.8 resolution: "combined-stream@npm:1.0.8" @@ -5687,7 +5804,7 @@ __metadata: languageName: node linkType: hard -"commander@npm:^2.12.1": +"commander@npm:^2.12.1, commander@npm:^2.20.3": version: 2.20.3 resolution: "commander@npm:2.20.3" checksum: ab8c07884e42c3a8dbc5dd9592c606176c7eb5c1ca5ff274bcf907039b2c41de3626f684ea75ccf4d361ba004bbaff1f577d5384c155f3871e456bdf27becf9e @@ -8743,6 +8860,17 @@ dts-critic@latest: languageName: node linkType: hard +"fs-extra@npm:~7.0.1": + version: 7.0.1 + resolution: "fs-extra@npm:7.0.1" + dependencies: + graceful-fs: ^4.1.2 + jsonfile: ^4.0.0 + universalify: ^0.1.0 + checksum: 141b9dccb23b66a66cefdd81f4cda959ff89282b1d721b98cea19ba08db3dcbe6f862f28841f3cf24bb299e0b7e6c42303908f65093cb7e201708e86ea5a8dcf + languageName: node + linkType: hard + "fs-minipass@npm:^2.0.0": version: 2.1.0 resolution: "fs-minipass@npm:2.1.0" @@ -9703,6 +9831,13 @@ dts-critic@latest: languageName: node linkType: hard +"import-lazy@npm:~4.0.0": + version: 4.0.0 + resolution: "import-lazy@npm:4.0.0" + checksum: 22f5e51702134aef78890156738454f620e5fe7044b204ebc057c614888a1dd6fdf2ede0fdcca44d5c173fd64f65c985f19a51775b06967ef58cc3d26898df07 + languageName: node + linkType: hard + "import-local@npm:^3.0.2": version: 3.1.0 resolution: "import-local@npm:3.1.0" @@ -9941,6 +10076,15 @@ dts-critic@latest: languageName: node linkType: hard +"is-core-module@npm:^2.1.0": + version: 2.9.0 + resolution: "is-core-module@npm:2.9.0" + dependencies: + has: ^1.0.3 + checksum: b27034318b4b462f1c8f1dfb1b32baecd651d891a4e2d1922135daeff4141dfced2b82b07aef83ef54275c4a3526aa38da859223664d0868ca24182badb784ce + languageName: node + linkType: hard + "is-core-module@npm:^2.2.0, is-core-module@npm:^2.5.0": version: 2.8.0 resolution: "is-core-module@npm:2.8.0" @@ -10923,6 +11067,13 @@ dts-critic@latest: languageName: node linkType: hard +"jju@npm:~1.4.0": + version: 1.4.0 + resolution: "jju@npm:1.4.0" + checksum: 3790481bd2b7827dd6336e6e3dc2dcc6d425679ba7ebde7b679f61dceb4457ea0cda330972494de608571f4973c6dfb5f70fab6f3c5037dbab19ac449a60424f + languageName: node + linkType: hard + "joycon@npm:^3.0.1": version: 3.1.1 resolution: "joycon@npm:3.1.1" @@ -11506,6 +11657,20 @@ dts-critic@latest: languageName: node linkType: hard +"lodash.get@npm:^4.4.2": + version: 4.4.2 + resolution: "lodash.get@npm:4.4.2" + checksum: e403047ddb03181c9d0e92df9556570e2b67e0f0a930fcbbbd779370972368f5568e914f913e93f3b08f6d492abc71e14d4e9b7a18916c31fa04bd2306efe545 + languageName: node + linkType: hard + +"lodash.isequal@npm:^4.5.0": + version: 4.5.0 + resolution: "lodash.isequal@npm:4.5.0" + checksum: da27515dc5230eb1140ba65ff8de3613649620e8656b19a6270afe4866b7bd461d9ba2ac8a48dcc57f7adac4ee80e1de9f965d89d4d81a0ad52bb3eec2609644 + languageName: node + linkType: hard + "lodash.ismatch@npm:^4.4.0": version: 4.4.0 resolution: "lodash.ismatch@npm:4.4.0" @@ -11562,7 +11727,7 @@ dts-critic@latest: languageName: node linkType: hard -"lodash@npm:^4.17.14, lodash@npm:^4.17.15, lodash@npm:^4.17.19, lodash@npm:^4.17.21": +"lodash@npm:^4.17.14, lodash@npm:^4.17.15, lodash@npm:^4.17.19, lodash@npm:^4.17.21, lodash@npm:~4.17.15": version: 4.17.21 resolution: "lodash@npm:4.17.21" checksum: eb835a2e51d381e561e508ce932ea50a8e5a68f4ebdd771ea240d3048244a8d13658acbd502cd4829768c56f2e16bdd4340b9ea141297d472517b83868e677f7 @@ -14556,6 +14721,25 @@ dts-critic@latest: languageName: node linkType: hard +"resolve@npm:~1.17.0": + version: 1.17.0 + resolution: "resolve@npm:1.17.0" + dependencies: + path-parse: ^1.0.6 + checksum: 9ceaf83b3429f2d7ff5d0281b8d8f18a1f05b6ca86efea7633e76b8f76547f33800799dfdd24434942dec4fbd9e651ed3aef577d9a6b5ec87ad89c1060e24759 + languageName: node + linkType: hard + +"resolve@npm:~1.19.0": + version: 1.19.0 + resolution: "resolve@npm:1.19.0" + dependencies: + is-core-module: ^2.1.0 + path-parse: ^1.0.6 + checksum: a05b356e47b85ad3613d9e2a39a824f3c27f4fcad9c9ff6c7cc71a2e314c5904a90ab37481ad0069d03cab9eaaac6eb68aca1bc3355fdb05f1045cd50e2aacea + languageName: node + linkType: hard + "resolve@patch:resolve@^1.10.0#~builtin, resolve@patch:resolve@^1.20.0#~builtin, resolve@patch:resolve@^1.3.2#~builtin": version: 1.20.0 resolution: "resolve@patch:resolve@npm%3A1.20.0#~builtin::version=1.20.0&hash=07638b" @@ -14589,6 +14773,25 @@ dts-critic@latest: languageName: node linkType: hard +"resolve@patch:resolve@~1.17.0#~builtin": + version: 1.17.0 + resolution: "resolve@patch:resolve@npm%3A1.17.0#~builtin::version=1.17.0&hash=07638b" + dependencies: + path-parse: ^1.0.6 + checksum: 6fd799f282ddf078c4bc20ce863e3af01fa8cb218f0658d9162c57161a2dbafe092b13015b9a4c58d0e1e801cf7aa7a4f13115fea9db98c3f9a0c43e429bad6f + languageName: node + linkType: hard + +"resolve@patch:resolve@~1.19.0#~builtin": + version: 1.19.0 + resolution: "resolve@patch:resolve@npm%3A1.19.0#~builtin::version=1.19.0&hash=07638b" + dependencies: + is-core-module: ^2.1.0 + path-parse: ^1.0.6 + checksum: 2443b94d347e6946c87c85faf13071f605e609e0b54784829b0ed2b917d050bfc1cbaf4ecc6453f224cfa7d0c5dcd97cbb273454cd210bee68e4af15c1a5abc9 + languageName: node + linkType: hard + "responselike@npm:^2.0.0": version: 2.0.0 resolution: "responselike@npm:2.0.0" @@ -14828,7 +15031,7 @@ dts-critic@latest: languageName: node linkType: hard -"semver@npm:7.3.7, semver@npm:^7.3.2, semver@npm:^7.3.7": +"semver@npm:7.3.7, semver@npm:^7.3.2, semver@npm:^7.3.7, semver@npm:~7.3.0": version: 7.3.7 resolution: "semver@npm:7.3.7" dependencies: @@ -15465,6 +15668,13 @@ dts-critic@latest: languageName: node linkType: hard +"string-argv@npm:~0.3.1": + version: 0.3.1 + resolution: "string-argv@npm:0.3.1" + checksum: efbd0289b599bee808ce80820dfe49c9635610715429c6b7cc50750f0437e3c2f697c81e5c390208c13b5d5d12d904a1546172a88579f6ee5cbaaaa4dc9ec5cf + languageName: node + linkType: hard + "string-length@npm:^4.0.1": version: 4.0.2 resolution: "string-length@npm:4.0.2" @@ -15638,7 +15848,7 @@ dts-critic@latest: languageName: node linkType: hard -"strip-json-comments@npm:^3.1.0, strip-json-comments@npm:^3.1.1": +"strip-json-comments@npm:^3.1.0, strip-json-comments@npm:^3.1.1, strip-json-comments@npm:~3.1.1": version: 3.1.1 resolution: "strip-json-comments@npm:3.1.1" checksum: 492f73e27268f9b1c122733f28ecb0e7e8d8a531a6662efbd08e22cccb3f9475e90a1b82cab06a392f6afae6d2de636f977e231296400d0ec5304ba70f166443 @@ -16016,6 +16226,13 @@ dts-critic@latest: languageName: node linkType: hard +"timsort@npm:~0.3.0": + version: 0.3.0 + resolution: "timsort@npm:0.3.0" + checksum: 1a66cb897dacabd7dd7c91b7e2301498ca9e224de2edb9e42d19f5b17c4b6dc62a8d4cbc64f28be82aaf1541cb5a78ab49aa818f42a2989ebe049a64af731e2a + languageName: node + linkType: hard + "tinypool@npm:^0.1.3": version: 0.1.3 resolution: "tinypool@npm:0.1.3" @@ -16691,6 +16908,16 @@ dts-critic@latest: languageName: node linkType: hard +"typescript@npm:~4.6.3": + version: 4.6.4 + resolution: "typescript@npm:4.6.4" + bin: + tsc: bin/tsc + tsserver: bin/tsserver + checksum: e7bfcc39cd4571a63a54e5ea21f16b8445268b9900bf55aee0e02ad981be576acc140eba24f1af5e3c1457767c96cea6d12861768fb386cf3ffb34013718631a + languageName: node + linkType: hard + "typescript@patch:typescript@^4.6.4#~builtin, typescript@patch:typescript@^4.7.3#~builtin": version: 4.7.3 resolution: "typescript@patch:typescript@npm%3A4.7.3#~builtin::version=4.7.3&hash=7ad353" @@ -16711,6 +16938,16 @@ dts-critic@latest: languageName: node linkType: hard +"typescript@patch:typescript@~4.6.3#~builtin": + version: 4.6.4 + resolution: "typescript@patch:typescript@npm%3A4.6.4#~builtin::version=4.6.4&hash=7ad353" + bin: + tsc: bin/tsc + tsserver: bin/tsserver + checksum: 1cb434fbc637d347be90e3a0c6cd05e33c38f941713c8786d3031faf1842c2c148ba91d2fac01e7276b0ae3249b8633f1660e32686cc7a8c6a8fd5361dc52c66 + languageName: node + linkType: hard + "typical@npm:^2.4.2, typical@npm:^2.6.0, typical@npm:^2.6.1": version: 2.6.1 resolution: "typical@npm:2.6.1" @@ -17182,6 +17419,13 @@ dts-critic@latest: languageName: node linkType: hard +"validator@npm:^13.7.0": + version: 13.7.0 + resolution: "validator@npm:13.7.0" + checksum: 2b83283de1222ca549a7ef57f46e8d49c6669213348db78b7045bce36a3b5843ff1e9f709ebf74574e06223461ee1f264f8cc9a26a0060a79a27de079d8286ef + languageName: node + linkType: hard + "vary@npm:~1.1.2": version: 1.1.2 resolution: "vary@npm:1.1.2" @@ -17763,6 +18007,23 @@ dts-critic@latest: languageName: node linkType: hard +"z-schema@npm:~5.0.2": + version: 5.0.3 + resolution: "z-schema@npm:5.0.3" + dependencies: + commander: ^2.20.3 + lodash.get: ^4.4.2 + lodash.isequal: ^4.5.0 + validator: ^13.7.0 + dependenciesMeta: + commander: + optional: true + bin: + z-schema: bin/z-schema + checksum: eb6c2c3c2878c4c333fd3755703616c8f846158da0154f60f81f188c3c4ce7ad5b8ff5ce570d6372d4803fb5c8c9d97b4e54becdd5a832b1a31240d149b87191 + languageName: node + linkType: hard + "zwitch@npm:^2.0.0": version: 2.0.2 resolution: "zwitch@npm:2.0.2"