Standard library / Buffer · on the one-page reference

Buffer

Experimental — new, manually tested rather than conformance-suite covered.

A real, distinct byte-array type — not string under another name. Lumen's string is already raw []const u8 (not validated UTF-8), so Buffer could have been just method-name sugar over it; it is a separate type instead so passing raw binary data where text is expected (or vice versa) is a compile-time Buffer/string type mismatch, not a silent runtime bug — the same call Map/Set/ ReadableStream made. Built the same way: a dedicated heap-pointer type, constructed via a Buffer static namespace rather than new. Not yet wired into crypto (which still returns hex/base64 strings), streams (still string-chunked), or JSON — each a real, separate follow-up migration of an already-shipped contract, not bundled into the pass that introduces the type itself (see the roadmap below).

Buffer.from Buffer.alloc .length .toString .at .slice .equals
Buffer.from(s) · Buffer.from(s, encoding)

string → Buffer — the one-argument form takes s's raw bytes verbatim, no decoding. The two-argument form decodes s under "utf8" (same as one-argument, the default) | "hex" | "base64". Deviation from Node: an unrecognized encoding string falls back to raw "utf8" bytes rather than throwing ERR_UNKNOWN_ENCODING — the same "fallback, don't crash" convention every other fallible builtin here uses; malformed hex (odd length, non-hex characters) or malformed base64 similarly fall back to an empty Buffer instead of throwing.

const b1 = Buffer.from("hi");
console.log(b1.toString("hex")); // 6869

const b2 = Buffer.from("6869", "hex");
console.log(b2.toString("utf8")); // hi
Buffer.alloc(n)

int → Buffer — n zeroed bytes. A negative n clamps to 0 rather than erroring.

const b = Buffer.alloc(4);
console.log(b.length);  // 4
console.log(b.at(0));   // 0
Buffer.length

() → int (field syntax, no parens) — the byte count. Follows Map/Set's .size precedent (a method call under a property-syntax surface, since Buffer is heap-pointer-wrapped, not a raw slice at the Lumen type level), not string/array's raw-slice .length.

console.log(Buffer.from("hello").length); // 5
Buffer.toString(encoding)

string → string — "utf8" (raw passthrough) | "hex" | "base64"; an unrecognized encoding falls back to "utf8".

console.log(Buffer.from("hi").toString("base64")); // aGk=
Buffer.at(i)

int → int — the byte value (0-255) at index i; out of range (including negative i) returns 0 rather than crashing. Deviation from Node: there is no buf[i] index syntax — Lumen's [i] index checker is array-type-specific today, so .at(i) is the only way to read a byte.

const b = Buffer.from("A");
console.log(b.at(0));  // 65
console.log(b.at(99)); // 0 -- out of range, not a crash
Buffer.slice(start, end)

(int, int) → Buffer — a new Buffer over [start, end), clamped into range the same way string.slice behaves.

console.log(Buffer.from("hello").slice(1, 3).toString("utf8")); // el
Buffer.equals(other)

Buffer → bool — byte-for-byte comparison.

console.log(Buffer.from("abc").equals(Buffer.from("abc"))); // true
console.log(Buffer.from("abc").equals(Buffer.from("abd"))); // false