From af2860e15ce9fca1e70d5af5b7b94e5196e46aea Mon Sep 17 00:00:00 2001 From: Nathan Manceaux-Panot Date: Wed, 22 Jun 2022 18:38:56 +0200 Subject: [PATCH] Docs: (prematurely) add docs for ESM npm support Also tweak the npm docs in general. --- docs/api-reference-source/npm.xml | 109 +++++++++++++++++++++++++----- 1 file changed, 91 insertions(+), 18 deletions(-) diff --git a/docs/api-reference-source/npm.xml b/docs/api-reference-source/npm.xml index f55e43f..d705307 100644 --- a/docs/api-reference-source/npm.xml +++ b/docs/api-reference-source/npm.xml @@ -5,8 +5,12 @@ - The npm object provides access to all npm packages. -

+ The npm object provides access to all npm packages.
+ Both ESM and CommonJS exports are supported. +

+

+ You do not need to import or install the packages you use in any way; Tasklemon will automatically download and inject any package you access. +

]]> @@ -16,11 +20,54 @@
- + - To use a package, simply get it by name from npm's properties. + 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. +
    • +
+

+ + +cli.tell(npm.boxen(" Hello! ")); +/* ┌────────┐ + Displays: │ Hello! │ + └────────┘ */ + + + +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.

@@ -29,19 +76,10 @@ const uniqueFriendNames = npm.dedupe(friendNames); cli.tell('Total count of unique friend names: ' + uniqueFriendNames.length); - -

- You do not need to import or install the packages you use in any way; Tasklemon will automatically install and inject any package you use. -

- To access a package with special characters in its name, use bracket notation. + If a package has conflicting ESM and CommonJS exports, Tasklemon will return the ESM export.

- - -const uuid = npm['@allthings/uuid']; -cli.tell('New unique identifier: ' + uuid()); - ]]> @@ -60,7 +98,7 @@ cli.tell('Hello, ' + await npm.username() + '!');

- It's a good idea to do this, to ensure your script keeps the same behavior over time, even after new versions of the packages are released. + 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.

@@ -70,20 +108,55 @@ $ lemon --pin-pkg script.js ]]> - + + + + To access a package with special characters in its name, such as a scoped package, use bracket notation. +

+ + +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 it by using a colon to separate the package name from the sub-file path. + 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.

- + 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. +
    • +
+

+ ]]> + +