@pnpm/resolving.npm-resolver 1102.1.7 → 1102.1.8

package/lib/memoizeFetchMetadata.d.ts

@@ -0,0 +1,40 @@
+import type { PackageMeta } from '@pnpm/resolving.registry.types';
+import type { FetchMetadataNotModifiedResult, FetchMetadataOptions, FetchMetadataResult } from './fetch.js';
+export type FetchMetadata = (pkgName: string, opts: FetchMetadataOptions) => Promise<FetchMetadataResult | FetchMetadataNotModifiedResult>;
+export interface MemoizedFetchMetadata {
+    fetch: FetchMetadata;
+    clear: () => void;
+}
+export interface MemoizeFetchMetadataOptions {
+    /**
+     * Applied to a settled result's `meta` before the entry is retained for the
+     * rest of the resolution phase, so a full document doesn't stay pinned here
+     * at full size. Callers awaiting the in-flight request still receive the
+     * original document.
+     */
+    condenseSettledMeta?: (meta: PackageMeta) => PackageMeta;
+}
+/**
+ * Memoizes metadata fetches for the whole resolution phase (cleared via
+ * `clear`, see `clearResolutionCache`), deduplicating concurrent and repeat
+ * requests for the same package.
+ *
+ * Unlike plain memoization, the entry is swapped for a body-less clone once
+ * the request settles. `jsonText` — the raw registry response body, up to tens
+ * of MB for a popular package — reaches every caller sharing the in-flight
+ * request, so a package resolved by many workspace projects at once mirrors
+ * that one body to disk instead of each project separately re-serializing
+ * `meta`. Retaining bodies past settlement would pin hundreds of MB on large
+ * cold-cache graphs, so a later cache-hit caller that writes the mirror falls
+ * back to `JSON.stringify(meta)` in `prepareJsonForDisk`, which is equivalent
+ * on read: `loadMeta` re-derives `etag` from the headers line.
+ *
+ * Because that swap lands a turn after the request settles, both settlement
+ * paths write back only while the entry is still their own promise — a `clear`
+ * (or a retry that already replaced the entry) must not be undone by a request
+ * that was in flight when it happened.
+ *
+ * A rejected fetch is evicted so a transient network failure is retried by
+ * the next request instead of being cached for the rest of the phase.
+ */
+export declare function memoizeFetchMetadata(fetch: FetchMetadata, memoOpts?: MemoizeFetchMetadataOptions): MemoizedFetchMetadata;

package/lib/memoizeFetchMetadata.js

@@ -0,0 +1,66 @@
+/**
+ * Memoizes metadata fetches for the whole resolution phase (cleared via
+ * `clear`, see `clearResolutionCache`), deduplicating concurrent and repeat
+ * requests for the same package.
+ *
+ * Unlike plain memoization, the entry is swapped for a body-less clone once
+ * the request settles. `jsonText` — the raw registry response body, up to tens
+ * of MB for a popular package — reaches every caller sharing the in-flight
+ * request, so a package resolved by many workspace projects at once mirrors
+ * that one body to disk instead of each project separately re-serializing
+ * `meta`. Retaining bodies past settlement would pin hundreds of MB on large
+ * cold-cache graphs, so a later cache-hit caller that writes the mirror falls
+ * back to `JSON.stringify(meta)` in `prepareJsonForDisk`, which is equivalent
+ * on read: `loadMeta` re-derives `etag` from the headers line.
+ *
+ * Because that swap lands a turn after the request settles, both settlement
+ * paths write back only while the entry is still their own promise — a `clear`
+ * (or a retry that already replaced the entry) must not be undone by a request
+ * that was in flight when it happened.
+ *
+ * A rejected fetch is evicted so a transient network failure is retried by
+ * the next request instead of being cached for the rest of the phase.
+ */
+export function memoizeFetchMetadata(fetch, memoOpts) {
+    const condense = memoOpts?.condenseSettledMeta;
+    const cache = new Map();
+    return {
+        fetch: (pkgName, opts) => {
+            const key = JSON.stringify([pkgName, opts]);
+            const cached = cache.get(key);
+            if (cached != null)
+                return cached;
+            const pending = fetch(pkgName, opts);
+            cache.set(key, pending);
+            void pending.then((result) => {
+                if (cache.get(key) !== pending)
+                    return;
+                cache.set(key, Promise.resolve(settledEntry(result)));
+            }, () => {
+                if (cache.get(key) === pending)
+                    cache.delete(key);
+            });
+            return pending;
+        },
+        clear: () => {
+            cache.clear();
+        },
+    };
+    // Runs inside a fire-and-forget then-callback where a throw would become an
+    // unhandled rejection, so a failed condense falls back to the uncondensed
+    // meta; the resolution path condenses the same document with proper error
+    // propagation.
+    function settledEntry(result) {
+        if (result.notModified)
+            return result;
+        let meta = result.meta;
+        if (condense != null) {
+            try {
+                meta = condense(result.meta);
+            }
+            catch { }
+        }
+        return { ...result, jsonText: undefined, meta };
+    }
+}
+//# sourceMappingURL=memoizeFetchMetadata.js.map

package/lib/normalizeRegistryUrl.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Remove default ports (80 for HTTP, 443 for HTTPS) to ensure consistency
+ */
+export declare function normalizeRegistryUrl(urlString: string): string;

package/lib/normalizeRegistryUrl.js

@@ -0,0 +1,12 @@
+/**
+ * Remove default ports (80 for HTTP, 443 for HTTPS) to ensure consistency
+ */
+export function normalizeRegistryUrl(urlString) {
+    try {
+        return new URL(urlString).toString();
+    }
+    catch {
+        return urlString;
+    }
+}
+//# sourceMappingURL=normalizeRegistryUrl.js.map

package/lib/parseBareSpecifier.d.ts

@@ -0,0 +1,16 @@
+export interface RegistryPackageSpec {
+    type: 'tag' | 'version' | 'range';
+    name: string;
+    fetchSpec: string;
+    normalizedBareSpecifier?: string;
+}
+export declare function parseBareSpecifier(bareSpecifier: string, alias: string | undefined, defaultTag: string, registry: string): RegistryPackageSpec | null;
+export interface JsrRegistryPackageSpec extends RegistryPackageSpec {
+    jsrPkgName: string;
+}
+export declare function parseJsrSpecifierToRegistryPackageSpec(rawSpecifier: string, alias: string | undefined, defaultTag: string): JsrRegistryPackageSpec | null;
+export declare const BUILTIN_NAMED_REGISTRIES: Readonly<Record<string, string>>;
+export interface NamedRegistryPackageSpec extends RegistryPackageSpec {
+    registryName: string;
+}
+export declare function parseNamedRegistrySpecifierToRegistryPackageSpec(rawSpecifier: string, knownRegistryNames: ReadonlySet<string>, packageAlias: string | undefined, defaultTag: string): NamedRegistryPackageSpec | null;

package/lib/parseBareSpecifier.js

@@ -0,0 +1,143 @@
+import { PnpmError } from '@pnpm/error';
+import { parseJsrSpecifier } from '@pnpm/resolving.jsr-specifier-parser';
+import { parseNpmTarballUrl } from 'parse-npm-tarball-url';
+import semver from 'semver';
+import validateNpmPackageName from 'validate-npm-package-name';
+import getVersionSelectorType from 'version-selector-type';
+export function parseBareSpecifier(bareSpecifier, alias, defaultTag, registry) {
+    let name = alias;
+    if (bareSpecifier.startsWith('npm:')) {
+        bareSpecifier = bareSpecifier.slice(4);
+        // `npm:<version_selector>` — fall back to the outer dependency alias as
+        // the package name, mirroring the named-registry shape (e.g. `gh:^1.0.0`).
+        // Restricted to semver ranges/versions so unscoped package names like
+        // `npm:is-positive` keep their npm package-aliasing meaning.
+        if (alias && semver.validRange(bareSpecifier) != null) {
+            name = alias;
+        }
+        else {
+            const index = bareSpecifier.lastIndexOf('@');
+            if (index < 1) {
+                name = bareSpecifier;
+                bareSpecifier = defaultTag;
+            }
+            else {
+                name = bareSpecifier.slice(0, index);
+                bareSpecifier = bareSpecifier.slice(index + 1);
+            }
+        }
+    }
+    if (name) {
+        const selector = getVersionSelectorType(bareSpecifier);
+        if (selector != null) {
+            return {
+                fetchSpec: selector.normalized,
+                name,
+                type: selector.type,
+            };
+        }
+    }
+    if (bareSpecifier.startsWith(registry)) {
+        const pkg = parseNpmTarballUrl(bareSpecifier);
+        if (pkg != null) {
+            return {
+                fetchSpec: pkg.version,
+                name: pkg.name,
+                normalizedBareSpecifier: bareSpecifier,
+                type: 'version',
+            };
+        }
+    }
+    return null;
+}
+export function parseJsrSpecifierToRegistryPackageSpec(rawSpecifier, alias, defaultTag) {
+    const spec = parseJsrSpecifier(rawSpecifier, alias);
+    if (!spec?.npmPkgName)
+        return null;
+    const selector = getVersionSelectorType(spec.versionSelector ?? defaultTag);
+    if (selector == null)
+        return null;
+    return {
+        fetchSpec: selector.normalized,
+        name: spec.npmPkgName,
+        type: selector.type,
+        jsrPkgName: spec.jsrPkgName,
+    };
+}
+export const BUILTIN_NAMED_REGISTRIES = Object.freeze({
+    gh: 'https://npm.pkg.github.com/',
+});
+// Parses a named-registry specifier of the shape `<alias>:<body>` into a
+// RegistryPackageSpec. Returns `null` when the specifier does not use one of
+// the configured aliases, so the caller can fall through to other resolvers.
+// Throws INVALID_NAMED_REGISTRY_PACKAGE_NAME when the alias matches but the
+// package name is malformed (missing or empty scope/name segments, path
+// separators inside the name).
+// Supported shapes:
+// - `<alias>:[@<owner>/]<name>[@<version_selector>]`
+// - `<alias>:<version_selector>` paired with a package alias
+export function parseNamedRegistrySpecifierToRegistryPackageSpec(rawSpecifier, knownRegistryNames, packageAlias, defaultTag) {
+    const colon = rawSpecifier.indexOf(':');
+    if (colon <= 0)
+        return null;
+    const registryName = rawSpecifier.substring(0, colon);
+    if (!knownRegistryNames.has(registryName))
+        return null;
+    const body = rawSpecifier.substring(colon + 1);
+    let pkgName;
+    let versionSelector;
+    if (semver.validRange(body) != null) {
+        // `<alias>:<version_selector>` — fall back to the dependency alias as
+        // the package name. Unresolvable without one.
+        if (!packageAlias)
+            return null;
+        pkgName = packageAlias;
+        versionSelector = body;
+    }
+    else if (body[0] === '@') {
+        // `<alias>:@<owner>/<name>[@<version_selector>]` — scoped package.
+        const index = body.lastIndexOf('@');
+        if (index === 0) {
+            pkgName = body;
+        }
+        else {
+            pkgName = body.substring(0, index);
+            versionSelector = body.substring(index + '@'.length);
+        }
+    }
+    else if (packageAlias?.startsWith('@')) {
+        // `<alias>:<tag>` paired with a scoped alias — body is a version
+        // selector (tag/dist-tag). Mirrors GitHub Packages, where the package
+        // is always scoped and a bare body is a tag.
+        pkgName = packageAlias;
+        versionSelector = body;
+    }
+    else {
+        // `<alias>:<name>[@<version_selector>]` — unscoped package in body.
+        const index = body.lastIndexOf('@');
+        if (index < 1) {
+            pkgName = body;
+        }
+        else {
+            pkgName = body.substring(0, index);
+            versionSelector = body.substring(index + '@'.length);
+        }
+        if (!pkgName)
+            return null;
+    }
+    // The name is used in registry URLs and metadata cache file paths, so
+    // anything that is not a valid npm package name must never make it through.
+    if (!validateNpmPackageName(pkgName).validForOldPackages) {
+        throw new PnpmError('INVALID_NAMED_REGISTRY_PACKAGE_NAME', `The package name '${pkgName}' in named registry '${registryName}:' is invalid`);
+    }
+    const selector = getVersionSelectorType(versionSelector ?? defaultTag);
+    if (selector == null)
+        return null;
+    return {
+        fetchSpec: selector.normalized,
+        name: pkgName,
+        type: selector.type,
+        registryName,
+    };
+}
+//# sourceMappingURL=parseBareSpecifier.js.map

package/lib/pickPackage.d.ts

@@ -0,0 +1,113 @@
+import type { PackageInRegistry, PackageMeta } from '@pnpm/resolving.registry.types';
+import { type FetchMetadataNotModifiedResult, type FetchMetadataResult } from './fetch.js';
+import type { RegistryPackageSpec } from './parseBareSpecifier.js';
+import { type PickPackageFromMetaOptions } from './pickPackageFromMeta.js';
+export interface PackageMetaCache {
+    /**
+     * Must return the same object reference that `set` stored for the key: the
+     * resolver tracks whether a cached packument was validated against the
+     * registry by object identity (see `unverifiedDiskPackuments`). In a cache
+     * that clones or deserializes on read, that provenance is lost and recovery
+     * degrades — a stale disk-promoted entry that can't satisfy a spec fails
+     * the pick instead of falling through to the registry.
+     */
+    get: (key: string) => PackageMeta | undefined;
+    set: (key: string, meta: PackageMeta) => void;
+    has: (key: string) => boolean;
+}
+export interface PickPackageOptions extends PickPackageFromMetaOptions {
+    authHeaderValue?: string;
+    pickLowestVersion?: boolean;
+    registry: string;
+    dryRun: boolean;
+    includeLatestTag?: boolean;
+    optional?: boolean;
+    /**
+     * When true, force a conditional registry request so a stale on-disk
+     * packument can't satisfy the call: the on-disk exact-version fast
+     * path is skipped, and the in-memory cache is bypassed too. The fast
+     * path now promotes disk-loaded packuments into the in-memory cache,
+     * so an entry there can no longer be assumed to come from this
+     * install's own fresh network fetch — on a shared or long-lived
+     * resolver it might be disk-sourced, which would short-circuit the
+     * revalidation updateChecksums exists to force.
+     */
+    updateChecksums?: boolean;
+}
+export declare function pickPackage(ctx: {
+    fetch: (pkgName: string, opts: {
+        registry: string;
+        authHeaderValue?: string;
+        cacheBypass?: boolean;
+        fullMetadata?: boolean;
+        etag?: string;
+        modified?: string;
+    }) => Promise<FetchMetadataResult | FetchMetadataNotModifiedResult>;
+    fullMetadata?: boolean;
+    metaCache: PackageMetaCache;
+    cacheDir: string;
+    offline?: boolean;
+    preferOffline?: boolean;
+    filterMetadata?: boolean;
+    ignoreMissingTimeField?: boolean;
+}, spec: RegistryPackageSpec, opts: PickPackageOptions): Promise<{
+    meta: PackageMeta;
+    pickedPackage: PackageInRegistry | null;
+}>;
+export declare function encodePkgName(pkgName: string): string;
+/**
+ * Key for the in-memory `metaCache` holding a package's registry metadata. The
+ * registry is part of the key so that a package of the same name served by two
+ * registries in one install can't collide on a single slot (which would resolve
+ * the wrong tarball/integrity). `fullMetadata` and `filterMetadata` keep the
+ * abbreviated, full, and filtered-full documents in distinct slots, mirroring
+ * the on-disk `metaDir` split: a `filterMetadata` resolver stores a `clearMeta`-
+ * stripped packument, so it must not share a slot with an unfiltered full one
+ * (reachable only when a `metaCache` is shared across resolvers with different
+ * settings). `filterMetadata` only narrows the full slot — abbreviated metadata
+ * shares one on-disk mirror regardless, so its key carries no filtered variant.
+ * `\x00` can't appear in a registry URL or a package name, so it's an
+ * unambiguous separator. The verifier reads this same cache and must build the
+ * key with this function.
+ *
+ * The registry is canonicalized to its origin plus a trailing-slashed path, so
+ * the resolver (which may pass a configured named-registry URL verbatim) and
+ * the verifier (which routes through trailing-slashed prefixes) converge on one
+ * key for the same logical registry instead of creating duplicate slots. Origin
+ * and path are preserved, so two registries that genuinely differ never collapse.
+ */
+export declare function getPkgMetaCacheKey(registry: string, pkgName: string, fullMetadata: boolean, filterMetadata: boolean): string;
+/**
+ * Path of the on-disk JSONL document where pnpm mirrors a package's registry
+ * metadata. `metaDir` selects between abbreviated and full caches.
+ */
+export declare function getPkgMirrorPath(cacheDir: string, metaDir: string, registry: string, pkgName: string): string;
+/**
+ * Formats metadata for disk storage as two-line NDJSON:
+ *   Line 1: cache headers (etag, modified) — small, fast to read
+ *   Line 2: the registry metadata JSON
+ *
+ * The etag lives only in the headers line (`loadMeta` re-attaches it from
+ * there), so a `meta` that carries one is serialized without it.
+ */
+export declare function prepareJsonForDisk(meta: PackageMeta, etag: string | undefined, jsonText?: string): string;
+export declare function warnMissingTimeFieldOnce(pkgName: string): void;
+interface MetaHeaders {
+    etag?: string;
+    modified?: string;
+}
+/**
+ * Reads only the first line of the cached NDJSON metadata file to extract
+ * the cache headers (etag, modified). This avoids reading and
+ * parsing the full metadata (which can be megabytes for popular packages)
+ * when we only need conditional-request headers.
+ */
+export declare function loadMetaHeaders(pkgMirror: string): Promise<MetaHeaders | null>;
+/**
+ * Reads the full metadata from the cached NDJSON file.
+ * Line 1: cache headers (etag, modified)
+ * Line 2: registry metadata JSON
+ */
+export declare function loadMeta(pkgMirror: string): Promise<PackageMeta | null>;
+export declare function saveMeta(pkgMirror: string, json: string): Promise<void>;
+export {};