Pond 2.1.0 Released

Benjamin Sieffert

Benjamin Sieffert

Distributed Systems Engineer at Actyx

Today we have released Pond version 2.1.0 on npm.

This version does not bring new functionality; rather, it reduces the amount of exported types by a lot, hiding everything that is not part of the public API. This will make developing on the Pond in the IDE of your choice – like in our recommended editor, VSCode – much nicer, due to more relevant auto-complete and auto-import suggestions.

Read on for a brief explanation of how we cleaned up our type exports with the help of a tool called API Extractor.

TypeScript and JavaScript do not have a native concept of a "package" – all they know is modules. A module can only consist of one file. It hooks into other modules by importing part of their exports, and in turn exports some symbols – types, functions, classes, … – of its own.

Hence, functionality can be private to a module – by not being exported –, but there is no native way to have package-private functionality. In contrast, Java treats every symbol without an explicit access modifier as package-private by default!

Now turning our eyes on the Pond, our own npm package, there is of course a lot of internal functionality which the client code does not at all need to explicitly interact with. The type Pond declares our public API, but the implementation you get ahold of by calling e.g. Pond.default() uses dozens of modules (source files) which are actually internal, in the sense that they only exist to serve the Pond implementation.

So how can we "hide" these internal modules? TypeScript offers one piece of relevant functionality here, which is the annotation @internal that disables inclusion of types or parts of a type in its generated d.ts files. But it would be pretty tedious for us to go through all symbols in the Pond and annotate with @internal where applicable. It would also be very error-prone! What if we accidentally hid a symbol that is in fact needed to use the public API?

That is where API Extractor comes in. We supply it the "main entry point of our library" – which is basically just our type Pond export – and it automatically traverses the graph of types, collecting everything needed to use and construct our root type(s). Then it can warn us if we forgot to export any of the needed types from index.ts.

What it can also do is spare us the work of sticking the @internal label on everything else; it offers instead to roll up all public type declarations into one single d.ts file. That file is now being distributed as dist/pond.d.ts in our package. It is guaranteed to contain all the types needed to work with the Pond, and nothing else. Symbols which are not reachable from the public types are simply omitted.

The final step is that we declare "types": "dist/pond.d.ts" in our package.json file. An editor like VSCode automatically picks up on that, and stops suggesting anything buried deep inside the lib folder. When needed, though, it is still possible for client code using the Pond library to import internal types from @actyx/pond/lib/someModule/....

We hope this release gives a much improved development experience in your favorite IDE. In case it does not, let us know!