js-IPFS 0.55.0 greatly improves type definitions

Alex Potsides
js-IPFS 0.55.0 greatly improves type definitions
#breaking change #js-ipfs
Share this item:

# 🔦 Highlights

TypeScript type definitions have been rewritten from the ground up

# 🍪 Types

It's been a long time in the works, but js-ipfs@0.55.0 finally lands with a brand new set of TypeScript type definitions entirely re-written from the ground up.

We previously shipped 0.51.0 with bundled TypeScript type definitions which enabled users to explore the IPFS Core API through intellisense (opens new window) and use that to ensure they were calling methods that existed, but the argument and return types were frequently marked any, which, although would not cause TypeScript compilation errors, gave you little in the way of actual type safety.

Part of the problem is that js-ipfs exposes the return types of many supporting modules which do not ship with TypeScript definitions. This means we either had to PR support for TypeScript definitions into these modules or type their input/output at the js-ipfs level which is error prone and makes no guarantees about the actual underlying code.

We took a look at our stack and started to add TypeScript types from the lowest level up, which has been an enormous job with some 250 pull requests opened, reviewed, merged and shipped as part of this effort. A massive thanks to everyone involved, see the contributors list further down this post for who helped out!

# 🙅 noImplicitAny

Early on we decided to enable noImplicitAny (opens new window) in our tsconfig.json files. This is a strict setting which causes an error when type information for any variable cannot be found.

It means that everything has to be typed internally which increased the amount of work necessary to deliver this release but our internal code is now vastly safer and it even surfaced a few bugs and unhandled edge cases in the implementation so upgrading is very much recommended.

# 🤖 Future proofing

In line with our supported versions (opens new window), js-ipfs@0.55.0 has dropped support for Node.js < 14. This is so we can support the latest and greatest features without having to carry legacy baggage forward.

We've also switched to using named exports for our top-level modules instead of default exports as it makes them more pleasant to consume from ES module (opens new window) environments. It also means the type definitions generated from JSDoc annotations (opens new window) are more compact and have to jump through fewer hoops to reflect the code they are generated from.

From perspective of the external API, this only affects ipfs-http-client:

// before
const create = require('ipfs-http-client')
const ipfs = create()

// after
const { create } = require('ipfs-http-client')
const ipfs = create()

Finally, in some places we previously returned instances of the bignumber.js (opens new window) module—this has been necessary in the past because JavaScript lacked an arbitrary precision number type. BigInt (opens new window) has been present in all of our supported environments for some time so we've been removing bignumber.js in favour of BigInt in the Core API (opens new window).

# 🛍️ Upgrade guide

We've taken this opportunity to align the implementation with the published Core API Docs (opens new window). In some cases the accepted input types were broader than what was documented for backward compatibility, but that compatibility comes at the cost of code complexity and added maintenance, so those old code paths have been removed.

If you have coded against the Core API docs you should have very few surprises in store.

The API changes are as follows:

  • ipfs.bitswap.stat() - returned peers is a string[] (was CID[])
  • ipfs.bitstwap.stat() - returned blocksReceived is a BigInt (was bignumber.js)
  • ipfs.bitstwap.stat() - returned dataReceived is a BigInt (was bignumber.js)
  • ipfs.bitstwap.stat() - returned blocksSent is a BigInt (was bignumber.js)
  • ipfs.files.rm(path, opts) - path arg is string | string[] (was ...string)
  • ipfs.files.cp(source, dest, opts) - source arg is string | string[] (was ...string)
  • ipfs.files.mv(source, dest, opts) - source arg is string | string[] (was ...string)

# ✨New features

# 🔨 Breaking changes

  • The minimum supported Node.js version is 14
  • All Core API methods now have types, some method signatures have changed (see Upgrade Guide above)
  • Named exports are now used by the http, grpc and ipfs client modules (see Future proofing, above)

# 🕷️ Bug fixes

# 🗺️ What’s next?

Check out the js-IPFS Project Roadmap (opens new window) which contains headline features organised in the order we hope them to land.

Only large features are called out in the roadmap, expect lots of small bugfix releases between the roadmapped items!

# 😍 Huge thank you to everyone that made this release possible

# 🙌🏽 Want to contribute?

Would you like to contribute to the IPFS project and don’t know how? Well, there are a few places you can get started:

# ⁉️ Do you have questions?

The best place to ask your questions about IPFS, how it works, and what you can do with it is at discuss.ipfs.tech (opens new window). We are also available at the #ipfs channel on Freenode.