Allow cache add to accept multiple specs

This is a backwards incompatible change to the undocumented
`cache add pkg version`, but

Motivations for this can be found here:
#2976 (comment)

Signed-off-by: Marco Sirabella <marco@sirabella.org>

docs/content/commands/npm-cache.md

@@ -7,10 +7,10 @@ description: Manipulates packages cache
 ### Synopsis
 
 ```bash
-npm cache add <tarball file>
-npm cache add <folder>
-npm cache add <tarball url>
-npm cache add <name>@<version>
+npm cache add <tarball file>...
+npm cache add <folder>...
+npm cache add <tarball url>...
+npm cache add <name>@<version>...
 
 npm cache clean
 aliases: npm cache clear, npm cache rm
@@ -25,7 +25,7 @@ Note: This command is unaware of workspaces.
 Used to add, list, or clean the npm cache folder.
 
 * add:
-  Add the specified package to the local cache.  This command is primarily
+  Add the specified packages to the local cache.  This command is primarily
   intended to be used internally by npm, but it can provide a way to
   add data to the local installation cache explicitly.
 

lib/cache.js

@@ -86,32 +86,30 @@ with --force.`)
     return rimraf(cachePath)
   }
 
-  // npm cache add <tarball-url>
-  // npm cache add <pkg> <ver>
-  // npm cache add <tarball>
-  // npm cache add <folder>
+  // npm cache add <tarball-url>...
+  // npm cache add <pkg> <ver>...
+  // npm cache add <tarball>...
+  // npm cache add <folder>...
   async add (args) {
     const usage = 'Usage:\n' +
-      '    npm cache add <tarball-url>\n' +
-      '    npm cache add <pkg>@<ver>\n' +
-      '    npm cache add <tarball>\n' +
-      '    npm cache add <folder>\n'
+      '    npm cache add <tarball-url>...\n' +
+      '    npm cache add <pkg>@<ver>...\n' +
+      '    npm cache add <tarball>...\n' +
+      '    npm cache add <folder>...\n'
     log.silly('cache add', 'args', args)
-    const spec = args[0] && args[0] +
-      (args[1] === undefined || args[1] === null ? '' : `@${args[1]}`)
-
-    if (!spec)
+    if (args.length === 0)
       throw Object.assign(new Error(usage), { code: 'EUSAGE' })
 
-    log.silly('cache add', 'spec', spec)
-
-    // we ask pacote for the thing, and then just throw the data
-    // away so that it tee-pipes it into the cache like it does
-    // for a normal request.
-    await pacote.tarball.stream(spec, stream => {
-      stream.resume()
-      return stream.promise()
-    }, this.npm.flatOptions)
+    return Promise.all(args.map(spec => {
+      log.silly('cache add', 'spec', spec)
+      // we ask pacote for the thing, and then just throw the data
+      // away so that it tee-pipes it into the cache like it does
+      // for a normal request.
+      return pacote.tarball.stream(spec, stream => {
+        stream.resume()
+        return stream.promise()
+      }, this.npm.flatOptions)
+    }))
   }
 
   async verify () {

test/lib/cache.js

@@ -134,20 +134,21 @@ t.test('cache add pkg only', t => {
   })
 })
 
-t.test('cache add pkg w/ spec modifier', t => {
+t.test('cache add multiple pkgs', t => {
   t.teardown(() => {
     logOutput = []
     tarballStreamSpec = ''
     tarballStreamOpts = {}
   })
 
-  cache.exec(['add', 'mypkg', 'latest'], err => {
+  cache.exec(['add', 'mypkg', 'anotherpkg'], err => {
     t.error(err)
     t.strictSame(logOutput, [
-      ['silly', 'cache add', 'args', ['mypkg', 'latest']],
-      ['silly', 'cache add', 'spec', 'mypkg@latest'],
+      ['silly', 'cache add', 'args', ['mypkg', 'anotherpkg']],
+      ['silly', 'cache add', 'spec', 'mypkg'],
+      ['silly', 'cache add', 'spec', 'anotherpkg'],
     ], 'logs correctly')
-    t.equal(tarballStreamSpec, 'mypkg@latest', 'passes the correct spec to pacote')
+    t.equal(tarballStreamSpec, 'anotherpkg', 'passes the correct spec to pacote')
     t.same(tarballStreamOpts, npm.flatOptions, 'passes the correct options to pacote')
     t.end()
   })