Nuclear Pumpkin Mayhem

    @diplomatiq/convertibles
    TypeScript icon, indicating that this package has built-in type declarations

    2.0.0 • Public • Published

    TypeScript utility library to convert values between textual and binary representation.

    build status languages used downloads from npm latest released version on npm license Dependabot


    Installation

    Being an npm package, you can install convertibles with the following command:

    npm install -P @diplomatiq/convertibles

    Testing

    Run tests with the following:

    npm test

    Goals

    This module is built with the intention to help:

    • encode a source value into a better-suited serialization format,
    • decode the serialized format and get the source value back.

    For example, you have a meaningful Unicode string value as the source value. This source value is what your application works with, this is what your business logic is built upon.

    Sometimes you want to store or transmit this source value in different formats. You want to encode the source value into something less complex and better manageable target value, like:

    • a byte array (e.g. for storing it in binary structures),
    • a Base64 string (e.g. for transmitting it as the part of a JSON payload),
    • or a Base64URL string (e.g. for storing it as a filename or putting it into a URL).

    Supported source and target formats

    Currently the following source formats are supported.

    Source format to/from Uint8Array to/from Base64 to/from Base64URL to/from hex
    Unicode string ✔️ ✔️ ✔️ *
    Uint8Array ✔️ ✔️ ✔️

    * Of course, no one stops you from converting a Unicode string into a Uint8Array, then to hex.

    Usage

    Note: This package is built as an ES6 package. You will not be able to use require().

    Every source format has a converter class:

    • for Unicode strings, use the DefaultStringConverter class,
    • for byte arrays, use the DefaultBinaryConverter class.

    Besides converters, there are transformers, which does not really convert, but rather just minimally transform:

    • to transform a Base64 value to/from Base64URL, use the DefaultBase64UrlTransformer class.

    After installation, import the appropriate class into your project, and use its API after instantiation:

    import { DefaultStringConverter } from '@diplomatiq/convertibles';
    
    // …
    
    function main() {
        const source = 'Dįplőmàtiq Å & Å is effective.';
    
        const stringConverter = new DefaultStringConverter();
    
        const asBytes = stringConverter.encodeToBytes(source);
        console.log(asBytes); // Uint8Array(41) [68, 105, 204, …]
        console.log(stringConverter.decodeFromBytes(asBytes)); // 'Dįplőmàtiq Å & Å is effective.'
    
        const asBase64 = stringConverter.encodeToBase64(source);
        console.log(asBase64); // 'RGnMqHBsb8yLbWHMgHRpcSBBzIogJiBBzIogaXMgZe+sgGVjdGl2ZS4='
        console.log(stringConverter.decodeFromBase64(asBase64)); // 'Dįplőmàtiq Å & Å is effective.'
    
        const asBase64Url = stringConverter.encodeToBase64Url(source);
        console.log(asBase64Url); // 'RGnMqHBsb8yLbWHMgHRpcSBBzIogJiBBzIogaXMgZe-sgGVjdGl2ZS4'
        console.log(stringConverter.decodeFromBase64Url(asBase64Url)); // 'Dįplőmàtiq Å & Å is effective.'
    }

    API

    DefaultStringConverter

    Instantiation

    You can inject your own UTF-8 encoder/decoder, binary converter, or Base64URL transformer, as long as they implement the required interfaces.

    constructor(
      private readonly utf8Encoder: Utf8Encoder = new TextEncoder(),
      private readonly utf8Decoder: Utf8Decoder = new TextDecoder('utf-8', { fatal: true }),
      private readonly binaryConverter: BinaryConverter = new DefaultBinaryConverter(),
      private readonly base64UrlTransformer: Base64UrlTransformer = new DefaultBase64UrlTransformer(),
    ) {}

    Instantiated without constructor parameters, DefaultStringConverter will use the defaults:

    const stringConverter = new DefaultStringConverter();

    encodeToBytes(string: string): Uint8Array;

    /**
     * Encodes a Unicode string into UTF-8 binary representation.
     * Symmetric to @member decodeFromBytes.
     * Does not throw.
     */
    encodeToBytes(string: string): Uint8Array;

    decodeFromBytes(bytes: Uint8Array): string;

    /**
     * Decodes the UTF-8 binary representation of a Unicode string.
     * Symmetric to @member encodeToBytes.
     * Throws if decoding is unsuccessful.
     */
    decodeFromBytes(bytes: Uint8Array): string;

    encodeToBase64(string: string): string;

    /**
     * Encodes a Unicode string into Base64.
     * Symmetric to @member decodeFromBase64.
     * Does not throw.
     *
     * This method is not equivalent to window.btoa, as it accepts arbitrary
     * Unicode strings as input rather than only supporting Windows-1252. The
     * Base64 string result of this method is the Base64 representation of the
     * UTF-8 binary representation of the encoded Unicode string.
     *
     * This method is not symmetric to window.atob. While window.atob is always
     * able to decode the result of this method, the result will not be equal
     * to the originally encoded string for any character set wider than
     * the original ASCII ([0x00-0x7f]).
     */
    encodeToBase64(string: string): string;

    decodeFromBase64(base64: string): string;

    /**
     * Decodes a Base64-encoded Unicode string.
     * Symmetric to @member encodeToBase64.
     * Throws if decoding is unsuccessful.
     *
     * This method is not equivalent to window.atob. The string result of this
     * method is a Unicode string, decoded from the UTF-8 binary representation
     * (which was encoded as Base64) of the original string.
     *
     * This method is not symmetric to window.btoa. Since window.btoa requires
     * its input to be a binary string, effectively it can only encode
     * characters from the Windows-1252 character set. While this method is
     * always able to decode the result of window.btoa, the result will not be
     * equal to the originally encoded string for any character set wider than
     * the original ASCII ([0x00-0x7f]).
     */
    decodeFromBase64(base64: string): string;

    encodeToBase64Url(string: string): string;

    /**
     * Encodes a Unicode string into (URL- and filename-safe) Base64URL format.
     * Symmetric to @member decodeFromBase64Url.
     * Does not throw.
     */
    encodeToBase64Url(string: string): string;

    decodeFromBase64Url(base64url: string): string;

    /**
     * Decodes a (URL- and filename-safe) Base64URL-encoded Unicode string.
     * Symmetric to @member encodeToBase64Url.
     * Throws if decoding is unsuccessful.
     */
    decodeFromBase64Url(base64url: string): string;

    DefaultBinaryConverter

    Instantiation

    You can inject your own Base64URL transformer, as long as it implements the required interface.

    constructor(
      private readonly base64UrlTransformer: Base64UrlTransformer = new DefaultBase64UrlTransformer(),
    ) {}

    Instantiated without constructor parameters, DefaultBinaryConverter will use the defaults:

    const binaryConverter = new DefaultBinaryConverter();

    encodeToHex(bytes: Uint8Array): string;

    /**
     * Encodes a binary representation into a hexadecimal string.
     * Does not throw.
     */
    encodeToHex(bytes: Uint8Array): string;

    decodeFromHex(hex: string): Uint8Array;

    /**
     * Decodes a hexadecimal string into a binary representation.
     * Throws if decoding is unsuccessful.
     */
    decodeFromHex(hex: string): Uint8Array;

    encodeToBase64(bytes: Uint8Array): string;

    /**
     * Encodes a binary representation into Base64 format.
     * Does not throw.
     */
    encodeToBase64(bytes: Uint8Array): string;

    decodeFromBase64(base64: string): Uint8Array;

    /**
     * Decodes a Base64-encoded binary representation.
     * Throws if decoding is unsuccessful.
     */
    decodeFromBase64(base64: string): Uint8Array;

    encodeToBase64Url(bytes: Uint8Array): string;

    /**
     * Encodes a binary representation into (URL- and filename-safe) Base64URL format.
     */
    encodeToBase64Url(bytes: Uint8Array): string;

    decodeFromBase64Url(base64Url: string): Uint8Array;

    /**
     * Decodes a (URL- and filename-safe) Base64URL-encoded binary representation.
     */
    decodeFromBase64Url(base64Url: string): Uint8Array;

    DefaultBase64UrlTransformer

    transformBase64ToBase64Url(base64: string): string;

    /**
     * Transforms a Base64 representation to Base64URL.
     * Symmetric to @member transformBase64UrlToBase64.
     */
    transformBase64ToBase64Url(base64: string): string;

    transformBase64UrlToBase64(base64Url: string): string;

    /**
     * Transforms a Base64URL representation to Base64.
     * Symmetric to @member transformBase64ToBase64Url.
     */
    transformBase64UrlToBase64(base64Url: string): string;

    Development

    See CONTRIBUTING.md for details.


    Copyright (c) 2018 Diplomatiq

    Install

    npm i @diplomatiq/convertibles

    DownloadsWeekly Downloads

    3

    Version

    2.0.0

    License

    MIT

    Unpacked Size

    29.2 kB

    Total Files

    22

    Last publish

    Collaborators

    • luczsoma