Configuration Options

interface CoreOptions {
  /**
   * Cache directory path for storing downloaded packages and metadata
   * @default Platform-specific cache directory (same as npm)
   */
  cache?: string;

  /**
   * npm registry URL for fetching packages and metadata
   * @default 'https://registry.npmjs.org'
   */
  registry?: string;

  /**
   * Expected integrity hash for package validation
   * Supports SRI format (sha256, sha384, sha512)
   */
  integrity?: string;

  /**
   * Pre-resolved package URL to skip resolution step
   * Useful for performance optimization when URL is already known
   */
  resolved?: string;

  /**
   * Base directory for resolving relative file: dependencies
   * @default process.cwd()
   */
  where?: string;
}

const pacote = require('pacote');

// Basic configuration
const manifest = await pacote.manifest('express@latest', {
  cache: './custom-cache',
  registry: 'https://npm.example.com'
});

// With integrity verification
const tarball = await pacote.tarball('lodash@4.17.21', {
  integrity: 'sha512-v2kDEe57lecTulaDIuNTPy3Ry4gLGJ6Z1O3vE1krgXZNrsQ+LFTGHVxVjcXPs17LhbZVGedAJv8XZ1tvj5FvSg=='
});

// Using resolved URL
await pacote.extract('react@18.0.0', './react', {
  resolved: 'https://registry.npmjs.org/react/-/react-18.0.0.tgz'
});

interface NetworkOptions {
  /**
   * Prefer revalidating cache entries even when not strictly necessary
   * @default false
   */
  preferOnline?: boolean;

  /**
   * Prefer using cached data when available
   * @default false
   */
  preferOffline?: boolean;

  /**
   * Only use cached data, never make network requests
   * @default false
   */
  offline?: boolean;

  /**
   * Custom packument cache Map to avoid duplicate registry requests
   * Only applies to registry fetchers
   */
  packumentCache?: Map<string, any>;

  /**
   * Registry hostname replacement behavior
   * 'never', 'always', or specific hostname
   * @default 'registry.npmjs.org'
   */
  replaceRegistryHost?: string;
}

const pacote = require('pacote');

// Offline-first approach
const manifest = await pacote.manifest('express@4.18.2', {
  preferOffline: true
});

// Shared packument cache for performance
const cache = new Map();
const express = await pacote.packument('express', { packumentCache: cache });
const lodash = await pacote.packument('lodash', { packumentCache: cache });

// Registry host replacement
await pacote.resolve('lodash@latest', {
  registry: 'https://internal-registry.company.com',
  replaceRegistryHost: 'registry.npmjs.org'
});

interface SecurityOptions {
  /**
   * Enable registry signature verification for manifests
   * Requires configured _keys for the registry
   * @default false
   */
  verifySignatures?: boolean;

  /**
   * Enable package attestation verification via Sigstore
   * Requires configured _keys for the registry
   * @default false
   */
  verifyAttestations?: boolean;

  /**
   * Default integrity algorithm for packages without explicit integrity
   * @default 'sha512'
   */
  defaultIntegrityAlgorithm?: string;

  /**
   * TUF cache directory for attestation key material
   * @default Platform-specific cache directory
   */
  tufCache?: string;
}

const pacote = require('pacote');

// With signature verification
const manifest = await pacote.manifest('express@latest', {
  verifySignatures: true,
  'registry.npmjs.org:_keys': ['key1', 'key2'] // Registry keys
});

// With attestation verification
await pacote.extract('lodash@4.17.21', './lodash', {
  verifyAttestations: true,
  tufCache: './custom-tuf-cache'
});

// Custom integrity algorithm
const resolved = await pacote.resolve('react@18.0.0', {
  defaultIntegrityAlgorithm: 'sha256'
});

interface FileSystemOptions {
  /**
   * Minimum permission mode for extracted files
   * @default 0o666
   */
  fmode?: number;

  /**
   * Minimum permission mode for extracted directories
   * @default 0o777
   */
  dmode?: number;

  /**
   * Permission mode mask for extracted files and directories
   * @default 0o22
   */
  umask?: number;

  /**
   * Allow git ignore files to be processed during git operations
   * @default false
   */
  allowGitIgnore?: boolean;
}

const pacote = require('pacote');

// Custom file permissions
await pacote.extract('express@4.18.2', './express', {
  fmode: 0o644,   // Files: -rw-r--r--
  dmode: 0o755,   // Directories: drwxr-xr-x
  umask: 0o022    // Standard umask
});

// More restrictive permissions
await pacote.extract('private-package@1.0.0', './private', {
  fmode: 0o600,   // Files: -rw-------
  dmode: 0o700,   // Directories: drwx------
  umask: 0o077    // Restrictive umask
});

interface MetadataOptions {
  /**
   * Fetch full metadata from registry instead of compressed format
   * Required for publish time information and extended metadata
   * @default false (true when 'before' is set)
   */
  fullMetadata?: boolean;

  /**
   * Use slower read-package-json instead of read-package-json-fast
   * Includes extra fields like "readme" in manifest
   * @default false
   */
  fullReadJson?: boolean;

  /**
   * Only consider packages published before this date
   * ISO 8601 date string, forces fullMetadata to true
   */
  before?: string;

  /**
   * Default dist-tag to use when choosing manifest from packument
   * @default 'latest'
   */
  defaultTag?: string;
}

const pacote = require('pacote');

// Full metadata with publish times
const packument = await pacote.packument('express', {
  fullMetadata: true
});
console.log('Publish times:', packument.time);

// Only versions before specific date
const oldManifest = await pacote.manifest('lodash@*', {
  before: '2020-01-01T00:00:00.000Z'
});

// Custom default tag
const betaManifest = await pacote.manifest('react', {
  defaultTag: 'beta'
});

// Full readme in manifest
const withReadme = await pacote.manifest('express@latest', {
  fullReadJson: true
});
console.log('Readme:', withReadme.readme);

interface BuildOptions {
  /**
   * npm binary path for running prepare scripts
   * @default 'npm'
   */
  npmBin?: string;

  /**
   * npm install command array for dependency installation
   * @default ['install', '--force']
   */
  npmInstallCmd?: string[];

  /**
   * npm CLI configuration array
   */
  npmCliConfig?: string[];

  /**
   * Arborist constructor for dependency tree operations
   * Required for DirFetcher operations
   */
  Arborist?: typeof import('@npmcli/arborist');

  /**
   * Pre-built Arborist tree object
   */
  tree?: Object;

  /**
   * Environment variables for prepare script execution
   */
  env?: Record<string, string>;

  /**
   * Shell for running scripts
   * @default '/bin/sh'
   */
  scriptShell?: string;

  /**
   * Run scripts with inherit stdio (foreground)
   * @default false
   */
  foregroundScripts?: boolean;

  /**
   * Skip running prepare scripts
   * @default false
   */
  ignoreScripts?: boolean;

  /**
   * Workspace configuration for packlist
   */
  workspaces?: string[] | boolean;
}

const pacote = require('pacote');
const Arborist = require('@npmcli/arborist');

// Custom npm binary
await pacote.extract('file:./my-package', './built', {
  npmBin: 'yarn',
  npmInstallCmd: ['install', '--frozen-lockfile']
});

// With Arborist for directory operations
const dirFetcher = new (require('pacote').DirFetcher)('file:./src', {
  Arborist,
  env: {
    NODE_ENV: 'production'
  }
});

await dirFetcher.extract('./dist');

const pacote = require('pacote');

// This will use:
// - Default registry from .npmrc or environment
// - Cache directory from npm config
// - Plus explicit options
const manifest = await pacote.manifest('express@latest', {
  preferOffline: true,  // Explicit option
  integrity: 'sha512-...' // Explicit option
  // registry: inherited from npm config
  // cache: inherited from npm config
});

const options = {
  registry: 'https://internal-registry.company.com',
  '//internal-registry.company.com:_authToken': 'token123',
  '//internal-registry.company.com:_keys': ['key1', 'key2'],
  
  // Public registry settings still available
  '//registry.npmjs.org:_keys': ['public-key1']
};

const manifest = await pacote.manifest('@company/private-pkg@latest', options);

const pacote = require('pacote');

try {
  // This might fail with network error
  await pacote.manifest('express@latest', { preferOnline: true });
} catch (error) {
  if (error.code === 'ENOTFOUND') {
    // Fallback to offline
    const manifest = await pacote.manifest('express@latest', { 
      offline: true 
    });
  }
}

try {
  // This might fail with integrity error
  await pacote.extract('lodash@4.17.21', './lodash', {
    integrity: 'sha512-wrong-hash'
  });
} catch (error) {
  if (error.code === 'EINTEGRITY') {
    console.log('Integrity verification failed');
    // Extract without integrity check
    await pacote.extract('lodash@4.17.21', './lodash');
  }
}

const pacote = require('pacote');

// Shared cache for multiple operations
const cache = new Map();
const sharedOptions = {
  packumentCache: cache,
  preferOffline: true,
  fullMetadata: false // Use compressed format
};

// Batch operations with shared config
const results = await Promise.all([
  pacote.manifest('express@latest', sharedOptions),
  pacote.manifest('lodash@latest', sharedOptions),
  pacote.manifest('react@latest', sharedOptions)
]);

// Pre-resolved URLs for known packages
const knownPackages = {
  'express@4.18.2': 'https://registry.npmjs.org/express/-/express-4.18.2.tgz'
};

for (const [spec, resolved] of Object.entries(knownPackages)) {
  await pacote.extract(spec, `./packages/${spec.split('@')[0]}`, {
    resolved, // Skip resolution step
    preferOffline: true
  });
}