@vltpkg/types 1.3.0 → 1.3.1

package/dist/index.d.ts

@@ -35,14 +35,22 @@ export type Dist = {
      * reference relative to this `dist`'s `tarball` (e.g. the bare filename
      * `foo-1.2.3.tar.br`), resolved with `new URL(entry.tarball, tarball)`.
      *
-     * An alternate is a *different artifact*, not a different encoding of the
-     * same bytes: it carries no `integrity` here and hashes differently from
-     * the `.tgz`. A client that downloads one pins that artifact's own hash,
-     * taken from the tarball response's RFC 9530 `Repr-Digest`.
+     * An alternate is a different artifact, not a re-encoding of the same
+     * bytes. It hashes differently from the `.tgz`, so `dist.integrity` does
+     * not describe it.
+     *
+     * The `integrity` field here is the alternate's own hash. It is optional,
+     * because a hash does not compress and a registry may prefer to keep
+     * packuments small. If a registry does send it, the client pins it like
+     * any other integrity, and can look the package up in the global store
+     * without downloading anything first. If it does not, the client verifies
+     * the download against the tarball response's RFC 9530 `Repr-Digest`
+     * header and learns the hash from there.
      */
     alternates?: {
         kind: string;
         tarball: string;
+        integrity?: Integrity;
     }[];
 };
 /** An object used to mark some peerDeps as optional */
@@ -455,7 +463,13 @@ export declare const brotliTarballName: (tgz: string) => string;
  * those derivations sound -- and costs an unusual reference the
  * optimization rather than the install.
  */
-export declare const brotliTarballUrl: (tarball: string | undefined, alternates: Dist["alternates"]) => string | undefined;
+export type BrotliAlternate = {
+    /** The absolute URL of the `.tar.br`. */
+    tarball: string;
+    /** The alternate's own hash, if the registry sent one. */
+    integrity?: Integrity;
+};
+export declare const brotliTarballUrl: (tarball: string | undefined, alternates: Dist["alternates"]) => BrotliAlternate | undefined;
 export declare const keyIDRE: RegExp;
 export declare const isKeyID: (k: unknown) => k is KeyID;
 export declare const asKeyID: (k: unknown) => KeyID;

package/dist/index.js

@@ -566,23 +566,6 @@ export const tarballFormat = (url) => {
  * and a different extension.
  */
 export const brotliTarballName = (tgz) => tgz.replace(/\.tgz$/, BROTLI_TARBALL_EXT);
-/**
- * The absolute URL of a version's Brotli (`.tar.br`) tarball, from the
- * `tar.br` entry in its `dist.alternates` -- but only when that entry
- * resolves to the `.tgz`'s own sibling, i.e. {@link brotliTarballName} of
- * `tarball`. Anything else reads as no alternate at all.
- *
- * `alternates[].tarball` is a reference relative to `dist.tarball`, and
- * the protocol lets a registry point it anywhere. This client uses only
- * the conventional name, because two things downstream re-derive it and
- * both would otherwise be wrong: the format is read back off the URL
- * suffix (brotli bytes carry no signature to sniff), and a lockfile node
- * spends a single flag bit instead of a second URL, rebuilding the
- * address from the `.tgz` by this same convention. Narrowing here, at
- * the one point where the alternate is chosen, is what makes both of
- * those derivations sound -- and costs an unusual reference the
- * optimization rather than the install.
- */
 export const brotliTarballUrl = (tarball, alternates) => {
     if (!tarball)
         return undefined;
@@ -591,9 +574,17 @@ export const brotliTarballUrl = (tarball, alternates) => {
         return undefined;
     try {
         const href = new URL(entry.tarball, tarball).href;
-        return href === new URL(brotliTarballName(tarball)).href ?
-            href
-            : undefined;
+        if (href !== new URL(brotliTarballName(tarball)).href) {
+            return undefined;
+        }
+        // Ignore a hash we cannot parse. Pinning it would fail every check,
+        // so it is better to fall back to the Repr-Digest.
+        return {
+            tarball: href,
+            ...(isIntegrity(entry.integrity) && {
+                integrity: entry.integrity,
+            }),
+        };
         /* c8 ignore start - a malformed reference just means no brotli */
     }
     catch {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@vltpkg/types",
   "description": "definitions for some of vlt's core types",
-  "version": "1.3.0",
+  "version": "1.3.1",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/vltpkg/vltpkg.git",
@@ -13,10 +13,10 @@
     "url": "http://vlt.sh"
   },
   "dependencies": {
-    "@vltpkg/dep-id": "1.3.0",
-    "@vltpkg/error-cause": "1.3.0",
-    "@vltpkg/semver": "1.3.0",
-    "@vltpkg/spec": "1.3.0"
+    "@vltpkg/dep-id": "1.3.1",
+    "@vltpkg/error-cause": "1.3.1",
+    "@vltpkg/semver": "1.3.1",
+    "@vltpkg/spec": "1.3.1"
   },
   "devDependencies": {
     "@eslint/js": "^9.39.1",