# DIMBIN

> High-performance serialization for multi-dimension arrays
>
> 针对大量数据网络传输设计的序列化方案，用于储存多维数组
>
> 通过*直接内存操作*实现高于 JSON 多个数量级的性能和更小的传输体积

[《序列化方案选型建议》](https://github.com/alibaba/DIMBIN/wiki/序列化方案选型对比)

## Useage

### C#

[see ./csharp](./csharp/README.md)

### javascript

`npm install --save dimbin`

```javascript
import DIMBIN from 'dimbin' // v3

// import DIMBIN from 'dimbin/v2' // old version
```

```javascript
const data = [
    [0, 1, 2, 3], // 普通数值数组 ✅
    new Int16Array([1, 2, 3, 4]), // TypedArray ✅
    [
        // 更高维度数组 ✅
        [0, 1, 2],
        [0, 1, 2, 3, 4],
    ],
    DIMBIN.stringsSerialize(['a', 'bc', '😊']), // Array<string>
    DIMBIN.booleansSerialize([true, false, true, true]), // Array<boolean>
]

// 序列化为ArrayBuffer
const bin = DIMBIN.serialize(data)

// 反序列化为 Array<TypedArray>
const dim = DIMBIN.parse(bin)
dim[3] = DIMBIN.stringsParse(dim[3])
dim[4] = DIMBIN.booleansParse(dim[4])

/*
[
    Float32Array{0, 1, 2, 3},
    Int16Array{1, 2, 3, 4},
    [
        Float32Array{0, 1, 2},
        Float32Array{0, 1, 2, 3, 4},
    ],
    ['a', 'bc', '😊'],
    [true, false, true, true]
]
*/
```

## 数据结构

DIMBIN 为多维数组而设计, 因此传入的数据结构必须为多维数组, 数组维数没有上限, 每一维度数组的元素个数上线为 2^32 . 维度和数组元素个数受运行环境和设备限制.

```javascript
// 粒子 🌰

// 正确的格式
const input = [
    // Array
    [1, 2, 3],
    // TypedArray
    new Float32Array(1000),
    // higher dimensions
    [
        //
        [4, 5, 6],
        new Float64Array(2000),
    ],
]

const wrong1 = [
    // 必须为多维数组
    1,
    2,
    3,
]

const wrong2 = [
    // - 数组元素必须 *全部为数组* 或者 *全部为数值*
    [1, 2, 3, [4], [5]],
]

const wrong3 = [
    // 非数值数据需要先转换为数值数据
    ['123', 'hello'],
]
```

数组的元素支持以下数据类型

-   number: Int8, UInt8, Int16, UInt16, Int32, UInt32, Float32, Float64
-   string
-   boolean

默认情况下, 所有的数据将使用 Float32 格式进行保存.
如果需要指定数据格式, 请先转换成 TypedArray.
如需要处理字符串和布尔值, 请使用对应的接口预先转换成 TypedArray.

## API

### C#

[see ./csharp](./csharp/README.md)

### javascript

#### `serialize`

序列化为二进制数据

-   @param `{Array<TypedArray|Array<number|TypedArray|Array>>} data` 多维数组
-   @param `{float} magicNumber` 用户控制的标识位
-   @return `{ArrayBuffer}`

#### `parse`

反序列化回多维数组

-   @param `{ArrayBuffer|Buffer|DataView} buffer` 序列化后的二进制数据
-   @return `{Array<TypedArray|Array<TypedArray|Array>>}`

#### `getMeta`

读取二进制数据的元数据

-   @param `{ArrayBuffer|Buffer|DataView} buffer` 序列化后的二进制数据
-   @return `{Meta}`

```typescript
interface Meta {
    version: number
    magic_num: number
    seg_meta_bytes: number
    seg_meta_start: number
    len: number
    big_endian: boolean
}
```

#### `stringsSerialize`

将 Array<string> 序列化成 TypedArray

-   @param `{string[]} strs` 元素为字符串的数组
-   @return `{UInt8Array}` 序列化后的二进制数据

#### `stringsParse`

将 stringsSerialize 生成的二进制数据解析回 Array<string>

-   @param `{UInt8Array}` 序列化后的二进制数据
-   @return `{string[]}` 元素为字符串的数组

#### `booleansSerialize`

将 Array<boolean> 序列化成 TypedArray

-   @param `{boolean[]} strs` 元素为布尔值的数组
-   @return `{UInt8Array}` 序列化后的二进制数据

#### `booleansParse`

将 booleansSerialize 生成的二进制数据解析回 Array<boolean>

-   @param `{UInt8Array}` 序列化后的二进制数据
-   @return `{boolean[]}` 元素为布尔值的数组

## Performance

JS 环境下：当使用**纯数值数据**时

-   序列化性能为 JSON 的 **3-10 倍**
-   反序列化性能为 JSON 的 **十万到百万 倍**
-   体积比 JSON **减小 60%**

在 JS 环境中, 性能高于 flatbuffers 30%~100%, 远高于 protocolbuffers.

**详细 benchmark 以及与 JSON / ProtocolBuffers / FlatBuffer 的对比与选型建议 >>>**

[**序列化方案选型对比**](https://github.com/alibaba/DIMBIN/wiki/序列化方案选型对比)

## Development

`npm install`

`npm start`

open `http://localhost:3112/html/api` in your browser.

`npm test`

`npm run dist`

## Specifications

`specifications/v3.md`