fix: typedef resolution & add examples that use types

examples/types-use-ipfs-from-ts/README.md

@@ -0,0 +1,56 @@
+# Using IPFS with Typescript
+
+> This example provides a template for using js-ipfs in typescript project.
+
+
+## Before you start
+
+First clone this repo, install dependencies in the project root.
+
+```
+git clone https://github.com/ipfs/js-ipfs.git
+cd js-ipfs/examples/types-use-ipfs-from-ts
+npm install
+```
+
+You can type check this example by runing following in the example directory:
+
+```
+npm test
+```
+
+You should see following output:
+
+```
+> tsc --noEmit
+```
+
+If you remove `// @ts-expect-error` comment is `src/main.ts` on line 16 and run `npm test` once again you should see a following output instead:
+
+```
+tsc --noEmit
+
+src/main.ts:16:14 - error TS2339: Property 'toUpperCase' does not exist on type 'CID'.
+
+16     file.cid.toUpperCase()
+                ~~~~~~~~~~~
+
+
+Found 1 error.
+```
+
+
+## IntelliSense
+
+In the vscode and other code editors that provide [comparable IntelliSense features](https://docs.microsoft.com/en-us/visualstudio/ide/using-intellisense?view=vs-2019) you should be able to get code auto complete, paramatere and return value information for `js-ipfs` APIs.
+
+![Preview](Preview.png)
+
+## Limitations
+
+- Things should work out of the box, with most `tsconfig` settings, however unless
+[`skipLibCheck`](https://www.typescriptlang.org/tsconfig#skipLibCheck) is set to `true` many errors will be reported.
+  > That is because
+types are generated from source JSDoc comments and typescript seems to emit declarations which it then complains about.
+
+- Not all APIs are fully entyped so you might observe gaps and `any` types here and there. We hope to improve this over time.

examples/types-use-ipfs-from-ts/package.json

@@ -0,0 +1,13 @@
+{
+  "name": "types-use-ipfs-from-ts",
+  "private": true,
+  "dependencies": {
+    "ipfs": "^0.51.0"
+  },
+  "devDependencies": {
+    "typescript": "^4.0.3"
+  },
+  "scripts": {
+    "test": "tsc --noEmit"
+  }
+}

examples/types-use-ipfs-from-ts/src/main.ts

@@ -0,0 +1,28 @@
+import IPFS from 'ipfs'
+
+export default async function main () {
+  const node = await IPFS.create()
+  const version = await node.version()
+
+  console.log('Version:', version.version)
+
+  const file = await node.add({
+    path: 'hello.txt',
+    content: new TextEncoder().encode('Hello World 101')
+  })
+
+  console.log('Added file:', file.path, file.cid.toString())
+  try {
+    file.cid.toUpperCase()
+  } catch(error) {
+
+  }
+
+  const decoder = new TextDecoder()
+  let content = ''
+  for await (const chunk of node.cat(file.cid)) {
+    content += decoder.decode(chunk)  
+  }
+
+  console.log('Added file contents:', content)
+}

examples/types-use-ipfs-from-ts/tsconfig.json

@@ -0,0 +1,13 @@
+{
+  "compilerOptions": {
+    "strict": true,
+    "skipLibCheck": true,
+    "noImplicitAny": false,
+    "esModuleInterop": true,
+    "moduleResolution": "Node",
+    "noEmit": true
+  },
+  "include": [
+    "src"
+  ]
+}

examples/types-use-ipfs-from-typed-js/README.md

@@ -0,0 +1,59 @@
+# Using IPFS with typed JS 
+
+> This example provides a template for setting up a [JS project that utilizes type checker](https://www.typescriptlang.org/docs/handbook/type-checking-javascript-files.html) and `js-ipfs` type [declarations the were generated from JSDoc comments](https://www.typescriptlang.org/docs/handbook/declaration-files/dts-from-js.html)
+
+Things should work out of the box, only requirement is to disable
+[`skipLibCheck`](https://www.typescriptlang.org/tsconfig#skipLibCheck) because type declarations generated by typescript for commonjs modules raise some issues when consumed.
+
+
+## Before you start
+
+First clone this repo, install dependencies in the project root.
+
+```
+git clone https://github.com/ipfs/js-ipfs.git
+cd js-ipfs/examples/types-use-ipfs-from-typed-js
+npm install
+```
+
+## Type checking
+
+You can type check this example by runing following in the example directory:
+
+```
+npm test
+```
+
+You should see following output:
+
+```
+> tsc --noEmit
+```
+
+If you remove `// @ts-expect-error` comment is `src/main.js` on line 16 and run `npm test` once again you should see a following output instead:
+
+```
+> tsc --noEmit
+src/main.js:16:14 - error TS2339: Property 'toUpperCase' does not exist on type 'CID'.
+
+16     file.cid.toUpperCase()
+                ~~~~~~~~~~~
+
+
+Found 1 error.
+```
+
+## IntelliSense
+
+In the vscode and other code editors that provide [comparable IntelliSense features](https://docs.microsoft.com/en-us/visualstudio/ide/using-intellisense?view=vs-2019) you should be able to get code auto complete, paramatere and return value information for `js-ipfs` APIs.
+
+![Preview](Preview.png)
+
+## Limitations
+
+- Things should work out of the box, with most `tsconfig` settings, however unless
+[`skipLibCheck`](https://www.typescriptlang.org/tsconfig#skipLibCheck) is set to `true` many errors will be reported.
+  > That is because
+types are generated from source JSDoc comments and typescript seems to emit declarations which it then complains about.
+
+- Not all APIs are fully entyped so you might observe gaps and `any` types here and there. We hope to improve this over time.

examples/types-use-ipfs-from-typed-js/package.json

@@ -0,0 +1,13 @@
+{
+  "name": "types-use-ipfs-from-typed-js",
+  "private": true,
+  "dependencies": {
+    "ipfs": "^0.51.0"
+  },
+  "devDependencies": {
+    "typescript": "^4.0.3"
+  },
+  "scripts": {
+    "test": "tsc --noEmit"
+  }
+}

examples/types-use-ipfs-from-typed-js/src/main.js

@@ -0,0 +1,30 @@
+const IPFS = require('ipfs')
+
+async function main () {
+  const node = await IPFS.create()
+  const version = await node.version()
+
+  console.log('Version:', version.version)
+
+  const file = await node.add({
+    path: 'hello.txt',
+    content: new TextEncoder().encode('Hello World 101')
+  })
+
+  console.log('Added file:', file.path, file.cid.toString())
+  try {
+    file.cid.toUpperCase()
+  } catch(error) {
+
+  }
+
+  const decoder = new TextDecoder()
+  let content = ''
+  for await (const chunk of node.cat(file.cid)) {
+    content += decoder.decode(chunk)  
+  }
+
+  console.log('Added file contents:', content)
+}
+
+main()

examples/types-use-ipfs-from-typed-js/tsconfig.json

@@ -0,0 +1,15 @@
+{
+  "compilerOptions": {
+    "allowJs": true,
+    "checkJs": true,
+    "strict": true,
+    "skipLibCheck": true,
+    "noImplicitAny": false,
+    "esModuleInterop": true,
+    "moduleResolution": "Node",
+    "noEmit": true
+  },
+  "include": [
+    "src"
+  ]
+}

packages/ipfs-core-utils/package.json

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

packages/ipfs-core/package.json

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

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

@@ -5,17 +5,17 @@ const isIpfs = require('is-ipfs')
 
 /**
  * @typedef {Object} MFS
- * @property {ReturnType<import('./stat')>} stat
- * @property {ReturnType<import('./chmod')>} chmod
- * @property {ReturnType<import('./cp')>} cp
- * @property {ReturnType<import('./flush')>} flush
- * @property {ReturnType<import('./mkdir')>} mkdir
- * @property {ReturnType<import('./mv')>} mv
- * @property {ReturnType<import('./rm')>} rm
- * @property {ReturnType<import('./touch')>} touch
- * @property {ReturnType<import('./write')>} write
- * @property {ReturnType<import('./read')>} read
- * @property {ReturnType<import('./ls')>} ls
+ * @property {ReturnType<typeof import('./stat')>} stat
+ * @property {ReturnType<typeof import('./chmod')>} chmod
+ * @property {ReturnType<typeof import('./cp')>} cp
+ * @property {ReturnType<typeof import('./flush')>} flush
+ * @property {ReturnType<typeof import('./mkdir')>} mkdir
+ * @property {ReturnType<typeof import('./mv')>} mv
+ * @property {ReturnType<typeof import('./rm')>} rm
+ * @property {ReturnType<typeof import('./touch')>} touch
+ * @property {ReturnType<typeof import('./write')>} write
+ * @property {ReturnType<typeof import('./read')>} read
+ * @property {ReturnType<typeof import('./ls')>} ls
  */
 
 // These operations are read-locked at the function level and will execute simultaneously