@pnpm/tarball-resolver

@pnpm/tarball-resolver is a resolver for tarball dependencies that handles HTTP/HTTPS URLs. It processes tarball URLs from npm registries and other sources, managing redirects for immutable cache responses and filtering out direct repository URLs.

Package Information

• Package Name: @pnpm/tarball-resolver
• Package Type: npm
• Language: TypeScript
• Installation: npm install @pnpm/tarball-resolver
• Node.js Requirements: >=18.12

Core Imports

import { resolveFromTarball, type TarballResolveResult } from "@pnpm/tarball-resolver";

For CommonJS:

const { resolveFromTarball } = require("@pnpm/tarball-resolver");

Note: Some older examples show require('@pnpm/tarball-resolver').default, but the named import is preferred.

Basic Usage

import { resolveFromTarball } from "@pnpm/tarball-resolver";
import { createFetchFromRegistry } from "@pnpm/fetch";

// Create a fetch function for registry requests
const fetch = createFetchFromRegistry({});

// Resolve a tarball from npm registry
const result = await resolveFromTarball(fetch, {
  bareSpecifier: "https://registry.npmjs.org/is-array/-/is-array-1.0.1.tgz"
});

if (result) {
  console.log("Resolved tarball:");
  console.log("ID:", result.id);
  console.log("Tarball URL:", result.resolution.tarball);
  console.log("Resolved via:", result.resolvedVia);
}

Capabilities

Tarball Resolution

Resolves tarball dependencies from HTTP/HTTPS URLs, handling redirects for immutable responses and filtering out repository URLs.

async function resolveFromTarball(
  fetchFromRegistry: FetchFromRegistry,
  wantedDependency: { bareSpecifier: string }
): Promise<TarballResolveResult | null>;

Parameters:

• fetchFromRegistry: Function that performs HTTP requests to package registries
• wantedDependency: Object containing the tarball URL to resolve

Returns:

• Promise<TarballResolveResult | null>: Resolution result or null if URL is not a valid tarball

Behavior:

• Only processes URLs starting with http: or https:
• Returns null for non-HTTP/HTTPS URLs
• Returns null for direct repository URLs (GitHub, GitLab, Bitbucket)
• Makes HEAD request to check for immutable cache-control headers
• Uses final redirected URL for immutable responses
• Uses original URL for mutable responses

Usage Examples:

Resolving an immutable tarball (npm registry):

const result = await resolveFromTarball(fetch, {
  bareSpecifier: "http://registry.npmjs.org/is-array/-/is-array-1.0.1.tgz"
});
// Returns result with HTTPS redirected URL

Resolving a mutable tarball:

const result = await resolveFromTarball(fetch, {
  bareSpecifier: "https://github.com/hegemonic/taffydb/tarball/master"
});
// Returns result with original URL

Non-tarball URLs (returns null):

// Repository URLs are filtered out
const result1 = await resolveFromTarball(fetch, {
  bareSpecifier: "https://github.com/foo/bar"
});
// Returns null

// Non-HTTP URLs are filtered out
const result2 = await resolveFromTarball(fetch, {
  bareSpecifier: "file:///path/to/local.tgz"
});
// Returns null

Types

interface TarballResolveResult extends ResolveResult {
  normalizedBareSpecifier: string;
  resolution: TarballResolution;
  resolvedVia: 'url';
}

The result object returned by resolveFromTarball when successful.

Properties:

• id: Package resolution identifier (inherited from ResolveResult)
• normalizedBareSpecifier: The final tarball URL (after any redirects)
• resolution: Tarball resolution metadata containing the tarball URL
• resolvedVia: Always set to 'url' for tarball resolutions

interface TarballResolution {
  type?: undefined;
  tarball: string;
  integrity?: string;
  path?: string;
}

Resolution metadata for tarball dependencies.

Properties:

• tarball: The URL of the tarball file
• integrity: Optional integrity hash for verification
• path: Optional path within the tarball
• type: Always undefined for tarball resolutions

type FetchFromRegistry = (
  url: string,
  opts?: RequestInit & {
    authHeaderValue?: string;
    compress?: boolean;
    retry?: RetryTimeoutOptions;
    timeout?: number;
  }
) => Promise<Response>;

Function type for making HTTP requests to package registries.

Parameters:

• url: The URL to fetch
• opts: Optional request options including authentication, compression, retry, and timeout settings

Returns:

• Promise<Response>: Standard HTTP Response object

type ResolveResult = {
  id: PkgResolutionId;
  latest?: string;
  publishedAt?: string;
  manifest?: DependencyManifest;
  resolution: Resolution;
  resolvedVia: string;
  normalizedBareSpecifier?: string;
  alias?: string;
};

Base interface for all resolution results (from @pnpm/resolver-base).

type PkgResolutionId = string;

Unique identifier for a resolved package (from @pnpm/resolver-base).