chore: add more types and fix function's comments

src/codec.ts

@@ -3,7 +3,7 @@ import { toString as uint8ArrayToString } from 'uint8arrays/to-string'
 import varint from 'varint'
 import { convertToBytes, convertToString } from './convert.js'
 import { getProtocol } from './protocols-table.js'
-import type { StringTuple, Tuple, Protocol } from './index.js'
+import type { StringTuple, Tuple, Protocol, MultiaddrInputString, MultiaddrInputStringResult } from './index.js'
 
 /**
  * string -> [[str name, str addr]... ]
@@ -66,9 +66,10 @@ export function stringTuplesToString (tuples: StringTuple[]): string {
 }
 
 /**
- * [[str name, str addr]... ] -> [[int code, Uint8Array]... ]
+ * [[str name, str addr]... ] -> {tuples: [[int code, Uint8Array]... ], path: str}
+ * The logic to get path is the same to DefaultMultiaddr.getPath()
  */
-export function stringTuplesToTuples (stringTuples: Array<string[] | string>): { tuples: Tuple[], path: string | null } {
+export function stringTuplesToTuples (stringTuples: Array<string[] | string>): Omit<MultiaddrInputStringResult, 'bytes'> {
   let path: string | null | undefined
   const tuples = stringTuples.map((tup) => {
     if (!Array.isArray(tup)) {
@@ -177,9 +178,9 @@ export function bytesToString (buf: Uint8Array): string {
 }
 
 /**
- * String -> Uint8Array
+ * MultiaddrInputString -> MultiaddrInputStringResult
  */
-export function stringToBytes (str: string): { bytes: Uint8Array, tuples: Tuple[], path: string | null } {
+export function parseMultiaddrInputString (str: MultiaddrInputString): MultiaddrInputStringResult {
   str = cleanPath(str)
   const stringTuples = stringToStringTuples(str)
   const { tuples, path } = stringTuplesToTuples(stringTuples)
@@ -188,10 +189,10 @@ export function stringToBytes (str: string): { bytes: Uint8Array, tuples: Tuple[
 }
 
 /**
- * String -> Uint8Array
+ * MultiaddrInputString -> MultiaddrInputStringResult
  */
-export function fromString (str: string): { bytes: Uint8Array, tuples: Tuple[], path: string | null } {
-  return stringToBytes(str)
+export function fromMultiaddrInputString (str: MultiaddrInputString): MultiaddrInputStringResult {
+  return parseMultiaddrInputString(str)
 }
 
 /**

src/index.ts

@@ -60,10 +60,15 @@ export interface NodeAddress {
   port: number
 }
 
+/**
+ * Represent a multiaaddr input string
+ */
+export type MultiaddrInputString = string
+
 /**
  * These types can be parsed into a {@link Multiaddr} object
  */
-export type MultiaddrInput = string | Multiaddr | Uint8Array | null
+export type MultiaddrInput = MultiaddrInputString | Multiaddr | Uint8Array | null
 
 /**
  * A Resolver is a function that takes a {@link Multiaddr} and resolves it into one
@@ -81,6 +86,13 @@ export type Tuple = [number, Uint8Array?]
  */
 export type StringTuple = [number, string?]
 
+/** The result of parsing a MultiaddrInput string */
+export interface MultiaddrInputStringResult {
+  bytes: Uint8Array
+  tuples: Tuple[]
+  path: string | null
+}
+
 /**
  * Allows aborting long-lived operations
  */
@@ -513,7 +525,7 @@ class DefaultMultiaddr implements Multiaddr {
       if (addr.length > 0 && addr.charAt(0) !== '/') {
         throw new Error(`multiaddr "${addr}" must start with a "/"`)
       }
-      const { bytes, tuples, path } = codec.fromString(addr)
+      const { bytes, tuples, path } = codec.fromMultiaddrInputString(addr)
       this.bytes = bytes
       this.#tuples = tuples
       this.#path = path

test/codec.spec.ts

@@ -19,7 +19,8 @@ describe('codec', () => {
   describe('.stringTuplesToTuples', () => {
     const testCases: Array<{ name: string, stringTuples: Array<string[] | string>, tuples: Array<[number, Uint8Array?]>, path: string | null }> = [
       { name: 'handles non array tuples', stringTuples: [['ip4', '0.0.0.0'], 'utp'], tuples: [[4, Uint8Array.from([0, 0, 0, 0])], [302]], path: null },
-      { name: 'handle not null path', stringTuples: [['unix', '/tmp/p2p.sock']], tuples: [[400, convertToBytes(400, '/tmp/p2p.sock')]], path: '/tmp/p2p.sock' }
+      { name: 'handle not null path', stringTuples: [['unix', '/tmp/p2p.sock']], tuples: [[400, convertToBytes(400, '/tmp/p2p.sock')]], path: '/tmp/p2p.sock' },
+      { name: 'should return the 1st path', stringTuples: [['unix', '/tmp/p2p.sock'], ['unix', '/tmp2/p2p.sock']], tuples: [[400, convertToBytes(400, '/tmp/p2p.sock')], [400, convertToBytes(400, '/tmp2/p2p.sock')]], path: '/tmp/p2p.sock' }
     ]
 
     for (const { name, stringTuples, tuples, path } of testCases) {