npm package: @pallad/text-buffer-view
Description: <div align="center"> <h1>Text buffer view 🌄</h1>
Author: Łukasz Kużyński
Latest version: 1.0.3

<div align="center">
<h1>Text buffer view 🌄</h1>

<p>Work with text buffers easily</p>
</div>

---
[![CircleCI](https://circleci.com/gh/pallad-ts/text-buffer-view/tree/master.svg?style=svg)](https://circleci.com/gh/pallad-ts/text-buffer-view/tree/master)
[![npm version](https://badge.fury.io/js/@pallad%2Ftext-buffer-view.svg)](https://badge.fury.io/js/@pallad%2Ftext-buffer-view)
[![Coverage Status](https://coveralls.io/repos/github/pallad-ts/text-buffer-view/badge.svg?branch=master)](https://coveralls.io/github/pallad-ts/text-buffer-view?branch=master)
[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](https://opensource.org/licenses/MIT)
---

Allows to work with array buffers, regular node.js buffers and strings in a unified way.

Supported encodings:
* `ascii`
* `utf8`
* `base64`
* `base64url`
* `hex`

# But why?

`Buffer.from` does not throw error for invalid data which is an issue hard to spot.

Additionally, I want to work more with `ArrayBuffer` for modern `webcrypto` api and constant juggling between `Buffer` and `ArrayBuffer` was annoying.

# Usage

```typescript
import { TextBufferView } from '@pallad/text-buffer-view';

const buffer = TextBufferView.fromString('Hello, world!', 'utf8');

buffer.toString('hex');
buffer.toString('base64');
buffer.toString('base64url');
```

## Prevents providing invalid input data

```typescript
import {TextBufferView} from "./TextBufferView";

TextBufferView.fromString('invalid hex', 'hex'); // throws an error and Buffer.from('invalid hex', 'hex') does not
TextBufferView.fromString('invalid base64', 'base64'); // throws an error and Buffer.from('invalid base64', 'base64') does not
```

Providing empty string is always allowed

```typescript
TextBufferView.fromString('', 'hex'); // buffer of length 0 
TextBufferView.fromString('', 'base64'); // buffer of length 0
```

## Creating from string

`TextBufferView.fromString` creates view from string. 

```typescript
TextBufferView.fromString('c2478b42259098672eb247e1e46b28ee', 'hex');
TextBufferView.fromString('just regular text', 'utf8');
```

It is similar to `Buffer.from` but throws an error when input string is invalid (only for `hex`, `base64` and `base64url` encodings).
```typescript
TextBufferView.fromString('invalid hex', 'hex'); // throws an error and Buffer.from('invalid hex', 'hex') does not
TextBufferView.fromString('invalid base64', 'base64'); // throws an error and Buffer.from('invalid base64', 'base64') does not
```

## Converting to string

```ts
const view = TextBufferView.fromString('c2478b42259098672eb247e1e46b28ee', 'hex');
view.toString('hex'); // 'c2478b42259098672eb247e1e46b28ee'
view.toString('base64'); // 'wkeLQilAmGcuskfh5Gso7g=='
view.toString('base64url'); // 'wkeLQiWQmGcuskfh5Gso7g'
view.toString('utf8'); // some utf8 gibberish
view.toString('ascii'); // some ascii gibberish
```

## Accessing buffer

```typescript
const view = TextBufferView.fromString('c2478b42259098672eb247e1e46b28ee', 'hex');

view.buffer; // makes copy of a buffer
view.originalBuffer; // returns original buffer - risking of modifying it
```