@libp2p/interface 2.9.0-f1de46607 → 2.10.0-aa25d38ab

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
 }