Add type generation from jsdoc

package.json

@@ -4,16 +4,21 @@
   "description": "Interfaces for JS Libp2p",
   "leadMaintainer": "Jacob Heun <jacobheun@gmail.com>",
   "main": "src/index.js",
+  "types": "types/src/index.d.ts",
   "files": [
     "src",
+    "types",
     "dist"
   ],
   "scripts": {
     "lint": "aegir lint",
     "build": "aegir build",
+    "pregenerate:types": "rimraf './src/**/*.d.ts'",
+    "generate:types": "tsc",
     "test": "aegir test",
     "test:node": "aegir test --target node",
     "test:browser": "aegir test --target browser",
+    "prepublishOnly": "npm run generate:types",
     "release": "aegir release -t node -t browser",
     "release-minor": "aegir release --type minor -t node -t browser",
     "release-major": "aegir release --type major -t node -t browser"
@@ -63,7 +68,9 @@
   },
   "devDependencies": {
     "aegir": "^25.0.0",
-    "it-handshake": "^1.0.1"
+    "it-handshake": "^1.0.1",
+    "rimraf": "^3.0.2",
+    "typescript": "3.7.5"
   },
   "contributors": [
     "Alan Shaw <alan.shaw@protocol.ai>",

src/connection/connection.d.ts

@@ -0,0 +1,149 @@
+declare const _exports: typeof Connection;
+export = _exports;
+/**
+ * An implementation of the js-libp2p connection.
+ * Any libp2p transport should use an upgrader to return this connection.
+ */
+declare class Connection {
+    /**
+     * Creates an instance of Connection.
+     * @param {object} properties properties of the connection.
+     * @param {multiaddr} [properties.localAddr] local multiaddr of the connection if known.
+     * @param {multiaddr} [properties.remoteAddr] remote multiaddr of the connection.
+     * @param {PeerId} properties.localPeer local peer-id.
+     * @param {PeerId} properties.remotePeer remote peer-id.
+     * @param {function} properties.newStream new stream muxer function.
+     * @param {function} properties.close close raw connection function.
+     * @param {function(): Stream[]} properties.getStreams get streams from muxer function.
+     * @param {object} properties.stat metadata of the connection.
+     * @param {string} properties.stat.direction connection establishment direction ("inbound" or "outbound").
+     * @param {object} properties.stat.timeline connection relevant events timestamp.
+     * @param {string} properties.stat.timeline.open connection opening timestamp.
+     * @param {string} properties.stat.timeline.upgraded connection upgraded timestamp.
+     * @param {string} [properties.stat.multiplexer] connection multiplexing identifier.
+     * @param {string} [properties.stat.encryption] connection encryption method identifier.
+     */
+    constructor({ localAddr, remoteAddr, localPeer, remotePeer, newStream, close, getStreams, stat }: {
+        localAddr?: import("multiaddr");
+        remoteAddr?: import("multiaddr");
+        localPeer: import("peer-id");
+        remotePeer: import("peer-id");
+        newStream: Function;
+        close: Function;
+        getStreams: () => any[];
+        stat: {
+            direction: string;
+            timeline: {
+                open: string;
+                upgraded: string;
+            };
+            multiplexer?: string;
+            encryption?: string;
+        };
+    });
+    /**
+     * Connection identifier.
+     */
+    id: any;
+    /**
+     * Observed multiaddr of the local peer
+     */
+    localAddr: import("multiaddr");
+    /**
+     * Observed multiaddr of the remote peer
+     */
+    remoteAddr: import("multiaddr");
+    /**
+     * Local peer id.
+     */
+    localPeer: import("peer-id");
+    /**
+     * Remote peer id.
+     */
+    remotePeer: import("peer-id");
+    /**
+     * Connection metadata.
+     */
+    _stat: {
+        status: string;
+        direction: string;
+        timeline: {
+            open: string;
+            upgraded: string;
+        };
+        multiplexer?: string;
+        encryption?: string;
+    };
+    /**
+     * Reference to the new stream function of the multiplexer
+     */
+    _newStream: Function;
+    /**
+     * Reference to the close function of the raw connection
+     */
+    _close: Function;
+    /**
+     * Reference to the getStreams function of the muxer
+     */
+    _getStreams: () => any[];
+    /**
+     * Connection streams registry
+     */
+    registry: Map<any, any>;
+    /**
+     * User provided tags
+     * @type {string[]}
+     */
+    tags: string[];
+    /**
+     * Get connection metadata
+     * @this {Connection}
+     */
+    get stat(): {
+        status: string;
+        direction: string;
+        timeline: {
+            open: string;
+            upgraded: string;
+        };
+        multiplexer?: string;
+        encryption?: string;
+    };
+    /**
+     * Get all the streams of the muxer.
+     * @this {Connection}
+     */
+    get streams(): any[];
+    /**
+     * Create a new stream from this connection
+     * @param {string[]} protocols intended protocol for the stream
+     * @return {Promise<{stream: Stream, protocol: string}>} with muxed+multistream-selected stream and selected protocol
+     */
+    newStream(protocols: string[]): Promise<{
+        stream: any;
+        protocol: string;
+    }>;
+    /**
+     * Add a stream when it is opened to the registry.
+     * @param {*} muxedStream a muxed stream
+     * @param {object} properties the stream properties to be registered
+     * @param {string} properties.protocol the protocol used by the stream
+     * @param {object} properties.metadata metadata of the stream
+     * @return {void}
+     */
+    addStream(muxedStream: any, { protocol, metadata }: {
+        protocol: string;
+        metadata: any;
+    }): void;
+    /**
+     * Remove stream registry after it is closed.
+     * @param {string} id identifier of the stream
+     */
+    removeStream(id: string): void;
+    /**
+     * Close the connection.
+     * @return {Promise<void>}
+     */
+    close(): Promise<void>;
+    _closing: any;
+}

src/connection/connection.js

@@ -66,7 +66,7 @@ class Connection {
    * @param {PeerId} properties.remotePeer remote peer-id.
    * @param {function} properties.newStream new stream muxer function.
    * @param {function} properties.close close raw connection function.
-   * @param {function} properties.getStreams get streams from muxer function.
+   * @param {function(): Stream[]} properties.getStreams get streams from muxer function.
    * @param {object} properties.stat metadata of the connection.
    * @param {string} properties.stat.direction connection establishment direction ("inbound" or "outbound").
    * @param {object} properties.stat.timeline connection relevant events timestamp.
@@ -133,21 +133,22 @@ class Connection {
 
     /**
      * User provided tags
+     * @type {string[]}
      */
     this.tags = []
   }
 
   /**
    * Get connection metadata
-   * @return {Object}
+   * @this {Connection}
    */
   get stat () {
     return this._stat
   }
 
   /**
    * Get all the streams of the muxer.
-   * @return {Array<*>}
+   * @this {Connection}
    */
   get streams () {
     return this._getStreams()
@@ -156,7 +157,7 @@ class Connection {
   /**
    * Create a new stream from this connection
    * @param {string[]} protocols intended protocol for the stream
-   * @return {Promise<object>} with muxed+multistream-selected stream and selected protocol
+   * @return {Promise<{stream: Stream, protocol: string}>} with muxed+multistream-selected stream and selected protocol
    */
   async newStream (protocols) {
     if (this.stat.status === Status.CLOSING) {
@@ -205,7 +206,7 @@ class Connection {
 
   /**
    * Close the connection.
-   * @return {Promise}
+   * @return {Promise<void>}
    */
   async close () {
     if (this.stat.status === Status.CLOSED) {
@@ -226,4 +227,8 @@ class Connection {
   }
 }
 
+/**
+ * @module
+ * @type {typeof Connection}
+ */
 module.exports = withIs(Connection, { className: 'Connection', symbolName: '@libp2p/interface-connection/connection' })

src/connection/index.d.ts

@@ -0,0 +1 @@
+export var Connection: typeof import('./connection');

src/connection/index.js

@@ -1,3 +1,7 @@
 'use strict'
 
+/**
+ * @module connection/index
+ * @type {typeof import('./connection')}
+ */
 exports.Connection = require('./connection')

src/connection/status.d.ts

@@ -0,0 +1,3 @@
+export declare const OPEN: string;
+export declare const CLOSING: string;
+export declare const CLOSED: string;

src/crypto/errors.d.ts

@@ -0,0 +1,15 @@
+export class UnexpectedPeerError extends Error {
+    static get code(): string;
+    constructor(message?: string);
+    code: string;
+}
+export class InvalidCryptoExchangeError extends Error {
+    static get code(): string;
+    constructor(message?: string);
+    code: string;
+}
+export class InvalidCryptoTransmissionError extends Error {
+    static get code(): string;
+    constructor(message?: string);
+    code: string;
+}

src/pubsub/errors.d.ts

@@ -0,0 +1,4 @@
+export namespace codes {
+    export const ERR_MISSING_SIGNATURE: string;
+    export const ERR_INVALID_SIGNATURE: string;
+}