@unikvs/base64url

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

Overview

Middleware that returns bytes as a URL-safe base64url string. Middleware

It avoids + and /, making it suitable for URLs and file names. It supports both padded and unpadded forms, and accepts either form when decoding.

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

Install with:

npm install @unikvs/base64url

pnpm add @unikvs/base64url

yarn add @unikvs/base64url

bun add @unikvs/base64url

nub add @unikvs/base64url

aube add @unikvs/base64url

Usage

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

import { Base64Url } from "@unikvs/base64url";

Constructor arguments:

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

import { Base64Url } from "@unikvs/base64url";
import { Memory } from "@unikvs/memory";
import * as unikvs from "unikvs";

const kvs = new unikvs.Builder<{ file: unikvs.Value<Uint8Array> }>()
  .use(new Base64Url())
  .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 base64url string and encodes it as UTF-8 bytes.
• decode converts base64url-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:

Base64UrlDecodeError

Meaning

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

How to fix

Make sure the input is valid base64url.

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

Base64UrlInvalidPaddingError

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 false.