API Referenceregistry-clientindex

@vltpkg/registry-client

new RegistryClient(options): RegistryClient

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

Properties

agent

agent: RetryAgent

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

cache

cache: Cache

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

identity

identity: string

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

staleWhileRevalidateFactor

staleWhileRevalidateFactor: number

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

Methods

cachedBody()

cachedBody(url, options): undefined | CachedBody

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

Read a valid cached non-JSON body straight off disk, bypassing the in-memory cache LRU so that a tarball is never held in it.

One read: the head is decoded from the same bytes the body comes from, so cache-unzip rewriting the head cannot land between the two and hand back a body at a stale offset.

Does not log a cache hit — the caller may still reject the body and fall back to request, which logs its own.

Returns undefined on anything unexpected; callers fall back to request.

Returns

undefined | CachedBody

login(registry): Promise<void>

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

Log into the registry specified.

When a list of registries is provided, the web login flow runs once against the first of them, and the token it returns is saved for all of them. This is for registries that share credentials — like the ones under a single vlt.io account — where opening the browser once per registry would just be asking for the same token again.

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 | string[]

Returns

Promise<void>

logout()

logout(registry): Promise<void>

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

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:594

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:323

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:342

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:449

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:84

CachedBody

type CachedBody = object

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

A response body read straight out of the cache file.

Type declaration

body

body: Buffer

the body, a view into the file’s bytes

path

path: string

the cache file it came from

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:91

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:131

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:221

Functions

cacheKey()

function cacheKey(method, url): string

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

Parameters

method

string

url

string | URL

Returns

string

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:85

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.

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/’

function setRuntimeToken(registry, token): void

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

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

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

On this page

@vltpkg/registry-client