feat: add types

Author: vasco-santos

package.json

@@ -12,15 +12,15 @@
   "scripts": {
     "lint": "aegir lint",
     "build": "aegir build",
-    "pregenerate:types": "rimraf './src/**/*.d.ts'",
-    "generate:types": "tsc --build",
     "test": "aegir test",
     "test:node": "aegir test --target node",
     "test:browser": "aegir test --target browser",
+    "test:types": "aegir ts -p check",
     "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"
+    "release-major": "aegir release --type major -t node -t browser",
+    "remove:types": "rimraf './src/**/*.d.ts'"
   },
   "repository": {
     "type": "git",
@@ -63,13 +63,13 @@
     "protons": "^2.0.0",
     "sinon": "^9.0.2",
     "streaming-iterables": "^5.0.2",
+    "typescript": "^4.1.2",
     "uint8arrays": "^1.1.0"
   },
   "devDependencies": {
-    "aegir": "^25.0.0",
+    "aegir": "^29.2.0",
     "it-handshake": "^1.0.1",
-    "rimraf": "^3.0.2",
-    "typescript": "^4.0.5"
+    "rimraf": "^3.0.2"
   },
   "contributors": [
     "Alan Shaw <alan.shaw@protocol.ai>",

src/connection/connection.d.ts

@@ -1,4 +1,27 @@
 export = Connection;
+/**
+ * @typedef {import('../stream-muxer/types').MuxedStream} MuxedStream
+ */
+/**
+ * @typedef {Object} ConectionStat
+ * @property {string} direction - connection establishment direction ("inbound" or "outbound").
+ * @property {object} timeline - connection relevant events timestamp.
+ * @property {number} timeline.open - connection opening timestamp.
+ * @property {number} [timeline.upgraded] - connection upgraded timestamp.
+ * @property {number} [timeline.close] - connection upgraded timestamp.
+ * @property {string} [multiplexer] - connection multiplexing identifier.
+ * @property {string} [encryption] - connection encryption method identifier.
+ *
+ * @typedef {Object} ConnectionOptions
+ * @property {multiaddr} [localAddr] - local multiaddr of the connection if known.
+ * @property {multiaddr} remoteAddr - remote multiaddr of the connection.
+ * @property {PeerId} localPeer - local peer-id.
+ * @property {PeerId} remotePeer - remote peer-id.
+ * @property {(protocols: string|string[]) => Promise<{stream: MuxedStream, protocol: string}>} newStream - new stream muxer function.
+ * @property {() => Promise<void>} close - close raw connection function.
+ * @property {() => MuxedStream[]} getStreams - get streams from muxer function.
+ * @property {ConectionStat} stat - metadata of the connection.
+ */
 /**
  * An implementation of the js-libp2p connection.
  * Any libp2p transport should use an upgrader to return this connection.
@@ -12,149 +35,224 @@ declare class Connection {
      */
     static isConnection(other: any): other is 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: multiaddr | undefined;
-        remoteAddr: multiaddr | undefined;
-        localPeer: PeerId;
-        remotePeer: PeerId;
-        newStream: Function;
-        close: Function;
-        getStreams: () => any[];
-        stat: {
-            direction: string;
-            timeline: {
-                open: string;
-                upgraded: string;
-            };
-            multiplexer: string | undefined;
-            encryption: string | undefined;
-        };
-    });
+     * An implementation of the js-libp2p connection.
+     * Any libp2p transport should use an upgrader to return this connection.
+     *
+     * @class
+     * @param {ConnectionOptions} options
+     */
+    constructor({ localAddr, remoteAddr, localPeer, remotePeer, newStream, close, getStreams, stat }: ConnectionOptions);
     /**
      * Connection identifier.
      */
     id: string;
     /**
      * Observed multiaddr of the local peer
      */
-    localAddr: multiaddr | undefined;
+    localAddr: import("multiaddr") | undefined;
     /**
      * Observed multiaddr of the remote peer
      */
-    remoteAddr: multiaddr | undefined;
+    remoteAddr: import("multiaddr");
     /**
      * Local peer id.
      */
-    localPeer: PeerId;
+    localPeer: import("peer-id");
     /**
      * Remote peer id.
      */
-    remotePeer: PeerId;
+    remotePeer: import("peer-id");
     /**
      * Connection metadata.
      */
     _stat: {
         status: "open";
+        /**
+         * - connection establishment direction ("inbound" or "outbound").
+         */
         direction: string;
+        /**
+         * - connection relevant events timestamp.
+         */
         timeline: {
-            open: string;
-            upgraded: string;
+            open: number;
+            upgraded: number | undefined;
+            close: number | undefined;
         };
+        /**
+         * - connection multiplexing identifier.
+         */
         multiplexer?: string | undefined;
+        /**
+         * - connection encryption method identifier.
+         */
         encryption?: string | undefined;
     };
     /**
      * Reference to the new stream function of the multiplexer
      */
-    _newStream: Function;
+    _newStream: (protocols: string | string[]) => Promise<{
+        stream: MuxedStream;
+        protocol: string;
+    }>;
     /**
      * Reference to the close function of the raw connection
      */
-    _close: Function;
+    _close: () => Promise<void>;
     /**
      * Reference to the getStreams function of the muxer
      */
-    _getStreams: () => any[];
+    _getStreams: () => MuxedStream[];
     /**
      * Connection streams registry
      */
     registry: Map<any, any>;
     /**
      * User provided tags
+     *
      * @type {string[]}
      */
     tags: string[];
     get [Symbol.toStringTag](): string;
     /**
      * Get connection metadata
+     *
      * @this {Connection}
      */
     get stat(): {
         status: "open";
+        /**
+         * - connection establishment direction ("inbound" or "outbound").
+         */
         direction: string;
+        /**
+         * - connection relevant events timestamp.
+         */
         timeline: {
-            open: string;
-            upgraded: string;
+            open: number;
+            upgraded: number | undefined;
+            close: number | undefined;
         };
+        /**
+         * - connection multiplexing identifier.
+         */
         multiplexer?: string | undefined;
+        /**
+         * - connection encryption method identifier.
+         */
         encryption?: string | undefined;
     };
     /**
      * Get all the streams of the muxer.
+     *
      * @this {Connection}
      */
-    get streams(): any[];
+    get streams(): import("../stream-muxer/types").MuxedStream[];
     /**
      * 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
+     *
+     * @param {string|string[]} protocols - intended protocol for the stream
+     * @returns {Promise<{stream: MuxedStream, protocol: string}>} with muxed+multistream-selected stream and selected protocol
      */
-    newStream(protocols: string[]): Promise<{
-        stream: any;
+    newStream(protocols: string | string[]): Promise<{
+        stream: MuxedStream;
         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}
+     *
+     * @param {MuxedStream} 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
+     * @returns {void}
      */
-    addStream(muxedStream: any, { protocol, metadata }: {
+    addStream(muxedStream: MuxedStream, { protocol, metadata }: {
         protocol: string;
         metadata: object;
     }): void;
     /**
      * Remove stream registry after it is closed.
-     * @param {string} id identifier of the stream
+     *
+     * @param {string} id - identifier of the stream
      */
     removeStream(id: string): void;
     /**
      * Close the connection.
-     * @return {Promise<void>}
+     *
+     * @returns {Promise<void>}
      */
     close(): Promise<void>;
-    _closing: any;
-    get [connectionSymbol](): boolean;
+    _closing: void | undefined;
+}
+declare namespace Connection {
+    export { MuxedStream, ConectionStat, ConnectionOptions };
 }
-import multiaddr = require("multiaddr");
-import PeerId = require("peer-id");
-declare const connectionSymbol: unique symbol;
+type MuxedStream = {
+    close: () => void;
+    abort: () => void;
+    reset: () => void;
+    sink: (source: Uint8Array) => Promise<Uint8Array>;
+    source: () => AsyncIterable<Uint8Array>;
+    timeline: import("../stream-muxer/types").MuxedTimeline;
+    id: string;
+};
+type ConnectionOptions = {
+    /**
+     * - local multiaddr of the connection if known.
+     */
+    localAddr?: import("multiaddr") | undefined;
+    /**
+     * - remote multiaddr of the connection.
+     */
+    remoteAddr: import("multiaddr");
+    /**
+     * - local peer-id.
+     */
+    localPeer: import("peer-id");
+    /**
+     * - remote peer-id.
+     */
+    remotePeer: import("peer-id");
+    /**
+     * - new stream muxer function.
+     */
+    newStream: (protocols: string | string[]) => Promise<{
+        stream: MuxedStream;
+        protocol: string;
+    }>;
+    /**
+     * - close raw connection function.
+     */
+    close: () => Promise<void>;
+    /**
+     * - get streams from muxer function.
+     */
+    getStreams: () => MuxedStream[];
+    /**
+     * - metadata of the connection.
+     */
+    stat: ConectionStat;
+};
+type ConectionStat = {
+    /**
+     * - connection establishment direction ("inbound" or "outbound").
+     */
+    direction: string;
+    /**
+     * - connection relevant events timestamp.
+     */
+    timeline: {
+        open: number;
+        upgraded: number | undefined;
+        close: number | undefined;
+    };
+    /**
+     * - connection multiplexing identifier.
+     */
+    multiplexer?: string | undefined;
+    /**
+     * - connection encryption method identifier.
+     */
+    encryption?: string | undefined;
+};