npm

Modern npm packages usually expose their functionality as ESM modules.

To use such a package, access it through the npm global:

• The package's default export is exposed directly.
  For instance, npm.chalk returns the default export of the chalk package.
• The package's named exports are exposed as properties.
  For instance, npm.telegram.TelegramClient returns the TelegramClient export of the telegram package.

sample Use the boxen package's default export

cli.tell(npm.boxen(" Hello! "));
/*            ┌────────┐
   Displays:  │ Hello! │
              └────────┘ */

sample Use the “length” named export of the stringz package

cli.tell(npm.stringz.length("👩🏿‍💻 Contributing"));
// Displays “14”

In rare cases, there can be collisions between injected named exports, and default export properties. See Accessing shadowed default export properties for a solution.

Many other packages, including older ones, expose their functionality as CommonJS modules.

You can use these packages in the same way as ESM-based packages, by accessing them directly on the npm global.

sample Use the dedupe package

const friendNames = await cli.ask('What are your friends called?', Array);
const uniqueFriendNames = npm.dedupe(friendNames);

cli.tell('Total count of unique friend names: ' + uniqueFriendNames.length);

If a package has conflicting ESM and CommonJS exports, Tasklemon will return the ESM export.

If your script needs a specific version of a package, you can add a package version directive at the top of your script.
Add the directive below the shebang, if any, and above the script's code.

sample Specify which version of username to use

// tl:require: username@5.0.0

cli.tell('Hello, ' + await npm.username() + '!');

It's a good idea to do this, to ensure your script's behavior stays the same over time, even after new versions of the packages are released. To have Tasklemon automatically add a tl:require directive for all the packages used by your script, setting them to their latest available version, you can use the --pin-pkg command-line action.

sample Automatically add version directives to a script

$ lemon --pin-pkg script.js

To access a package with special characters in its name, such as a scoped package, use bracket notation.

sample Use the UUID package from Allthings

const uuid = npm['@allthings/uuid'];
cli.tell('New unique identifier: ' + uuid());

If your script needs to use a specific sub-file of a package, rather than the package's main file, you can specify the file's path, separated by a colon.

sample Use the v4 mode of the uuid package

const uuid = npm['uuid:v4'];
cli.tell('New unique identifier: ' + uuid());

Most of the time, when using ESM packages, there is no collision between named exports, and properties on the default export.
However, if you do need to access a property that's been shadowed, you can do so through the raw default export, accessible as the unmodifiedDefaultExport property.

For example, consider a package named contrivedExample. Its default export has an ambiguousLabel property; and one of its named exports happens to be named ambiguousLabel as well. In this situation:

• npm.contrivedExample.ambiguousLabel returns the ambiguousLabel named export.
• npm.contrivedExample.unmodifiedDefaultExport.ambiguousLabel returns the ambiguousLabel property of the default export.

In order to ensure a script can execute offline, and without any download delays, you can ask Tasklemon to preload all of the script's required packages. These include packages you implicitely require, not just the packages pinned by version directives.
This has no purpose for a script that's been run at least once, since Tasklemon will already have downloaded its packages.

sample Preload the packages used by a script

$ lemon --preload-pkg script.js

Tasklemon's package cache is generally very resilient, and can recover from most download and installation issues. If something seems broken, however, you can try emptying the package cache.

sample Empty the package cache

$ lemon --clear-pkg-cache