diff --git a/.gitignore b/.gitignore index 7d3286a..1531bdf 100644 --- a/.gitignore +++ b/.gitignore @@ -1,33 +1,6 @@ -package-lock.json -yarn.lock -# Logs -logs -*.log - -# Runtime data -pids -*.pid -*.seed - -# Directory for instrumented libs generated by jscoverage/JSCover -lib-cov -.nyc_output - -# Coverage directory used by tools like istanbul -coverage - -# Grunt intermediate storage (http://gruntjs.com/creating-plugins#storing-task-files) -.grunt - -# node-waf configuration -.lock-wscript - -# Compiled binary addons (http://nodejs.org/api/addons.html) -build/Release - -# Dependency directory -# https://www.npmjs.org/doc/misc/npm-faq.html#should-i-check-my-node_modules-folder-into-git node_modules - dist -docs +.docs +.coverage +package-lock.json +yarn.lock diff --git a/README.md b/README.md index f538097..750e0b7 100644 --- a/README.md +++ b/README.md @@ -3,18 +3,18 @@ [![libp2p.io](https://img.shields.io/badge/project-libp2p-yellow.svg?style=flat-square)](http://libp2p.io/) [![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-utils/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 - [Install](#install) -- [Lead Maintainer](#lead-maintainer) + - [Browser ` +``` + 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. @@ -29,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. @@ -43,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). +- ## License @@ -58,6 +60,6 @@ Licensed under either of - Apache 2.0, ([LICENSE-APACHE](LICENSE-APACHE) / ) - MIT ([LICENSE-MIT](LICENSE-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. diff --git a/package.json b/package.json index 9607546..30886a7 100644 --- a/package.json +++ b/package.json @@ -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", diff --git a/src/address-sort.ts b/src/address-sort.ts index 1cf3cb3..b9a1ced 100644 --- a/src/address-sort.ts +++ b/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 { + return Uint8Array.from([0, 1, 2]) +} diff --git a/src/array-equals.ts b/src/array-equals.ts index 3d530d4..21db488 100644 --- a/src/array-equals.ts +++ b/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. diff --git a/src/stream-to-ma-conn.ts b/src/stream-to-ma-conn.ts index cbce121..2eeb28d 100644 --- a/src/stream-to-ma-conn.ts +++ b/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 remoteAddr: Multiaddr localAddr: Multiaddr