@hyperfrontend/versioning/registry/npmnpm
NPM registry client: fetches package metadata from a registry endpoint with in-memory caching and safe URL encoding.
createNpmRegistry(config) returns a registry binding that resolves packages via the standard https://registry.npmjs.org/<package> API. escapePackageName and escapeVersion produce URL-safe path segments for scoped packages and prerelease tags. The cache (createCache, Cache, CacheEntry) is a small TTL-bound in-memory store so repeated lookups within a release flow do not refetch the same package metadata.
API Reference§
ƒ Functions
Decides whether a failed
Only a 404 from the registry proves absence, and npm reports both a missing package and a missing version that way. Every other outcome, including a timeout that produces no output at all, leaves the published state unknown and must not be read as "not published".
npm view proves absence or leaves the answer unknown. Only a 404 from the registry proves absence, and npm reports both a missing package and a missing version that way. Every other outcome, including a timeout that produces no output at all, leaves the published state unknown and must not be read as "not published".
Parameters
| Name | Type | Description |
|---|---|---|
§error | unknown | The error thrown by the invocation |
Returns
NpmLookupFailureWhether the package is absent, or why the registry could not answer
Example
Classifying a lookup failure
try {
execFileSync('npm', ['view', name, 'version'])
} catch (error) {
const failure = classifyNpmError(error)
if (failure.kind === 'absent') return null
throw createRegistryUnavailableError({ ...failure, packageName: name })
}Creates a new cache instance.
Parameters
| Name | Type | Description |
|---|---|---|
§ttl | number | Time-to-live in milliseconds (default: 60000 = 1 minute)(default: 60000) |
Returns
CacheA new Cache instance
Example
Using a cache with custom TTL
const cache = createCache(30000) // 30 second TTL
cache.set('key', { data: 'value' })
const value = cache.get<{ data: string }>('key')Creates an npm registry client.
Parameters
| Name | Type | Description |
|---|---|---|
§config | RegistryConfig | Registry configuration(default: {}) |
Returns
RegistryA Registry implementation for npm
Example
Creating an npm registry client
const registry = createNpmRegistry()
const version = await registry.getLatestVersion('@hyperfrontend/utils')Escapes a package name for safe use in shell commands. Uses character-by-character validation to prevent injection.
Parameters
| Name | Type | Description |
|---|---|---|
§name | string | Package name to escape |
Returns
stringSafe package name
Example
Validating package names for shell safety
escapePackageName('@scope/package') // => '@scope/package'
escapePackageName('simple-pkg') // => 'simple-pkg'
escapePackageName('pkg$invalid') // throws - '$' is invalidEscapes a version string for safe use in shell commands.
Parameters
| Name | Type | Description |
|---|---|---|
§version | string | Version string to escape |
Returns
stringSafe version string
Example
Validating version strings for shell safety
escapeVersion('1.2.3') // => '1.2.3'
escapeVersion('1.0.0-beta.1') // => '1.0.0-beta.1'
escapeVersion('1.0.0+build') // => '1.0.0+build'◈ Interfaces
◆ Types
Outcome of a failed
npm view invocation.type NpmLookupFailure = AbsentLookupFailure | UnavailableLookupFailure