Skip to content

Commit

Permalink
docs: publish API docs to github pages on release (#289)
Browse files Browse the repository at this point in the history 
Updates JSDoc comments and configures GH actions to publish docs to gh-pages branch on every release.
  • Loading branch information
@achingbrain
achingbrain authored Dec 7, 2022
1 parent 86e4293 commit c22e55f
Show file tree
Hide file tree
Showing 7 changed files with 226 additions and 91 deletions.
3 changes: 3 additions & 0 deletions .github/workflows/js-test-and-release.yml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -140,6 +140,9 @@ jobs:
with:
docker-token: ${{ secrets.DOCKER_TOKEN }}
docker-username: ${{ secrets.DOCKER_USERNAME }}
- run: npm run --if-present docs
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
- run: npm run --if-present release
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
Expand Down
5 changes: 3 additions & 2 deletions package.json
View file
Original file line number Diff line number Diff line change
Expand Up @@ -161,7 +161,8 @@
"test:firefox-webworker": "aegir test -t webworker -- --browser firefox",
"test:node": "aegir test -t node --cov",
"test:electron-main": "aegir test -t electron-main",
"release": "aegir release"
"release": "aegir release",
"docs": "aegir docs"
},
"dependencies": {
"@chainsafe/is-ip": "^2.0.1",
Expand All @@ -173,7 +174,7 @@
},
"devDependencies": {
"@types/varint": "^6.0.0",
"aegir": "^37.4.5",
"aegir": "^37.6.2",
"sinon": "^15.0.0",
"util": "^0.12.3"
},
Expand Down
30 changes: 16 additions & 14 deletions src/codec.ts
View file
Original file line number Diff line number Diff line change
Expand Up @@ -3,13 +3,12 @@ import { getProtocol } from './protocols-table.js'
import varint from 'varint'
import { concat as uint8ArrayConcat } from 'uint8arrays/concat'
import { toString as uint8ArrayToString } from 'uint8arrays/to-string'
import type { Protocol } from './protocols-table.js'
import type { StringTuple, Tuple } from './index.js'
import type { StringTuple, Tuple, Protocol } from './index.js'

/**
* string -> [[str name, str addr]... ]
*/
export function stringToStringTuples (str: string) {
export function stringToStringTuples (str: string): string[][] {
const tuples = []
const parts = str.split('/').slice(1) // skip first empty elem
if (parts.length === 1 && parts[0] === '') {
Expand Down Expand Up @@ -51,7 +50,7 @@ export function stringToStringTuples (str: string) {
/**
* [[str name, str addr]... ] -> string
*/
export function stringTuplesToString (tuples: StringTuple[]) {
export function stringTuplesToString (tuples: StringTuple[]): string {
const parts: string[] = []
tuples.map((tup) => {
const proto = protoFromTuple(tup)
Expand Down Expand Up @@ -99,7 +98,7 @@ export function tuplesToStringTuples (tuples: Tuple[]): StringTuple[] {
/**
* [[int code, Uint8Array ]... ] -> Uint8Array
*/
export function tuplesToBytes (tuples: Tuple[]) {
export function tuplesToBytes (tuples: Tuple[]): Uint8Array {
return fromBytes(uint8ArrayConcat(tuples.map((tup) => {
const proto = protoFromTuple(tup)
let buf = Uint8Array.from(varint.encode(proto.code))
Expand All @@ -112,7 +111,10 @@ export function tuplesToBytes (tuples: Tuple[]) {
})))
}

export function sizeForAddr (p: Protocol, addr: Uint8Array | number[]) {
/**
* For the passed address, return the serialized size
*/
export function sizeForAddr (p: Protocol, addr: Uint8Array | number[]): number {
if (p.size > 0) {
return p.size / 8
} else if (p.size === 0) {
Expand Down Expand Up @@ -158,7 +160,7 @@ export function bytesToTuples (buf: Uint8Array): Tuple[] {
/**
* Uint8Array -> String
*/
export function bytesToString (buf: Uint8Array) {
export function bytesToString (buf: Uint8Array): string {
const a = bytesToTuples(buf)
const b = tuplesToStringTuples(a)
return stringTuplesToString(b)
Expand All @@ -167,7 +169,7 @@ export function bytesToString (buf: Uint8Array) {
/**
* String -> Uint8Array
*/
export function stringToBytes (str: string) {
export function stringToBytes (str: string): Uint8Array {
str = cleanPath(str)
const a = stringToStringTuples(str)
const b = stringTuplesToTuples(a)
Expand All @@ -178,14 +180,14 @@ export function stringToBytes (str: string) {
/**
* String -> Uint8Array
*/
export function fromString (str: string) {
export function fromString (str: string): Uint8Array {
return stringToBytes(str)
}

/**
* Uint8Array -> Uint8Array
*/
export function fromBytes (buf: Uint8Array) {
export function fromBytes (buf: Uint8Array): Uint8Array {
const err = validateBytes(buf)
if (err != null) {
throw err
Expand All @@ -201,19 +203,19 @@ export function validateBytes (buf: Uint8Array): Error | undefined {
}
}

export function isValidBytes (buf: Uint8Array) {
export function isValidBytes (buf: Uint8Array): boolean {
return validateBytes(buf) === undefined
}

export function cleanPath (str: string) {
export function cleanPath (str: string): string {
return '/' + str.trim().split('/').filter((a) => a).join('/')
}

export function ParseError (str: string) {
export function ParseError (str: string): Error {
return new Error('Error parsing address: ' + str)
}

export function protoFromTuple (tup: any[]) {
export function protoFromTuple (tup: any[]): Protocol {
const proto = getProtocol(tup[0])
return proto
}
37 changes: 22 additions & 15 deletions src/convert.ts
View file
Original file line number Diff line number Diff line change
@@ -1,3 +1,8 @@
/**
* @packageDocumentation
*
* Provides methods for converting
*/

import * as ip from './ip.js'
import { getProtocol } from './protocols-table.js'
Expand All @@ -14,7 +19,9 @@ import { concat as uint8ArrayConcat } from 'uint8arrays/concat'
/**
* converts (serializes) addresses
*/
export function convert (proto: string, a: string | Uint8Array) {
export function convert (proto: string, a: string): Uint8Array
export function convert (proto: string, a: Uint8Array): string
export function convert (proto: string, a: string | Uint8Array): Uint8Array | string {
if (a instanceof Uint8Array) {
return convertToString(proto, a)
} else {
Expand All @@ -25,7 +32,7 @@ export function convert (proto: string, a: string | Uint8Array) {
/**
* Convert [code,Uint8Array] to string
*/
export function convertToString (proto: number | string, buf: Uint8Array) {
export function convertToString (proto: number | string, buf: Uint8Array): string {
const protocol = getProtocol(proto)
switch (protocol.code) {
case 4: // ipv4
Expand Down Expand Up @@ -59,7 +66,7 @@ export function convertToString (proto: number | string, buf: Uint8Array) {
}
}

export function convertToBytes (proto: string | number, str: string) {
export function convertToBytes (proto: string | number, str: string): Uint8Array {
const protocol = getProtocol(proto)
switch (protocol.code) {
case 4: // ipv4
Expand Down Expand Up @@ -101,14 +108,14 @@ const anybaseDecoder = (function () {
return acc
})()

function ip2bytes (ipString: string) {
function ip2bytes (ipString: string): Uint8Array {
if (!ip.isIP(ipString)) {
throw new Error('invalid ip address')
}
return ip.toBytes(ipString)
}

function bytes2ip (ipBuff: Uint8Array) {
function bytes2ip (ipBuff: Uint8Array): string {
const ipString = ip.toString(ipBuff, 0, ipBuff.length)
if (ipString == null) {
throw new Error('ipBuff is required')
Expand All @@ -119,26 +126,26 @@ function bytes2ip (ipBuff: Uint8Array) {
return ipString
}

function port2bytes (port: number) {
function port2bytes (port: number): Uint8Array {
const buf = new ArrayBuffer(2)
const view = new DataView(buf)
view.setUint16(0, port)

return new Uint8Array(buf)
}

function bytes2port (buf: Uint8Array) {
function bytes2port (buf: Uint8Array): number {
const view = new DataView(buf.buffer)
return view.getUint16(buf.byteOffset)
}

function str2bytes (str: string) {
function str2bytes (str: string): Uint8Array {
const buf = uint8ArrayFromString(str)
const size = Uint8Array.from(varint.encode(buf.length))
return uint8ArrayConcat([size, buf], size.length + buf.length)
}

function bytes2str (buf: Uint8Array) {
function bytes2str (buf: Uint8Array): string {
const size = varint.decode(buf)
buf = buf.slice(varint.decode.bytes)

Expand All @@ -149,7 +156,7 @@ function bytes2str (buf: Uint8Array) {
return uint8ArrayToString(buf)
}

function mh2bytes (hash: string) {
function mh2bytes (hash: string): Uint8Array {
let mh

if (hash[0] === 'Q' || hash[0] === '1') {
Expand All @@ -163,7 +170,7 @@ function mh2bytes (hash: string) {
return uint8ArrayConcat([size, mh], size.length + mh.length)
}

function mb2bytes (mbstr: string) {
function mb2bytes (mbstr: string): Uint8Array {
const mb = anybaseDecoder.decode(mbstr)
const size = Uint8Array.from(varint.encode(mb.length))
return uint8ArrayConcat([size, mb], size.length + mb.length)
Expand All @@ -182,7 +189,7 @@ function bytes2mb (buf: Uint8Array) {
/**
* Converts bytes to bas58btc string
*/
function bytes2mh (buf: Uint8Array) {
function bytes2mh (buf: Uint8Array): string {
const size = varint.decode(buf)
const address = buf.slice(varint.decode.bytes)

Expand All @@ -193,7 +200,7 @@ function bytes2mh (buf: Uint8Array) {
return uint8ArrayToString(address, 'base58btc')
}

function onion2bytes (str: string) {
function onion2bytes (str: string): Uint8Array {
const addr = str.split(':')
if (addr.length !== 2) {
throw new Error(`failed to parse onion addr: ["'${addr.join('", "')}'"]' does not contain a port number`)
Expand All @@ -214,7 +221,7 @@ function onion2bytes (str: string) {
return uint8ArrayConcat([buf, portBuf], buf.length + portBuf.length)
}

function onion32bytes (str: string) {
function onion32bytes (str: string): Uint8Array {
const addr = str.split(':')
if (addr.length !== 2) {
throw new Error(`failed to parse onion addr: ["'${addr.join('", "')}'"]' does not contain a port number`)
Expand All @@ -234,7 +241,7 @@ function onion32bytes (str: string) {
return uint8ArrayConcat([buf, portBuf], buf.length + portBuf.length)
}

function bytes2onion (buf: Uint8Array) {
function bytes2onion (buf: Uint8Array): string {
const addrBytes = buf.slice(0, buf.length - 2)
const portBytes = buf.slice(buf.length - 2)
const addr = uint8ArrayToString(addrBytes, 'base32')
Expand Down
Loading

0 comments on commit c22e55f

Please sign in to comment.