Skip to content

Commit

Permalink
v1.5.0 (#3)
Browse files Browse the repository at this point in the history
  • Loading branch information
reececomo committed Mar 2, 2024
1 parent 42896c8 commit d7569f6
Show file tree
Hide file tree
Showing 65 changed files with 4,379 additions and 1,194 deletions.
103 changes: 103 additions & 0 deletions .eslintrc
Original file line number Diff line number Diff line change
@@ -0,0 +1,103 @@
{
"root": true,
"rules": {
"newline-before-return": 0,
"prefer-const": 0,
"no-fallthrough": 0,
"@typescript-eslint/no-duplicate-enum-values": 0,
"@typescript-eslint/no-inferrable-types": 0,
"@typescript-eslint/no-explicit-any": 0,
"@typescript-eslint/no-empty-interface": 0,
"@typescript-eslint/no-non-null-assertion": 0,
"@typescript-eslint/no-empty-function": 0,
"@typescript-eslint/indent": 0,
"@typescript-eslint/no-extra-semi": 0,
"jsdoc/require-jsdoc": 0,
"jsdoc/require-param": 0,
"jsdoc/require-returns": 0,
"jsdoc/require-param-type": 0,
"jsdoc/require-param-description": 0,
"jsdoc/require-returns-type": 0,
"jsdoc/require-returns-description": 0,
"jsdoc/tag-lines": 0,
"jsdoc/multiline-blocks": 0,
"@typescript-eslint/explicit-member-accessibility": 1,
"jsdoc/check-line-alignment": 1,
"jsdoc/check-syntax": 1,
"jsdoc/no-blank-block-descriptions": 1,
"jsdoc/no-blank-blocks": 1,
"jsdoc/informative-docs": 1,
"jsdoc/no-defaults": 1,
"jsdoc/no-types": 1,
"no-trailing-spaces": "warn",
"@typescript-eslint/ban-types": "warn",
"disable-autofix/jsdoc/require-jsdoc": [
"warn",
{
"checkConstructors": false,
"publicOnly": true,
"require": {
"MethodDefinition": true
}
}
],
"max-len": [
"warn",
200
],
"brace-style": [
"warn",
"stroustrup"
],
"curly": "warn",
"semi": [
"warn",
"always"
],
"import-newlines/enforce": [
"warn",
{
"items": 3,
"max-len": 80,
"semi": true
}
],
"indent": [
"warn",
2,
{
"SwitchCase": 1
}
],
"@typescript-eslint/explicit-function-return-type": [
"error",
{
"allowExpressions": true
}
],
"@typescript-eslint/no-unused-vars": [
"warn",
{
"args": "none"
}
]
},
"extends": [
"eslint:recommended",
"plugin:@typescript-eslint/eslint-recommended",
"plugin:@typescript-eslint/recommended",
"plugin:@typescript-eslint/strict",
"plugin:jsdoc/recommended"
],
"parser": "@typescript-eslint/parser",
"parserOptions": {
"ecmaVersion": 2020,
"sourceType": "module"
},
"plugins": [
"@typescript-eslint",
"import-newlines",
"jsdoc",
"eslint-plugin-disable-autofix"
]
}
28 changes: 28 additions & 0 deletions .github/workflows/lint.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,28 @@
name: "lint"

on:
push:
branches: ["main"]
paths:
- "**/*.ts"
pull_request:
branches: ["main"]
paths:
- "**/*.ts"

jobs:
lint:
runs-on: ubuntu-latest

strategy:
matrix:
node-version: [16.x]

steps:
- uses: actions/checkout@v3
- name: Use Node.js ${{ matrix.node-version }}
uses: actions/setup-node@v3
with:
node-version: ${{ matrix.node-version }}
- run: npm install
- run: npm run lint
30 changes: 30 additions & 0 deletions .github/workflows/test.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,30 @@
name: "test"

on:
push:
branches: ["main"]
paths:
- "**/*.js"
- "**/*.ts"
pull_request:
branches: ["*"]
paths:
- "**/*.js"
- "**/*.ts"

jobs:
test:
runs-on: ubuntu-latest

strategy:
matrix:
node-version: [16.x]

steps:
- uses: actions/checkout@v3
- name: Use Node.js ${{ matrix.node-version }}
uses: actions/setup-node@v3
with:
node-version: ${{ matrix.node-version }}
- run: npm install
- run: npm run test
1 change: 1 addition & 0 deletions .gitignore
Original file line number Diff line number Diff line change
@@ -1,2 +1,3 @@
node_modules
.DS_Store
coverage/
19 changes: 19 additions & 0 deletions .vscode/settings.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,19 @@
{
"editor.rulers": [
120
],
"editor.tabSize": 2,
"editor.formatOnSave": true,
"editor.codeActionsOnSave": {
"source.fixAll.eslint": "explicit"
},
"eslint.format.enable": true,
"files.eol": "\n",
"search.exclude": {
"**/node_modules": true,
"**/dist": true,
"**/package-lock.json": true,
},
"typescript.preferences.importModuleSpecifier": "relative",
"workbench.tree.indent": 20,
}
94 changes: 49 additions & 45 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,12 +7,14 @@
Powerful, lightweight binary formats in TypeScript.

[![NPM version](https://img.shields.io/npm/v/typescript-binary.svg?style=flat-square)](https://www.npmjs.com/package/typescript-binary)
[![test](https://github.com/reececomo/typescript-binary/actions/workflows/test.yml/badge.svg)](https://github.com/reececomo/typescript-binary/actions/workflows/test.yml)
[![test](https://github.com/reececomo/typescript-binary/actions/workflows/lint.yml/badge.svg)](https://github.com/reececomo/typescript-binary/actions/workflows/lint.yml)

</div>

* Compatible with [geckos.io](https://github.com/geckosio/geckos.io), [socket.io](https://github.com/socketio/socket.io) and [peer.js](https://github.com/peers/peerjs).
* Similar to [FlatBuffers](https://github.com/google/flatbuffers) and [Protocol Buffers](https://protobuf.dev/), with zero dependencies.
* Hard-forked from the fantastic [sitegui/js-binary](https://github.com/sitegui/js-binary) library, written by [Guilherme Souza](https://github.com/sitegui).
- Compatible with [geckos.io](https://github.com/geckosio/geckos.io), [socket.io](https://github.com/socketio/socket.io) and [peer.js](https://github.com/peers/peerjs).
- Similar to [FlatBuffers](https://github.com/google/flatbuffers) and [Protocol Buffers](https://protobuf.dev/), with zero dependencies.
- Hard-forked from the fantastic [sitegui/js-binary](https://github.com/sitegui/js-binary) library, written by [Guilherme Souza](https://github.com/sitegui).

## Install

Expand All @@ -25,26 +27,28 @@ Powerful, lightweight binary formats in TypeScript.
Define a `BinaryCode` like so:

```js
import { BinaryCodec, Type, Optional } from 'typescript-binary';
import { BinaryCoder, Type, Optional } from "typescript-binary";

// Define
const GameWorldData = new BinaryCodec({
const GameWorldData = new BinaryCoder({
timeRemaining: Type.UInt,
players: [{
id: Type.String,
health: Type.UInt8,
position: Optional({
x: Type.Float34,
y: Type.Float34
}),
isJumping: Type.Boolean
}],
players: [
{
id: Type.String,
health: Type.UInt8,
position: Optional({
x: Type.Float34,
y: Type.Float34,
}),
isJumping: Type.Boolean,
},
],
});

// Encode
const binary = GameWorldData.encode(gameWorld.getState());

binary.byteLength
binary.byteLength;
// 20

// Decode
Expand All @@ -65,9 +69,9 @@ const data = GameWorldData.decode(binary);

### Handling multiple binary formats

By default, each `BinaryCodec` includes a 2-byte `UInt16` identifier. This can be disabled by setting `Id` as `false` in the `BinaryCodec` constructor. You can also provide your own fixed identifier instead (i.e. an `Enum`).
By default, each `BinaryCoder` includes a 2-byte `UInt16` identifier. This can be disabled by setting `Id` as `false` in the `BinaryCoder` constructor. You can also provide your own fixed identifier instead (i.e. an `Enum`).

Read the identifer with the static function `BinaryCodec.peekId(...)`.
Read the identifer with the static function `BinaryCoder.peekId(...)`.

#### BinaryFormatHandler

Expand All @@ -86,34 +90,34 @@ binaryHandler.processBuffer(binary);

Here are all the ready-to-use types:

| **Type** | **JavaScript Type** | **Bytes** | **About** |
|:---:|:---:|:---:|---|
| `Type.Int` | `number` | 1-8<sup>*</sup> | Integer up to `±Number.MAX_SAFE_INTEGER`. Dynamically sized. |
| `Type.Int8` | `number` | 1 | Integer between -127 to 128. |
| `Type.Int16` | `number` | 2 | Integer between -32,767 to 32,767. |
| `Type.Int32` | `number` | 4 | Integer between -2,147,483,647 to 2,147,483,647. |
| `Type.UInt` | `number` | 1-8<sup>#</sup> | Unsigned integer up to `Number.MAX_SAFE_INTEGER`. Dynamically sized. |
| `Type.UInt8` | `number` | 1 | Unsigned integer up to 255. |
| `Type.UInt16` | `number` | 2 | Unsigned integer up to 65,535. |
| `Type.UInt32` | `number` | 4 | Unsigned integer up to 4,294,967,295. |
| `Type.Float16` | `number` | 2 | A 16-bit "half-precision" floating point.<br/>**Important Note:** Low decimal precision. Max. large values ±65,500. |
| `Type.Float32` | `number` | 4 | A 32-bit "single-precision" floating point. |
| `Type.Float64` | `number` | 8 | Default JavaScript `number` type. A 64-bit "double-precision" floating point. |
| `Type.String` | `string` | 1<sup>†</sup>&nbsp;+&nbsp;n | A UTF-8 string. |
| `Type.Boolean` | `boolean` | 1 | A single boolean. |
| `Type.BooleanTuple` | `boolean[]` | 1<sup>¶</sup> | An array of booleans. Dynamically sized. |
| `Type.Bitmask8` | `boolean[]` | 1 | 1-8 booleans. |
| `Type.Bitmask16` | `boolean[]` | 2 | 1-16 booleans. |
| `Type.Bitmask32` | `boolean[]` | 4 | 1-32 booleans. |
| `Type.JSON` | `any` | 1<sup>†</sup>&nbsp;+&nbsp;n | [JSON format](http://json.org/) data, encoded as a UTF-8 string. |
| `Type.Binary` | `ArrayBuffer` | 1<sup>†</sup>&nbsp;+&nbsp;n | JavaScript `ArrayBuffer` data. |
| `Type.RegExp` | `RegExp` | 1<sup>†</sup>&nbsp;+&nbsp;n&nbsp;+&nbsp;1 | JavaScript `RegExp` object. |
| `Type.Date` | `Date` | 8 | JavaScript `Date` object. |
| `Optional(T)` | `T \| undefined` | 1 | Any optional field. Use the `Optional(...)` helper. Array elements cannot be optional. |
| `[T]` | `Array<T>` | 1<sup>†</sup>&nbsp;+&nbsp;n | Use array syntax. Any array. |
| `{}` | `object` | _none_ | Use object syntax. No overhead to using object types. Buffers are ordered, flattened structures. |

<sup>*</sup>`Int` encodes <±64 = 1 byte, <±8,192 = 2 bytes, <±268,435,456 = 4 bytes, otherwise = 8 bytes.
| **Type** | **JavaScript Type** | **Bytes** | **About** |
| :-----------------: | :-----------------: | :---------------------------------------: | ------------------------------------------------------------------------------------------------------------------- |
| `Type.Int` | `number` | 1-8<sup>\*</sup> | Integer up to `±Number.MAX_SAFE_INTEGER`. Dynamically sized. |
| `Type.Int8` | `number` | 1 | Integer between -127 to 128. |
| `Type.Int16` | `number` | 2 | Integer between -32,767 to 32,767. |
| `Type.Int32` | `number` | 4 | Integer between -2,147,483,647 to 2,147,483,647. |
| `Type.UInt` | `number` | 1-8<sup>#</sup> | Unsigned integer up to `Number.MAX_SAFE_INTEGER`. Dynamically sized. |
| `Type.UInt8` | `number` | 1 | Unsigned integer up to 255. |
| `Type.UInt16` | `number` | 2 | Unsigned integer up to 65,535. |
| `Type.UInt32` | `number` | 4 | Unsigned integer up to 4,294,967,295. |
| `Type.Float16` | `number` | 2 | A 16-bit "half-precision" floating point.<br/>**Important Note:** Low decimal precision. Max. large values ±65,500. |
| `Type.Float32` | `number` | 4 | A 32-bit "single-precision" floating point. |
| `Type.Float64` | `number` | 8 | Default JavaScript `number` type. A 64-bit "double-precision" floating point. |
| `Type.String` | `string` | 1<sup>†</sup>&nbsp;+&nbsp;n | A UTF-8 string. |
| `Type.Boolean` | `boolean` | 1 | A single boolean. |
| `Type.BooleanTuple` | `boolean[]` | 1<sup>¶</sup> | An array of booleans. Dynamically sized. |
| `Type.Bitmask8` | `boolean[]` | 1 | 1-8 booleans. |
| `Type.Bitmask16` | `boolean[]` | 2 | 1-16 booleans. |
| `Type.Bitmask32` | `boolean[]` | 4 | 1-32 booleans. |
| `Type.JSON` | `any` | 1<sup>†</sup>&nbsp;+&nbsp;n | [JSON format](http://json.org/) data, encoded as a UTF-8 string. |
| `Type.Binary` | `ArrayBuffer` | 1<sup>†</sup>&nbsp;+&nbsp;n | JavaScript `ArrayBuffer` data. |
| `Type.RegExp` | `RegExp` | 1<sup>†</sup>&nbsp;+&nbsp;n&nbsp;+&nbsp;1 | JavaScript `RegExp` object. |
| `Type.Date` | `Date` | 8 | JavaScript `Date` object. |
| `Optional(T)` | `T \| undefined` | 1 | Any optional field. Use the `Optional(...)` helper. Array elements cannot be optional. |
| `[T]` | `Array<T>` | 1<sup>†</sup>&nbsp;+&nbsp;n | Use array syntax. Any array. |
| `{}` | `object` | _none_ | Use object syntax. No overhead to using object types. Buffers are ordered, flattened structures. |

<sup>\*</sup>`Int` encodes <±64 = 1 byte, <±8,192 = 2 bytes, <±268,435,456 = 4 bytes, otherwise = 8 bytes.

<sup>#</sup>`UInt` encodes <128 = 1 byte, <16,384 = 2 bytes, <536,870,912 = 4 bytes, otherwise = 8 bytes.

Expand Down
1 change: 0 additions & 1 deletion dist/core/BinaryCodec.d.ts.map

This file was deleted.

Loading

0 comments on commit d7569f6

Please sign in to comment.