structurae - npm Package Compare versions

Comparing version 2.0.1 to 2.1.0

CHANGELOG.md

@@ -7,2 +7,10 @@ # Changelog
 
+## [2.1.0] - 2020-02-11
+### Added
+- BinaryProtocol class to simplify operating on tagged ObjectView
+
+## [2.0.1] - 2020-01-09
+### Fixed
+- TypeScript type declarations for ObjectView
+
 ## [2.0.0] - 2019-11-21
@@ -9,0 +17,0 @@ ### Removed

index.d.ts

@@ -329,2 +329,17 @@ // Type definitions for structurae
 
+interface BinaryProtocolSchema {
+    [propName: number]: object|typeof ObjectView;
+}
+
+export declare class BinaryProtocol {
+    Views: BinaryProtocolSchema;
+    private tagName: string;
+    private tagType: PrimitiveFieldType;
+
+    constructor(views: BinaryProtocolSchema, tagName?: string, tagType?: string);
+    view(buffer: ArrayBuffer, offset?: number): ObjectView;
+    encode(object: object, arrayBuffer?: ArrayBuffer, offset?: number): ObjectView;
+    decode(buffer: ArrayBuffer, offset?: number): object;
+}
+
 export declare class BitArray extends Uint32Array {
@@ -331,0 +346,0 @@ size: number;

index.js

@@ -21,2 +21,3 @@ const BitField = require('./lib/bit-field');
 const TypedArrayViewMixin = require('./lib/typed-array-view');
+const BinaryProtocol = require('./lib/binary-protocol');
 
@@ -61,2 +62,3 @@ /**
   TypedArrayViewMixin,
+  BinaryProtocol,
 };

package.json

 {
   "name": "structurae",
-  "version": "2.0.1",
+  "version": "2.1.0",
   "description": "Data structures for performance-sensitive modern JavaScript applications.",
@@ -47,8 +47,8 @@ "main": "index.js",
   "devDependencies": {
-    "@types/jest": "^24.0.25",
+    "@types/jest": "^25.1.2",
     "benchmark": "^2.1.4",
     "eslint": "^6.8.0",
     "eslint-config-airbnb-base": "^14.0.0",
-    "eslint-plugin-import": "^2.19.1",
-    "jest": "^24.9.0",
+    "eslint-plugin-import": "^2.20.1",
+    "jest": "^25.1.0",
     "jsdoc-to-markdown": "^5.0.3",
@@ -55,0 +55,0 @@ "json-schema-faker": "^0.5.0-rc23"

README.md

@@ -14,2 +14,3 @@ # Structurae
     - [TypedArrayView](https://github.com/zandaqo/structurae#TypedArrayView) - a DataView based TypedArray that supports endianness and can be set at any offset.
+    - [BinaryProtocol](https://github.com/zandaqo/structurae#BinaryProtocol) - a helper class that simplifies defining and operating on multiple tagged ObjectViews.
 - Bit Structures:
@@ -309,2 +310,73 @@ - [BitField & BigBitField](https://github.com/zandaqo/structurae#BitField) - stores and operates on data in Numbers and BigInts treating them as bitfields.
 
+#### BinaryProtocol
+When transferring our buffers encoded with views we can often rely on meta information to know what kind of ObjectView
+to use in order to decode a received buffer, e.g. let's say we have a `HouseView` class to encode/decode all buffers
+that go through `/houses` route. However, sometimes we need our ObjectViews to carry within themselves an information
+as to what kind of ObjectView was used to encode them. To do that, we can prepend or tag each view with a value indicating its
+class, i.e. add a field that defaults to a certain value for each view class. Now upon receiving a buffer we can read that field
+using the DataView and convert it into an appropriate view. The `BinaryProtocol` does all that under the hood serving as a helper class
+to remove boilerplate, plus it creates the necessary ObjectView classes from schemas for when we are not concerned too much about individual
+classes:
+
+```javascript
+const { BinaryProtocol } = require('structurae');
+
+const protocol = new BinaryProtocol({
+  0: {
+    age: { type: 'int8' },
+    name: { type: 'string', length: 10 },
+  },
+  1: {
+    id: { type: 'uint32' },
+    items: { type: 'string', size: 3, length: 10 },
+  },
+});
+
+const person = protocol.encode({ tag: 0, age: 100, name: 'abc' });
+//=> ObjectView (12)
+protocol.decode(person.buffer)
+//=> { tag: 0, age: 100, name: 'abc' }
+const personView = protocol.view(person.buffer);
+personView.get('age');
+//=> 100
+const item = protocol.encode({ tag: 1, id: 10, items: ['a', 'b', 'c'] });
+//=> ObjectView (35)
+protocol.decode(item.buffer)
+//=> { tag: 1, id: 10, items: ['a', 'b', 'c'] }
+```
+
+We can of course define ObjectViews separately, however we will have to specify that tag field by ourselves in that case.
+```javascript
+const View = ObjectViewMixin({
+  tag: { type: 'uint8', default: 1 },
+  id: { type: 'uint32' },
+  items: { type: 'string', size: 3, length: 10 },
+});
+
+const protocol = new BinaryProtocol({
+  0: {
+   age: { type: 'int8' },
+   name: { type: 'string', length: 10 },
+  },
+  1: View,
+});
+```
+
+By default, the tag field is named `tag` and has the type of `uint8`, both can be changed and provided as second and third parameters to protocol constructor.
+```javascript
+const View = ObjectViewMixin({
+  tagId: { type: 'uint32', default: 1 },
+  id: { type: 'uint32' },
+  items: { type: 'string', size: 3, length: 10 },
+});
+
+const protocol = new BinaryProtocol({
+  0: {
+   age: { type: 'int8' },
+   name: { type: 'string', length: 10 },
+  },
+  1: View,
+}, 'tagId', 'uint32');
+```
+
 ### Bit Structures
@@ -311,0 +383,0 @@ #### BitField & BigBitField

No alert changes

Improved metrics

Total package byte prevSize

202556

increased by3.58%

Number of package files

30

increased by3.45%

Lines of code

5546

increased by2.23%

Number of lines in readme file

955

increased by8.15%

No dependency changes