@libp2p/utils 3.0.2 → 3.0.4

package/README.md

@@ -1,21 +1,20 @@
 # @libp2p/utils <!-- omit in toc -->
 
 [![libp2p.io](https://img.shields.io/badge/project-libp2p-yellow.svg?style=flat-square)](http://libp2p.io/)
-[![IRC](https://img.shields.io/badge/freenode-%23libp2p-yellow.svg?style=flat-square)](http://webchat.freenode.net/?channels=%23libp2p)
 [![Discuss](https://img.shields.io/discourse/https/discuss.libp2p.io/posts.svg?style=flat-square)](https://discuss.libp2p.io)
 [![codecov](https://img.shields.io/codecov/c/github/libp2p/js-libp2p-utils.svg?style=flat-square)](https://codecov.io/gh/libp2p/js-libp2p-utils)
-[![CI](https://img.shields.io/github/workflow/status/libp2p/js-libp2p-interfaces/test%20&%20maybe%20release/master?style=flat-square)](https://github.com/libp2p/js-libp2p-utils/actions/workflows/js-test-and-release.yml)
+[![CI](https://img.shields.io/github/actions/workflow/status/libp2p/js-libp2p-utils/js-test-and-release.yml?branch=master\&style=flat-square)](https://github.com/libp2p/js-libp2p-utils/actions/workflows/js-test-and-release.yml?query=branch%3Amaster)
 
 > Package to aggregate shared logic and dependencies for the libp2p ecosystem
 
 ## Table of contents <!-- omit in toc -->
 
 - [Install](#install)
-- [Lead Maintainer](#lead-maintainer)
+  - [Browser `<script>` tag](#browser-script-tag)
 - [Usage](#usage)
-- [Contribute](#contribute)
+- [API Docs](#api-docs)
 - [License](#license)
-- [Contribute](#contribute-1)
+- [Contribution](#contribution)
 
 ## Install
 
@@ -23,6 +22,14 @@
 $ npm i @libp2p/utils
 ```
 
+### Browser `<script>` tag
+
+Loading this module through a script tag will make it's exports available as `Libp2pUtils` in the global namespace.
+
+```html
+<script src="https://unpkg.com/@libp2p/utils/dist/index.min.js"></script>
+```
+
 The libp2p ecosystem has lots of repos with it comes several problems like:
 
 - Domain logic dedupe - all modules shared a lot of logic like validation, streams handling, etc.
@@ -30,10 +37,6 @@ The libp2p ecosystem has lots of repos with it comes several problems like:
 
 These problems are the motivation for this package, having shared logic in this package avoids creating cyclic dependencies, centralizes common use modules/functions (exactly like aegir does for the tooling), semantic versioning for 3rd party dependencies is handled in one single place (a good example is going from streams 2 to 3) and maintainers should only care about having `libp2p-utils` updated.
 
-## Lead Maintainer
-
-[Vasco Santos](https://github.com/vasco-santos)
-
 ## Usage
 
 Each function should be imported directly.
@@ -44,13 +47,11 @@ import ipAndPortToMultiaddr from '@libp2p/utils/ip-port-to-multiaddr'
 const ma = ipAndPortToMultiaddr('127.0.0.1', 9000)
 ```
 
-You can check the [API docs](./API.md).
-
-## Contribute
+You can check the [API docs](https://libp2p.github.io/js-libp2p-utils).
 
-Contributions welcome. Please check out [the issues](https://github.com/libp2p/js-libp2p-utils/issues).
+## API Docs
 
-Check out our [contributing document](https://github.com/ipfs/community/blob/master/contributing.md) for more information on how we work, and about contributing in general. Please be aware that all interactions related to this repo are subject to the IPFS [Code of Conduct](https://github.com/ipfs/community/blob/master/code-of-conduct.md).
+- <https://libp2p.github.io/js-libp2p-utils>
 
 ## License
 
@@ -59,6 +60,6 @@ Licensed under either of
 - Apache 2.0, ([LICENSE-APACHE](LICENSE-APACHE) / <http://www.apache.org/licenses/LICENSE-2.0>)
 - MIT ([LICENSE-MIT](LICENSE-MIT) / <http://opensource.org/licenses/MIT>)
 
-## Contribute
+## Contribution
 
 Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.

package/dist/index.min.js

@@ -0,0 +1,3 @@
+(function (root, factory) {(typeof module === 'object' && module.exports) ? module.exports = factory() : root.Libp2PUtils = factory()}(typeof self !== 'undefined' ? self : this, function () {
+"use strict";var Libp2PUtils=(()=>{var t=Object.defineProperty;var a=Object.getOwnPropertyDescriptor;var b=Object.getOwnPropertyNames;var c=Object.prototype.hasOwnProperty;var d=(o,e,x,r)=>{if(e&&typeof e=="object"||typeof e=="function")for(let p of b(e))!c.call(o,p)&&p!==x&&t(o,p,{get:()=>e[p],enumerable:!(r=a(e,p))||r.enumerable});return o};var f=o=>d(t({},"__esModule",{value:!0}),o);var g={};return f(g);})();
+return Libp2PUtils}));

package/dist/src/address-sort.d.ts

@@ -1,3 +1,24 @@
+/**
+ * @packageDocumentation
+ *
+ * Provides strategies to sort a list of multiaddrs.
+ *
+ * @example
+ *
+ * ```typescript
+ * import { publicAddressesFirst } from '@libp2p/utils/address-sort'
+ * import { multiaddr } from '@multformats/multiaddr'
+ *
+ *
+ * const addresses = [
+ *   multiaddr('/ip4/127.0.0.1/tcp/9000'),
+ *   multiaddr('/ip4/82.41.53.1/tcp/9000')
+ * ].sort(publicAddressesFirst)
+ *
+ * console.info(addresses)
+ * // ['/ip4/82.41.53.1/tcp/9000', '/ip4/127.0.0.1/tcp/9000']
+ * ```
+ */
 import type { Address } from '@libp2p/interface-peer-store';
 /**
  * Compare function for array.sort().
@@ -5,4 +26,8 @@ import type { Address } from '@libp2p/interface-peer-store';
  * In case of equality, a certified address will come first.
  */
 export declare function publicAddressesFirst(a: Address, b: Address): -1 | 0 | 1;
+/**
+ * A test thing
+ */
+export declare function something(): Promise<Uint8Array>;
 //# sourceMappingURL=address-sort.d.ts.map

package/dist/src/address-sort.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"address-sort.d.ts","sourceRoot":"","sources":["../../src/address-sort.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,8BAA8B,CAAA;AAG3D;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAE,CAAC,EAAE,OAAO,EAAE,CAAC,EAAE,OAAO,GAAG,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,CAiBxE"}
+{"version":3,"file":"address-sort.d.ts","sourceRoot":"","sources":["../../src/address-sort.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,8BAA8B,CAAA;AAG3D;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAE,CAAC,EAAE,OAAO,EAAE,CAAC,EAAE,OAAO,GAAG,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,CAiBxE;AAED;;GAEG;AACH,wBAAsB,SAAS,IAAK,OAAO,CAAC,UAAU,CAAC,CAEtD"}

package/dist/src/address-sort.js

@@ -1,3 +1,24 @@
+/**
+ * @packageDocumentation
+ *
+ * Provides strategies to sort a list of multiaddrs.
+ *
+ * @example
+ *
+ * ```typescript
+ * import { publicAddressesFirst } from '@libp2p/utils/address-sort'
+ * import { multiaddr } from '@multformats/multiaddr'
+ *
+ *
+ * const addresses = [
+ *   multiaddr('/ip4/127.0.0.1/tcp/9000'),
+ *   multiaddr('/ip4/82.41.53.1/tcp/9000')
+ * ].sort(publicAddressesFirst)
+ *
+ * console.info(addresses)
+ * // ['/ip4/82.41.53.1/tcp/9000', '/ip4/127.0.0.1/tcp/9000']
+ * ```
+ */
 import { isPrivate } from './multiaddr/is-private.js';
 /**
  * Compare function for array.sort().
@@ -22,4 +43,10 @@ export function publicAddressesFirst(a, b) {
     }
     return 0;
 }
+/**
+ * A test thing
+ */
+export async function something() {
+    return Uint8Array.from([0, 1, 2]);
+}
 //# sourceMappingURL=address-sort.js.map

package/dist/src/address-sort.js.map

@@ -1 +1 @@
-{"version":3,"file":"address-sort.js","sourceRoot":"","sources":["../../src/address-sort.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,SAAS,EAAE,MAAM,2BAA2B,CAAA;AAErD;;;;GAIG;AACH,MAAM,UAAU,oBAAoB,CAAE,CAAU,EAAE,CAAU;IAC1D,MAAM,UAAU,GAAG,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAA;IACzC,MAAM,UAAU,GAAG,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAA;IAEzC,IAAI,UAAU,IAAI,CAAC,UAAU,EAAE;QAC7B,OAAO,CAAC,CAAA;KACT;SAAM,IAAI,CAAC,UAAU,IAAI,UAAU,EAAE;QACpC,OAAO,CAAC,CAAC,CAAA;KACV;IACD,mBAAmB;IACnB,IAAI,CAAC,CAAC,WAAW,IAAI,CAAC,CAAC,CAAC,WAAW,EAAE;QACnC,OAAO,CAAC,CAAC,CAAA;KACV;SAAM,IAAI,CAAC,CAAC,CAAC,WAAW,IAAI,CAAC,CAAC,WAAW,EAAE;QAC1C,OAAO,CAAC,CAAA;KACT;IAED,OAAO,CAAC,CAAA;AACV,CAAC"}
+{"version":3,"file":"address-sort.js","sourceRoot":"","sources":["../../src/address-sort.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAGH,OAAO,EAAE,SAAS,EAAE,MAAM,2BAA2B,CAAA;AAErD;;;;GAIG;AACH,MAAM,UAAU,oBAAoB,CAAE,CAAU,EAAE,CAAU;IAC1D,MAAM,UAAU,GAAG,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAA;IACzC,MAAM,UAAU,GAAG,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAA;IAEzC,IAAI,UAAU,IAAI,CAAC,UAAU,EAAE;QAC7B,OAAO,CAAC,CAAA;KACT;SAAM,IAAI,CAAC,UAAU,IAAI,UAAU,EAAE;QACpC,OAAO,CAAC,CAAC,CAAA;KACV;IACD,mBAAmB;IACnB,IAAI,CAAC,CAAC,WAAW,IAAI,CAAC,CAAC,CAAC,WAAW,EAAE;QACnC,OAAO,CAAC,CAAC,CAAA;KACV;SAAM,IAAI,CAAC,CAAC,CAAC,WAAW,IAAI,CAAC,CAAC,WAAW,EAAE;QAC1C,OAAO,CAAC,CAAA;KACT;IAED,OAAO,CAAC,CAAA;AACV,CAAC;AAED;;GAEG;AACH,MAAM,CAAC,KAAK,UAAU,SAAS;IAC7B,OAAO,UAAU,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC,CAAA;AACnC,CAAC"}

package/dist/src/array-equals.d.ts

@@ -1,3 +1,21 @@
+/**
+ * @packageDocumentation
+ *
+ * Provides strategies ensure arrays are equivalent.
+ *
+ * @example
+ *
+ * ```typescript
+ * import { arrayEquals } from '@libp2p/utils/array-equals'
+ * import { multiaddr } from '@multformats/multiaddr'
+ *
+ * const ma1 = multiaddr('/ip4/127.0.0.1/tcp/9000'),
+ * const ma2 = multiaddr('/ip4/82.41.53.1/tcp/9000')
+ *
+ * console.info(arrayEquals([ma1], [ma1])) // true
+ * console.info(arrayEquals([ma1], [ma2])) // false
+ * ```
+ */
 /**
  * Verify if two arrays of non primitive types with the "equals" function are equal.
  * Compatible with multiaddr, peer-id and others.

package/dist/src/array-equals.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"array-equals.d.ts","sourceRoot":"","sources":["../../src/array-equals.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,wBAAgB,WAAW,CAAE,CAAC,EAAE,GAAG,EAAE,EAAE,CAAC,EAAE,GAAG,EAAE,WAU9C"}
+{"version":3,"file":"array-equals.d.ts","sourceRoot":"","sources":["../../src/array-equals.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH;;;GAGG;AACH,wBAAgB,WAAW,CAAE,CAAC,EAAE,GAAG,EAAE,EAAE,CAAC,EAAE,GAAG,EAAE,WAU9C"}

package/dist/src/array-equals.js

@@ -1,3 +1,21 @@
+/**
+ * @packageDocumentation
+ *
+ * Provides strategies ensure arrays are equivalent.
+ *
+ * @example
+ *
+ * ```typescript
+ * import { arrayEquals } from '@libp2p/utils/array-equals'
+ * import { multiaddr } from '@multformats/multiaddr'
+ *
+ * const ma1 = multiaddr('/ip4/127.0.0.1/tcp/9000'),
+ * const ma2 = multiaddr('/ip4/82.41.53.1/tcp/9000')
+ *
+ * console.info(arrayEquals([ma1], [ma1])) // true
+ * console.info(arrayEquals([ma1], [ma2])) // false
+ * ```
+ */
 /**
  * Verify if two arrays of non primitive types with the "equals" function are equal.
  * Compatible with multiaddr, peer-id and others.

package/dist/src/array-equals.js.map

@@ -1 +1 @@
-{"version":3,"file":"array-equals.js","sourceRoot":"","sources":["../../src/array-equals.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,MAAM,UAAU,WAAW,CAAE,CAAQ,EAAE,CAAQ;IAC7C,MAAM,IAAI,GAAG,CAAC,CAAM,EAAE,CAAM,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,EAAE,CAAC,aAAa,CAAC,CAAC,CAAC,QAAQ,EAAE,CAAC,CAAA;IAEzE,IAAI,CAAC,CAAC,MAAM,KAAK,CAAC,CAAC,MAAM,EAAE;QACzB,OAAO,KAAK,CAAA;KACb;IAED,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;IAEZ,OAAO,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,KAAK,CAAC,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAA;AACnE,CAAC"}
+{"version":3,"file":"array-equals.js","sourceRoot":"","sources":["../../src/array-equals.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH;;;GAGG;AACH,MAAM,UAAU,WAAW,CAAE,CAAQ,EAAE,CAAQ;IAC7C,MAAM,IAAI,GAAG,CAAC,CAAM,EAAE,CAAM,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,EAAE,CAAC,aAAa,CAAC,CAAC,CAAC,QAAQ,EAAE,CAAC,CAAA;IAEzE,IAAI,CAAC,CAAC,MAAM,KAAK,CAAC,CAAC,MAAM,EAAE;QACzB,OAAO,KAAK,CAAA;KACb;IAED,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;IAEZ,OAAO,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,KAAK,CAAC,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAA;AACnE,CAAC"}

package/dist/src/stream-to-ma-conn.d.ts

@@ -16,10 +16,10 @@ export interface Timeline {
      */
     close?: number;
 }
-interface StreamOptions {
+export interface StreamOptions {
     signal?: AbortSignal;
 }
-interface StreamProperties {
+export interface StreamProperties {
     stream: Duplex<Uint8ArrayList, Uint8ArrayList | Uint8Array>;
     remoteAddr: Multiaddr;
     localAddr: Multiaddr;
@@ -29,5 +29,4 @@ interface StreamProperties {
  * https://github.com/libp2p/interface-transport#multiaddrconnection
  */
 export declare function streamToMaConnection(props: StreamProperties, options?: StreamOptions): MultiaddrConnection;
-export {};
 //# sourceMappingURL=stream-to-ma-conn.d.ts.map

package/dist/src/stream-to-ma-conn.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"stream-to-ma-conn.d.ts","sourceRoot":"","sources":["../../src/stream-to-ma-conn.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yBAAyB,CAAA;AACxD,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,8BAA8B,CAAA;AACvE,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,iBAAiB,CAAA;AAC7C,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAA;AAIpD,MAAM,WAAW,QAAQ;IACvB;;OAEG;IACH,IAAI,EAAE,MAAM,CAAA;IAEZ;;OAEG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAA;IAEjB;;OAEG;IACH,KAAK,CAAC,EAAE,MAAM,CAAA;CACf;AAED,UAAU,aAAa;IACrB,MAAM,CAAC,EAAE,WAAW,CAAA;CAErB;AAED,UAAU,gBAAgB;IACxB,MAAM,EAAE,MAAM,CAAC,cAAc,EAAE,cAAc,GAAG,UAAU,CAAC,CAAA;IAC3D,UAAU,EAAE,SAAS,CAAA;IACrB,SAAS,EAAE,SAAS,CAAA;CACrB;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,CAAE,KAAK,EAAE,gBAAgB,EAAE,OAAO,GAAE,aAAkB,uBAiDzF"}
+{"version":3,"file":"stream-to-ma-conn.d.ts","sourceRoot":"","sources":["../../src/stream-to-ma-conn.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yBAAyB,CAAA;AACxD,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,8BAA8B,CAAA;AACvE,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,iBAAiB,CAAA;AAC7C,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAA;AAIpD,MAAM,WAAW,QAAQ;IACvB;;OAEG;IACH,IAAI,EAAE,MAAM,CAAA;IAEZ;;OAEG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAA;IAEjB;;OAEG;IACH,KAAK,CAAC,EAAE,MAAM,CAAA;CACf;AAED,MAAM,WAAW,aAAa;IAC5B,MAAM,CAAC,EAAE,WAAW,CAAA;CAErB;AAED,MAAM,WAAW,gBAAgB;IAC/B,MAAM,EAAE,MAAM,CAAC,cAAc,EAAE,cAAc,GAAG,UAAU,CAAC,CAAA;IAC3D,UAAU,EAAE,SAAS,CAAA;IACrB,SAAS,EAAE,SAAS,CAAA;CACrB;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,CAAE,KAAK,EAAE,gBAAgB,EAAE,OAAO,GAAE,aAAkB,uBAiDzF"}

package/dist/typedoc-urls.json

@@ -0,0 +1,13 @@
+{
+  "publicAddressesFirst": "https://libp2p.github.io/js-libp2p-utils/functions/address_sort.publicAddressesFirst.html",
+  "something": "https://libp2p.github.io/js-libp2p-utils/functions/address_sort.something.html",
+  "arrayEquals": "https://libp2p.github.io/js-libp2p-utils/functions/array_equals.arrayEquals.html",
+  "Errors": "https://libp2p.github.io/js-libp2p-utils/variables/ip_port_to_multiaddr.Errors.html",
+  "ipPortToMultiaddr": "https://libp2p.github.io/js-libp2p-utils/functions/ip_port_to_multiaddr.ipPortToMultiaddr.html",
+  "isLoopback": "https://libp2p.github.io/js-libp2p-utils/functions/multiaddr_is_loopback.isLoopback.html",
+  "isPrivate": "https://libp2p.github.io/js-libp2p-utils/functions/multiaddr_is_private.isPrivate.html",
+  "StreamOptions": "https://libp2p.github.io/js-libp2p-utils/interfaces/stream_to_ma_conn.StreamOptions.html",
+  "StreamProperties": "https://libp2p.github.io/js-libp2p-utils/interfaces/stream_to_ma_conn.StreamProperties.html",
+  "Timeline": "https://libp2p.github.io/js-libp2p-utils/interfaces/stream_to_ma_conn.Timeline.html",
+  "streamToMaConnection": "https://libp2p.github.io/js-libp2p-utils/functions/stream_to_ma_conn.streamToMaConnection.html"
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@libp2p/utils",
-  "version": "3.0.2",
+  "version": "3.0.4",
   "description": "Package to aggregate shared logic and dependencies for the libp2p ecosystem",
   "license": "Apache-2.0 OR MIT",
   "homepage": "https://github.com/libp2p/js-libp2p-utils#readme",
@@ -35,7 +35,7 @@
   },
   "files": [
     "src",
-    "dist/src",
+    "dist",
     "!dist/test",
     "!**/*.tsbuildinfo"
   ],
@@ -165,6 +165,7 @@
     "lint": "aegir lint",
     "dep-check": "aegir dep-check",
     "build": "aegir build",
+    "docs": "aegir docs",
     "test": "aegir test",
     "test:chrome": "aegir test -t browser --cov",
     "test:chrome-webworker": "aegir test -t webworker",
@@ -184,16 +185,16 @@
     "err-code": "^3.0.1",
     "is-loopback-addr": "^2.0.1",
     "it-stream-types": "^1.0.4",
-    "private-ip": "^2.1.1",
+    "private-ip": "^3.0.0",
     "uint8arraylist": "^2.3.2"
   },
   "devDependencies": {
     "aegir": "^37.2.0",
-    "it-all": "^1.0.6",
-    "it-map": "^1.0.6",
+    "it-all": "^2.0.0",
+    "it-map": "^2.0.0",
     "it-pair": "^2.0.2",
     "it-pipe": "^2.0.2",
     "p-defer": "^4.0.0",
-    "uint8arrays": "^3.0.0"
+    "uint8arrays": "^4.0.2"
   }
 }

package/src/address-sort.ts

@@ -1,3 +1,25 @@
+/**
+ * @packageDocumentation
+ *
+ * Provides strategies to sort a list of multiaddrs.
+ *
+ * @example
+ *
+ * ```typescript
+ * import { publicAddressesFirst } from '@libp2p/utils/address-sort'
+ * import { multiaddr } from '@multformats/multiaddr'
+ *
+ *
+ * const addresses = [
+ *   multiaddr('/ip4/127.0.0.1/tcp/9000'),
+ *   multiaddr('/ip4/82.41.53.1/tcp/9000')
+ * ].sort(publicAddressesFirst)
+ *
+ * console.info(addresses)
+ * // ['/ip4/82.41.53.1/tcp/9000', '/ip4/127.0.0.1/tcp/9000']
+ * ```
+ */
+
 import type { Address } from '@libp2p/interface-peer-store'
 import { isPrivate } from './multiaddr/is-private.js'
 
@@ -24,3 +46,10 @@ export function publicAddressesFirst (a: Address, b: Address): -1 | 0 | 1 {
 
   return 0
 }
+
+/**
+ * A test thing
+ */
+export async function something (): Promise<Uint8Array> {
+  return Uint8Array.from([0, 1, 2])
+}

package/src/array-equals.ts

@@ -1,3 +1,22 @@
+/**
+ * @packageDocumentation
+ *
+ * Provides strategies ensure arrays are equivalent.
+ *
+ * @example
+ *
+ * ```typescript
+ * import { arrayEquals } from '@libp2p/utils/array-equals'
+ * import { multiaddr } from '@multformats/multiaddr'
+ *
+ * const ma1 = multiaddr('/ip4/127.0.0.1/tcp/9000'),
+ * const ma2 = multiaddr('/ip4/82.41.53.1/tcp/9000')
+ *
+ * console.info(arrayEquals([ma1], [ma1])) // true
+ * console.info(arrayEquals([ma1], [ma2])) // false
+ * ```
+ */
+
 /**
  * Verify if two arrays of non primitive types with the "equals" function are equal.
  * Compatible with multiaddr, peer-id and others.

package/src/stream-to-ma-conn.ts

@@ -24,12 +24,12 @@ export interface Timeline {
   close?: number
 }
 
-interface StreamOptions {
+export interface StreamOptions {
   signal?: AbortSignal
 
 }
 
-interface StreamProperties {
+export interface StreamProperties {
   stream: Duplex<Uint8ArrayList, Uint8ArrayList | Uint8Array>
   remoteAddr: Multiaddr
   localAddr: Multiaddr