← 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
CreatePackageInfoOptionsConfiguration 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
RegistryUnavailableDetailsWhich 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
CreateVersionInfoOptionsConfiguration 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
unknownValue 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 name:stringMaintainer name
§readonly email?:stringMaintainer email
View source →
§interface

PackageInfo

Package information from a registry.
Properties
§readonly name:stringPackage name
§readonly description?:stringPackage description
§readonly latestVersion:stringLatest version
§readonly versions:unknownAll published versions
§readonly license?:stringSPDX license identifier
§readonly repository?:stringRepository URL
§readonly homepage?:stringHomepage URL
§readonly maintainers:unknownPackage maintainers
§readonly keywords?:unknownKeywords
§readonly lastModified?:stringTime of last modification
View source →
§interface

Registry

Abstract interface for package registries.
Properties
§readonly name:stringRegistry name (e.g., "npm", "yarn")
§readonly url:stringRegistry URL
Methods
§getLatestVersion(packageName: string): Promise<string>
Get the latest published version of a package.

Parameters

NameTypeDescription
§packageName
stringThe package name to look up

Returns

Promise<string>
The latest version string, or null if not published
§getPackageInfo(packageName: string): Promise<PackageInfo>
Get full package information.

Parameters

NameTypeDescription
§packageName
stringName of the package to query (e.g., '@hyperfrontend/versioning')

Returns

Promise<PackageInfo>
Package info, or null if not found
§getVersionInfo(packageName: string, version: string): Promise<VersionInfo>
Get version-specific information including publish time.

Parameters

NameTypeDescription
§packageName
stringName of the package to query (e.g., '@hyperfrontend/versioning')
§version
stringSemver version string to look up (e.g., '1.2.3')

Returns

Promise<VersionInfo>
Version info, or null if not found
§isVersionPublished(packageName: string, version: string): Promise<boolean>
Check if a specific version is published.

Parameters

NameTypeDescription
§packageName
stringName of the package to check (e.g., '@hyperfrontend/versioning')
§version
stringSemver version string to verify (e.g., '1.2.3')

Returns

Promise<boolean>
True if the version is published
§listVersions(packageName: string): Promise<unknown>
List all published versions.

Parameters

NameTypeDescription
§packageName
stringName of the package to query (e.g., '@hyperfrontend/versioning')

Returns

Promise<unknown>
Array of version strings
View source →
§interface

RegistryConfig

Registry configuration options.
Properties
§readonly url?:stringRegistry URL
§readonly timeout?:numberRequest timeout in milliseconds
§readonly cacheTtl?:numberCache TTL in milliseconds
§readonly authToken?:stringAuthentication token
View source →
§interface

RegistryUnavailableDetails

Details identifying the failed lookup.
Properties
§readonly registry:stringRegistry that was queried, for example npm.
§readonly packageName:stringPackage the lookup was for.
§readonly operation:stringClient operation that failed, for example getLatestVersion.
§readonly reason:RegistryFailureReasonWhy the registry could not answer.
§readonly detail?:stringDiagnostic text from the underlying client, included in the message.
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
§readonly name:stringAlways REGISTRY_UNAVAILABLE_ERROR.
§cause?:unknown
§readonly registry:stringRegistry that was queried, for example npm.
§readonly packageName:stringPackage the lookup was for.
§readonly operation:stringClient operation that failed, for example getLatestVersion.
§readonly reason:RegistryFailureReasonWhy the registry could not answer.
§message:string
§stack?:string
View source →
§interface

VersionInfo

Version-specific information from a registry.
Properties
§readonly version:stringVersion string
§readonly publishedAt:stringISO date when published
§readonly tarball:stringTarball URL
§readonly integrity?:stringSubresource integrity hash
§readonly dependencies?:Record<string, string>Runtime dependencies
§readonly devDependencies?:Record<string, string>Development dependencies
§readonly peerDependencies?:Record<string, string>Peer dependencies
§readonly optionalDependencies?:Record<string, string>Optional peer dependencies
§readonly engines?:Record<string, string>Engine requirements
§readonly nodeVersion?:stringNode.js version range
§readonly npmVersion?:stringnpm version used to publish
§readonly gitHead?:stringGit 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.
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 →