Crypto Buffer 🚌

Lightweight TypeScript Node.js Buffers utility library

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

Parameters

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

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

writeUint16BE

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

Parameters

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

Returns

Type: Buffer

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

Example usage

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.

Parameters

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

Returns

Type: number

The unsigned 16-bit integer read from the buffer.

Example usage

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.

Parameters

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

Returns

Type: Buffer

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

Example usage

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.

Parameters

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

Returns

Type: number

The unsigned 32-bit integer read from the buffer.

Example usage

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;

Parameters

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`

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

`coerceToInt16Array`

Coerces input data into a Int16Array.

Parameters

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

Returns

Type: Int16Array

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

`coerceToUint16Array`

Coerces input data into a Uint16Array.

Parameters

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

Returns

Type: Uint16Array

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

`coerceToInt32Array`

Coerces input data into a Int32Array.

Parameters

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

Returns

Type: Int32Array

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

`coerceToUint32Array`

Coerces input data into a Uint32Array.

Parameters

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

Returns

Type: Uint32Array

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

`coerceToSharedArrayBuffer`

Coerces input data into a SharedArrayBuffer.

Parameters

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

Returns

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.

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

Made with ☕

Alessio Frittoli

https://alessiofrittoli.it | info@alessiofrittoli.it

Name		Name	Last commit message	Last commit date
Latest commit History 68 Commits
.github		.github
.vscode		.vscode
__tests__		__tests__
scripts		scripts
src		src
.editorconfig		.editorconfig
.gitignore		.gitignore
.markdownlint.json		.markdownlint.json
.npmignore		.npmignore
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CONTRIBUTING.md		CONTRIBUTING.md
README.md		README.md
eslint.config.mjs		eslint.config.mjs
jest.config.ts		jest.config.ts
jest.setup.ts		jest.setup.ts
license.md		license.md
package.json		package.json
pnpm-lock.yaml		pnpm-lock.yaml
pnpm-workspace.yaml		pnpm-workspace.yaml
tsconfig.json		tsconfig.json
tsup.config.ts		tsup.config.ts

Uh oh!

Folders and files

Latest commit

History

Repository files navigation

Crypto Buffer 🚌

Lightweight TypeScript Node.js Buffers utility library

Table of Contents

Getting started

Utilities

toDataView

Input Type

Converting a String to DataView

Converting a Uint8Array to DataView

Handling Invalid Input

Common Utilities

bufferEquals

Convert a String in a Node.js Environment

Conversion Utilities

stringToBinary

Convert a String to binary data

stringToBytes

Convert a String to Bytes

binaryToString

Node.js

Browser

unicodeToBinarySequence

binarySequenceToUint8Array

writeUint16BE

readUint16BE

writeUint32BE

readUint32BE

Coercion Utilities

coerceToUint8Array

Input Type

Converting a String to Uint8Array

Converting a DataView to Uint8Array

coerceToInt16Array

coerceToUint16Array

coerceToInt32Array

coerceToUint32Array

coerceToSharedArrayBuffer

coerceToFloatArray

coerceToFloat32Array

coerceToFloat64Array

coerceToBigArray

coerceToBigInt64Array

coerceToBigUint64Array

Development

Install depenendencies

Build the source code

ESLint

Jest

Contributing

Security

Made with ☕

About

Topics

Resources

Code of conduct

Contributing

Stars

Watchers

Forks

Releases

Sponsor this project

Used by

Contributors

Languages

`toDataView`

`bufferEquals`

`stringToBinary`

`stringToBytes`

`binaryToString`

`unicodeToBinarySequence`

`binarySequenceToUint8Array`

`coerceToUint8Array`

`coerceToInt16Array`

`coerceToUint16Array`

`coerceToInt32Array`

`coerceToUint32Array`

`coerceToSharedArrayBuffer`

`coerceToFloatArray`

`coerceToFloat32Array`

`coerceToFloat64Array`

`coerceToBigArray`

`coerceToBigInt64Array`

`coerceToBigUint64Array`