docs: add types and documentation

[hacdias]

• TypeScript typings
• Update README with some docs

[hacdias]

@jacobheun as I think you have more experience with TypeScript, I'm pinging you here to ask you to validate my TypeScript typings: am I writing them the way they're supposed to be? Is there any configuration that I'm missing? I feel like there's something lacking

[jacobheun]

Tapping @Gozala and @hugomrdias for TS typings, they're currently adding typings through js-ipfs/js-libp2p.

We've also started using a github action typechecker, that would be good to setup here as well, https://github.com/gozala/typescript-error-reporter-action.

[hugomrdias]

My advice is to not manually write definitions and do the same thing we are doing in ipfs and libp2p. We are using JSdoc to type the code inline and aegir to check and generate definitions.
https://github.com/ipfs/aegir/blob/master/md/ts-jsdoc.md
ipfs/js-ipfs#2945

[hugomrdias]

would be better to use Array.flat and consider pino instead of winston

[hacdias]

The linter complains because Array.flat was not available on Node 10. I could not change the engines to Node 12.

Thanks for the pino suggestion!

[hugomrdias]

why are you supporting node10 ?

[hacdias]

Apparently it's the TS checker. The linter is Ok.

Edit: please ignore this.

[hugomrdias]

wait why are flattening that method returns an object not a array

[hacdias]

why are you supporting node10 ?

@hugomrdias every time I change the engines in package.json to:

  "engines": {
    "node": ">=12.0.0"
  },

I get:

./node_modules/.bin/aegir lint-package-json

./package.json
✖ valid-values-engines - node: engines - Invalid value for engines
1 error
0 warnings
Command failed with exit code 2: npmPkgJsonLint /Users/henriquedias/Code/testground/sdk-js/package.json -c /Users/henriquedias/Code/testground/sdk-js/node_modules/aegir/src/config/.npmpackagejsonlintrc.json

Then I saw this and assumed we had to support Node 10.

[hugomrdias]

ah got it i will fix that, sorry my bad, that rule is dumb

[hacdias]

Thanks @hugomrdias. Quick question, is the bundle size checker tailored only for packages that can go into the browser? For example, here I'm getting the error Can't resolve 'os', which lead me to assume that. I want to make this package work on the browser too in the future, but I'm not sure if I can obtain the network interfaces and the hostname in the browser!

[hugomrdias]

Q: will this be only targeted at node ? we would also might want to include browser, electron, react-native nodes in the tests.

[hacdias]

Q: will this be only targeted at node ? we would also might want to include browser, electron, react-native nodes in the tests.

See comment above. I want to make it work on the browser, but I didn't find alternatives for those functions of the os package...

[hugomrdias]

Thanks @hugomrdias. Quick question, is the bundle size checker tailored only for packages that can go into the browser? For example, here I'm getting the error Can't resolve 'os', which lead me to assume that. I want to make this package work on the browser too in the future, but I'm not sure if I can obtain the network interfaces and the hostname in the browser!

its tailored to everything that might use bundlers and those will not include node globals or builtins

[hugomrdias]

Everything "native" should be injected rather than locking yourself right from the beginning into nodejs

[hugomrdias]

the architecture of this should abstract these things in a way we can implement env specific implementations, and then swap them as needed.
so i would recommend thinking a bit about all the info you might need and where that comes from in different envs.

Some solutions might just be injecting as globals or process.env vars or abstract into an interface that can be implemented for different envs. ie. browser doesnt have network interfaces but libp2p in some cases might overcome that or you might need some hooks to orchestrate external nodes to delegate. React native has interfaces but the way to get them is really different from nodejs.

[hacdias]

the architecture of this should abstract these things in a way we can implement env specific implementations, and then swap them as needed.
so i would recommend thinking a bit about all the info you might need and where that comes from in different envs.

Some solutions might just be injecting as globals or process.env vars or abstract into an interface that can be implemented for different envs. ie. browser doesnt have network interfaces but libp2p in some cases might overcome that or you might need some hooks to orchestrate external nodes to delegate. React native has interfaces but the way to get them is really different from nodejs.

Sounds reasonable. If we take into account that the test is always started by Testground, we will always have a way to obtain those informations and pass them to the tests somehow. I will rework the environment specific variables so we can inject them. I will probably go for the interface way. Seems more flexible.

[hacdias]

Superseeded by #15

[hacdias]

the architecture of this should abstract these things in a way we can implement env specific implementations, and then swap them as needed.
so i would recommend thinking a bit about all the info you might need and where that comes from in different envs.

Some solutions might just be injecting as globals or process.env vars or abstract into an interface that can be implemented for different envs. ie. browser doesnt have network interfaces but libp2p in some cases might overcome that or you might need some hooks to orchestrate external nodes to delegate. React native has interfaces but the way to get them is really different from nodejs.

@hugomrdias After investigating, we can do so for stuff like 'path' and 'os'. However, I can't find any redis client that does not depend on Node built-ins. I will investigate. If you know any, that'd be great.

[hugomrdias]

ah right, the only solution i found for browser connection is to use https://webd.is/
but you can split by env and target browser like and bundlers with an http client to webdis and node with a node native redis-client.
if you need help ping me