@hyperfrontend/versioning/registry/npm

npm

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 escapePackageVersion 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

§function

createCache(ttl: number): Cache

Creates a new cache instance.

Parameters

Name	Type	Description
§ttl	`number`	Time-to-live in milliseconds (default: 60000 = 1 minute) (default: `60000`)

Returns

Cache

A 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')

§function

createNpmRegistry(config: RegistryConfig): Registry

Creates an npm registry client.

Parameters

Name	Type	Description
§config	`RegistryConfig`	Registry configuration (default: `{}`)

Returns

Registry

A Registry implementation for npm

Example

Creating an npm registry client
const registry = createNpmRegistry()
const version = await registry.getLatestVersion('@hyperfrontend/utils')

§function

escapePackageName(name: string): string

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

string

Safe package name

Example

Validating package names for shell safety

escapePackageName('@scope/package') // => '@scope/package'
escapePackageName('simple-pkg') // => 'simple-pkg'
escapePackageName('pkg$invalid') // throws - '$' is invalid

§function

escapeVersion(version: string): string

Escapes a version string for safe use in shell commands.

Parameters

Name	Type	Description
§version	`string`	Version string to escape

Returns

string

Safe 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

§interface

Cache

Simple in-memory cache with TTL support.

Properties

§interface

CacheEntry

Cache entry with data and expiration time.

Properties

§readonly data:T—

Cached data

§readonly timestamp:number—

Timestamp when entry was created