@alessiofrittoli/crypto-buffer v3.6.3

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
)

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.

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\

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.

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.

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.

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.

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

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
)

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

coerceToFloatArray

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

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.

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.

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.

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.

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.

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 security@alessiofrittoli.it to disclose any security vulnerabilities.

Made with ☕