`Buffer` / `node:buffer`

Elide implements the [Node.js Buffer][nodejs-buffer] type as a fixed-length sequence of bytes backed by a host NIO byte array. The Buffer constructor is exposed both as a global and as the Buffer named export of the node:buffer module; the two are the same identity (===).

[nodejs-buffer]: https://nodejs.org/api/buffer.html

Construction

Buffer is not directly constructible — new Buffer(...) raises TypeError. Use the static factories:

declare class Buffer {
  static alloc(size: number, fill?: number | string | Buffer, encoding?: string): Buffer;
  static allocUnsafe(size: number): Buffer;
  static allocUnsafeSlow(size: number): Buffer;
  static from(input: string | ArrayBuffer | Uint8Array | Buffer, encodingOrOffset?: string | number, length?: number): Buffer;

  static isBuffer(value: unknown): boolean;
  static isEncoding(name: string): boolean;
  static byteLength(input: string | ArrayBuffer | Uint8Array | Buffer, encoding?: string): number;
  static concat(list: Buffer[], totalLength?: number): Buffer;
  static compare(a: Buffer, b: Buffer): -1 | 0 | 1;
}

Instance surface

interface Buffer {
  readonly length: number;
  readonly byteOffset: number;
  readonly buffer: Uint8Array; // a fresh byte snapshot — see "Notes" below

  // NOTE: the instance `compare` is not implemented at runtime — use the static `Buffer.compare(a, b)`.
  compare(other: Buffer, ts?: number, te?: number, ss?: number, se?: number): -1 | 0 | 1;
  copy(target: Buffer, targetStart?: number, sourceStart?: number, sourceEnd?: number): number;
  equals(other: Buffer): boolean;
  fill(value: number | string | Buffer, offset?: number, end?: number, encoding?: string): Buffer;
  includes(value: number | string | Buffer, byteOffset?: number, encoding?: string): boolean;
  indexOf(value: number | string | Buffer, byteOffset?: number, encoding?: string): number;
  lastIndexOf(value: number | string | Buffer, byteOffset?: number, encoding?: string): number;
  slice(start?: number, end?: number): Buffer;       // alias for subarray
  subarray(start?: number, end?: number): Buffer;    // shares the underlying memory
  write(string: string, offset?: number, length?: number, encoding?: string): number;
  toString(encoding?: string, start?: number, end?: number): string;
  toJSON(): { type: "Buffer"; data: number[] };

  // Read / write at every fixed-width Int8/16/32 + UInt8/16/32 + Float / Double in BE / LE.
  readUInt8(offset?: number): number;
  readUInt16BE(offset?: number): number; readUInt16LE(offset?: number): number;
  readUInt32BE(offset?: number): number; readUInt32LE(offset?: number): number;
  readInt8(offset?: number): number;
  readInt16BE(offset?: number): number;  readInt16LE(offset?: number): number;
  readInt32BE(offset?: number): number;  readInt32LE(offset?: number): number;
  readFloatBE(offset?: number): number;  readFloatLE(offset?: number): number;
  readDoubleBE(offset?: number): number; readDoubleLE(offset?: number): number;

  writeUInt8(value: number, offset?: number): number;
  writeUInt16BE(value: number, offset?: number): number; writeUInt16LE(value: number, offset?: number): number;
  writeUInt32BE(value: number, offset?: number): number; writeUInt32LE(value: number, offset?: number): number;
  writeInt8(value: number, offset?: number): number;
  writeInt16BE(value: number, offset?: number): number; writeInt16LE(value: number, offset?: number): number;
  writeInt32BE(value: number, offset?: number): number; writeInt32LE(value: number, offset?: number): number;
  writeFloatBE(value: number, offset?: number): number; writeFloatLE(value: number, offset?: number): number;
  writeDoubleBE(value: number, offset?: number): number; writeDoubleLE(value: number, offset?: number): number;

  swap16(): Buffer;   // pairwise byte swap; throws RangeError if length % 2 !== 0
  swap32(): Buffer;   // 4-byte block reverse; throws RangeError if length % 4 !== 0
  swap64(): Buffer;   // 8-byte block reverse; throws RangeError if length % 8 !== 0
}

Encodings

Encoding	Aliases
`utf8`	`utf-8`
`utf16le`	`utf-16le`, `ucs2`, `ucs-2`
`utf16be`	`utf-16be`
`latin1`	`binary`
`ascii`	(high bit silently masked, matching Node)
`base64`	(whitespace-tolerant)
`base64url`	(URL-safe alphabet, padding optional)
`hex`	(case-insensitive; truncates at first invalid digit pair, matching Node)

Buffer.isEncoding(name) reports true for any alias above.

Module exports — `node:buffer`

Export	Type	Notes
`Buffer`	constructor	Same identity as `globalThis.Buffer`.
`atob(s)`	`(string) => string`	Latin-1 mapping over base64-decoded bytes.
`btoa(s)`	`(string) => string`	Base64 over Latin-1; throws `TypeError` on chars > U+00FF.
`isAscii(buf)`	`(buf) => boolean`	Whether every byte's high bit is clear.
`isUtf8(buf)`	`(buf) => boolean`	Validates UTF-8 grammar (overlong / surrogate / out-of-range rejected).
`kMaxLength`	`number`	Largest buffer size representable as a 32-bit JS integer (`2³¹−1`).
`kStringMaxLength`	`number`	Largest string length the runtime will allocate.
`constants`	`object`	Empty placeholder for source compatibility.

Memory semantics

Buffer.alloc(n) and Buffer.allocUnsafe(n) both produce a zero-filled byte array; the "unsafe" naming exists for source compatibility with Node, but the implementation does not expose uninitialised memory.
subarray(start, end) and slice(start, end) (the same operation) return a new Buffer view over the same backing storage. Mutations through one view are visible through the parent and any sibling views, mirroring Node's documented behaviour.
Buffer.from(otherBuffer) makes an independent copy; mutations do not propagate.

Notes on the implementation

Buffer instanceof Uint8Array returns false in this version. The host backing is a NIO byte array, not a JSArrayBufferView, so the spec's "Buffer extends Uint8Array" inheritance is not yet wired through the prototype chain. Buffer.isBuffer(value) is the recommended way to type-check.
Indexed access (buf[0] / buf[0] = 1) is not implemented — use buf.readUInt8(i) / buf.writeUInt8(value, i).
The buffer getter (buf.buffer) currently returns a fresh byte[] snapshot rather than the underlying ArrayBuffer. Cross-language callers that need shared-memory ArrayBuffer semantics should round-trip through subarray + toString / write.
64-bit integer (readBigInt64/writeBigInt64) operations are not in the WebIDL surface and are not implemented; future expansion is planned alongside BigInt interop work.
The variable-length integer methods (readUIntLE/readUIntBE/readIntLE/readIntBE and their writeUInt/writeInt counterparts) are implemented on the prototype, though they are not listed in the interface above.

Buffer / node:buffer