Skip to content

Latest commit

 

History

History
195 lines (157 loc) · 7.8 KB

README_EN.md

File metadata and controls

195 lines (157 loc) · 7.8 KB
Raw

base64-pro

base64-pro does base64 encoding and decoding.

Version Downloads jsdelivr Commit Issues License

简体中文  English 

Features

  • Pure JS
  • Zero dependencies
  • Supports modern browsers & Node.js
  • Support conversion between binary data and "base64 string"
  • Support conversion between "unicode string" and "base64 string" (atob and btoa only support characters which code point is between 0 and 255)
  • Support converting binary data or "unicode string" to DataURL
  • Support custom base64 character set
  • Support TypeScript
  • Support ESM, CommonJS, browser direct loading

Installation

npm i base64-pro

Quick Start

import Base64 from "base64-pro"; // ESM

Or

const Base64 = require("base64-pro"); // CommonJS

Or

Loading the JS file directly in the browser. You will get the global variable window.Base64.

1. Conversion between binary data and "base64 string". (Binary data means an instance of ArrayBuffer or TypedArray or DataView or Buffer in Node.js)

const b64 = new Base64();
// encoding
b64.bufferToBase64(new Uint8Array([1, 2, 3, 4])); // AQIDBA==
// decoding
b64.base64ToBuffer("AQIDBA=="); // ArrayBuffer { [Uint8Contents]: <01 02 03 04>, byteLength: 4 }

2. Conversion between "unicode string" and "base64 string".

// encoding
b64.strToBase64("👻base64-pro🤗"); // 8J+Ru2Jhc2U2NC1wcm/wn6SX
// decoding
b64.base64ToStr("8J+Ru2Jhc2U2NC1wcm/wn6SX"); // 👻base64-pro🤗

3. Converting binary data or "unicode string" to DataURL.

b64.bufferToDataURL(require("fs").readFileSync("icon.png"), "image/png"); // data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAA...

b64.strToDataURL("👻base64-pro🤗"); // data:text/plain;charset=utf-8;base64,8J%2BRu2Jhc2U2NC1wcm%2Fwn6SX

Details of the Class Base64

I. Constructor

new Base64(initOpts)

  • initOpts
    • required: no
    • type: object
    • props:
      • alphabet
        • required: no
        • type: string
        • default: "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/"
        • description: base64 character set
      • encodeChunkSize
        • required: no
        • type: number
        • default: 16383
        • description: Performance optimization related, not recommended to be changed. Long strings are slow to stitch together, so when generating base64 strings, they are generated in chunks and finally merged into a complete string. This value represents a temporary string fragment generated for every how many bytes of raw binary data.

II. Methods

1. bufferToBase64(value[, padding])

  • description: Converts binary data to a base64 string.
  • arguments:
    • value
      • required: yes
      • type: buffer
      • description: buffer means an ArrayBuffer instance or a TypedArray instance or a DataView instance or a Buffer instance in Node.js.
    • padding
      • required: no
      • type: boolean
      • default: true
      • description: When the length of a base64 string is not an integer multiple of 4, is it automatically completed with = at the end.
  • return: A base64 string.

2. base64ToBuffer(base64Str)

  • description: Converts a base64 string to binary data.
  • arguments:
    • base64Str
      • required: yes
      • type: string
      • description: a valid base64 string
  • return: An ArrayBuffer instance. You are free to create any kind of view to read this part of the binary data.

3. strToBase64(str[, encoding[, padding]])

  • description: Converts a unicode string to a base64 string.
  • arguments:
    • str
      • required: yes
      • type: string
      • description: A unicode string
    • encoding
      • required: no
      • type: string
      • default: utf-8
      • optional values: utf-8, utf8, utf-16, utf-16le, utf-16be
      • description: Unicode has multiple character encoding methods, and even if the characters are the same, the underlying binary will be different for different encoding methods. Currently, we only supported convert to base64 strings in utf-8 and utf-16 encoding. utf8 is an alias for utf-8. utf-16 is an alias for utf-16le. utf-16le is a little-endian byte order encoding, and utf-16be is a big-endian byte order encoding.
    • padding
      • required: no
      • type: boolean
      • default: true
      • description: ibid.
  • return: A base64 string.

4. base64ToStr(base64Str[, encoding])

  • description: Converts a base64 string to a unicode string.
  • arguments:
    • base64Str
      • required: yes
      • type: string
      • description: A valid base64 string
    • encoding
      • required: no
      • type: string
      • default: utf-8
      • optional values: utf-8, utf8, utf-16, utf-16le, utf-16be
      • description: ibid.
  • return: A unicode string

5. strToDataURL(str[, encoding])

  • description: Converts a unicode string into a DataURL string. The converted result can be opened directly in the browser address bar.
  • arguments:
    • str
      • required: yes
      • type: string
      • description: a unicode string
    • encoding
      • required: no
      • type: string
      • default: utf-8
      • optional values: utf-8, utf8, utf-16, utf-16le, utf-16be
      • description: ibid.
  • return: A DataURL string.

6. bufferToDataURL(value[, mimeType])

  • description: Converts binary data into a DataURL string. Using DataURL reduces network requests, and it is recommended that smaller files be converted to DataURL.
  • arguments:
    • value
      • required: yes
      • type: buffer
      • description: ibid.
    • mimeType
      • required: no
      • type: string
      • default: application/octet-stream
      • description: a valid MIME Type, for example, image/png, application/pdf, etc.
  • return: A DataURL string.

Stargazers over time