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.
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
Pond declares our public API, but the implementation you get ahold of by calling
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
d.ts files. But it would be pretty tedious for us to go through all symbols in the Pond and
@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
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
folder. When needed, though, it is still possible for client code using the Pond library to import
internal types from
We hope this release gives a much improved development experience in your favorite IDE. In case it does not, let us know!