[node.js] Buffer 란?

최근 node.js 프로젝트를 하면서 node.js의 buffer를 많이 다루었습니다.

특히 파일을 읽을 때나 새로운 파일을 만들 때 사용했는데,
node.js의 buffer에 대해 정확히 파악하지 못하고 사용하는 것 같아 조사해 봤습니다.

Buffer 란?

컴퓨터 과학에서 Buffer는 데이터를 한 곳에서 다른 한 곳으로 전송하는 동안 일시적으로 데이터를 보관하는 메모리 영역입니다.

Buffer는 네트워크 상에서 자료를 주고받을 때, 디스크 드라이브 같은 하드웨어의 입출력을 결합하는데 자주 이용됩니다.

node.js에서 Buffer는?

node.js에서도 네트워크에서 자료를 주고받거나 파일 등 원시 바이너리 데이터를 읽고 쓸 수 있도록 Buffer라는 특별한 객체를 구현해 놨습니다.

 

node.js의 공식문서에 나와있는 Buffer의 정의는 다음과 같습니다.

Buffer는 고정 길이의 바이트 시퀀스를 표현하는 데 사용됩니다. 많은 Node.js API가 버퍼를 지원합니다.

Buffer 클래스는 JavaScript의 <Uint8Array> 클래스의 하위 클래스로, 추가적인 사용 사례를 다루는 메서드들로 이를 확장합니다. Node.js API는 Buffer가 지원되는 곳이라면 어디서나 일반 <Uint8Array>도 수용합니다.

 

흔히 node.js에서 fs.readFileSync()를 사용하여 파일을 읽으면 결괏값이 Buffer 객체로 반환됩니다.

const buffer = fs.readFileSync('example.txt'); // Buffer 객체로 반환

 

추가적으로 Buffer 객체는 global scope에서 사용할 수 있지만, import나 require 문을 사용하여 참조하여 사용하는 것이 권장된다고 합니다.

const { Buffer } = require('node:buffer');

 

 

Buffer와 문자 인코딩

Buffer.from

Buffer.from을 사용하면 문자열을 버퍼 객체로 만들 수 있습니다.

이때 인코딩 형식을 명시해야 합니다.

const buf = Buffer.from('hello world', 'utf8');
const buf2 = Buffer.from('hello world'); // 기본값으로 utf-8 적용

 

node.js에서 문자열을 버퍼로 객체로 만들 때 지원하는 인코딩은 다음과 같습니다.

• 'utf8' : 다중 바이트 인코딩된 유니코드 문자입니다. 유효한 UTF-8 데이터만 포함하지 않는 문자열로 버퍼를 디코딩할 때, 해당 오류는 유니코드 대체 문자 U+FFFD �로 표시됩니다.
• 'utf16le' : 다중 바이트 인코딩된 유니코드 문자입니다. 'utf8'과 달리, 문자열 내 각 문자는 2바이트 또는 4바이트로 인코딩 됩니다. Node.js는 UTF-16의 리틀 엔디안 변형만 지원합니다.
• 'latin1' : 이 문자 인코딩은 U+0000부터 U+00FF까지의 유니코드 문자만 지원합니다. 각 문자는 단일 바이트로 인코딩 됩니다. 해당 범위에 맞지 않는 문자는 잘려서 해당 범위의 문자로 매핑됩니다.

만약 인코딩을 명시하지 않으면 utf-8이 기본값으로 설정됩니다.

 

Buffer.toString

반대로 버퍼에 있는 이진데이터를 문자열로 만들 수 있습니다.

이때도 인코딩 형식을 명시합니다.

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

 

이진데이터를 문자로 만들 때 지원하는 인코딩은 다음과 같습니다.

• 'base64' : base64로 인코딩합니다. base64 인코딩 된 문자열 내에 포함된 공백, 탭, 줄 바꿈 등의 공백 문자는 무시됩니다.
• 'base64url' : 문자열로부터 버퍼를 생성할 때, 이 인코딩은 일반 base64 인코딩 된 문자열도 올바르게 수용합니다. 버퍼를 문자열로 인코딩할 때, 이 인코딩은 패딩을 생략합니다.
• 'hex' : 각 바이트를 16진수 두 글자로 인코딩합니다. 16진수 글자 수가 반드시 짝수 개가 아닌 문자열을 디코딩할 때 데이터가 잘릴 수 있습니다.

이외에도 지원하는 레거시 인코딩 형식입니다.

• 'ascii' : 7비트 ASCII 데이터 전용입니다. 문자열을 버퍼로 인코딩할 때 이 인코딩은 'latin1'을 사용하는 것과 동일합니다.
• 'binary'
• 'ucs2'

 

인코딩? 디코딩?

Node.js는 텍스트-바이너리 인코딩과 바이너리-텍스트 인코딩 둘 다 지원합니다.

 

텍스트-바이너리 인코딩 경우

텍스트를 바이너리 데이터로 만드는 것을 인코딩, 바이너리 데이터를 텍스트로 만드는 것을 디코딩이라고 합니다. 

 

바이너리-텍스트 인코딩의 경우 반대입니다.

바이너리를 텍스트로 만드는 것을 인코딩, 텍스트를 바이너리로 만드는 것을 디코딩이라고 합니다.

 

Buffer와 TypedArray

Buffer 인스턴스는 Javascript의 Uint8Array와 TypedArray 인스턴스이기도 합니다.

따라서 TypedArray의 모든 메서드는 Buffer 인스턴스에서 사용 가능합니다.

 

단, Buffer API와 TypedArray API 사이에는 미묘한 호환성 문제가 있습니다.

• TypedArray.prototype.slice는 TypedArray의 일부를 복사해서 생성하지만, Buffer.prototype.slice는 Buffer를 복사하지 않고 해당 Buffer의 view를 생성합니다.
  TypedArray.prototype.subarray는 Buffer와 TypedArray 모두에서 Buffer.prototype.slice의 동작을 구현할 수 있습니다.
• buf.toString은 TypedArray와 호환되지 않습니다.
• Buffer의 많은 메서드들, 예를 들어 buf.indexOf은 추가 인수를 지원합니다.

Buffer에서 TypedArray 생성하기

TypedArray 생성자에 인수로 Buffer 객체를 넘길 수 있습니다.

TypedArray의 생성자에서는 Buffer의 데이터를 복사하여 정수 배열로 변환합니다.

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

console.log(uint32array);
// Prints: Uint32Array(4) [ 1, 2, 3, 4 ]

 

 

추가적으로 TypedArray와 가리키는 메모리가 동일한 Buffer를 생성할 수 있습니다.

TypedArray 객체의 buffer 프로퍼티를 Buffer.from에 넘겨서 Buffer를 생성하면 TypedArray 객체와 Buffer 객체가 가르키는 메모리 공간이 동일합니다.

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>

 

TypedArray 객체의 buffer 프로퍼티를 사용해 Buffer를 생성할 때, bypteOffset과 length를 지정해서 ArrayBuffer의 부분만 지정할 수 있습니다.

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의 메서드와 프로퍼티

Buffer의 메소드와 프로퍼티는 굉장히 많아, 직접 확인해 보는 게 좋을 것 같습니다. 😅

https://nodejs.org/api/buffer.html#class-buffer

Buffer | Node.js v25.2.1 Documentation