it-pb-stream - npm Package Compare versions

Comparing version 2.0.2 to 2.0.3

dist/src/index.d.ts

@@ -0,21 +1,73 @@
+/**
+ * @packageDocumentation
+ *
+ * This module makes it easy to send and receive Protobuf encoded messages over
+ * streams.
+ *
+ * @example
+ *
+ * ```typescript
+ * import { pbStream } from 'it-pb-stream'
+ * import { MessageType } from './src/my-message-type.js'
+ *
+ * // RequestType and ResponseType have been generate from `.proto` files and have
+ * // `.encode` and `.decode` methods for serialization/deserialization
+ *
+ * const stream = pbStream(duplex)
+ * stream.writePB({
+ *   foo: 'bar'
+ * }, MessageType)
+ * const res = await stream.readPB(MessageType)
+ * ```
+ */
 import * as lp from 'it-length-prefixed';
 import type { Duplex } from 'it-stream-types';
 import type { Uint8ArrayList } from 'uint8arraylist';
-interface Decoder<T> {
+/**
+ * A protobuf decoder - takes a byte array and returns an object
+ */
+export interface Decoder<T> {
     (data: Uint8Array | Uint8ArrayList): T;
 }
-interface Encoder<T> {
+/**
+ * A protobuf encoder - takes an object and returns a byte array
+ */
+export interface Encoder<T> {
     (data: T): Uint8Array;
 }
+/**
+ * Convinience methods for working with protobuf streams
+ */
 export interface ProtobufStream {
+    /**
+     * Read a set number of bytes from the stream
+     */
     read: (bytes?: number) => Promise<Uint8ArrayList>;
+    /**
+     * Read the next length-prefixed number of bytes from the stream
+     */
     readLP: () => Promise<Uint8ArrayList>;
+    /**
+     * Read the next length-prefixed byte array from the stream and decode it as the passed protobuf format
+     */
     readPB: <T>(proto: {
         decode: Decoder<T>;
     }) => Promise<T>;
+    /**
+     * Write the passed bytes to the stream
+     */
     write: (input: Uint8Array | Uint8ArrayList) => void;
+    /**
+     * Write the passed bytes to the stream prefixed by their length
+     */
     writeLP: (input: Uint8Array | Uint8ArrayList) => void;
-    writePB: (data: Uint8Array | Uint8ArrayList, proto: {
-        encode: Encoder<any>;
+    /**
+     * Encode the passed object as a protobuf message and write it's length-prefixed bytes tot he stream
+     */
+    writePB: <T>(data: T, proto: {
+        encode: Encoder<T>;
     }) => void;
+    /**
+     * Returns an object with read/write methods for operating on protobuf messages
+     */
     pb: <T>(proto: {
@@ -26,4 +78,7 @@ encode: Encoder<T>;
         read: () => Promise<T>;
-        write: (d: Uint8Array | Uint8ArrayList) => void;
+        write: (d: T) => void;
     };
+    /**
+     * Returns the underlying stream
+     */
     unwrap: () => Duplex<Uint8ArrayList, Uint8Array>;
@@ -39,4 +94,3 @@ }
 }
-export declare function pbStream(duplex: Duplex<Uint8Array>, opts?: {}): ProtobufStream;
-export {};
+export declare function pbStream(duplex: Duplex<Uint8ArrayList | Uint8Array, Uint8Array>, opts?: {}): ProtobufStream;
 //# sourceMappingURL=index.d.ts.map

dist/src/index.js

@@ -0,1 +1,23 @@
+/**
+ * @packageDocumentation
+ *
+ * This module makes it easy to send and receive Protobuf encoded messages over
+ * streams.
+ *
+ * @example
+ *
+ * ```typescript
+ * import { pbStream } from 'it-pb-stream'
+ * import { MessageType } from './src/my-message-type.js'
+ *
+ * // RequestType and ResponseType have been generate from `.proto` files and have
+ * // `.encode` and `.decode` methods for serialization/deserialization
+ *
+ * const stream = pbStream(duplex)
+ * stream.writePB({
+ *   foo: 'bar'
+ * }, MessageType)
+ * const res = await stream.readPB(MessageType)
+ * ```
+ */
 import { handshake } from 'it-handshake';
@@ -31,3 +53,3 @@ import * as lp from 'it-length-prefixed';
             // Is this a buffer?
-            const buf = value instanceof Uint8Array ? value : value.slice();
+            const buf = value instanceof Uint8Array ? value : value.subarray();
             return proto.decode(buf);
@@ -41,3 +63,3 @@ },
             else {
-                shake.writer.push(data.slice());
+                shake.writer.push(data.subarray());
             }
@@ -44,0 +66,0 @@ },

package.json

 {
   "name": "it-pb-stream",
-  "version": "2.0.2",
+  "version": "2.0.3",
   "description": "A convenience-wrapper around protocol-buffers and lp-messages functions",
@@ -23,3 +23,3 @@ "author": "Alex Potsides <[e-mail]>",
     "src",
-    "dist/src",
+    "dist",
     "!dist/test",
@@ -137,3 +137,4 @@ "!**/*.tsbuildinfo"
     "test:electron-main": "aegir test -t electron-main",
-    "release": "aegir release"
+    "release": "aegir release",
+    "docs": "aegir docs"
   },
@@ -147,7 +148,7 @@ "dependencies": {
   "devDependencies": {
-    "aegir": "^37.4.7",
+    "aegir": "^37.7.11",
     "buffer": "^6.0.3",
     "it-pair": "^2.0.2",
-    "uint8arrays": "^3.0.0"
+    "uint8arrays": "^4.0.2"
   }
 }

README.md

 # it-pb-stream <!-- omit in toc -->
 
 [![codecov](https://img.shields.io/codecov/c/github/achingbrain/it-pb-stream.svg?style=flat-square)](https://codecov.io/gh/achingbrain/it-pb-stream)
-[![CI](https://img.shields.io/github/workflow/status/achingbrain/it-pb-stream/test%20&%20maybe%20release/master?style=flat-square)](https://github.com/achingbrain/it-pb-stream/actions/workflows/js-test-and-release.yml)
+[![CI](https://img.shields.io/github/actions/workflow/status/achingbrain/it-pb-stream/js-test-and-release.yml?branch=master\&style=flat-square)](https://github.com/achingbrain/it-pb-stream/actions/workflows/js-test-and-release.yml?query=branch%3Amaster)
 
@@ -11,3 +11,5 @@ > A convenience-wrapper around protocol-buffers and lp-messages functions
 - [Install](#install)
+  - [Browser `<script>` tag](#browser-script-tag)
 - [Usage](#usage)
+- [API Docs](#api-docs)
 - [License](#license)
@@ -22,6 +24,14 @@ - [Contribution](#contribution)
 
+### Browser `<script>` tag
+
+Loading this module through a script tag will make it's exports available as `ItPbStream` in the global namespace.
+
+```html
+<script src="https://unpkg.com/it-pb-stream/dist/index.min.js"></script>
+```
+
 - [Install](#install)
-  - [npm](#npm)
 - [Usage](#usage)
 - [License](#license)
+- [Contribution](#contribution)
 
@@ -43,2 +53,6 @@ ```sh
 
+## API Docs
+
+- <https://achingbrain.github.io/it-pb-stream>
+
 ## License
@@ -45,0 +59,0 @@

src/index.ts

@@ -0,1 +1,24 @@
+/**
+ * @packageDocumentation
+ *
+ * This module makes it easy to send and receive Protobuf encoded messages over
+ * streams.
+ *
+ * @example
+ *
+ * ```typescript
+ * import { pbStream } from 'it-pb-stream'
+ * import { MessageType } from './src/my-message-type.js'
+ *
+ * // RequestType and ResponseType have been generate from `.proto` files and have
+ * // `.encode` and `.decode` methods for serialization/deserialization
+ *
+ * const stream = pbStream(duplex)
+ * stream.writePB({
+ *   foo: 'bar'
+ * }, MessageType)
+ * const res = await stream.readPB(MessageType)
+ * ```
+ */
+
 import { handshake } from 'it-handshake'
@@ -6,20 +29,58 @@ import * as lp from 'it-length-prefixed'
 
-interface Decoder<T> {
+/**
+ * A protobuf decoder - takes a byte array and returns an object
+ */
+export interface Decoder<T> {
   (data: Uint8Array | Uint8ArrayList): T
 }
 
-interface Encoder<T> {
+/**
+ * A protobuf encoder - takes an object and returns a byte array
+ */
+export interface Encoder<T> {
   (data: T): Uint8Array
 }
 
+/**
+ * Convinience methods for working with protobuf streams
+ */
 export interface ProtobufStream {
+  /**
+   * Read a set number of bytes from the stream
+   */
   read: (bytes?: number) => Promise<Uint8ArrayList>
+
+  /**
+   * Read the next length-prefixed number of bytes from the stream
+   */
   readLP: () => Promise<Uint8ArrayList>
+
+  /**
+   * Read the next length-prefixed byte array from the stream and decode it as the passed protobuf format
+   */
   readPB: <T>(proto: { decode: Decoder<T> }) => Promise<T>
+
+  /**
+   * Write the passed bytes to the stream
+   */
   write: (input: Uint8Array | Uint8ArrayList) => void
+
+  /**
+   * Write the passed bytes to the stream prefixed by their length
+   */
   writeLP: (input: Uint8Array | Uint8ArrayList) => void
-  writePB: (data: Uint8Array | Uint8ArrayList, proto: {encode: Encoder<any>}) => void
-  pb: <T> (proto: {encode: Encoder<T>, decode: Decoder<T> }) => {read: () => Promise<T>, write: (d: Uint8Array | Uint8ArrayList) => void}
 
-  // return vanilla duplex
+  /**
+   * Encode the passed object as a protobuf message and write it's length-prefixed bytes tot he stream
+   */
+  writePB: <T>(data: T, proto: {encode: Encoder<T>}) => void
+
+  /**
+   * Returns an object with read/write methods for operating on protobuf messages
+   */
+  pb: <T> (proto: {encode: Encoder<T>, decode: Decoder<T> }) => {read: () => Promise<T>, write: (d: T) => void}
+
+  /**
+   * Returns the underlying stream
+   */
   unwrap: () => Duplex<Uint8ArrayList, Uint8Array>
@@ -40,3 +101,3 @@ }
 
-export function pbStream (duplex: Duplex<Uint8Array>, opts = {}): ProtobufStream {
+export function pbStream (duplex: Duplex<Uint8ArrayList | Uint8Array, Uint8Array>, opts = {}): ProtobufStream {
   const shake = handshake(duplex)
@@ -79,3 +140,3 @@ const lpReader = lp.decode.fromReader(
       // Is this a buffer?
-      const buf = value instanceof Uint8Array ? value : value.slice()
+      const buf = value instanceof Uint8Array ? value : value.subarray()
 
@@ -89,3 +150,3 @@ return proto.decode(buf)
       } else {
-        shake.writer.push(data.slice())
+        shake.writer.push(data.subarray())
       }
@@ -92,0 +153,0 @@ },

No alert changes

Improved metrics

Total package byte prevSize

35243

increased by134.58%

Number of package files

10

increased by25%

Lines of code

395

increased by99.49%

Number of lines in readme file

65

increased by27.45%

No dependency changes