@libp2p/interface 2.9.0 → 2.10.0-aa25d38ab

package/dist/src/transport.d.ts.map

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

package/dist/src/transport.js

@@ -1,4 +1,7 @@
 export const transportSymbol = Symbol.for('@libp2p/transport');
+/**
+ * Used to disambiguate transport implementations
+ */
 export function isTransport(other) {
     return other != null && Boolean(other[transportSymbol]);
 }

package/dist/src/transport.js.map

@@ -1 +1 @@
-{"version":3,"file":"transport.js","sourceRoot":"","sources":["../../src/transport.ts"],"names":[],"mappings":"AAgDA,MAAM,CAAC,MAAM,eAAe,GAAG,MAAM,CAAC,GAAG,CAAC,mBAAmB,CAAC,CAAA;AAyD9D,MAAM,UAAU,WAAW,CAAE,KAAU;IACrC,OAAO,KAAK,IAAI,IAAI,IAAI,OAAO,CAAC,KAAK,CAAC,eAAe,CAAC,CAAC,CAAA;AACzD,CAAC;AAED;;GAEG;AACH,MAAM,CAAN,IAAY,cAUX;AAVD,WAAY,cAAc;IACxB;;OAEG;IACH,6DAAa,CAAA;IAEb;;OAEG;IACH,2DAAQ,CAAA;AACV,CAAC,EAVW,cAAc,KAAd,cAAc,QAUzB"}
+{"version":3,"file":"transport.js","sourceRoot":"","sources":["../../src/transport.ts"],"names":[],"mappings":"AAgDA,MAAM,CAAC,MAAM,eAAe,GAAG,MAAM,CAAC,GAAG,CAAC,mBAAmB,CAAC,CAAA;AA8D9D;;GAEG;AACH,MAAM,UAAU,WAAW,CAAE,KAAW;IACtC,OAAO,KAAK,IAAI,IAAI,IAAI,OAAO,CAAC,KAAK,CAAC,eAAe,CAAC,CAAC,CAAA;AACzD,CAAC;AAED;;GAEG;AACH,MAAM,CAAN,IAAY,cAUX;AAVD,WAAY,cAAc;IACxB;;OAEG;IACH,6DAAa,CAAA;IAEb;;OAEG;IACH,2DAAQ,CAAA;AACV,CAAC,EAVW,cAAc,KAAd,cAAc,QAUzB"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@libp2p/interface",
-  "version": "2.9.0",
+  "version": "2.10.0-aa25d38ab",
   "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",
@@ -33,13 +33,6 @@
       "import": "./dist/src/index.js"
     }
   },
-  "eslintConfig": {
-    "extends": "ipfs",
-    "parserOptions": {
-      "project": true,
-      "sourceType": "module"
-    }
-  },
   "scripts": {
     "clean": "aegir clean",
     "lint": "aegir lint",
@@ -48,15 +41,15 @@
     "build": "aegir build"
   },
   "dependencies": {
-    "@multiformats/multiaddr": "^12.3.3",
+    "@multiformats/multiaddr": "^12.4.0",
     "it-pushable": "^3.2.3",
     "it-stream-types": "^2.0.2",
-    "multiformats": "^13.3.1",
+    "multiformats": "^13.3.4",
     "progress-events": "^1.0.1",
     "uint8arraylist": "^2.4.8"
   },
   "devDependencies": {
-    "aegir": "^45.1.1"
+    "aegir": "^47.0.6"
   },
   "browser": {
     "./dist/src/events.js": "./dist/src/events.browser.js"

package/src/content-routing.ts

@@ -4,7 +4,7 @@ import type { CID } from 'multiformats/cid'
 
 /**
  * Any object that implements this Symbol as a property should return a
- * ContentRouting instance as the property value, similar to how
+ * Partial<ContentRouting> instance as the property value, similar to how
  * `Symbol.Iterable` can be used to return an `Iterable` from an `Iterator`.
  *
  * @example
@@ -28,7 +28,7 @@ export const contentRoutingSymbol = Symbol.for('@libp2p/content-routing')
  * interested callers.
  */
 export interface ContentRoutingProvider {
-  [contentRoutingSymbol]: ContentRouting
+  [contentRoutingSymbol]: Partial<ContentRouting>
 }
 
 export interface ContentRouting {

package/src/errors.ts

@@ -353,7 +353,7 @@ export class TooManyOutboundProtocolStreamsError extends Error {
 }
 
 /**
- * Thrown when and attempt to operate on an unsupported key was made
+ * Thrown when an attempt to operate on an unsupported key was made
  */
 export class UnsupportedKeyTypeError extends Error {
   static name = 'UnsupportedKeyTypeError'
@@ -363,3 +363,15 @@ export class UnsupportedKeyTypeError extends Error {
     this.name = 'UnsupportedKeyTypeError'
   }
 }
+
+/**
+ * Thrown when an operation has not been implemented
+ */
+export class NotImplementedError extends Error {
+  static name = 'NotImplementedError'
+
+  constructor (message = 'Not implemented') {
+    super(message)
+    this.name = 'NotImplementedError'
+  }
+}

package/src/event-target.ts

@@ -10,7 +10,8 @@ interface Listener {
 }
 
 /**
- * Adds types to the EventTarget class. Hopefully this won't be necessary forever.
+ * Adds types to the EventTarget class. Hopefully this won't be necessary
+ * forever.
  *
  * https://github.com/microsoft/TypeScript/issues/28357
  * https://github.com/microsoft/TypeScript/issues/43477
@@ -31,7 +32,6 @@ export interface TypedEventTarget <EventMap extends Record<string, any>> extends
 
 /**
  * An implementation of a typed event target
- * etc
  */
 export class TypedEventEmitter<EventMap extends Record<string, any>> extends EventTarget implements TypedEventTarget<EventMap> {
   readonly #listeners = new Map<any, Listener[]>()

package/src/index.ts

@@ -53,6 +53,9 @@ export interface SignedPeerRecord {
   seq: bigint
 }
 
+/**
+ * A certificate that can be used to secure connections
+ */
 export interface TLSCertificate {
   /**
    * The private key that corresponds to the certificate in PEM format
@@ -130,9 +133,43 @@ export interface Logger {
 }
 
 /**
- * Peer logger component for libp2p
+ * Peer logger component for libp2p. This can be used to create loggers that are
+ * scoped to individual system components or services.
+ *
+ * To see logs, run your app with `DEBUG` set as an env var or for browsers, in
+ * `localStorage`:
+ *
+ * ```console
+ * $ DEBUG=libp2p* node index.js
+ *  libp2p:my-service hello +0ms
+ * ```
  */
 export interface ComponentLogger {
+  /**
+   * Returns a logger for the specified component.
+   *
+   * @example
+   *
+   * ```TypeScript
+   * import { ComponentLogger, Logger } from '@libp2p/interface'
+   *
+   * interface MyServiceComponents {
+   *   logger: ComponentLogger
+   * }
+   *
+   * class MyService {
+   *   private readonly log: Logger
+   *
+   *   constructor (components) {
+   *     this.log = components.logger.forComponent('libp2p:my-service')
+   *
+   *     this.log('hello')
+   *     // logs:
+   *     // libp2p:my-service hello +0ms
+   *   }
+   * }
+   * ```
+   */
   forComponent(name: string): Logger
 }
 
@@ -299,7 +336,7 @@ export interface Libp2pEvents<T extends ServiceMap = ServiceMap> {
    * })
    * ```
    */
-  'start': CustomEvent<Libp2p<T>>
+  start: CustomEvent<Libp2p<T>>
 
   /**
    * This event notifies listeners that the node has stopped
@@ -310,7 +347,7 @@ export interface Libp2pEvents<T extends ServiceMap = ServiceMap> {
    * })
    * ```
    */
-  'stop': CustomEvent<Libp2p<T>>
+  stop: CustomEvent<Libp2p<T>>
 }
 
 /**

package/src/metrics.ts

@@ -510,7 +510,7 @@ export interface Metrics {
 /**
  * Infer the yielded type of an (async)iterable
  */
-type YieldType<T extends AsyncIterator<any> | Iterator<any>> = T extends AsyncIterator<infer Y> ? Y : T extends Iterator<infer Y, any, any> ? Y : never
+export type YieldType<T extends AsyncIterator<any> | Iterator<any>> = T extends AsyncIterator<infer Y> ? Y : T extends Iterator<infer Y, any, any> ? Y : never
 
 export type TraceAttributes = Record<string, number | string | boolean | number[] | string[] | boolean[]>
 

package/src/peer-discovery.ts

@@ -31,7 +31,12 @@ export interface PeerDiscoveryProvider {
 }
 
 export interface PeerDiscoveryEvents {
-  'peer': CustomEvent<PeerInfo>
+  peer: CustomEvent<PeerInfo>
 }
 
+/**
+ * A class that implements the `PeerDiscovery` interface uses an
+ * implementation-specific method to discover peers. These peers are then added
+ * to the peer store for use by other system components and services.
+ */
 export interface PeerDiscovery extends TypedEventTarget<PeerDiscoveryEvents> {}

package/src/peer-routing.ts

@@ -4,8 +4,8 @@ import type { PeerInfo } from './peer-info.js'
 
 /**
  * Any object that implements this Symbol as a property should return a
- * PeerRouting instance as the property value, similar to how
- * `Symbol.Iterable` can be used to return an `Iterable` from an `Iterator`.
+ * PeerRouting instance as the property value, similar to how `Symbol.Iterable`
+ * can be used to return an `Iterable` from an `Iterator`.
  *
  * @example
  *
@@ -28,7 +28,7 @@ export const peerRoutingSymbol = Symbol.for('@libp2p/peer-routing')
  * interested callers.
  */
 export interface PeerRoutingProvider {
-  [peerRoutingSymbol]: PeerRouting
+  [peerRoutingSymbol]: Partial<PeerRouting>
 }
 
 export interface PeerRouting {

package/src/peer-store.ts

@@ -1,5 +1,6 @@
 import type { PublicKey } from './keys.js'
 import type { PeerId } from './peer-id.js'
+import type { PeerInfo } from './peer-info.js'
 import type { Multiaddr } from '@multiformats/multiaddr'
 
 /**
@@ -229,6 +230,32 @@ export interface PeerStore {
    */
   get(peerId: PeerId): Promise<Peer>
 
+  /**
+   * Returns a PeerInfo object for the passed peer id. This is similar to `get`
+   * except the returned value contains fewer fields and is often used to
+   * exchange peer information with other systems.
+   *
+   * The returned object can be passed to `JSON.stringify` without any
+   * additional processing.
+   *
+   * @see https://docs.libp2p.io/concepts/fundamentals/peers/#peer-info
+   *
+   * @example
+   *
+   * ```TypeScript
+   * const peerInfo = await peerStore.getInfo(peerId)
+   *
+   * console.info(JSON.stringify(peerInfo))
+   * // {
+   * //    id: 'peerId'
+   * //    multiaddrs: [
+   * //      '...'
+   * //    ]
+   * // }
+   * ```
+   */
+  getInfo (peerId: PeerId): Promise<PeerInfo>
+
   /**
    * Adds a peer to the peer store, overwriting any existing data
    *

package/src/pubsub.ts

@@ -7,23 +7,23 @@ import type { Uint8ArrayList } from 'uint8arraylist'
 
 /**
  * On the producing side:
- * * Build messages with the signature, key (from may be enough for certain inlineable public key types), from and seqno fields.
+ * - Build messages with the signature, key (from may be enough for certain inlineable public key types), from and seqno fields.
  *
  * On the consuming side:
- * * Enforce the fields to be present, reject otherwise.
- * * Propagate only if the fields are valid and signature can be verified, reject otherwise.
+ * - Enforce the fields to be present, reject otherwise.
+ * - Propagate only if the fields are valid and signature can be verified, reject otherwise.
  */
 export const StrictSign = 'StrictSign'
 
 /**
  * On the producing side:
- * * Build messages without the signature, key, from and seqno fields.
- * * The corresponding protobuf key-value pairs are absent from the marshaled message, not just empty.
+ * - Build messages without the signature, key, from and seqno fields.
+ * - The corresponding protobuf key-value pairs are absent from the marshaled message, not just empty.
  *
  * On the consuming side:
- * * Enforce the fields to be absent, reject otherwise.
- * * Propagate only if the fields are absent, reject otherwise.
- * * A message_id function will not be able to use the above fields, and should instead rely on the data field. A commonplace strategy is to calculate a hash.
+ * - Enforce the fields to be absent, reject otherwise.
+ * - Propagate only if the fields are absent, reject otherwise.
+ * - A message_id function will not be able to use the above fields, and should instead rely on the data field. A commonplace strategy is to calculate a hash.
  */
 export const StrictNoSign = 'StrictNoSign'
 
@@ -127,7 +127,7 @@ export interface SubscriptionChangeData {
 
 export interface PubSubEvents {
   'subscription-change': CustomEvent<SubscriptionChangeData>
-  'message': CustomEvent<Message>
+  message: CustomEvent<Message>
 }
 
 export interface PublishResult {
@@ -153,6 +153,9 @@ export interface TopicValidatorFn {
   (peer: PeerId, message: Message): TopicValidatorResult | Promise<TopicValidatorResult>
 }
 
+/**
+ * @deprecated This will be removed from `@libp2p/interface` in a future release, pubsub implementations should declare their own types
+ */
 export interface PubSub<Events extends Record<string, any> = PubSubEvents> extends TypedEventTarget<Events> {
   /**
    * The global signature policy controls whether or not we sill send and receive
@@ -266,7 +269,7 @@ export interface PubSub<Events extends Record<string, any> = PubSubEvents> exten
 export interface PeerStreamEvents {
   'stream:inbound': CustomEvent<never>
   'stream:outbound': CustomEvent<never>
-  'close': CustomEvent<never>
+  close: CustomEvent<never>
 }
 
 /**

package/src/record.ts

@@ -23,13 +23,42 @@ export interface Record {
   equals(other: Record): boolean
 }
 
+/**
+ * A message with a signed payload.
+ */
 export interface Envelope {
+  /**
+   * The public key of the keypair used to sign the payload
+   */
   publicKey: PublicKey
+
+  /**
+   * How the payload should be interpreted
+   */
   payloadType: Uint8Array | Uint8ArrayList
+
+  /**
+   * The contents of the envelope
+   */
   payload: Uint8Array
+
+  /**
+   * A signature that can be used to verify the payload is intact
+   */
   signature: Uint8Array | Uint8ArrayList
 
+  /**
+   * Serialize the envelope to a binary format
+   */
   marshal(): Uint8Array
+
+  /**
+   * Use the public key to validate that the payload is intact
+   */
   validate(domain: string): Promise<boolean>
-  equals(other: Envelope): boolean
+
+  /**
+   * Returns true if this envelope has equivalency with the passed object
+   */
+  equals(other?: Envelope): boolean
 }

package/src/startable.ts

@@ -45,10 +45,37 @@ export interface Startable {
   afterStop?(): void | Promise<void>
 }
 
-export function isStartable (obj: any): obj is Startable {
+/**
+ * Returns `true` if the object has type overlap with `Startable`
+ */
+export function isStartable (obj?: any): obj is Startable {
   return obj != null && typeof obj.start === 'function' && typeof obj.stop === 'function'
 }
 
+/**
+ * A function that can be used to start and objects passed to it. This checks
+ * that an object is startable before invoking its lifecycle methods so it is
+ * safe to pass non-`Startable`s in.
+ *
+ * @example
+ *
+ * ```TypeScript
+ * import { start } from '@libp2p/interface'
+ * import type { Startable } from '@libp2p/interface'
+ *
+ * const startable: Startable = {
+ *   start: () => {},
+ *   stop: () => {}
+ * }
+ *
+ * const notStartable = 5
+ *
+ * await start(
+ *   startable,
+ *   notStartable
+ * )
+ * ```
+ */
 export async function start (...objs: any[]): Promise<void> {
   const startables: Startable[] = []
 
@@ -81,6 +108,30 @@ export async function start (...objs: any[]): Promise<void> {
   )
 }
 
+/**
+ * A function that can be used to stop and objects passed to it. This checks
+ * that an object is startable before invoking its lifecycle methods so it is
+ * safe to pass non-`Startable`s in.
+ *
+ * @example
+ *
+ * ```TypeScript
+ * import { stop } from '@libp2p/interface'
+ * import type { Startable } from '@libp2p/interface'
+ *
+ * const startable: Startable = {
+ *   start: () => {},
+ *   stop: () => {}
+ * }
+ *
+ * const notStartable = 5
+ *
+ * await stop(
+ *   startable,
+ *   notStartable
+ * )
+ * ```
+ */
 export async function stop (...objs: any[]): Promise<void> {
   const startables: Startable[] = []
 

package/src/topology.ts

@@ -2,7 +2,8 @@ import type { Connection } from './connection.js'
 import type { PeerId } from './peer-id.js'
 
 /**
- * A topology filter
+ * A topology filter - this can be used by topologies to ensure they do not
+ * receive duplicate notifications of individual peers
  *
  * @see https://libp2p.github.io/js-libp2p/functions/_libp2p_peer_collections.peerFilter-1.html
  */

package/src/transport.ts

@@ -10,18 +10,18 @@ export interface ListenerEvents {
    * This event signals to the transport manager that the listening addresses
    * have changed and may be emitted at any point and/or multiple times
    */
-  'listening': CustomEvent
+  listening: CustomEvent
 
   /**
    * Emitted if listening on an address failed
    */
-  'error': CustomEvent<Error>
+  error: CustomEvent<Error>
 
   /**
    * Emitted when the listener has been shut down, has no open connections and
    * will no longer accept new connections
    */
-  'close': CustomEvent
+  close: CustomEvent
 }
 
 export interface Listener extends TypedEventTarget<ListenerEvents> {
@@ -48,7 +48,12 @@ export interface Listener extends TypedEventTarget<ListenerEvents> {
 
 export const transportSymbol = Symbol.for('@libp2p/transport')
 
-export interface MultiaddrFilter { (multiaddrs: Multiaddr[]): Multiaddr[] }
+/**
+ * A filter that acts on a list of multiaddrs
+ */
+export interface MultiaddrFilter {
+  (multiaddrs: Multiaddr[]): Multiaddr[]
+}
 
 export interface CreateListenerOptions {
   /**
@@ -103,7 +108,10 @@ export interface Transport<DialEvents extends ProgressEvent = ProgressEvent> {
   dialFilter: MultiaddrFilter
 }
 
-export function isTransport (other: any): other is Transport {
+/**
+ * Used to disambiguate transport implementations
+ */
+export function isTransport (other?: any): other is Transport {
   return other != null && Boolean(other[transportSymbol])
 }
 
@@ -122,11 +130,45 @@ export enum FaultTolerance {
   NO_FATAL
 }
 
+/**
+ * Options accepted by the upgrader during connection establishment
+ */
 export interface UpgraderOptions<ConnectionUpgradeEvents extends ProgressEvent = ProgressEvent> extends ProgressOptions<ConnectionUpgradeEvents>, Required<AbortOptions> {
+  /**
+   * If true the invoking transport is expected to implement it's own encryption
+   * and an encryption protocol will not attempted to be negotiated via
+   * multi-stream select
+   *
+   * @default false
+   */
   skipEncryption?: boolean
+
+  /**
+   * If true no connection protection will be performed on the connection.
+   */
   skipProtection?: boolean
+
+  /**
+   * By default a stream muxer protocol will be negotiated via multi-stream
+   * select after an encryption protocol has been agreed on.
+   *
+   * If a transport provides it's own stream muxing facility pass a muxer
+   * factory instance here to skip muxer negotiation.
+   */
   muxerFactory?: StreamMuxerFactory
+
+  /**
+   * If the connection is to have limits applied to it, pass them here
+   */
   limits?: ConnectionLimits
+
+  /**
+   * Multi-stream select is a initiator/responder protocol. By default a
+   * connection returned from `upgrader.upgradeOutbound` will be the initiator
+   * and one returned from `upgrader.upgradeInbound` will be the responder.
+   *
+   * Pass a value here to override the default.
+   */
   initiator?: boolean
 }