@unikvs/base64

How to use @unikvs/base64, middleware that encodes bytes as base64.

Overview

Middleware that returns bytes as a base64 string. Middleware

It supports both padded and unpadded forms, and accepts either form when decoding.

• name is "Base64".
• isOpen is always true.

Install with:

npm install @unikvs/base64

pnpm add @unikvs/base64

yarn add @unikvs/base64

bun add @unikvs/base64

nub add @unikvs/base64

aube add @unikvs/base64

Usage

Base64 implements IMiddleware. Pass it to UniKvs with use().

import { Base64 } from "@unikvs/base64";

Constructor arguments:

The following example stores bytes as base64 and restores the original bytes on read.

import { Base64 } from "@unikvs/base64";
import { Memory } from "@unikvs/memory";
import * as unikvs from "unikvs";

const kvs = new unikvs.Builder<{ file: unikvs.Value<Uint8Array> }>()
  .use(new Base64())
  .persist(new Memory())
  .build();

await kvs.open();
await kvs.set("file", new Uint8Array([0x01, 0x02, 0x03]));
const file = await kvs.get("file");
await kvs.close();

Data types

• encode converts bytes to a base64 string and encodes it as UTF-8 bytes.
• decode converts base64-encoded bytes back to the original bytes.
• Decoding accepts both padded and unpadded forms.
• encodeStream splits input into 3-byte units, carrying remainders across chunks.
• Encode remainders are finalized when the stream ends.
• decodeStream restores 4 characters at a time, carrying remainders to the next call.
• A padded trailing sequence is validated and restored when the stream ends.

Errors

Errors thrown by this package:

Base64DecodeError

Meaning

Thrown when the input cannot be interpreted as base64. This covers invalid characters, misplaced = padding, and inputs whose length remainder is 1.

How to fix

Make sure the input is valid base64.

A TypeError propagates unchanged when trailing partial UTF-8 bytes remain at the end of a stream.

Base64InvalidPaddingError

Thrown when the padding option is not a boolean.

Meaning

Because this is a usage error, it extends InvalidUsageErrorBase. meta.actual keeps the specified value as-is.

How to fix

Specify true or false for padding. It defaults to true.