feat: export functions to make custom matchers

To allow creating custom matchers, export all the necessary functions
from the `/utils` path.

Author: achingbrain

package.json

@@ -26,6 +26,10 @@
     ".": {
       "types": "./dist/src/index.d.ts",
       "import": "./dist/src/index.js"
+    },
+    "./utils": {
+      "types": "./dist/src/utils.d.ts",
+      "import": "./dist/src/utils.js"
     }
   },
   "eslintConfig": {

src/index.ts

@@ -33,224 +33,29 @@
  */
 
 import { isIPv4, isIPv6 } from '@chainsafe/is-ip'
-import { type Multiaddr } from '@multiformats/multiaddr'
-import { base58btc } from 'multiformats/bases/base58'
-import { base64url } from 'multiformats/bases/base64'
-
-/**
- * Split a multiaddr into path components
- */
-const toParts = (ma: Multiaddr): string[] => {
-  return ma.toString().split('/').slice(1)
-}
+import { and, or, literal, string, peerId, optional, fmt, func, number, certhash } from './utils.js'
+import type { Multiaddr } from '@multiformats/multiaddr'
 
 /**
  * A matcher accepts multiaddr components and either fails to match and returns
  * false or returns a sublist of unmatched components
  */
-interface Matcher {
+export interface Matcher {
   match(parts: string[]): string[] | false
   pattern: string
 }
 
-const func = (fn: (val: string) => boolean): Matcher => {
-  return {
-    match: (vals) => {
-      if (vals.length < 1) {
-        return false
-      }
-
-      if (fn(vals[0])) {
-        return vals.slice(1)
-      }
-
-      return false
-    },
-    pattern: 'fn'
-  }
-}
-
-const literal = (str: string): Matcher => {
-  return {
-    match: (vals) => func((val) => val === str).match(vals),
-    pattern: str
-  }
-}
-
-const string = (): Matcher => {
-  return {
-    match: (vals) => func((val) => typeof val === 'string').match(vals),
-    pattern: '{string}'
-  }
-}
-
-const number = (): Matcher => {
-  return {
-    match: (vals) => func((val) => !isNaN(parseInt(val))).match(vals),
-    pattern: '{number}'
-  }
-}
-
-const peerId = (): Matcher => {
-  return {
-    match: (vals) => {
-      if (vals.length < 2) {
-        return false
-      }
-
-      if (vals[0] !== 'p2p' && vals[0] !== 'ipfs') {
-        return false
-      }
-
-      // Q is RSA, 1 is Ed25519 or Secp256k1
-      if (vals[1].startsWith('Q') || vals[1].startsWith('1')) {
-        try {
-          base58btc.decode(`z${vals[1]}`)
-        } catch (err) {
-          return false
-        }
-      } else {
-        return false
-      }
-
-      return vals.slice(2)
-    },
-    pattern: '/p2p/{peerid}'
-  }
-}
-
-const certhash = (): Matcher => {
-  return {
-    match: (vals) => {
-      if (vals.length < 2) {
-        return false
-      }
-
-      if (vals[0] !== 'certhash') {
-        return false
-      }
-
-      try {
-        base64url.decode(vals[1])
-      } catch {
-        return false
-      }
-
-      return vals.slice(2)
-    },
-    pattern: '/certhash/{certhash}'
-  }
-}
-
-const optional = (matcher: Matcher): Matcher => {
-  return {
-    match: (vals) => {
-      const result = matcher.match(vals)
-
-      if (result === false) {
-        return vals
-      }
-
-      return result
-    },
-    pattern: `optional(${matcher.pattern})`
-  }
-}
-
-const or = (...matchers: Matcher[]): Matcher => {
-  return {
-    match: (vals) => {
-      let matches: string[] | undefined
-
-      for (const matcher of matchers) {
-        const result = matcher.match(vals)
-
-        // no match
-        if (result === false) {
-          continue
-        }
-
-        // choose greediest matcher
-        if (matches == null || result.length < matches.length) {
-          matches = result
-        }
-      }
-
-      if (matches == null) {
-        return false
-      }
-
-      return matches
-    },
-    pattern: `or(${matchers.map(m => m.pattern).join(', ')})`
-  }
-}
-
-const and = (...matchers: Matcher[]): Matcher => {
-  return {
-    match: (vals) => {
-      for (const matcher of matchers) {
-        // pass what's left of the array
-        const result = matcher.match(vals)
-
-        // no match
-        if (result === false) {
-          return false
-        }
-
-        vals = result
-      }
-
-      return vals
-    },
-    pattern: `and(${matchers.map(m => m.pattern).join(', ')})`
-  }
-}
-
-function fmt (...matchers: Matcher[]): MultiaddrMatcher {
-  function match (ma: Multiaddr): string[] | false {
-    let parts = toParts(ma)
-
-    for (const matcher of matchers) {
-      const result = matcher.match(parts)
-
-      if (result === false) {
-        return false
-      }
-
-      parts = result
-    }
-
-    return parts
-  }
-
-  function matches (ma: Multiaddr): boolean {
-    const result = match(ma)
-
-    return result !== false
-  }
-
-  function exactMatch (ma: Multiaddr): boolean {
-    const result = match(ma)
-
-    if (result === false) {
-      return false
-    }
-
-    return result.length === 0
-  }
-
-  return {
-    matches,
-    exactMatch
-  }
-}
-
 /**
  * A MultiaddrMatcher allows interpreting a multiaddr as a certain type of
  * multiaddr
  */
 export interface MultiaddrMatcher {
+  /**
+   * The matchers that make up this MultiaddrMatcher - useful if you want to
+   * make your own custom matchers
+   */
+  matchers: Matcher[]
+
   /**
    * Returns true if the passed multiaddr can be treated as this type of
    * multiaddr