types: return more precise `Buffer<ArrayBuffer>` from `toBuffer` by Andarist · Pull Request #4520 · lovell/sharp

Andarist · 2026-04-10T11:02:08Z

No description provided.

lovell · 2026-04-11T11:44:03Z

Hi Mateusz, thanks for the PR.

If you hadn't seen, the next 0.35.0 release of sharp will also allow output via a new toUint8Array() to complement the existing toBuffer() - see #4355

toUint8Array(): Promise<{ data: Uint8Array; info: OutputInfo }>;

My understanding is that Node.js Buffer instances allocated by native code are treated as being backed by a SharedArrayBuffer and are considered non-transferable whereas Uint8Array instances are always backed by an ArrayBuffer and are transferable (e.g. between worker threads).

I think this means that that existing toBuffer() will resolve with a Buffer<SharedArrayBuffer> - is this something you're able to check?

lovell · 2026-06-26T20:37:28Z

@Andarist Hej Mateusz, is this something you're still interested in working on? No worries if not, I'm happy to take it on.

lovell · 2026-06-27T09:59:55Z

Posting a possible diff here for my future self to use as this might be a breaking change:

--- a/lib/index.d.ts
+++ b/lib/index.d.ts
@@ -667,7 +667,7 @@ declare namespace sharp {
          * @param options.resolveWithObject Resolve the Promise with an Object containing data and info properties instead of resolving only with data.
          * @returns A promise that resolves with the Buffer data.
          */
-        toBuffer(options?: { resolveWithObject: false }): Promise<Buffer>;
+        toBuffer(options?: { resolveWithObject: false }): Promise<Buffer<SharedArrayBuffer>>;
 
         /**
          * Write output to a Buffer. JPEG, PNG, WebP, AVIF, TIFF, GIF and RAW output are supported.
@@ -676,14 +676,14 @@ declare namespace sharp {
          * @param options.resolveWithObject Resolve the Promise with an Object containing data and info properties instead of resolving only with data.
          * @returns A promise that resolves with an object containing the Buffer data and an info object containing the output image format, size (bytes), width, height and channels
          */
-        toBuffer(options: { resolveWithObject: true }): Promise<{ data: Buffer; info: OutputInfo }>;
+        toBuffer(options: { resolveWithObject: true }): Promise<{ data: Buffer<SharedArrayBuffer>; info: OutputInfo }>;
 
         /**
          * Write output to a Uint8Array backed by a transferable ArrayBuffer. JPEG, PNG, WebP, AVIF, TIFF, GIF and RAW output are supported.
          * By default, the format will match the input image, except SVG input which becomes PNG output.
          * @returns A promise that resolves with an object containing the Uint8Array data and an info object containing the output image format, size (bytes), width, height and channels
          */
-        toUint8Array(): Promise<{ data: Uint8Array; info: OutputInfo }>;
+        toUint8Array(): Promise<{ data: Uint8Array<ArrayBuffer>; info: OutputInfo }>;
 
         /**
          * Set output density (DPI) in EXIF metadata.

Andarist · 2026-06-27T10:51:39Z

I tested this with:

const sharp = require("sharp");
const {
  MessageChannel,
  isMarkedAsUntransferable,
} = require("node:worker_threads");

(async () => {
  for (const mode of ["toBuffer", "toUint8Array"]) {
    const image = sharp({
      create: {
        width: 1,
        height: 1,
        channels: 3,
        background: "red",
      },
    }).png();

    const value =
      mode === "toBuffer"
        ? await image.toBuffer()
        : (await image.toUint8Array()).data;

    console.log(`\n${mode}`);
    console.log("sharp:", sharp.versions.sharp);
    console.log("node:", process.version);
    console.log("Buffer.isBuffer:", Buffer.isBuffer(value));
    console.log("value.constructor.name:", value.constructor.name);
    console.log(
      "value.buffer.constructor.name:",
      value.buffer.constructor.name,
    );
    console.log(
      "value.buffer instanceof ArrayBuffer:",
      value.buffer instanceof ArrayBuffer,
    );
    console.log(
      "value.buffer instanceof SharedArrayBuffer:",
      value.buffer instanceof SharedArrayBuffer,
    );
    console.log(
      "isMarkedAsUntransferable(value.buffer):",
      isMarkedAsUntransferable(value.buffer),
    );

    const { port2 } = new MessageChannel();

    try {
      port2.postMessage(value.buffer, [value.buffer]);
      console.log("transfer: ok");
    } catch (err) {
      console.log("transfer:", err.name, err.message);
    }
  }
})();

and got this output:

  toBuffer
  Buffer.isBuffer: true
  value.constructor.name: Buffer
  value.buffer.constructor.name: ArrayBuffer
  value.buffer instanceof ArrayBuffer: true
  value.buffer instanceof SharedArrayBuffer: false
  isMarkedAsUntransferable(value.buffer): true
  transfer: DataCloneError Cannot transfer object of unsupported type.

  toUint8Array
  Buffer.isBuffer: true
  value.constructor.name: Buffer
  value.buffer.constructor.name: ArrayBuffer
  value.buffer instanceof ArrayBuffer: true
  value.buffer instanceof SharedArrayBuffer: false
  isMarkedAsUntransferable(value.buffer): false
  transfer: ok

From what I can tell, none of those return SharedArrayBuffer here.

lovell · 2026-06-27T17:11:17Z

Brilliant, thanks for the update Mateusz.

Although ArrayBuffer instances are supposed to be transferable (MDN), it looks like a Node.js Buffer instance wraps an ArrayBuffer that is marked as non-transferable. Given the outcome of your research this behaviour feels a bit like a bug, and there's some discussion about this upstream at nodejs/node#55593 so we're not alone.

Node-API added an experimental node_api_create_external_sharedarraybuffer method from Node.js 26.1.0 but we can't use that yet, and it's unclear if we need to anyway.

In summary I think this means that Buffer<ArrayBuffer> is correct in theory but a bit broken in practice.

lovell · 2026-06-29T10:07:14Z

This feels like a documentation thing now so let's merge and publish. Thanks again for taking the time to make a PR.

This PR contains the following updates: | Package | Change | [Age](https://docs.renovatebot.com/merge-confidence/) | [Confidence](https://docs.renovatebot.com/merge-confidence/) | |---|---|---|---| | [sharp](https://sharp.pixelplumbing.com) ([source](https://github.com/lovell/sharp), [changelog](https://github.com/lovell/sharp/blob/main/docs/src/content/docs/changelog.md)) | [`0.35.2` → `0.35.3`](https://renovatebot.com/diffs/npm/sharp/0.35.2/0.35.3) | ![age](https://developer.mend.io/api/mc/badges/age/npm/sharp/0.35.3?slim=true) | ![confidence](https://developer.mend.io/api/mc/badges/confidence/npm/sharp/0.35.2/0.35.3?slim=true) | --- ### Release Notes <details> <summary>lovell/sharp (sharp)</summary> ### [`v0.35.3`](https://github.com/lovell/sharp/releases/tag/v0.35.3) [Compare Source](lovell/sharp@v0.35.2...v0.35.3) - Tighten verification of `text` dimensions, TIFF tile dimensions and `extend` values. - Improve code bundler support by resolving path to libvips binary. - Increase default concurrency when use of `MALLOC_ARENA_MAX` is detected. - Emit warning about binaries provided by Electron for use on Linux. - Add `hasAlpha` property to output `info`. [#4500](lovell/sharp#4500) - TypeScript: Return more precise `Buffer<ArrayBuffer>` from `toBuffer`. [#4520](lovell/sharp#4520) [@Andarist](https://github.com/Andarist) - Bound `clahe` width and height to avoid signed overflow. [#4551](lovell/sharp#4551) [@metsw24-max](https://github.com/metsw24-max) - Bound `trim` margin to avoid signed overflow. [#4552](lovell/sharp#4552) [@metsw24-max](https://github.com/metsw24-max) - Reject infinite values when validating numbers. [#4553](lovell/sharp#4553) [@metsw24-max](https://github.com/metsw24-max) - Bound extract region to libvips coordinate limit. [#4555](lovell/sharp#4555) [@metsw24-max](https://github.com/metsw24-max) - Verify background colour values are numbers. [#4556](lovell/sharp#4556) [@metsw24-max](https://github.com/metsw24-max) - Bound create and raw input dimensions to coordinate limit. [#4558](lovell/sharp#4558) [@metsw24-max](https://github.com/metsw24-max) - Tighten recomb and affine matrix verification. [#4560](lovell/sharp#4560) [@chatman-media](https://github.com/chatman-media) - Verify cache memory limit to avoid overflow. [#4561](lovell/sharp#4561) [@metsw24-max](https://github.com/metsw24-max) </details> --- ### Configuration 📅 **Schedule**: (UTC) - Branch creation - At any time (no schedule defined) - Automerge - At any time (no schedule defined) 🚦 **Automerge**: Disabled by config. Please merge this manually once you are satisfied. ♻ **Rebasing**: Whenever PR becomes conflicted, or you tick the rebase/retry checkbox. 🔕 **Ignore**: Close this PR and you won't be reminded about this update again. --- - [ ] If you want to rebase/retry this PR, check this box --- This PR has been generated by [Mend Renovate](https://github.com/renovatebot/renovate).

types: return more precise Buffer<ArrayBuffer> from toBuffer

3c5ba67

Andarist commented Apr 10, 2026

View reviewed changes

Comment thread package.json

lovell added the typescript label Apr 11, 2026

Merge remote-tracking branch 'origin/main' into tobuffer-types

748a4aa

lovell merged commit 8694db0 into lovell:main Jun 29, 2026
32 checks passed

lovell added a commit that referenced this pull request Jun 29, 2026

Docs: Add changelog entry and note about transferable #4520

9a8d002

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

types: return more precise `Buffer<ArrayBuffer>` from `toBuffer`#4520

types: return more precise `Buffer<ArrayBuffer>` from `toBuffer`#4520
lovell merged 2 commits into
lovell:mainfrom
Andarist:tobuffer-types

Andarist commented Apr 10, 2026

Uh oh!

Uh oh!

lovell commented Apr 11, 2026

Uh oh!

lovell commented Jun 26, 2026

Uh oh!

lovell commented Jun 27, 2026

Uh oh!

Andarist commented Jun 27, 2026

Uh oh!

lovell commented Jun 27, 2026

Uh oh!

Uh oh!

lovell commented Jun 29, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Uh oh!

Conversation

Andarist commented Apr 10, 2026

Uh oh!

Uh oh!

lovell commented Apr 11, 2026

Uh oh!

lovell commented Jun 26, 2026

Uh oh!

lovell commented Jun 27, 2026

Uh oh!

Andarist commented Jun 27, 2026

Uh oh!

lovell commented Jun 27, 2026

Uh oh!

Uh oh!

lovell commented Jun 29, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants