Буфер

Исходный код: lib/buffer.js

Buffer объекты используются для представления последовательности байтов фиксированной длины. Многие API Node.js поддерживают Buffer.

Класс Buffer является подклассом класса JavaScript Uint8Array и расширяет его методами, охватывающими дополнительные случаи использования. API Node.js принимают обычные Uint8Array там, где Buffer также поддерживаются.

Класс Buffer находится в глобальной области видимости, что делает маловероятным необходимость использования require('buffer').Buffer.

// Creates a zero-filled Buffer of length 10.
const buf1 = Buffer.alloc(10);

// Creates a Buffer of length 10,
// filled with bytes which all have the value `1`.
const buf2 = Buffer.alloc(10, 1);

// Creates an uninitialized buffer of length 10.
// This is faster than calling Buffer.alloc() but the returned
// Buffer instance might contain old data that needs to be
// overwritten using fill(), write(), or other functions that fill the Buffer's
// contents.
const buf3 = Buffer.allocUnsafe(10);

// Creates a Buffer containing the bytes [1, 2, 3].
const buf4 = Buffer.from([1, 2, 3]);

// Creates a Buffer containing the bytes [1, 1, 1, 1] – the entries
// are all truncated using `(value & 255)` to fit into the range 0–255.
const buf5 = Buffer.from([257, 257.5, -255, '1']);

// Creates a Buffer containing the UTF-8-encoded bytes for the string 'tést':
// [0x74, 0xc3, 0xa9, 0x73, 0x74] (in hexadecimal notation)
// [116, 195, 169, 115, 116] (in decimal notation)
const buf6 = Buffer.from('tést');

// Creates a Buffer containing the Latin-1 bytes [0x74, 0xe9, 0x73, 0x74].
const buf7 = Buffer.from('tést', 'latin1');

Буферы и кодировки символов

При преобразовании между Buffer и строками может быть указана кодировка символов. Если кодировка символов не указана, по умолчанию используется UTF-8.

const buf = Buffer.from('hello world', 'utf8');

console.log(buf.toString('hex'));
// Prints: 68656c6c6f20776f726c64
console.log(buf.toString('base64'));
// Prints: aGVsbG8gd29ybGQ=

console.log(Buffer.from('fhqwhgads', 'utf8'));
// Prints: <Buffer 66 68 71 77 68 67 61 64 73>
console.log(Buffer.from('fhqwhgads', 'utf16le'));
// Prints: <Buffer 66 00 68 00 71 00 77 00 68 00 67 00 61 00 64 00 73 00>

Кодировки символов, в настоящее время поддерживаемые Node.js, следующие:

• 'utf8': Многобайтовая кодировка символов Юникода. Многие веб-страницы и другие форматы документов используют UTF-8. Это кодировка символов по умолчанию. При декодировании Buffer в строку, которая не содержит только допустимые данные UTF-8, для обозначения этих ошибок будет использоваться символ замены Юникода U+FFFD �.

• 'utf16le': Многобайтовая кодировка символов Юникода. В отличие от 'utf8', каждый символ в строке будет закодирован с использованием 2 или 4 байт. Node.js поддерживает только малое эндианное представление кодировки UTF-16.

• 'latin1': Latin-1 обозначает ISO-8859-1. Эта кодировка символов поддерживает только символы Юникода с кодами от U+0000 до U+00FF Каждый символ кодируется одним байтом. Символы, которые не попадают в этот диапазон, усекаются и будут отображаться как символы из этого диапазона.

Преобразование Buffer в строку с использованием одной из вышеперечисленных кодировок называется декодированием, а преобразование строки в Buffer называется кодированием.

Node.js также поддерживает две следующие бинарно-текстовые кодировки. Для бинарно-текстовых кодировок используется обратный порядок именования: Преобразование Buffer в строку обычно называется кодированием, а преобразование строки в Buffer — декодированием.

• 'base64': Кодировка Base64. При создании Buffer из строки эта кодировка также правильно примет «алфавит URL и безопасный для имён файлов», как указано в RFC 4648, раздел 5. Пробельные символы, такие как пробелы, табуляции и новые строки, содержащиеся в строке Base64, игнорируются.

• 'hex': Каждый байт кодируется двумя шестнадцатеричными символами. Может произойти усечение данных при декодировании строк, которые содержат только допустимые шестнадцатеричные символы. См. пример ниже.

Также поддерживаются следующие устаревшие кодировки символов:

• 'ascii': Только для 7-битных данных ASCII. При кодировании строки в Buffer, это эквивалентно использованию 'latin1' При декодировании Buffer в строку с использованием этой кодировки, также будет сброшен старший бит каждого байта перед декодированием как 'latin1' В общем случае нет необходимости использовать эту кодировку, так как 'utf8' (или, если данные всегда являются только ASCII, 'latin1') будут лучшим выбором при кодировании или декодировании только ASCII-текста. Она предоставлена только для обеспечения обратной совместимости.

• 'binary': Псевдоним для 'latin1'. См. бинарные строки для более подробной информации об этой теме. Название этой кодировки может быть очень вводящим в заблуждение, так как все перечисленные здесь кодировки преобразуют строки в двоичные данные. Для преобразования между строками и Buffer обычно 'utf-8' является правильным выбором.

• 'ucs2': Псевдоним 'utf16le'. UCS-2 раньше обозначал вариант UTF-16, который не поддерживал символы с кодовыми точками, превышающими U+FFFF. В Node.js эти кодовые точки всегда поддерживаются.

Buffer.from('1ag', 'hex');
// Prints <Buffer 1a>, data truncated when first non-hexadecimal value
// ('g') encountered.

Buffer.from('1a7g', 'hex');
// Prints <Buffer 1a>, data truncated when data ends in single digit ('7').

Buffer.from('1634', 'hex');
// Prints <Buffer 16 34>, all data represented.

Современные веб-браузеры следуют стандарту кодировок WHATWG, который делает 'latin1' и 'ISO-8859-1' псевдонимами 'win-1252'. Это означает, что при выполнении действия вроде http.get(), если возвращаемый charset один из тех, что перечислены в спецификации WHATWG, возможно, сервер на самом деле вернул данные, закодированные в 'win-1252', а использование кодировки 'latin1' может неправильно декодировать символы.

Буферы и TypedArrays

Buffer экземпляры также являются JavaScript Uint8Array и TypedArray экземплярами. Все методы TypedArray доступны для Buffer. Однако между API Buffer и API TypedArray существуют тонкие несовместимости.

В частности:

• Хотя TypedArray#slice() создает копию части TypedArray, Buffer#slice() создаёт представление над существующим Buffer без копирования. Это поведение может быть неожиданным и существует только для обеспечения обратной совместимости. TypedArray#subarray() может использоваться для достижения поведения Buffer#slice() как для Buffer , так и для других TypedArray.
• buf.toString() несовместим со своим эквивалентом TypedArray.
• Несколько методов, например, buf.indexOf(), поддерживают дополнительные аргументы.

Есть два способа создать новые экземпляры TypedArray из Buffer:

• Передача Buffer в конструктор TypedArray скопирует содержимое Buffer , интерпретируя его как массив целых чисел, а не как последовательность байтов целевого типа.

const buf = Buffer.from([1, 2, 3, 4]);
const uint32array = new Uint32Array(buf);

console.log(uint32array);

// Prints: Uint32Array(4) [ 1, 2, 3, 4 ]

• Передача базового ArrayBuffer объекта Buffer создаст TypedArray, который разделяет память с Buffer.

const buf = Buffer.from('hello', 'utf16le');
const uint16arr = new Uint16Array(
  buf.buffer,
  buf.byteOffset,
  buf.length / Uint16Array.BYTES_PER_ELEMENT);

console.log(uint16array);

// Prints: Uint16Array(5) [ 104, 101, 108, 108, 111 ]

Можно создать новый Buffer , который разделяет выделенную память с экземпляром TypedArray, используя свойство TypedArray объекта .buffer таким же образом. Buffer.from() ведет себя как new Uint8Array() в этом контексте.

const arr = new Uint16Array(2);

arr[0] = 5000;
arr[1] = 4000;

// Copies the contents of `arr`.
const buf1 = Buffer.from(arr);

// Shares memory with `arr`.
const buf2 = Buffer.from(arr.buffer);

console.log(buf1);
// Prints: <Buffer 88 a0>
console.log(buf2);
// Prints: <Buffer 88 13 a0 0f>

arr[1] = 6000;

console.log(buf1);
// Prints: <Buffer 88 a0>
console.log(buf2);
// Prints: <Buffer 88 13 70 17>

При создании Buffer с помощью свойства TypedArray, можно использовать только часть базового ArrayBuffer , передавая параметры byteOffset и length.

const arr = new Uint16Array(20);
const buf = Buffer.from(arr.buffer, 0, 16);

console.log(buf.length);
// Prints: 16

Buffer.from() и TypedArray.from() имеют разные сигнатуры и реализации. В частности, варианты TypedArray принимают второй аргумент, представляющий функцию отображения, которая вызывается для каждого элемента массива с типом данных:

• TypedArray.from(source[, mapFn[, thisArg]])

Метод Buffer.from() , однако, не поддерживает использование функции отображения:

• Buffer.from(array)
• Buffer.from(buffer)
• Buffer.from(arrayBuffer[, byteOffset[, length]])
• Buffer.from(string[, encoding])

Буферы и итерация

Buffer экземпляры можно перебирать с использованием синтаксиса for..of:

const buf = Buffer.from([1, 2, 3]);

for (const b of buf) {
  console.log(b);
}
// Prints:
//   1
//   2
//   3

Кроме того, можно использовать методы buf.values(), buf.keys() и buf.entries() для создания итераторов.

Класс: Buffer

Класс Buffer — это глобальный тип для работы с двоичными данными напрямую. Он может быть создан различными способами.

Статический метод: Buffer.alloc(size[, fill[, encoding]])

• size <целое> Требуемая длина нового Buffer.
• fill <строка> | <Buffer> | <Uint8Array> | <целое> Значение для предварительного заполнения нового Buffer . По умолчанию: 0.
• encoding <строка> Если fill — строка, это её кодировка. По умолчанию: 'utf8'.

Создаёт новый Buffer размером в size байт. Если fill равно undefined, Buffer будет заполнен нулями.

const buf = Buffer.alloc(5);

console.log(buf);
// Prints: <Buffer 00 00 00 00 00>

Если size больше buffer.constants.MAX_LENGTH или меньше 0, выбрасывается ERR_INVALID_OPT_VALUE.

Если fill указано, созданный Buffer будет инициализирован вызовом buf.fill(fill).

const buf = Buffer.alloc(5, 'a');

console.log(buf);
// Prints: <Buffer 61 61 61 61 61>

Если и fill, и encoding указаны, созданный Buffer будет инициализирован вызовом buf.fill(fill, encoding).

const buf = Buffer.alloc(11, 'aGVsbG8gd29ybGQ=', 'base64');

console.log(buf);
// Prints: <Buffer 68 65 6c 6c 6f 20 77 6f 72 6c 64>

Вызов Buffer.alloc() может быть заметно медленнее, чем альтернативный Buffer.allocUnsafe(), но гарантирует, что содержимое нового экземпляра Buffer никогда не будет содержать конфиденциальные данные из предыдущих выделений, включая данные, которые могли не быть выделены для Buffer.

Будет выброшено исключение TypeError, если size не является числом.

Статический метод: Buffer.allocUnsafe(size)

• size <целое> Требуемая длина нового Buffer.

Создаёт новый Buffer размером в size байт. Если size больше buffer.constants.MAX_LENGTH или меньше 0, выбрасывается ERR_INVALID_OPT_VALUE.

Основная память для экземпляров Buffer , созданных таким образом, не инициализируется. Содержимое нового созданного Buffer неизвестно и может содержать конфиденциальные данные. Используйте Buffer.alloc() для инициализации экземпляров Buffer нулями.

const buf = Buffer.allocUnsafe(10);

console.log(buf);
// Prints (contents may vary): <Buffer a0 8b 28 3f 01 00 00 00 50 32>

buf.fill(0);

console.log(buf);
// Prints: <Buffer 00 00 00 00 00 00 00 00 00 00>

Будет выброшено исключение TypeError, если size не является числом.

Модуль Buffer предварительно выделяет внутренний экземпляр Buffer размером Buffer.poolSize, который используется в качестве пула для быстрого выделения новых экземпляров Buffer , созданных с помощью Buffer.allocUnsafe(), Buffer.from(array), Buffer.concat() и устаревшего конструктора new Buffer(size) только тогда, когда size меньше или равно Buffer.poolSize >> 1 (целая часть Buffer.poolSize делённая на два).

Использование этого предварительно выделенного внутреннего пула памяти — ключевое отличие между вызовом Buffer.alloc(size, fill) и Buffer.allocUnsafe(size).fill(fill). В частности, Buffer.alloc(size, fill) никогда не использует внутренний пул Buffer, в то время как Buffer.allocUnsafe(size).fill(fill) использует внутренний пул Buffer если size меньше или равно половине Buffer.poolSize. Разница тонкая, но может быть важна, когда приложение требует дополнительной производительности, предоставляемой Buffer.allocUnsafe().

Статический метод: Buffer.allocUnsafeSlow(size)

• size <целое> Требуемая длина нового Buffer.

Создаёт новый Buffer размером в size байт. Если size больше buffer.constants.MAX_LENGTH или меньше 0, выбрасывается ERR_INVALID_OPT_VALUE. Buffer нулевой длины создаётся, если size равно 0.

Основная память для экземпляров Buffer , созданных таким образом, не инициализируется. Содержимое нового созданного Buffer неизвестно и может содержать конфиденциальные данные. Используйте buf.fill(0) для инициализации таких экземпляров Buffer нулями.

При использовании Buffer.allocUnsafe() для выделения новых экземпляров Buffer, выделения менее 4 КБ берутся из одного предварительно выделенного Buffer. Это позволяет приложениям избежать накладных расходов на сборку мусора при создании многих отдельных выделенных экземпляров Buffer . Этот подход улучшает как производительность, так и использование памяти, устраняя необходимость отслеживания и очистки большого количества отдельных объектов ArrayBuffer .

Однако, в случаях, когда разработчик может нуждаться в удержании небольшого фрагмента памяти из пула на неопределённый срок, может быть уместно создать экземпляр Buffer без пула с помощью Buffer.allocUnsafeSlow() и затем скопировать соответствующие биты.

// Need to keep around a few small chunks of memory.
const store = [];

socket.on('readable', () => {
  let data;
  while (null !== (data = readable.read())) {
    // Allocate for retained data.
    const sb = Buffer.allocUnsafeSlow(10);

    // Copy the data into the new allocation.
    data.copy(sb, 0, 0, 10);

    store.push(sb);
  }
});

Будет выброшено исключение TypeError, если size не является числом.

Статический метод: Buffer.byteLength(string[, encoding])

• string <строка> | <Buffer> | <TypedArray> | <DataView> | <ArrayBuffer> | <SharedArrayBuffer> Значение для расчёта длины.
• encoding <строка> Если string — строка, это её кодировка. По умолчанию: 'utf8'.
• Возвращает: <целое> Количество байт, содержащихся в string.

Возвращает длину строки в байтах, закодированной с использованием encoding. Это не то же самое, что String.prototype.length, которое не учитывает кодировку, используемую для преобразования строки в байты.

Для 'base64' и 'hex', эта функция предполагает корректный ввод. Для строк, содержащих данные, не закодированные в base64/hex (например, пробелы), возвращаемое значение может быть больше длины Buffer , созданного из строки.

const str = '\u00bd + \u00bc = \u00be';

console.log(`${str}: ${str.length} characters, ` +
            `${Buffer.byteLength(str, 'utf8')} bytes`);
// Prints: ½ + ¼ = ¾: 9 characters, 12 bytes

Когда string является Buffer/DataView/TypedArray/ArrayBuffer/ SharedArrayBuffer, возвращается длина в байтах, как сообщает .byteLength.

Статический метод: Buffer.compare(buf1, buf2)

• buf1 <Buffer> | <Uint8Array>
• buf2 <Buffer> | <Uint8Array>
• Возвращает: <целое> Либо -1, либо 0, либо 1, в зависимости от результата сравнения. Подробности см. в buf.compare().

Сравнивает buf1 с buf2, обычно для сортировки массивов экземпляров Buffer. Эквивалентно вызову buf1.compare(buf2).

const buf1 = Buffer.from('1234');
const buf2 = Buffer.from('0123');
const arr = [buf1, buf2];

console.log(arr.sort(Buffer.compare));
// Prints: [ <Buffer 30 31 32 33>, <Buffer 31 32 33 34> ]
// (This result is equal to: [buf2, buf1].)

Статический метод: Buffer.concat(list[, totalLength])

• list <Buffer[]> | <Uint8Array[]> Список экземпляров Buffer или Uint8Array для конкатенации.
• totalLength <целое> Общая длина экземпляров Buffer в list после конкатенации.
• Возвращает: <Buffer>

Возвращает новый Buffer, являющийся результатом конкатенации всех экземпляров Buffer в list.

Если список пуст или totalLength равно 0, то возвращается новый буфер нулевой длины Buffer.

Если totalLength не указан, он вычисляется по сумме длин экземпляров Buffer в list.

Если totalLength указан, он приводится к беззнаковому целому числу. Если общая длина Buffer в list превышает totalLength, результат усекается до totalLength.

// Create a single `Buffer` from a list of three `Buffer` instances.

const buf1 = Buffer.alloc(10);
const buf2 = Buffer.alloc(14);
const buf3 = Buffer.alloc(18);
const totalLength = buf1.length + buf2.length + buf3.length;

console.log(totalLength);
// Prints: 42

const bufA = Buffer.concat([buf1, buf2, buf3], totalLength);

console.log(bufA);
// Prints: <Buffer 00 00 00 00 ...>
console.log(bufA.length);
// Prints: 42

Buffer.concat() также может использовать внутренний пул Buffer, как и Buffer.allocUnsafe().

Статический метод: Buffer.from(array)

• array <массив целых>

Выделяет новый буфер Buffer с использованием массива байтов в диапазоне 0 – 255. Элементы массива вне этого диапазона будут усечены, чтобы поместиться в него.

// Creates a new Buffer containing the UTF-8 bytes of the string 'buffer'.
const buf = Buffer.from([0x62, 0x75, 0x66, 0x66, 0x65, 0x72]);

Будет выброшено исключение TypeError, если array не является массивом Array или другим типом, подходящим для вариантов Buffer.from().

Buffer.from(array) и Buffer.from(string) также могут использовать внутренний пул Buffer, как и Buffer.allocUnsafe().

Статический метод: Buffer.from(arrayBuffer[, byteOffset[, length]])

• arrayBuffer <ArrayBuffer> | <SharedArrayBuffer> ArrayBuffer, SharedArrayBuffer, например, свойство .buffer экземпляра TypedArray.
• byteOffset <целое> Индекс первого байта для экспонирования. По умолчанию: 0.
• length <целое> Количество байтов для экспонирования. По умолчанию: arrayBuffer.byteLength - byteOffset.

Создаёт представление ArrayBuffer без копирования подлежащей памяти. Например, при передаче ссылки на свойство .buffer экземпляра TypedArray, созданный буфер Buffer будет использовать ту же выделенную память, что и TypedArray.

const arr = new Uint16Array(2);

arr[0] = 5000;
arr[1] = 4000;

// Shares memory with `arr`.
const buf = Buffer.from(arr.buffer);

console.log(buf);
// Prints: <Buffer 88 13 a0 0f>

// Changing the original Uint16Array changes the Buffer also.
arr[1] = 6000;

console.log(buf);
// Prints: <Buffer 88 13 70 17>

Дополнительные аргументы byteOffset и length задают диапазон памяти в arrayBuffer, который будет совместно использоваться Buffer.

const ab = new ArrayBuffer(10);
const buf = Buffer.from(ab, 0, 2);

console.log(buf.length);
// Prints: 2

Будет выброшено исключение TypeError, если arrayBuffer не является ArrayBuffer или SharedArrayBuffer, или другим типом, подходящим для вариантов Buffer.from().

Статический метод: Buffer.from(buffer)

• buffer <Buffer> | <Uint8Array> Существующий буфер Buffer или Uint8Array для копирования данных.

Копирует данные переданного буфера buffer в новый экземпляр буфера Buffer.

const buf1 = Buffer.from('buffer');
const buf2 = Buffer.from(buf1);

buf1[0] = 0x61;

console.log(buf1.toString());
// Prints: auffer
console.log(buf2.toString());
// Prints: buffer

Будет выброшено исключение TypeError, если buffer не является буфером Buffer или другим типом, подходящим для вариантов Buffer.from().

Статический метод: Buffer.from(object[, offsetOrEncoding[, length]])

• object <Объект> Объект, поддерживающий Symbol.toPrimitive или valueOf().
• offsetOrEncoding <целое> | <строка> Смещение байта или кодировка.
• length <целое> Длина.

Для объектов, чья функция valueOf() возвращает значение, не строго равное object, возвращает Buffer.from(object.valueOf(), offsetOrEncoding, length).

const buf = Buffer.from(new String('this is a test'));
// Prints: <Buffer 74 68 69 73 20 69 73 20 61 20 74 65 73 74>

Для объектов, поддерживающих Symbol.toPrimitive, возвращает Buffer.from(object[Symbol.toPrimitive]('string'), offsetOrEncoding).

class Foo {
  [Symbol.toPrimitive]() {
    return 'this is a test';
  }
}

const buf = Buffer.from(new Foo(), 'utf8');
// Prints: <Buffer 74 68 69 73 20 69 73 20 61 20 74 65 73 74>

Будет выброшено исключение TypeError, если object не имеет указанных методов или не является другим типом, подходящим для вариантов Buffer.from().

Статический метод: Buffer.from(string[, encoding])

• string <строка> Строка для кодирования.
• encoding <строка> Кодировка string. По умолчанию: 'utf8'.

Создаёт новый буфер Buffer, содержащий string. Параметр encoding определяет кодировку символов, используемую при преобразовании string в байты.

const buf1 = Buffer.from('this is a tést');
const buf2 = Buffer.from('7468697320697320612074c3a97374', 'hex');

console.log(buf1.toString());
// Prints: this is a tést
console.log(buf2.toString());
// Prints: this is a tést
console.log(buf1.toString('latin1'));
// Prints: this is a tést

Будет выброшено исключение TypeError, если string не является строкой или другим типом, подходящим для вариантов Buffer.from().

Статический метод: Buffer.isBuffer(obj)

• obj <Объект>
• Возвращает: <булево>

Возвращает true, если obj является буфером Buffer, в противном случае false.

Статический метод: Buffer.isEncoding(encoding)

• encoding <строка> Название кодировки символов для проверки.
• Возвращает: <булево>

Возвращает true, если encoding является именем поддерживаемой кодировки символов, иначе false.

console.log(Buffer.isEncoding('utf-8'));
// Prints: true

console.log(Buffer.isEncoding('hex'));
// Prints: true

console.log(Buffer.isEncoding('utf/8'));
// Prints: false

console.log(Buffer.isEncoding(''));
// Prints: false

Свойство класса: Buffer.poolSize

• <целое> По умолчанию: 8192

Это размер (в байтах) предварительно выделенных внутренних экземпляров буферов, используемых для пулинга. Это значение может быть изменено.

buf[index]

• index <целое>

Оператор индекса [index] может использоваться для получения и установки октета в позиции index в buf. Значения относятся к отдельным байтам, поэтому допустимый диапазон значений находится между 0x00 и 0xFF (в шестнадцатеричном формате) или 0 и 255 (в десятичном формате).

Этот оператор унаследован от Uint8Array, поэтому его поведение при обращении к несуществующим позициям такое же, как у Uint8Array. Другими словами, buf[index] возвращает undefined, когда index отрицательное или больше или равно buf.length, и buf[index] = value не изменяет буфер, если index отрицательное или >= buf.length.

// Copy an ASCII string into a `Buffer` one byte at a time.
// (This only works for ASCII-only strings. In general, one should use
// `Buffer.from()` to perform this conversion.)

const str = 'Node.js';
const buf = Buffer.allocUnsafe(str.length);

for (let i = 0; i < str.length; i++) {
  buf[i] = str.charCodeAt(i);
}

console.log(buf.toString('utf8'));
// Prints: Node.js

buf.buffer

• <ArrayBuffer> Базовый объект ArrayBuffer, на основе которого создан этот объект Buffer.

Этот объект ArrayBuffer не гарантируется, что будет точно соответствовать исходному объекту Buffer. Подробности см. в примечаниях к buf.byteOffset.

const arrayBuffer = new ArrayBuffer(16);
const buffer = Buffer.from(arrayBuffer);

console.log(buffer.buffer === arrayBuffer);
// Prints: true

buf.byteOffset

• <целое> Смещение byteOffset объекта Buffer относительно базового объекта ArrayBuffer.

При установке byteOffset в Buffer.from(ArrayBuffer, byteOffset, length), или иногда при выделении буфера меньшего размера, чем Buffer.poolSize, буфер не начинается с нулевого смещения в базовом объекте ArrayBuffer.

Это может вызвать проблемы при непосредственном доступе к базовому объекту ArrayBuffer с помощью buf.buffer, так как другие части буфера могут быть не связаны с самим объектом Buffer.

Частая проблема при создании объекта TypedArray, который разделяет память с объектом Buffer, заключается в том, что в этом случае необходимо правильно указать byteOffset.

// Create a buffer smaller than `Buffer.poolSize`.
const nodeBuffer = new Buffer.from([0, 1, 2, 3, 4, 5, 6, 7, 8, 9]);

// When casting the Node.js Buffer to an Int8Array, use the byteOffset
// to refer only to the part of `nodeBuffer.buffer` that contains the memory
// for `nodeBuffer`.
new Int8Array(nodeBuffer.buffer, nodeBuffer.byteOffset, nodeBuffer.length);

buf.compare(target[, targetStart[, targetEnd[, sourceStart[, sourceEnd]]]])

• target <Буфер> | <Uint8Array> Буфер или Uint8Array для сравнения с buf.
• targetStart <целое> Смещение в target для начала сравнения. По умолчанию: 0.
• targetEnd <целое> Смещение в target для окончания сравнения (не включая). По умолчанию: target.length.
• sourceStart <целое> Смещение в buf для начала сравнения. По умолчанию: 0.
• sourceEnd <целое> Смещение в buf для окончания сравнения (не включая). По умолчанию: buf.length.
• Возвращает: <целое>

Сравнивает buf с target и возвращает число, указывающее, предшествует ли buf элементу target, следует ли за ним или они равны в порядке сортировки. Сравнение основано на фактической последовательности байтов в каждом Buffer.

• 0 возвращается, если target равно buf
• 1 возвращается, если target должен предшествовать buf при сортировке.
• -1 возвращается, если target должен следовать за buf при сортировке.

const buf1 = Buffer.from('ABC');
const buf2 = Buffer.from('BCD');
const buf3 = Buffer.from('ABCD');

console.log(buf1.compare(buf1));
// Prints: 0
console.log(buf1.compare(buf2));
// Prints: -1
console.log(buf1.compare(buf3));
// Prints: -1
console.log(buf2.compare(buf1));
// Prints: 1
console.log(buf2.compare(buf3));
// Prints: 1
console.log([buf1, buf2, buf3].sort(Buffer.compare));
// Prints: [ <Buffer 41 42 43>, <Buffer 41 42 43 44>, <Buffer 42 43 44> ]
// (This result is equal to: [buf1, buf3, buf2].)

Необязательные аргументы targetStart, targetEnd, sourceStart, и sourceEnd могут использоваться для ограничения сравнения определёнными диапазонами в target и buf соответственно.

const buf1 = Buffer.from([1, 2, 3, 4, 5, 6, 7, 8, 9]);
const buf2 = Buffer.from([5, 6, 7, 8, 9, 1, 2, 3, 4]);

console.log(buf1.compare(buf2, 5, 9, 0, 4));
// Prints: 0
console.log(buf1.compare(buf2, 0, 6, 4));
// Prints: -1
console.log(buf1.compare(buf2, 5, 6, 5));
// Prints: 1

ERR_OUT_OF_RANGE вызывается, если targetStart < 0, sourceStart < 0, targetEnd > target.byteLength, или sourceEnd > source.byteLength.

buf.copy(target[, targetStart[, sourceStart[, sourceEnd]]])

• target <Буфер> | <Uint8Array> Буфер или Uint8Array для копирования данных.
• targetStart <целое> Смещение в target для начала записи. По умолчанию: 0.
• sourceStart <целое> Смещение в buf для начала копирования. По умолчанию: 0.
• sourceEnd <целое> Смещение в buf для окончания копирования (не включая). По умолчанию: buf.length.
• Возвращает: <целое> Количество скопированных байтов.

Копирует данные из области buf в область в target, даже если область памяти target перекрывается с buf.

TypedArray#set() выполняет ту же операцию и доступна для всех TypedArray, включая Node.js Buffers, хотя принимает другие аргументы функции.

// Create two `Buffer` instances.
const buf1 = Buffer.allocUnsafe(26);
const buf2 = Buffer.allocUnsafe(26).fill('!');

for (let i = 0; i < 26; i++) {
  // 97 is the decimal ASCII value for 'a'.
  buf1[i] = i + 97;
}

// Copy `buf1` bytes 16 through 19 into `buf2` starting at byte 8 of `buf2`.
buf1.copy(buf2, 8, 16, 20);
// This is equivalent to:
// buf2.set(buf1.subarray(16, 20), 8);

console.log(buf2.toString('ascii', 0, 25));
// Prints: !!!!!!!!qrst!!!!!!!!!!!!!

// Create a `Buffer` and copy data from one region to an overlapping region
// within the same `Buffer`.

const buf = Buffer.allocUnsafe(26);

for (let i = 0; i < 26; i++) {
  // 97 is the decimal ASCII value for 'a'.
  buf[i] = i + 97;
}

buf.copy(buf, 0, 4, 10);

console.log(buf.toString());
// Prints: efghijghijklmnopqrstuvwxyz

buf.entries()

• Возвращает: <Итератор>

Создаёт и возвращает итератор пар [index, byte] из содержимого buf.

// Log the entire contents of a `Buffer`.

const buf = Buffer.from('buffer');

for (const pair of buf.entries()) {
  console.log(pair);
}
// Prints:
//   [0, 98]
//   [1, 117]
//   [2, 102]
//   [3, 102]
//   [4, 101]
//   [5, 114]

buf.equals(otherBuffer)

• otherBuffer <Буфер> | <Uint8Array> Буфер или Uint8Array для сравнения с buf.
• Возвращает: <логическое значение>

Возвращает true, если у buf и otherBuffer ровно одинаковые байты, false иначе. Эквивалентно buf.compare(otherBuffer) === 0.

const buf1 = Buffer.from('ABC');
const buf2 = Buffer.from('414243', 'hex');
const buf3 = Buffer.from('ABCD');

console.log(buf1.equals(buf2));
// Prints: true
console.log(buf1.equals(buf3));
// Prints: false

buf.fill(value[, offset[, end]][, encoding])

• value <строка> | <Буфер> | <Uint8Array> | <целое> Значение для заполнения buf.
• offset <целое> Количество байтов для пропуска перед началом заполнения buf. По умолчанию: 0.
• end <целое> Граница заполнения buf (не включая). По умолчанию: buf.length.
• encoding <строка> Кодировка для value если value это строка. По умолчанию: 'utf8'.
• Возвращает: <Буфер> Ссылка на buf.

Заполняет buf указанным значением value. Если offset и end не указаны, то весь buf будет заполнен:

// Fill a `Buffer` with the ASCII character 'h'.

const b = Buffer.allocUnsafe(50).fill('h');

console.log(b.toString());
// Prints: hhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhh

value приводится к значению типа uint32 если это не строка, Buffer, или целое число. Если полученное целое число больше, чем 255 (десятичное), buf будет заполнен значением value & 255.

Если последнее запись операции fill() попадает на многобайтовый символ, то записываются только те байты этого символа, которые помещаются в buf:

// Fill a `Buffer` with character that takes up two bytes in UTF-8.

console.log(Buffer.allocUnsafe(5).fill('\u0222'));
// Prints: <Buffer c8 a2 c8 a2 c8>

Если value содержит недопустимые символы, то оно усекается; если не остаётся действительных данных для заполнения, выбрасывается исключение:

const buf = Buffer.allocUnsafe(5);

console.log(buf.fill('a'));
// Prints: <Buffer 61 61 61 61 61>
console.log(buf.fill('aazz', 'hex'));
// Prints: <Buffer aa aa aa aa aa>
console.log(buf.fill('zz', 'hex'));
// Throws an exception.

buf.includes(value[, byteOffset][, encoding])

• value <строка> | <Буфер> | <Uint8Array> | <целое число> Что искать.
• byteOffset <целое число> С какой позиции начинать поиск в buf. Если отрицательное, то смещение вычисляется с конца buf. По умолчанию: 0.
• encoding <строка> Если value является строкой, это её кодировка. По умолчанию: 'utf8'.
• Возвращает: <логическое значение> true если value был найден в buf, false в противном случае.

Эквивалентно buf.indexOf() !== -1.

const buf = Buffer.from('this is a buffer');

console.log(buf.includes('this'));
// Prints: true
console.log(buf.includes('is'));
// Prints: true
console.log(buf.includes(Buffer.from('a buffer')));
// Prints: true
console.log(buf.includes(97));
// Prints: true (97 is the decimal ASCII value for 'a')
console.log(buf.includes(Buffer.from('a buffer example')));
// Prints: false
console.log(buf.includes(Buffer.from('a buffer example').slice(0, 8)));
// Prints: true
console.log(buf.includes('this', 4));
// Prints: false

buf.indexOf(value[, byteOffset][, encoding])

• value <строка> | <Буфер> | <Uint8Array> | <целое число> Что искать.
• byteOffset <целое число> С какой позиции начинать поиск в buf. Если отрицательное, то смещение вычисляется с конца buf. По умолчанию: 0.
• encoding <строка> Если value является строкой, это кодировка, используемая для определения двоичного представления строки, которое будет искаться в buf. По умолчанию: 'utf8'.
• Возвращает: <целое число> Индекс первого вхождения value в buf, или -1 если buf не содержит value.

Если value является:

• строкой, то value интерпретируется в соответствии с кодировкой символов в encoding.
• буфером или Uint8Array, то value будет использован целиком. Чтобы сравнить частичный Buffer, используйте buf.slice().
• числом, то value будет интерпретировано как значение целого беззнакового 8-битного числа от 0 до 255.

const buf = Buffer.from('this is a buffer');

console.log(buf.indexOf('this'));
// Prints: 0
console.log(buf.indexOf('is'));
// Prints: 2
console.log(buf.indexOf(Buffer.from('a buffer')));
// Prints: 8
console.log(buf.indexOf(97));
// Prints: 8 (97 is the decimal ASCII value for 'a')
console.log(buf.indexOf(Buffer.from('a buffer example')));
// Prints: -1
console.log(buf.indexOf(Buffer.from('a buffer example').slice(0, 8)));
// Prints: 8

const utf16Buffer = Buffer.from('\u039a\u0391\u03a3\u03a3\u0395', 'utf16le');

console.log(utf16Buffer.indexOf('\u03a3', 0, 'utf16le'));
// Prints: 4
console.log(utf16Buffer.indexOf('\u03a3', -4, 'utf16le'));
// Prints: 6

Если value не является строкой, числом или Buffer, этот метод выбросит TypeError. Если value является числом, оно будет приведено к допустимому байтовому значению, целому числу от 0 до 255.

Если byteOffset не является числом, оно будет приведено к числу. Если результат приведения к числу равен NaN или 0, весь буфер будет обработан. Это поведение совпадает с String#indexOf().

const b = Buffer.from('abcdef');

// Passing a value that's a number, but not a valid byte.
// Prints: 2, equivalent to searching for 99 or 'c'.
console.log(b.indexOf(99.9));
console.log(b.indexOf(256 + 99));

// Passing a byteOffset that coerces to NaN or 0.
// Prints: 1, searching the whole buffer.
console.log(b.indexOf('b', undefined));
console.log(b.indexOf('b', {}));
console.log(b.indexOf('b', null));
console.log(b.indexOf('b', []));

Если value является пустой строкой или пустым Buffer, и byteOffset меньше buf.length, будет возвращено byteOffset. Если value пусто, а byteOffset хотя бы buf.length, будет возвращено buf.length.

buf.keys()

• Возвращает: <Итератор>

Создаёт и возвращает итератор ключей (индексов) buf.

const buf = Buffer.from('buffer');

for (const key of buf.keys()) {
  console.log(key);
}
// Prints:
//   0
//   1
//   2
//   3
//   4
//   5

buf.lastIndexOf(value[, byteOffset][, encoding])

• value <строка> | <Буфер> | <Uint8Array> | <целое число> Что искать.
• byteOffset <целое число> С какой позиции начинать поиск в buf. Если отрицательное, то смещение вычисляется с конца buf. По умолчанию: buf.length - 1.
• encoding <строка> Если value является строкой, это кодировка, используемая для определения двоичного представления строки, которое будет искаться в buf. По умолчанию: 'utf8'.
• Возвращает: <целое число> Индекс последнего вхождения value в buf, или -1 если buf не содержит value.

Идентично buf.indexOf(), за исключением того, что ищется последнее вхождение value вместо первого.

const buf = Buffer.from('this buffer is a buffer');

console.log(buf.lastIndexOf('this'));
// Prints: 0
console.log(buf.lastIndexOf('buffer'));
// Prints: 17
console.log(buf.lastIndexOf(Buffer.from('buffer')));
// Prints: 17
console.log(buf.lastIndexOf(97));
// Prints: 15 (97 is the decimal ASCII value for 'a')
console.log(buf.lastIndexOf(Buffer.from('yolo')));
// Prints: -1
console.log(buf.lastIndexOf('buffer', 5));
// Prints: 5
console.log(buf.lastIndexOf('buffer', 4));
// Prints: -1

const utf16Buffer = Buffer.from('\u039a\u0391\u03a3\u03a3\u0395', 'utf16le');

console.log(utf16Buffer.lastIndexOf('\u03a3', undefined, 'utf16le'));
// Prints: 6
console.log(utf16Buffer.lastIndexOf('\u03a3', -5, 'utf16le'));
// Prints: 4

Если value не является строкой, числом или Buffer, этот метод выбросит TypeError. Если value является числом, оно будет приведено к допустимому байтовому значению, целому числу от 0 до 255.

Если byteOffset не является числом, оно будет приведено к числу. Любые аргументы, которые приводятся к NaN, подобные {} или undefined, будут искать по всему буферу. Это поведение соответствует String#lastIndexOf().

const b = Buffer.from('abcdef');

// Passing a value that's a number, but not a valid byte.
// Prints: 2, equivalent to searching for 99 or 'c'.
console.log(b.lastIndexOf(99.9));
console.log(b.lastIndexOf(256 + 99));

// Passing a byteOffset that coerces to NaN.
// Prints: 1, searching the whole buffer.
console.log(b.lastIndexOf('b', undefined));
console.log(b.lastIndexOf('b', {}));

// Passing a byteOffset that coerces to 0.
// Prints: -1, equivalent to passing 0.
console.log(b.lastIndexOf('b', null));
console.log(b.lastIndexOf('b', []));

Если value является пустой строкой или пустым Buffer, будет возвращено byteOffset.

buf.length

• <целое число>

Возвращает количество байт в buf.

// Create a `Buffer` and write a shorter string to it using UTF-8.

const buf = Buffer.alloc(1234);

console.log(buf.length);
// Prints: 1234

buf.write('some string', 0, 'utf8');

console.log(buf.length);
// Prints: 1234

buf.parent

Свойство buf.parent - устаревший псевдоним для buf.buffer.

buf.readBigInt64BE([offset])

• offset <целое число> Количество байт, которые нужно пропустить перед началом чтения. Должно удовлетворять: 0 <= offset <= buf.length - 8. По умолчанию: 0.
• Возвращает: <bigint>

Читает целое 64-битное число со знаком, big-endian из buf в указанном offset.

Целые числа, считанные из Buffer интерпретируются как числа со знаком в дополнении до двух.

buf.readBigInt64LE([offset])

• offset <целое число> Количество байт, которые нужно пропустить перед началом чтения. Должно удовлетворять: 0 <= offset <= buf.length - 8. По умолчанию: 0.
• Возвращает: <bigint>

Читает целое 64-битное число со знаком, little-endian из buf в указанном offset.

Целые числа, считанные из Buffer интерпретируются как числа со знаком в дополнении до двух.

buf.readBigUInt64BE([offset])

• offset <целое> Количество байтов, которые нужно пропустить перед началом чтения. Должно удовлетворять условию: 0 <= offset <= buf.length - 8. По умолчанию: 0.
• Возвращает: <bigint>

Считывает беззнаковое целое 64-битное число в формате big-endian из buf по указанному offset.

const buf = Buffer.from([0x00, 0x00, 0x00, 0x00, 0xff, 0xff, 0xff, 0xff]);

console.log(buf.readBigUInt64BE(0));
// Prints: 4294967295n

buf.readBigUInt64LE([offset])

• offset <целое> Количество байтов, которые нужно пропустить перед началом чтения. Должно удовлетворять условию: 0 <= offset <= buf.length - 8. По умолчанию: 0.
• Возвращает: <bigint>

Считывает беззнаковое целое 64-битное число в формате little-endian из buf по указанному offset.

const buf = Buffer.from([0x00, 0x00, 0x00, 0x00, 0xff, 0xff, 0xff, 0xff]);

console.log(buf.readBigUInt64LE(0));
// Prints: 18446744069414584320n

buf.readDoubleBE([offset])

• offset <целое> Количество байтов, которые нужно пропустить перед началом чтения. Должно удовлетворять условию 0 <= offset <= buf.length - 8. По умолчанию: 0.
• Возвращает: <число>

Считывает 64-битное число с плавающей запятой в формате big-endian из buf по указанному offset.

const buf = Buffer.from([1, 2, 3, 4, 5, 6, 7, 8]);

console.log(buf.readDoubleBE(0));
// Prints: 8.20788039913184e-304

buf.readDoubleLE([offset])

• offset <целое> Количество байтов, которые нужно пропустить перед началом чтения. Должно удовлетворять условию 0 <= offset <= buf.length - 8. По умолчанию: 0.
• Возвращает: <число>

Считывает 64-битное число с плавающей запятой в формате little-endian из buf по указанному offset.

const buf = Buffer.from([1, 2, 3, 4, 5, 6, 7, 8]);

console.log(buf.readDoubleLE(0));
// Prints: 5.447603722011605e-270
console.log(buf.readDoubleLE(1));
// Throws ERR_OUT_OF_RANGE.

buf.readFloatBE([offset])

• offset <целое> Количество байтов, которые нужно пропустить перед началом чтения. Должно удовлетворять условию 0 <= offset <= buf.length - 4. По умолчанию: 0.
• Возвращает: <число>

Считывает 32-битное число с плавающей запятой в формате big-endian из buf по указанному offset.

const buf = Buffer.from([1, 2, 3, 4]);

console.log(buf.readFloatBE(0));
// Prints: 2.387939260590663e-38

buf.readFloatLE([offset])

• offset <целое> Количество байтов, которые нужно пропустить перед началом чтения. Должно удовлетворять условию 0 <= offset <= buf.length - 4. По умолчанию: 0.
• Возвращает: <число>

Считывает 32-битное число с плавающей запятой в формате little-endian из buf по указанному offset.

const buf = Buffer.from([1, 2, 3, 4]);

console.log(buf.readFloatLE(0));
// Prints: 1.539989614439558e-36
console.log(buf.readFloatLE(1));
// Throws ERR_OUT_OF_RANGE.

buf.readInt8([offset])

• offset <целое> Количество байтов, которые нужно пропустить перед началом чтения. Должно удовлетворять условию 0 <= offset <= buf.length - 1. По умолчанию: 0.
• Возвращает: <целое>

Считывает знаковое 8-битное целое число из buf по указанному offset.

Целые числа, считанные из Buffer интерпретируются как значения со знаком в дополнении до двух.

const buf = Buffer.from([-1, 5]);

console.log(buf.readInt8(0));
// Prints: -1
console.log(buf.readInt8(1));
// Prints: 5
console.log(buf.readInt8(2));
// Throws ERR_OUT_OF_RANGE.

buf.readInt16BE([offset])

• offset <целое> Количество байтов, которые нужно пропустить перед началом чтения. Должно удовлетворять условию 0 <= offset <= buf.length - 2. По умолчанию: 0.
• Возвращает: <целое>

Считывает знаковое целое 16-битное число в формате big-endian из buf по указанному offset.

Целые числа, считанные из Buffer интерпретируются как значения со знаком в дополнении до двух.

const buf = Buffer.from([0, 5]);

console.log(buf.readInt16BE(0));
// Prints: 5

buf.readInt16LE([offset])

• offset <целое> Количество байтов, которые нужно пропустить перед началом чтения. Должно удовлетворять условию 0 <= offset <= buf.length - 2. По умолчанию: 0.
• Возвращает: <целое>

Считывает знаковое целое 16-битное число в формате little-endian из buf по указанному offset.

Целые числа, считанные из Buffer интерпретируются как значения со знаком в дополнении до двух.

const buf = Buffer.from([0, 5]);

console.log(buf.readInt16LE(0));
// Prints: 1280
console.log(buf.readInt16LE(1));
// Throws ERR_OUT_OF_RANGE.

buf.readInt32BE([offset])

• offset <целое> Количество байтов, которые нужно пропустить перед началом чтения. Должно удовлетворять условию 0 <= offset <= buf.length - 4. По умолчанию: 0.
• Возвращает: <целое>

Считывает знаковое целое 32-битное число в формате big-endian из buf по указанному offset.

Целые числа, считанные из Buffer интерпретируются как значения со знаком в дополнении до двух.

const buf = Buffer.from([0, 0, 0, 5]);

console.log(buf.readInt32BE(0));
// Prints: 5

buf.readInt32LE([offset])

• offset <целое> Количество байтов, которые нужно пропустить перед началом чтения. Должно удовлетворять условию 0 <= offset <= buf.length - 4. По умолчанию: 0.
• Возвращает: <целое>

Считывает знаковое целое 32-битное число в формате little-endian из buf по указанному offset.

Целые числа, считанные из Buffer интерпретируются как значения со знаком в дополнении до двух.

const buf = Buffer.from([0, 0, 0, 5]);

console.log(buf.readInt32LE(0));
// Prints: 83886080
console.log(buf.readInt32LE(1));
// Throws ERR_OUT_OF_RANGE.

buf.readIntBE(offset, byteLength)

• offset <целое> Количество байтов, которые нужно пропустить перед началом чтения. Должно удовлетворять 0 <= offset <= buf.length - byteLength.
• byteLength <целое> Количество байтов для чтения. Должно удовлетворять 0 < byteLength <= 6.
• Возвращает: <целое>

Читает byteLength байтов из buf по указанному offset и интерпретирует результат как знаковое целое значение в формате big-endian, дополнение до двух, поддерживая точность до 48 бит.

const buf = Buffer.from([0x12, 0x34, 0x56, 0x78, 0x90, 0xab]);

console.log(buf.readIntBE(0, 6).toString(16));
// Prints: 1234567890ab
console.log(buf.readIntBE(1, 6).toString(16));
// Throws ERR_OUT_OF_RANGE.
console.log(buf.readIntBE(1, 0).toString(16));
// Throws ERR_OUT_OF_RANGE.

buf.readIntLE(offset, byteLength)

• offset <целое> Количество байтов, которые нужно пропустить перед началом чтения. Должно удовлетворять 0 <= offset <= buf.length - byteLength.
• byteLength <целое> Количество байтов для чтения. Должно удовлетворять 0 < byteLength <= 6.
• Возвращает: <целое>

Читает byteLength байтов из buf по указанному offset и интерпретирует результат как знаковое целое значение в формате little-endian, дополнение до двух, поддерживая точность до 48 бит.

const buf = Buffer.from([0x12, 0x34, 0x56, 0x78, 0x90, 0xab]);

console.log(buf.readIntLE(0, 6).toString(16));
// Prints: -546f87a9cbee

buf.readUInt8([offset])

• offset <целое> Количество байтов, которые нужно пропустить перед началом чтения. Должно удовлетворять 0 <= offset <= buf.length - 1. По умолчанию: 0.
• Возвращает: <целое>

Читает целое беззнаковое 8-битное число из buf по указанному offset.

const buf = Buffer.from([1, -2]);

console.log(buf.readUInt8(0));
// Prints: 1
console.log(buf.readUInt8(1));
// Prints: 254
console.log(buf.readUInt8(2));
// Throws ERR_OUT_OF_RANGE.

buf.readUInt16BE([offset])

• offset <целое> Количество байтов, которые нужно пропустить перед началом чтения. Должно удовлетворять 0 <= offset <= buf.length - 2. По умолчанию: 0.
• Возвращает: <целое>

Читает беззнаковое целое 16-битное число в формате big-endian из buf по указанному offset.

const buf = Buffer.from([0x12, 0x34, 0x56]);

console.log(buf.readUInt16BE(0).toString(16));
// Prints: 1234
console.log(buf.readUInt16BE(1).toString(16));
// Prints: 3456

buf.readUInt16LE([offset])

• offset <целое> Количество байтов, которые нужно пропустить перед началом чтения. Должно удовлетворять 0 <= offset <= buf.length - 2. По умолчанию: 0.
• Возвращает: <целое>

Читает беззнаковое целое 16-битное число в формате little-endian из buf по указанному offset.

const buf = Buffer.from([0x12, 0x34, 0x56]);

console.log(buf.readUInt16LE(0).toString(16));
// Prints: 3412
console.log(buf.readUInt16LE(1).toString(16));
// Prints: 5634
console.log(buf.readUInt16LE(2).toString(16));
// Throws ERR_OUT_OF_RANGE.

buf.readUInt32BE([offset])

• offset <целое> Количество байтов, которые нужно пропустить перед началом чтения. Должно удовлетворять 0 <= offset <= buf.length - 4. По умолчанию: 0.
• Возвращает: <целое>

Читает беззнаковое целое 32-битное число в формате big-endian из buf по указанному offset.

const buf = Buffer.from([0x12, 0x34, 0x56, 0x78]);

console.log(buf.readUInt32BE(0).toString(16));
// Prints: 12345678

buf.readUInt32LE([offset])

• offset <целое> Количество байтов, которые нужно пропустить перед началом чтения. Должно удовлетворять 0 <= offset <= buf.length - 4. По умолчанию: 0.
• Возвращает: <целое>

Читает беззнаковое целое 32-битное число в формате little-endian из buf по указанному offset.

const buf = Buffer.from([0x12, 0x34, 0x56, 0x78]);

console.log(buf.readUInt32LE(0).toString(16));
// Prints: 78563412
console.log(buf.readUInt32LE(1).toString(16));
// Throws ERR_OUT_OF_RANGE.

buf.readUIntBE(offset, byteLength)

• offset <целое> Количество байтов, которые нужно пропустить перед началом чтения. Должно удовлетворять 0 <= offset <= buf.length - byteLength.
• byteLength <целое> Количество байтов для чтения. Должно удовлетворять 0 < byteLength <= 6.
• Возвращает: <целое>

Читает byteLength байтов из buf по указанному offset и интерпретирует результат как беззнаковое целое число в формате big-endian, поддерживая точность до 48 бит.

const buf = Buffer.from([0x12, 0x34, 0x56, 0x78, 0x90, 0xab]);

console.log(buf.readUIntBE(0, 6).toString(16));
// Prints: 1234567890ab
console.log(buf.readUIntBE(1, 6).toString(16));
// Throws ERR_OUT_OF_RANGE.

buf.readUIntLE(offset, byteLength)

• offset <целое> Количество байтов, которые нужно пропустить перед началом чтения. Должно удовлетворять 0 <= offset <= buf.length - byteLength.
• byteLength <целое> Количество байтов для чтения. Должно удовлетворять 0 < byteLength <= 6.
• Возвращает: <целое>

Читает byteLength байтов из buf по указанному offset и интерпретирует результат как беззнаковое целое число в формате little-endian, поддерживая точность до 48 бит.

const buf = Buffer.from([0x12, 0x34, 0x56, 0x78, 0x90, 0xab]);

console.log(buf.readUIntLE(0, 6).toString(16));
// Prints: ab9078563412

buf.subarray([start[, end]])

• start <целое> С какой позиции начнётся новый Buffer. По умолчанию: 0.
• end <целое> До какой позиции (не включая) будет новый Buffer . По умолчанию: buf.length.
• Возвращает: <Буфер>

Возвращает новый Buffer, который ссылается на ту же память, что и оригинал, но смещён и обрезан индексами start и end.

Указание end больше, чем buf.length, вернёт тот же результат, что и end, равный buf.length.

Этот метод унаследован от TypedArray#subarray().

Изменение нового среза Buffer изменяет память в исходном Buffer, потому что выделенная память двух объектов перекрывается.

// Create a `Buffer` with the ASCII alphabet, take a slice, and modify one byte
// from the original `Buffer`.

const buf1 = Buffer.allocUnsafe(26);

for (let i = 0; i < 26; i++) {
  // 97 is the decimal ASCII value for 'a'.
  buf1[i] = i + 97;
}

const buf2 = buf1.subarray(0, 3);

console.log(buf2.toString('ascii', 0, buf2.length));
// Prints: abc

buf1[0] = 33;

console.log(buf2.toString('ascii', 0, buf2.length));
// Prints: !bc

Указание отрицательных индексов приводит к тому, что срез генерируется относительно конца buf вместо начала.

const buf = Buffer.from('buffer');

console.log(buf.subarray(-6, -1).toString());
// Prints: buffe
// (Equivalent to buf.subarray(0, 5).)

console.log(buf.subarray(-6, -2).toString());
// Prints: buff
// (Equivalent to buf.subarray(0, 4).)

console.log(buf.subarray(-5, -2).toString());
// Prints: uff
// (Equivalent to buf.subarray(1, 4).)

buf.slice([start[, end]])

• start <целое> С какой позиции начнётся новый Buffer. По умолчанию: 0.
• end <целое> Где закончится новый Buffer (не включая). По умолчанию: buf.length.
• Возвращает: <Буфер>

Возвращает новый Buffer, который ссылается на ту же память, что и оригинал, но смещён и обрезан индексами start и end.

Это тот же поведение, что и buf.subarray().

Этот метод несовместим с Uint8Array.prototype.slice(), который является суперклассом Buffer. Для копирования среза используйте Uint8Array.prototype.slice().

const buf = Buffer.from('buffer');

const copiedBuf = Uint8Array.prototype.slice.call(buf);
copiedBuf[0]++;
console.log(copiedBuf.toString());
// Prints: cuffer

console.log(buf.toString());
// Prints: buffer

buf.swap16()

• Возвращает: <Буфер> Ссылка на buf.

Рассматривает buf как массив беззнаковых 16-битных целых чисел и меняет порядок байтов на месте. Бросает ERR_INVALID_BUFFER_SIZE, если buf.length не кратно 2.

const buf1 = Buffer.from([0x1, 0x2, 0x3, 0x4, 0x5, 0x6, 0x7, 0x8]);

console.log(buf1);
// Prints: <Buffer 01 02 03 04 05 06 07 08>

buf1.swap16();

console.log(buf1);
// Prints: <Buffer 02 01 04 03 06 05 08 07>

const buf2 = Buffer.from([0x1, 0x2, 0x3]);

buf2.swap16();
// Throws ERR_INVALID_BUFFER_SIZE.

Одно удобное применение buf.swap16() - это быстрое преобразование на месте между UTF-16 little-endian и UTF-16 big-endian:

const buf = Buffer.from('This is little-endian UTF-16', 'utf16le');
buf.swap16(); // Convert to big-endian UTF-16 text.

buf.swap32()

• Возвращает: <Буфер> Ссылка на buf.

Рассматривает buf как массив беззнаковых 32-битных целых чисел и меняет порядок байтов на месте. Бросает ERR_INVALID_BUFFER_SIZE, если buf.length не кратно 4.

const buf1 = Buffer.from([0x1, 0x2, 0x3, 0x4, 0x5, 0x6, 0x7, 0x8]);

console.log(buf1);
// Prints: <Buffer 01 02 03 04 05 06 07 08>

buf1.swap32();

console.log(buf1);
// Prints: <Buffer 04 03 02 01 08 07 06 05>

const buf2 = Buffer.from([0x1, 0x2, 0x3]);

buf2.swap32();
// Throws ERR_INVALID_BUFFER_SIZE.

buf.swap64()

• Возвращает: <Буфер> Ссылка на buf.

Рассматривает buf как массив 64-битных чисел и меняет порядок байтов на месте. Бросает ERR_INVALID_BUFFER_SIZE, если buf.length не кратно 8.

const buf1 = Buffer.from([0x1, 0x2, 0x3, 0x4, 0x5, 0x6, 0x7, 0x8]);

console.log(buf1);
// Prints: <Buffer 01 02 03 04 05 06 07 08>

buf1.swap64();

console.log(buf1);
// Prints: <Buffer 08 07 06 05 04 03 02 01>

const buf2 = Buffer.from([0x1, 0x2, 0x3]);

buf2.swap64();
// Throws ERR_INVALID_BUFFER_SIZE.

buf.toJSON()

• Возвращает: <Объект>

Возвращает JSON-представление buf. JSON.stringify() неявно вызывает эту функцию при сериализации экземпляра Buffer.

Buffer.from() принимает объекты в формате, возвращаемом этим методом. В частности, Buffer.from(buf.toJSON()) работает так же, как Buffer.from(buf).

const buf = Buffer.from([0x1, 0x2, 0x3, 0x4, 0x5]);
const json = JSON.stringify(buf);

console.log(json);
// Prints: {"type":"Buffer","data":[1,2,3,4,5]}

const copy = JSON.parse(json, (key, value) => {
  return value && value.type === 'Buffer' ?
    Buffer.from(value) :
    value;
});

console.log(copy);
// Prints: <Buffer 01 02 03 04 05>

buf.toString([encoding[, start[, end]]])

• encoding <строка> Кодировка символов для использования. По умолчанию: 'utf8'.
• start <целое> Смещение байта для начала декодирования. По умолчанию: 0.
• end <целое> Смещение байта для остановки декодирования (не включая). По умолчанию: buf.length.
• Возвращает: <строка>

Декодирует buf в строку в соответствии с указанной кодировкой символов в encoding. start и end могут быть переданы для декодирования только подмножества buf.

Если encoding равно 'utf8', и последовательность байтов на входе не является допустимым UTF-8, то каждый недопустимый байт заменяется символом замены U+FFFD.

Максимальная длина экземпляра строки (в единицах кода UTF-16) доступна в buffer.constants.MAX_STRING_LENGTH.

const buf1 = Buffer.allocUnsafe(26);

for (let i = 0; i < 26; i++) {
  // 97 is the decimal ASCII value for 'a'.
  buf1[i] = i + 97;
}

console.log(buf1.toString('utf8'));
// Prints: abcdefghijklmnopqrstuvwxyz
console.log(buf1.toString('utf8', 0, 5));
// Prints: abcde

const buf2 = Buffer.from('tést');

console.log(buf2.toString('hex'));
// Prints: 74c3a97374
console.log(buf2.toString('utf8', 0, 3));
// Prints: té
console.log(buf2.toString(undefined, 0, 3));
// Prints: té

buf.values()

• Возвращает: <Итератор>

Создаёт и возвращает итератор для значений buf (байты). Эта функция вызывается автоматически, когда Buffer используется в операторе for..of.

const buf = Buffer.from('buffer');

for (const value of buf.values()) {
  console.log(value);
}
// Prints:
//   98
//   117
//   102
//   102
//   101
//   114

for (const value of buf) {
  console.log(value);
}
// Prints:
//   98
//   117
//   102
//   102
//   101
//   114

buf.write(string[, offset[, length]][, encoding])

• string <строка> Строка, которую нужно записать в buf.
• offset <целое> Количество байтов, которые нужно пропустить, прежде чем начать запись string. По умолчанию: 0.
• length <целое> Максимальное количество байтов для записи (записанные байты не превысят buf.length - offset). По умолчанию: buf.length - offset.
• encoding <строка> Кодировка символов string. По умолчанию: 'utf8'.
• Возвращает: <целое> Количество записанных байтов.

Записывает string в buf по смещению offset в соответствии с кодировкой символов в encoding. Параметр length - количество байтов для записи. Если buf не содержало достаточно места для всей строки, будет записана только часть string. Однако частично закодированные символы не будут записаны.

const buf = Buffer.alloc(256);

const len = buf.write('\u00bd + \u00bc = \u00be', 0);

console.log(`${len} bytes: ${buf.toString('utf8', 0, len)}`);
// Prints: 12 bytes: ½ + ¼ = ¾

const buffer = Buffer.alloc(10);

const length = buffer.write('abcd', 8);

console.log(`${length} bytes: ${buffer.toString('utf8', 8, 10)}`);
// Prints: 2 bytes : ab

buf.writeBigInt64BE(value[, offset])

• value <bigint> Число, которое нужно записать в buf.
• offset <целое> Количество байтов, которые нужно пропустить, прежде чем начать запись. Должно удовлетворять: 0 <= offset <= buf.length - 8. По умолчанию: 0.
• Возвращает: <целое> offset плюс количество записанных байтов.

Записывает value в buf по указанному offset в формате big-endian.

value интерпретируется и записывается как целое число со знаком в дополнении до двух.

const buf = Buffer.allocUnsafe(8);

buf.writeBigInt64BE(0x0102030405060708n, 0);

console.log(buf);
// Prints: <Buffer 01 02 03 04 05 06 07 08>

buf.writeBigInt64LE(value[, offset])

• value <bigint> Число, которое нужно записать в buf.
• offset <целое> Количество байтов, которые нужно пропустить, прежде чем начать запись. Должно удовлетворять: 0 <= offset <= buf.length - 8. По умолчанию: 0.
• Возвращает: <целое> offset плюс количество записанных байтов.

Записывает value в buf по указанному offset в формате little-endian.

value интерпретируется и записывается как целое число со знаком в дополнении до двух.

const buf = Buffer.allocUnsafe(8);

buf.writeBigInt64LE(0x0102030405060708n, 0);

console.log(buf);
// Prints: <Buffer 08 07 06 05 04 03 02 01>

buf.writeBigUInt64BE(value[, offset])

• value <bigint> Число, которое нужно записать в buf.
• offset <integer> Количество байтов, которые нужно пропустить перед началом записи. Должно удовлетворять условию: 0 <= offset <= buf.length - 8. По умолчанию: 0.
• Возвращает: <integer> offset плюс количество записанных байтов.

Записывает value в buf по указанному offset в формате big-endian.

const buf = Buffer.allocUnsafe(8);

buf.writeBigUInt64BE(0xdecafafecacefaden, 0);

console.log(buf);
// Prints: <Buffer de ca fa fe ca ce fa de>

buf.writeBigUInt64LE(value[, offset])

• value <bigint> Число, которое нужно записать в buf.
• offset <integer> Количество байтов, которые нужно пропустить перед началом записи. Должно удовлетворять условию: 0 <= offset <= buf.length - 8. По умолчанию: 0.
• Возвращает: <integer> offset плюс количество записанных байтов.

Записывает value в buf по указанному offset в формате little-endian

const buf = Buffer.allocUnsafe(8);

buf.writeBigUInt64LE(0xdecafafecacefaden, 0);

console.log(buf);
// Prints: <Buffer de fa ce ca fe fa ca de>

buf.writeDoubleBE(value[, offset])

• value <number> Число, которое нужно записать в buf.
• offset <integer> Количество байтов, которые нужно пропустить перед началом записи. Должно удовлетворять условию 0 <= offset <= buf.length - 8. По умолчанию: 0.
• Возвращает: <integer> offset плюс количество записанных байтов.

Записывает value в buf по указанному offset в формате big-endian. value должно быть числом JavaScript. Поведение не определено, если value — что-то другое, кроме числа JavaScript.

const buf = Buffer.allocUnsafe(8);

buf.writeDoubleBE(123.456, 0);

console.log(buf);
// Prints: <Buffer 40 5e dd 2f 1a 9f be 77>

buf.writeDoubleLE(value[, offset])

• value <number> Число, которое нужно записать в buf.
• offset <integer> Количество байтов, которые нужно пропустить перед началом записи. Должно удовлетворять условию 0 <= offset <= buf.length - 8. По умолчанию: 0.
• Возвращает: <integer> offset плюс количество записанных байтов.

Записывает value в buf по указанному offset в формате little-endian. value должно быть числом JavaScript. Поведение не определено, если value — что-то другое, кроме числа JavaScript.

const buf = Buffer.allocUnsafe(8);

buf.writeDoubleLE(123.456, 0);

console.log(buf);
// Prints: <Buffer 77 be 9f 1a 2f dd 5e 40>

buf.writeFloatBE(value[, offset])

• value <number> Число, которое нужно записать в buf.
• offset <integer> Количество байтов, которые нужно пропустить перед началом записи. Должно удовлетворять условию 0 <= offset <= buf.length - 4. По умолчанию: 0.
• Возвращает: <integer> offset плюс количество записанных байтов.

Записывает value в buf по указанному offset в формате big-endian. Поведение не определено, если value — что-то другое, кроме числа JavaScript.

const buf = Buffer.allocUnsafe(4);

buf.writeFloatBE(0xcafebabe, 0);

console.log(buf);
// Prints: <Buffer 4f 4a fe bb>

buf.writeFloatLE(value[, offset])

• value <number> Число, которое нужно записать в buf.
• offset <integer> Количество байтов, которые нужно пропустить перед началом записи. Должно удовлетворять условию 0 <= offset <= buf.length - 4. По умолчанию: 0.
• Возвращает: <integer> offset плюс количество записанных байтов.

Записывает value в buf по указанному offset в формате little-endian. Поведение не определено, если value — что-то другое, кроме числа JavaScript.

const buf = Buffer.allocUnsafe(4);

buf.writeFloatLE(0xcafebabe, 0);

console.log(buf);
// Prints: <Buffer bb fe 4a 4f>

buf.writeInt8(value[, offset])

• value <integer> Число, которое нужно записать в buf.
• offset <integer> Количество байтов, которые нужно пропустить перед началом записи. Должно удовлетворять условию 0 <= offset <= buf.length - 1. По умолчанию: 0.
• Возвращает: <integer> offset плюс количество записанных байтов.

Записывает value в buf по указанному offset. value должно быть допустимым целым 8-битным числом со знаком. Поведение не определено, если value — что-то другое, кроме целого 8-битного числа со знаком.

value интерпретируется и записывается как целое число со знаком в дополнении до двух.

const buf = Buffer.allocUnsafe(2);

buf.writeInt8(2, 0);
buf.writeInt8(-2, 1);

console.log(buf);
// Prints: <Buffer 02 fe>

buf.writeInt16BE(value[, offset])

• value <integer> Число, которое нужно записать в buf.
• offset <integer> Количество байтов, которые нужно пропустить перед началом записи. Должно удовлетворять условию 0 <= offset <= buf.length - 2. По умолчанию: 0.
• Возвращает: <integer> offset плюс количество записанных байтов.

Записывает value в buf по указанному offset в формате big-endian. value должно быть допустимым целым 16-битным числом со знаком. Поведение не определено, если value — что-то другое, кроме целого 16-битного числа со знаком.

value интерпретируется и записывается как целое число со знаком в дополнении до двух.

const buf = Buffer.allocUnsafe(2);

buf.writeInt16BE(0x0102, 0);

console.log(buf);
// Prints: <Buffer 01 02>

buf.writeInt16LE(value[, offset])

• value <integer> Число, которое нужно записать в buf.
• offset <integer> Количество байтов, которые нужно пропустить перед началом записи. Должно удовлетворять 0 <= offset <= buf.length - 2. По умолчанию: 0.
• Возвращает: <integer> offset плюс количество записанных байтов.

Записывает value в buf в указанной offset позиции в формате little-endian. value должно быть допустимым целым 16-битным числом со знаком. Поведение не определено, когда value является чем-то другим, кроме целого 16-битного числа со знаком.

value интерпретируется и записывается как целое число со знаком в дополнительном коде.

const buf = Buffer.allocUnsafe(2);

buf.writeInt16LE(0x0304, 0);

console.log(buf);
// Prints: <Buffer 04 03>

buf.writeInt32BE(value[, offset])

• value <integer> Число, которое нужно записать в buf.
• offset <integer> Количество байтов, которые нужно пропустить перед началом записи. Должно удовлетворять 0 <= offset <= buf.length - 4. По умолчанию: 0.
• Возвращает: <integer> offset плюс количество записанных байтов.

Записывает value в buf в указанной offset позиции в формате big-endian. value должно быть допустимым целым 32-битным числом со знаком. Поведение не определено, когда value является чем-то другим, кроме целого 32-битного числа со знаком.

value интерпретируется и записывается как целое число со знаком в дополнительном коде.

const buf = Buffer.allocUnsafe(4);

buf.writeInt32BE(0x01020304, 0);

console.log(buf);
// Prints: <Buffer 01 02 03 04>

buf.writeInt32LE(value[, offset])

• value <integer> Число, которое нужно записать в buf.
• offset <integer> Количество байтов, которые нужно пропустить перед началом записи. Должно удовлетворять 0 <= offset <= buf.length - 4. По умолчанию: 0.
• Возвращает: <integer> offset плюс количество записанных байтов.

Записывает value в buf в указанной offset позиции в формате little-endian. value должно быть допустимым целым 32-битным числом со знаком. Поведение не определено, когда value является чем-то другим, кроме целого 32-битного числа со знаком.

value интерпретируется и записывается как целое число со знаком в дополнительном коде.

const buf = Buffer.allocUnsafe(4);

buf.writeInt32LE(0x05060708, 0);

console.log(buf);
// Prints: <Buffer 08 07 06 05>

buf.writeIntBE(value, offset, byteLength)

• value <integer> Число, которое нужно записать в buf.
• offset <integer> Количество байтов, которые нужно пропустить перед началом записи. Должно удовлетворять 0 <= offset <= buf.length - byteLength.
• byteLength <integer> Количество байтов для записи. Должно удовлетворять 0 < byteLength <= 6.
• Возвращает: <integer> offset плюс количество записанных байтов.

Записывает byteLength байта value в buf в указанной offset позиции в формате big-endian. Поддерживает точность до 48 бит. Поведение не определено, если value — не целое число со знаком.

const buf = Buffer.allocUnsafe(6);

buf.writeIntBE(0x1234567890ab, 0, 6);

console.log(buf);
// Prints: <Buffer 12 34 56 78 90 ab>

buf.writeIntLE(value, offset, byteLength)

• value <integer> Число, которое нужно записать в buf.
• offset <integer> Количество байтов, которые нужно пропустить перед началом записи. Должно удовлетворять 0 <= offset <= buf.length - byteLength.
• byteLength <integer> Количество байтов для записи. Должно удовлетворять 0 < byteLength <= 6.
• Возвращает: <integer> offset плюс количество записанных байтов.

Записывает byteLength байтов value в buf в указанной offset позиции в формате little-endian. Поддерживает точность до 48 бит. Поведение не определено, если value — не целое число со знаком.

const buf = Buffer.allocUnsafe(6);

buf.writeIntLE(0x1234567890ab, 0, 6);

console.log(buf);
// Prints: <Buffer ab 90 78 56 34 12>

buf.writeUInt8(value[, offset])

• value <integer> Число, которое нужно записать в buf.
• offset <integer> Количество байтов, которые нужно пропустить перед началом записи. Должно удовлетворять 0 <= offset <= buf.length - 1. По умолчанию: 0.
• Возвращает: <integer> offset плюс количество записанных байтов.

Записывает value в buf в указанной offset. value должно быть допустимым беззнаковым 8-битным целым числом. Поведение не определено, если value — не беззнаковое 8-битное целое число.

const buf = Buffer.allocUnsafe(4);

buf.writeUInt8(0x3, 0);
buf.writeUInt8(0x4, 1);
buf.writeUInt8(0x23, 2);
buf.writeUInt8(0x42, 3);

console.log(buf);
// Prints: <Buffer 03 04 23 42>

buf.writeUInt16BE(value[, offset])

• value <integer> Число, которое нужно записать в buf.
• offset <integer> Количество байтов, которые нужно пропустить перед началом записи. Должно удовлетворять 0 <= offset <= buf.length - 2. По умолчанию: 0.
• Возвращает: <integer> offset плюс количество записанных байтов.

Записывает value в buf в указанной offset позиции в формате big-endian. value должно быть допустимым беззнаковым 16-битным целым числом. Поведение не определено, если value — не беззнаковое 16-битное целое число.

const buf = Buffer.allocUnsafe(4);

buf.writeUInt16BE(0xdead, 0);
buf.writeUInt16BE(0xbeef, 2);

console.log(buf);
// Prints: <Buffer de ad be ef>

buf.writeUInt16LE(value[, offset])

• value <integer> Число, которое нужно записать в buf.
• offset <integer> Количество байтов, которые нужно пропустить перед началом записи. Должно удовлетворять 0 <= offset <= buf.length - 2. По умолчанию: 0.
• Возвращает: <integer> offset плюс количество записанных байтов.

Записывает value в buf по указанному offset в формате little-endian. value должно быть допустимым целым беззнаковым 16-битным числом. Поведение не определено, когда value является чем-либо отличным от целого беззнакового 16-битного числа.

const buf = Buffer.allocUnsafe(4);

buf.writeUInt16LE(0xdead, 0);
buf.writeUInt16LE(0xbeef, 2);

console.log(buf);
// Prints: <Buffer ad de ef be>

buf.writeUInt32BE(value[, offset])

• value <целое> Число, которое нужно записать в buf.
• offset <целое> Число байтов, которые нужно пропустить перед началом записи. Должно удовлетворять 0 <= offset <= buf.length - 4. По умолчанию: 0.
• Возвращает: <целое> offset плюс количество записанных байтов.

Записывает value в buf по указанному offset в формате big-endian. value должно быть допустимым целым беззнаковым 32-битным числом. Поведение не определено, когда value является чем-либо отличным от целого беззнакового 32-битного числа.

const buf = Buffer.allocUnsafe(4);

buf.writeUInt32BE(0xfeedface, 0);

console.log(buf);
// Prints: <Buffer fe ed fa ce>

buf.writeUInt32LE(value[, offset])

• value <целое> Число, которое нужно записать в buf.
• offset <целое> Число байтов, которые нужно пропустить перед началом записи. Должно удовлетворять 0 <= offset <= buf.length - 4. По умолчанию: 0.
• Возвращает: <целое> offset плюс количество записанных байтов.

Записывает value в buf по указанному offset в формате little-endian. value должно быть допустимым целым беззнаковым 32-битным числом. Поведение не определено, когда value является чем-либо отличным от целого беззнакового 32-битного числа.

const buf = Buffer.allocUnsafe(4);

buf.writeUInt32LE(0xfeedface, 0);

console.log(buf);
// Prints: <Buffer ce fa ed fe>

buf.writeUIntBE(value, offset, byteLength)

• value <целое> Число, которое нужно записать в buf.
• offset <целое> Число байтов, которые нужно пропустить перед началом записи. Должно удовлетворять 0 <= offset <= buf.length - byteLength.
• byteLength <целое> Число байтов для записи. Должно удовлетворять 0 < byteLength <= 6.
• Возвращает: <целое> offset плюс количество записанных байтов.

Записывает byteLength байтов value в buf по указанному offset в формате big-endian. Поддерживает точность до 48 бит. Поведение не определено, когда value является чем-либо отличным от целого беззнакового числа.

const buf = Buffer.allocUnsafe(6);

buf.writeUIntBE(0x1234567890ab, 0, 6);

console.log(buf);
// Prints: <Buffer 12 34 56 78 90 ab>

buf.writeUIntLE(value, offset, byteLength)

• value <целое> Число, которое нужно записать в buf.
• offset <целое> Число байтов, которые нужно пропустить перед началом записи. Должно удовлетворять 0 <= offset <= buf.length - byteLength.
• byteLength <целое> Число байтов для записи. Должно удовлетворять 0 < byteLength <= 6.
• Возвращает: <целое> offset плюс количество записанных байтов.

Записывает byteLength байтов value в buf по указанному offset в формате little-endian. Поддерживает точность до 48 бит. Поведение не определено, когда value является чем-либо отличным от целого беззнакового числа.

const buf = Buffer.allocUnsafe(6);

buf.writeUIntLE(0x1234567890ab, 0, 6);

console.log(buf);
// Prints: <Buffer ab 90 78 56 34 12>

new Buffer(array)

• array <массив целых> Массив байтов для копирования.

См. Buffer.from(array).

new Buffer(arrayBuffer[, byteOffset[, length]])

• arrayBuffer <ArrayBuffer> | <SharedArrayBuffer> ArrayBuffer, SharedArrayBuffer или свойство .buffer TypedArray.
• byteOffset <целое> Индекс первого байта для экспонирования. По умолчанию: 0.
• length <целое> Количество байтов для экспонирования. По умолчанию: arrayBuffer.byteLength - byteOffset.

См. Buffer.from(arrayBuffer[, byteOffset[, length]]).

new Buffer(buffer)

• buffer <Buffer> | <Uint8Array> Существующий Buffer или Uint8Array, из которого нужно скопировать данные.

См. Buffer.from(buffer).

new Buffer(size)

• size <целое> Желаемая длина нового Buffer.

См. Buffer.alloc() и Buffer.allocUnsafe(). Этот вариант конструктора эквивалентен Buffer.alloc().

new Buffer(string[, encoding])

• string <строка> Строка для кодирования.
• encoding <строка> Кодировка string. По умолчанию: 'utf8'.

См. Buffer.from(string[, encoding]).

buffer модуля API

Хотя объект Buffer доступен как глобальный, есть дополнительные API, относящиеся к Buffer и доступные только через модуль buffer с использованием require('buffer').

buffer.INSPECT_MAX_BYTES

• <целое> По умолчанию: 50

Возвращает максимальное количество байтов, которое будет возвращено при вызове buf.inspect(). Это может быть переопределено пользовательскими модулями. См. util.inspect() для получения более подробной информации о поведении buf.inspect().

buffer.kMaxLength

• <целое> Максимальный размер, разрешённый для одного экземпляра Buffer.

Псевдоним для buffer.constants.MAX_LENGTH.

buffer.transcode(source, fromEnc, toEnc)

• source <Buffer> | <Uint8Array> Экземпляр Buffer или Uint8Array.
• fromEnc <строка> Текущая кодировка.
• toEnc <строка> Кодировка назначения.
• Возвращает: <Buffer>

Перекодирует заданный экземпляр Buffer или Uint8Array из одной кодировки символов в другую. Возвращает новый экземпляр Buffer.

Выбрасывает исключение, если fromEnc или toEnc указывают недопустимые кодировки символов или если преобразование из fromEnc в toEnc запрещено.

Кодировки, поддерживаемые buffer.transcode(): 'ascii', 'utf8', 'utf16le', 'ucs2', 'latin1', и 'binary'.

Процесс перекодирования будет использовать символы подстановки, если заданная последовательность байтов не может быть адекватно представлена в кодировке назначения. Например:

const buffer = require('buffer');

const newBuf = buffer.transcode(Buffer.from('€'), 'utf8', 'ascii');
console.log(newBuf.toString('ascii'));
// Prints: '?'

Так как символ евро (€) не может быть представлен в US-ASCII, он заменяется на ? в перекодированном Buffer.

Класс: SlowBuffer

См. Buffer.allocUnsafeSlow(). Этот класс никогда не был классом в том смысле, что конструктор всегда возвращал экземпляр Buffer вместо экземпляра SlowBuffer.

new SlowBuffer(size)

• size <целое> Желаемая длина нового SlowBuffer.

См. Buffer.allocUnsafeSlow().

Постоянные значения буфера

buffer.constants.MAX_LENGTH

• <целое> Максимальный размер, разрешённый для одного экземпляра Buffer.

На 32-битных архитектурах это значение в настоящее время составляет 2³⁰ - 1 (~1 ГБ). На 64-битных архитектурах это значение в настоящее время составляет 2³¹ - 1 (~2 ГБ).

Это значение также доступно как buffer.kMaxLength.

buffer.constants.MAX_STRING_LENGTH

• <целое> Максимальная длина, разрешённая для одного экземпляра string.

Представляет самую большую length, которую может иметь примитив string, отсчитывая в единицах кодов UTF-16.

Это значение может зависеть от используемого движка JS.

Buffer.from(), Buffer.alloc(), и Buffer.allocUnsafe()

В версиях Node.js до 6.0.0 экземпляры Buffer создавались с помощью конструктора Buffer, который распределяет возвращаемый Buffer по-разному в зависимости от переданных аргументов:

• Передача числа в качестве первого аргумента в Buffer() (например, new Buffer(10)) выделяет новый объект Buffer указанного размера. До Node.js 8.0.0 память, выделенная для таких экземпляров Buffer, не инициализируется и может содержать конфиденциальные данные. Такие экземпляры Buffer обязательно должны быть инициализированы впоследствии с помощью buf.fill(0) или записи во весь Buffer до чтения данных из Buffer . Хотя это поведение намеренное для повышения производительности, опыт разработки показал, что необходима более ясная разница между быстрым, но неинициализированным Buffer и медленным, но безопасным Buffer. С Node.js 8.0.0, Buffer(num) и new Buffer(num) возвращают Buffer с инициализированной памятью.
• Передача строки, массива или Buffer в качестве первого аргумента копирует данные переданного объекта в Buffer.
• Передача ArrayBuffer или SharedArrayBuffer возвращает Buffer , который разделяет выделенную память с заданным буфером массива.

Поскольку поведение new Buffer() различается в зависимости от типа первого аргумента, в приложениях могут быть непреднамеренно введены проблемы безопасности и надежности, если проверка аргументов или инициализация Buffer не выполняются.

Например, если злоумышленник может заставить приложение получить число вместо ожидаемой строки, приложение может вызвать new Buffer(100) вместо new Buffer("100"), что приведет к выделению буфера размером 100 байт вместо выделения буфера размером 3 байта с содержимым "100". Это часто возможно при использовании вызовов JSON-API. Поскольку JSON различает числовые и строковые типы, он позволяет вводить числа вместо строк, которые ожидаются в приложении, недостаточно тщательно проверяющем входные данные. До версии Node.js 8.0.0 выделенный буфер размером 100 байт мог содержать произвольные данные из памяти, что позволяло раскрыть конфиденциальные данные в памяти удалённому злоумышленнику. Начиная с Node.js 8.0.0, раскрытие памяти невозможно, так как данные обнуляются. Однако возможны и другие атаки, такие как выделение очень больших буферов сервером, что приводит к ухудшению производительности или аварийному завершению из-за исчерпания памяти.

Для повышения надёжности и снижения вероятности ошибок при создании экземпляров Buffer, различные формы конструктора new Buffer() были устаревшими и заменены отдельными методами Buffer.from(), Buffer.alloc() и Buffer.allocUnsafe().

Разработчики должны мигрировать все существующие использования конструкторов new Buffer() на одну из этих новых API.

• Buffer.from(array) возвращает новый экземпляр Buffer, содержащий копию предоставленных октетов.
• Buffer.from(arrayBuffer[, byteOffset[, length]]) возвращает новый экземпляр Buffer, делящий ту же выделенную память, что и заданный ArrayBuffer.
• Buffer.from(buffer) возвращает новый экземпляр Buffer, содержащий копию содержимого заданного экземпляра Buffer.
• Buffer.from(string[, encoding]) возвращает новый экземпляр Buffer, содержащий копию предоставленной строки.
• Buffer.alloc(size[, fill[, encoding]]) возвращает новый инициализированный экземпляр Buffer заданного размера. Этот метод медленнее, чем Buffer.allocUnsafe(size), но гарантирует, что вновь созданные экземпляры Buffer никогда не содержат старые, потенциально конфиденциальные данные. Будет выброшено исключение TypeError, если size не является числом.
• Buffer.allocUnsafe(size) и Buffer.allocUnsafeSlow(size) каждый возвращают новый неинициализированный экземпляр Buffer заданного размера size. Поскольку экземпляр Buffer неинициализирован, выделенный участок памяти может содержать старые, потенциально конфиденциальные данные.

Экземпляры Buffer, возвращаемые Buffer.allocUnsafe() и Buffer.from(array), могут быть выделены из общего внутреннего пула памяти, если size меньше или равно половине Buffer.poolSize. Экземпляры, возвращаемые Buffer.allocUnsafeSlow(), никогда не используют общий внутренний пул памяти.

Опция командной строки --zero-fill-buffers

Node.js можно запустить с помощью опции командной строки --zero-fill-buffers, чтобы все вновь выделенные экземпляры Buffer по умолчанию обнулялись при создании. Без этой опции буферы, созданные с помощью Buffer.allocUnsafe(), Buffer.allocUnsafeSlow() и new SlowBuffer(size), не обнуляются. Использование этого флага может оказать заметное негативное влияние на производительность. Используйте опцию --zero-fill-buffers только при необходимости, чтобы гарантировать, что вновь выделенные экземпляры Buffer не содержат старых, потенциально конфиденциальных данных.

$ node --zero-fill-buffers
> Buffer.allocUnsafe(5);
<Buffer 00 00 00 00 00>

Что делает Buffer.allocUnsafe() и Buffer.allocUnsafeSlow() "неопасными"?

При вызове Buffer.allocUnsafe() и Buffer.allocUnsafeSlow(), выделенный участок памяти не инициализирован (не обнулен). Хотя это обеспечивает высокую скорость выделения памяти, выделенный участок памяти может содержать старые, потенциально конфиденциальные данные. Использование экземпляра Buffer, созданного с помощью Buffer.allocUnsafe(), без полной перезаписи памяти, может привести к утечке этих старых данных при чтении из памяти Buffer.

Хотя использование Buffer.allocUnsafe() имеет явные преимущества в плане производительности, необходимо проявлять особую осторожность, чтобы не ввести уязвимости в приложение.