chore: some more type work

2026-03-09 16:13:31 +01:00 · 2024-07-17 15:07:43 +04:00
parent 4d2a1110b8
commit a6ee54aa0c
12 changed files with 113 additions and 4 deletions
--- a/packages/discord.js/scripts/generateRequires.mjs
+++ b/packages/discord.js/scripts/generateRequires.mjs
@@ -123,9 +123,15 @@ declare class ActionsManager {
        dtsLines.push(`  ${fileName}: Action<[import('discord-api-types/v10').GatewayMessagePollVoteDispatchData]>;`);
        break;
      }
+      case 'ChannelCreate': {
+        dtsLines.push(
+          `  ${fileName}: Action<[import('discord-api-types/v10').GatewayChannelCreateDispatchData], { channel?: BaseChannel | null }>;`,
+        );
+        break;
+      }
      case 'ChannelUpdate': {
        dtsLines.push(
-          `  ${fileName}: Action<[import('discord-api-types/v10').GatewayChannelUpdateDispatchData], { old?: BaseChannel; updated?: BaseChannel; }>;`,
+          `  ${fileName}: Action<[import('discord-api-types/v10').GatewayChannelUpdateDispatchData], { old?: BaseChannel | null; updated?: BaseChannel; }>;`,
        );
        break;
      }
--- a/packages/discord.js/src/client/actions/Action.js
+++ b/packages/discord.js/src/client/actions/Action.js
@@ -2,6 +2,7 @@

 /**
 * @import Client from '../Client';
+ * @import CachedManager from '../../managers/CachedManager';
 */

 const Partials = require('../../util/Partials');
@@ -21,6 +22,7 @@ that WebSocket events don't clash with REST methods.
 /**
 * @template {any[]} Arguments
 * @template {any} [ReturnType=void]
+ * @ignore
 */
 class GenericAction {
  /**
@@ -35,6 +37,7 @@ class GenericAction {
  /**
   * @param {Arguments} _args Arguments passed to the handler
   * @returns {ReturnType}
+   * @ignore
   */
  handle(..._args) {
    /** @type {any} */
@@ -42,6 +45,14 @@ class GenericAction {
    return casted;
  }

+  /**
+   * @param {unknown} data The data to add
+   * @param {CachedManager} manager The manager the data is for
+   * @param {string} id The id of the entry
+   * @param {Partials} partialType If a partial structure is supported, the type of partial
+   * @param {boolean} cache Whether the added data should be cached
+   * @returns {unknown}
+   */
  getPayload(data, manager, id, partialType, cache) {
    return this.client.options.partials.includes(partialType) ? manager._add(data, cache) : manager.cache.get(id);
  }
--- a/packages/discord.js/src/client/actions/ActionsManager.d.ts
+++ b/packages/discord.js/src/client/actions/ActionsManager.d.ts
@@ -25,11 +25,14 @@ declare class ActionsManager {
  AutoModerationRuleCreate: Action<[import('discord-api-types/v10').GatewayAutoModerationRuleCreateDispatchData]>;
  AutoModerationRuleDelete: Action<[import('discord-api-types/v10').GatewayAutoModerationRuleDeleteDispatchData]>;
  AutoModerationRuleUpdate: Action<[import('discord-api-types/v10').GatewayAutoModerationRuleUpdateDispatchData]>;
-  ChannelCreate: Action<[import('discord-api-types/v10').GatewayChannelCreateDispatchData]>;
+  ChannelCreate: Action<
+    [import('discord-api-types/v10').GatewayChannelCreateDispatchData],
+    { channel?: BaseChannel | null }
+  >;
  ChannelDelete: Action<[import('discord-api-types/v10').GatewayChannelDeleteDispatchData]>;
  ChannelUpdate: Action<
    [import('discord-api-types/v10').GatewayChannelUpdateDispatchData],
-    { old?: BaseChannel; updated?: BaseChannel }
+    { old?: BaseChannel | null; updated?: BaseChannel }
  >;
  EntitlementCreate: Action<[import('discord-api-types/v10').GatewayEntitlementCreateDispatchData]>;
  EntitlementDelete: Action<[import('discord-api-types/v10').GatewayEntitlementDeleteDispatchData]>;
--- a/packages/discord.js/src/client/actions/ApplicationCommandPermissionsUpdate.js
+++ b/packages/discord.js/src/client/actions/ApplicationCommandPermissionsUpdate.js
@@ -12,7 +12,16 @@ const Events = require('../../util/Events');
 * @property {ApplicationCommandPermissions[]} permissions The updated permissions
 */

+/**
+ * @extends {Action<[import('discord-api-types/v10').GatewayApplicationCommandPermissionsUpdateDispatchData]>}
+ * @private
+ * @internal
+ */
 class ApplicationCommandPermissionsUpdateAction extends Action {
+  /**
+   * @override
+   * @param {import('discord-api-types/v10').GatewayApplicationCommandPermissionsUpdateDispatchData} data
+   */
  handle(data) {
    const client = this.client;
    /**
--- a/packages/discord.js/src/client/actions/AutoModerationActionExecution.js
+++ b/packages/discord.js/src/client/actions/AutoModerationActionExecution.js
@@ -4,7 +4,16 @@ const Action = require('./Action');
 const AutoModerationActionExecution = require('../../structures/AutoModerationActionExecution');
 const Events = require('../../util/Events');

+/**
+ * @extends {Action<[import('discord-api-types/v10').GatewayAutoModerationActionExecutionDispatchData]>}
+ * @private
+ * @internal
+ */
 class AutoModerationActionExecutionAction extends Action {
+  /**
+   * @override
+   * @param {import('discord-api-types/v10').GatewayAutoModerationActionExecutionDispatchData} data
+   */
  handle(data) {
    const { client } = this;
    const guild = client.guilds.cache.get(data.guild_id);
--- a/packages/discord.js/src/client/actions/AutoModerationRuleCreate.js
+++ b/packages/discord.js/src/client/actions/AutoModerationRuleCreate.js
@@ -3,7 +3,16 @@
 const Action = require('./Action');
 const Events = require('../../util/Events');

+/**
+ * @extends {Action<[import('discord-api-types/v10').GatewayAutoModerationRuleCreateDispatchData]>}
+ * @private
+ * @internal
+ */
 class AutoModerationRuleCreateAction extends Action {
+  /**
+   * @override
+   * @param {import('discord-api-types/v10').GatewayAutoModerationRuleCreateDispatchData} data
+   */
  handle(data) {
    const { client } = this;
    const guild = client.guilds.cache.get(data.guild_id);
--- a/packages/discord.js/src/client/actions/AutoModerationRuleDelete.js
+++ b/packages/discord.js/src/client/actions/AutoModerationRuleDelete.js
@@ -3,7 +3,16 @@
 const Action = require('./Action');
 const Events = require('../../util/Events');

+/**
+ * @extends {Action<[import('discord-api-types/v10').GatewayAutoModerationRuleDeleteDispatchData]>}
+ * @private
+ * @internal
+ */
 class AutoModerationRuleDeleteAction extends Action {
+  /**
+   * @override
+   * @param {import('discord-api-types/v10').GatewayAutoModerationRuleDeleteDispatchData} data
+   */
  handle(data) {
    const { client } = this;
    const guild = client.guilds.cache.get(data.guild_id);
--- a/packages/discord.js/src/client/actions/AutoModerationRuleUpdate.js
+++ b/packages/discord.js/src/client/actions/AutoModerationRuleUpdate.js
@@ -3,7 +3,16 @@
 const Action = require('./Action');
 const Events = require('../../util/Events');

+/**
+ * @extends {Action<[import('discord-api-types/v10').GatewayAutoModerationRuleDeleteDispatchData]>}
+ * @private
+ * @internal
+ */
 class AutoModerationRuleUpdateAction extends Action {
+  /**
+   * @override
+   * @param {import('discord-api-types/v10').GatewayAutoModerationRuleDeleteDispatchData} data
+   */
  handle(data) {
    const { client } = this;
    const guild = client.guilds.cache.get(data.guild_id);
--- a/packages/discord.js/src/client/actions/ChannelCreate.js
+++ b/packages/discord.js/src/client/actions/ChannelCreate.js
@@ -1,13 +1,27 @@
 'use strict';

+/**
+ * @import { BaseChannel } from '../../structures/BaseChannel';
+ */
+
 const Action = require('./Action');
 const Events = require('../../util/Events');

+/**
+ * @extends {Action<[import('discord-api-types/v10').GatewayChannelCreateDispatchData], { channel?: BaseChannel | null }>}
+ * @private
+ * @internal
+ */
 class ChannelCreateAction extends Action {
+  /**
+   * @override
+   * @param {import('discord-api-types/v10').GatewayChannelCreateDispatchData} data
+   */
  handle(data) {
    const client = this.client;
    const existing = client.channels.cache.has(data.id);
    const channel = client.channels._add(data);
+
    if (!existing && channel) {
      /**
       * Emitted whenever a guild channel is created.
@@ -16,6 +30,7 @@ class ChannelCreateAction extends Action {
       */
      client.emit(Events.ChannelCreate, channel);
    }
+
    return { channel };
  }
 }
--- a/packages/discord.js/src/managers/BaseManager.d.ts
+++ b/packages/discord.js/src/managers/BaseManager.d.ts
@@ -0,0 +1,8 @@
+import Client from '../client/Client';
+
+declare class BaseManager {
+  readonly client: Client;
+  constructor(client: Client);
+}
+
+export = BaseManager;
--- a/packages/discord.js/src/managers/ChannelManager.js
+++ b/packages/discord.js/src/managers/ChannelManager.js
@@ -1,5 +1,10 @@
 'use strict';

+/**
+ * @import { Guild } from '../structures/Guild';
+ * @import Client from '../client/Client';
+ */
+
 const process = require('node:process');
 const { Routes } = require('discord-api-types/v10');
 const CachedManager = require('./CachedManager');
@@ -15,12 +20,19 @@ let cacheWarningEmitted = false;
 * @extends {CachedManager}
 */
 class ChannelManager extends CachedManager {
+  /**
+   * @ignore
+   * @param {Client} client The client
+   * @param {unknown[]} iterable existing channels
+   */
  constructor(client, iterable) {
    super(client, BaseChannel, iterable);
+
    const defaultCaching =
      this._cache.constructor.name === 'Collection' ||
      this._cache.maxSize === undefined ||
      this._cache.maxSize === Infinity;
+
    if (!cacheWarningEmitted && !defaultCaching) {
      cacheWarningEmitted = true;
      process.emitWarning(
@@ -36,6 +48,15 @@ class ChannelManager extends CachedManager {
   * @name ChannelManager#cache
   */

+  // eslint-disable-next-line valid-jsdoc
+  /**
+   * @ignore
+   * @param {import('discord-api-types/v10').APIChannel} data
+   * @param {Guild} [guild]
+   * @param {{ cache?: boolean; allowUnknownGuild?: boolean; }} [options]
+   * @returns {?BaseChannel}
+   * @override
+   */
  _add(data, guild, { cache = true, allowUnknownGuild = false } = {}) {
    const existing = this.cache.get(data.id);
    if (existing) {
--- a/packages/discord.js/src/util/Channels.js
+++ b/packages/discord.js/src/util/Channels.js
@@ -18,7 +18,7 @@ const getMediaChannel = lazy(() => require('../structures/MediaChannel'));
 /**
 * Extra options for creating a channel.
 * @typedef {Object} CreateChannelOptions
- * @property {boolean} [allowFromUnknownGuild] Whether to allow creating a channel from an unknown guild
+ * @property {boolean} [allowUnknownGuild] Whether to allow creating a channel from an unknown guild
 * @private
 */