Перейти к содержанию

Буфер

latest

Стабильность: 2 – Стабильная

Совместимость с экосистемой npm имеет высокий приоритет.

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

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

Хотя класс Buffer доступен в глобальной области видимости, рекомендуется явно ссылаться на него через import или require.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
import { Buffer } from 'node: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');

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
const { Buffer } = require('node: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.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
import { Buffer } from 'node:buffer';

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>

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
const { Buffer } = require('node:buffer');

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 принимают любые варианты регистра в строках кодировок, которые им передают. Например, UTF-8 можно указать как 'utf8', 'UTF8' или 'uTf8'.

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

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

  • 'utf16le' (псевдоним: 'utf-16le'): многобайтовое кодирование символов Unicode. В отличие от 'utf8', каждый символ строки кодируется 2 или 4 байтами. Node.js поддерживает только младший порядок байтов(endianness) для UTF-16.

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

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

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

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

  • 'base64url': кодирование base64url по RFC 4648, Section 5. При создании Buffer из строки эта кодировка также принимает обычные строки в base64. При кодировании Buffer в строку заполнение (padding) опускается.

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

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

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

  • 'binary': псевдоним 'latin1'. Название может вводить в заблуждение: все перечисленные здесь кодировки преобразуют строки и двоичные данные. Для строк и Buffer чаще всего подходит 'utf8'.

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

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
import { Buffer } from 'node:buffer';

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

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

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

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
const { Buffer } = require('node:buffer');

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

Buffer.from('1a7', '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 Encoding Standard, где 'latin1' и 'ISO-8859-1' сопоставляются с 'win-1252'. Поэтому при вызове, например, http.get(), если в ответе указана одна из кодировок из спецификации WHATWG, сервер мог вернуть данные в 'win-1252', и декодирование с 'latin1' может дать неверные символы.

Буферы и TypedArray

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

В частности:

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

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

  • Передача Buffer в конструктор TypedArray копирует содержимое Buffer, интерпретируемое как массив целых чисел, а не как последовательность байтов целевого типа.
1
2
3
4
5
6
7
8
import { Buffer } from 'node:buffer';

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

console.log(uint32array);

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

1
2
3
4
5
6
7
8
const { Buffer } = require('node:buffer');

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

console.log(uint32array);

// Prints: Uint32Array(4) [ 1, 2, 3, 4 ]
  • Передача лежащего в основе Buffer ArrayBuffer создаст TypedArray, разделяющий с Buffer память.
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
import { Buffer } from 'node:buffer';

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

console.log(uint16array);

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

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
const { Buffer } = require('node:buffer');

const buf = Buffer.from('hello', 'utf16le');
const uint16array = 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, можно создать через свойство .buffer объекта TypedArray так же, как описано выше. Buffer.from() в этом случае ведёт себя как new Uint8Array().

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
import { Buffer } from 'node:buffer';

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>

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
const { Buffer } = require('node:buffer');

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 из .buffer у TypedArray можно использовать только часть лежащего в основе ArrayBuffer, передав параметры byteOffset и length.

1
2
3
4
5
6
7
import { Buffer } from 'node:buffer';

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

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

1
2
3
4
5
6
7
const { Buffer } = require('node:buffer');

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

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

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

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

Методы Buffer можно вызывать для экземпляров Uint8Array

Все методы прототипа Buffer можно вызывать с экземпляром Uint8Array.

1
2
3
4
5
6
7
8
const { toString, write } = Buffer.prototype;

const uint8array = new Uint8Array(5);

write.call(uint8array, 'hello', 0, 5, 'utf8'); // 5
// <Uint8Array 68 65 6c 6c 6f>

toString.call(uint8array, 'utf8'); // 'hello'

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

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

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
import { Buffer } from 'node:buffer';

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

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

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
const { Buffer } = require('node:buffer');

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().

Класс: Blob

Blob инкапсулирует неизменяемые сырые данные, которые безопасно разделять между несколькими рабочими потоками.

new buffer.Blob([sources[, options]])

  • sources <string[]> | <ArrayBuffer[]> | <TypedArray[]> | <DataView[]> | <Blob[]> Массив строк, ArrayBuffer, TypedArray, DataView или Blob, либо любая смесь таких объектов, которые будут помещены в Blob.
  • options <Object>
    • endings <string> Одно из значений 'transparent' или 'native'. При 'native' окончания строк в строковых частях приводятся к родному для платформы виду, как в require('node:os').EOL.
    • type <string> MIME-тип содержимого блоба. Поле type задаёт предполагаемый тип данных; формат строки не проверяется.

Создаёт новый объект Blob, объединяющий указанные источники.

Источники ArrayBuffer, TypedArray, DataView и Buffer копируются в Blob, поэтому после создания Blob их можно безопасно изменять.

Строковые источники кодируются в UTF-8 и копируются в блоб. Непарные суррогатные пары в каждой строковой части заменяются символом замены Unicode U+FFFD.

blob.arrayBuffer()

Возвращает промис, который выполняется с ArrayBuffer, содержащим копию данных Blob.

blob.bytes()

Метод blob.bytes() возвращает байты объекта Blob в виде Promise<Uint8Array>.

1
2
3
4
const blob = new Blob(['hello']);
blob.bytes().then((bytes) => {
    console.log(bytes); // Outputs: Uint8Array(5) [ 104, 101, 108, 108, 111 ]
});

blob.size

Общий размер Blob в байтах.

blob.slice([start[, end[, type]]])

  • start <number> Начальный индекс.
  • end <number> Конечный индекс.
  • type <string> MIME-тип для нового Blob

Создаёт и возвращает новый Blob с подмножеством данных этого Blob. Исходный Blob не изменяется.

blob.stream()

Возвращает новый ReadableStream для чтения содержимого Blob.

blob.text()

Возвращает промис, который выполняется со строкой — содержимым Blob, декодированным как UTF-8.

blob.type

MIME-тип содержимого Blob.

Объекты Blob и MessageChannel

После создания Blob его можно передать через MessagePort в несколько мест без переноса или немедленного копирования данных. Данные внутри Blob копируются только при вызове arrayBuffer() или text().

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
import { Blob } from 'node:buffer';
import { setTimeout as delay } from 'node:timers/promises';

const blob = new Blob(['hello there']);

const mc1 = new MessageChannel();
const mc2 = new MessageChannel();

mc1.port1.onmessage = async ({ data }) => {
  console.log(await data.arrayBuffer());
  mc1.port1.close();
};

mc2.port1.onmessage = async ({ data }) => {
  await delay(1000);
  console.log(await data.arrayBuffer());
  mc2.port1.close();
};

mc1.port2.postMessage(blob);
mc2.port2.postMessage(blob);

// The Blob is still usable after posting.
blob.text().then(console.log);

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
const { Blob } = require('node:buffer');
const { setTimeout: delay } = require('node:timers/promises');

const blob = new Blob(['hello there']);

const mc1 = new MessageChannel();
const mc2 = new MessageChannel();

mc1.port1.onmessage = async ({ data }) => {
  console.log(await data.arrayBuffer());
  mc1.port1.close();
};

mc2.port1.onmessage = async ({ data }) => {
  await delay(1000);
  console.log(await data.arrayBuffer());
  mc2.port1.close();
};

mc1.port2.postMessage(blob);
mc2.port2.postMessage(blob);

// The Blob is still usable after posting.
blob.text().then(console.log);

Класс: Buffer

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

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

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

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

1
2
3
4
5
6
import { Buffer } from 'node:buffer';

const buf = Buffer.alloc(5);

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

1
2
3
4
5
6
const { Buffer } = require('node:buffer');

const buf = Buffer.alloc(5);

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

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

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

1
2
3
4
5
6
import { Buffer } from 'node:buffer';

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

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

1
2
3
4
5
6
const { Buffer } = require('node:buffer');

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

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

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

1
2
3
4
5
6
import { Buffer } from 'node:buffer';

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

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

1
2
3
4
5
6
const { Buffer } = require('node:buffer');

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.

Если size не является числом, выбрасывается TypeError.

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

  • size <integer> Желаемая длина нового Buffer.
  • Возвращает: <Buffer>

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

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

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
import { Buffer } from 'node: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>

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
const { Buffer } = require('node: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>

Если size не является числом, выбрасывается TypeError.

Модуль Buffer заранее выделяет внутренний экземпляр размера Buffer.poolSize — пул для быстрого выделения новых Buffer, создаваемых через Buffer.allocUnsafe(), Buffer.from(array), Buffer.from(string) и Buffer.concat(), только если 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) использует его, если size не больше половины Buffer.poolSize. Разница тонкая, но важна, когда нужна дополнительная производительность Buffer.allocUnsafe().

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

  • size <integer> Желаемая длина нового Buffer.
  • Возвращает: <Buffer>

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

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

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

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

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
import { Buffer } from 'node:buffer';

// 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);
  }
});

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
const { Buffer } = require('node:buffer');

// 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);
  }
});

Если size не является числом, выбрасывается TypeError.

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

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

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

1
2
3
4
5
6
7
import { Buffer } from 'node:buffer';

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

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

1
2
3
4
5
6
7
const { Buffer } = require('node: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 с buf2, обычно для сортировки массивов экземпляров Buffer. Эквивалентно вызову buf1.compare(buf2).

1
2
3
4
5
6
7
8
9
import { Buffer } from 'node:buffer';

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].)

1
2
3
4
5
6
7
8
9
const { Buffer } = require('node:buffer');

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 <integer> Суммарная длина экземпляров Buffer в list после конкатенации.
  • Возвращает: <Buffer>

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

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

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

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

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
import { Buffer } from 'node:buffer';

// 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

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
const { Buffer } = require('node:buffer');

// 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.copyBytesFrom(view[, offset[, length]])

  • view <TypedArray> TypedArray для копирования.
  • offset <integer> Начальное смещение в view. По умолчанию: 0.
  • length <integer> Число элементов из view для копирования. По умолчанию: view.length - offset.
  • Возвращает: <Buffer>

Копирует базовую память view в новый Buffer.

1
2
3
4
5
6
const u16 = new Uint16Array([0, 0xffff]);
const buf = Buffer.copyBytesFrom(u16, 1, 1);
u16[1] = 0;
console.log(buf.length); // 2
console.log(buf[0]); // 255
console.log(buf[1]); // 255

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

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

1
2
3
4
import { Buffer } from 'node:buffer';

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

1
2
3
4
const { Buffer } = require('node:buffer');

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

Если array — объект, похожий на Array (то есть с свойством length типа number), он обрабатывается как массив, если только это не Buffer или Uint8Array. Иначе говоря, все остальные варианты TypedArray обрабатываются как Array. Чтобы создать Buffer из байтов, лежащих в основе TypedArray, используйте Buffer.copyBytesFrom().

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

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

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

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

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
import { Buffer } from 'node:buffer';

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>

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
const { Buffer } = require('node:buffer');

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.

1
2
3
4
5
6
7
import { Buffer } from 'node:buffer';

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

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

1
2
3
4
5
6
7
const { Buffer } = require('node: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().

Важно помнить, что базовый ArrayBuffer может охватывать область памяти шире, чем представление TypedArray. Новый Buffer, созданный через свойство buffer у TypedArray, может выходить за границы самого TypedArray:

1
2
3
4
5
6
7
8
9
import { Buffer } from 'node:buffer';

const arrA = Uint8Array.from([0x63, 0x64, 0x65, 0x66]); // 4 elements
const arrB = new Uint8Array(arrA.buffer, 1, 2); // 2 elements
console.log(arrA.buffer === arrB.buffer); // true

const buf = Buffer.from(arrB.buffer);
console.log(buf);
// Prints: <Buffer 63 64 65 66>

1
2
3
4
5
6
7
8
9
const { Buffer } = require('node:buffer');

const arrA = Uint8Array.from([0x63, 0x64, 0x65, 0x66]); // 4 elements
const arrB = new Uint8Array(arrA.buffer, 1, 2); // 2 elements
console.log(arrA.buffer === arrB.buffer); // true

const buf = Buffer.from(arrB.buffer);
console.log(buf);
// Prints: <Buffer 63 64 65 66>

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

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

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
import { Buffer } from 'node: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

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
const { Buffer } = require('node: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 <Object> Объект с поддержкой Symbol.toPrimitive или valueOf().
  • offsetOrEncoding <integer> | <string> Смещение в байтах или кодировка.
  • length <integer> Длина.
  • Возвращает: <Buffer>

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

1
2
3
4
import { Buffer } from 'node:buffer';

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>

1
2
3
4
const { Buffer } = require('node:buffer');

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).

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
import { Buffer } from 'node:buffer';

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>

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
const { Buffer } = require('node:buffer');

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 <string> Строка для кодирования.
  • encoding <string> Кодировка string. По умолчанию: 'utf8'.
  • Возвращает: <Buffer>

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

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
import { Buffer } from 'node:buffer';

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

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
const { Buffer } = require('node:buffer');

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.from(string) также может использовать внутренний пул Buffer, как это делает Buffer.allocUnsafe().

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

Возвращает true, если obj — это Buffer, иначе false.

1
2
3
4
5
6
7
import { Buffer } from 'node:buffer';

Buffer.isBuffer(Buffer.alloc(10)); // true
Buffer.isBuffer(Buffer.from('foo')); // true
Buffer.isBuffer('a string'); // false
Buffer.isBuffer([]); // false
Buffer.isBuffer(new Uint8Array(1024)); // false

1
2
3
4
5
6
7
const { Buffer } = require('node:buffer');

Buffer.isBuffer(Buffer.alloc(10)); // true
Buffer.isBuffer(Buffer.from('foo')); // true
Buffer.isBuffer('a string'); // false
Buffer.isBuffer([]); // false
Buffer.isBuffer(new Uint8Array(1024)); // false

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

  • encoding <string> Имя кодировки для проверки.
  • Возвращает: <boolean>

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

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
import { Buffer } from 'node:buffer';

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

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

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

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

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
const { Buffer } = require('node:buffer');

console.log(Buffer.isEncoding('utf8'));
// 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

  • Тип: <integer> По умолчанию: 8192

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

buf[index]

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

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

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
import { Buffer } from 'node:buffer';

// 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

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
const { Buffer } = require('node:buffer');

// 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.

1
2
3
4
5
6
7
import { Buffer } from 'node:buffer';

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

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

1
2
3
4
5
6
7
const { Buffer } = require('node:buffer');

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

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

buf.byteOffset

  • Тип: <integer> byteOffset базового объекта ArrayBuffer у Buffer.

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

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

Частая проблема при создании TypedArray, разделяющего память с Buffer, — нужно корректно указать byteOffset:

1
2
3
4
5
6
7
8
9
import { Buffer } from 'node:buffer';

// Create a buffer smaller than `Buffer.poolSize`.
const nodeBuffer = 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);

1
2
3
4
5
6
7
8
9
const { Buffer } = require('node:buffer');

// Create a buffer smaller than `Buffer.poolSize`.
const nodeBuffer = 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 <Buffer> | <Uint8Array> Buffer или Uint8Array, с которым сравнивается buf.
  • targetStart <integer> Смещение в target, с которого начинается сравнение. По умолчанию: 0.
  • targetEnd <integer> Смещение в target, на котором сравнение заканчивается (не включая). По умолчанию: target.length.
  • sourceStart <integer> Смещение в buf, с которого начинается сравнение. По умолчанию: 0.
  • sourceEnd <integer> Смещение в buf, на котором сравнение заканчивается (не включая). По умолчанию: buf.length.
  • Возвращает: <integer>

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

  • возвращается 0, если target совпадает с buf;
  • возвращается 1, если target при сортировке должен идти перед buf;
  • возвращается -1, если target при сортировке должен идти после buf.
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
import { Buffer } from 'node:buffer';

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].)

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
const { Buffer } = require('node:buffer');

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.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
import { Buffer } from 'node:buffer';

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

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
const { Buffer } = require('node:buffer');

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 <Buffer> | <Uint8Array> Buffer или Uint8Array, в который копируют.
  • targetStart <integer> Смещение в target, с которого начинается запись. По умолчанию: 0.
  • sourceStart <integer> Смещение в buf, с которого начинается копирование. По умолчанию: 0.
  • sourceEnd <integer> Смещение в buf, на котором копирование останавливается (не включая). По умолчанию: buf.length.
  • Возвращает: <integer> Число скопированных байтов.

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

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

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
import { Buffer } from 'node:buffer';

// 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!!!!!!!!!!!!!

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
const { Buffer } = require('node:buffer');

// 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!!!!!!!!!!!!!

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
import { Buffer } from 'node:buffer';

// 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

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
const { Buffer } = require('node:buffer');

// 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()

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

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
import { Buffer } from 'node:buffer';

// 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]

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
const { Buffer } = require('node:buffer');

// 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)

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

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
import { Buffer } from 'node:buffer';

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

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
const { Buffer } = require('node:buffer');

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 <string> | <Buffer> | <Uint8Array> | <integer> Значение для заполнения buf. Пустое значение (строка, Uint8Array, Buffer) приводится к 0.
  • offset <integer> Сколько байт пропустить перед началом заполнения buf. По умолчанию: 0.
  • end <integer> Где закончить заполнение buf (не включая). По умолчанию: buf.length.
  • encoding <string> Кодировка для value, если value — строка. По умолчанию: 'utf8'.
  • Возвращает: <Buffer> Ссылка на buf.

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

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
import { Buffer } from 'node:buffer';

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

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

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

// Fill a buffer with empty string
const c = Buffer.allocUnsafe(5).fill('');

console.log(c.fill(''));
// Prints: <Buffer 00 00 00 00 00>

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
const { Buffer } = require('node:buffer');

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

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

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

// Fill a buffer with empty string
const c = Buffer.allocUnsafe(5).fill('');

console.log(c.fill(''));
// Prints: <Buffer 00 00 00 00 00>

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

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

1
2
3
4
5
6
import { Buffer } from 'node:buffer';

// 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>

1
2
3
4
5
6
const { Buffer } = require('node:buffer');

// 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 содержит недопустимые символы, они отбрасываются; если не остаётся корректных данных для заполнения, выбрасывается исключение:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
import { Buffer } from 'node:buffer';

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.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
const { Buffer } = require('node:buffer');

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[, start[, end]][, encoding])

  • value <string> | <Buffer> | <Uint8Array> | <integer> Что искать.
  • start <integer> С какого места начинать поиск в buf. Если отрицательно, смещение считается от конца buf. По умолчанию: 0.
  • end <integer> Где закончить поиск в buf (не включая). По умолчанию: buf.length.
  • encoding <string> Если value — строка, это её кодировка. По умолчанию: 'utf8'.
  • Возвращает: <boolean> true, если value найден в buf, иначе false.

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

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
import { Buffer } from 'node:buffer';

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

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
const { Buffer } = require('node:buffer');

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[, start[, end]][, encoding])

  • value <string> | <Buffer> | <Uint8Array> | <integer> Что искать.
  • start <integer> С какого места начинать поиск в buf. Если отрицательно, смещение считается от конца buf. По умолчанию: 0.
  • end <integer> Где закончить поиск в buf (не включая). По умолчанию: buf.length.
  • encoding <string> Если value — строка, задаёт кодировку для двоичного представления строки при поиске в buf. По умолчанию: 'utf8'.
  • Возвращает: <integer> Индекс первого вхождения value в buf или -1, если value в buf нет.

Если value — это:

  • строка, value интерпретируется в соответствии с кодировкой символов в encoding;
  • Buffer или Uint8Array, используется value целиком; для сравнения части Buffer используйте buf.subarray;
  • число, value интерпретируется как беззнаковое 8-битное целое в диапазоне от 0 до 255.
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
import { Buffer } from 'node:buffer';

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

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
const { Buffer } = require('node:buffer');

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.prototype.indexOf().

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
import { Buffer } from 'node:buffer';

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', []));

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
const { Buffer } = require('node:buffer');

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()

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

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
import { Buffer } from 'node:buffer';

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

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

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
const { Buffer } = require('node:buffer');

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

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

buf.lastIndexOf(value[, start[, end]][, encoding])

  • value <string> | <Buffer> | <Uint8Array> | <integer> Что искать.
  • start <integer> С какого места начинать поиск в buf. Если отрицательно, смещение считается от конца buf. По умолчанию: buf.length - 1.
  • end <integer> Где закончить поиск в buf (не включая). По умолчанию: buf.length.
  • encoding <string> Если value — строка, задаёт кодировку для двоичного представления строки при поиске в buf. По умолчанию: 'utf8'.
  • Возвращает: <integer> Индекс последнего вхождения value в buf или -1, если value в buf нет.

То же, что buf.indexOf(), но ищется последнее вхождение value, а не первое.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
import { Buffer } from 'node:buffer';

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

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
const { Buffer } = require('node:buffer');

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.prototype.lastIndexOf().

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
import { Buffer } from 'node:buffer';

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', []));

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
const { Buffer } = require('node:buffer');

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.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
import { Buffer } from 'node:buffer';

// 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

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
const { Buffer } = require('node:buffer');

// 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

Стабильность: 0 - Устарело: используйте buf.buffer вместо этого.

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

buf.readBigInt64BE([offset])

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

Читает знаковое 64-битное целое (big-endian) из buf по указанному смещению offset.

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

buf.readBigInt64LE([offset])

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

Читает знаковое 64-битное целое (little-endian) из buf по указанному смещению offset.

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

buf.readBigUInt64BE([offset])

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

Читает беззнаковое 64-битное целое (big-endian) из buf по указанному смещению offset.

Также доступна под псевдонимом readBigUint64BE.

1
2
3
4
5
6
import { Buffer } from 'node:buffer';

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

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

1
2
3
4
5
6
const { Buffer } = require('node:buffer');

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

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

buf.readBigUInt64LE([offset])

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

Читает беззнаковое 64-битное целое (little-endian) из buf по указанному смещению offset.

Также доступна под псевдонимом readBigUint64LE.

1
2
3
4
5
6
import { Buffer } from 'node:buffer';

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

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

1
2
3
4
5
6
const { Buffer } = require('node:buffer');

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

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

buf.readDoubleBE([offset])

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

Читает 64-битное число с плавающей запятой (big-endian) из buf по указанному смещению offset.

1
2
3
4
5
6
import { Buffer } from 'node:buffer';

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

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

1
2
3
4
5
6
const { Buffer } = require('node:buffer');

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 <integer> Сколько байт пропустить перед чтением. Должно выполняться 0 <= offset <= buf.length - 8. По умолчанию: 0.
  • Возвращает: <number>

Читает 64-битное число с плавающей запятой (little-endian) из buf по указанному смещению offset.

1
2
3
4
5
6
7
8
import { Buffer } from 'node:buffer';

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.

1
2
3
4
5
6
7
8
const { Buffer } = require('node:buffer');

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 <integer> Сколько байт пропустить перед чтением. Должно выполняться 0 <= offset <= buf.length - 4. По умолчанию: 0.
  • Возвращает: <number>

Читает 32-битное число с плавающей запятой (big-endian) из buf по указанному смещению offset.

1
2
3
4
5
6
import { Buffer } from 'node:buffer';

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

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

1
2
3
4
5
6
const { Buffer } = require('node:buffer');

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

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

buf.readFloatLE([offset])

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

Читает 32-битное число с плавающей запятой (little-endian) из buf по указанному смещению offset.

1
2
3
4
5
6
7
8
import { Buffer } from 'node:buffer';

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.

1
2
3
4
5
6
7
8
const { Buffer } = require('node:buffer');

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

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

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

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
import { Buffer } from 'node: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.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
const { Buffer } = require('node: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 <integer> Сколько байт пропустить перед чтением. Должно выполняться 0 <= offset <= buf.length - 2. По умолчанию: 0.
  • Возвращает: <integer>

Читает знаковое 16-битное целое (big-endian) из buf по указанному смещению offset.

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

1
2
3
4
5
6
import { Buffer } from 'node:buffer';

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

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

1
2
3
4
5
6
const { Buffer } = require('node:buffer');

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

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

buf.readInt16LE([offset])

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

Читает знаковое 16-битное целое (little-endian) из buf по указанному смещению offset.

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

1
2
3
4
5
6
7
8
import { Buffer } from 'node:buffer';

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

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

1
2
3
4
5
6
7
8
const { Buffer } = require('node: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 <integer> Сколько байт пропустить перед чтением. Должно выполняться 0 <= offset <= buf.length - 4. По умолчанию: 0.
  • Возвращает: <integer>

Читает знаковое 32-битное целое (big-endian) из buf по указанному смещению offset.

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

1
2
3
4
5
6
import { Buffer } from 'node:buffer';

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

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

1
2
3
4
5
6
const { Buffer } = require('node:buffer');

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

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

buf.readInt32LE([offset])

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

Читает знаковое 32-битное целое (little-endian) из buf по указанному смещению offset.

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

1
2
3
4
5
6
7
8
import { Buffer } from 'node: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.

1
2
3
4
5
6
7
8
const { Buffer } = require('node: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 <integer> Сколько байт пропустить перед чтением. Должно выполняться 0 <= offset <= buf.length - byteLength.
  • byteLength <integer> Сколько байт прочитать. Должно выполняться 0 < byteLength <= 6.
  • Возвращает: <integer>

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

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
import { Buffer } from 'node:buffer';

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.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
const { Buffer } = require('node:buffer');

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 <integer> Сколько байт пропустить перед чтением. Должно выполняться 0 <= offset <= buf.length - byteLength.
  • byteLength <integer> Сколько байт прочитать. Должно выполняться 0 < byteLength <= 6.
  • Возвращает: <integer>

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

1
2
3
4
5
6
import { Buffer } from 'node:buffer';

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

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

1
2
3
4
5
6
const { Buffer } = require('node:buffer');

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

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

buf.readUInt8([offset])

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

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

Также доступна под псевдонимом readUint8.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
import { Buffer } from 'node:buffer';

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.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
const { Buffer } = require('node:buffer');

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

Читает беззнаковое 16-битное целое (big-endian) из buf по указанному смещению offset.

Также доступна под псевдонимом readUint16BE.

1
2
3
4
5
6
7
8
import { Buffer } from 'node:buffer';

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

1
2
3
4
5
6
7
8
const { Buffer } = require('node:buffer');

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

Читает беззнаковое 16-битное целое (little-endian) из buf по указанному смещению offset.

Также доступна под псевдонимом readUint16LE.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
import { Buffer } from 'node:buffer';

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.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
const { Buffer } = require('node:buffer');

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

Читает беззнаковое 32-битное целое (big-endian) из buf по указанному смещению offset.

Также доступна под псевдонимом readUint32BE.

1
2
3
4
5
6
import { Buffer } from 'node:buffer';

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

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

1
2
3
4
5
6
const { Buffer } = require('node:buffer');

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

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

buf.readUInt32LE([offset])

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

Читает беззнаковое 32-битное целое (little-endian) из buf по указанному смещению offset.

Также доступна под псевдонимом readUint32LE.

1
2
3
4
5
6
7
8
import { Buffer } from 'node:buffer';

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.

1
2
3
4
5
6
7
8
const { Buffer } = require('node:buffer');

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 <integer> Сколько байт пропустить перед чтением. Должно выполняться 0 <= offset <= buf.length - byteLength.
  • byteLength <integer> Сколько байт прочитать. Должно выполняться 0 < byteLength <= 6.
  • Возвращает: <integer>

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

Также доступна под псевдонимом readUintBE.

1
2
3
4
5
6
7
8
import { Buffer } from 'node:buffer';

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.

1
2
3
4
5
6
7
8
const { Buffer } = require('node:buffer');

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 <integer> Сколько байт пропустить перед чтением. Должно выполняться 0 <= offset <= buf.length - byteLength.
  • byteLength <integer> Сколько байт прочитать. Должно выполняться 0 < byteLength <= 6.
  • Возвращает: <integer>

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

Также доступна под псевдонимом readUintLE.

1
2
3
4
5
6
import { Buffer } from 'node:buffer';

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

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

1
2
3
4
5
6
const { Buffer } = require('node:buffer');

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 <integer> С какого индекса начинается новый Buffer. По умолчанию: 0.
  • end <integer> Где заканчивается новый Buffer (не включая). По умолчанию: buf.length.
  • Возвращает: <Buffer>

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

Если указать end больше buf.length, результат совпадёт с вариантом, когда end равен buf.length.

Метод унаследован от TypedArray.prototype.subarray().

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

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
import { Buffer } from 'node: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

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
const { Buffer } = require('node: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, а не начала.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
import { Buffer } from 'node:buffer';

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).)

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
const { Buffer } = require('node:buffer');

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]])

Стабильность: 0 - Устарело: используйте buf.subarray вместо этого.

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

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

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

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
import { Buffer } from 'node:buffer';

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

// With buf.slice(), the original buffer is modified.
const notReallyCopiedBuf = buf.slice();
notReallyCopiedBuf[0]++;
console.log(notReallyCopiedBuf.toString());
// Prints: cuffer
console.log(buf.toString());
// Also prints: cuffer (!)

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
const { Buffer } = require('node:buffer');

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

// With buf.slice(), the original buffer is modified.
const notReallyCopiedBuf = buf.slice();
notReallyCopiedBuf[0]++;
console.log(notReallyCopiedBuf.toString());
// Prints: cuffer
console.log(buf.toString());
// Also prints: cuffer (!)

buf.swap16()

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

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

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
import { Buffer } from 'node:buffer';

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.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
const { Buffer } = require('node:buffer');

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:

1
2
3
4
import { Buffer } from 'node:buffer';

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

1
2
3
4
const { Buffer } = require('node:buffer');

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

buf.swap32()

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

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

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
import { Buffer } from 'node:buffer';

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.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
const { Buffer } = require('node:buffer');

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()

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

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

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
import { Buffer } from 'node:buffer';

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.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
const { Buffer } = require('node:buffer');

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).

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
import { Buffer } from 'node:buffer';

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>

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
const { Buffer } = require('node:buffer');

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 <string> Кодировка символов. По умолчанию: 'utf8'.
  • start <integer> Смещение в байтах, с которого начинать декодирование. По умолчанию: 0.
  • end <integer> Смещение в байтах, на котором декодирование останавливается (не включая). По умолчанию: buf.length.
  • Возвращает: <string>

Декодирует buf в строку в соответствии с кодировкой encoding. Можно передать start и end, чтобы декодировать только часть buf.

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

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

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
import { Buffer } from 'node: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;
}

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é

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
const { Buffer } = require('node: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;
}

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()

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

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
import { Buffer } from 'node:buffer';

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

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
const { Buffer } = require('node:buffer');

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

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

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
import { Buffer } from 'node:buffer';

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

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
const { Buffer } = require('node:buffer');

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 <integer> Сколько байт пропустить перед записью. Должно выполняться: 0 <= offset <= buf.length - 8. По умолчанию: 0.
  • Возвращает: <integer> offset плюс число записанных байт.

Записывает value в buf по смещению offset в порядке big-endian.

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

1
2
3
4
5
6
7
8
import { Buffer } from 'node:buffer';

const buf = Buffer.allocUnsafe(8);

buf.writeBigInt64BE(0x0102030405060708n, 0);

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

1
2
3
4
5
6
7
8
const { Buffer } = require('node:buffer');

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 <integer> Сколько байт пропустить перед записью. Должно выполняться: 0 <= offset <= buf.length - 8. По умолчанию: 0.
  • Возвращает: <integer> offset плюс число записанных байт.

Записывает value в buf по смещению offset в порядке little-endian.

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

1
2
3
4
5
6
7
8
import { Buffer } from 'node:buffer';

const buf = Buffer.allocUnsafe(8);

buf.writeBigInt64LE(0x0102030405060708n, 0);

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

1
2
3
4
5
6
7
8
const { Buffer } = require('node:buffer');

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.

Также доступна под псевдонимом writeBigUint64BE.

1
2
3
4
5
6
7
8
import { Buffer } from 'node:buffer';

const buf = Buffer.allocUnsafe(8);

buf.writeBigUInt64BE(0xdecafafecacefaden, 0);

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

1
2
3
4
5
6
7
8
const { Buffer } = require('node:buffer');

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.

1
2
3
4
5
6
7
8
import { Buffer } from 'node:buffer';

const buf = Buffer.allocUnsafe(8);

buf.writeBigUInt64LE(0xdecafafecacefaden, 0);

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

1
2
3
4
5
6
7
8
const { Buffer } = require('node:buffer');

const buf = Buffer.allocUnsafe(8);

buf.writeBigUInt64LE(0xdecafafecacefaden, 0);

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

Также доступна под псевдонимом writeBigUint64LE.

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.

1
2
3
4
5
6
7
8
import { Buffer } from 'node:buffer';

const buf = Buffer.allocUnsafe(8);

buf.writeDoubleBE(123.456, 0);

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

1
2
3
4
5
6
7
8
const { Buffer } = require('node:buffer');

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.

1
2
3
4
5
6
7
8
import { Buffer } from 'node:buffer';

const buf = Buffer.allocUnsafe(8);

buf.writeDoubleLE(123.456, 0);

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

1
2
3
4
5
6
7
8
const { Buffer } = require('node:buffer');

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.

1
2
3
4
5
6
7
8
import { Buffer } from 'node:buffer';

const buf = Buffer.allocUnsafe(4);

buf.writeFloatBE(0xcafebabe, 0);

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

1
2
3
4
5
6
7
8
const { Buffer } = require('node:buffer');

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.

1
2
3
4
5
6
7
8
import { Buffer } from 'node:buffer';

const buf = Buffer.allocUnsafe(4);

buf.writeFloatLE(0xcafebabe, 0);

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

1
2
3
4
5
6
7
8
const { Buffer } = require('node:buffer');

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 не является таким числом.

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

1
2
3
4
5
6
7
8
9
import { Buffer } from 'node:buffer';

const buf = Buffer.allocUnsafe(2);

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

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

1
2
3
4
5
6
7
8
9
const { Buffer } = require('node:buffer');

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 не является таким числом.

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

1
2
3
4
5
6
7
8
import { Buffer } from 'node:buffer';

const buf = Buffer.allocUnsafe(2);

buf.writeInt16BE(0x0102, 0);

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

1
2
3
4
5
6
7
8
const { Buffer } = require('node:buffer');

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 не является таким числом.

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

1
2
3
4
5
6
7
8
import { Buffer } from 'node:buffer';

const buf = Buffer.allocUnsafe(2);

buf.writeInt16LE(0x0304, 0);

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

1
2
3
4
5
6
7
8
const { Buffer } = require('node:buffer');

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 не является таким числом.

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

1
2
3
4
5
6
7
8
import { Buffer } from 'node:buffer';

const buf = Buffer.allocUnsafe(4);

buf.writeInt32BE(0x01020304, 0);

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

1
2
3
4
5
6
7
8
const { Buffer } = require('node:buffer');

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 не является таким числом.

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

1
2
3
4
5
6
7
8
import { Buffer } from 'node:buffer';

const buf = Buffer.allocUnsafe(4);

buf.writeInt32LE(0x05060708, 0);

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

1
2
3
4
5
6
7
8
const { Buffer } = require('node:buffer');

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 не является знаковым целым.

1
2
3
4
5
6
7
8
import { Buffer } from 'node:buffer';

const buf = Buffer.allocUnsafe(6);

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

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

1
2
3
4
5
6
7
8
const { Buffer } = require('node:buffer');

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 не является знаковым целым.

1
2
3
4
5
6
7
8
import { Buffer } from 'node:buffer';

const buf = Buffer.allocUnsafe(6);

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

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

1
2
3
4
5
6
7
8
const { Buffer } = require('node:buffer');

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 не является таким числом.

Также доступна под псевдонимом writeUint8.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
import { Buffer } from 'node:buffer';

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>

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
const { Buffer } = require('node:buffer');

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 не является таким числом.

Также доступна под псевдонимом writeUint16BE.

1
2
3
4
5
6
7
8
9
import { Buffer } from 'node:buffer';

const buf = Buffer.allocUnsafe(4);

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

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

1
2
3
4
5
6
7
8
9
const { Buffer } = require('node:buffer');

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 не является таким числом.

Также доступна под псевдонимом writeUint16LE.

1
2
3
4
5
6
7
8
9
import { Buffer } from 'node:buffer';

const buf = Buffer.allocUnsafe(4);

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

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

1
2
3
4
5
6
7
8
9
const { Buffer } = require('node:buffer');

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

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

Также доступна под псевдонимом writeUint32BE.

1
2
3
4
5
6
7
8
import { Buffer } from 'node:buffer';

const buf = Buffer.allocUnsafe(4);

buf.writeUInt32BE(0xfeedface, 0);

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

1
2
3
4
5
6
7
8
const { Buffer } = require('node:buffer');

const buf = Buffer.allocUnsafe(4);

buf.writeUInt32BE(0xfeedface, 0);

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

buf.writeUInt32LE(value[, offset])

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

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

Также доступна под псевдонимом writeUint32LE.

1
2
3
4
5
6
7
8
import { Buffer } from 'node:buffer';

const buf = Buffer.allocUnsafe(4);

buf.writeUInt32LE(0xfeedface, 0);

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

1
2
3
4
5
6
7
8
const { Buffer } = require('node:buffer');

const buf = Buffer.allocUnsafe(4);

buf.writeUInt32LE(0xfeedface, 0);

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

buf.writeUIntBE(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 не является беззнаковым целым.

Также доступна под псевдонимом writeUintBE.

1
2
3
4
5
6
7
8
import { Buffer } from 'node:buffer';

const buf = Buffer.allocUnsafe(6);

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

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

1
2
3
4
5
6
7
8
const { Buffer } = require('node:buffer');

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

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

Также доступна под псевдонимом writeUintLE.

1
2
3
4
5
6
7
8
import { Buffer } from 'node:buffer';

const buf = Buffer.allocUnsafe(6);

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

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

1
2
3
4
5
6
7
8
const { Buffer } = require('node:buffer');

const buf = Buffer.allocUnsafe(6);

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

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

new Buffer(array)

Stability: 0 - Устарело: Используйте Buffer.from(array) вместо этого.

  • array <integer[]> Массив байтов для копирования.

См. Buffer.from(array).

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

Стабильность: 0 - Устарело: используйте Buffer.from(arrayBuffer[, byteOffset[, length]]) вместо этого.

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

new Buffer(buffer)

Стабильность: 0 - Устарело: используйте Buffer.from(buffer) вместо этого.

См. Buffer.from(buffer).

new Buffer(size)

Стабильность: 0 - Устарело: используйте Buffer.alloc() вместо этого (см. также Buffer.allocUnsafe()).

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

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

new Buffer(string[, encoding])

Стабильность: 0 - Устарело: используйте Buffer.from(string[, encoding]) вместо этого.

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

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

Класс: File

File представляет сведения о файле.

new buffer.File(sources, fileName[, options])

file.name

Имя File.

file.lastModified

Дата последнего изменения File.

API модуля node:buffer

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

buffer.atob(data)

Стабильность: 3 - Закрыто. Вместо этого используйте Buffer.from(data, 'base64').

  • data <any> Входная строка в Base64.

Декодирует строку Base64 в байты и кодирует эти байты в строку Latin-1 (ISO-8859-1).

data может быть любым значением JavaScript, приводимым к строке.

Функция оставлена для совместимости со старыми веб-API и не должна использоваться в новом коде: строки для двоичных данных и отсутствие типизированных массивов устарели. В коде на Node.js преобразование между base64 и двоичными данными делайте через Buffer.from(str, 'base64') и buf.toString('base64').

Доступна автоматическая миграция (исходники:

1
npx codemod@latest @nodejs/buffer-atob-btoa

buffer.btoa(data)

Стабильность: 3 - Закрыто. Вместо этого используйте buf.toString('base64').

  • data <any> Строка ASCII (Latin1).

Декодирует строку в байты по Latin-1 (ISO-8859) и кодирует байты в Base64.

data может быть любым значением JavaScript, приводимым к строке.

Функция оставлена для совместимости со старыми веб-API и не должна использоваться в новом коде. В коде на Node.js используйте Buffer.from(str, 'base64') и buf.toString('base64').

Доступна автоматическая миграция (исходники:

1
npx codemod@latest @nodejs/buffer-atob-btoa

buffer.isAscii(input)

Возвращает true, если input содержит только корректные данные в ASCII, в том числе при пустом input.

Выбрасывает исключение, если input — отсоединённый ArrayBuffer.

buffer.isUtf8(input)

Возвращает true, если input содержит только корректные данные UTF-8, в том числе при пустом input.

Выбрасывает исключение, если input — отсоединённый ArrayBuffer.

buffer.INSPECT_MAX_BYTES

  • Тип: <integer> По умолчанию: 50

Максимальное число байт, возвращаемых при вызове buf.inspect(). Пользовательские модули могут переопределить значение. Подробнее о поведении buf.inspect() см. util.inspect().

buffer.kMaxLength

  • Тип: <integer> Наибольший допустимый размер одного экземпляра Buffer.

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

buffer.kStringMaxLength

  • Тип: <integer> Наибольшая допустимая длина одного примитива string.

Псевдоним buffer.constants.MAX_STRING_LENGTH.

buffer.resolveObjectURL(id)

  • id <string> Строка URL вида 'blob:nodedata:..., полученная ранее от URL.createObjectURL().
  • Возвращает: <Blob>

Сопоставляет 'blob:nodedata:...' с соответствующим объектом Blob, зарегистрированным ранее через URL.createObjectURL().

buffer.transcode(source, fromEnc, toEnc)

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

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

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

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

1
2
3
4
5
import { Buffer, transcode } from 'node:buffer';

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

1
2
3
4
5
const { Buffer, transcode } = require('node:buffer');

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

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

Константы Buffer

buffer.constants.MAX_LENGTH

  • Тип: <integer> Наибольший допустимый размер одного экземпляра Buffer.

На 32-битных архитектурах значение равно 231 - 1 (около 2 ГиБ).

На 64-битных — Number.MAX_SAFE_INTEGER (253 - 1, около 8 ПиБ).

Внутри соответствует v8::Uint8Array::kMaxLength.

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

buffer.constants.MAX_STRING_LENGTH

  • Тип: <integer> Наибольшая допустимая длина одного примитива string.

Наибольшая длина length у примитива string в UTF-16 кодовых единицах.

Значение может зависеть от движка JavaScript.

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

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

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

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

Например, если злоумышленник заставит приложение получить число там, где ожидалась строка, может вызваться new Buffer(100) вместо new Buffer("100") — будет выделен буфер на 100 байт вместо трёх байт со строкой "100". Такое часто возможно через JSON API: типы числа и строки различимы, и в наивный код без проверки можно подставить число. До Node.js 8.0.0 буфер на 100 байт мог содержать произвольные остатки памяти и использоваться для утечки секретов. С Node.js 8.0.0 память обнуляется, но возможны другие атаки — например выделение очень больших буферов и исчерпание памяти.

Чтобы сделать создание Buffer надёжнее, варианты конструктора new Buffer() устарели и заменены методами Buffer.from(), Buffer.alloc() и Buffer.allocUnsafe().

Следует перенести весь существующий код с new Buffer() на эти API.

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

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

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

1
2
3
$ 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.allocUnsafe() выше, но нужна повышенная осторожность, чтобы не ввести уязвимости.

Комментарии