@vltpkg/graph 1.2.0 → 1.3.1

package/dist/graph.js

@@ -427,7 +427,11 @@ export class Graph {
                     toFoundNode.manifest = manifest;
                     this.manifests.set(toFoundNode.id, manifest);
                 }
-                toFoundNode.integrity ??= manifest.dist?.integrity;
+                // never onto a node resolved to a `.tar.br`: `dist.integrity`
+                // is the `.tgz` hash, a different artifact's bytes
+                if (!toFoundNode.brotli) {
+                    toFoundNode.integrity ??= manifest.dist?.integrity;
+                }
             }
             return toFoundNode;
         }
@@ -455,7 +459,10 @@ export class Graph {
         toNode.optional = flags.optional;
         if (samePackage)
             copyPackageMetadata(toNode, samePackage);
-        toNode.integrity ??= manifest?.dist?.integrity;
+        // not onto a node bound for the `.tar.br`: `dist.integrity` is the
+        // `.tgz` hash, and that is a different artifact's bytes
+        if (!toNode.brotli)
+            toNode.integrity ??= manifest?.dist?.integrity;
         // split extra into modifier and peerSetHash
         if (extra) {
             const { modifier, peerSetHash } = splitExtra(extra);

package/dist/lockfile/load-nodes.js

@@ -68,10 +68,13 @@ export const loadNodes = (graph, nodes, options, actual, throwOnMissingManifest)
                 node.peerSetHash = peerSetHash;
             }
         }
-        const { dev, optional } = getBooleanFlagsFromNum(flags);
+        const { dev, optional, brotli } = getBooleanFlagsFromNum(flags);
         node.options = options;
         node.dev = dev;
         node.optional = optional;
+        // before setResolved(), which needs it to pick the extension for a
+        // node whose `resolved` the lockfile left out
+        node.brotli = brotli;
         node.integrity = integrity ?? referenceNode?.integrity;
         node.resolved =
             type === 'remote' ? filepath : ((resolved ?? referenceNode?.resolved));

package/dist/lockfile/types.d.ts

@@ -57,19 +57,30 @@ export declare const LOCKFILE_VERSION = 1;
 export declare const getFlagNumFromNode: (node: {
     optional?: boolean;
     dev?: boolean;
-}) => 1 | 0 | 2 | 3;
+    brotli?: boolean;
+}) => LockfileNodeFlags;
 export declare const getBooleanFlagsFromNum: (flags: LockfileNodeFlags) => {
     dev: boolean;
     optional: boolean;
+    brotli: boolean;
 };
 export declare const LockfileNodeFlagNone = 0;
 export declare const LockfileNodeFlagOptional = 1;
 export declare const LockfileNodeFlagDev = 2;
 export declare const LockfileNodeFlagDevOptional = 3;
 /**
- * Bit flags indicating whether a node is optional and/or dev.
+ * This node's artifact is the registry's Brotli (`.tar.br`) tarball, so
+ * `integrity` is that artifact's hash. Carried as a flag bit rather than a
+ * field because a default-registry node writes no `resolved` at all --
+ * `Node.setResolved()` rebuilds the URL, and this is what tells it which
+ * extension to rebuild.
  */
-export type LockfileNodeFlags = 0 | 1 | 2 | 3;
+export declare const LockfileNodeFlagBrotli = 4;
+/**
+ * Bit flags indicating whether a node is optional, dev, and/or served as
+ * a Brotli tarball.
+ */
+export type LockfileNodeFlags = 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7;
 /**
  * Build state constants for lockfile nodes
  */

package/dist/lockfile/types.js

@@ -4,18 +4,26 @@
  * Bump when making breaking format changes.
  */
 export const LOCKFILE_VERSION = 1;
-export const getFlagNumFromNode = (node) => node.optional && node.dev ? LockfileNodeFlagDevOptional
-    : node.optional ? LockfileNodeFlagOptional
-        : node.dev ? LockfileNodeFlagDev
-            : LockfileNodeFlagNone;
+export const getFlagNumFromNode = (node) => ((node.optional ? LockfileNodeFlagOptional : 0) |
+    (node.dev ? LockfileNodeFlagDev : 0) |
+    (node.brotli ? LockfileNodeFlagBrotli : 0));
 export const getBooleanFlagsFromNum = (flags) => ({
     dev: !!(flags & LockfileNodeFlagDev),
     optional: !!(flags & LockfileNodeFlagOptional),
+    brotli: !!(flags & LockfileNodeFlagBrotli),
 });
 export const LockfileNodeFlagNone = 0;
 export const LockfileNodeFlagOptional = 1;
 export const LockfileNodeFlagDev = 2;
 export const LockfileNodeFlagDevOptional = 3;
+/**
+ * This node's artifact is the registry's Brotli (`.tar.br`) tarball, so
+ * `integrity` is that artifact's hash. Carried as a flag bit rather than a
+ * field because a default-registry node writes no `resolved` at all --
+ * `Node.setResolved()` rebuilds the URL, and this is what tells it which
+ * extension to rebuild.
+ */
+export const LockfileNodeFlagBrotli = 4;
 /**
  * Build state constants for lockfile nodes
  */

package/dist/node.d.ts

@@ -7,6 +7,11 @@ import type { Graph } from './graph.ts';
 export type NodeOptions = SpecOptions & {
     projectRoot: string;
     graph: GraphLike;
+    /**
+     * Resolve to a version's Brotli (`.tar.br`) alternate when its manifest
+     * advertises one. Defaults to true; false always resolves to the `.tgz`.
+     */
+    'brotli-tarballs'?: boolean;
 };
 export declare class Node implements NodeLike {
     #private;
@@ -85,6 +90,16 @@ export declare class Node implements NodeLike {
      * The manifest this node represents in the graph.
      */
     manifest?: NormalizedManifest;
+    /**
+     * True when this node's artifact is the registry's Brotli (`.tar.br`)
+     * tarball rather than the gzip `.tgz`, which makes `integrity` that
+     * artifact's hash. `resolved` is authoritative whenever it is set, so
+     * the two can never drift; the stored bit only carries the lockfile's
+     * answer across to `setResolved()`, which has to know the extension
+     * before it can build the URL.
+     */
+    get brotli(): boolean;
+    set brotli(brotli: boolean);
     /**
      * Project where this node resides
      */

package/dist/node.js

@@ -1,8 +1,15 @@
 import { isPackageNameConfused, getId, hydrateTuple, splitDepID, } from '@vltpkg/dep-id';
 import { typeError } from '@vltpkg/error-cause';
-import { expandNormalizedManifestSymbols } from '@vltpkg/types';
+import { brotliTarballName, brotliTarballUrl, expandNormalizedManifestSymbols, tarballFormat, } from '@vltpkg/types';
 import { Edge } from "./edge.js";
 import { stringifyNode } from "./stringify-node.js";
+/**
+ * The absolute URL of a version's Brotli (`.tar.br`) tarball. `dist`
+ * arrives here with an absolute `tarball`, so the alternate's relative
+ * reference resolves against it. See {@link brotliTarballUrl} for which
+ * references this client accepts.
+ */
+const brotliAlternate = (dist) => brotliTarballUrl(dist?.tarball, dist?.alternates);
 export class Node {
     get [Symbol.toStringTag]() {
         return '@vltpkg/graph.Node';
@@ -110,6 +117,31 @@ export class Node {
      * The manifest this node represents in the graph.
      */
     manifest;
+    /**
+     * Whether this node's artifact is the `.tar.br`: from the manifest's
+     * `dist.alternates` at construction, or overwritten by the lockfile's
+     * flag bit when the node came from one (so an existing lockfile keeps
+     * whichever artifact it pinned). Only consulted while `resolved` is
+     * still unset -- once there is a URL, it is the answer (see the
+     * getter).
+     */
+    #brotli = false;
+    /**
+     * True when this node's artifact is the registry's Brotli (`.tar.br`)
+     * tarball rather than the gzip `.tgz`, which makes `integrity` that
+     * artifact's hash. `resolved` is authoritative whenever it is set, so
+     * the two can never drift; the stored bit only carries the lockfile's
+     * answer across to `setResolved()`, which has to know the extension
+     * before it can build the URL.
+     */
+    get brotli() {
+        return this.resolved ?
+            tarballFormat(this.resolved) === 'brotli'
+            : this.#brotli;
+    }
+    set brotli(brotli) {
+        this.#brotli = brotli;
+    }
     /**
      * Project where this node resides
      */
@@ -245,6 +277,13 @@ export class Node {
         }
         this.graph = options.graph;
         this.manifest = manifest;
+        // Settled here, not in setResolved(), because `integrity` is filled
+        // in from `dist.integrity` between the two -- and that hash is the
+        // `.tgz`'s. A node whose artifact is the `.tar.br` has to be able to
+        // turn that down before it arrives.
+        this.#brotli =
+            options['brotli-tarballs'] !== false &&
+                !!brotliAlternate(manifest?.dist);
         this.#name = name || this.manifest?.name;
         this.version = version || this.manifest?.version;
     }
@@ -263,9 +302,28 @@ export class Node {
     }
     #registryNodeResolved(tuple) {
         const spec = hydrateTuple(tuple, this.#name, this.#options);
-        this.resolved =
-            this.manifest?.dist?.tarball || spec.conventionalRegistryTarball;
-        this.integrity ??= this.manifest?.dist?.integrity;
+        const dist = this.manifest?.dist;
+        const tarball = dist?.tarball || spec.conventionalRegistryTarball;
+        // Use the manifest's own reference if there is one. Otherwise build
+        // the URL the way the registry names these: the same stem as the
+        // `.tgz` with a different extension. Relying on that convention is
+        // what lets a lockfile node, which has no manifest, store one flag
+        // bit instead of a second URL.
+        const alt = this.#brotli ? brotliAlternate(dist) : undefined;
+        const brotli = this.#brotli ?
+            (alt?.tarball ?? (tarball && brotliTarballName(tarball)))
+            : undefined;
+        if (brotli) {
+            this.resolved = brotli;
+            // `dist.integrity` belongs to the `.tgz`, so never copy it here.
+            // Use the alternate's own hash if the registry sent one. If not,
+            // the first fetch learns it from the Repr-Digest header.
+            if (alt?.integrity)
+                this.integrity ??= alt.integrity;
+            return;
+        }
+        this.resolved = tarball;
+        this.integrity ??= dist?.integrity;
     }
     get options() {
         return this.#options;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@vltpkg/graph",
   "description": "A library that helps understanding & expressing what happens on an install",
-  "version": "1.2.0",
+  "version": "1.3.1",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/vltpkg/vltpkg.git",
@@ -13,26 +13,26 @@
     "url": "http://vlt.sh"
   },
   "dependencies": {
-    "@vltpkg/cmd-shim": "1.2.0",
-    "@vltpkg/dep-id": "1.2.0",
-    "@vltpkg/dss-breadcrumb": "1.2.0",
-    "@vltpkg/error-cause": "1.2.0",
-    "@vltpkg/fast-split": "1.2.0",
-    "@vltpkg/graph-run": "1.2.0",
-    "@vltpkg/init": "1.2.0",
-    "@vltpkg/output": "1.2.0",
-    "@vltpkg/package-info": "1.2.0",
-    "@vltpkg/package-json": "1.2.0",
-    "@vltpkg/pick-manifest": "1.2.0",
-    "@vltpkg/query": "1.2.0",
-    "@vltpkg/rollback-remove": "1.2.0",
-    "@vltpkg/run": "1.2.0",
-    "@vltpkg/satisfies": "1.2.0",
-    "@vltpkg/security-archive": "1.2.0",
-    "@vltpkg/spec": "1.2.0",
-    "@vltpkg/types": "1.2.0",
-    "@vltpkg/vlt-json": "1.2.0",
-    "@vltpkg/workspaces": "1.2.0",
+    "@vltpkg/cmd-shim": "1.3.1",
+    "@vltpkg/dep-id": "1.3.1",
+    "@vltpkg/dss-breadcrumb": "1.3.1",
+    "@vltpkg/error-cause": "1.3.1",
+    "@vltpkg/fast-split": "1.3.1",
+    "@vltpkg/graph-run": "1.3.1",
+    "@vltpkg/init": "1.3.1",
+    "@vltpkg/output": "1.3.1",
+    "@vltpkg/package-info": "1.3.1",
+    "@vltpkg/package-json": "1.3.1",
+    "@vltpkg/pick-manifest": "1.3.1",
+    "@vltpkg/query": "1.3.1",
+    "@vltpkg/rollback-remove": "1.3.1",
+    "@vltpkg/run": "1.3.1",
+    "@vltpkg/satisfies": "1.3.1",
+    "@vltpkg/security-archive": "1.3.1",
+    "@vltpkg/spec": "1.3.1",
+    "@vltpkg/types": "1.3.1",
+    "@vltpkg/vlt-json": "1.3.1",
+    "@vltpkg/workspaces": "1.3.1",
     "path-scurry": "^2.0.1",
     "promise-call-limit": "^3.0.2"
   },