Module @whiteflagprotocol/util

WFJSL Utility Classes and Functions

Overview

The Whiteflag JavaScript Library (WFJSL) is an implementation of the Whiteflag Protocol written in TypeScript, and compiled to JavaScript, to support the development of Whiteflag-enabled applications in JavaScript.

The @whiteflagprotocol/util package provides common utilities for other Whiteflag packages. These utilities include common data conversions, generic helper functions, etc. for other Whiteflag packages. It should normally not be necessary to add this package as a dependency, but its functionality might be useful for other purposes.

This description provides a generic overview of the WFJSL utility package. Please see the WFJSL TypeDoc documentation for a detailed description of all classes and functions.

BinaryBuffer class

The binary module of the Whiteflag utility package provides the BinaryBuffer class. Objects of this class represent a binary encoded piece of data, e.g. a Whiteflag message, that can be manipulated at bit level.

Static methods to create a binary buffer:

BinaryBuffer.empty(): creates an empty binary buffer
BinaryBuffer.from(...): creates a binary buffer from another binary buffer
BinaryBuffer.fromBytes(...): creates a binary buffer from bytes in a number array
BinaryBuffer.fromHex(...): creates a binary buffer from a hexadecimal string
BinaryBuffer.fromU8a(...): creates a binary buffer from a Uint8Array

Public methods to manipulate a binary buffer:

BinaryBuffer.append(...): appends another binary buffer to the end of the binary buffer
BinaryBuffer.crop(...): shortens the binary buffer to the length of the specified bits
BinaryBuffer.extract(...): extracts the specified bits from the binary buffer
BinaryBuffer.insert(...): inserts another binary buffer at the start of the binary buffer
BinaryBuffer.shiftLeft(...): shifts bits in the buffer to the left, shrinking the buffer
BinaryBuffer.shiftRight(...): shifts bits in the buffer to the right, enlarging the buffer

Some of these functions have an equivalent that allow to use a different binary representation, e.g. appendHex(...) or insertU8a(...).

Data conversions

The encoding module provides generic functions to convert data from one encoding to another.

Encoding	Description	Converts to
Base64	a string with a 64-character binary-to-text encoding	Base64url
Base64url	a string with a URL-safe 64-character binary-to-text encoding	Base64, Hexadecimal, String, UInt8Array
Hexadecimal	a string with a hexadecimal representation of a binary	Base64url, String, UInt8Array
Object	a plain JavaScript object	Base64url
Text	a string with UTF-8 characters	Base64url, Hexadecimal, UInt8Array
UInt8Array	an array of bytes representing a binary encoding	Base64url, Hexadecimal, String

For example hexToB64u(...) creates a base64url encoded string from a hexadecimal string. The module also provides some additional helper functions for different data encodings:

isObject(...) checks if something is an object
isString(...) checks if something is a string
isBase64(...) checks if a string is base64 encoded
isBase64u(...) checks if a string is base64url encoded
isHex(...) checks if a string is hexadecimal encoded
noHexPrefix(...) removes the '0x' hex prefix if present

JSON Web Signature (JWS)

Whiteflag uses JSON Web Signatures (JWS). To create, sign and convert JWSs the jws module provides a common Jws class to other Whiteflag packages.

Classes

BinaryBuffer
Jws