Add first class Javascript/Typescript support to the Mill build tool #4127 (#4187)

This pr implements the examples for jslib/dependencies.

#3927

Checklist:
- [x] **example/jslib/dependencies**
     - [x]  1-npm-deps/
     - [x]  2-unmanaged-packages/
     - [x]  3-downloading-unmanaged-packages/
- [x] 4-repository-config/: examples of how to use alternate NPM mirrors
or repositories

Author: monyedavid

docs/modules/ROOT/pages/javascriptlib/dependencies.adoc

@@ -0,0 +1,22 @@
+= Typescript Library Dependencies
+
+include::partial$gtag-config.adoc[]
+
+This page goes into more detail about configuring third party dependencies
+for `TypescriptModule`s.
+
+== Adding Dependencies
+
+include::partial$example/javascriptlib/dependencies/1-npm-deps.adoc[]
+
+== Unmanaged Packages
+
+include::partial$example/javascriptlib/dependencies/2-unmanaged-packages.adoc[]
+
+== Downloading Unmanaged Packages
+
+include::partial$example/javascriptlib/dependencies/3-downloading-unmanaged-packages.adoc[]
+
+== Using Custom or Private Registries
+
+include::partial$example/javascriptlib/dependencies/4-repository-config.adoc[]

example/javascriptlib/dependencies/1-npm-deps/build.mill

@@ -0,0 +1,16 @@
+package build
+import mill._, javascriptlib._
+
+object foo extends TypeScriptModule {
+  def npmDeps = Seq("[email protected]")
+  def npmDevDeps = Seq("@types/[email protected]")
+}
+
+// You can define `npmDeps` field to add dependencies to your module and
+// define `npmDevDeps` field to add dev dependencies to your module, which will be installed
+// via configured registry.
+
+/** Usage
+> mill foo.run e b k a l m o p
+Sorted with lodash: [a,b,e,k,l,m,o,p]
+*/

example/javascriptlib/dependencies/1-npm-deps/foo/src/foo.ts

@@ -0,0 +1,4 @@
+import {sortBy} from 'node_modules/lodash'
+
+const args = process.argv.slice(2);
+console.log(`Sorted with lodash: [${sortBy(args).join(",")}]`);

example/javascriptlib/dependencies/2-unmanaged-packages/build.mill

@@ -0,0 +1,23 @@
+package build
+import mill._, javascriptlib._
+
+object foo extends TypeScriptModule {
+  def unmanagedDeps = Seq.from(os.list(millSourcePath / "lib").map(PathRef(_)))
+}
+
+// You can override `unmanagedDeps` to point to a
+// source distribution .tar.gz you place on the
+// filesystem, e.g. in the above snippet any files that happen to live in the
+// `lib/` folder.
+
+// Note:
+// When installing from a .tgz file, Node.js and npm determine the package name
+// and how to import it from the package.json file inside the .tgz archive.
+
+// For more info on `package.json`, see: https://docs.npmjs.com/cli/v10/configuring-npm/package-json?v=true&utm_source=chatgpt.com
+// For more info on creating unmanaged dependecies, see: https://docs.npmjs.com/cli/v10/commands/npm-pack
+
+/** Usage
+> mill foo.run e b k a l m o p
+Sorted with lodash: [a,b,e,k,l,m,o,p]
+*/

example/javascriptlib/dependencies/2-unmanaged-packages/foo/lib/lodash-4.17.21.tgz

@@ -0,0 +1,4 @@
+import {sortBy} from 'node_modules/lodash'
+
+const args = process.argv.slice(2);
+console.log(`Sorted with lodash: [${sortBy(args).join(",")}]`);

example/javascriptlib/dependencies/2-unmanaged-packages/foo/src/foo.ts

@@ -0,0 +1,34 @@
+// You can also override `unmanagedDeps` to point it at wheels that you want to
+// download from arbitrary URLs.
+// `requests.get` comes from the https://github.com/com-lihaoyi/requests-scala[Requests-Scala]
+// library, one of Mill's xref:fundamentals/bundled-libraries.adoc[Bundled Libraries].
+//
+package build
+import mill._, javascriptlib._
+
+object foo extends TypeScriptModule {
+  def unmanagedDeps = Task {
+    val name = "lodash-4.17.21.tgz"
+    val url = "https://github.com/lodash/lodash/archive/refs/tags/4.17.21.tar.gz"
+    os.write(Task.dest / name, requests.get.stream(url))
+    Seq(PathRef(Task.dest / name))
+  }
+}
+
+/** Usage
+> mill foo.run e b k a l m o p
+Sorted with lodash: [a,b,e,k,l,m,o,p]
+*/
+
+// Tasks like `unmanagedDeps` and `npmDeps` are cached, so your package is downloaded only
+// once and re-used indefinitely after that. This is usually not a problem, because usually URLs
+// follow the rule that https://www.w3.org/Provider/Style/URI[Cool URIs don't change], and so files
+// downloaded from the same URL will always contain the same contents.
+
+// NOTE: An unmanaged depedencies downloaded via `requests.get` is still unmanaged: even though you
+// downloaded it from somewhere, `requests.get` does not know how to pull in third party
+// dependencies or de-duplicate different versions.
+
+// In case you **do** want mill to take care of managing dependencies of a package,
+// you shouldn't get that package in `unmanagedDeps` (like we did in the
+// example above). Instead, you can declare the dependency as a regular `npmDeps` and `npmDevDeps`

example/javascriptlib/dependencies/3-downloading-unmanaged-packages/build.mill

@@ -0,0 +1,4 @@
+import {sortBy} from 'node_modules/lodash'
+
+const args = process.argv.slice(2);
+console.log(`Sorted with lodash: [${sortBy(args).join(",")}]`);

example/javascriptlib/dependencies/3-downloading-unmanaged-packages/foo/src/foo.ts

@@ -0,0 +1,7 @@
+registry=https://registry.npmmirror.com
+
+# Use scoped private/alternative & set authentication
+# @private/package-name:registry=private.repo.com/:_authToken=your-auth-token
+
+# Optional:  on private/alternative registry
+# .../:_authToken=your-auth-token

example/javascriptlib/dependencies/4-repository-config/.npmrc

@@ -0,0 +1,31 @@
+package build
+import mill._, javascriptlib._
+
+object foo extends TypeScriptModule {
+  def npmDeps = Seq("[email protected]")
+  def npmDevDeps = Seq("@types/[email protected]")
+}
+
+// Mill uses https://registry.npmjs.org to find and install dependencies.
+//
+// === Alternate/Private registries
+//
+// You can configure registries via a `.npmrc` file in project root.
+// For more information on npmrc see: https://docs.npmjs.com/cli/v9/configuring-npm/npmrc.
+// The example below uses the alternate registry https://registry.npmmirror.com
+
+/** Usage
+
+> mill foo.run e b k a l m o p
+Sorted with lodash: [a,b,e,k,l,m,o,p]
+....
+{
+  version: '4.17.21',
+  resolved: 'https://registry.npmmirror.com/lodash/-/lodash-4.17.21.tgz',
+  integrity: ...,
+...
+}
+
+> cd out/foo/npmInstall.dest && npm config get registry
+https://registry.npmmirror.com
+*/