npm-types

@nodesecure/npm-types

Up to date typescript definitions for npm registry content

Requirements

• Node.js v24 or higher

Getting Started

This package is available in the Node Package Repository and can be easily installed with npm or yarn.

$ npm i @nodesecure/npm-types -D
# or
$ yarn add @nodesecure/npm-types -D

Usage example

import type { PackageJSON } from "@nodesecure/npm-types";

📚 Types Documentation

Core Package Types

PackageJSON

Represents a standard package.json file with all npm-supported fields.

import type { PackageJSON } from "@nodesecure/npm-types";

const pkg: PackageJSON = {
  name: "my-package",
  version: "1.0.0",
  dependencies: { ... }
};

WorkspacesPackageJSON

Extends PackageJSON for monorepo workspace configurations. Name and version are optional.

import type { WorkspacesPackageJSON } from "@nodesecure/npm-types";

const workspace: WorkspacesPackageJSON = {
  workspaces: ["packages/*"]
};

Registry Metadata Types

Packument

Complete package metadata as returned by the npm registry. Contains all versions, maintainers, and distribution information.

import type { Packument } from "@nodesecure/npm-types";

const packument: Packument = {
  _id: "my-package",
  name: "my-package",
  "dist-tags": { latest: "1.0.0" },
  versions: { ... },
  time: { ... }
};

PackumentVersion

Metadata for a specific package version within a packument. Includes distribution details, maintainers, and npm-specific fields.

import type { PackumentVersion } from "@nodesecure/npm-types";

const version: PackumentVersion = {
  name: "my-package",
  version: "1.0.0",
  dist: {
    tarball: "https://...",
    shasum: "...",
    integrity: "sha512-..."
  },
  _npmUser: { name: "username" }
};

Manifest

Abbreviated package metadata format (corgi format). Lighter alternative to Packument for install operations.

import type { Manifest } from "@nodesecure/npm-types";

AbbreviatedManifestDocument

Minimal manifest shape compatible with abbreviated registry manifests (e.g. pacote.manifest()).

• No [field: string]: unknown index signature (unlike BasePackageJSON).
• Avoids the need for explicit casts when assigning Pick-based types like pacote.AbbreviatedManifest & pacote.ManifestResult.

import type { AbbreviatedManifestDocument } from "@nodesecure/npm-types";

const doc: AbbreviatedManifestDocument = {
  name: "my-package",
  version: "1.0.0",
  dependencies: { lodash: "^4.17.21" }
};

Utility Types

Contact

Represents a person (author, contributor, maintainer).

import type { Contact } from "@nodesecure/npm-types";

const author: Contact = {
  name: "John Doe",
  email: "john@example.com",
  url: "https://johndoe.com"
};

Repository

Git repository information.

import type { Repository } from "@nodesecure/npm-types";

const repo: Repository = {
  type: "git",
  url: "https://github.com/user/repo.git",
  directory: "packages/core"
};

Dist

Distribution information for a package version (tarball location, integrity hashes, signatures).

import type { Dist } from "@nodesecure/npm-types";

DistTags

Version tags (latest, next, beta, etc.) pointing to specific versions.

import type { DistTags } from "@nodesecure/npm-types";

const tags: DistTags = {
  latest: "1.0.0",
  next: "2.0.0-beta.1"
};

Spec

Package specification string in the format name@version.

import type { Spec } from "@nodesecure/npm-types";

const spec: Spec = "lodash@4.17.21";

Node.js Specific Types

NodeExport & ConditionalNodeExport

Types for Node.js conditional exports (ESM/CJS).

import type { NodeExport } from "@nodesecure/npm-types";

const exports: NodeExport = {
  import: "./dist/index.mjs",
  require: "./dist/index.cjs",
  default: "./dist/index.js"
};

NodeImport

Types for Node.js subpath imports (# imports).

import type { NodeImport } from "@nodesecure/npm-types";

Additional Types

PackTarball

Metadata returned by npm pack command.

import type { PackTarball } from "@nodesecure/npm-types";

Signature

PGP signature information for signed packages.

import type { Signature } from "@nodesecure/npm-types";

🔍 Common Use Cases

Parsing a package.json file

import type { PackageJSON } from "@nodesecure/npm-types";
import { readFileSync } from "node:fs";

const pkg: PackageJSON = JSON.parse(
  readFileSync("./package.json", "utf-8")
);

Fetching registry metadata

import type { Packument } from "@nodesecure/npm-types";

const response = await fetch("https://registry.npmjs.org/lodash");
const packument: Packument = await response.json();

console.log(packument["dist-tags"].latest);