{"id":13493249,"url":"https://github.com/npm/pacote","last_synced_at":"2025-05-13T20:12:18.232Z","repository":{"id":37561773,"uuid":"193812680","full_name":"npm/pacote","owner":"npm","description":"npm fetcher","archived":false,"fork":false,"pushed_at":"2025-04-15T14:31:42.000Z","size":2080,"stargazers_count":368,"open_issues_count":15,"forks_count":48,"subscribers_count":17,"default_branch":"main","last_synced_at":"2025-04-22T05:26:37.630Z","etag":null,"topics":["npm-cli"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"isc","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/npm.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2019-06-26T02:09:03.000Z","updated_at":"2025-04-15T14:31:45.000Z","dependencies_parsed_at":"2023-12-01T17:26:34.542Z","dependency_job_id":"0f679889-b0bd-4a52-8550-786eb3943263","html_url":"https://github.com/npm/pacote","commit_stats":{"total_commits":1115,"total_committers":53,"mean_commits":"21.037735849056602","dds":0.5497757847533633,"last_synced_commit":"d606b58fa155a343d695c6e556adb2d33ffbdb8b"},"previous_names":[],"tags_count":224,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/npm%2Fpacote","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/npm%2Fpacote/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/npm%2Fpacote/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/npm%2Fpacote/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/npm","download_url":"https://codeload.github.com/npm/pacote/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":251299681,"owners_count":21567281,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["npm-cli"],"created_at":"2024-07-31T19:01:13.532Z","updated_at":"2025-04-28T10:50:20.617Z","avatar_url":"https://github.com/npm.png","language":"JavaScript","readme":"# pacote\n\nFetches package manifests and tarballs from the npm registry.\n\n## USAGE\n\n```js\nconst pacote = require('pacote')\n\n// get a package manifest\npacote.manifest('foo@1.x').then(manifest =\u003e console.log('got it', manifest))\n\n// extract a package into a folder\npacote.extract('github:npm/cli', 'some/path', options)\n  .then(({from, resolved, integrity}) =\u003e {\n    console.log('extracted!', from, resolved, integrity)\n  })\n\npacote.tarball('https://server.com/package.tgz').then(data =\u003e {\n  console.log('got ' + data.length + ' bytes of tarball data')\n})\n```\n\n`pacote` works with any kind of package specifier that npm can install.  If\nyou can pass it to the npm CLI, you can pass it to pacote.  (In fact, that's\nexactly what the npm CLI does.)\n\nAnything that you can do with one kind of package, you can do with another.\n\nData that isn't relevant (like a packument for a tarball) will be\nsimulated.\n\n`prepare` scripts will be run when generating tarballs from `git` and\n`directory` locations, to simulate what _would_ be published to the\nregistry, so that you get a working package instead of just raw source\ncode that might need to be transpiled.\n\n## CLI\n\nThis module exports a command line interface that can do most of what is\ndescribed below.  Run `pacote -h` to learn more.\n\n```\nPacote - The JavaScript Package Handler, v10.1.1\n\nUsage:\n\n  pacote resolve \u003cspec\u003e\n    Resolve a specifier and output the fully resolved target\n    Returns integrity and from if '--long' flag is set.\n\n  pacote manifest \u003cspec\u003e\n    Fetch a manifest and print to stdout\n\n  pacote packument \u003cspec\u003e\n    Fetch a full packument and print to stdout\n\n  pacote tarball \u003cspec\u003e [\u003cfilename\u003e]\n    Fetch a package tarball and save to \u003cfilename\u003e\n    If \u003cfilename\u003e is missing or '-', the tarball will be streamed to stdout.\n\n  pacote extract \u003cspec\u003e \u003cfolder\u003e\n    Extract a package to the destination folder.\n\nConfiguration values all match the names of configs passed to npm, or\noptions passed to Pacote.  Additional flags for this executable:\n\n  --long     Print an object from 'resolve', including integrity and spec.\n  --json     Print result objects as JSON rather than node's default.\n             (This is the default if stdout is not a TTY.)\n  --help -h  Print this helpful text.\n\nFor example '--cache=/path/to/folder' will use that folder as the cache.\n```\n\n## API\n\nThe `spec` refers to any kind of package specifier that npm can install.\nIf you can pass it to the npm CLI, you can pass it to pacote.  (In fact,\nthat's exactly what the npm CLI does.)\n\nSee below for valid `opts` values.\n\n* `pacote.resolve(spec, opts)` Resolve a specifier like `foo@latest` or\n  `github:user/project` all the way to a tarball url, tarball file, or git\n  repo with commit hash.\n\n* `pacote.extract(spec, dest, opts)` Extract a package's tarball into a\n  destination folder.  Returns a promise that resolves to the\n  `{from,resolved,integrity}` of the extracted package.\n\n* `pacote.manifest(spec, opts)` Fetch (or simulate) a package's manifest\n  (basically, the `package.json` file, plus a bit of metadata).\n  See below for more on manifests and packuments.  Returns a Promise that\n  resolves to the manifest object.\n\n* `pacote.packument(spec, opts)` Fetch (or simulate) a package's packument\n  (basically, the top-level package document listing all the manifests that\n  the registry returns).  See below for more on manifests and packuments.\n  Returns a Promise that resolves to the packument object.\n\n* `pacote.tarball(spec, opts)`  Get a package tarball data as a buffer in\n  memory.  Returns a Promise that resolves to the tarball data Buffer, with\n  `from`, `resolved`, and `integrity` fields attached.\n\n* `pacote.tarball.file(spec, dest, opts)`  Save a package tarball data to\n  a file on disk.  Returns a Promise that resolves to\n  `{from,integrity,resolved}` of the fetched tarball.\n\n* `pacote.tarball.stream(spec, streamHandler, opts)`  Fetch a tarball and\n  make the stream available to the `streamHandler` function.\n\n    This is mostly an internal function, but it is exposed because it does\n    provide some functionality that may be difficult to achieve otherwise.\n\n    The `streamHandler` function MUST return a Promise that resolves when\n    the stream (and all associated work) is ended, or rejects if the stream\n    has an error.\n\n    The `streamHandler` function MAY be called multiple times, as Pacote\n    retries requests in some scenarios, such as cache corruption or\n    retriable network failures.\n\n### Options\n\nOptions are passed to\n[`npm-registry-fetch`](http://npm.im/npm-registry-fetch) and\n[`cacache`](http://npm.im/cacache), so in addition to these, anything for\nthose modules can be given to pacote as well.\n\nOptions object is cloned, and mutated along the way to add integrity,\nresolved, and other properties, as they are determined.\n\n* `cache` Where to store cache entries and temp files.  Passed to\n  [`cacache`](http://npm.im/cacache).  Defaults to the same cache directory\n  that npm will use by default, based on platform and environment.\n* `where` Base folder for resolving relative `file:` dependencies.\n* `resolved` Shortcut for looking up resolved values.  Should be specified\n  if known.\n* `integrity` Expected integrity of fetched package tarball.  If specified,\n  tarballs with mismatched integrity values will raise an `EINTEGRITY`\n  error.\n* `umask` Permission mode mask for extracted files and directories.\n  Defaults to `0o22`.  See \"Extracted File Modes\" below.\n* `fmode` Minimum permission mode for extracted files.  Defaults to\n  `0o666`.  See \"Extracted File Modes\" below.\n* `dmode` Minimum permission mode for extracted directories.  Defaults to\n  `0o777`.  See \"Extracted File Modes\" below.\n* `preferOnline` Prefer to revalidate cache entries, even when it would not\n  be strictly necessary.  Default `false`.\n* `before` When picking a manifest from a packument, only consider\n  packages published before the specified date.  Default `null`.\n* `defaultTag` The default `dist-tag` to use when choosing a manifest from a\n  packument.  Defaults to `latest`.\n* `registry` The npm registry to use by default.  Defaults to\n  `https://registry.npmjs.org/`.\n* `fullMetadata` Fetch the full metadata from the registry for packuments,\n  including information not strictly required for installation (author,\n  description, etc.)  Defaults to `true` when `before` is set, since the\n  version publish time is part of the extended packument metadata.\n* `fullReadJson` Use the slower `read-package-json` package insted of\n  `read-package-json-fast` in order to include extra fields like \"readme\" in\n  the manifest. Defaults to `false`.\n* `packumentCache` For registry packuments only, you may provide a `Map`\n  object which will be used to cache packument requests between pacote\n  calls.  This allows you to easily avoid hitting the registry multiple\n  times (even just to validate the cache) for a given packument, since it\n  is unlikely to change in the span of a single command.\n* `verifySignatures` A boolean that will make pacote verify the\n    integrity signature of a manifest, if present.  There must be a\n    configured `_keys` entry in the config that is scoped to the\n    registry the manifest is being fetched from.\n* `verifyAttestations` A boolean that will make pacote verify Sigstore\n    attestations, if present. There must be a configured `_keys` entry in the\n    config that is scoped to the registry the manifest is being fetched from.\n* `tufCache` Where to store metadata/target files when retrieving the package\n  attestation key material via TUF. Defaults to the same cache directory that\n  npm will use by default, based on platform and environment.\n\n### Advanced API\n\nEach different type of fetcher is exposed for more advanced usage such as\nusing helper methods from this classes:\n\n* `DirFetcher`\n* `FileFetcher`\n* `GitFetcher`\n* `RegistryFetcher`\n* `RemoteFetcher`\n\n## Extracted File Modes\n\nFiles are extracted with a mode matching the following formula:\n\n```\n( (tarball entry mode value) | (minimum mode option) ) ~ (umask)\n```\n\nThis is in order to prevent unreadable files or unlistable directories from\ncluttering a project's `node_modules` folder, even if the package tarball\nspecifies that the file should be inaccessible.\n\nIt also prevents files from being group- or world-writable without explicit\nopt-in by the user, because all file and directory modes are masked against\nthe `umask` value.\n\nSo, a file which is `0o771` in the tarball, using the default `fmode` of\n`0o666` and `umask` of `0o22`, will result in a file mode of `0o755`:\n\n```\n(0o771 | 0o666) =\u003e 0o777\n(0o777 ~ 0o22) =\u003e 0o755\n```\n\nIn almost every case, the defaults are appropriate.  To respect exactly\nwhat is in the package tarball (even if this makes an unusable system), set\nboth `dmode` and `fmode` options to `0`.  Otherwise, the `umask` config\nshould be used in most cases where file mode modifications are required,\nand this functions more or less the same as the `umask` value in most Unix\nsystems.\n\n## Extracted File Ownership\n\nWhen running as `root` on Unix systems, all extracted files and folders\nwill have their owning `uid` and `gid` values set to match the ownership\nof the containing folder.\n\nThis prevents `root`-owned files showing up in a project's `node_modules`\nfolder when a user runs `sudo npm install`.\n\n## Manifests\n\nA `manifest` is similar to a `package.json` file.  However, it has a few\npieces of extra metadata, and sometimes lacks metadata that is inessential\nto package installation.\n\nIn addition to the common `package.json` fields, manifests include:\n\n* `manifest._resolved` The tarball url or file path where the package\n  artifact can be found.\n* `manifest._from` A normalized form of the spec passed in as an argument.\n* `manifest._integrity` The integrity value for the package artifact.\n* `manifest._id` The canonical spec of this package version: name@version.\n* `manifest.dist` Registry manifests (those included in a packument) have a\n  `dist` object.  Only `tarball` is required, though at least one of\n  `shasum` or `integrity` is almost always present.\n\n    * `tarball` The url to the associated package artifact.  (Copied by\n      Pacote to `manifest._resolved`.)\n    * `integrity` The integrity SRI string for the artifact.  This may not\n      be present for older packages on the npm registry.  (Copied by Pacote\n      to `manifest._integrity`.)\n    * `shasum` Legacy integrity value.  Hexadecimal-encoded sha1 hash.\n      (Converted to an SRI string and copied by Pacote to\n      `manifest._integrity` when `dist.integrity` is not present.)\n    * `fileCount` Number of files in the tarball.\n    * `unpackedSize` Size on disk of the package when unpacked.\n    * `signatures` Signatures of the shasum.  Includes the keyid that\n        correlates to a [`key from the npm\n        registry`](https://registry.npmjs.org/-/npm/v1/keys)\n\n## Packuments\n\nA packument is the top-level package document that lists the set of\nmanifests for available versions for a package.\n\nWhen a packument is fetched with `accept:\napplication/vnd.npm.install-v1+json` in the HTTP headers, only the most\nminimum necessary metadata is returned.  Additional metadata is returned\nwhen fetched with only `accept: application/json`.\n\nFor Pacote's purposes, the following fields are relevant:\n\n* `versions` An object where each key is a version, and each value is the\n  manifest for that version.\n* `dist-tags` An object mapping dist-tags to version numbers.  This is how\n  `foo@latest` gets turned into `foo@1.2.3`.\n* `time` In the full packument, an object mapping version numbers to\n  publication times, for the `opts.before` functionality.\n\nPacote adds the following field, regardless of the accept header:\n\n* `_contentLength` The size of the packument.\n","funding_links":[],"categories":["JavaScript","Repository"],"sub_categories":["NPM"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnpm%2Fpacote","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnpm%2Fpacote","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnpm%2Fpacote/lists"}