npm 패키지 레퍼런스
base64hub는 Node.js 18 이상용 ES 모듈로, 함수 네 개와 TypeScript 타입, b64 명령을 제공합니다. 의존성은 없습니다.
설치
npm i base64hub # library
npm i -g base64hub # b64 command
이 패키지는 ESM 전용입니다. import로 불러오고, CommonJS에서는 await import("base64hub")를 쓰세요. 타입 정의가 함께 들어 있습니다.
import { encode, decode, validate, dataUri, Base64Error } from "base64hub";
encode(input, options?)
바이트, 또는 문자열의 UTF-8 바이트를 인코딩해 문자열을 반환합니다. input은 문자열, Uint8Array(Node.js의 Buffer도 여기에 해당), ArrayBuffer, 또는 아무 타입 배열 뷰나 될 수 있습니다.
| 옵션 | 타입 | 기본값 | 효과 |
|---|---|---|---|
url | boolean | false | URL-safe 알파벳(-와 _). |
pad | boolean | true | = 패딩 추가. |
wrap | number | 0 | N자마다 \n을 넣고 끝에는 넣지 않음. 76은 MIME. |
encode("Hello, hub!"); // "SGVsbG8sIGh1YiE="
encode("Привет", { url: true, pad: false }); // "0J_RgNC40LLQtdGC"
encode("foobar", { wrap: 4 }); // "Zm9v\nYmFy"
encode(new Uint8Array([0xfb, 0xff, 0xbf])); // "+/+/"
decode(text)
Base64를 Uint8Array로 디코딩합니다. 공백, 탭, 줄 바꿈, data:...;base64, 접두사, 빠진 패딩, 두 알파벳 모두 받아들입니다. 그 밖의 입력에는 Base64Error를 던지며, 이 오류의 position은 정리한 입력에서 잘못된 문자의 인덱스(0부터 시작)입니다.
decode("+/+/"); // Uint8Array(3) [ 251, 255, 191 ]
new TextDecoder().decode(decode("SGVsbG8sIGh1YiE")); // "Hello, hub!"
try {
decode("Zm9v!");
} catch (e) {
if (e instanceof Base64Error) console.log(e.message, e.position);
// invalid character '!' at position 4 4
}
텍스트가 필요하면 new TextDecoder().decode(bytes)를, 다른 Node.js API가 Buffer를 요구하면 Buffer.from(bytes)를 쓰세요.
validate(text)
예외를 던지지 않고 텍스트를 검사합니다. decode가 성공할 때 정확히 유효로 판정합니다.
validate("SGVsbG8sIGh1YiE");
// { valid: true, variant: 'either', padded: false, bytes: 11 }
validate("Zm9v!");
// { valid: false, error: "invalid character '!' at position 4" }
| 필드 | 의미 |
|---|---|
valid | true 또는 false. |
variant | standard(+나 / 있음), url(-나 _ 있음), mixed(둘 다 있음), either(둘 다 없음). |
padded | =를 포함한 정리된 길이가 4의 배수인지. |
bytes | 디코딩한 크기(바이트). |
error | 입력이 잘못됐을 때만 있음. decode가 던질 오류와 같은 문구의 이유. |
dataUri(input, mime?)
data:<mime>;base64,<payload> 문자열을 만듭니다. 표준 알파벳에 패딩을 포함하고 줄 바꿈은 하지 않습니다. mime이 없으면 타입을 감지합니다. PNG, JPEG, GIF, WebP, PDF, SVG는 시그니처로 판정하고, UTF-8 텍스트는 text/plain;charset=utf-8, 그 밖에는 application/octet-stream입니다.
dataUri("Hi"); // "data:text/plain;charset=utf-8;base64,SGk="
dataUri("a,b", "text/csv"); // "data:text/csv;base64,YSxi"
import { readFile } from "node:fs/promises";
dataUri(await readFile("logo.png")); // "data:image/png;base64,iVBORw0KGgo..."
b64 명령
npm i -g base64hub는 b64를 설치하고, npx base64hub "Hello, hub!"는 설치하지 않고 한 번 실행합니다. 플래그, 메시지, 종료 코드는 CLI 레퍼런스와 같습니다. npm 빌드는 처리하기 전에 입력 전체를 메모리로 읽으므로, 아주 큰 파일에는 Go 빌드를 쓰세요.
업데이트 2026. 11. 22.