base64.js Documentation 📦
This document covers the linuxfront-v2-logistics/new_2025_js/base64.js utility, detailing its functionality, internal components, and usage patterns. The file implements Base64 encoding and decoding with full UTF-8 support, based on Fred Palmer’s 2008 implementation .
License Notice 📝
The code is released under the MIT License, granting permission to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software.
“THE SOFTWARE IS PROVIDED ‘AS IS’, WITHOUT WARRANTY OF ANY KIND…”
Purpose and Overview 🎯
This module provides two main operations:
- encode(input: string) → Converts a Unicode string to a Base64-encoded ASCII string.
- decode(input: string) → Converts a Base64-encoded ASCII string back to the original Unicode string.
It handles Unicode correctly by first converting characters to UTF-8 byte sequences, then applying standard Base64 bit-grouping.
Component Summary 📋
| Component | Responsibility | Key Methods |
|---|---|---|
| StringBuffer | Efficient accumulation of string fragments | append(string), toString() |
| Base64 | Public API for Base64 encoding/decoding | encode(input), decode(input) |
| Utf8EncodeEnumerator | Converts JS string to a stream of UTF-8 byte codes |
moveNext(), current |
| Base64DecodeEnumerator | Parses Base64 characters into raw byte codes | moveNext(), current |
StringBuffer Class ✍️
A simple buffer to accumulate strings efficiently, avoiding repeated concatenation overhead.
function StringBuffer() {
this.buffer = [];
}
StringBuffer.prototype.append = function append(string) {
this.buffer.push(string);
return this;
};
StringBuffer.prototype.toString = function toString() {
return this.buffer.join("");
};
- append(string): Adds
stringto internal array. - toString(): Joins and returns the full concatenated result.
Base64 Object ⚙️
A global object exposing encode and decode functions, using an internal codex string of 65 characters (including = padding).
var Base64 = {
codex: "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/=",
encode: function(input) { /* ... */ },
decode: function(input) { /* ... */ }
};
encode(input)
Transforms a JS string into Base64:
- Step 1: UTF-8 encode the input via
Utf8EncodeEnumerator. - Step 2: Read three bytes at a time (
chr1,chr2,chr3). - Step 3: Compute four 6-bit groups (
enc1…enc4). - Step 4: Handle padding when input length isn’t divisible by 3.
- Step 5: Map each 6-bit group to a character in
codexand accumulate.
Base64.encode("✓ à la mode");
// → "4pyTIMOgIGxhIG1vZGU="
decode(input)
Reverses Base64 back into the original string:
- Step 1: Use
Base64DecodeEnumeratorto read decoded byte codes. - Step 2: For each byte:
- If
< 128, append directly. - If between
192and223, combine two-byte sequences. - Else combine three-byte sequences.
- If
- Step 3: Convert byte codes back to Unicode characters.
Base64.decode("4pyTIMOgIGxhIG1vZGU=");
// → "✓ à la mode"
Utf8EncodeEnumerator 🧩
Converts a JavaScript string into a sequence of UTF-8 byte codes:
function Utf8EncodeEnumerator(input) {
this._input = input;
this._index = -1;
this._buffer = [];
}
Utf8EncodeEnumerator.prototype = {
current: Number.NaN,
moveNext: function() {
// If buffered bytes remain, shift out next
if (this._buffer.length > 0) {
this.current = this._buffer.shift();
return true;
}
// End of input
if (this._index >= this._input.length - 1) {
this.current = Number.NaN;
return false;
}
// Read next character, normalize CRLF to LF
var charCode = this._input.charCodeAt(++this._index);
if ((charCode == 13) && (this._input.charCodeAt(this._index + 1) == 10)) {
charCode = 10;
this._index++;
}
// Single-byte
if (charCode < 128) {
this.current = charCode;
}
// Two-byte
else if (charCode < 2048) {
this.current = (charCode >> 6) | 192;
this._buffer.push((charCode & 63) | 128);
}
// Three-byte
else {
this.current = (charCode >> 12) | 224;
this._buffer.push(((charCode >> 6) & 63) | 128);
this._buffer.push((charCode & 63) | 128);
}
return true;
}
};
Base64DecodeEnumerator 🔄
Reads a Base64 string four characters at a time and yields the original byte codes:
function Base64DecodeEnumerator(input) {
this._input = input;
this._index = -1;
this._buffer = [];
}
Base64DecodeEnumerator.prototype = {
current: 64,
moveNext: function() {
if (this._buffer.length > 0) {
this.current = this._buffer.shift();
return true;
}
if (this._index >= this._input.length - 1) {
return false;
}
// Read four Base64 chars
var enc1 = Base64.codex.indexOf(this._input.charAt(++this._index));
var enc2 = Base64.codex.indexOf(this._input.charAt(++this._index));
var enc3 = Base64.codex.indexOf(this._input.charAt(++this._index));
var enc4 = Base64.codex.indexOf(this._input.charAt(++this._index));
// Reconstruct bytes
var chr1 = (enc1 << 2) | (enc2 >> 4);
var chr2 = ((enc2 & 15) << 4) | (enc3 >> 2);
var chr3 = ((enc3 & 3) << 6) | enc4;
this.current = chr1;
if (enc3 !== 64) this._buffer.push(chr2);
if (enc4 !== 64) this._buffer.push(chr3);
return true;
}
};
Usage Examples 🔧
Include the script in your HTML:
<script src="new_2025_js/base64.js"></script>
<script>
var text = "Hello, 🌍!";
var encoded = Base64.encode(text);
var decoded = Base64.decode(encoded);
console.log(encoded, decoded);
</script>
- Encode:
Base64.encode(string) - Decode:
Base64.decode(base64String)
Integration & Dependencies 🔗
- Standalone: No external dependencies; attaches to global scope.
- Browser & Node.js: Can run in any JS environment supporting bitwise ops.
- Loading: Include via
<script>or require as static asset.
Related Implementations 🔍
Identical copies exist across the codebase:
linuxfront-v2-logistics/js/base64.jslinuxfront-v2/js/base64.jslinuxfront-v2/label_js/external/base64.js
This promotes reusability but suggests centralizing in one shared module 🎯 .
Contributing & Testing 🧪
- Unit Tests: Add tests for edge cases (e.g., invalid padding, non-ASCII).
- Error Handling: Currently silent on malformed input—consider throwing on unexpected chars.
- Refactoring: Modernize to ES6 classes and modules; use
Uint8ArrayandTextEncoder/TextDecoder.
Documentation generated from the source code of base64.js .