refactor: builders (#10448)

BREAKING CHANGE: formatters export removed (prev. deprecated)
BREAKING CHANGE: `SelectMenuBuilder` and `SelectMenuOptionBuilder` have been removed (prev. deprecated)
BREAKING CHANGE: `EmbedBuilder` no longer takes camalCase options
BREAKING CHANGE: `ActionRowBuilder` now has specialized `[add/set]X` methods as opposed to the current `[add/set]Components`
BREAKING CHANGE: Removed `equals` methods
BREAKING CHANGE: Sapphire -> zod for validation
BREAKING CHANGE: Removed the ability to pass `null`/`undefined` to clear fields, use `clearX()` instead
BREAKING CHANGE: Renamed all "slash command" symbols to instead use "chat input command"
BREAKING CHANGE: Removed `ContextMenuCommandBuilder` in favor of `MessageCommandBuilder` and `UserCommandBuilder`
BREAKING CHANGE: Removed support for passing the "string key"s of enums
BREAKING CHANGE: Removed `Button` class in favor for specialized classes depending on the style
BREAKING CHANGE: Removed nested `addX` styled-methods in favor of plural `addXs`

Co-authored-by: Vlad Frangu <me@vladfrangu.dev>
Co-authored-by: Almeida <github@almeidx.dev>

packages/builders/src/util/resolveBuilder.ts

@@ -0,0 +1,40 @@
+import type { JSONEncodable } from '@discordjs/util';
+
+/**
+ * @privateRemarks
+ * This is a type-guard util, because if you were to in-line `builder instanceof Constructor` in the `resolveBuilder`
+ * function, TS doesn't narrow out the type `Builder`, causing a type error on the last return statement.
+ * @internal
+ */
+function isBuilder<Builder extends JSONEncodable<any>>(
+	builder: unknown,
+	Constructor: new () => Builder,
+): builder is Builder {
+	return builder instanceof Constructor;
+}
+
+/**
+ * "Resolves" a builder from the 3 ways it can be input:
+ * 1. A clean instance
+ * 2. A data object that can be used to construct the builder
+ * 3. A function that takes a builder and returns a builder e.g. `builder => builder.setFoo('bar')`
+ *
+ * @typeParam Builder - The builder type
+ * @typeParam BuilderData - The data object that can be used to construct the builder
+ * @param builder - The user input, as described in the function description
+ * @param Constructor - The constructor of the builder
+ */
+export function resolveBuilder<Builder extends JSONEncodable<any>, BuilderData extends Record<PropertyKey, any>>(
+	builder: Builder | BuilderData | ((builder: Builder) => Builder),
+	Constructor: new (data?: BuilderData) => Builder,
+): Builder {
+	if (isBuilder(builder, Constructor)) {
+		return builder;
+	}
+
+	if (typeof builder === 'function') {
+		return builder(new Constructor());
+	}
+
+	return new Constructor(builder);
+}