Skip to content
This repository was archived by the owner on Feb 12, 2024. It is now read-only.

Commit dc2795a

Browse files
Gozalaachingbrain
andauthored
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 <alex@achingbrain.net>
1 parent b5ea76a commit dc2795a

File tree

43 files changed

+347
-115
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

43 files changed

+347
-115
lines changed
Lines changed: 56 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,56 @@
1+
# Using IPFS with Typescript
2+
3+
> This example provides a template for using js-ipfs in typescript project.
4+
5+
6+
## Before you start
7+
8+
First clone this repo, install dependencies in the project root.
9+
10+
```
11+
git clone https://github.com/ipfs/js-ipfs.git
12+
cd js-ipfs/examples/types-use-ipfs-from-ts
13+
npm install
14+
```
15+
16+
You can type check this example by runing following in the example directory:
17+
18+
```
19+
npm test
20+
```
21+
22+
You should see following output:
23+
24+
```
25+
> tsc --noEmit
26+
```
27+
28+
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:
29+
30+
```
31+
tsc --noEmit
32+
33+
src/main.ts:16:14 - error TS2339: Property 'toUpperCase' does not exist on type 'CID'.
34+
35+
16 file.cid.toUpperCase()
36+
~~~~~~~~~~~
37+
38+
39+
Found 1 error.
40+
```
41+
42+
43+
## IntelliSense
44+
45+
In [VSCode](https://code.visualstudio.com/) 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, parameter and return value information for `js-ipfs` APIs.
46+
47+
![Preview](./preview.png)
48+
49+
## Limitations
50+
51+
- Things should work out of the box, with most `tsconfig` settings, however unless
52+
[`skipLibCheck`](https://www.typescriptlang.org/tsconfig#skipLibCheck) is set to `true` many errors will be reported.
53+
> That is because
54+
types are generated from source JSDoc comments and typescript seems to emit declarations which it then complains about.
55+
56+
- Not all APIs are fully entyped so you might observe gaps and `any` types here and there. We hope to improve this over time.
Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
{
2+
"name": "types-use-ipfs-from-ts",
3+
"private": true,
4+
"dependencies": {
5+
"ipfs": "^0.51.0"
6+
},
7+
"devDependencies": {
8+
"typescript": "^4.0.3"
9+
},
10+
"scripts": {
11+
"test": "tsc --noEmit"
12+
}
13+
}
557 KB
Loading
Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
import IPFS from 'ipfs'
2+
3+
export default async function main () {
4+
const node = await IPFS.create()
5+
const version = await node.version()
6+
7+
console.log('Version:', version.version)
8+
9+
const file = await node.add({
10+
path: 'hello.txt',
11+
content: new TextEncoder().encode('Hello World 101')
12+
})
13+
14+
console.log('Added file:', file.path, file.cid.toString())
15+
try {
16+
file.cid.toUpperCase()
17+
} catch(error) {
18+
19+
}
20+
21+
const decoder = new TextDecoder()
22+
let content = ''
23+
for await (const chunk of node.cat(file.cid)) {
24+
content += decoder.decode(chunk)
25+
}
26+
27+
console.log('Added file contents:', content)
28+
}
Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
{
2+
"compilerOptions": {
3+
"strict": true,
4+
"skipLibCheck": true,
5+
"noImplicitAny": false,
6+
"esModuleInterop": true,
7+
"moduleResolution": "Node",
8+
"noEmit": true
9+
},
10+
"include": [
11+
"src"
12+
]
13+
}
Lines changed: 59 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,59 @@
1+
# Using IPFS with typed JS
2+
3+
> 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)
4+
5+
Things should work out of the box, only requirement is to disable
6+
[`skipLibCheck`](https://www.typescriptlang.org/tsconfig#skipLibCheck) because type declarations generated by typescript for commonjs modules raise some issues when consumed.
7+
8+
9+
## Before you start
10+
11+
First clone this repo, install dependencies in the project root.
12+
13+
```
14+
git clone https://github.com/ipfs/js-ipfs.git
15+
cd js-ipfs/examples/types-use-ipfs-from-typed-js
16+
npm install
17+
```
18+
19+
## Type checking
20+
21+
You can type check this example by runing following in the example directory:
22+
23+
```
24+
npm test
25+
```
26+
27+
You should see following output:
28+
29+
```
30+
> tsc --noEmit
31+
```
32+
33+
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:
34+
35+
```
36+
> tsc --noEmit
37+
src/main.js:16:14 - error TS2339: Property 'toUpperCase' does not exist on type 'CID'.
38+
39+
16 file.cid.toUpperCase()
40+
~~~~~~~~~~~
41+
42+
43+
Found 1 error.
44+
```
45+
46+
## IntelliSense
47+
48+
In [VSCode](https://code.visualstudio.com/) 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, parameter and return value information for `js-ipfs` APIs.
49+
50+
![Preview](./preview.png)
51+
52+
## Limitations
53+
54+
- Things should work out of the box, with most `tsconfig` settings, however unless
55+
[`skipLibCheck`](https://www.typescriptlang.org/tsconfig#skipLibCheck) is set to `true` many errors will be reported.
56+
> That is because
57+
types are generated from source JSDoc comments and typescript seems to emit declarations which it then complains about.
58+
59+
- Not all APIs are fully entyped so you might observe gaps and `any` types here and there. We hope to improve this over time.
Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
{
2+
"name": "types-use-ipfs-from-typed-js",
3+
"private": true,
4+
"dependencies": {
5+
"ipfs": "^0.51.0"
6+
},
7+
"devDependencies": {
8+
"typescript": "^4.0.3"
9+
},
10+
"scripts": {
11+
"test": "tsc --noEmit"
12+
}
13+
}
514 KB
Loading
Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
const IPFS = require('ipfs')
2+
3+
async function main () {
4+
const node = await IPFS.create()
5+
const version = await node.version()
6+
7+
console.log('Version:', version.version)
8+
9+
const file = await node.add({
10+
path: 'hello.txt',
11+
content: new TextEncoder().encode('Hello World 101')
12+
})
13+
14+
console.log('Added file:', file.path, file.cid.toString())
15+
try {
16+
file.cid.toUpperCase()
17+
} catch(error) {
18+
19+
}
20+
21+
const decoder = new TextDecoder()
22+
let content = ''
23+
for await (const chunk of node.cat(file.cid)) {
24+
content += decoder.decode(chunk)
25+
}
26+
27+
console.log('Added file contents:', content)
28+
}
29+
30+
main()
Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
{
2+
"compilerOptions": {
3+
"allowJs": true,
4+
"checkJs": true,
5+
"strict": true,
6+
"skipLibCheck": true,
7+
"noImplicitAny": false,
8+
"esModuleInterop": true,
9+
"moduleResolution": "Node",
10+
"noEmit": true
11+
},
12+
"include": [
13+
"src"
14+
]
15+
}

0 commit comments

Comments
 (0)