@vltpkg/registry-client 0.0.0-0.1730239248325 → 0.0.0-10

package/README.md

@@ -1,71 +1,74 @@
-# `@vltpkg/registry-client`
+![registry-client](https://github.com/user-attachments/assets/664e4107-bf7b-4179-802d-9ec9f1499955)
 
-This is a very light wrapper around undici, optimized for
-interfacing with an npm registry.
+# @vltpkg/registry-client
 
-Any response with `immutable` in the `cache-control` header, or
-with a `content-type` of `application/octet-stream` or a path
-ending in `.tgz`, will be cached forever and never requested
-again as long as the cache survives.
+This is a very light wrapper around undici, optimized for interfacing
+with an npm registry.
+
+**[Cache Unzipped](#cache-unzipped)** ·
+**[Integrity Options](#integrity-options)** · **[Usage](#usage)**
+
+## Overview
+
+Any response with `immutable` in the `cache-control` header, or with a
+`content-type` of `application/octet-stream` or a path ending in
+`.tgz`, will be cached forever and never requested again as long as
+the cache survives.
 
 If the request has a cached response:
 
-- Cached responses with `immutable` in the `cache-control`
-  header will be returned from cache without a network request,
-  no matter what.
-- Cached responses with a `content-type` of
-  `application/octet-stream` will be returned from cache without
-  a network request, no matter what, because tarballs are
-  immutable.
+- Cached responses with `immutable` in the `cache-control` header will
+  be returned from cache without a network request, no matter what.
+- Cached responses with a `content-type` of `application/octet-stream`
+  will be returned from cache without a network request, no matter
+  what, because tarballs are immutable.
 - Cached responses with `max-age=<n>` or `s-max-age=<n>` will be
-  served from cache without a network request if it's less than
-  `<n>` seconds old.
+  served from cache without a network request if it's less than `<n>`
+  seconds old.
 - Otherwise, a network request to the registry will be made
-  - if an `etag` is present in the cached response, it will be
-    used as the `if-none-match` header.
-  - If a `last-modified` header is in the response, that will
-    be used as the `if-modified-since` request header.
-  - If there is no `last-modified` header, then use the `mtime`
-    of the cache file as the `if-modified-since` header.
+  - if an `etag` is present in the cached response, it will be used as
+    the `if-none-match` header.
+  - If a `last-modified` header is in the response, that will be used
+    as the `if-modified-since` request header.
+  - If there is no `last-modified` header, then use the `mtime` of the
+    cache file as the `if-modified-since` header.
 
 This is the extent of the cache control logic. It is not a
-full-featured spec-compliant caching HTTP client, because that is
-not needed for this use case. Every response will be cached, even
-if the registry headers don't technically allow it.
+full-featured spec-compliant caching HTTP client, because that is not
+needed for this use case. Every response will be cached, even if the
+registry headers don't technically allow it.
 
 ## Cache Unzipped
 
-Client always sends `accept-encoding: gzip;q=1.0, *;q=0.5`
-header when making requests, to save time on the wire.
+Client always sends `accept-encoding: gzip;q=1.0, *;q=0.5` header when
+making requests, to save time on the wire.
 
-If response has `content-encoding: gzip`, then we swap out the
-body for the unzipped response body in the cache, as if it was
-not gzipped in the first place. This _must_ be done before
-returning the response, because you can't `JSON.parse()` a
-gzipped response anyway.
+If response has `content-encoding: gzip`, then we swap out the body
+for the unzipped response body in the cache, as if it was not gzipped
+in the first place. This _must_ be done before returning the response,
+because you can't `JSON.parse()` a gzipped response anyway.
 
-If the response is `content-type: application/octet-stream` and
-starts with the gzip header, then we return the raw body as we
-received it, but as a best-effort background job, unzip it and
-update the cache entry to be an unzipped response body. This is
-done in the `@vltpkg/cache-unzip` worker.
+If the response is `content-type: application/octet-stream` and starts
+with the gzip header, then we return the raw body as we received it,
+but as a best-effort background job, unzip it and update the cache
+entry to be an unzipped response body. This is done in the
+`@vltpkg/cache-unzip` worker.
 
 So,
 
-- json responses will always be un-zipped, in the response and in
-  the cache.
-- artifact responses _may_ be gzipped (and thus, have to be
-  unzipped by the unpack operation), but will eventually be
-  cached as unzipped tarballs.
+- json responses will always be un-zipped, in the response and in the
+  cache.
+- artifact responses _may_ be gzipped (and thus, have to be unzipped
+  by the unpack operation), but will eventually be cached as unzipped
+  tarballs.
 
-Thus, the `content-length` response header will _usually_ not
-match the actual byte length of the response body.
+Thus, the `content-length` response header will _usually_ not match
+the actual byte length of the response body.
 
 ## Integrity Options
 
-An `integrity` option may be specified in a
-`fetchOptions.context` object, or in the options provided to
-`cache.set()`. For example:
+An `integrity` option may be specified in a `fetchOptions.context`
+object, or in the options provided to `cache.set()`. For example:
 
 ```js
 const integrity = `sha512-${base64hash}`
@@ -80,19 +83,19 @@ cache.set(key, value, { integrity })
 const value = await cache.fetch(key, { context: { integrity } })
 ```
 
-If the integrity provided is obviously not a valid sha512
-`Integrity` string, then it is ignored.
+If the integrity provided is obviously not a valid sha512 `Integrity`
+string, then it is ignored.
 
-Integrity values are not calculated or verified. The caller must do this
-check, if desired.
+Integrity values are not calculated or verified. The caller must do
+this check, if desired.
 
 Note that the integrity provided to `cache.fetch()` or `cache.set()`
 does _not_ typically match the calculated integrity of the object
-being cached. Typically, the integrity is related to the body of
-the response that a `@vltpkg/registry-client.CacheEntry` object
+being cached. Typically, the integrity is related to the body of the
+response that a `@vltpkg/registry-client.CacheEntry` object
 represents.
 
-## USAGE
+## Usage
 
 ```js
 import { Cache } from '@vltpkg/cache'

package/dist/esm/add-header.d.ts

@@ -1,2 +1,2 @@
-export declare const addHeader: <H extends [string, string[] | string][] | Iterable<[string, string[] | string | undefined]> | Record<string, string[] | string | undefined> | string[]>(headers: H | null | undefined, key: string, value: string) => H;
+export declare const addHeader: <H extends [string, string[] | string][] | Iterable<[string, string[] | string | undefined]> | Record<string, string[] | string | undefined> | string[]>(headers: H | null | undefined, key: string, value?: string) => H;
 //# sourceMappingURL=add-header.d.ts.map

package/dist/esm/add-header.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"add-header.d.ts","sourceRoot":"","sources":["../../src/add-header.ts"],"names":[],"mappings":"AAKA,eAAO,MAAM,SAAS,GACpB,CAAC,SACG,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,MAAM,CAAC,EAAE,GAC7B,QAAQ,CAAC,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,MAAM,GAAG,SAAS,CAAC,CAAC,GACjD,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,MAAM,GAAG,SAAS,CAAC,GAC7C,MAAM,EAAE,WAEH,CAAC,GAAG,IAAI,GAAG,SAAS,OACxB,MAAM,SACJ,MAAM,KACZ,CAgBF,CAAA"}
+{"version":3,"file":"add-header.d.ts","sourceRoot":"","sources":["../../src/add-header.ts"],"names":[],"mappings":"AAKA,eAAO,MAAM,SAAS,GACpB,CAAC,SACG,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,MAAM,CAAC,EAAE,GAC7B,QAAQ,CAAC,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,MAAM,GAAG,SAAS,CAAC,CAAC,GACjD,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,MAAM,GAAG,SAAS,CAAC,GAC7C,MAAM,EAAE,WAEH,CAAC,GAAG,IAAI,GAAG,SAAS,OACxB,MAAM,UACH,MAAM,KACb,CAkBF,CAAA"}

package/dist/esm/add-header.js

@@ -1,7 +1,10 @@
-const isIterable = (o) => !!o && !!o[Symbol.iterator];
+import { deleteHeader } from "./delete-header.js";
+import { isIterable } from "./is-iterable.js";
 // this does some rude things with types, but not much way around it,
 // since the opts.headers type is so loosey goosey to begin with.
 export const addHeader = (headers, key, value) => {
+    if (!value)
+        return deleteHeader(headers, key);
     if (!headers)
         return { [key]: value };
     if (Array.isArray(headers)) {

package/dist/esm/add-header.js.map

@@ -1 +1 @@
-{"version":3,"file":"add-header.js","sourceRoot":"","sources":["../../src/add-header.ts"],"names":[],"mappings":"AAAA,MAAM,UAAU,GAAG,CAAI,CAAM,EAAoB,EAAE,CACjD,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAA;AAE7B,qEAAqE;AACrE,iEAAiE;AACjE,MAAM,CAAC,MAAM,SAAS,GAAG,CAOvB,OAA6B,EAC7B,GAAW,EACX,KAAa,EACV,EAAE;IACL,IAAI,CAAC,OAAO;QAAE,OAAO,EAAE,CAAC,GAAG,CAAC,EAAE,KAAK,EAAO,CAAA;IAC1C,IAAI,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC,EAAE,CAAC;QAC3B,IAAI,CAAC,OAAO,CAAC,MAAM;YAAE,OAAO,CAAC,CAAC,GAAG,EAAE,KAAK,CAAC,CAAiB,CAAA;QAC1D,IAAI,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC;YAC1B,OAA8B,CAAC,IAAI,CAAC,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC,CAAA;;YAC9C,OAAoB,CAAC,IAAI,CAAC,GAAG,EAAE,KAAK,CAAC,CAAA;QAC3C,OAAO,OAAO,CAAA;IAChB,CAAC;SAAM,IACL,UAAU,CAA0C,OAAO,CAAC,EAC5D,CAAC;QACD,OAAO,CAAC,GAAG,OAAO,EAAE,CAAC,GAAG,EAAE,KAAK,CAAC,CAAiB,CAAA;IACnD,CAAC;SAAM,CAAC;QACN,OAAO,CAAC,GAAG,CAAC,GAAG,KAAK,CAAA;QACpB,OAAO,OAAO,CAAA;IAChB,CAAC;AACH,CAAC,CAAA","sourcesContent":["const isIterable = <T>(o: any): o is Iterable<T> =>\n  !!o && !!o[Symbol.iterator]\n\n// this does some rude things with types, but not much way around it,\n// since the opts.headers type is so loosey goosey to begin with.\nexport const addHeader = <\n  H extends\n    | [string, string[] | string][]\n    | Iterable<[string, string[] | string | undefined]>\n    | Record<string, string[] | string | undefined>\n    | string[],\n>(\n  headers: H | null | undefined,\n  key: string,\n  value: string,\n): H => {\n  if (!headers) return { [key]: value } as H\n  if (Array.isArray(headers)) {\n    if (!headers.length) return [[key, value]] as unknown as H\n    if (Array.isArray(headers[0]))\n      (headers as [string, string][]).push([key, value])\n    else (headers as string[]).push(key, value)\n    return headers\n  } else if (\n    isIterable<[string, string[] | string | undefined]>(headers)\n  ) {\n    return [...headers, [key, value]] as unknown as H\n  } else {\n    headers[key] = value\n    return headers\n  }\n}\n"]}
+{"version":3,"file":"add-header.js","sourceRoot":"","sources":["../../src/add-header.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAA;AACjD,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAA;AAE7C,qEAAqE;AACrE,iEAAiE;AACjE,MAAM,CAAC,MAAM,SAAS,GAAG,CAOvB,OAA6B,EAC7B,GAAW,EACX,KAAc,EACX,EAAE;IACL,IAAI,CAAC,KAAK;QAAE,OAAO,YAAY,CAAC,OAAO,EAAE,GAAG,CAAC,CAAA;IAE7C,IAAI,CAAC,OAAO;QAAE,OAAO,EAAE,CAAC,GAAG,CAAC,EAAE,KAAK,EAAO,CAAA;IAC1C,IAAI,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC,EAAE,CAAC;QAC3B,IAAI,CAAC,OAAO,CAAC,MAAM;YAAE,OAAO,CAAC,CAAC,GAAG,EAAE,KAAK,CAAC,CAAiB,CAAA;QAC1D,IAAI,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC;YAC1B,OAA8B,CAAC,IAAI,CAAC,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC,CAAA;;YAC9C,OAAoB,CAAC,IAAI,CAAC,GAAG,EAAE,KAAK,CAAC,CAAA;QAC3C,OAAO,OAAO,CAAA;IAChB,CAAC;SAAM,IACL,UAAU,CAA0C,OAAO,CAAC,EAC5D,CAAC;QACD,OAAO,CAAC,GAAG,OAAO,EAAE,CAAC,GAAG,EAAE,KAAK,CAAC,CAAiB,CAAA;IACnD,CAAC;SAAM,CAAC;QACN,OAAO,CAAC,GAAG,CAAC,GAAG,KAAK,CAAA;QACpB,OAAO,OAAO,CAAA;IAChB,CAAC;AACH,CAAC,CAAA","sourcesContent":["import { deleteHeader } from './delete-header.ts'\nimport { isIterable } from './is-iterable.ts'\n\n// this does some rude things with types, but not much way around it,\n// since the opts.headers type is so loosey goosey to begin with.\nexport const addHeader = <\n  H extends\n    | [string, string[] | string][]\n    | Iterable<[string, string[] | string | undefined]>\n    | Record<string, string[] | string | undefined>\n    | string[],\n>(\n  headers: H | null | undefined,\n  key: string,\n  value?: string,\n): H => {\n  if (!value) return deleteHeader(headers, key)\n\n  if (!headers) return { [key]: value } as H\n  if (Array.isArray(headers)) {\n    if (!headers.length) return [[key, value]] as unknown as H\n    if (Array.isArray(headers[0]))\n      (headers as [string, string][]).push([key, value])\n    else (headers as string[]).push(key, value)\n    return headers\n  } else if (\n    isIterable<[string, string[] | string | undefined]>(headers)\n  ) {\n    return [...headers, [key, value]] as unknown as H\n  } else {\n    headers[key] = value\n    return headers\n  }\n}\n"]}

package/dist/esm/auth.d.ts

@@ -0,0 +1,9 @@
+import { Keychain } from '@vltpkg/keychain';
+export type Token = `Bearer ${string}` | `Basic ${string}`;
+export declare const keychains: Map<string, Keychain<Token>>;
+export declare const getKC: (identity: string) => Keychain<Token>;
+export declare const isToken: (t: any) => t is Token;
+export declare const deleteToken: (registry: string, identity: string) => Promise<void>;
+export declare const setToken: (registry: string, token: Token, identity: string) => Promise<void>;
+export declare const getToken: (registry: string, identity: string) => Promise<Token | undefined>;
+//# sourceMappingURL=auth.d.ts.map

package/dist/esm/auth.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth.d.ts","sourceRoot":"","sources":["../../src/auth.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAA;AAE3C,MAAM,MAAM,KAAK,GAAG,UAAU,MAAM,EAAE,GAAG,SAAS,MAAM,EAAE,CAAA;AAG1D,eAAO,MAAM,SAAS,8BAAqC,CAAA;AAE3D,eAAO,MAAM,KAAK,aAAc,MAAM,oBAOrC,CAAA;AAED,eAAO,MAAM,OAAO,MAAO,GAAG,KAAG,CAAC,IAAI,KAEe,CAAA;AAErD,eAAO,MAAM,WAAW,aACZ,MAAM,YACN,MAAM,KACf,OAAO,CAAC,IAAI,CAKd,CAAA;AAED,eAAO,MAAM,QAAQ,aACT,MAAM,SACT,KAAK,YACF,MAAM,KACf,OAAO,CAAC,IAAI,CAGd,CAAA;AAED,eAAO,MAAM,QAAQ,aACT,MAAM,YACN,MAAM,KACf,OAAO,CAAC,KAAK,GAAG,SAAS,CAc3B,CAAA"}

package/dist/esm/auth.js

@@ -0,0 +1,39 @@
+import { Keychain } from '@vltpkg/keychain';
+// just exported for testing
+export const keychains = new Map();
+export const getKC = (identity) => {
+    const kc = keychains.get(identity);
+    if (kc)
+        return kc;
+    const i = identity ? `vlt/auth/${identity}` : 'vlt/auth';
+    const nkc = new Keychain(i);
+    keychains.set(identity, nkc);
+    return nkc;
+};
+export const isToken = (t) => typeof t === 'string' &&
+    (t.startsWith('Bearer ') || t.startsWith('Basic '));
+export const deleteToken = async (registry, identity) => {
+    const kc = getKC(identity);
+    await kc.load();
+    kc.delete(new URL(registry).origin);
+    await kc.save();
+};
+export const setToken = async (registry, token, identity) => {
+    const kc = getKC(identity);
+    return kc.set(new URL(registry).origin, token);
+};
+export const getToken = async (registry, identity) => {
+    const kc = getKC(identity);
+    registry = new URL(registry).origin;
+    const envReg = process.env.VLT_REGISTRY;
+    if (envReg && registry === new URL(envReg).origin) {
+        const envTok = process.env.VLT_TOKEN;
+        if (envTok)
+            return `Bearer ${envTok}`;
+    }
+    const tok = process.env[`VLT_TOKEN_${registry.replace(/[^a-zA-Z0-9]+/g, '_')}`];
+    if (tok)
+        return `Bearer ${tok}`;
+    return kc.get(registry);
+};
+//# sourceMappingURL=auth.js.map

package/dist/esm/auth.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth.js","sourceRoot":"","sources":["../../src/auth.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAA;AAI3C,4BAA4B;AAC5B,MAAM,CAAC,MAAM,SAAS,GAAG,IAAI,GAAG,EAA2B,CAAA;AAE3D,MAAM,CAAC,MAAM,KAAK,GAAG,CAAC,QAAgB,EAAE,EAAE;IACxC,MAAM,EAAE,GAAG,SAAS,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAA;IAClC,IAAI,EAAE;QAAE,OAAO,EAAE,CAAA;IACjB,MAAM,CAAC,GAAG,QAAQ,CAAC,CAAC,CAAC,YAAY,QAAQ,EAAE,CAAC,CAAC,CAAC,UAAU,CAAA;IACxD,MAAM,GAAG,GAAG,IAAI,QAAQ,CAAQ,CAAC,CAAC,CAAA;IAClC,SAAS,CAAC,GAAG,CAAC,QAAQ,EAAE,GAAG,CAAC,CAAA;IAC5B,OAAO,GAAG,CAAA;AACZ,CAAC,CAAA;AAED,MAAM,CAAC,MAAM,OAAO,GAAG,CAAC,CAAM,EAAc,EAAE,CAC5C,OAAO,CAAC,KAAK,QAAQ;IACrB,CAAC,CAAC,CAAC,UAAU,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC,UAAU,CAAC,QAAQ,CAAC,CAAC,CAAA;AAErD,MAAM,CAAC,MAAM,WAAW,GAAG,KAAK,EAC9B,QAAgB,EAChB,QAAgB,EACD,EAAE;IACjB,MAAM,EAAE,GAAG,KAAK,CAAC,QAAQ,CAAC,CAAA;IAC1B,MAAM,EAAE,CAAC,IAAI,EAAE,CAAA;IACf,EAAE,CAAC,MAAM,CAAC,IAAI,GAAG,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,CAAA;IACnC,MAAM,EAAE,CAAC,IAAI,EAAE,CAAA;AACjB,CAAC,CAAA;AAED,MAAM,CAAC,MAAM,QAAQ,GAAG,KAAK,EAC3B,QAAgB,EAChB,KAAY,EACZ,QAAgB,EACD,EAAE;IACjB,MAAM,EAAE,GAAG,KAAK,CAAC,QAAQ,CAAC,CAAA;IAC1B,OAAO,EAAE,CAAC,GAAG,CAAC,IAAI,GAAG,CAAC,QAAQ,CAAC,CAAC,MAAM,EAAE,KAAK,CAAC,CAAA;AAChD,CAAC,CAAA;AAED,MAAM,CAAC,MAAM,QAAQ,GAAG,KAAK,EAC3B,QAAgB,EAChB,QAAgB,EACY,EAAE;IAC9B,MAAM,EAAE,GAAG,KAAK,CAAC,QAAQ,CAAC,CAAA;IAC1B,QAAQ,GAAG,IAAI,GAAG,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAA;IACnC,MAAM,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,YAAY,CAAA;IACvC,IAAI,MAAM,IAAI,QAAQ,KAAK,IAAI,GAAG,CAAC,MAAM,CAAC,CAAC,MAAM,EAAE,CAAC;QAClD,MAAM,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,SAAS,CAAA;QACpC,IAAI,MAAM;YAAE,OAAO,UAAU,MAAM,EAAE,CAAA;IACvC,CAAC;IACD,MAAM,GAAG,GACP,OAAO,CAAC,GAAG,CACT,aAAa,QAAQ,CAAC,OAAO,CAAC,gBAAgB,EAAE,GAAG,CAAC,EAAE,CACvD,CAAA;IACH,IAAI,GAAG;QAAE,OAAO,UAAU,GAAG,EAAE,CAAA;IAC/B,OAAO,EAAE,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAA;AACzB,CAAC,CAAA","sourcesContent":["import { Keychain } from '@vltpkg/keychain'\n\nexport type Token = `Bearer ${string}` | `Basic ${string}`\n\n// just exported for testing\nexport const keychains = new Map<string, Keychain<Token>>()\n\nexport const getKC = (identity: string) => {\n  const kc = keychains.get(identity)\n  if (kc) return kc\n  const i = identity ? `vlt/auth/${identity}` : 'vlt/auth'\n  const nkc = new Keychain<Token>(i)\n  keychains.set(identity, nkc)\n  return nkc\n}\n\nexport const isToken = (t: any): t is Token =>\n  typeof t === 'string' &&\n  (t.startsWith('Bearer ') || t.startsWith('Basic '))\n\nexport const deleteToken = async (\n  registry: string,\n  identity: string,\n): Promise<void> => {\n  const kc = getKC(identity)\n  await kc.load()\n  kc.delete(new URL(registry).origin)\n  await kc.save()\n}\n\nexport const setToken = async (\n  registry: string,\n  token: Token,\n  identity: string,\n): Promise<void> => {\n  const kc = getKC(identity)\n  return kc.set(new URL(registry).origin, token)\n}\n\nexport const getToken = async (\n  registry: string,\n  identity: string,\n): Promise<Token | undefined> => {\n  const kc = getKC(identity)\n  registry = new URL(registry).origin\n  const envReg = process.env.VLT_REGISTRY\n  if (envReg && registry === new URL(envReg).origin) {\n    const envTok = process.env.VLT_TOKEN\n    if (envTok) return `Bearer ${envTok}`\n  }\n  const tok =\n    process.env[\n      `VLT_TOKEN_${registry.replace(/[^a-zA-Z0-9]+/g, '_')}`\n    ]\n  if (tok) return `Bearer ${tok}`\n  return kc.get(registry)\n}\n"]}

package/dist/esm/cache-entry.d.ts

@@ -1,33 +1,80 @@
-import { Integrity, JSONField } from '@vltpkg/types';
+import type { ErrorCauseOptions } from '@vltpkg/error-cause';
+import type { Integrity, JSONField } from '@vltpkg/types';
+import ccp from 'cache-control-parser';
+import type { InspectOptions } from 'node:util';
+export type JSONObj = Record<string, JSONField>;
 declare const kCustomInspect: unique symbol;
-export declare class CacheEntry {
-    #private;
-    constructor(statusCode: number, headers: Buffer[], integrity?: Integrity);
-    [kCustomInspect](...args: any[]): string;
+export type CacheEntryOptions = {
+    /**
+     * The expected integrity value for this response body
+     */
+    integrity?: Integrity;
+    /**
+     * 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.
+     */
+    trustIntegrity?: boolean;
     /**
-     * `true` if the entry represents a cached response that is still
-     * valid to use.
+     * 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.
      */
+    'stale-while-revalidate-factor'?: number;
+};
+export declare class CacheEntry {
+    #private;
+    constructor(statusCode: number, headers: Buffer[], { integrity, trustIntegrity, 'stale-while-revalidate-factor': staleWhileRevalidateFactor, }?: CacheEntryOptions);
+    toJSON(): {
+        [k: string]: string | number | boolean | [string, string][] | Date | ccp.CacheControl | undefined;
+    };
+    [kCustomInspect](depth: number, options: InspectOptions): string;
+    get date(): Date | undefined;
+    get maxAge(): number;
+    get cacheControl(): ccp.CacheControl;
+    get staleWhileRevalidate(): boolean;
+    get contentType(): string;
     get valid(): boolean;
     addBody(b: Buffer): void;
     get statusCode(): number;
-    get headers(): Buffer[];
+    get headers(): Buffer<ArrayBufferLike>[];
     /**
-     * check that the sri integrity string that was provided to the ctor
+     * 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 the cache entries are un-gzipped in place. It should
-     * *only* be called for artifacts that come from an actual http response.
+     * _only_ be called for artifacts that come from an actual http response.
+     *
+     * Returns true if anything was actually verified.
      */
-    checkIntegrity(): boolean;
+    checkIntegrity(context?: ErrorCauseOptions): this is CacheEntry & {
+        integrity: Integrity;
+    };
     get integrityActual(): Integrity;
-    get integrity(): `sha512-${string}` | undefined;
+    set integrityActual(i: Integrity);
+    set integrity(i: Integrity | undefined);
+    get integrity(): Integrity | undefined;
     /**
      * Give it a key, and it'll return the buffer of that header value
      */
-    getHeader(h: string): Buffer | undefined;
+    getHeader(h: string): Buffer<ArrayBufferLike> | undefined;
     /**
      * Set a header to a specific value
      */
@@ -53,13 +100,14 @@ export declare class CacheEntry {
     /**
      * Parse the entry body as JSON and return the result
      */
-    json(): Record<string, JSONField>;
+    json(): JSONObj;
     /**
      * 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.
      */
     static decode(buffer: Buffer): CacheEntry;
+    static isGzipEntry(buffer: Buffer): boolean;
     /**
      * Encode the entry as a single Buffer for writing to the cache
      */

package/dist/esm/cache-entry.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cache-entry.d.ts","sourceRoot":"","sources":["../../src/cache-entry.ts"],"names":[],"mappings":"AAsBA,OAAO,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,eAAe,CAAA;AA+BpD,QAAA,MAAM,cAAc,eAA2C,CAAA;AAE/D,qBAAa,UAAU;;gBAUnB,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,MAAM,EAAE,EACjB,SAAS,CAAC,EAAE,SAAS;IAiBvB,CAAC,cAAc,CAAC,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,GAAG,MAAM;IAYxC;;;OAGG;IACH,IAAI,KAAK,IAAI,OAAO,CAsBnB;IAED,OAAO,CAAC,CAAC,EAAE,MAAM;IAKjB,IAAI,UAAU,WAEb;IACD,IAAI,OAAO,aAEV;IAED;;;;;;;;OAQG;IACH,cAAc,IAAI,OAAO;IAIzB,IAAI,eAAe,IAAI,SAAS,CAM/B;IACD,IAAI,SAAS,mCAEZ;IAED;;OAEG;IACH,SAAS,CAAC,CAAC,EAAE,MAAM;IAInB;;OAEG;IACH,SAAS,CAAC,CAAC,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM;IAI3C;;OAEG;IACH,MAAM,IAAI,MAAM;IAWhB,IAAI,IAAI,IAAI,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAEvC;IAGD,IAAI,MAAM,IAAI,OAAO,CAcpB;IAGD,IAAI,MAAM,IAAI,OAAO,CAcpB;IAED;;;;OAIG;IACH,KAAK;IAmBL;;;OAGG;IACH,IAAI;IAKJ;;OAEG;IACH,IAAI,IAAI,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC;IAgBjC;;;;OAIG;IACH,MAAM,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,UAAU;IAiCzC;;OAEG;IAGH,MAAM,IAAI,MAAM;CAoCjB"}
+{"version":3,"file":"cache-entry.d.ts","sourceRoot":"","sources":["../../src/cache-entry.ts"],"names":[],"mappings":"AAqBA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAA;AAE5D,OAAO,KAAK,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,eAAe,CAAA;AACzD,OAAO,GAAG,MAAM,sBAAsB,CAAA;AAEtC,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,WAAW,CAAA;AAK/C,MAAM,MAAM,OAAO,GAAG,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,CAAA;AAyB/C,QAAA,MAAM,cAAc,eAA2C,CAAA;AAE/D,MAAM,MAAM,iBAAiB,GAAG;IAC9B;;OAEG;IACH,SAAS,CAAC,EAAE,SAAS,CAAA;IACrB;;;;;;;OAOG;IACH,cAAc,CAAC,EAAE,OAAO,CAAA;IAExB;;;;;;;;;;;;;;OAcG;IACH,+BAA+B,CAAC,EAAE,MAAM,CAAA;CACzC,CAAA;AAED,qBAAa,UAAU;;gBAYnB,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,MAAM,EAAE,EACjB,EACE,SAAS,EACT,cAAsB,EACtB,+BAA+B,EAC7B,0BAA+B,GAClC,GAAE,iBAAsB;IAmB3B,MAAM;;;IAwCN,CAAC,cAAc,CAAC,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,cAAc,GAAG,MAAM;IAShE,IAAI,IAAI,IAAI,IAAI,GAAG,SAAS,CAK3B;IAGD,IAAI,MAAM,IAAI,MAAM,CAQnB;IAGD,IAAI,YAAY,IAAI,GAAG,CAAC,YAAY,CAKnC;IAGD,IAAI,oBAAoB,IAAI,OAAO,CAWlC;IAGD,IAAI,WAAW,WAKd;IAOD,IAAI,KAAK,IAAI,OAAO,CAmBnB;IAED,OAAO,CAAC,CAAC,EAAE,MAAM;IAKjB,IAAI,UAAU,WAEb;IACD,IAAI,OAAO,8BAEV;IAED;;;;;;;;;;;;OAYG;IACH,cAAc,CACZ,OAAO,GAAE,iBAAsB,GAC9B,IAAI,IAAI,UAAU,GAAG;QAAE,SAAS,EAAE,SAAS,CAAA;KAAE;IAchD,IAAI,eAAe,IAAI,SAAS,CAO/B;IAED,IAAI,eAAe,CAAC,CAAC,EAAE,SAAS,EAG/B;IAED,IAAI,SAAS,CAAC,CAAC,EAAE,SAAS,GAAG,SAAS,EAKrC;IACD,IAAI,SAAS,IANI,SAAS,GAAG,SAAS,CAQrC;IAED;;OAEG;IACH,SAAS,CAAC,CAAC,EAAE,MAAM;IAInB;;OAEG;IACH,SAAS,CAAC,CAAC,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM;IAI3C;;OAEG;IACH,MAAM,IAAI,MAAM;IAWhB,IAAI,IAAI,IAAI,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAEvC;IAGD,IAAI,MAAM,IAAI,OAAO,CAYpB;IAGD,IAAI,MAAM,IAAI,OAAO,CAcpB;IAED;;;;OAIG;IACH,KAAK;IAmBL;;;OAGG;IACH,IAAI;IAKJ;;OAEG;IACH,IAAI,IAAI,OAAO;IAQf;;;;OAIG;IACH,MAAM,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,UAAU;IAsDzC,MAAM,CAAC,WAAW,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO;IAO3C;;OAEG;IAGH,MAAM,IAAI,MAAM;CAmCjB"}