HyperFrontend logoHyperFrontend
← Back to @hyperfrontend/versioning
@hyperfrontend/versioning/registry/models

models

Registry data models: registries themselves, package metadata, version metadata, and maintainer records.

Registry and RegistryConfig describe a configured registry endpoint (URL, scope, auth headers) used by the registry clients. PackageInfo (built via createPackageInfo) carries package-level metadata: name, dist-tags, versions list. VersionInfo (built via createVersionInfo) carries per-version metadata: version string, dependency declarations, dist (tarball + integrity), and Maintainer[]. The factories produce normalized objects regardless of the registry's exact payload shape so downstream code can rely on a single model.

API Reference§

ƒ Functions

§function

createPackageInfo(options: CreatePackageInfoOptions): PackageInfo

Creates a new PackageInfo object.

Parameters

NameTypeDescription
§options
CreatePackageInfoOptions
Configuration for the package info

Returns

PackageInfo
A new PackageInfo object

Example

Creating package info from registry data

const info = createPackageInfo({
  name: '@scope/my-package',
  latestVersion: '2.0.0',
  versions: ['1.0.0', '1.1.0', '2.0.0'],
  license: 'MIT'
})
View source →
§function

createRegistryUnavailableError(details: RegistryUnavailableDetails): RegistryUnavailableError

Creates an error describing a registry that could not answer a lookup.

Parameters

NameTypeDescription
§details
RegistryUnavailableDetails
Which lookup failed, against which registry, and why

Returns

RegistryUnavailableError
An error carrying the failure details

Example

Reporting an unreachable registry

throw createRegistryUnavailableError({
  registry: 'npm',
  packageName: '@scope/pkg',
  operation: 'getLatestVersion',
  reason: 'network',
  detail: 'ECONNREFUSED',
})
View source →
§function

createVersionInfo(options: CreateVersionInfoOptions): VersionInfo

Creates a new VersionInfo object.

Parameters

NameTypeDescription
§options
CreateVersionInfoOptions
Configuration for the release info

Returns

VersionInfo
A new VersionInfo object

Example

Creating version info from registry data

const release = createVersionInfo({
  version: '1.2.3',
  publishedAt: '2024-01-15T10:30:00Z',
  tarball: 'https://registry.npmjs.org/pkg/-/pkg-1.2.3.tgz'
})
View source →
§function

isRegistryUnavailableError(value: unknown): unknown

Checks whether a value is a RegistryUnavailableError.

Parameters

NameTypeDescription
§value
unknown
Value to test, typically a caught error

Returns

unknown
True when the value reports a registry that could not answer

Example

Distinguishing an unreachable registry from other failures

try {
  await registry.getLatestVersion('@scope/pkg')
} catch (error) {
  if (isRegistryUnavailableError(error)) {
    logger.error(error.message)
  }
}
View source →

◈ Interfaces

§interface

Maintainer

Maintainer information.

Properties

§readonly email?:string
Maintainer email
§readonly name:string
Maintainer name
View source →
§interface

PackageInfo

Package information from a registry.

Properties

§readonly description?:string
Package description
§readonly homepage?:string
Homepage URL
§readonly keywords?:unknown
Keywords
§readonly lastModified?:string
Time of last modification
§readonly latestVersion:string
Latest version
§readonly license?:string
SPDX license identifier
§readonly maintainers:unknown
Package maintainers
§readonly name:string
Package name
§readonly repository?:string
Repository URL
§readonly versions:unknown
All published versions
View source →
§interface

Registry

Abstract interface for package registries.

Properties

§readonly name:string
Registry name (e.g., "npm", "yarn")
§readonly url:string
Registry URL
View source →
§interface

RegistryConfig

Registry configuration options.

Properties

§readonly authToken?:string
Authentication token
§readonly cacheTtl?:number
Cache TTL in milliseconds
§readonly timeout?:number
Request timeout in milliseconds
§readonly url?:string
Registry URL
View source →
§interface

RegistryUnavailableDetails

Details identifying the failed lookup.

Properties

§readonly detail?:string
Diagnostic text from the underlying client, included in the message.
§readonly operation:string
Client operation that failed, for example getLatestVersion.
§readonly packageName:string
Package the lookup was for.
§readonly reason:RegistryFailureReason
Why the registry could not answer.
§readonly registry:string
Registry that was queried, for example npm.
View source →
§interface

RegistryUnavailableError

Error raised when a registry lookup could not be completed.
Distinct from a lookup that completed and found nothing: this means the registry did not give an answer, so no release decision may be derived from it.

Properties

§cause?:unknown
§message:string
§readonly name:string
Always REGISTRY_UNAVAILABLE_ERROR.
§readonly operation:string
Client operation that failed, for example getLatestVersion.
§readonly packageName:string
Package the lookup was for.
§readonly reason:RegistryFailureReason
Why the registry could not answer.
§readonly registry:string
Registry that was queried, for example npm.
§stack?:string
View source →
§interface

VersionInfo

Version-specific information from a registry.

Properties

§readonly dependencies?:Record<string, string>
Runtime dependencies
§readonly devDependencies?:Record<string, string>
Development dependencies
§readonly engines?:Record<string, string>
Engine requirements
§readonly gitHead?:string
Git commit hash at publish time. Used to determine commit range for changelog generation.
NOTE: This value comes from npm registry, making it immutable and independent of local git state.
§readonly integrity?:string
Subresource integrity hash
§readonly nodeVersion?:string
Node.js version range
§readonly npmVersion?:string
npm version used to publish
§readonly optionalDependencies?:Record<string, string>
Optional peer dependencies
§readonly peerDependencies?:Record<string, string>
Peer dependencies
§readonly publishedAt:string
ISO date when published
§readonly tarball:string
Tarball URL
§readonly version:string
Version string
View source →

◆ Types

§type

RegistryFailureReason

Why a registry could not answer a lookup.
Every value here means the answer is unknown, never that the package or version is absent. An absent package is a successful lookup with a negative answer, and is reported through the normal return value instead.
type RegistryFailureReason = "network" | "authentication" | "rate-limit" | "server" | "timeout" | "unknown"
View source →

● Variables

§type

REGISTRY_UNAVAILABLE_ERROR

Name carried by every error this module raises, used to identify it across module boundaries.
View source →