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 string to 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 codex and accumulate.
Base64.encode("✓ à la mode");
// → "4pyTIMOgIGxhIG1vZGU=" 

decode(input)

Reverses Base64 back into the original string:

  • Step 1: Use Base64DecodeEnumerator to read decoded byte codes.
  • Step 2: For each byte:
    • If < 128, append directly.
    • If between 192 and 223, combine two-byte sequences.
    • Else combine three-byte sequences.
  • 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.

Identical copies exist across the codebase:

  • linuxfront-v2-logistics/js/base64.js
  • linuxfront-v2/js/base64.js
  • linuxfront-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 Uint8Array and TextEncoder/TextDecoder.

Documentation generated from the source code of base64.js .