https://github.com/alessiofrittoli/crypto-encoder
Lightweight TypeScript encoder/decoder library
https://github.com/alessiofrittoli/crypto-encoder
base32 base64 base64url buffers decoding encoding
Last synced: 2 months ago
JSON representation
Lightweight TypeScript encoder/decoder library
- Host: GitHub
- URL: https://github.com/alessiofrittoli/crypto-encoder
- Owner: alessiofrittoli
- License: mit
- Created: 2024-12-01T13:59:18.000Z (7 months ago)
- Default Branch: master
- Last Pushed: 2025-03-20T14:48:35.000Z (3 months ago)
- Last Synced: 2025-03-20T14:55:49.687Z (3 months ago)
- Topics: base32, base64, base64url, buffers, decoding, encoding
- Language: TypeScript
- Homepage: https://npmjs.com/package/@alessiofrittoli/crypto-encoder
- Size: 265 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 Encoder 🧮
[![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-encoder
[npm-url]: https://npmjs.org/package/%40alessiofrittoli%2Fcrypto-encoder
[coverage-badge]: https://coveralls.io/repos/github/alessiofrittoli/crypto-encoder/badge.svg
[coverage-url]: https://coveralls.io/github/alessiofrittoli/crypto-encoder
[socket-badge]: https://socket.dev/api/badge/npm/package/@alessiofrittoli/crypto-encoder
[socket-url]: https://socket.dev/npm/package/@alessiofrittoli/crypto-encoder/overview
[downloads-badge]: https://img.shields.io/npm/dm/%40alessiofrittoli%2Fcrypto-encoder.svg
[deps-badge]: https://img.shields.io/librariesio/release/npm/%40alessiofrittoli%2Fcrypto-encoder
[deps-url]: https://libraries.io/npm/%40alessiofrittoli%2Fcrypto-encoder
[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 encoder/decoder library
### Table of Contents
- [Getting started](#getting-started)
- [Base32](#base32)
- [Base64](#base64)
- [Encoder](#encoder)
- [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-encoder` in your projects:
```bash
npm i @alessiofrittoli/crypto-encoder
```
or using `pnpm`
```bash
pnpm i @alessiofrittoli/crypto-encoder
```
---
### Supported input data types
This module supports different input data types and it uses the `coerceToUint8Array` utility function from [`@alessiofrittoli/crypto-buffer`](https://npmjs.com/package/@alessiofrittoli/crypto-buffer) to convert it to a `Uint8Array`.
Here is the list of supported input data types (typed as `CoerceToUint8ArrayInput`):
- `string`
- `Array` (array of bytes)
- `DataView`
- `Buffer`
- `ArrayBuffer`
- `NodeJS.TypedArray`
- `Uint8Array`
- `Uint8ClampedArray`
- `Uint16Array`
- `Uint32Array`
- `Int8Array`
- `Int16Array`
- `Int32Array`
- `BigUint64Array`
- `BigInt64Array`
- `Float32Array`
- `Float64Array`
### Base32
This module provides a `Base32` utility class for encoding and decoding data according to various `Base32` specifications.\
It supports multiple `Base32` variants and offers flexible options for encoding.
Overview
The `Base32` class provides methods to encode and decode data using Base32, supporting multiple variants as defined by the following specifications:
- [Base32 from RFC4648](https://tools.ietf.org/html/rfc4648)
- [Base32hex from RFC4648](https://tools.ietf.org/html/rfc4648)
- [Crockford's Base32](http://www.crockford.com/wrmg/base32.html)
Variants
The following Base32 variants are supported:
- `RFC3548` - Alias for `RFC4648`
- `RFC4648` - The standard Base32 encoding.
- `RFC4648-HEX` - Base32 encoding with a hexadecimal-like alphabet.
- `Crockford` - A Base32 variant designed to be human-friendly.
API Reference
#### Static Properties
##### `Base32.VARIANT`
An object containing the available Base32 variants:
```ts
Base32.VARIANT = {
RFC3548 : 'RFC3548',
RFC4648 : 'RFC4648',
RFC4648_HEX : 'RFC4648-HEX',
Crockford : 'Crockford',
}
```
#### Static Methods
##### `Base32.encode()`
Encodes data to a Base32 string.
###### Parameters
| Parameter | Type | Description |
|-------------------|-----------------|------------------------------------|
| `data` | `CoerceToUint8ArrayInput` | The data to encode. See the [list of supported input data types](#supported-input-data-types). |
| `variant` | `Variant` | The Base32 variant to use. |
| `options` | `EncodeOptions` | (Optional) Encoding options. |
| `options.padding` | `boolean` | If set, forcefully enable or disable padding. The default behavior is to follow the default of the selected variant. |
###### Returns
Type: `string`
A Base32 encoded string.
###### Example usage
```ts
import { Base32 } from '@alessiofrittoli/crypto-encoder'
// or
import { Base32 } from '@alessiofrittoli/crypto-encoder/Base32'
console.log( Base32.encode( 'some value', 'RFC3548' ) )
// or
console.log( Base32.encode( 'some value', Base32.VARIANT.RFC3548 ) )
// Outputs: 'ONXW2ZJAOZQWY5LF'
```
---
##### `Base32.decode()`
Decodes a Base32 data.
###### Parameters
| Parameter | Type | Description |
|-----------|---------------------------|----------------------------------------------|
| `data` | `CoerceToUint8ArrayInput` | The Base32-encoded data. See the [list of supported input data types](#supported-input-data-types). |
| `variant` | `Variant` | The Base32 variant used to encode the input. |
###### Returns
Type: `Uint8Array`
An `Uint8Array` containing the decoded data.
###### Example usage
```ts
import { Base32 } from '@alessiofrittoli/crypto-encoder'
// or
import { Base32 } from '@alessiofrittoli/crypto-encoder/Base32'
const input = 'ONXW2ZJAOZQWY5LF'
const decoded = Base32.decode( input, 'RFC3548' )
// or
const decoded = Base32.decode( input, Base32.VARIANT.RFC3548 )
console.log( Buffer.from( decoded ).toString() ) // Node.js
// or
console.log( new TextDecoder().decode( decoded ) ) // client-side
// or
console.log( Base32.toString( decoded ) ) // Node.js + client-side
// Outputs: 'some value'
```
---
### Base64
This module provides a static `Base64` utility class for encoding and decoding data to and from Base64/Base64url formats. It supports various input types and offers options for normalization between Base64 and Base64url formats.
Overview
The `Base64` class provides static methods for:
- Encoding data to Base64/Base64url strings.
- Decoding Base64/Base64url strings to binary data.
- Normalizing strings between Base64 and Base64url formats.
The implementation is compatible with both browser and Node.js environments.
API Reference
#### Static Methods
##### `Base64.encode()`
Encodes data to a Base64 or Base64url string.
###### Parameters
| Parameter | Type | Default | Description |
|-------------|-----------------|---------| ----------------------------------------------|
| `data` | `CoerceToUint8ArrayInput` | - | The data to encode. See the [list of supported input data types](#supported-input-data-types). |
| `normalize` | `boolean` | `false` | Whether to normalize the output to Base64url. |
###### Returns
Type: `string`
A Base64 or Base64url encoded string.
###### Example
```ts
import { Base64 } from '@alessiofrittoli/crypto-encoder'
// or
import { Base64 } from '@alessiofrittoli/crypto-encoder/Base64'
const data = 'Hello, World!'
const base64 = Base64.encode( data )
const base64url = Base64.encode( data, true )
console.log( base64 ) // Outputs: 'SGVsbG8sIFdvcmxkIQ=='
console.log( base64url ) // Outputs: 'SGVsbG8sIFdvcmxkIQ'
```
---
##### `Base64.decode()`
Decodes a Base64 or Base64url string.
###### Parameters
| Parameter | Type | Description |
|-----------|---------------------------|-------------------------------------------|
| `data` | `CoerceToUint8ArrayInput` | The Base64 or Base64url encoded data. See the [list of supported input data types](#supported-input-data-types). |
###### Returns
Type: `Buffer | Uint8Array`
A `Buffer` containing the decoded data.
###### Example
```ts
import { Base64 } from '@alessiofrittoli/crypto-encoder'
// or
import { Base64 } from '@alessiofrittoli/crypto-encoder/Base64'
const base64 = 'SGVsbG8sIFdvcmxkIQ=='
const base64url = 'SGVsbG8sIFdvcmxkIQ'
console.log( Base64.toString( Base64.decode( base64 ) ) )
// or
console.log( Base64.toString( Base64.decode( base64url ) ) )
// Outputs: 'Hello, World!'
```
---
### Encoder
The `Encoder` class provides static methods for encoding and decoding data using various encoding schemes, including custom ones like `base32`.
API Reference
#### **Types**
##### `Encoding`
Represents the encoding types supported by the `Encoder` class. Includes all standard `BufferEncoding` types as well as the custom `base32` encoding.
#### Static Properties
##### `Encoder.SUPPORTED_ENCODINGS`
Type: `Encoding[]`
A list of all encodings supported by the `Encoder` class. Includes standard `BufferEncoding` types and the custom `base32` encoding.
#### Static Methods
##### `Encoder.encode()`
Encodes the provided data using the specified encoding scheme.
###### Parameters
| Parameter | Type | Default | Description |
|-----------------|------------|---------| -------------------------------------------|
| `data` | `CoerceToUint8ArrayInput` | - | The data to encode. See the [list of supported input data types](#supported-input-data-types). |
| `encoding` | `Encoding` | `utf8` | (Optional) The output encoding. |
| `inputEncoding` | `Encoding` | - | (Optional) The encoding of the input data. |
###### Returns
Type: `string`
The encoded data as a string.
###### Behavior
- If `encoding` is `base32`, uses the [`Base32`](#base32) class with the `RFC3548` standard.
- If `encoding` is `base64` or `base64url`, uses the [`Base64`](#base64) class.
- Otherwise, falls back to `Buffer` (if available) or the `binaryToString` function for encoding.
###### Example
```ts
import { Encoder } from '@alessiofrittoli/crypto-encoder'
// or
import { Encoder } from '@alessiofrittoli/crypto-encoder/Encoder'
const data = 'Hello, world!'
const buffer = Buffer.from( data )
const bytes = [
72, 101, 108, 108, 111,
44, 32, 119, 111, 114,
108, 100, 33
]
console.log( Encoder.encode( data, 'hex' ) )
console.log( Encoder.encode( data, 'base32' ) )
console.log( Encoder.encode( data, 'base64' ) )
console.log( Encoder.encode( buffer ) )
console.log( Encoder.encode( bytes ) )
```
---
##### `Encoder.decode()`
Decodes the provided data using the specified encoding scheme.
###### Parameters
| Parameter | Type | Description |
|-----------|---------------------------|-------------------------------------------|
| `data` | `CoerceToUint8ArrayInput` | The input data to decode. See the [list of supported input data types](#supported-input-data-types). |
| `encoding`| `Encoding` | The encoding of the input data. |
###### Returns
Type: `Buffer | Uint8Array`
A `Buffer` containing the decoded data.
###### Behavior
- If `encoding` is `base32`, uses the [`Base32`](#base32) class with the `RFC3548` standard.
- If `encoding` is `base64` or `base64url`, uses the [`Base64`](#base64) class.
- Otherwise, falls back to `Buffer` (if available) or coerces the input data to a `Uint8Array`.
###### Example
```ts
import { Encoder } from '@alessiofrittoli/crypto-encoder'
// or
import { Encoder } from '@alessiofrittoli/crypto-encoder/Encoder'
const decoded = Encoder.decode( 'JBSWY3DPFQQHO33SNRSCC===', 'base32' )
console.log( Encoder.toString( decoded ) ) // Outputs: '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]