refactor!: remove AttachmentBuilder and support new file body encodables

[didinele]

Depends on #11248

Closes #11273

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

2 Skipped Deployments

Project	Deployment	Preview	Comments	Updated (UTC)
discord-js	Skipped			Nov 20, 2025 1:23pm
discord-js-guide	Skipped			Nov 20, 2025 1:23pm

[didinele]

Ready for review, but blocked until the other PR is merged.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 44.97%. Comparing base (68bb8af) to head (e6aef1e).

Additional details and impacted files

@@           Coverage Diff           @@
##             main   #11278   +/-   ##
=======================================
  Coverage   44.97%   44.97%           
=======================================
  Files         317      317           
  Lines       18222    18222           
  Branches     1817     1817           
=======================================
  Hits         8196     8196           
  Misses      10013    10013           
  Partials       13       13           

Flag	Coverage Δ
builders	81.15% <ø> (ø)

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

Resolved.

[Qjuh]

I'd prefer if there was still a way to pass an AttachmentBuilder into here, albeit not sure what type would make sense to put for that here.

Another helper type like RawFileEncodable which extends JSONEncodable with the additional getRawFile() method? Seems clunky but 🤷‍♂️

[didinele]

The main issue I have with this is that AttachmentBuilder includes data tied to.. well, the attachments array.

What do we do when the user sets that data and they also provide attachments manually?

[Qjuh]

The same we did before:

discord.js/packages/discord.js/src/structures/MessagePayload.js

Lines 193 to 204 in 02fc101

	const attachments = this.options.files?.map((file, index) => ({
	id: index.toString(),
	description: file.description,
	title: file.title,
	waveform: file.waveform,
	duration_secs: file.duration,
	}));
	if (Array.isArray(this.options.attachments)) {
	this.options.attachments.push(...(attachments ?? []));
	} else {
	this.options.attachments = attachments;
	}

[didinele]

That is absolutely awful in terms of library behavior. That snippet effectively means that if you pass both files and attachments at the same time, it's a guaranteed API error, unless it's a message edit and the elements the user passed to the attachments array specifically refer to existing attachments.

In essence, this renders the attachments field as edit-only, we're just completely taking over it with this behavior, largely hiding how the API payload works too (which I am not fond of at all, no matter how rich the the abstraction).

[Qjuh]

But that's what AttachmentBuilder does too... it hides the same things the same way.

[didinele]

No. This isn't about hiding things, it's allowing the user to easily pass garbage. AttachmentBuilder on its own is fundamentally different from what you want, it removes your granular control of the files/attachments fields, it ties them together completely. There is no way when using it to get non-sense miss-matched arrays. All the more so when you use MessageBuilder

[didinele]

Circling back on this, the only way I'd accept it is making it a union type that forbids files if attachments is AttachmentBuilder[], I'm not compromising otherwise

[Qjuh]

Thing is that all the other types allowed for files here will also fill the attachments. So if anything it would make sense to completely disallow attachments in create Message options.

And you got it backwards: it's an accepted type for the files property and will disallow the attachments property.

[didinele]

Sure. I'm okay with designing the API that way, but we do also have to acknowledge the complexity it adds