feat: combine jsdoc with tsimport

jsdoc-lib.json

@@ -1,5 +1,8 @@
 {
-  "plugins": ["plugins/markdown"],
+  "plugins": [
+    "plugins/markdown",
+    "node_modules/jsdoc-tsimport-plugin"
+  ],
   "source": {
     "include": ["./src", "./README.md"]
   },

package.json

@@ -51,6 +51,7 @@
     "eslint-plugin-promise": "^6.1.1",
     "husky": "^7.0.0",
     "jsdoc": "^4.0.2",
+    "jsdoc-tsimport-plugin": "^1.0.5",
     "license-check-and-add": "^4.0.3",
     "lint-staged": "^11.0.0",
     "minify": "^9.1",

src/asp.js

@@ -13,9 +13,8 @@ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 See the License for the specific language governing permissions and
 limitations under the License.
 */
-import axios, * as axiosMod from 'axios'
+import axios from 'axios'
 import { decodeProtectedHeader, importJWK, compactVerify, calculateJwkThumbprint } from 'jose'
-import * as joseMod from 'jose'
 import { base32, base64url } from 'rfc4648'
 import { Claim } from './claim.js'
 import { Persona } from './persona.js'
@@ -58,12 +57,12 @@ export async function fetchASPE (uri) {
         responseType: 'text'
       }
     )
-      .then((/** @type {axiosMod.AxiosResponse} */ response) => {
+      .then((/** @type {import('axios').AxiosResponse} */ response) => {
         if (response.status === 200) {
           return response
         }
       })
-      .then((/** @type {axiosMod.AxiosResponse} */ response) => response.data)
+      .then((/** @type {import('axios').AxiosResponse} */ response) => response.data)
   } catch (e) {
     throw new Error(`Error fetching Keybase key: ${e.message}`)
   }
@@ -170,9 +169,9 @@ export async function parseProfileJws (profileJws, uri) {
 }
 
 /**
- * Compute the fingerprint for JWK keys
+ * Compute the fingerprint for {@link https://github.com/panva/jose/blob/main/docs/interfaces/types.JWK.md JWK} keys
  * @function
- * @param {joseMod.JWK} key - The JWK public key for which to compute the fingerprint
+ * @param {import('jose').JWK} key - The JWK public key for which to compute the fingerprint
  * @returns {Promise<string>} The computed fingerprint
  */
 export async function computeJwkFingerprint (key) {

src/claim.js

@@ -22,7 +22,6 @@ import { list, data as _data } from './serviceProviders/index.js'
 import { opts as _opts } from './defaults.js'
 import { ClaimStatus } from './enums.js'
 import { ServiceProvider } from './serviceProvider.js'
-import * as Types from './types.js'
 
 /**
  * @class
@@ -217,7 +216,7 @@ export class Claim {
    * regardless of the result.
    * @async
    * @function
-   * @param {Types.VerificationConfig} [opts] - Options for proxy, fetchers
+   * @param {import('./types').VerificationConfig} [opts] - Options for proxy, fetchers
    */
   async verify (opts) {
     if (this._status === ClaimStatus.INIT) {
@@ -245,7 +244,7 @@ export class Claim {
 
       let claimData = this._matches[index]
 
-      /** @type {Types.VerificationResult} */
+      /** @type {import('./types').VerificationResult} */
       let verificationResult = null
       let proofData = null
       let proofFetchError

src/defaults.js

@@ -14,7 +14,6 @@ See the License for the specific language governing permissions and
 limitations under the License.
 */
 import { ProxyPolicy } from './enums.js'
-import * as Types from './types.js'
 
 /**
  * Contains default values
@@ -24,7 +23,7 @@ import * as Types from './types.js'
 /**
  * The default claim verification config used throughout the library
  * @constant
- * @type {Types.VerificationConfig}
+ * @type {import('./types').VerificationConfig}
  */
 export const opts = {
   proxy: {

src/fetcher/activitypub.js

@@ -26,7 +26,6 @@ import isURL from 'validator/lib/isURL.js'
 import { isNode } from 'browser-or-node'
 import crypto from 'crypto'
 import { version } from '../constants.js'
-import * as Types from '../types.js'
 
 /**
  * Default timeout after which the fetch is aborted
@@ -43,7 +42,7 @@ export const timeout = 5000
  * @param {object} data - Data used in the request
  * @param {string} data.url - The URL of the account to verify
  * @param {number} [data.fetcherTimeout] - Optional timeout for the fetcher
- * @param {Types.VerificationConfig} [opts] - Options used to enable the request
+ * @param {import('../types').VerificationConfig} [opts] - Options used to enable the request
  * @returns {Promise<object>} The fetched ActivityPub object
  */
 export async function fn (data, opts) {

src/fetcher/aspe.js

@@ -24,7 +24,6 @@ import axios from 'axios'
 import isFQDN from 'validator/lib/isFQDN.js'
 import { version } from '../constants.js'
 import { parseProfileJws } from '../asp.js'
-import * as Types from '../types.js'
 
 /**
  * Default timeout after which the fetch is aborted
@@ -43,7 +42,7 @@ const reURI = /^aspe:([a-zA-Z0-9.\-_]*):([a-zA-Z0-9]*)/
  * @param {object} data - Data used in the request
  * @param {string} data.aspeUri - ASPE URI of the targeted profile
  * @param {number} [data.fetcherTimeout] - Optional timeout for the fetcher
- * @param {Types.VerificationConfig} [opts] - Options used to enable the request
+ * @param {import('../types').VerificationConfig} [opts] - Options used to enable the request
  * @returns {Promise<object>} The fetched claims from an ASP profile
  */
 export async function fn (data, opts) {

src/fetcher/dns.js

@@ -23,7 +23,6 @@ limitations under the License.
 
 import { isBrowser } from 'browser-or-node'
 import dns from 'dns'
-import * as Types from '../types.js'
 
 /**
  * Default timeout after which the fetch is aborted
@@ -40,7 +39,7 @@ export const timeout = 5000
  * @param {object} data - Data used in the request
  * @param {string} data.domain - The targeted domain
  * @param {number} [data.fetcherTimeout] - Optional timeout for the fetcher
- * @param {Types.VerificationConfig} [opts] - Options used to enable the request
+ * @param {import('../types').VerificationConfig} [opts] - Options used to enable the request
  * @returns {Promise<object>} The fetched DNS records
  */
 export async function fn (data, opts) {

src/fetcher/graphql.js

@@ -23,7 +23,6 @@ limitations under the License.
 
 import axios from 'axios'
 import { version } from '../constants.js'
-import * as Types from '../types.js'
 
 /**
  * Default timeout after which the fetch is aborted
@@ -41,7 +40,7 @@ export const timeout = 5000
  * @param {string} data.url - The URL pointing at the GraphQL HTTP endpoint
  * @param {string} data.query - The GraphQL query to fetch the data containing the proof
  * @param {number} [data.fetcherTimeout] - Optional timeout for the fetcher
- * @param {Types.VerificationConfig} [opts] - Options used to enable the request
+ * @param {import('../types').VerificationConfig} [opts] - Options used to enable the request
  * @returns {Promise<object>} The fetched GraphQL object
  */
 export async function fn (data, opts) {

src/fetcher/http.js

@@ -24,7 +24,6 @@ limitations under the License.
 import axios from 'axios'
 import { ProofFormat } from '../enums.js'
 import { version } from '../constants.js'
-import * as Types from '../types.js'
 
 /**
  * Default timeout after which the fetch is aborted
@@ -42,7 +41,7 @@ export const timeout = 5000
  * @param {string} data.url - The URL pointing at targeted content
  * @param {string} data.format - The format of the targeted content
  * @param {number} [data.fetcherTimeout] - Optional timeout for the fetcher
- * @param {Types.VerificationConfig} [opts] - Options used to enable the request
+ * @param {import('../types').VerificationConfig} [opts] - Options used to enable the request
  * @returns {Promise<object|string>} The fetched JSON object or text
  */
 export async function fn (data, opts) {

src/fetcher/irc.js

@@ -23,7 +23,6 @@ limitations under the License.
 
 import irc from 'irc-upd'
 import isAscii from 'validator/lib/isAscii.js'
-import * as Types from '../types.js'
 
 /**
  * Default timeout after which the fetch is aborted
@@ -41,7 +40,7 @@ export const timeout = 20000
  * @param {string} data.nick - The nick of the targeted account
  * @param {string} data.domain - The domain on which the targeted account is registered
  * @param {number} [data.fetcherTimeout] - Optional timeout for the fetcher
- * @param {Types.VerificationConfig} [opts] - Options used to enable the request
+ * @param {import('../types').VerificationConfig} [opts] - Options used to enable the request
  * @returns {Promise<string[]>} The fetched proofs from an IRC account
  */
 export async function fn (data, opts) {

src/fetcher/matrix.js

@@ -25,7 +25,6 @@ import axios from 'axios'
 import isFQDN from 'validator/lib/isFQDN.js'
 import isAscii from 'validator/lib/isAscii.js'
 import { version } from '../constants.js'
-import * as Types from '../types.js'
 
 /**
  * Default timeout after which the fetch is aborted
@@ -43,7 +42,7 @@ export const timeout = 5000
  * @param {string} data.eventId - The identifier of the targeted post
  * @param {string} data.roomId - The identifier of the room containing the targeted post
  * @param {number} [data.fetcherTimeout] - Optional timeout for the fetcher
- * @param {Types.VerificationConfig} [opts] - Options used to enable the request
+ * @param {import('../types').VerificationConfig} [opts] - Options used to enable the request
  * @returns {Promise<object>} The fetched Matrix object
  */
 export async function fn (data, opts) {

src/fetcher/openpgp.js

@@ -33,7 +33,6 @@ import { readKey } from 'openpgp'
 import { OpenPgpQueryProtocol } from '../enums.js'
 import { version } from '../constants.js'
 import { parsePublicKey } from '../openpgp.js'
-import * as Types from '../types.js'
 
 /**
  * Default timeout after which the fetch is aborted
@@ -51,7 +50,7 @@ export const timeout = 5000
  * @param {string} data.url - The URL pointing at targeted content
  * @param {OpenPgpQueryProtocol} data.protocol - The protocol used to access the targeted content
  * @param {number} [data.fetcherTimeout] - Optional timeout for the fetcher
- * @param {Types.VerificationConfig} [opts] - Options used to enable the request
+ * @param {import('../types').VerificationConfig} [opts] - Options used to enable the request
  * @returns {Promise<object>} The fetched notations from an OpenPGP key
  */
 export async function fn (data, opts) {

src/fetcher/telegram.js

@@ -24,7 +24,6 @@ limitations under the License.
 import axios from 'axios'
 import isAscii from 'validator/lib/isAscii.js'
 import { version } from '../constants.js'
-import * as Types from '../types.js'
 
 /**
  * Default timeout after which the fetch is aborted
@@ -42,7 +41,7 @@ export const timeout = 5000
  * @param {string} data.chat - Telegram public group name (slug)
  * @param {string} data.user - Telegram username
  * @param {number} [data.fetcherTimeout] - Optional timeout for the fetcher
- * @param {Types.VerificationConfig} [opts] - Options used to enable the request
+ * @param {import('../types').VerificationConfig} [opts] - Options used to enable the request
  * @returns {Promise<object|string>} The fetched Telegram object
  */
 export async function fn (data, opts) {

src/fetcher/xmpp.js

@@ -25,7 +25,6 @@ import { client, xml } from '@xmpp/client'
 import debug from '@xmpp/debug'
 import isFQDN from 'validator/lib/isFQDN.js'
 import isAscii from 'validator/lib/isAscii.js'
-import * as Types from '../types.js'
 
 /**
  * Default timeout after which the fetch is aborted
@@ -43,7 +42,7 @@ let iqCaller = null
  * @ignore
  * @function
  * @async
- * @param {Types.XmppClaimVerificationConfig} params - XMPP claim verification config
+ * @param {import('../types').XmppClaimVerificationConfig} params - XMPP claim verification config
  * @returns {Promise<object>} The fetched proofs from an XMPP account
  */
 const xmppStart = async (params) => {
@@ -74,7 +73,7 @@ const xmppStart = async (params) => {
  * @param {object} data - Data used in the request
  * @param {string} data.id - The identifier of the targeted account
  * @param {number} [data.fetcherTimeout] - Optional timeout for the fetcher
- * @param {Types.VerificationConfig} [opts] - Options used to enable the request
+ * @param {import('../types').VerificationConfig} [opts] - Options used to enable the request
  * @returns {Promise<Array<string>>} The fetched proofs from an XMPP account
  */
 export async function fn (data, opts) {

src/index.js

@@ -28,4 +28,3 @@ export * as utils from './utils.js'
 export * as verifications from './verifications.js'
 export * as schemas from './schemas.js'
 export * as fetcher from './fetcher/index.js'
-export * as types from './types.js'

src/openpgp.js

@@ -13,7 +13,7 @@ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 See the License for the specific language governing permissions and
 limitations under the License.
 */
-import axios, * as axiosMod from 'axios'
+import axios from 'axios'
 import { isUri } from 'valid-url'
 import { readKey, PublicKey } from 'openpgp'
 import HKP from '@openpgp/hkp-client'
@@ -128,12 +128,12 @@ export async function fetchKeybase (username, fingerprint) {
         responseType: 'text'
       }
     )
-      .then((/** @type {axiosMod.AxiosResponse} */ response) => {
+      .then((/** @type {import('axios').AxiosResponse} */ response) => {
         if (response.status === 200) {
           return response
         }
       })
-      .then((/** @type {axiosMod.AxiosResponse} */ response) => response.data)
+      .then((/** @type {import('axios').AxiosResponse} */ response) => response.data)
   } catch (e) {
     throw new Error(`Error fetching Keybase key: ${e.message}`)
   }

src/profile.js

@@ -15,7 +15,6 @@ limitations under the License.
 */
 import { PublicKeyFetchMethod, PublicKeyEncoding, PublicKeyType, ProfileType } from './enums.js'
 import { Persona } from './persona.js'
-import * as Types from './types.js'
 
 /**
  * @class
@@ -64,7 +63,7 @@ export class Profile {
     this.primaryPersonaIndex = personas.length > 0 ? 0 : -1
     /**
      * The cryptographic key associated with the profile
-     * @type {Types.ProfilePublicKey}
+     * @type {import('./types').ProfilePublicKey}
      * @public
      */
     this.publicKey = {
@@ -81,7 +80,7 @@ export class Profile {
     }
     /**
      * List of verifier URLs
-     * @type {Types.ProfileVerifier[]}
+     * @type {import('./types').ProfileVerifier[]}
      * @public
      */
     this.verifiers = []

src/proofs.js

@@ -18,7 +18,6 @@ import { fetcher } from './index.js'
 import { generateProxyURL } from './utils.js'
 import { ProxyPolicy, ProofAccessRestriction } from './enums.js'
 import { ServiceProvider } from './serviceProvider.js'
-import * as Types from './types.js'
 
 /**
  * @module proofs
@@ -32,7 +31,7 @@ import * as Types from './types.js'
  * approach is possible.
  * @async
  * @param {ServiceProvider} data - Data from a claim definition
- * @param {Types.VerificationConfig} opts - Options to enable the request
+ * @param {import('./types').VerificationConfig} opts - Options to enable the request
  * @returns {Promise<object|string>} Fetched proof data
  */
 export async function fetch (data, opts) {

src/serviceProvider.js

@@ -13,7 +13,6 @@ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 See the License for the specific language governing permissions and
 limitations under the License.
 */
-import * as Types from './types.js'
 
 /**
  * A service provider matched to an identity claim
@@ -22,27 +21,27 @@ import * as Types from './types.js'
  */
 export class ServiceProvider {
   /**
-   * @param {Types.ServiceProviderObject} serviceProviderObject - JSON representation of a {@link ServiceProvider}
+   * @param {import('./types').ServiceProviderObject} serviceProviderObject - JSON representation of a {@link ServiceProvider}
    */
   constructor (serviceProviderObject) {
     /**
      * Details about the service provider
-     * @type {Types.ServiceProviderAbout}
+     * @type {import('./types').ServiceProviderAbout}
      */
     this.about = serviceProviderObject.about
     /**
      * What the profile would look like if a claim matches this service provider
-     * @type {Types.ServiceProviderProfile}
+     * @type {import('./types').ServiceProviderProfile}
      */
     this.profile = serviceProviderObject.profile
     /**
      * Information about the claim matching process
-     * @type {Types.ServiceProviderClaim}
+     * @type {import('./types').ServiceProviderClaim}
      */
     this.claim = serviceProviderObject.claim
     /**
      * Information for the proof verification process
-     * @type {Types.ServiceProviderProof}
+     * @type {import('./types').ServiceProviderProof}
      */
     this.proof = serviceProviderObject.proof
   }
@@ -50,7 +49,7 @@ export class ServiceProvider {
   /**
    * Get a JSON representation of the {@link ServiceProvider}
    * @function
-   * @returns {Types.ServiceProviderObject} JSON representation of a {@link ServiceProvider}
+   * @returns {import('./types').ServiceProviderObject} JSON representation of a {@link ServiceProvider}
    */
   toJSON () {
     return {

src/types.js

@@ -18,9 +18,7 @@ limitations under the License.
  * @module types
  */
 
-import { PublicKey } from 'openpgp'
+import { PublicKeyType, PublicKeyEncoding, PublicKeyFetchMethod, ProxyPolicy, ClaimFormat, EntityEncodingFormat, ClaimRelation, ProofAccessRestriction, ProofFormat } from './enums'
-import * as joseMod from 'jose'
-import { ClaimFormat, ClaimRelation, EntityEncodingFormat, ProofAccessRestriction, ProofFormat, ProxyPolicy, PublicKeyEncoding, PublicKeyFetchMethod, PublicKeyType } from './enums.js'
 
 /**
  * Service provider
@@ -84,7 +82,7 @@ import { ClaimFormat, ClaimRelation, EntityEncodingFormat, ProofAccessRestrictio
  * @property {PublicKeyEncoding} encoding - The encoding of the cryptographic key
  * @property {string} [fingerprint] - The fingerprint of the cryptographic key
  * @property {string} [encodedKey] - The encoded cryptographic key
- * @property {PublicKey | joseMod.JWK} [key] - The raw cryptographic key as object (to be removed during toJSON())
+ * @property {import('openpgp').PublicKey | import('jose').JWK} [key] - The raw cryptographic key as object (to be removed during toJSON())
  * @property {ProfilePublicKeyFetch} fetch - Details on how to fetch the public key
  */
 
@@ -108,7 +106,7 @@ import { ClaimFormat, ClaimRelation, EntityEncodingFormat, ProofAccessRestrictio
  * @typedef {object} ProxyVerificationConfig
  * @property {string} [scheme] - The scheme to use for proxy requests
  * @property {string} [hostname] - The hostname of the proxy
- * @property {ProxyPolicy} policy - The policy that defines when to use a proxy ({@link module:enums~ProxyPolicy|here})
+ * @property {ProxyPolicy} policy - The policy that defines when to use a proxy
  */
 
 /**

src/utils.js

@@ -15,7 +15,6 @@ limitations under the License.
 */
 import isFQDN from 'validator/lib/isFQDN.js'
 import { ClaimFormat } from './enums.js'
-import * as Types from './types.js'
 
 /**
  * @module utils
@@ -25,7 +24,7 @@ import * as Types from './types.js'
  * Generate an URL to request data from a proxy server
  * @param {string} type - The name of the fetcher the proxy must use
  * @param {object} data - The data the proxy must provide to the fetcher
- * @param {Types.VerificationConfig} opts - Options to enable the request
+ * @param {import('./types').VerificationConfig} opts - Options to enable the request
  * @returns {string} Generated proxy URL
  */
 export function generateProxyURL (type, data, opts) {
@@ -51,7 +50,7 @@ export function generateProxyURL (type, data, opts) {
 /**
  * Generate the string that must be found in the proof to verify a claim
  * @param {string} fingerprint - The fingerprint of the claim
- * @param {ClaimFormat} format - The claim's format (see {@link ClaimFormat})
+ * @param {ClaimFormat} format - The claim's format
  * @returns {string} Generate claim
  */
 export function generateClaim (fingerprint, format) {

src/verifications.js

@@ -18,7 +18,6 @@ import { ClaimFormat, EntityEncodingFormat, ClaimRelation, ProofFormat } from '.
 import { bcryptVerify, argon2Verify } from 'hash-wasm'
 import { decodeHTML, decodeXML } from 'entities'
 import { ServiceProvider } from './serviceProvider.js'
-import * as Types from './types.js'
 
 /**
  * @module verifications
@@ -29,7 +28,7 @@ import * as Types from './types.js'
  * Check if string contains the proof
  * @function
  * @param {string} data - Data potentially containing the proof
- * @param {Types.VerificationParams} params - Verification parameters
+ * @param {import('./types').VerificationParams} params - Verification parameters
  * @returns {Promise<boolean>} Whether the proof was found in the string
  */
 const containsProof = async (data, params) => {
@@ -218,7 +217,7 @@ const containsProof = async (data, params) => {
  * @function
  * @param {any} proofData - Data potentially containing the proof
  * @param {string[]} checkPath - Paths to check for proof
- * @param {Types.VerificationParams} params - Verification parameters
+ * @param {import('./types').VerificationParams} params - Verification parameters
  * @returns {Promise<boolean>} Whether the proof was found in the object
  */
 const runJSON = async (proofData, checkPath, params) => {
@@ -271,10 +270,10 @@ const runJSON = async (proofData, checkPath, params) => {
  * @param {object} proofData - The proof data
  * @param {ServiceProvider} claimData - The claim data
  * @param {string} fingerprint - The fingerprint
- * @returns {Promise<Types.VerificationResult>} Result of the verification
+ * @returns {Promise<import('./types').VerificationResult>} Result of the verification
  */
 export async function run (proofData, claimData, fingerprint) {
-  /** @type {Types.VerificationResult} */
+  /** @type {import('./types').VerificationResult} */
   const res = {
     result: false,
     completed: false,

yarn.lock

@@ -2834,6 +2834,11 @@ js2xmlparser@^4.0.2:
   dependencies:
     xmlcreate "^2.0.4"
 
+jsdoc-tsimport-plugin@^1.0.5:
+  version "1.0.5"
+  resolved "https://registry.yarnpkg.com/jsdoc-tsimport-plugin/-/jsdoc-tsimport-plugin-1.0.5.tgz#a329f48a01c307747931cca81aa856f51bf49c26"
+  integrity sha512-6mvyF+tXdanf3zxEumTF9Uf/sXGlANP+XohSuiJiOVVWPGxi+3f2a2sy5Ew3W+0PMYUkcGYNxfYd5mMZsIHQpg==
+
 jsdoc-type-pratt-parser@~4.0.0:
   version "4.0.0"
   resolved "https://registry.yarnpkg.com/jsdoc-type-pratt-parser/-/jsdoc-type-pratt-parser-4.0.0.tgz#136f0571a99c184d84ec84662c45c29ceff71114"