Crypto Buffer 🚌

Version 2.0.1

Lightweight TypeScript Node.js Buffers utility library

Table of Contents

• Getting started
• Utilities
  • toDataView
  • Common Utilities
    • bufferEquals
  • Conversion Utilities
    • stringToBinary
    • stringToBytes
    • binaryToString
• 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>
	| ArrayLike<number>
	| Buffer
	| ArrayBuffer
	| ArrayBufferLike
	| Int8Array
	| Int16Array
	| Int32Array
	| Uint8Array
	| Uint16Array
	| Uint32Array
	| Uint8ClampedArray
)

| Parameter | Type | Description | |-----------|-------------------|-------------------------------------------------------------------------| | input | ToDataViewInput | The data to be converted into a DataView. Possible input Type can be: | | | | - string | | | | - Array<number> | | | | - ArrayLike<number> | | | | - Buffer | | | | - ArrayBuffer | | | | - ArrayBufferLike | | | | - Int8Array | | | | - Int16Array | | | | - Int32Array | | | | - Uint8Array | | | | - Uint16Array | | | | - Uint32Array | | | | - Uint8ClampedArray |

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 toDataView utility to normalize input buffers into DataView 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 using the getUint8 method of DataView.

| Parameter | Type | Description | |-----------|-------------------|----------------------------------------------| | buffer1 | ToDataViewInput | The first buffer to compare. | | buffer1 | ToDataViewInput | The second buffer 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 | BinaryToStringInput | The binary data to be converted to a string. | | | | - Array<number> - A simple array of bytes. | | | | - Buffer - Node.js buffer instance. | | | | - ArrayBuffer - Generic buffer for binary data. | | | | - Int8Array | | | | - Int16Array | | | | - Int32Array | | | | - Uint8Array | | | | - Uint16Array | | | | - Uint32Array | | | | - Uint8ClampedArray |

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

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 ☕