Crypto Buffer 🚌

Lightweight TypeScript Node.js Buffers utility library

Table of Contents

• Getting started
• Utilities
  • toDataView
  • Common Utilities
    • bufferEquals
  • Conversion Utilities
    • stringToBinary
    • stringToBytes
    • binaryToString
    • unicodeToBinarySequence
    • binarySequenceToUint8Array
    • writeUint16BE
    • readUint16BE
    • writeUint32BE
    • readUint32BE
  • Coercion Utilities
    • coerceToUint8Array
    • coerceToFloatArray
    • coerceToFloat32Array
    • coerceToFloat64Array
    • coerceToBigArray
    • coerceToBigInt64Array
    • coerceToBigUint64Array
• Development
  • Install depenendencies
  • Build the source code
  • ESLint
  • Jest
  • Contributing
  • Security
• Credits

Getting started

Run the following command to start using crypto-buffer in your projects:

npm i @alessiofrittoli/crypto-buffer

or using pnpm

pnpm i @alessiofrittoli/crypto-buffer

Utilities

toDataView

The toDataView function is a utility designed to convert various data types into a DataView. It ensures compatibility with a wide range of input formats, including strings, arrays, typed arrays, and buffers, providing a DataView representation of the given data.

Input Type

type ToDataViewInput = CoerceToUint8ArrayInput;

• See CoerceToUint8ArrayInput

| Parameter | Type | Description | | --------- | ----------------- | ------------------------------------------- | | input | ToDataViewInput | The data to be converted into a DataView. |

Type: DataView

The function returns a DataView object created from the input data.

Throws a TypeError if the input does not match any of the supported types.

Converting a String to DataView

import { toDataView } from "@alessiofrittoli/crypto-buffer";
// or
import { toDataView } from "@alessiofrittoli/crypto-buffer/toDataView";

const data = "Hello, World!";
const view = toDataView(data);

console.log(view.byteLength); // Logs the byte length of the string.

Converting a Uint8Array to DataView

import { toDataView } from "@alessiofrittoli/crypto-buffer";
// or
import { toDataView } from "@alessiofrittoli/crypto-buffer/toDataView";

const data = new Uint8Array([1, 2, 3, 4]);
const view = toDataView(data);

console.log(view.getUint8(0)); // Logs 1

Handling Invalid Input

import { toDataView } from "@alessiofrittoli/crypto-buffer";
// or
import { toDataView } from "@alessiofrittoli/crypto-buffer/toDataView";

try {
  const invalidInput = { foo: "bar" };
  const view = toDataView(invalidInput);
} catch (error) {
  console.error(error.message); // Expected `input` to be a Expected `input` to be a string, Array<number>, ...
}

Common Utilities

bufferEquals

The bufferEquals function leverages the coerceToUint8Array utility function to normalize input data into Uint8Array objects for consistent byte-level comparison.

It first checks the byte lengths of the two buffers to ensure they are identical. If the lengths match, it performs a byte-by-byte comparison.

| Parameter | Type | Description | | --------- | ------------------------- | ------------------------------------------- | | buffer1 | CoerceToUint8ArrayInput | The first input to compare. | | buffer2 | CoerceToUint8ArrayInput | The second input to compare with buffer1. |

Type: boolean

true if the buffers are equal, false otherwise.

Convert a String in a Node.js Environment

import { bufferEquals } from "@alessiofrittoli/crypto-buffer";
// or
import { bufferEquals } from "@alessiofrittoli/crypto-buffer/common";

const buffer1 = new Uint8Array([1, 2, 3]);
const buffer2 = new Uint8Array([1, 2, 3]);
const buffer3 = new Uint8Array([4, 5, 6]);

console.log(bufferEquals(buffer1, buffer2)); // true
console.log(bufferEquals(buffer1, buffer3)); // false

Conversion Utilities

stringToBinary

The stringToBinary function is a utility for converting a string into a Uint8Array\

| Parameter | Type | Description | | --------- | -------- | --------------------------- | | input | string | The string to be converted. |

Type: Uint8Array

The function returns a new Uint8Array instance.

Convert a String to binary data

import { stringToBinary } from "@alessiofrittoli/crypto-buffer";
// or
import { stringToBinary } from "@alessiofrittoli/crypto-buffer/conversion";

const data = "Hello, World!";
const binary = stringToBinary(data);

console.log(new TextDecoder().decode(binary));
// Outputs: 'Hello, World!'

stringToBytes

The stringToBytes function converts a string into an Array of bytes (number[]). It leverages the stringToBinary utility to handle string-to-binary conversion, ensuring compatibility with both browser and Node.js environments. The resulting array represents the byte values of the input string.

| Parameter | Type | Description | | --------- | -------- | --------------------------- | | input | string | The string to be converted. |

Type: number[]

The function returns an array of bytes (number[]), where each element represents a single byte of the input string.

Convert a String to Bytes

import { stringToBytes } from "@alessiofrittoli/crypto-buffer";
// or
import { stringToBytes } from "@alessiofrittoli/crypto-buffer/conversion";

const data = "Hello";
const bytes = stringToBytes(data);

console.log(bytes); // [ 72, 101, 108, 108, 111 ] (ASCII values of 'Hello')

binaryToString

The binaryToString function converts various binary data types into their string representations.
It is designed to be cross-platform, working in both Node.js and browser environments.

| Parameter | Type | Description | | --------- | ------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | | input | CoerceToUint8ArrayInput | The binary data to be converted to a string. See coerceToUint8Array for a list of possible input data types. |

Type string

A string representation of the given input.

Node.js

import { binaryToString } from "@alessiofrittoli/crypto-buffer";
// or
import { binaryToString } from "@alessiofrittoli/crypto-buffer/conversion";

console.log(binaryToString(Buffer.from("Hello, World!")));
// Outputs: 'Hello, World!'

Browser

import { binaryToString, stringToBytes } from "@alessiofrittoli/crypto-buffer";
// or
import {
  binaryToString,
  stringToBytes,
} from "@alessiofrittoli/crypto-buffer/conversion";

const uint8Array = new Uint8Array(stringToBytes("Hello!"));
console.log(binaryToString(uint8Array));
// Outputs: 'Hello!'

unicodeToBinarySequence

The unicodeToBinarySequence function converts unicode characters to a 0-1 binary sequence.

| Parameter | Type | Description | | --------- | ------------------------- | ----------------------------------------------------------------------------------------------------------- | | input | CoerceToUint8ArrayInput | The data to convert. See coerceToUint8Array for a list of possible input data types. |

Type string

The 0-1 converted binary sequence.

import { unicodeToBinarySequence } from "@alessiofrittoli/crypto-buffer";
// or
import { unicodeToBinarySequence } from "@alessiofrittoli/crypto-buffer/conversion";

console.log(unicodeToBinarySequence("Hello world!"));
// Outputs: '01001000 01100101 01101100 01101100 01101111 00100000 01110111 01101111 01110010 01101100 01100100 00100001'

console.log(unicodeToBinarySequence("Hello world!", "-"));
// Outputs: '01001000-01100101-01101100-01101100-01101111-00100000-01110111-01101111-01110010-01101100-01100100-00100001'

binarySequenceToUint8Array

The binarySequenceToUint8Array function converts a 0-1 binary sequence to Uint8Array.

| Parameter | Type | Description | | --------- | ------------------------- | ----------------------------------------------------------------------------------------------------------- | | input | CoerceToUint8ArrayInput | The data to convert. See coerceToUint8Array for a list of possible input data types. |

Type Uint8Array

A new Uint8Array instance.

import { binarySequenceToUint8Array } from "@alessiofrittoli/crypto-buffer";
// or
import { binarySequenceToUint8Array } from "@alessiofrittoli/crypto-buffer/conversion";

console.log(
  binaryToString(
    binarySequenceToUint8Array(
      "01001000 01100101 01101100 01101100 01101111 00100000 01110111 01101111 01110010 01101100 01100100 00100001"
    )
  )
);
// Outputs: 'Hello world!'

console.log(
  binaryToString(
    binarySequenceToUint8Array(
      "01001000-01100101-01101100-01101100-01101111-00100000-01110111-01101111-01110010-01101100-01100100-00100001",
      "-"
    )
  )
);
// Outputs: 'Hello world!'

writeUint16BE

Writes a 16-bit unsigned integer to a new Buffer in big-endian format.

| Parameter | Type | Description | | --------- | -------- | --------------------------------------------------- | | value | number | The 16-bit unsigned integer to write to the buffer. |

Type: Buffer

A Buffer containing the big-endian representation of the input value.

import { writeUint16BE } from "@alessiofrittoli/crypto-buffer";
// or
import { writeUint16BE } from "@alessiofrittoli/crypto-buffer/conversion";

console.log(writeUint16BE(0xffff));
// Outputs: <Buffer ff ff>

readUint16BE

Reads an unsigned 16-bit integer from the given buffer at the specified offset using big-endian byte order.

| Parameter | Type | Default | Description | | --------- | -------- | ------- | ---------------------------------------------------------- | | buffer | number | - | The buffer to read from. | | offset | number | 0 | (Optional) The offset in the buffer to start reading from. |

Type: number

The unsigned 16-bit integer read from the buffer.

import { readUint16BE } from "@alessiofrittoli/crypto-buffer";
// or
import { readUint16BE } from "@alessiofrittoli/crypto-buffer/conversion";

console.log(readUint16BE(Buffer.from([0x12, 0x34])));
// Outputs: 0x1234

writeUint32BE

Writes a 32-bit unsigned integer to a new Buffer in big-endian format.

| Parameter | Type | Description | | --------- | -------- | --------------------------------------------------- | | value | number | The 32-bit unsigned integer to write to the buffer. |

Type: Buffer

A Buffer containing the big-endian representation of the input value.

import { writeUint32BE } from "@alessiofrittoli/crypto-buffer";
// or
import { writeUint32BE } from "@alessiofrittoli/crypto-buffer/conversion";

console.log(writeUint32BE(0xffffffff));
// Outputs: <Buffer ff ff ff ff>

readUint32BE

Reads an unsigned 32-bit integer from the given buffer at the specified offset using big-endian byte order.

| Parameter | Type | Default | Description | | --------- | -------- | ------- | ---------------------------------------------------------- | | buffer | number | - | The buffer to read from. | | offset | number | 0 | (Optional) The offset in the buffer to start reading from. |

Type: number

The unsigned 32-bit integer read from the buffer.

import { readUint32BE } from "@alessiofrittoli/crypto-buffer";
// or
import { readUint32BE } from "@alessiofrittoli/crypto-buffer/conversion";

console.log(readUint32BE(Buffer.from([0x12, 0x34, 0x56, 0x78])));
// Outputs: 0x12345678

Coercion Utilities

This module provides a set of utility functions for coercing data into specific array types, such as Uint8Array, Float32Array, Float64Array, BigInt64Array, and BigUint64Array.
It supports various input types and ensures compatibility across different data representations.

coerceToUint8Array

Coerces input data into a Uint8Array.

Input Type

type CoerceToUint8ArrayInput =
  | string
  | number
  | bigint
  | Array<number>
  | Buffer
  | ArrayBufferLike
  | ArrayBufferView
  | NodeJS.ArrayBufferView;

| Parameter | Type | Description | | --------- | ------------------------- | ------------------------------------------------------ | | input | CoerceToUint8ArrayInput | The input data to convert. Possible input Type can be: | | | | - string | | | | - number (will be automatically converted to string) | | | | - bigint (will be automatically converted to string) | | | | - Array<number> (array of bytes) | | | | - Buffer | | | | - ArrayBufferLike | | | | - ArrayBufferView | | | | - NodeJS.ArrayBufferView |

Type: Uint8Array

The function returns a new Uint8Array instance created from the input data.

Converting a String to Uint8Array

import { coerceToUint8Array } from "@alessiofrittoli/crypto-buffer";
// or
import { coerceToUint8Array } from "@alessiofrittoli/crypto-buffer/coercion";

const buffer = coerceToUint8Array("Hello, World!");

Converting a DataView to Uint8Array

import { coerceToUint8Array } from "@alessiofrittoli/crypto-buffer";
// or
import { coerceToUint8Array } from "@alessiofrittoli/crypto-buffer/coercion";
import { toDataView } from "@alessiofrittoli/crypto-buffer/toDataView";
import { stringToBinary } from "@alessiofrittoli/crypto-buffer/conversion";

const view = toDataView(stringToBinary("Hello, World!"));

console.log(coerceToUint8Array(view));

coerceToInt16Array

Coerces input data into a Int16Array.

| Parameter | Type | Description | | --------- | ------------------------- | -------------------------------------------------------------------------------------------------- | | input | CoerceToUint8ArrayInput | The input data to convert. See CoerceToUint8ArrayInput for accepted data types. |

Type: Int16Array

The function returns a new Int16Array instance created from the input data.

coerceToUint16Array

Coerces input data into a Uint16Array.

| Parameter | Type | Description | | --------- | ------------------------- | -------------------------------------------------------------------------------------------------- | | input | CoerceToUint8ArrayInput | The input data to convert. See CoerceToUint8ArrayInput for accepted data types. |

Type: Uint16Array

The function returns a new Uint16Array instance created from the input data.

coerceToInt32Array

Coerces input data into a Int32Array.

| Parameter | Type | Description | | --------- | ------------------------- | -------------------------------------------------------------------------------------------------- | | input | CoerceToUint8ArrayInput | The input data to convert. See CoerceToUint8ArrayInput for accepted data types. |

Type: Int32Array

The function returns a new Int32Array instance created from the input data.

coerceToUint32Array

Coerces input data into a Uint32Array.

| Parameter | Type | Description | | --------- | ------------------------- | -------------------------------------------------------------------------------------------------- | | input | CoerceToUint8ArrayInput | The input data to convert. See CoerceToUint8ArrayInput for accepted data types. |

Type: Uint32Array

The function returns a new Uint32Array instance created from the input data.

coerceToSharedArrayBuffer

Coerces input data into a SharedArrayBuffer.

| Parameter | Type | Description | | --------- | ------------------------- | -------------------------------------------------------------------------------------------------- | | input | CoerceToUint8ArrayInput | The input data to convert. See CoerceToUint8ArrayInput for accepted data types. |

Type: SharedArrayBuffer

The function returns a new SharedArrayBuffer instance created from the input data.

coerceToFloatArray

Coerces input data into a Float32Array or Float64Array, based on the specified bit size.

| Parameter | Type | Description | | --------- | ------------------------- | ----------------------------------------------------------------------------------------------------------------- | | input | CoerceToUint8ArrayInput | The input data to convert. See coerceToUint8Array for a list of possible input data types. | | bit | 32 \| 64 | Specifies whether to return a Float32Array (32-bit) or Float64Array (64-bit). |

Type: Float32Array | Float64Array

A new instance of the respective float array type.

coerceToFloat32Array

A specialized version of coerceToFloatArray that coerces input data into a Float32Array.

| Parameter | Type | Description | | --------- | ------------------------- | ----------------------------------------------------------------------------------------------------------------- | | input | CoerceToUint8ArrayInput | The input data to convert. See coerceToUint8Array for a list of possible input data types. |

Type: Float32Array

A new instance of Float32Array.

import { coerceToFloat32Array } from "@alessiofrittoli/crypto-buffer";
// or
import { coerceToFloat32Array } from "@alessiofrittoli/crypto-buffer/coercion";

const float32Array = coerceToFloat32Array("Hello, World!");

coerceToFloat64Array

A specialized version of coerceToFloatArray that coerces input data into a Float64Array.

| Parameter | Type | Description | | --------- | ------------------------- | ----------------------------------------------------------------------------------------------------------------- | | input | CoerceToUint8ArrayInput | The input data to convert. See coerceToUint8Array for a list of possible input data types. |

Type: Float64Array

A new instance of Float64Array.

import { coerceToFloat64Array } from "@alessiofrittoli/crypto-buffer";
// or
import { coerceToFloat64Array } from "@alessiofrittoli/crypto-buffer/coercion";

const float64Array = coerceToFloat64Array("Hello, World!");

coerceToBigArray

Coerces input data into a BigInt64Array or BigUint64Array based on the isUnsigned parameter.

| Parameter | Type | Description | | ------------ | ------------------------- | ----------------------------------------------------------------------------------------------------------------- | | input | CoerceToUint8ArrayInput | The input data to convert. See coerceToUint8Array for a list of possible input data types. | | isUnsigned | boolean | If true, returns a BigUint64Array, BigInt64Array otherwise. |

Type: BigInt64Array | BigUint64Array

A new instance of the respective big integer array type.

coerceToBigInt64Array

A specialized version of coerceToFloatArray that coerces input data into a BigInt64Array.

| Parameter | Type | Description | | --------- | ------------------------- | ----------------------------------------------------------------------------------------------------------------- | | input | CoerceToUint8ArrayInput | The input data to convert. See coerceToUint8Array for a list of possible input data types. |

Type: BigInt64Array

A new instance of BigInt64Array.

import { coerceToBigInt64Array } from "@alessiofrittoli/crypto-buffer";
// or
import { coerceToBigInt64Array } from "@alessiofrittoli/crypto-buffer/coercion";

const bigInt64Array = coerceToBigInt64Array("Hello, World!");

coerceToBigUint64Array

A specialized version of coerceToFloatArray that coerces input data into a BigUint64Array.

| Parameter | Type | Description | | --------- | ------------------------- | ----------------------------------------------------------------------------------------------------------------- | | input | CoerceToUint8ArrayInput | The input data to convert. See coerceToUint8Array for a list of possible input data types. |

Type: BigUint64Array

A new instance of BigUint64Array.

import { coerceToBigUint64Array } from "@alessiofrittoli/crypto-buffer";
// or
import { coerceToBigUint64Array } from "@alessiofrittoli/crypto-buffer/coercion";

const bigUint64Array = coerceToBigUint64Array("Hello, World!");

Development

Install depenendencies

npm install

or using pnpm

pnpm i

Build the source code

Run the following command to test and build code for distribution.

pnpm build

ESLint

warnings / errors check.

pnpm lint

Jest

Run all the defined test suites by running the following:

# Run tests and watch file changes.
pnpm test:watch

# Run tests in a CI environment.
pnpm test:ci

• See package.json file scripts for more info.

Run tests with coverage.

An HTTP server is then started to serve coverage files from ./coverage folder.

⚠️ You may see a blank page the first time you run this command. Simply refresh the browser to see the updates.

test:coverage:serve

Contributing

Contributions are truly welcome!

Please refer to the Contributing Doc for more information on how to start contributing to this project.

Help keep this project up to date with GitHub Sponsor.

Security

If you believe you have found a security vulnerability, we encourage you to responsibly disclose this and NOT open a public issue. We will investigate all legitimate reports. Email [email protected] to disclose any security vulnerabilities.

Made with ☕