How do I type Buffers and Uint8Arrays in JSDoc?

The short answer

Take bytes as @param {Uint8Array}. A Node.js Buffer is a subclass of Uint8Array, so the same function accepts a file read from disk and bytes from TextEncoder:

import { createHash } from "node:crypto";
import { readFile } from "node:fs/promises";

/**
 * @param {Uint8Array} bytes
 * @returns {string}
 */
export function sha256Hex(bytes) {
  return createHash("sha256").update(bytes).digest("hex");
}

/**
 * @param {Uint8Array} bytes
 * @returns {string}
 */
export function toHex(bytes) {
  return Array.from(bytes, (byte) => byte.toString(16).padStart(2, "0")).join("");
}

const file = await readFile("logo.png");
console.log(sha256Hex(file), toHex(new TextEncoder().encode("LAMP-01")));

import { createHash } from "node:crypto";
import { readFile } from "node:fs/promises";

export function sha256Hex(bytes: Uint8Array): string {
  return createHash("sha256").update(bytes).digest("hex");
}

export function toHex(bytes: Uint8Array): string {
  return Array.from(bytes, (byte) => byte.toString(16).padStart(2, "0")).join("");
}

const file = await readFile("logo.png");
console.log(sha256Hex(file), toHex(new TextEncoder().encode("LAMP-01")));

Inside, use what Uint8Array offers (indexing, Array.from, subarray), and pass the bytes to APIs that accept views, such as hash.update().

Why it works

@types/node declares Buffer as extending Uint8Array, which is how Node.js implements it. A parameter typed with the base class accepts both, and tsc checks that the function only uses members the base class has. Writing to the wider type keeps the function usable outside Node.js too.

The same thing in TypeScript

The TypeScript equivalent tab writes bytes: Uint8Array in the parameter list; the bodies are unchanged.

What goes wrong

Uint8Array has a toString() with no parameters, so the Buffer habit toString("hex") is an argument count error (TS2554). A string is not bytes, and an ArrayBuffer is raw memory without the view methods (TS2345 for both):

/** @param {Uint8Array} bytes */
export function toHex(bytes) {
  return bytes.toString("hex");error TS2554: Expected 0 arguments, but got 1.
}

toHex("LAMP-01");error TS2345: Argument of type 'string' is not assignable to parameter of type 'Uint8Array<ArrayBufferLike>'.
toHex(new ArrayBuffer(8));error TS2345: Argument of type 'ArrayBuffer' is not assignable to parameter of type 'Uint8Array<ArrayBufferLike>'.
  Type 'ArrayBuffer' is missing the following properties from type 'Uint8Array<ArrayBufferLike>': BYTES_PER_ELEMENT, buffer, byteOffset, copyWithin, and 24 more.

Encode strings with new TextEncoder().encode(text) (or Buffer.from(text) in Node.js), and wrap an ArrayBuffer with new Uint8Array(buffer).

Gotchas

• Buffer’s own methods need @param {Buffer}. If the function really needs readUInt32BE or toString("base64"), type the parameter as Buffer and accept that it is Node.js only.
• @types/node 24 names some buffers NonSharedBuffer. It appears in messages for values like readFile’s result; it is a Buffer backed by an ordinary ArrayBuffer.
• subarray shares memory, slice on a Buffer does too. On a Uint8Array, slice copies; on a Buffer, slice and subarray both return a view of the same memory, and both are typed as Buffer. The types do not show the difference, so prefer subarray when you mean a view.