meteor - What does api.imply do?

Question

From the Meteor docs:

Give users of this package access to another package (by passing in the string packagename) or a collection of packages (by passing in an array of strings [packagename1, packagename2]).

I have no idea what it means.
From this question I know that imply can be employed with use.

What does api.imply do?
What's exactly the difference between api.use and api.imply?

Answer 1

api.use gives a package access to other packages exported symbols.

For example you need to api.use("random") (see how it's done in the accounts-base package) if you want to use the Random symbol in a package code (see how the random package.js is api.exporting Random).

However, meteor adding accounts-base wouldn't give your whole application access to its used packages (random in this case). If your app needs random, you'd still need to meteor add it.

---

api.imply on the other hand, gives the whole application access to that package exported symbols.

For example, see how accounts-google is api.implying accounts-base.

accounts-base is responsible for exporting the Accounts symbol, when you meteor add accounts-google, not only does accounts-base is also added in your application dependencies, but accounts-base symbols are also made available in your app, specifically because it was implied.

---

accounts-base is both using Accounts in its own code (api.use) and exporting its dependencies symbols to the whole app (api.imply).

api.imply can be used to make "shadow packages" that are just pulling in some other packages.

For example, at some point MDG renamed the showdown package to markdown, they could just have stated to meteor remove showdown && meteor add markdown, but it would have required some actions on end users.

What they did instead is keeping the showdown package and just make it implying the new markdown package.