Version Management

/**
 * Advanced semver version class with formatting and validation
 */
class Version {
  /**
   * Create a new Version instance
   * @param version - A valid SemVer version string
   * @param increment - Optional semver increment to apply
   * @param options - Optional configuration object
   * @param options.prereleasePrefix - A prefix to use for prerelease versions
   */
  constructor(version: string, increment?: SemVerIncrement, options?: {prereleasePrefix?: string});
  
  /**
   * Set version from input string or increment
   * @param input - Version string or semver increment to increase the current version by
   * @param options - Optional configuration object
   * @param options.prereleasePrefix - A prefix to use for prerelease versions
   * @throws If input is not a valid SemVer version or increment, or if input is a valid SemVer version but is not greater than the current version
   */
  setFrom(input: string | SemVerIncrement, options?: {prereleasePrefix?: string}): Version;
  
  /**
   * Format version string with optional styling and diff highlighting
   * @param options - Formatting options
   * @param options.color - Color name for the version string (default: 'dim')
   * @param options.diffColor - Color name for the diff highlighting (default: 'cyan')
   * @param options.previousVersion - Previous version for diff calculation
   * @returns Color-formatted version string
   */
  format(options?: {color?: ColorName; diffColor?: ColorName; previousVersion?: string}): string;
  
  /**
   * Check if version satisfies a semver range
   * @param range - SemVer range string
   * @returns True if version satisfies range
   * @throws If range is invalid
   */
  satisfies(range: string): boolean;
  
  /**
   * Check if version has any prerelease components
   * @returns True if version is prerelease
   */
  isPrerelease(): boolean;
  
  /**
   * Convert version to string
   * @returns String representation of the version
   */
  toString(): string;
}

import Version from "np/source/version.js";

// Create version with increment
const version = new Version("1.0.0", "minor");
console.log(version.toString()); // "1.1.0"

// Create version with prerelease prefix
const betaVersion = new Version("1.0.0", "prepatch", { prereleasePrefix: "beta" });
console.log(betaVersion.toString()); // "1.0.1-beta.0"

// Set from input - returns the Version instance
version.setFrom("patch");
console.log(version.toString()); // "1.1.1"

// Set specific version
version.setFrom("2.0.0");
console.log(version.toString()); // "2.0.0"

// Check prerelease
const preVersion = new Version("1.0.0-alpha.1");
console.log(preVersion.isPrerelease()); // true

// Format with color and diff highlighting
console.log(version.format({ 
  color: 'dim', 
  diffColor: 'cyan',
  previousVersion: '1.0.0'
})); // Colored output with diff highlighting

// Range validation
console.log(version.satisfies("^2.0.0")); // true
console.log(version.satisfies("^1.0.0")); // false

/**
 * Array of valid semver increment types
 */
const SEMVER_INCREMENTS: string[] = [
  'patch',
  'minor', 
  'major',
  'prepatch',
  'preminor',
  'premajor',
  'prerelease'
];

/**
 * Comma-separated list of semver increments for display
 */
const SEMVER_INCREMENTS_LIST: string;

import { SEMVER_INCREMENTS, SEMVER_INCREMENTS_LIST } from "np/source/version.js";

// Validate increment
function isValidIncrement(increment) {
  return SEMVER_INCREMENTS.includes(increment);
}

// Display options
console.log(`Valid increments: ${SEMVER_INCREMENTS_LIST}`);
// "Valid increments: patch, minor, major, prepatch, preminor, premajor, prerelease"

/**
 * Validate that engine version satisfies requirements
 * @param engine - Engine name (node, npm, etc.)
 * @param version - Version string to validate
 * @throws Error if version doesn't satisfy engine requirements
 */
function validateEngineVersionSatisfies(engine: string, version: string): void;

// Specific versions
"1.2.3"
"2.0.0-beta.1"
"1.0.0-alpha.2"
"3.1.4-rc.1"

// Basic formatting
version.format(); // Standard version string

// With color/styling (CLI context)
version.format({ 
  style: 'bold',
  color: 'green'
});

// With prefix/suffix
version.format({
  prefix: 'v',
  suffix: '-release'
});

/**
 * Get version tag prefix from package manager configuration
 * @param packageManager - Package manager configuration
 * @returns Promise resolving to tag prefix string
 */
function getTagVersionPrefix(packageManager: object): Promise<string>;

/**
 * Get prerelease prefix from configuration
 * @param config - Configuration object
 * @returns Promise resolving to prerelease prefix
 */
function getPreReleasePrefix(config: object): Promise<string>;

? Select semver increment or specify new version (currently 1.0.0):
❯ patch   (1.0.1)
  minor   (1.1.0)
  major   (2.0.0)
  prepatch (1.0.1-0)
  preminor (1.1.0-0)
  premajor (2.0.0-0)
  prerelease (1.0.1-0)
  Other (specify)

// npm
["npm", ["version", "patch", "--message", "v%s"]]

// yarn
["yarn", ["version", "--new-version", "1.0.1", "--message", "v%s"]]

// pnpm  
["pnpm", ["version", "patch", "--message", "v%s"]]