index
Classes
RegistryClient
Defined in: src/registry-client/src/index.ts:288
Constructors
new RegistryClient()
new RegistryClient(options): RegistryClientDefined in: src/registry-client/src/index.ts:296
Parameters
| Parameter | Type |
|---|---|
options | RegistryClientOptions |
Returns
Properties
| Property | Type |
|---|---|
agent | RetryAgent |
cache | Cache |
identity | string |
staleWhileRevalidateFactor | number |
Methods
cachedBody()
cachedBody(url, options): undefined | CachedBodyDefined in: src/registry-client/src/index.ts:653
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.
Parameters
| Parameter | Type |
|---|---|
url | string | URL |
options | { integrity: `sha512-${string}`; method: CacheableMethod; } |
options.integrity? | `sha512-${string}` |
options.method? | CacheableMethod |
Returns
undefined | CachedBody
login()
login(registry): Promise<void>Defined in: src/registry-client/src/index.ts:498
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
| Parameter | Type |
|---|---|
registry | string | string[] |
Returns
Promise<void>
logout()
logout(registry): Promise<void>Defined in: src/registry-client/src/index.ts:424
Log out from the registry specified, attempting to destroy the token if the registry supports that endpoint.
Parameters
| Parameter | Type |
|---|---|
registry | string |
Returns
Promise<void>
queueForStore()
queueForStore(key, integrity?): voidDefined in: src/registry-client/src/index.ts:722
Queue the cached tarball at key (a CachedBody key) for the
background child: exploded into the global store when that is on,
else un-gzipped. integrity finds it when only the integrity path
holds it.
Parameters
| Parameter | Type |
|---|---|
key | string |
integrity? | `sha512-${string}` |
Returns
void
request()
request(url, options): Promise<CacheEntry>Defined in: src/registry-client/src/index.ts:731
Parameters
| Parameter | Type |
|---|---|
url | string | URL |
options | RegistryClientRequestOptions |
Returns
Promise<CacheEntry>
scroll()
scroll<T>(
url,
options,
seek?): Promise<T[]>Defined in: src/registry-client/src/index.ts:347
Fetch the entire set of a paginated list of objects
Type Parameters
| Type Parameter |
|---|
T |
Parameters
| Parameter | Type |
|---|---|
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:412
find a given item in a paginated set
Type Parameters
| Type Parameter |
|---|
T |
Parameters
| Parameter | Type |
|---|---|
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:554
Given a WebAuthChallenge, open the authUrl in a browser and
hang on the doneUrl until it returns a TokenResponse object.
Parameters
| Parameter | Type |
|---|---|
__namedParameters | WebAuthChallenge |
Returns
Promise<TokenResponse>
Type Aliases
CacheableMethod
type CacheableMethod = "GET" | "HEAD";Defined in: src/registry-client/src/index.ts:102
CachedBody
type CachedBody = object;Defined in: src/registry-client/src/index.ts:89
A response body read straight out of the cache file.
Type declaration
| Name | Type | Description |
|---|---|---|
body | Buffer | the body, a view into the file's bytes |
gzip | boolean | the body on disk is gzipped (body may be un-gzipped) |
integrity? | Integrity | the hash the entry was stored under, if it has one |
key | string | the cache key of the request |
path | string | the cache file it came from |
OidcOptions
type OidcOptions = object;Defined in: src/registry-client/src/oidc.ts:5
Type declaration
| Name | Type | Description |
|---|---|---|
packageName | string | The package name being published, e.g. @scope/name |
registry | string | The full registry URL, e.g. https://registry.npmjs.org/ |
RegistryClientOptions
type RegistryClientOptions = object;Defined in: src/registry-client/src/index.ts:109
Type declaration
| Name | Type | Description |
|---|---|---|
cache? | string | Path on disk where the cache should be stored Defaults to the XDG cache folder for vlt/registry-client |
fetch-retries? | number | Number of retries to perform when encountering network errors or likely-transient errors from git hosts. |
fetch-retry-factor? | number | The exponential backoff factor to use when retrying git hosts |
fetch-retry-maxtimeout? | number | Maximum number of milliseconds between two retries |
fetch-retry-mintimeout? | number | Number of milliseconds before starting first retry |
identity? | string | the identity to use for storing auth tokens |
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. |
storeRoot? | string | Global store root. Defaults to storeRoot of cache. |
RegistryClientRequestOptions
type RegistryClientRequestOptions = Omit<Dispatcher.RequestOptions, "method" | "path"> & object;Defined in: src/registry-client/src/index.ts:151
Type declaration
| Name | Type | Description |
|---|---|---|
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? | 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? | Dispatcher.DispatchOptions["method"] | Method is optional, defaults to 'GET' |
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? | 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? | false | Set to false to suppress ANY lookups from cache. This will also prevent storing the result to the cache. |
verifyDigest? | boolean | "required" | With no integrity to expect, check the body against the RFC 9530 Repr-Digest the server sent with it. 'required' also rejects a response that carries no digest. Runs before the response is cached, so a body that fails is never served from the cache later. |
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
| Name | Type |
|---|---|
token | string |
WebAuthChallenge
type WebAuthChallenge = object;Defined in: src/registry-client/src/web-auth-challenge.ts:1
Type declaration
| Name | Type |
|---|---|
authUrl | string |
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/user-agent/src/index.ts:49
The User-Agent header sent with every request vlt makes, and the value
of npm_config_user_agent in lifecycle script environments.
Looks like vlt/1.2.3 Node.js/22.22.0, with the trailing portion coming
from navigator.userAgent when the runtime provides one.
Functions
cacheKey()
function cacheKey(method, url): stringDefined in: src/registry-client/src/index.ts:106
Parameters
| Parameter | Type |
|---|---|
method | string |
url | string | URL |
Returns
string
clearRuntimeTokens()
function clearRuntimeTokens(): voidDefined 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
| Parameter | Type |
|---|---|
registry | string |
identity | string |
Returns
Promise<void>
getKC()
function getKC(identity): Keychain<Token>Defined in: src/registry-client/src/auth.ts:47
Parameters
| Parameter | Type |
|---|---|
identity | string |
Returns
getToken()
function getToken(registry, identity): Promise<undefined | Token>Defined in: src/registry-client/src/auth.ts:81
Parameters
| Parameter | Type |
|---|---|
registry | string |
identity | string |
Returns
Promise<undefined | Token>
getTokenByURL()
function getTokenByURL(requestUrl, identity): Promise<undefined | Token>Defined in: src/registry-client/src/auth.ts:117
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). A key that resolves no token is skipped.
VLT_TOKEN_<key> env vars are only read for a known key: their
names are lossy (., -, / all become _), so probing them by
request URL would hand the token to lookalike hosts.
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
| Parameter | Type |
|---|---|
requestUrl | string |
identity | string |
Returns
Promise<undefined | Token>
isCacheableMethod()
function isCacheableMethod(m): m is CacheableMethodDefined in: src/registry-client/src/index.ts:103
Parameters
| Parameter | Type |
|---|---|
m | unknown |
Returns
m is CacheableMethod
isToken()
function isToken(t): t is TokenDefined in: src/registry-client/src/auth.ts:56
Parameters
| Parameter | Type |
|---|---|
t | any |
Returns
t is Token
normalizeRegistryKey()
function normalizeRegistryKey(url): stringDefined 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
| Parameter | Type |
|---|---|
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
| Parameter | Type |
|---|---|
opts | OidcOptions |
Returns
Promise<undefined | Token>
registryBase()
function registryBase(url): stringDefined 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
| Parameter | Type |
|---|---|
url | string |
Returns
string
setRuntimeToken()
function setRuntimeToken(registry, token): voidDefined in: src/registry-client/src/auth.ts:39
Parameters
| Parameter | Type |
|---|---|
registry | string |
token | Token |
Returns
void
setToken()
function setToken(
registry,
token,
identity): Promise<void>Defined in: src/registry-client/src/auth.ts:70
Parameters
| Parameter | Type |
|---|---|
registry | string |
token | Token |
identity | string |
Returns
Promise<void>
References
assertOk
Re-exports assertOk
CacheEntry
Re-exports CacheEntry
ErrorResponse
Re-exports ErrorResponse
JSONObj
Re-exports JSONObj
registryErrorMessage
Re-exports registryErrorMessage
requestError
Re-exports requestError
storeRoot
Re-exports storeRoot