npm_install_helpers.ts

view source

Declarations
#

7 declarations

install_with_cache_healing
#

npm_install_helpers.ts view source

(pm_cli: string, options?: InstallCacheHealingOptions): Promise<NpmCommandResult> import {install_with_cache_healing} from '@fuzdev/gro/npm_install_helpers.js';

Installs dependencies, self-healing the stale-cache (ETARGET) failure mode.

Strategy:

  1. First attempt: ${pm_cli} install [...install_args].
  2. On an npm ETARGET-class failure (stale cache): npm cache clean --force then retry the same install once.
  3. On any other failure — or any failure under a non-npm pm_cli — return immediately without healing.

Why ETARGET happens: right after a dependency is published and the registry has propagated, npm's local cache may still hold stale "404"/no-version metadata for it; clearing the cache forces a fresh metadata fetch. This makes installs safe to run immediately after publishing an upstream package — e.g. picking up a just-released dep in a dependency-ordered publish chain, or gro upgrade-ing to a fresh @latest.

npm only: the heal uses npm-specific syntax (cache clean --force), so it's gated on pm_cli === 'npm'. A non-npm pm_cli surfaces the failure unchanged rather than running a command it can't understand.

The env is always passed through sanitize_install_env so the build's devDependencies survive.

pm_cli

the npm-compatible CLI to run (e.g. config.pm_cli)

type string

options

cwd, env, logger, extra install args, and an injectable runner

type InstallCacheHealingOptions
default {}

returns

Promise<NpmCommandResult>

the result of the (possibly retried) install

install_with_cache_healing_or_throw
#

npm_install_helpers.ts view source

(pm_cli: string, options?: InstallCacheHealingOptions & { context?: string | undefined; }): Promise<void> import {install_with_cache_healing_or_throw} from '@fuzdev/gro/npm_install_helpers.js';

install_with_cache_healing that throws a TaskError on failure instead of returning the result — the shape every task callsite wants. The thrown message names the exact command (including install_args), an optional context clause, and the failure detail.

pm_cli

the npm-compatible CLI to run (e.g. config.pm_cli)

type string

options

same as install_with_cache_healing, plus an optional context clause appended after the command (e.g. 'after version bump')

type InstallCacheHealingOptions & { context?: string | undefined; }
default {}

returns

Promise<void>

throws

  • TaskError - when the install fails, even after a cache-heal retry

InstallCacheHealingOptions
#

npm_install_helpers.ts view source

InstallCacheHealingOptions import type {InstallCacheHealingOptions} from '@fuzdev/gro/npm_install_helpers.js';

cwd?

working directory for the install; defaults to the current directory

type string

env?

base env; devDependency-pruning vars are stripped via sanitize_install_env

type NodeJS.ProcessEnv

log?

logger for cache-heal progress

type Logger

run?

injectable command runner for tests; defaults to a live-teeing spawn

type NpmCommandRunner

install_args?

Extra args appended after install, e.g. package specs and flags for gro upgrade (['foo@latest', '--force']) or a single dep for gro changeset (['-D', '@changesets/changelog-git']). The same args are reused on the post-cache-clean retry.

type ReadonlyArray<string>

is_etarget_error
#

npm_install_helpers.ts view source

(message: string, stderr: string): boolean import {is_etarget_error} from '@fuzdev/gro/npm_install_helpers.js';

Checks if an npm install failure is caused by stale cache (ETARGET).

Detects the several shapes npm uses for "the requested version isn't there": code ETARGET, ETARGET, notarget, and No matching version found.

message

the short outcome string (e.g. code 1)

type string

stderr

the captured stderr of the failed command

type string

returns

boolean

true when the failure looks like an ETARGET-class staleness error

NpmCommandResult
#

npm_install_helpers.ts view source

NpmCommandResult import type {NpmCommandResult} from '@fuzdev/gro/npm_install_helpers.js';

Result of one install or cache-clean attempt.

ok

type boolean

stderr

captured stderr; the default runner also tees this live to the terminal

type string

detail

short human-readable outcome, e.g. code 1 or error: spawn ENOENT

type string

NpmCommandRunner
#

npm_install_helpers.ts view source

NpmCommandRunner import type {NpmCommandRunner} from '@fuzdev/gro/npm_install_helpers.js';

Runs an npm-compatible command and reports ok plus captured stderr. Injected by install_with_cache_healing for testing; the default implementation spawns a real subprocess.

(call)

type (command: string, args: readonly string[], options?: { cwd?: string | undefined; env?: ProcessEnv | undefined; } | undefined): Promise<NpmCommandResult>

command

type string

args

type readonly string[]

options?

type { cwd?: string | undefined; env?: ProcessEnv | undefined; } | undefined
optional
returns Promise<NpmCommandResult>

sanitize_install_env
#

npm_install_helpers.ts view source

(env: ProcessEnv): ProcessEnv import {sanitize_install_env} from '@fuzdev/gro/npm_install_helpers.js';

Returns a copy of env with the devDependency-pruning vars removed.

env

the source environment to sanitize

type ProcessEnv

returns

ProcessEnv

a fresh env object; the input is not mutated

Depends on
#

Imported by
#