Normalize Package Data

Normalize Package Data provides comprehensive normalization and validation of package.json metadata. It transforms inconsistent package.json data into standardized formats by cleaning version numbers, converting string dependencies to objects, normalizing people fields, and inferring missing metadata from related fields.

Package Information

• Package Name: normalize-package-data
• Package Type: npm
• Language: JavaScript
• Node.js Version: ^20.17.0 || >=22.9.0
• Installation: npm install normalize-package-data

Core Imports

const normalize = require("normalize-package-data");

Basic Usage

const normalize = require("normalize-package-data");

// Load package data
const packageData = require("./package.json");

// Basic normalization
normalize(packageData);
// packageData is now normalized in-place

// With warning callback
const warnings = [];
normalize(packageData, (warning) => {
  warnings.push(warning);
});

// Strict mode (Semver 2.0 compliance)
normalize(packageData, true);

// Strict mode with warning callback
normalize(packageData, (warning) => {
  console.error("Warning:", warning);
}, true);

Architecture

Normalize Package Data operates through a central normalize function that orchestrates field-specific normalization tasks:

• Main Function: normalize() coordinates all normalization operations
• Fixer Module: Contains individual field normalization functions
• Warning System: Provides detailed feedback about data quality issues
• Utility Modules: Support functions for description extraction, safe formatting, and warning message generation

Capabilities

Package Normalization

Core normalization function that transforms package.json data into standardized format.

/**
 * Normalizes package.json data in-place
 * @param {Object} data - Package data object to normalize
 * @param {Function|boolean} [warn] - Warning callback function or strict mode flag
 * @param {boolean} [strict] - Enable strict validation mode
 */
function normalize(data, warn, strict);

Parameters:

• data (Object): Package.json data to normalize (modified in-place)
• warn (Function|boolean): Warning callback function or true for strict mode
• strict (boolean): When true, enforces strict Semver 2.0 compliance and name validation

Normalization Operations:

• Version field validation and cleaning using semver
• Name field validation and encoding checks
• Repository field normalization with hosted git provider support
• Dependencies conversion from arrays/strings to objects
• People fields (author, contributors, maintainers) parsing
• Files, bin, man field type validation and conversion
• Keywords field normalization from strings to arrays
• License field validation against SPDX standards
• Bugs and homepage inference from repository data
• Description extraction from README when missing
• Common typo correction across all fields

Advanced Access

Access to the underlying fixer module for custom normalization workflows.

/**
 * Direct access to the fixer module with individual field normalization functions
 */
normalize.fixer: {
  warn: Function;
  fixRepositoryField: Function;
  fixTypos: Function;
  fixScriptsField: Function;
  fixFilesField: Function;
  fixBinField: Function;
  fixManField: Function;
  fixBundleDependenciesField: Function;
  fixDependencies: Function;
  fixModulesField: Function;
  fixKeywordsField: Function;
  fixVersionField: Function;
  fixPeople: Function;
  fixNameField: Function; // fixNameField(data, options)
  fixDescriptionField: Function;
  fixReadmeField: Function;
  fixBugsField: Function;
  fixHomepageField: Function;
  fixLicenseField: Function;
}

Warning System

The warning system provides detailed feedback about data quality issues during normalization.

Warning Callback Usage:

const warnings = [];
normalize(packageData, (message) => {
  warnings.push(message);
});

// Warning types (29 total warning messages):
// Missing data: missingRepository, missingDescription, missingReadme, missingLicense
// Invalid types: nonObjectScripts, nonStringScript, nonArrayFiles, nonArrayKeywords
// Invalid values: invalidFilename, invalidLicense, nonEmailUrlBugsString
// Dependencies: nonObjectDependencies, nonStringDependency, deprecatedArrayDependencies
// Typos: repositories (should be repository), dependancies (should be dependencies)
// URLs: brokenGitUrl, nonUrlHomepage, nonUrlBugsUrlField
// Deprecated: deprecatedModules
// Name conflicts: conflictingName (conflicts with Node.js core modules)

Strict Mode: When strict mode is enabled:

• Only Semver 2.0 version strings are accepted (vs Semver 1.0 in lenient mode)
• Package names must not contain leading/trailing whitespace
• Name field is required and cannot be empty
• Enhanced validation across all fields

Field-Specific Normalization

Individual field normalization functions available through normalize.fixer:

Version Field

/**
 * Validates and cleans version field using semver
 * @param {Object} data - Package data
 * @param {boolean} strict - Strict mode flag
 */
fixVersionField(data, strict);

Dependencies

/**
 * Normalizes all dependency fields (dependencies, devDependencies, optionalDependencies)
 * Converts arrays/strings to objects, validates URLs, merges optionalDependencies
 * @param {Object} data - Package data
 */
fixDependencies(data);

Name Field

/**
 * Validates and normalizes the package name field
 * @param {Object} data - Package data
 * @param {Object|boolean} [options] - Options object or strict boolean
 * @param {boolean} [options.strict] - Enable strict validation
 * @param {boolean} [options.allowLegacyCase] - Allow legacy case patterns
 */
fixNameField(data, options);

People Fields

/**
 * Normalizes author, contributors, and maintainers fields
 * Converts strings to structured objects with name, email, url properties
 * @param {Object} data - Package data
 */
fixPeople(data);

Repository Field

/**
 * Normalizes repository field and infers bugs/homepage URLs
 * Supports hosted git providers (GitHub, GitLab, etc.)
 * @param {Object} data - Package data
 */
fixRepositoryField(data);

Error Handling

The normalize function may throw errors for critical validation failures:

• Invalid version: Throws Error when version field contains invalid semver
• Invalid name: Throws Error when package name violates npm naming rules
• Type errors: Internal utility functions may throw TypeError for invalid arguments

Non-critical issues are reported through the warning callback system rather than throwing errors.

Internal Processing

The normalize function processes fields in a specific order and performs special transformations:

Field Processing Order:

1. Basic fields: name, version, description, repository, modules, scripts, files, bin, man, bugs, keywords, readme, homepage, license
2. Additional processing: dependencies, people (author/contributors/maintainers), typos

Special Behaviors:

• Sets gypfile: true when install script is "node-gyp rebuild" and no preinstall script exists
• Automatically generates _id field as name@version
• Processes typo corrections for 22 common field misspellings:
  • Top-level fields: "dependancies"/"dependecies"/"depdenencies" → "dependencies", "repostitory" → "repository", "autohr"/"autor" → "author", "contributers" → "contributors", etc.
  • Script fields: "tests" → "test", "server" → "start"
  • Bugs fields: "web"/"name" → "url"
• Infers bugs and homepage URLs from repository information when missing

Types

Note: Type definitions below use TypeScript syntax for clarity, but this is a JavaScript package.

/**
 * Warning callback function type
 * @callback WarningCallback
 * @param {string} message - Formatted warning message
 */

/**
 * Person object structure (normalized from string format)
 */
interface PersonObject {
  name?: string;
  email?: string;
  url?: string;
}

/**
 * Repository object structure
 */
interface RepositoryObject {
  type: string;
  url: string;
}

/**
 * Bugs object structure
 */
interface BugsObject {
  url?: string;
  email?: string;
}