@vltpkg/types 1.2.0 → 1.3.1

package/dist/index.d.ts

@@ -29,6 +29,29 @@ export type Dist = {
         keyid: KeyID;
         sig: string;
     }[];
+    /**
+     * Alternate tarball formats the registry offers for this version. A
+     * `tar.br` entry is a Brotli-recompressed tar whose `tarball` is a
+     * 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 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 */
 export type PeerDependenciesMetaValue = {
@@ -299,6 +322,17 @@ export type Manifest = {
     contributors?: Person[];
     /** the license of the package */
     license?: string;
+    /**
+     * npm/yarn-style workspace globs. Honored by vlt as a fallback when
+     * `vlt.json` has no `workspaces` field of its own. Only the npm
+     * (`string[]`) and yarn-classic (`{packages}`) forms are accepted;
+     * vlt's named workspace groups are a `vlt.json` feature. yarn's
+     * `nohoist` is parsed and ignored.
+     */
+    workspaces?: string[] | {
+        packages?: string[] | string;
+        nohoist?: string[];
+    } | string;
 };
 export type NormalizedFields = {
     bugs: NormalizedBugs | undefined;
@@ -387,6 +421,55 @@ export declare const assertIntegrity: (i: unknown) => asserts i is Integrity;
  * sha512 integrity. Names tarball cache and global store entries.
  */
 export declare const integrityHex: (i: unknown) => string | undefined;
+/**
+ * How a tarball's bytes are compressed. `gzip` is sniffed from the two
+ * magic bytes (the `.tgz` and raw-tar cases), so it never has to be
+ * passed. Brotli has no magic-byte signature, so a `.tar.br` MUST be
+ * declared by the caller -- it can never be detected from the bytes.
+ */
+export type TarballFormat = 'gzip' | 'brotli';
+/** Filename extension of a Brotli-recompressed tarball. */
+export declare const BROTLI_TARBALL_EXT = ".tar.br";
+/**
+ * The {@link TarballFormat} a tarball URL (or a registry-client cache key,
+ * which is the URL) names, or undefined when the bytes can be sniffed.
+ *
+ * The extension is the only signal there is: brotli bytes are opaque, and
+ * the response carries no `Content-Encoding` (a `.tar.br` is an artifact in
+ * its own right, not a transfer encoding of the `.tgz`). Query and fragment
+ * are ignored so a signed or cache-busted URL still reads correctly.
+ */
+export declare const tarballFormat: (url: string) => TarballFormat | undefined;
+/**
+ * `https://…/foo-1.2.3.tgz` -> `https://…/foo-1.2.3.tar.br`: the name a
+ * registry gives a version's Brotli alternate, same stem as the `.tgz`
+ * and a different extension.
+ */
+export declare const brotliTarballName: (tgz: string) => string;
+/**
+ * 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 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;
@@ -537,6 +620,14 @@ export type NodeLike = {
     integrity?: string | null;
     resolved?: string | null;
     resolvedFromLockfile?: boolean;
+    /**
+     * This node's artifact is the registry's Brotli (`.tar.br`) tarball
+     * rather than the gzip `.tgz`, so `resolved` and `integrity` both
+     * describe that artifact. Persisted in the lockfile as a flag bit, which
+     * is what lets `setResolved()` rebuild the `.tar.br` URL for a node whose
+     * `resolved` is not written out.
+     */
+    brotli?: boolean;
     importer: boolean;
     graph: GraphLike;
     mainImporter: boolean;

package/dist/index.js

@@ -544,6 +544,54 @@ export const assertIntegrity = i => {
 export const integrityHex = (i) => isIntegrity(i) ?
     Buffer.from(i.slice(7), 'base64').toString('hex')
     : undefined;
+/** Filename extension of a Brotli-recompressed tarball. */
+export const BROTLI_TARBALL_EXT = '.tar.br';
+/**
+ * The {@link TarballFormat} a tarball URL (or a registry-client cache key,
+ * which is the URL) names, or undefined when the bytes can be sniffed.
+ *
+ * The extension is the only signal there is: brotli bytes are opaque, and
+ * the response carries no `Content-Encoding` (a `.tar.br` is an artifact in
+ * its own right, not a transfer encoding of the `.tgz`). Query and fragment
+ * are ignored so a signed or cache-busted URL still reads correctly.
+ */
+export const tarballFormat = (url) => {
+    // endsWith's second argument reads the string as if it ended there
+    const end = /[?#]/.exec(url)?.index ?? url.length;
+    return url.endsWith(BROTLI_TARBALL_EXT, end) ? 'brotli' : undefined;
+};
+/**
+ * `https://…/foo-1.2.3.tgz` -> `https://…/foo-1.2.3.tar.br`: the name a
+ * registry gives a version's Brotli alternate, same stem as the `.tgz`
+ * and a different extension.
+ */
+export const brotliTarballName = (tgz) => tgz.replace(/\.tgz$/, BROTLI_TARBALL_EXT);
+export const brotliTarballUrl = (tarball, alternates) => {
+    if (!tarball)
+        return undefined;
+    const entry = alternates?.find(a => a.kind === 'tar.br' && !!a.tarball);
+    if (!entry)
+        return undefined;
+    try {
+        const href = new URL(entry.tarball, tarball).href;
+        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 {
+        return undefined;
+    }
+    /* c8 ignore stop */
+};
 export const keyIDRE = /^SHA256:[a-zA-Z0-9/+]{43}$/;
 export const isKeyID = (k) => typeof k === 'string' && keyIDRE.test(k);
 export const asKeyID = (k) => {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@vltpkg/types",
   "description": "definitions for some of vlt's core types",
-  "version": "1.2.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.2.0",
-    "@vltpkg/error-cause": "1.2.0",
-    "@vltpkg/semver": "1.2.0",
-    "@vltpkg/spec": "1.2.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",