cache-entry
Classes
CacheEntry
Defined in: src/registry-client/src/cache-entry.ts:127
Constructors
new CacheEntry()
new CacheEntry(
statusCode,
headers,
__namedParameters): CacheEntryDefined in: src/registry-client/src/cache-entry.ts:150
Parameters
| Parameter | Type |
|---|---|
statusCode | number |
headers | Uint8Array<ArrayBufferLike>[] |
__namedParameters | CacheEntryOptions |
Returns
Accessors
_body
Get Signature
get _body(): Uint8ArrayDefined in: src/registry-client/src/cache-entry.ts:379
Returns the body as a single Uint8Array, concatenating parts if needed.
Returns
Uint8Array
body
Get Signature
get body(): Uint8Array<ArrayBufferLike> | Record<string, any>Defined in: src/registry-client/src/cache-entry.ts:565
Returns
Uint8Array<ArrayBufferLike> | Record<string, any>
cacheControl
Get Signature
get cacheControl(): CacheControlDefined in: src/registry-client/src/cache-entry.ts:265
Returns
CacheControl
contentType
Get Signature
get contentType(): stringDefined in: src/registry-client/src/cache-entry.ts:288
Returns
string
date
Get Signature
get date(): undefined | DateDefined in: src/registry-client/src/cache-entry.ts:246
Returns
undefined | Date
digest
Get Signature
get digest(): undefined | `sha512-${string}`Defined in: src/registry-client/src/cache-entry.ts:498
The sha-512 member of an RFC 9530 Repr-Digest (or Content-Digest)
response header, as an SRI string. A registry that serves packuments
without dist.integrity labels each tarball this way instead.
Returns
undefined | `sha512-${string}`
fromCache
Get Signature
get fromCache(): booleanDefined in: src/registry-client/src/cache-entry.ts:343
True when this entry was decoded from the on-disk cache.
Returns
boolean
headers
Get Signature
get headers(): Uint8Array<ArrayBufferLike>[]Defined in: src/registry-client/src/cache-entry.ts:372
Returns
Uint8Array<ArrayBufferLike>[]
headSize
Get Signature
get headSize(): undefined | numberDefined in: src/registry-client/src/cache-entry.ts:351
Byte length of the encoded head (4-byte length prefix + status +
headers). Set when decoded from cache or after encodeHead().
Returns
undefined | number
integrity
Get Signature
get integrity(): undefined | `sha512-${string}`Defined in: src/registry-client/src/cache-entry.ts:489
Returns
undefined | `sha512-${string}`
Set Signature
set integrity(i): voidDefined in: src/registry-client/src/cache-entry.ts:483
Parameters
| Parameter | Type |
|---|---|
i | undefined | `sha512-${string}` |
Returns
void
integrityActual
Get Signature
get integrityActual(): `sha512-${string}`Defined in: src/registry-client/src/cache-entry.ts:471
Returns
`sha512-${string}`
Set Signature
set integrityActual(i): voidDefined in: src/registry-client/src/cache-entry.ts:478
Parameters
| Parameter | Type |
|---|---|
i | `sha512-${string}` |
Returns
void
isGzip
Get Signature
get isGzip(): booleanDefined in: src/registry-client/src/cache-entry.ts:631
Returns
boolean
isJSON
Get Signature
get isJSON(): booleanDefined in: src/registry-client/src/cache-entry.ts:570
Returns
boolean
maxAge
Get Signature
get maxAge(): numberDefined in: src/registry-client/src/cache-entry.ts:254
Returns
number
ok
Get Signature
get ok(): booleanDefined in: src/registry-client/src/cache-entry.ts:369
True when the registry answered with a 2xx.
RegistryClient.request() resolves for every status, so this is how
code holding a real CacheEntry asks "did it work?".
Note this is the strict form. Use it only where a genuine CacheEntry
is guaranteed; assertOk uses the loose range check because it is
also handed duck-typed responses.
Returns
boolean
staleWhileRevalidate
Get Signature
get staleWhileRevalidate(): booleanDefined in: src/registry-client/src/cache-entry.ts:273
Returns
boolean
statusCode
Get Signature
get statusCode(): numberDefined in: src/registry-client/src/cache-entry.ts:355
Returns
number
valid
Get Signature
get valid(): booleanDefined in: src/registry-client/src/cache-entry.ts:300
Returns
boolean
Methods
[kCustomInspect]()
kCustomInspect: stringDefined in: src/registry-client/src/cache-entry.ts:237
Parameters
| Parameter | Type |
|---|---|
depth | number |
options | InspectOptions |
Returns
string
addBody()
addBody(b): voidDefined in: src/registry-client/src/cache-entry.ts:328
Add contents to the entry body.
Parameters
| Parameter | Type |
|---|---|
b | Uint8Array |
Returns
void
buffer()
buffer(): BufferDefined in: src/registry-client/src/cache-entry.ts:555
Return the body of the entry as a Buffer
Returns
Buffer
checkDigest()
checkDigest(required, context): `sha512-${string}`Defined in: src/registry-client/src/cache-entry.ts:434
Check the body against the RFC 9530 digest the server sent with it,
for a response that had no expected integrity. A registry that omits
dist.integrity labels every tarball, so a missing digest fails when
required. Like checkIntegrity, only for an actual http
response: cached bodies are un-gzipped in place.
Will throw on a mismatch. Returns the hash of the body.
Parameters
| Parameter | Type |
|---|---|
required | boolean |
context | ErrorCauseOptions |
Returns
`sha512-${string}`
checkIntegrity()
checkIntegrity(context): this is CacheEntry & { integrity: `sha512-${string}` }Defined in: src/registry-client/src/cache-entry.ts:409
Check that the sri integrity string that was provided to the ctor matches the body that we actually received. This should only be called AFTER the entire body has been completely downloaded.
This method will throw if the integrity values do not match.
Note that this will usually not be true if the value is coming out of the cache, because cache entries not exploded into the global store are un-gzipped in place. It should only be called for artifacts that come from an actual http response, whatever its encoding: an identity body is hashed as it came, a gzipped one before anything un-gzips it in memory.
Returns true if anything was actually verified.
Parameters
| Parameter | Type |
|---|---|
context | ErrorCauseOptions |
Returns
this is CacheEntry & { integrity: `sha512-${string}` }
deleteHeader()
deleteHeader(h): voidDefined in: src/registry-client/src/cache-entry.ts:541
Remove a header, if present
Parameters
| Parameter | Type |
|---|---|
h | string |
Returns
void
encode()
encode(): BufferDefined in: src/registry-client/src/cache-entry.ts:876
Encode the entry as a single Buffer for writing to the cache
Returns
Buffer
encodeHead()
encodeHead(): BufferDefined in: src/registry-client/src/cache-entry.ts:841
Encode status + headers (no body) as they appear at the start of an on-disk cache file.
Returns
Buffer
getHeader()
getHeader(h): undefined | Uint8Array<ArrayBufferLike>Defined in: src/registry-client/src/cache-entry.ts:510
Give it a key, and it'll return the buffer of that header value
Parameters
| Parameter | Type |
|---|---|
h | string |
Returns
undefined | Uint8Array<ArrayBufferLike>
getHeaderString()
getHeaderString(h): undefined | stringDefined in: src/registry-client/src/cache-entry.ts:517
Give it a key, and it'll return the decoded string of that header value
Parameters
| Parameter | Type |
|---|---|
h | string |
Returns
undefined | string
json()
json(): JSONObjDefined in: src/registry-client/src/cache-entry.ts:707
Parse the entry body as JSON and return the result
Returns
labelArtifact()
labelArtifact(): voidDefined in: src/registry-client/src/cache-entry.ts:617
Label a 200 network body that is not json and came with no
content-type application/octet-stream, the way the json sniff
labels json text/json.
The label says the hash the entry is stored under is the hash of
its bytes as served, checked or recorded by
RegistryClient.request(). So it is applied only where that is
known, right before such an entry is stored, and never by the
sniff: an entry with no content-type read back from the cache is
not known to be one.
A decoded entry, an error body, an empty body, json, and a body served with a content-type are left as they are. Not an error body or an empty one: a content-type that is not json makes an entry immutable (see valid), which neither was when served with none, and no artifact is empty. The length is checked after the sniff, which un-gzips a body with no content-type.
Returns
void
setHeader()
setHeader(h, value): voidDefined in: src/registry-client/src/cache-entry.ts:527
Set a header to a specific value
Parameters
| Parameter | Type |
|---|---|
h | string |
value | string | Uint8Array<ArrayBufferLike> |
Returns
void
text()
text(): stringDefined in: src/registry-client/src/cache-entry.ts:699
Return the body of the entry as utf8 text Automatically unzips if the content is gzip encoded
Returns
string
toJSON()
toJSON(): objectDefined in: src/registry-client/src/cache-entry.ts:197
Returns
object
unzip()
unzip(): booleanDefined in: src/registry-client/src/cache-entry.ts:680
Un-gzip encode the body. Returns true if it was previously gzip (so something was done), otherwise returns false.
Returns
boolean
unzippedIntegrity()
unzippedIntegrity(): `sha512-${string}`Defined in: src/registry-client/src/cache-entry.ts:467
The hash of the body un-gzipped, or of the body itself if it is not gzipped, without un-gzipping the entry. Bounded like unzip, and throws like it on a body that will not un-gzip.
Never the hash to record for an artifact, which is the hash of its bytes as served. It pins the same content, though, and is what a body hashed after something un-gzipped it was pinned with.
Returns
`sha512-${string}`
decode()
static decode(buffer, options): CacheEntryDefined in: src/registry-client/src/cache-entry.ts:770
Pass the contents of a @vltpkg/cache.Cache object as a buffer, and this static method will decode it into a CacheEntry representing the cached response.
Parameters
| Parameter | Type |
|---|---|
buffer | Uint8Array |
options | CacheEntryOptions |
Returns
decodeHead()
static decodeHead(buffer): CacheEntryDefined in: src/registry-client/src/cache-entry.ts:752
Decode only the status/headers from an encoded cache buffer.
The body is not read; headSize records how many bytes the head
occupies so a later encodeHead() can be patched in place.
Parameters
| Parameter | Type |
|---|---|
buffer | Uint8Array |
Returns
isGzipEntry()
static isGzipEntry(buffer): booleanDefined in: src/registry-client/src/cache-entry.ts:807
Parameters
| Parameter | Type |
|---|---|
buffer | Uint8Array |
Returns
boolean
isTarballEntry()
static isTarballEntry(buffer): booleanDefined in: src/registry-client/src/cache-entry.ts:818
Head-only check for a 200 non-JSON body with an integrity header, i.e. a tarball the global store can be built from.
Parameters
| Parameter | Type |
|---|---|
buffer | Uint8Array |
Returns
boolean
tarballIntegrity()
static tarballIntegrity(buffer): undefined | `sha512-${string}`Defined in: src/registry-client/src/cache-entry.ts:826
The hash recorded on such an entry, or undefined if this is not one. isTarballEntry is built on this, and both only need the head.
Parameters
| Parameter | Type |
|---|---|
buffer | Uint8Array |
Returns
undefined | `sha512-${string}`
Type Aliases
CacheEntryOptions
type CacheEntryOptions = object;Defined in: src/registry-client/src/cache-entry.ts:77
Type declaration
| Name | Type | Description |
|---|---|---|
body? | Uint8Array | An optional body to use. Adopted as-is (no copy). The caller must not mutate or reuse it. Used when decoding a cache entry from a buffer. Do not call addBody after providing this. Worker-thread transfers must copy or structuredClone first so the cache ArrayBuffer is not detached. |
contentLength? | number | An optional content length of the body to use, if undefined the content-length header will be used. |
integrity? | Integrity | The expected integrity value for this response body |
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. |
trustIntegrity? | boolean | Whether to trust the integrity, or calculate the actual value. This indicates that we just accept whatever the integrity is as the actual integrity for saving back to the cache, because it's coming directly from the registry that we fetched a packument from, and is an initial gzipped artifact request. |
JSONObj
type JSONObj = Record<string, JSONField>;Defined in: src/registry-client/src/cache-entry.ts:36