https://github.com/alessiofrittoli/crypto-buffer
Lightweight TypeScript Node.js Buffers utility library
https://github.com/alessiofrittoli/crypto-buffer
buffers nodejs
Last synced: about 2 months ago
JSON representation
Lightweight TypeScript Node.js Buffers utility library
- Host: GitHub
- URL: https://github.com/alessiofrittoli/crypto-buffer
- Owner: alessiofrittoli
- License: mit
- Created: 2024-12-02T14:19:30.000Z (6 months ago)
- Default Branch: master
- Last Pushed: 2025-03-21T20:24:34.000Z (3 months ago)
- Last Synced: 2025-03-28T16:21:01.488Z (3 months ago)
- Topics: buffers, nodejs
- Language: TypeScript
- Homepage: https://npmjs.com/package/@alessiofrittoli/crypto-buffer
- Size: 285 KB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- Funding: .github/FUNDING.yml
- License: license.md
- Code of conduct: CODE_OF_CONDUCT.md
Awesome Lists containing this project
README
# Crypto Buffer 🚌
[![NPM Latest Version][version-badge]][npm-url] [![Coverage Status][coverage-badge]][coverage-url] [![Socket Status][socket-badge]][socket-url] [![NPM Monthly Downloads][downloads-badge]][npm-url] [![Dependencies][deps-badge]][deps-url]
[![GitHub Sponsor][sponsor-badge]][sponsor-url]
[version-badge]: https://img.shields.io/npm/v/%40alessiofrittoli%2Fcrypto-buffer
[npm-url]: https://npmjs.org/package/%40alessiofrittoli%2Fcrypto-buffer
[coverage-badge]: https://coveralls.io/repos/github/alessiofrittoli/crypto-buffer/badge.svg
[coverage-url]: https://coveralls.io/github/alessiofrittoli/crypto-buffer
[socket-badge]: https://socket.dev/api/badge/npm/package/@alessiofrittoli/crypto-buffer
[socket-url]: https://socket.dev/npm/package/@alessiofrittoli/crypto-buffer/overview
[downloads-badge]: https://img.shields.io/npm/dm/%40alessiofrittoli%2Fcrypto-buffer.svg
[deps-badge]: https://img.shields.io/librariesio/release/npm/%40alessiofrittoli%2Fcrypto-buffer
[deps-url]: https://libraries.io/npm/%40alessiofrittoli%2Fcrypto-buffer
[sponsor-badge]: https://img.shields.io/static/v1?label=Fund%20this%20package&message=%E2%9D%A4&logo=GitHub&color=%23DB61A2
[sponsor-url]: https://github.com/sponsors/alessiofrittoli
## Lightweight TypeScript Node.js Buffers utility library
### Table of Contents
- [Getting started](#getting-started)
- [Utilities](#utilities)
- [`toDataView`](#todataview)
- [Common Utilities](#common-utilities)
- [`bufferEquals`](#bufferequals)
- [Conversion Utilities](#conversion-utilities)
- [`stringToBinary`](#stringtobinary)
- [`stringToBytes`](#stringtobytes)
- [`binaryToString`](#binarytostring)
- [`unicodeToBinarySequence`](#unicodetobinarysequence)
- [`binarySequenceToUint8Array`](#binarysequencetouint8array)
- [Coercion Utilities](#coercion-utilities)
- [`coerceToUint8Array`](#coercetouint8array)
- [`coerceToFloatArray`](#coercetofloatarray)
- [`coerceToFloat32Array`](#coercetofloat32array)
- [`coerceToFloat64Array`](#coercetofloat64array)
- [`coerceToBigArray`](#coercetobigarray)
- [`coerceToBigInt64Array`](#coercetobigint64array)
- [`coerceToBigUint64Array`](#coercetobiguint64array)
- [Development](#development)
- [Install depenendencies](#install-depenendencies)
- [Build the source code](#build-the-source-code)
- [ESLint](#eslint)
- [Jest](#jest)
- [Contributing](#contributing)
- [Security](#security)
- [Credits](#made-with-)
---
### Getting started
Run the following command to start using `crypto-buffer` in your projects:
```bash
npm i @alessiofrittoli/crypto-buffer
```
or using `pnpm`
```bash
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
```ts
type ToDataViewInput = (
| string
| Array
| 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` (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
```ts
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
```ts
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
```ts
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, ...
}
```
---
#### 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
```ts
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
```ts
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](#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
```ts
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](#coercetouint8array) for a list of possible input data types. |
---
Returns
Type `string`
A string representation of the given input.
---
Example usage
###### Node.js
```ts
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
```ts
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](#coercetouint8array) for a list of possible input data types. |
---
Returns
Type `string`
The 0-1 converted binary sequence.
---
Example usage
```ts
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](#coercetouint8array) for a list of possible input data types. |
---
Returns
Type `Uint8Array`
A new Uint8Array instance.
---
Example usage
```ts
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
```ts
type CoerceToUint8ArrayInput = (
| string
| number
| Array
| 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` (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
```ts
import { coerceToUint8Array } from '@alessiofrittoli/crypto-buffer'
// or
import { coerceToUint8Array } from '@alessiofrittoli/crypto-buffer/coercion'
const buffer = coerceToUint8Array( 'Hello, World!' )
```
###### Converting a DataView to Uint8Array
```ts
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](#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](#coercetouint8array) for a list of possible input data types. |
---
Returns
Type: `Float32Array`
A new instance of `Float32Array`.
---
Usage
```ts
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](#coercetouint8array) for a list of possible input data types. |
---
Returns
Type: `Float64Array`
A new instance of `Float64Array`.
---
Usage
```ts
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](#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](#coercetouint8array) for a list of possible input data types. |
---
Returns
Type: `BigInt64Array`
A new instance of `BigInt64Array`.
---
Usage
```ts
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](#coercetouint8array) for a list of possible input data types. |
---
Returns
Type: `BigUint64Array`
A new instance of `BigUint64Array`.
---
Usage
```ts
import { coerceToBigUint64Array } from '@alessiofrittoli/crypto-buffer'
// or
import { coerceToBigUint64Array } from '@alessiofrittoli/crypto-buffer/coercion'
const bigUint64Array = coerceToBigUint64Array( 'Hello, World!' )
```
---
### Development
#### Install depenendencies
```bash
npm install
```
or using `pnpm`
```bash
pnpm i
```
#### Build the source code
Run the following command to test and build code for distribution.
```bash
pnpm build
```
#### [ESLint](https://www.npmjs.com/package/eslint)
warnings / errors check.
```bash
pnpm lint
```
#### [Jest](https://npmjs.com/package/jest)
Run all the defined test suites by running the following:
```bash
# Run tests and watch file changes.
pnpm test:watch
# Run tests in a CI environment.
pnpm test:ci
```
- See [`package.json`](./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.
```bash
test:coverage:serve
```
---
### Contributing
Contributions are truly welcome!
Please refer to the [Contributing Doc](./CONTRIBUTING.md) for more information on how to start contributing to this project.
Help keep this project up to date with [GitHub Sponsor][sponsor-url].
[![GitHub Sponsor][sponsor-badge]][sponsor-url]
---
### 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 ☕
Alessio Frittoli
https://alessiofrittoli.it |
[email protected]