Skip to content
packagesregistry-clientmodule_index

@vltpkg/registry-client

Classes

RegistryClient

Defined in: src/registry-client/src/index.ts:214

Constructors

new RegistryClient()
new RegistryClient(options): RegistryClient

Defined in: src/registry-client/src/index.ts:220

Parameters
options

RegistryClientOptions

Returns

RegistryClient

Properties

agent
agent: RetryAgent

Defined in: src/registry-client/src/index.ts:215

cache
cache: Cache

Defined in: src/registry-client/src/index.ts:216

identity
identity: string

Defined in: src/registry-client/src/index.ts:217

staleWhileRevalidateFactor
staleWhileRevalidateFactor: number

Defined in: src/registry-client/src/index.ts:218

Methods

login()
login(registry): Promise<void>

Defined in: src/registry-client/src/index.ts:329

Log into the registry specified

Does not return the token or expose it, just saves to the auth keychain and returns void if it worked. Otherwise, error is raised.

Parameters
registry

string

Returns

Promise<void>

logout()
logout(registry): Promise<void>

Defined in: src/registry-client/src/index.ts:296

Log out from the registry specified, attempting to destroy the token if the registry supports that endpoint.

Parameters
registry

string

Returns

Promise<void>

request()
request(url, options): Promise<CacheEntry>

Defined in: src/registry-client/src/index.ts:415

Parameters
url

string | URL

options

RegistryClientRequestOptions = {}

Returns

Promise<CacheEntry>

scroll()
scroll<T>(
   url,
   options,
seek?): Promise<T[]>

Defined in: src/registry-client/src/index.ts:265

Fetch the entire set of a paginated list of objects

Type Parameters

• T

Parameters
url

string | URL

options

RegistryClientRequestOptions = {}

seek?

(obj) => boolean

Returns

Promise<T[]>

seek()
seek<T>(
   url,
   seek,
options): Promise<undefined | T>

Defined in: src/registry-client/src/index.ts:284

find a given item in a paginated set

Type Parameters

• T

Parameters
url

string | URL

seek

(obj) => boolean

options

RegistryClientRequestOptions = {}

Returns

Promise<undefined | T>

webAuthOpener()
webAuthOpener(__namedParameters): Promise<TokenResponse>

Defined in: src/registry-client/src/index.ts:370

Given a WebAuthChallenge, open the authUrl in a browser and hang on the doneUrl until it returns a TokenResponse object.

Parameters
__namedParameters

WebAuthChallenge

Returns

Promise<TokenResponse>

Type Aliases

CacheableMethod

type CacheableMethod = 'GET' | 'HEAD'

Defined in: src/registry-client/src/index.ts:67

OidcOptions

type OidcOptions = object

Defined in: src/registry-client/src/oidc.ts:5

Type declaration

packageName
packageName: string

The package name being published, e.g. @scope/name

registry
registry: string

The full registry URL, e.g. https://registry.npmjs.org/

RegistryClientOptions

type RegistryClientOptions = object

Defined in: src/registry-client/src/index.ts:71

Type declaration

cache?
optional cache: string;

Path on disk where the cache should be stored

Defaults to the XDG cache folder for vlt/registry-client

fetch-retries?
optional fetch-retries: number;

Number of retries to perform when encountering network errors or likely-transient errors from git hosts.

fetch-retry-factor?
optional fetch-retry-factor: number;

The exponential backoff factor to use when retrying git hosts

fetch-retry-maxtimeout?
optional fetch-retry-maxtimeout: number;

Maximum number of milliseconds between two retries

fetch-retry-mintimeout?
optional fetch-retry-mintimeout: number;

Number of milliseconds before starting first retry

identity?
optional identity: string;

the identity to use for storing auth tokens

stale-while-revalidate-factor?
optional stale-while-revalidate-factor: number;

If the server does not serve a stale-while-revalidate value in the cache-control header, then this multiplier is applied to the max-age or s-maxage values.

By default, this is 60, so for example a response that is cacheable for 5 minutes will allow a stale response while revalidating for up to 5 hours.

If the server does provide a stale-while-revalidate value, then that is always used.

Set to 0 to prevent any stale-while-revalidate behavior unless explicitly allowed by the server’s cache-control header.

RegistryClientRequestOptions

type RegistryClientRequestOptions = Omit<
  Dispatcher.RequestOptions,
  'method' | 'path'
> &
  object

Defined in: src/registry-client/src/index.ts:111

Type declaration

integrity?
optional integrity: Integrity;

Provide an SRI string to verify integrity of the item being fetched.

This is only relevant when it must make a request to the registry. Once in the local disk cache, items are assumed to be trustworthy.

maxRedirections?
optional maxRedirections: number;

Follow up to 10 redirections by default. Set this to 0 to just return the 3xx response. If the max redirections are expired, and we still get a redirection response, then fail the request. Redirection cycles are always treated as an error.

method?
optional method: Dispatcher.DispatchOptions["method"];

Method is optional, defaults to ‘GET’

path?
optional path: string;

path should not be set when using the RegistryClient. It will be overwritten with the path on the URL being requested. This only here for compliance with the DispatchOptions base type.

Deprecated
trustIntegrity?
optional trustIntegrity: boolean;

Set to true if the integrity should be trusted implicitly without a recalculation, for example if it comes from a trusted registry that also serves the tarball itself.

useCache?
optional useCache: false;

Set to false to suppress ANY lookups from cache. This will also prevent storing the result to the cache.

Token

type Token = `Bearer ${string}` | `Basic ${string}`

Defined in: src/registry-client/src/auth.ts:3

TokenResponse

type TokenResponse = object

Defined in: src/registry-client/src/token-response.ts:1

Type declaration

token
token: string

WebAuthChallenge

type WebAuthChallenge = object

Defined in: src/registry-client/src/web-auth-challenge.ts:1

Type declaration

authUrl
authUrl: string
doneUrl
doneUrl: string

Variables

keychains

const keychains: Map<string, Keychain<Token>>

Defined in: src/registry-client/src/auth.ts:31

runtimeTokens

const runtimeTokens: Map<string, Token>

Defined in: src/registry-client/src/auth.ts:37

In-memory token store for OIDC-exchanged tokens. These take precedence over env vars and keychain.

userAgent

const userAgent: string

Defined in: src/registry-client/src/index.ts:194

Functions

clearRuntimeTokens()

function clearRuntimeTokens(): void

Defined in: src/registry-client/src/auth.ts:43

Returns

void

deleteToken()

function deleteToken(registry, identity): Promise<void>

Defined in: src/registry-client/src/auth.ts:60

Parameters

registry

string

identity

string

Returns

Promise<void>

getKC()

function getKC(identity): Keychain<Token>

Defined in: src/registry-client/src/auth.ts:47

Parameters

identity

string

Returns

Keychain<Token>

getToken()

function getToken(registry, identity): Promise<undefined | Token>

Defined in: src/registry-client/src/auth.ts:81

Parameters

registry

string

identity

string

Returns

Promise<undefined | Token>

getTokenByURL()

function getTokenByURL(
  requestUrl,
  identity,
): Promise<undefined | Token>

Defined in: src/registry-client/src/auth.ts:112

Find the best matching token for a request URL by performing a longest-prefix match against all known registry keys (runtime tokens, env-var registries, and keychain entries).

This is used by RegistryClient.request() which only has the full request URL — not the configured registry URL that was used to construct it.

Parameters

requestUrl

string

identity

string

Returns

Promise<undefined | Token>

isCacheableMethod()

function isCacheableMethod(m): m is CacheableMethod

Defined in: src/registry-client/src/index.ts:68

Parameters

m

unknown

Returns

m is CacheableMethod

isToken()

function isToken(t): t is Token

Defined in: src/registry-client/src/auth.ts:56

Parameters

t

any

Returns

t is Token

normalizeRegistryKey()

function normalizeRegistryKey(url): string

Defined in: src/registry-client/src/auth.ts:15

Normalize a registry URL into a stable key that preserves the path prefix. The result is origin + pathname with trailing slashes stripped so that https://r.io/luke/ and https://r.io/luke both produce the same key.

For plain-origin registries the result is identical to the old new URL(url).origin behaviour (e.g. https://registry.npmjs.org).

Parameters

url

string

Returns

string

oidc()

function oidc(opts): Promise<undefined | Token>

Defined in: src/registry-client/src/oidc.ts:58

Detect CI environment and exchange an OIDC ID token for a registry auth token. Sets the token into the runtime token store so subsequent requests are authenticated.

This function never throws. OIDC is always optional — if it is unavailable or any step fails the function returns undefined silently.

Parameters

opts

OidcOptions

Returns

Promise<undefined | Token>

registryBase()

function registryBase(url): string

Defined in: src/registry-client/src/auth.ts:27

Ensure a registry URL ends with / so that new URL(path, base) appends under the full path instead of replacing the last segment.

registryBase(‘https://r.io/scope/name’) // → ‘https://r.io/scope/name/‘

Parameters

url

string

Returns

string

setRuntimeToken()

function setRuntimeToken(registry, token): void

Defined in: src/registry-client/src/auth.ts:39

Parameters

registry

string

token

Token

Returns

void

setToken()

function setToken(registry, token, identity): Promise<void>

Defined in: src/registry-client/src/auth.ts:70

Parameters

registry

string

token

Token

identity

string

Returns

Promise<void>

References

CacheEntry

Re-exports CacheEntry

JSONObj

Re-exports JSONObj