fix: typedef resolution & add examples that use types (#3359)

1. addresses #3356 in a different way based no findings in #3358. 
2. Adds ts project example that uses ipfs and tests that it type checks.
3. Adds js project example that uses ipfs and runs type checker to ensure types are picked up and inferred.
4. Changes all the `ReturnType<import(...)>`'s to `ReturnType<typeof import(...)>` as former seems to raise errors in stricter TS setup.

Co-authored-by: achingbrain <[email protected]>

Author: Gozala

package.json

@@ -23,7 +23,8 @@
   "typesVersions": {
     "*": {
       "*": [
-        "dist/*"
+        "dist/*",
+        "dist/*/index"
       ]
     }
   },

src/add-all.js

@@ -10,7 +10,7 @@ const AbortController = require('native-abort-controller')
 
 module.exports = configure((api) => {
   /**
-   * @type {import('.').Implements<import('ipfs-core/src/components/add-all/index')>}
+   * @type {import('.').Implements<typeof import('ipfs-core/src/components/add-all/index')>}
    */
   async function * addAll (source, options = {}) {
     const progressFn = options.progress

src/add.js

@@ -11,7 +11,7 @@ module.exports = (options) => {
   const all = addAll(options)
   return configure(() => {
     /**
-     * @type {import('.').Implements<import('ipfs-core/src/components/add')>}
+     * @type {import('.').Implements<typeof import('ipfs-core/src/components/add')>}
      */
     async function add (input, options = {}) {
       // @ts-ignore - last may return undefind if source is empty

src/bitswap/unwant.js

@@ -6,7 +6,7 @@ const toUrlSearchParams = require('../lib/to-url-search-params')
 
 module.exports = configure(api => {
   /**
-   * @type {import('..').Implements<import('ipfs-core/src/components/bitswap/unwant')>}
+   * @type {import('..').Implements<typeof import('ipfs-core/src/components/bitswap/unwant')>}
    */
   async function unwant (cid, options = {}) {
     const res = await api.post('bitswap/unwant', {

src/block/get.js

@@ -7,7 +7,7 @@ const toUrlSearchParams = require('../lib/to-url-search-params')
 
 module.exports = configure(api => {
   /**
-   * @type {import('..').Implements<import('ipfs-core/src/components/block/get')>}
+   * @type {import('..').Implements<typeof import('ipfs-core/src/components/block/get')>}
    */
   async function get (cid, options = {}) {
     // @ts-ignore - CID|string seems to confuse typedef

src/block/put.js

@@ -11,7 +11,7 @@ const AbortController = require('native-abort-controller')
 
 module.exports = configure(api => {
   /**
-   * @type {import('..').Implements<import('ipfs-core/src/components/block/put')>}
+   * @type {import('..').Implements<typeof import('ipfs-core/src/components/block/put')>}
    */
   async function put (data, options = {}) {
     if (Block.isBlock(data)) {

src/block/rm.js

@@ -6,7 +6,7 @@ const toUrlSearchParams = require('../lib/to-url-search-params')
 
 module.exports = configure(api => {
   /**
-   * @type {import('..').Implements<import('ipfs-core/src/components/block/rm')>}
+   * @type {import('..').Implements<typeof import('ipfs-core/src/components/block/rm')>}
    */
   async function * rm (cid, options = {}) {
     if (!Array.isArray(cid)) {

src/block/stat.js

@@ -6,7 +6,7 @@ const toUrlSearchParams = require('../lib/to-url-search-params')
 
 module.exports = configure(api => {
   /**
-   * @type {import('..').Implements<import('ipfs-core/src/components/block/stat')>}
+   * @type {import('..').Implements<typeof import('ipfs-core/src/components/block/stat')>}
    */
   async function stat (cid, options = {}) {
     const res = await api.post('block/stat', {

src/bootstrap/add.js

@@ -6,7 +6,7 @@ const Multiaddr = require('multiaddr')
 
 module.exports = configure(api => {
   /**
-   * @type {import('..').Implements<import('ipfs-core/src/components/bootstrap/add')>}
+   * @type {import('..').Implements<typeof import('ipfs-core/src/components/bootstrap/add')>}
    */
   async function add (addr, options = {}) {
     const res = await api.post('bootstrap/add', {

src/bootstrap/clear.js

@@ -6,7 +6,7 @@ const Multiaddr = require('multiaddr')
 
 module.exports = configure(api => {
   /**
-   * @type {import('..').Implements<import('ipfs-core/src/components/bootstrap/clear')>}
+   * @type {import('..').Implements<typeof import('ipfs-core/src/components/bootstrap/clear')>}
    */
   async function clear (options = {}) {
     const res = await api.post('bootstrap/rm', {

src/bootstrap/list.js

@@ -6,7 +6,7 @@ const Multiaddr = require('multiaddr')
 
 module.exports = configure(api => {
   /**
-   * @type {import('..').Implements<import('ipfs-core/src/components/bootstrap/list')>}
+   * @type {import('..').Implements<typeof import('ipfs-core/src/components/bootstrap/list')>}
    */
   async function list (options = {}) {
     const res = await api.post('bootstrap/list', {

src/bootstrap/reset.js

@@ -6,7 +6,7 @@ const Multiaddr = require('multiaddr')
 
 module.exports = configure(api => {
   /**
-   * @type {import('..').Implements<import('ipfs-core/src/components/bootstrap/reset')>}
+   * @type {import('..').Implements<typeof import('ipfs-core/src/components/bootstrap/reset')>}
    */
   async function reset (options = {}) {
     const res = await api.post('bootstrap/add', {

src/bootstrap/rm.js

@@ -6,7 +6,7 @@ const Multiaddr = require('multiaddr')
 
 module.exports = configure(api => {
   /**
-   * @type {import('..').Implements<import('ipfs-core/src/components/bootstrap/rm')>}
+   * @type {import('..').Implements<typeof import('ipfs-core/src/components/bootstrap/rm')>}
    */
   async function rm (addr, options = {}) {
     const res = await api.post('bootstrap/rm', {

src/cat.js

@@ -6,7 +6,7 @@ const toUrlSearchParams = require('./lib/to-url-search-params')
 
 module.exports = configure(api => {
   /**
-   * @type {import('.').Implements<import('ipfs-core/src/components/cat')>}
+   * @type {import('.').Implements<typeof import('ipfs-core/src/components/cat')>}
    */
   async function * cat (path, options = {}) {
     const res = await api.post('cat', {

src/dag/get.js

@@ -10,7 +10,7 @@ module.exports = configure((api, opts) => {
   const load = loadFormat(opts.ipld)
 
   /**
-   * @type {import('..').Implements<import('ipfs-core/src/components/dag/get')>}
+   * @type {import('..').Implements<typeof import('ipfs-core/src/components/dag/get')>}
    */
   const get = async (cid, options = {}) => {
     const resolved = await dagResolve(cid, options)

src/dag/put.js

@@ -14,7 +14,7 @@ module.exports = configure((api, opts) => {
   const load = loadFormat(opts.ipld)
 
   /**
-   * @type {import('..').Implements<import('ipfs-core/src/components/dag/put')>}
+   * @type {import('..').Implements<typeof import('ipfs-core/src/components/dag/put')>}
    */
   const put = async (dagNode, options = {}) => {
     if (options.cid && (options.format || options.hashAlg)) {

src/dag/resolve.js

@@ -6,7 +6,7 @@ const toUrlSearchParams = require('../lib/to-url-search-params')
 
 module.exports = configure(api => {
   /**
-   * @type {import('..').Implements<import('ipfs-core/src/components/dag/resolve')>}
+   * @type {import('..').Implements<typeof import('ipfs-core/src/components/dag/resolve')>}
    */
   const resolve = async (ipfsPath, options = {}) => {
     const res = await api.post('dag/resolve', {

src/dns.js

@@ -5,7 +5,7 @@ const toUrlSearchParams = require('./lib/to-url-search-params')
 
 module.exports = configure(api => {
   /**
-   * @type {import('.').Implements<import('ipfs-core/src/components/dns')>}
+   * @type {import('.').Implements<typeof import('ipfs-core/src/components/dns')>}
    */
   const dns = async (domain, options = {}) => {
     const res = await api.post('dns', {

src/get.js

@@ -8,7 +8,7 @@ const map = require('it-map')
 
 module.exports = configure(api => {
   /**
-   * @type {import('.').Implements<import('ipfs-core/src/components/get')>}
+   * @type {import('.').Implements<typeof import('ipfs-core/src/components/get')>}
    */
   async function * get (path, options = {}) {
     const res = await api.post('get', {

src/id.js

@@ -7,7 +7,7 @@ const toUrlSearchParams = require('./lib/to-url-search-params')
 
 module.exports = configure(api => {
   /**
-   * @type {import('.').Implements<import('ipfs-core/src/components/id')>}
+   * @type {import('.').Implements<typeof import('ipfs-core/src/components/id')>}
    */
   async function id (options = {}) {
     const res = await api.post('id', {

src/resolve.js

@@ -5,7 +5,7 @@ const toUrlSearchParams = require('./lib/to-url-search-params')
 
 module.exports = configure(api => {
   /**
-   * @type {import('.').Implements<import('ipfs-core/src/components/resolve')>}
+   * @type {import('.').Implements<typeof import('ipfs-core/src/components/resolve')>}
    */
   async function resolve (path, options = {}) {
     const res = await api.post('resolve', {

src/version.js

@@ -7,7 +7,7 @@ const pkg = require('../package.json')
 
 module.exports = configure(api => {
   /**
-   * @type {import('.').Implements<import('ipfs-core/src/components/version')>}
+   * @type {import('.').Implements<typeof import('ipfs-core/src/components/version')>}
    */
   async function version (options = {}) {
     const res = await api.post('version', {