feat: support offline mode (#457)

closes #456

bin/install.js

@@ -70,6 +70,7 @@ Object.assign(argv, parseArgs(originalArgv, {
     'save-dependencies-tree',
     'force-link-latest',
     'workspaces',
+    'offline',
   ],
   default: {
     optional: true,
@@ -142,6 +143,7 @@ Options:
   --prune: prune unnecessary files from ./node_modules, such as markdown, typescript source files, and so on.
   --dependencies-tree: install with dependencies tree to restore the last install.
   --force-link-latest: force link latest version package to module root path.
+  --offline: offline mode. If a package won't be found locally, the installation will fail.
 `
   );
   process.exit(0);
@@ -313,6 +315,7 @@ debug('argv: %j, env: %j', argv, env);
     config.detail = true;
   }
   config.client = argv.client;
+  config.offline = !!argv.offline;
 
   if (argv['tarball-url-mapping']) {
     const tarballUrlMapping = JSON.parse(argv['tarball-url-mapping']);
@@ -352,6 +355,10 @@ debug('argv: %j, env: %j', argv, env);
     }
   });
 
+  if (config.offline) {
+    console.warn(chalk.yellow('npminstall WARN running on offline mode'));
+  }
+
   // -g install to npm's global prefix
   if (argv.global) {
     // support custom prefix for global install

lib/download/npm.js

@@ -1,13 +1,13 @@
 const debug = require('node:util').debuglog('npminstall:download:npm');
-const bytes = require('bytes');
 const { randomUUID } = require('node:crypto');
 const { createWriteStream, createReadStream, rmSync } = require('node:fs');
 const fs = require('node:fs/promises');
 const path = require('node:path');
 const crypto = require('node:crypto');
-const urlresolve = require('node:url').resolve;
+const { resolve: urlresolve } = require('node:url');
 const zlib = require('node:zlib');
 const os = require('node:os');
+const bytes = require('bytes');
 const tar = require('tar');
 const destroy = require('destroy');
 const chalk = require('chalk');
@@ -181,6 +181,10 @@ async function removeCacheInfo(fullname, globalOptions) {
 
 async function getFullPackageMeta(fullname, globalOptions) {
   const info = await _getCacheInfo(fullname, globalOptions);
+  if (globalOptions.offline && !info.cache) {
+    throw new Error(`Can\'t find package ${fullname} manifests on offline mode`);
+  }
+
   if (!info.cacheFile) {
     const result = await _fetchFullPackageMeta(info.pkgUrl, globalOptions);
     return result.data;
@@ -190,7 +194,8 @@ async function getFullPackageMeta(fullname, globalOptions) {
     return await _fetchFullPackageMetaWithCache(info.pkgUrl, globalOptions, info.cacheFile);
   }
   // check is expired or not
-  if (info.cache.expired > Date.now()) {
+  // offline should force to use cache manifests
+  if (globalOptions.offline || info.cache.expired > Date.now()) {
     globalOptions.totalCacheJSONCount += 1;
     return info.cache.manifests;
   }

lib/local_install.js

@@ -43,6 +43,7 @@ const { runLifecycleScripts } = require('./lifecycle_scripts');
  *  - {Boolean} [trace] - show memory and cpu usages traces of installation
  *  - {Boolean} [flatten] - flatten dependencies by matching ancestors' dependencies
  *  - {Boolean} [disableFallbackStore] - disable fallback store, default is `false`
+ *  - {Boolean} [offline] - offline mode, default is `false`
  * @param {Object} context - install context
  */
 module.exports = async (options, context = new Context()) => {

test/fixtures/install-offline/index.js

@@ -0,0 +1,6 @@
+'use strict';
+
+console.log(
+  require.resolve('koa'),
+  !!require('koa')
+);

test/fixtures/install-offline/package.json

@@ -0,0 +1,14 @@
+{
+  "name": "install-offline",
+  "version": "1.0.0",
+  "scripts": {
+    "postinstall": "node index.js"
+  },
+  "dependencies": {
+    "debug": "~2.2.0",
+    "koa": "^1.1.2"
+  },
+  "devDependencies": {
+    "co": "^4.6.0"
+  }
+}

test/install-offline.test.js

@@ -0,0 +1,56 @@
+const path = require('node:path');
+const coffee = require('coffee');
+const helper = require('./helper');
+
+describe('test/install-offline.test.js', () => {
+  const [ homedir, cleanupTmp ] = helper.tmp();
+  const demo = helper.fixtures('install-offline');
+  const cleanupModules = helper.cleanup(demo);
+
+  async function cleanup() {
+    await cleanupModules();
+    await cleanupTmp();
+  }
+
+  beforeEach(cleanup);
+  afterEach(cleanup);
+
+  it('should install fail when cache manifests not exists', async () => {
+    await coffee.fork(helper.npminstall, [ '--offline' ], {
+      cwd: demo,
+      env: Object.assign({}, process.env, {
+        npm_config_cache: path.join(homedir, 'foocache/.npminstall_tarball'),
+      }),
+    })
+      .debug()
+      .expect('code', 1)
+      .expect('stderr', /Can\'t find package .+? manifests on offline mode/)
+      .end();
+  });
+
+  it('should install success when cache manifests exists', async () => {
+    await coffee.fork(helper.npminstall, [ '-d' ], {
+      cwd: demo,
+      env: Object.assign({}, process.env, {
+        npm_config_cache: path.join(homedir, 'foocache/.npminstall_tarball'),
+      }),
+    })
+      .debug()
+      .expect('code', 0)
+      .expect('stdout', /All packages installed/)
+      .end();
+
+    await cleanupModules();
+    await coffee.fork(helper.npminstall, [ '-d', '--offline' ], {
+      cwd: demo,
+      env: Object.assign({}, process.env, {
+        npm_config_cache: path.join(homedir, 'foocache/.npminstall_tarball'),
+      }),
+    })
+      .debug()
+      .expect('code', 0)
+      .expect('stdout', /All packages installed/)
+      .expect('stdout', /speed 0B\/s, json 0\(0B\), tarball 0B, manifests cache hit \d+, etag hit 0 \/ miss 0/)
+      .end();
+  });
+});