# node-buffer-helper

> 一个用于解析Buffer数据的简单封装，这个库的开发初衷是用于解析一些协议方面的数据，对Buffer的一个简单的封装，设计采用Stream数据流动的思想。

Latest version **1.0.10** (published 2020-05-30) · ISC license · 0 weekly downloads

## Install

```sh
npm install node-buffer-helper
pnpm add node-buffer-helper
yarn add node-buffer-helper
bun add node-buffer-helper
```

## Health

**Score 15/100 (F)** — status: abandoned.

Positive: no vulnerabilities.

Warnings: low downloads; no types; no esm support.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 1.0.10 |
| Published | 2020-05-30 |
| First published | 2020-05-20 |
| Weekly downloads | 0 |
| License | ISC |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 0 |
| Unpacked size | 14.7 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Maintainers | yinwenfeng |

## Links

- npm: https://www.npmjs.com/package/node-buffer-helper
- npm.io page: https://npm.io/package/node-buffer-helper

## Recent versions

- 1.0.10 (latest) — 2020-05-30
- 1.0.9 — 2020-05-30
- 1.0.8 — 2020-05-30
- 1.0.7 — 2020-05-30
- 1.0.6 — 2020-05-30
- 1.0.5 — 2020-05-28
- 1.0.3 — 2020-05-28
- 1.0.1 — 2020-05-20
- 1.0.0 — 2020-05-20

## README

### 一、简介
一个用于解析Buffer数据的简单封装，这个库的开发初衷是用于解析一些协议方面的数据，对Buffer的一个简单的封装，设计采用Stream数据流动的思想。

它提供了一个Reader类，包含readArray、readInt、readShort、readByte四个方法，用于从Buffer中读取指定长度的数据，并提供一些简单数据转换函数。

也有Writer类，向Buffer中写数据。
### 二、Reader
#### 2.1 constructor(buff,[data])
+ **参数**
    - `{Buffer} buff：需要解析的Buffer对象`
    - `{Object} data`
+ **用法**
  初始化一个Reader实例，使用`new Reader(buff)`或者`Reader(buff)`初始化一个`Reader`。
  
+ **示例**
  ```javascript
  var buff = Buffer.from([1,2,3,4,5,6,7])
  Reader(buff) //或者
  new Reader(buff)
  ```
 以上语法都会返回一个Reader的实例，可以不用new的语法是希望提供一种函数式初始化语法。data是一个可选项，如果有data参数，那么Reader解析出来的结果会挂载在data对象上。

#### 2.2 Reader.prototype.readByte(options)
+ **参数**
    - `{String | Object} options：解析的选项`
+ **用法**
从buffer中取出1个字节，并将其转换成数值。

#### 2.3 Reader.prototype.readShort(options)
+ **参数**
    - `{String | Object} options：解析的选项`
+ **用法**
从buffer中取出2个字节，并将其转换成数值。

#### 2.4 Reader.prototype.readInt(options)
+ **参数**
    - `{String | Object} options：解析的选项`
+ **用法**
从buffer中取出4个字节，并将其转换成数值。

#### 2.5 Reader.prototype.readArray(options)
+ **参数**
    - `{String | Object} options：解析的选项`
+ **用法**
从buffer中取出非固定长度的字节，长度在options中给定默认为0，并将其转换成整数数组。

#### 2.6 Reader.prototype.Value()
+ **用法**
获取Reader解析的结果，得到的结果是一个Object对象

#### 2.7 Reader.prototype.Sum()
+ **用法**
获取已经读取的数据byte的和，buffer还未读到的部分不会参与计算。主要目的是为了求校验和。
+ **示例**
```
var buffer = Buffer.from([1,2,3,4,5])
Reader(buffer).readArray({
	len:4
}).Sum() //=>10
```

#### 2.8 Reader.prototype.check(len)
+ **参数**
    - `{Number} len：检查长度`
+ **用法**
检查buffer剩余长度是否超过len，每次读取数据的时候会自动被调用，如果读取长度超过当前buffer的剩余长度，会抛出一个异常`throw new Error("读取长度超过buffer！")`。

#### 2.9 Reader.prototype.validate(validate_fn,data)
+ **参数**
	- `{Function} validate_fn:验证函数，目前仅支持函数，不支持表达式`
	- `{Object} data:read之后的数组`
+ **用法**
对解析的结果进行验证，如果验证失败会抛出一个异常`throw new Error("验证失败")`，这个函数也是自动被调用的，当读取时options的选项中包含`validate`参数时有效。这个函数的出现为了解析数据时验证数据包的头部
+ **示例**
```javascript
var buffer = Buffer.from([0x68,0,0,0,0x68])
Reader(buffer).readByte({
	key:'head',
	validate:(data)=>{data==0x68}
}).Value() //=>{head:0x68}
```

#### 2.10 Reader.prototype.map(fn)
+ **参数**
	- `{Function} fn:对buffer的每一个元素都执行fn方法`

+ **用法**
	正常的对数组的map操作，不过它只会修改buffer还未被读取的部分。

+ **示例**
```
var buffer = Buffer.from([1,1,1,1,1])
Reader(buffer).readByte('head').map(x=>x+2).readByte('body').Sum() //=>4
```

#### 补充
`options`参数可以字符串或者object，如果传递参数为字符串，会被转换成`{key:options}`。`options`支持以下选项：
+ `{String} key`：写入data的键值，如果为空则不会将解析结果放入到最后的data中
+ `{Function} validate`：验证解析结果，如果验证失败会抛出异常，目前*暂不支持自定义异常提示*
+ `{Function} callback`：对结果执行解析结果执行callback，并将callback的结果存放到data中，它在验证之后执行
+ `{Number} len`:如果是读取数组需要用到该选项，指定读取的长度，默认为0

### 三、Writer
#### 2.1 constructor([data])
+ **参数**
    - `{Object} data:预先给定一些可能需要用到的数据，后面可以通过key取到结果，暂不支持表达式`
+ **用法**
  初始化一个Writer实例，使用`new Writer()`或者`Writer(data)`初始化一个`Writer`。
  
 
 以上语法都会返回一个Writer的实例，可以不用new的语法是希望提供一种函数式初始化语法，data是一个可选项。

#### 2.2 Writer.prototype.writerByte(options)
+ **参数**
    - `{String | Object | Number | Array} options`
+ **用法**
向Buffer中写入1个字节的数据。

#### 2.3 Writer.prototype.writeShort(options)
+ **参数**
    - `{String | Object | Number | Array} options：解析的选项`
+ **用法**
向Buffer中写入2个字节的数据。

#### 2.4 Writer.prototype.writeInt(options)
+ **参数**
    - `{String | Object | Number| Array} options：解析的选项`
+ **用法**
向Buffer中写入4个字节的数据。

#### 2.5 Writer.prototype.writeArray(options)
+ **参数**
    - `{String | Object | Number | Array} options：解析的选项`
+ **用法**
向Buffer中写入指定字节的数据，长度在options中给定默认为0，并将其转换成整数数组。

#### 2.6 Writer.prototype.Value()
+ **用法**
获取一个Buffer实例

#### 2.7 Writer.prototype.Sum()
+ **用法**
获取已经写入部分的和，也是为了求校验和

#### 2.8 补充
`options`参数可以字符串或者object，如果传递参数为`String`，则会从构造函数中传递的data中取值，`options`对象变成如下的形式`{value:this.data[options]}`，如果传递的参数为`Number`或者`Array`，`options`则变成`{value:options}`。`options`支持以下选项：
+ `{String} value`：即将要解析的值，会转换成对应的格式。如果超过长度会截断，不足会补0。
+ `{Number} len`:如果是写入数组需要用到该选项，指定读取的长度，默认为0
+ `{Function} callback`：对即将要写入的结果执行callback，并将callback的结果写入

### 四、后期添加功能
为了能用于更多的场景，后期应该添加一些功能拟定如下：
+ 读取UTF-8串
+ 写入UTF-8串
+ 读取PNG图片
+ 写入PNG图片

---
_Source: https://npm.io/package/node-buffer-helper · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._