feat(builders): multipart form data output support (#11248)

* feat(builders): multipart form data output support

* refactor: proper key management

* chore: add missing remarks

* chore: requested changes

* chore: rename encodables file

* chore: requested changes

* chore: requested changes

* chore: nits

Co-authored-by: Almeida <github@almeidx.dev>

* chore: requested change

* chore: requested change

---------

Co-authored-by: Almeida <github@almeidx.dev>

packages/util/src/JSONEncodable.ts

@@ -1,20 +0,0 @@
-/**
- * Represents an object capable of representing itself as a JSON object
- *
- * @typeParam Value - The JSON type corresponding to {@link JSONEncodable.toJSON} outputs.
- */
-export interface JSONEncodable<Value> {
-	/**
-	 * Transforms this object to its JSON format
-	 */
-	toJSON(): Value;
-}
-
-/**
- * Indicates if an object is encodable or not.
- *
- * @param maybeEncodable - The object to check against
- */
-export function isJSONEncodable(maybeEncodable: unknown): maybeEncodable is JSONEncodable<unknown> {
-	return maybeEncodable !== null && typeof maybeEncodable === 'object' && 'toJSON' in maybeEncodable;
-}

packages/util/src/RawFile.ts

@@ -0,0 +1,34 @@
+import type { Buffer } from 'node:buffer';
+
+/**
+ * Represents a file to be added to a request with multipart/form-data encoding
+ */
+export interface RawFile {
+	/**
+	 * Content-Type of the file.
+	 * If not provided, it will be inferred from the file data when possible
+	 *
+	 * @example 'image/png'
+	 * @example 'application/pdf'
+	 */
+	contentType?: string;
+	/**
+	 * The actual data for the file
+	 */
+	data: Buffer | Uint8Array | boolean | number | string;
+	/**
+	 * An explicit key to use for the formdata field for this file.
+	 * When not provided, the index of the file in the files array is used in the form `files[${index}]`.
+	 * If you wish to alter the placeholder snowflake, you must provide this property in the same form (`files[${placeholder}]`)
+	 */
+	key?: string;
+	/**
+	 * The name of the file. This is the actual filename that will be used when uploading to Discord.
+	 * This is also the name you'll use to reference the file with attachment:// URLs.
+	 *
+	 * @example 'image.png'
+	 * @example 'document.pdf'
+	 * @example 'SPOILER_secret.jpeg'
+	 */
+	name: string;
+}

packages/util/src/encodables.ts

@@ -0,0 +1,61 @@
+import type { RawFile } from './RawFile.js';
+
+/**
+ * Represents an object capable of representing itself as a JSON object
+ *
+ * @typeParam Value - The JSON type corresponding to {@link JSONEncodable.toJSON} outputs.
+ */
+export interface JSONEncodable<Value> {
+	/**
+	 * Transforms this object to its JSON format
+	 */
+	toJSON(): Value;
+}
+
+/**
+ * Indicates if an object is encodable or not.
+ *
+ * @param maybeEncodable - The object to check against
+ */
+export function isJSONEncodable(maybeEncodable: unknown): maybeEncodable is JSONEncodable<unknown> {
+	return maybeEncodable !== null && typeof maybeEncodable === 'object' && 'toJSON' in maybeEncodable;
+}
+
+/**
+ * Result of encoding an object that includes file attachments
+ *
+ * @typeParam BodyValue - The JSON body type
+ */
+export interface FileBodyEncodableResult<BodyValue> {
+	/**
+	 * The JSON body to send with the request
+	 */
+	body: BodyValue;
+	/**
+	 * The files to attach to the request
+	 */
+	files: RawFile[];
+}
+
+/**
+ * Represents an object capable of representing itself as a request body with file attachments.
+ * Objects implementing this interface can separate JSON body data from binary file data,
+ * which is necessary for multipart/form-data requests.
+ *
+ * @typeParam BodyValue - The JSON body type
+ */
+export interface FileBodyEncodable<BodyValue> {
+	/**
+	 * Transforms this object to its file body format, separating the JSON body from file attachments.
+	 */
+	toFileBody(): FileBodyEncodableResult<BodyValue>;
+}
+
+/**
+ * Indicates if an object is file body encodable or not.
+ *
+ * @param maybeEncodable - The object to check against
+ */
+export function isFileBodyEncodable(maybeEncodable: unknown): maybeEncodable is FileBodyEncodable<unknown> {
+	return maybeEncodable !== null && typeof maybeEncodable === 'object' && 'toFileBody' in maybeEncodable;
+}

packages/util/src/index.ts

@@ -1,6 +1,7 @@
 export type * from './types.js';
 export * from './functions/index.js';
-export * from './JSONEncodable.js';
+export * from './encodables.js';
+export type * from './RawFile.js';
 export * from './Equatable.js';
 export * from './gatewayRateLimitError.js';