nish/base64

Standard base64 (RFC 4648 §4) with = padding, the encoding kitty graphics frames are sent in.

import {
  base64Encode,
  base64EncodeInto,
  base64EncodedLength,
} from "nish/base64";
import { base64Encode, base64EncodeInto, base64EncodedLength } from "nish/base64";

export const main = (): i32 => {
  const hi: u8[] = [72, 105];                    // "Hi"
  const text: string = base64Encode(hi);         // "SGk="
  const out: u8[] = new Array<u8>(base64EncodedLength(2) + 1);
  const end: i32 = base64EncodeInto(hi, 0, 2, out, 1); // out[1..5) is "SGk=", end is 5
  return end;
};
The alphabet is `A-Z a-z 0-9 + /`

Every three bytes become four characters, and a final group of one or two bytes becomes two or three characters filled out to four with = (RFC 4648 §4, the padding rules of §3.2), so the text is always a multiple of four long.

  • base64EncodedLength(n) is the characters n bytes encode to.
  • base64EncodeInto(src, off, len, dst, at) writes the encoding of src[off..off+len) into dst from at and allocates nothing, so a frame can be encoded chunk by chunk straight into its output buffer.
  • base64Encode(bytes) is the whole array as a string.
This module only encodes

what it is for writes base64 and never reads it back. It is not the strict decoder of nish/crypto/base64url, which is a different alphabet without padding and is written not to branch on the data; what goes through here is pixels, not secrets, so a sextet becomes its character by indexing the alphabet. The output is ASCII, so the string is the same bytes natively and under Node.

Private helpers carry the module's name

Private helpers carry the module's name because they share the importing program's flat symbol namespace (docs/wp26-stdlib.md §3e).

Functions

base64Encode

bytes as padded base64. Panics past 1,610,612,733 bytes, whose encoding would not fit a string.

const base64Encode: (bytes: u8[]) => string
bytesu8[]required

The bytes to encode, all of them; an empty array answers "".

returnsstring

A fresh string holding the padded encoding.

base64EncodeInto

Write the base64 of src[off..off+len) into dst from index at, and answer the index just past the last character written, which is at + base64EncodedLength(len). Nothing is allocated. Panics when the source range is not inside src or the encoding does not fit in dst from at; both are checked before anything is written.

const base64EncodeInto: (
  src: u8[],
  off: i32,
  len: i32,
  dst: u8[],
  at: i32,
) => i32
srcu8[]required

The bytes to encode from; only src[off..off+len) is read.

offi32required

Where in src the bytes to encode start.

leni32required

How many bytes of src to encode; zero writes nothing and answers at.

dstu8[]required

The buffer the characters are written into, one ASCII byte per character; bytes outside the written range are left as they were.

ati32required

Where in dst the first character goes.

returnsi32

The index in dst just past the last character written.

base64EncodedLength

The characters n bytes encode to: four for every three, a short final group counted as a whole one. Panics when n is negative or the length would pass 2^31 - 1, which n above 1,610,612,733 does.

const base64EncodedLength: (n: i32) => i32
ni32required

How many bytes are to be encoded; zero answers zero.

returnsi32

The number of base64 characters, padding included, that n bytes encode to: always a multiple of four.