perf: lazy-load heavy external imports across modules

Defer loading of heavy external sub-bundles until first use via lazy
require() getters with /*@__PURE__*/ and /*@__NO_SIDE_EFFECTS__*/
annotations for tree-shaking.

sorts.ts: semver (2.5 MB via npm-pack) and fastSort (8 KB)
versions.ts: semver (2.5 MB via npm-pack)
archives.ts: adm-zip (102 KB) and tar-fs (105 KB)
globs.ts: fast-glob and picomatch (260 KB via pico-pack)
fs.ts: del (260 KB via pico-pack)
spawn.ts: @npmcli/promise-spawn (17 KB)
strings.ts: get-east-asian-width (10 KB)

Impact: consumers importing lightweight exports (isObject, httpJson,
localeCompare, defaultIgnore, readJsonSync, stripAnsi, spawnSync) no
longer pay for heavy externals at module init time. Total deferred:
~494 KB unique, ~2.8 MB including npm-pack chain.

Author: jdalton

src/archives.ts

@@ -8,8 +8,26 @@ import { pipeline } from 'node:stream/promises'
 import { createGunzip } from 'node:zlib'
 import process from 'node:process'
 
-import AdmZip from './external/adm-zip.js'
-import tarFs from './external/tar-fs.js'
+import type AdmZipType from './external/adm-zip.js'
+import type tarFsType from './external/tar-fs.js'
+
+let _AdmZip: typeof AdmZipType | undefined
+/*@__NO_SIDE_EFFECTS__*/
+function getAdmZip() {
+  if (_AdmZip === undefined) {
+    _AdmZip = /*@__PURE__*/ require('./external/adm-zip.js')
+  }
+  return _AdmZip!
+}
+
+let _tarFs: typeof tarFsType | undefined
+/*@__NO_SIDE_EFFECTS__*/
+function getTarFs() {
+  if (_tarFs === undefined) {
+    _tarFs = /*@__PURE__*/ require('./external/tar-fs.js')
+  }
+  return _tarFs!
+}
 
 import { safeMkdir } from './fs.js'
 import { normalizePath } from './paths/normalize.js'
@@ -142,7 +160,7 @@ export async function extractTar(
 
   let destroyScheduled = false
 
-  const extractStream = tarFs.extract(normalizedOutputDir, {
+  const extractStream = getTarFs().extract(normalizedOutputDir, {
     map: (header: { name: string; size?: number; type?: string }) => {
       // Skip if destroy already scheduled
       if (destroyScheduled) {
@@ -267,7 +285,7 @@ export async function extractTarGz(
 
   let destroyScheduled = false
 
-  const extractStream = tarFs.extract(normalizedOutputDir, {
+  const extractStream = getTarFs().extract(normalizedOutputDir, {
     map: (header: { name: string; size?: number; type?: string }) => {
       // Skip if destroy already scheduled
       if (destroyScheduled) {
@@ -387,7 +405,7 @@ export async function extractZip(
   const normalizedOutputDir = normalizePath(outputDir)
   await safeMkdir(normalizedOutputDir)
 
-  const zip = new AdmZip(archivePath)
+  const zip = new (getAdmZip())(archivePath)
   const path = getPath()
 
   // Pre-validate all entries for security

src/fs.ts

@@ -19,7 +19,21 @@ import type {
 import { getAbortSignal } from './constants/process'
 
 import { isArray } from './arrays'
-import { deleteAsync, deleteSync } from './external/del'
+import type {
+  deleteAsync as deleteAsyncType,
+  deleteSync as deleteSyncType,
+} from './external/del'
+
+let _del:
+  | { deleteAsync: typeof deleteAsyncType; deleteSync: typeof deleteSyncType }
+  | undefined
+/*@__NO_SIDE_EFFECTS__*/
+function getDel() {
+  if (_del === undefined) {
+    _del = /*@__PURE__*/ require('./external/del')
+  }
+  return _del!
+}
 import { pRetry } from './promises'
 import { defaultIgnore, getGlobMatcher } from './globs'
 import type { JsonReviver } from './json/types'
@@ -1235,7 +1249,7 @@ export async function safeDelete(
   filepath: PathLike | PathLike[],
   options?: RemoveOptions | undefined,
 ) {
-  // deleteAsync is imported at the top
+  // deleteAsync is lazily loaded via getDel()
   const opts = { __proto__: null, ...options } as RemoveOptions
   const patterns = isArray(filepath)
     ? filepath.map(pathLikeToString)
@@ -1278,7 +1292,7 @@ export async function safeDelete(
   /* c8 ignore start - External del call */
   await pRetry(
     async () => {
-      await deleteAsync(patterns, {
+      await getDel().deleteAsync(patterns, {
         dryRun: false,
         force: shouldForce,
         onlyFiles: false,
@@ -1328,7 +1342,7 @@ export function safeDeleteSync(
   filepath: PathLike | PathLike[],
   options?: RemoveOptions | undefined,
 ) {
-  // deleteSync is imported at the top
+  // deleteSync is lazily loaded via getDel()
   const opts = { __proto__: null, ...options } as RemoveOptions
   const patterns = isArray(filepath)
     ? filepath.map(pathLikeToString)
@@ -1373,7 +1387,7 @@ export function safeDeleteSync(
   let delay = retryDelay
   for (let attempt = 0; attempt <= maxRetries; attempt++) {
     try {
-      deleteSync(patterns, {
+      getDel().deleteSync(patterns, {
         dryRun: false,
         force: shouldForce,
         onlyFiles: false,

src/globs.ts

@@ -3,9 +3,26 @@
  * Provides file filtering and glob matcher functions for npm-like behavior.
  */
 
-// IMPORTANT: Do not use destructuring here - use direct assignment instead.
-import * as fastGlob from './external/fast-glob.js'
-import picomatch from './external/picomatch.js'
+import type * as fastGlobType from './external/fast-glob.js'
+import type picomatchType from './external/picomatch.js'
+
+let _fastGlob: typeof fastGlobType | undefined
+/*@__NO_SIDE_EFFECTS__*/
+function getFastGlob() {
+  if (_fastGlob === undefined) {
+    _fastGlob = /*@__PURE__*/ require('./external/fast-glob.js')
+  }
+  return _fastGlob!
+}
+
+let _picomatch: typeof picomatchType | undefined
+/*@__NO_SIDE_EFFECTS__*/
+function getPicomatch() {
+  if (_picomatch === undefined) {
+    _picomatch = /*@__PURE__*/ require('./external/picomatch.js')
+  }
+  return _picomatch!
+}
 
 import { objectFreeze as ObjectFreeze } from './objects'
 import {
@@ -112,7 +129,7 @@ export function globStreamLicenses(
     ignore.push(LICENSE_ORIGINAL_GLOB_RECURSIVE)
   }
   /* c8 ignore start - External fast-glob call */
-  return fastGlob.globStream(
+  return getFastGlob().globStream(
     [recursive ? LICENSE_GLOB_RECURSIVE : LICENSE_GLOB],
     {
       __proto__: null,
@@ -189,7 +206,7 @@ export function getGlobMatcher(
   }
 
   /* c8 ignore next 4 - External picomatch call */
-  matcher = picomatch(
+  matcher = getPicomatch()(
     positivePatterns.length > 0 ? positivePatterns : patterns,
     matchOptions,
   ) as (path: string) => boolean
@@ -209,7 +226,7 @@ export function glob(
   options?: FastGlobOptions,
 ): Promise<string[]> {
   /* c8 ignore next - External fast-glob call */
-  return fastGlob.glob(patterns, options as import('fast-glob').Options)
+  return getFastGlob().glob(patterns, options as import('fast-glob').Options)
 }
 
 /**
@@ -222,5 +239,8 @@ export function globSync(
   options?: FastGlobOptions,
 ): string[] {
   /* c8 ignore next - External fast-glob call */
-  return fastGlob.globSync(patterns, options as import('fast-glob').Options)
+  return getFastGlob().globSync(
+    patterns,
+    options as import('fast-glob').Options,
+  )
 }

src/sorts.ts

@@ -3,17 +3,34 @@
  * Provides various comparison utilities for arrays and collections.
  */
 
-import * as fastSort from './external/fast-sort.js'
-import * as semver from './external/semver.js'
+import type * as fastSortType from './external/fast-sort.js'
+import type * as semverType from './external/semver.js'
+
+let _semver: typeof semverType | undefined
+function getSemver() {
+  if (_semver === undefined) {
+    _semver = require('./external/semver.js')
+  }
+  return _semver!
+}
+
+let _fastSort: typeof fastSortType | undefined
+function getFastSort() {
+  if (_fastSort === undefined) {
+    _fastSort = require('./external/fast-sort.js')
+  }
+  return _fastSort!
+}
 
 /**
  * Compare semantic versions.
  */
 /*@__NO_SIDE_EFFECTS__*/
 export function compareSemver(a: string, b: string): number {
   /* c8 ignore next 2 - External semver calls */
-  const validA: string | null = semver.valid(a)
-  const validB: string | null = semver.valid(b)
+  const sv = getSemver()
+  const validA: string | null = sv.valid(a)
+  const validB: string | null = sv.valid(b)
 
   if (!validA && !validB) {
     return 0
@@ -25,7 +42,7 @@ export function compareSemver(a: string, b: string): number {
     return 1
   }
   /* c8 ignore next - External semver call */
-  return semver.compare(a, b) as number
+  return sv.compare(a, b) as number
 }
 
 /**
@@ -90,7 +107,7 @@ export function naturalSorter<T>(
 ): ReturnType<FastSortFunction> {
   if (_naturalSorter === undefined) {
     /* c8 ignore next 3 - External fast-sort call */
-    _naturalSorter = fastSort.createNewSortInstance({
+    _naturalSorter = getFastSort().createNewSortInstance({
       comparer: naturalCompare,
     }) as FastSortFunction
   }

src/spawn.ts

@@ -30,7 +30,16 @@ import process from 'node:process'
 import { getAbortSignal } from './constants/process'
 import { stackWithCauses } from './errors'
 
-import npmCliPromiseSpawn from './external/@npmcli/promise-spawn'
+import type npmCliPromiseSpawnType from './external/@npmcli/promise-spawn'
+
+let _npmCliPromiseSpawn: typeof npmCliPromiseSpawnType | undefined
+/*@__NO_SIDE_EFFECTS__*/
+function getNpmCliPromiseSpawn() {
+  if (_npmCliPromiseSpawn === undefined) {
+    _npmCliPromiseSpawn = /*@__PURE__*/ require('./external/@npmcli/promise-spawn')
+  }
+  return _npmCliPromiseSpawn!
+}
 
 let _path: typeof import('node:path') | undefined
 /**
@@ -738,7 +747,7 @@ export function spawn(
   if (shouldStopSpinner) {
     spinnerInstance.stop()
   }
-  // npmCliPromiseSpawn is imported at the top
+  // npmCliPromiseSpawn is lazily loaded via getNpmCliPromiseSpawn()
   // Use __proto__: null to prevent prototype pollution when passing to
   // third-party code, Node.js built-ins, or JavaScript built-in methods.
   // https://github.com/npm/promise-spawn
@@ -769,10 +778,10 @@ export function spawn(
     gid: spawnOptions.gid,
   } as unknown as PromiseSpawnOptions
   /* c8 ignore start - External npmCliPromiseSpawn call */
-  const spawnPromise = npmCliPromiseSpawn(
+  const spawnPromise = getNpmCliPromiseSpawn()(
     actualCmd,
     args ? [...args] : [],
-    promiseSpawnOpts as Parameters<typeof npmCliPromiseSpawn>[2],
+    promiseSpawnOpts as Parameters<typeof npmCliPromiseSpawnType>[2],
     extra,
   )
   /* c8 ignore stop */

src/strings.ts

@@ -4,7 +4,20 @@
  */
 
 import { ansiRegex, stripAnsi } from './ansi'
-import { eastAsianWidth } from './external/get-east-asian-width'
+import type { eastAsianWidth as eastAsianWidthType } from './external/get-east-asian-width'
+
+let _eastAsianWidth: typeof eastAsianWidthType | undefined
+/*@__NO_SIDE_EFFECTS__*/
+function getEastAsianWidth() {
+  if (_eastAsianWidth === undefined) {
+    _eastAsianWidth = /*@__PURE__*/ (
+      require('./external/get-east-asian-width') as {
+        eastAsianWidth: typeof eastAsianWidthType
+      }
+    ).eastAsianWidth
+  }
+  return _eastAsianWidth!
+}
 // Import get-east-asian-width from external wrapper.
 // This library implements Unicode Standard Annex #11 (East Asian Width).
 // https://www.unicode.org/reports/tr11/
@@ -736,7 +749,7 @@ export function stringWidth(text: string): number {
     // - Halfwidth (1 column): Halfwidth Katakana (ｱ, ｲ, ｳ)
     // - Ambiguous (1 column per our config): Greek, Cyrillic, box drawing
     /* c8 ignore next - External eastAsianWidth call */
-    width += eastAsianWidth(codePoint, eastAsianWidthOptions)
+    width += getEastAsianWidth()(codePoint, eastAsianWidthOptions)
 
     // STEP 4: Handle trailing Halfwidth and Fullwidth Forms
     //
@@ -770,7 +783,10 @@ export function stringWidth(text: string): number {
             // Add the East Asian Width of this trailing character.
             // Most halfwidth forms contribute 1 column, fullwidth contribute 2.
             /* c8 ignore next - External eastAsianWidth call */
-            width += eastAsianWidth(trailingCodePoint, eastAsianWidthOptions)
+            width += getEastAsianWidth()(
+              trailingCodePoint,
+              eastAsianWidthOptions,
+            )
           }
         }
       }