fs: support caller-supplied readFile() buffers

[mcollina]

Fixes: #63600

[ShogunPanda]

LGTM!

[Renegade334]

Could we not consolidate these two? Plenty of places across the API surface have options with "either a thing or a thing-like function" types.

[MattiasBuelens]

Agreed. It should be quite cheap to check typeof options.buffer === 'function' at the start.

[Renegade334]

I would personally advocate for this to throw if both buffer and encoding are provided – directly contradictory patterns should fail validation.

[codecov]

Codecov Report

❌ Patch coverage is 96.32353% with 10 lines in your changes missing coverage. Please review.
✅ Project coverage is 90.35%. Comparing base (8d0a3b8) to head (e8edd28).
⚠️ Report is 19 commits behind head on main.

Files with missing lines	Patch %	Lines
lib/internal/fs/promises.js	93.10%	4 Missing ⚠️
lib/fs.js	95.89%	3 Missing ⚠️
lib/internal/fs/read/context.js	95.94%	3 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main   #63634      +/-   ##
==========================================
+ Coverage   90.29%   90.35%   +0.06%     
==========================================
  Files         730      732       +2     
  Lines      234782   236689    +1907     
  Branches    43953    44582     +629     
==========================================
+ Hits       211993   213862    +1869     
- Misses      14501    14561      +60     
+ Partials     8288     8266      -22     

Files with missing lines	Coverage Δ
lib/internal/fs/utils.js	98.53% <100.00%> (+0.09%)	⬆️
lib/fs.js	98.36% <95.89%> (+0.16%)	⬆️
lib/internal/fs/read/context.js	94.92% <95.94%> (+0.35%)	⬆️
lib/internal/fs/promises.js	92.94% <93.10%> (+0.12%)	⬆️

... and 65 files with indirect coverage changes

🚀 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.

[LiviaMedeiros]

If we don't introduce options.getBuffer at all, this seems redundant.

Suggested change

	const { buffer, getBuffer } = options;
	if (getBuffer !== undefined) {
	throw new ERR_INVALID_ARG_VALUE.HideStackFramesError(
	'options.getBuffer',
	getBuffer,
	'is not supported. Use options.buffer instead',
	);
	}
	const { buffer } = options;

[LiviaMedeiros]

I think the validation should look more like this:

Suggested change

	if (buffer !== undefined) {
	if (typeof buffer === 'function') {
	validateFunction.withoutStackTrace(buffer, 'options.buffer');
	} else {
	validateBuffer.withoutStackTrace(buffer, 'options.buffer');
	}
	}
	if (buffer !== undefined && typeof buffer !== 'function' && !isArrayBufferView(buffer)) {
	throw new ERR_INVALID_ARG_TYPE.HideStackFramesError('options.buffer', ['Buffer', 'TypedArray', 'DataView', 'Function'], buffer);
	}