feat: add buffers() method returning Buffer[]

claude · claude · commit 9c63469fc08f · 2026-04-22T14:00:14.000Z
Adds a new Source.prototype.buffers() method that returns the represented source code as an array of Buffers, avoiding the intermediate Buffer.concat allocation that buffer() performs on composite sources such as ConcatSource. Consumers that can accept Buffer[] (e.g. fs.createWriteStream backed by writev) can now keep data as Buffer[] across nested CachedSource/ConcatSource layers and write it out in one shot, which avoids repeatedly copying the same bytes. - Source: default buffers() returns [this.buffer()]. - ConcatSource: flattens child buffers() into a single Buffer[] without concatenating, and buffer() is now implemented via Buffer.concat(buffers()). - CachedSource: caches the Buffer[] separately from the Buffer; buffer() concatenates lazily when requested, so repeated buffers() calls do not trigger copies. - CompatSource: forwards to sourceLike.buffers() when available, otherwise falls back to the default. - SizeOnlySource: throws like buffer(). Closes #157
diff --git a/.changeset/buffers-method.md b/.changeset/buffers-method.md
@@ -0,0 +1,5 @@
+---
+"webpack-sources": minor
+---
+
+Add `Source.prototype.buffers()` that returns the source as `Buffer[]`. `ConcatSource`, `CachedSource`, and `CompatSource` implement it without allocating an intermediate concatenated buffer, allowing consumers that can write multiple buffers at once (e.g. via `writev`) to avoid the overhead of `Buffer.concat` in deeply nested sources.
diff --git a/README.md b/README.md
@@ -28,6 +28,21 @@ Source.prototype.buffer() -> Buffer
 
 Returns the represented source code as Buffer. Strings are converted to utf-8.
 
+#### `buffers`
+
+<!-- eslint-skip -->
+```typescript
+Source.prototype.buffers() -> Buffer[]
+```
+
+Returns the represented source code as an array of Buffers. This avoids the
+intermediate `Buffer.concat` allocation performed by `buffer()` when the source
+is composed of multiple children (for example `ConcatSource`). Consumers that
+can accept an array of buffers (e.g. writing via `fs.createWriteStream` or
+`writev`) should prefer this method for better performance.
+
+The default implementation returns `[this.buffer()]`.
+
 #### `size`
 
 <!-- eslint-skip -->
diff --git a/lib/CachedSource.js b/lib/CachedSource.js
@@ -114,6 +114,11 @@ class CachedSource extends Source {
 		 * @type {Buffer | undefined}
 		 */
 		this._cachedBuffer = cachedData ? cachedData.buffer : undefined;
+		/**
+		 * @private
+		 * @type {Buffer[] | undefined}
+		 */
+		this._cachedBuffers = undefined;
 		/**
 		 * @private
 		 * @type {number | undefined}
@@ -228,6 +233,9 @@ class CachedSource extends Source {
 	 */
 	buffer() {
 		if (this._cachedBuffer !== undefined) return this._cachedBuffer;
+		if (this._cachedBuffers !== undefined) {
+			return (this._cachedBuffer = Buffer.concat(this._cachedBuffers));
+		}
 		if (this._cachedSource !== undefined) {
 			const value = Buffer.isBuffer(this._cachedSource)
 				? this._cachedSource
@@ -251,6 +259,21 @@ class CachedSource extends Source {
 		return value;
 	}
 
+	/**
+	 * @returns {Buffer[]} buffers
+	 */
+	buffers() {
+		if (this._cachedBuffers !== undefined) return this._cachedBuffers;
+		if (this._cachedBuffer !== undefined) {
+			return (this._cachedBuffers = [this._cachedBuffer]);
+		}
+		const original = this.original();
+		if (typeof original.buffers === "function") {
+			return (this._cachedBuffers = original.buffers());
+		}
+		return (this._cachedBuffers = [this.buffer()]);
+	}
+
 	/**
 	 * @returns {number} size
 	 */
diff --git a/lib/CompatSource.js b/lib/CompatSource.js
@@ -17,6 +17,7 @@ const Source = require("./Source");
  * @typedef {object} SourceLike
  * @property {() => SourceValue} source source
  * @property {(() => Buffer)=} buffer buffer
+ * @property {(() => Buffer[])=} buffers buffers
  * @property {(() => number)=} size size
  * @property {((options?: MapOptions) => RawSourceMap | null)=} map map
  * @property {((options?: MapOptions) => SourceAndMap)=} sourceAndMap source and map
@@ -60,6 +61,16 @@ class CompatSource extends Source {
 		return super.buffer();
 	}
 
+	/**
+	 * @returns {Buffer[]} buffers
+	 */
+	buffers() {
+		if (typeof this._sourceLike.buffers === "function") {
+			return this._sourceLike.buffers();
+		}
+		return super.buffers();
+	}
+
 	size() {
 		if (typeof this._sourceLike.size === "function") {
 			return this._sourceLike.size();
diff --git a/lib/ConcatSource.js b/lib/ConcatSource.js
@@ -89,11 +89,22 @@ class ConcatSource extends Source {
 	}
 
 	buffer() {
+		return Buffer.concat(this.buffers());
+	}
+
+	/**
+	 * @returns {Buffer[]} buffers
+	 */
+	buffers() {
 		if (!this._isOptimized) this._optimize();
 		/** @type {Buffer[]} */
 		const buffers = [];
 		for (const child of /** @type {SourceLike[]} */ (this._children)) {
-			if (typeof child.buffer === "function") {
+			if (typeof child.buffers === "function") {
+				for (const buffer of child.buffers()) {
+					buffers.push(buffer);
+				}
+			} else if (typeof child.buffer === "function") {
 				buffers.push(child.buffer());
 			} else {
 				const bufferOrString = child.source();
@@ -105,7 +116,7 @@ class ConcatSource extends Source {
 				}
 			}
 		}
-		return Buffer.concat(buffers);
+		return buffers;
 	}
 
 	/**
diff --git a/lib/SizeOnlySource.js b/lib/SizeOnlySource.js
@@ -49,6 +49,13 @@ class SizeOnlySource extends Source {
 		throw this._error();
 	}
 
+	/**
+	 * @returns {Buffer[]} buffers
+	 */
+	buffers() {
+		throw this._error();
+	}
+
 	/**
 	 * @param {MapOptions=} options map options
 	 * @returns {RawSourceMap | null} map
diff --git a/lib/Source.js b/lib/Source.js
@@ -52,6 +52,13 @@ class Source {
 		return Buffer.from(source, "utf8");
 	}
 
+	/**
+	 * @returns {Buffer[]} buffers
+	 */
+	buffers() {
+		return [this.buffer()];
+	}
+
 	size() {
 		return this.buffer().length;
 	}
diff --git a/test/CachedSource.js b/test/CachedSource.js
@@ -4,6 +4,7 @@ jest.mock("./__mocks__/createMappingsSerializer");
 
 const crypto = require("crypto");
 const { CachedSource } = require("../");
+const { ConcatSource } = require("../");
 const { OriginalSource } = require("../");
 const { RawSource } = require("../");
 const { Source } = require("../");
@@ -548,6 +549,32 @@ describe.each([
 		expect(chunks.length).toBeGreaterThan(0);
 	});
 
+	it("should return Buffer[] from buffers() and delegate to the original source", () => {
+		const original = new ConcatSource(
+			new RawSource(Buffer.from("hello ")),
+			new RawSource(Buffer.from("world")),
+		);
+		const cachedSource = new CachedSource(original);
+
+		const buffers = cachedSource.buffers();
+		expect(Array.isArray(buffers)).toBe(true);
+		expect(buffers).toHaveLength(2);
+		expect(Buffer.concat(buffers).toString("utf8")).toBe("hello world");
+		// The second call should return the cached array
+		expect(cachedSource.buffers()).toBe(buffers);
+	});
+
+	it("should return a single-entry Buffer[] from buffers() when buffer is already cached", () => {
+		const buffer = Buffer.from("cached");
+		const original = new RawSource(buffer);
+		const cachedSource = new CachedSource(original);
+		// Populate the buffer cache
+		cachedSource.buffer();
+		const buffers = cachedSource.buffers();
+		expect(buffers).toHaveLength(1);
+		expect(buffers[0]).toBe(buffer);
+	});
+
 	it("should round-trip CachedSource with a Buffer-backed source", () => {
 		const buffer = Buffer.from(Array.from({ length: 64 }, (_, i) => i));
 		const original = new RawSource(buffer);
diff --git a/test/CompatSource.js b/test/CompatSource.js
@@ -51,6 +51,31 @@ describe("compatSource", () => {
 		expect(source.buffer()).toBe(buffer);
 	});
 
+	it("should use buffers from source-like when provided", () => {
+		const buffers = [Buffer.from("a"), Buffer.from("b")];
+		const source = CompatSource.from({
+			source() {
+				return "ab";
+			},
+			buffers() {
+				return buffers;
+			},
+		});
+		expect(source.buffers()).toBe(buffers);
+	});
+
+	it("should fall back to super buffers() when sourceLike doesn't provide it", () => {
+		const CONTENT = "Hello";
+		const source = CompatSource.from({
+			source() {
+				return CONTENT;
+			},
+		});
+		const buffers = source.buffers();
+		expect(buffers).toHaveLength(1);
+		expect(buffers[0]).toEqual(Buffer.from(CONTENT));
+	});
+
 	it("should use size from super when sourceLike doesn't define size", () => {
 		const CONTENT = "Hello";
 		const source = CompatSource.from({
diff --git a/test/ConcatSource.js b/test/ConcatSource.js
@@ -229,6 +229,59 @@ describe("concatSource", () => {
 		);
 	});
 
+	it("should expose individual buffers via buffers() without concatenating", () => {
+		const a = new RawSource(Buffer.from("a"));
+		const b = new RawSource(Buffer.from("b"));
+		const c = new RawSource(Buffer.from("c"));
+		const source = new ConcatSource(a, b, c);
+		const buffers = source.buffers();
+		expect(Array.isArray(buffers)).toBe(true);
+		expect(buffers).toHaveLength(3);
+		expect(buffers[0]).toEqual(Buffer.from("a"));
+		expect(buffers[1]).toEqual(Buffer.from("b"));
+		expect(buffers[2]).toEqual(Buffer.from("c"));
+		expect(Buffer.concat(buffers)).toEqual(source.buffer());
+	});
+
+	it("should flatten nested ConcatSource buffers() into a flat Buffer[]", () => {
+		const inner = new ConcatSource(
+			new RawSource(Buffer.from("x")),
+			new RawSource(Buffer.from("y")),
+		);
+		const outer = new ConcatSource(new RawSource(Buffer.from("a")), inner);
+		const buffers = outer.buffers();
+		expect(buffers).toHaveLength(3);
+		expect(Buffer.concat(buffers).toString("utf8")).toBe("axy");
+	});
+
+	it("should fall back to buffer()/source() in buffers() for SourceLike children", () => {
+		const customBuffer = Buffer.from("custom");
+		const bufferOnly = {
+			source() {
+				return customBuffer;
+			},
+			buffer() {
+				return customBuffer;
+			},
+			size() {
+				return customBuffer.length;
+			},
+		};
+		const sourceOnly = {
+			source() {
+				return Buffer.from("more");
+			},
+			size() {
+				return 4;
+			},
+		};
+		const source = new ConcatSource(bufferOnly, sourceOnly);
+		const buffers = source.buffers();
+		expect(buffers).toHaveLength(2);
+		expect(buffers[0]).toBe(customBuffer);
+		expect(buffers[1]).toEqual(Buffer.from("more"));
+	});
+
 	it("should concat a SourceLike child where source() returns a string (no buffer())", () => {
 		const customSource = {
 			source() {
diff --git a/test/SizeOnlySource.js b/test/SizeOnlySource.js
@@ -8,7 +8,7 @@ describe("sizeOnlySource", () => {
 		expect(source.size()).toBe(42);
 	});
 
-	for (const method of ["source", "map", "sourceAndMap", "buffer"]) {
+	for (const method of ["source", "map", "sourceAndMap", "buffer", "buffers"]) {
 		it(`should throw on ${method}()`, () => {
 			const source = new SizeOnlySource(42);
 			expect(() => {
diff --git a/test/Source.js b/test/Source.js
@@ -73,4 +73,17 @@ describe("source", () => {
 		const source = new DummySource();
 		expect(source.size()).toBe(6);
 	});
+
+	it("should return a single-entry array for buffers() by default", () => {
+		class DummySource extends Source {
+			source() {
+				return "dummy";
+			}
+		}
+		const source = new DummySource();
+		const buffers = source.buffers();
+		expect(Array.isArray(buffers)).toBe(true);
+		expect(buffers).toHaveLength(1);
+		expect(buffers[0]).toEqual(Buffer.from("dummy", "utf8"));
+	});
 });
diff --git a/types.d.ts b/types.d.ts
@@ -318,6 +318,7 @@ declare class Source {
 	constructor();
 	source(): SourceValue;
 	buffer(): Buffer;
+	buffers(): Buffer[];
 	size(): number;
 	map(options?: MapOptions): null | RawSourceMap;
 	sourceAndMap(options?: MapOptions): SourceAndMap;
@@ -345,6 +346,11 @@ declare interface SourceLike {
 	 */
 	buffer?: () => Buffer;
 
+	/**
+	 * buffers
+	 */
+	buffers?: () => Buffer[];
+
 	/**
 	 * size
 	 */

-Original file line number
+Diff line change
@@ @@ -0,0 +1,5 @@ @@
 +---
 +"webpack-sources": minor
 +---
++
 +Add `Source.prototype.buffers()` that returns the source as `Buffer[]`. `ConcatSource`, `CachedSource`, and `CompatSource` implement it without allocating an intermediate concatenated buffer, allowing consumers that can write multiple buffers at once (e.g. via `writev`) to avoid the overhead of `Buffer.concat` in deeply nested sources.
Original file line number	Diff line number	Diff line change
`@@ -52,6 +52,13 @@ class Source {`
`52`	`52`	`return Buffer.from(source, "utf8");`
`53`	`53`	`}`
`54`	`54`
	`55`	`+ /**`
	`56`	`+ * @returns {Buffer[]} buffers`
	`57`	`+ */`
	`58`	`+ buffers() {`
	`59`	`+ return [this.buffer()];`
	`60`	`+ }`
	`61`	`+`
`55`	`62`	`size() {`
`56`	`63`	`return this.buffer().length;`
`57`	`64`	`}`