@libp2p/interface 1.1.2 → 1.1.3-bedfd0aa2

package/README.md

@@ -5,20 +5,6 @@
 
 > The interface implemented by a libp2p node
 
-# About
-
-Exports a `Libp2p` type for modules to use as a type argument.
-
-## Example
-
-```typescript
-import type { Libp2p } from '@libp2p/interface'
-
-function doSomethingWithLibp2p (node: Libp2p) {
-  // ...
-}
-```
-
 # Install
 
 ```console

package/dist/index.min.js

@@ -1,3 +1,3 @@
 (function (root, factory) {(typeof module === 'object' && module.exports) ? module.exports = factory() : root.Libp2PInterface = factory()}(typeof self !== 'undefined' ? self : this, function () {
-"use strict";var Libp2PInterface=(()=>{var n=Object.defineProperty;var y=Object.getOwnPropertyDescriptor;var _=Object.getOwnPropertyNames;var L=Object.prototype.hasOwnProperty;var g=(e,t)=>{for(var o in t)n(e,o,{get:t[o],enumerable:!0})},I=(e,t,o,s)=>{if(t&&typeof t=="object"||typeof t=="function")for(let r of _(t))!L.call(e,r)&&r!==o&&n(e,r,{get:()=>t[r],enumerable:!(s=y(t,r))||s.enumerable});return e};var N=e=>I(n({},"__esModule",{value:!0}),e);var q={};g(q,{AbortError:()=>i,AggregateCodeError:()=>l,CodeError:()=>a,CustomEvent:()=>b,ERR_INVALID_MESSAGE:()=>X,ERR_INVALID_PARAMETERS:()=>G,ERR_NOT_FOUND:()=>j,ERR_TIMEOUT:()=>F,Ed25519:()=>w,FaultTolerance:()=>p,InvalidCryptoExchangeError:()=>x,InvalidCryptoTransmissionError:()=>u,KEEP_ALIVE:()=>C,RSA:()=>P,StrictNoSign:()=>k,StrictSign:()=>U,TopicValidatorResult:()=>c,TypedEventEmitter:()=>m,UnexpectedPeerError:()=>f,connectionSymbol:()=>S,contentRoutingSymbol:()=>v,isConnection:()=>T,isPeerId:()=>M,isStartable:()=>E,isTransport:()=>B,peerDiscoverySymbol:()=>D,peerIdSymbol:()=>R,peerRoutingSymbol:()=>V,secp256k1:()=>O,setMaxListeners:()=>Y,start:()=>H,stop:()=>K,transportSymbol:()=>A});var S=Symbol.for("@libp2p/connection");function T(e){return e!=null&&!!e[S]}var v=Symbol.for("@libp2p/content-routing");var w="Ed25519",P="RSA",O="secp256k1";var D=Symbol.for("@libp2p/peer-discovery");var R=Symbol.for("@libp2p/peer-id");function M(e){return e!=null&&!!e[R]}var V=Symbol.for("@libp2p/peer-routing");var C="keep-alive";var U="StrictSign",k="StrictNoSign",c;(function(e){e.Accept="accept",e.Ignore="ignore",e.Reject="reject"})(c||(c={}));var A=Symbol.for("@libp2p/transport");function B(e){return e!=null&&!!e[A]}var p;(function(e){e[e.FATAL_ALL=0]="FATAL_ALL",e[e.NO_FATAL=1]="NO_FATAL"})(p||(p={}));var i=class e extends Error{code;type;constructor(t="The operation was aborted"){super(t),this.code=e.code,this.type=e.type}static code="ABORT_ERR";static type="aborted"},a=class extends Error{code;props;constructor(t,o,s){super(t),this.code=o,this.name=s?.name??"CodeError",this.props=s??{}}},l=class extends AggregateError{code;props;constructor(t,o,s,r){super(t,o),this.code=s,this.name=r?.name??"AggregateCodeError",this.props=r??{}}},f=class e extends Error{code;constructor(t="Unexpected Peer"){super(t),this.code=e.code}static code="ERR_UNEXPECTED_PEER"},x=class e extends Error{code;constructor(t="Invalid crypto exchange"){super(t),this.code=e.code}static code="ERR_INVALID_CRYPTO_EXCHANGE"},u=class e extends Error{code;constructor(t="Invalid crypto transmission"){super(t),this.code=e.code}static code="ERR_INVALID_CRYPTO_TRANSMISSION"},F="ERR_TIMEOUT",G="ERR_INVALID_PARAMETERS",j="ERR_NOT_FOUND",X="ERR_INVALID_MESSAGE";var m=class extends EventTarget{#t=new Map;listenerCount(t){let o=this.#t.get(t);return o==null?0:o.length}addEventListener(t,o,s){super.addEventListener(t,o,s);let r=this.#t.get(t);r==null&&(r=[],this.#t.set(t,r)),r.push({callback:o,once:(s!==!0&&s!==!1&&s?.once)??!1})}removeEventListener(t,o,s){super.removeEventListener(t.toString(),o??null,s);let r=this.#t.get(t);r!=null&&(r=r.filter(({callback:h})=>h!==o),this.#t.set(t,r))}dispatchEvent(t){let o=super.dispatchEvent(t),s=this.#t.get(t.type);return s==null||(s=s.filter(({once:r})=>!r),this.#t.set(t.type,s)),o}safeDispatchEvent(t,o={}){return this.dispatchEvent(new b(t,o))}},d=class extends Event{detail;constructor(t,o){super(t,o),this.detail=o?.detail}},b=globalThis.CustomEvent??d;var Y=(e,...t)=>{try{[...t]}catch{}};function E(e){return e!=null&&typeof e.start=="function"&&typeof e.stop=="function"}async function H(...e){let t=[];for(let o of e)E(o)&&t.push(o);await Promise.all(t.map(async o=>{o.beforeStart!=null&&await o.beforeStart()})),await Promise.all(t.map(async o=>{await o.start()})),await Promise.all(t.map(async o=>{o.afterStart!=null&&await o.afterStart()}))}async function K(...e){let t=[];for(let o of e)E(o)&&t.push(o);await Promise.all(t.map(async o=>{o.beforeStop!=null&&await o.beforeStop()})),await Promise.all(t.map(async o=>{await o.stop()})),await Promise.all(t.map(async o=>{o.afterStop!=null&&await o.afterStop()}))}return N(q);})();
+"use strict";var Libp2PInterface=(()=>{var n=Object.defineProperty;var L=Object.getOwnPropertyDescriptor;var _=Object.getOwnPropertyNames;var g=Object.prototype.hasOwnProperty;var I=(e,t)=>{for(var o in t)n(e,o,{get:t[o],enumerable:!0})},N=(e,t,o,s)=>{if(t&&typeof t=="object"||typeof t=="function")for(let r of _(t))!g.call(e,r)&&r!==o&&n(e,r,{get:()=>t[r],enumerable:!(s=L(t,r))||s.enumerable});return e};var T=e=>N(n({},"__esModule",{value:!0}),e);var q={};I(q,{AbortError:()=>i,AggregateCodeError:()=>l,CodeError:()=>a,CustomEvent:()=>b,ERR_INVALID_MESSAGE:()=>Y,ERR_INVALID_PARAMETERS:()=>j,ERR_NOT_FOUND:()=>X,ERR_TIMEOUT:()=>G,Ed25519:()=>P,FaultTolerance:()=>p,InvalidCryptoExchangeError:()=>x,InvalidCryptoTransmissionError:()=>u,KEEP_ALIVE:()=>U,RSA:()=>M,StrictNoSign:()=>B,StrictSign:()=>k,TopicValidatorResult:()=>c,TypedEventEmitter:()=>d,UnexpectedPeerError:()=>f,connectionSymbol:()=>R,contentRoutingSymbol:()=>w,isConnection:()=>v,isPeerId:()=>V,isStartable:()=>S,isTransport:()=>F,peerDiscoverySymbol:()=>D,peerIdSymbol:()=>h,peerRoutingSymbol:()=>C,secp256k1:()=>O,setMaxListeners:()=>m,start:()=>H,stop:()=>K,transportSymbol:()=>A});var R=Symbol.for("@libp2p/connection");function v(e){return e!=null&&!!e[R]}var w=Symbol.for("@libp2p/content-routing");var P="Ed25519",M="RSA",O="secp256k1";var D=Symbol.for("@libp2p/peer-discovery");var h=Symbol.for("@libp2p/peer-id");function V(e){return e!=null&&!!e[h]}var C=Symbol.for("@libp2p/peer-routing");var U="keep-alive";var k="StrictSign",B="StrictNoSign",c;(function(e){e.Accept="accept",e.Ignore="ignore",e.Reject="reject"})(c||(c={}));var A=Symbol.for("@libp2p/transport");function F(e){return e!=null&&!!e[A]}var p;(function(e){e[e.FATAL_ALL=0]="FATAL_ALL",e[e.NO_FATAL=1]="NO_FATAL"})(p||(p={}));var i=class e extends Error{code;type;constructor(t="The operation was aborted"){super(t),this.code=e.code,this.type=e.type}static code="ABORT_ERR";static type="aborted"},a=class extends Error{code;props;constructor(t,o,s){super(t),this.code=o,this.name=s?.name??"CodeError",this.props=s??{}}},l=class extends AggregateError{code;props;constructor(t,o,s,r){super(t,o),this.code=s,this.name=r?.name??"AggregateCodeError",this.props=r??{}}},f=class e extends Error{code;constructor(t="Unexpected Peer"){super(t),this.code=e.code}static code="ERR_UNEXPECTED_PEER"},x=class e extends Error{code;constructor(t="Invalid crypto exchange"){super(t),this.code=e.code}static code="ERR_INVALID_CRYPTO_EXCHANGE"},u=class e extends Error{code;constructor(t="Invalid crypto transmission"){super(t),this.code=e.code}static code="ERR_INVALID_CRYPTO_TRANSMISSION"},G="ERR_TIMEOUT",j="ERR_INVALID_PARAMETERS",X="ERR_NOT_FOUND",Y="ERR_INVALID_MESSAGE";var m=(e,...t)=>{try{[...t]}catch{}};var d=class extends EventTarget{#t=new Map;constructor(){super(),m(1/0,this)}listenerCount(t){let o=this.#t.get(t);return o==null?0:o.length}addEventListener(t,o,s){super.addEventListener(t,o,s);let r=this.#t.get(t);r==null&&(r=[],this.#t.set(t,r)),r.push({callback:o,once:(s!==!0&&s!==!1&&s?.once)??!1})}removeEventListener(t,o,s){super.removeEventListener(t.toString(),o??null,s);let r=this.#t.get(t);r!=null&&(r=r.filter(({callback:y})=>y!==o),this.#t.set(t,r))}dispatchEvent(t){let o=super.dispatchEvent(t),s=this.#t.get(t.type);return s==null||(s=s.filter(({once:r})=>!r),this.#t.set(t.type,s)),o}safeDispatchEvent(t,o={}){return this.dispatchEvent(new b(t,o))}},E=class extends Event{detail;constructor(t,o){super(t,o),this.detail=o?.detail}},b=globalThis.CustomEvent??E;function S(e){return e!=null&&typeof e.start=="function"&&typeof e.stop=="function"}async function H(...e){let t=[];for(let o of e)S(o)&&t.push(o);await Promise.all(t.map(async o=>{o.beforeStart!=null&&await o.beforeStart()})),await Promise.all(t.map(async o=>{await o.start()})),await Promise.all(t.map(async o=>{o.afterStart!=null&&await o.afterStart()}))}async function K(...e){let t=[];for(let o of e)S(o)&&t.push(o);await Promise.all(t.map(async o=>{o.beforeStop!=null&&await o.beforeStop()})),await Promise.all(t.map(async o=>{await o.stop()})),await Promise.all(t.map(async o=>{o.afterStop!=null&&await o.afterStop()}))}return T(q);})();
 return Libp2PInterface}));

package/dist/src/event-target.d.ts

@@ -26,6 +26,7 @@ export interface TypedEventTarget<EventMap extends Record<string, any>> extends
  */
 export declare class TypedEventEmitter<EventMap extends Record<string, any>> extends EventTarget implements TypedEventTarget<EventMap> {
     #private;
+    constructor();
     listenerCount(type: string): number;
     addEventListener<K extends keyof EventMap>(type: K, listener: EventHandler<EventMap[K]> | null, options?: boolean | AddEventListenerOptions): void;
     removeEventListener<K extends keyof EventMap>(type: K, listener?: EventHandler<EventMap[K]> | null, options?: boolean | EventListenerOptions): void;

package/dist/src/event-target.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"event-target.d.ts","sourceRoot":"","sources":["../../src/event-target.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,aAAa,CAAC,SAAS;IAAI,CAAC,GAAG,EAAE,SAAS,GAAG,IAAI,CAAA;CAAE;AACpE,MAAM,WAAW,WAAW,CAAC,SAAS;IAAI,WAAW,EAAE,aAAa,CAAC,SAAS,CAAC,CAAA;CAAE;AACjF,MAAM,MAAM,YAAY,CAAC,SAAS,IAAI,aAAa,CAAC,SAAS,CAAC,GAAG,WAAW,CAAC,SAAS,CAAC,CAAA;AAOvF;;;;;;;GAOG;AACH,MAAM,WAAW,gBAAgB,CAAE,QAAQ,SAAS,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAE,SAAQ,WAAW;IAC1F,gBAAgB,CAAC,CAAC,SAAS,MAAM,QAAQ,EAAE,IAAI,EAAE,CAAC,EAAE,QAAQ,EAAE,YAAY,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,GAAG,IAAI,EAAE,OAAO,CAAC,EAAE,OAAO,GAAG,uBAAuB,GAAG,IAAI,CAAA;IAElJ,aAAa,CAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAAA;IAEpC,mBAAmB,CAAC,CAAC,SAAS,MAAM,QAAQ,EAAE,IAAI,EAAE,CAAC,EAAE,QAAQ,CAAC,EAAE,YAAY,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,GAAG,IAAI,EAAE,OAAO,CAAC,EAAE,OAAO,GAAG,oBAAoB,GAAG,IAAI,CAAA;IAEnJ,mBAAmB,CAAE,IAAI,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,YAAY,CAAC,KAAK,CAAC,EAAE,OAAO,CAAC,EAAE,OAAO,GAAG,oBAAoB,GAAG,IAAI,CAAA;IAElH,iBAAiB,CAAC,MAAM,EAAE,IAAI,EAAE,MAAM,QAAQ,EAAE,MAAM,EAAE,eAAe,CAAC,MAAM,CAAC,GAAG,OAAO,CAAA;CAC1F;AAED;;;GAGG;AACH,qBAAa,iBAAiB,CAAC,QAAQ,SAAS,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAE,SAAQ,WAAY,YAAW,gBAAgB,CAAC,QAAQ,CAAC;;IAG5H,aAAa,CAAE,IAAI,EAAE,MAAM,GAAG,MAAM;IAUpC,gBAAgB,CAAC,CAAC,SAAS,MAAM,QAAQ,EAAE,IAAI,EAAE,CAAC,EAAE,QAAQ,EAAE,YAAY,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,GAAG,IAAI,EAAE,OAAO,CAAC,EAAE,OAAO,GAAG,uBAAuB,GAAG,IAAI;IAiBlJ,mBAAmB,CAAC,CAAC,SAAS,MAAM,QAAQ,EAAE,IAAI,EAAE,CAAC,EAAE,QAAQ,CAAC,EAAE,YAAY,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,GAAG,IAAI,EAAE,OAAO,CAAC,EAAE,OAAO,GAAG,oBAAoB,GAAG,IAAI;IAcnJ,aAAa,CAAE,KAAK,EAAE,KAAK,GAAG,OAAO;IAerC,iBAAiB,CAAC,MAAM,EAAE,IAAI,EAAE,MAAM,QAAQ,EAAE,MAAM,GAAE,eAAe,CAAC,MAAM,CAAM,GAAG,OAAO;CAG/F;AAoBD,eAAO,MAAM,WAAW;;;CAAgD,CAAA"}
+{"version":3,"file":"event-target.d.ts","sourceRoot":"","sources":["../../src/event-target.ts"],"names":[],"mappings":"AAEA,MAAM,WAAW,aAAa,CAAC,SAAS;IAAI,CAAC,GAAG,EAAE,SAAS,GAAG,IAAI,CAAA;CAAE;AACpE,MAAM,WAAW,WAAW,CAAC,SAAS;IAAI,WAAW,EAAE,aAAa,CAAC,SAAS,CAAC,CAAA;CAAE;AACjF,MAAM,MAAM,YAAY,CAAC,SAAS,IAAI,aAAa,CAAC,SAAS,CAAC,GAAG,WAAW,CAAC,SAAS,CAAC,CAAA;AAOvF;;;;;;;GAOG;AACH,MAAM,WAAW,gBAAgB,CAAE,QAAQ,SAAS,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAE,SAAQ,WAAW;IAC1F,gBAAgB,CAAC,CAAC,SAAS,MAAM,QAAQ,EAAE,IAAI,EAAE,CAAC,EAAE,QAAQ,EAAE,YAAY,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,GAAG,IAAI,EAAE,OAAO,CAAC,EAAE,OAAO,GAAG,uBAAuB,GAAG,IAAI,CAAA;IAElJ,aAAa,CAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAAA;IAEpC,mBAAmB,CAAC,CAAC,SAAS,MAAM,QAAQ,EAAE,IAAI,EAAE,CAAC,EAAE,QAAQ,CAAC,EAAE,YAAY,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,GAAG,IAAI,EAAE,OAAO,CAAC,EAAE,OAAO,GAAG,oBAAoB,GAAG,IAAI,CAAA;IAEnJ,mBAAmB,CAAE,IAAI,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,YAAY,CAAC,KAAK,CAAC,EAAE,OAAO,CAAC,EAAE,OAAO,GAAG,oBAAoB,GAAG,IAAI,CAAA;IAElH,iBAAiB,CAAC,MAAM,EAAE,IAAI,EAAE,MAAM,QAAQ,EAAE,MAAM,EAAE,eAAe,CAAC,MAAM,CAAC,GAAG,OAAO,CAAA;CAC1F;AAED;;;GAGG;AACH,qBAAa,iBAAiB,CAAC,QAAQ,SAAS,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAE,SAAQ,WAAY,YAAW,gBAAgB,CAAC,QAAQ,CAAC;;;IAW5H,aAAa,CAAE,IAAI,EAAE,MAAM,GAAG,MAAM;IAUpC,gBAAgB,CAAC,CAAC,SAAS,MAAM,QAAQ,EAAE,IAAI,EAAE,CAAC,EAAE,QAAQ,EAAE,YAAY,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,GAAG,IAAI,EAAE,OAAO,CAAC,EAAE,OAAO,GAAG,uBAAuB,GAAG,IAAI;IAiBlJ,mBAAmB,CAAC,CAAC,SAAS,MAAM,QAAQ,EAAE,IAAI,EAAE,CAAC,EAAE,QAAQ,CAAC,EAAE,YAAY,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,GAAG,IAAI,EAAE,OAAO,CAAC,EAAE,OAAO,GAAG,oBAAoB,GAAG,IAAI;IAcnJ,aAAa,CAAE,KAAK,EAAE,KAAK,GAAG,OAAO;IAerC,iBAAiB,CAAC,MAAM,EAAE,IAAI,EAAE,MAAM,QAAQ,EAAE,MAAM,GAAE,eAAe,CAAC,MAAM,CAAM,GAAG,OAAO;CAG/F;AAoBD,eAAO,MAAM,WAAW;;;CAAgD,CAAA"}

package/dist/src/event-target.js

@@ -1,9 +1,16 @@
+import { setMaxListeners } from './events.js';
 /**
  * An implementation of a typed event target
  * etc
  */
 export class TypedEventEmitter extends EventTarget {
     #listeners = new Map();
+    constructor() {
+        super();
+        // silence MaxListenersExceededWarning warning on Node.js, this is a red
+        // herring almost all of the time
+        setMaxListeners(Infinity, this);
+    }
     listenerCount(type) {
         const listeners = this.#listeners.get(type);
         if (listeners == null) {

package/dist/src/event-target.js.map

@@ -1 +1 @@
-{"version":3,"file":"event-target.js","sourceRoot":"","sources":["../../src/event-target.ts"],"names":[],"mappings":"AA6BA;;;GAGG;AACH,MAAM,OAAO,iBAAwD,SAAQ,WAAW;IACtF,UAAU,GAAG,IAAI,GAAG,EAAmB,CAAA;IAEvC,aAAa,CAAE,IAAY;QACzB,MAAM,SAAS,GAAG,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,IAAI,CAAC,CAAA;QAE3C,IAAI,SAAS,IAAI,IAAI,EAAE,CAAC;YACtB,OAAO,CAAC,CAAA;QACV,CAAC;QAED,OAAO,SAAS,CAAC,MAAM,CAAA;IACzB,CAAC;IAGD,gBAAgB,CAAE,IAAY,EAAE,QAA6B,EAAE,OAA2C;QACxG,KAAK,CAAC,gBAAgB,CAAC,IAAI,EAAE,QAAQ,EAAE,OAAO,CAAC,CAAA;QAE/C,IAAI,IAAI,GAAG,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,IAAI,CAAC,CAAA;QAEpC,IAAI,IAAI,IAAI,IAAI,EAAE,CAAC;YACjB,IAAI,GAAG,EAAE,CAAA;YACT,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,IAAI,EAAE,IAAI,CAAC,CAAA;QACjC,CAAC;QAED,IAAI,CAAC,IAAI,CAAC;YACR,QAAQ,EAAE,QAAQ;YAClB,IAAI,EAAE,CAAC,OAAO,KAAK,IAAI,IAAI,OAAO,KAAK,KAAK,IAAI,OAAO,EAAE,IAAI,CAAC,IAAI,KAAK;SACxE,CAAC,CAAA;IACJ,CAAC;IAGD,mBAAmB,CAAE,IAAY,EAAE,QAA8B,EAAE,OAAwC;QACzG,KAAK,CAAC,mBAAmB,CAAC,IAAI,CAAC,QAAQ,EAAE,EAAE,QAAQ,IAAI,IAAI,EAAE,OAAO,CAAC,CAAA;QAErE,IAAI,IAAI,GAAG,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,IAAI,CAAC,CAAA;QAEpC,IAAI,IAAI,IAAI,IAAI,EAAE,CAAC;YACjB,OAAM;QACR,CAAC;QAED,IAAI,GAAG,IAAI,CAAC,MAAM,CAAC,CAAC,EAAE,QAAQ,EAAE,EAAE,EAAE,CAAC,QAAQ,KAAK,QAAQ,CAAC,CAAA;QAC3D,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,IAAI,EAAE,IAAI,CAAC,CAAA;IACjC,CAAC;IAED,aAAa,CAAE,KAAY;QACzB,MAAM,MAAM,GAAG,KAAK,CAAC,aAAa,CAAC,KAAK,CAAC,CAAA;QAEzC,IAAI,IAAI,GAAG,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,CAAA;QAE1C,IAAI,IAAI,IAAI,IAAI,EAAE,CAAC;YACjB,OAAO,MAAM,CAAA;QACf,CAAC;QAED,IAAI,GAAG,IAAI,CAAC,MAAM,CAAC,CAAC,EAAE,IAAI,EAAE,EAAE,EAAE,CAAC,CAAC,IAAI,CAAC,CAAA;QACvC,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,EAAE,IAAI,CAAC,CAAA;QAErC,OAAO,MAAM,CAAA;IACf,CAAC;IAED,iBAAiB,CAAS,IAAoB,EAAE,SAAkC,EAAE;QAClF,OAAO,IAAI,CAAC,aAAa,CAAC,IAAI,WAAW,CAAS,IAAc,EAAE,MAAM,CAAC,CAAC,CAAA;IAC5E,CAAC;CACF;AAED;;;;;;GAMG;AACH,MAAM,mBAA6B,SAAQ,KAAK;IAC9C,2FAA2F;IACpF,MAAM,CAAG;IAEhB,YAAa,OAAe,EAAE,IAAgC;QAC5D,KAAK,CAAC,OAAO,EAAE,IAAI,CAAC,CAAA;QACpB,sCAAsC;QACtC,IAAI,CAAC,MAAM,GAAG,IAAI,EAAE,MAAM,CAAA;IAC5B,CAAC;CACF;AAED,MAAM,CAAC,MAAM,WAAW,GAAG,UAAU,CAAC,WAAW,IAAI,mBAAmB,CAAA"}
+{"version":3,"file":"event-target.js","sourceRoot":"","sources":["../../src/event-target.ts"],"names":[],"mappings":"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"}

package/dist/src/metrics/index.d.ts

@@ -128,6 +128,144 @@ export interface CounterGroup {
  * The libp2p metrics tracking object. This interface is only concerned
  * with the collection of metrics, please see the individual implementations
  * for how to extract metrics for viewing.
+ *
+ * @example How to register a simple metric
+ *
+ * ```typescript
+ * import { Metrics, Metric } from '@libp2p/interface/metrics
+ *
+ * interface MyServiceComponents {
+ *   metrics: Metrics
+ * }
+ *
+ * class MyService {
+ *   private readonly myMetric: Metric
+ *
+ *   constructor (components: MyServiceComponents) {
+ *     this.myMetric = components.metrics.registerMetric({
+ *       name: 'my_metric',
+ *       label: 'my_label',
+ *       help: 'my help text'
+ *     })
+ *   }
+ *
+ *   // later
+ *   doSomething () {
+ *     this.myMetric.update(1)
+ *   }
+ * }
+ * ```
+ *
+ * @example How to register a dynamically calculated metric
+ *
+ * A metric that is expensive to calculate can be created by passing a `calculate` function that will only be invoked when metrics are being scraped:
+ *
+ * ```typescript
+ * import { Metrics, Metric } from '@libp2p/interface/metrics
+ *
+ * interface MyServiceComponents {
+ *   metrics: Metrics
+ * }
+ *
+ * class MyService {
+ *   private readonly myMetric: Metric
+ *
+ *   constructor (components: MyServiceComponents) {
+ *     this.myMetric = components.metrics.registerMetric({
+ *       name: 'my_metric',
+ *       label: 'my_label',
+ *       help: 'my help text',
+ *       calculate: async () => {
+ *         // do something expensive
+ *         return 1
+ *       }
+ *     })
+ *   }
+ * }
+ * ```
+ *
+ * @example How to register a group of metrics
+ *
+ * If several metrics should be grouped together (e.g. for graphing purposes) `registerMetricGroup` can be used instead:
+ *
+ * ```typescript
+ * import { Metrics, MetricGroup } from '@libp2p/interface/metrics
+ *
+ * interface MyServiceComponents {
+ *   metrics: Metrics
+ * }
+ *
+ * class MyService {
+ *   private readonly myMetricGroup: MetricGroup
+ *
+ *   constructor (components: MyServiceComponents) {
+ *     this.myMetricGroup = components.metrics.registerMetricGroup({
+ *       name: 'my_metric_group',
+ *       label: 'my_label',
+ *       help: 'my help text'
+ *     })
+ *   }
+ *
+ *   // later
+ *   doSomething () {
+ *     this.myMetricGroup.increment({ my_label: 'my_value' })
+ *   }
+ * }
+ * ```
+ *
+ * There are specific metric groups for tracking libp2p connections and streams:
+ *
+ * @example How to track multiaddr connections
+ *
+ * This is something only libp2p transports need to do.
+ *
+ * ```typescript
+ * import { Metrics } from '@libp2p/interface/metrics
+ *
+ * interface MyServiceComponents {
+ *   metrics: Metrics
+ * }
+ *
+ * class MyService {
+ *   private readonly metrics: Metrics
+ *
+ *   constructor (components: MyServiceComponents) {
+ *     this.metrics = components.metrics
+ *   }
+ *
+ *   // later
+ *   doSomething () {
+ *     const connection = {} // create a connection
+ *     this.metrics.trackMultiaddrConnection(connection)
+ *   }
+ * }
+ * ```
+ *
+ * @example How to track protocol streams
+ *
+ * This is something only libp2p connections need to do.
+ *
+ * ```typescript
+ * import { Metrics } from '@libp2p/interface/metrics
+ *
+ * interface MyServiceComponents {
+ *   metrics: Metrics
+ * }
+ *
+ * class MyService {
+ *   private readonly metrics: Metrics
+ *
+ *   constructor (components: MyServiceComponents) {
+ *     this.metrics = components.metrics
+ *   }
+ *
+ *   // later
+ *   doSomething () {
+ *     const stream = {} // create a stream
+ *     this.metrics.trackProtocolStream(stream)
+ *   }
+ * }
+ * ```
  */
 export interface Metrics {
     /**

package/dist/src/metrics/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/metrics/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/metrics/index.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@libp2p/interface",
-  "version": "1.1.2",
+  "version": "1.1.3-bedfd0aa2",
   "description": "The interface implemented by a libp2p node",
   "license": "Apache-2.0 OR MIT",
   "homepage": "https://github.com/libp2p/js-libp2p/tree/main/packages/interface#readme",
@@ -47,15 +47,15 @@
     "build": "aegir build"
   },
   "dependencies": {
-    "@multiformats/multiaddr": "^12.1.10",
+    "@multiformats/multiaddr": "^12.1.14",
     "it-pushable": "^3.2.3",
     "it-stream-types": "^2.0.1",
-    "multiformats": "^13.0.0",
+    "multiformats": "^13.0.1",
     "progress-events": "^1.0.0",
-    "uint8arraylist": "^2.4.7"
+    "uint8arraylist": "^2.4.8"
   },
   "devDependencies": {
-    "aegir": "^42.0.0"
+    "aegir": "^42.2.3"
   },
   "browser": {
     "events": "./dist/src/events.browser.js"

package/src/event-target.ts

@@ -1,3 +1,5 @@
+import { setMaxListeners } from './events.js'
+
 export interface EventCallback<EventType> { (evt: EventType): void }
 export interface EventObject<EventType> { handleEvent: EventCallback<EventType> }
 export type EventHandler<EventType> = EventCallback<EventType> | EventObject<EventType>
@@ -34,6 +36,14 @@ export interface TypedEventTarget <EventMap extends Record<string, any>> extends
 export class TypedEventEmitter<EventMap extends Record<string, any>> extends EventTarget implements TypedEventTarget<EventMap> {
   #listeners = new Map<any, Listener[]>()
 
+  constructor () {
+    super()
+
+    // silence MaxListenersExceededWarning warning on Node.js, this is a red
+    // herring almost all of the time
+    setMaxListeners(Infinity, this)
+  }
+
   listenerCount (type: string): number {
     const listeners = this.#listeners.get(type)
 

package/src/metrics/index.ts

@@ -146,6 +146,144 @@ export interface CounterGroup {
  * The libp2p metrics tracking object. This interface is only concerned
  * with the collection of metrics, please see the individual implementations
  * for how to extract metrics for viewing.
+ *
+ * @example How to register a simple metric
+ *
+ * ```typescript
+ * import { Metrics, Metric } from '@libp2p/interface/metrics
+ *
+ * interface MyServiceComponents {
+ *   metrics: Metrics
+ * }
+ *
+ * class MyService {
+ *   private readonly myMetric: Metric
+ *
+ *   constructor (components: MyServiceComponents) {
+ *     this.myMetric = components.metrics.registerMetric({
+ *       name: 'my_metric',
+ *       label: 'my_label',
+ *       help: 'my help text'
+ *     })
+ *   }
+ *
+ *   // later
+ *   doSomething () {
+ *     this.myMetric.update(1)
+ *   }
+ * }
+ * ```
+ *
+ * @example How to register a dynamically calculated metric
+ *
+ * A metric that is expensive to calculate can be created by passing a `calculate` function that will only be invoked when metrics are being scraped:
+ *
+ * ```typescript
+ * import { Metrics, Metric } from '@libp2p/interface/metrics
+ *
+ * interface MyServiceComponents {
+ *   metrics: Metrics
+ * }
+ *
+ * class MyService {
+ *   private readonly myMetric: Metric
+ *
+ *   constructor (components: MyServiceComponents) {
+ *     this.myMetric = components.metrics.registerMetric({
+ *       name: 'my_metric',
+ *       label: 'my_label',
+ *       help: 'my help text',
+ *       calculate: async () => {
+ *         // do something expensive
+ *         return 1
+ *       }
+ *     })
+ *   }
+ * }
+ * ```
+ *
+ * @example How to register a group of metrics
+ *
+ * If several metrics should be grouped together (e.g. for graphing purposes) `registerMetricGroup` can be used instead:
+ *
+ * ```typescript
+ * import { Metrics, MetricGroup } from '@libp2p/interface/metrics
+ *
+ * interface MyServiceComponents {
+ *   metrics: Metrics
+ * }
+ *
+ * class MyService {
+ *   private readonly myMetricGroup: MetricGroup
+ *
+ *   constructor (components: MyServiceComponents) {
+ *     this.myMetricGroup = components.metrics.registerMetricGroup({
+ *       name: 'my_metric_group',
+ *       label: 'my_label',
+ *       help: 'my help text'
+ *     })
+ *   }
+ *
+ *   // later
+ *   doSomething () {
+ *     this.myMetricGroup.increment({ my_label: 'my_value' })
+ *   }
+ * }
+ * ```
+ *
+ * There are specific metric groups for tracking libp2p connections and streams:
+ *
+ * @example How to track multiaddr connections
+ *
+ * This is something only libp2p transports need to do.
+ *
+ * ```typescript
+ * import { Metrics } from '@libp2p/interface/metrics
+ *
+ * interface MyServiceComponents {
+ *   metrics: Metrics
+ * }
+ *
+ * class MyService {
+ *   private readonly metrics: Metrics
+ *
+ *   constructor (components: MyServiceComponents) {
+ *     this.metrics = components.metrics
+ *   }
+ *
+ *   // later
+ *   doSomething () {
+ *     const connection = {} // create a connection
+ *     this.metrics.trackMultiaddrConnection(connection)
+ *   }
+ * }
+ * ```
+ *
+ * @example How to track protocol streams
+ *
+ * This is something only libp2p connections need to do.
+ *
+ * ```typescript
+ * import { Metrics } from '@libp2p/interface/metrics
+ *
+ * interface MyServiceComponents {
+ *   metrics: Metrics
+ * }
+ *
+ * class MyService {
+ *   private readonly metrics: Metrics
+ *
+ *   constructor (components: MyServiceComponents) {
+ *     this.metrics = components.metrics
+ *   }
+ *
+ *   // later
+ *   doSomething () {
+ *     const stream = {} // create a stream
+ *     this.metrics.trackProtocolStream(stream)
+ *   }
+ * }
+ * ```
  */
 export interface Metrics {
   /**

package/dist/typedoc-urls.json

@@ -1,158 +0,0 @@
-{
-  "FaultTolerance": "https://libp2p.github.io/js-libp2p/enums/_libp2p_interface.FaultTolerance.html",
-  "TopicValidatorResult": "https://libp2p.github.io/js-libp2p/enums/_libp2p_interface.TopicValidatorResult.html",
-  "AbortError": "https://libp2p.github.io/js-libp2p/classes/_libp2p_interface.AbortError.html",
-  "AggregateCodeError": "https://libp2p.github.io/js-libp2p/classes/_libp2p_interface.AggregateCodeError.html",
-  "CodeError": "https://libp2p.github.io/js-libp2p/classes/_libp2p_interface.CodeError.html",
-  "InvalidCryptoExchangeError": "https://libp2p.github.io/js-libp2p/classes/_libp2p_interface.InvalidCryptoExchangeError.html",
-  "InvalidCryptoTransmissionError": "https://libp2p.github.io/js-libp2p/classes/_libp2p_interface.InvalidCryptoTransmissionError.html",
-  "TypedEventEmitter": "https://libp2p.github.io/js-libp2p/classes/_libp2p_interface.TypedEventEmitter.html",
-  "UnexpectedPeerError": "https://libp2p.github.io/js-libp2p/classes/_libp2p_interface.UnexpectedPeerError.html",
-  "AbortOptions": "https://libp2p.github.io/js-libp2p/interfaces/_libp2p_interface.AbortOptions.html",
-  ".:AbortOptions": "https://libp2p.github.io/js-libp2p/interfaces/_libp2p_interface.AbortOptions.html",
-  "Address": "https://libp2p.github.io/js-libp2p/interfaces/_libp2p_interface.Address.html",
-  "AddressSorter": "https://libp2p.github.io/js-libp2p/interfaces/_libp2p_interface.AddressSorter.html",
-  ".:AddressSorter": "https://libp2p.github.io/js-libp2p/interfaces/_libp2p_interface.AddressSorter.html",
-  "CalculatedMetricOptions": "https://libp2p.github.io/js-libp2p/interfaces/_libp2p_interface.CalculatedMetricOptions.html",
-  "ComponentLogger": "https://libp2p.github.io/js-libp2p/interfaces/_libp2p_interface.ComponentLogger.html",
-  ".:ComponentLogger": "https://libp2p.github.io/js-libp2p/interfaces/_libp2p_interface.ComponentLogger.html",
-  "Connection": "https://libp2p.github.io/js-libp2p/interfaces/_libp2p_interface.Connection.html",
-  "ConnectionEncrypter": "https://libp2p.github.io/js-libp2p/interfaces/_libp2p_interface.ConnectionEncrypter.html",
-  "ConnectionGater": "https://libp2p.github.io/js-libp2p/interfaces/_libp2p_interface.ConnectionGater.html",
-  "ConnectionHandler": "https://libp2p.github.io/js-libp2p/interfaces/_libp2p_interface.ConnectionHandler.html",
-  "ConnectionProtector": "https://libp2p.github.io/js-libp2p/interfaces/_libp2p_interface.ConnectionProtector.html",
-  "ConnectionTimeline": "https://libp2p.github.io/js-libp2p/interfaces/_libp2p_interface.ConnectionTimeline.html",
-  "ContentRouting": "https://libp2p.github.io/js-libp2p/interfaces/_libp2p_interface.ContentRouting.html",
-  "ContentRoutingProvider": "https://libp2p.github.io/js-libp2p/interfaces/_libp2p_interface.ContentRoutingProvider.html",
-  "Counter": "https://libp2p.github.io/js-libp2p/interfaces/_libp2p_interface.Counter.html",
-  "CounterGroup": "https://libp2p.github.io/js-libp2p/interfaces/_libp2p_interface.CounterGroup.html",
-  "CreateListenerOptions": "https://libp2p.github.io/js-libp2p/interfaces/_libp2p_interface.CreateListenerOptions.html",
-  "DialOptions": "https://libp2p.github.io/js-libp2p/interfaces/_libp2p_interface.DialOptions.html",
-  "Ed25519PeerId": "https://libp2p.github.io/js-libp2p/interfaces/_libp2p_interface.Ed25519PeerId.html",
-  "Envelope": "https://libp2p.github.io/js-libp2p/interfaces/_libp2p_interface.Envelope.html",
-  "EventCallback": "https://libp2p.github.io/js-libp2p/interfaces/_libp2p_interface.EventCallback.html",
-  "EventObject": "https://libp2p.github.io/js-libp2p/interfaces/_libp2p_interface.EventObject.html",
-  "IdentifyResult": "https://libp2p.github.io/js-libp2p/interfaces/_libp2p_interface.IdentifyResult.html",
-  ".:IdentifyResult": "https://libp2p.github.io/js-libp2p/interfaces/_libp2p_interface.IdentifyResult.html",
-  "IncomingStreamData": "https://libp2p.github.io/js-libp2p/interfaces/_libp2p_interface.IncomingStreamData.html",
-  "Libp2p": "https://libp2p.github.io/js-libp2p/interfaces/_libp2p_interface.Libp2p.html",
-  ".:Libp2p": "https://libp2p.github.io/js-libp2p/interfaces/libp2p.index.Libp2p.html",
-  "Libp2pEvents": "https://libp2p.github.io/js-libp2p/interfaces/_libp2p_interface.Libp2pEvents.html",
-  ".:Libp2pEvents": "https://libp2p.github.io/js-libp2p/interfaces/_libp2p_interface.Libp2pEvents.html",
-  "Listener": "https://libp2p.github.io/js-libp2p/interfaces/_libp2p_interface.Listener.html",
-  "ListenerEvents": "https://libp2p.github.io/js-libp2p/interfaces/_libp2p_interface.ListenerEvents.html",
-  "Logger": "https://libp2p.github.io/js-libp2p/interfaces/_libp2p_interface.Logger.html",
-  ".:Logger": "https://libp2p.github.io/js-libp2p/interfaces/_libp2p_interface.Logger.html",
-  "LoggerOptions": "https://libp2p.github.io/js-libp2p/interfaces/_libp2p_interface.LoggerOptions.html",
-  ".:LoggerOptions": "https://libp2p.github.io/js-libp2p/interfaces/_libp2p_interface.LoggerOptions.html",
-  "Metric": "https://libp2p.github.io/js-libp2p/interfaces/_libp2p_interface.Metric.html",
-  "MetricGroup": "https://libp2p.github.io/js-libp2p/interfaces/_libp2p_interface.MetricGroup.html",
-  "MetricOptions": "https://libp2p.github.io/js-libp2p/interfaces/_libp2p_interface.MetricOptions.html",
-  "Metrics": "https://libp2p.github.io/js-libp2p/interfaces/_libp2p_interface.Metrics.html",
-  "MultiaddrConnection": "https://libp2p.github.io/js-libp2p/interfaces/_libp2p_interface.MultiaddrConnection.html",
-  "MultiaddrConnectionTimeline": "https://libp2p.github.io/js-libp2p/interfaces/_libp2p_interface.MultiaddrConnectionTimeline.html",
-  "MultiaddrFilter": "https://libp2p.github.io/js-libp2p/interfaces/_libp2p_interface.MultiaddrFilter.html",
-  "NewStreamOptions": "https://libp2p.github.io/js-libp2p/interfaces/_libp2p_interface.NewStreamOptions.html",
-  "NodeInfo": "https://libp2p.github.io/js-libp2p/interfaces/_libp2p_interface.NodeInfo.html",
-  ".:NodeInfo": "https://libp2p.github.io/js-libp2p/interfaces/_libp2p_interface.NodeInfo.html",
-  "Peer": "https://libp2p.github.io/js-libp2p/interfaces/_libp2p_interface.Peer.html",
-  "PeerData": "https://libp2p.github.io/js-libp2p/interfaces/_libp2p_interface.PeerData.html",
-  "PeerDiscovery": "https://libp2p.github.io/js-libp2p/interfaces/_libp2p_interface.PeerDiscovery.html",
-  "PeerDiscoveryEvents": "https://libp2p.github.io/js-libp2p/interfaces/_libp2p_interface.PeerDiscoveryEvents.html",
-  "PeerDiscoveryProvider": "https://libp2p.github.io/js-libp2p/interfaces/_libp2p_interface.PeerDiscoveryProvider.html",
-  "PeerInfo": "https://libp2p.github.io/js-libp2p/interfaces/_libp2p_interface.PeerInfo.html",
-  "PeerQuery": "https://libp2p.github.io/js-libp2p/interfaces/_libp2p_interface.PeerQuery.html",
-  "PeerQueryFilter": "https://libp2p.github.io/js-libp2p/interfaces/_libp2p_interface.PeerQueryFilter.html",
-  "PeerQueryOrder": "https://libp2p.github.io/js-libp2p/interfaces/_libp2p_interface.PeerQueryOrder.html",
-  "PeerRouting": "https://libp2p.github.io/js-libp2p/interfaces/_libp2p_interface.PeerRouting.html",
-  "PeerRoutingProvider": "https://libp2p.github.io/js-libp2p/interfaces/_libp2p_interface.PeerRoutingProvider.html",
-  "PeerStore": "https://libp2p.github.io/js-libp2p/interfaces/_libp2p_interface.PeerStore.html",
-  "PeerStreamEvents": "https://libp2p.github.io/js-libp2p/interfaces/_libp2p_interface.PeerStreamEvents.html",
-  "PeerStreams": "https://libp2p.github.io/js-libp2p/interfaces/_libp2p_interface.PeerStreams.html",
-  "PeerUpdate": "https://libp2p.github.io/js-libp2p/interfaces/_libp2p_interface.PeerUpdate.html",
-  ".:PeerUpdate": "https://libp2p.github.io/js-libp2p/interfaces/_libp2p_interface.PeerUpdate.html",
-  "PendingDial": "https://libp2p.github.io/js-libp2p/interfaces/_libp2p_interface.PendingDial.html",
-  ".:PendingDial": "https://libp2p.github.io/js-libp2p/interfaces/_libp2p_interface.PendingDial.html",
-  "PrivateKey": "https://libp2p.github.io/js-libp2p/interfaces/_libp2p_interface.PrivateKey.html",
-  "PubSub": "https://libp2p.github.io/js-libp2p/interfaces/_libp2p_interface.PubSub.html",
-  "PubSubEvents": "https://libp2p.github.io/js-libp2p/interfaces/_libp2p_interface.PubSubEvents.html",
-  "PubSubInit": "https://libp2p.github.io/js-libp2p/interfaces/_libp2p_interface.PubSubInit.html",
-  "PubSubRPC": "https://libp2p.github.io/js-libp2p/interfaces/_libp2p_interface.PubSubRPC.html",
-  "PubSubRPCMessage": "https://libp2p.github.io/js-libp2p/interfaces/_libp2p_interface.PubSubRPCMessage.html",
-  "PubSubRPCSubscription": "https://libp2p.github.io/js-libp2p/interfaces/_libp2p_interface.PubSubRPCSubscription.html",
-  "PublicKey": "https://libp2p.github.io/js-libp2p/interfaces/_libp2p_interface.PublicKey.html",
-  "PublishResult": "https://libp2p.github.io/js-libp2p/interfaces/_libp2p_interface.PublishResult.html",
-  "RSAPeerId": "https://libp2p.github.io/js-libp2p/interfaces/_libp2p_interface.RSAPeerId.html",
-  "Record": "https://libp2p.github.io/js-libp2p/interfaces/_libp2p_interface.Record.html",
-  "RoutingOptions": "https://libp2p.github.io/js-libp2p/interfaces/_libp2p_interface.RoutingOptions.html",
-  ".:RoutingOptions": "https://libp2p.github.io/js-libp2p/interfaces/_libp2p_interface.RoutingOptions.html",
-  "Secp256k1PeerId": "https://libp2p.github.io/js-libp2p/interfaces/_libp2p_interface.Secp256k1PeerId.html",
-  "SecuredConnection": "https://libp2p.github.io/js-libp2p/interfaces/_libp2p_interface.SecuredConnection.html",
-  "SignedMessage": "https://libp2p.github.io/js-libp2p/interfaces/_libp2p_interface.SignedMessage.html",
-  "SignedPeerRecord": "https://libp2p.github.io/js-libp2p/interfaces/_libp2p_interface.SignedPeerRecord.html",
-  ".:SignedPeerRecord": "https://libp2p.github.io/js-libp2p/interfaces/_libp2p_interface.SignedPeerRecord.html",
-  "Startable": "https://libp2p.github.io/js-libp2p/interfaces/_libp2p_interface.Startable.html",
-  "StopTimer": "https://libp2p.github.io/js-libp2p/interfaces/_libp2p_interface.StopTimer.html",
-  "Stream": "https://libp2p.github.io/js-libp2p/interfaces/_libp2p_interface.Stream.html",
-  "StreamHandler": "https://libp2p.github.io/js-libp2p/interfaces/_libp2p_interface.StreamHandler.html",
-  "StreamHandlerOptions": "https://libp2p.github.io/js-libp2p/interfaces/_libp2p_interface.StreamHandlerOptions.html",
-  "StreamHandlerRecord": "https://libp2p.github.io/js-libp2p/interfaces/_libp2p_interface.StreamHandlerRecord.html",
-  "StreamMuxer": "https://libp2p.github.io/js-libp2p/interfaces/_libp2p_interface.StreamMuxer.html",
-  "StreamMuxerFactory": "https://libp2p.github.io/js-libp2p/interfaces/_libp2p_interface.StreamMuxerFactory.html",
-  "StreamMuxerInit": "https://libp2p.github.io/js-libp2p/interfaces/_libp2p_interface.StreamMuxerInit.html",
-  "StreamTimeline": "https://libp2p.github.io/js-libp2p/interfaces/_libp2p_interface.StreamTimeline.html",
-  "SubscriptionChangeData": "https://libp2p.github.io/js-libp2p/interfaces/_libp2p_interface.SubscriptionChangeData.html",
-  "Tag": "https://libp2p.github.io/js-libp2p/interfaces/_libp2p_interface.Tag.html",
-  "TagOptions": "https://libp2p.github.io/js-libp2p/interfaces/_libp2p_interface.TagOptions.html",
-  "TopicValidatorFn": "https://libp2p.github.io/js-libp2p/interfaces/_libp2p_interface.TopicValidatorFn.html",
-  "Topology": "https://libp2p.github.io/js-libp2p/interfaces/_libp2p_interface.Topology.html",
-  "Transport": "https://libp2p.github.io/js-libp2p/interfaces/_libp2p_interface.Transport.html",
-  "TypedEventTarget": "https://libp2p.github.io/js-libp2p/interfaces/_libp2p_interface.TypedEventTarget.html",
-  "UnsignedMessage": "https://libp2p.github.io/js-libp2p/interfaces/_libp2p_interface.UnsignedMessage.html",
-  "Upgrader": "https://libp2p.github.io/js-libp2p/interfaces/_libp2p_interface.Upgrader.html",
-  "UpgraderOptions": "https://libp2p.github.io/js-libp2p/interfaces/_libp2p_interface.UpgraderOptions.html",
-  "CalculateMetric": "https://libp2p.github.io/js-libp2p/types/_libp2p_interface.CalculateMetric.html",
-  "ConnectionStatus": "https://libp2p.github.io/js-libp2p/types/_libp2p_interface.ConnectionStatus.html",
-  "Direction": "https://libp2p.github.io/js-libp2p/types/_libp2p_interface.Direction.html",
-  "EventHandler": "https://libp2p.github.io/js-libp2p/types/_libp2p_interface.EventHandler.html",
-  "KeyType": "https://libp2p.github.io/js-libp2p/types/_libp2p_interface.KeyType.html",
-  "Libp2pStatus": "https://libp2p.github.io/js-libp2p/types/_libp2p_interface.Libp2pStatus.html",
-  ".:Libp2pStatus": "https://libp2p.github.io/js-libp2p/types/_libp2p_interface.Libp2pStatus.html",
-  "Message": "https://libp2p.github.io/js-libp2p/types/_libp2p_interface.Message.html",
-  "PeerId": "https://libp2p.github.io/js-libp2p/types/_libp2p_interface.PeerId.html",
-  "PeerIdType": "https://libp2p.github.io/js-libp2p/types/_libp2p_interface.PeerIdType.html",
-  "PendingDialStatus": "https://libp2p.github.io/js-libp2p/types/_libp2p_interface.PendingDialStatus.html",
-  ".:PendingDialStatus": "https://libp2p.github.io/js-libp2p/types/_libp2p_interface.PendingDialStatus.html",
-  "ReadStatus": "https://libp2p.github.io/js-libp2p/types/_libp2p_interface.ReadStatus.html",
-  "RecursivePartial": "https://libp2p.github.io/js-libp2p/types/_libp2p_interface.RecursivePartial.html",
-  ".:RecursivePartial": "https://libp2p.github.io/js-libp2p/types/_libp2p_interface.RecursivePartial.html",
-  "ServiceMap": "https://libp2p.github.io/js-libp2p/types/_libp2p_interface.ServiceMap.html",
-  ".:ServiceMap": "https://libp2p.github.io/js-libp2p/types/_libp2p_interface.ServiceMap.html",
-  "SignaturePolicy": "https://libp2p.github.io/js-libp2p/types/_libp2p_interface.SignaturePolicy.html",
-  "StreamStatus": "https://libp2p.github.io/js-libp2p/types/_libp2p_interface.StreamStatus.html",
-  "WriteStatus": "https://libp2p.github.io/js-libp2p/types/_libp2p_interface.WriteStatus.html",
-  "CustomEvent": "https://libp2p.github.io/js-libp2p/variables/_libp2p_interface.CustomEvent.html",
-  "ERR_INVALID_MESSAGE": "https://libp2p.github.io/js-libp2p/variables/_libp2p_interface.ERR_INVALID_MESSAGE.html",
-  "ERR_INVALID_PARAMETERS": "https://libp2p.github.io/js-libp2p/variables/_libp2p_interface.ERR_INVALID_PARAMETERS.html",
-  "ERR_NOT_FOUND": "https://libp2p.github.io/js-libp2p/variables/_libp2p_interface.ERR_NOT_FOUND.html",
-  "ERR_TIMEOUT": "https://libp2p.github.io/js-libp2p/variables/_libp2p_interface.ERR_TIMEOUT.html",
-  "Ed25519": "https://libp2p.github.io/js-libp2p/variables/_libp2p_interface.Ed25519.html",
-  "KEEP_ALIVE": "https://libp2p.github.io/js-libp2p/variables/_libp2p_interface.KEEP_ALIVE.html",
-  "RSA": "https://libp2p.github.io/js-libp2p/variables/_libp2p_interface.RSA.html",
-  "StrictNoSign": "https://libp2p.github.io/js-libp2p/variables/_libp2p_interface.StrictNoSign.html",
-  "StrictSign": "https://libp2p.github.io/js-libp2p/variables/_libp2p_interface.StrictSign.html",
-  "connectionSymbol": "https://libp2p.github.io/js-libp2p/variables/_libp2p_interface.connectionSymbol.html",
-  "contentRoutingSymbol": "https://libp2p.github.io/js-libp2p/variables/_libp2p_interface.contentRoutingSymbol.html",
-  "peerDiscoverySymbol": "https://libp2p.github.io/js-libp2p/variables/_libp2p_interface.peerDiscoverySymbol.html",
-  "peerIdSymbol": "https://libp2p.github.io/js-libp2p/variables/_libp2p_interface.peerIdSymbol.html",
-  "peerRoutingSymbol": "https://libp2p.github.io/js-libp2p/variables/_libp2p_interface.peerRoutingSymbol.html",
-  "secp256k1": "https://libp2p.github.io/js-libp2p/variables/_libp2p_interface.secp256k1.html",
-  "transportSymbol": "https://libp2p.github.io/js-libp2p/variables/_libp2p_interface.transportSymbol.html",
-  "isConnection": "https://libp2p.github.io/js-libp2p/functions/_libp2p_interface.isConnection.html",
-  "isPeerId": "https://libp2p.github.io/js-libp2p/functions/_libp2p_interface.isPeerId.html",
-  "isStartable": "https://libp2p.github.io/js-libp2p/functions/_libp2p_interface.isStartable.html",
-  "isTransport": "https://libp2p.github.io/js-libp2p/functions/_libp2p_interface.isTransport.html",
-  "setMaxListeners": "https://libp2p.github.io/js-libp2p/functions/_libp2p_interface.setMaxListeners.html",
-  "start": "https://libp2p.github.io/js-libp2p/functions/_libp2p_interface.start.html",
-  "stop": "https://libp2p.github.io/js-libp2p/functions/_libp2p_interface.stop.html"
-}