deps(dev): bump aegir from 39.0.13 to 41.0.5

.github/dependabot.yml

@@ -5,7 +5,7 @@ updates:
   schedule:
     interval: daily
     time: "10:00"
-  open-pull-requests-limit: 10
+  open-pull-requests-limit: 20
   commit-message:
     prefix: "deps"
     prefix-development: "deps(dev)"

.github/workflows/js-test-and-release.yml

@@ -9,7 +9,9 @@ on:
 
 permissions:
   contents: write
+  id-token: write
   packages: write
+  pull-requests: write
 
 concurrency:
   group: ${{ github.workflow }}-${{ github.event_name }}-${{ github.event_name == 'push' && github.sha || github.ref }}

.github/workflows/semantic-pull-request.yml

@@ -0,0 +1,12 @@
+name: Semantic PR
+
+on:
+  pull_request_target:
+    types:
+      - opened
+      - edited
+      - synchronize
+
+jobs:
+  main:
+    uses: pl-strflt/.github/.github/workflows/[email protected]

.github/workflows/stale.yml

@@ -0,0 +1,13 @@
+name: Close and mark stale issue
+
+on:
+  schedule:
+    - cron: '0 0 * * *'
+
+permissions:
+  issues: write
+  pull-requests: write
+
+jobs:
+  stale:
+    uses: pl-strflt/.github/.github/workflows/[email protected]

README.md

@@ -4,32 +4,13 @@
 [![codecov](https://img.shields.io/codecov/c/github/multiformats/js-multiaddr-to-uri.svg?style=flat-square)](https://codecov.io/gh/multiformats/js-multiaddr-to-uri)
 [![CI](https://img.shields.io/github/actions/workflow/status/multiformats/js-multiaddr-to-uri/js-test-and-release.yml?branch=master\&style=flat-square)](https://github.com/multiformats/js-multiaddr-to-uri/actions/workflows/js-test-and-release.yml?query=branch%3Amaster)
 
-> Convert a Multiaddr to a URI /dnsaddr/ipfs.io/http -> <http://ipfs.io>
+> Convert a Multiaddr to a URI
 
-## Table of contents <!-- omit in toc -->
+# About
 
-- [Install](#install)
-  - [Browser `<script>` tag](#browser-script-tag)
-- [Usage](#usage)
-- [API Docs](#api-docs)
-- [License](#license)
-- [Contribution](#contribution)
+This module allows easy conversion of Multiaddrs to URLs.
 
-## Install
-
-```console
-$ npm i @multiformats/multiaddr-to-uri
-```
-
-### Browser `<script>` tag
-
-Loading this module through a script tag will make it's exports available as `MultiformatsMultiaddrToUri` in the global namespace.
-
-```html
-<script src="https://unpkg.com/@multiformats/multiaddr-to-uri/dist/index.min.js"></script>
-```
-
-## Usage
+## Example - Converting multiaddrs to URLs
 
 ```js
 import { multiaddrToUri } from '@multiformats/multiaddr-to-uri'
@@ -54,17 +35,31 @@ Note:
   - is not a valid multiaddr
   - is not supported as a URI e.g. circuit
 
-## API Docs
+# Install
+
+```console
+$ npm i @multiformats/multiaddr-to-uri
+```
+
+## Browser `<script>` tag
+
+Loading this module through a script tag will make it's exports available as `MultiformatsMultiaddrToUri` in the global namespace.
+
+```html
+<script src="https://unpkg.com/@multiformats/multiaddr-to-uri/dist/index.min.js"></script>
+```
+
+# API Docs
 
 - <https://multiformats.github.io/js-multiaddr-to-uri>
 
-## License
+# License
 
 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>)
 
-## Contribution
+# 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.json

@@ -1,7 +1,7 @@
 {
   "name": "@multiformats/multiaddr-to-uri",
   "version": "9.0.7",
-  "description": "Convert a Multiaddr to a URI /dnsaddr/ipfs.io/http -> http://ipfs.io",
+  "description": "Convert a Multiaddr to a URI",
   "author": "Alan Shaw",
   "license": "Apache-2.0 OR MIT",
   "homepage": "https://github.com/multiformats/js-multiaddr-to-uri#readme",
@@ -12,15 +12,15 @@
   "bugs": {
     "url": "https://github.com/multiformats/js-multiaddr-to-uri/issues"
   },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
   "keywords": [
     "URL",
     "multiaddr",
     "toString"
   ],
-  "engines": {
-    "node": ">=16.0.0",
-    "npm": ">=7.0.0"
-  },
   "type": "module",
   "types": "./dist/src/index.d.ts",
   "files": [
@@ -38,6 +38,7 @@
   "eslintConfig": {
     "extends": "ipfs",
     "parserOptions": {
+      "project": true,
       "sourceType": "module"
     }
   },
@@ -146,6 +147,6 @@
     "@multiformats/multiaddr": "^12.0.0"
   },
   "devDependencies": {
-    "aegir": "^39.0.7"
+    "aegir": "^42.2.2"
   }
 }

src/index.ts

@@ -1,3 +1,34 @@
+/**
+ * @packageDocumentation
+ *
+ * This module allows easy conversion of Multiaddrs to URLs.
+ *
+ * @example Converting multiaddrs to URLs
+ *
+ * ```js
+ * import { multiaddrToUri } from '@multiformats/multiaddr-to-uri'
+ *
+ * console.log(multiaddrToUri('/dnsaddr/protocol.ai/https'))
+ * // -> https://protocol.ai
+ *
+ * console.log(multiaddrToUri('/ip4/127.0.0.1/tcp/8080'))
+ * // -> http://127.0.0.1:8080
+ *
+ * console.log(multiaddrToUri('/ip4/127.0.0.1/tcp/8080', { assumeHttp: false }))
+ * // -> tcp://127.0.0.1:8080
+ * ```
+ *
+ * Note:
+ *
+ * - When `/tcp` is the last (terminating) protocol HTTP is assumed by default (implicit `assumeHttp: true`)
+ *   - this means produced URIs will start with `http://` instead of `tcp://`
+ *   - passing `{ assumeHttp: false }` disables this behavior
+ * - Might be lossy - e.g. a DNSv6 multiaddr
+ * - Can throw if the passed multiaddr:
+ *   - is not a valid multiaddr
+ *   - is not supported as a URI e.g. circuit
+ */
+
 import { multiaddr, protocols } from '@multiformats/multiaddr'
 import type { Multiaddr, StringTuple } from '@multiformats/multiaddr'
 
@@ -12,9 +43,9 @@
   try {
     sniProtoCode = protocols('sni').code
   } catch (e) {
     // No SNI protocol in multiaddr
     return null
   }
   for (const [proto, value] of ma) {
     if (proto === sniProtoCode && value !== undefined) {
       return value
@@ -30,8 +61,8 @@
 function interpretNext (headProtoCode: number, headProtoVal: string, restMa: StringTuple[]): string {
   const interpreter = interpreters[protocols(headProtoCode).name]
   if (interpreter === undefined) {
     throw new Error(`Can't interpret protocol ${protocols(headProtoCode).name}`)
   }
   const restVal = interpreter(headProtoVal, restMa)
   if (headProtoCode === protocols('ip6').code) {
     return `[${restVal}]`
@@ -45,20 +76,20 @@
     if (restMa.length === 0) {
       return value
     }
     return `[${value}]`
   },
   tcp: (value: string, restMa: StringTuple[]) => {
     const tailProto = restMa.pop()
     if (tailProto === undefined) {
       throw new Error('Unexpected end of multiaddr')
     }
     return `tcp://${interpretNext(tailProto[0], tailProto[1] ?? '', restMa)}:${value}`
   },
   udp: (value: string, restMa: StringTuple[]) => {
     const tailProto = restMa.pop()
     if (tailProto === undefined) {
       throw new Error('Unexpected end of multiaddr')
     }
     return `udp://${interpretNext(tailProto[0], tailProto[1] ?? '', restMa)}:${value}`
   },
   dnsaddr: (value: string, restMa: StringTuple[]) => value,
@@ -66,17 +97,17 @@
   dns6: (value: string, restMa: StringTuple[]) => value,
   dns: (value: string, restMa: StringTuple[]) => value,
   ipfs: (value: string, restMa: StringTuple[]) => {
     const tailProto = restMa.pop()
     if (tailProto === undefined) {
       throw new Error('Unexpected end of multiaddr')
     }
     return `${interpretNext(tailProto[0], tailProto[1] ?? '', restMa)}/ipfs/${value}`
   },
   p2p: (value: string, restMa: StringTuple[]) => {
     const tailProto = restMa.pop()
     if (tailProto === undefined) {
       throw new Error('Unexpected end of multiaddr')
     }
     return `${interpretNext(tailProto[0], tailProto[1] ?? '', restMa)}/p2p/${value}`
   },
   http: (value: string, restMa: StringTuple[]) => {
@@ -88,7 +119,7 @@
     const protocol = maHasTLS ? 'https://' : 'http://'
     const tailProto = restMa.pop()
     if (tailProto === undefined) {
       throw new Error('Unexpected end of multiaddr')
     }
     let baseVal = interpretNext(tailProto[0], tailProto[1] ?? '', restMa)
     // We are reinterpreting the base as http, so we need to remove the tcp:// if it's there
@@ -100,24 +131,24 @@
     // anything here
     const tailProto = restMa.pop()
     if (tailProto === undefined) {
       throw new Error('Unexpected end of multiaddr')
     }
     return interpretNext(tailProto[0], tailProto[1] ?? '', restMa)
   },
   sni: (value: string, restMa: StringTuple[]) => {
     // Noop, the parent context uses the sni information, we don't need to do
     // anything here
     const tailProto = restMa.pop()
     if (tailProto === undefined) {
       throw new Error('Unexpected end of multiaddr')
     }
     return interpretNext(tailProto[0], tailProto[1] ?? '', restMa)
   },
   https: (value: string, restMa: StringTuple[]) => {
     const tailProto = restMa.pop()
     if (tailProto === undefined) {
       throw new Error('Unexpected end of multiaddr')
     }
     let baseVal = interpretNext(tailProto[0], tailProto[1] ?? '', restMa)
     // We are reinterpreting the base as http, so we need to remove the tcp:// if it's there
     baseVal = baseVal.replace('tcp://', '')
@@ -132,7 +163,7 @@
     const protocol = maHasTLS ? 'wss://' : 'ws://'
     const tailProto = restMa.pop()
     if (tailProto === undefined) {
       throw new Error('Unexpected end of multiaddr')
     }
     let baseVal = interpretNext(tailProto[0], tailProto[1] ?? '', restMa)
     // We are reinterpreting the base, so we need to remove the tcp:// if it's there
@@ -142,8 +173,8 @@
   wss: (value: string, restMa: StringTuple[]) => {
     const tailProto = restMa.pop()
     if (tailProto === undefined) {
       throw new Error('Unexpected end of multiaddr')
     }
     let baseVal = interpretNext(tailProto[0], tailProto[1] ?? '', restMa)
     // We are reinterpreting the base as http, so we need to remove the tcp:// if it's there
     baseVal = baseVal.replace('tcp://', '')
@@ -152,22 +183,22 @@
   'p2p-websocket-star': (value: string, restMa: StringTuple[]) => {
     const tailProto = restMa.pop()
     if (tailProto === undefined) {
       throw new Error('Unexpected end of multiaddr')
     }
     return `${interpretNext(tailProto[0], tailProto[1] ?? '', restMa)}/p2p-websocket-star`
   },
   'p2p-webrtc-star': (value: string, restMa: StringTuple[]) => {
     const tailProto = restMa.pop()
     if (tailProto === undefined) {
       throw new Error('Unexpected end of multiaddr')
     }
     return `${interpretNext(tailProto[0], tailProto[1] ?? '', restMa)}/p2p-webrtc-star`
   },
   'p2p-webrtc-direct': (value: string, restMa: StringTuple[]) => {
     const tailProto = restMa.pop()
     if (tailProto === undefined) {
       throw new Error('Unexpected end of multiaddr')
     }
     return `${interpretNext(tailProto[0], tailProto[1] ?? '', restMa)}/p2p-webrtc-direct`
   }
 }
@@ -177,8 +208,8 @@
   const parts = ma.stringTuples()
   const head = parts.pop()
   if (head === undefined) {
     throw new Error('Unexpected end of multiaddr')
   }
 
   const protocol = protocols(head[0])
   const interpreter = interpreters[protocol.name]

typedoc.json

@@ -0,0 +1,5 @@
+{
+  "entryPoints": [
+    "./src/index.ts"
+  ]
+}