chore: re-enable doc-check for Typescript snippets

doc/CONFIGURATION.md

@@ -930,11 +930,11 @@ For more information see https://docs.libp2p.io/concepts/nat/autonat/#what-is-au
 
 ```ts
 import { createLibp2p } from 'libp2p'
-import { autoNATService } from '@libp2p/autonat'
+import { autoNAT } from '@libp2p/autonat'
 
 const node = await createLibp2p({
   services: {
-    nat: autoNATService({
+    nat: autoNAT({
       protocolPrefix: 'my-node', // this should be left as the default value to ensure maximum compatibility
       timeout: 30000, // the remote must complete the AutoNAT protocol within this timeout
       maxInboundStreams: 1, // how many concurrent inbound AutoNAT protocols streams to allow on each connection

doc/GETTING_STARTED.md

@@ -121,25 +121,24 @@ If you want to know more about libp2p connection encryption, you should read the
 
 While multiplexers are not strictly required, they are highly recommended as they improve the effectiveness and efficiency of connections for the various protocols libp2p runs. Adding a multiplexer to your configuration will allow libp2p to run several of its internal protocols, like Identify, as well as allow your application to easily run any number of protocols over a single connection.
 
-Looking at the [available stream multiplexing](./CONFIGURATION.md#stream-multiplexing) modules, js-libp2p currently only supports `@libp2p/mplex`, so we will use that here. Bear in mind that future libp2p Transports might have `multiplexing` capabilities already built-in (such as `QUIC`).
+Looking at the [available stream multiplexing](./CONFIGURATION.md#stream-multiplexing) modules. Bear in mind that future libp2p Transports might have `multiplexing` capabilities already built-in (such as `QUIC`).
 
-You can install `@libp2p/mplex` and add it to your libp2p node as follows in the next example.
+You can install `@chainsafe/libp2p-yamux` and add it to your libp2p node as follows in the next example.
 
 ```sh
-npm install @libp2p/mplex
+npm install @chainsafe/libp2p-yamux
 ```
 
-```js
+```ts
 import { createLibp2p } from 'libp2p'
 import { webSockets } from '@libp2p/websockets'
 import { noise } from '@chainsafe/libp2p-noise'
-import { mplex } from '@libp2p/mplex'
 import { yamux } from '@chainsafe/libp2p-yamux'
 
 const node = await createLibp2p({
   transports: [webSockets()],
   connectionEncryption: [noise()],
-  streamMuxers: [yamux(), mplex()]
+  streamMuxers: [yamux()]
 })
 ```
 
@@ -155,11 +154,11 @@ If you want to know more about libp2p stream multiplexing, you should read the f
 
 Now that you have configured a [**Transport**][transport], [**Crypto**][crypto] and [**Stream Multiplexer**](streamMuxer) module, you can start your libp2p node. We can start and stop libp2p using the [`libp2p.start()`](./API.md#start) and [`libp2p.stop()`](./API.md#stop) methods.
 
-```js
+```ts
 import { createLibp2p } from 'libp2p'
 import { webSockets } from '@libp2p/websockets'
 import { noise } from '@chainsafe/libp2p-noise'
-import { mplex } from '@libp2p/mplex'
+import { yamux } from '@chainsafe/libp2p-yamux'
 
 const node = await createLibp2p({
   // libp2p nodes are started by default, pass false to override this
@@ -169,7 +168,7 @@ const node = await createLibp2p({
   },
   transports: [webSockets()],
   connectionEncryption: [noise()],
-  streamMuxers: [yamux(), mplex()]
+  streamMuxers: [yamux()]
 })
 
 // start libp2p
@@ -209,13 +208,11 @@ npm install @libp2p/bootstrap
 
 We can provide specific configurations for each protocol within a `config.peerDiscovery` property in the options as shown below.
 
-```js
+```ts
 import { createLibp2p } from 'libp2p'
 import { webSockets } from '@libp2p/websockets'
 import { noise } from '@chainsafe/libp2p-noise'
-import { mplex } from '@libp2p/mplex'
 import { yamux } from '@chainsafe/libp2p-yamux'
-
 import { bootstrap } from '@libp2p/bootstrap'
 
 // Known peers addresses
@@ -227,7 +224,7 @@ const bootstrapMultiaddrs = [
 const node = await createLibp2p({
   transports: [webSockets()],
   connectionEncryption: [noise()],
-  streamMuxers: [yamux(), mplex()],
+  streamMuxers: [yamux()],
   peerDiscovery: [
     bootstrap({
       list: bootstrapMultiaddrs, // provide array of multiaddrs
@@ -240,7 +237,7 @@ node.addEventListener('peer:discovery', (evt) => {
 })
 
 node.addEventListener('peer:connect', (evt) => {
-  console.log('Connected to %s', evt.detail.remotePeer.toString()) // Log connected peer
+  console.log('Connected to %s', evt.detail.toString()) // Log connected peer
 })
 ```
 

doc/METRICS.md

@@ -84,17 +84,20 @@ class MyClass {
 A tracked metric can be created by calling either `registerMetric` on the metrics object:
 
 ```ts
-import type { Metrics } from '@libp2p/interface/metrics'
 import { prometheusMetrics } from '@libp2p/prometheus-metrics'
+import { createLibp2p } from 'libp2p'
 
-const metrics: Metrics = prometheusMetrics()()
+const node = await createLibp2p({
+  metrics: prometheusMetrics()
+  //... other config
+})
 
-const metric = metrics.registerMetric('my_metric', {
+const metric = node.metrics?.registerMetric('my_metric', {
   // an optional label
   label: 'label',
   // optional help text
   help: 'help'
-})
+})!
 
 // set a value
 metric.update(5)
@@ -119,10 +122,14 @@ A metric that is expensive to calculate can be created by passing a `calculate`
 ```ts
 import type { Metrics } from '@libp2p/interface/metrics'
 import { prometheusMetrics } from '@libp2p/prometheus-metrics'
+import { createLibp2p } from 'libp2p'
 
-const metrics: Metrics = prometheusMetrics()()
+const node = await createLibp2p({
+  metrics: prometheusMetrics()
+  //... other config
+})
 
-metrics.registerMetric('my_metric', {
+node.metrics?.registerMetric('my_metric', {
   async calculate () {
     return 5
   }
@@ -132,17 +139,20 @@ metrics.registerMetric('my_metric', {
 If several metrics should be grouped together (e.g. for graphing purposes) `registerMetricGroup` can be used instead:
 
 ```ts
-import type { Metrics } from '@libp2p/interface/metrics'
 import { prometheusMetrics } from '@libp2p/prometheus-metrics'
+import { createLibp2p } from 'libp2p'
 
-const metrics: Metrics = prometheusMetrics()()
+const node = await createLibp2p({
+  metrics: prometheusMetrics()
+  //... other config
+})
 
-const metric = metrics.registerMetricGroup('my_metric', {
+const metric = node.metrics?.registerMetricGroup('my_metric', {
   // an optional label
   label: 'label',
   // optional help text
   help: 'help'
-})
+})!
 
 metric.update({
   key1: 1,
@@ -176,7 +186,6 @@ Metrics implementations will allow extracting the values for presentation in an
 ```ts
 import { prometheusMetrics } from '@libp2p/prometheus-metrics'
 import { createLibp2p } from 'libp2p'
-
 import client from 'prom-client'
 import { createServer } from 'http'
 

doc/package.json

@@ -19,6 +19,7 @@
       "sourceType": "module"
     }
   },
+  "exports": {},
   "scripts": {
     "doc-check": "aegir doc-check"
   },

packages/interface/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 {
   /**