Merge branch 'main' into escapeMarkdown

apps/website/src/components/Badges.tsx

@@ -18,8 +18,9 @@ export async function Badges({ node }: { readonly node: any }) {
 	const isAbstract = node.isAbstract;
 	const isReadonly = node.isReadonly;
 	const isOptional = node.isOptional;
+	const isExternal = node.isExternal;
 
-	const isAny = isDeprecated || isProtected || isStatic || isAbstract || isReadonly || isOptional;
+	const isAny = isDeprecated || isProtected || isStatic || isAbstract || isReadonly || isOptional || isExternal;
 
 	return isAny ? (
 		<div className="mb-1 flex gap-3">
@@ -33,6 +34,7 @@ export async function Badges({ node }: { readonly node: any }) {
 			{isAbstract ? <Badge className="bg-cyan-500/20 text-cyan-500">abstract</Badge> : null}
 			{isReadonly ? <Badge className="bg-purple-500/20 text-purple-500">readonly</Badge> : null}
 			{isOptional ? <Badge className="bg-cyan-500/20 text-cyan-500">optional</Badge> : null}
+			{isExternal ? <Badge className="bg-purple-500/20 text-purple-500">external</Badge> : null}
 		</div>
 	) : null;
 }

packages/builders/__tests__/interactions/ChatInputCommands/ChatInputCommands.test.ts

@@ -501,7 +501,7 @@ describe('ChatInput Commands', () => {
 		});
 
 		describe('integration types', () => {
-			test('GIVEN a builder with valid integraton types THEN does not throw an error', () => {
+			test('GIVEN a builder with valid integration types THEN does not throw an error', () => {
 				expect(() =>
 					getNamedBuilder()
 						.setIntegrationTypes([ApplicationIntegrationType.GuildInstall, ApplicationIntegrationType.UserInstall])

packages/builders/__tests__/interactions/ContextMenuCommands.test.ts

@@ -111,7 +111,7 @@ describe('Context Menu Commands', () => {
 		});
 
 		describe('integration types', () => {
-			test('GIVEN a builder with valid integraton types THEN does not throw an error', () => {
+			test('GIVEN a builder with valid integration types THEN does not throw an error', () => {
 				expect(() =>
 					getBuilder().setIntegrationTypes([
 						ApplicationIntegrationType.GuildInstall,

packages/builders/src/util/validation.ts

@@ -29,7 +29,7 @@ export function isValidationEnabled() {
 }
 
 /**
- * Parses a value with a given validator, accounting for wether validation is enabled.
+ * Parses a value with a given validator, accounting for whether validation is enabled.
  *
  * @param validator - The zod validator to use
  * @param value - The value to parse

packages/collection/__tests__/collection.test.ts

@@ -829,6 +829,33 @@ describe('sort() tests', () => {
 			const coll = createCollectionFrom(['a', 5], ['b', 3], ['c', 1]);
 			expect(coll.sort()).toStrictEqual(createCollectionFrom(['c', 1], ['b', 3], ['a', 5]));
 		});
+
+		describe('returns correct sort order for test values', () => {
+			const defaultSort = Collection['defaultSort']; // eslint-disable-line @typescript-eslint/dot-notation
+			const testDefaultSortOrder = (firstValue: any, secondValue: any, result: number) => {
+				expect(defaultSort(firstValue, secondValue)).toStrictEqual(result);
+				expect(defaultSort(secondValue, firstValue)).toStrictEqual(result ? result * -1 : 0);
+			};
+
+			test('correctly evaluates sort order of undefined', () => {
+				testDefaultSortOrder(undefined, undefined, 0);
+				testDefaultSortOrder(0, undefined, -1);
+			});
+
+			test('correctly evaluates numeric values stringwise', () => {
+				testDefaultSortOrder(-1, -2, -1); // "-1" before "-2"
+				testDefaultSortOrder(1, '1', 0); // "1" equal to "1"
+				testDefaultSortOrder(1, '1.0', -1); // "1" before "1.0"
+				testDefaultSortOrder(1.1, '1.1', 0); // "1.1" equal to "1.1"
+				testDefaultSortOrder('01', 1, -1); // "01" before "1"
+				testDefaultSortOrder(1, 1n, 0); // "1" equal to "1"
+				testDefaultSortOrder(Number.NaN, 'NaN', 0); // "NaN" equal to "NaN"
+			});
+
+			test('evaluates object literals as equal', () => {
+				testDefaultSortOrder({ a: 1 }, { b: 2 }, 0);
+			});
+		});
 	});
 });
 

packages/collection/src/collection.ts

@@ -831,10 +831,11 @@ export class Collection<Key, Value> extends Map<Key, Value> {
 
 	/**
 	 * The sort method sorts the items of a collection in place and returns it.
-	 * The default sort order is according to string Unicode code points.
+	 * If a comparison function is not provided, the function sorts by element values, using the same stringwise comparison algorithm as
+	 * {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/sort | Array.sort()}.
 	 *
-	 * @param compareFunction - Specifies a function that defines the sort order.
-	 * If omitted, the collection is sorted according to each character's Unicode code point value, according to the string conversion of each element.
+	 * @param compareFunction - Specifies a function that defines the sort order. The return value of this function should be negative if
+	 * `a` comes before `b`, positive if `b` comes before `a`, or zero if `a` and `b` are considered equal.
 	 * @example
 	 * ```ts
 	 * collection.sort((userA, userB) => userA.createdTimestamp - userB.createdTimestamp);
@@ -1024,15 +1025,15 @@ export class Collection<Key, Value> extends Map<Key, Value> {
 	}
 
 	/**
-	 * The sorted method sorts the items of a collection and returns it.
-	 * The default sort order is according to string Unicode code points.
+	 * The toSorted method returns a shallow copy of the collection with the items sorted.
+	 * If a comparison function is not provided, the function sorts by element values, using the same stringwise comparison algorithm as
+	 * {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/sort | Array.sort()}.
 	 *
-	 * @param compareFunction - Specifies a function that defines the sort order.
-	 * If omitted, the collection is sorted according to each character's Unicode code point value,
-	 * according to the string conversion of each element.
+	 * @param compareFunction - Specifies a function that defines the sort order. The return value of this function should be negative if
+	 * `a` comes before `b`, positive if `b` comes before `a`, or zero if `a` and `b` are considered equal.
 	 * @example
 	 * ```ts
-	 * collection.sorted((userA, userB) => userA.createdTimestamp - userB.createdTimestamp);
+	 * const sortedCollection = collection.toSorted((userA, userB) => userA.createdTimestamp - userB.createdTimestamp);
 	 * ```
 	 */
 	public toSorted(compareFunction: Comparator<Key, Value> = Collection.defaultSort): Collection<Key, Value> {
@@ -1044,8 +1045,20 @@ export class Collection<Key, Value> extends Map<Key, Value> {
 		return [...this.entries()];
 	}
 
+	/**
+	 * Emulates the default sort comparison algorithm used in ECMAScript. Equivalent to calling the
+	 * {@link https://tc39.es/ecma262/multipage/indexed-collections.html#sec-comparearrayelements | CompareArrayElements}
+	 * operation with arguments `firstValue`, `secondValue` and `undefined`.
+	 */
 	private static defaultSort<Value>(firstValue: Value, secondValue: Value): number {
-		return Number(firstValue > secondValue) || Number(firstValue === secondValue) - 1;
+		if (firstValue === undefined) return secondValue === undefined ? 0 : 1;
+		if (secondValue === undefined) return -1;
+
+		const x = String(firstValue);
+		const y = String(secondValue);
+		if (x < y) return -1;
+		if (y < x) return 1;
+		return 0;
 	}
 
 	/**

packages/core/api-extractor.json

@@ -1,5 +1,6 @@
 {
 	"extends": "../../api-extractor.json",
+	"bundledPackages": ["discord-api-types"],
 	"docModel": {
 		"projectFolderUrl": "https://github.com/discordjs/discord.js/tree/main/packages/core"
 	}

packages/core/src/api/channel.ts

@@ -41,6 +41,14 @@ export interface StartForumThreadOptions extends RESTPostAPIGuildForumThreadsJSO
 	message: RESTPostAPIGuildForumThreadsJSONBody['message'] & { files?: RawFile[] };
 }
 
+export interface CreateMessageOptions extends RESTPostAPIChannelMessageJSONBody {
+	files?: RawFile[];
+}
+
+export interface EditMessageOptions extends RESTPatchAPIChannelMessageJSONBody {
+	files?: RawFile[];
+}
+
 export class ChannelsAPI {
 	public constructor(private readonly rest: REST) {}
 
@@ -54,7 +62,7 @@ export class ChannelsAPI {
 	 */
 	public async createMessage(
 		channelId: Snowflake,
-		{ files, ...body }: RESTPostAPIChannelMessageJSONBody & { files?: RawFile[] },
+		{ files, ...body }: CreateMessageOptions,
 		{ signal }: Pick<RequestData, 'signal'> = {},
 	) {
 		return this.rest.post(Routes.channelMessages(channelId), {
@@ -76,7 +84,7 @@ export class ChannelsAPI {
 	public async editMessage(
 		channelId: Snowflake,
 		messageId: Snowflake,
-		{ files, ...body }: RESTPatchAPIChannelMessageJSONBody & { files?: RawFile[] },
+		{ files, ...body }: EditMessageOptions,
 		{ signal }: Pick<RequestData, 'signal'> = {},
 	) {
 		return this.rest.patch(Routes.channelMessage(channelId, messageId), {

packages/core/src/api/guild.ts

@@ -1,6 +1,6 @@
 /* eslint-disable jsdoc/check-param-names */
 
-import { makeURLSearchParams, type REST, type RawFile, type RequestData } from '@discordjs/rest';
+import { makeURLSearchParams, type RawFile, type REST, type RequestData } from '@discordjs/rest';
 import {
 	Routes,
 	type GuildMFALevel,
@@ -110,19 +110,13 @@ import {
 } from 'discord-api-types/v10';
 import { VoiceAPI } from './voice';
 
+export interface CreateStickerOptions extends Omit<RESTPostAPIGuildStickerFormDataBody, 'file'> {
+	file: RawFile;
+}
+
 export class GuildsAPI {
 	public constructor(private readonly rest: REST) {}
 
-	/**
-	 * Fetches a guild
-	 *
-	 * @see {@link https://discord.com/developers/docs/resources/guild#get-guild}
-	 * @param guildId - The id of the guild
-	 * @param options - The options for fetching the guild
-	 * @deprecated Use the overload with a query instead.
-	 */
-	public async get(guildId: Snowflake, { signal }?: Pick<RequestData, 'signal'>): Promise<RESTGetAPIGuildResult>;
-
 	/**
 	 * Fetches a guild
 	 *
@@ -131,26 +125,11 @@ export class GuildsAPI {
 	 * @param query - The query options for fetching the guild
 	 * @param options - The options for fetching the guild
 	 */
-	public async get(
-		guildId: Snowflake,
-		query?: RESTGetAPIGuildQuery,
-		options?: Pick<RequestData, 'signal'>,
-	): Promise<RESTGetAPIGuildResult>;
-
-	public async get(
-		guildId: Snowflake,
-		queryOrOptions: Pick<RequestData, 'signal'> | RESTGetAPIGuildQuery = {},
-		options: Pick<RequestData, 'signal'> = {},
-	) {
-		const requestData: RequestData = {
-			signal: ('signal' in queryOrOptions ? queryOrOptions : options).signal,
-		};
-
-		if ('with_counts' in queryOrOptions) {
-			requestData.query = makeURLSearchParams(queryOrOptions);
-		}
-
-		return this.rest.get(Routes.guild(guildId), requestData) as Promise<RESTGetAPIGuildResult>;
+	public async get(guildId: Snowflake, query: RESTGetAPIGuildQuery = {}, { signal }: Pick<RequestData, 'signal'> = {}) {
+		return this.rest.get(Routes.guild(guildId), {
+			query: makeURLSearchParams(query),
+			signal,
+		}) as Promise<RESTGetAPIGuildResult>;
 	}
 
 	/**
@@ -1013,7 +992,7 @@ export class GuildsAPI {
 	 */
 	public async createSticker(
 		guildId: Snowflake,
-		{ file, ...body }: Omit<RESTPostAPIGuildStickerFormDataBody, 'file'> & { file: RawFile },
+		{ file, ...body }: CreateStickerOptions,
 		{ reason, signal }: Pick<RequestData, 'reason' | 'signal'> = {},
 	) {
 		const fileData = { ...file, key: 'file' };