index
Classes
RegistryClient
Defined in: src/registry-client/src/index.ts:319
Constructors
new RegistryClient()
new RegistryClient(options): RegistryClientDefined in: src/registry-client/src/index.ts:342
Parameters
| Parameter | Type |
|---|---|
options | RegistryClientOptions |
Returns
Properties
| Property | Type | Description |
|---|---|---|
agent | RetryAgent | - |
cache | Cache | - |
identity | string | - |
registryKeys | readonly string[] | configured registry keys; VLT_TOKEN_<key> applies under each |
staleWhileRevalidateFactor | number | - |
Methods
cachedBody()
cachedBody(url, options): undefined | CachedBodyDefined in: src/registry-client/src/index.ts:750
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
cachedIntegrity()
cachedIntegrity(url, options): undefined | `sha512-${string}`Defined in: src/registry-client/src/index.ts:702
The hash the cache recorded for url. This reads only the entry's
head, which is about a kilobyte, rather than the body, which can be a
megabyte. A caller that is about to look the package up in the global
store needs nothing else, and if the store misses it can still read
the body afterwards.
Returns undefined if there is no entry, or if the entry is not a
tarball. This never reads the body, so if cache-unzip rewrote the
entry underneath us the worst case is a stale hash. That misses in the
store; it cannot return the wrong bytes.
Parameters
| Parameter | Type |
|---|---|
url | string | URL |
options | { method: CacheableMethod; } |
options.method? | CacheableMethod |
Returns
undefined | `sha512-${string}`
drain()
drain(): Promise<void>Defined in: src/registry-client/src/index.ts:907
Settle in-flight requests and their cache writes. Await before removing the cache dir.
Returns
Promise<void>
login()
login(registry): Promise<void>Defined in: src/registry-client/src/index.ts:549
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:475
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:823
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:914
Parameters
| Parameter | Type |
|---|---|
url | string | URL |
options | RegistryClientRequestOptions |
Returns
Promise<CacheEntry>
requestStream()
requestStream(url, options): Promise<{
body: Readable;
statusCode: number;
}>Defined in: src/registry-client/src/index.ts:844
Make a request and hand back the response body as it arrives, instead of buffering it into a CacheEntry. For a body a caller acts on line by line — the NDJSON the batch endpoints stream — waiting for the last byte is the difference between using the first record now and using it once the server has finished computing the last one.
The body is gunzipped here when the registry compressed it, so a caller always reads what the server serialized. Nothing is cached and nothing is retried: a caller that loses the stream falls back to the requests it was avoiding.
Parameters
| Parameter | Type |
|---|---|
url | string | URL |
options | RegistryClientRequestOptions |
Returns
Promise<{
body: Readable;
statusCode: number;
}>
scroll()
scroll<T>(
url,
options,
seek?): Promise<T[]>Defined in: src/registry-client/src/index.ts:398
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:463
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:605
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:110
CachedBody
type CachedBody = object;Defined in: src/registry-client/src/index.ts:97
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 = RegistryURLs & object;Defined in: src/registry-client/src/index.ts:121
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 |
signal? | AbortSignal | aborts every request this client makes |
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:166
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 |
readCache? | false | Set to false to fetch from the network without looking in the cache first, on this url and on every url it redirects to, while still storing the result. No cached entry is served, stale or not, or revalidated, so nothing is sent conditionally either. Meant for an entry that cannot be trusted any more: forceRevalidate would still hand it back on a 304, and evicting it does not stop a redirect from reading the entry under the final url back instead. |
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. |
RegistryURLs
type RegistryURLs = object;Defined in: src/registry-client/src/auth.ts:114
Configured registry URLs, by config option name.
Type declaration
| Name | Type |
|---|---|
jsr-registries? | Record<string, string> |
registries? | Record<string, string> |
registry? | string |
scoped-registries? | Record<string, string> |
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:118
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,
token?): Promise<void>Defined in: src/registry-client/src/auth.ts:64
Delete the token for registry. With token, also delete every other
key holding it: one login can save a token under many registries.
Parameters
| Parameter | Type |
|---|---|
registry | string |
identity | string |
token? | Token |
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:91
Parameters
| Parameter | Type |
|---|---|
registry | string |
identity | string |
Returns
Promise<undefined | Token>
getTokenByURL()
function getTokenByURL(
requestUrl,
identity,
keys): Promise<undefined | Token>Defined in: src/registry-client/src/auth.ts:152
Find the best matching token for a request URL by performing a
longest-prefix match against all known registry keys (runtime
tokens, VLT_REGISTRY, keychain entries, and keys: normalized
configured registry keys, e.g. from registryKeys). 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.
Used by RegistryClient.request(), which has the request URL, not
the registry URL it was built from.
Parameters
| Parameter | Type | Default value |
|---|---|---|
requestUrl | string | undefined |
identity | string | undefined |
keys | readonly string[] | [] |
Returns
Promise<undefined | Token>
isCacheableMethod()
function isCacheableMethod(m): m is CacheableMethodDefined in: src/registry-client/src/index.ts:111
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
registryKeys()
function registryKeys(o): string[]Defined in: src/registry-client/src/auth.ts:125
Normalized, deduped keys of the configured registries. Unparseable URLs are skipped.
Parameters
| Parameter | Type |
|---|---|
o | RegistryURLs |
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:80
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