@alessiofrittoli/crypto-buffer

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
  • 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 = (
  | string
  | Array<number>
  | Buffer
  | ArrayBuffer
  | NodeJS.TypedArray
)

Parameters

Parameter	Type	Description
input	ToDataViewInput	The data to be converted into a DataView. Possible input Type can be:
		- string
		- Array<number> (array of bytes)
		- Buffer
		- ArrayBuffer
		- NodeJS.TypedArray

---

Returns

Type: DataView

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

---

Errors

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

---

Usage

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.

Parameters

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

---

Returns

Type: boolean

true if the buffers are equal, false otherwise.

---

Usage

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\

Parameters

Parameter	Type	Description
input	string	The string to be converted.

---

Returns

Type: Uint8Array

The function returns a new Uint8Array instance.

---

Usage

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.

Parameters

Parameter	Type	Description
input	string	The string to be converted.

---

Returns

Type: number[]

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

---

Usage

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.

Parameters

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

---

Returns

Type string

A string representation of the given input.

---

Example usage

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.

Parameters

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

---

Returns

Type string

The 0-1 converted binary sequence.

---

Example usage

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.

Parameters

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

---

Returns

Type Uint8Array

A new Uint8Array instance.

---

Example usage

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!'

---

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
  | Array<number>
  | DataView
  | Buffer
  | ArrayBuffer
  | NodeJS.TypedArray
)

Parameters

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

---

Returns

Type: Uint8Array

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

---

Usage

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 ) )

---

coerceToFloatArray

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

Parameters

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

---

Returns

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.

Parameters

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

---

Returns

Type: Float32Array

A new instance of Float32Array.

---

Usage

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.

Parameters

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

---

Returns

Type: Float64Array

A new instance of Float64Array.

---

Usage

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.

Parameters

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.

---

Returns

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.

Parameters

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

---

Returns

Type: BigInt64Array

A new instance of BigInt64Array.

---

Usage

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.

Parameters

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

---

Returns

Type: BigUint64Array

A new instance of BigUint64Array.

---

Usage

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 [e-mail] to disclose any security vulnerabilities.

Made with ☕

Alessio Frittoli https://alessiofrittoli.it | [e-mail]