chore(discord.js): release discord.js@14.25.0

* feat(GuildMemberManager): handle gateway request ratelimit

* fix: account for ws abstraction layer

* chore: yada yada

* refactor: use new error class

* fix: linter

---------

Co-authored-by: Jiralite <33201955+Jiralite@users.noreply.github.com>

.commitlintrc.json

@@ -1,10 +1,13 @@
 {
+	"$schema": "https://json.schemastore.org/commitlintrc.json",
 	"extends": ["@commitlint/config-angular"],
 	"rules": {
 		"type-enum": [
 			2,
 			"always",
-			["chore", "build", "ci", "docs", "feat", "fix", "perf", "refactor", "revert", "style", "test", "types", "typings"]
-		]
+			["chore", "build", "ci", "docs", "feat", "fix", "perf", "refactor", "revert", "style", "test", "types"]
+		],
+		"scope-case": [0],
+		"subject-exclamation-mark": [0]
 	}
 }

.dockerignore

@@ -0,0 +1,67 @@
+# Packages
+**/node_modules
+
+# Log files
+**/logs
+**/*.log
+**/npm-debug.log*
+
+# Runtime data
+**/pids
+**/*.pid
+**/*.seed
+
+# Env
+**/.env
+
+# Dist
+**/dist/
+**/dist-docs/
+
+# Miscellaneous
+**/.tmp
+**/.vscode
+**/.idea
+**/.DS_Store
+**/.turbo
+**/tsconfig.tsbuildinfo
+**/coverage
+**/__tests__
+**/out
+
+# yarn
+.pnp.*
+.yarn/*
+!.yarn/patches
+!.yarn/plugins
+!.yarn/releases
+!.yarn/sdks
+!.yarn/versions
+
+# Cache
+**/.prettiercache
+**/.eslintcache
+**/.vercel
+
+# Docker specific
+**/.cliff-jumperrc.json
+**/api-extractor.json
+**/api-extractor-docs.json
+**/.eslintignore
+**/.eslintrc.json
+**/.lintstagedrc.js
+**/.lintstagedrc.cjs
+**/.lintstagedrc.json
+**/.prettierignore
+**/.prettierrc.js
+**/.prettierrc.cjs
+**/.prettierrc.json
+**/cliff.toml
+**/CHANGELOG.md
+**/README.md
+**/LICENSE
+**/tsconfig.eslint.json
+**/tsconfig.docs.json
+**/docs/
+**/vitest.config.ts
+

.gitattributes

@@ -1 +1,2 @@
 * text=auto eol=lf
+pnpm-lock.yaml linguist-generated=true text=auto eol=lf

.github/.kodiak.toml

@@ -0,0 +1,11 @@
+version = 1
+
+[merge]
+require_automerge_label = false
+blocking_labels = ['blocked', 'in review']
+method = 'squash'
+
+[merge.message]
+title = 'pull_request_title'
+strip_html_comments = true
+include_coauthors = true

.github/CODEOWNERS

@@ -0,0 +1,24 @@
+# Learn how to add code owners here:
+# https://help.github.com/articles/about-code-owners
+
+* @iCrawl
+
+/packages/actions/ @discordjs/actions
+/packages/api-extractor-utils/ @discordjs/api-extractor-utils
+/packages/brokers/ @discordjs/brokers
+/packages/builders/ @discordjs/builders
+/packages/collection/ @discordjs/collection
+/packages/core/ @discordjs/core
+/packages/create-discord-bot/ @discordjs/guide
+/packages/discord.js/ @discordjs/core
+/packages/docgen/ @iCrawl
+/packages/formatters/ @discordjs/formatters
+/packages/next/ @discordjs/core
+/packages/proxy/ @discordjs/proxy
+/packages/proxy-container/ @discordjs/proxy
+/packages/rest/ @discordjs/rest
+/packages/scripts/ @discordjs/scripts
+/packages/ui/ @discordjs/ui
+/packages/util/ @discordjs/util
+/packages/voice/ @discordjs/core
+/packages/ws/ @discordjs/ws

.github/COMMIT_CONVENTION.md

@@ -7,7 +7,7 @@
 Messages must be matched by the following regex:
 
 ```js
-/^(revert: )?(feat|fix|docs|style|refactor|perf|test|workflow|build|ci|chore|types|wip)(\(.+\))?: .{1,72}/;
+/^(revert: )?(feat|fix|docs|style|refactor|perf|test|build|ci|chore|types)(\(.+\))?!?: .{1,72}/;
 ```
 
 #### Examples
@@ -15,13 +15,13 @@ Messages must be matched by the following regex:
 Appears under "Features" header, `GuildMember` subheader:
 
 ```
-feat(guildmember): add 'tag' method
+feat(GuildMember): add 'tag' method
 ```
 
 Appears under "Bug Fixes" header, `Guild` subheader, with a link to issue #28:
 
 ```
-fix(guild): handle events correctly
+fix(Guild): handle events correctly
 
 close #28
 ```
@@ -37,7 +37,7 @@ BREAKING CHANGE: The 'bar' option has been removed.
 The following commit and commit `667ecc1` do not appear in the changelog if they are under the same release. If not, the revert commit appears under the "Reverts" header.
 
 ```
-revert: feat(managers): add Managers
+revert: feat(Managers): add Managers
 
 This reverts commit 667ecc1654a317a13331b17617d973392f415f02.
 ```
@@ -55,6 +55,7 @@ A commit message consists of a **header**, **body** and **footer**. The header h
 ```
 
 The **header** is mandatory and the **scope** of the header is optional.
+If the commit contains **Breaking Changes**, a `!` can be added before the `:` as an indicator.
 
 ### Revert
 
@@ -68,7 +69,7 @@ Other prefixes are up to your discretion. Suggested prefixes are `docs`, `chore`
 
 ### Scope
 
-The scope could be anything specifying the place of the commit change. For example `GuildMember`, `Guild`, `Message`, `MessageEmbed` etc...
+The scope could be anything specifying the place of the commit change. For example `GuildMember`, `Guild`, `Message`, `TextChannel` etc...
 
 ### Subject
 

.github/CONTRIBUTING.md

@@ -11,7 +11,39 @@ is a great boon to your development process.
 To get ready to work on the codebase, please do the following:
 
 1. Fork & clone the repository, and make sure you're on the **main** branch
-2. Run `npm ci`
-3. Code your heart out!
-4. Run `npm test` to run ESLint and ensure any JSDoc changes are valid
-5. [Submit a pull request](https://github.com/discordjs/discord.js/compare) (Make sure you follow the [conventional commit format](https://github.com/discordjs/discord.js/blob/main/.github/COMMIT_CONVENTION.md))
+2. Run `pnpm install --frozen-lockfile` ([install](https://pnpm.io/installation))
+3. Run `pnpm run build` to build local packages
+4. Code your heart out!
+5. Run `pnpm run test` to run ESLint and ensure any JSDoc changes are valid
+6. [Submit a pull request](https://github.com/discordjs/discord.js/compare) (Make sure you follow the [conventional commit format](https://github.com/discordjs/discord.js/blob/main/.github/COMMIT_CONVENTION.md))
+
+## Testing changes locally
+
+If you want to test changes you've made locally, you can do so by using `pnpm link <package-you-want-to-link-to-your-current-package>`. This will create a symlink to your local copy of the discord.js libraries.
+
+1. Create a new directory `mkdir discordjs-test` and move into it `cd discordjs-test`
+2. Initialize a new pnpm project `pnpm init`
+3. Now link the discord.js package from the directory you cloned earlier `pnpm link {PATH_TO_DISCORDJS_REPO}/packages/<package>`. (e.g. `pnpm link ~/discord.js/packages/rest`)
+4. Import the package in your source code and test them out!
+
+### Working with TypeScript packages
+
+When testing local changes, you may notice you need to manually recompile TypeScript projects on every change in order to get the latest code changes to test locally.
+
+To avoid this you can use the `--watch` parameter in the package build script to automatically recompile the project when changes are detected.
+
+For example, to automatically recompile the `@discordjs/rest` project when changes are detected, run `pnpm turbo run build --filter='@discordjs/rest' -- --watch` in the root folder of where you cloned the discord.js repo.
+
+## Adding new packages
+
+If you'd like to create another package under the `@discordjs` organization run the following command:
+
+```sh
+pnpm run create-package <package-name> [package-description]
+```
+
+This will create new package directory under `packages/` with the required configuration files. You may begin
+to make changes within the `src/` directory. You may also need to:
+
+- Update workflows that utilize packages
+- Update the CODEOWNERS file

.github/ISSUE_TEMPLATE/01-package_bug_report.yml

@@ -0,0 +1,139 @@
+name: Bug report
+description: Report an issue with discord.js or another package.
+labels: [bug, need repro]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thank you for filing an issue! If you are here to ask a question, use Discord instead: https://discord.gg/djs
+
+        This issue form is for discord.js, including other packages.
+  - type: dropdown
+    id: package
+    attributes:
+      label: Which package is this bug report for?
+      options:
+        - discord.js
+        - brokers
+        - builders
+        - collection
+        - core
+        - create-discord-bot
+        - formatters
+        - next
+        - proxy
+        - proxy-container
+        - rest
+        - ui
+        - util
+        - voice
+        - ws
+    validations:
+      required: true
+  - type: textarea
+    id: description
+    attributes:
+      label: Issue description
+      description: Describe the issue in as much detail as possible.
+      placeholder: |
+        Steps to reproduce with below code sample:
+        1. Do thing
+        2. Do thing in Discord client
+        3. Observe behavior
+        4. See error logs below
+    validations:
+      required: true
+  - type: textarea
+    id: code_sample
+    attributes:
+      label: Code sample
+      description: |
+        Your code sample should be:
+        1. Minimal - Use as little code as possible that still produces the same problem (and is understandable)
+        2. Complete - Provide all parts someone else needs to reproduce your problem
+        3. Reproducible - Test the code you're about to provide to make sure it reproduces the problem
+
+        This will be automatically formatted into code, so no need for backticks.
+      render: typescript
+  - type: textarea
+    id: versions
+    attributes:
+      label: Versions
+      description: List necessary versions here. This includes your package version, runtime version, operating system etc.
+      placeholder: |
+        - discord.js 14.12.1 (`npm ls discord.js` or another package)
+        - Node.js 16.11.0 (`node --version`)
+        - TypeScript 5.1.6 (`npm ls typescript` if you use it)
+        - macOS Ventura 13.3.1
+    validations:
+      required: true
+  - type: dropdown
+    id: priority
+    attributes:
+      label: Issue priority
+      description: Please be realistic. If you need to elaborate on your reasoning, please use the issue description field above.
+      options:
+        - Low (slightly annoying)
+        - Medium (should be fixed soon)
+        - High (immediate attention needed)
+    validations:
+      required: true
+  - type: dropdown
+    id: partials
+    attributes:
+      label: Which partials do you have configured?
+      description: Check your `Client` constructor for the `partials` key.
+      options:
+        - Not applicable
+        - No Partials
+        - User
+        - Channel
+        - GuildMember
+        - Message
+        - Reaction
+        - GuildScheduledEvent
+        - ThreadMember
+      multiple: true
+    validations:
+      required: true
+  - type: dropdown
+    id: intents
+    attributes:
+      label: Which gateway intents are you subscribing to?
+      description: Check your `Client` constructor for the `intents` key.
+      options:
+        - Not applicable
+        - No Intents
+        - Guilds
+        - GuildMembers
+        - GuildModeration
+        - GuildEmojisAndStickers
+        - GuildIntegrations
+        - GuildWebhooks
+        - GuildInvites
+        - GuildVoiceStates
+        - GuildPresences
+        - GuildMessages
+        - GuildMessageReactions
+        - GuildMessageTyping
+        - DirectMessages
+        - DirectMessageReactions
+        - DirectMessageTyping
+        - MessageContent
+        - GuildScheduledEvents
+        - AutoModerationConfiguration
+        - AutoModerationExecution
+        - GuildMessagePolls
+        - DirectMessagePolls
+      multiple: true
+    validations:
+      required: true
+  - type: input
+    id: dev_release
+    attributes:
+      label: I have tested this issue on a development release
+      placeholder: d23280c (commit hash)
+      description: |
+        The issue might already be fixed in a development release or main. This is not required, but helps us greatly.
+        [discord.js only] To install the latest development release run `npm i discord.js@dev` in your project directory.
+        Run `npm list discord.js` and use the last part of the printed information (`d23280c` for `discord.js@xx.x.x-dev.1530234593.d23280c`)

.github/ISSUE_TEMPLATE/02-application_bug_report.yml

@@ -0,0 +1,58 @@
+name: Websites bug report
+description: Report an issue with the documentation or guide websites.
+labels: [bug, need repro]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thank you for filing an issue! If you are here to ask a question, use Discord instead: https://discord.gg/djs
+
+        This issue form is for our documentation and guide websites.
+  - type: dropdown
+    id: application
+    attributes:
+      label: Which application is this bug report for?
+      options:
+        - Documentation
+        - Guide
+    validations:
+      required: true
+  - type: textarea
+    id: description
+    attributes:
+      label: Issue description
+      description: Describe the issue in as much detail as possible.
+    validations:
+      required: true
+  - type: textarea
+    id: steps_to_reproduce
+    attributes:
+      label: Steps to Reproduce
+      description: What steps must be taken to reproduce this issue?
+      placeholder: |
+        1. Visit a page
+        2. Click a link
+        3. ...
+    validations:
+      required: true
+  - type: textarea
+    id: versions
+    attributes:
+      label: Versions
+      description: List necessary versions here. This includes your browser, operating system etc.
+      placeholder: |
+        - Safari 16.4 (18615.1.26.11.23)
+        - macOS Ventura 13.3.1
+    validations:
+      required: true
+  - type: dropdown
+    id: priority
+    attributes:
+      label: Issue priority
+      description: Please be realistic. If you need to elaborate on your reasoning, please use the issue description field above.
+      options:
+        - Low (slightly annoying)
+        - Medium (should be fixed soon)
+        - High (immediate attention needed)
+    validations:
+      required: true

.github/ISSUE_TEMPLATE/03-feature_request.yml

@@ -5,19 +5,31 @@ body:
   - type: markdown
     attributes:
       value: |
-        We can only implement features that Discord publishes, documents and merges into the Discord API documentation.
+        We can only implement features that Discord publishes, documents, and merges into the Discord API documentation.
         We do not implement unreleased features.
         Use Discord for questions: https://discord.gg/djs
   - type: dropdown
-    id: package
+    id: application_or_package
     attributes:
-      label: Which package is the feature request for?
+      label: Which application or package is this feature request for?
       options:
         - discord.js
+        - Documentation
+        - Guide
+        - brokers
         - builders
         - collection
+        - core
+        - create-discord-bot
+        - formatters
+        - next
+        - proxy
+        - proxy-container
         - rest
+        - ui
+        - util
         - voice
+        - ws
     validations:
       required: true
   - type: textarea
@@ -41,7 +53,7 @@ body:
       label: Alternative solutions or implementations
       description: A clear and concise description of any alternative solutions or features you have considered.
   - type: textarea
-    id: additional-context
+    id: additional_context
     attributes:
       label: Other context
       description: Any other context, screenshots, or file uploads that help us understand your feature request.

.github/ISSUE_TEMPLATE/bug_report.yml

@@ -1,140 +0,0 @@
-name: Bug report
-description: Report incorrect or unexpected behavior of a package
-labels: [bug, need repro]
-body:
-  - type: markdown
-    attributes:
-      value: |
-        Use Discord for questions: https://discord.gg/djs
-  - type: dropdown
-    id: package
-    attributes:
-      label: Which package is this bug report for?
-      options:
-        - discord.js
-        - builders
-        - collection
-        - rest
-        - voice
-    validations:
-      required: true
-  - type: textarea
-    id: description
-    attributes:
-      label: Issue description
-      description: |
-        Describe the issue in as much detail as possible.
-
-        Tip: You can attach images or log files by clicking this area to highlight it and then dragging files into it.
-      placeholder: |
-        Steps to reproduce with below code sample:
-        1. do thing
-        2. do thing in Discord client
-        3. observe behavior
-        4. see error logs below
-    validations:
-      required: true
-  - type: textarea
-    id: codesample
-    attributes:
-      label: Code sample
-      description: Include a reproducible, minimal code sample. This will be automatically formatted into code, so no need for backticks.
-      render: typescript
-      placeholder: |
-        Your code sample should be...
-        ... Minimal - Use as little code as possible that still produces the same problem (and is understandable)
-        ... Complete - Provide all parts someone else needs to reproduce your problem
-        ... Reproducible - Test the code you're about to provide to make sure it reproduces the problem
-  - type: input
-    id: djs-version
-    attributes:
-      label: Package version
-      description: Which version of are you using? Run `npm list <package>` in your project directory and paste the output.
-      placeholder: We no longer support version 12 or earlier of discord.js
-    validations:
-      required: true
-  - type: input
-    id: node-version
-    attributes:
-      label: Node.js version
-      description: |
-        Which version of Node.js are you using? Run `node --version` in your project directory and paste the output.
-        If you are using TypeScript, please include its version (`npm list typescript`) as well.
-      placeholder: Node.js version 16.9+ is required for version 14.0.0+
-    validations:
-      required: true
-  - type: input
-    id: os
-    attributes:
-      label: Operating system
-      description: Which OS does your application run on?
-  - type: dropdown
-    id: priority
-    attributes:
-      label: Priority this issue should have
-      description: Please be realistic. If you need to elaborate on your reasoning, please use the Issue description field above.
-      options:
-        - Low (slightly annoying)
-        - Medium (should be fixed soon)
-        - High (immediate attention needed)
-    validations:
-      required: true
-  - type: dropdown
-    id: partials
-    attributes:
-      label: Which partials do you have configured?
-      description: |
-        Check your Client constructor for the `partials` key.
-
-        Tip: you can select multiple items
-      options:
-        - Not applicable (subpackage bug)
-        - No Partials
-        - USER
-        - CHANNEL
-        - GUILD_MEMBER
-        - MESSAGE
-        - REACTION
-        - GUILD_SCHEDULED_EVENT
-      multiple: true
-    validations:
-      required: true
-  - type: dropdown
-    id: intents
-    attributes:
-      label: Which gateway intents are you subscribing to?
-      description: |
-        Check your Client constructor options for the `intents` key.
-
-        Tip: you can select multiple items
-      options:
-        - Not applicable (subpackage bug)
-        - No Intents
-        - GUILDS
-        - GUILD_MEMBERS
-        - GUILD_BANS
-        - GUILD_EMOJIS_AND_STICKERS
-        - GUILD_INTEGRATIONS
-        - GUILD_WEBHOOKS
-        - GUILD_INVITES
-        - GUILD_VOICE_STATES
-        - GUILD_PRESENCES
-        - GUILD_MESSAGES
-        - GUILD_MESSAGE_REACTIONS
-        - GUILD_MESSAGE_TYPING
-        - DIRECT_MESSAGES
-        - DIRECT_MESSAGE_REACTIONS
-        - DIRECT_MESSAGE_TYPING
-        - GUILD_SCHEDULED_EVENTS
-      multiple: true
-    validations:
-      required: true
-  - type: input
-    id: dev-release
-    attributes:
-      label: I have tested this issue on a development release
-      placeholder: d23280c (commit hash)
-      description: |
-        The issue might already be fixed in a development release or main. This is not required, but helps us greatly.
-        [discord.js only] To install the latest development release run `npm i discord.js@dev` in your project directory.
-        Run `npm list discord.js` and use the last part of the printed information (`d23280c` for `discord.js@xx.x.x-dev.1530234593.d23280c`)

.github/auto_assign.yml

@@ -1,7 +0,0 @@
-addReviewers: true
-reviewers:
-  - iCrawl
-  - SpaceEEC
-  - kyranet
-  - vladfrangu
-numberOfReviewers: 0

.github/issue-labeler.yml

@@ -0,0 +1,51 @@
+apps:guide:
+  - "### Which (application|package|application or package) is this (bug
+    report|feature request) for\\?\\n\\nGuide\\n"
+apps:website:
+  - "### Which (application|package|application or package) is this (bug
+    report|feature request) for\\?\\n\\nDocumentation\\n"
+packages:brokers:
+  - "### Which (application|package|application or package) is this (bug
+    report|feature request) for\\?\\n\\nbrokers\\n"
+packages:builders:
+  - "### Which (application|package|application or package) is this (bug
+    report|feature request) for\\?\\n\\nbuilders\\n"
+packages:collection:
+  - "### Which (application|package|application or package) is this (bug
+    report|feature request) for\\?\\n\\ncollection\\n"
+packages:core:
+  - "### Which (application|package|application or package) is this (bug
+    report|feature request) for\\?\\n\\ncore\\n"
+packages:create-discord-bot:
+  - "### Which (application|package|application or package) is this (bug
+    report|feature request) for\\?\\n\\ncreate-discord-bot\\n"
+packages:discord.js:
+  - "### Which (application|package|application or package) is this (bug
+    report|feature request) for\\?\\n\\ndiscord.js\\n"
+packages:formatters:
+  - "### Which (application|package|application or package) is this (bug
+    report|feature request) for\\?\\n\\nformatters\\n"
+packages:next:
+  - "### Which (application|package|application or package) is this (bug
+    report|feature request) for\\?\\n\\nnext\\n"
+packages:proxy:
+  - "### Which (application|package|application or package) is this (bug
+    report|feature request) for\\?\\n\\nproxy\\n"
+packages:proxy-container:
+  - "### Which (application|package|application or package) is this (bug
+    report|feature request) for\\?\\n\\nproxy-container\\n"
+packages:rest:
+  - "### Which (application|package|application or package) is this (bug
+    report|feature request) for\\?\\n\\nrest\\n"
+packages:ui:
+  - "### Which (application|package|application or package) is this (bug
+    report|feature request) for\\?\\n\\ui\\n"
+packages:util:
+  - "### Which (application|package|application or package) is this (bug
+    report|feature request) for\\?\\n\\util\\n"
+packages:voice:
+  - "### Which (application|package|application or package) is this (bug
+    report|feature request) for\\?\\n\\nvoice\\n"
+packages:ws:
+  - "### Which (application|package|application or package) is this (bug
+    report|feature request) for\\?\\n\\nws\\n"

.github/labeler.yml

@@ -1,27 +1,100 @@
-chore:
-  - any: ['*']
-    all: ['!packages/*', '!packages/**/*']
-
-'packages:builders':
-  - packages/builders/*
-  - packages/builders/**/*
-
-'packages:collection':
-  - packages/collection/*
-  - packages/collection/**/*
-
-'packages:discord.js':
-  - packages/discord.js/*
-  - packages/discord.js/**/*
-
-'packages:rest':
-  - packages/rest/*
-  - packages/rest/**/*
-
-'packages:voice':
-  - packages/voice/*
-  - packages/voice/**/*
-
-'packages:ws':
-  - packages/ws/*
-  - packages/ws/**/*
+apps:guide:
+  - changed-files:
+      - any-glob-to-any-file:
+          - apps/guide/*
+          - apps/guide/**/*
+apps:website:
+  - changed-files:
+      - any-glob-to-any-file:
+          - apps/website/*
+          - apps/website/**/*
+packages:api-extractor:
+  - changed-files:
+      - any-glob-to-any-file:
+          - packages/api-extractor/*
+          - packages/api-extractor/**/*
+packages:api-extractor-model:
+  - changed-files:
+      - any-glob-to-any-file:
+          - packages/api-extractor-model/*
+          - packages/api-extractor-model/**/*
+packages:brokers:
+  - changed-files:
+      - any-glob-to-any-file:
+          - packages/brokers/*
+          - packages/brokers/**/*
+packages:builders:
+  - changed-files:
+      - any-glob-to-any-file:
+          - packages/builders/*
+          - packages/builders/**/*
+packages:collection:
+  - changed-files:
+      - any-glob-to-any-file:
+          - packages/collection/*
+          - packages/collection/**/*
+packages:core:
+  - changed-files:
+      - any-glob-to-any-file:
+          - packages/core/*
+          - packages/core/**/*
+packages:create-discord-bot:
+  - changed-files:
+      - any-glob-to-any-file:
+          - packages/create-discord-bot/*
+          - packages/create-discord-bot/**/*
+packages:discord.js:
+  - changed-files:
+      - any-glob-to-any-file:
+          - packages/discord.js/*
+          - packages/discord.js/**/*
+packages:docgen:
+  - changed-files:
+      - any-glob-to-any-file:
+          - packages/docgen/*
+          - packages/docgen/**/*
+packages:formatters:
+  - changed-files:
+      - any-glob-to-any-file:
+          - packages/formatters/*
+          - packages/formatters/**/*
+packages:next:
+  - changed-files:
+      - any-glob-to-any-file:
+          - packages/next/*
+          - packages/next/**/*
+packages:proxy:
+  - changed-files:
+      - any-glob-to-any-file:
+          - packages/proxy/*
+          - packages/proxy/**/*
+packages:proxy-container:
+  - changed-files:
+      - any-glob-to-any-file:
+          - packages/proxy-container/*
+          - packages/proxy-container/**/*
+packages:rest:
+  - changed-files:
+      - any-glob-to-any-file:
+          - packages/rest/*
+          - packages/rest/**/*
+packages:ui:
+  - changed-files:
+      - any-glob-to-any-file:
+          - packages/ui/*
+          - packages/ui/**/*
+packages:util:
+  - changed-files:
+      - any-glob-to-any-file:
+          - packages/util/*
+          - packages/util/**/*
+packages:voice:
+  - changed-files:
+      - any-glob-to-any-file:
+          - packages/voice/*
+          - packages/voice/**/*
+packages:ws:
+  - changed-files:
+      - any-glob-to-any-file:
+          - packages/ws/*
+          - packages/ws/**/*

.github/labels.yml

@@ -1,92 +1,124 @@
-- name: 'api changes'
+- name: api changes
   color: '5663e9'
-- name: 'api support'
+- name: api support
   color: '5663e9'
-- name: 'backlog'
-  color: '7ef7ef'
-- name: 'bug'
-  color: 'd73a4a'
-- name: 'caching'
-  color: '80c042'
-- name: 'chore'
-  color: 'ffffff'
-- name: 'ci'
-  color: '0075ca'
-- name: 'dependencies'
-  color: '276bd1'
-- name: 'discussion'
-  color: 'b6b1f9'
-- name: 'discord'
+- name: apps:guide
+  color: fbca04
+- name: apps:website
+  color: fbca04
+- name: backlog
+  color: 7ef7ef
+- name: backport
+  color: 88aabb
+- name: blocked
+  color: fc1423
+- name: bug
+  color: d73a4a
+- name: caching
+  color: 80c042
+- name: chore
+  color: ffffff
+- name: ci
+  color: 0075ca
+- name: dependencies
+  color: 276bd1
+- name: discord
   color: '5663e9'
-- name: 'documentation'
-  color: '0075ca'
-- name: 'duplicate'
-  color: 'cfd3d7'
-- name: 'error handling'
-  color: '80c042'
-- name: 'feature request'
-  color: 'fcf95a'
-- name: 'gateway'
-  color: '80c042'
-- name: 'good first issue'
-  color: '7057ff'
-- name: 'has PR'
-  color: '4b1f8e'
-- name: 'help wanted'
+- name: discussion
+  color: b6b1f9
+- name: documentation
+  color: 0075ca
+- name: duplicate
+  color: cfd3d7
+- name: error handling
+  color: 80c042
+- name: feature request
+  color: fcf95a
+- name: gateway
+  color: 80c042
+- name: good first issue
+  color: 7057ff
+- name: has PR
+  color: 4b1f8e
+- name: help wanted
   color: '008672'
-- name: 'interactions'
-  color: '80c042'
-- name: 'in progress'
-  color: 'ffccd7'
-- name: 'in review'
-  color: 'aed5fc'
-- name: 'invalid'
-  color: 'e4e669'
-- name: 'need repro'
-  color: 'c66037'
-- name: 'packages:builders'
-  color: 'fbca04'
-- name: 'packages:collection'
-  color: 'fbca04'
-- name: 'packages:discord.js'
-  color: 'fbca04'
-- name: 'packages:rest'
-  color: 'fbca04'
-- name: 'packages:voice'
-  color: 'fbca04'
-- name: 'packages:ws'
-  color: 'fbca04'
-- name: 'performance'
-  color: '80c042'
-- name: 'permissions'
-  color: '80c042'
-- name: 'priority:high'
-  color: 'fc1423'
-- name: 'question (please use Discord instead)'
-  color: 'd876e3'
-- name: 'ratelimits'
-  color: '80c042'
-- name: 'refactor'
-  color: '1d637f'
-- name: 'regression'
-  color: 'ea8785'
-- name: 'REST'
-  color: '80c042'
-- name: 'semver:major'
-  color: 'c10f47'
-- name: 'semver:minor'
-  color: 'e4f486'
-- name: 'semver:patch'
-  color: 'e8be8b'
-- name: 'sharding'
-  color: '80c042'
-- name: 'tests'
-  color: 'f06dff'
-- name: 'threads'
-  color: '80c042'
-- name: 'typings'
-  color: '80c042'
-- name: 'utility'
-  color: '80c042'
-- name: 'wontfix'
-  color: 'ffffff'
+- name: in progress
+  color: ffccd7
+- name: in review
+  color: aed5fc
+- name: interactions
+  color: 80c042
+- name: invalid
+  color: e4e669
+- name: need repro
+  color: c66037
+- name: packages:api-extractor
+  color: fbca04
+- name: packages:api-extractor-model
+  color: fbca04
+- name: packages:brokers
+  color: fbca04
+- name: packages:builders
+  color: fbca04
+- name: packages:collection
+  color: fbca04
+- name: packages:core
+  color: fbca04
+- name: packages:create-discord-bot
+  color: fbca04
+- name: packages:discord.js
+  color: fbca04
+- name: packages:docgen
+  color: fbca04
+- name: packages:formatters
+  color: fbca04
+- name: packages:next
+  color: fbca04
+- name: packages:proxy
+  color: fbca04
+- name: packages:proxy-container
+  color: fbca04
+- name: packages:rest
+  color: fbca04
+- name: packages:ui
+  color: fbca04
+- name: packages:util
+  color: fbca04
+- name: packages:voice
+  color: fbca04
+- name: packages:ws
+  color: fbca04
+- name: performance
+  color: 80c042
+- name: permissions
+  color: 80c042
+- name: priority:high
+  color: fc1423
+- name: question (please use Discord instead)
+  color: d876e3
+- name: ratelimits
+  color: 80c042
+- name: refactor
+  color: 1d637f
+- name: regression
+  color: ea8785
+- name: REST
+  color: 80c042
+- name: semver:major
+  color: c10f47
+- name: semver:minor
+  color: e4f486
+- name: semver:patch
+  color: e8be8b
+- name: sharding
+  color: 80c042
+- name: tests
+  color: f06dff
+- name: threads
+  color: 80c042
+- name: typings
+  color: 80c042
+- name: utility
+  color: 80c042
+- name: wontfix
+  color: ffffff

.github/workflows/auto-deprecate.yml

@@ -1,28 +0,0 @@
-name: npm auto deprecate
-on:
-  workflow_dispatch:
-  schedule:
-    - cron: '0 1 * * *'
-jobs:
-  auto-deprecate:
-    name: npm auto deprecate
-    runs-on: ubuntu-latest
-    if: github.repository_owner == 'discordjs'
-    steps:
-      - name: Checkout repository
-        uses: actions/checkout@v2
-
-      - name: Install node.js v16
-        uses: actions/setup-node@v2
-        with:
-          node-version: 16
-          cache: 'yarn'
-          cache-dependency-path: yarn.lock
-
-      - name: Install dependencies
-        run: yarn --immutable
-
-      - name: Deprecate versions
-        run: 'yarn npm-deprecate --name "*dev*" --package "discord.js"'
-        env:
-          NODE_AUTH_TOKEN: ${{ secrets.NPM_PUBLISH_TOKEN }}

.github/workflows/cleanup-cache.yml

@@ -0,0 +1,35 @@
+# https://docs.github.com/actions/using-workflows/caching-dependencies-to-speed-up-workflows#force-deleting-cache-entries
+name: Cleanup caches
+on:
+  pull_request:
+    types:
+      - closed
+  workflow_dispatch:
+jobs:
+  cleanup:
+    name: Cleanup caches
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Cleanup caches
+        run: |
+          gh extension install actions/gh-actions-cache
+
+          REPO=${{ github.repository }}
+          BRANCH="refs/pull/${{ github.event.pull_request.number }}/merge"
+
+          echo "Fetching list of cache key"
+          cacheKeysForPR=$(gh actions-cache list -R $REPO -B $BRANCH | cut -f 1 )
+
+          ## Setting this to not fail the workflow while deleting cache keys.
+          set +e
+          echo "Deleting caches..."
+          for cacheKey in $cacheKeysForPR
+          do
+              gh actions-cache delete $cacheKey -R $REPO -B $BRANCH --confirm
+          done
+          echo "Done"
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}

.github/workflows/deprecate-version.yml

@@ -0,0 +1,50 @@
+name: Deprecate version
+on:
+  workflow_dispatch:
+    inputs:
+      package:
+        description: Package
+        required: true
+        type: choice
+        options:
+          - '@discordjs/brokers'
+          - '@discordjs/builders'
+          - '@discordjs/collection'
+          - '@discordjs/core'
+          - 'create-discord-bot'
+          - '@discordjs/formatters'
+          - 'discord.js'
+          - '@discordjs/next'
+          - '@discordjs/proxy'
+          - '@discordjs/rest'
+          - '@discordjs/util'
+          - '@discordjs/voice'
+          - '@discordjs/ws'
+      version:
+        description: Version(s)
+        required: true
+        type: string
+      message:
+        description: Deprecation message
+        required: false
+        type: string
+jobs:
+  deprecate:
+    runs-on: ubuntu-latest
+    if: github.repository_owner == 'discordjs'
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Install Node.js v20
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20
+
+      - name: Install dependencies
+        uses: ./packages/actions/src/pnpmCache
+
+      - name: Deprecate
+        run: pnpm exec npm-deprecate --name "${{inputs.version}}" --message "${{inputs.message || 'This version is deprecated. Please use a newer version.'}}" --package ${{inputs.package}}
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_PUBLISH_TOKEN }}

.github/workflows/documentation.yml

@@ -3,91 +3,242 @@ on:
   push:
     branches:
       - 'main'
-      - 'stable'
-      - '!docs'
+    paths:
+      - 'packages/*/src/**'
+      - '!packages/create-discord-bot/**'
+      - '!packages/proxy-container/**'
+      - '!packages/ui/**'
     tags:
-      - '*'
+      - '**'
+  workflow_dispatch:
+    inputs:
+      ref:
+        description: 'The branch, tag or SHA to checkout'
+        required: true
+      ref_type:
+        type: choice
+        description: 'Branch or tag'
+        options:
+          - branch
+          - tag
+        required: true
+concurrency:
+  group: ${{ github.workflow }}-${{ github.head_ref || github.ref }}
+  cancel-in-progress: true
 jobs:
-  build:
-    name: Build documentation
-    runs-on: ubuntu-latest
-    if: github.repository_owner == 'discordjs'
-    outputs:
-      BRANCH_NAME: ${{ steps.env.outputs.BRANCH_NAME }}
-      BRANCH_OR_TAG: ${{ steps.env.outputs.BRANCH_OR_TAG }}
-      SHA: ${{ steps.env.outputs.SHA }}
-    steps:
-      - name: Checkout repository
-        uses: actions/checkout@v2
-
-      - name: Install node.js v16
-        uses: actions/setup-node@v2
-        with:
-          node-version: 16
-          cache: 'yarn'
-          cache-dependency-path: yarn.lock
-
-      - name: Turbo cache
-        id: turbo-cache
-        uses: actions/cache@v2
-        with:
-          path: .turbo
-          key: turbo-${{ github.job }}-${{ github.ref_name }}-${{ github.sha }}
-          restore-keys: |
-            turbo-${{ github.job }}-${{ github.ref_name }}-
-
-      - name: Install dependencies
-        run: yarn --immutable
-
-      - name: Build docs
-        run: yarn docs --cache-dir=".turbo"
-
-      - name: Upload artifacts
-        uses: actions/upload-artifact@v2
-        with:
-          name: docs
-          path: packages/*/docs/docs.json
-
-      - name: Set outputs for upload job
-        id: env
-        run: |
-          echo "::set-output name=BRANCH_NAME::${GITHUB_REF_NAME}"
-          echo "::set-output name=BRANCH_OR_TAG::${GITHUB_REF_TYPE}"
-          echo "::set-output name=SHA::${GITHUB_SHA}"
-
-  upload:
-    name: Upload Documentation
-    needs: build
-    strategy:
-      max-parallel: 1
-      fail-fast: false
-      matrix:
-        package: ['builders', 'collection', 'discord.js', 'rest', 'voice']
+  build-docs:
+    name: Build & upload documentation
     runs-on: ubuntu-latest
     env:
-      BRANCH_NAME: ${{ needs.build.outputs.BRANCH_NAME }}
-      BRANCH_OR_TAG: ${{ needs.build.outputs.BRANCH_OR_TAG }}
-      SHA: ${{ needs.build.outputs.SHA }}
+      TURBO_TOKEN: ${{ secrets.TURBO_TOKEN }}
+      TURBO_TEAM: ${{ secrets.TURBO_TEAM }}
+      REF_TYPE: ${{ inputs.ref_type || github.ref_type }}
+    if: github.repository_owner == 'discordjs'
     steps:
-      - name: Download artifacts
-        uses: actions/download-artifact@v2
+      - name: Checkout repository
+        uses: actions/checkout@v4
         with:
-          name: docs
-          path: docs
+          ref: ${{ inputs.ref || '' }}
+
+      - name: Install Node.js v20
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20
+
+      - name: Install dependencies
+        uses: ./packages/actions/src/pnpmCache
+
+      - name: Build dependencies
+        run: pnpm run build
+
+      - name: Checkout main repository
+        if: ${{ inputs.ref && inputs.ref != 'main' }}
+        uses: actions/checkout@v4
+        with:
+          path: 'main'
+
+      - name: Build main
+        if: ${{ inputs.ref && inputs.ref != 'main' }}
+        shell: bash
+        run: |
+          cd main
+          pnpm install --frozen-lockfile --prefer-offline --loglevel error
+          pnpm run build
+          cd ..
+
+      - name: Extract package and semver from tag
+        if: ${{ env.REF_TYPE == 'tag' }}
+        id: extract-tag
+        uses: ./packages/actions/src/formatTag
+        with:
+          tag: ${{ inputs.ref || github.ref_name }}
+
+      - name: Apply tag to api-extractor config
+        if: ${{ env.REF_TYPE == 'tag' && !inputs.ref }}
+        run: sed -i 's!https://github.com/discordjs/discord.js/tree/main!https://github.com/discordjs/discord.js/tree/${{ github.ref_name }}!' "packages/${{ steps.extract-tag.outputs.package}}/api-extractor.json"
+
+      - name: Build docs
+        run: pnpm run docs
+
+      - name: Build docs with main api-extractor
+        if: ${{ inputs.ref && inputs.ref != 'main' }}
+        run: |
+          declare -a PACKAGES=("brokers" "builders" "collection" "core" "discord.js" "formatters" "next" "proxy" "rest" "util" "voice" "ws")
+          for PACKAGE in "${PACKAGES[@]}"; do
+            cd "packages/${PACKAGE}"
+            sed -i 's!https://github.com/discordjs/discord.js/tree/main!https://github.com/discordjs/discord.js/tree/${{ inputs.ref }}!' api-extractor.json
+            ../../main/packages/api-extractor/bin/api-extractor run --local --minify
+            ../../main/packages/scripts/bin/generateSplitDocumentation.js
+            cd ../..
+          done
 
       - name: Checkout docs repository
-        uses: actions/checkout@v2
+        uses: actions/checkout@v4
         with:
           repository: 'discordjs/docs'
           token: ${{ secrets.DJS_DOCS }}
           path: 'out'
 
-      - name: Move docs to correct directory
+      - name: Upload documentation to database
+        if: ${{ env.REF_TYPE == 'tag' && (!inputs.ref || inputs.ref == 'main') }}
         env:
-          PACKAGE: ${{ matrix.package }}
+          DATABASE_URL: ${{ secrets.DATABASE_URL }}
+          CF_D1_DOCS_API_KEY: ${{ secrets.CF_D1_DOCS_API_KEY }}
+          CF_D1_DOCS_ID: ${{ secrets.CF_D1_DOCS_ID }}
+          CF_ACCOUNT_ID: ${{ secrets.CF_ACCOUNT_ID }}
+          BLOB_READ_WRITE_TOKEN: ${{ secrets.BLOB_READ_WRITE_TOKEN }}
+          CF_R2_DOCS_URL: ${{ secrets.CF_R2_DOCS_URL }}
+          CF_R2_DOCS_ACCESS_KEY_ID: ${{ secrets.CF_R2_DOCS_ACCESS_KEY_ID }}
+          CF_R2_DOCS_SECRET_ACCESS_KEY: ${{ secrets.CF_R2_DOCS_SECRET_ACCESS_KEY }}
+          CF_R2_DOCS_BUCKET: ${{ secrets.CF_R2_DOCS_BUCKET }}
+          CF_R2_DOCS_BUCKET_URL: ${{ secrets.CF_R2_DOCS_BUCKET_URL }}
+        uses: ./packages/actions/src/uploadDocumentation
+        with:
+          package: ${{ steps.extract-tag.outputs.package }}
+          version: ${{ steps.extract-tag.outputs.semver }}
+
+      - name: Upload documentation to database
+        if: ${{ env.REF_TYPE == 'tag' && inputs.ref && inputs.ref != 'main' }}
+        env:
+          DATABASE_URL: ${{ secrets.DATABASE_URL }}
+          CF_D1_DOCS_API_KEY: ${{ secrets.CF_D1_DOCS_API_KEY }}
+          CF_D1_DOCS_ID: ${{ secrets.CF_D1_DOCS_ID }}
+          CF_ACCOUNT_ID: ${{ secrets.CF_ACCOUNT_ID }}
+          BLOB_READ_WRITE_TOKEN: ${{ secrets.BLOB_READ_WRITE_TOKEN }}
+          CF_R2_DOCS_URL: ${{ secrets.CF_R2_DOCS_URL }}
+          CF_R2_DOCS_ACCESS_KEY_ID: ${{ secrets.CF_R2_DOCS_ACCESS_KEY_ID }}
+          CF_R2_DOCS_SECRET_ACCESS_KEY: ${{ secrets.CF_R2_DOCS_SECRET_ACCESS_KEY }}
+          CF_R2_DOCS_BUCKET: ${{ secrets.CF_R2_DOCS_BUCKET }}
+          CF_R2_DOCS_BUCKET_URL: ${{ secrets.CF_R2_DOCS_BUCKET_URL }}
+        uses: ./main/packages/actions/src/uploadDocumentation
+        with:
+          package: ${{ steps.extract-tag.outputs.package }}
+          version: ${{ steps.extract-tag.outputs.semver }}
+
+      - name: Upload split documentation to blob storage
+        if: ${{ env.REF_TYPE == 'tag' && (!inputs.ref || inputs.ref == 'main') }}
+        env:
+          BLOB_READ_WRITE_TOKEN: ${{ secrets.BLOB_READ_WRITE_TOKEN }}
+          CF_R2_DOCS_URL: ${{ secrets.CF_R2_DOCS_URL }}
+          CF_R2_DOCS_ACCESS_KEY_ID: ${{ secrets.CF_R2_DOCS_ACCESS_KEY_ID }}
+          CF_R2_DOCS_SECRET_ACCESS_KEY: ${{ secrets.CF_R2_DOCS_SECRET_ACCESS_KEY }}
+          CF_R2_DOCS_BUCKET: ${{ secrets.CF_R2_DOCS_BUCKET }}
+        uses: ./packages/actions/src/uploadSplitDocumentation
+        with:
+          package: ${{ steps.extract-tag.outputs.package }}
+          version: ${{ steps.extract-tag.outputs.semver }}
+
+      - name: Upload split documentation to blob storage
+        if: ${{ env.REF_TYPE == 'tag' && inputs.ref && inputs.ref != 'main' }}
+        env:
+          BLOB_READ_WRITE_TOKEN: ${{ secrets.BLOB_READ_WRITE_TOKEN }}
+          CF_R2_DOCS_URL: ${{ secrets.CF_R2_DOCS_URL }}
+          CF_R2_DOCS_ACCESS_KEY_ID: ${{ secrets.CF_R2_DOCS_ACCESS_KEY_ID }}
+          CF_R2_DOCS_SECRET_ACCESS_KEY: ${{ secrets.CF_R2_DOCS_SECRET_ACCESS_KEY }}
+          CF_R2_DOCS_BUCKET: ${{ secrets.CF_R2_DOCS_BUCKET }}
+        uses: ./main/packages/actions/src/uploadSplitDocumentation
+        with:
+          package: ${{ steps.extract-tag.outputs.package }}
+          version: ${{ steps.extract-tag.outputs.semver }}
+
+      - name: Move docs to correct directory
+        if: ${{ env.REF_TYPE == 'tag' }}
+        env:
+          PACKAGE: ${{ steps.extract-tag.outputs.package }}
+          SEMVER: ${{ steps.extract-tag.outputs.semver }}
         run: |
-          mkdir -p out/${PACKAGE}
-          mv docs/${PACKAGE}/docs/docs.json out/${PACKAGE}/${BRANCH_NAME}.json
+          mkdir -p "out/${PACKAGE}"
+          if [[ "${PACKAGE}" == "discord.js" ]]; then
+            mv "packages/${PACKAGE}/docs/docs.json" "out/${PACKAGE}/${SEMVER}.json"
+            mv "packages/${PACKAGE}/docs/docs.api.json" "out/${PACKAGE}/${SEMVER}.api.json"
+          else
+            mv "packages/${PACKAGE}/docs/docs.api.json" "out/${PACKAGE}/${SEMVER}.api.json"
+          fi
+
+      - name: Upload documentation to database
+        if: ${{ env.REF_TYPE == 'branch' && (!inputs.ref || inputs.ref == 'main') }}
+        env:
+          DATABASE_URL: ${{ secrets.DATABASE_URL }}
+          CF_D1_DOCS_API_KEY: ${{ secrets.CF_D1_DOCS_API_KEY }}
+          CF_D1_DOCS_ID: ${{ secrets.CF_D1_DOCS_ID }}
+          CF_ACCOUNT_ID: ${{ secrets.CF_ACCOUNT_ID }}
+          BLOB_READ_WRITE_TOKEN: ${{ secrets.BLOB_READ_WRITE_TOKEN }}
+          CF_R2_DOCS_URL: ${{ secrets.CF_R2_DOCS_URL }}
+          CF_R2_DOCS_ACCESS_KEY_ID: ${{ secrets.CF_R2_DOCS_ACCESS_KEY_ID }}
+          CF_R2_DOCS_SECRET_ACCESS_KEY: ${{ secrets.CF_R2_DOCS_SECRET_ACCESS_KEY }}
+          CF_R2_DOCS_BUCKET: ${{ secrets.CF_R2_DOCS_BUCKET }}
+          CF_R2_DOCS_BUCKET_URL: ${{ secrets.CF_R2_DOCS_BUCKET_URL }}
+        uses: ./packages/actions/src/uploadDocumentation
+
+      - name: Upload documentation to database
+        if: ${{ env.REF_TYPE == 'branch' && inputs.ref && inputs.ref != 'main' }}
+        env:
+          DATABASE_URL: ${{ secrets.DATABASE_URL }}
+          CF_D1_DOCS_API_KEY: ${{ secrets.CF_D1_DOCS_API_KEY }}
+          CF_D1_DOCS_ID: ${{ secrets.CF_D1_DOCS_ID }}
+          CF_ACCOUNT_ID: ${{ secrets.CF_ACCOUNT_ID }}
+          BLOB_READ_WRITE_TOKEN: ${{ secrets.BLOB_READ_WRITE_TOKEN }}
+          CF_R2_DOCS_URL: ${{ secrets.CF_R2_DOCS_URL }}
+          CF_R2_DOCS_ACCESS_KEY_ID: ${{ secrets.CF_R2_DOCS_ACCESS_KEY_ID }}
+          CF_R2_DOCS_SECRET_ACCESS_KEY: ${{ secrets.CF_R2_DOCS_SECRET_ACCESS_KEY }}
+          CF_R2_DOCS_BUCKET: ${{ secrets.CF_R2_DOCS_BUCKET }}
+          CF_R2_DOCS_BUCKET_URL: ${{ secrets.CF_R2_DOCS_BUCKET_URL }}
+        uses: ./main/packages/actions/src/uploadDocumentation
+
+      - name: Upload split documentation to blob storage
+        if: ${{ env.REF_TYPE == 'branch' && (!inputs.ref || inputs.ref == 'main') }}
+        env:
+          BLOB_READ_WRITE_TOKEN: ${{ secrets.BLOB_READ_WRITE_TOKEN }}
+          CF_R2_DOCS_URL: ${{ secrets.CF_R2_DOCS_URL }}
+          CF_R2_DOCS_ACCESS_KEY_ID: ${{ secrets.CF_R2_DOCS_ACCESS_KEY_ID }}
+          CF_R2_DOCS_SECRET_ACCESS_KEY: ${{ secrets.CF_R2_DOCS_SECRET_ACCESS_KEY }}
+          CF_R2_DOCS_BUCKET: ${{ secrets.CF_R2_DOCS_BUCKET }}
+        uses: ./packages/actions/src/uploadSplitDocumentation
+
+      - name: Upload split documentation to blob storage
+        if: ${{ env.REF_TYPE == 'branch' && inputs.ref && inputs.ref != 'main' }}
+        env:
+          BLOB_READ_WRITE_TOKEN: ${{ secrets.BLOB_READ_WRITE_TOKEN }}
+          CF_R2_DOCS_URL: ${{ secrets.CF_R2_DOCS_URL }}
+          CF_R2_DOCS_ACCESS_KEY_ID: ${{ secrets.CF_R2_DOCS_ACCESS_KEY_ID }}
+          CF_R2_DOCS_SECRET_ACCESS_KEY: ${{ secrets.CF_R2_DOCS_SECRET_ACCESS_KEY }}
+          CF_R2_DOCS_BUCKET: ${{ secrets.CF_R2_DOCS_BUCKET }}
+        uses: ./main/packages/actions/src/uploadSplitDocumentation
+
+      - name: Move docs to correct directory
+        if: ${{ env.REF_TYPE == 'branch' }}
+        run: |
+          declare -a PACKAGES=("brokers" "builders" "collection" "core" "discord.js" "formatters" "next" "proxy" "rest" "util" "voice" "ws")
+          for PACKAGE in "${PACKAGES[@]}"; do
+            if [[ "${PACKAGE}" == "discord.js" ]]; then
+              mkdir -p "out/${PACKAGE}"
+              mv "packages/${PACKAGE}/docs/docs.json" "out/${PACKAGE}/${GITHUB_REF_NAME}.json"
+              mv "packages/${PACKAGE}/docs/docs.api.json" "out/${PACKAGE}/${GITHUB_REF_NAME}.api.json"
+            else
+              mkdir -p "out/${PACKAGE}"
+              mv "packages/${PACKAGE}/docs/docs.api.json" "out/${PACKAGE}/${GITHUB_REF_NAME}.api.json"
+            fi
+          done
 
       - name: Commit and push
         run: |
@@ -95,5 +246,35 @@ jobs:
           git config user.name github-actions[bot]
           git config user.email 41898282+github-actions[bot]@users.noreply.github.com
           git add .
-          git commit -m "Docs build for ${BRANCH_OR_TAG} ${BRANCH_NAME}: ${SHA}" || true
+          git commit -m "Docs build for ${GITHUB_REF_TYPE} ${GITHUB_REF_NAME}: ${GITHUB_SHA}" || true
           git push
+
+  build-indices:
+    needs: build-docs
+    name: Build & upload search indices
+    runs-on: ubuntu-latest
+    env:
+      TURBO_TOKEN: ${{ secrets.TURBO_TOKEN }}
+      TURBO_TEAM: ${{ secrets.TURBO_TEAM }}
+    if: github.repository_owner == 'discordjs'
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Install Node.js v20
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20
+
+      - name: Install dependencies
+        uses: ./packages/actions/src/pnpmCache
+
+      - name: Build dependencies
+        run: pnpm run build
+
+      - name: Upload search indices to meilisearch
+        env:
+          DATABASE_URL: ${{ secrets.DATABASE_URL }}
+          SEARCH_API_URL: ${{ secrets.SEARCH_API_URL }}
+          SEARCH_API_KEY: ${{ secrets.SEARCH_API_KEY }}
+        uses: ./packages/actions/src/uploadSearchIndices

.github/workflows/issue-triage.yml

@@ -0,0 +1,14 @@
+name: 'Issue Labeler'
+on:
+  issues:
+    types: [opened]
+jobs:
+  issue-triage:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: github/issue-labeler@v3.4
+        with:
+          repo-token: '${{ secrets.GITHUB_TOKEN }}'
+          configuration-path: .github/issue-labeler.yml
+          not-before: 2023-01-13T10:25:03.847Z
+          enable-versioned-regex: 0

.github/workflows/label-sync.yml

@@ -1,4 +1,4 @@
-name: Label Sync
+name: Label sync
 on:
   schedule:
     - cron: '0 0 * * *'
@@ -9,14 +9,15 @@ on:
     paths:
       - '.github/labels.yml'
 jobs:
-  labelsync:
+  label-sync:
     name: Label sync
     runs-on: ubuntu-latest
+    if: github.repository_owner == 'discordjs'
     steps:
       - name: Checkout repository
-        uses: actions/checkout@v2
+        uses: actions/checkout@v4
 
       - name: Label sync
-        uses: crazy-max/ghaction-github-labeler@v3
+        uses: crazy-max/ghaction-github-labeler@v5
         with:
           github-token: ${{ secrets.GITHUB_TOKEN }}

.github/workflows/lock.yml

@@ -0,0 +1,19 @@
+name: Lock Ancient Issues
+on:
+  schedule:
+    - cron: '0 16 * * *'
+  workflow_dispatch:
+concurrency:
+  group: lock
+jobs:
+  action:
+    runs-on: ubuntu-latest
+    permissions:
+      issues: write
+    steps:
+      - uses: dessant/lock-threads@v5
+        with:
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+          issue-inactive-days: 365
+          issue-lock-reason: resolved
+          process-only: issues

.github/workflows/pr-automation.yml

@@ -1,16 +0,0 @@
-name: 'PR Automation'
-on:
-  pull_request_target:
-jobs:
-  triage:
-    runs-on: ubuntu-latest
-    steps:
-      - name: Automatically label PR
-        uses: actions/labeler@v3
-        with:
-          repo-token: '${{ secrets.GITHUB_TOKEN }}'
-          sync-labels: true
-
-      - name: Automatically assign reviewers
-        if: ${{ github.event.action == 'opened' }}
-        uses: kentaro-m/auto-assign-action@v1.1.2

.github/workflows/pr-triage.yml

@@ -0,0 +1,35 @@
+name: 'PR Triage'
+on:
+  pull_request_target:
+    types:
+      - opened
+      - edited
+      - reopened
+      - synchronize
+jobs:
+  label:
+    name: Label
+    if: github.event.action != 'edited'
+    runs-on: ubuntu-latest
+    steps:
+      - name: Label pull request
+        uses: actions/labeler@v5
+        with:
+          repo-token: '${{ secrets.GITHUB_TOKEN }}'
+          sync-labels: true
+  validate-title:
+    name: Validate title
+    if: github.event.action != 'synchronize'
+    runs-on: ubuntu-latest
+    steps:
+      - name: Validate pull request title
+        env:
+          TITLE: ${{ github.event.pull_request.title }}
+        run: |
+          REGEX="^(revert: )?(feat|fix|docs|style|refactor|perf|test|build|ci|chore|types)(\\(.+\\))?!?: .{1,72}$"
+
+          echo "Title: \"$TITLE\""
+
+          if [[ ! "$TITLE" =~ $REGEX ]]; then
+            exit 1
+          fi

.github/workflows/publish-dev-docker.yml

@@ -0,0 +1,30 @@
+name: Publish dev docker images
+on:
+  schedule:
+    - cron: '0 */12 * * *'
+  workflow_dispatch:
+jobs:
+  docker-publish:
+    name: Docker publish
+    runs-on: ubuntu-latest
+    if: github.repository_owner == 'discordjs'
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Install Node.js v20
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20
+
+      - name: Install dependencies
+        uses: ./packages/actions/src/pnpmCache
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v3
+
+      - name: Login to DockerHub
+        run: echo ${{ secrets.DOCKER_ACCESS_TOKEN }} | docker login -u ${{ secrets.DOCKER_USERNAME }} --password-stdin
+
+      - name: Build & push docker image
+        run: docker build -f packages/proxy-container/Dockerfile -t discordjs/proxy:latest --push .

.github/workflows/publish-dev.yml

@@ -1,59 +1,84 @@
 name: Publish dev
 on:
-  workflow_dispatch:
   schedule:
     - cron: '0 */12 * * *'
+  workflow_dispatch:
 jobs:
-  npm:
-    name: npm
+  npm-publish:
+    name: npm publish
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - package: '@discordjs/brokers'
+            folder: 'brokers'
+          - package: '@discordjs/builders'
+            folder: 'builders'
+          - package: '@discordjs/collection'
+            folder: 'collection'
+          - package: '@discordjs/core'
+            folder: 'core'
+          - package: '@discordjs/formatters'
+            folder: 'formatters'
+          - package: 'discord.js'
+            folder: 'discord.js'
+          - package: '@discordjs/next'
+            folder: 'next'
+          - package: '@discordjs/proxy'
+            folder: 'proxy'
+          - package: '@discordjs/rest'
+            folder: 'rest'
+          - package: '@discordjs/util'
+            folder: 'util'
+          - package: '@discordjs/voice'
+            folder: 'voice'
+          - package: '@discordjs/ws'
+            folder: 'ws'
     runs-on: ubuntu-latest
+    permissions:
+      id-token: write
+    env:
+      TURBO_TOKEN: ${{ secrets.TURBO_TOKEN }}
+      TURBO_TEAM: ${{ secrets.TURBO_TEAM }}
     if: github.repository_owner == 'discordjs'
     steps:
       - name: Checkout repository
-        uses: actions/checkout@v2
-
-      - name: Install node.js v16
-        uses: actions/setup-node@v2
+        uses: actions/checkout@v4
         with:
-          node-version: 16
+          fetch-depth: 0
+
+      - name: Install Node.js v20
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20
           registry-url: https://registry.npmjs.org/
-          cache: 'yarn'
-          cache-dependency-path: yarn.lock
 
-      - name: Turbo cache
-        id: turbo-cache
-        uses: actions/cache@v2
-        with:
-          path: .turbo
-          key: turbo-${{ github.job }}-${{ github.ref_name }}-${{ github.sha }}
-          restore-keys: |
-            turbo-${{ github.job }}-${{ github.ref_name }}-
-
-      - name: Check previous released version
-        id: pre-release
+      - name: Check the current development version
+        id: release-check
         run: |
-          if [[ $(npm view discord.js@dev version | grep -e "$(jq --raw-output '.version' packages/discord.js/package.json).*.$(git rev-parse --short HEAD | cut -b1-3)") ]]; \
-          then echo '::set-output name=release::false'; \
-          else echo '::set-output name=release::true'; fi
+          if [[ $(npm view ${{ matrix.package }}@dev version | grep -e "$(git rev-parse --short HEAD)") ]]; \
+            then echo "RELEASE=0" >> "$GITHUB_OUTPUT"; \
+            else echo "RELEASE=1" >> "$GITHUB_OUTPUT"; \
+          fi
 
       - name: Install dependencies
-        if: steps.pre-release.outputs.release == 'true'
-        run: yarn --immutable
+        if: steps.release-check.outputs.release == '1'
+        uses: ./packages/actions/src/pnpmCache
 
       - name: Build dependencies
-        if: steps.pre-release.outputs.release == 'true'
-        run: yarn build --cache-dir=".turbo"
+        if: steps.release-check.outputs.release == '1'
+        run: pnpm run build
 
-      - name: Deprecate old versions
-        if: steps.pre-release.outputs.release == 'true'
-        run: npm deprecate discord.js@"~$(jq --raw-output '.version' packages/discord.js/package.json)" "no longer supported" || true
-        env:
-          NODE_AUTH_TOKEN: ${{ secrets.NPM_PUBLISH_TOKEN }}
-
-      - name: Publish
-        if: steps.pre-release.outputs.release == 'true'
+      - name: Publish package
+        if: steps.release-check.outputs.release == '1'
         run: |
-          yarn workspace discord.js version --no-git-tag-version --new-version $(jq --raw-output '.version' packages/discord.js/package.json).$(date +%s).$(git rev-parse --short HEAD)
-          yarn workspace discord.js publish --tag dev || true
+          pnpm --filter=${{ matrix.package }} run release --preid "dev.$(date +%s)-$(git rev-parse --short HEAD)" --skip-changelog
+          pnpm --filter=${{ matrix.package }} publish --provenance --no-git-checks --tag dev || true
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_PUBLISH_TOKEN }}
+
+      - name: Deprecate prior development releases
+        if: steps.release-check.outputs.release == '1'
+        run: pnpm exec npm-deprecate --name "*dev*" --message "This version is deprecated. Please use a newer version." --package ${{ matrix.package }}
         env:
           NODE_AUTH_TOKEN: ${{ secrets.NPM_PUBLISH_TOKEN }}

.github/workflows/publish-docker.yml

@@ -0,0 +1,27 @@
+name: Publish docker images
+on:
+  workflow_dispatch:
+jobs:
+  docker-publish:
+    name: Docker publish
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Install Node.js v20
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20
+
+      - name: Install dependencies
+        uses: ./packages/actions/src/pnpmCache
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v3
+
+      - name: Login to DockerHub
+        run: echo ${{ secrets.DOCKER_ACCESS_TOKEN }} | docker login -u ${{ secrets.DOCKER_USERNAME }} --password-stdin
+
+      - name: Build & push docker image
+        run: docker build -f packages/proxy-container/Dockerfile -t discordjs/proxy:$(cut -d '.' -f1 <<< $(jq --raw-output '.version' packages/proxy-container/package.json)) --push .

.github/workflows/publish-release.yml

@@ -0,0 +1,41 @@
+name: Publish Release
+on:
+  release:
+    types: [released]
+jobs:
+  npm-publish:
+    name: npm publish
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write
+    env:
+      TURBO_TOKEN: ${{ secrets.TURBO_TOKEN }}
+      TURBO_TEAM: ${{ secrets.TURBO_TEAM }}
+    if: github.repository_owner == 'discordjs'
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Install Node.js v20
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          registry-url: https://registry.npmjs.org/
+
+      - name: Install dependencies
+        uses: ./packages/actions/src/pnpmCache
+
+      - name: Build dependencies
+        run: pnpm run build
+
+      - name: Extract package and semver from tag
+        id: extract-tag
+        uses: ./packages/actions/src/formatTag
+        with:
+          tag: ${{ github.ref_name }}
+
+      - name: Publish package
+        run: |
+          pnpm --filter=${{ steps.extract-tag.outputs.subpackage == 'true' && '@discordjs/' || '' }}${{ steps.extract-tag.outputs.package }} publish --provenance --no-git-checks
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_PUBLISH_TOKEN }}

.github/workflows/test.yml

@@ -1,37 +0,0 @@
-name: Tests
-on: [push, pull_request]
-jobs:
-  lint:
-    name: Lint
-    runs-on: ubuntu-latest
-    steps:
-      - name: Checkout repository
-        uses: actions/checkout@v2
-
-      - name: Install node.js v16
-        uses: actions/setup-node@v2
-        with:
-          node-version: 16
-          cache: 'yarn'
-          cache-dependency-path: yarn.lock
-
-      - name: Turbo cache
-        id: turbo-cache
-        uses: actions/cache@v2
-        with:
-          path: .turbo
-          key: turbo-${{ github.job }}-${{ github.ref_name }}-${{ github.sha }}
-          restore-keys: |
-            turbo-${{ github.job }}-${{ github.ref_name }}-
-
-      - name: Install dependencies
-        run: yarn --immutable
-
-      - name: ESLint
-        run: yarn lint --cache-dir=".turbo"
-
-      - name: Tests
-        run: yarn test --cache-dir=".turbo"
-
-      - name: Build
-        run: yarn build --cache-dir=".turbo"

.github/workflows/tests.yml

@@ -0,0 +1,66 @@
+name: Tests
+on:
+  push:
+  pull_request:
+concurrency:
+  # Group based on workflow name and PR if it exists, if no PR, let it run so carryforward flags work
+  group: ${{ github.workflow }}-${{ github.head_ref || github.run_id }}
+  cancel-in-progress: true
+jobs:
+  tests:
+    name: Tests
+    runs-on: ubuntu-latest
+    env:
+      TURBO_TOKEN: ${{ secrets.TURBO_TOKEN }}
+      TURBO_TEAM: ${{ secrets.TURBO_TEAM }}
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Install Node.js v20
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20
+
+      - name: Install dependencies
+        uses: ./packages/actions/src/pnpmCache
+
+      - name: Build dependencies (PR)
+        if: ${{ github.event_name != 'push' }}
+        run: pnpm exec turbo run build --filter="...[origin/${{ github.event_name == 'pull_request' && github.event.pull_request.base.ref || 'main' }}]" --concurrency=4
+
+      - name: Build dependencies (Push)
+        if: ${{ github.event_name == 'push' }}
+        run: pnpm exec turbo run build --filter="...[HEAD^1]" --concurrency=4
+
+      - name: Tests (PR)
+        if: ${{ github.event_name != 'push' }}
+        run: pnpm exec turbo run test --filter="...[origin/${{ github.event_name == 'pull_request' && github.event.pull_request.base.ref || 'main' }}]" --concurrency=4
+
+      - name: Tests (Push)
+        if: ${{ github.event_name == 'push' }}
+        run: pnpm exec turbo run test --filter="...[HEAD^1]" --concurrency=4
+
+      - name: ESLint (PR)
+        if: ${{ github.event_name != 'push' }}
+        run: pnpm exec turbo run lint --filter="...[origin/${{ github.event_name == 'pull_request' && github.event.pull_request.base.ref || 'main' }}]" --concurrency=4 -- --format=compact
+
+      - name: ESLint (Push)
+        if: ${{ github.event_name == 'push' }}
+        run: pnpm exec turbo run lint --filter="...[HEAD^1]" --concurrency=4 -- --format=compact
+
+      - name: Docs (PR)
+        if: ${{ github.event_name != 'push' }}
+        run: pnpm exec turbo run docs --filter="...[origin/${{ github.event_name == 'pull_request' && github.event.pull_request.base.ref || 'main' }}]" --concurrency=4
+
+      - name: Docs (Push)
+        if: ${{ github.event_name == 'push' }}
+        run: pnpm exec turbo run docs --filter="...[HEAD^1]" --concurrency=4
+
+      - name: Upload Coverage
+        if: github.repository_owner == 'discordjs'
+        uses: ./packages/actions/src/uploadCoverage
+        with:
+          codecov_token: ${{ secrets.CODECOV_TOKEN }}

.gitignore

@@ -1,8 +1,8 @@
 # Packages
-node_modules/
+node_modules
 
 # Log files
-logs/
+logs
 *.log
 npm-debug.log*
 
@@ -15,14 +15,40 @@ pids
 .env
 
 # Dist
-dist/
+dist
+dist-docs
 
 # Miscellaneous
-.tmp/
+.tmp
 .vscode/*
 !.vscode/extensions.json
 !.vscode/settings.json
-.idea/
+.idea
 .DS_Store
 .turbo
 tsconfig.tsbuildinfo
+coverage
+out
+package.tgz
+tsup.config.bundled*
+vitest.config.ts.timestamp*
+
+# Deno
+deno.lock
+
+# Bun
+bun.lockb
+
+# yarn
+.pnp.*
+.yarn/*
+!.yarn/patches
+!.yarn/plugins
+!.yarn/releases
+!.yarn/sdks
+!.yarn/versions
+
+# Cache
+.prettiercache
+.eslintcache
+.vercel

.husky/commit-msg

@@ -1,4 +1 @@
-#!/bin/sh
-. "$(dirname "$0")/_/husky.sh"
-
-yarn commitlint --edit $1
+pnpm exec commitlint --edit $1

.husky/pre-commit

@@ -1,4 +1 @@
-#!/bin/sh
-. "$(dirname "$0")/_/husky.sh"
-
-yarn format
+pnpm run build:affected && pnpm exec lint-staged

.lintstagedrc.json

@@ -0,0 +1,6 @@
+{
+	"$schema": "https://json.schemastore.org/lintstagedrc.schema.json",
+	"*": "prettier --ignore-unknown --write",
+	"{src/**,__tests__/**}.{mjs,js,cjs,ts,tsx}": "eslint --fix",
+	"src/**.ts": "vitest related --run --config ../../vitest.config.ts"
+}

.npmrc

@@ -0,0 +1,6 @@
+auto-install-peers=false
+resolution-mode=highest
+public-hoist-pattern[]=*eslint*
+public-hoist-pattern[]=*prettier*
+public-hoist-pattern[]=*@rushstack/node-core-library*
+public-hoist-pattern[]=*jju*

.prettierignore

@@ -0,0 +1,5 @@
+CODEOWNERS
+CHANGELOG.md
+tsup.config.bundled*
+vitest.config.ts.timestamp*
+pnpm-lock.yaml

.prettierrc.json

@@ -1,4 +1,5 @@
 {
+	"$schema": "https://json.schemastore.org/prettierrc.json",
 	"printWidth": 120,
 	"useTabs": true,
 	"singleQuote": true,

.vscode/extensions.json

@@ -7,6 +7,7 @@
 		"codezombiech.gitignore",
 		"eamodio.gitlens",
 		"christian-kohler.npm-intellisense",
-		"christian-kohler.path-intellisense"
+		"christian-kohler.path-intellisense",
+		"unifiedjs.vscode-mdx"
 	]
 }

.vscode/settings.json

@@ -1,9 +1,31 @@
 {
-	"eslint.workingDirectories": [{ "pattern": "./packages/*" }],
+	"eslint.validate": ["javascript", "javascriptreact", "typescript", "typescriptreact"],
+	"eslint.useFlatConfig": true,
+	"eslint.workingDirectories": [{ "directory": "${workspaceFolder}" }, { "pattern": "./packages/*/" }],
 	"editor.defaultFormatter": "esbenp.prettier-vscode",
 	"editor.formatOnSave": true,
 	"editor.codeActionsOnSave": {
-		"source.fixAll": true,
-		"source.organizeImports": false
-	}
+		"source.organizeImports": "never",
+		"source.fixAll.eslint": "explicit",
+		"source.fixAll": "explicit"
+	},
+	"editor.trimAutoWhitespace": false,
+	"files.associations": {
+		"api-extractor.json": "jsonc",
+		"api-extractor-docs.json": "jsonc",
+		"tsconfig.json": "jsonc",
+		"tsconfig.eslint.json": "jsonc",
+		"tsconfig.docs.json": "jsonc"
+	},
+	"files.insertFinalNewline": true,
+	"files.eol": "\n",
+	"npm.packageManager": "pnpm",
+	"typescript.tsdk": "node_modules/typescript/lib",
+	"typescript.enablePromptUseWorkspaceTsdk": true,
+	"unocss.disable": true,
+	"deno.enable": false,
+	"deno.enablePaths": ["./packages/create-discord-bot/template/Deno"],
+	"deno.lint": false,
+	"deno.unstable": [],
+	"deno.config": "./packages/create-discord-bot/template/Deno/deno.jsonc"
 }

LICENSE

@@ -0,0 +1,191 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   Copyright 2021 Noel Buechler
+   Copyright 2015 Amish Shah
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

README.md

@@ -1,127 +1,89 @@
 <div align="center">
-  <br />
-  <p>
-    <a href="https://discord.js.org"><img src="https://discord.js.org/static/logo.svg" width="546" alt="discord.js" /></a>
-  </p>
-  <br />
-  <p>
-    <a href="https://discord.gg/djs"><img src="https://img.shields.io/discord/222078108977594368?color=5865F2&logo=discord&logoColor=white" alt="Discord server" /></a>
-    <a href="https://www.npmjs.com/package/discord.js"><img src="https://img.shields.io/npm/v/discord.js.svg?maxAge=3600" alt="npm version" /></a>
-    <a href="https://www.npmjs.com/package/discord.js"><img src="https://img.shields.io/npm/dt/discord.js.svg?maxAge=3600" alt="npm downloads" /></a>
-    <a href="https://github.com/discordjs/discord.js/actions"><img src="https://github.com/discordjs/discord.js/actions/workflows/test.yml/badge.svg" alt="Tests status" /></a>
-  </p>
+	<br />
+	<p>
+		<a href="https://discord.js.org"><img src="https://discord.js.org/static/logo.svg" width="546" alt="discord.js" /></a>
+	</p>
+	<br />
+	<p>
+		<a href="https://discord.gg/djs"><img src="https://img.shields.io/discord/222078108977594368?color=5865F2&logo=discord&logoColor=white" alt="Discord server" /></a>
+		<a href="https://www.npmjs.com/package/discord.js"><img src="https://img.shields.io/npm/v/discord.js.svg?maxAge=3600" alt="npm version" /></a>
+		<a href="https://www.npmjs.com/package/discord.js"><img src="https://img.shields.io/npm/dt/discord.js.svg?maxAge=3600" alt="npm downloads" /></a>
+		<a href="https://github.com/discordjs/discord.js/actions"><img src="https://github.com/discordjs/discord.js/actions/workflows/test.yml/badge.svg" alt="Tests status" /></a>
+		<a href="https://github.com/discordjs/discord.js/commits/main"><img src="https://img.shields.io/github/last-commit/discordjs/discord.js.svg?logo=github&logoColor=ffffff" alt="Last commit." /></a>
+		<a href="https://github.com/discordjs/discord.js/graphs/contributors"><img src="https://img.shields.io/github/contributors/discordjs/discord.js.svg?maxAge=3600&logo=github&logoColor=fff&color=00c7be" alt="contributors" /></a>
+		<a href="https://codecov.io/gh/discordjs/discord.js"><img src="https://codecov.io/gh/discordjs/discord.js/branch/main/graph/badge.svg?precision=2" alt="Code coverage" /></a>
+	</p>
+	<p>
+		<a href="https://vercel.com/?utm_source=discordjs&utm_campaign=oss"><img src="https://raw.githubusercontent.com/discordjs/discord.js/main/.github/powered-by-vercel.svg" alt="Vercel" /></a>
+		<a href="https://www.cloudflare.com"><img src="https://raw.githubusercontent.com/discordjs/discord.js/main/.github/powered-by-workers.png" alt="Cloudflare Workers" height="44" /></a>
+	</p>
 </div>
 
 ## About
 
-discord.js is a powerful [Node.js](https://nodejs.org) module that allows you to easily interact with the
-[Discord API](https://discord.com/developers/docs/intro).
+This repository contains multiple packages with separate [releases][github-releases]. You can find the assembled Discord API wrapper at [`discord.js`][source]. It is a powerful [Node.js](https://nodejs.org/en) module that allows you to easily interact with the [Discord API](https://discord.com/developers/docs/intro).
 
-- Object-oriented
-- Predictable abstractions
-- Performant
-- 100% coverage of the Discord API
+## Packages
 
-## Installation
-
-**Node.js 16.9.0 or newer is required.**
-
-```sh-session
-npm install discord.js
-yarn add discord.js
-pnpm add discord.js
-```
-
-### Optional packages
-
-- [zlib-sync](https://www.npmjs.com/package/zlib-sync) for WebSocket data compression and inflation (`npm install zlib-sync`)
-- [erlpack](https://github.com/discord/erlpack) for significantly faster WebSocket data (de)serialisation (`npm install discord/erlpack`)
-- [bufferutil](https://www.npmjs.com/package/bufferutil) for a much faster WebSocket connection (`npm install bufferutil`)
-- [utf-8-validate](https://www.npmjs.com/package/utf-8-validate) in combination with `bufferutil` for much faster WebSocket processing (`npm install utf-8-validate`)
-- [@discordjs/voice](https://www.npmjs.com/package/@discordjs/voice) for interacting with the Discord Voice API (`npm install @discordjs/voice`)
-
-## Example usage
-
-Install all required dependencies:
-
-```sh-session
-npm install discord.js @discordjs/rest discord-api-types
-yarn add discord.js @discordjs/rest discord-api-types
-pnpm add discord.js @discordjs/rest discord-api-types
-```
-
-Register a slash command against the Discord API:
-
-```js
-const { REST } = require('@discordjs/rest');
-const { Routes } = require('discord-api-types/v9');
-
-const commands = [
-	{
-		name: 'ping',
-		description: 'Replies with Pong!',
-	},
-];
-
-const rest = new REST({ version: '9' }).setToken('token');
-
-(async () => {
-	try {
-		console.log('Started refreshing application (/) commands.');
-
-		await rest.put(Routes.applicationGuildCommands(CLIENT_ID, GUILD_ID), { body: commands });
-
-		console.log('Successfully reloaded application (/) commands.');
-	} catch (error) {
-		console.error(error);
-	}
-})();
-```
-
-Afterwards we can create a quite simple example bot:
-
-```js
-const { Client, Intents } = require('discord.js');
-const client = new Client({ intents: [Intents.FLAGS.GUILDS] });
-
-client.on('ready', () => {
-	console.log(`Logged in as ${client.user.tag}!`);
-});
-
-client.on('interactionCreate', async (interaction) => {
-	if (!interaction.isCommand()) return;
-
-	if (interaction.commandName === 'ping') {
-		await interaction.reply('Pong!');
-	}
-});
-
-client.login('token');
-```
+- `discord.js` ([source][source]) - A powerful Node.js module for interacting with the Discord API
+- `@discordjs/brokers` ([source][brokers-source]) - A collection of brokers for use with discord.js
+- `@discordjs/builders` ([source][builders-source]) - A utility package for easily building Discord API payloads
+- `@discordjs/collection` ([source][collection-source]) - A powerful utility data structure
+- `@discordjs/core` ([source][core-source]) - A thinly abstracted wrapper around the core components of the Discord API
+- `@discordjs/formatters` ([source][formatters-source]) - A collection of functions for formatting strings
+- `@discordjs/proxy` ([source][proxy-source]) - A wrapper around `@discordjs/rest` for running an HTTP proxy
+- `@discordjs/rest` ([source][rest-source]) - A module for interacting with the Discord REST API
+- `@discordjs/voice` ([source][voice-source]) - A module for interacting with the Discord Voice API
+- `@discordjs/util` ([source][util-source]) - A collection of utility functions
+- `@discordjs/ws` ([source][ws-source]) - A wrapper around Discord's gateway
 
 ## Links
 
-- [Website](https://discord.js.org/) ([source](https://github.com/discordjs/website))
-- [Documentation](https://discord.js.org/#/docs)
-- [Guide](https://discordjs.guide/) ([source](https://github.com/discordjs/guide))
-  See also the [Update Guide](https://discordjs.guide/additional-info/changes-in-v13.html), including updated and removed items in the library.
-- [discord.js Discord server](https://discord.gg/djs)
-- [Discord API Discord server](https://discord.gg/discord-api)
-- [GitHub](https://github.com/discordjs/discord.js)
-- [npm](https://www.npmjs.com/package/discord.js)
-- [Related libraries](https://discord.com/developers/docs/topics/community-resources#libraries)
+- [Website][website] ([source][website-source])
+- [Documentation][documentation]
+- [Guide][guide] ([source][guide-source])
+  Also see the v13 to v14 [Update Guide][guide-update], which includes updated and removed items from the library.
+- [discord.js Discord server][discord]
+- [Discord API Discord server][discord-api]
+- [GitHub][source]
+- [npm][npm]
+- [Related libraries][related-libs]
 
 ### Extensions
 
-- [RPC](https://www.npmjs.com/package/discord-rpc) ([source](https://github.com/discordjs/RPC))
+- [RPC][rpc] ([source][rpc-source])
 
 ## Contributing
 
-Before creating an issue, please ensure that it hasn't already been reported/suggested, and double-check the
-[documentation](https://discord.js.org/#/docs).  
-See [the contribution guide](https://github.com/discordjs/discord.js/blob/main/.github/CONTRIBUTING.md) if you'd like to submit a PR.
+Please read through our [contribution guidelines][contributing] before starting a pull request. We welcome contributions of all kinds, not just code! If you're stuck for ideas, look for the [good first issue][good-first-issue] label on issues in the repository. If you have any questions about the project, feel free to ask them on [Discord][discord]. Before creating your own issue or pull request, always check to see if one already exists! Don't rush contributions, take your time and ensure you're doing it correctly.
 
 ## Help
 
-If you don't understand something in the documentation, you are experiencing problems, or you just need a gentle
-nudge in the right direction, please don't hesitate to join our official [discord.js Server](https://discord.gg/djs).
+If you don't understand something in the documentation, you are experiencing problems, or you just need a gentle nudge in the right direction, please join our [Discord server][discord].
+
+[website]: https://discord.js.org
+[website-source]: https://github.com/discordjs/discord.js/tree/main/apps/website
+[documentation]: https://discord.js.org/docs
+[guide]: https://discordjs.guide/
+[guide-source]: https://github.com/discordjs/guide
+[guide-update]: https://discordjs.guide/additional-info/changes-in-v14.html
+[discord]: https://discord.gg/djs
+[discord-api]: https://discord.gg/discord-api
+[source]: https://github.com/discordjs/discord.js/tree/main/packages/discord.js
+[npm]: https://www.npmjs.com/package/discord.js
+[related-libs]: https://discord.com/developers/docs/topics/community-resources#libraries
+[rpc]: https://www.npmjs.com/package/discord-rpc
+[rpc-source]: https://github.com/discordjs/RPC
+[contributing]: https://github.com/discordjs/discord.js/blob/main/.github/CONTRIBUTING.md
+[github-releases]: https://github.com/discordjs/discord.js/releases
+[brokers-source]: https://github.com/discordjs/discord.js/tree/main/packages/brokers
+[builders-source]: https://github.com/discordjs/discord.js/tree/main/packages/builders
+[collection-source]: https://github.com/discordjs/discord.js/tree/main/packages/collection
+[core-source]: https://github.com/discordjs/discord.js/tree/main/packages/core
+[formatters-source]: https://github.com/discordjs/discord.js/tree/main/packages/formatters
+[proxy-source]: https://github.com/discordjs/discord.js/tree/main/packages/proxy
+[rest-source]: https://github.com/discordjs/discord.js/tree/main/packages/rest
+[voice-source]: https://github.com/discordjs/discord.js/tree/main/packages/voice
+[util-source]: https://github.com/discordjs/discord.js/tree/main/packages/util
+[ws-source]: https://github.com/discordjs/discord.js/tree/main/packages/ws
+[good-first-issue]: https://github.com/discordjs/discord.js/contribute

api-extractor.json

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

biome.json

@@ -0,0 +1,36 @@
+{
+	"$schema": "https://biomejs.dev/schemas/1.5.3/schema.json",
+	"formatter": {
+		"enabled": true,
+		"formatWithErrors": false,
+		"indentStyle": "tab",
+		"indentWidth": 2,
+		"lineWidth": 120,
+		"lineEnding": "lf",
+		"ignore": [
+			".turbo",
+			".vercel",
+			".contentlayer",
+			".next",
+			"coverage",
+			"dist",
+			"dist-docs",
+			"docs",
+			"CHANGELOG.md",
+			"tsup.config.bundled*"
+		]
+	},
+	"javascript": {
+		"formatter": {
+			"enabled": true,
+			"quoteStyle": "single",
+			"quoteProperties": "asNeeded",
+			"trailingComma": "all",
+			"semicolons": "always"
+		}
+	},
+	"files": {
+		"ignoreUnknown": true,
+		"maxSize": 1000000
+	}
+}

codecov.yml

@@ -0,0 +1,27 @@
+codecov:
+  notify:
+    after_n_builds: 6
+  strict_yaml_branch: main
+
+coverage:
+  range: '50...90'
+  status:
+    project:
+      default:
+        target: auto
+        threshold: 5%
+        informational: true
+    patch: off
+
+flag_management:
+  default_rules:
+    carryforward: true
+    statuses:
+      - type: project
+        target: auto
+        threshold: 2%
+        informational: true
+
+comment:
+  require_changes: true
+  after_n_builds: 6

eslint.config.js

@@ -0,0 +1,139 @@
+import unocss from '@unocss/eslint-plugin';
+import common from 'eslint-config-neon/flat/common.js';
+import edge from 'eslint-config-neon/flat/edge.js';
+import next from 'eslint-config-neon/flat/next.js';
+import node from 'eslint-config-neon/flat/node.js';
+import prettier from 'eslint-config-neon/flat/prettier.js';
+import react from 'eslint-config-neon/flat/react.js';
+import typescript from 'eslint-config-neon/flat/typescript.js';
+// import oxlint from 'eslint-plugin-oxlint';
+import merge from 'lodash.merge';
+import tseslint from 'typescript-eslint';
+
+const commonFiles = '{js,mjs,cjs,ts,mts,cts,jsx,tsx}';
+
+const commonRuleset = merge(...common, { files: [`**/*${commonFiles}`] });
+
+const nodeRuleset = merge(...node, { files: [`**/*${commonFiles}`] });
+
+const typeScriptRuleset = merge(...typescript, {
+	files: [`**/*${commonFiles}`],
+	languageOptions: {
+		parserOptions: {
+			warnOnUnsupportedTypeScriptVersion: false,
+			allowAutomaticSingleRunInference: true,
+			project: ['tsconfig.eslint.json', 'packages/*/tsconfig.eslint.json'],
+		},
+	},
+	rules: {
+		'@typescript-eslint/consistent-type-definitions': [2, 'interface'],
+		'@typescript-eslint/naming-convention': [
+			2,
+			{
+				selector: 'typeParameter',
+				format: ['PascalCase'],
+				custom: {
+					regex: '^\\w{3,}',
+					match: true,
+				},
+			},
+		],
+	},
+	settings: {
+		'import/resolver': {
+			typescript: {
+				project: ['tsconfig.eslint.json', 'packages/*/tsconfig.eslint.json'],
+			},
+		},
+	},
+});
+
+const reactRuleset = merge(...react, {
+	files: [`packages/ui/**/*${commonFiles}`],
+	rules: {
+		'@next/next/no-html-link-for-pages': 0,
+		'react/react-in-jsx-scope': 0,
+		'react/jsx-filename-extension': [1, { extensions: ['.tsx'] }],
+	},
+});
+
+const prettierRuleset = merge(...prettier, { files: [`**/*${commonFiles}`] });
+
+// const oxlintRuleset = merge({ rules: oxlint.rules }, { files: [`**/*${commonFiles}`] });
+
+export default tseslint.config(
+	{
+		ignores: [
+			'**/node_modules/',
+			'.git/',
+			'**/dist/',
+			'**/template/',
+			'**/coverage/',
+			'**/storybook-static/',
+			'**/.next/',
+			'packages/discord.js/',
+		],
+	},
+	commonRuleset,
+	nodeRuleset,
+	typeScriptRuleset,
+	{
+		files: ['**/*{ts,mts,cts,tsx}'],
+		rules: { 'jsdoc/no-undefined-types': 0 },
+	},
+	{
+		files: [`packages/{api-extractor,brokers,create-discord-bot,docgen,ws}/**/*${commonFiles}`],
+		rules: { 'n/no-sync': 0 },
+	},
+	{
+		files: [`packages/rest/**/*${commonFiles}`],
+		rules: {
+			'n/prefer-global/url': 0,
+			'n/prefer-global/url-search-params': 0,
+			'n/prefer-global/buffer': 0,
+			'n/prefer-global/process': 0,
+			'no-restricted-globals': 0,
+			'unicorn/prefer-node-protocol': 0,
+		},
+	},
+	{
+		files: [`packages/voice/**/*${commonFiles}`],
+		rules: { 'no-restricted-globals': 0 },
+	},
+	{
+		files: [`packages/api-extractor-model/**/*${commonFiles}`],
+		rules: {
+			'@typescript-eslint/no-namespace': 0,
+			'no-prototype-builtins': 0,
+			'consistent-this': 0,
+			'unicorn/no-this-assignment': 0,
+			'@typescript-eslint/no-this-alias': 0,
+		},
+	},
+	{
+		files: [`packages/api-extractor/**/*${commonFiles}`],
+		rules: {
+			'consistent-this': 0,
+			'unicorn/no-this-assignment': 0,
+			'@typescript-eslint/no-this-alias': 0,
+		},
+	},
+	{
+		files: [`packages/{api-extractor,api-extractor-model,api-extractor-utils}/**/*${commonFiles}`],
+		rules: { '@typescript-eslint/naming-convention': 0 },
+	},
+	reactRuleset,
+	{
+		files: [`packages/ui/**/*${commonFiles}`],
+		plugins: { '@unocss': unocss },
+		rules: {
+			'@unocss/order': 2,
+		},
+	},
+	{
+		files: ['**/*{js,mjs,cjs,jsx}'],
+		rules: { 'tsdoc/syntax': 0 },
+	},
+	prettierRuleset,
+	// oxlintRuleset,
+);

package.json

@@ -1,25 +1,34 @@
 {
+	"$schema": "https://json.schemastore.org/package.json",
 	"name": "@discordjs/discord.js",
 	"version": "0.0.0",
 	"description": "A powerful library for interacting with the Discord API",
 	"private": true,
 	"scripts": {
-		"build": "turbo run build",
-		"test": "turbo run test",
-		"lint": "turbo run lint",
-		"format": "turbo run format",
-		"fmt": "turbo run format",
-		"postinstall": "is-ci || husky install",
-		"docs": "turbo run docs",
-		"changelog": "turbo run changelog",
-		"update": "yarn upgrade-interactive --latest"
+		"build": "turbo run build --concurrency=4",
+		"build:affected": "turbo run build --filter=...[origin/v14] --concurrency=4",
+		"test": "turbo run test --concurrency=4",
+		"test:affected": "turbo run test --filter=...[origin/v14] --concurrency=4",
+		"lint": "turbo run lint --concurrency=4",
+		"lint:affected": "turbo run lint --filter=...[origin/v14] --concurrency=4",
+		"format": "turbo run format --concurrency=4",
+		"format:affected": "turbo run format --filter=...[origin/v14] --concurrency=4",
+		"fmt": "turbo run format --concurrency=4",
+		"fmt:affected": "turbo run format --filter=...[origin/v14] --concurrency=4",
+		"docs": "turbo run docs --concurrency=4",
+		"docs:affected": "turbo run docs --filter=...[origin/v14] --concurrency=4",
+		"prepare": "is-ci || husky",
+		"update": "pnpm --recursive update --interactive",
+		"update:latest": "pnpm --recursive update --interactive --latest",
+		"create-package": "turbo gen create-package --args"
 	},
+	"type": "module",
 	"contributors": [
 		"Crawl <icrawltogo@gmail.com>",
 		"Amish Shah <amishshah.2k@gmail.com>",
-		"Vlad Frangu <kingdgrizzle@gmail.com>",
+		"Vlad Frangu <me@vladfrangu.dev>",
 		"SpaceEEC <spaceeec@yahoo.com>",
-		"Antonio Roman <kyradiscord@gmail.com>"
+		"Aura Román <kyradiscord@gmail.com>"
 	],
 	"keywords": [
 		"discord",
@@ -37,66 +46,54 @@
 		"url": "https://github.com/discordjs/discord.js/issues"
 	},
 	"homepage": "https://discord.js.org",
+	"funding": "https://github.com/discordjs/discord.js?sponsor",
 	"devDependencies": {
-		"@commitlint/cli": "^16.1.0",
-		"@commitlint/config-angular": "^16.0.0",
-		"@favware/npm-deprecate": "^1.0.4",
-		"conventional-changelog-cli": "^2.2.2",
-		"husky": "^7.0.4",
-		"prettier": "^2.5.1",
-		"turbo": "1.0.28"
+		"@commitlint/cli": "^19.4.0",
+		"@commitlint/config-angular": "^19.3.0",
+		"@favware/cliff-jumper": "^4.1.0",
+		"@favware/npm-deprecate": "^1.0.7",
+		"@types/lodash.merge": "^4.6.9",
+		"@unocss/eslint-plugin": "^0.59.4",
+		"@vitest/coverage-v8": "^2.0.5",
+		"conventional-changelog-cli": "^4.1.0",
+		"eslint": "^8.57.0",
+		"eslint-config-neon": "^0.1.62",
+		"husky": "^9.1.5",
+		"is-ci": "^3.0.1",
+		"lint-staged": "^15.2.9",
+		"lodash.merge": "^4.6.2",
+		"prettier": "^3.3.3",
+		"tsup": "^8.2.4",
+		"turbo": "^2.0.14",
+		"typescript": "~5.5.4",
+		"typescript-eslint": "^8.2.0",
+		"unocss": "^0.60.4",
+		"vercel": "^37.0.0",
+		"vitest": "^2.0.5"
+	},
+	"pnpm": {
+		"peerDependencyRules": {
+			"ignoreMissing": [
+				"*"
+			],
+			"allowedAny": [
+				"*"
+			]
+		},
+		"overrides": {
+			"@contentlayer/utils>@opentelemetry/core": "^1.15.1",
+			"@contentlayer/utils>@opentelemetry/exporter-trace-otlp-grpc": "^0.41.1",
+			"@contentlayer/utils>@opentelemetry/resources": "^1.15.1",
+			"@contentlayer/utils>@opentelemetry/sdk-trace-base": "^1.15.1",
+			"@contentlayer/utils>@opentelemetry/sdk-trace-node": "^1.15.1",
+			"@contentlayer/utils>@opentelemetry/semantic-conventions": "^1.15.1"
+		},
+		"patchedDependencies": {
+			"@microsoft/tsdoc-config@0.16.2": "patches/@microsoft__tsdoc-config@0.16.2.patch"
+		}
 	},
 	"engines": {
-		"node": ">=16.9.0"
+		"node": ">=18"
 	},
-	"workspaces": [
-		"packages/*"
-	],
-	"turbo": {
-		"baseBranch": "origin/main",
-		"pipeline": {
-			"build": {
-				"dependsOn": [
-					"^build"
-				],
-				"outputs": [
-					"dist/**",
-					"docs/docs.json"
-				]
-			},
-			"test": {
-				"dependsOn": [
-					"^build"
-				],
-				"outputs": [
-					"coverage/**"
-				]
-			},
-			"lint": {
-				"dependsOn": [
-					"^build"
-				],
-				"outputs": []
-			},
-			"format": {
-				"outputs": []
-			},
-			"docs": {
-				"dependsOn": [
-					"^build"
-				],
-				"outputs": [
-					"docs/docs.json"
-				]
-			},
-			"changelog": {
-				"dependsOn": [
-					"^build"
-				],
-				"outputs": [
-					"CHANGELOG.md"
-				]
-			}
-		}
-	}
+	"packageManager": "pnpm@9.8.0"
 }

packages/actions/.gitignore

@@ -0,0 +1,23 @@
+# Packages
+node_modules
+
+# Log files
+logs
+*.log
+npm-debug.log*
+
+# Runtime data
+pids
+*.pid
+*.seed
+
+# Env
+.env
+
+# Dist
+dist
+
+# Miscellaneous
+.turbo
+.tmp
+coverage

packages/actions/.lintstagedrc.cjs

@@ -0,0 +1,2 @@
+/** @type {import('lint-staged').Config} */
+module.exports = require('../../.lintstagedrc.json');

packages/actions/.prettierignore

@@ -0,0 +1,4 @@
+.turbo
+coverage
+dist
+tsup.config.bundled*

packages/actions/.prettierrc.cjs

@@ -0,0 +1,2 @@
+/** @type {import('prettier').Config} */
+module.exports = require('../../.prettierrc.json');

packages/actions/LICENSE

@@ -0,0 +1,190 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   Copyright 2022 Noel Buechler
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

packages/actions/README.md

@@ -0,0 +1,45 @@
+<div align="center">
+	<br />
+	<p>
+		<a href="https://discord.js.org"><img src="https://discord.js.org/static/logo.svg" width="546" alt="discord.js" /></a>
+	</p>
+	<br />
+	<p>
+		<a href="https://discord.gg/djs"><img src="https://img.shields.io/discord/222078108977594368?color=5865F2&logo=discord&logoColor=white" alt="Discord server" /></a>
+		<a href="https://github.com/discordjs/discord.js/actions"><img src="https://github.com/discordjs/discord.js/actions/workflows/test.yml/badge.svg" alt="Build status" /></a>
+	</p>
+	<p>
+		<a href="https://vercel.com/?utm_source=discordjs&utm_campaign=oss"><img src="https://raw.githubusercontent.com/discordjs/discord.js/main/.github/powered-by-vercel.svg" alt="Vercel" /></a>
+		<a href="https://www.cloudflare.com"><img src="https://raw.githubusercontent.com/discordjs/discord.js/main/.github/powered-by-workers.png" alt="Cloudflare Workers" height="44" /></a>
+	</p>
+</div>
+
+## Links
+
+- [Website][website] ([source][website-source])
+- [Guide][guide] ([source][guide-source])
+  Also see the v13 to v14 [Update Guide][guide-update], which includes updated and removed items from the library.
+- [discord.js Discord server][discord]
+- [Discord API Discord server][discord-api]
+- [GitHub][source]
+- [Related libraries][related-libs]
+
+## Contributing
+
+Before creating an issue, please ensure that it hasn't already been reported/suggested.  
+See [the contribution guide][contributing] if you'd like to submit a PR.
+
+## Help
+
+If you don't understand something in the documentation, you are experiencing problems, or you just need a gentle nudge in the right direction, please don't hesitate to join our official [discord.js Server][discord].
+
+[website]: https://discord.js.org
+[website-source]: https://github.com/discordjs/discord.js/tree/main/apps/website
+[guide]: https://discordjs.guide/
+[guide-source]: https://github.com/discordjs/guide
+[guide-update]: https://discordjs.guide/additional-info/changes-in-v14.html
+[discord]: https://discord.gg/djs
+[discord-api]: https://discord.gg/discord-api
+[source]: https://github.com/discordjs/discord.js/tree/main/packages/actions
+[related-libs]: https://discord.com/developers/docs/topics/community-resources#libraries
+[contributing]: https://github.com/discordjs/discord.js/blob/main/.github/CONTRIBUTING.md

packages/actions/__tests__/formatTag.test.ts

@@ -0,0 +1,55 @@
+import { describe, test, expect } from 'vitest';
+import { formatTag } from '../src/index.js';
+
+describe('Format Tag', () => {
+	test('GIVEN tag with a prefix THEN format tag to not contain the prefix', () => {
+		expect(formatTag('@discordjs/rest@0.4.0')).toEqual({
+			isSubpackage: true,
+			package: 'rest',
+			semver: '0.4.0',
+		});
+		expect(formatTag('@discordjs/collection@0.6.0')).toEqual({
+			isSubpackage: true,
+			package: 'collection',
+			semver: '0.6.0',
+		});
+		expect(formatTag('@discordjs/proxy@0.1.0')).toEqual({
+			isSubpackage: true,
+			package: 'proxy',
+			semver: '0.1.0',
+		});
+		expect(formatTag('@discordjs/builders@0.13.0')).toEqual({
+			isSubpackage: true,
+			package: 'builders',
+			semver: '0.13.0',
+		});
+		expect(formatTag('@discordjs/voice@0.9.0')).toEqual({
+			isSubpackage: true,
+			package: 'voice',
+			semver: '0.9.0',
+		});
+	});
+
+	test('GIVEN tag with no prefix THEN return tag', () => {
+		expect(formatTag('13.5.1')).toEqual({
+			isSubpackage: false,
+			package: 'discord.js',
+			semver: '13.5.1',
+		});
+		expect(formatTag('13.7.0')).toEqual({
+			isSubpackage: false,
+			package: 'discord.js',
+			semver: '13.7.0',
+		});
+		expect(formatTag('create-discord-bot@1.0.0')).toEqual({
+			isSubpackage: false,
+			package: 'create-discord-bot',
+			semver: '1.0.0',
+		});
+	});
+
+	test('GIVEN no or invalid tag THEN return null', () => {
+		expect(formatTag('')).toEqual(null);
+		expect(formatTag('abc')).toEqual(null);
+	});
+});

packages/actions/package.json

@@ -0,0 +1,74 @@
+{
+	"$schema": "https://json.schemastore.org/package.json",
+	"name": "@discordjs/actions",
+	"version": "0.1.0",
+	"description": "A set of actions that we use for our workflows",
+	"private": true,
+	"scripts": {
+		"test": "vitest run",
+		"build": "tsc --noEmit --lib ESNext,DOM && tsup",
+		"lint": "prettier --check . && cross-env TIMING=1 eslint --format=pretty src __tests__",
+		"format": "prettier --write . && cross-env TIMING=1 eslint --fix --format=pretty src __tests__",
+		"fmt": "pnpm run format"
+	},
+	"type": "module",
+	"directories": {
+		"lib": "src",
+		"test": "__tests__"
+	},
+	"files": [
+		"dist"
+	],
+	"contributors": [
+		"Crawl <icrawltogo@gmail.com>"
+	],
+	"license": "Apache-2.0",
+	"keywords": [
+		"api",
+		"bot",
+		"client",
+		"node",
+		"discordjs"
+	],
+	"repository": {
+		"type": "git",
+		"url": "https://github.com/discordjs/discord.js.git",
+		"directory": "packages/actions"
+	},
+	"bugs": {
+		"url": "https://github.com/discordjs/discord.js/issues"
+	},
+	"homepage": "https://discord.js.org",
+	"funding": "https://github.com/discordjs/discord.js?sponsor",
+	"dependencies": {
+		"@actions/core": "^1.11.1",
+		"@actions/glob": "^0.5.0",
+		"@aws-sdk/client-s3": "^3.787.0",
+		"@discordjs/scripts": "workspace:^",
+		"@vercel/blob": "^0.27.3",
+		"@vercel/postgres": "^0.9.0",
+		"cloudflare": "^4.2.0",
+		"meilisearch": "^0.38.0",
+		"p-limit": "^6.2.0",
+		"p-queue": "^8.1.0",
+		"tslib": "^2.8.1",
+		"undici": "7.8.0"
+	},
+	"devDependencies": {
+		"@types/node": "^22.14.0",
+		"@vitest/coverage-v8": "^3.1.1",
+		"cross-env": "^7.0.3",
+		"eslint": "^8.57.0",
+		"eslint-config-neon": "^0.1.62",
+		"eslint-formatter-pretty": "^6.0.1",
+		"prettier": "^3.5.3",
+		"terser": "^5.37.0",
+		"tsup": "^8.4.0",
+		"turbo": "^2.5.0",
+		"typescript": "~5.8.3",
+		"vitest": "^3.1.1"
+	},
+	"engines": {
+		"node": ">=18"
+	}
+}

packages/actions/src/formatTag/action.yml

@@ -0,0 +1,16 @@
+name: 'Format Tag'
+description: 'Formats a git tag to remove potentially prefixes'
+inputs:
+  tag:
+    description: 'The input tag'
+    required: true
+outputs:
+  subpackage:
+    description: 'Whether this tag is a subpackage tag'
+  package:
+    description: 'The package string that was extracted from this tag'
+  semver:
+    description: 'The semver string that was extracted from this tag'
+runs:
+  using: node20
+  main: ../../dist/formatTag/index.js

packages/actions/src/formatTag/formatTag.ts

@@ -0,0 +1,18 @@
+export function formatTag(tag: string) {
+	const parsed = /(?:^@.*\/(?<package>.*)@v?)?(?<semver>\d+.\d+.\d+)-?.*/.exec(tag);
+	const parsedPackage = /(?<package>.*)@v?-?.*/.exec(tag);
+
+	if (parsed?.groups) {
+		const isSubpackage = typeof parsed.groups.package === 'string';
+		const pkg = isSubpackage ? parsed.groups.package : (parsedPackage?.groups?.package ?? 'discord.js');
+		const semver = parsed.groups.semver;
+
+		return {
+			isSubpackage,
+			package: pkg,
+			semver,
+		};
+	}
+
+	return null;
+}

packages/actions/src/formatTag/index.ts

@@ -0,0 +1,11 @@
+import { getInput, setOutput } from '@actions/core';
+import { formatTag } from './formatTag.js';
+
+const tag = getInput('tag', { required: true });
+const parsed = formatTag(tag);
+
+if (parsed) {
+	setOutput('subpackage', parsed.isSubpackage);
+	setOutput('package', parsed.package);
+	setOutput('semver', parsed.semver);
+}

packages/actions/src/index.ts

@@ -0,0 +1 @@
+export * from './formatTag/formatTag.js';

packages/actions/src/pnpmCache/action.yml

@@ -0,0 +1,42 @@
+name: 'pnpm install'
+description: 'Run pnpm install with cache enabled'
+runs:
+  using: 'composite'
+  steps:
+    - name: Set up swap space
+      if: runner.os == 'Linux'
+      uses: pierotofy/set-swap-space@v1.0
+      with:
+        swap-size-gb: 10
+
+    - uses: pnpm/action-setup@v4.1.0
+      name: Install pnpm
+      with:
+        run_install: false
+
+    - name: Expose pnpm config(s) through "$GITHUB_OUTPUT"
+      id: pnpm-config
+      shell: bash
+      run: |
+        echo "STORE_PATH=$(pnpm store path)" >> $GITHUB_OUTPUT
+
+    - name: Cache rotation keys
+      id: cache-rotation
+      shell: bash
+      run: |
+        echo "YEAR_MONTH=$(/bin/date -u "+%Y%m")" >> $GITHUB_OUTPUT
+
+    - uses: actions/cache@v4
+      name: Setup pnpm cache
+      with:
+        path: ${{ steps.pnpm-config.outputs.STORE_PATH }}
+        key: ${{ runner.os }}-pnpm-store-cache-${{ steps.cache-rotation.outputs.YEAR_MONTH }}-${{ hashFiles('**/pnpm-lock.yaml') }}
+        restore-keys: |
+          ${{ runner.os }}-pnpm-store-cache-${{ steps.cache-rotation.outputs.YEAR_MONTH }}-
+
+    - name: Install dependencies
+      shell: bash
+      run: |
+        pnpm install --frozen-lockfile --prefer-offline --loglevel error
+      env:
+        HUSKY: '0'

packages/actions/src/uploadCoverage/action.yml

@@ -0,0 +1,116 @@
+name: 'Upload Coverage'
+description: 'Uploads code coverage reports to codecov with separate flags for separate packages'
+inputs:
+  codecov_token:
+    description: 'Codecov token.'
+    required: true
+runs:
+  using: 'composite'
+  steps:
+    - name: Upload Brokers Coverage
+      if: ${{ hashFiles('packages/brokers/coverage/cobertura-coverage.xml') != '' }}
+      uses: codecov/codecov-action@v4
+      with:
+        files: ./packages/brokers/coverage/cobertura-coverage.xml
+        disable_search: true
+        flags: brokers
+        token: ${{ inputs.CODECOV_TOKEN }}
+
+    - name: Upload Builders Coverage
+      if: ${{ hashFiles('packages/builders/coverage/cobertura-coverage.xml') != '' }}
+      uses: codecov/codecov-action@v4
+      with:
+        files: ./packages/builders/coverage/cobertura-coverage.xml
+        disable_search: true
+        flags: builders
+        token: ${{ inputs.CODECOV_TOKEN }}
+
+    - name: Upload Collection Coverage
+      if: ${{ hashFiles('packages/collection/coverage/cobertura-coverage.xml') != '' }}
+      uses: codecov/codecov-action@v4
+      with:
+        files: ./packages/collection/coverage/cobertura-coverage.xml
+        disable_search: true
+        flags: collection
+        token: ${{ inputs.CODECOV_TOKEN }}
+
+    - name: Upload Discord.js Coverage
+      if: ${{ hashFiles('packages/discord.js/coverage/cobertura-coverage.xml') != '' }}
+      uses: codecov/codecov-action@v4
+      with:
+        files: ./packages/discord.js/coverage/cobertura-coverage.xml
+        disable_search: true
+        flags: discord.js
+        token: ${{ inputs.CODECOV_TOKEN }}
+
+    - name: Upload Formatters Coverage
+      if: ${{ hashFiles('packages/formatters/coverage/cobertura-coverage.xml') != '' }}
+      uses: codecov/codecov-action@v4
+      with:
+        files: ./packages/formatters/coverage/cobertura-coverage.xml
+        disable_search: true
+        flags: formatters
+        token: ${{ inputs.CODECOV_TOKEN }}
+
+    - name: Upload Next Coverage
+      if: ${{ hashFiles('packages/next/coverage/cobertura-coverage.xml') != '' }}
+      uses: codecov/codecov-action@v4
+      with:
+        files: ./packages/next/coverage/cobertura-coverage.xml
+        disable_search: true
+        flags: next
+        token: ${{ inputs.CODECOV_TOKEN }}
+
+    - name: Upload Proxy Coverage
+      if: ${{ hashFiles('packages/proxy/coverage/cobertura-coverage.xml') != '' }}
+      uses: codecov/codecov-action@v4
+      with:
+        files: ./packages/proxy/coverage/cobertura-coverage.xml
+        disable_search: true
+        flags: proxy
+        token: ${{ inputs.CODECOV_TOKEN }}
+
+    - name: Upload Rest Coverage
+      if: ${{ hashFiles('packages/rest/coverage/cobertura-coverage.xml') != '' }}
+      uses: codecov/codecov-action@v4
+      with:
+        files: ./packages/rest/coverage/cobertura-coverage.xml
+        disable_search: true
+        flags: rest
+        token: ${{ inputs.CODECOV_TOKEN }}
+
+    - name: Upload Voice Coverage
+      if: ${{ hashFiles('packages/voice/coverage/cobertura-coverage.xml') != '' }}
+      uses: codecov/codecov-action@v4
+      with:
+        files: ./packages/voice/coverage/cobertura-coverage.xml
+        disable_search: true
+        flags: voice
+        token: ${{ inputs.CODECOV_TOKEN }}
+
+    - name: Upload WS Coverage
+      if: ${{ hashFiles('packages/ws/coverage/cobertura-coverage.xml') != '' }}
+      uses: codecov/codecov-action@v4
+      with:
+        files: ./packages/ws/coverage/cobertura-coverage.xml
+        disable_search: true
+        flags: ws
+        token: ${{ inputs.CODECOV_TOKEN }}
+
+    - name: Upload Util Coverage
+      if: ${{ hashFiles('packages/util/coverage/cobertura-coverage.xml') != '' }}
+      uses: codecov/codecov-action@v4
+      with:
+        files: ./packages/util/coverage/cobertura-coverage.xml
+        disable_search: true
+        flags: util
+        token: ${{ inputs.CODECOV_TOKEN }}
+
+    - name: Upload Utilities Coverage
+      if: ${{ hashFiles('packages/actions/coverage/cobertura-coverage.xml') != '' || hashFiles('packages/scripts/coverage/cobertura-coverage.xml') != '' }}
+      uses: codecov/codecov-action@v4
+      with:
+        files: ./packages/actions/coverage/cobertura-coverage.xml, ./packages/scripts/coverage/cobertura-coverage.xml
+        disable_search: true
+        flags: utilities
+        token: ${{ inputs.CODECOV_TOKEN }}

packages/actions/src/uploadDocumentation/action.yml

@@ -0,0 +1,10 @@
+name: 'Upload documentation'
+description: 'Uploads the docs.api.json file to a neon postgresql database'
+inputs:
+  package:
+    description: 'The package string'
+  version:
+    description: 'The semver string'
+runs:
+  using: node20
+  main: ../../dist/uploadDocumentation/index.js

packages/actions/src/uploadDocumentation/index.ts

@@ -0,0 +1,96 @@
+/* eslint-disable @typescript-eslint/no-loop-func */
+import { readFile } from 'node:fs/promises';
+import process from 'node:process';
+import { getInput, setFailed } from '@actions/core';
+import { create } from '@actions/glob';
+import { PutObjectCommand, S3Client } from '@aws-sdk/client-s3';
+import { put } from '@vercel/blob';
+import { createPool } from '@vercel/postgres';
+import Cloudflare from 'cloudflare';
+import pLimit from 'p-limit';
+
+if (
+	!process.env.DATABASE_URL ||
+	!process.env.CF_R2_DOCS_URL ||
+	!process.env.CF_R2_DOCS_ACCESS_KEY_ID ||
+	!process.env.CF_R2_DOCS_SECRET_ACCESS_KEY ||
+	!process.env.CF_R2_DOCS_BUCKET ||
+	!process.env.CF_R2_DOCS_BUCKET_URL ||
+	!process.env.CF_D1_DOCS_API_KEY ||
+	!process.env.CF_D1_DOCS_ID ||
+	!process.env.CF_ACCOUNT_ID
+) {
+	setFailed('Missing environment variables');
+}
+
+const pkg = getInput('package') || '*';
+const version = getInput('version') || 'main';
+
+const pool = createPool({
+	connectionString: process.env.DATABASE_URL,
+});
+
+const S3 = new S3Client({
+	region: 'auto',
+	endpoint: process.env.CF_R2_DOCS_URL!,
+	credentials: {
+		accessKeyId: process.env.CF_R2_DOCS_ACCESS_KEY_ID!,
+		secretAccessKey: process.env.CF_R2_DOCS_SECRET_ACCESS_KEY!,
+	},
+	requestChecksumCalculation: 'WHEN_REQUIRED',
+	responseChecksumValidation: 'WHEN_REQUIRED',
+});
+
+const client = new Cloudflare({
+	apiToken: process.env.CF_D1_DOCS_API_KEY,
+});
+
+const limit = pLimit(10);
+const promises = [];
+
+const globber = await create(`packages/${pkg}/docs/docs.api.json`);
+console.log('Glob: ', await globber.glob());
+for await (const file of globber.globGenerator()) {
+	const data = await readFile(file, 'utf8');
+	try {
+		promises.push(
+			limit(async () => {
+				console.log(`Uploading ${file} with ${version}...`);
+				const json = JSON.parse(data);
+				const name = json.name ?? json.n;
+
+				const key = `${name.replace('@discordjs/', '')}/${version}.json`;
+
+				const { url } = await put(key, data, {
+					access: 'public',
+					addRandomSuffix: false,
+				});
+				await pool.sql`insert into documentation (name, version, url) values (${name.replace(
+					'@discordjs/',
+					'',
+				)}, ${version}, ${url}) on conflict (name, version) do update set url = EXCLUDED.url`;
+
+				await S3.send(
+					new PutObjectCommand({
+						Bucket: process.env.CF_R2_DOCS_BUCKET,
+						Key: key,
+						Body: data,
+					}),
+				);
+				await client.d1.database.raw(process.env.CF_D1_DOCS_ID!, {
+					account_id: process.env.CF_ACCOUNT_ID!,
+					sql: `insert into documentation (name, version, url) values (?, ?, ?) on conflict (name, version) do update set url = excluded.url;`,
+					params: [name.replace('@discordjs/', ''), version, process.env.CF_R2_DOCS_BUCKET_URL + '/' + key],
+				});
+			}),
+		);
+	} catch (error) {
+		console.log(error);
+	}
+}
+
+try {
+	await Promise.all(promises);
+} catch (error) {
+	console.log(error);
+}

packages/actions/src/uploadSearchIndices/action.yml

@@ -0,0 +1,5 @@
+name: 'Upload search indices'
+description: 'Uploads the search indices to a meilisearch database'
+runs:
+  using: node20
+  main: ../../dist/uploadSearchIndices/index.js

packages/actions/src/uploadSearchIndices/index.ts

@@ -0,0 +1,86 @@
+import process from 'node:process';
+import { setFailed } from '@actions/core';
+import { generateAllIndices } from '@discordjs/scripts';
+import { createPool } from '@vercel/postgres';
+import { MeiliSearch } from 'meilisearch';
+import pLimit from 'p-limit';
+import { fetch } from 'undici';
+
+if (!process.env.DATABASE_URL) {
+	setFailed('DATABASE_URL is not set');
+}
+
+if (!process.env.SEARCH_API_URL) {
+	setFailed('SEARCH_API_URL is not set');
+}
+
+if (!process.env.SEARCH_API_KEY) {
+	setFailed('SEARCH_API_KEY is not set');
+}
+
+const pool = createPool({
+	connectionString: process.env.DATABASE_URL,
+});
+
+const client = new MeiliSearch({
+	host: process.env.SEARCH_API_URL!,
+	apiKey: process.env.SEARCH_API_KEY!,
+});
+
+const limit = pLimit(10);
+let promises: Promise<any>[] = [];
+
+try {
+	console.log('Generating all indices...');
+	const indices = await generateAllIndices({
+		fetchPackageVersions: async (pkg) => {
+			console.log(`Fetching versions for ${pkg}...`);
+			const { rows } = await pool.sql`select version from documentation where name = ${pkg}`;
+
+			return rows.map((row) => row.version);
+		},
+		fetchPackageVersionDocs: async (pkg, version) => {
+			console.log(`Fetching data for ${pkg} ${version}...`);
+			const { rows } = await pool.sql`select url from documentation where name = ${pkg} and version = ${version}`;
+			const res = await fetch(rows[0]?.url ?? '');
+
+			return res.json();
+		},
+		writeToFile: false,
+	});
+	console.log('Generated all indices.');
+
+	console.log('Uploading indices...');
+
+	try {
+		promises = indices.map(async (index) =>
+			limit(async () => {
+				console.log(`Uploading ${index.index}...`);
+				let task;
+				try {
+					task = await client.createIndex(index.index);
+				} catch {}
+
+				if (task) {
+					await client.waitForTask(task.taskUid);
+				}
+
+				const searchIndex = client.index(index.index);
+				await searchIndex.updateSettings({ sortableAttributes: ['type'] });
+
+				await searchIndex.addDocuments(index.data);
+			}),
+		);
+	} catch {}
+
+	console.log('Uploaded all indices.');
+} catch (error) {
+	const err = error as Error;
+	setFailed(err.message);
+}
+
+try {
+	await Promise.all(promises);
+} catch (error) {
+	console.log(error);
+}

packages/actions/src/uploadSplitDocumentation/action.yml

@@ -0,0 +1,10 @@
+name: 'Upload split documentation'
+description: 'Splits and uploads the docs.api.json file into more fine-grained [item].api.json files'
+inputs:
+  package:
+    description: 'The package string'
+  version:
+    description: 'The semver string'
+runs:
+  using: node20
+  main: ../../dist/uploadSplitDocumentation/index.js

packages/actions/src/uploadSplitDocumentation/index.ts

@@ -0,0 +1,94 @@
+/* eslint-disable @typescript-eslint/no-loop-func */
+import { readFile } from 'node:fs/promises';
+import { basename, dirname, relative, sep } from 'node:path';
+import process from 'node:process';
+import { setTimeout as sleep } from 'node:timers/promises';
+import { setFailed, getInput } from '@actions/core';
+import { create } from '@actions/glob';
+import { S3Client, PutObjectCommand } from '@aws-sdk/client-s3';
+import { put } from '@vercel/blob';
+import PQueue from 'p-queue';
+
+if (
+	!process.env.CF_R2_DOCS_URL ||
+	!process.env.CF_R2_DOCS_ACCESS_KEY_ID ||
+	!process.env.CF_R2_DOCS_SECRET_ACCESS_KEY ||
+	!process.env.CF_R2_DOCS_BUCKET
+) {
+	setFailed('Missing environment variables');
+}
+
+const pkg = getInput('package') || '*';
+const version = getInput('version') || 'main';
+
+const queue = new PQueue({ concurrency: 10, interval: 60_000, intervalCap: 1_000 });
+const promises = [];
+const failedUploads: string[] = [];
+
+const S3 = new S3Client({
+	region: 'auto',
+	endpoint: process.env.CF_R2_DOCS_URL!,
+	credentials: {
+		accessKeyId: process.env.CF_R2_DOCS_ACCESS_KEY_ID!,
+		secretAccessKey: process.env.CF_R2_DOCS_SECRET_ACCESS_KEY!,
+	},
+	requestChecksumCalculation: 'WHEN_REQUIRED',
+	responseChecksumValidation: 'WHEN_REQUIRED',
+});
+
+const globber = await create(`packages/${pkg}/docs/${pkg}/split/*.api.json`);
+console.log('Glob: ', await globber.glob());
+for await (const file of globber.globGenerator()) {
+	const data = await readFile(file, 'utf8');
+	const pkgName = dirname(relative(process.cwd(), file)).split(sep)[1];
+	try {
+		promises.push(
+			queue.add(async () => {
+				console.log(`Uploading ${file} with ${version} from ${pkgName}...`);
+				const name = basename(file).replace('main.', '');
+				async function upload(retries = 0) {
+					try {
+						await put(`rewrite/${pkgName}/${version}.${name}`, data, {
+							access: 'public',
+							addRandomSuffix: false,
+						});
+						await S3.send(
+							new PutObjectCommand({
+								Bucket: process.env.CF_R2_DOCS_BUCKET,
+								Key: `${pkgName}/${version}.${name}`,
+								Body: data,
+							}),
+						);
+					} catch (error) {
+						if (retries > 3) {
+							console.error(`Could not upload ${file} after 3 retries`, error);
+							failedUploads.push(name);
+							return;
+						}
+
+						if (typeof error === 'object' && error && 'retryAfter' in error && typeof error.retryAfter === 'number') {
+							await sleep(error.retryAfter * 1_000);
+							return upload(retries + 1);
+						} else {
+							console.error(`Could not upload ${file}`, error);
+							failedUploads.push(name);
+						}
+					}
+				}
+
+				await upload();
+			}),
+		);
+	} catch (error) {
+		console.log(error);
+	}
+}
+
+try {
+	await Promise.all(promises);
+	if (failedUploads.length) {
+		setFailed(`Failed to upload ${failedUploads.length} files: ${failedUploads.join(', ')}`);
+	}
+} catch (error) {
+	console.log(error);
+}

packages/actions/src/yarnCache/action.yml

@@ -0,0 +1,48 @@
+name: 'yarn install'
+description: 'Run yarn install with node_modules linker and cache enabled'
+runs:
+  using: 'composite'
+  steps:
+    - name: Set up swap space
+      if: runner.os == 'Linux'
+      uses: pierotofy/set-swap-space@v1.0
+      with:
+        swap-size-gb: 10
+
+    - name: Expose yarn config as "$GITHUB_OUTPUT"
+      id: yarn-config
+      shell: bash
+      env:
+        YARN_ENABLE_GLOBAL_CACHE: 'false'
+      run: |
+        echo "CACHE_FOLDER=$(yarn config get cacheFolder)" >> $GITHUB_OUTPUT
+        echo "CURRENT_NODE_VERSION="node-$(node --version)"" >> $GITHUB_OUTPUT
+        echo "CURRENT_BRANCH=$(echo ${GITHUB_REF#refs/heads/} | sed -r 's,/,-,g')" >> $GITHUB_OUTPUT
+        echo "NPM_GLOBAL_CACHE_FOLDER=$(npm config get cache)" >> $GITHUB_OUTPUT
+
+    - name: Restore yarn cache
+      uses: actions/cache@v4
+      id: yarn-download-cache
+      with:
+        path: ${{ steps.yarn-config.outputs.CACHE_FOLDER }}
+        key: yarn-download-cache-default-${{ hashFiles(yarn.lock, .yarnrc.yml) }}
+        restore-keys: |
+          yarn-download-cache-default-
+
+    - name: Restore global npm cache folder
+      id: npm-global-cache
+      uses: actions/cache@v4
+      with:
+        path: ${{ steps.yarn-config.outputs.NPM_GLOBAL_CACHE_FOLDER }}
+        key: npm-global-cache-default-${{ runner.os }}-${{ steps.yarn-config.outputs.CURRENT_NODE_VERSION }}-${{ hashFiles(yarn.lock, .yarnrc.yml) }}
+
+    - name: Install dependencies
+      shell: bash
+      run: |
+        yarn install --immutable --inline-builds
+      env:
+        YARN_ENABLE_GLOBAL_CACHE: 'false'
+        YARN_ENABLE_MIRROR: 'false'
+        YARN_NM_MODE: 'hardlinks-local'
+        YARN_INSTALL_STATE_PATH: '.yarn/ci-cache/install-state.gz'
+        HUSKY: '0'

packages/actions/tsconfig.eslint.json

@@ -0,0 +1,22 @@
+{
+	"$schema": "https://json.schemastore.org/tsconfig.json",
+	"extends": "./tsconfig.json",
+	"compilerOptions": {
+		"allowJs": true
+	},
+	"include": [
+		"*.ts",
+		"*.js",
+		"*.cjs",
+		"*.mjs",
+		"src/**/*.ts",
+		"src/**/*.js",
+		"src/**/*.cjs",
+		"src/**/*.mjs",
+		"bin",
+		"scripts",
+		"__tests__",
+		"__mocks__"
+	],
+	"exclude": ["node_modules"]
+}

packages/actions/tsconfig.json

@@ -0,0 +1,6 @@
+{
+	"$schema": "https://json.schemastore.org/tsconfig.json",
+	"extends": "../../tsconfig.json",
+	"include": ["src/**/*.ts", "src/**/*.js", "src/**/*.cjs", "src/**/*.mjs", "bin"],
+	"exclude": ["node_modules"]
+}

packages/actions/tsconfig.test.json

@@ -0,0 +1,10 @@
+{
+	"$schema": "https://json.schemastore.org/tsconfig.json",
+	"extends": "./tsconfig.json",
+	"compilerOptions": {
+		"noEmit": true,
+		"skipLibCheck": true
+	},
+	"include": ["__tests__/**/*.ts"],
+	"exclude": ["node_modules"]
+}

packages/actions/tsup.config.ts

@@ -0,0 +1,14 @@
+import { createTsupConfig } from '../../tsup.config.js';
+
+export default createTsupConfig({
+	entry: [
+		'src/index.ts',
+		'src/formatTag/index.ts',
+		'src/uploadDocumentation/index.ts',
+		'src/uploadSearchIndices/index.ts',
+		'src/uploadSplitDocumentation/index.ts',
+	],
+	dts: false,
+	format: 'esm',
+	minify: 'terser',
+});

packages/api-extractor-model/.gitignore

@@ -0,0 +1,23 @@
+# Packages
+node_modules
+
+# Log files
+logs
+*.log
+npm-debug.log*
+
+# Runtime data
+pids
+*.pid
+*.seed
+
+# Env
+.env
+
+# Dist
+dist
+
+# Miscellaneous
+.turbo
+.tmp
+coverage

packages/api-extractor-model/.lintstagedrc.js

@@ -0,0 +1,2 @@
+/** @type {import('lint-staged').Config} */
+module.exports = require('../../.lintstagedrc.json');

packages/api-extractor-model/.npmignore

@@ -0,0 +1,30 @@
+# THIS IS A STANDARD TEMPLATE FOR .npmignore FILES IN THIS REPO.
+
+# Ignore all files by default, to avoid accidentally publishing unintended files.
+*
+
+# Use negative patterns to bring back the specific things we want to publish.
+!/bin/**
+!/lib/**
+!/lib-*/**
+!/dist/**
+!ThirdPartyNotice.txt
+
+# Ignore certain patterns that should not get published.
+/dist/*.stats.*
+/lib/**/test/
+/lib-*/**/test/
+*.test.js
+
+# NOTE: These don't need to be specified, because NPM includes them automatically.
+#
+# package.json
+# README (and its variants)
+# CHANGELOG (and its variants)
+# LICENSE / LICENCE
+
+#--------------------------------------------
+# DO NOT MODIFY THE TEMPLATE ABOVE THIS LINE
+#--------------------------------------------
+
+# (Add your project-specific overrides here)

packages/api-extractor-model/.prettierignore

@@ -0,0 +1,5 @@
+.turbo
+coverage
+dist
+CHANGELOG.md
+tsup.config.bundled*

packages/api-extractor-model/.prettierrc.js

@@ -0,0 +1,2 @@
+/** @type {import('prettier').Config} */
+module.exports = require('../../.prettierrc.json');

packages/api-extractor-model/CHANGELOG.md

@@ -0,0 +1,965 @@
+# Change Log - @microsoft/api-extractor-model
+
+This log was last generated on Thu, 28 Sep 2023 20:53:16 GMT and should not be manually modified.
+
+## 7.28.2
+Thu, 28 Sep 2023 20:53:16 GMT
+
+_Version update only_
+
+## 7.28.1
+Tue, 26 Sep 2023 09:30:33 GMT
+
+### Patches
+
+- Update type-only imports to include the type modifier.
+
+## 7.28.0
+Fri, 15 Sep 2023 00:36:58 GMT
+
+### Minor changes
+
+- Update @types/node from 14 to 18
+
+## 7.27.6
+Tue, 08 Aug 2023 07:10:40 GMT
+
+_Version update only_
+
+## 7.27.5
+Wed, 19 Jul 2023 00:20:32 GMT
+
+_Version update only_
+
+## 7.27.4
+Thu, 06 Jul 2023 00:16:20 GMT
+
+_Version update only_
+
+## 7.27.3
+Thu, 15 Jun 2023 00:21:01 GMT
+
+_Version update only_
+
+## 7.27.2
+Wed, 07 Jun 2023 22:45:16 GMT
+
+_Version update only_
+
+## 7.27.1
+Mon, 29 May 2023 15:21:15 GMT
+
+_Version update only_
+
+## 7.27.0
+Mon, 22 May 2023 06:34:32 GMT
+
+### Minor changes
+
+- Upgrade the TypeScript dependency to ~5.0.4
+
+## 7.26.9
+Fri, 12 May 2023 00:23:05 GMT
+
+_Version update only_
+
+## 7.26.8
+Thu, 04 May 2023 00:20:28 GMT
+
+### Patches
+
+- Fix a mistake in the documentation for ApiParameterListMixin.overloadIndex
+
+## 7.26.7
+Mon, 01 May 2023 15:23:20 GMT
+
+_Version update only_
+
+## 7.26.6
+Sat, 29 Apr 2023 00:23:03 GMT
+
+_Version update only_
+
+## 7.26.5
+Thu, 27 Apr 2023 17:18:43 GMT
+
+_Version update only_
+
+## 7.26.4
+Fri, 10 Feb 2023 01:18:51 GMT
+
+_Version update only_
+
+## 7.26.3
+Sun, 05 Feb 2023 03:02:02 GMT
+
+_Version update only_
+
+## 7.26.2
+Wed, 01 Feb 2023 02:16:34 GMT
+
+_Version update only_
+
+## 7.26.1
+Mon, 30 Jan 2023 16:22:30 GMT
+
+_Version update only_
+
+## 7.26.0
+Wed, 25 Jan 2023 07:26:55 GMT
+
+### Minor changes
+
+- Add new .api.json field `isAbstract` to track `abstract` modifier in ApiClass, ApiMethod, and ApiProperty via ApiAbstractMixin (GitHub #3661)
+
+## 7.25.3
+Fri, 09 Dec 2022 16:18:28 GMT
+
+_Version update only_
+
+## 7.25.2
+Wed, 26 Oct 2022 00:16:16 GMT
+
+### Patches
+
+- Update the @microsoft/tsdoc dependency version to 0.14.2.
+
+## 7.25.1
+Thu, 13 Oct 2022 00:20:15 GMT
+
+_Version update only_
+
+## 7.25.0
+Tue, 11 Oct 2022 23:49:12 GMT
+
+### Minor changes
+
+- Add a new fileUrlPath property to relevant API items and serialize this to the .api.json. Additionally, add a SourceFile helper class for constructing file URLs from these paths and the projectFolderUrl.
+
+## 7.24.4
+Mon, 10 Oct 2022 15:23:44 GMT
+
+_Version update only_
+
+## 7.24.3
+Thu, 29 Sep 2022 07:13:06 GMT
+
+_Version update only_
+
+## 7.24.2
+Wed, 21 Sep 2022 20:21:10 GMT
+
+_Version update only_
+
+## 7.24.1
+Thu, 15 Sep 2022 00:18:52 GMT
+
+_Version update only_
+
+## 7.24.0
+Fri, 02 Sep 2022 17:48:42 GMT
+
+### Minor changes
+
+- Add new ApiExportedMixin mixin class for determining whether an API item is exported or not
+
+## 7.23.3
+Wed, 24 Aug 2022 03:01:22 GMT
+
+_Version update only_
+
+## 7.23.2
+Wed, 24 Aug 2022 00:14:38 GMT
+
+### Patches
+
+- Remove use of LegacyAdapters.sortStable
+
+## 7.23.1
+Fri, 19 Aug 2022 00:17:19 GMT
+
+_Version update only_
+
+## 7.23.0
+Wed, 03 Aug 2022 18:40:35 GMT
+
+### Minor changes
+
+- Upgrade TypeScript dependency to 4.7
+
+## 7.22.2
+Mon, 01 Aug 2022 02:45:32 GMT
+
+_Version update only_
+
+## 7.22.1
+Thu, 21 Jul 2022 23:30:27 GMT
+
+### Patches
+
+- Improve IFindApiItemMessage and fix two small bugs with ApiItemContainerMixin.findMembersWithInheritance()
+
+## 7.22.0
+Thu, 21 Jul 2022 00:16:14 GMT
+
+### Minor changes
+
+- Add a new ApiItemContainerMixin.findMembersWithInheritance() method for finding an item's inherited members
+
+## 7.21.0
+Thu, 30 Jun 2022 04:48:53 GMT
+
+### Minor changes
+
+- Update model to reflect that index signatures can also be readonly
+
+## 7.20.3
+Tue, 28 Jun 2022 22:47:13 GMT
+
+_Version update only_
+
+## 7.20.2
+Tue, 28 Jun 2022 00:23:32 GMT
+
+_Version update only_
+
+## 7.20.1
+Mon, 27 Jun 2022 18:43:09 GMT
+
+_Version update only_
+
+## 7.20.0
+Sat, 25 Jun 2022 21:00:40 GMT
+
+### Minor changes
+
+- Add a new initializerTokenRange field to ApiProperty and ApiVariable items.
+
+## 7.19.1
+Sat, 25 Jun 2022 01:54:29 GMT
+
+_Version update only_
+
+## 7.19.0
+Fri, 24 Jun 2022 07:16:47 GMT
+
+### Minor changes
+
+- Added new configuration for ItemContainerMixin member ordering
+
+## 7.18.2
+Fri, 17 Jun 2022 09:17:54 GMT
+
+_Version update only_
+
+## 7.18.1
+Fri, 17 Jun 2022 00:16:18 GMT
+
+_Version update only_
+
+## 7.18.0
+Tue, 07 Jun 2022 09:37:04 GMT
+
+### Minor changes
+
+- Add an "isReadonly" field to ApiProperty, ApiPropertySignature, and ApiVariable
+- Add an "isProtected" field to ApiConstructor, ApiMethod, and ApiProperty
+
+## 7.17.3
+Tue, 10 May 2022 01:20:43 GMT
+
+_Version update only_
+
+## 7.17.2
+Sat, 23 Apr 2022 02:13:07 GMT
+
+_Version update only_
+
+## 7.17.1
+Fri, 15 Apr 2022 00:12:36 GMT
+
+_Version update only_
+
+## 7.17.0
+Wed, 13 Apr 2022 15:12:40 GMT
+
+### Minor changes
+
+- Add a new isOptional property to TypeParameters deserialized from the .api.json file with api-extractor-model.
+
+## 7.16.2
+Tue, 12 Apr 2022 02:58:32 GMT
+
+### Patches
+
+- Update TSDoc dependencies.
+
+## 7.16.1
+Sat, 09 Apr 2022 02:24:26 GMT
+
+### Patches
+
+- Rename the "master" branch to "main".
+- Update a path in the README.
+
+## 7.16.0
+Thu, 31 Mar 2022 02:06:05 GMT
+
+### Minor changes
+
+- Updated api-extractor-model to store whether a parameter is optional.
+
+## 7.15.4
+Tue, 15 Mar 2022 19:15:53 GMT
+
+_Version update only_
+
+## 7.15.3
+Wed, 05 Jan 2022 16:07:47 GMT
+
+_Version update only_
+
+## 7.15.2
+Mon, 27 Dec 2021 16:10:40 GMT
+
+_Version update only_
+
+## 7.15.1
+Thu, 09 Dec 2021 20:34:41 GMT
+
+_Version update only_
+
+## 7.15.0
+Thu, 09 Dec 2021 00:21:54 GMT
+
+### Minor changes
+
+- Replace const enums with conventional enums to allow for compatibility with JavaScript consumers.
+
+## 7.14.0
+Wed, 08 Dec 2021 16:14:05 GMT
+
+### Minor changes
+
+- Update to TypeScript 4.5
+
+## 7.13.18
+Mon, 06 Dec 2021 16:08:33 GMT
+
+_Version update only_
+
+## 7.13.17
+Fri, 03 Dec 2021 03:05:22 GMT
+
+_Version update only_
+
+## 7.13.16
+Sat, 06 Nov 2021 00:09:13 GMT
+
+_Version update only_
+
+## 7.13.15
+Fri, 05 Nov 2021 15:09:18 GMT
+
+_Version update only_
+
+## 7.13.14
+Wed, 27 Oct 2021 00:08:15 GMT
+
+### Patches
+
+- Update the package.json repository field to include the directory property.
+
+## 7.13.13
+Wed, 13 Oct 2021 15:09:54 GMT
+
+_Version update only_
+
+## 7.13.12
+Fri, 08 Oct 2021 08:08:34 GMT
+
+_Version update only_
+
+## 7.13.11
+Thu, 07 Oct 2021 07:13:35 GMT
+
+_Version update only_
+
+## 7.13.10
+Tue, 05 Oct 2021 15:08:38 GMT
+
+_Version update only_
+
+## 7.13.9
+Fri, 24 Sep 2021 00:09:29 GMT
+
+_Version update only_
+
+## 7.13.8
+Thu, 23 Sep 2021 00:10:40 GMT
+
+### Patches
+
+- Upgrade the `@types/node` dependency to version to version 12.
+
+## 7.13.7
+Tue, 14 Sep 2021 01:17:04 GMT
+
+_Version update only_
+
+## 7.13.6
+Mon, 13 Sep 2021 15:07:06 GMT
+
+_Version update only_
+
+## 7.13.5
+Wed, 11 Aug 2021 00:07:21 GMT
+
+_Version update only_
+
+## 7.13.4
+Mon, 12 Jul 2021 23:08:26 GMT
+
+_Version update only_
+
+## 7.13.3
+Fri, 04 Jun 2021 19:59:53 GMT
+
+_Version update only_
+
+## 7.13.2
+Wed, 19 May 2021 00:11:39 GMT
+
+_Version update only_
+
+## 7.13.1
+Mon, 03 May 2021 15:10:29 GMT
+
+_Version update only_
+
+## 7.13.0
+Tue, 20 Apr 2021 04:59:51 GMT
+
+### Minor changes
+
+- The .api.json file format now stores the TSDoc configuration used for parsing doc comments
+
+## 7.12.5
+Mon, 12 Apr 2021 15:10:28 GMT
+
+_Version update only_
+
+## 7.12.4
+Thu, 08 Apr 2021 06:05:31 GMT
+
+### Patches
+
+- Fix minor typo in README.md
+
+## 7.12.3
+Tue, 06 Apr 2021 15:14:22 GMT
+
+_Version update only_
+
+## 7.12.2
+Fri, 05 Feb 2021 16:10:42 GMT
+
+_Version update only_
+
+## 7.12.1
+Thu, 10 Dec 2020 23:25:49 GMT
+
+### Patches
+
+- Enable support for @decorator
+
+## 7.12.0
+Wed, 18 Nov 2020 08:19:54 GMT
+
+### Minor changes
+
+- Introduce an ApiOptionalMixin base class for representing optional properties and methods
+
+## 7.11.0
+Wed, 18 Nov 2020 06:21:57 GMT
+
+### Minor changes
+
+- Update .api.json file format to store a new field "isOptional" for documenting optional properties
+
+## 7.10.10
+Wed, 11 Nov 2020 01:08:59 GMT
+
+_Version update only_
+
+## 7.10.9
+Tue, 10 Nov 2020 23:13:12 GMT
+
+_Version update only_
+
+## 7.10.8
+Fri, 30 Oct 2020 06:38:39 GMT
+
+_Version update only_
+
+## 7.10.7
+Fri, 30 Oct 2020 00:10:14 GMT
+
+_Version update only_
+
+## 7.10.6
+Thu, 29 Oct 2020 06:14:19 GMT
+
+### Patches
+
+- Fix .d.ts error when the library is imported by a project using TypeScript 4.0
+
+## 7.10.5
+Wed, 28 Oct 2020 01:18:03 GMT
+
+_Version update only_
+
+## 7.10.4
+Tue, 27 Oct 2020 15:10:14 GMT
+
+_Version update only_
+
+## 7.10.3
+Tue, 06 Oct 2020 00:24:06 GMT
+
+_Version update only_
+
+## 7.10.2
+Mon, 05 Oct 2020 22:36:57 GMT
+
+_Version update only_
+
+## 7.10.1
+Wed, 30 Sep 2020 18:39:17 GMT
+
+### Patches
+
+- Update to build with @rushstack/heft-node-rig
+
+## 7.10.0
+Wed, 30 Sep 2020 06:53:53 GMT
+
+### Minor changes
+
+- Upgrade compiler; the API now requires TypeScript 3.9 or newer
+
+### Patches
+
+- Update README.md
+
+## 7.9.7
+Tue, 22 Sep 2020 05:45:57 GMT
+
+_Version update only_
+
+## 7.9.6
+Tue, 22 Sep 2020 01:45:31 GMT
+
+_Version update only_
+
+## 7.9.5
+Tue, 22 Sep 2020 00:08:53 GMT
+
+_Version update only_
+
+## 7.9.4
+Sat, 19 Sep 2020 04:37:27 GMT
+
+_Version update only_
+
+## 7.9.3
+Sat, 19 Sep 2020 03:33:07 GMT
+
+_Version update only_
+
+## 7.9.2
+Fri, 18 Sep 2020 22:57:24 GMT
+
+_Version update only_
+
+## 7.9.1
+Fri, 18 Sep 2020 21:49:54 GMT
+
+_Version update only_
+
+## 7.9.0
+Sun, 13 Sep 2020 01:53:20 GMT
+
+### Minor changes
+
+- Add support for system selectors in declaration references
+
+## 7.8.22
+Fri, 11 Sep 2020 02:13:35 GMT
+
+_Version update only_
+
+## 7.8.21
+Mon, 07 Sep 2020 07:37:37 GMT
+
+_Version update only_
+
+## 7.8.20
+Sat, 05 Sep 2020 18:56:34 GMT
+
+### Patches
+
+- Fix "Converting circular structure to JSON" error (GitHub #2152)
+
+## 7.8.19
+Thu, 27 Aug 2020 11:27:06 GMT
+
+_Version update only_
+
+## 7.8.18
+Mon, 24 Aug 2020 07:35:20 GMT
+
+_Version update only_
+
+## 7.8.17
+Sat, 22 Aug 2020 05:55:43 GMT
+
+_Version update only_
+
+## 7.8.16
+Tue, 18 Aug 2020 23:59:42 GMT
+
+_Version update only_
+
+## 7.8.15
+Mon, 17 Aug 2020 04:53:23 GMT
+
+_Version update only_
+
+## 7.8.14
+Wed, 12 Aug 2020 00:10:05 GMT
+
+### Patches
+
+- Updated project to build with Heft
+
+## 7.8.13
+Wed, 05 Aug 2020 18:27:33 GMT
+
+_Version update only_
+
+## 7.8.12
+Fri, 03 Jul 2020 15:09:04 GMT
+
+_Version update only_
+
+## 7.8.11
+Thu, 25 Jun 2020 06:43:35 GMT
+
+_Version update only_
+
+## 7.8.10
+Wed, 24 Jun 2020 09:50:48 GMT
+
+_Version update only_
+
+## 7.8.9
+Wed, 24 Jun 2020 09:04:28 GMT
+
+_Version update only_
+
+## 7.8.8
+Wed, 10 Jun 2020 20:48:30 GMT
+
+_Version update only_
+
+## 7.8.7
+Sat, 30 May 2020 02:59:54 GMT
+
+_Version update only_
+
+## 7.8.6
+Thu, 28 May 2020 05:59:02 GMT
+
+_Version update only_
+
+## 7.8.5
+Wed, 27 May 2020 05:15:11 GMT
+
+_Version update only_
+
+## 7.8.4
+Tue, 26 May 2020 23:00:25 GMT
+
+_Version update only_
+
+## 7.8.3
+Fri, 22 May 2020 15:08:43 GMT
+
+_Version update only_
+
+## 7.8.2
+Thu, 21 May 2020 23:09:44 GMT
+
+_Version update only_
+
+## 7.8.1
+Thu, 21 May 2020 15:42:00 GMT
+
+_Version update only_
+
+## 7.8.0
+Wed, 06 May 2020 08:23:45 GMT
+
+### Minor changes
+
+- Enable canonicalReference to ApiItem lookup
+
+## 7.7.11
+Wed, 08 Apr 2020 04:07:33 GMT
+
+_Version update only_
+
+## 7.7.10
+Sat, 28 Mar 2020 00:37:16 GMT
+
+### Patches
+
+- Upgrade to TSdoc 0.12.19
+
+## 7.7.9
+Wed, 18 Mar 2020 15:07:47 GMT
+
+### Patches
+
+- Upgrade cyclic dependencies
+
+## 7.7.8
+Tue, 17 Mar 2020 23:55:58 GMT
+
+### Patches
+
+- Replace dependencies whose NPM scope was renamed from `@microsoft` to `@rushstack`
+
+## 7.7.7
+Tue, 28 Jan 2020 02:23:44 GMT
+
+_Version update only_
+
+## 7.7.6
+Thu, 23 Jan 2020 01:07:56 GMT
+
+_Version update only_
+
+## 7.7.5
+Tue, 21 Jan 2020 21:56:14 GMT
+
+_Version update only_
+
+## 7.7.4
+Sun, 19 Jan 2020 02:26:52 GMT
+
+### Patches
+
+- Upgrade Node typings to Node 10
+
+## 7.7.3
+Fri, 17 Jan 2020 01:08:23 GMT
+
+_Version update only_
+
+## 7.7.2
+Thu, 09 Jan 2020 06:44:13 GMT
+
+_Version update only_
+
+## 7.7.1
+Wed, 08 Jan 2020 00:11:31 GMT
+
+_Version update only_
+
+## 7.7.0
+Tue, 03 Dec 2019 03:17:43 GMT
+
+### Minor changes
+
+- Improve declaration reference syntax to allow linking to overloaded functions/methods
+
+## 7.6.0
+Sun, 24 Nov 2019 00:54:04 GMT
+
+### Minor changes
+
+- Added support for `@throws`
+
+## 7.5.6
+Fri, 15 Nov 2019 04:50:50 GMT
+
+_Version update only_
+
+## 7.5.5
+Mon, 11 Nov 2019 16:07:56 GMT
+
+_Version update only_
+
+## 7.5.4
+Tue, 05 Nov 2019 06:49:28 GMT
+
+### Patches
+
+- Fix an issue where API reports sometimes were ordered differently depending on the version of NodeJS (GitHub #1552)
+
+## 7.5.3
+Tue, 05 Nov 2019 01:08:39 GMT
+
+### Patches
+
+- Clarified an error message
+
+## 7.5.2
+Tue, 22 Oct 2019 06:24:44 GMT
+
+### Patches
+
+- Refactor some code as part of migration from TSLint to ESLint
+
+## 7.5.1
+Sun, 29 Sep 2019 23:56:29 GMT
+
+### Patches
+
+- Update repository URL
+
+## 7.5.0
+Wed, 25 Sep 2019 15:15:31 GMT
+
+### Minor changes
+
+- Add ApiItem.getMergedSiblings() API
+
+## 7.4.2
+Mon, 23 Sep 2019 15:14:55 GMT
+
+### Patches
+
+- Remove unnecessary dependency on @types/node
+
+## 7.4.1
+Tue, 10 Sep 2019 22:32:23 GMT
+
+### Patches
+
+- Update documentation
+
+## 7.4.0
+Tue, 10 Sep 2019 20:38:33 GMT
+
+### Minor changes
+
+- Add 'canonicalReference' to ExcerptToken
+
+## 7.3.4
+Wed, 04 Sep 2019 18:28:06 GMT
+
+_Version update only_
+
+## 7.3.3
+Wed, 04 Sep 2019 15:15:37 GMT
+
+### Patches
+
+- Update TSDoc dependency to 0.12.14
+
+## 7.3.2
+Thu, 08 Aug 2019 15:14:17 GMT
+
+_Version update only_
+
+## 7.3.1
+Thu, 08 Aug 2019 00:49:05 GMT
+
+### Patches
+
+- (Experimental) Add ApiExtractor.canonicalReference which is a beta implementation of the revised TSDoc declaration reference notation
+
+## 7.3.0
+Mon, 22 Jul 2019 19:13:10 GMT
+
+### Minor changes
+
+- Rename `ApiItem.canonicalReference` to `.containerKey`; rename `ApiItemContainerMixin.tryGetMember()` to `.tryGetMemberByKey()`; rename `Api___.getCanonicalReference()` to `.getContainerKey()`
+
+## 7.2.0
+Tue, 11 Jun 2019 00:48:06 GMT
+
+### Minor changes
+
+- Add API support for type parameters and type alias types
+
+### Patches
+
+- Improve the .api.json deserializer to validate the schema version and support backwards compatibility
+
+## 7.1.3
+Wed, 05 Jun 2019 19:12:34 GMT
+
+### Patches
+
+- Fix an issue where TSDoc index selectors (ApiParameterListMixin.overloadIndex) started from 0, whereas TSDoc requires a nonzero number
+
+## 7.1.2
+Tue, 04 Jun 2019 05:51:53 GMT
+
+### Patches
+
+- Fix an issue where ApiConstructor inherited from ApiStaticMixin, but TypeScript constructors cannot be static
+
+## 7.1.1
+Mon, 27 May 2019 04:13:44 GMT
+
+### Patches
+
+- Make the strings returned by ApiItem.displayName less verbose
+- Improve formatting of the strings returned by ApiItem.getScopedNameWithinPackage()
+
+## 7.1.0
+Tue, 16 Apr 2019 11:01:37 GMT
+
+### Minor changes
+
+- Initial stable release of API Extractor 7
+
+## 7.0.28
+Wed, 20 Mar 2019 19:14:49 GMT
+
+_Version update only_
+
+## 7.0.27
+Mon, 18 Mar 2019 04:28:43 GMT
+
+### Patches
+
+- Add helper functions for ReleaseTag
+- Export IApiItemConstructor to eliminate the ae-forgotten-export warning
+
+## 7.0.26
+Wed, 13 Mar 2019 19:13:14 GMT
+
+### Patches
+
+- Refactor code to move the IndentedWriter API from api-extractor-model to api-documenter
+
+## 7.0.25
+Wed, 13 Mar 2019 01:14:05 GMT
+
+### Patches
+
+- Upgrade TSDoc
+
+## 7.0.24
+Mon, 11 Mar 2019 16:13:36 GMT
+
+### Patches
+
+- Initial setup of new package @microsoft/api-extractor-model
+

packages/api-extractor-model/LICENSE

@@ -0,0 +1,24 @@
+@microsoft/api-extractor
+
+Copyright (c) Microsoft Corporation. All rights reserved.
+
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

packages/api-extractor-model/README.md

@@ -0,0 +1,67 @@
+# @discordjs/api-extractor-model
+
+Use this library to read and write \*.api.json files as defined by the [API Extractor](https://api-extractor.com/) tool.
+These files are used to generate a documentation website for your TypeScript package. The files store the
+API signatures and doc comments that were extracted from your package.
+
+API documentation for this package: https://rushstack.io/pages/api/api-extractor-model/
+
+## Example Usage
+
+The following code sample shows how to load `example.api.json`, which would be generated by API Extractor
+when it analyzes a hypothetical NPM package called `example`:
+
+```ts
+import { ApiModel, ApiPackage } from '@discordjs/api-extractor-model';
+
+const apiModel: ApiModel = new ApiModel();
+const apiPackage: ApiPackage = apiModel.loadPackage('example.api.json');
+
+for (const member of apiPackage.members) {
+	console.log(member.displayName);
+}
+```
+
+The `ApiModel` is acts as a container for various packages that are loaded and operated on as a group.
+For example, a documentation tool may need to resolve `@link` references across different packages.
+In this case we would load the various packages into the `ApiModel`, and then use
+the `ApiModel.resolveDeclarationReference()` to resolve the `@link` targets.
+
+The data structure forms a tree of various classes that start with the `Api` prefix. The nesting hierarchy
+might look like this:
+
+```
+- ApiModel
+  - ApiPackage
+    - ApiEntryPoint
+      - ApiClass
+        - ApiMethod
+        - ApiProperty
+      - ApiEnum
+        - ApiEnumMember
+      - ApiInterface
+        - ApiMethodSignature
+        - ApiPropertySignature
+      - ApiNamespace
+        - (ApiClass, ApiEnum, ApiInterface, ...)
+```
+
+You can use the `ApiItem.members` property to traverse this tree.
+
+Note that the non-abstract classes (e.g. `ApiClass`, `ApiEnum`, `ApiInterface`, etc.) use
+TypeScript "mixin" functions (e.g. `ApiDeclaredItem`, `ApiItemContainerMixin`, etc.) to add various
+features that cannot be represented as a normal inheritance chain (since TypeScript does not allow a child class
+to extend more than one base class). The "mixin" is a TypeScript merged declaration with three components:
+the function that generates a subclass, an interface that describes the members of the subclass, and
+a namespace containing static members of the class.
+
+> For a complete project that uses these APIs to generate an API reference web site,
+> see the [@microsoft/api-documenter](https://www.npmjs.com/package/@microsoft/api-documenter) source code.
+
+## Links
+
+- [CHANGELOG.md](https://github.com/discordjs/discord.js/blob/main/packages/api-extractor-model/CHANGELOG.md) - Find
+  out what's new in the latest version
+- [API Reference](https://rushstack.io/pages/api/api-extractor-model/)
+
+API Extractor is part of the [Rush Stack](https://rushstack.io/) family of projects.

packages/api-extractor-model/config/api-extractor.json

@@ -0,0 +1,20 @@
+{
+	"$schema": "https://developer.microsoft.com/json-schemas/api-extractor/v7/api-extractor.schema.json",
+
+	"mainEntryPointFilePath": "<projectFolder>/lib/index.d.ts",
+
+	"apiReport": {
+		"enabled": true,
+		"reportFolder": "../../../common/reviews/api"
+	},
+
+	"docModel": {
+		"enabled": true,
+		"apiJsonFilePath": "../../../common/temp/api/<unscopedPackageName>.api.json"
+	},
+
+	"dtsRollup": {
+		"enabled": true,
+		"untrimmedFilePath": "<projectFolder>/dist/rollup.d.ts"
+	}
+}

packages/api-extractor-model/config/jest.config.json

@@ -0,0 +1,11 @@
+{
+	"extends": "@rushstack/heft-node-rig/profiles/default/config/jest.config.json",
+
+	// Enable code coverage for Jest
+	"collectCoverage": true,
+	"coverageDirectory": "<rootDir>/coverage",
+	"coverageReporters": ["cobertura", "html"],
+
+	// Use v8 coverage provider to avoid Babel
+	"coverageProvider": "v8"
+}

packages/api-extractor-model/package.json

@@ -0,0 +1,51 @@
+{
+	"name": "@discordjs/api-extractor-model",
+	"version": "7.28.2",
+	"description": "A helper library for loading and saving the .api.json files created by API Extractor",
+	"private": true,
+	"repository": {
+		"type": "git",
+		"url": "https://github.com/discordjs/discord.js.git",
+		"directory": "packages/api-extractor-model"
+	},
+	"homepage": "https://discord.js.org",
+	"funding": "https://github.com/discordjs/discord.js?sponsor",
+	"license": "MIT",
+	"main": "./dist/index.js",
+	"types": "./dist/index.d.ts",
+	"scripts": {
+		"build": "tsc --noEmit && tsup",
+		"lint": "prettier --check . && cross-env TIMING=1 eslint --format=pretty src",
+		"format": "prettier --write . && cross-env TIMING=1 eslint --fix --format=pretty src"
+	},
+	"exports": {
+		".": {
+			"require": {
+				"types": "./dist/index.d.ts",
+				"default": "./dist/index.js"
+			},
+			"import": {
+				"types": "./dist/index.d.mts",
+				"default": "./dist/index.mjs"
+			}
+		}
+	},
+	"dependencies": {
+		"@microsoft/tsdoc": "0.14.2",
+		"@microsoft/tsdoc-config": "0.16.2",
+		"@rushstack/node-core-library": "4.1.0"
+	},
+	"devDependencies": {
+		"@types/jest": "^29.5.12",
+		"@types/node": "^18.19.45",
+		"cross-env": "^7.0.3",
+		"eslint": "^8.57.0",
+		"eslint-config-neon": "^0.1.62",
+		"eslint-formatter-pretty": "^6.0.1",
+		"jest": "^29.7.0",
+		"prettier": "^3.3.3",
+		"tsup": "^8.2.4",
+		"turbo": "^2.0.14",
+		"typescript": "~5.5.4"
+	}
+}

packages/api-extractor-model/src/aedoc/AedocDefinitions.ts

@@ -0,0 +1,68 @@
+// Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license.
+// See LICENSE in the project root for license information.
+
+import { TSDocConfiguration, TSDocTagDefinition, TSDocTagSyntaxKind, StandardTags } from '@microsoft/tsdoc';
+
+/**
+ * @internal
+ * @deprecated - tsdoc configuration is now constructed from tsdoc.json files associated with each package.
+ */
+export class AedocDefinitions {
+	public static readonly betaDocumentation: TSDocTagDefinition = new TSDocTagDefinition({
+		tagName: '@betaDocumentation',
+		syntaxKind: TSDocTagSyntaxKind.ModifierTag,
+	});
+
+	public static readonly internalRemarks: TSDocTagDefinition = new TSDocTagDefinition({
+		tagName: '@internalRemarks',
+		syntaxKind: TSDocTagSyntaxKind.BlockTag,
+	});
+
+	public static readonly preapprovedTag: TSDocTagDefinition = new TSDocTagDefinition({
+		tagName: '@preapproved',
+		syntaxKind: TSDocTagSyntaxKind.ModifierTag,
+	});
+
+	public static get tsdocConfiguration(): TSDocConfiguration {
+		if (!AedocDefinitions._tsdocConfiguration) {
+			const configuration: TSDocConfiguration = new TSDocConfiguration();
+			configuration.addTagDefinitions(
+				[AedocDefinitions.betaDocumentation, AedocDefinitions.internalRemarks, AedocDefinitions.preapprovedTag],
+				true,
+			);
+
+			configuration.setSupportForTags(
+				[
+					StandardTags.alpha,
+					StandardTags.beta,
+					StandardTags.decorator,
+					StandardTags.defaultValue,
+					StandardTags.deprecated,
+					StandardTags.eventProperty,
+					StandardTags.example,
+					StandardTags.inheritDoc,
+					StandardTags.internal,
+					StandardTags.link,
+					StandardTags.override,
+					StandardTags.packageDocumentation,
+					StandardTags.param,
+					StandardTags.privateRemarks,
+					StandardTags.public,
+					StandardTags.readonly,
+					StandardTags.remarks,
+					StandardTags.returns,
+					StandardTags.sealed,
+					StandardTags.throws,
+					StandardTags.virtual,
+				],
+				true,
+			);
+
+			AedocDefinitions._tsdocConfiguration = configuration;
+		}
+
+		return AedocDefinitions._tsdocConfiguration;
+	}
+
+	private static _tsdocConfiguration: TSDocConfiguration | undefined;
+}

packages/api-extractor-model/src/aedoc/ReleaseTag.ts

@@ -0,0 +1,88 @@
+// Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license.
+// See LICENSE in the project root for license information.
+
+/**
+ * A "release tag" is a custom TSDoc tag that is applied to an API to communicate the level of support
+ * provided for third-party developers.
+ *
+ * @remarks
+ *
+ * The four release tags are: `@internal`, `@alpha`, `@beta`, and `@public`. They are applied to API items such
+ * as classes, member functions, enums, etc.  The release tag applies recursively to members of a container
+ * (e.g. class or interface). For example, if a class is marked as `@beta`, then all of its members automatically
+ * have this status; you DON'T need add the `@beta` tag to each member function. However, you could add
+ * `@internal` to a member function to give it a different release status.
+ * @public
+ */
+export enum ReleaseTag {
+	/**
+	 * No release tag was specified in the AEDoc summary.
+	 */
+	None = 0,
+	/**
+	 * Indicates that an API item is meant only for usage by other NPM packages from the same
+	 * maintainer. Third parties should never use "internal" APIs. (To emphasize this, their
+	 * names are prefixed by underscores.)
+	 */
+	Internal = 1,
+	/**
+	 * Indicates that an API item is eventually intended to be public, but currently is in an
+	 * early stage of development. Third parties should not use "alpha" APIs.
+	 */
+	Alpha = 2,
+	/**
+	 * Indicates that an API item has been released in an experimental state. Third parties are
+	 * encouraged to try it and provide feedback. However, a "beta" API should NOT be used
+	 * in production.
+	 */
+	Beta = 3,
+	/**
+	 * Indicates that an API item has been officially released. It is part of the supported
+	 * contract (e.g. SemVer) for a package.
+	 */
+	Public = 4,
+}
+
+/**
+ * Helper functions for working with the `ReleaseTag` enum.
+ *
+ * @public
+ */
+
+// export namespace ReleaseTag {
+/**
+ * Returns the TSDoc tag name for a `ReleaseTag` value.
+ *
+ * @remarks
+ * For example, `getTagName(ReleaseTag.Internal)` would return the string `@internal`.
+ */
+export function getTagName(releaseTag: ReleaseTag): string {
+	switch (releaseTag) {
+		case ReleaseTag.None:
+			return '(none)';
+		case ReleaseTag.Internal:
+			return '@internal';
+		case ReleaseTag.Alpha:
+			return '@alpha';
+		case ReleaseTag.Beta:
+			return '@beta';
+		case ReleaseTag.Public:
+			return '@public';
+		default:
+			throw new Error('Unsupported release tag');
+	}
+}
+
+/**
+ * Compares two `ReleaseTag` values. Their values must not be `ReleaseTag.None`.
+ *
+ * @returns 0 if `a` and `b` are equal, a positive number if `a` is more public than `b`,
+ * and a negative number if `a` is less public than `b`.
+ * @remarks
+ * For example, `compareReleaseTag(ReleaseTag.Beta, ReleaseTag.Alpha)` will return a positive
+ * number because beta is more public than alpha.
+ */
+export function compare(a: ReleaseTag, b: ReleaseTag): number {
+	return a - b;
+}
+// }

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

@@ -0,0 +1,85 @@
+// Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license.
+// See LICENSE in the project root for license information.
+
+/**
+ * Use this library to read and write *.api.json files as defined by the
+ * {@link https://api-extractor.com/ | API Extractor}  tool.  These files are used to generate a documentation
+ * website for your TypeScript package.  The files store the API signatures and doc comments that were extracted
+ * from your package.
+ *
+ * @packageDocumentation
+ */
+
+export { AedocDefinitions } from './aedoc/AedocDefinitions.js';
+export { ReleaseTag, compare as releaseTagCompare, getTagName as releaseTagGetTagName } from './aedoc/ReleaseTag.js';
+
+// items
+export { type IApiDeclaredItemOptions, ApiDeclaredItem } from './items/ApiDeclaredItem.js';
+export { type IApiDocumentedItemOptions, ApiDocumentedItem } from './items/ApiDocumentedItem.js';
+export { ApiItemKind, type IApiItemOptions, ApiItem, type IApiItemConstructor } from './items/ApiItem.js';
+export { type IApiPropertyItemOptions, ApiPropertyItem } from './items/ApiPropertyItem.js';
+
+// mixins
+export {
+	type IApiParameterListMixinOptions,
+	type IApiParameterOptions,
+	ApiParameterListMixin,
+} from './mixins/ApiParameterListMixin.js';
+export {
+	type IApiTypeParameterOptions,
+	type IApiTypeParameterListMixinOptions,
+	ApiTypeParameterListMixin,
+} from './mixins/ApiTypeParameterListMixin.js';
+export { type IApiAbstractMixinOptions, ApiAbstractMixin } from './mixins/ApiAbstractMixin.js';
+export { type IApiItemContainerMixinOptions, ApiItemContainerMixin } from './mixins/ApiItemContainerMixin.js';
+export { type IApiProtectedMixinOptions, ApiProtectedMixin } from './mixins/ApiProtectedMixin.js';
+export { type IApiReleaseTagMixinOptions, ApiReleaseTagMixin } from './mixins/ApiReleaseTagMixin.js';
+export { type IApiReturnTypeMixinOptions, ApiReturnTypeMixin } from './mixins/ApiReturnTypeMixin.js';
+export { type IApiStaticMixinOptions, ApiStaticMixin } from './mixins/ApiStaticMixin.js';
+export { type IApiNameMixinOptions, ApiNameMixin } from './mixins/ApiNameMixin.js';
+export { type IApiOptionalMixinOptions, ApiOptionalMixin } from './mixins/ApiOptionalMixin.js';
+export { type IApiReadonlyMixinOptions, ApiReadonlyMixin } from './mixins/ApiReadonlyMixin.js';
+export { type IApiInitializerMixinOptions, ApiInitializerMixin } from './mixins/ApiInitializerMixin.js';
+export { type IApiExportedMixinOptions, ApiExportedMixin } from './mixins/ApiExportedMixin.js';
+export {
+	type IFindApiItemsResult,
+	type IFindApiItemsMessage,
+	FindApiItemsMessageId,
+} from './mixins/IFindApiItemsResult.js';
+
+export {
+	ExcerptTokenKind,
+	type IExcerptTokenRange,
+	type IExcerptToken,
+	ExcerptToken,
+	Excerpt,
+} from './mixins/Excerpt.js';
+export type { Constructor, PropertiesOf } from './mixins/Mixin.js';
+
+// model
+export { type IApiCallSignatureOptions, ApiCallSignature } from './model/ApiCallSignature.js';
+export { type IApiClassOptions, ApiClass, type IExcerptTokenRangeWithTypeParameters } from './model/ApiClass.js';
+export { type IApiConstructorOptions, ApiConstructor } from './model/ApiConstructor.js';
+export { type IApiConstructSignatureOptions, ApiConstructSignature } from './model/ApiConstructSignature.js';
+export { type IApiEntryPointOptions, ApiEntryPoint } from './model/ApiEntryPoint.js';
+export { type IApiEnumOptions, ApiEnum } from './model/ApiEnum.js';
+export { type IApiEnumMemberOptions, ApiEnumMember, EnumMemberOrder } from './model/ApiEnumMember.js';
+export { type IApiEventOptions, ApiEvent } from './model/ApiEvent.js';
+export { type IApiFunctionOptions, ApiFunction } from './model/ApiFunction.js';
+export { type IApiIndexSignatureOptions, ApiIndexSignature } from './model/ApiIndexSignature.js';
+export { type IApiInterfaceOptions, ApiInterface } from './model/ApiInterface.js';
+export { type IApiMethodOptions, ApiMethod } from './model/ApiMethod.js';
+export { type IApiMethodSignatureOptions, ApiMethodSignature } from './model/ApiMethodSignature.js';
+export { ApiModel } from './model/ApiModel.js';
+export { type IApiNamespaceOptions, ApiNamespace } from './model/ApiNamespace.js';
+export { type IApiPackageOptions, ApiPackage, type IApiPackageSaveOptions } from './model/ApiPackage.js';
+export { type IParameterOptions, Parameter } from './model/Parameter.js';
+export { type IApiPropertyOptions, ApiProperty } from './model/ApiProperty.js';
+export { type IApiPropertySignatureOptions, ApiPropertySignature } from './model/ApiPropertySignature.js';
+export { type IApiTypeAliasOptions, ApiTypeAlias } from './model/ApiTypeAlias.js';
+export { type ITypeParameterOptions, TypeParameter } from './model/TypeParameter.js';
+export { type IApiVariableOptions, ApiVariable } from './model/ApiVariable.js';
+export type { IResolveDeclarationReferenceResult } from './model/ModelReferenceResolver.js';
+export { HeritageType } from './model/HeritageType.js';
+export { type ISourceLocationOptions, SourceLocation } from './model/SourceLocation.js';
+export { Navigation, Meaning } from './items/ApiItem.js';

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

@@ -0,0 +1,225 @@
+// Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license.
+// See LICENSE in the project root for license information.
+
+import { DeclarationReference } from '@microsoft/tsdoc/lib-commonjs/beta/DeclarationReference.js';
+import { Excerpt, ExcerptToken, type IExcerptTokenRange, type IExcerptToken } from '../mixins/Excerpt.js';
+import type { DeserializerContext } from '../model/DeserializerContext.js';
+import { SourceLocation } from '../model/SourceLocation.js';
+import { ApiDocumentedItem, type IApiDocumentedItemJson, type IApiDocumentedItemOptions } from './ApiDocumentedItem.js';
+import type { ApiItem } from './ApiItem.js';
+
+/**
+ * Constructor options for {@link ApiDeclaredItem}.
+ *
+ * @public
+ */
+export interface IApiDeclaredItemOptions extends IApiDocumentedItemOptions {
+	excerptTokens: IExcerptToken[];
+	fileColumn?: number | undefined;
+	fileLine?: number | undefined;
+	fileUrlPath?: string | undefined;
+}
+
+export interface IApiDeclaredItemJson extends IApiDocumentedItemJson {
+	excerptTokens: IExcerptToken[];
+	fileColumn?: number;
+	fileLine?: number;
+	fileUrlPath?: string | undefined;
+}
+
+/**
+ * The base class for API items that have an associated source code excerpt containing a TypeScript declaration.
+ *
+ * @remarks
+ *
+ * This is part of the {@link ApiModel} hierarchy of classes, which are serializable representations of
+ * API declarations.
+ *
+ * Most `ApiItem` subclasses have declarations and thus extend `ApiDeclaredItem`.  Counterexamples include
+ * `ApiModel` and `ApiPackage`, which do not have any corresponding TypeScript source code.
+ * @public
+ */
+
+export class ApiDeclaredItem extends ApiDocumentedItem {
+	private readonly _excerptTokens: ExcerptToken[];
+
+	private readonly _excerpt: Excerpt;
+
+	private readonly _fileUrlPath?: string | undefined;
+
+	private readonly _fileLine?: number | undefined;
+
+	private readonly _fileColumn?: number | undefined;
+
+	private _sourceLocation?: SourceLocation;
+
+	public constructor(options: IApiDeclaredItemOptions) {
+		super(options);
+
+		this._excerptTokens = options.excerptTokens.map((token) => {
+			const canonicalReference: DeclarationReference | undefined =
+				token.canonicalReference === undefined ? undefined : DeclarationReference.parse(token.canonicalReference);
+			return new ExcerptToken(token.kind, token.text, canonicalReference);
+		});
+		this._excerpt = new Excerpt(this.excerptTokens, { startIndex: 0, endIndex: this.excerptTokens.length });
+		this._fileUrlPath = options.fileUrlPath;
+		this._fileLine = options.fileLine;
+		this._fileColumn = options.fileColumn;
+	}
+
+	/**
+	 * @override
+	 */
+	public static override onDeserializeInto(
+		options: Partial<IApiDeclaredItemOptions>,
+		context: DeserializerContext,
+		jsonObject: IApiDeclaredItemJson,
+	): void {
+		super.onDeserializeInto(options, context, jsonObject);
+
+		options.excerptTokens = jsonObject.excerptTokens;
+		options.fileUrlPath = jsonObject.fileUrlPath;
+		options.fileLine = jsonObject.fileLine;
+		options.fileColumn = jsonObject.fileColumn;
+	}
+
+	/**
+	 * The source code excerpt where the API item is declared.
+	 */
+	public get excerpt(): Excerpt {
+		return this._excerpt;
+	}
+
+	/**
+	 * The individual source code tokens that comprise the main excerpt.
+	 */
+	public get excerptTokens(): readonly ExcerptToken[] {
+		return this._excerptTokens;
+	}
+
+	/**
+	 * The file URL path relative to the `projectFolder` and `projectFolderURL` fields
+	 * as defined in the `api-extractor.json` config. Is `undefined` if the path is
+	 * the same as the parent API item's.
+	 */
+	public get fileUrlPath(): string | undefined {
+		return this._fileUrlPath;
+	}
+
+	/**
+	 * The line in the `fileUrlPath` where the API item is declared.
+	 */
+	public get fileLine(): number | undefined {
+		return this._fileLine;
+	}
+
+	/**
+	 * The column in the `fileUrlPath` where the API item is declared.
+	 */
+	public get fileColumn(): number | undefined {
+		return this._fileColumn;
+	}
+
+	/**
+	 * Returns the source location where the API item is declared.
+	 */
+	public get sourceLocation(): SourceLocation {
+		if (!this._sourceLocation) {
+			this._sourceLocation = this._buildSourceLocation();
+		}
+
+		return this._sourceLocation;
+	}
+
+	/**
+	 * If the API item has certain important modifier tags such as `@sealed`, `@virtual`, or `@override`,
+	 * this prepends them as a doc comment above the excerpt.
+	 */
+	public getExcerptWithModifiers(): string {
+		const excerpt: string = this.excerpt.text;
+		const modifierTags: string[] = [];
+
+		if (excerpt.length > 0 && this instanceof ApiDocumentedItem) {
+			if (this.tsdocComment) {
+				if (this.tsdocComment.modifierTagSet.isSealed()) {
+					modifierTags.push('@sealed');
+				}
+
+				if (this.tsdocComment.modifierTagSet.isVirtual()) {
+					modifierTags.push('@virtual');
+				}
+
+				if (this.tsdocComment.modifierTagSet.isOverride()) {
+					modifierTags.push('@override');
+				}
+			}
+
+			if (modifierTags.length > 0) {
+				return '/** ' + modifierTags.join(' ') + ' */\n' + excerpt;
+			}
+		}
+
+		return excerpt;
+	}
+
+	/**
+	 * @override
+	 */
+	public override serializeInto(jsonObject: Partial<IApiDeclaredItemJson>): void {
+		super.serializeInto(jsonObject);
+		jsonObject.excerptTokens = this.excerptTokens.map((x) => {
+			const excerptToken: IExcerptToken = { kind: x.kind, text: x.text };
+			if (x.canonicalReference !== undefined) {
+				excerptToken.canonicalReference = x.canonicalReference.toString();
+			}
+
+			return excerptToken;
+		});
+
+		// Only serialize this API item's file URL path if it exists and it's different from its parent's
+		// (a little optimization to keep the doc model succinct).
+		if (
+			this.fileUrlPath &&
+			(!(this.parent instanceof ApiDeclaredItem) || this.fileUrlPath !== this.parent.fileUrlPath)
+		) {
+			jsonObject.fileUrlPath = this.fileUrlPath;
+		}
+
+		if (this.fileLine) {
+			jsonObject.fileLine = this.fileLine;
+		}
+
+		if (this.fileColumn) {
+			jsonObject.fileColumn = this.fileColumn;
+		}
+	}
+
+	/**
+	 * Constructs a new {@link Excerpt} corresponding to the provided token range.
+	 */
+	public buildExcerpt(tokenRange: IExcerptTokenRange): Excerpt {
+		return new Excerpt(this.excerptTokens, tokenRange);
+	}
+
+	/**
+	 * Builds the cached object used by the `sourceLocation` property.
+	 */
+	private _buildSourceLocation(): SourceLocation {
+		const projectFolderUrl: string | undefined = this.getAssociatedPackage()?.projectFolderUrl;
+
+		let fileUrlPath: string | undefined;
+		for (let current: ApiItem | undefined = this; current !== undefined; current = current.parent) {
+			if (current instanceof ApiDeclaredItem && current.fileUrlPath) {
+				fileUrlPath = current.fileUrlPath;
+				break;
+			}
+		}
+
+		return new SourceLocation({
+			projectFolderUrl,
+			fileUrlPath,
+			sourceFileColumn: this.fileColumn,
+			sourceFileLine: this.fileLine,
+		});
+	}
+}

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

@@ -0,0 +1,78 @@
+// Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license.
+// See LICENSE in the project root for license information.
+
+import * as tsdoc from '@microsoft/tsdoc';
+import type { DeserializerContext } from '../model/DeserializerContext.js';
+import { ApiItem, type IApiItemOptions, type IApiItemJson } from './ApiItem.js';
+
+/**
+ * Constructor options for {@link ApiDocumentedItem}.
+ *
+ * @public
+ */
+export interface IApiDocumentedItemOptions extends IApiItemOptions {
+	docComment: tsdoc.DocComment | undefined;
+}
+
+export interface IApiDocumentedItemJson extends IApiItemJson {
+	docComment: string;
+}
+
+/**
+ * An abstract base class for API declarations that can have an associated TSDoc comment.
+ *
+ * @remarks
+ *
+ * This is part of the {@link ApiModel} hierarchy of classes, which are serializable representations of
+ * API declarations.
+ * @public
+ */
+export class ApiDocumentedItem extends ApiItem {
+	private readonly _tsdocComment: tsdoc.DocComment | undefined;
+
+	public constructor(options: IApiDocumentedItemOptions) {
+		super(options);
+		this._tsdocComment = options.docComment;
+	}
+
+	/**
+	 * @override
+	 */
+	public static override onDeserializeInto(
+		options: Partial<IApiDocumentedItemOptions>,
+		context: DeserializerContext,
+		jsonObject: IApiItemJson,
+	): void {
+		super.onDeserializeInto(options, context, jsonObject);
+
+		const documentedJson: IApiDocumentedItemJson = jsonObject as IApiDocumentedItemJson;
+
+		if (documentedJson.docComment) {
+			const tsdocParser: tsdoc.TSDocParser = new tsdoc.TSDocParser(context.tsdocConfiguration);
+
+			// NOTE: For now, we ignore TSDoc errors found in a serialized .api.json file.
+			// Normally these errors would have already been reported by API Extractor during analysis.
+			// However, they could also arise if the JSON file was edited manually, or if the file was saved
+			// using a different release of the software that used an incompatible syntax.
+			const parserContext: tsdoc.ParserContext = tsdocParser.parseString(documentedJson.docComment);
+
+			options.docComment = parserContext.docComment;
+		}
+	}
+
+	public get tsdocComment(): tsdoc.DocComment | undefined {
+		return this._tsdocComment;
+	}
+
+	/**
+	 * @override
+	 */
+	public override serializeInto(jsonObject: Partial<IApiDocumentedItemJson>): void {
+		super.serializeInto(jsonObject);
+		if (this.tsdocComment === undefined) {
+			jsonObject.docComment = '';
+		} else {
+			jsonObject.docComment = this.tsdocComment.emitAsTsdoc();
+		}
+	}
+}

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

@@ -0,0 +1,375 @@
+// Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license.
+// See LICENSE in the project root for license information.
+
+import type { DeclarationReference } from '@microsoft/tsdoc/lib-commonjs/beta/DeclarationReference.js';
+import { InternalError } from '@rushstack/node-core-library';
+import { ApiItemContainerMixin } from '../mixins/ApiItemContainerMixin.js';
+import { ApiParameterListMixin } from '../mixins/ApiParameterListMixin.js';
+import type { Constructor, PropertiesOf } from '../mixins/Mixin.js';
+import type { ApiModel } from '../model/ApiModel.js';
+import type { ApiPackage } from '../model/ApiPackage.js';
+import type { DocgenJson } from '../model/Deserializer';
+import type { DeserializerContext } from '../model/DeserializerContext.js';
+
+/**
+ * The type returned by the {@link ApiItem.kind} property, which can be used to easily distinguish subclasses of
+ * {@link ApiItem}.
+ *
+ * @public
+ */
+export enum ApiItemKind {
+	CallSignature = 'CallSignature',
+	Class = 'Class',
+	ConstructSignature = 'ConstructSignature',
+	Constructor = 'Constructor',
+	EntryPoint = 'EntryPoint',
+	Enum = 'Enum',
+	EnumMember = 'EnumMember',
+	Event = 'Event',
+	Function = 'Function',
+	IndexSignature = 'IndexSignature',
+	Interface = 'Interface',
+	Method = 'Method',
+	MethodSignature = 'MethodSignature',
+	Model = 'Model',
+	Namespace = 'Namespace',
+	None = 'None',
+	Package = 'Package',
+	Property = 'Property',
+	PropertySignature = 'PropertySignature',
+	TypeAlias = 'TypeAlias',
+	Variable = 'Variable',
+}
+/**
+ * Indicates the symbol table from which to resolve the next symbol component.
+ *
+ * @beta
+ */
+export enum Navigation {
+	Exports = '.',
+	Locals = '~',
+	Members = '#',
+}
+/**
+ * @beta
+ */
+export enum Meaning {
+	CallSignature = 'call',
+	Class = 'class',
+	ComplexType = 'complex',
+	ConstructSignature = 'new',
+	Constructor = 'constructor',
+	Enum = 'enum',
+	Event = 'event',
+	Function = 'function',
+	IndexSignature = 'index',
+	Interface = 'interface',
+	Member = 'member',
+	Namespace = 'namespace',
+	TypeAlias = 'type',
+	Variable = 'var',
+}
+
+/**
+ * Constructor options for {@link ApiItem}.
+ *
+ * @public
+ */
+// eslint-disable-next-line @typescript-eslint/no-empty-interface
+export interface IApiItemOptions {}
+
+export interface IApiItemJson {
+	canonicalReference: string;
+	kind: ApiItemKind;
+}
+
+// PRIVATE - Allows ApiItemContainerMixin to assign the parent.
+//
+export const apiItem_onParentChanged: unique symbol = Symbol('ApiItem._onAddToContainer');
+
+/**
+ * The abstract base class for all members of an `ApiModel` object.
+ *
+ * @remarks
+ * This is part of the {@link ApiModel} hierarchy of classes, which are serializable representations of
+ * API declarations.
+ * @public
+ */
+export class ApiItem {
+	private _canonicalReference: DeclarationReference | undefined;
+
+	private _parent: ApiItem | undefined;
+
+	// eslint-disable-next-line @typescript-eslint/no-useless-constructor
+	public constructor(_options: IApiItemOptions) {
+		// ("options" is not used here, but part of the inheritance pattern)
+	}
+
+	public static deserialize(jsonObject: IApiItemJson, context: DeserializerContext): ApiItem {
+		// The Deserializer class is coupled with a ton of other classes, so  we delay loading it
+		// to avoid ES5 circular imports.
+		// eslint-disable-next-line @typescript-eslint/consistent-type-imports, @typescript-eslint/no-require-imports, @typescript-eslint/no-var-requires
+		const deserializerModule: typeof import('../model/Deserializer') = require('../model/Deserializer');
+		return deserializerModule.Deserializer.deserialize(context, jsonObject);
+	}
+
+	public static deserializeDocgen(jsonObject: DocgenJson, _package: string): ApiItem {
+		// eslint-disable-next-line @typescript-eslint/consistent-type-imports, @typescript-eslint/no-require-imports, @typescript-eslint/no-var-requires
+		const deserializerModule: typeof import('../model/Deserializer') = require('../model/Deserializer');
+		return deserializerModule.Deserializer.deserializeDocgen(jsonObject, _package);
+	}
+
+	/**
+	 * @virtual
+	 */
+	public static onDeserializeInto(
+		_options: Partial<IApiItemOptions>,
+		_context: DeserializerContext,
+		_jsonObject: IApiItemJson,
+	): void {
+		// (implemented by subclasses)
+	}
+
+	/**
+	 * @virtual
+	 */
+	public serializeInto(jsonObject: Partial<IApiItemJson>): void {
+		jsonObject.kind = this.kind;
+		jsonObject.canonicalReference = this.canonicalReference.toString();
+	}
+
+	/**
+	 * Identifies the subclass of the `ApiItem` base class.
+	 *
+	 * @virtual
+	 */
+	public get kind(): ApiItemKind {
+		throw new Error('ApiItem.kind was not implemented by the child class');
+	}
+
+	/**
+	 * Warning: This API is used internally by API extractor but is not yet ready for general usage.
+	 *
+	 * @remarks
+	 *
+	 * Returns a `DeclarationReference` object using the experimental new declaration reference notation.
+	 * @beta
+	 */
+	public get canonicalReference(): DeclarationReference {
+		if (!this._canonicalReference) {
+			try {
+				this._canonicalReference = this.buildCanonicalReference();
+			} catch (error) {
+				const name: string = this.getScopedNameWithinPackage() || this.displayName;
+				throw new InternalError(`Error building canonical reference for ${name}:\n` + (error as Error).message);
+			}
+		}
+
+		return this._canonicalReference;
+	}
+
+	/**
+	 * Returns a string key that can be used to efficiently retrieve an `ApiItem` from an `ApiItemContainerMixin`.
+	 * The key is unique within the container.  Its format is undocumented and may change at any time.
+	 *
+	 * @remarks
+	 * Use the `getContainerKey()` static member to construct the key.  Each subclass has a different implementation
+	 * of this function, according to the aspects that are important for identifying it.
+	 * @virtual
+	 */
+	public get containerKey(): string {
+		throw new InternalError('ApiItem.containerKey was not implemented by the child class');
+	}
+
+	/**
+	 * Returns a name for this object that can be used in diagnostic messages, for example.
+	 *
+	 * @remarks
+	 * For an object that inherits ApiNameMixin, this will return the declared name (e.g. the name of a TypeScript
+	 * function).  Otherwise, it will return a string such as "(call signature)" or "(model)".
+	 * @virtual
+	 */
+	public get displayName(): string {
+		switch (this.kind) {
+			case ApiItemKind.CallSignature:
+				return '(call)';
+			case ApiItemKind.Constructor:
+				return '(constructor)';
+			case ApiItemKind.ConstructSignature:
+				return '(new)';
+			case ApiItemKind.IndexSignature:
+				return '(indexer)';
+			case ApiItemKind.Model:
+				return '(model)';
+			default:
+				return '(???)'; // All other types should inherit ApiNameMixin which will override this property
+		}
+	}
+
+	/**
+	 * If this item was added to a ApiItemContainerMixin item, then this returns the container item.
+	 * If this is an Parameter that was added to a method or function, then this returns the function item.
+	 * Otherwise, it returns undefined.
+	 *
+	 * @virtual
+	 */
+	public get parent(): ApiItem | undefined {
+		return this._parent;
+	}
+
+	/**
+	 * This property supports a visitor pattern for walking the tree.
+	 * For items with ApiItemContainerMixin, it returns the contained items, sorted alphabetically.
+	 * Otherwise it returns an empty array.
+	 *
+	 * @virtual
+	 */
+	public get members(): readonly ApiItem[] {
+		return [];
+	}
+
+	/**
+	 * If this item has a name (i.e. extends `ApiNameMixin`), then return all items that have the same parent
+	 * and the same name.  Otherwise, return all items that have the same parent and the same `ApiItemKind`.
+	 *
+	 * @remarks
+	 * Examples: For a function, this would return all overloads for the function.  For a constructor, this would
+	 * return all overloads for the constructor.  For a merged declaration (e.g. a `namespace` and `enum` with the
+	 * same name), this would return both declarations.  If this item does not have a parent, or if it is the only
+	 * item of its name/kind, then the result is an array containing only this item.
+	 */
+	public getMergedSiblings(): readonly ApiItem[] {
+		const parent: ApiItem | undefined = this._parent;
+		if (parent && ApiItemContainerMixin.isBaseClassOf(parent)) {
+			return parent._getMergedSiblingsForMember(this);
+		}
+
+		return [];
+	}
+
+	/**
+	 * Returns the chain of ancestors, starting from the root of the tree, and ending with the this item.
+	 */
+	public getHierarchy(): readonly ApiItem[] {
+		const hierarchy: ApiItem[] = [];
+		for (let current: ApiItem | undefined = this; current !== undefined; current = current.parent) {
+			hierarchy.push(current);
+		}
+
+		hierarchy.reverse();
+		return hierarchy;
+	}
+
+	/**
+	 * This returns a scoped name such as `"Namespace1.Namespace2.MyClass.myMember()"`.  It does not include the
+	 * package name or entry point.
+	 *
+	 * @remarks
+	 * If called on an ApiEntrypoint, ApiPackage, or ApiModel item, the result is an empty string.
+	 */
+	public getScopedNameWithinPackage(): string {
+		const reversedParts: string[] = [];
+
+		for (let current: ApiItem | undefined = this; current !== undefined; current = current.parent) {
+			if (
+				current.kind === ApiItemKind.Model ||
+				current.kind === ApiItemKind.Package ||
+				current.kind === ApiItemKind.EntryPoint
+			) {
+				break;
+			}
+
+			if (reversedParts.length === 0) {
+				switch (current.kind) {
+					case ApiItemKind.CallSignature:
+					case ApiItemKind.ConstructSignature:
+					case ApiItemKind.Constructor:
+					case ApiItemKind.IndexSignature:
+						// These functional forms don't have a proper name, so we don't append the "()" suffix
+						break;
+					default:
+						if (ApiParameterListMixin.isBaseClassOf(current)) {
+							reversedParts.push('()');
+						}
+				}
+			} else {
+				reversedParts.push('.');
+			}
+
+			reversedParts.push(current.displayName);
+		}
+
+		return reversedParts.reverse().join('');
+	}
+
+	/**
+	 * If this item is an ApiPackage or has an ApiPackage as one of its parents, then that object is returned.
+	 * Otherwise undefined is returned.
+	 */
+	public getAssociatedPackage(): ApiPackage | undefined {
+		for (let current: ApiItem | undefined = this; current !== undefined; current = current.parent) {
+			if (current.kind === ApiItemKind.Package) {
+				return current as ApiPackage;
+			}
+		}
+
+		return undefined;
+	}
+
+	/**
+	 * If this item is an ApiModel or has an ApiModel as one of its parents, then that object is returned.
+	 * Otherwise undefined is returned.
+	 */
+	public getAssociatedModel(): ApiModel | undefined {
+		for (let current: ApiItem | undefined = this; current !== undefined; current = current.parent) {
+			if (current.kind === ApiItemKind.Model) {
+				return current as ApiModel;
+			}
+		}
+
+		return undefined;
+	}
+
+	/**
+	 * A text string whose value determines the sort order that is automatically applied by the
+	 * {@link (ApiItemContainerMixin:interface)} class.
+	 *
+	 * @remarks
+	 * The value of this string is undocumented and may change at any time.
+	 * If {@link (ApiItemContainerMixin:interface).preserveMemberOrder} is enabled for the `ApiItem`'s parent,
+	 * then no sorting is performed, and this key is not used.
+	 * @virtual
+	 */
+	public getSortKey(): string {
+		return this.containerKey;
+	}
+
+	/**
+	 * PRIVATE
+	 *
+	 * @privateRemarks
+	 * Allows ApiItemContainerMixin to assign the parent when the item is added to a container.
+	 * @internal
+	 */
+	public [apiItem_onParentChanged](parent: ApiItem | undefined): void {
+		this._parent = parent;
+		this._canonicalReference = undefined;
+	}
+
+	/**
+	 * Builds the cached object used by the `canonicalReference` property.
+	 *
+	 * @virtual
+	 */
+	protected buildCanonicalReference(): DeclarationReference {
+		throw new InternalError('ApiItem.canonicalReference was not implemented by the child class');
+	}
+}
+
+/**
+ * This abstraction is used by the mixin pattern.
+ * It describes a class type that inherits from {@link ApiItem}.
+ *
+ * @public
+ */
+export interface IApiItemConstructor extends Constructor<ApiItem>, PropertiesOf<typeof ApiItem> {}

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

@@ -0,0 +1,88 @@
+// Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license.
+// See LICENSE in the project root for license information.
+
+import { type IApiNameMixinOptions, ApiNameMixin } from '../mixins/ApiNameMixin.js';
+import { ApiOptionalMixin, type IApiOptionalMixinOptions } from '../mixins/ApiOptionalMixin.js';
+import { ApiReadonlyMixin, type IApiReadonlyMixinOptions } from '../mixins/ApiReadonlyMixin.js';
+import { ApiReleaseTagMixin, type IApiReleaseTagMixinOptions } from '../mixins/ApiReleaseTagMixin.js';
+import type { Excerpt, IExcerptTokenRange } from '../mixins/Excerpt.js';
+import type { DeserializerContext } from '../model/DeserializerContext.js';
+import { type IApiDeclaredItemOptions, ApiDeclaredItem, type IApiDeclaredItemJson } from './ApiDeclaredItem.js';
+
+/**
+ * Constructor options for {@link ApiPropertyItem}.
+ *
+ * @public
+ */
+export interface IApiPropertyItemOptions
+	extends IApiNameMixinOptions,
+		IApiReleaseTagMixinOptions,
+		IApiOptionalMixinOptions,
+		IApiReadonlyMixinOptions,
+		IApiDeclaredItemOptions {
+	propertyTypeTokenRange: IExcerptTokenRange;
+}
+
+export interface IApiPropertyItemJson extends IApiDeclaredItemJson {
+	propertyTypeTokenRange: IExcerptTokenRange;
+}
+
+/**
+ * The abstract base class for {@link ApiProperty} and {@link ApiPropertySignature}.
+ *
+ * @public
+ */
+export class ApiPropertyItem extends ApiNameMixin(
+	ApiReleaseTagMixin(ApiOptionalMixin(ApiReadonlyMixin(ApiDeclaredItem))),
+) {
+	/**
+	 * An {@link Excerpt} that describes the type of the property.
+	 */
+	public readonly propertyTypeExcerpt: Excerpt;
+
+	public constructor(options: IApiPropertyItemOptions) {
+		super(options);
+
+		this.propertyTypeExcerpt = this.buildExcerpt(options.propertyTypeTokenRange);
+	}
+
+	/**
+	 * @override
+	 */
+	public static override onDeserializeInto(
+		options: Partial<IApiPropertyItemOptions>,
+		context: DeserializerContext,
+		jsonObject: IApiPropertyItemJson,
+	): void {
+		super.onDeserializeInto(options, context, jsonObject);
+
+		options.propertyTypeTokenRange = jsonObject.propertyTypeTokenRange;
+	}
+
+	/**
+	 * Returns true if this property should be documented as an event.
+	 *
+	 * @remarks
+	 * The `@eventProperty` TSDoc modifier can be added to readonly properties to indicate that they return an
+	 * event object that event handlers can be attached to.  The event-handling API is implementation-defined, but
+	 * typically the return type would be a class with members such as `addHandler()` and `removeHandler()`.
+	 * The documentation should display such properties under an "Events" heading instead of the
+	 * usual "Properties" heading.
+	 */
+	public get isEventProperty(): boolean {
+		if (this.tsdocComment) {
+			return this.tsdocComment.modifierTagSet.isEventProperty();
+		}
+
+		return false;
+	}
+
+	/**
+	 * @override
+	 */
+	public override serializeInto(jsonObject: Partial<IApiPropertyItemJson>): void {
+		super.serializeInto(jsonObject);
+
+		jsonObject.propertyTypeTokenRange = this.propertyTypeExcerpt.tokenRange;
+	}
+}

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

@@ -0,0 +1,115 @@
+// Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license.
+// See LICENSE in the project root for license information.
+
+import type { ApiItem, IApiItemJson, IApiItemConstructor, IApiItemOptions } from '../items/ApiItem.js';
+import type { DeserializerContext } from '../model/DeserializerContext.js';
+
+/**
+ * Constructor options for {@link (ApiAbstractMixin:interface)}.
+ *
+ * @public
+ */
+export interface IApiAbstractMixinOptions extends IApiItemOptions {
+	isAbstract: boolean;
+}
+
+export interface IApiAbstractMixinJson extends IApiItemJson {
+	isAbstract: boolean;
+}
+
+const _isAbstract: unique symbol = Symbol('ApiAbstractMixin._isAbstract');
+
+/**
+ * The mixin base class for API items that have an abstract modifier.
+ *
+ * @remarks
+ *
+ * This is part of the {@link ApiModel} hierarchy of classes, which are serializable representations of
+ * API declarations.  The non-abstract classes (e.g. `ApiClass`, `ApiEnum`, `ApiInterface`, etc.) use
+ * TypeScript "mixin" functions (e.g. `ApiDeclaredItem`, `ApiItemContainerMixin`, etc.) to add various
+ * features that cannot be represented as a normal inheritance chain (since TypeScript does not allow a child class
+ * to extend more than one base class).  The "mixin" is a TypeScript merged declaration with three components:
+ * the function that generates a subclass, an interface that describes the members of the subclass, and
+ * a namespace containing static members of the class.
+ * @public
+ */
+
+export interface ApiAbstractMixin extends ApiItem {
+	/**
+	 * Indicates that the API item's value has an 'abstract' modifier.
+	 */
+	readonly isAbstract: boolean;
+
+	serializeInto(jsonObject: Partial<IApiItemJson>): void;
+}
+
+/**
+ * Mixin function for {@link (ApiAbstractMixin:interface)}.
+ *
+ * @param baseClass - The base class to be extended
+ * @returns A child class that extends baseClass, adding the {@link (ApiAbstractMixin:interface)}
+ * functionality.
+ * @public
+ */
+export function ApiAbstractMixin<TBaseClass extends IApiItemConstructor>(
+	baseClass: TBaseClass,
+): TBaseClass & (new (...args: any[]) => ApiAbstractMixin) {
+	class MixedClass extends baseClass implements ApiAbstractMixin {
+		public [_isAbstract]: boolean;
+
+		public constructor(...args: any[]) {
+			super(...args);
+
+			const options: IApiAbstractMixinOptions = args[0];
+			this[_isAbstract] = options.isAbstract;
+		}
+
+		/**
+		 * @override
+		 */
+		public static override onDeserializeInto(
+			options: Partial<IApiAbstractMixinOptions>,
+			context: DeserializerContext,
+			jsonObject: IApiAbstractMixinJson,
+		): void {
+			baseClass.onDeserializeInto(options, context, jsonObject);
+
+			options.isAbstract = jsonObject.isAbstract || false;
+		}
+
+		public get isAbstract(): boolean {
+			return this[_isAbstract];
+		}
+
+		/**
+		 * @override
+		 */
+		public override serializeInto(jsonObject: Partial<IApiAbstractMixinJson>): void {
+			super.serializeInto(jsonObject);
+
+			jsonObject.isAbstract = this.isAbstract;
+		}
+	}
+
+	return MixedClass;
+}
+
+/**
+ * Static members for {@link (ApiAbstractMixin:interface)}.
+ *
+ * @public
+ */
+export namespace ApiAbstractMixin {
+	/**
+	 * A type guard that tests whether the specified `ApiItem` subclass extends the `ApiAbstractMixin` mixin.
+	 *
+	 * @remarks
+	 *
+	 * The JavaScript `instanceof` operator cannot be used to test for mixin inheritance, because each invocation of
+	 * the mixin function produces a different subclass.  (This could be mitigated by `Symbol.hasInstance`, however
+	 * the TypeScript type system cannot invoke a runtime test.)
+	 */
+	export function isBaseClassOf(apiItem: ApiItem): apiItem is ApiAbstractMixin {
+		return apiItem.hasOwnProperty(_isAbstract);
+	}
+}

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

@@ -0,0 +1,143 @@
+// Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license.
+// See LICENSE in the project root for license information.
+
+import { DeclarationReference } from '@microsoft/tsdoc/lib-commonjs/beta/DeclarationReference.js';
+import type { ApiItem, IApiItemJson, IApiItemConstructor, IApiItemOptions } from '../items/ApiItem.js';
+import { Navigation } from '../items/ApiItem.js';
+import type { DeserializerContext } from '../model/DeserializerContext.js';
+
+/**
+ * Constructor options for {@link (IApiExportedMixinOptions:interface)}.
+ *
+ * @public
+ */
+export interface IApiExportedMixinOptions extends IApiItemOptions {
+	isExported: boolean;
+}
+
+export interface IApiExportedMixinJson extends IApiItemJson {
+	isExported: boolean;
+}
+
+const _isExported: unique symbol = Symbol('ApiExportedMixin._isExported');
+
+/**
+ * The mixin base class for API items that can be exported.
+ *
+ * @remarks
+ *
+ * This is part of the {@link ApiModel} hierarchy of classes, which are serializable representations of
+ * API declarations.  The non-abstract classes (e.g. `ApiClass`, `ApiEnum`, `ApiInterface`, etc.) use
+ * TypeScript "mixin" functions (e.g. `ApiDeclaredItem`, `ApiItemContainerMixin`, etc.) to add various
+ * features that cannot be represented as a normal inheritance chain (since TypeScript does not allow a child class
+ * to extend more than one base class).  The "mixin" is a TypeScript merged declaration with three components:
+ * the function that generates a subclass, an interface that describes the members of the subclass, and
+ * a namespace containing static members of the class.
+ * @public
+ */
+
+export interface ApiExportedMixin extends ApiItem {
+	/**
+	 * Whether the declaration is exported from its parent item container (i.e. either an `ApiEntryPoint` or an
+	 * `ApiNamespace`).
+	 *
+	 * @remarks
+	 * Suppose `index.ts` is your entry point:
+	 *
+	 * ```ts
+	 * // index.ts
+	 *
+	 * export class A {}
+	 * class B {}
+	 *
+	 * namespace n {
+	 *   export class C {}
+	 *   class D {}
+	 * }
+	 *
+	 * // file.ts
+	 * export class E {}
+	 * ```
+	 *
+	 * Classes `A` and `C` are both exported, while classes `B`, `D`, and `E` are not. `E` is exported from its
+	 * local file, but not from its parent item container (i.e. the entry point).
+	 */
+	readonly isExported: boolean;
+
+	/**
+	 * @override
+	 */
+	serializeInto(jsonObject: Partial<IApiItemJson>): void;
+}
+
+/**
+ * Mixin function for {@link (ApiExportedMixin:interface)}.
+ *
+ * @param baseClass - The base class to be extended
+ * @returns A child class that extends baseClass, adding the {@link (ApiExportedMixin:interface)} functionality.
+ * @public
+ */
+export function ApiExportedMixin<TBaseClass extends IApiItemConstructor>(
+	baseClass: TBaseClass,
+): TBaseClass & (new (...args: any[]) => ApiExportedMixin) {
+	class MixedClass extends baseClass implements ApiExportedMixin {
+		public [_isExported]: boolean;
+
+		public constructor(...args: any[]) {
+			super(...args);
+
+			const options: IApiExportedMixinOptions = args[0];
+			this[_isExported] = options.isExported;
+		}
+
+		/**
+		 * @override
+		 */
+		public static override onDeserializeInto(
+			options: Partial<IApiExportedMixinOptions>,
+			context: DeserializerContext,
+			jsonObject: IApiExportedMixinJson,
+		): void {
+			baseClass.onDeserializeInto(options, context, jsonObject);
+
+			const declarationReference: DeclarationReference = DeclarationReference.parse(jsonObject.canonicalReference);
+			options.isExported = declarationReference.navigation === (Navigation.Exports as any); // ambient const enums suck...
+		}
+
+		public get isExported(): boolean {
+			return this[_isExported];
+		}
+
+		/**
+		 * The `isExported` property is intentionally not serialized because the information is already present
+		 * in the item's `canonicalReference`.
+		 *
+		 * @override
+		 */
+		public override serializeInto(jsonObject: Partial<IApiExportedMixinJson>): void {
+			super.serializeInto(jsonObject);
+		}
+	}
+
+	return MixedClass;
+}
+
+/**
+ * Static members for {@link (ApiExportedMixin:interface)}.
+ *
+ * @public
+ */
+export namespace ApiExportedMixin {
+	/**
+	 * A type guard that tests whether the specified `ApiItem` subclass extends the `ApiExportedMixin` mixin.
+	 *
+	 * @remarks
+	 *
+	 * The JavaScript `instanceof` operator cannot be used to test for mixin inheritance, because each invocation of
+	 * the mixin function produces a different subclass.  (This could be mitigated by `Symbol.hasInstance`, however
+	 * the TypeScript type system cannot invoke a runtime test.)
+	 */
+	export function isBaseClassOf(apiItem: ApiItem): apiItem is ApiExportedMixin {
+		return apiItem.hasOwnProperty(_isExported);
+	}
+}

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

@@ -0,0 +1,130 @@
+// Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license.
+// See LICENSE in the project root for license information.
+
+import { InternalError } from '@rushstack/node-core-library';
+import { ApiDeclaredItem } from '../items/ApiDeclaredItem.js';
+import type { ApiItem, IApiItemJson, IApiItemConstructor, IApiItemOptions } from '../items/ApiItem.js';
+import type { DeserializerContext } from '../model/DeserializerContext.js';
+import type { IExcerptTokenRange, Excerpt } from './Excerpt.js';
+
+/**
+ * Constructor options for {@link (IApiInitializerMixinOptions:interface)}.
+ *
+ * @public
+ */
+export interface IApiInitializerMixinOptions extends IApiItemOptions {
+	initializerTokenRange?: IExcerptTokenRange | undefined;
+}
+
+export interface IApiInitializerMixinJson extends IApiItemJson {
+	initializerTokenRange?: IExcerptTokenRange;
+}
+
+const _initializerExcerpt: unique symbol = Symbol('ApiInitializerMixin._initializerExcerpt');
+
+/**
+ * The mixin base class for API items that can have an initializer.
+ *
+ * @remarks
+ *
+ * This is part of the {@link ApiModel} hierarchy of classes, which are serializable representations of
+ * API declarations.  The non-abstract classes (e.g. `ApiClass`, `ApiEnum`, `ApiInterface`, etc.) use
+ * TypeScript "mixin" functions (e.g. `ApiDeclaredItem`, `ApiItemContainerMixin`, etc.) to add various
+ * features that cannot be represented as a normal inheritance chain (since TypeScript does not allow a child class
+ * to extend more than one base class).  The "mixin" is a TypeScript merged declaration with three components:
+ * the function that generates a subclass, an interface that describes the members of the subclass, and
+ * a namespace containing static members of the class.
+ * @public
+ */
+
+export interface ApiInitializerMixin extends ApiItem {
+	/**
+	 * An {@link Excerpt} that describes the item's initializer.
+	 */
+	readonly initializerExcerpt?: Excerpt | undefined;
+
+	/**
+	 * @override
+	 */
+	serializeInto(jsonObject: Partial<IApiInitializerMixinJson>): void;
+}
+
+/**
+ * Mixin function for {@link (ApiInitializerMixin:interface)}.
+ *
+ * @param baseClass - The base class to be extended
+ * @returns A child class that extends baseClass, adding the {@link (ApiInitializerMixin:interface)} functionality.
+ * @public
+ */
+export function ApiInitializerMixin<TBaseClass extends IApiItemConstructor>(
+	baseClass: TBaseClass,
+): TBaseClass & (new (...args: any[]) => ApiInitializerMixin) {
+	class MixedClass extends baseClass implements ApiInitializerMixin {
+		public [_initializerExcerpt]?: Excerpt;
+
+		public constructor(...args: any[]) {
+			super(...args);
+
+			const options: IApiInitializerMixinOptions = args[0];
+
+			if (this instanceof ApiDeclaredItem) {
+				if (options.initializerTokenRange) {
+					this[_initializerExcerpt] = this.buildExcerpt(options.initializerTokenRange);
+				}
+			} else {
+				throw new InternalError('ApiInitializerMixin expects a base class that inherits from ApiDeclaredItem');
+			}
+		}
+
+		/**
+		 * @override
+		 */
+		public static override onDeserializeInto(
+			options: Partial<IApiInitializerMixinOptions>,
+			context: DeserializerContext,
+			jsonObject: IApiInitializerMixinJson,
+		): void {
+			baseClass.onDeserializeInto(options, context, jsonObject);
+
+			options.initializerTokenRange = jsonObject.initializerTokenRange;
+		}
+
+		public get initializerExcerpt(): Excerpt | undefined {
+			return this[_initializerExcerpt];
+		}
+
+		/**
+		 * @override
+		 */
+		public override serializeInto(jsonObject: Partial<IApiInitializerMixinJson>): void {
+			super.serializeInto(jsonObject);
+
+			// Note that JSON does not support the "undefined" value, so we simply omit the field entirely if it is undefined
+			if (this.initializerExcerpt) {
+				jsonObject.initializerTokenRange = this.initializerExcerpt.tokenRange;
+			}
+		}
+	}
+
+	return MixedClass;
+}
+
+/**
+ * Static members for {@link (ApiInitializerMixin:interface)}.
+ *
+ * @public
+ */
+export namespace ApiInitializerMixin {
+	/**
+	 * A type guard that tests whether the specified `ApiItem` subclass extends the `ApiInitializerMixin` mixin.
+	 *
+	 * @remarks
+	 *
+	 * The JavaScript `instanceof` operator cannot be used to test for mixin inheritance, because each invocation of
+	 * the mixin function produces a different subclass.  (This could be mitigated by `Symbol.hasInstance`, however
+	 * the TypeScript type system cannot invoke a runtime test.)
+	 */
+	export function isBaseClassOf(apiItem: ApiItem): apiItem is ApiInitializerMixin {
+		return apiItem.hasOwnProperty(_initializerExcerpt);
+	}
+}

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

@@ -0,0 +1,639 @@
+/* eslint-disable @typescript-eslint/no-loop-func */
+// Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license.
+// See LICENSE in the project root for license information.
+
+import { TSDocConfiguration } from '@microsoft/tsdoc';
+import type { DeclarationReference } from '@microsoft/tsdoc/lib-commonjs/beta/DeclarationReference.js';
+import { InternalError } from '@rushstack/node-core-library';
+import type { IExcerptToken, IExcerptTokenRange } from '../index.js';
+import { ApiDeclaredItem } from '../index.js';
+import type { IApiDeclaredItemJson } from '../items/ApiDeclaredItem.js';
+import {
+	ApiItem,
+	apiItem_onParentChanged,
+	type IApiItemJson,
+	type IApiItemOptions,
+	type IApiItemConstructor,
+	ApiItemKind,
+} from '../items/ApiItem.js';
+import type { ApiClass } from '../model/ApiClass.js';
+import type { ApiInterface } from '../model/ApiInterface.js';
+import type { ApiModel } from '../model/ApiModel.js';
+import { ApiJsonSchemaVersion, type DeserializerContext } from '../model/DeserializerContext.js';
+import type { HeritageType } from '../model/HeritageType.js';
+import type { IResolveDeclarationReferenceResult } from '../model/ModelReferenceResolver.js';
+import { ApiNameMixin } from './ApiNameMixin.js';
+import type { ExcerptToken } from './Excerpt.js';
+import { ExcerptTokenKind } from './Excerpt.js';
+import { type IFindApiItemsResult, type IFindApiItemsMessage, FindApiItemsMessageId } from './IFindApiItemsResult.js';
+
+/**
+ * Constructor options for {@link (ApiItemContainerMixin:interface)}.
+ *
+ * @public
+ */
+export interface IApiItemContainerMixinOptions extends IApiItemOptions {
+	members?: ApiItem[] | undefined;
+	preserveMemberOrder?: boolean | undefined;
+}
+
+export interface IApiItemContainerJson extends IApiItemJson {
+	members: IApiItemJson[];
+	preserveMemberOrder?: boolean;
+}
+
+interface ExcerptTokenRangeInDeclaredItem {
+	item: ApiDeclaredItem;
+	range: IExcerptTokenRange;
+}
+interface IMappedTypeParameters {
+	item: ApiItem;
+	mappedTypeParameters: Map<string, ExcerptTokenRangeInDeclaredItem>;
+}
+
+const _members: unique symbol = Symbol('ApiItemContainerMixin._members');
+const _membersSorted: unique symbol = Symbol('ApiItemContainerMixin._membersSorted');
+const _membersByContainerKey: unique symbol = Symbol('ApiItemContainerMixin._membersByContainerKey');
+const _membersByName: unique symbol = Symbol('ApiItemContainerMixin._membersByName');
+const _membersByKind: unique symbol = Symbol('ApiItemContainerMixin._membersByKind');
+const _preserveMemberOrder: unique symbol = Symbol('ApiItemContainerMixin._preserveMemberOrder');
+
+/**
+ * The mixin base class for API items that act as containers for other child items.
+ *
+ * @remarks
+ *
+ * This is part of the {@link ApiModel} hierarchy of classes, which are serializable representations of
+ * API declarations.  The non-abstract classes (e.g. `ApiClass`, `ApiEnum`, `ApiInterface`, etc.) use
+ * TypeScript "mixin" functions (e.g. `ApiDeclaredItem`, `ApiItemContainerMixin`, etc.) to add various
+ * features that cannot be represented as a normal inheritance chain (since TypeScript does not allow a child class
+ * to extend more than one base class).  The "mixin" is a TypeScript merged declaration with three components:
+ * the function that generates a subclass, an interface that describes the members of the subclass, and
+ * a namespace containing static members of the class.
+ *
+ * Examples of `ApiItemContainerMixin` child classes include `ApiModel`, `ApiPackage`, `ApiEntryPoint`,
+ * and `ApiEnum`.  But note that `Parameter` is not considered a "member" of an `ApiMethod`; this relationship
+ * is modeled using {@link (ApiParameterListMixin:interface).parameters} instead
+ * of {@link ApiItem.members}.
+ * @public
+ */
+
+export interface ApiItemContainerMixin extends ApiItem {
+	/**
+	 * For a given member of this container, return its `ApiItem.getMergedSiblings()` list.
+	 *
+	 * @internal
+	 */
+	_getMergedSiblingsForMember(memberApiItem: ApiItem): readonly ApiItem[];
+
+	/**
+	 * Adds a new member to the container.
+	 *
+	 * @remarks
+	 * An ApiItem cannot be added to more than one container.
+	 */
+	addMember(member: ApiItem): void;
+
+	/**
+	 * Returns a list of members with the specified name.
+	 */
+	findMembersByName(name: string): readonly ApiItem[];
+
+	/**
+	 * Finds all of the ApiItem's immediate and inherited members by walking up the inheritance tree.
+	 *
+	 * @remarks
+	 *
+	 * Given the following class heritage:
+	 *
+	 * ```
+	 * export class A {
+	 *   public a: number|boolean;
+	 * }
+	 *
+	 * export class B extends A {
+	 *   public a: number;
+	 *   public b: string;
+	 * }
+	 *
+	 * export class C extends B {
+	 *   public c: boolean;
+	 * }
+	 * ```
+	 *
+	 * Calling `findMembersWithInheritance` on `C` will return `B.a`, `B.b`, and `C.c`. Calling the
+	 * method on `B` will return `B.a` and `B.b`. And calling the method on `A` will return just
+	 * `A.a`.
+	 *
+	 * The inherited members returned by this method may be incomplete. If so, there will be a flag
+	 * on the result object indicating this as well as messages explaining the errors in more detail.
+	 * Some scenarios include:
+	 *
+	 * - Interface extending from a type alias.
+	 *
+	 * - Class extending from a variable.
+	 *
+	 * - Extending from a declaration not present in the model (e.g. external package).
+	 *
+	 * - Extending from an unexported declaration (e.g. ae-forgotten-export). Common in mixin
+	 *   patterns.
+	 *
+	 * - Unexpected runtime errors...
+	 *
+	 * Lastly, be aware that the types of inherited members are returned with respect to their
+	 * defining class as opposed to with respect to the inheriting class. For example, consider
+	 * the following:
+	 *
+	 * ```
+	 * export class A<T> {
+	 *   public a: T;
+	 * }
+	 *
+	 * export class B extends A<number> {}
+	 * ```
+	 *
+	 * When called on `B`, this method will return `B.a` with type `T` as opposed to type
+	 * `number`, although the latter is more accurate.
+	 */
+	findMembersWithInheritance(): IFindApiItemsResult;
+
+	/**
+	 * Disables automatic sorting of {@link ApiItem.members}.
+	 *
+	 * @remarks
+	 * By default `ApiItemContainerMixin` will automatically sort its members according to their
+	 * {@link ApiItem.getSortKey} string, which provides a standardized mostly alphabetical ordering
+	 * that is appropriate for most API items.  When loading older .api.json files the automatic sorting
+	 * is reapplied and may update the ordering.
+	 *
+	 * Set `preserveMemberOrder` to true to disable automatic sorting for this container; instead, the
+	 * members will retain whatever ordering appeared in the {@link IApiItemContainerMixinOptions.members} array.
+	 * The `preserveMemberOrder` option is saved in the .api.json file.
+	 */
+	readonly preserveMemberOrder: boolean;
+
+	/**
+	 * @override
+	 */
+	serializeInto(jsonObject: Partial<IApiItemJson>): void;
+
+	/**
+	 * Attempts to retrieve a member using its containerKey, or returns `undefined` if no matching member was found.
+	 *
+	 * @remarks
+	 * Use the `getContainerKey()` static member to construct the key.  Each subclass has a different implementation
+	 * of this function, according to the aspects that are important for identifying it.
+	 *
+	 * See {@link ApiItem.containerKey} for more information.
+	 */
+	tryGetMemberByKey(containerKey: string): ApiItem | undefined;
+}
+
+/**
+ * Mixin function for {@link ApiDeclaredItem}.
+ *
+ * @param baseClass - The base class to be extended
+ * @returns A child class that extends baseClass, adding the {@link (ApiItemContainerMixin:interface)} functionality.
+ * @public
+ */
+export function ApiItemContainerMixin<TBaseClass extends IApiItemConstructor>(
+	baseClass: TBaseClass,
+): TBaseClass & (new (...args: any[]) => ApiItemContainerMixin) {
+	class MixedClass extends baseClass implements ApiItemContainerMixin {
+		public readonly [_members]: ApiItem[];
+
+		public [_membersSorted]: boolean;
+
+		public [_membersByContainerKey]: Map<string, ApiItem>;
+
+		public [_preserveMemberOrder]: boolean;
+
+		// For members of this container that extend ApiNameMixin, this stores the list of members with a given name.
+		// Examples include merged declarations, overloaded functions, etc.
+		public [_membersByName]: Map<string, ApiItem[]> | undefined;
+
+		// For members of this container that do NOT extend ApiNameMixin, this stores the list of members
+		// that share a common ApiItemKind.  Examples include overloaded constructors or index signatures.
+		public [_membersByKind]: Map<string, ApiItem[]> | undefined; // key is ApiItemKind
+
+		public constructor(...args: any[]) {
+			super(...args);
+			const options: IApiItemContainerMixinOptions = args[0] as IApiItemContainerMixinOptions;
+
+			this[_members] = [];
+			this[_membersSorted] = false;
+			this[_membersByContainerKey] = new Map<string, ApiItem>();
+			this[_preserveMemberOrder] = options.preserveMemberOrder ?? false;
+
+			if (options.members) {
+				for (const member of options.members) {
+					this.addMember(member);
+				}
+			}
+		}
+
+		/**
+		 * @override
+		 */
+		public static override onDeserializeInto(
+			options: Partial<IApiItemContainerMixinOptions>,
+			context: DeserializerContext,
+			jsonObject: IApiItemContainerJson,
+		): void {
+			baseClass.onDeserializeInto(options, context, jsonObject);
+			options.preserveMemberOrder = jsonObject.preserveMemberOrder;
+			options.members = [];
+			for (const memberObject of jsonObject.members) {
+				options.members.push(ApiItem.deserialize(memberObject, context));
+			}
+		}
+
+		/**
+		 * @override
+		 */
+		public override get members(): readonly ApiItem[] {
+			if (!this[_membersSorted] && !this[_preserveMemberOrder]) {
+				this[_members].sort((x, y) => x.getSortKey().localeCompare(y.getSortKey()));
+				this[_membersSorted] = true;
+			}
+
+			return this[_members];
+		}
+
+		public get preserveMemberOrder(): boolean {
+			return this[_preserveMemberOrder];
+		}
+
+		public addMember(member: ApiItem): void {
+			if (this[_membersByContainerKey].has(member.containerKey)) {
+				throw new Error(
+					`Another member has already been added with the same name (${member.displayName})` +
+						` and containerKey (${member.containerKey})`,
+				);
+			}
+
+			const existingParent: ApiItem | undefined = member.parent;
+			if (existingParent !== undefined) {
+				throw new Error(`This item has already been added to another container: "${existingParent.displayName}"`);
+			}
+
+			this[_members].push(member);
+			this[_membersByName] = undefined; // invalidate the lookup
+			this[_membersByKind] = undefined; // invalidate the lookup
+			this[_membersSorted] = false;
+			this[_membersByContainerKey].set(member.containerKey, member);
+
+			member[apiItem_onParentChanged](this);
+		}
+
+		public tryGetMemberByKey(containerKey: string): ApiItem | undefined {
+			return this[_membersByContainerKey].get(containerKey);
+		}
+
+		public findMembersByName(name: string): readonly ApiItem[] {
+			this._ensureMemberMaps();
+			return this[_membersByName]!.get(name) ?? [];
+		}
+
+		public findMembersWithInheritance(): IFindApiItemsResult {
+			const messages: IFindApiItemsMessage[] = [];
+			let maybeIncompleteResult = false;
+
+			// For API items that don't support inheritance, this method just returns the item's
+			// immediate members.
+			switch (this.kind) {
+				case ApiItemKind.Class:
+				case ApiItemKind.Interface:
+					break;
+				default: {
+					return {
+						items: this.members.concat(),
+						messages,
+						maybeIncompleteResult,
+					};
+				}
+			}
+
+			// The Deserializer class is coupled with a ton of other classes, so  we delay loading it
+			// to avoid ES5 circular imports.
+			// *eslint-disable-next-line @typescript-eslint/consistent-type-imports, @typescript-eslint/no-require-imports, @typescript-eslint/no-var-requires
+			// const deserializerModule: typeof import('../model/Deserializer') = require('../model/Deserializer');
+
+			const membersByName: Map<string, ApiItem[]> = new Map();
+			const membersByKind: Map<ApiItemKind, ApiItem[]> = new Map();
+
+			const toVisit: IMappedTypeParameters[] = [];
+			let next: IMappedTypeParameters | undefined = { item: this, mappedTypeParameters: new Map() };
+
+			while (next?.item) {
+				const membersToAdd: ApiItem[] = []; //*
+				const typeParams = next.mappedTypeParameters;
+				const context: DeserializerContext = {
+					apiJsonFilename: '',
+					toolPackage: '',
+					toolVersion: '',
+					versionToDeserialize: ApiJsonSchemaVersion.LATEST,
+					tsdocConfiguration: new TSDocConfiguration(),
+				}; // */
+
+				// eslint-disable-next-line @typescript-eslint/consistent-type-imports, @typescript-eslint/no-require-imports, @typescript-eslint/no-var-requires
+				const deserializerModule: typeof import('../model/Deserializer') = require('../model/Deserializer');
+
+				// For each member, check to see if we've already seen a member with the same name
+				// previously in the inheritance tree. If so, we know we won't inherit it, and thus
+				// do not add it to our `membersToAdd` array.
+				for (let member of next.item.members) {
+					// We add the to-be-added members to an intermediate array instead of immediately
+					// to the maps themselves to support method overloads with the same name.
+
+					// This was supposed to replace type parameters with their assigned values in inheritance, but doesn't work yet
+					//*
+					if (member instanceof ApiDeclaredItem && member.excerptTokens.some((token) => typeParams.has(token.text))) {
+						const jsonObject: Partial<IApiItemJson> = {};
+						member.serializeInto(jsonObject);
+						const excerptTokens = (jsonObject as IApiDeclaredItemJson).excerptTokens.map((token) => {
+							let x: ExcerptToken | undefined;
+							if (typeParams.has(token.text) && next?.item instanceof ApiDeclaredItem) {
+								const originalValue = typeParams.get(token.text)!;
+								x = originalValue.item.excerptTokens[originalValue.range.startIndex];
+							}
+
+							const excerptToken: IExcerptToken = x ? { kind: x.kind, text: x.text } : token;
+							if (x?.canonicalReference !== undefined) {
+								excerptToken.canonicalReference = x.canonicalReference.toString();
+							}
+
+							return excerptToken;
+						});
+						member = deserializerModule.Deserializer.deserialize(context, {
+							...jsonObject,
+							excerptTokens,
+						} as IApiDeclaredItemJson);
+						member[apiItem_onParentChanged](next.item);
+					}
+
+					if (ApiNameMixin.isBaseClassOf(member)) {
+						if (!membersByName.has(member.name)) {
+							membersToAdd.push(member);
+						}
+					} else if (!membersByKind.has(member.kind)) {
+						membersToAdd.push(member);
+					}
+				}
+
+				for (const member of membersToAdd) {
+					if (ApiNameMixin.isBaseClassOf(member)) {
+						const members: ApiItem[] = membersByName.get(member.name) ?? [];
+						members.push(member);
+						membersByName.set(member.name, members);
+					} else {
+						const members: ApiItem[] = membersByKind.get(member.kind) ?? [];
+						members.push(member);
+						membersByKind.set(member.kind, members);
+					}
+				}
+
+				// Interfaces can extend multiple interfaces, so iterate through all of them.
+				const extendedItems: IMappedTypeParameters[] = [];
+				let extendsTypes: readonly HeritageType[] | undefined;
+
+				switch (next.item.kind) {
+					case ApiItemKind.Class: {
+						const apiClass: ApiClass = next.item as ApiClass;
+						extendsTypes = apiClass.extendsType ? [apiClass.extendsType] : [];
+						break;
+					}
+
+					case ApiItemKind.Interface: {
+						const apiInterface: ApiInterface = next.item as ApiInterface;
+						extendsTypes = apiInterface.extendsTypes;
+						break;
+					}
+
+					default:
+						break;
+				}
+
+				if (extendsTypes === undefined) {
+					messages.push({
+						messageId: FindApiItemsMessageId.UnsupportedKind,
+						text: `Unable to analyze references of API item ${next.item.displayName} because it is of unsupported kind ${next.item.kind}`,
+					});
+					maybeIncompleteResult = true;
+					next = toVisit.shift();
+					continue;
+				}
+
+				for (const extendsType of extendsTypes) {
+					// We want to find the reference token associated with the actual inherited declaration.
+					// In every case we support, this is the first reference token. For example:
+					//
+					// ```
+					// export class A extends B {}
+					//                        ^
+					// export class A extends B<C> {}
+					//                        ^
+					// export class A extends B.C {}
+					//                        ^^^
+					// ```
+					const firstReferenceToken: ExcerptToken | undefined = extendsType.excerpt.spannedTokens.find(
+						(token: ExcerptToken) => {
+							return token.kind === ExcerptTokenKind.Reference && token.canonicalReference;
+						},
+					);
+
+					if (!firstReferenceToken) {
+						messages.push({
+							messageId: FindApiItemsMessageId.ExtendsClauseMissingReference,
+							text: `Unable to analyze extends clause ${extendsType.excerpt.text} of API item ${next.item.displayName} because no canonical reference was found`,
+						});
+						maybeIncompleteResult = true;
+						continue;
+					}
+
+					const apiModel: ApiModel | undefined = this.getAssociatedModel();
+					if (!apiModel) {
+						messages.push({
+							messageId: FindApiItemsMessageId.NoAssociatedApiModel,
+							text: `Unable to analyze references of API item ${next.item.displayName} because it is not associated with an ApiModel`,
+						});
+						maybeIncompleteResult = true;
+						continue;
+					}
+
+					const canonicalReference: DeclarationReference = firstReferenceToken.canonicalReference!;
+					const apiItemResult: IResolveDeclarationReferenceResult = apiModel.resolveDeclarationReference(
+						canonicalReference,
+						undefined,
+					);
+
+					const apiItem: ApiItem | undefined = apiItemResult.resolvedApiItem;
+					if (!apiItem) {
+						messages.push({
+							messageId: FindApiItemsMessageId.DeclarationResolutionFailed,
+							text: `Unable to resolve declaration reference within API item ${next.item.displayName}: ${apiItemResult.errorMessage}`,
+						});
+						maybeIncompleteResult = true;
+						continue;
+					}
+
+					const mappedTypeParameters: Map<string, ExcerptTokenRangeInDeclaredItem> = new Map();
+					if (
+						(apiItem.kind === ApiItemKind.Class || apiItem.kind === ApiItemKind.Interface) &&
+						next.item.kind === ApiItemKind.Class
+					) {
+						for (const [index, key] of (apiItem as ApiClass | ApiInterface).typeParameters.entries() ?? []) {
+							const typeParameter = extendsType.typeParameters?.[index];
+							if (typeParameter)
+								mappedTypeParameters.set(key.name, { item: next.item as ApiDeclaredItem, range: typeParameter });
+							else if (key.defaultTypeExcerpt)
+								mappedTypeParameters.set(key.name, {
+									item: apiItem as ApiDeclaredItem,
+									range: key.defaultTypeExcerpt.tokenRange,
+								});
+						}
+					}
+
+					extendedItems.push({ item: apiItem, mappedTypeParameters });
+				}
+
+				// For classes, this array will only have one item. For interfaces, there may be multiple items. Sort the array
+				// into alphabetical order before adding to our list of API items to visit. This ensures that in the case
+				// of multiple interface inheritance, a member inherited from multiple interfaces is attributed to the interface
+				// earlier in alphabetical order (as opposed to source order).
+				//
+				// For example, in the code block below, `Bar.x` is reported as the inherited item, not `Foo.x`.
+				//
+				// ```
+				// interface Foo {
+				//   public x: string;
+				// }
+				//
+				// interface Bar {
+				//   public x: string;
+				// }
+				//
+				// interface FooBar extends Foo, Bar {}
+				// ```
+				extendedItems.sort((x: IMappedTypeParameters, y: IMappedTypeParameters) =>
+					x.item.getSortKey().localeCompare(y.item.getSortKey()),
+				);
+
+				toVisit.push(...extendedItems);
+				next = toVisit.shift();
+			}
+
+			const items: ApiItem[] = [];
+			for (const members of membersByName.values()) {
+				items.push(...members);
+			}
+
+			for (const members of membersByKind.values()) {
+				items.push(...members);
+			}
+
+			items.sort((x: ApiItem, y: ApiItem) => x.getSortKey().localeCompare(y.getSortKey()));
+
+			return {
+				items,
+				messages,
+				maybeIncompleteResult,
+			};
+		}
+
+		/**
+		 * @internal
+		 */
+		public _getMergedSiblingsForMember(memberApiItem: ApiItem): readonly ApiItem[] {
+			this._ensureMemberMaps();
+			let result: ApiItem[] | undefined;
+			if (ApiNameMixin.isBaseClassOf(memberApiItem)) {
+				result = this[_membersByName]!.get(memberApiItem.name);
+			} else {
+				result = this[_membersByKind]!.get(memberApiItem.kind);
+			}
+
+			if (!result) {
+				throw new InternalError('Item was not found in the _membersByName/_membersByKind lookup');
+			}
+
+			return result;
+		}
+
+		/**
+		 * @internal
+		 */
+		public _ensureMemberMaps(): void {
+			// Build the _membersByName and _membersByKind tables if they don't already exist
+			if (this[_membersByName] === undefined) {
+				const membersByName: Map<string, ApiItem[]> = new Map<string, ApiItem[]>();
+				const membersByKind: Map<string, ApiItem[]> = new Map<string, ApiItem[]>();
+
+				for (const member of this[_members]) {
+					let map: Map<ApiItemKind, ApiItem[]> | Map<string, ApiItem[]>;
+					let key: ApiItemKind | string;
+
+					if (ApiNameMixin.isBaseClassOf(member)) {
+						map = membersByName;
+						key = member.name;
+					} else {
+						map = membersByKind;
+						key = member.kind;
+					}
+
+					let list: ApiItem[] | undefined = map.get(key);
+					if (list === undefined) {
+						list = [];
+						map.set(key, list);
+					}
+
+					list.push(member);
+				}
+
+				this[_membersByName] = membersByName;
+				this[_membersByKind] = membersByKind;
+			}
+		}
+
+		/**
+		 * @override
+		 */
+		public override serializeInto(jsonObject: Partial<IApiItemContainerJson>): void {
+			super.serializeInto(jsonObject);
+
+			const memberObjects: IApiItemJson[] = [];
+
+			for (const member of this.members) {
+				const memberJsonObject: Partial<IApiItemJson> = {};
+				member.serializeInto(memberJsonObject);
+				memberObjects.push(memberJsonObject as IApiItemJson);
+			}
+
+			jsonObject.preserveMemberOrder = this.preserveMemberOrder;
+			jsonObject.members = memberObjects;
+		}
+	}
+
+	return MixedClass;
+}
+
+/**
+ * Static members for {@link (ApiItemContainerMixin:interface)}.
+ *
+ * @public
+ */
+
+export namespace ApiItemContainerMixin {
+	/**
+	 * A type guard that tests whether the specified `ApiItem` subclass extends the `ApiItemContainerMixin` mixin.
+	 *
+	 * @remarks
+	 *
+	 * The JavaScript `instanceof` operator cannot be used to test for mixin inheritance, because each invocation of
+	 * the mixin function produces a different subclass.  (This could be mitigated by `Symbol.hasInstance`, however
+	 * the TypeScript type system cannot invoke a runtime test.)
+	 */
+	export function isBaseClassOf(apiItem: ApiItem): apiItem is ApiItemContainerMixin {
+		return apiItem.hasOwnProperty(_members);
+	}
+}

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

@@ -0,0 +1,128 @@
+// Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license.
+// See LICENSE in the project root for license information.
+
+import type { ApiItem, IApiItemJson, IApiItemConstructor, IApiItemOptions } from '../items/ApiItem.js';
+import type { DeserializerContext } from '../model/DeserializerContext.js';
+
+/**
+ * Constructor options for {@link (IApiNameMixinOptions:interface)}.
+ *
+ * @public
+ */
+export interface IApiNameMixinOptions extends IApiItemOptions {
+	name: string;
+}
+
+export interface IApiNameMixinJson extends IApiItemJson {
+	name: string;
+}
+
+const _name: unique symbol = Symbol('ApiNameMixin._name');
+
+/**
+ * The mixin base class for API items that have a name.  For example, a class has a name, but a class constructor
+ * does not.
+ *
+ * @remarks
+ *
+ * This is part of the {@link ApiModel} hierarchy of classes, which are serializable representations of
+ * API declarations.  The non-abstract classes (e.g. `ApiClass`, `ApiEnum`, `ApiInterface`, etc.) use
+ * TypeScript "mixin" functions (e.g. `ApiDeclaredItem`, `ApiItemContainerMixin`, etc.) to add various
+ * features that cannot be represented as a normal inheritance chain (since TypeScript does not allow a child class
+ * to extend more than one base class).  The "mixin" is a TypeScript merged declaration with three components:
+ * the function that generates a subclass, an interface that describes the members of the subclass, and
+ * a namespace containing static members of the class.
+ * @public
+ */
+
+export interface ApiNameMixin extends ApiItem {
+	/**
+	 * The exported name of this API item.
+	 *
+	 * @remarks
+	 * Note that due tue type aliasing, the exported name may be different from the locally declared name.
+	 */
+	readonly name: string;
+
+	/**
+	 * @override
+	 */
+	serializeInto(jsonObject: Partial<IApiItemJson>): void;
+}
+
+/**
+ * Mixin function for {@link (ApiNameMixin:interface)}.
+ *
+ * @param baseClass - The base class to be extended
+ * @returns A child class that extends baseClass, adding the {@link (ApiNameMixin:interface)} functionality.
+ * @public
+ */
+export function ApiNameMixin<TBaseClass extends IApiItemConstructor>(
+	baseClass: TBaseClass,
+): TBaseClass & (new (...args: any[]) => ApiNameMixin) {
+	class MixedClass extends baseClass implements ApiNameMixin {
+		public readonly [_name]: string;
+
+		public constructor(...args: any[]) {
+			super(...args);
+
+			const options: IApiNameMixinOptions = args[0];
+			this[_name] = options.name;
+		}
+
+		/**
+		 * @override
+		 */
+		public static override onDeserializeInto(
+			options: Partial<IApiNameMixinOptions>,
+			context: DeserializerContext,
+			jsonObject: IApiNameMixinJson,
+		): void {
+			baseClass.onDeserializeInto(options, context, jsonObject);
+
+			options.name = jsonObject.name;
+		}
+
+		public get name(): string {
+			return this[_name];
+		}
+
+		/**
+		 * @override
+		 */
+		public override get displayName(): string {
+			return this[_name];
+		}
+
+		/**
+		 * @override
+		 */
+		public override serializeInto(jsonObject: Partial<IApiNameMixinJson>): void {
+			super.serializeInto(jsonObject);
+
+			jsonObject.name = this.name;
+		}
+	}
+
+	return MixedClass;
+}
+
+/**
+ * Static members for {@link (ApiNameMixin:interface)}.
+ *
+ * @public
+ */
+export namespace ApiNameMixin {
+	/**
+	 * A type guard that tests whether the specified `ApiItem` subclass extends the `ApiNameMixin` mixin.
+	 *
+	 * @remarks
+	 *
+	 * The JavaScript `instanceof` operator cannot be used to test for mixin inheritance, because each invocation of
+	 * the mixin function produces a different subclass.  (This could be mitigated by `Symbol.hasInstance`, however
+	 * the TypeScript type system cannot invoke a runtime test.)
+	 */
+	export function isBaseClassOf(apiItem: ApiItem): apiItem is ApiNameMixin {
+		return apiItem.hasOwnProperty(_name);
+	}
+}

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

@@ -0,0 +1,127 @@
+// Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license.
+// See LICENSE in the project root for license information.
+
+import type { ApiItem, IApiItemJson, IApiItemConstructor, IApiItemOptions } from '../items/ApiItem.js';
+import type { DeserializerContext } from '../model/DeserializerContext.js';
+
+/**
+ * Constructor options for {@link (IApiOptionalMixinOptions:interface)}.
+ *
+ * @public
+ */
+export interface IApiOptionalMixinOptions extends IApiItemOptions {
+	isOptional: boolean;
+}
+
+export interface IApiOptionalMixinJson extends IApiItemJson {
+	isOptional: boolean;
+}
+
+const _isOptional: unique symbol = Symbol('ApiOptionalMixin._isOptional');
+
+/**
+ * The mixin base class for API items that can be marked as optional by appending a `?` to them.
+ * For example, a property of an interface can be optional.
+ *
+ * @remarks
+ *
+ * This is part of the {@link ApiModel} hierarchy of classes, which are serializable representations of
+ * API declarations.  The non-abstract classes (e.g. `ApiClass`, `ApiEnum`, `ApiInterface`, etc.) use
+ * TypeScript "mixin" functions (e.g. `ApiDeclaredItem`, `ApiItemContainerMixin`, etc.) to add various
+ * features that cannot be represented as a normal inheritance chain (since TypeScript does not allow a child class
+ * to extend more than one base class).  The "mixin" is a TypeScript merged declaration with three components:
+ * the function that generates a subclass, an interface that describes the members of the subclass, and
+ * a namespace containing static members of the class.
+ * @public
+ */
+
+export interface ApiOptionalMixin extends ApiItem {
+	/**
+	 * True if this is an optional property.
+	 *
+	 * @remarks
+	 * For example:
+	 * ```ts
+	 * interface X {
+	 *   y: string;   // not optional
+	 *   z?: string;  // optional
+	 * }
+	 * ```
+	 */
+	readonly isOptional: boolean;
+
+	/**
+	 * @override
+	 */
+	serializeInto(jsonObject: Partial<IApiItemJson>): void;
+}
+
+/**
+ * Mixin function for {@link (ApiOptionalMixin:interface)}.
+ *
+ * @param baseClass - The base class to be extended
+ * @returns A child class that extends baseClass, adding the {@link (ApiOptionalMixin:interface)} functionality.
+ * @public
+ */
+export function ApiOptionalMixin<TBaseClass extends IApiItemConstructor>(
+	baseClass: TBaseClass,
+): TBaseClass & (new (...args: any[]) => ApiOptionalMixin) {
+	class MixedClass extends baseClass implements ApiOptionalMixin {
+		public [_isOptional]: boolean;
+
+		public constructor(...args: any[]) {
+			super(...args);
+
+			const options: IApiOptionalMixinOptions = args[0];
+			this[_isOptional] = Boolean(options.isOptional);
+		}
+
+		/**
+		 * @override
+		 */
+		public static override onDeserializeInto(
+			options: Partial<IApiOptionalMixinOptions>,
+			context: DeserializerContext,
+			jsonObject: IApiOptionalMixinJson,
+		): void {
+			baseClass.onDeserializeInto(options, context, jsonObject);
+
+			options.isOptional = Boolean(jsonObject.isOptional);
+		}
+
+		public get isOptional(): boolean {
+			return this[_isOptional];
+		}
+
+		/**
+		 * @override
+		 */
+		public override serializeInto(jsonObject: Partial<IApiOptionalMixinJson>): void {
+			super.serializeInto(jsonObject);
+
+			jsonObject.isOptional = this.isOptional;
+		}
+	}
+
+	return MixedClass;
+}
+
+/**
+ * Optional members for {@link (ApiOptionalMixin:interface)}.
+ *
+ * @public
+ */
+export namespace ApiOptionalMixin {
+	/**
+	 * A type guard that tests whether the specified `ApiItem` subclass extends the `ApiOptionalMixin` mixin.
+	 *
+	 * @remarks
+	 *
+	 * The JavaScript `instanceof` operator cannot be used to test for mixin inheritance, because each invocation of
+	 * the mixin function produces a different subclass.  (This could be mitigated by `Symbol.hasInstance`, however
+	 * the TypeScript type system cannot invoke a runtime test.)
+	 */
+	export function isBaseClassOf(apiItem: ApiItem): apiItem is ApiOptionalMixin {
+		return apiItem.hasOwnProperty(_isOptional);
+	}
+}

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

@@ -0,0 +1,205 @@
+// Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license.
+// See LICENSE in the project root for license information.
+
+import { InternalError } from '@rushstack/node-core-library';
+import { ApiDeclaredItem } from '../items/ApiDeclaredItem.js';
+import type { ApiItem, IApiItemJson, IApiItemConstructor, IApiItemOptions } from '../items/ApiItem.js';
+import type { DeserializerContext } from '../model/DeserializerContext.js';
+import { Parameter } from '../model/Parameter.js';
+import type { IExcerptTokenRange } from './Excerpt.js';
+
+/**
+ * Represents parameter information that is part of {@link IApiParameterListMixinOptions}
+ *
+ * @public
+ */
+export interface IApiParameterOptions {
+	defaultValue: string | undefined;
+	isOptional: boolean;
+	isRest: boolean;
+	parameterName: string;
+	parameterTypeTokenRange: IExcerptTokenRange;
+}
+
+/**
+ * Constructor options for {@link (ApiParameterListMixin:interface)}.
+ *
+ * @public
+ */
+export interface IApiParameterListMixinOptions extends IApiItemOptions {
+	overloadIndex: number;
+	parameters: IApiParameterOptions[];
+}
+
+export interface IApiParameterListJson extends IApiItemJson {
+	overloadIndex: number;
+	parameters: IApiParameterOptions[];
+}
+
+const _overloadIndex: unique symbol = Symbol('ApiParameterListMixin._overloadIndex');
+const _parameters: unique symbol = Symbol('ApiParameterListMixin._parameters');
+
+/**
+ * The mixin base class for API items that can have function parameters (but not necessarily a return value).
+ *
+ * @remarks
+ *
+ * This is part of the {@link ApiModel} hierarchy of classes, which are serializable representations of
+ * API declarations.  The non-abstract classes (e.g. `ApiClass`, `ApiEnum`, `ApiInterface`, etc.) use
+ * TypeScript "mixin" functions (e.g. `ApiDeclaredItem`, `ApiItemContainerMixin`, etc.) to add various
+ * features that cannot be represented as a normal inheritance chain (since TypeScript does not allow a child class
+ * to extend more than one base class).  The "mixin" is a TypeScript merged declaration with three components:
+ * the function that generates a subclass, an interface that describes the members of the subclass, and
+ * a namespace containing static members of the class.
+ * @public
+ */
+
+export interface ApiParameterListMixin extends ApiItem {
+	/**
+	 * When a function has multiple overloaded declarations, this one-based integer index can be used to uniquely
+	 * identify them.
+	 *
+	 * @remarks
+	 *
+	 * Consider this overloaded declaration:
+	 *
+	 * ```ts
+	 * export namespace Versioning {
+	 *   // TSDoc: Versioning.(addVersions:1)
+	 *   export function addVersions(x: number, y: number): number;
+	 *
+	 *   // TSDoc: Versioning.(addVersions:2)
+	 *   export function addVersions(x: string, y: string): string;
+	 *
+	 *   // (implementation)
+	 *   export function addVersions(x: number|string, y: number|string): number|string {
+	 *     // . . .
+	 *   }
+	 * }
+	 * ```
+	 *
+	 * In the above example, there are two overloaded declarations.  The overload using numbers will have
+	 * `overloadIndex = 1`.  The overload using strings will have `overloadIndex = 2`.  The third declaration that
+	 * accepts all possible inputs is considered part of the implementation, and is not processed by API Extractor.
+	 */
+	readonly overloadIndex: number;
+
+	/**
+	 * The function parameters.
+	 */
+	readonly parameters: readonly Parameter[];
+
+	serializeInto(jsonObject: Partial<IApiItemJson>): void;
+}
+
+/**
+ * Mixin function for {@link (ApiParameterListMixin:interface)}.
+ *
+ * @param baseClass - The base class to be extended
+ * @returns A child class that extends baseClass, adding the {@link (ApiParameterListMixin:interface)} functionality.
+ * @public
+ */
+export function ApiParameterListMixin<TBaseClass extends IApiItemConstructor>(
+	baseClass: TBaseClass,
+): TBaseClass & (new (...args: any[]) => ApiParameterListMixin) {
+	class MixedClass extends baseClass implements ApiParameterListMixin {
+		public readonly [_overloadIndex]: number;
+
+		public readonly [_parameters]: Parameter[];
+
+		public constructor(...args: any[]) {
+			super(...args);
+
+			const options: IApiParameterListMixinOptions = args[0];
+			this[_overloadIndex] = options.overloadIndex;
+
+			this[_parameters] = [];
+
+			if (this instanceof ApiDeclaredItem) {
+				if (options.parameters) {
+					for (const parameterOptions of options.parameters) {
+						const parameter: Parameter = new Parameter({
+							name: parameterOptions.parameterName,
+							parameterTypeExcerpt: this.buildExcerpt(parameterOptions.parameterTypeTokenRange),
+							// Prior to ApiJsonSchemaVersion.V_1005 this input will be undefined
+							isOptional: Boolean(parameterOptions.isOptional),
+							isRest: Boolean(parameterOptions.isRest),
+							parent: this,
+							defaultValue: parameterOptions.defaultValue,
+						});
+
+						this[_parameters].push(parameter);
+					}
+				}
+			} else {
+				throw new InternalError('ApiReturnTypeMixin expects a base class that inherits from ApiDeclaredItem');
+			}
+		}
+
+		/**
+		 * @override
+		 */
+		public static override onDeserializeInto(
+			options: Partial<IApiParameterListMixinOptions>,
+			context: DeserializerContext,
+			jsonObject: IApiParameterListJson,
+		): void {
+			baseClass.onDeserializeInto(options, context, jsonObject);
+
+			options.overloadIndex = jsonObject.overloadIndex;
+			options.parameters = jsonObject.parameters || [];
+		}
+
+		public get overloadIndex(): number {
+			return this[_overloadIndex];
+		}
+
+		public get parameters(): readonly Parameter[] {
+			return this[_parameters];
+		}
+
+		/**
+		 * @override
+		 */
+		public override serializeInto(jsonObject: Partial<IApiParameterListJson>): void {
+			super.serializeInto(jsonObject);
+
+			jsonObject.overloadIndex = this.overloadIndex;
+
+			const parameterObjects: IApiParameterOptions[] = [];
+			for (const parameter of this.parameters) {
+				parameterObjects.push({
+					parameterName: parameter.name,
+					parameterTypeTokenRange: parameter.parameterTypeExcerpt.tokenRange,
+					isOptional: parameter.isOptional,
+					isRest: parameter.isRest,
+					defaultValue: parameter.defaultValue,
+				});
+			}
+
+			jsonObject.parameters = parameterObjects;
+		}
+	}
+
+	return MixedClass;
+}
+
+/**
+ * Static members for {@link (ApiParameterListMixin:interface)}.
+ *
+ * @public
+ */
+export namespace ApiParameterListMixin {
+	/**
+	 * A type guard that tests whether the specified `ApiItem` subclass extends the `ApiParameterListMixin` mixin.
+	 *
+	 * @remarks
+	 *
+	 * The JavaScript `instanceof` operator cannot be used to test for mixin inheritance, because each invocation of
+	 * the mixin function produces a different subclass.  (This could be mitigated by `Symbol.hasInstance`, however
+	 * the TypeScript type system cannot invoke a runtime test.)
+	 */
+	export function isBaseClassOf(apiItem: ApiItem): apiItem is ApiParameterListMixin {
+		return apiItem.hasOwnProperty(_parameters);
+	}
+}

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

@@ -0,0 +1,117 @@
+// Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license.
+// See LICENSE in the project root for license information.
+
+import type { ApiItem, IApiItemJson, IApiItemConstructor, IApiItemOptions } from '../items/ApiItem.js';
+import type { DeserializerContext } from '../model/DeserializerContext.js';
+
+/**
+ * Constructor options for {@link (IApiProtectedMixinOptions:interface)}.
+ *
+ * @public
+ */
+export interface IApiProtectedMixinOptions extends IApiItemOptions {
+	isProtected: boolean;
+}
+
+export interface IApiProtectedMixinJson extends IApiItemJson {
+	isProtected: boolean;
+}
+
+const _isProtected: unique symbol = Symbol('ApiProtectedMixin._isProtected');
+
+/**
+ * The mixin base class for API items that can have the TypeScript `protected` keyword applied to them.
+ *
+ * @remarks
+ *
+ * This is part of the {@link ApiModel} hierarchy of classes, which are serializable representations of
+ * API declarations.  The non-abstract classes (e.g. `ApiClass`, `ApiEnum`, `ApiInterface`, etc.) use
+ * TypeScript "mixin" functions (e.g. `ApiDeclaredItem`, `ApiItemContainerMixin`, etc.) to add various
+ * features that cannot be represented as a normal inheritance chain (since TypeScript does not allow a child class
+ * to extend more than one base class).  The "mixin" is a TypeScript merged declaration with three components:
+ * the function that generates a subclass, an interface that describes the members of the subclass, and
+ * a namespace containing static members of the class.
+ * @public
+ */
+
+export interface ApiProtectedMixin extends ApiItem {
+	/**
+	 * Whether the declaration has the TypeScript `protected` keyword.
+	 */
+	readonly isProtected: boolean;
+
+	/**
+	 * @override
+	 */
+	serializeInto(jsonObject: Partial<IApiItemJson>): void;
+}
+
+/**
+ * Mixin function for {@link (ApiProtectedMixin:interface)}.
+ *
+ * @param baseClass - The base class to be extended
+ * @returns A child class that extends baseClass, adding the {@link (ApiProtectedMixin:interface)} functionality.
+ * @public
+ */
+export function ApiProtectedMixin<TBaseClass extends IApiItemConstructor>(
+	baseClass: TBaseClass,
+): TBaseClass & (new (...args: any[]) => ApiProtectedMixin) {
+	class MixedClass extends baseClass implements ApiProtectedMixin {
+		public [_isProtected]: boolean;
+
+		public constructor(...args: any[]) {
+			super(...args);
+
+			const options: IApiProtectedMixinOptions = args[0];
+			this[_isProtected] = options.isProtected;
+		}
+
+		/**
+		 * @override
+		 */
+		public static override onDeserializeInto(
+			options: Partial<IApiProtectedMixinOptions>,
+			context: DeserializerContext,
+			jsonObject: IApiProtectedMixinJson,
+		): void {
+			baseClass.onDeserializeInto(options, context, jsonObject);
+
+			options.isProtected = jsonObject.isProtected;
+		}
+
+		public get isProtected(): boolean {
+			return this[_isProtected];
+		}
+
+		/**
+		 * @override
+		 */
+		public override serializeInto(jsonObject: Partial<IApiProtectedMixinJson>): void {
+			super.serializeInto(jsonObject);
+
+			jsonObject.isProtected = this.isProtected;
+		}
+	}
+
+	return MixedClass;
+}
+
+/**
+ * Static members for {@link (ApiProtectedMixin:interface)}.
+ *
+ * @public
+ */
+export namespace ApiProtectedMixin {
+	/**
+	 * A type guard that tests whether the specified `ApiItem` subclass extends the `ApiProtectedMixin` mixin.
+	 *
+	 * @remarks
+	 *
+	 * The JavaScript `instanceof` operator cannot be used to test for mixin inheritance, because each invocation of
+	 * the mixin function produces a different subclass.  (This could be mitigated by `Symbol.hasInstance`, however
+	 * the TypeScript type system cannot invoke a runtime test.)
+	 */
+	export function isBaseClassOf(apiItem: ApiItem): apiItem is ApiProtectedMixin {
+		return apiItem.hasOwnProperty(_isProtected);
+	}
+}