@pnpm/package-requester

import { createPackageRequester, type PackageResponse } from "@pnpm/package-requester";

const { createPackageRequester } = require("@pnpm/package-requester");

import { createPackageRequester } from "@pnpm/package-requester";

// Create a package requester instance
const { requestPackage, fetchPackageToStore, getFilesIndexFilePath } = createPackageRequester({
  resolve: myResolveFunction,
  fetchers: myFetchers,
  cafs: myCafs,
  storeDir: "/path/to/store",
  verifyStoreIntegrity: true,
  virtualStoreDirMaxLength: 1024
});

// Request a package with resolution and fetching
const response = await requestPackage(
  { bareSpecifier: "^4.17.0", alias: "lodash" },
  {
    projectDir: "/path/to/project",
    lockfileDir: "/path/to/project",
    preferredVersions: {},
    downloadPriority: 0
  }
);

// Access the resolved package
console.log(response.body.manifest.name); // "lodash"
console.log(response.body.resolution.integrity); // integrity hash

function createPackageRequester(opts: CreatePackageRequesterOptions): PackageRequesterInstance;

interface CreatePackageRequesterOptions {
  /** Enforce engine compatibility strict mode */
  engineStrict?: boolean;
  /** Force refetch packages, ignoring cache */
  force?: boolean;
  /** Node.js version for compatibility checks */
  nodeVersion?: string;
  /** pnpm version */
  pnpmVersion?: string;
  /** Package resolution function */
  resolve: ResolveFunction;
  /** Package fetchers organized by hosting type */
  fetchers: Fetchers;
  /** Content-addressable file store instance */
  cafs: Cafs;
  /** File ignore predicate function */
  ignoreFile?: (filename: string) => boolean;
  /** Network request concurrency limit (minimum 16) */
  networkConcurrency?: number;
  /** Store directory path */
  storeDir: string;
  /** Enable store integrity verification */
  verifyStoreIntegrity: boolean;
  /** Maximum virtual store directory path length */
  virtualStoreDirMaxLength: number;
  /** Enable strict package content validation */
  strictStorePkgContentCheck?: boolean;
}

interface PackageRequesterInstance {
  /** Request and resolve packages with caching and concurrency control */
  requestPackage: RequestPackageFunction;
  /** Fetch packages directly to store without resolution */
  fetchPackageToStore: FetchPackageToStoreFunction;
  /** Get package files index path */
  getFilesIndexFilePath: GetFilesIndexFilePath;
  /** Direct access to the request package function (same as requestPackage) */
  (wantedDependency: WantedDependency & { optional?: boolean }, options: RequestPackageOptions): Promise<PackageResponse>;
}

interface RequestPackageFunction {
  (
    wantedDependency: WantedDependency & { optional?: boolean },
    options: RequestPackageOptions
  ): Promise<PackageResponse>;
}

type WantedDependency = {
  /** Whether dependency was injected */
  injected?: boolean;
  /** Previous version specifier */
  prevSpecifier?: string;
} & ({
  /** Package alias (optional when bareSpecifier provided) */
  alias?: string;
  /** Version range, tag, or exact version */
  bareSpecifier: string;
} | {
  /** Package alias (required when bareSpecifier is optional) */
  alias: string;
  /** Version range, tag, or exact version (optional when alias provided) */
  bareSpecifier?: string;
});

interface RequestPackageOptions {
  /** Always try workspace packages first */
  alwaysTryWorkspacePackages?: boolean;
  /** Current package info for updates */
  currentPkg?: {
    id?: PkgResolutionId;
    name?: string;
    resolution?: Resolution;
    version?: string;
  };
  /** Expected package name/version from lockfile */
  expectedPkg?: PkgNameVersion;
  /** Default tag for resolution (e.g., 'latest') */
  defaultTag?: string;
  /** Pick lowest version when multiple options available */
  pickLowestVersion?: boolean;
  /** Filter packages by publication date */
  publishedBy?: Date;
  /** Download priority level (0 = highest) */
  downloadPriority: number;
  /** Skip running scripts during processing */
  ignoreScripts?: boolean;
  /** Project directory path */
  projectDir: string;
  /** Lockfile directory path */
  lockfileDir: string;
  /** Version preferences for resolution */
  preferredVersions: PreferredVersions;
  /** Prefer workspace packages over registry packages */
  preferWorkspacePackages?: boolean;
  /** Enable side effects caching */
  sideEffectsCache?: boolean;
  /** Skip fetching, only resolve */
  skipFetch?: boolean;
  /** Update strategy: 'compatible', 'latest', or false */
  update?: 'compatible' | 'latest' | false;
  /** Available workspace packages */
  workspacePackages?: WorkspacePackages;
  /** Force resolution even if cached */
  forceResolve?: boolean;
  /** Platform architecture constraints */
  supportedArchitectures?: SupportedArchitectures;
  /** Error handling callback for fetch errors */
  onFetchError?: OnFetchError;
  /** Inject workspace packages into dependency resolution */
  injectWorkspacePackages?: boolean;
  /** Calculate exact version specifier */
  calcSpecifier?: boolean;
  /** Pinned version preference */
  pinnedVersion?: PinnedVersion;
}

interface FetchPackageToStoreFunction {
  (opts: FetchPackageToStoreOptions): Promise<FetchResponse>;
}

interface FetchPackageToStoreOptions {
  /** Fetch raw manifest without processing */
  fetchRawManifest?: boolean;
  /** Force refetch, ignoring cache */
  force: boolean;
  /** Skip running scripts during package processing */
  ignoreScripts?: boolean;
  /** Lockfile directory path */
  lockfileDir: string;
  /** Package information with ID and resolution */
  pkg: PkgNameVersion & {
    id: string;
    resolution: Resolution;
  };
  /** Error handling callback */
  onFetchError?: OnFetchError;
  /** Platform architecture constraints */
  supportedArchitectures?: SupportedArchitectures;
}

type OnFetchError = (error: Error) => Error;

interface FetchResponse {
  /** Files index file path */
  filesIndexFile: string;
  /** Fetching promise for lazy evaluation */
  fetching: () => Promise<PkgRequestFetchResult>;
}

interface GetFilesIndexFilePath {
  (
    opts: Pick<FetchPackageToStoreOptions, 'pkg' | 'ignoreScripts' | 'supportedArchitectures'>
  ): {
    target: string;
    filesIndexFile: string;
    resolution: AtomicResolution;
  };
}

interface PackageResponse {
  /** Optional fetching promise for lazy evaluation */
  fetching?: () => Promise<PkgRequestFetchResult>;
  /** Files index file path */
  filesIndexFile?: string;
  /** Response body with package metadata */
  body: {
    /** Whether package is local */
    isLocal: boolean;
    /** Installation compatibility flag */
    isInstallable?: boolean;
    /** Package resolution information */
    resolution: Resolution;
    /** Package manifest (package.json content) */
    manifest?: PackageManifest;
    /** Package resolution ID */
    id: string;
    /** Normalized bare specifier */
    normalizedBareSpecifier?: string;
    /** Whether package was updated */
    updated: boolean;
    /** Publication timestamp */
    publishedAt?: string;
    /** Resolution method used */
    resolvedVia?: string;
    /** Latest version information */
    latest?: string;
    /** Package alias */
    alias?: string;
  };
}

interface BundledManifest {
  /** Binary executable definitions */
  bin?: Record<string, string>;
  /** Bundled dependencies list */
  bundledDependencies?: string[];
  /** Legacy bundled dependencies list */
  bundleDependencies?: string[];
  /** CPU architecture constraints */
  cpu?: string[];
  /** Runtime dependencies */
  dependencies?: Record<string, string>;
  /** Directory mappings */
  directories?: Record<string, string>;
  /** Engine requirements */
  engines?: Record<string, string>;
  /** Package name */
  name?: string;
  /** Optional dependencies */
  optionalDependencies?: Record<string, string>;
  /** Operating system constraints */
  os?: string[];
  /** Peer dependencies */
  peerDependencies?: Record<string, string>;
  /** Peer dependencies metadata */
  peerDependenciesMeta?: Record<string, any>;
  /** Build and lifecycle scripts */
  scripts?: Record<string, string>;
  /** Package version */
  version?: string;
}

interface PreferredVersions {
  [packageName: string]: VersionSelectors;
}

interface SupportedArchitectures {
  os?: string[];
  cpu?: string[];
  libc?: string[];
}

type Resolution = AtomicResolution | VariationsResolution;

interface PackageManifest {
  /** Package name */
  name: string;
  /** Package version */
  version: string;
  /** Package description */
  description?: string;
  /** Main entry point */
  main?: string;
  /** Module entry point */
  module?: string;
  /** TypeScript definitions */
  types?: string;
  /** Package dependencies */
  dependencies?: Record<string, string>;
  /** Development dependencies */
  devDependencies?: Record<string, string>;
  /** Peer dependencies */
  peerDependencies?: Record<string, string>;
  /** Optional dependencies */
  optionalDependencies?: Record<string, string>;
  [key: string]: any;
}

interface PkgRequestFetchResult {
  /** Bundled manifest */
  bundledManifest?: BundledManifest;
  /** Package files response with index and metadata */
  files: PackageFilesResponse;
}

interface PkgNameVersion {
  /** Package name */
  name?: string;
  /** Package version */
  version?: string;
}

interface PackageFilesIndex {
  /** Package name (nullable for backward compatibility) */
  name?: string;
  /** Package version (nullable for backward compatibility) */
  version?: string;
  /** Whether package requires build step */
  requiresBuild?: boolean;
  /** File entries mapping */
  files: PackageFiles;
  /** Side effects information */
  sideEffects?: SideEffects;
}

interface PackageFileInfo {
  /** Last checked timestamp (nullable for backward compatibility) */
  checkedAt?: number;
  /** File integrity hash */
  integrity: string;
  /** File mode/permissions */
  mode: number;
  /** File size in bytes */
  size: number;
}

type PackageFiles = Record<string, PackageFileInfo>;

type SideEffects = Record<string, boolean>;

interface PackageFilesResponse {
  /** Whether files came from cache without processing */
  unprocessed?: boolean;
  /** Files index mapping filenames to file info */
  filesIndex: PackageFiles;
  /** Where files were resolved from */
  resolvedFrom: ResolvedFrom;
  /** Package import method for directory packages */
  packageImportMethod?: string;
  /** Side effects information */
  sideEffects?: SideEffects;
  /** Whether package requires build step */
  requiresBuild: boolean;
}

type ResolvedFrom = 'remote' | 'store' | 'local-dir';

type VersionSelectorType = 'version' | 'range' | 'tag';

interface VersionSelectors {
  [selector: string]: VersionSelectorWithWeight | VersionSelectorType;
}

interface VersionSelectorWithWeight {
  selectorType: VersionSelectorType;
  weight: number;
}

type PkgResolutionId = string;

type WorkspacePackages = Map<string, WorkspacePackagesByVersion>;

interface WorkspacePackagesByVersion {
  [version: string]: {
    dir: string;
    manifest: PackageManifest;
  };
}

type PinnedVersion = 'major' | 'minor' | 'patch';

type AtomicResolution = TarballResolution | DirectoryResolution | GitResolution | BinaryResolution;

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

interface BinaryResolution {
  type: 'binary';
  archive: 'tarball' | 'zip';
  url: string;
  integrity: string;
  bin: string;
  prefix?: string;
}

interface DirectoryResolution {
  type: 'directory';
  directory: string;
}

interface GitResolution {
  commit: string;
  repo: string;
  path?: string;
  type: 'git';
}

type VariationsResolution = {
  type: 'variations';
  variants: PlatformAssetResolution[];
};

interface PlatformAssetResolution {
  resolution: AtomicResolution;
  targets: PlatformAssetTarget[];
}

interface PlatformAssetTarget {
  os: string;
  cpu: string;
  libc?: 'musl';
}