chore: add default option extentions (#3965)

We can extend options passed to the core-api by defining an extension
object, this is so we can pass http options to the http api client
but still get type safety.

We define a default extension type of `{}` so we don't need to define
the extension in places we aren't extending it (e.g. ipfs-core).

Problem is, JSDoc doesn't pick up the default extension object so we
need to add it to the function definitions.

Refs: #3917 (comment)

packages/ipfs-cli/src/commands/get.js

@@ -43,7 +43,7 @@ export default {
     compressionLevel: {
       alias: ['l', 'compression-level'],
       type: 'number',
-      desc: 'The level of compression (1-9)',
+      desc: 'The level of compression (-1-9)',
       default: 6
     }
   },
@@ -57,7 +57,7 @@ export default {
    * @param {number} argv.timeout
    * @param {boolean} argv.archive
    * @param {boolean} argv.compress
-   * @param {number} argv.compressionLevel
+   * @param {-1 | 0 | 1 | 2 | 3 | 4 | 5 | 6| 7 | 8| 9} argv.compressionLevel
    */
   async handler ({ ctx: { ipfs, print }, ipfsPath, output, force, timeout, archive, compress, compressionLevel }) {
     print(`Saving file(s) ${stripControlCharacters(ipfsPath)}`)

packages/ipfs-core-config/src/init-assets.js

@@ -5,7 +5,7 @@ import assets from './init-files/init-docs/index.js'
  * Add the default assets to the repo.
  *
  * @param {object} arg
- * @param {import('ipfs-core-types/src/root').API["addAll"]} arg.addAll
+ * @param {import('ipfs-core-types/src/root').API<{}>["addAll"]} arg.addAll
  * @param {(msg: string) => void} arg.print
  */
 export async function initAssets ({ addAll, print }) {

packages/ipfs-core-types/src/root.ts

@@ -259,7 +259,7 @@ export interface CatOptions extends AbortOptions, PreloadOptions {
 export interface GetOptions extends AbortOptions, PreloadOptions {
   archive?: boolean
   compress?: boolean
-  compressionLevel?: number
+  compressionLevel?: -1 | 0 | 1 | 2 | 3 | 4 | 5 | 6| 7 | 8| 9
 }
 
 export interface ListOptions extends AbortOptions, PreloadOptions {

packages/ipfs-core/src/components/add-all/index.js

@@ -22,7 +22,7 @@ export function createAddAll ({ repo, preload, options }) {
   const isShardingEnabled = options && options.sharding
 
   /**
-   * @type {import('ipfs-core-types/src/root').API["addAll"]}
+   * @type {import('ipfs-core-types/src/root').API<{}>["addAll"]}
    */
   async function * addAll (source, options = {}) {
     const opts = mergeOptions({

packages/ipfs-core/src/components/add.js

@@ -3,11 +3,11 @@ import { normaliseInput } from 'ipfs-core-utils/files/normalise-input-single'
 
 /**
  * @param {Object} context
- * @param {import('ipfs-core-types/src/root').API["addAll"]} context.addAll
+ * @param {import('ipfs-core-types/src/root').API<{}>["addAll"]} context.addAll
  */
 export function createAdd ({ addAll }) {
   /**
-   * @type {import('ipfs-core-types/src/root').API["add"]}
+   * @type {import('ipfs-core-types/src/root').API<{}>["add"]}
    */
   async function add (entry, options = {}) {
     // @ts-ignore TODO: https://github.com/ipfs/js-ipfs/issues/3290

packages/ipfs-core/src/components/bitswap/stat.js

@@ -6,7 +6,7 @@ import { withTimeoutOption } from 'ipfs-core-utils/with-timeout-option'
  */
 export function createStat ({ network }) {
   /**
-   * @type {import('ipfs-core-types/src/bitswap').API["stat"]}
+   * @type {import('ipfs-core-types/src/bitswap').API<{}>["stat"]}
    */
   async function stat (options = {}) {
     /** @type {import('ipfs-bitswap').IPFSBitswap} */

packages/ipfs-core/src/components/bitswap/unwant.js

@@ -6,7 +6,7 @@ import { withTimeoutOption } from 'ipfs-core-utils/with-timeout-option'
  */
 export function createUnwant ({ network }) {
   /**
-   * @type {import('ipfs-core-types/src/bitswap').API["unwant"]}
+   * @type {import('ipfs-core-types/src/bitswap').API<{}>["unwant"]}
    */
   async function unwant (cids, options = {}) {
     const { bitswap } = await network.use(options)

packages/ipfs-core/src/components/bitswap/wantlist-for-peer.js

@@ -7,7 +7,7 @@ import { withTimeoutOption } from 'ipfs-core-utils/with-timeout-option'
  */
 export function createWantlistForPeer ({ network }) {
   /**
-   * @type {import('ipfs-core-types/src/bitswap').API["wantlistForPeer"]}
+   * @type {import('ipfs-core-types/src/bitswap').API<{}>["wantlistForPeer"]}
    */
   async function wantlistForPeer (peerId, options = {}) {
     const { bitswap } = await network.use(options)

packages/ipfs-core/src/components/bitswap/wantlist.js

@@ -6,7 +6,7 @@ import { withTimeoutOption } from 'ipfs-core-utils/with-timeout-option'
  */
 export function createWantlist ({ network }) {
   /**
-   * @type {import('ipfs-core-types/src/bitswap').API["wantlist"]}
+   * @type {import('ipfs-core-types/src/bitswap').API<{}>["wantlist"]}
    */
   async function wantlist (options = {}) {
     const { bitswap } = await network.use(options)

packages/ipfs-core/src/components/block/get.js

@@ -7,7 +7,7 @@ import { withTimeoutOption } from 'ipfs-core-utils/with-timeout-option'
  */
 export function createGet ({ preload, repo }) {
   /**
-   * @type {import('ipfs-core-types/src/block').API["get"]}
+   * @type {import('ipfs-core-types/src/block').API<{}>["get"]}
    */
   async function get (cid, options = {}) { // eslint-disable-line require-await
     if (options.preload !== false) {

packages/ipfs-core/src/components/block/put.js

@@ -15,7 +15,7 @@ import { withTimeoutOption } from 'ipfs-core-utils/with-timeout-option'
  */
 export function createPut ({ codecs, hashers, repo, preload }) {
   /**
-   * @type {import('ipfs-core-types/src/block').API["put"]}
+   * @type {import('ipfs-core-types/src/block').API<{}>["put"]}
    */
   async function put (block, options = {}) {
     const release = options.pin ? await repo.gcLock.readLock() : null

packages/ipfs-core/src/components/block/rm.js

@@ -14,7 +14,7 @@ const BLOCK_RM_CONCURRENCY = 8
  */
 export function createRm ({ repo }) {
   /**
-   * @type {import('ipfs-core-types/src/block').API["rm"]}
+   * @type {import('ipfs-core-types/src/block').API<{}>["rm"]}
    */
   async function * rm (cids, options = {}) {
     if (!Array.isArray(cids)) {

packages/ipfs-core/src/components/block/stat.js

@@ -9,7 +9,7 @@ import { withTimeoutOption } from 'ipfs-core-utils/with-timeout-option'
 
 export function createStat ({ repo, preload }) {
   /**
-   * @type {import('ipfs-core-types/src/block').API["stat"]}
+   * @type {import('ipfs-core-types/src/block').API<{}>["stat"]}
    */
   async function stat (cid, options = {}) {
     cid = cleanCid(cid)

packages/ipfs-core/src/components/bootstrap/add.js

@@ -7,7 +7,7 @@ import { withTimeoutOption } from 'ipfs-core-utils/with-timeout-option'
  */
 export function createAdd ({ repo }) {
   /**
-   * @type {import('ipfs-core-types/src/bootstrap').API["add"]}
+   * @type {import('ipfs-core-types/src/bootstrap').API<{}>["add"]}
    */
   async function add (multiaddr, options = {}) {
     if (!isValidMultiaddr(multiaddr)) {

packages/ipfs-core/src/components/bootstrap/clear.js

@@ -7,7 +7,7 @@ import { Multiaddr } from 'multiaddr'
  */
 export function createClear ({ repo }) {
   /**
-   * @type {import('ipfs-core-types/src/bootstrap').API["clear"]}
+   * @type {import('ipfs-core-types/src/bootstrap').API<{}>["clear"]}
    */
   async function clear (options = {}) {
     /** @type {import('ipfs-core-types/src/config').Config} */

packages/ipfs-core/src/components/bootstrap/list.js

@@ -7,7 +7,7 @@ import { Multiaddr } from 'multiaddr'
  */
 export function createList ({ repo }) {
   /**
-   * @type {import('ipfs-core-types/src/bootstrap').API["list"]}
+   * @type {import('ipfs-core-types/src/bootstrap').API<{}>["list"]}
    */
   async function list (options = {}) {
     /** @type {string[]|null} */

packages/ipfs-core/src/components/bootstrap/reset.js

@@ -8,7 +8,7 @@ import { Multiaddr } from 'multiaddr'
  */
 export function createReset ({ repo }) {
   /**
-   * @type {import('ipfs-core-types/src/bootstrap').API["reset"]}
+   * @type {import('ipfs-core-types/src/bootstrap').API<{}>["reset"]}
    */
   async function reset (options = {}) {
     /** @type {import('ipfs-core-types/src/config').Config} */

packages/ipfs-core/src/components/bootstrap/rm.js

@@ -7,7 +7,7 @@ import { withTimeoutOption } from 'ipfs-core-utils/with-timeout-option'
  */
 export function createRm ({ repo }) {
   /**
-   * @type {import('ipfs-core-types/src/bootstrap').API["rm"]}
+   * @type {import('ipfs-core-types/src/bootstrap').API<{}>["rm"]}
    */
   async function rm (multiaddr, options = {}) {
     if (!isValidMultiaddr(multiaddr)) {

packages/ipfs-core/src/components/cat.js

@@ -12,7 +12,7 @@ import { CID } from 'multiformats/cid'
  */
 export function createCat ({ repo, preload }) {
   /**
-   * @type {import('ipfs-core-types/src/root').API["cat"]}
+   * @type {import('ipfs-core-types/src/root').API<{}>["cat"]}
    */
   async function * cat (ipfsPath, options = {}) {
     ipfsPath = normalizeCidPath(ipfsPath)

packages/ipfs-core/src/components/config/index.js

@@ -21,15 +21,15 @@ export function createConfig ({ repo }) {
   }
 
   /**
-   * @type {import('ipfs-core-types/src/config').API["getAll"]}
+   * @type {import('ipfs-core-types/src/config').API<{}>["getAll"]}
    */
   async function getAll (options = {}) { // eslint-disable-line require-await
     // @ts-ignore TODO: move config typedefs into ipfs-repo
     return repo.config.getAll(options)
   }
 
   /**
-   * @type {import('ipfs-core-types/src/config').API["get"]}
+   * @type {import('ipfs-core-types/src/config').API<{}>["get"]}
    */
   async function get (key, options) { // eslint-disable-line require-await
     if (!key) {
@@ -41,21 +41,21 @@ export function createConfig ({ repo }) {
   }
 
   /**
-   * @type {import('ipfs-core-types/src/config').API["set"]}
+   * @type {import('ipfs-core-types/src/config').API<{}>["set"]}
    */
   async function set (key, value, options) { // eslint-disable-line require-await
     return repo.config.set(key, value, options)
   }
 
   /**
-   * @type {import('ipfs-core-types/src/config').API["replace"]}
+   * @type {import('ipfs-core-types/src/config').API<{}>["replace"]}
    */
   async function replace (value, options) { // eslint-disable-line require-await
     return repo.config.replace(value, options)
   }
 
   /**
-   * @type {import('ipfs-core-types/src/config/profiles').API["apply"]}
+   * @type {import('ipfs-core-types/src/config/profiles').API<{}>["apply"]}
    */
   async function applyProfile (profileName, options = { dryRun: false }) {
     const { dryRun } = options
@@ -91,7 +91,7 @@ export function createConfig ({ repo }) {
 }
 
 /**
- * @type {import('ipfs-core-types/src/config/profiles').API["list"]}
+ * @type {import('ipfs-core-types/src/config/profiles').API<{}>["list"]}
  */
 async function listProfiles (_options) { // eslint-disable-line require-await
   return Object.keys(profiles).map(name => ({

packages/ipfs-core/src/components/dag/export.js

@@ -31,7 +31,7 @@ const NO_LINKS_CODECS = [
  */
 export function createExport ({ repo, preload, codecs }) {
   /**
-   * @type {import('ipfs-core-types/src/dag').API["export"]}
+   * @type {import('ipfs-core-types/src/dag').API<{}>["export"]}
    */
   async function * dagExport (root, options = {}) {
     if (options.preload !== false) {

packages/ipfs-core/src/components/dag/get.js

@@ -12,7 +12,7 @@ import errCode from 'err-code'
  */
 export function createGet ({ codecs, repo, preload }) {
   /**
-   * @type {import('ipfs-core-types/src/dag').API["get"]}
+   * @type {import('ipfs-core-types/src/dag').API<{}>["get"]}
    */
   const get = async function get (cid, options = {}) {
     if (options.preload !== false) {

packages/ipfs-core/src/components/dag/import.js

@@ -19,7 +19,7 @@ const log = debug('ipfs:components:dag:import')
  */
 export function createImport ({ repo }) {
   /**
-   * @type {import('ipfs-core-types/src/dag').API["import"]}
+   * @type {import('ipfs-core-types/src/dag').API<{}>["import"]}
    */
   async function * dagImport (sources, options = {}) {
     const release = await repo.gcLock.readLock()

packages/ipfs-core/src/components/dag/put.js

@@ -10,7 +10,7 @@ import { withTimeoutOption } from 'ipfs-core-utils/with-timeout-option'
  */
 export function createPut ({ repo, codecs, hashers, preload }) {
   /**
-   * @type {import('ipfs-core-types/src/dag').API["put"]}
+   * @type {import('ipfs-core-types/src/dag').API<{}>["put"]}
    */
   async function put (dagNode, options = {}) {
     const release = options.pin ? await repo.gcLock.readLock() : null

packages/ipfs-core/src/components/dag/resolve.js

@@ -10,7 +10,7 @@ import { resolvePath } from '../../utils.js'
  */
 export function createResolve ({ repo, codecs, preload }) {
   /**
-   * @type {import('ipfs-core-types/src/dag').API["resolve"]}
+   * @type {import('ipfs-core-types/src/dag').API<{}>["resolve"]}
    */
   async function dagResolve (ipfsPath, options = {}) {
     const {

packages/ipfs-core/src/components/dht.js

@@ -157,7 +157,7 @@ function mapEvent (event) {
 export function createDht ({ network, repo, peerId }) {
   const { get, put, findProvs, findPeer, provide, query } = {
     /**
-     * @type {import('ipfs-core-types/src/dht').API["get"]}
+     * @type {import('ipfs-core-types/src/dht').API<{}>["get"]}
      */
     async * get (key, options = {}) {
       const { libp2p } = await use(network, peerId, options)
@@ -168,7 +168,7 @@ export function createDht ({ network, repo, peerId }) {
     },
 
     /**
-     * @type {import('ipfs-core-types/src/dht').API["put"]}
+     * @type {import('ipfs-core-types/src/dht').API<{}>["put"]}
      */
     async * put (key, value, options) {
       const { libp2p } = await use(network, peerId, options)
@@ -179,9 +179,9 @@ export function createDht ({ network, repo, peerId }) {
     },
 
     /**
-     * @type {import('ipfs-core-types/src/dht').API["findProvs"]}
+     * @type {import('ipfs-core-types/src/dht').API<{}>["findProvs"]}
      */
-    async * findProvs (cid, options = { numProviders: 20 }) {
+    async * findProvs (cid, options = {}) {
       const { libp2p } = await use(network, peerId, options)
 
       yield * map(libp2p._dht.findProviders(cid, {
@@ -190,7 +190,7 @@ export function createDht ({ network, repo, peerId }) {
     },
 
     /**
-     * @type {import('ipfs-core-types/src/dht').API["findPeer"]}
+     * @type {import('ipfs-core-types/src/dht').API<{}>["findPeer"]}
      */
     async * findPeer (peerIdToFind, options = {}) {
       const { libp2p } = await use(network, peerId, options)
@@ -201,7 +201,7 @@ export function createDht ({ network, repo, peerId }) {
     },
 
     /**
-     * @type {import('ipfs-core-types/src/dht').API["provide"]}
+     * @type {import('ipfs-core-types/src/dht').API<{}>["provide"]}
      */
     async * provide (cid, options = { recursive: false }) {
       const { libp2p } = await use(network, peerId, options)
@@ -222,7 +222,7 @@ export function createDht ({ network, repo, peerId }) {
     },
 
     /**
-     * @type {import('ipfs-core-types/src/dht').API["query"]}
+     * @type {import('ipfs-core-types/src/dht').API<{}>["query"]}
      */
     async * query (peerIdToQuery, options = {}) {
       const { libp2p } = await use(network, peerId, options)

packages/ipfs-core/src/components/dns.js

@@ -17,7 +17,7 @@ function fqdnFixups (domain) {
 
 export function createDns () {
   /**
-   * @type {import('ipfs-core-types/src/root').API["dns"]}
+   * @type {import('ipfs-core-types/src/root').API<{}>["dns"]}
    */
   const resolveDNS = async (domain, options = { recursive: true }) => { // eslint-disable-line require-await
     if (typeof domain !== 'string') {

packages/ipfs-core/src/components/files/chmod.js

@@ -214,7 +214,7 @@ function calculateMode (mode, metadata) {
  */
 export function createChmod (context) {
   /**
-   * @type {import('ipfs-core-types/src/files').API["chmod"]}
+   * @type {import('ipfs-core-types/src/files').API<{}>["chmod"]}
    */
   async function mfsChmod (path, mode, options = {}) {
     /** @type {DefaultOptions} */

packages/ipfs-core/src/components/files/cp.js

@@ -47,7 +47,7 @@ const defaultOptions = {
  */
 export function createCp (context) {
   /**
-   * @type {import('ipfs-core-types/src/files').API["cp"]}
+   * @type {import('ipfs-core-types/src/files').API<{}>["cp"]}
    */
   async function mfsCp (from, to, opts = {}) {
     /** @type {DefaultOptions} */

packages/ipfs-core/src/components/files/flush.js

@@ -21,7 +21,7 @@ const defaultOptions = {}
  */
 export function createFlush (context) {
   /**
-   * @type {import('ipfs-core-types/src/files').API["flush"]}
+   * @type {import('ipfs-core-types/src/files').API<{}>["flush"]}
    */
   async function mfsFlush (path, options = {}) {
     /** @type {DefaultOptions} */

packages/ipfs-core/src/components/files/ls.js

@@ -33,7 +33,7 @@ const toOutput = (fsEntry) => {
  */
 export function createLs (context) {
   /**
-   * @type {import('ipfs-core-types/src/files').API["ls"]}
+   * @type {import('ipfs-core-types/src/files').API<{}>["ls"]}
    */
   async function * mfsLs (path, options = {}) {
     const mfsPath = await toMfsPath(context, path, options)

packages/ipfs-core/src/components/files/mkdir.js

@@ -47,7 +47,7 @@ const defaultOptions = {
  */
 export function createMkdir (context) {
   /**
-   * @type {import('ipfs-core-types/src/files').API["mkdir"]}
+   * @type {import('ipfs-core-types/src/files').API<{}>["mkdir"]}
    */
   async function mfsMkdir (path, options = {}) {
     /** @type {DefaultOptions} */